@qingflow-tech/qingflow-app-builder-mcp 1.0.8 → 1.0.9

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "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.8"
+version = "1.0.9"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -61,7 +61,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
   - supplying `sections` means full replace semantics for sections
 - Chart work:
-  - `app_charts_apply` is the public write path
+  - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
+  - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
+  - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
+  - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
   - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
   - `visibility` is a public capability and should be treated as a base-only permission update
   - do not model chart visibility changes as raw config rewrites
@@ -79,12 +82,13 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `placement=list` configures row/list buttons and maps to the backend `INSIDE` button position
   - advanced bindings may use `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls` only when visibility or print-template behavior is required
 - Associated resources:
-  - `app_associated_resources_apply` is the public write path for the app-level associated report/view pool and per-view display config
+  - `app_associated_resources_apply` is the public write path for the Qingflow app-level associated report/view pool and per-view display config
+  - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
   - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
-  - `associated_item_id` must come from `app_get.associated_resources[].associated_item_id`; it is not `chart_id`, `chart_key`, or `view_key`
+  - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
   - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
   - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
-  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and dataset reports use `report_source="dataset"`
+  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
   - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:

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

@@ -25,6 +25,14 @@
 - `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept `publish=false`
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
+## BI Reports
+
+- Use `app_charts_apply` for QingBI report body/config creation or updates.
+- Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
+- `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
+- 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
 
 - 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.
@@ -45,6 +53,7 @@
 
 - Before creating an associated view/report, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`.
 - If the resource already exists, use `patch_resources` with its `associated_item_id`; do not call `upsert_resources` again.
+- For per-view display, remove, and reorder, existing associated reports/views may be referenced by `associated_item_id`, `chart_id`/`chart_key`, or `view_key`; the tool resolves these to the internal id before writing.
 - `client_key` is only a same-call alias for `view_configs[].associated_item_refs`. It is not stored by Qingflow and cannot prevent duplicates in later calls.
 - Repeated `upsert_resources` without `associated_item_id` can create multiple app-level associated items pointing to the same view/report.
 

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

@@ -47,8 +47,8 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key
 - `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.
-- `app_associated_resources_apply`: use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; use `match_mappings` for associated view/report filters; manage per-view display config; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only for BI dataset reports. 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.
-- `app_charts_apply`: use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `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.
+- `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
 - `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
 
 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": {...}}]`. 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.
@@ -75,6 +75,8 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
   `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`
+- 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:
   `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
 

package/skills/qingflow-app-builder/references/update-views.md

@@ -30,7 +30,7 @@ Canonical rules before any example:
 - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
 - Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
-- Use `app_associated_resources_apply` for the frontend associated report/view area. `associated_item_id` must be copied from `app_get.associated_resources[].associated_item_id`; it is not `chart_id` or `chart_key`. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- Use `app_associated_resources_apply` for the frontend associated report/view area. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
 - For gantt, use `start_field`, `end_field`, and optionally `title_field`
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.
@@ -116,7 +116,7 @@ View associated resources example:
 }
 ```
 
-Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above must come from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
+Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above can be internal `associated_item_id` values or existing resource `chart_id`/`chart_key`/`view_key` values from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. Dataset BI reports must already exist in QingBI and should be attached with `report_source="dataset"`; do not try to create them through `app_charts_apply`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
 
 Create and show a BI indicator-card report in the same call:
 

package/src/qingflow_mcp/builder_facade/models.py

@@ -142,10 +142,34 @@ class PublicButtonPlacement(str, Enum):
 
 class PublicChartType(str, Enum):
     target = "target"
+    indicator = "indicator"
+    summary = "summary"
     pie = "pie"
     bar = "bar"
+    columnar = "columnar"
     line = "line"
     table = "table"
