@josephyan/qingflow-app-builder-mcp 0.2.0-beta.11 → 0.2.0-beta.13

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.11",
+  "version": "0.2.0-beta.13",
   "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.0b11"
+version = "0.2.0b13"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -17,6 +17,29 @@ Before any write or verification flow, identify whether the task targets `test`
 
 Pick the smallest tool layer that can finish the task.
 
+## Mental Model
+
+Model builder requests in four layers. Do not flatten them.
+
+- `package`: the solution container or app bundle, for example “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package, for example “项目”, “需求”, “任务”, “缺陷”, “团队”
+- `field`: one field inside one app
+- `relation`: a field that links one app to another app
+
+Interpret user intent with this hierarchy:
+
+- If the user says “应用包”, “系统”, “包含多个表单”, “多个模块”, or asks for several named forms that relate to each other, treat it as a `package` with multiple `apps`
+- Do not compress a multi-app system into one app with several text fields
+- Names like “项目/需求/任务/缺陷/团队” or “费用申请/预算管理/报销审批” are usually separate apps, not text fields
+- Build the apps first, then add `relation` fields to connect them
+
+Default modeling rules:
+
+- One business object -> one app
+- Attributes of that object -> fields inside that app
+- Another business object -> a separate app, not a text field
+- Cross-object links -> relation fields, not text fields
+
 - 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`
@@ -34,6 +57,7 @@ Note:
 - For flow presets, map natural language to canonical values before calling MCP:
   - “默认审批/基础审批/普通审批” -> `basic_approval`
   - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
 - For workflow assignees, prefer roles over explicit members:
   - use `role_search` first
   - use `member_search` only when the user explicitly names members or no stable role exists
@@ -44,6 +68,7 @@ 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.
 - 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.
 
 ## Standard Operating Order
 
@@ -56,38 +81,49 @@ Before any business tool:
 For builder work:
 
 1. Resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`. If you believe a new package should be created, ask the user to confirm before calling `package_create`.
-2. Resolve the target app with `app_resolve` if the request is an update.
-3. 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`.
-4. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
-5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
-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.
-8. Use `app_flow_apply` after schema exists. It publishes by default.
-9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
-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.
+2. Decide whether the target is one app or a multi-app package:
+   - one app: continue with `app_resolve`
+   - 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.
 
 For view work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+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`
 
 For flow work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. `role_search` or `member_search` if assignees need to come from the directory
-4. `role_create` if the user wants a reusable role and no suitable role exists yet
-5. Start from a canonical preset when possible
-6. Use patch-style edits to that skeleton instead of freehand full-graph generation
-7. Declare approver/fill/copy assignees explicitly:
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search` if assignees need to come from the directory
+5. `role_create` if the user wants a reusable role and no suitable role exists yet
+6. Start from a canonical preset when possible
+7. Use patch-style edits to that skeleton instead of freehand full-graph generation
+8. When patching a preset skeleton, reuse the preset node ids:
+   - `basic_approval` -> patch `approve_1`
+   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
+   Do not invent a second approval/fill node id unless you are intentionally replacing the skeleton and removing the preset node.
+9. Declare approver/fill/copy assignees explicitly:
    - prefer `assignees.role_names`
    - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
-8. When a node must edit specific fields, declare `permissions.editable_fields`
-9. `app_flow_plan`
-10. `app_flow_apply`
+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.
 
@@ -104,18 +140,23 @@ For additive work on existing systems:
 - `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.
 - 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:
   1. create a base skeleton with a preset
   2. apply explicit business-specific changes as patchable nodes/transitions
+- For preset-based flows, treat preset node ids as part of the public contract. Patch the skeleton nodes by the same ids instead of creating a parallel node with a new id and leaving the preset node unassigned.
 - Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
 - For workflow nodes, use the canonical public shape:
   - `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`.
 - 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.
 - `relation` and `subtable` must be explicit; do not infer them from vague natural language.
+- Another app is not a field. If two business objects should both have their own records, build two apps and connect them with relation fields.
 - In `prod`, prefer explicit patch tools and avoid any speculative create flow.
 - Never try to bypass collaborative edit locks. `app_release_edit_lock_if_mine` is only for the case where the lock owner is the current authenticated user.
 
