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

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

@@ -1,22 +1,23 @@
 ---
 name: qingflow-app-builder
-description: Build, configure, and modify Qingflow apps and systems after the MCP is already connected and authenticated. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
+description: Build, configure, and modify Qingflow apps and systems using the current Wingent Momo runtime MCP session. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
 metadata:
   short-description: Build and modify Qingflow apps and systems
 ---
 
 # Qingflow App Builder
 
-> **Skill 版本**：`qingflow-skills-2026.06.30.1`
+> **Skill 版本**：`qingflow-skills-2026.06.30.10`（入口文档版本；CLI 实际执行包以 `qingflow --json version` 返回的 `package / version / package_root / skill_version` 为准）。
 
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
-Assumes MCP is already connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust the injected MCP session, credentials, workspace, and route context until a tool explicitly reports otherwise.
 
 Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
 
 Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
+Then pick the matching development guide: [single-app-development-guide.md](references/single-app-development-guide.md) for one app, or [complete-system-development-guide.md](references/complete-system-development-guide.md) for app packages/systems.
 
 ## Current Public Mental Model
 
@@ -34,13 +35,45 @@ Default modeling rules:
 - Another business object -> a separate app, not a text field
 - Cross-object links -> relation fields, not text fields
 
+## Route First
+
+Before any builder write, classify the request:
+
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. This is the main path for complete systems, not a bulk shortcut to abandon after the first slow response. Do not squeeze several business objects into one app.
+- **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
+- **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
+
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields should use `target_app_ref` for another `apps[].client_key`; use `target_app_key` only when the target app already exists or has been confirmed by readback. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+
+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
+- 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
 
 - Package: `package_get`, `package_apply`
-- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `app_get_associated_resources`
+- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`
 - Builder reads: `portal_list`, `portal_get`, `view_get`, `chart_get`, `builder_tool_contract`
 - Directory: `member_search`, `role_search`, `role_create`
-- Writes: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_associated_resources_apply`, `app_charts_apply`, `portal_apply`, `app_release_edit_lock_if_mine`
+- Writes: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_custom_buttons_apply`, `app_associated_resources_apply`, `app_charts_apply`, `portal_apply`, `app_release_edit_lock_if_mine`
 - Verification: `app_publish_verify`
 - Cross-cutting escalation: `feedback_submit` after explicit user confirmation when the public builder surface still cannot satisfy the user's need
 
@@ -52,100 +85,126 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_get(package_id=...)` to read one known package
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
-  - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
-  - put form layout directly in `apps[].form.sections`; the CLI writes it in the same schema save as fields and relations
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
+  - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
+  - same-call relation fields should use `target_app_ref` to point at another `apps[].client_key`; use `target_app` only when the app name is unique and stable, and use `target_app_key` only after the target app already exists or readback has confirmed it
+  - timeout / `partial_success` / `write_executed=true` / `safe_to_retry=false` means `readback_before_retry`; do not directly downgrade to single-app creation
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
 - Partial update rule:
-  - for existing views, associated resources, and charts, prefer `patch_views` / `patch_resources` / `patch_charts`
-  - each patch item uses the object's real selector field (`view_key` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
+  - for existing views, prefer `app_views_apply.views[]` with `operation="patch"`; for custom buttons, associated resources, and charts, prefer `patch_buttons` / `patch_resources` / `patch_charts`
+  - each patch item uses the object's real selector field (`view_key` / `button_id` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
   - use `upsert_*` for creation or full target configuration; do not send a partial `upsert_*` and expect the backend to merge missing required fields
 - Portal work:
   - `portal_apply` is the public write path
-  - complete-system portals create QingBI charts inline through `sections[].chart`; do not pre-create charts as the standard route
   - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
   - supplying `sections` means full replace semantics for sections