+    detail = "detail"
+    area = "area"
+    stacked_area = "stacked_area"
+    pct_stack_area = "pct_stack_area"
+    funnel = "funnel"
+    waterfall = "waterfall"
+    gauge = "gauge"
+    heatmap = "heatmap"
+    histogram = "histogram"
+    treemap = "treemap"
+    radar = "radar"
+    stacked_bar = "stacked_bar"
+    pct_stack_bar = "pct_stack_bar"
+    stacked_column = "stacked_column"
+    pct_stack_col = "pct_stack_col"
+    scatter = "scatter"
+    ring = "ring"
+    rose = "rose"
+    dualaxes = "dualaxes"
+    map = "map"
+    timeline = "timeline"
 
 
 class LayoutApplyMode(str, Enum):
@@ -1576,8 +1600,8 @@ class AssociatedResourcesApplyRequest(StrictModel):
     app_key: str
     upsert_resources: list[AssociatedResourceUpsertPatch] = Field(default_factory=list)
     patch_resources: list[AssociatedResourcePartialPatch] = Field(default_factory=list)
-    remove_associated_item_ids: list[int] = Field(default_factory=list)
-    reorder_associated_item_ids: list[int] = Field(default_factory=list)
+    remove_associated_item_ids: list[Any] = Field(default_factory=list)
+    reorder_associated_item_ids: list[Any] = Field(default_factory=list)
     view_configs: list[AssociatedResourceViewConfigPatch] = Field(default_factory=list)
 
     @model_validator(mode="before")
@@ -1775,10 +1799,18 @@ class ChartUpsertPatch(StrictModel):
             normalized = raw_type.strip().lower()
             aliases = {
                 "targetchart": PublicChartType.target.value,
+                "indicatorchart": PublicChartType.indicator.value,
+                "summarychart": PublicChartType.summary.value,
                 "piechart": PublicChartType.pie.value,
                 "barchart": PublicChartType.bar.value,
+                "columnchart": PublicChartType.columnar.value,
+                "columnarchart": PublicChartType.columnar.value,
                 "linechart": PublicChartType.line.value,
                 "tablechart": PublicChartType.table.value,
+                "detailchart": PublicChartType.detail.value,
+                "percent_stacked_column": PublicChartType.pct_stack_col.value,
+                "percent_stacked_bar": PublicChartType.pct_stack_bar.value,
+                "percent_stacked_area": PublicChartType.pct_stack_area.value,
             }
             if normalized in aliases:
                 payload["chart_type"] = aliases[normalized]

package/src/qingflow_mcp/builder_facade/service.py

@@ -3672,6 +3672,7 @@ class AiBuilderFacade:
         client_key_to_id: dict[str, int] = {}
         used_client_keys: set[str] = set()
         force_update_resource_ids: set[int] = set()
+        resolved_associated_item_refs: dict[str, list[int]] = {}
 
         upsert_resources = list(request.upsert_resources)
         if request.patch_resources:
@@ -3778,34 +3779,35 @@ class AiBuilderFacade:
             else:
                 upsert_ops.append({"operation": "create", "associated_item_id": None, "patch": patch, "index": index})
 
-        remove_ids = [
-            item_id
-            for item_id in (_coerce_positive_int(raw_id) for raw_id in request.remove_associated_item_ids)
-            if item_id is not None
-        ]
+        remove_ids: list[int] = []
         for raw_id in request.remove_associated_item_ids:
-            item_id = _coerce_positive_int(raw_id)
+            item_id, issue = _resolve_associated_resource_selector(
+                raw_id,
+                existing_resources=existing_resources,
+                existing_by_id=existing_by_id,
+                reason_path="remove_associated_item_ids",
+            )
             if item_id is None:
