@josephyan/qingflow-app-builder-mcp 1.1.3 → 1.1.5

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

@@ -0,0 +1,123 @@
+# Complete System Development Guide
+
+Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
+Do not compress several business objects into one app.
+
+## Recommended Completeness
+
+Required:
+
+- package exists or is created through `package_apply`
+- core business objects are modeled as separate apps
+- all new apps are created in one multi-app `app_schema_apply(package_id=..., apps=[...])`
+- every app has stable `client_key`, `app_name`, `icon`, `color`, and one readable `as_data_title: true`
+- no app creates platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
+- same-call relations use `target_app_ref` to point to another `apps[].client_key`
+- basic operating views exist for each core app
+- package/apps/fields/relations are read back before repair or retry
+
+Strongly recommended:
+
+- cross-app relation fields for the main business links
+- core metric charts and BI charts using semantic `metric`, `metrics`, `group_by`, and `where`
+- a standard portal: business entry area, core metrics, BI charts, then concrete data views
+- portal grid/business-entry sections contain real `config.items[]`, not empty containers
+
+Workflow preflight:
+
+- If an app will have approval/fill/copy workflow nodes, create an explicit business status `select` field in schema first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
+- Do not create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- If `app_flow_apply` returns `FLOW_DEPENDENCY_MISSING`, fix schema with the returned `suggested_next_call`, read fields back, then retry the flow. Do not skip the workflow silently.
+
+Optional:
+
+- workflow, reminders, buttons, associated resources, sample data, roles, and permissions when the user asks for them or the business process clearly depends on them
+
+## Standard Path
+
+1. Resolve or create package: `package_get` / `package_apply`.
+2. Draft all apps and relations with stable `client_key` values.
+3. Run one multi-app `app_schema_apply` with `apps[]`.
+4. If write result is uncertain, run readback before retrying.
+5. For each app, apply layout and views.
+6. Create charts before portals when the portal needs metrics or BI sections. Submit chart upserts in batches of 4-8; if `CHART_UPSERT_BATCH_TOO_LARGE` appears, execute `details.suggested_batch_payloads[]` one at a time.
+7. Create portal only after referenced apps, views, and charts are known.
+8. Add workflows/buttons/associated resources when they are part of the requested business process.
+9. Before the final response, write the complete-system delivery summary file described below.
+
+## Field Modeling Rules
+
+- Use agent-friendly field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`. The tool normalizes aliases such as `multiline -> long_text` and `select -> single_select`.
+- Create only business fields. Do not create platform system fields listed in Required; reference them only where a tool explicitly supports system fields, such as button `source_field: "数据ID"`.
+- Use `number` for ratios, completion rates, scores, percentages, durations, and quantities that may need decimals. Use `amount` only for currency/money semantics. This prevents sample data from producing decimal values for a field that the backend treats as integer money.
+- For select fields, define the option set during schema design. Later sample data must use only those option labels or ids.
+
+## View Query Rules
+
+- Use `filters` for fixed saved filters that apply when the view opens.
+- Use `query_conditions` only for the frontend query panel layout. It is not another filter DSL and it does not express OR.
+- `query_conditions.rows` should contain query-panel fields such as text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
+- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`.
+- For current-record related views/reports, use `app_associated_resources_apply.match_mappings`, not `query_conditions`.
+
+## Delivery Summary File
+
+For complete-system builds, create or update one local JSON file before the final response:
+
+`tmp/qingflow_system_build_summary.json`
+
+Use this file as the structured source of truth for the final report. Include at least:
+
+```json
+{
+  "package_id": 0,
+  "package_name": "",
+  "portal_dash_key": "",
+  "portal_live_status": "verified | unverified | not_created",
+  "front_end_visible": true,
+  "apps": [
+    {
+      "app_key": "",
+      "app_name": "",
+      "fields_count": 0,
+      "views_count": 0,
+      "flows_count": 0,
+      "charts_count": 0,
+      "publish_verify_status": "verified | unverified | failed"
+    }
+  ],
+  "warnings": [],
+  "partial_items": [],
+  "needs_followup": []
+}
+```
+
+Rules:
+
+- Populate IDs and counts from readback, not from intended payload only.
+- If a required resource is not verified, put it in `partial_items` or `needs_followup` instead of reporting the system as fully complete.
+- If the user later adds a data-entry task, keep that separate from the system-build summary unless the user explicitly wants one combined report.
+- The final response should match this file: completed resources, unverified items, frontend visibility, and follow-up needs must not contradict the JSON.
+- When running from the CLI repo or a test harness, validate the file with:
+  `python scripts/validate_system_build_summary.py tmp/qingflow_system_build_summary.json`.
+
+## Recovery Rules
+
+- Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means `write_may_have_succeeded`.
+- Next action is always `readback_before_retry`: read package, resolve intended apps, then read fields/relations.
+- Retry only verified missing apps, fields, or relations.
+- Do not rebuild the system as separate single-app creates.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
+## Portal Template
+
+- Top area: one business entry grid plus one todo/common/frequent component when useful.
+- Metrics: one row of 4-6 indicator/target cards with portal section `role: "metric"`; recommended height 5.
+- BI charts: one row of 2-3 charts, 1-2 rows; recommended height 7.
+- Data views: one row of 1-2 concrete views, 1-2 rows; recommended height 11.
+
+## Stop Conditions
+
+- If the user only asked for one app, switch to the single-app guide.
+- If required package/app/field/relation readback contradicts the intended model, repair the specific missing slice before building dependent resources.
+- If a public tool cannot express a needed business feature, state the gap and ask before using any fallback or submitting feedback.

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

