@josephyan/qingflow-app-builder-mcp 0.2.0-beta.37 → 0.2.0-beta.39

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.37
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.39
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.37 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.39 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

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

package/pyproject.toml

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

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

@@ -49,15 +49,17 @@ Default modeling rules:
 - Authentication and workspace: `auth_*`, `workspace_*`
 - File upload: `file_upload_local`
 - Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
-- Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
-- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `chart_apply`, `portal_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
 - Publish and verify: `app_publish_verify`
 
 Note:
 - Do not try to handcraft raw Qingflow schema or internal solution payloads.
-- Do not rely on low-level `view_*`, `workflow_*`, or `qingbi_report_*` write payloads from public builder flows.
-- Public builder work should stay on the resource path: `resolve -> summary read -> plan -> apply -> attach -> publish_verify`.
+- Do not rely on low-level `view_*`, `workflow_*`, `qingbi_report_*`, or `portal_*` write payloads from public builder flows.
+- Public builder work should stay on the resource path: `resolve -> summary read -> apply -> attach -> publish_verify`.
 - `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` publish by default; pass `publish=false` only when you intentionally want to leave changes in draft.
+- `chart_apply` is immediate-live and does not publish.
+- `portal_apply` uses replace semantics for sections; remove a section by omitting it from the next full sections list.
+- `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` now perform planning, normalization, and dependency checks internally; when prechecks block, read the returned blocking issues and `suggested_next_call` directly from the apply result.
 - If you are unsure about a public builder tool's keys, aliases, presets, or minimal legal shape, call `builder_tool_contract` instead of guessing.
 - For views, always write the canonical key `columns`. Do not emit `column_names`; treat `fields` only as a tolerated legacy alias, not the preferred shape.
 - For flow presets, map natural language to canonical values before calling MCP:
@@ -73,7 +75,7 @@ Note:
 
 Default policy:
 
-- Creating or updating one app inside an existing package: resolve the package/app, read compact state, plan patches on the server, then apply schema/layout/flow/views patches explicitly.
+- Creating or updating one app inside an existing package: resolve the package/app, read compact state, then apply schema/layout/flow/views patches explicitly.
 - If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
 - If the user describes a system/package with multiple forms or modules, do not start with `app_schema_apply` on the package name. Resolve or create the package first, then create each app separately.
 
@@ -93,23 +95,21 @@ For builder work:
    - multi-app package/system: create or resolve the package, then create each app separately before adding relations
 3. Resolve the target app with `app_resolve` if the request is an update.
 4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
-5. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
-6. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
-7. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
-8. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
-9. Use `app_flow_apply` after schema exists. It publishes by default.
-10. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
-11. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
-12. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
+5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands; noop schema requests do not publish.
+6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
+7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default after the patch lands; noop layout requests do not publish.
+8. Use `app_flow_apply` after schema exists. It publishes by default; pass `publish=false` when you only want draft/precheck behavior.
+9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default after the patch lands; noop view requests do not publish.
+10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
+11. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
 
 For view work, keep the order strict:
 
 1. `builder_tool_contract`
 2. `app_read_fields`
 3. `app_read_views_summary`
-4. `app_views_plan`
-5. `app_views_apply`
-6. `app_read_views_summary` again whenever `app_views_apply` returns `failed` or `partial_success`
+4. `app_views_apply`
+5. `app_read_views_summary` again whenever `app_views_apply` returns `failed` or `partial_success`
 
 For flow work, keep the order strict:
 
@@ -128,11 +128,10 @@ For flow work, keep the order strict:
    - prefer `assignees.role_names`
    - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
 10. When a node must edit specific fields, declare `permissions.editable_fields`
-11. `app_flow_plan`
-12. `app_flow_apply`
-13. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
-
-In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
+11. `app_flow_apply`
+12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
+13. Use `chart_apply` for QingBI chart creation and updates, not raw `qingbi_report_*` writes
+14. Use `portal_apply` for builder-side portal work; treat sections as a full replacement list
 
 For additive work on existing systems:
 
@@ -145,7 +144,7 @@ For additive work on existing systems:
 
 - When using `package_name`, expect deterministic resolution only on a unique exact package name match; if multiple packages match, stop and resolve the ambiguity instead of guessing
 - `app_schema_apply` is the only public patch tool allowed to create an app shell; `app_layout_apply`, `app_flow_apply`, and `app_views_apply` require an existing app.
-- Prefer `*_plan` before `*_apply`; the plan tools do server-side normalization and return the next executable call skeleton.
+- Prefer reading compact state plus `builder_tool_contract` before `*_apply`; apply already performs server-side normalization and returns blocking issues or the next executable call shape when needed.
 - For abstract requests like “默认视图”, “基础审批流”, “灵活流程”, or “美观布局”, first translate the intent into a stable preset or explicit patch. Do not send those phrases to MCP unchanged.
 - If the user asks for a business system or package that contains several forms, do not use the system/package name as `app_name` and do not try to store the child app names as text fields.
 - For flexible workflow requests, split the work into two steps:
@@ -157,14 +156,12 @@ For additive work on existing systems:
   - `assignees.role_names`
   - `assignees.member_names`
   - `permissions.editable_fields`
-- Reuse `app_flow_plan` output directly when it succeeds. Do not rewrite it into internal keys such as `role_entries` or `editable_que_ids`.
-- Reuse `app_views_plan` output directly when it succeeds. Do not re-expand aliases such as `column_names`.
 - For layout work, keep the public section shape canonical:
   - `title`
   - `rows`
   Do not invent top-level layout `columns`, and do not prefer `fields` or `field_ids` once `rows` is known.
 - Translate natural language like “一行四个字段 / 四列布局 / 每行放四个” into `rows` matrices, not guessed layout parameters.
-- If the same layout-shape `VALIDATION_ERROR` repeats twice, stop guessing and re-read `builder_tool_contract(app_layout_plan)` or the layout reference before trying again.
+- If the same layout-shape `VALIDATION_ERROR` repeats twice, stop guessing and re-read `builder_tool_contract(app_layout_apply)` or the layout reference before trying again.
 - Do not guess role ids or member ids. Resolve them from the directory first.
 - `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
