@josephyan/qingflow-app-builder-mcp 1.1.17 → 1.1.18

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.17
+npm install @josephyan/qingflow-app-builder-mcp@1.1.18
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.17 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.18 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.17"
+version = "1.1.18"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App Builder
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.28.3`（入口文档版本；CLI 实际执行包以 `qingflow --json version` 返回的 `package / version / package_root / skill_version` 为准）。
 
 ## Overview
 
@@ -47,11 +47,24 @@ For complete systems, `apps[]` should use stable `client_key` values. Same-call
 
 If a complete-system `app_schema_apply` times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, treat it as an uncertain write, not as a failed create. The next action is always `readback_before_retry`: read the package/app/fields first, compare intended `client_key`/`app_name`/relations against reality, and only then repair the missing slice. Do not retry the whole multi-app create, create `V2`/`测试`/random-suffix apps, or split the system into single-app rebuilds to bypass a duplicate/conflict.
 
+Before any write, apply this decision gate:
+
+| Evidence | Action |
+| --- | --- |
+| Exact `app_key`, `view_key`, `chart_id`, `dash_key`, or `package_id` is provided | Update that existing target unless the user explicitly asks for a new one |
+| Several forms/modules or a “system/package” are requested | Use the complete-system path; do not compress them into one app |
+| Same/similar package or app already exists and user did not say extend/replace/new | Stop and ask which target strategy to use |
+| Readback already contains part of the requested build | Patch only verified missing or incorrect slices |
+| Write state is uncertain | Read back before retrying; do not create duplicate names with suffixes |
+
 Builder schema inputs should follow agent-intuitive semantics:
 
+- choose field type by business intent first: title/short text -> `text`; notes/description -> `multiline`; status/type/stage -> `select` with `options`; labels/multiple choices -> `multi_select`; quantities/ratios/scores/durations -> `number`; money -> `amount`; cross-app link -> `relation`
+- field types in drafts may use intuitive aliases: `multiline -> long_text`, `select -> single_select`, `multi_select -> multi_select`, `amount -> amount`, `phone -> phone`; readback returns canonical types and that is not a schema mismatch
 - primary icon syntax is `icon + color`, for example `icon: "table", color: "blue"`; `icon_name/icon_color`, `icon_config`, and `icon: {name, color}` are compatibility aliases only
-- `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
-- relation fields need a target plus `display_field` and `visible_fields`
+- select-style field `options` may be strings or objects such as `{label, value}`; tools normalize to option labels
+- relation fields need a target plus object selectors: same-batch `target_app_ref`, existing app `target_app_key`, `display_field: {"name": "..."}`, and `visible_fields: [{"name": "..."}]`
+- do not impose an artificial one-relation-field-per-app limit; create the relation fields the business model needs, then rely on backend validation and readback
 - do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
 
 ## Public Tools You Should Think In
@@ -87,10 +100,23 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `portal_apply` is the public write path
   - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
   - supplying `sections` means full replace semantics for sections
+  - `patch_sections[]` is the preferred path for changing one existing portal block
+  - do not confuse form layout with portal layout: form layout uses field-name `rows`; portal layout uses component `position.pc.x/y/cols/rows`
+  - portal PC layout uses a 24-column grid; components with the same `y` must share the same `rows`, and their `cols` should sum to 24 unless the user explicitly wants blank space
+  - standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`
+  - business-entry grid sections must include real `config.items[]`; do not submit an empty grid container
+  - build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known by readback
+  - standard order is business entry -> metric cards -> BI charts -> concrete data views
+  - do not use platform default views such as `全部数据` / `我的数据` as the main portal views
+  - do not use `source_type: "filter"` as the normal automation path; portal filter is raw/unstable and not part of the unified filter DSL
 - Chart work:
   - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
   - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
   - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
+  - use `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters; normal record/form fields are not enough
+  - choose chart type by goal: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, `dualaxes` for two-metric comparison
+  - use semantic metrics: `count(*)`, `sum(金额)`, `avg(工时)`, `group_by`, `where`; do not handwrite raw `indicator_field_ids`, `selectedMetrics`, or QingBI filter matrices on the main path
+  - do not use `summary` for a single metric card; use `target` / `indicator`
   - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
   - chart `filters` use the unified fixed-filter DSL: `field_name + operator + value/values`; the tool compiles them to QingBI string judge types
   - for complete systems, submit `upsert_charts` in batches of 4-8. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
