@josephyan/qingflow-cli 1.1.3 → 1.1.5

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

@@ -0,0 +1,123 @@
+# 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 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 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. 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.
+
+## 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`.
+
+## 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.
+
+## 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

@@ -0,0 +1,182 @@
+# 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 each app separately
+3. keep package ownership on the public `package_id` path instead of a separate attach step
+4. add relation fields between apps
+
+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(create_if_missing=true, package_name=...)`.
+
+## 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(create_if_missing=true, package_name=...)`
+2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
+
+## Example
+
+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": "研发项目管理",
+  "create_if_missing": true
+}
+```
+
+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,
+  "create_if_missing": true,
+  "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": "single_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,
+  "create_if_missing": true,
+  "publish": true,
+  "apps": [
+    {
+      "client_key": "customer",
+      "app_name": "客户",
+      "add_fields": [
+        {
+          "name": "客户名称",
+          "type": "text",
+          "required": true,
+          "as_data_title": true
+        }
+      ]
+    },
+    {
+      "client_key": "order",
+      "app_name": "订单",
+      "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 on create. Continue with `create_if_missing=true`.
+
+### `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

@@ -0,0 +1,63 @@
+# 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:
+
+- `preflight` or `plan` is still preferred, but fast `apply` is acceptable when the user explicitly wants an end-to-end smoke test
+- 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
+- default to `preflight` or `plan` before any `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 `plan`, `apply`, `repair`, or `verify`
+- 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

@@ -0,0 +1,142 @@
+# 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

@@ -0,0 +1,108 @@
+# 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.
+- `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
+
+## Custom buttons
+
+- Use `app_custom_buttons_apply` for button creation/update/removal and view placement; do not split placement into `app_views_apply.buttons` unless you are maintaining a legacy patch.
+- When changing one existing button parameter, use `patch_buttons` with `set/unset`. Do not send a partial `upsert_buttons` object and expect the backend to preserve hidden required fields.
+- For add-data buttons, prefer semantic `trigger_add_data_config.target_app_key`, `field_mappings`, and `default_values`.
+- Do not handwrite raw `que_relation` unless you are preserving an existing backend config. If `field_mappings` and `que_relation` are mixed, the tool blocks the write.
+- `field_mappings.source_field` can use source app fields and supported system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`).
+- To fill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`. Use `default_values` only for static constants.
+- For field type compatibility, read `references/match-rules.md`.
+- Default button placements are `header` and `detail`; these map to the frontend's header and detail button areas.
+- `view_configs[].buttons` is required in merge mode. Do not send a view config with only `view_key`; it is blocked to avoid no-op writes and accidental publish.
+- Builder view configs use raw `view_key` from `app_get.views[].view_key`; do not prefix it with `custom:`. The `custom:<viewKey>` form is for record-data `view_id`.
+- View button bindings merge by default. Use `view_configs[].mode="replace"` to replace the full set, or pass an explicit empty `buttons: []` when you intend to clear all custom button bindings for that view.
+- Advanced view button bindings can include `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls`, but keep ordinary buttons simple unless the user asks for conditional visibility or print templates.
+- `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
+
+## Associated resources
+
+- Before creating an associated view/report, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`.
+- If the resource already exists, use `patch_resources` with its `associated_item_id`; do not call `upsert_resources` again.
+- For per-view display, remove, and reorder, existing associated reports/views may be referenced by `associated_item_id`, `chart_id`/`chart_key`, or `view_key`; the tool resolves these to the internal id before writing.
+- `client_key` is only a same-call alias for `view_configs[].associated_item_refs`. It is not stored by Qingflow and cannot prevent duplicates in later calls.
+- Repeated `upsert_resources` without `associated_item_id` can create multiple app-level associated items pointing to the same view/report.
+
+## Readback scope
+
+- Prefer summary reads over large raw payloads
+- Use `app_get_fields` before schema or view work
+- Use `app_get_layout` before layout work
+- Use `app_get_flow` before workflow work
+- Use `app_get_views` before view work
+
+## Partial update discipline
+
+- Existing views, custom buttons, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
+- The backend may still save a full payload. The CLI patch path is responsible for reading current config and preserving fields the user did not mention.
+- Do not use `upsert_views`, `upsert_buttons`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
+- `app_layout_apply(mode=merge)` is already a safe layout merge path; `mode=replace` is full layout replacement.
+- `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list.
+- `app_flow_apply` is intentionally replace-only for the public linear workflow graph.
+
+## Workflow dependencies
+
+- Approval-style flows usually require an explicit status field
+- Approval, fill, and copy nodes also require at least one assignee
+- Prefer roles over explicit members unless the user explicitly names people
+- Resolve assignees with `role_search` / `member_search` before flow apply
+- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
+- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
+- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
+- Do not switch to hidden `solution_*` tools from public builder flows
+
+## Retry discipline
+
+- If a write returns `partial_success`, read back before retrying
+- Do not repeat create steps after `app_key` already exists
+- For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
+- For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
+- For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `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 plan.