@josephyan/qingflow-app-builder-mcp 1.1.30 → 1.1.33

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

@@ -0,0 +1,84 @@
+# 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
+- core operating views declare needed business actions directly in `app_views_apply.views[].action_buttons`, when the view has real actions
+- simple charts when the app has status, amount, date, or owner fields worth tracking
+
+Optional:
+
+- workflow, 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. For a new app, apply fields and form layout together with `app_schema_apply` using `form`; for an existing app, use `app_schema_apply` only for field changes.
+4. Use `app_layout_apply` only when repairing or changing layout on an existing app. Do not call it after new-app creation just to place fields.
+5. Apply workflow with the new complete chain when the user asks for approval, fill, copy, reminders, or process routing: read flow schema/current flow, build a WorkflowSpec for full flow writes or `patch_nodes` for targeted edits, call `app_flow_apply`, then read back flow. Do not use legacy `nodes/transitions` except for deliberately simple linear compatibility.
+6. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request; declare needed view actions in `action_buttons` while designing the view.
+7. Apply charts only if they are part of the app's actual reporting need.
+8. 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`.
+- The tool normalizes aliases: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`. Readback may show canonical types; do not treat that as a failed write.
+- Select fields must define `options` during schema design. Options may be strings or objects such as `{"label": "进行中"}`; later sample data should use those option labels or ids.
+- Relation fields are for real cross-object links. If used, include `target_app_key` for an existing app or `target_app_ref` for a same-batch app, plus `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]`.
+- Do not impose a one-relation-field limit. Add the relation fields the business needs, then rely on backend validation and readback.
+- 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.
+
+## Chart Rules
+
+- Read `app_get_fields.chart_fields` before chart apply; normal form fields are not enough for QingBI dimensions, metrics, or filters.
+- Use semantic chart input first: `metric`, `metrics`, `group_by`, and `where`.
+- One KPI card uses `target` / `indicator` with `metric: "count(*)"` or `metric: "sum(金额)"`.
+- Grouped distribution uses `bar` / `columnar` / `pie` with `group_by + metric`.
+- Trend uses `line` / `area` / `columnar` with a date/month `group_by`.
+- Do not use `summary` for a single KPI; `summary` is for table-style grouped summaries.
+- Do not handwrite raw `indicator_field_ids`, `selectedMetrics`, or QingBI filter matrices on the main path.
+
+## View Action Rules
+
+- Use `action_buttons` inside `app_views_apply.views[]` for buttons tied to one view.
+- Use `add_data` when a current record creates a downstream/child record; configure `target_app_key + field_mappings`, usually mapping `source_field: "数据ID"` to the target relation/reference field.
+- Use `link` only for SOP, help, external system, or fixed URL navigation. Do not use it to fake approval, status transition, or data writeback.
+- Prefer `detail` for current-record add-data actions, `list` for row actions, and `header` for global actions with no current-row context. Do not use current-record `field_mappings` on `header`.
+- Approval, rejection, close-task, and status transition should be workflow/task behavior or existing automation; they are not generic custom-button types.
+
+## Stop Conditions
+
+- If the task actually needs multiple business objects, stop and switch to the complete-system guide.
+- If an existing app with the same or very similar name appears and the user did not explicitly say update, extend, or create new, stop and ask which target to use.
+- If readback shows the requested app already has some resources, patch the verified gaps instead of recreating the app.
+- 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.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names in a real business package.

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,27 +19,40 @@ 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`
-- `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; `package_name` without `package_id` creates a package; 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_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
@@ -47,14 +60,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`: layout-only maintenance for existing apps; new app layout belongs in `app_schema_apply` `form.sections`
-- `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 top-level `views[]` for same-app/cross-app batch create, patch, and remove; view business actions belong in each view item's `action_buttons`
-- `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/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 top-level `views[]`; `operation="upsert"` creates or fully targets a view, `operation="patch"` changes existing view parameters, and `operation="remove"` removes by key; declare view-specific business buttons in the same `views[]` item with `action_buttons`; 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.
 
-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_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart": {"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, use the object's real selector field plus `set` and optional `unset`; `selector` is only a concept, not a literal key. Examples: `views: [{"operation": "patch", "app_key": "APP_KEY", "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
 
@@ -65,27 +79,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(create_if_missing=true) -> app_schema_apply`
+  `package_apply(package_name, icon, color) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[] with form.sections)`
+  `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
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
-  `app_get_fields -> app_get_layout -> app_layout_apply`
+  `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:
-  `app_get_fields -> app_get_views -> app_views_apply.views[] -> app_get_views`
-- Add QingBI charts for a portal:
-  `portal_apply.sections[].chart`
+  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply(views[]) -> 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`
-- Update portal section(s) without replacing all:
-  `portal_get -> portal_apply.patch_sections[]`
+- Patch one portal section:
+  `portal_get -> portal_apply.patch_sections[] -> portal_get`
 
 ## Avoid
 
@@ -103,3 +117,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.
 
@@ -55,50 +56,13 @@ Apply a simple approval flow with a role assignee and node-level editable fields
 }
 ```
 
-For flexible business requirements, do not jump straight to a full custom graph. Use this safer pattern:
+For flexible business requirements, do not freehand hidden backend fields. Use this safer pattern:
 
-1. build a base skeleton from a preset
-2. identify the business-specific changes
-3. patch nodes/transitions explicitly
+1. read `app_flow_get_schema`
+2. read the current flow with `app_get_flow` / `app_flow_get`
+3. use `patch_nodes` for targeted edits, or submit a complete `spec` when replacing the workflow
 
-## 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`
-- `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.
+Legacy `nodes/transitions` input is still limited to simple linear public aliases: `start`, `approve`, `fill`, `copy`, `webhook`, and `end`. Requirements that need branching or richer routing should use the WorkflowSpec `spec` path after reading the schema.
 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.
 
@@ -124,7 +88,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 +152,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,18 @@ 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
@@ -64,9 +76,11 @@ 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,45 +28,89 @@ 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 canonical keys `field_name`, `operator`, `value`/`values`
+- Use `filters` with the unified fixed-filter DSL: `field_name`, `operator`, `value`/`values`; do not write raw `judgeType` / `judgeValues`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
-- 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.
+- 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 `views[]` with `operation: "patch"`.
 - 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. `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.
