@josephyan/qingflow-app-builder-mcp 0.2.0-beta.12 → 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.12
+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.12 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.12",
+  "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.0b12"
+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`
@@ -45,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
 
@@ -57,16 +81,19 @@ 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:
 
@@ -86,13 +113,17 @@ For flow work, keep the order strict:
 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. Declare approver/fill/copy assignees explicitly:
+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`
-9. When a node must edit specific fields, declare `permissions.editable_fields`
-10. `app_flow_plan`
-11. `app_flow_apply`
-12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
+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.
 
@@ -109,9 +140,11 @@ 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`
@@ -123,6 +156,7 @@ For additive work on existing systems:
 - `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.
 

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
 

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,6 +68,8 @@ 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:
@@ -71,9 +84,12 @@ These execute normalized patches and publish by default unless `publish=false`.
 - 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

@@ -11,9 +11,14 @@ Use this when the app already exists and the task is only about workflow.
 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. `app_flow_plan`
-9. `app_flow_apply`
-10. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
+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.
 
@@ -145,6 +150,7 @@ 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
 
@@ -152,12 +158,19 @@ After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.argument
 
 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`
 

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/service.py

@@ -3624,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)
@@ -3654,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)]