@@ -184,7 +181,7 @@ For additive work on existing systems:
 - If multiple views share the same name, do not guess which one to update. Read `view_key` from `app_read_views_summary` and pass it explicitly in `upsert_views[]`.
 - In final user-facing summaries, distinguish clearly between:
   - contract is visible / canonical shape is known
-  - plan succeeded
+  - apply precheck succeeded
   - apply landed and readback verified it
   - base template/skeleton applied
   - business-specific rules completed
@@ -203,10 +200,6 @@ For additive work on existing systems:
 - Read layout summary: `app_read_layout_summary`
 - Read views summary: `app_read_views_summary`
 - Read flow summary: `app_read_flow_summary`
-- Plan schema patch: `app_schema_plan`
-- Plan layout patch: `app_layout_plan`
-- Plan workflow patch: `app_flow_plan`
-- Plan view patch: `app_views_plan`
 - Search members for workflow assignees: `member_search`
 - Search roles for workflow assignees: `role_search`
 - Create reusable workflow role: `role_create`
@@ -214,6 +207,8 @@ For additive work on existing systems:
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
 - Upsert/remove views: `app_views_apply`
+- Upsert/remove/reorder QingBI charts: `chart_apply`
+- Create or replace-update portal pages: `portal_apply`
 - Attach one app to a package: `package_attach_app`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Publish and verify: `app_publish_verify` when you need a separate verification pass beyond the default auto-publish behavior in apply tools

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

@@ -20,10 +20,9 @@ If creating a brand new package would help, ask the user to confirm package crea
 
 1. `package_resolve`
 2. `app_resolve`
-3. `app_schema_plan`
-4. `app_schema_apply`
-5. `package_attach_app`
-6. `app_publish_verify` only when the user asks for explicit final verification
+3. `app_schema_apply`
+4. `package_attach_app`
+5. `app_publish_verify` only when the user asks for explicit final verification
 
 ## Multi-app systems are different
 
@@ -38,7 +37,7 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_resolve` or `package_create`
-2. for each app name, run `app_schema_plan -> app_schema_apply -> package_attach_app`
+2. for each app name, run `app_schema_apply -> package_attach_app`
 3. once the apps exist, add `relation` fields between them
 
 ## Example
@@ -67,16 +66,17 @@ Resolve the package:
 }
 ```
 