-  - portal sections use a 24-column PC grid; all components sharing the same `y` coordinate must have identical `rows` values and their `cols` must sum to exactly 24; mixing `rows` in the same row causes height misalignment, and a `cols` sum under 24 leaves blank space at the row end; the next row's `y` must equal the previous row's `y` + `rows`
-- Standalone chart maintenance:
+  - `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`
-  - do not use it as the standard complete-system route; complete-system portals should inline QingBI charts through `portal_apply sections[].chart`
   - 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, keep chart payloads business-scoped, commonly 4-8 `upsert_charts` by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
   - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
   - `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
 - View action work:
-  - declare button configuration only inside `app_views_apply` view items with `action_buttons`
-  - design the view and its available actions together
-  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` and `编号`
+  - for view-specific business buttons, use `app_views_apply.views[].action_buttons`; for existing views use `operation="patch"` with `set.action_buttons`
+  - 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 button
+  - 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
+  - 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`
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
+  - `app_custom_buttons_apply` is not a main build path; use it only after an explicit maintenance request for existing standalone buttons, cross-view binding, deletion, or exact advanced automation config
 - Associated resources:
   - `app_associated_resources_apply` is the public write path for the Qingflow app-level associated report/view pool and per-view display config
-  - for multi-app systems, use `apps[]` to batch associated-resource writes; each item carries its own `app_key` plus `upsert_resources` / `patch_resources` / `view_configs`
   - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
   - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
   - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
   - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
   - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
   - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
-  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
+  - use `match_mappings` for associated view/report filters; dynamic context matches use `source_field`, static filters use `value`; do not handwrite raw `matchRules`
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:
   - stay on `app_views_apply` / `app_flow_apply`
-  - new views use top-level `views[]`; the same batch may mix same-app and cross-app views
-  - buttons belong in view `action_buttons`
-  - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
+  - before building approval/fill/copy flows, make sure the app schema has an explicit business status `select` field such as `状态` / `处理状态` / `审批状态`; do not create platform workflow system fields such as `当前流程状态`
+  - use `views[]` with `operation="patch"` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
   - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
+  - 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` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
-  - when creating any new table or card view, always include `query_conditions` with `enabled: true`; populate `rows` with the fields most useful for searching — 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
+  - 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`
 
 ## Standard Operating Order
 
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm whether the task is read-only or write-impacting
+1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
+2. Confirm whether the task is read-only or write-impacting
+3. Classify the build scope:
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(package_id=..., apps=[...])`
+   - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
+   - record/task/data request -> leave builder and use the matching record/task skill
 4. Resolve the smallest stable target:
    - app-scoped work -> `app_resolve`
    - package-scoped work with known id -> `package_get`
    - portal inventory -> `portal_list`
 5. Read only the smallest config slice needed:
-   - app map -> `app_get` (default entry; includes compact views, charts, and associated resource pool)
+   - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
    - 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 and form layout -> `app_schema_apply`
-   - layout-only maintenance -> `app_layout_apply`
-   - flow -> `app_flow_apply`
-   - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
+   - fields -> `app_schema_apply`
+   - layout -> `app_layout_apply`
+   - flow -> `app_flow_apply` only when workflow is requested or clearly required
+   - views -> `app_views_apply(views=[...])`; use `operation="upsert"` for new/full views and `operation="patch"` for existing-view parameter changes
+   - view-specific business buttons -> put `action_buttons` on the same `views[]` item; use `set.action_buttons` for patch
+   - standalone button maintenance explicitly requested by the user -> `app_custom_buttons_apply`
    - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
    - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
 8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
+9. For complete-system builds, write `tmp/qingflow_system_build_summary.json` before the final response and make the final report match that file
 
 ## Safe Usage Rules
 
 - Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
+- Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
 - If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
+- Do not bypass package/app-name conflicts by inventing `V2`, `测试`, timestamp, or random suffix apps in a real business package. Read back and decide whether to update the existing app, create only a truly missing app, or ask the user.
+- After any uncertain schema write, do `readback_before_retry` with `package_get` / `app_resolve` / `app_get_fields`; retry only the verified missing or failed slice.
 - Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
-- Always pass `publish: true` (or CLI `--publish`) explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` when those tools are used directly. `app_associated_resources_apply` publishes automatically after at least one write succeeds and does not accept a `publish` parameter. `app_charts_apply` is immediate-live without a publish step.
+- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
 - 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.
-- When any tool returns `error_code` or `VALIDATION_ERROR`, read the `message` field verbatim first before guessing at parameter or CLI parsing issues. A clear `message` like "relation field requires visible_fields" is the root cause — do not redirect to unrelated hypotheses such as `create_if_missing` parsing or flag conflicts.
+- 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.
+- Workflow work should prefer `app_flow_get_schema` / `app_get_flow` readback plus `app_flow_apply(spec=...)` for full WorkflowSpec writes, or `patch_nodes` for targeted existing-node edits. Legacy `nodes/transitions` is only for simple linear flows.
 - Respect collaborative edit locks. Only use `app_release_edit_lock_if_mine` when the lock owner is the current authenticated user.
 - If the supported builder surface is still awkward or blocked after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
 
@@ -156,10 +215,18 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
 - 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 but verification is incomplete.
+- `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
@@ -183,30 +250,19 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Search members or roles: `member_search`, `role_search`
 - Create reusable role: `role_create`
 - Add/update/remove fields: `app_schema_apply`
