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

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

@@ -3,7 +3,7 @@
 ## Auth and workspace
 
 - `auth_*` success does not mean a workspace is selected
-- In Wingent Momo runtime, do not run `workspace_select` before builder work. Re-run it only after an explicit auth/route recovery or when a business tool reports the workspace is missing.
+- Re-run `workspace_select` after auth changes or route changes
 
 ## Package ownership
 
@@ -17,14 +17,13 @@
 - Another app is not a field
 - If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
 - Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
-- For a complete system, the main creation path is one multi-app `app_schema_apply(package_id=..., apps=[...])` with stable `apps[].client_key` values and same-call relation fields using `target_app_ref`
-- Use `target_app_key` only for an app that already exists or has been confirmed by readback
 
-## Auto publish
+## Publish
 
-- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
-- For those four tools, pass `publish=false` 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 `publish=false`
+- 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_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
 
 ## BI Reports
@@ -33,25 +32,18 @@
 - 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.
-- Main chart config should use semantic `metric`, `metrics`, `group_by`, and `where`; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices unless diagnosing or preserving existing raw config.
 - `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`.
-- Use `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Record schema fields or normal form fields are not enough for chart apply.
-- Use `target` / `indicator` for one metric card; do not use `summary` for a single KPI.
 
 ## Custom buttons
 
-- For ordinary view-specific business buttons, use `app_views_apply` with `action_buttons`; do not use legacy `app_views_apply.buttons` unless you are maintaining an old full-replacement patch.
-- Use `app_custom_buttons_apply` for advanced button creation/update/removal and view placement: custom style/icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
+- 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.
-- `addData` / `add_data` creates a related/downstream Qingflow record; use current-record `field_mappings` only on `detail` or `list`. `link` only opens a URL. `qRobot`/`wings` require user-provided exact config and must not be invented.
 - 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.
-- Do not put current-record `field_mappings` on a `header` button; `header` has no current row. Use `detail` or `list` for current-record add-data actions.
-- Do not model approval, rejection, close-task, or status transition as a generic `link` button. Use workflow/task behavior, or `qRobot`/`wings` only when the user provides existing automation config.
 - For field type compatibility, read `references/match-rules.md`.
-- Use `header` for global actions with no current-row context, `detail` for safest current-record actions, and `list` for row/list actions.
+- 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.
@@ -80,14 +72,7 @@
 - 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; use `patch_sections[]` for one-section updates.
-- PC portal layout is 24-column. Group components by the same `y`: all components in that row must have the same `rows`, and their `cols` should sum to 24 unless the user explicitly wants blank space.
-- Standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`.
-- Business-entry `grid` sections must include real `config.items[]`; an empty grid container is not a valid business entrance.
-- Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known by readback. Intended names are not enough.
-- Use standard order: business entry -> metric cards -> BI charts -> concrete data views.
-- Do not use platform default views such as `全部数据` / `我的数据` as the main portal views.
-- Do not use portal `source_type: "filter"` as the normal automation path; it is raw/unstable and not part of the unified filter DSL.
+- `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
@@ -104,16 +89,9 @@
 ## Retry discipline
 
 - If a write returns `partial_success`, read back before retrying
-- If multi-app schema apply times out, returns `write_executed=true`, returns `safe_to_retry=false`, or has incomplete readback, treat it as `write_may_have_succeeded`; the next action is `readback_before_retry`
-- `readback_before_retry` means read package/app/fields first, classify which intended apps and relation fields actually exist, and retry only the verified missing slice
 - Do not repeat create steps after `app_key` already exists
-- Do not split a complete-system schema create into single-app rebuilds until readback proves exactly what is missing
-- Do not bypass duplicate/conflict states by inventing `V2`, `测试`, timestamp, or random-suffix app names in a real business package
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
-- For `builder_tool_contract`, read the returned `json_paths` first. Successful contract data is under `$.contract`; `allowed_values` uses flat dotted keys such as `["field.type"]`, not nested objects. Do not read successful field enums from top-level `allowed_values`.
-- For `workspace_icon_catalog_get`, read icon candidates from `$.icon_names` and colors from `$.icon_colors`.
-- For builder apply responses, read returned `json_paths` first. Stable fields are `$.summary` and `$.resources[]`; use `resources[].id/key/name` before legacy top-level fields.
 - For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
 - For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
   - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`

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