-Plan schema for a new app:
+Apply schema for a new app:
 
 ```json
 {
-  "tool_name": "app_schema_plan",
+  "tool_name": "app_schema_apply",
   "arguments": {
     "profile": "default",
     "app_name": "客户订单",
     "package_tag_id": 1218950,
     "create_if_missing": true,
+    "publish": true,
     "add_fields": [
       {"name": "订单编号", "type": "text", "required": true},
       {"name": "客户名称", "type": "text", "required": true},
@@ -88,26 +88,6 @@ Plan schema for a new app:
   }
 }
 ```
-
-Apply schema. This publishes by default:
-
-```json
-{
-  "tool_name": "app_schema_apply",
-  "arguments": {
-    "profile": "default",
-    "app_name": "客户订单",
-    "package_tag_id": 1218950,
-    "create_if_missing": true,
-    "publish": true,
-    "add_fields": [
-      {"name": "订单编号", "type": "text", "required": true},
-      {"name": "客户名称", "type": "text", "required": true},
-      {"name": "订单金额", "type": "amount"},
-      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
-    ],
-    "update_fields": [],
-    "remove_fields": []
   }
 }
 ```

package/skills/qingflow-app-builder/references/flow-actors-and-permissions.md

@@ -6,7 +6,7 @@ Use this when the workflow needs real assignees or node-level editable field per
 
 - Approval, fill, and copy nodes must declare at least one assignee.
 - Prefer roles over explicit members.
-- Resolve directory actors before calling `app_flow_plan` or `app_flow_apply`.
+- Resolve directory actors before calling `app_flow_apply`.
 - Use canonical keys only:
   - `assignees.role_names`
   - `assignees.role_ids`