+- 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.
 - 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
+- If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `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 an existing view, prefer `views[].operation="patch"` for parameter replacement. Do not send a partial `upsert` 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 view-specific business buttons, declare `action_buttons` inside the same `views[]` item. For existing views, use `operation: "patch"` with `set.action_buttons`.
+- 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 default table view:
+Apply a business table view:
 
 ```json
 {
   "tool_name": "app_views_apply",
   "arguments": {
     "profile": "default",
-    "app_key": "APP_123",
     "publish": true,
-    "upsert_views": [
+    "views": [
       {
-        "name": "全部订单",
+        "operation": "upsert",
+        "app_key": "APP_123",
+        "name": "订单台账视图",
         "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态", "负责人", "创建时间"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["订单编号", "客户名称"], ["状态", "负责人"], ["创建时间"]]
-        }
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
       }
-    ],
-    "remove_views": []
+    ]
   }
 }
 ```
 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",
+    "publish": true,
+    "views": [
+      {
+        "operation": "upsert",
+        "app_key": "APP_123",
+        "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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 Existing table view: replace only frontend query conditions:
 
 ```json
@@ -74,10 +118,11 @@ Existing table view: replace only frontend query conditions:
   "tool_name": "app_views_apply",
   "arguments": {
     "profile": "default",
-    "app_key": "APP_123",
     "publish": true,
-    "patch_views": [
+    "views": [
       {
+        "operation": "patch",
+        "app_key": "APP_123",
         "view_key": "VIEW_KEY",
         "set": {
           "query_conditions": {
@@ -88,8 +133,7 @@ Existing table view: replace only frontend query conditions:
           }
         }
       }
-    ],
-    "remove_views": []
+    ]
   }
 }
 ```
@@ -168,16 +212,16 @@ Board example:
   "tool_name": "app_views_apply",
   "arguments": {
     "profile": "default",
-    "app_key": "APP_123",
-    "upsert_views": [
+    "views": [
       {
+        "operation": "upsert",
+        "app_key": "APP_123",
         "name": "按状态看板",
         "type": "board",
         "group_by": "状态",
         "columns": ["订单编号", "客户名称", "订单金额"]
       }
-    ],
-    "remove_views": []
+    ]
   }
 }
 ```
@@ -189,9 +233,10 @@ Gantt example with filters:
   "tool_name": "app_views_apply",
   "arguments": {
     "profile": "default",
-    "app_key": "APP_123",
-    "upsert_views": [
+    "views": [
       {
+        "operation": "upsert",
+        "app_key": "APP_123",
         "name": "项目甘特图",
         "type": "gantt",
         "columns": ["项目名称", "开始日期", "结束日期", "状态"],
@@ -206,8 +251,7 @@ Gantt example with filters:
           }
         ]
       }
-    ],
-    "remove_views": []
+    ]
   }
 }
 ```
@@ -277,7 +321,32 @@ 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, such as attachment, relation, Q-Linker, code block, location/address, or subtable/subfield selections.
+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.
 
 ## Notes
 
@@ -286,6 +355,6 @@ The field exists but cannot be used in the frontend query-condition panel, such
 - `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
+- `query_conditions.rows` does not mean OR; it controls frontend query-field layout and should only contain query-panel supported fields
 - `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