@qingflow-tech/qingflow-app-builder-mcp 1.0.40 → 1.0.41

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.40
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.41
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.40 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.41 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution 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.41"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App Builder
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
@@ -15,6 +17,7 @@ In Wingent Momo runtime, trust the injected MCP session, credentials, workspace,
 Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
 
 Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
+Then pick the matching development guide: [single-app-development-guide.md](references/single-app-development-guide.md) for one app, or [complete-system-development-guide.md](references/complete-system-development-guide.md) for app packages/systems.
 
 ## Current Public Mental Model
 
@@ -36,11 +39,13 @@ Default modeling rules:
 
 Before any builder write, classify the request:
 
-- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. This is the main path for complete systems, not a bulk shortcut to abandon after the first slow response. Do not squeeze several business objects into one app.
 - **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
 - **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
 
-For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields should use `target_app_ref` for another `apps[].client_key`; use `target_app_key` only when the target app already exists or has been confirmed by readback. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+
+If a complete-system `app_schema_apply` times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, treat it as an uncertain write, not as a failed create. The next action is always `readback_before_retry`: read the package/app/fields first, compare intended `client_key`/`app_name`/relations against reality, and only then repair the missing slice. Do not retry the whole multi-app create, create `V2`/`测试`/random-suffix apps, or split the system into single-app rebuilds to bypass a duplicate/conflict.
 
 Builder schema inputs should follow agent-intuitive semantics:
 
@@ -69,7 +74,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Multi-app schema work:
   - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
   - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
+  - same-call relation fields should use `target_app_ref` to point at another `apps[].client_key`; use `target_app` only when the app name is unique and stable, and use `target_app_key` only after the target app already exists or readback has confirmed it
+  - timeout / `partial_success` / `write_executed=true` / `safe_to_retry=false` means `readback_before_retry`; do not directly downgrade to single-app creation
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
@@ -161,6 +167,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
 - Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
 - If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
+- Do not bypass package/app-name conflicts by inventing `V2`, `测试`, timestamp, or random suffix apps in a real business package. Read back and decide whether to update the existing app, create only a truly missing app, or ask the user.
+- After any uncertain schema write, do `readback_before_retry` with `package_get` / `app_resolve` / `app_get_fields`; retry only the verified missing or failed slice.
 - Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
@@ -179,7 +187,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
 - Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