@@ -22,8 +22,7 @@ Use this when the workflow needs real assignees or node-level editable field per
 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_plan`
-7. `app_flow_apply`
+6. `app_flow_apply`
 
 ## Examples
 
@@ -31,7 +30,7 @@ Use this when the workflow needs real assignees or node-level editable field per
 
 ```json
 {
-  "tool_name": "app_flow_plan",
+  "tool_name": "app_flow_apply",
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
@@ -54,7 +53,7 @@ Use this when the workflow needs real assignees or node-level editable field per
 
 ```json
 {
-  "tool_name": "app_flow_plan",
+  "tool_name": "app_flow_apply",
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",

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

@@ -40,7 +40,7 @@
 - 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_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
+- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 
 ## Retry discipline
@@ -49,11 +49,11 @@
 - 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 `builder_tool_contract(app_layout_plan)`.
+- 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 `builder_tool_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_read_views_summary` and `app_views_plan/apply` should all be read and written in that shape.
+- For view work, treat `columns` as the only canonical public key. `app_read_views_summary` and `app_views_apply` should all be read and written in that shape.
 - 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.

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -6,23 +6,20 @@ Use these when you need a quick reminder of the standard v2 builder sequences.
 
 1. `package_resolve`
 2. `app_resolve`
-3. `app_schema_plan`
-4. `app_schema_apply`
-5. `package_attach_app`
-6. `app_publish_verify` only if the user asks for explicit live verification
+3. `app_schema_apply`
+4. `package_attach_app`
+5. `app_publish_verify` only if the user asks for explicit live verification
 
 ## Update fields on an existing app
 
 1. `app_resolve`
 2. `app_read_fields`
-3. `app_schema_plan`
-4. `app_schema_apply`
+3. `app_schema_apply`
 
 ## Rework layout
 
 1. `app_read_layout_summary`
-2. `app_layout_plan`
-3. `app_layout_apply`
+2. `app_layout_apply`
 
 Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
 
@@ -32,18 +29,16 @@ Prefer `mode=merge`. Use `mode=replace` only when every field placement is inten
 2. `app_read_flow_summary`
 3. `role_search` or `member_search`
 4. `role_create` if the business wants a reusable role and no good exact role exists
-5. `app_flow_plan`
-6. `app_flow_apply`
+5. `app_flow_apply`
 
-If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
+If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
 If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
 
 ## Add or update views
 
 1. `app_read_fields`
 2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+3. `app_views_apply`
 
 For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
 

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -4,9 +4,9 @@ Use the smallest v2 builder tool chain that can finish the task.
 
 ## Default path
 
-`resolve -> summary read -> plan -> apply -> attach -> publish_verify`
+`resolve -> summary read -> apply -> attach -> publish_verify`
 
-Use `plan` before `apply` unless the patch is trivial and already normalized.
+Public builder `apply` tools already perform server-side planning, normalization, and dependency checks internally. Do not route normal public builder work through explicit `*_plan` tools.
 
 ## Hierarchy first
 
@@ -37,17 +37,6 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 - `app_read_views_summary`: current view names, types, columns, group-by
 - `app_read_flow_summary`: workflow enabled state, nodes, transitions
 
-## Plan tools
-
-Use these when the patch is non-trivial or the model is likely to drift.
-
-- `app_schema_plan`: normalize field patches before add/update/remove
-- `app_layout_plan`: preview merge/replace layout changes or layout presets
-- `app_flow_plan`: validate workflow nodes, transitions, and dependencies
-- `app_views_plan`: normalize view aliases and validate referenced fields
-
-Use `builder_tool_contract` before guessing keys, aliases, presets, or enum values.
-
 ## Apply tools
 
 These execute normalized patches and publish by default unless `publish=false`.
@@ -56,6 +45,8 @@ These execute normalized patches and publish by default unless `publish=false`.
 - `app_layout_apply`: merge or replace layout
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: upsert or remove views
+- `chart_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish
+- `portal_apply`: create or replace-update portal pages; sections are replace-only and omission deletes old sections
 
 ## Explicit post-apply tools
 
@@ -65,19 +56,23 @@ These execute normalized patches and publish by default unless `publish=false`.
 ## Decision shortcuts
 
 - Create one app inside an existing package:
-  `package_resolve -> app_resolve -> app_schema_plan -> app_schema_apply -> package_attach_app`
+  `package_resolve -> app_resolve -> app_schema_apply -> package_attach_app`
 - Create a brand new package, then create one app in it:
-  `package_create -> package_resolve -> app_schema_plan -> app_schema_apply -> package_attach_app`
+  `package_create -> package_resolve -> app_schema_apply -> package_attach_app`
 - Create a brand new multi-app system/package:
-  `package_create/resolve -> per-app app_schema_plan/apply -> package_attach_app per app -> relation field patches`
+  `package_create/resolve -> per-app app_schema_apply -> package_attach_app per app -> relation field patches`
 - Update fields on an existing app:
-  `app_resolve -> app_read_fields -> app_schema_plan -> app_schema_apply`
+  `app_resolve -> app_read_fields -> app_schema_apply`
 - Tidy layout:
-  `app_read_fields -> app_read_layout_summary -> builder_tool_contract (if shape is unclear) -> app_layout_plan -> app_layout_apply`
+  `app_read_fields -> app_read_layout_summary -> builder_tool_contract (if shape is unclear) -> app_layout_apply`
 - Add workflow:
-  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
+  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_apply -> app_read_flow_summary`
 - Add views:
-  `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply -> app_read_views_summary`
+  `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_apply -> app_read_views_summary`
+- Add QingBI charts:
+  `builder_tool_contract -> app_read_fields -> chart_apply`
+- Create or update a portal:
+  `builder_tool_contract -> portal_apply`
 
 ## Avoid
 

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

@@ -4,7 +4,7 @@ Use this when the app already exists and the task is only about workflow.
 
 ## Minimal sequence
 
-1. `builder_tool_contract(tool_name="app_flow_plan")`
+1. `builder_tool_contract(tool_name="app_flow_apply")`
 2. `app_read_fields`
 3. `app_read_flow_summary`
 4. `role_search` or `member_search`
@@ -16,9 +16,8 @@ Use this when the app already exists and the task is only about workflow.
    - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
    Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
    The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
-9. `app_flow_plan`
-10. `app_flow_apply`
-11. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
+9. `app_flow_apply`
+10. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -29,15 +28,16 @@ Canonical preset mapping:
 - “默认审批/基础审批/普通审批” -> `basic_approval`
 - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
 
-Plan a simple approval flow with a role assignee and node-level editable fields:
+Apply a simple approval flow with a role assignee and node-level editable fields:
 
 ```json
 {
-  "tool_name": "app_flow_plan",
+  "tool_name": "app_flow_apply",
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
     "preset": "basic_approval",
+    "publish": true,
     "nodes": [
       {
         "id": "approve_1",
@@ -72,7 +72,7 @@ Canonical branch example:
 
 ```json
 {
-  "tool_name": "app_flow_plan",
+  "tool_name": "app_flow_apply",
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
@@ -115,41 +115,7 @@ Canonical branch example:
   }
 }
 ```
-
-Only after that should you use explicit nodes:
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-        "profile": "default",
-        "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"}
-        ]
-      }
-}
-```
-
-After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+After `app_flow_apply` returns blocking issues or canonical arguments, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
 When you patch a preset, patch the preset node itself. Do not leave the preset approval node unassigned while adding a second custom approval node.
 
 ## Common failures
@@ -170,7 +136,7 @@ Preferred fix order:
 2. `member_search` only if the user explicitly named members
 3. `role_create` if the business needs a reusable role
 4. patch the preset node id itself with canonical `assignees.*`
-5. retry `app_flow_plan` or `app_flow_apply`
+5. retry `app_flow_apply`
 
 ### `FLOW_DEPENDENCY_MISSING`
 
@@ -181,7 +147,7 @@ Preferred recovery:
 1. use the returned `suggested_next_call`
 2. apply the minimal schema patch
 3. rerun `app_read_fields`
-4. rerun `app_flow_plan`
+4. rerun `app_flow_apply`
 
 ### `INVALID_FLOW_EDGE`
 
@@ -202,7 +168,7 @@ The app has no explicit status field recognized by the internal workflow compile
 
 ### `FLOW_STAGE_CONTEXT_MISSING`
 
-Internal flow stage context was missing or invalid. Re-run `app_flow_plan`, then retry `app_flow_apply`. Do not switch to hidden `solution_*` tools.
+Internal flow stage context was missing or invalid. Re-run `app_flow_apply` with the normalized arguments, and do not switch to hidden `solution_*` tools.
 
 ### `VALIDATION_ERROR`
 

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

@@ -7,34 +7,11 @@ Use this when fields already exist and the task is only about form grouping or o
 1. `app_read_fields`
 2. `app_read_layout_summary`
 3. `builder_tool_contract` when the section shape is not already obvious
-4. `app_layout_plan`
-5. `app_layout_apply`
+4. `app_layout_apply`
 
 ## Example
 
-Plan a custom layout with the canonical public section shape:
-
-```json
-{
-  "tool_name": "app_layout_plan",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "mode": "merge",
-    "sections": [
-      {
-        "title": "基础信息",
-        "rows": [
-          ["客户名称", "订单金额"],
-          ["状态", "跟进日期"]
-        ]
-      }
-    ]
-  }
-}
-```
-
-Apply the layout. This publishes by default:
+Apply a custom layout with the canonical public section shape:
 
 ```json
 {
@@ -79,7 +56,7 @@ Re-read with `app_read_layout_summary`. Check `current_field_names`, `request_id
 
 Do not keep guessing section keys. Reuse `suggested_next_call`, `canonical_arguments`, `section_allowed_keys`, and `minimal_section_example`.
 
-If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_plan)`.
+If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
 
 ## Notes
 

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

@@ -6,8 +6,7 @@ Use this when the app already exists and the task is only about fields.
 
 1. `app_resolve`
 2. `app_read_fields`
-3. `app_schema_plan`
-4. `app_schema_apply`
+3. `app_schema_apply`
 
 ## Example
 
@@ -23,27 +22,6 @@ Read current fields first:
 }
 ```
 
-Plan the patch:
-
-```json
-{
-  "tool_name": "app_schema_plan",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "add_fields": [
-      {"name": "跟进日期", "type": "date"}
-    ],
-    "update_fields": [
-      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
-    ],
-    "remove_fields": [
-      {"name": "旧字段"}
-    ]
-  }
-}
-```
-
 Apply the patch:
 
 ```json