@qingflow-tech/qingflow-app-user-mcp 1.0.11 → 1.0.12

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

@@ -0,0 +1,107 @@
+# Builder Gotchas
+
+## 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.
+
+## Package ownership
+
+- Public package work should stay on `package_get / package_apply`
+- Do not treat `package_attach_app` as the public default story anymore; if it still exists in low-level code, treat it as internal/legacy
+- Check package-related readback after schema writes instead of assuming package ownership from the write alone
+
+## Package vs app vs field
+
+- A package/system is not an app
+- 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
+
+## Auto 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`
+- `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` 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
+
+- Prefer summary reads over large raw payloads
+- Use `app_get_fields` before schema or view work
+- Use `app_get_layout` before layout work
+- 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
+- Approval, fill, and copy nodes also require at least one assignee
+- Prefer roles over explicit members unless the user explicitly names people
+- Resolve assignees with `role_search` / `member_search` before flow apply
+- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
+- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
+- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
+- Do not switch to hidden `solution_*` tools from public builder flows
+
+## Retry discipline
+
+- If a write returns `partial_success`, read back before retrying
+- Do not repeat create steps after `app_key` already exists
+- 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 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`
+  - `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.
+- If a view or flow write fails, report the smallest next action:
+  - wrong key -> switch to canonical key
+  - unsupported preset -> switch to allowed canonical preset
+  - backend reject -> re-read summary and retry only the failed patch
+- Do not translate abstract user phrases like “灵活流程” or “默认视图” directly into MCP arguments. First convert them to a preset or explicit patch plan.

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/public-surface-sync.md