@@ -4,12 +4,6 @@ Use this reference for builder-side field matching rules in custom buttons and a
 
 This is not the same thing as `record_access` analysis filters or normal view `filters`.
 
-Unified public semantics:
-
-- Fixed filters use `field_name + operator + value/values`, for example view `filters` and chart `filters`.
-- Current-record context matches use `target_field + operator + source_field/value`, for example associated resource `match_mappings` and add-data button mappings.
-- Do not handwrite `judgeType`, `judgeValues`, or `matchRules`; the CLI compiles them for the target backend protocol.
-
 ## Where These Rules Apply
 
 - `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
@@ -86,15 +80,6 @@ Use `match_mappings` for associated view/report filters:
 
 Dynamic conditions use `source_field`; static conditions use `value`.
 
-Recommended operators are `eq`, `neq`, `in`, `contains`, `gte`, `lte`, `is_empty`, and `not_empty`; aliases such as `equal`, `equals`, `=`, `!=`, `any_of`, `one_of`, and `empty` are accepted. `field_name` and `field` can be used as aliases for `target_field`. Static single-value filters should use `value`; a single-item `values` array is also accepted.
-
-Examples:
-
-```json
-{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
-{"target_field": "状态", "operator": "eq", "value": "有效"}
-```
-
 For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
 
 ```json

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

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

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

@@ -19,40 +19,28 @@ Before picking tools, decide which layer the request targets:
 
 If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
 
-Use this split consistently:
-
-- Complete system/package: `package_apply` first, then one `app_schema_apply(package_id=..., apps=[...])`.
-- Single app: `app_resolve/app_get` first, then app-scoped apply tools.
-- Record/task/data operation: leave builder and use record/task skills.
-
-Decision gate before writing:
-
-| Evidence | Action |
-| --- | --- |
-| User gives an `app_key`, `view_key`, `chart_id`, `dash_key`, or exact `package_id` | Treat the task as an update to that existing target unless the user explicitly asks for a new one |
-| User names several forms/modules or asks for a system/package | Use the complete-system path; do not compress them into one app |
-| Same or very similar package/app already exists and the user did not say extend/replace/new | Stop and ask whether to extend existing, repair missing parts, or create a new target |
-| Existing readback already contains part of the requested system | List verified existing resources, identify gaps, and patch only missing or incorrect slices |
-| A write is uncertain: timeout, `partial_success`, `write_executed=true`, or `safe_to_retry=false` | Read back before retrying; do not create `V2`, `测试`, timestamp, or random-suffix resources |
-
 ## Resolve
 
-- `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
-- `package_apply`: create or update one package; `package_name` without `package_id` creates a package; layout/group/order changes require package edit permission because they call the backend package ordering route
+- `package_get`: read one known package by `package_id`
+- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent
 - `member_search`: resolve named people from the directory
 - `role_search`: resolve reusable roles from the directory
 - `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`; by-name resolution checks package detail/current visible apps before using broader admin-style app search, so a `/app/item` permission miss is not a frontend-visible-app failure
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
 
 ## Summary reads
 
+All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch). Batch returns `{status, apps[], errors[]}` — prefer batch when reading multiple apps in one step.
+
 - `app_get`: overall app config health, publish state, counts, and builder editability
 - `app_get_fields`: field names, types, required flags, section ids
 - `app_get_layout`: sections, rows, unplaced fields
 - `app_get_views`: current view names, types, columns, group-by
-- `app_get_flow`: workflow enabled state, nodes, transitions
+- `app_get_flow`: workflow enabled state, full spec (nodes + transitions)
 - `app_get_charts`: current chart ids, names, types, order
-- `chart_get`: one chart's base/config detail; base info is read through the Qingflow/qflow visible route first, and config may degrade from chart data when the CHART_SEE config endpoint is unavailable. Treat degraded config as a read-mode warning, not as proof the user cannot see the chart.
+- `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
 
 ## Apply tools
@@ -60,15 +48,15 @@ Decision gate before writing:
 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
-- `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; for normal view-specific business buttons, declare `action_buttons` in the view object or `patch_views[].set`; new views default associated report/view display to visible with `limit_type="all"`
-- `app_custom_buttons_apply`: advanced custom-button maintenance only: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering bindings, or exact qRobot/wings configs. Use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; 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. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. 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` with `target_field + operator + source_field/value` 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 `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Use semantic `metric`, `metrics`, `group_by`, and `where`: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, and `dualaxes` for two-metric comparison. Do not use `summary` for a single metric card. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices on the main path; charts are immediate-live and do not publish; use `chart_id` when names are not unique; for complete systems, keep chart writes business-scoped, commonly 4-8 upserts by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
-- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; create mode only prechecks package add_app, matching backend portal creation; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics. Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known. PC layout uses 24 columns: components with the same `y` must have the same `rows`, same-row `cols` should sum to 24, metric cards use `rows=5`, BI charts use `rows=7`, data views use `rows=11`, and business-entry grids must include real `config.items[]`. Use business entry -> metrics -> BI charts -> concrete data views; do not use platform default views or raw `source_type: "filter"` as the main path.
+- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
+- `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_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
 
-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.
+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.
 
 ## Explicit post-apply tools
 
@@ -79,29 +67,27 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create one app inside an existing package:
   `package_get -> app_resolve -> app_schema_apply`
 - Create a brand new package, then create one app in it:
-  `package_apply(package_name, icon, color) -> app_schema_apply`
+  `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(package_name, icon, color) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
 - 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`
 - 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 ordinary view buttons:
-  `app_get_views -> app_views_apply.patch_views/upsert_views with action_buttons -> app_get_views`
-- Maintain advanced custom buttons:
-  `app_get -> app_custom_buttons_apply.patch_buttons/upsert_buttons + view_configs -> 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`
-- Patch one portal section:
-  `portal_get -> portal_apply.patch_sections[] -> portal_get`
+- Update portal section(s) without replacing all:
+  `portal_get -> portal_apply.patch_sections[]`
 
 ## Avoid
 
@@ -119,4 +105,3 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
-- Do not force agent-authored schema into backend-internal names when public keys exist: write icons as `icon + color` first; `icon_config` / `icon:{name,color}` are compatibility aliases only. Options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

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

@@ -6,19 +6,18 @@ Use this when the app already exists and the task is only about workflow.
 
 1. `builder_tool_contract(tool_name="app_flow_apply")`
 2. `app_get_fields`
-3. Confirm the app has one explicit business status field, usually a `select` named `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
-4. `app_get_flow`
-5. `role_search` or `member_search`
-6. `role_create` if the user wants a reusable directory role and no good role exists
-7. start from a canonical preset when possible
-8. patch the skeleton instead of freehanding a full graph
-9. reuse preset node ids when patching:
+3. `app_get_flow`
+4. `role_search` or `member_search`
+5. `role_create` if the user wants a reusable directory role and no good role exists
+6. start from a canonical preset when possible
+7. patch the skeleton instead of freehanding a full graph
+8. reuse preset node ids when patching:
    - `basic_approval` -> patch `approve_1`
    - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
    Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
    The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
-10. `app_flow_apply`
-11. `app_get_flow` when apply returns `partial_success` or the user asked for verification
+9. `app_flow_apply`
+10. `app_get_flow` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -62,6 +61,34 @@ For flexible business requirements, do not jump straight to a full custom graph.
 2. identify the business-specific changes
 3. patch nodes/transitions explicitly
 
+## Targeted node updates
+
+To change one or a few nodes without rewriting the full spec, use `patch_nodes[]` instead of `spec`:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "patch_nodes": [
+      {
+        "id": "approve_1",
+        "set": {
+          "name": "总监审批",
+          "assignees": {"role_names": ["总监"]}
+        }
+      }
+    ]
+  }
+}
+```
+
+`patch_nodes[]` reads the current flow, merges `set` keys and removes `unset` keys on the matched node, then writes the full spec back. It returns `FLOW_NODE_NOT_FOUND` if the `id` does not match any existing node — call `app_get_flow` first to confirm ids.
+
+Do NOT use `patch_nodes` and `spec` together in the same call.
+
 Public flow building is intentionally limited to linear workflows. Use only:
 
 - `start`
@@ -97,18 +124,7 @@ Preferred fix order:
 
 ### `FLOW_DEPENDENCY_MISSING`
 
-The workflow depends on fields that do not exist yet, usually an explicit business status field. Fix schema first.
-
-Do:
-
-- add a business field such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
-- use type `select` / `single_select`
-- use business options such as `草稿`, `进行中`, `已完成`
-
-Do not:
-
-- create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
-- skip the flow and still report workflow completion
+The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
 
 Preferred recovery:
 
@@ -161,7 +177,7 @@ Do not copy internal keys from old plan outputs or logs, including:
 
 ## Notes
 
-- `mode=replace` is the only supported flow apply mode
+- `mode=replace` is the only supported flow apply mode when using `spec`; `patch_nodes[]` does not require a `mode`
 - `app_flow_apply` publishes by default
 - Prefer roles over explicit members unless the user explicitly asks for named members
 - `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows

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

@@ -10,18 +10,6 @@ Use this when the app already exists and the task is only about fields.
 
 ## Example
 
-Do not add platform system fields as form controls: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by Qingflow; use readback/list fields when you need them.
-
-Field patch rules:
-
-- Re-read fields first, then choose `add_fields`, `update_fields`, or `remove_fields`. If a field already exists, use `update_fields` instead of adding a duplicate.
-- Drafts may use intuitive type aliases: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`, `currency -> amount`, `mobile -> phone`. Readback canonical types are normal and do not prove a failed update.
-- `title` and `label` are accepted aliases for `name`, but the preferred public key is `name`.
-- Keep exactly one top-level data title field after the patch. `as_data_cover` is optional and only valid on top-level `attachment`.
-- Select fields must keep a clear `options` set. Sample data and filters should use those option labels or ids.
-- Relation fields must use `target_app_key` for existing apps, or `target_app_ref` only in same-batch app creation. `display_field` and `visible_fields` are selector objects such as `{"name": "客户名称"}`, not bare strings.
-- Do not impose a one-relation-field limit when updating schema; add the relation fields the business needs and rely on backend validation/readback.
-
 Read current fields first:
 
 ```json
@@ -76,11 +64,9 @@ Treat it as uncertain write state. Read back with `app_get_fields` before retryi
 
 - `title` and `label` are accepted aliases for `name`
 - `textarea -> long_text`
-- `multiline` / `multiline_text -> long_text`
 - `currency -> amount`
 - `mobile -> phone`
 - `select/radio -> single_select`
 - `checkbox -> multi_select`
 - `as_data_title: true` marks the app data title; the final form must have exactly one top-level data title field
 - `as_data_cover: true` marks the app data cover; the cover is optional and must be a top-level `attachment` field
-- `数据ID`, `编号`, applicant/creation/update time, and workflow status fields are system-generated and must not appear in `add_fields`

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

@@ -28,25 +28,17 @@ Canonical rules before any example:
 - Always use `columns`
 - Do not emit `column_names`
 - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
-- Use `filters` with the unified fixed-filter DSL: `field_name`, `operator`, `value`/`values`; do not write raw `judgeType` / `judgeValues`
+- 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`.
-- Do not create views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`. These are built-in default/system views. New views must use business-specific names such as `订单台账视图`, `客户跟进视图`, or `逾期任务看板`.
-- To change a built-in default/system view, first read the existing raw `view_key` from `app_get.views` or `app_get_views`, then use `patch_views` or a full `upsert_views` item with that `view_key`.
+- When creating any new table or card view, always include `query_conditions` with `enabled: true`. In `rows`, list the fields users would most commonly search by — typically the data-title field, any status/type select fields, date fields, and member fields. Do not omit `query_conditions` or leave `rows` empty on a new view.
 - New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
-- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. `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` with `target_field + operator + source_field/value` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. `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.
-- For ordinary view-specific business buttons, declare `action_buttons` inside `upsert_views[]` or `patch_views[].set`. Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
-- Choose the button by user intent before choosing a trigger type:
-  - current record -> downstream/related record: `add_data` with `target_app_key + field_mappings`
-  - global independent entry: `add_data` on `header` without current-record `source_field`
-  - URL/SOP/help page: `link` with `url`
-  - approval/status transition/close task: do not fake it with a normal button; use workflow/task action or exact existing automation config
-- Button placement choice: `header` is global and has no current-row context; `list` is row/list action; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`.
 
-Apply a business table view:
+Apply a default table view:
 
 ```json
 {
@@ -57,10 +49,16 @@ Apply a business table view:
     "publish": true,
     "upsert_views": [
       {
-        "name": "订单台账视图",
+        "name": "全部订单",
         "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+        "columns": ["订单编号", "客户名称", "订单金额", "状态", "负责人", "创建时间"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["订单编号", "客户名称"], ["状态", "负责人"], ["创建时间"]]
+        }
       }
     ],
     "remove_views": []
@@ -69,48 +67,6 @@ Apply a business 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`.
 
-Create a table view with ordinary business buttons:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "upsert_views": [
-      {
-        "name": "工单执行视图",
-        "type": "table",
-        "columns": ["工单编号", "产品", "状态", "负责人"],
-        "action_buttons": [
-          {
-            "text": "创建质检单",
-            "action": "add_data",
-            "target_app_key": "QUALITY_APP",
-            "field_mappings": [
-              {"source_field": "数据ID", "target_field": "关联工单"}
-            ],
-            "default_values": {"处理状态": "待处理"},
-            "placement": "detail",
-            "visible_when": [
-              {"field_name": "状态", "operator": "eq", "value": "已完工"}
-            ]
-          },
-          {
-            "text": "查看作业说明",
-            "action": "link",
-            "url": "https://example.com/sop",
-            "placement": "header"
-          }
-        ]
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-
 Existing table view: replace only frontend query conditions:
 
 ```json
@@ -321,32 +277,7 @@ At least one `query_conditions.rows` field does not exist on the app.
 
 ### `INVALID_QUERY_CONDITION_FIELD`
 
-The field exists but cannot be used in the frontend query-condition panel.
-
-Supported `query_conditions.rows` fields are query-panel fields:
-
-- text / long text
-- number / amount
-- date / datetime
-- single select / multi select
-- member / department
-- phone / email
-- boolean
-
-Do not use these fields in `query_conditions`:
-
-- relation
-- attachment
-- subtable or subtable subfield
-- address/location
-- Q-Linker
-- code block
-
-Fix path:
-
-- If you wanted a saved filter that opens with the view, use `filters`.
-- If you wanted a related report/view to match the current record, use `app_associated_resources_apply.match_mappings`.
-- If you only need frontend search fields, remove unsupported fields from `query_conditions.rows` and keep query-panel supported fields only.
+The field exists but cannot be used in the frontend query-condition panel, such as attachment, relation, Q-Linker, code block, location/address, or subtable/subfield selections.
 
 ## Notes
 
@@ -355,6 +286,6 @@ Fix path:
 - `app_get_views` should be treated as canonical readback and now returns `columns`
 - If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_get_views`; then retry with the exact `view_key`
 - `filters` are ANDed together as one flat condition group
-- `query_conditions.rows` does not mean OR; it controls frontend query-field layout and should only contain query-panel supported fields
+- `query_conditions.rows` does not mean OR; it controls frontend query-field layout
 - `app_views_apply` publishes by default
 - For select-style filters, success means the backend preserved the option value in readback, not just that the view name now exists

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

@@ -1,14 +1,12 @@
 ---
 name: qingflow-app-builder-code-integrations
-description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. In Wingent Momo runtime, use the injected MCP session and recover auth/workspace only after a tool error.
+description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
 metadata:
   short-description: Configure Qingflow code blocks and Q-Linkers safely
 ---
 
 # Qingflow App Builder Code Integrations
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
-
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields
@@ -60,7 +58,7 @@ For code block or Q-Linker work, use this order:
 
 1. Resolve the app and read fields:
    - `app_resolve`
-   - `app_get_fields`
+   - `app_read_fields`
 2. Confirm the target field set already exists.
 3. Apply schema updates with `app_schema_apply`.
 4. Read fields again and verify:
@@ -117,7 +115,7 @@ Hard rules:
 
 After each code block or Q-Linker change, verify all of these:
 
-- `app_get_fields` shows the intended field type
+- `app_read_fields` shows the intended field type
 - the high-level config is readable and stable
 - target fields still have valid types
 - insert schema can be opened

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -59,7 +59,7 @@ Do not bind code block outputs to:
 
 ## Safe Verification
 
-- `app_get_fields`
+- `app_read_fields`
 - `record_insert_schema_get`
 - optional `record_code_block_run`
 

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -70,7 +70,7 @@ Avoid:
 
 ## Safe Verification
 
-- `app_get_fields`
+- `app_read_fields`
 - `record_insert_schema_get`
 - `record_insert`