@@ -98,13 +124,22 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `visibility` is a public capability and should be treated as a base-only permission update
   - do not model chart visibility changes as raw config rewrites
 - Button work:
-  - `app_custom_buttons_apply` is the public write path for custom button bodies and view placement
+  - for normal view-specific business buttons, prefer `app_views_apply.upsert_views[].action_buttons` or `patch_views[].set.action_buttons`; design the view and its actions together
+  - use `app_custom_buttons_apply` for advanced button maintenance: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering view bindings, or exact qRobot/wings configs
   - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
+  - choose by user intent first: current record -> downstream record uses `add_data`; global independent entry uses `header`; URL/SOP/help uses `link`; approval/status transition/close task is workflow/task/automation, not a fake normal button
+  - action choice:
+    - current record -> downstream/child record: use `add_data` in view `action_buttons`, or `addData` in standalone buttons, with `target_app_key + field_mappings`
+    - global independent create: use `add_data`/`addData` on `header` without current-record `source_field`
+    - SOP/external/fixed page: use `link` with `url`
+    - existing automation only: use `qRobot`/`wings` only when the user provides exact config
+    - approval/status transition/close task is not a generic button action; model workflow/task action first, or use existing automation. Do not fake it with `link`
   - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
   - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`)
   - to prefill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`; use `default_values` only for static constants
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
-  - bind buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
+  - placement choice: `header` is global and has no current-row context; `list` is row/list action and maps to backend `INSIDE`; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`
+  - bind advanced standalone buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
   - builder `view_configs[].view_key` uses the raw key from `app_get.views[].view_key`, without a `custom:` prefix
   - `buttons` is required in merge mode; do not send a view config with only `view_key`
   - `view_configs[].mode` defaults to `merge`; use `mode: "replace"` or an explicit empty `buttons: []` to clear a view's custom button bindings
@@ -128,6 +163,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - do not create platform default/system views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`; they are built in. New views must use business-specific names. To change a built-in view, patch by its existing raw `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
   - keep view `filters` and `query_conditions` separate: `filters` use `field_name + operator + value/values` and are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
+  - choose condition/matching surface by intent: fixed saved filters -> `filters`; frontend query panel -> `query_conditions.rows`; current-record associated report/view filtering -> `match_mappings`; current-record add-data prefill -> `field_mappings`; button visibility -> `visible_when` / `button_limit`
   - keep relation/attachment/subtable/address/Q-Linker/code-block fields out of `query_conditions`; member/department fields may be used as query-panel fields when readback supports them. Use `filters` for fixed filters or associated-resource `match_mappings` for current-record related report/view matching
   - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
   - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
@@ -149,14 +185,14 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - fields -> `app_get_fields`
    - layout -> `app_get_layout`
    - views -> `app_get_views` only when the app_get compact list is not enough
-   - flow -> `app_get_flow`
+   - flow -> `app_get_flow` only when the task involves approval, fill/copy, reminders, process routing, task handling, or flow repair
    - charts -> `app_get_charts` only when the app_get compact list is not enough
    - portal -> `portal_get`
 6. If the public shape is unclear, call `builder_tool_contract`
 7. Apply the smallest patch tool that fits:
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
-   - flow -> `app_flow_apply`
+   - flow -> `app_flow_apply` only when workflow is requested or clearly required
    - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
    - existing buttons -> `app_custom_buttons_apply.patch_buttons`; new/full buttons -> `app_custom_buttons_apply.upsert_buttons`
    - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
@@ -179,6 +215,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - When creating or updating fields, configure the app data title/cover directly in field JSON: `as_data_title: true` is required on exactly one readable top-level title field; `as_data_cover: true` is optional and only valid on one top-level `attachment` field.
 - Do not add platform system fields to `add_fields`; if the user asks for record id, number, applicant, creation/update time, or workflow status, use the built-in data/list/readback fields instead of creating duplicate controls.
 - If the same validation error repeats twice, stop guessing and re-read `builder_tool_contract`.
+- Do not create workflows just to make a build look complete. If no approval/fill/copy/reminder/process-routing requirement exists, report workflow as not requested/not configured.
 - For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
 - Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.
 - Respect collaborative edit locks. Only use `app_release_edit_lock_if_mine` when the lock owner is the current authenticated user.
@@ -192,9 +229,17 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
 - `success` means write and verification completed; `partial_success` means the write landed or may have landed but verification is incomplete. If `write_executed=true`, `safe_to_retry=false`, or readback is unavailable, do `readback_before_retry` before any create retry.
+- Final status rule:
+  - write result answers whether the write was attempted
+  - readback answers what actually exists
+  - publish/portal verification answers whether it is front-end visible
+  - validation/contract error with `write_executed=false` is a real failure and can be fixed/retried
+  - `partial_success`, timeout, post-write 40002/404, or readback unavailable is not enough to call the write failed; read back first and patch only proven gaps
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
+  - patching one section with `patch_sections[]`
+  - layout validity: same-row `rows`, same-row `cols` sum, and non-empty grid `items`
 - For object apply tools, distinguish clearly between:
   - `patch_*`: public partial parameter replacement; the tool hydrates current config and full-saves internally
   - `upsert_*`: create or full target configuration; omitted fields may mean default/clear depending on that object
@@ -220,17 +265,17 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Add/update/remove fields: `app_schema_apply`
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
-- Upsert/patch/remove views: `app_views_apply`
-- Upsert/patch/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
+- Upsert/patch/remove views, including ordinary view-specific `action_buttons`: `app_views_apply`
+- Advanced custom button maintenance and cross-view binding: `app_custom_buttons_apply`
 - Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
 - Upsert/patch/remove/reorder charts: `app_charts_apply`
 - Create or update portal pages: `portal_apply`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Final publish verification: `app_publish_verify`
 
-## Button Pattern
+## Advanced Button Pattern
 
-Use `app_custom_buttons_apply` for the whole custom-button path: button body, add-data mapping, default values, and placement.
+For ordinary view-specific buttons, prefer `app_views_apply` with `action_buttons`; see [references/update-views.md](references/update-views.md). Use `app_custom_buttons_apply` only when you need standalone/advanced maintenance: custom style or icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config.
 
 ```json
 {

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

@@ -19,6 +19,7 @@ Required:
 Strongly recommended:
 
 - cross-app relation fields for the main business links
+- 1-3 concrete business buttons on core operating views through `app_views_apply.action_buttons`
 - 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
@@ -39,18 +40,23 @@ Optional:
 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.
+5. For each app, apply layout.
+6. Apply workflow with `app_flow_apply` when the user asks for approval, fill, copy, reminders, or process routing.
+7. Apply views; declare ordinary business buttons in `action_buttons` while designing the core operating views.
+8. 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.
+9. Add associated resources and advanced standalone buttons when they are part of the requested business process.
+10. Create portal only after referenced apps, views, and charts are known.
+11. 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`.
+- Readback may show canonical field types such as `long_text` or `single_select`; do not rewrite fields just because aliases were normalized.
 - 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.
+- Relation fields must include `target_app_ref` for same-batch apps or `target_app_key` for existing apps, plus `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]`; do not write bare strings for display/visible field selectors.
+- Do not impose a one-relation-field-per-app limit. Model the real business links and let backend validation/readback decide whether a specific relation is unsupported.
 
 ## View Query Rules
 
@@ -60,6 +66,29 @@ Optional:
 - 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`.
 