@@ -125,7 +166,11 @@ For additive work on existing systems:
 - `app_publish_verify` is the publish source of truth.
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
+- For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
 - In final user-facing summaries, distinguish clearly between:
+  - contract is visible / canonical shape is known
+  - plan succeeded
+  - apply landed and readback verified it
   - base template/skeleton applied
   - business-specific rules completed
   - remaining gaps or follow-up patches

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

@@ -2,6 +2,18 @@
 
 Use this when the user wants one new app inside an existing package.
 
+Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
+
+1. resolve or create the package
+2. create each app separately
+3. attach each app to the package
+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, call `package_create` before this sequence.
 
 ## Minimal sequence
@@ -13,6 +25,22 @@ If creating a brand new package would help, ask the user to confirm package crea
 5. `package_attach_app`
 6. `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_resolve` or `package_create`
+2. for each app name, run `app_schema_plan -> app_schema_apply -> package_attach_app`
+3. once the apps exist, add `relation` fields between them
+
 ## Example
 
 Create a new package only after the user confirms package creation:
@@ -110,3 +138,11 @@ The create route did not resolve in the current backend route context. Re-run `w
 ### `PACKAGE_ATTACH_FAILED`
 
 Do not retry schema creation. Re-run only `package_attach_app`, then verify with `app_read_summary`.
+
+### 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-app-builder/references/gotchas.md

@@ -11,6 +11,13 @@
 - Treat `package_attach_app` as the source of truth for package ownership
 - Check `tag_ids_after` after schema writes
 
+## 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
+
 ## Auto publish
 
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
@@ -32,6 +39,7 @@
 - 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_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 
@@ -41,6 +49,10 @@
 - 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 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.
 - 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

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

@@ -8,6 +8,17 @@ Use the smallest v2 builder tool chain that can finish the task.
 
 Use `plan` before `apply` unless the patch is trivial and already normalized.
 
+## Hierarchy first
+
+Before picking tools, decide which layer the request targets:
+
+- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package
+- `field`: one field inside one app
+- `relation`: a field that links two apps
+
+If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
+
 ## Resolve
 
 - `package_create`: create a new package only after the user confirms package creation; exact-name duplicates return `noop=true`
@@ -57,22 +68,28 @@ These execute normalized patches and publish by default unless `publish=false`.
   `package_resolve -> app_resolve -> app_schema_plan -> 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`
+- 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`
 - Update fields on an existing app:
   `app_resolve -> app_read_fields -> app_schema_plan -> app_schema_apply`
 - Tidy layout:
   `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
 - Add workflow:
-  `app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
 - Add views:
-  `app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply -> app_read_views_summary`
 
 ## Avoid
 
 - Do not handcraft raw Qingflow schema payloads
 - Do not rely on internal `solution_*` tools in public builder flows
 - Do not create a new package without first asking the user to confirm package creation
+- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
+- Do not compress multiple business objects into one app with several text fields
 - Do not skip summary reads before flow or view work
 - Do not emit `column_names`; always use `columns`
+- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
 - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
 - Do not omit assignees on approval/fill/copy nodes
+- Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first

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

@@ -4,14 +4,21 @@ Use this when the app already exists and the task is only about workflow.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. `role_search` or `member_search`
-4. `role_create` if the user wants a reusable directory role and no good role exists
-5. start from a canonical preset when possible
-6. patch the skeleton instead of freehanding a full graph
-7. `app_flow_plan`
-8. `app_flow_apply`
+1. `builder_tool_contract(tool_name="app_flow_plan")`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search`
+5. `role_create` if the user wants a reusable directory role and no good role exists
+6. start from a canonical preset when possible
+7. patch the skeleton instead of freehanding a full graph
+8. reuse preset node ids when patching:
+   - `basic_approval` -> patch `approve_1`
+   - `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
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -142,23 +149,40 @@ Only after that should you use explicit nodes:
 }
 ```
 
+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`.
+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
 
 ### `FLOW_ASSIGNEE_REQUIRED`
 
 Approval, fill, and copy nodes must declare at least one assignee.
 
