@josephyan/qingflow-app-builder-mcp 1.1.26 → 1.1.28

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

@@ -6,7 +6,7 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create each app separately
+2. create related apps together with one `app_schema_apply(apps=[...])`
 3. keep package ownership on the public `package_id` path instead of a separate attach step
 4. add relation fields between apps
 
@@ -85,6 +85,12 @@ Apply schema for a new app:
       {"name": "订单金额", "type": "amount"},
       {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
     ],
+    "form": {
+      "sections": [
+        {"title": "基础信息", "rows": [["订单编号", "客户名称"], ["状态"]]},
+        {"title": "金额与附件", "rows": [["订单金额"], ["订单封面"]]}
+      ]
+    },
     "update_fields": [],
     "remove_fields": []
   }
@@ -105,13 +111,18 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
+        "icon": "user-group",
+        "color": "blue",
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
-        ]
+        ],
+        "form": {"sections": [{"title": "基础信息", "rows": [["客户名称"]]}]}
       },
       {
         "client_key": "order",
         "app_name": "订单",
+        "icon": "delivery-box-1",
+        "color": "green",
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {
@@ -121,7 +132,8 @@ Apply schema for multiple apps in one call:
             "display_field": {"name": "客户名称"},
             "visible_fields": [{"name": "客户名称"}]
           }
-        ]
+        ],
+        "form": {"sections": [{"title": "基础信息", "rows": [["订单编号", "关联客户"]]}]}
       }
     ]
   }

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

@@ -22,7 +22,7 @@
 
 - Always pass `publish: true` explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default
 - Pass `publish: false` on those five tools only when the user explicitly wants to leave changes in draft
-- `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a `publish` parameter
+- `app_associated_resources_apply` publishes after at least one write succeeds and does not accept a `publish` parameter
 - `app_charts_apply` is immediate-live and has no publish step
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
@@ -34,20 +34,16 @@
 - Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
 - `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
 
-## Custom buttons
+## View actions
 
-- Use `app_custom_buttons_apply` for button creation/update/removal and view placement; do not split placement into `app_views_apply.buttons` unless you are maintaining a legacy patch.
-- When changing one existing button parameter, use `patch_buttons` with `set/unset`. Do not send a partial `upsert_buttons` object and expect the backend to preserve hidden required fields.
-- For add-data buttons, prefer semantic `trigger_add_data_config.target_app_key`, `field_mappings`, and `default_values`.
+- Put business actions directly in the target view's `action_buttons`.
+- For add-data actions, use semantic `target_app_key`, `field_mappings`, and `default_values`.
 - Do not handwrite raw `que_relation` unless you are preserving an existing backend config. If `field_mappings` and `que_relation` are mixed, the tool blocks the write.
 - `field_mappings.source_field` can use source app fields and supported system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`).
 - To fill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`. Use `default_values` only for static constants.
 - For field type compatibility, read `references/match-rules.md`.
 - Default button placements are `header` and `detail`; these map to the frontend's header and detail button areas.
-- `view_configs[].buttons` is required in merge mode. Do not send a view config with only `view_key`; it is blocked to avoid no-op writes and accidental publish.
 - Builder view configs use raw `view_key` from `app_get.views[].view_key`; do not prefix it with `custom:`. The `custom:<viewKey>` form is for record-data `view_id`.
-- View button bindings merge by default. Use `view_configs[].mode="replace"` to replace the full set, or pass an explicit empty `buttons: []` when you intend to clear all custom button bindings for that view.
-- Advanced view button bindings can include `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls`, but keep ordinary buttons simple unless the user asks for conditional visibility or print templates.
 - `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
 
 ## Associated resources
@@ -68,9 +64,9 @@
 
 ## Partial update discipline
 
-- Existing views, custom buttons, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
+- Existing views, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
 - The backend may still save a full payload. The MCP/CLI patch path is responsible for reading current config and preserving fields the user did not mention.
-- Do not use `upsert_views`, `upsert_buttons`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
+- Do not use `upsert_views`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
 - `app_layout_apply(mode=merge)` is already a safe layout merge path; `mode=replace` is full layout replacement.
 - `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list.
 - `app_flow_apply` is intentionally replace-only for the public linear workflow graph.

package/skills/qingflow-app-builder/references/match-rules.md

@@ -1,13 +1,13 @@
 # Builder Match Rules
 
-Use this reference for builder-side field matching rules in custom buttons and associated view/report filters.
+Use this reference for builder-side field matching rules in view actions and associated view/report filters.
 
 This is not the same thing as `record_access` analysis filters or normal view `filters`.
 
 ## Where These Rules Apply
 