+## 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`.
+- Two-metric comparison uses `dualaxes` with `left_metric` and `right_metric`.
+- 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.
+- For complete systems, submit new charts in batches of 4-8.
+
+## Button Rules
+
+- Design ordinary business buttons with the view: `app_views_apply.upsert_views[].action_buttons` or `patch_views[].set.action_buttons`.
+- Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
+- Use `add_data` when a current record creates a downstream/child record, such as order -> acceptance, work order -> inspection, or customer -> follow-up. Configure `target_app_key + field_mappings`; map `source_field: "数据ID"` to the target relation/reference field when linking back to the source record.
+- Use `link` only for SOP, help, external system, or fixed URL navigation. Do not use `link` to fake approval, status transition, or data writeback.
+- Use `qRobot`/`wings` only when the user provides exact existing automation config. Do not invent ids, parameters, or hidden automation.
+- 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 modeled as workflow/task behavior or existing automation; they are not generic custom-button types.
+- Do not claim a complete operational system if all core operating views have no buttons and no reason is given.
+
 ## Delivery Summary File
 
 For complete-system builds, create or update one local JSON file before the final response:
@@ -98,9 +127,21 @@ Rules:
 - 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.
+- `front_end_visible=true` only when the relevant portal/app publish or live readback proves it. Backend write success alone is not enough.
+- Do not mark workflow as missing when the user did not ask for approval, fill, copy, reminders, or process routing. Report it as "not requested/not configured".
+- If `partial_items` or `needs_followup` is non-empty, the final status is partial, not complete.
 - 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`.
 
+Final response shape:
+
+```text
+已完成：...
+未验证/待确认：...
+前端可见：是/否/未确认
+需要继续修复：是/否；原因...
+```
+
 ## Recovery Rules
 
 - Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means `write_may_have_succeeded`.
@@ -115,9 +156,17 @@ Rules:
 - 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.
+- PC layout uses 24 columns. Components in the same row share the same `y`, must have the same `rows`, and their `cols` should sum to 24.
+- Business-entry grid components must include real `config.items[]` entries linking to apps or portals; never submit an empty grid container.
+- Build the portal only after referenced apps, raw `view_key`s, and chart ids/keys have been read back.
+- Standard section order is business entry -> metric cards -> BI charts -> concrete business views.
+- Do not reference platform default views such as `全部数据` / `我的数据` as main portal data views.
+- Do not use portal `source_type: "filter"` as the normal automation path; it is raw/unstable and not part of the unified filter DSL.
 
 ## Stop Conditions
 
 - If the user only asked for one app, switch to the single-app guide.
+- If a same/similar package or app set already exists and the user did not say whether to extend, repair, replace, or create new, stop and ask. Do not start probing with new names.
+- If readback shows part of the requested system already exists, list existing apps/fields/views/charts/portal, identify gaps, and patch only the missing or incorrect slices.
 - 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

@@ -47,6 +47,15 @@ If that multi-app call times out, returns `partial_success`, returns `write_exec
 
 When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
 
