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

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.7
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.9
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.7 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.7",
+  "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.7"
+version = "1.0.9"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -52,28 +52,49 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - 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
+- Partial update rule:
+  - for existing views, custom buttons, associated resources, and charts, prefer `patch_views` / `patch_buttons` / `patch_resources` / `patch_charts`
+  - each patch item uses the object's real selector field (`view_key` / `button_id` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
+  - use `upsert_*` for creation or full target configuration; do not send a partial `upsert_*` and expect the backend to merge missing required fields
 - Portal work:
   - `portal_apply` is the public write path
   - 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
 - Button work:
   - `app_custom_buttons_apply` is the public write path for custom button bodies and view placement
+  - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
   - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
+  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`)
+  - to prefill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`; use `default_values` only for static constants
+  - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
   - bind buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
+  - builder `view_configs[].view_key` uses the raw key from `app_get.views[].view_key`, without a `custom:` prefix
   - `buttons` is required in merge mode; do not send a view config with only `view_key`
   - `view_configs[].mode` defaults to `merge`; use `mode: "replace"` or an explicit empty `buttons: []` to clear a view's custom button bindings
-  - `placement=list` is experimental because some backend deployments reject it with `LIST_BUTTON_BACKEND_UNSUPPORTED`
+  - `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
-  - `associated_item_id` must come from `app_get.associated_resources[].associated_item_id`; it is not `chart_id`, `chart_key`, or `view_key`
-  - 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"`
+  - `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` 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 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:
   - stay on `app_views_apply` / `app_flow_apply`
+  - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
+  - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
   - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
   - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
@@ -100,8 +121,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
    - flow -> `app_flow_apply`
-   - views -> `app_views_apply`
-   - charts -> `app_charts_apply`
+   - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
+   - existing buttons -> `app_custom_buttons_apply.patch_buttons`; new/full buttons -> `app_custom_buttons_apply.upsert_buttons`
+   - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
+   - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
 8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
@@ -127,6 +150,9 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
+- For object apply tools, distinguish clearly between:
+  - `patch_*`: public partial parameter replacement; the tool hydrates current config and full-saves internally
+  - `upsert_*`: create or full target configuration; omitted fields may mean default/clear depending on that object
 - For charts, distinguish clearly between:
   - base / visibility change
   - real chart-config change
@@ -149,10 +175,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Add/update/remove fields: `app_schema_apply`
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
-- Upsert/remove views: `app_views_apply`
-- Upsert/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
-- Manage app associated reports/views and per-view display: `app_associated_resources_apply`
-- Upsert/remove/reorder charts: `app_charts_apply`
+- Upsert/patch/remove views: `app_views_apply`
+- Upsert/patch/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
+- Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
+- Upsert/patch/remove/reorder charts: `app_charts_apply`
 - Create or update portal pages: `portal_apply`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Final publish verification: `app_publish_verify`
@@ -176,8 +202,9 @@ Use `app_custom_buttons_apply` for the whole custom-button path: button body, ad
         "trigger_add_data_config": {
           "target_app_key": "WORKLOG_APP",
           "field_mappings": [
-            {"source_field": "员工名称", "target_field": "员工"},
-            {"source_field": "所属部门", "target_field": "部门"}
+            {"source_field": "数据ID", "target_field": "关联员工"},
+            {"source_field": "员工名称", "target_field": "员工姓名"},
+            {"source_field": "所属部门", "target_field": "部门名称"}
           ],
           "default_values": {
             "工时类型": "日常工作",
@@ -200,13 +227,16 @@ Use `app_custom_buttons_apply` for the whole custom-button path: button body, ad
 }
 ```
 
-`button_ref` may be a same-call `client_key` or an existing `button_id`. Default placements are `header` and `detail`; `list` is experimental and should only be used when the user explicitly asks for row/list buttons.
+`button_ref` may be a same-call `client_key` or an existing `button_id`. Supported placements are `header`, `detail`, and `list`; `list` maps to the backend `INSIDE` row/list button position.
+
+For add-data buttons that create a child record linked back to the current record, map `source_field: "数据ID"` to the target relation field. Do not use raw `que_relation` unless maintaining an existing backend config.
 
 ## Resources
 
 - Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
 - Environment switching: [references/environments.md](references/environments.md)
 - 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)
 - 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)

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

@@ -25,16 +25,37 @@
 - `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.
+- 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`.
 - 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` is experimental for row/list buttons. Some backend deployments still reject it. If the tool returns `LIST_BUTTON_BACKEND_UNSUPPORTED`, treat `header/detail` as applied when verified and report list placement as unsupported by the current backend route.
+- `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
+
+## Associated resources
+
+- 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.
 
 ## Readback scope
 
@@ -44,6 +65,15 @@
 - Use `app_get_flow` before workflow work
 - Use `app_get_views` before view work
 
+## Partial update discipline
+
+- Existing views, custom buttons, 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.
+- `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.
+
 ## Workflow dependencies
 
 - Approval-style flows usually require an explicit status field
@@ -66,6 +96,7 @@
   - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
   - `permissions.editable_fields`
 - For view work, treat `columns` as the only canonical public key. `app_get_views` and `app_views_apply` should all be read and written in that shape.
+- For existing view parameter changes, prefer `patch_views`. Example: to change only query-panel fields, set only `query_conditions`; the tool will preserve columns, filters, date config, card fields, buttons, and other backend-required fields.
 - For layout work, treat `title + rows` as the only canonical public section shape. `fields`, `field_ids`, and `columns` may appear in legacy/internal shapes, but they are not the preferred public write shape.
 - A created view is not enough to claim a filter succeeded. When `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, treat the view as present but the filter as unverified.
 - If duplicate view names exist, do not retry by name. Read the exact `view_key` and target that one.

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

@@ -0,0 +1,114 @@
+# Builder Match Rules
+
+Use this reference for builder-side field matching rules in custom buttons 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_associated_resources_apply.upsert_resources[].match_mappings`
+- `app_associated_resources_apply.patch_resources[].set.match_mappings`
+
+Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
+
+## System Fields
+
+System fields can participate in mappings:
+
+- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
+  This is the current record's real apply/record ID.
+- `编号`, `数据编号`, `record_number` -> `field_id=0`
+  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
+
+Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
+
+## Custom Buttons
+
+Use `field_mappings` for dynamic values copied from the current source record:
+
+```json
+{
+  "target_app_key": "WORKLOG_APP",
+  "field_mappings": [
+    {"source_field": "数据ID", "target_field": "关联员工"},
+    {"source_field": "员工名称", "target_field": "员工姓名"}
+  ],
+  "default_values": {
+    "状态": "待提交"
+  }
+}
+```
+
+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`:
+
+```json
+{
+  "button_id": 3858041,
+  "set": {
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"}
+      ],
+      "default_values": {
+        "状态": "待提交"
+      }
+    }
+  }
+}
+```
+
+## Associated Resources
+
+Use `match_mappings` for associated view/report filters:
+
+```json
+{
+  "graph_type": "view",
+  "target_app_key": "WORKLOG_APP",
+  "view_key": "WORKLOG_VIEW",
+  "match_mappings": [
+    {"target_field": "关联员工", "source_field": "数据ID"},
+    {"target_field": "状态", "value": "待提交"}
+  ]
+}
+```
+
+Dynamic conditions use `source_field`; static conditions use `value`.
+
+For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
+
+```json
+{
+  "associated_item_id": 3497587,
+  "set": {
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"}
+    ]
+  }
+}
+```
+
+## Type Compatibility
+
+- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
+- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
+- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
+- Member fields: only match member fields.
+- Department fields: only match department fields.
+- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
+- Date fields: date and datetime can match each other.
+- Text fields: text, long text, phone, and email can match each other.
+- Number fields: number and amount can match each other.
+- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
+
+## Error Interpretation
+
+- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
+- Type mismatch: choose a compatible source/target pair from the matrix above.
+- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
+- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.

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

@@ -45,12 +45,14 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_schema_apply`: create app shell or change fields
 - `app_layout_apply`: merge or replace layout
 - `app_flow_apply`: replace workflow