-                blocking_issues.append({"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "remove_associated_item_ids", "received": raw_id})
+                blocking_issues.append(issue or {"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "remove_associated_item_ids", "received": raw_id})
                 continue
-            if item_id not in existing_by_id:
-                blocking_issues.append(_associated_resource_not_found_issue("remove_associated_item_ids", item_id, existing_by_id))
-            elif item_id in touched_ids:
+            remove_ids.append(item_id)
+            if item_id in touched_ids:
                 blocking_issues.append(_duplicate_associated_resource_issue("remove_associated_item_ids", item_id))
             else:
                 touched_ids.add(item_id)
 
-        reorder_ids = [
-            item_id
-            for item_id in (_coerce_positive_int(raw_id) for raw_id in request.reorder_associated_item_ids)
-            if item_id is not None
-        ]
+        reorder_ids: list[int] = []
         for raw_id in request.reorder_associated_item_ids:
-            item_id = _coerce_positive_int(raw_id)
+            item_id, issue = _resolve_associated_resource_selector(
+                raw_id,
+                existing_resources=existing_resources,
+                existing_by_id=existing_by_id,
+                reason_path="reorder_associated_item_ids",
+            )
             if item_id is None:
-                blocking_issues.append({"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "reorder_associated_item_ids", "received": raw_id})
-            elif item_id not in existing_by_id:
-                blocking_issues.append(_associated_resource_not_found_issue("reorder_associated_item_ids", item_id, existing_by_id))
+                blocking_issues.append(issue or {"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "reorder_associated_item_ids", "received": raw_id})
+                continue
+            reorder_ids.append(item_id)
 
         for index, view_config in enumerate(request.view_configs):
             refs = [str(ref or "").strip() for ref in view_config.associated_item_refs if str(ref or "").strip()]
@@ -3819,21 +3821,26 @@ class AiBuilderFacade:
                         "message": "associated_item_refs must reference client_key values from upsert_resources in the same apply call",
                     }
                 )
-            invalid_ids = [
-                item_id
-                for item_id in view_config.associated_item_ids
-                if _coerce_positive_int(item_id) is None or _coerce_positive_int(item_id) not in existing_by_id
-            ]
-            if invalid_ids:
-                blocking_issues.append(
-                    {
-                        "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
-                        "reason_path": f"view_configs[{index}].associated_item_ids",
-                        "invalid_associated_item_ids": invalid_ids,
-                        "available_associated_item_ids": sorted(existing_by_id),
-                        "message": "view_configs.associated_item_ids must use app-level associated_item_id values from app_get",
-                    }
+            resolved_ids: list[int] = []
+            for raw_id in view_config.associated_item_ids:
+                item_id, issue = _resolve_associated_resource_selector(
+                    raw_id,
+                    existing_resources=existing_resources,
+                    existing_by_id=existing_by_id,
+                    reason_path=f"view_configs[{index}].associated_item_ids",
                 )
+                if item_id is None:
+                    blocking_issues.append(
+                        issue
+                        or {
+                            "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+                            "reason_path": f"view_configs[{index}].associated_item_ids",
+                            "received": raw_id,
+                        }
+                    )
+                    continue
+                resolved_ids.append(item_id)
+            resolved_associated_item_refs[f"view_configs[{index}].associated_item_ids"] = resolved_ids
             raw_limit_type = str(view_config.limit_type or ("all" if view_config.visible else "")).strip().lower()
             if view_config.visible and raw_limit_type and raw_limit_type not in {"all", "select"}:
                 blocking_issues.append(
@@ -3851,6 +3858,8 @@ class AiBuilderFacade:
                 for issue in resource_match_issues
             ]
         )
+        if resolved_associated_item_refs:
+            normalized_args["resolved_associated_item_refs"] = deepcopy(resolved_associated_item_refs)
 
         if blocking_issues:
             return finalize(
@@ -4008,12 +4017,13 @@ class AiBuilderFacade:
             resources_after = []
 
         for index, view_config in enumerate(request.view_configs):
+            resolved_view_config_ids = resolved_associated_item_refs.get(f"view_configs[{index}].associated_item_ids", [])
             selected_ids = [
                 item_id
                 for item_id in (
                     _coerce_positive_int(raw_id)
                     for raw_id in [
-                        *view_config.associated_item_ids,
+                        *resolved_view_config_ids,
                         *[client_key_to_id.get(str(ref or "").strip()) for ref in view_config.associated_item_refs],
                     ]
                 )
@@ -4115,6 +4125,7 @@ class AiBuilderFacade:
                     str(index): _summarize_compiled_match_rules(rules)
                     for index, rules in compiled_resource_match_rules.items()
                 },
+                "resolved_associated_item_refs": resolved_associated_item_refs,
             },
             "request_id": None,
             "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
@@ -9657,6 +9668,13 @@ class AiBuilderFacade:
 
         for patch in upsert_charts:
             try:
+                dataset_source = _chart_patch_dataset_source_type(patch)
+                if dataset_source:
+                    raise ValueError(
+                        "app_charts_apply only creates or edits app-source QingBI reports with dataSourceType=qingflow; "
+                        f"dataset report source '{dataset_source}' is not supported for creation/update yet. "
+                        "Create the dataset report in QingBI first, then attach it with app_associated_resources_apply using report_source='dataset'."
+                    )
                 config_update_requested = _chart_patch_updates_chart_config(patch)
                 chart_visible_auth = (
                     self._compile_visibility_to_chart_visible_auth(profile=profile, visibility=patch.visibility)
@@ -9680,6 +9698,13 @@ class AiBuilderFacade:
                 existing_name = str((existing or {}).get("chartName") or "").strip()
                 existing_type = _normalize_backend_chart_type((existing or {}).get("chartType"))
                 target_type = _map_public_chart_type_to_backend(patch.chart_type)
+                existing_source_type = _chart_item_dataset_source_type(existing or {})
+                if existing_source_type:
+                    raise ValueError(
+                        "app_charts_apply only creates or edits app-source QingBI reports with dataSourceType=qingflow; "
+                        f"existing chart '{chart_id or patch.name}' uses dataset report source '{existing_source_type}' and is not supported for update yet. "
+                        "Update it in QingBI directly, then attach the existing report with app_associated_resources_apply using report_source='dataset'."
+                    )
                 if existing is None:
                     temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
                     create_payload = {
@@ -12337,13 +12362,16 @@ def _bi_field_id_for_field(*, app_key: str, field: dict[str, Any], qingbi_fields
 
 
 def _map_public_chart_type_to_backend(chart_type: PublicChartType) -> str:
-    return {
+    aliases = {
         PublicChartType.target: "indicator",
+        PublicChartType.indicator: "indicator",
         PublicChartType.pie: "pie",
         PublicChartType.bar: "bar",
         PublicChartType.line: "line",
         PublicChartType.table: "detail",
-    }[chart_type]
+        PublicChartType.detail: "detail",
+    }
+    return aliases.get(chart_type, chart_type.value)
 
 
 _CHART_PARTIAL_PATCH_KEY_ALIASES = {
@@ -12579,6 +12607,25 @@ def _build_public_metric_fields(
     return metrics or [_default_public_total_metric()]
 
 
+def _split_axis_metric_fields(metrics: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    if not metrics:
+        default_metric = _default_public_total_metric()
+        return [deepcopy(default_metric)], [deepcopy(default_metric)]
+    if len(metrics) == 1:
+        return [deepcopy(metrics[0])], [deepcopy(metrics[0])]
+    return [deepcopy(metrics[0])], [deepcopy(metrics[1])]
+
+
+def _two_gauge_metric_fields(metrics: list[dict[str, Any]], *, requested_metric_count: int) -> list[dict[str, Any]]:
+    if not metrics:
+        return []
+    if len(metrics) == 1:
+        if requested_metric_count <= 0:
+            return [deepcopy(metrics[0])]
+        return [deepcopy(metrics[0]), _default_public_total_metric()]
+    return [deepcopy(metrics[0]), deepcopy(metrics[1])]
+
+
 def _build_public_chart_filter_matrix(
     rules: list[Any],
     *,
@@ -12647,23 +12694,28 @@ def _build_public_chart_config_payload(
     for selector in list(config.pop("query_condition_field_ids", []) or []):
         field = _resolve_public_field(selector, field_lookup=field_lookup)
         query_condition_field_ids.append(_bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id))
+    backend_chart_type = _map_public_chart_type_to_backend(patch.chart_type)
+    if backend_chart_type == "gauge" and not patch.indicator_field_ids and "selectedMetrics" not in config:
+        raise ValueError("gauge charts require at least one indicator_field_ids value; pass one metric and the CLI will pair it with 数据总量")
+    selected_dimensions = _build_public_dimension_fields(
+        patch.dimension_field_ids,
+        app_key=app_key,
+        field_lookup=field_lookup,
+        qingbi_fields_by_id=qingbi_fields_by_id,
+    )
+    selected_metrics = _build_public_metric_fields(
+        patch.indicator_field_ids,
+        app_key=app_key,
+        field_lookup=field_lookup,
+        qingbi_fields_by_id=qingbi_fields_by_id,
+        aggregate=aggregate,
+    )
     payload: dict[str, Any] = {
         "chartName": patch.name,
-        "chartType": _map_public_chart_type_to_backend(patch.chart_type),
+        "chartType": backend_chart_type,
         "dataSource": {"dataSourceId": app_key, "dataSourceType": "qingflow"},
-        "selectedDimensions": _build_public_dimension_fields(
-            patch.dimension_field_ids,
-            app_key=app_key,
-            field_lookup=field_lookup,
-            qingbi_fields_by_id=qingbi_fields_by_id,
-        ),
-        "selectedMetrics": _build_public_metric_fields(
-            patch.indicator_field_ids,
-            app_key=app_key,
-            field_lookup=field_lookup,
-            qingbi_fields_by_id=qingbi_fields_by_id,
-            aggregate=aggregate,
-        ),
+        "selectedDimensions": selected_dimensions,
+        "selectedMetrics": selected_metrics,
         "beforeAggregationFilterMatrix": before_filters,
         "afterAggregationFilterMatrix": after_filters,
         "chartStyleConfigs": deepcopy(config.pop("chartStyleConfigs", [])),
@@ -12679,6 +12731,23 @@ def _build_public_chart_config_payload(
         "queryConditionStatus": bool(config.pop("queryConditionStatus", bool(query_condition_field_ids))),
         "queryConditionExact": bool(config.pop("queryConditionExact", False)),
     }
+    if backend_chart_type == "summary":
+        payload.pop("selectedDimensions", None)
+        payload.setdefault("xDimensions", deepcopy(selected_dimensions))
+        payload.setdefault("yDimensions", [])
+    elif backend_chart_type == "scatter":
+        x_metrics, y_metrics = _split_axis_metric_fields(selected_metrics)
+        payload.pop("selectedMetrics", None)
+        payload.setdefault("xMetrics", x_metrics)
+        payload.setdefault("yMetrics", y_metrics)
+    elif backend_chart_type == "dualaxes":
+        left_metrics, right_metrics = _split_axis_metric_fields(selected_metrics)
+        payload.pop("selectedMetrics", None)
+        payload.setdefault("leftMetrics", left_metrics)
+        payload.setdefault("rightMetrics", right_metrics)
+    elif backend_chart_type == "gauge":
+        payload["selectedDimensions"] = []
+        payload["selectedMetrics"] = _two_gauge_metric_fields(selected_metrics, requested_metric_count=len(patch.indicator_field_ids or []))
     for key in (
         "selectedTime",
         "xDimensions",
@@ -12701,6 +12770,46 @@ def _chart_patch_updates_chart_config(patch: ChartUpsertPatch) -> bool:
     return bool({"dimension_field_ids", "indicator_field_ids", "filters", "config"} & explicit_fields)
 
 
+def _chart_patch_dataset_source_type(patch: ChartUpsertPatch) -> str:
+    config = patch.config if isinstance(patch.config, dict) else {}
+    candidates = [
+        config.get("dataSourceType"),
+        config.get("data_source_type"),
+    ]
+    data_source = config.get("dataSource")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    data_source = config.get("data_source")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    for candidate in candidates:
+        normalized = str(candidate or "").strip().lower()
+        if not normalized:
+            continue
+        if normalized not in {"qingflow", "app"}:
+            return normalized
+    return ""
+
+
+def _chart_item_dataset_source_type(item: dict[str, Any]) -> str:
+    candidates = [
+        item.get("dataSourceType"),
+        item.get("data_source_type"),
+        item.get("sourceType"),
+        item.get("source_type"),
+    ]
+    data_source = item.get("dataSource")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    for candidate in candidates:
+        normalized = str(candidate or "").strip().lower()
+        if not normalized:
+            continue
+        if normalized not in {"qingflow", "app", "bi_qingflow"}:
+            return normalized
+    return ""
+
+
 def _build_public_portal_base_payload(
     *,
     dash_name: str,
@@ -12771,16 +12880,33 @@ def _normalize_backend_chart_type(value: Any) -> str:
         "12": "dualaxes",
         "13": "map",
         "14": "timeline",
+        "15": "area",
+        "16": "stacked_column",
+        "17": "stacked_bar",
+        "18": "rose",
+        "19": "stacked_area",
+        "20": "pct_stack_col",
+        "21": "pct_stack_bar",
+        "22": "pct_stack_area",
+        "23": "waterfall",
+        "24": "gauge",
+        "25": "heatmap",
+        "26": "histogram",
+        "27": "treemap",
+    }
+    aliases = {
+        "percent_stacked_column": "pct_stack_col",
+        "percent_stacked_bar": "pct_stack_bar",
+        "percent_stacked_area": "pct_stack_area",
     }
-    return by_code.get(raw, raw.lower())
+    normalized = by_code.get(raw, raw.lower())
+    return aliases.get(normalized, normalized)
 
 
 def _public_chart_type_from_backend(value: Any) -> str:
     normalized = _normalize_backend_chart_type(value)
     return {
         "indicator": PublicChartType.target.value,
-        "summary": PublicChartType.target.value,
-        "columnar": PublicChartType.bar.value,
         "detail": PublicChartType.table.value,
     }.get(normalized, normalized)
 
@@ -20129,7 +20255,7 @@ def _build_view_associated_resources_payload(
                     "missing_fields": [],
                     "received": raw_item_id,
                     "message": "associated_item_id must be an app-level associated resource id from app_get.associated_resources",
-                    "next_action": "call app_get and use associated_resources[].associated_item_id, not chart_id",
+                    "next_action": "prefer app_associated_resources_apply for associated report/view display; it can resolve associated_item_id, chart_id/chart_key, or view_key",
                 }
             ]
         item_ids.append(item_id)
@@ -20143,7 +20269,7 @@ def _build_view_associated_resources_payload(
                 "invalid_associated_item_ids": missing_ids,
                 "available_associated_item_ids": sorted(available_by_id),
                 "message": "associated_resource references ids that are not in the app-level associated resource pool",
-                "next_action": "call app_get and use associated_resources[].associated_item_id, not chart_id",
+                "next_action": "prefer app_associated_resources_apply for associated report/view display; it can resolve associated_item_id, chart_id/chart_key, or view_key",
             }
         ]
     payload = {
@@ -20561,6 +20687,77 @@ def _associated_resource_upsert_payload_from_existing_item(
     return _compact_dict(payload)
 
 
+def _resolve_associated_resource_selector(
+    selector: Any,
+    *,
+    existing_resources: list[dict[str, Any]],
+    existing_by_id: dict[int, dict[str, Any]],
+    reason_path: str,
+) -> tuple[int | None, dict[str, Any] | None]:
+    item_id = _coerce_positive_int(selector)
+    if item_id is not None:
+        if item_id in existing_by_id:
+            return item_id, None
+    raw = str(selector or "").strip()
+    if not raw:
+        return None, {
+            "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+            "reason_path": reason_path,
+            "received": selector,
+            "available_associated_item_ids": sorted(existing_by_id),
+            "message": "associated resource selector cannot be empty",
+        }
+    matches: list[dict[str, Any]] = []
+    for resource in existing_resources:
+        if not isinstance(resource, dict):
+            continue
+        candidates = [
+            resource.get("chart_id"),
+            resource.get("chart_key"),
+            resource.get("view_key"),
+            resource.get("associated_item_id"),
+        ]
+        if raw in {str(candidate).strip() for candidate in candidates if candidate not in {None, ""}}:
+            matches.append(resource)
+    if len(matches) == 1:
+        resolved_id = _coerce_positive_int(matches[0].get("associated_item_id"))
+        if resolved_id is not None:
+            return resolved_id, None
+    if len(matches) > 1:
+        return None, {
+            "error_code": "AMBIGUOUS_ASSOCIATED_RESOURCE",
+            "reason_path": reason_path,
+            "received": selector,
+            "candidate_associated_item_ids": [
+                item_id
+                for item_id in (_coerce_positive_int(item.get("associated_item_id")) for item in matches)
+                if item_id is not None
+            ],
+            "message": "selector matches multiple associated resources; pass associated_item_id",
+        }
+    return None, {
+        "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+        "reason_path": reason_path,
+        "received": selector,
+        "available_associated_item_ids": sorted(existing_by_id),
+        "available_chart_ids": sorted(
+            {
+                str(resource.get("chart_id") or resource.get("chart_key") or "").strip()
+                for resource in existing_resources
+                if str(resource.get("chart_id") or resource.get("chart_key") or "").strip()
+            }
+        ),
+        "available_view_keys": sorted(
+            {
+                str(resource.get("view_key") or "").strip()
+                for resource in existing_resources
+                if str(resource.get("view_key") or "").strip()
+            }
+        ),
+        "message": "selector must be an associated_item_id, QingBI chart_id/chart_key, or Qingflow view_key from the app-level associated resource pool",
+    }
+
+
 def _associated_resource_not_found_issue(reason_path: str, associated_item_id: int, existing_by_id: dict[int, dict[str, Any]]) -> dict[str, Any]:
     return {
         "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
@@ -20568,7 +20765,7 @@ def _associated_resource_not_found_issue(reason_path: str, associated_item_id: i
         "associated_item_id": associated_item_id,
         "available_associated_item_ids": sorted(existing_by_id),
         "message": "associated_item_id is not in the app-level associated resource pool",
-        "next_action": "call app_get and use associated_resources[].associated_item_id; do not pass chart_id/chart_key",
+        "next_action": "call app_get and use associated_resources[].associated_item_id, chart_id/chart_key, or view_key",
     }
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -43,8 +43,9 @@ def build_builder_server() -> FastMCP:
             "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. "
             "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. "
             "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
-            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, not chart_id/chart_key. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
+            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -2976,6 +2976,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "graphType": "graph_type",
             "targetAppKey": "target_app_key",
             "chartKey": "chart_key",
+            "chartId": "chart_key",
             "viewKey": "view_key",
             "viewgraphKey": "view_key",
             "reportSource": "report_source",
@@ -2990,12 +2991,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view_configs[].limit_type": ["all", "select"],
         },
         "execution_notes": [
+            "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
+            "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
             "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
             "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
-            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; it is not chart_id, chart_key, or view_key",
+            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
             "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
             "graph_type=view uses view_key and internally compiles to the Qingflow view source; graph_type=chart uses chart_key and defaults to report_source=app",
-            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET; do not pass raw backend sourceType",
+            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET for associating an existing dataset report; do not pass raw backend sourceType",
             "use match_mappings for associated view/report filtering; dynamic conditions use source_field and static conditions use value",
             "match_mappings.source_field accepts source schema fields plus system fields 数据ID(-17) and 编号(0); match_mappings compiles to backend matchRules",
             "do not write raw match_rules unless preserving a legacy backend config; match_mappings and match_rules are mutually exclusive",
@@ -3673,7 +3676,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "can_edit_form covers form/schema routes only and does not imply app base-info writes",
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
-            "associated_resources[].associated_item_id is the id required by app_associated_resources_apply.view_configs.associated_item_ids; do not pass chart_id there",
+            "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3797,6 +3800,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
             "execution_notes": [
+                "this tool manages QingBI report bodies/configs; it does not attach reports to Qingflow app associated-resource display",
+                "app_charts_apply creates/updates app-source QingBI reports only; generated payloads use dataSourceType=qingflow",
+                "dataset BI reports are not created or edited by this tool yet; create them in QingBI first, then attach the existing report with app_associated_resources_apply report_source=dataset",
+                "after creating or updating an app-source report body, use app_associated_resources_apply when the report should appear inside a Qingflow app/view",
                 "app_charts_apply is immediate-live and does not publish",
                 "use patch_charts for partial parameter replacement on existing charts; the tool reads current chart base/config, merges patch_charts[].set/unset, then submits full QingBI base/config payloads internally",
                 "chart matching precedence is chart_id first, then exact unique chart name",