+Field authoring rules:
+
+- Use intuitive field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
+- The tool normalizes aliases before writing: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`, `currency -> amount`, `mobile -> phone`. Readback may show canonical types; that is not a failed write.
+- Every new app must have exactly one top-level `as_data_title: true` field. `as_data_cover: true` is optional and only valid on a top-level `attachment`.
+- Select fields must define `options` during schema design. Options may be strings or objects such as `{"label": "进行中"}`; sample data must use those labels or ids.
+- Relation fields must use `target_app_ref` for same-batch apps or `target_app_key` for existing apps, plus object selectors: `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]`. Do not write bare strings for display/visible field selectors.
+- Do not impose a one-relation-field-per-app limit. Model the real business links and let backend validation/readback decide.
+
 Create a new package only after the user confirms package creation:
 
 ```json
@@ -92,7 +101,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": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
+      {"name": "状态", "type": "select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
     ],
     "update_fields": [],
     "remove_fields": []

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

@@ -33,18 +33,25 @@
 - Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
 - `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
 - Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
+- Main chart config should use semantic `metric`, `metrics`, `group_by`, and `where`; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices unless diagnosing or preserving existing raw config.
 - `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
+- Use `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Record schema fields or normal form fields are not enough for chart apply.
+- Use `target` / `indicator` for one metric card; do not use `summary` for a single KPI.
 
 ## Custom buttons
 
-- 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.
+- For ordinary view-specific business buttons, use `app_views_apply` with `action_buttons`; do not use legacy `app_views_apply.buttons` unless you are maintaining an old full-replacement patch.
+- Use `app_custom_buttons_apply` for advanced button creation/update/removal and view placement: custom style/icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
 - When changing one existing button parameter, use `patch_buttons` with `set/unset`. Do not send a partial `upsert_buttons` object and expect the backend to preserve hidden required fields.
+- `addData` / `add_data` creates a related/downstream Qingflow record; use current-record `field_mappings` only on `detail` or `list`. `link` only opens a URL. `qRobot`/`wings` require user-provided exact config and must not be invented.
 - For add-data buttons, prefer semantic `trigger_add_data_config.target_app_key`, `field_mappings`, and `default_values`.
 - Do not handwrite raw `que_relation` unless you are preserving an existing backend config. If `field_mappings` and `que_relation` are mixed, the tool blocks the write.
 - `field_mappings.source_field` can use source app fields and supported system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`).
 - To fill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`. Use `default_values` only for static constants.
+- Do not put current-record `field_mappings` on a `header` button; `header` has no current row. Use `detail` or `list` for current-record add-data actions.
+- Do not model approval, rejection, close-task, or status transition as a generic `link` button. Use workflow/task behavior, or `qRobot`/`wings` only when the user provides existing automation config.
 - For field type compatibility, read `references/match-rules.md`.
-- Default button placements are `header` and `detail`; these map to the frontend's header and detail button areas.
+- Use `header` for global actions with no current-row context, `detail` for safest current-record actions, and `list` for row/list actions.
 - `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.