-- `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
+- `success` means write and verification completed; `partial_success` means the write landed or may have landed but verification is incomplete. If `write_executed=true`, `safe_to_retry=false`, or readback is unavailable, do `readback_before_retry` before any create retry.
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
@@ -271,6 +279,8 @@ For add-data buttons that create a child record linked back to the current recor
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
 - Field matching rules: [references/match-rules.md](references/match-rules.md)
 - Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Single app development guide: [references/single-app-development-guide.md](references/single-app-development-guide.md)
+- Complete system development guide: [references/complete-system-development-guide.md](references/complete-system-development-guide.md)
 - Create one app in an existing package: [references/create-app.md](references/create-app.md)
 - Update fields only: [references/update-schema.md](references/update-schema.md)
 - Update layout only: [references/update-layout.md](references/update-layout.md)

package/skills/qingflow-app-builder/references/complete-system-development-guide.md

@@ -0,0 +1,59 @@
+# Complete System Development Guide
+
+Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
+Do not compress several business objects into one app.
+
+## Recommended Completeness
+
+Required:
+
+- package exists or is created through `package_apply`
+- core business objects are modeled as separate apps
+- all new apps are created in one multi-app `app_schema_apply(package_id=..., apps=[...])`
+- every app has stable `client_key`, `app_name`, `icon`, `color`, and one readable `as_data_title: true`
+- same-call relations use `target_app_ref` to point to another `apps[].client_key`
+- basic operating views exist for each core app
+- package/apps/fields/relations are read back before repair or retry
+
+Strongly recommended:
+
+- cross-app relation fields for the main business links
+- core metric charts and BI charts using semantic `metric`, `metrics`, `group_by`, and `where`
+- a standard portal: business entry area, core metrics, BI charts, then concrete data views
+- portal grid/business-entry sections contain real `config.items[]`, not empty containers
+
+Optional:
+
+- workflow, reminders, buttons, associated resources, sample data, roles, and permissions when the user asks for them or the business process clearly depends on them
+
+## Standard Path
+
+1. Resolve or create package: `package_get` / `package_apply`.
+2. Draft all apps and relations with stable `client_key` values.
+3. Run one multi-app `app_schema_apply` with `apps[]`.
+4. If write result is uncertain, run readback before retrying.
+5. For each app, apply layout and views.
+6. Create charts before portals when the portal needs metrics or BI sections.
+7. Create portal only after referenced apps, views, and charts are known.
+8. Add workflows/buttons/associated resources when they are part of the requested business process.
+
+## Recovery Rules
+
+- Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means `write_may_have_succeeded`.
+- Next action is always `readback_before_retry`: read package, resolve intended apps, then read fields/relations.
+- Retry only verified missing apps, fields, or relations.
+- Do not rebuild the system as separate single-app creates.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
+## Portal Template
+
+- Top area: one business entry grid plus one todo/common/frequent component when useful.
+- Metrics: one row of 4-6 indicator/target cards with portal section `role: "metric"`; recommended height 5.
+- BI charts: one row of 2-3 charts, 1-2 rows; recommended height 7.
+- Data views: one row of 1-2 concrete views, 1-2 rows; recommended height 11.
+
+## Stop Conditions
+
+- If the user only asked for one app, switch to the single-app guide.
+- If required package/app/field/relation readback contradicts the intended model, repair the specific missing slice before building dependent resources.
+- If a public tool cannot express a needed business feature, state the gap and ask before using any fallback or submitting feedback.

package/skills/qingflow-app-builder/references/create-app.md

@@ -8,7 +8,7 @@ Do not use this playbook when the user is really asking for a system/package wit
 1. read or create the package through `package_get` / `package_apply`
 2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add same-call relation fields with `target_app_ref` when one new app references another new app
+4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
 5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
@@ -41,6 +41,8 @@ Use this pattern instead:
 2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
+If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
 ## Example
 
 When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.

package/skills/qingflow-app-builder/references/gotchas.md

@@ -17,6 +17,8 @@
 - Another app is not a field
 - If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
 - Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
+- For a complete system, the main creation path is one multi-app `app_schema_apply(package_id=..., apps=[...])` with stable `apps[].client_key` values and same-call relation fields using `target_app_ref`
+- Use `target_app_key` only for an app that already exists or has been confirmed by readback
 
 ## Auto publish
 
@@ -88,7 +90,11 @@
 ## Retry discipline
 
 - If a write returns `partial_success`, read back before retrying
+- If multi-app schema apply times out, returns `write_executed=true`, returns `safe_to_retry=false`, or has incomplete readback, treat it as `write_may_have_succeeded`; the next action is `readback_before_retry`
+- `readback_before_retry` means read package/app/fields first, classify which intended apps and relation fields actually exist, and retry only the verified missing slice
 - Do not repeat create steps after `app_key` already exists
+- Do not split a complete-system schema create into single-app rebuilds until readback proves exactly what is missing
+- Do not bypass duplicate/conflict states by inventing `V2`, `测试`, timestamp, or random-suffix app names in a real business package
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
 - For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.

package/skills/qingflow-app-builder/references/single-app-development-guide.md

@@ -0,0 +1,47 @@
+# Single App Development Guide
+
+Use this when the user asks for one app/form, or gives one `app_key`.
+If the user asks for a package, system, or several related modules, use `complete-system-development-guide.md` instead.
+
+## Recommended Completeness
+
+Required:
+
+- target package/app resolved by `package_get`, `app_resolve`, or `app_get`
+- business fields created or updated through `app_schema_apply`
+- exactly one readable top-level `as_data_title: true`
+- no platform system fields in `add_fields`
+- layout places the important fields
+- at least one business view beyond platform default views when the task includes user-facing list work
+
+Strongly recommended:
+
+- saved filters and query panel fields for the main operating views
+- simple charts when the app has status, amount, date, or owner fields worth tracking
+- associated resources or buttons only when they support a concrete workflow
+
+Optional:
+
+- workflow, portal entry, sample data, roles, or visibility changes when requested by the user or clearly needed by the app's job
+
+## Standard Path
+
+1. Read current target: `app_resolve` or `app_get`.
+2. Read current fields: `app_get_fields`.
+3. Apply fields with `app_schema_apply`.
+4. Apply layout with `app_layout_apply`.
+5. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request.
+6. Apply charts/buttons/associated resources only if they are part of the app's actual workflow.
+7. Use `app_publish_verify` only when explicit live verification is required.
+
+## Field Rules
+
+- Use agent-friendly field types where possible: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
+- Do not create `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- Do not create built-in default views such as `全部数据` or `我的数据`; Qingflow provides system views.
+
+## Stop Conditions
+
+- If the task actually needs multiple business objects, stop and switch to the complete-system guide.
+- If a write returns `partial_success`, `write_executed=true`, or `safe_to_retry=false`, read back before retrying.
+- If the same validation error repeats twice, re-read `builder_tool_contract` instead of guessing.

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -2,6 +2,16 @@
 
 Use these when you need a quick reminder of the standard v2 builder sequences.
 
+## Create a complete system / app package
+
+1. `package_get` or `package_apply`
+2. one multi-app `app_schema_apply(package_id=..., apps=[...])`
+3. use stable `apps[].client_key` values and relation `target_app_ref` for same-call app references
+4. use returned/readback `app_key` values for layout, views, workflow, charts, buttons, associated resources, and portal work
+5. `app_publish_verify` only when the user asks for explicit live verification or a final verification pass is required
+
+If the multi-app schema write times out or returns `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback, the next action is `readback_before_retry`: read package/app/fields first, then retry only verified missing pieces. Do not repeat the whole apps payload, split into single-app rebuilds, or create `V2` / `测试` / random-suffix apps to dodge duplicate names.
+
 ## Create a new app in an existing package
 
 1. `package_get`

package/skills/qingflow-app-builder-code-integrations/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App Builder Code Integrations
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields

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)