-- `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
-- `app_custom_buttons_apply.patch_buttons[].set.trigger_add_data_config.field_mappings`
+- `app_views_apply.views[].action_buttons[].field_mappings`
+- `app_views_apply.patch_views[].set.action_buttons[].field_mappings`
 - `app_associated_resources_apply.upsert_resources[].match_mappings`
 - `app_associated_resources_apply.patch_resources[].set.match_mappings`
 
@@ -24,7 +24,7 @@ System fields can participate in mappings:
 
 Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
 
-## Custom Buttons
+## View Actions
 
 Use `field_mappings` for dynamic values copied from the current source record:
 
@@ -43,21 +43,25 @@ Use `field_mappings` for dynamic values copied from the current source record:
 
 Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
 
-For an existing button, put the same semantic config under `patch_buttons[].set`:
+For an existing view, patch the view's action list through `patch_views[].set.action_buttons`:
 
 ```json
 {
-  "button_id": 3858041,
+  "view_key": "VIEW_KEY",
   "set": {
-    "trigger_add_data_config": {
-      "target_app_key": "WORKLOG_APP",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联员工"}
-      ],
-      "default_values": {
-        "状态": "待提交"
+    "action_buttons": [
+      {
+        "text": "新建工时",
+        "action": "add_data",
+        "target_app_key": "WORKLOG_APP",
+        "field_mappings": [
+          {"source_field": "数据ID", "target_field": "关联员工"}
+        ],
+        "default_values": {
+          "状态": "待提交"
+        }
       }
-    }
+    ]
   }
 }
 ```

package/skills/qingflow-app-builder/references/public-surface-sync.md

@@ -39,14 +39,14 @@ It is not a user-facing product spec. It exists to prevent skill drift.
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
-  - `app_custom_buttons_apply`
   - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- View actions are declared through `app_views_apply` `action_buttons`
+- Existing object parameter replacement should use `patch_views`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -38,7 +38,6 @@ All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch).
 - `app_get_views`: current view names, types, columns, group-by
 - `app_get_flow`: workflow enabled state, full spec (nodes + transitions)
 - `app_get_charts`: current chart ids, names, types, order
-- `app_get_buttons`: current custom button list (draft state)
 - `app_get_associated_resources`: current associated resource pool (draft state)
 - `app_publish_verify`: publish state and package tag verification — accepts `app_keys[]` for multi-app batch
 - `portal_get`: current portal config detail and component inventory
@@ -48,15 +47,14 @@ All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch).
 These execute normalized patches. Some app apply tools publish by default and still accept `publish=false`; custom button and associated-resource apply publish after at least one write succeeds and do not expose that switch.
 
 - `app_schema_apply`: create app shell or change fields
-- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
+- `app_layout_apply`: layout-only maintenance for existing apps; new app layout belongs in `app_schema_apply` `form.sections`
 - `app_flow_apply`: replace full workflow spec; use `patch_nodes[]` (`{id, set, unset}`) to update specific nodes without rewriting the full spec
-- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`; use `apps[]` for multi-app batch
-- `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field. Use `apps[]` for multi-app batch.
+- `app_views_apply`: use top-level `views[]` for same-app/cross-app batch create, patch, and remove; view business actions belong in each view item's `action_buttons`
 - `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call. Use `apps[]` for multi-app batch.
 - `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique; use `apps[]` for multi-app batch
-- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; use `patch_sections[]` (`{chart_ref/view_ref/order, set, unset}`) to update individual sections without replacing all
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; use `patch_sections[]` (`{chart/view_ref/order, set, unset}`) to update individual sections without replacing all
 
-For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart_ref": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
+For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
 
 ## Explicit post-apply tools
 
@@ -69,19 +67,19 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[] with form.sections)`
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
-  `app_get_fields -> app_get_layout -> builder_tool_contract (if shape is unclear) -> app_layout_apply`
+  `app_get_fields -> app_get_layout -> app_layout_apply`
 - Add workflow:
   `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
 - Update specific flow nodes:
   `app_get_flow -> app_flow_apply.patch_nodes[]`
 - Add views:
-  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
-- Add QingBI charts:
-  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+  `app_get_fields -> app_get_views -> app_views_apply.views[] -> app_get_views`
+- Add QingBI charts for a portal:
+  `portal_apply.sections[].chart`
 - Show an existing QingBI chart inside a Qingflow app/view:
   `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
 - Create or update a portal:

package/src/qingflow_mcp/builder_facade/models.py

@@ -72,6 +72,9 @@ class PublicExternalVisibilityMode(str, Enum):
 
 FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
     "textarea": PublicFieldType.long_text,
+    "multiline": PublicFieldType.long_text,
+    "multi_line": PublicFieldType.long_text,
+    "multiline_text": PublicFieldType.long_text,
     "amount": PublicFieldType.amount,
     "currency": PublicFieldType.amount,
     "mobile": PublicFieldType.phone,
@@ -1456,6 +1459,9 @@ class CustomButtonViewButtonBindingPatch(StrictModel):
         raw_limits = payload.get("button_limit", payload.get("buttonLimit", payload.get("visible_when", payload.get("visibleWhen"))))
         if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
             payload["button_limit"] = [raw_limits]