-- Merge or replace layout-only changes on an existing app: `app_layout_apply`
+- Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
-- Upsert/patch/remove views: `app_views_apply`
+- Upsert/patch/remove views, including view-specific `action_buttons`: `app_views_apply(views=[...])`
+- Advanced standalone button maintenance only when explicitly requested: `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`
 
-## Playbook Selection
-
-Before starting any build or create task, route to the right reference first:
-
-| User intent | Signal phrases | Playbook |
-|-------------|---------------|---------|
-| Multi-app business system with cross-app relations and a portal workbench | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [build-complete-system.md](references/build-complete-system.md) |
-| Single app end-to-end: schema, form layout, views, view actions, optional workflow, and verification | "建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX"、"我需要一个管理XX的应用" | [build-single-app.md](references/build-single-app.md) |
-| Add one new app inside an existing package | "在这个包里加一个表单"、"现有系统里新增一个模块" | [create-app.md](references/create-app.md) |
-| Update fields or schema only | "加一个字段"、"改字段名"、"删除字段" | [update-schema.md](references/update-schema.md) |
-| Update layout only | "调整分组"、"改排列顺序" | [update-layout.md](references/update-layout.md) |
-| Update workflow only | "修改审批流"、"加一个审批节点" | [update-flow.md](references/update-flow.md) |
-| Update views only | "加一个看板"、"改筛选条件"、"新增视图" | [update-views.md](references/update-views.md) |
+## Standalone Button Boundary
 
-Decision rule: if the user mentions **multiple related apps or a portal**, use `build-complete-system.md`. If it is **one app** with a from-scratch setup request, use `build-single-app.md`. If the target app already exists and the user only wants to change one layer, use the matching single-layer playbook.
+For ordinary business builds, do not start from `app_custom_buttons_apply`. Put buttons in the view with `action_buttons`; see [references/update-views.md](references/update-views.md).
 
 ## Resources
 
@@ -215,6 +271,8 @@ Decision rule: if the user mentions **multiple related apps or a portal**, use `
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
 - Field matching rules: [references/match-rules.md](references/match-rules.md)
 - Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Single app development guide: [references/single-app-development-guide.md](references/single-app-development-guide.md)
+- Complete system development guide: [references/complete-system-development-guide.md](references/complete-system-development-guide.md)
 - Create one app in an existing package: [references/create-app.md](references/create-app.md)
 - Update fields only: [references/update-schema.md](references/update-schema.md)
 - Update layout only: [references/update-layout.md](references/update-layout.md)
@@ -222,5 +280,3 @@ Decision rule: if the user mentions **multiple related apps or a portal**, use `
 - Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
 - Update views only: [references/update-views.md](references/update-views.md)
 - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)
-- Build a complete multi-app system from scratch: [references/build-complete-system.md](references/build-complete-system.md)
-- Build a single app end-to-end (schema + form layout + views + view actions + optional workflow + verification): [references/build-single-app.md](references/build-single-app.md)

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