@@ -73,7 +80,14 @@
 - 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.
+- `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list; use `patch_sections[]` for one-section updates.
+- PC portal layout is 24-column. Group components by the same `y`: all components in that row must have the same `rows`, and their `cols` should sum to 24 unless the user explicitly wants blank space.
+- Standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`.
+- Business-entry `grid` sections must include real `config.items[]`; an empty grid container is not a valid business entrance.
+- Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known by readback. Intended names are not enough.
+- Use standard order: business entry -> metric cards -> BI charts -> concrete data views.
+- Do not use platform default views such as `全部数据` / `我的数据` as the main portal views.
+- Do not use portal `source_type: "filter"` as the normal automation path; it is raw/unstable and not part of the unified filter DSL.
 - `app_flow_apply` is intentionally replace-only for the public linear workflow graph.
 
 ## Workflow dependencies

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

@@ -17,8 +17,9 @@ Required:
 Strongly recommended:
 
 - saved filters and query panel fields for the main operating views
+- 1-3 concrete business buttons on core operating views through `app_views_apply.action_buttons`, when the view has real actions
 - 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
+- associated resources or advanced standalone buttons only when they support a concrete workflow
 
 Optional:
 
@@ -35,13 +36,18 @@ Workflow preflight:
 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.
+5. Apply workflow with `app_flow_apply` when the user asks for approval, fill, copy, reminders, or process routing.
+6. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request; declare ordinary business buttons in `action_buttons` while designing the view.
+7. Apply charts/associated resources/advanced standalone buttons only if they are part of the app's actual workflow.
+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.
 
@@ -51,8 +57,31 @@ Workflow preflight:
 - 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.
+
+## Button Rules
+
+- Use `action_buttons` for ordinary buttons tied to one view.
+- Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
+- 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.
+- Use `qRobot`/`wings` only when the user provides exact existing automation config.
+- 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/tool-selection.md

@@ -25,6 +25,16 @@ Use this split consistently:
 - Single app: `app_resolve/app_get` first, then app-scoped apply tools.
 - Record/task/data operation: leave builder and use record/task skills.
 