+        for alias in ("buttonLimit", "visible_when", "visibleWhen"):
+            if alias in payload and alias != "button_limit":
+                payload.pop(alias, None)
         return payload
 
 
@@ -1642,7 +1648,7 @@ class ViewButtonBindingPatch(StrictModel):
     being_main: bool = Field(default=False, validation_alias=AliasChoices("being_main", "beingMain"))
     button_limit: list[list[ViewFilterRulePatch]] = Field(
         default_factory=list,
-        validation_alias=AliasChoices("button_limit", "buttonLimit"),
+        validation_alias=AliasChoices("button_limit", "buttonLimit", "visible_when", "visibleWhen"),
     )
     button_formula: str | None = Field(default=None, validation_alias=AliasChoices("button_formula", "buttonFormula"))
     button_formula_type: int = Field(default=1, validation_alias=AliasChoices("button_formula_type", "buttonFormulaType"))
@@ -1671,9 +1677,12 @@ class ViewButtonBindingPatch(StrictModel):
                 payload["config_type"] = "DETAIL"
             elif normalized_config in {"inside", "list", "row", "row_action"}:
                 payload["config_type"] = "INSIDE"
-        raw_limits = payload.get("button_limit", payload.get("buttonLimit"))
+        raw_limits = payload.get("button_limit", payload.get("buttonLimit", payload.get("visible_when", payload.get("visibleWhen"))))
         if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
             payload["button_limit"] = [raw_limits]
+        for alias in ("buttonLimit", "visible_when", "visibleWhen"):
+            if alias in payload and alias != "button_limit":
+                payload.pop(alias, None)
         return payload
 
     @model_validator(mode="after")
@@ -1763,68 +1772,63 @@ class ChartFilterRulePatch(StrictModel):
         return self
 
 
-_CHART_METRIC_RE = re.compile(r"^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*)\)\s*$")
-
-
-def _normalize_chart_string_list(value: Any) -> list[str]:
-    if value is None:
-        return []
-    if isinstance(value, (list, tuple)):
-        return [str(item).strip() for item in value if item is not None and str(item).strip()]
-    raw = str(value).strip()
-    return [raw] if raw else []
+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
 
-def _parse_chart_metric_item(value: Any) -> tuple[list[str], str | None]:
-    if value is None:
-        return [], None
-    if isinstance(value, dict):
-        op = str(value.get("op") or value.get("agg") or value.get("aggregate") or value.get("aggregation") or "").strip().lower()
-        field = value.get("field", value.get("field_name", value.get("name", value.get("selector"))))
-        selectors = _normalize_chart_string_list(field)
-        return selectors, op or ("count" if not selectors else None)
-    raw = str(value).strip()
-    if not raw:
-        return [], None
-    matched = _CHART_METRIC_RE.match(raw)
-    if matched:
-        op = matched.group(1).strip().lower()
-        field = matched.group(2).strip()
-        if field in {"*", ""}:
-            return [], op
-        return [field], op
-    if raw.lower() in {"count", "count(*)"}:
-        return [], "count"
-    return [raw], None
-
-
-def _apply_semantic_chart_metric_aliases(payload: dict[str, Any]) -> None:
-    raw_metrics: list[Any] = []
-    if "metric" in payload:
-        raw_metrics.append(payload.pop("metric"))
-    if "metrics" in payload:
-        metrics = payload.pop("metrics")
-        raw_metrics.extend(metrics if isinstance(metrics, list) else [metrics])
-    if not raw_metrics:
-        return
-    selectors: list[str] = []
-    aggregates: list[str] = []
-    for metric in raw_metrics:
-        metric_selectors, aggregate = _parse_chart_metric_item(metric)
-        selectors.extend(metric_selectors)
-        if aggregate:
-            aggregates.append(aggregate)
-    if selectors and "indicator_field_ids" not in payload:
-        payload["indicator_field_ids"] = selectors
-    if aggregates:
-        normalized_aggregate = aggregates[0]
-        config = payload.get("config")
-        if not isinstance(config, dict):
-            config = {}
-        else:
-            config = dict(config)
-        config.setdefault("aggregate", normalized_aggregate)
-        payload["config"] = config
+    @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):
@@ -1834,6 +1838,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)
@@ -1851,19 +1866,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")
-        if "group_by" in payload and "dimension_field_ids" not in payload:
-            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("group_by"))
-        if "groupBy" in payload and "dimension_field_ids" not in payload:
-            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("groupBy"))
-        if "where" in payload and "filters" not in payload:
-            payload["filters"] = payload.pop("where")
-        else:
-            payload.pop("where", None)
-        _apply_semantic_chart_metric_aliases(payload)
+        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()
@@ -1890,8 +1960,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
@@ -2287,6 +2380,9 @@ class ChartGetResponse(StrictModel):
     chart_id: str
     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)