@@ -0,0 +1,169 @@
+# Complete System Development Guide
+
+Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
+Do not compress several business objects into one app.
+
+## Recommended Completeness
+
+Required:
+
+- package exists or is created through `package_apply`
+- core business objects are modeled as separate apps
+- all new apps are created in one multi-app `app_schema_apply(package_id=..., apps=[...])`
+- every app has stable `client_key`, `app_name`, `icon`, `color`, and one readable `as_data_title: true`
+- no app creates platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
+- same-call relations use `target_app_ref` to point to another `apps[].client_key`
+- basic operating views exist for each core app
+- package/apps/fields/relations are read back before repair or retry
+
+Strongly recommended:
+
+- cross-app relation fields for the main business links
+- core operating views declare needed business actions directly in `app_views_apply.views[].action_buttons`
+- portal chart sections declare needed QingBI charts inline through `sections[].chart`
+- a standard portal: business entry area, core metrics, BI charts, then concrete data views
+- portal grid/business-entry sections contain real `config.items[]`, not empty containers
+
+Workflow preflight:
+
+- If an app will have approval/fill/copy workflow nodes, create an explicit business status `select` field in schema first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
+- Do not create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- If `app_flow_apply` returns `FLOW_DEPENDENCY_MISSING`, fix schema with the returned `suggested_next_call`, read fields back, then retry the flow. Do not skip the workflow silently.
+
+Optional:
+
+- workflow, reminders, buttons, associated resources, sample data, roles, and permissions when the user asks for them or the business process clearly depends on them
+
+## Standard Path
+
+1. Resolve or create package: `package_get` / `package_apply`.
+2. Draft all apps and relations with stable `client_key` values.
+3. Run one multi-app `app_schema_apply` with `apps[]`.
+4. If write result is uncertain, run readback before retrying.
+5. Treat field layout as part of `apps[].form`; only use layout maintenance later when repairing an existing app.
+6. 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.
+7. Apply views; put view-specific business actions in `action_buttons` while designing the core operating views.
+8. Create the portal after referenced apps and views are known; create or reuse QingBI charts inline in portal sections with `chart`.
+9. Before the final response, write the complete-system delivery summary file described below.
+
+## Field Modeling Rules
+
+- Use agent-friendly field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`. The tool normalizes aliases such as `multiline -> long_text` and `select -> single_select`.
+- 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
+
+- Use `filters` for fixed saved filters that apply when the view opens.
+- Use `query_conditions` only for the frontend query panel layout. It is not another filter DSL and it does not express OR.
+- `query_conditions.rows` should contain query-panel fields such as text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
+- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`.
+- For current-record related views/reports, use `app_associated_resources_apply.match_mappings`, not `query_conditions`.
+
+## Portal Chart Rules
+
+- For complete systems, do not make chart creation a separate main step. When the portal needs metrics or BI blocks, declare them in `portal_apply.sections[].chart`.
+- Read `app_get_fields.chart_fields` before writing portal chart sections; 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.
+- Keep portal chart definitions business-scoped, commonly 4-8 charts by app or topic. Larger calls are accepted but should be read back before retrying.
+
+## View Action Rules
+
+- Design business buttons only with the view: `app_views_apply.views[].action_buttons`; for existing views use `operation="patch"` with `set.action_buttons`.
+- 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.
+- 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:
+
+`tmp/qingflow_system_build_summary.json`
+
+Use this file as the structured source of truth for the final report. Include at least:
+
+```json
+{
+  "package_id": 0,
+  "package_name": "",
+  "portal_dash_key": "",
+  "portal_live_status": "verified | unverified | not_created",
+  "front_end_visible": true,
+  "apps": [
+    {
+      "app_key": "",
+      "app_name": "",
+      "fields_count": 0,
+      "views_count": 0,
+      "flows_count": 0,
+      "charts_count": 0,
+      "publish_verify_status": "verified | unverified | failed"
+    }
+  ],
+  "warnings": [],
+  "partial_items": [],
+  "needs_followup": []
+}
+```
+
+Rules:
+
+- Populate IDs and counts from readback, not from intended payload only.
+- If a required resource is not verified, put it in `partial_items` or `needs_followup` instead of reporting the system as fully complete.
+- If the user later adds a data-entry task, keep that separate from the system-build summary unless the user explicitly wants one combined report.
+- The final response should match this file: completed resources, unverified items, frontend visibility, and follow-up needs must not contradict the JSON.
+- `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`.
+- Next action is always `readback_before_retry`: read package, resolve intended apps, then read fields/relations.
+- Retry only verified missing apps, fields, or relations.
+- Do not rebuild the system as separate single-app creates.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
+## Portal Template
+
+- Top area: one business entry grid plus one todo/common/frequent component when useful.
+- Metrics: one row of 4-6 indicator/target cards with portal section `role: "metric"`; recommended height 5.
+- BI charts: one row of 2-3 charts, 1-2 rows; recommended height 7.
+- Data views: one row of 1-2 concrete views, 1-2 rows; recommended height 11.
+- 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.