@@ -0,0 +1,75 @@
+# Qingflow Core Public Surface Sync
+
+Use this file as the maintenance baseline for the core Qingflow skills.
+It is not a user-facing product spec. It exists to prevent skill drift.
+
+## Current Public Defaults
+
+### User data
+
+- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
+- Standard flows:
+  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
+  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
+  - insert: `record_insert_schema_get -> record_insert(items)`
+  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
+
+### Tasks
+
+- Discovery stays on `task_list`
+- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
+- Public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields`
+- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
+
+### Builder
+
+- Official package entry: `package_get`, `package_apply`
+- Official builder writes:
+  - `app_schema_apply`
+  - `app_layout_apply`
+  - `app_flow_apply`
+  - `app_views_apply`
+  - `app_custom_buttons_apply`
+  - `app_associated_resources_apply`
+  - `app_charts_apply`
+  - `portal_apply`
+  - `app_publish_verify`
+- `portal_apply` edit mode may omit `sections` for base-info-only updates
+- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- `app_get.editability` uses:
+  - `can_edit_app_base`
+  - `can_edit_form`
+  - `can_edit_flow`
+  - `can_edit_views`
+  - `can_edit_charts`
+
+## Known High-Drift Areas
+
+- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
+- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
+- App editability: do not let `can_edit_form` imply app base-info writes
+- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
+- Analysis path: standard path stays `record_access -> Python`
+
+## Release Checklist For Skill Maintenance
+
+After each beta that changes public behavior, re-check:
+
+1. `public_surface.py`
+2. `README.md`
+3. `server_app_builder.py` and `server.py` top-level guidance
+4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
+5. Whether new warnings or verification fields need to be explained in skills
+
+If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

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

@@ -0,0 +1,52 @@
+# Builder Playbooks
+
+Use these when you need a quick reminder of the standard v2 builder sequences.
+
+## Create a new app in an existing package
+
+1. `package_get`
+2. `app_resolve`
+3. `app_schema_apply`
+5. `app_publish_verify` only if the user asks for explicit live verification
+
+## Update fields on an existing app
+
+1. `app_resolve`
+2. `app_get_fields`
+3. `app_schema_apply`
+
+## Rework layout
+
+1. `app_get_layout`
+2. `app_layout_apply`
+
+Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
+
+## Add or update workflow
+
+1. `app_get_fields`
+2. `app_get_flow`
+3. `role_search` or `member_search`
+4. `role_create` if the business wants a reusable role and no good exact role exists
+5. `app_flow_apply`
+
+If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
+If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
+
+## Add or update views
+
+1. `app_get_fields`
+2. `app_get_views`
+3. `app_views_apply`
+
+For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
+
+## Final readback
+
+Prefer these fields after writes:
+
+- `app_get.tag_ids`
+- `app_get.publish_status`
+- `app_get_layout.unplaced_fields`
+- `app_get_views.views`
+- `app_get_flow.nodes`

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

@@ -0,0 +1,99 @@
+# Tool Selection
+
+Use the smallest v2 builder tool chain that can finish the task.
+
+## Default path
+
+`summary read -> apply -> publish_verify`
+
+Public builder `apply` tools already perform server-side planning, normalization, and dependency checks internally. Do not route normal public builder work through explicit `*_plan` tools.
+
+## Hierarchy first
+
+Before picking tools, decide which layer the request targets:
+
+- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package
+- `field`: one field inside one app
+- `relation`: a field that links two apps
+
+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.
+
+## 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; 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`; 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
+
+- `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_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.
+- `portal_get`: current portal config detail and component inventory
+
+## Apply tools
+
+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; 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` 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; 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": {...}}]`. 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
+
+## Decision shortcuts
+
+- 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(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[])`
+- 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`
+- Add views:
+  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
+- Add QingBI charts:
+  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+- 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`
+
+## Avoid
+
+- Do not handcraft raw Qingflow schema payloads
+- Do not rely on internal `solution_*` tools in public builder flows
+- Do not create a new package without first asking the user to confirm package creation
+- Do not regress to `package_create` or `package_attach_app` as the public default story
+- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
+- Do not compress multiple business objects into one app with several text fields
+- Do not skip summary reads before flow or view work
+- Do not emit `column_names`; always use `columns`
+- Do not model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
+- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
+- Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
+- 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

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

@@ -0,0 +1,158 @@
+# Update Flow
+
+Use this when the app already exists and the task is only about workflow.
+
+## Minimal sequence
+
+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:
+   - `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
+
+If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
+
+## Example
+
+Canonical preset mapping:
+
+- “默认审批/基础审批/普通审批” -> `basic_approval`
+- “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+
+Apply a simple approval flow with a role assignee and node-level editable fields:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval",
+    "publish": true,
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "role_names": ["项目经理"]
+        },
+        "permissions": {
+          "editable_fields": ["状态", "审批意见"]
+        }
+      }
+    ]
+  }
+}
+```
+
+For flexible business requirements, do not jump straight to a full custom graph. Use this safer pattern:
+
+1. build a base skeleton from a preset
+2. identify the business-specific changes
+3. patch nodes/transitions explicitly
+
+Public flow building is intentionally limited to linear workflows. Use only:
+
+- `start`
+- `approve`
+- `fill`
+- `copy`
+- `webhook`
+- `end`
+
+Do not generate `branch` or `condition` nodes through `app_flow_apply`. The backend workflow route is not front-end stable for those node types, and MCP now returns `FLOW_NODE_TYPE_UNSUPPORTED` instead of writing a visually broken flow.
+After `app_flow_apply` returns blocking issues or canonical arguments, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+When you patch a preset, patch the preset node itself. Do not leave the preset approval node unassigned while adding a second custom approval node.
+
+## Common failures
+
+### `FLOW_ASSIGNEE_REQUIRED`
+
+Approval, fill, and copy nodes must declare at least one assignee.
+
+If this happens after using a preset, check for this specific mistake first:
+
+- the preset created `approve_1` or `fill_1`
+- your patch created a different node id instead of patching that preset node
+- the original preset node remained in the graph without assignees
+
+Preferred fix order:
+
+1. `role_search`
+2. `member_search` only if the user explicitly named members
+3. `role_create` if the business needs a reusable role
+4. patch the preset node id itself with canonical `assignees.*`
+5. retry `app_flow_apply`
+
+### `FLOW_DEPENDENCY_MISSING`
+
+The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
+
+Preferred recovery:
+
+1. use the returned `suggested_next_call`
+2. apply the minimal schema patch
+3. rerun `app_get_fields`
+4. rerun `app_flow_apply`
+
+### `INVALID_FLOW_EDGE`
+
+One or more transitions reference unknown nodes or create an invalid graph.
+
+### `UNKNOWN_FLOW_FIELD`
+
+The workflow referenced a field name that does not exist, often in:
+
+- `permissions.editable_fields`
+
+Call `app_get_fields` and retry with the exact field names returned by the app.
+
+### `FLOW_NODE_TYPE_UNSUPPORTED`
+
+The public workflow builder only supports linear flows. Remove `branch` and `condition` nodes and redesign the flow with stable sequential nodes instead of retrying the same graph.
+
+### `STATUS_FIELD_REQUIRED`
+
+The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
+
+### `FLOW_STAGE_CONTEXT_MISSING`
+
+Internal flow stage context was missing or invalid. Re-run `app_flow_apply` with the normalized arguments, and do not switch to hidden `solution_*` tools.
+
+### `VALIDATION_ERROR`
+
+Do not keep guessing preset names or node shapes. First:
+
+1. inspect `suggested_next_call`
+2. reuse `canonical_arguments` if present
+3. check `allowed_values`
+4. retry with canonical preset or canonical node types
+5. for workflow actors and permissions, always convert to:
+   - `assignees.role_names`
+   - `assignees.member_names`
+   - `permissions.editable_fields`
+
+Do not copy internal keys from old plan outputs or logs, including:
+
+- `role_entries`
+- `editable_que_ids`
+
+## Notes
+
+- `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
+- Report results precisely:
+  - “基础流程骨架已创建” when only the preset landed
+  - “业务定制规则已补齐” only after the patch phase is complete