+Decision gate before writing:
+
+| Evidence | Action |
+| --- | --- |
+| User gives an `app_key`, `view_key`, `chart_id`, `dash_key`, or exact `package_id` | Treat the task as an update to that existing target unless the user explicitly asks for a new one |
+| User names several forms/modules or asks for a system/package | Use the complete-system path; do not compress them into one app |
+| Same or very similar package/app already exists and the user did not say extend/replace/new | Stop and ask whether to extend existing, repair missing parts, or create a new target |
+| Existing readback already contains part of the requested system | List verified existing resources, identify gaps, and patch only missing or incorrect slices |
+| A write is uncertain: timeout, `partial_success`, `write_executed=true`, or `safe_to_retry=false` | Read back before retrying; do not create `V2`, `测试`, timestamp, or random-suffix resources |
+
 ## Resolve
 
 - `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
@@ -52,11 +62,11 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_schema_apply`: create app shell or change fields
 - `app_layout_apply`: merge or replace layout
 - `app_flow_apply`: replace workflow
-- `app_views_apply`: 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_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; for normal view-specific business buttons, declare `action_buttons` in the view object or `patch_views[].set`; new views default associated report/view display to visible with `limit_type="all"`
+- `app_custom_buttons_apply`: advanced custom-button maintenance only: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering bindings, or exact qRobot/wings configs. Use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
 - `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` with `target_field + operator + source_field/value` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
-- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `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
+- `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, 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. 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_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.
 
@@ -80,12 +90,18 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
   `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 ordinary view buttons:
+  `app_get_views -> app_views_apply.patch_views/upsert_views with action_buttons -> app_get_views`
+- Maintain advanced custom buttons:
+  `app_get -> app_custom_buttons_apply.patch_buttons/upsert_buttons + view_configs -> app_get_views`
 - Add QingBI charts:
   `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
 - Show an existing QingBI chart inside a Qingflow app/view:
   `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
 - Create or update a portal:
   `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
+- Patch one portal section:
+  `portal_get -> portal_apply.patch_sections[] -> portal_get`
 
 ## Avoid
 

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

@@ -12,6 +12,16 @@ Use this when the app already exists and the task is only about fields.
 
 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
@@ -66,6 +76,7 @@ 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`

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

@@ -38,6 +38,13 @@ Canonical rules before any example:
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.
 - For an existing view, prefer `patch_views` for parameter replacement. Do not send a partial `upsert_views` object such as only `name/type/query_conditions`; backend view saves require other type-specific fields, and the patch path preserves them for you.
+- For ordinary view-specific business buttons, declare `action_buttons` inside `upsert_views[]` or `patch_views[].set`. Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
+- Choose the button by user intent before choosing a trigger type:
+  - current record -> downstream/related record: `add_data` with `target_app_key + field_mappings`
+  - global independent entry: `add_data` on `header` without current-record `source_field`
+  - URL/SOP/help page: `link` with `url`
+  - approval/status transition/close task: do not fake it with a normal button; use workflow/task action or exact existing automation config
+- Button placement choice: `header` is global and has no current-row context; `list` is row/list action; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`.
 
 Apply a business table view:
 
@@ -62,6 +69,48 @@ Apply a business table view:
 ```
 After `app_views_apply` returns canonical arguments or blocking issues, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
 
+Create a table view with ordinary business buttons:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "工单执行视图",
+        "type": "table",
+        "columns": ["工单编号", "产品", "状态", "负责人"],
+        "action_buttons": [
+          {
+            "text": "创建质检单",
+            "action": "add_data",
+            "target_app_key": "QUALITY_APP",
+            "field_mappings": [
+              {"source_field": "数据ID", "target_field": "关联工单"}
+            ],
+            "default_values": {"处理状态": "待处理"},
+            "placement": "detail",
+            "visible_when": [
+              {"field_name": "状态", "operator": "eq", "value": "已完工"}
+            ]
+          },
+          {
+            "text": "查看作业说明",
+            "action": "link",
+            "url": "https://example.com/sop",
+            "placement": "header"
+          }
+        ]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
 Existing table view: replace only frontend query conditions:
 
 ```json