+If this happens after using a preset, check for this specific mistake first:
+
+- the preset created `approve_1` or `fill_1`
+- your patch created a different node id instead of patching that preset node
+- the original preset node remained in the graph without assignees
+
 Preferred fix order:
 
 1. `role_search`
 2. `member_search` only if the user explicitly named members
 3. `role_create` if the business needs a reusable role
-4. retry `app_flow_plan` or `app_flow_apply` with canonical `assignees.*`
+4. patch the preset node id itself with canonical `assignees.*`
+5. retry `app_flow_plan` or `app_flow_apply`
 
 ### `FLOW_DEPENDENCY_MISSING`
 
 The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
 
+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`
+
 ### `INVALID_FLOW_EDGE`
 
 One or more transitions reference unknown nodes or create an invalid graph.
@@ -193,6 +217,11 @@ Do not keep guessing preset names or node shapes. First:
    - `assignees.member_names`
    - `permissions.editable_fields`
 
+Do not copy internal keys from old plan outputs or logs, including:
+
+- `role_entries`
+- `editable_que_ids`
+
 ## Notes
 
 - `mode=replace` is the only supported flow apply mode

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

@@ -4,10 +4,12 @@ Use this when the task is only about table, card, board, or gantt views.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+1. `builder_tool_contract(tool_name="app_views_plan")`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever apply returns `failed` or `partial_success`
 
 If you are unsure about keys or view types, call `builder_tool_contract(tool_name="app_views_apply")` before guessing.
 
@@ -62,6 +64,8 @@ Apply it:
 }
 ```
 
+After `app_views_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
+
 Board example:
 
 ```json
@@ -146,12 +150,14 @@ Do not repeat `app_views_apply` with guessed keys. First:
 
 1. check `suggested_next_call`
 2. reuse `canonical_arguments` if present
