@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

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

@@ -2,52 +2,71 @@
 
 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`
 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
+
+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_apply -> package_attach_app`
+3. once the apps exist, add `relation` fields between them
 
 ## Example
 
-Resolve the package:
+Create a new package only after the user confirms package creation:
 
 ```json
 {
-  "tool_name": "package_resolve",
+  "tool_name": "package_create",
   "arguments": {
     "profile": "default",
-    "package_name": "测试应用包"
+    "package_name": "研发项目管理"
   }
 }
 ```
 
-Plan schema for a new app:
+Resolve the package:
 
 ```json
 {
-  "tool_name": "app_schema_plan",
+  "tool_name": "package_resolve",
   "arguments": {
     "profile": "default",
-    "app_name": "客户订单",
-    "package_tag_id": 1218950,
-    "create_if_missing": 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_name": "测试应用包"
   }
 }
 ```
 
-Apply schema. This publishes by default:
+Apply schema for a new app:
 
 ```json
 {
@@ -68,6 +87,9 @@ Apply schema. This publishes by default:
     "remove_fields": []
   }
 }
+```
+  }
+}
 ```
 
 Attach explicitly if `tag_ids_after` does not yet contain the package:
@@ -96,3 +118,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,123 @@
+# Flow Actors And Permissions
+
+Use this when the workflow needs real assignees or node-level editable field permissions.
+
+## Canonical policy
+
+- Approval, fill, and copy nodes must declare at least one assignee.
+- Prefer roles over explicit members.
+- Resolve directory actors before calling `app_flow_apply`.
+- Use canonical keys only:
+  - `assignees.role_names`
+  - `assignees.role_ids`
+  - `assignees.member_names`
+  - `assignees.member_emails`
+  - `assignees.member_uids`
+  - `permissions.editable_fields`
+
+## Recommended order
+
+1. `app_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_apply`
+
+## Examples
+
+### Route an approval node to a reusable role
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "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_apply",
+  "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,11 +30,17 @@
 - 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
-- If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
+- Approval, fill, and copy nodes also require at least one assignee
+- Prefer roles over explicit members unless the user explicitly names people
+- Resolve assignees with `role_search` / `member_search` before flow apply
+- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
+- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
+- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 
 ## Retry discipline
@@ -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_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_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

@@ -6,40 +6,42 @@ 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.
 
 ## 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_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_views_plan`
+2. `app_read_views_summary`
 3. `app_views_apply`
 
+For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
+
 ## Final readback
 
 Prefer these fields after writes:

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

@@ -4,15 +4,30 @@ 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
+
+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
-- `app_resolve`: locate an existing app by `app_key` or `app_name`
+- `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 exactly one selector mode: `app_key`, or `app_name + package_tag_id`
 
 ## Summary reads
 
@@ -21,15 +36,8 @@ Use `plan` before `apply` unless the patch is trivial and already normalized.
 - `app_read_layout_summary`: sections, rows, unplaced fields
 - `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
+- `app_read_charts_summary`: current chart ids, names, types, order
+- `portal_read_summary`: current draft/live portal metadata and compact section inventory
 
 ## Apply tools
 
@@ -39,27 +47,47 @@ 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
+- `app_charts_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_tag_id + dash_name` for create mode; sections are replace-only and omission deletes old sections; `publish=false` only guarantees draft/base-info updates
 
 ## Explicit post-apply tools
 
-- `package_attach_app`: attach an app to a package; do not assume create or publish attaches it
+- `package_attach_app`: attach an app to a package with `tag_id + app_key`; do not assume create or publish attaches it
 - `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
 
 ## 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_apply -> package_attach_app`
+- Create a brand new multi-app system/package:
+  `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_layout_summary -> 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:
-  `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_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_apply -> app_read_views_summary`
+- Add QingBI charts:
+  `builder_tool_contract -> app_read_fields -> app_read_charts_summary -> app_charts_apply -> app_read_charts_summary`
+- Create or update a portal:
+  `builder_tool_contract -> portal_read_summary -> portal_apply -> portal_read_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

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

@@ -4,27 +4,31 @@ 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. `app_flow_plan`
-4. `app_flow_apply`
+1. `builder_tool_contract(tool_name="app_flow_apply")`
+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_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.
 
 ## Example
 
-Plan a simple approval flow:
+Canonical preset mapping:
 
-```json
-{
-  "tool_name": "app_flow_plan",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "preset": "basic_approval"
-  }
-}
-```
+- “默认审批/基础审批/普通审批” -> `basic_approval`
+- “先填报再审批/提交后审批” -> `basic_fill_then_approve`
 
-Or use explicit nodes:
+Apply a simple approval flow with a role assignee and node-level editable fields:
 
 ```json
 {
@@ -32,40 +36,123 @@ Or use explicit nodes:
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
-    "mode": "replace",
+    "preset": "basic_approval",
     "publish": true,
     "nodes": [
-      {"id": "start", "type": "start", "name": "发起"},
-      {"id": "approve_1", "type": "approve", "name": "审批"},
-      {"id": "end", "type": "end", "name": "结束"}
-    ],
-    "transitions": [
-      {"from": "start", "to": "approve_1"},
-      {"from": "approve_1", "to": "end"}
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "role_names": ["项目经理"]
+        },
+        "permissions": {
+          "editable_fields": ["状态", "审批意见"]
+        }
+      }
     ]
   }
 }
 ```
 
+For flexible business requirements, do not jump straight to a full custom graph. Use this safer pattern:
+
+1. build a base skeleton from a preset
+2. identify the business-specific changes
+3. patch nodes/transitions explicitly
+
+Public flow building is intentionally limited to linear workflows. Use only:
+
+- `start`
+- `approve`
+- `fill`
+- `copy`
+- `webhook`
+- `end`
+
+Do not generate `branch` or `condition` nodes through `app_flow_apply`. The backend workflow route is not front-end stable for those node types, and MCP now returns `FLOW_NODE_TYPE_UNSUPPORTED` instead of writing a visually broken flow.
+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
 
+### `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. patch the preset node id itself with canonical `assignees.*`
+5. retry `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_apply`
+
 ### `INVALID_FLOW_EDGE`
 
 One or more transitions reference unknown nodes or create an invalid graph.
 
+### `UNKNOWN_FLOW_FIELD`
+
+The workflow referenced a field name that does not exist, often in:
+
+- `permissions.editable_fields`
+
+Call `app_read_fields` and retry with the exact field names returned by the app.
+
+### `FLOW_NODE_TYPE_UNSUPPORTED`
+
+The public workflow builder only supports linear flows. Remove `branch` and `condition` nodes and redesign the flow with stable sequential nodes instead of retrying the same graph.
+
 ### `STATUS_FIELD_REQUIRED`
 
 The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
 
 ### `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`
+
+Do not keep guessing preset names or node shapes. First:
+
+1. inspect `suggested_next_call`
+2. reuse `canonical_arguments` if present
+3. check `allowed_values`
+4. retry with canonical preset or canonical node types
+5. for workflow actors and permissions, always convert to:
+   - `assignees.role_names`
+   - `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
 - `app_flow_apply` publishes by default
+- Prefer roles over explicit members unless the user explicitly asks for named members
+- `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows
+- Report results precisely:
+  - “基础流程骨架已创建” when only the preset landed
+  - “业务定制规则已补齐” only after the patch phase is complete