-- `app_views_apply`: upsert or remove views
-- `app_custom_buttons_apply`: create, update, or remove custom buttons; configure add-data field mappings/default values; bind buttons to header/detail view positions; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings; `placement=list` is experimental
-- `app_associated_resources_apply`: manage app associated reports/views and per-view display config; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only for BI dataset reports
-- `app_charts_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `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`: 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.
+
 ## Explicit post-apply tools
 
 - `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
@@ -70,9 +72,11 @@ These execute normalized patches. Some app apply tools publish by default and st
 - Add workflow:
   `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
 - Add views:
-  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply -> app_get_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 -> app_get_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,9 +30,11 @@ 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 `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`.
+- For an existing view, prefer `patch_views` for parameter replacement. Do not send a partial `upsert_views` object such as only `name/type/query_conditions`; backend view saves require other type-specific fields, and the patch path preserves them for you.
 
 Apply a default table view:
 
@@ -57,7 +59,7 @@ Apply a default table view:
 ```
 After `app_views_apply` returns canonical arguments or blocking issues, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
 
-Table view with fixed filter plus frontend query conditions:
+Existing table view: replace only frontend query conditions:
 
 ```json
 {
@@ -66,23 +68,16 @@ Table view with fixed filter plus frontend query conditions:
     "profile": "default",
     "app_key": "APP_123",
     "publish": true,
-    "upsert_views": [
+    "patch_views": [
       {
-        "name": "客户查询视图",
-        "type": "table",
-        "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
-        "filters": [
-          {
-            "field_name": "客户状态",
-            "operator": "eq",
-            "value": "有效"
+        "view_key": "VIEW_KEY",
+        "set": {
+          "query_conditions": {
+            "enabled": true,
+            "exact": false,
+            "hide_before_query": false,
+            "rows": [["客户名称", "负责人"], ["创建时间"]]
           }
-        ],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["客户名称", "负责人"], ["创建时间"]]
         }
       }
     ],
@@ -96,6 +91,7 @@ Meaning:
 - `filters` are saved view filters and apply immediately when the view opens.
 - `query_conditions` only configures which fields appear in the frontend query panel. The query values come later from the user through the page.
 - `query_conditions.rows` is a matrix of field names and is compiled to backend `queryCondition` field ids.
+- The patch call preserves the view's existing columns, saved filters, type-specific date/card/board config, buttons, visibility, and other backend-required fields.
 
 View associated resources example:
 
@@ -120,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`. 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`.
+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:
 
@@ -136,7 +132,11 @@ Create and show a BI indicator-card report in the same call:
         "graph_type": "chart",
         "target_app_key": "TIMESHEET_APP",
         "chart_key": "CHART_KEY",
-        "report_source": "app"
+        "report_source": "app",
+        "match_mappings": [
+          {"target_field": "关联员工", "source_field": "数据ID"},
+          {"target_field": "状态", "value": "待提交"}
+        ]
       }
     ],
     "remove_associated_item_ids": [],