-3. if needed, call `builder_tool_contract`
-4. retry only the minimal failed view patch
+3. call `app_read_views_summary` to see whether any requested views landed anyway
+4. if needed, call `builder_tool_contract`
+5. retry only the minimal failed view patch
 
 ## Notes
 
 - `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
 - `column_names` should not appear in skill examples
+- `app_read_views_summary` should be treated as canonical readback and now returns `columns`
 - `filters` are ANDed together as one flat condition group
 - `app_views_apply` publishes by default

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b11"
+__version__ = "0.2.0b13"

package/src/qingflow_mcp/builder_facade/service.py

@@ -679,6 +679,58 @@ class AiBuilderFacade:
             normalized_nodes.append(normalized_node)
         return normalized_nodes, issues
 
+    def _canonicalize_flow_nodes_for_public_output(self, nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        public_nodes: list[dict[str, Any]] = []
+        for node in nodes:
+            if not isinstance(node, dict):
+                continue
+            payload = deepcopy(node)
+            assignees = payload.get("assignees") if isinstance(payload.get("assignees"), dict) else {}
+            permissions = payload.get("permissions") if isinstance(payload.get("permissions"), dict) else {}
+            public_assignees: dict[str, Any] = {}
+            role_ids = [
+                role_id
+                for role_id in (
+                    _coerce_positive_int(entry.get("roleId"))
+                    for entry in (assignees.get("role_entries") or [])
+                    if isinstance(entry, dict)
+                )
+                if role_id is not None
+            ]
+            member_uids = [
+                member_uid
+                for member_uid in (_coerce_positive_int(value) for value in (assignees.get("member_uids") or []))
+                if member_uid is not None
+            ]
+            if role_ids:
+                public_assignees["role_ids"] = role_ids
+            if member_uids:
+                public_assignees["member_uids"] = member_uids
+            if bool(assignees.get("include_sub_departs")):
+                public_assignees["include_sub_departs"] = True
+            public_permissions: dict[str, Any] = {}
+            editable_fields = [str(name) for name in (permissions.get("editable_fields") or []) if str(name or "").strip()]
+            if editable_fields:
+                public_permissions["editable_fields"] = editable_fields
+            config_payload = payload.get("config") if isinstance(payload.get("config"), dict) else {}
+            if isinstance(config_payload, dict):
+                config_payload = deepcopy(config_payload)
+                config_payload.pop("conditionFormatMatrix", None)
+            if public_assignees:
+                payload["assignees"] = public_assignees
+            else:
+                payload.pop("assignees", None)
+            if public_permissions:
+                payload["permissions"] = public_permissions
+            else:
+                payload.pop("permissions", None)
+            if config_payload:
+                payload["config"] = config_payload
+            else:
+                payload.pop("config", None)
+            public_nodes.append(payload)
+        return public_nodes
+
     def package_attach_app(
         self,
         *,
@@ -1287,7 +1339,8 @@ class AiBuilderFacade:
         if fields_result.get("status") == "failed":
             return fields_result
         current_fields = fields_result.get("fields", [])
-        nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
         if resolution_issues:
             first_issue = resolution_issues[0]
             suggested_call = None
@@ -1304,17 +1357,17 @@ class AiBuilderFacade:
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
                     "preset": request.preset.value if request.preset else None,
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"issues": resolution_issues},
                 suggested_next_call=suggested_call,
             )
         status_field_present = _infer_status_field_id(current_fields) is not None
-        node_types = {str(node.get("type") or "") for node in nodes}
+        node_types = {str(node.get("type") or "") for node in normalized_nodes}
         assignee_required_nodes = [
             node.get("id")
-            for node in nodes
+            for node in normalized_nodes
             if str(node.get("type") or "") in {"approve", "fill", "copy"}
             and not (
                 (node.get("assignees") or {}).get("role_entries")
@@ -1329,7 +1382,7 @@ class AiBuilderFacade:
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
                     "preset": request.preset.value if request.preset else None,
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
@@ -1342,7 +1395,7 @@ class AiBuilderFacade:
                 normalized_args={
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"missing_dependencies": ["status field"]},
@@ -1359,12 +1412,12 @@ class AiBuilderFacade:
                     },
                 },
             )
-        workflow = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        workflow = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
         if workflow.get("status") == "failed":
             workflow["normalized_args"] = {
                 "app_key": request.app_key,
                 "mode": str(request.mode or "replace"),
-                "nodes": nodes,
+                "nodes": public_nodes,
                 "transitions": transitions,
             }
             workflow["suggested_next_call"] = {
@@ -1373,7 +1426,7 @@ class AiBuilderFacade:
                     "profile": profile,
                     "app_key": request.app_key,
                     "mode": "replace",
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
             }
@@ -1381,7 +1434,7 @@ class AiBuilderFacade:
         normalized_args = {
             "app_key": request.app_key,
             "mode": str(request.mode or "replace"),
-            "nodes": nodes,
+            "nodes": public_nodes,
             "transitions": transitions,
         }
         return {
@@ -2030,7 +2083,9 @@ class AiBuilderFacade:
             )
         entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
         current_fields = _parse_schema(schema)["fields"]
-        nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
+        normalized_args["nodes"] = public_nodes
         if resolution_issues:
             first_issue = resolution_issues[0]
             suggested_call = None
@@ -2049,7 +2104,7 @@ class AiBuilderFacade:
             )
         assignee_required_nodes = [
             node.get("id")
-            for node in nodes
+            for node in normalized_nodes
             if str(node.get("type") or "") in {"approve", "fill", "copy"}
             and not (
                 (node.get("assignees") or {}).get("role_entries")
@@ -2064,13 +2119,13 @@ class AiBuilderFacade:
                 details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
                 suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, "keyword": ""}},
             )
-        workflow_spec = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        workflow_spec = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
         if workflow_spec.get("status") == "failed":
             workflow_spec["normalized_args"] = normalized_args
             workflow_spec.setdefault("request_id", None)
             workflow_spec["suggested_next_call"] = {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
             return workflow_spec
-        desired_node_count = len([node for node in nodes if node.get("type") != "end"])
+        desired_node_count = len([node for node in normalized_nodes if node.get("type") != "end"])
         current_workflow, _workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         current_node_count = len(_summarize_workflow_nodes(current_workflow))
         if current_node_count == desired_node_count and desired_node_count > 0:
@@ -2124,7 +2179,7 @@ class AiBuilderFacade:
                 arguments.setdefault("profile", profile)
                 arguments.setdefault("app_key", app_key)
                 arguments.setdefault("mode", mode)
-                arguments.setdefault("nodes", nodes)
+                arguments.setdefault("nodes", public_nodes)
                 arguments.setdefault("transitions", transitions)
                 suggested_next_call["arguments"] = arguments
             failed["suggested_next_call"] = suggested_next_call
@@ -2216,14 +2271,17 @@ class AiBuilderFacade:
             if isinstance(field, dict) and str(field.get("name") or "")
         }
         removed: list[str] = []
+        view_results: list[dict[str, Any]] = []
         for name in remove_views:
             key = existing_by_name.get(name)
             if key:
                 self.views.view_delete(profile=profile, viewgraph_key=key)
                 removed.append(name)
                 existing_by_name.pop(name, None)
+                view_results.append({"name": name, "type": None, "status": "removed"})
         created: list[str] = []
         updated: list[str] = []
+        failed_views: list[dict[str, Any]] = []
         existing_view_list = [
             view
             for view in (existing_views if isinstance(existing_views, list) else [])
@@ -2301,6 +2359,7 @@ class AiBuilderFacade:
                     )
                     self.views.view_update(profile=profile, viewgraph_key=existing_key, payload=payload)
                     updated.append(patch.name)
+                    view_results.append({"name": patch.name, "type": patch.type.value, "status": "updated"})
                 else:
                     template_key = _pick_view_template_key(existing_view_list, desired_type=patch.type.value)
                     if patch.type.value == "table" and template_key:
@@ -2326,9 +2385,13 @@ class AiBuilderFacade:
                         )
                         self.views.view_create(profile=profile, payload=payload)
                     created.append(patch.name)
+                    view_results.append({"name": patch.name, "type": patch.type.value, "status": "created"})
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
-                if api_error.backend_code == 48104:
+                should_retry_minimal = api_error.backend_code == 48104 or (
+                    patch.type.value == "table" and bool(patch.filters) and api_error.http_status is not None and api_error.http_status >= 500
+                )
+                if should_retry_minimal:
                     try:
                         if existing_key or created_key:
                             target_key = created_key or existing_key or ""
@@ -2342,8 +2405,14 @@ class AiBuilderFacade:
                             self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
                             if existing_key:
                                 updated.append(patch.name)
+                                view_results.append(
+                                    {"name": patch.name, "type": patch.type.value, "status": "updated", "fallback_applied": True}
+                                )
                             else:
                                 created.append(patch.name)
+                                view_results.append(
+                                    {"name": patch.name, "type": patch.type.value, "status": "created", "fallback_applied": True}
+                                )
                             continue
                         fallback_payload = _build_minimal_view_payload(
                             app_key=app_key,
@@ -2354,6 +2423,7 @@ class AiBuilderFacade:
                         )
                         self.views.view_create(profile=profile, payload=fallback_payload)
                         created.append(patch.name)
+                        view_results.append({"name": patch.name, "type": patch.type.value, "status": "created", "fallback_applied": True})
                         continue
                     except (QingflowApiError, RuntimeError) as fallback_error:
                         api_error = _coerce_api_error(fallback_error)
@@ -2362,11 +2432,17 @@ class AiBuilderFacade:
                         self.views.view_delete(profile=profile, viewgraph_key=created_key)
                     except Exception:
                         pass
-                return _failed_from_api_error(
-                    "VIEW_APPLY_FAILED",
-                    api_error,
-                    normalized_args=normalized_args,
-                    details={
+                failure_entry = {
+                    "name": patch.name,
+                    "type": patch.type.value,
+                    "status": "failed",
+                    "error_code": "VIEW_APPLY_FAILED",
+                    "message": _public_error_message("VIEW_APPLY_FAILED", api_error),
+                    "request_id": api_error.request_id,
+                    "backend_code": api_error.backend_code,
+                    "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                    "operation": "update" if existing_key or created_key else "create",
+                    "details": {
                         "app_key": app_key,
                         "view_name": patch.name,
                         "view_type": patch.type.value,
@@ -2377,12 +2453,16 @@ class AiBuilderFacade:
                         "end_field": patch.end_field,
                         "title_field": patch.title_field,
                         "operation": "update" if existing_key or created_key else "create",
+                        "transport_error": {
+                            "http_status": api_error.http_status,
+                            "backend_code": api_error.backend_code,
+                            "category": api_error.category,
+                        },
                     },
-                    suggested_next_call={
-                        "tool_name": "app_views_plan",
-                        "arguments": {"profile": profile, "app_key": app_key},
-                    },
-                )
+                }
+                failed_views.append(failure_entry)
+                view_results.append(failure_entry)
+                continue
         try:
             verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
         except (QingflowApiError, RuntimeError) as error:
@@ -2401,6 +2481,63 @@ class AiBuilderFacade:
         }
         verified = (not verified_views_unavailable) and all(name in verified_names for name in created + updated) and all(name not in verified_names for name in removed)
         noop = not created and not updated and not removed
+        if failed_views:
+            successful_changes = bool(created or updated or removed)
+            verification_by_view = []
+            for item in view_results:
+                if item.get("status") in {"created", "updated"}:
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": item.get("status"),
+                            "present_in_readback": None if verified_views_unavailable else item.get("name") in verified_names,
+                        }
+                    )
+                elif item.get("status") == "removed":
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": "removed",
+                            "present_in_readback": None if verified_views_unavailable else item.get("name") not in verified_names,
+                        }
+                    )
+                else:
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": "failed",
+                            "present_in_readback": None,
+                            "error_code": item.get("error_code"),
+                        }
+                    )
+            first_failure = failed_views[0]
+            response = {
+                "status": "partial_success" if successful_changes else "failed",
+                "error_code": "VIEW_APPLY_PARTIAL" if successful_changes else "VIEW_APPLY_FAILED",
+                "recoverable": True,
+                "message": "applied some view patches; at least one view failed" if successful_changes else "one or more view patches failed",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+                "details": {"per_view_results": view_results},
+                "request_id": first_failure.get("request_id"),
+                "suggested_next_call": {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                "backend_code": first_failure.get("backend_code"),
+                "http_status": first_failure.get("http_status"),
+                "noop": noop,
+                "verification": {
+                    "views_verified": verified,
+                    "views_read_unavailable": verified_views_unavailable,
+                    "by_view": verification_by_view,
+                },
+                "app_key": app_key,
+                "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
+                "verified": verified,
+            }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         response = {
             "status": "success" if verified else "partial_success",
             "error_code": None if not verified_views_unavailable else "VIEWS_READBACK_PENDING",
@@ -2413,9 +2550,9 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None if not verified_views_unavailable else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": noop,
-            "verification": {"views_verified": verified, "views_read_unavailable": verified_views_unavailable},
+            "verification": {"views_verified": verified, "views_read_unavailable": verified_views_unavailable, "by_view": view_results},
             "app_key": app_key,
-            "views_diff": {"created": created, "updated": updated, "removed": removed},
+            "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": verified,
         }
         return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
@@ -3487,6 +3624,11 @@ def _merge_flow_graph(
 ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     if not override_nodes and not override_transitions:
         return deepcopy(base_nodes), deepcopy(base_transitions)
+    override_nodes, override_transitions = _align_flow_preset_override_ids(
+        base_nodes=base_nodes,
+        override_nodes=override_nodes,
+        override_transitions=override_transitions,
+    )
     merged_nodes: list[dict[str, Any]] = []
     override_map = {
         str(node.get("id") or ""): deepcopy(node)
@@ -3517,6 +3659,72 @@ def _merge_flow_graph(
     return merged_nodes, merged_transitions
 
 
+def _align_flow_preset_override_ids(
+    *,
+    base_nodes: list[dict[str, Any]],
+    override_nodes: list[dict[str, Any]],
+    override_transitions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Map simple preset skeleton overrides back onto canonical preset node ids.
+
+    This keeps preset-based plans stable when the caller customizes the single
+    approval/fill/copy step semantically but forgets to reuse ids such as
+    `approve_1` or `fill_1`.
+    """
+    patchable_types = {"approve", "fill", "copy"}
+    base_by_type: dict[str, list[str]] = {}
+    override_by_type: dict[str, list[str]] = {}
+    for node in base_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            base_by_type.setdefault(node_type, []).append(node_id)
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            override_by_type.setdefault(node_type, []).append(node_id)
+    replacement_map: dict[str, str] = {}
+    for node_type in patchable_types:
+        base_ids = base_by_type.get(node_type) or []
+        override_ids = override_by_type.get(node_type) or []
+        if len(base_ids) != 1 or len(override_ids) != 1:
+            continue
+        base_id = base_ids[0]
+        override_id = override_ids[0]
+        if override_id == base_id:
+            continue
+        replacement_map[override_id] = base_id
+    if not replacement_map:
+        return deepcopy(override_nodes), deepcopy(override_transitions)
+    aligned_nodes: list[dict[str, Any]] = []
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        aligned = deepcopy(node)
+        node_id = str(aligned.get("id") or "")
+        if node_id in replacement_map:
+            aligned["id"] = replacement_map[node_id]
+        aligned_nodes.append(aligned)
+    aligned_transitions: list[dict[str, Any]] = []
+    for transition in override_transitions:
+        if not isinstance(transition, dict):
+            continue
+        aligned = deepcopy(transition)
+        source = str(aligned.get("from") or "")
+        target = str(aligned.get("to") or "")
+        if source in replacement_map:
+            aligned["from"] = replacement_map[source]
+        if target in replacement_map:
+            aligned["to"] = replacement_map[target]
+        aligned_transitions.append(aligned)
+    return aligned_nodes, aligned_transitions
+
+
 def _extract_directory_items(listed: JSONObject) -> list[dict[str, Any]]:
     if isinstance(listed.get("items"), list):
         return [item for item in listed["items"] if isinstance(item, dict)]
@@ -3694,13 +3902,20 @@ def _summarize_views(result: Any) -> list[dict[str, Any]]:
     for view in result:
         if not isinstance(view, dict):
             continue
+        name = view.get("viewgraphName") or view.get("viewName") or view.get("title")
+        view_key = view.get("viewgraphKey") or view.get("viewKey")
+        view_type = _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))
+        columns = view.get("columnNames") or view.get("columns") or []
+        group_by = view.get("groupBy") or view.get("group_by")
+        if not any((name, view_key, view_type, columns, group_by)):
+            continue
         items.append(
             {
-                "name": view.get("viewgraphName") or view.get("viewName") or view.get("title"),
-                "view_key": view.get("viewgraphKey") or view.get("viewKey"),
-                "type": view.get("viewgraphType") or view.get("type"),
-                "column_names": view.get("columnNames") or view.get("columns") or [],
-                "group_by": view.get("groupBy") or view.get("group_by"),
+                "name": name,
+                "view_key": view_key,
+                "type": view_type,
+                "columns": columns,
+                "group_by": group_by,
             }
         )
     return items
@@ -4080,6 +4295,8 @@ def _pick_view_template_key(existing_views: list[dict[str, Any]], *, desired_typ
 
 def _normalize_view_type_name(value: Any) -> str:
     normalized = str(value or "").strip().lower()
+    if not normalized:
+        return ""
     if "gantt" in normalized:
         return "gantt"
     if "board" in normalized:

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1319,6 +1319,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": [member.value for member in PublicFlowNodeType],
             "node.condition.operator": [member.value for member in FlowConditionOperator],
         },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -1396,6 +1400,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": [member.value for member in PublicFlowNodeType],
             "node.condition.operator": [member.value for member in FlowConditionOperator],
         },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -1516,6 +1524,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
         },
+        "execution_notes": [
+            "apply may return partial_success when some views land and others fail",
+            "read back app_read_views_summary after any failed or partial view apply",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",