@@ -6,9 +6,10 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create each app separately
+2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add relation fields between apps
+4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
+5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
 
@@ -37,11 +38,15 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
+If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
 ## Example
 
+When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
+
 Create a new package only after the user confirms package creation:
 
 ```json
@@ -50,7 +55,9 @@ Create a new package only after the user confirms package creation:
   "arguments": {
     "profile": "default",
     "package_name": "研发项目管理",
-    "create_if_missing": true
+    "create_if_missing": true,
+    "icon": "briefcase",
+    "color": "azure"
   }
 }
 ```
@@ -76,6 +83,8 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
+    "icon": "delivery-box-1",
+    "color": "emerald",
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
@@ -83,7 +92,7 @@ Apply schema for a new app:
       {"name": "客户名称", "type": "text", "required": true},
       {"name": "订单封面", "type": "attachment", "as_data_cover": true},
       {"name": "订单金额", "type": "amount"},
-      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+      {"name": "状态", "type": "single_select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
     ],
     "update_fields": [],
     "remove_fields": []
@@ -105,6 +114,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
+        "icon": "business-personalcard",
+        "color": "emerald",
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
         ]
@@ -112,6 +123,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "order",
         "app_name": "订单",
+        "icon": "delivery-box-1",
+        "color": "blue",
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {
@@ -138,7 +151,7 @@ Expected on create. Continue with `create_if_missing=true`.
 
 ### `CREATE_APP_ROUTE_NOT_FOUND`
 
-The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
+The create route did not resolve in the current backend route context. In Wingent Momo runtime, first retry the same `app_schema_apply` after confirming the injected session is still active. Only run `workspace_select` if a business tool explicitly reports a missing or wrong workspace.
 
 ### Hierarchy modeling mistake
 

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

@@ -16,7 +16,7 @@ If the user did not specify an environment, default to `prod`.
 Use test for:
 
 - first application of a new `SolutionSpec`
-- trying `solution_build_all(..., verify=true)`
+- trying builder apply flows end-to-end with readback verification, or `solution_install` when the user is installing an existing packaged solution
 - package initialization and schema evolution experiments
 - mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
 

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

@@ -3,7 +3,7 @@
 ## Auth and workspace
 
 - `auth_*` success does not mean a workspace is selected
-- Re-run `workspace_select` after auth changes or route changes
+- 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.
 
 ## Package ownership
 
@@ -17,13 +17,14 @@
 - 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
 
-## Publish
+## Auto publish
 
-- 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_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`
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
 ## BI Reports
@@ -89,9 +90,16 @@
 ## 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,6 +4,12 @@ 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`
@@ -80,6 +86,15 @@ 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/single-app-development-guide.md

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

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

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

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

@@ -19,28 +19,30 @@ 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.
+
 ## Resolve
 
-- `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
+- `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; use `create_if_missing=true` only after explicit user intent; layout/group/order changes require package edit permission because they call the backend package ordering route
 - `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`
+- `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
 
 ## 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, full spec (nodes + transitions)
+- `app_get_flow`: workflow enabled state, nodes, transitions
 - `app_get_charts`: current chart ids, names, types, order
-- `app_get_buttons`: current custom button list (draft state)
-- `app_get_associated_resources`: current associated resource pool (draft state)
-- `app_publish_verify`: publish state and package tag verification — accepts `app_keys[]` for multi-app batch
+- `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.
 - `portal_get`: current portal config detail and component inventory
 
 ## Apply tools
@@ -48,15 +50,15 @@ All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch).
 These execute normalized patches. Some app apply tools publish by default and still accept `publish=false`; custom button and associated-resource apply publish after at least one write succeeds and do not expose that switch.
 
 - `app_schema_apply`: create app shell or change fields
-- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
-- `app_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
+- `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; new views default associated report/view display to visible with `limit_type="all"`
+- `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. 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 `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; 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; for complete systems, submit large chart sets in batches of 4-8 upserts. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
+- `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
 
-For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart_ref": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
+For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_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
 
@@ -69,15 +71,13 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
 - 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 QingBI charts:
@@ -86,8 +86,6 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
   `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`
-- Update portal section(s) without replacing all:
-  `portal_get -> portal_apply.patch_sections[]`
 
 ## Avoid
 
@@ -105,3 +103,4 @@ 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,18 +6,19 @@ 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. `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:
+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:
    - `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.
-9. `app_flow_apply`
-10. `app_get_flow` when apply returns `partial_success` or the user asked for verification
+10. `app_flow_apply`
+11. `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.
 
@@ -61,34 +62,6 @@ 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`
@@ -124,7 +97,18 @@ Preferred fix order:
 
 ### `FLOW_DEPENDENCY_MISSING`
 
-The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
+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
 
 Preferred recovery:
 
@@ -177,7 +161,7 @@ Do not copy internal keys from old plan outputs or logs, including:
 
 ## Notes
 
-- `mode=replace` is the only supported flow apply mode when using `spec`; `patch_nodes[]` does not require a `mode`
+- `mode=replace` is the only supported flow apply 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,6 +10,8 @@ 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.
+
 Read current fields first:
 
 ```json
@@ -70,3 +72,4 @@ Treat it as uncertain write state. Read back with `app_get_fields` before retryi
 - `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`