@qingflow-tech/qingflow-cli 1.1.33 → 1.1.34

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/complete-system-development-guide.md

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

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/create-app.md

@@ -1,203 +0,0 @@
-# Create App
-
-Use this when the user wants one new app inside an existing package.
-This playbook follows the current public builder surface, not legacy package helper tools.
-
-Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
-
-1. read or create the package through `package_get` / `package_apply`
-2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
-3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
-5. choose explicit non-template `icon + color` for each new package/app
-
-Hierarchy reminder:
-
-- package -> app -> field -> relation
-- another business object is another app, not a text field
-
-If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(package_name + icon + color)`.
-
-## Minimal sequence
-
-1. `package_get` if `package_id` is already known; otherwise derive the package from related readback or ask the user for the id
-2. `app_resolve`
-3. `app_schema_apply`
-4. `app_publish_verify` only when the user asks for explicit final verification
-
-## Multi-app systems are different
-
-If the user says things like:
-
-- “创建一个完整应用包”
-- “包含项目、需求、任务、缺陷、团队这几个表单”
-- “这些表单之间建立关联关系”
-
-then do not treat that as one app.
-
-Use this pattern instead:
-
-1. `package_get` or `package_apply(package_name + icon + color)`
-2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
-3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
-
-If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
-
-## Example
-
-When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
-
-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:
-
-> CLI-only note: this is the payload from former internal surface `package_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "package_name": "研发项目管理",
-  "icon": "briefcase",
-  "color": "azure"
-}
-```
-
-Read the package when `package_id` is already known:
-
-> CLI-only note: this is the payload from former internal surface `package_get`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "package_id": 1218950
-}
-```
-
-Apply schema for a new app:
-
-> CLI-only note: this is the payload from former internal surface `app_schema_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "app_name": "客户订单",
-  "package_id": 1218950,
-  "icon": "delivery-box-1",
-  "color": "emerald",
-  "publish": true,
-  "add_fields": [
-    {
-      "name": "订单编号",
-      "type": "text",
-      "required": true,
-      "as_data_title": true
-    },
-    {
-      "name": "客户名称",
-      "type": "text",
-      "required": true
-    },
-    {
-      "name": "订单封面",
-      "type": "attachment",
-      "as_data_cover": true
-    },
-    {
-      "name": "订单金额",
-      "type": "amount"
-    },
-    {
-      "name": "状态",
-      "type": "select",
-      "options": [
-        "草稿",
-        "进行中",
-        "已完成"
-      ],
-      "required": true
-    }
-  ],
-  "update_fields": [],
-  "remove_fields": []
-}
-```
-
-Apply schema for multiple apps in one call:
-
-> CLI-only note: this is the payload from former internal surface `app_schema_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "package_id": 1218950,
-  "publish": true,
-  "apps": [
-    {
-      "client_key": "customer",
-      "app_name": "客户",
-      "icon": "business-personalcard",
-      "color": "emerald",
-      "add_fields": [
-        {
-          "name": "客户名称",
-          "type": "text",
-          "required": true,
-          "as_data_title": true
-        }
-      ]
-    },
-    {
-      "client_key": "order",
-      "app_name": "订单",
-      "icon": "delivery-box-1",
-      "color": "blue",
-      "add_fields": [
-        {
-          "name": "订单编号",
-          "type": "text",
-          "required": true,
-          "as_data_title": true
-        },
-        {
-          "name": "关联客户",
-          "type": "relation",
-          "target_app_ref": "customer",
-          "display_field": {
-            "name": "客户名称"
-          },
-          "visible_fields": [
-            {
-              "name": "客户名称"
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-
-Data title is required: mark exactly one top-level field with `as_data_title: true`. Data cover is optional and only valid on a top-level `attachment` field.
-
-## Common failures
-
-### `APP_NOT_FOUND`
-
-Expected when the request was accidentally treated as existing-app update. Use
-direct create mode (`package_id + app_name` for one app, or `{package_id,
-apps[]}` for multi-app) and submit the intended schema payload.
-
-### `CREATE_APP_ROUTE_NOT_FOUND`
-
-The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
-
-### Hierarchy modeling mistake
-
-If the user asked for several named forms/apps but the draft patch turns them into text fields inside one app, stop and remodel the task as:
-
-- one package
-- many apps
-- relation fields between those apps

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/environments.md

@@ -1,63 +0,0 @@
-# Environment Switching
-
-Use this reference before any builder-side write, repair, or verification flow.
-
-## Step 1: Resolve the active environment
-
-Decide explicitly whether the task targets:
-
-- `test`: build validation, mock data, trial package creation, safe iteration
-- `prod`: formal business system changes in the live environment
-
-If the user did not specify an environment, default to `prod`.
-
-## Test Environment
-
-Use test for:
-
-- first application of a new `SolutionSpec`
-- trying `solution_build_all(..., verify=true)`
-- package initialization and schema evolution experiments
-- mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
-
-Builder behavior in test:
-
-- Read the target and contract first, then submit the chosen payload with `apply`
-- package creation is acceptable
-- verify should read back apps, views, portal, navigation, and sample records
-
-Known current test backend:
-
-- use an explicitly provided non-production backend
-
-## Production Environment
-
-Use production for:
-
-- changes to real business systems
-- additive modifications to live packages and apps
-- controlled rollout of approved solution specs
-
-Builder behavior in prod:
-
-- always identify the target package or app set before changing anything
-- identify the target package or app set, read the relevant contract, then submit the chosen payload with `apply`
-- additive requirements should modify the existing package with ordinary tools by default
-- if creating a new package seems necessary in prod, ask the user to confirm package creation first
-- do not seed mock data unless the user explicitly approves it for production
-- verify is mandatory after writes
-
-Production guardrails:
-
-- restate the target workspace and target package before any write
-- call out whether the action creates, mutates, or deletes builder-side configuration
-- if a safer read-only inspection can answer the request, do that first
-
-## Reporting Rule
-
-For builder work, always report:
-
-- active environment
-- target workspace
-- whether the operation is `apply`, `repair`, `verify`, or readback
-- whether it touches an existing package or creates a new one

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/flow-actors-and-permissions.md

@@ -1,142 +0,0 @@
-# Flow Actors And Permissions
-
-Use this when the workflow needs real assignees or node-level editable field permissions.
-
-## Canonical policy
-
-- Approval, fill, and copy nodes must declare at least one assignee.
-- Prefer roles over explicit members.
-- Resolve directory actors before calling `app_flow_apply`.
-- Use canonical keys only:
-  - `assignees.role_names`
-  - `assignees.role_ids`
-  - `assignees.member_names`
-  - `assignees.member_emails`
-  - `assignees.member_uids`
-  - `permissions.editable_fields`
-
-## Recommended order
-
-1. `app_get_fields`
-2. `app_get_flow`
-3. `role_search`
-4. `member_search` when the user explicitly names people
-5. `role_create` when no reusable role exists and the user wants role-based routing
-6. `app_flow_apply`
-
-## Examples
-
-### Route an approval node to a reusable role
-
-> CLI-only note: this is the payload from former internal surface `app_flow_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "app_key": "APP_123",
-  "preset": "basic_approval",
-  "nodes": [
-    {
-      "id": "approve_1",
-      "type": "approve",
-      "name": "部门审批",
-      "assignees": {
-        "role_names": [
-          "项目经理"
-        ]
-      }
-    }
-  ]
-}
-```
-
-### Route to explicit members when the user names people
-
-> CLI-only note: this is the payload from former internal surface `app_flow_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "app_key": "APP_123",
-  "preset": "basic_approval",
-  "nodes": [
-    {
-      "id": "approve_1",
-      "type": "approve",
-      "name": "部门审批",
-      "assignees": {
-        "member_names": [
-          "严琪东",
-          "张三"
-        ]
-      }
-    }
-  ]
-}
-```
-
-### Let one node edit selected fields only
-
-> CLI-only note: this is the payload from former internal surface `app_flow_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "app_key": "APP_123",
-  "mode": "replace",
-  "publish": true,
-  "nodes": [
-    {
-      "id": "start",
-      "type": "start",
-      "name": "发起"
-    },
-    {
-      "id": "approve_1",
-      "type": "approve",
-      "name": "部门审批",
-      "assignees": {
-        "role_names": [
-          "项目经理"
-        ]
-      },
-      "permissions": {
-        "editable_fields": [
-          "状态",
-          "审批意见",
-          "项目负责人"
-        ]
-      }
-    },
-    {
-      "id": "end",
-      "type": "end",
-      "name": "结束"
-    }
-  ],
-  "transitions": [
-    {
-      "from": "start",
-      "to": "approve_1"
-    },
-    {
-      "from": "approve_1",
-      "to": "end"
-    }
-  ]
-}
-```
-
-## Common recovery
-
-### `ROLE_NOT_FOUND` / `AMBIGUOUS_ROLE`
-
-- retry with `role_search`
-- if the business wants a reusable route and no exact role exists, create one with `role_create`
-
-### `MEMBER_NOT_FOUND` / `AMBIGUOUS_MEMBER`
-
-- retry with `member_search`
-- do not guess user ids
-
-### `UNKNOWN_FLOW_FIELD`
-
-- reread fields with `app_get_fields`
-- only pass real current field names to `permissions.editable_fields`

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/gotchas.md

@@ -1,116 +0,0 @@
-# Builder Gotchas
-
-## Auth and workspace
-
-- `auth_*` success does not mean a workspace is selected
-- Re-run `workspace_select` after auth changes or route changes
-
-## Package ownership
-
-- Public package work should stay on `package_get / package_apply`
-- Do not treat `package_attach_app` as the public default story anymore; if it still exists in low-level code, treat it as internal/legacy
-- Check package-related readback after schema writes instead of assuming package ownership from the write alone
-
-## Package vs app vs field
-
-- A package/system is not an app
-- Another app is not a field
-- If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
-- Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
-
-## Publish
-
-- Always pass `publish: true` explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default
-- Pass `publish: false` on those five tools only when the user explicitly wants to leave changes in draft
-- `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a `publish` parameter
-- `app_charts_apply` is immediate-live and has no publish step
-- `app_publish_verify` is for explicit final verification, not the default next step after every write
-
-## BI Reports
-
-- Use `app_charts_apply` for QingBI report body/config creation or updates.
-- Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
-- `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
-- Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
-- 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`.
-
-## Custom buttons
-
-- For ordinary view-specific business buttons, use `app_views_apply.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`.
-- 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.
-- Advanced view button bindings can include `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls`, but keep ordinary buttons simple unless the user asks for conditional visibility or print templates.
-- `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
-
-## Associated resources
-
-- Before creating an associated view/report, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`.
-- If the resource already exists, use `patch_resources` with its `associated_item_id`; do not call `upsert_resources` again.
-- For per-view display, remove, and reorder, existing associated reports/views may be referenced by `associated_item_id`, `chart_id`/`chart_key`, or `view_key`; the tool resolves these to the internal id before writing.
-- `client_key` is only a same-call alias for `view_configs[].associated_item_refs`. It is not stored by Qingflow and cannot prevent duplicates in later calls.
-- Repeated `upsert_resources` without `associated_item_id` can create multiple app-level associated items pointing to the same view/report.
-
-## Readback scope
-
-- Prefer summary reads over large raw payloads
-- Use `app_get_fields` before schema or view work
-- Use `app_get_layout` before layout work
-- Use `app_get_flow` before workflow work
-- Use `app_get_views` before view work
-
-## Partial update discipline
-
-- Existing views, custom buttons, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
-- The backend may still save a full payload. The 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; 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.
-- `app_flow_apply` is intentionally replace-only for the public linear workflow graph.
-
-## Workflow dependencies
-
-- Approval-style flows usually require an explicit status field
-- Approval, fill, and copy nodes also require at least one assignee
-- Prefer roles over explicit members unless the user explicitly names people
-- Resolve assignees with `role_search` / `member_search` before flow apply
-- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
-- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
-- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
-- Do not switch to hidden `solution_*` tools from public builder flows
-
-## Retry discipline
-
-- If a write returns `partial_success`, read back before retrying
-- Do not repeat create steps after `app_key` already exists
-- For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
-- For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
-- For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `qingflow --json builder contract(app_layout_apply)`.
-- For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
-  - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
-  - `permissions.editable_fields`
-- For view work, treat `columns` as the only canonical public key. `app_get_views` and `app_views_apply` should all be read and written in that shape.
-- For existing view parameter changes, prefer `patch_views`. Example: to change only query-panel fields, set only `query_conditions`; the tool will preserve columns, filters, date config, card fields, buttons, and other backend-required fields.
-- For layout work, treat `title + rows` as the only canonical public section shape. `fields`, `field_ids`, and `columns` may appear in legacy/internal shapes, but they are not the preferred public write shape.
-- A created view is not enough to claim a filter succeeded. When `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, treat the view as present but the filter as unverified.
-- If duplicate view names exist, do not retry by name. Read the exact `view_key` and target that one.
-- If a view or flow write fails, report the smallest next action:
-  - wrong key -> switch to canonical key
-  - unsupported preset -> switch to allowed canonical preset
-  - backend reject -> re-read summary and retry only the failed patch
-- Do not translate abstract user phrases like “灵活流程” or “默认视图” directly into CLI arguments. First convert them to a preset or explicit patch design.