@qingflow-tech/qingflow-app-user-mcp 1.0.40 → 1.0.42

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.40
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.42
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.40 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.42 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -24,8 +24,6 @@ Bundled skills:
 
 - `skills/qingflow-app-user`
 - `skills/qingflow-mcp-setup`
-- `skills/qingflow-app-builder`
-- `skills/qingflow-app-builder-code-integrations`
 - `skills/qingflow-record-insert`
 - `skills/qingflow-record-update`
 - `skills/qingflow-record-delete`

package/docs/local-agent-install.md

@@ -128,7 +128,7 @@ qingflow-skills install --agent codex --scope user
 如果通过一次性 `npx -p <package>` 执行安装，请加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @josephyan/qingflow-cli qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli qingflow-skills install --agent codex --scope user --copy
 ```
 
 也可以挂载到项目级 agent 目录：
@@ -268,7 +268,7 @@ qingflow-app-builder-mcp-skills list
       "command": "npx",
       "args": [
         "-y",
-        "@josephyan/qingflow-app-user-mcp"
+        "@qingflow-tech/qingflow-app-user-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -281,7 +281,7 @@ qingflow-app-builder-mcp-skills list
       "command": "npx",
       "args": [
         "-y",
-        "@josephyan/qingflow-app-builder-mcp"
+        "@qingflow-tech/qingflow-app-builder-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -323,7 +323,7 @@ npm install
 
 如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
 
-1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
+1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
 2. 删除安装目录下的 `.npm-python`
 3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
 4. 再启动 MCP 客户端

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.40",
+  "version": "1.0.42",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.40"
+version = "1.0.42"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App User
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.
@@ -39,7 +41,7 @@ Route to exactly one of these specialized paths:
    Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
 
 8. App / view / workflow / chart / portal / package configuration
-   Switch to [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+   This is outside the App User MCP tool surface. Use the separate `qingflow-app-builder` skill/MCP package when that builder surface is installed; otherwise ask the user to enable the builder MCP.
 
 ## Routing Rules
 
@@ -50,7 +52,7 @@ Route to exactly one of these specialized paths:
 - If the task is about deleting records directly, switch to `$qingflow-record-delete`
 - If the task is about import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-import`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
-- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, switch to `$qingflow-app-builder`
+- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, do not continue with App User MCP tools. Use the separate `qingflow-app-builder` skill/MCP package when available, or ask the user to enable the builder MCP.
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
 - For member/department field ambiguity, keep the record insert/update route and use `record_member_candidates` / `record_department_candidates`; do not switch to `directory_*`, builder member search, external-contact lookup, or contact-directory management queries. App User MCP only exposes `directory_search` for member-visible keyword search, not directory tree/list management.
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
@@ -87,4 +89,4 @@ Route to exactly one of these specialized paths:
 - Record import: [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 - Task workflow operations: [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 - Dedicated analysis workflow: [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
-- Builder workflow: [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+- Builder workflow requires the separate `qingflow-app-builder` skill/MCP package.

package/skills/qingflow-mcp-setup/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow MCP Setup
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.

package/skills/qingflow-record-analysis/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Analysis
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill only for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
 
 Default path, every time:
@@ -37,7 +39,7 @@ The CLI command is under the `record` command group, so the discovery path is: f
 - Before final analysis, run a field-quality profile in pandas: row count, null rate, distinct count, and period coverage for candidate grouping fields.
 - Do not use a high-missing field as the main conclusion dimension. If a candidate dimension is sparse, downgrade it to an `已填写样本观察` and choose a cleaner semantic fallback when available.
 - Full final conclusions require `record_access.complete=true` and `record_access.safe_for_final_conclusion=true`.
-- `record_list` is only for sample inspection after the aggregate result is understood.
+- `record_list` is only for sample inspection after the aggregate result is understood; its `data.items[]` rows are flat field-title keyed objects, not nested `fields[]`.
 - `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
 - `record_export_direct` is only for explicit export/download/Excel requests.
 - `chart_get` / QingBI is only for user-provided report URLs or chart ids. If it reports `CHART_BASE_INFO_UNAVAILABLE` but `chart_data_loaded=true`, treat the chart data as readable and only the metadata/base info as degraded.

package/skills/qingflow-record-delete/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Delete
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_list / record_get -> record_delete`

package/skills/qingflow-record-import/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Import
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `app_get -> record_import_schema_get -> record_import_template_get -> record_import_verify -> (optional authorized repair) -> record_import_start -> record_import_status_get`
@@ -21,6 +23,33 @@ metadata:
 - `record_import_start`
 - `record_import_status_get`
 
+## File Shape And Field Mapping
+
+- Official template headers are the target contract. Do not rename them in the import file.
+- CSV can be used as a source format for planning or local transformation, but the current verify/start path expects the official Excel template (`.xlsx` / `.xls`).
+- When the user gives CSV-like data, map each source column to the official template header first, then write the mapped rows into a copy of the template after explicit user authorization.
+- Relation fields: prefer stable target `record_id` or another unique searchable value already accepted by the import schema. Do not rely on duplicated display names.
+- Member / department fields: use values inside the schema/candidate scope; do not invent departments or names that are not resolvable.
+- Select fields: use option labels from the schema/template; option ids are acceptable only when the import schema or prior readback proves they are supported.
+
+Example source CSV for planning only:
+
+```csv
+客户名称,关联客户,状态,负责人
+上海示例客户,CUST_RECORD_ID_001,有效,张三
+```
+
+Mapped template row concept:
+
+```json
+{
+  "客户名称": "上海示例客户",
+  "关联客户": "CUST_RECORD_ID_001",
+  "状态": "有效",
+  "负责人": "张三"
+}
+```
+
 ## Working Rules
 
 1. Inspect `app_get.data.import_capability` first

package/skills/qingflow-record-insert/SKILL.md

@@ -8,6 +8,8 @@ metadata:
 
 # Qingflow Record Insert
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_insert_schema_get -> record_insert(items) -> optional record_get/readback`
@@ -22,6 +24,26 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 - `record_department_candidates`
 - `file_upload_local`
 
+## Special Field Write Cheatsheet
+
+Always read the insert schema first, then use field titles as `items[].fields` keys. For special fields:
+
+- `member`: write a unique name, email, or resolved member id. If candidates are duplicated or the tool returns `needs_confirmation`, stop and surface candidates.
+- `department`: do not invent department names. Use a value inside the schema/candidate scope: unique department name, returned id/key, or returned object shape such as `{"key":"DEPT_ID","label":"部门名"}` / `{"id":"DEPT_ID","value":"部门名"}`.
+- `relation`: known target record id is most stable for batch inserts. Natural display text is allowed only when it uniquely resolves through the field's `searchable_fields`; duplicates require confirmation.
+- `single_select` / `multi_select`: option label and option id are both acceptable when present in schema/options. Prefer labels for readability; let the tool compile to the path-specific value.
+- `attachment`: upload the local file first with `file_upload_local`, then write the returned file value. Do not write only a filename or arbitrary URL.
+- System fields are read-only: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`.
+
+## Failure Repair Contract
+
+When insert returns `blocked`, `partial_success`, or `needs_confirmation`, do not retry the whole batch blindly.
+
+- Read `items[].failed_fields[]` first.
+- Each failed field exposes `error_code`, `expected_format`, `example_value`, and `next_action`.
+- For `member`, `department`, `relation`, `attachment`, and `select` fields, `next_action` is field-type specific: candidate lookup, upload first, use record/apply id, or use schema option label/id.
+- Retry only the failed `row_number` with corrected values. If any row has `write_executed=true` or `created_record_ids` is non-empty, never replay the original batch.
+
 ## Candidate Lookup
 
 Do not pre-query member or department ids by default. Use candidate commands only when:
@@ -72,7 +94,7 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
 10. If insert succeeds and single-record detail/readback matters, prefer `record_get`; for batch verification, rely on returned `created_record_ids` first, then use `record_get` for selected rows or `record_access -> Python` when a row-shaped bulk check is truly needed
 11. Keep subtable payloads under the parent field as a row array
-12. Member / department / relation fields may accept natural strings directly, such as `"张三"`, `"直销部"`, or `"海军军医大学"`; do not pre-query ids by default
+12. Follow the Special Field Write Cheatsheet for member, department, relation, select, and attachment values; do not pre-query ids by default when a natural value is unique enough
 13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
 14. Retry failed rows only with explicit ids / objects after the user confirms
 15. Keep `verify_write=true` for production inserts
@@ -123,6 +145,7 @@ qingflow --json record insert --app-key APP_KEY --items-file records.json
 - Do not invent missing required fields
 - Do not fill platform system fields such as `数据ID`, `编号`, `申请人`, `创建时间`, or `更新时间`
 - Do not flatten subtable leaf fields to the top level
+- Do not invent member / department / relation candidates outside schema or candidate scope
 - Do not pre-query or silently guess member / department / relation ids when a natural string is enough
 - Do not retry a whole batch after `created_record_ids` is non-empty
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

package/skills/qingflow-record-update/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Update
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_get -> record_update`
@@ -33,6 +35,7 @@ metadata:
 11. If single-record readback matters, prefer `record_get` after the write and read top-level `fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
 12. For batch updates, read top-level `mode`, `dry_run`, `total`, `succeeded`, `failed`, `needs_confirmation`, `updated_record_ids`, `write_executed`, `safe_to_retry`, `verification_status`, and `items[].row_number/status/record_id`
 13. If `write_executed=true`, do not blindly retry the whole batch; use `items[]` and `updated_record_ids` to decide whether only failed rows need repair
+14. If you use `record_list` to locate candidates, parse `data.items[]` as flat row objects such as `row["客户名称"]` + `row["record_id"]`; do not expect a nested `fields[]` array in list rows
 
 ## Special Field Values
 

package/skills/qingflow-task-ops/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Task Ops
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is for task workflow operations only.

package/src/qingflow_mcp/builder_facade/models.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from enum import Enum
 from typing import Any
 
@@ -70,17 +71,36 @@ class PublicExternalVisibilityMode(str, Enum):
 
 
 FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
+    "multiline": PublicFieldType.long_text,
+    "multiline_text": PublicFieldType.long_text,
+    "multi_line": PublicFieldType.long_text,
+    "multi_line_text": PublicFieldType.long_text,
     "textarea": PublicFieldType.long_text,
+    "longtext": PublicFieldType.long_text,
+    "long-text": PublicFieldType.long_text,
     "amount": PublicFieldType.amount,
     "currency": PublicFieldType.amount,
     "mobile": PublicFieldType.phone,
     "user": PublicFieldType.member,
     "users": PublicFieldType.member,
     "select": PublicFieldType.single_select,
+    "single_choice": PublicFieldType.single_select,
+    "single-choice": PublicFieldType.single_select,
+    "single choice": PublicFieldType.single_select,
+    "choice": PublicFieldType.single_select,
+    "dropdown": PublicFieldType.single_select,
     "radio": PublicFieldType.single_select,
     "checkbox": PublicFieldType.multi_select,
     "multi_select": PublicFieldType.multi_select,
     "multi-select": PublicFieldType.multi_select,
+    "multi select": PublicFieldType.multi_select,
+    "multiselect": PublicFieldType.multi_select,
+    "multi_choice": PublicFieldType.multi_select,
+    "multi-choice": PublicFieldType.multi_select,
+    "multi choice": PublicFieldType.multi_select,
+    "multiple_choice": PublicFieldType.multi_select,
+    "multiple-choice": PublicFieldType.multi_select,
+    "multiple choice": PublicFieldType.multi_select,
     "departments": PublicFieldType.department,
     "qlinker": PublicFieldType.q_linker,
     "q_linker": PublicFieldType.q_linker,
@@ -1796,6 +1816,65 @@ class ChartFilterRulePatch(StrictModel):
         return self
 
 
+class ChartMetricPatch(StrictModel):
+    op: str = "count"
+    field_name: str | None = Field(default=None, validation_alias=AliasChoices("field", "field_name", "fieldName", "name"))
+    alias: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_metric(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            raw = value.strip()
+            match = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*(.*?)\s*\)", raw)
+            if match:
+                op = match.group(1).strip().lower()
+                field = match.group(2).strip()
+                payload: dict[str, Any] = {"op": op}
+                if field and field != "*":
+                    payload["field_name"] = field
+                return payload
+            if raw:
+                return {"op": "sum", "field_name": raw}
+            return {"op": "count"}
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "operation" in payload and "op" not in payload:
+            payload["op"] = payload.pop("operation")
+        if "agg" in payload and "op" not in payload:
+            payload["op"] = payload.pop("agg")
+        if "aggregate" in payload and "op" not in payload:
+            payload["op"] = payload.pop("aggregate")
+        if "aggregation" in payload and "op" not in payload:
+            payload["op"] = payload.pop("aggregation")
+        return payload
+
+    @model_validator(mode="after")
+    def validate_metric(self) -> "ChartMetricPatch":
+        normalized_op = str(self.op or "count").strip().lower()
+        op_aliases = {
+            "average": "avg",
+            "mean": "avg",
+            "total": "sum",
+            "cnt": "count",
+            "count_all": "count",
+        }
+        self.op = op_aliases.get(normalized_op, normalized_op)
+        if self.field_name is not None:
+            field_name = str(self.field_name).strip()
+            self.field_name = field_name or None
+        if self.alias is not None:
+            alias = str(self.alias).strip()
+            self.alias = alias or None
+        supported = {"count", "sum", "avg", "max", "min"}
+        if self.op not in supported:
+            raise ValueError(f"chart metric op must be one of {sorted(supported)}")
+        if self.op != "count" and not self.field_name:
+            raise ValueError(f"chart metric op '{self.op}' requires field")
+        return self
+
+
 class ChartUpsertPatch(StrictModel):
     chart_id: str | None = None
     name: str
@@ -1803,6 +1882,17 @@ class ChartUpsertPatch(StrictModel):
     dimension_field_ids: list[str] = Field(default_factory=list)
     indicator_field_ids: list[str] = Field(default_factory=list)
     filters: list[ChartFilterRulePatch] = Field(default_factory=list)
+    group_by: list[str] = Field(default_factory=list)
+    rows: list[str] = Field(default_factory=list)
+    columns: list[str] = Field(default_factory=list)
+    metric: ChartMetricPatch | None = None
+    metrics: list[ChartMetricPatch] = Field(default_factory=list)
+    x_metric: ChartMetricPatch | None = None
+    y_metric: ChartMetricPatch | None = None
+    left_metric: ChartMetricPatch | None = None
+    right_metric: ChartMetricPatch | None = None
+    value_metric: ChartMetricPatch | None = None
+    target_metric: ChartMetricPatch | None = None
     question_config: list[dict[str, Any]] = Field(default_factory=list)
     user_config: list[dict[str, Any]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)
@@ -1820,10 +1910,74 @@ class ChartUpsertPatch(StrictModel):
             payload["chart_type"] = payload.pop("type")
         if "dimension_fields" in payload and "dimension_field_ids" not in payload:
             payload["dimension_field_ids"] = payload.pop("dimension_fields")
+        if "dimensions" in payload and "dimension_field_ids" not in payload and "group_by" not in payload:
+            payload["group_by"] = payload.pop("dimensions")
+        if "groupBy" in payload and "group_by" not in payload:
+            payload["group_by"] = payload.pop("groupBy")
+        if "where" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("where")
+        if "filter_rules" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("filter_rules")
+        if "filterRules" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("filterRules")
         if "indicator_fields" in payload and "indicator_field_ids" not in payload:
             payload["indicator_field_ids"] = payload.pop("indicator_fields")
         if "metric_field_ids" in payload and "indicator_field_ids" not in payload:
             payload["indicator_field_ids"] = payload.pop("metric_field_ids")
+        metric_slots: list[Any] = []
+        generic_metric_keys = ("metric", "metrics")
+        axis_metric_keys = (
+            "x_metric",
+            "xMetric",
+            "y_metric",
+            "yMetric",
+            "left_metric",
+            "leftMetric",
+            "right_metric",
+            "rightMetric",
+            "value_metric",
+            "valueMetric",
+            "target_metric",
+            "targetMetric",
+        )
+
+        def has_metric_value(key: str) -> bool:
+            entry = payload.get(key)
+            return entry is not None and entry != "" and entry != []
+
+        if any(has_metric_value(key) for key in generic_metric_keys) and any(has_metric_value(key) for key in axis_metric_keys):
+            raise ValueError(
+                "chart metric input is ambiguous: use either metric/metrics or axis-specific "
+                "x_metric/y_metric, left_metric/right_metric, value_metric/target_metric, not both"
+            )
+        if "metric" in payload and "metrics" not in payload:
+            payload["metrics"] = [payload["metric"]]
+        for key in ("x_metric", "xMetric", "left_metric", "leftMetric", "value_metric", "valueMetric"):
+            if key in payload:
+                slot_value = payload.get(key)
+                if slot_value is not None:
+                    metric_slots.append(slot_value)
+                canonical = {
+                    "xMetric": "x_metric",
+                    "leftMetric": "left_metric",
+                    "valueMetric": "value_metric",
+                }.get(key)
+                if canonical and canonical not in payload:
+                    payload[canonical] = payload.pop(key)
+        for key in ("y_metric", "yMetric", "right_metric", "rightMetric", "target_metric", "targetMetric"):
+            if key in payload:
+                slot_value = payload.get(key)
+                if slot_value is not None:
+                    metric_slots.append(slot_value)
+                canonical = {
+                    "yMetric": "y_metric",
+                    "rightMetric": "right_metric",
+                    "targetMetric": "target_metric",
+                }.get(key)
+                if canonical and canonical not in payload:
+                    payload[canonical] = payload.pop(key)
+        if metric_slots and "metrics" not in payload:
+            payload["metrics"] = metric_slots
         raw_type = payload.get("chart_type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -1850,8 +2004,31 @@ class ChartUpsertPatch(StrictModel):
             payload["dimension_field_ids"] = [str(item) for item in payload["dimension_field_ids"] if item is not None and str(item).strip()]
         if isinstance(payload.get("indicator_field_ids"), list):
             payload["indicator_field_ids"] = [str(item) for item in payload["indicator_field_ids"] if item is not None and str(item).strip()]
+        for key in ("group_by", "rows", "columns"):
+            if isinstance(payload.get(key), str):
+                payload[key] = [payload[key]]
+            if isinstance(payload.get(key), list):
+                payload[key] = [str(item) for item in payload[key] if item is not None and str(item).strip()]
         return payload
 
+    @model_validator(mode="after")
+    def apply_semantic_chart_fields(self) -> "ChartUpsertPatch":
+        if self.group_by and not self.dimension_field_ids:
+            self.dimension_field_ids = list(self.group_by)
+        if self.rows and not self.dimension_field_ids:
+            self.dimension_field_ids = list(self.rows)
+        semantic_metrics: list[ChartMetricPatch] = []
+        if self.metrics:
+            semantic_metrics.extend(self.metrics)
+        for metric in (self.x_metric, self.y_metric, self.left_metric, self.right_metric, self.value_metric, self.target_metric):
+            if metric is not None and metric not in semantic_metrics:
+                semantic_metrics.append(metric)
+        if semantic_metrics and not self.metrics:
+            self.metrics = semantic_metrics
+        if self.metrics and not self.metric:
+            self.metric = self.metrics[0]
+        return self
+
 
 class ChartPartialPatch(StrictModel):
     chart_id: str | None = None
@@ -1993,6 +2170,7 @@ class PortalViewRefPatch(StrictModel):
 class PortalSectionPatch(StrictModel):
     title: str
     source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
+    role: str | None = Field(default=None, validation_alias=AliasChoices("role", "zone", "section_role", "sectionRole"))
     position: PortalComponentPositionPatch | None = None
     dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
     config: dict[str, Any] = Field(default_factory=dict)
@@ -2010,6 +2188,9 @@ class PortalSectionPatch(StrictModel):
         raw_type = payload.get("source_type", payload.get("sourceType"))
         if isinstance(raw_type, str):
             payload["source_type"] = raw_type.strip().lower()
+        raw_role = payload.get("role", payload.get("zone", payload.get("section_role", payload.get("sectionRole"))))
+        if isinstance(raw_role, str):
+            payload["role"] = raw_role.strip().lower()
         if "chartRef" in payload and "chart_ref" not in payload:
             payload["chart_ref"] = payload.pop("chartRef")
         if "viewRef" in payload and "view_ref" not in payload:
@@ -2216,6 +2397,8 @@ class ChartGetResponse(StrictModel):
     base: dict[str, Any] = Field(default_factory=dict)
     visibility: dict[str, Any] = Field(default_factory=dict)
     filters: list[list[dict[str, Any]]] = Field(default_factory=list)
+    group_by: list[str] = Field(default_factory=list)
+    metrics: list[dict[str, Any]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)