@josephyan/qingflow-app-builder-mcp 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -0,0 +1,64 @@
+# Builder Gotchas
+
+## Auth and workspace
+
+- `auth_*` success does not mean a workspace is selected
+- Re-run `workspace_select` after auth changes or route changes
+
+## Package ownership
+
+- App creation and publish do not guarantee package attachment
+- 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
+- Pass `publish=false` only when the user explicitly wants to leave changes in draft
+- `app_publish_verify` is for explicit final verification, not the default next step after every write
+
+## Readback scope
+
+- Prefer summary reads over large raw payloads
+- 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
+
+## Retry discipline
+
+- 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

@@ -0,0 +1,58 @@
+# Builder Playbooks
+
+Use these when you need a quick reminder of the standard v2 builder sequences.
+
+## Create a new app in an existing package
+
+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
+
+## Update fields on an existing app
+
+1. `app_resolve`
+2. `app_read_fields`
+3. `app_schema_plan`
+4. `app_schema_apply`
+
+## Rework layout
+
+1. `app_read_layout_summary`
+2. `app_layout_plan`
+3. `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_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_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
+
+Prefer these fields after writes:
+
+- `app_read_summary.tag_ids`
+- `app_read_summary.publish_status`
+- `app_read_layout_summary.unplaced_fields`
+- `app_read_views_summary.views`
+- `app_read_flow_summary.nodes`

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

@@ -0,0 +1,96 @@
+# Tool Selection
+
+Use the smallest v2 builder tool chain that can finish the task.
+
+## Default path
+
+`resolve -> summary read -> plan -> apply -> attach -> publish_verify`
+
+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
+
+- `app_read_summary`: overall app health, publish state, counts
+- `app_read_fields`: field names, types, required flags, section ids
+- `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
+
+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`.
+
+- `app_schema_apply`: create app shell or change fields
+- `app_layout_apply`: merge or replace layout
+- `app_flow_apply`: replace workflow
+- `app_views_apply`: upsert or remove views
+
+## Explicit post-apply tools
+
+- `package_attach_app`: attach an app to a package; 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`
+- 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_fields -> app_read_layout_summary -> builder_tool_contract (if shape is unclear) -> app_layout_plan -> app_layout_apply`
+- Add workflow:
+  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
+- Add views:
+  `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 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

@@ -0,0 +1,233 @@
+# Update Flow
+
+Use this when the app already exists and the task is only about workflow.
+
+## Minimal sequence
+
+1. `builder_tool_contract(tool_name="app_flow_plan")`
+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.
+
+## Example
+
+Canonical preset mapping:
+
+- “默认审批/基础审批/普通审批” -> `basic_approval`
+- “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+
+Plan a simple approval flow with a role assignee and node-level editable fields:
+
+```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": ["项目经理"]
+        },
+        "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
+
+For branch flows, keep the public shape canonical:
+
+1. add a `branch` node
+2. add one or more `condition` nodes as branch lanes
+3. put filter rules on the `condition` nodes with `conditions` or `condition_groups`
+4. use an empty `condition` node as the default branch when needed
+
+Canonical branch example:
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "replace",
+    "nodes": [
+      {"id": "start", "type": "start", "name": "发起"},
+      {"id": "route", "type": "branch", "name": "金额分支"},
+      {
+        "id": "high_amount",
+        "type": "condition",
+        "name": "金额大于等于一万",
+        "conditions": [
+          {"field_name": "预计金额", "operator": "gte", "value": 10000}
+        ]
+      },
+      {
+        "id": "approve_finance",
+        "type": "approve",
+        "name": "财务审批",
+        "assignees": {"role_names": ["财务负责人"]}
+      },
+      {"id": "default_lane", "type": "condition", "name": "其他情况"},
+      {
+        "id": "approve_manager",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {"role_names": ["项目经理"]}
+      },
+      {"id": "end", "type": "end", "name": "结束"}
+    ],
+    "transitions": [
+      {"from": "start", "to": "route"},
+      {"from": "route", "to": "high_amount"},
+      {"from": "high_amount", "to": "approve_finance"},
+      {"from": "route", "to": "default_lane"},
+      {"from": "default_lane", "to": "approve_manager"},
+      {"from": "approve_finance", "to": "end"},
+      {"from": "approve_manager", "to": "end"}
+    ]
+  }
+}
+```
+
+Only after that should you use explicit nodes:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+        "profile": "default",
+        "app_key": "APP_123",
+        "mode": "replace",
+        "publish": true,
+        "nodes": [
+          {"id": "start", "type": "start", "name": "发起"},
+          {
+            "id": "approve_1",
+            "type": "approve",
+            "name": "部门审批",
+            "assignees": {
+              "role_names": ["项目经理"]
+            },
+            "permissions": {
+              "editable_fields": ["状态", "审批意见"]
+            }
+          },
+          {"id": "end", "type": "end", "name": "结束"}
+        ],
+        "transitions": [
+          {"from": "start", "to": "approve_1"},
+          {"from": "approve_1", "to": "end"}
+        ]
+      }
+}
+```
+
+After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+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_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.
+
+### `UNKNOWN_FLOW_FIELD`
+
+The workflow referenced a field name that does not exist, often in:
+
+- `permissions.editable_fields`
+- branch `conditions`
+
+Call `app_read_fields` and retry with the exact field names returned by the app.
+
+### `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.
+
+### `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

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

@@ -0,0 +1,91 @@
+# Update Layout
+
+Use this when fields already exist and the task is only about form grouping or ordering.
+
+## Minimal sequence
+
+1. `app_read_fields`
+2. `app_read_layout_summary`
+3. `builder_tool_contract` when the section shape is not already obvious
+4. `app_layout_plan`
+5. `app_layout_apply`
+
+## Example
+
+Plan a custom layout with the canonical public section shape:
+
+```json
+{
+  "tool_name": "app_layout_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "merge",
+    "sections": [
+      {
+        "title": "基础信息",
+        "rows": [
+          ["客户名称", "订单金额"],
+          ["状态", "跟进日期"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+Apply the layout. This publishes by default:
+
+```json
+{
+  "tool_name": "app_layout_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "merge",
+    "publish": true,
+    "sections": [
+      {
+        "title": "基础信息",
+        "rows": [
+          ["客户名称", "订单金额"],
+          ["状态", "跟进日期"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `UNKNOWN_LAYOUT_FIELD`
+
+At least one field name does not exist. Re-read with `app_read_fields`.
+
+### `DUPLICATE_LAYOUT_FIELD`
+
+The same field appears more than once in the requested layout.
+
+### `INCOMPLETE_LAYOUT`
+
+Only happens in `mode=replace`. Switch to `mode=merge` unless you intend to place every field exactly once.
+
+### `LAYOUT_APPLY_FAILED`
+
+Re-read with `app_read_layout_summary`. Check `current_field_names`, `request_id`, and `suggested_next_call`.
+
+### `VALIDATION_ERROR`
+
+Do not keep guessing section keys. Reuse `suggested_next_call`, `canonical_arguments`, `section_allowed_keys`, and `minimal_section_example`.
+
+If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_plan)`.
+
+## Notes
+
+- `section_id` is optional; it is generated from the section title
+- `merge` is safer than `replace`
+- Unmentioned fields stay in place or get auto-added to `未分组字段`
+- Public builder layout sections use `title + rows`
+- Do not treat “一行四个字段 / 四列布局 / 每行放四个” as a top-level `columns` parameter; translate it into a `rows` matrix
+- Do not prefer `fields` or `field_ids` once `rows` is known, even though MCP may normalize those shorthands for recovery