@josephyan/qingflow-app-builder-mcp 0.2.0-beta.3 → 0.2.0-beta.30

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.3
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.30
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.3 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.30 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -20,7 +20,7 @@ Environment:
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-builder-mcp` stdio MCP server.
 
-Bundled skill:
+Bundled skills:
 
 - `skills/qingflow-app-builder`
 

package/package.json

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

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

@@ -17,11 +17,34 @@ 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`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
+- 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`
+- 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`
 - Publish and verify: `app_publish_verify`
 
 Note:
@@ -29,11 +52,23 @@ Note:
 - 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`.
 - `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.
+- 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:
+  - “默认审批/基础审批/普通审批” -> `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
+  - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
+- On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
 
 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.
-- Do not create a new package unless the user explicitly asks for package separation.
+- 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
 
@@ -45,16 +80,50 @@ Before any business tool:
 
 For builder work:
 
-1. Resolve the target package with `package_resolve` when the user gives a package name. If resolution is ambiguous or you need a read-only fallback, use `package_list`.
-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 list/card/board 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.
+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. 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. `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. `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`
+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.
 
@@ -70,10 +139,32 @@ 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.
+- 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`.
+- 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.
+- 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.
 
 ## Response Interpretation
 
@@ -81,11 +172,24 @@ 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.
+- For views, “view exists” is not the same as “filters are active”. If `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, report the view as created but the filters as unverified until readback confirms them.
+- 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 landed and readback verified it
+  - base template/skeleton applied
+  - business-specific rules completed
+  - remaining gaps or follow-up patches
+- Do not report “流程已满足业务需求” when only a preset skeleton has landed.
 
 ## Practical Patterns
 
 - List packages: `package_list`
 - Resolve one package: `package_resolve`
+- Create one package: `package_create`
+- Read one public tool contract: `builder_tool_contract`
 - Resolve one app: `app_resolve`
 - Read one app summary: `app_read_summary`
 - Read fields only: `app_read_fields`
@@ -96,11 +200,15 @@ For additive work on existing systems:
 - 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`
 - Add/update/remove fields: `app_schema_apply`
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
 - Upsert/remove views: `app_views_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
 
 Detailed playbooks:
@@ -112,5 +220,6 @@ Detailed playbooks:
 - Update fields only: [references/update-schema.md](references/update-schema.md)
 - Update layout only: [references/update-layout.md](references/update-layout.md)
 - Update workflow only: [references/update-flow.md](references/update-flow.md)
+- Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
 - Update views only: [references/update-views.md](references/update-views.md)
 - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)

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

@@ -2,6 +2,20 @@
 
 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
 
 1. `package_resolve`
@@ -11,8 +25,36 @@ Use this when the user wants one new app inside an existing package.
 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:
+
+```json
+{
+  "tool_name": "package_create",
+  "arguments": {
+    "profile": "default",
+    "package_name": "研发项目管理"
+  }
+}
+```
+
 Resolve the package:
 
 ```json
@@ -96,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/environments.md

@@ -43,7 +43,7 @@ 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
-- do not create a new package unless the user explicitly wants package separation
+- 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
 

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

@@ -0,0 +1,124 @@
+# 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_plan` or `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_read_fields`
+2. `app_read_flow_summary`
+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`
+
+## Examples
+
+### Route an approval node to a reusable role
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "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
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval",
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "member_names": ["严琪东", "张三"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Let one node edit selected fields only
+
+```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"}
+    ]
+  }
+}
+```
+
+## 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_read_fields`
+- only pass real current field names to `permissions.editable_fields`

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
@@ -23,10 +30,16 @@
 - Use `app_read_fields` before schema or view work
 - Use `app_read_layout_summary` before layout work
 - Use `app_read_flow_summary` before workflow work
+- Use `app_read_views_summary` before view work
 
 ## 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_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 
@@ -35,3 +48,17 @@
 - 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 `builder_tool_contract(app_layout_plan)`.
+- 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 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 MCP arguments. First convert them to a preset or explicit patch plan.

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

@@ -29,16 +29,23 @@ Prefer `mode=merge`. Use `mode=replace` only when every field placement is inten
 ## Add or update workflow
 
 1. `app_read_fields`
-2. `app_flow_plan`
-3. `app_flow_apply`
+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`
 
 If `app_flow_plan` 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_views_plan`
-3. `app_views_apply`
+2. `app_read_views_summary`
+3. `app_views_plan`
+4. `app_views_apply`
+
+For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
 
 ## Final readback
 

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

@@ -8,10 +8,25 @@ 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`
 - `package_resolve`: exact package lookup by name
 - `package_list`: read-only fallback when package resolution is ambiguous
+- `member_search`: resolve named people from the directory
+- `role_search`: resolve reusable roles from the directory
+- `role_create`: create a reusable role when the business owner wants role-based routing
 - `app_resolve`: locate an existing app by `app_key` or `app_name`
 
 ## Summary reads
@@ -31,6 +46,8 @@ Use these when the patch is non-trivial or the model is likely to drift.
 - `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`.
@@ -49,17 +66,31 @@ These execute normalized patches and publish by default unless `publish=false`.
 
 - Create one app inside an existing package:
   `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`
+  `app_read_fields -> app_read_layout_summary -> builder_tool_contract (if shape is unclear) -> app_layout_plan -> app_layout_apply`
 - Add workflow:
-  `app_read_fields -> 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_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 unless the user explicitly asks for package separation
+- 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 model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
+- 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