@qingflow-tech/qingflow-app-builder-mcp 1.0.0

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

@@ -0,0 +1,53 @@
+# 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_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_get_fields`
+3. `app_schema_apply`
+
+## Rework layout
+
+1. `app_get_layout`
+2. `app_layout_apply`
+
+Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
+
+## Add or update workflow
+
+1. `app_get_fields`
+2. `app_get_flow`
+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_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_get_fields`
+2. `app_get_views`
+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:
+
+- `app_get.tag_ids`
+- `app_get.publish_status`
+- `app_get_layout.unplaced_fields`
+- `app_get_views.views`
+- `app_get_flow.nodes`

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

@@ -0,0 +1,93 @@
+# Tool Selection
+
+Use the smallest v2 builder tool chain that can finish the task.
+
+## Default path
+
+`resolve -> summary read -> apply -> attach -> publish_verify`
+
+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
+- `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
+
+- `app_get`: overall app config health, publish state, counts, and builder editability
+- `app_get_fields`: field names, types, required flags, section ids
+- `app_get_layout`: sections, rows, unplaced fields
+- `app_get_views`: current view names, types, columns, group-by
+- `app_get_flow`: workflow enabled state, nodes, transitions
+- `app_get_charts`: current chart ids, names, types, order
+- `portal_get`: current portal config detail and component inventory
+
+## 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
+- `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 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_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_get_fields -> app_schema_apply`
+- Tidy layout:
+  `app_get_fields -> app_get_layout -> builder_tool_contract (if shape is unclear) -> app_layout_apply`
+- Add workflow:
+  `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
+- Add views:
+  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply -> app_get_views`
+- Add QingBI charts:
+  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply -> app_get_charts`
+- Create or update a portal:
+  `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
+
+## 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,158 @@
+# 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_apply")`
+2. `app_get_fields`
+3. `app_get_flow`
+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_get_flow` 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`
+
+Apply a simple approval flow with a role assignee and node-level editable fields:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval",
+    "publish": true,
+    "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
+
+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_get_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_get_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_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

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

@@ -0,0 +1,68 @@
+# Update Layout
+
+Use this when fields already exist and the task is only about form grouping or ordering.
+
+## Minimal sequence
+
+1. `app_get_fields`
+2. `app_get_layout`
+3. `builder_tool_contract` when the section shape is not already obvious
+4. `app_layout_apply`
+
+## Example
+
+Apply a custom layout with the canonical public section shape:
+
+```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_get_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_get_layout`. 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_apply)`.
+
+## 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

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

@@ -0,0 +1,68 @@
+# Update Schema
+
+Use this when the app already exists and the task is only about fields.
+
+## Minimal sequence
+
+1. `app_resolve`
+2. `app_get_fields`
+3. `app_schema_apply`
+
+## Example
+
+Read current fields first:
+
+```json
+{
+  "tool_name": "app_get_fields",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123"
+  }
+}
+```
+
+Apply the patch:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "add_fields": [
+      {"name": "跟进日期", "type": "date"}
+    ],
+    "update_fields": [
+      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
+    ],
+    "remove_fields": [
+      {"name": "旧字段"}
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `FIELD_NOT_FOUND`
+
+The selector did not match current schema. Re-read with `app_get_fields` and use `name`, `field_id`, or `que_id`.
+
+### `DUPLICATE_FIELD`
+
+The field already exists with a different shape. Switch from `add_fields` to `update_fields`.
+
+### `SCHEMA_APPLY_FAILED`
+
+Treat it as uncertain write state. Read back with `app_get_fields` before retrying.
+
+## Notes
+
+- `title` and `label` are accepted aliases for `name`
+- `textarea -> long_text`
+- `currency -> amount`
+- `mobile -> phone`
+- `select/radio -> single_select`
+- `checkbox -> multi_select`

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

@@ -0,0 +1,162 @@
+# Update Views
+
+Use this when the task is only about table, card, board, or gantt views.
+
+## Minimal sequence
+
+1. `builder_tool_contract(tool_name="app_views_apply")`
+2. `app_get_fields`
+3. `app_get_views`
+4. `app_views_apply`
+5. `app_get_views` again whenever apply returns `failed` or `partial_success`
+
+If you are unsure about keys or view types, call `builder_tool_contract(tool_name="app_views_apply")` before guessing.
+
+Important verification rule:
+
+- `app_views_apply` can create a view object before every filter is fully verified in readback
+- Do not report “筛选已成功应用” unless the apply result also shows `verification.views_verified=true`
+- If apply returns `partial_success`, inspect `verification.by_view` and `details.filter_mismatches` before claiming the filters are active
+
+## Example
+
+Canonical rules before any example:
+
+- Always use `columns`
+- Do not emit `column_names`
+- Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
+- Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
+- For gantt, use `start_field`, `end_field`, and optionally `title_field`
+- If `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
+
+Apply a default table view:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "全部订单",
+        "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
+        "type": "table",
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+After `app_views_apply` returns canonical arguments or blocking issues, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
+
+Board example:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "按状态看板",
+        "type": "board",
+        "group_by": "状态",
+        "columns": ["订单编号", "客户名称", "订单金额"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+Gantt example with filters:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "项目甘特图",
+        "type": "gantt",
+        "columns": ["项目名称", "开始日期", "结束日期", "状态"],
+        "start_field": "开始日期",
+        "end_field": "结束日期",
+        "title_field": "项目名称",
+        "filters": [
+          {
+            "field_name": "状态",
+            "operator": "eq",
+            "value": "进行中"
+          }
+        ]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+## Common failures
+
+### `UNKNOWN_VIEW_FIELD`
+
+At least one `columns` or `group_by` field name does not exist.
+
+### `INVALID_VIEW_TYPE`
+
+Public view types are only `table`, `card`, `board`, `gantt`.
+
+Map old or intuitive labels before calling the tool:
+
+- `tableView` -> `table`
+- `cardView` -> `card`
+- `kanban` -> `board`
+
+### `INVALID_GANTT_CONFIG`
+
+Gantt views require at least:
+
+- `start_field`
+- `end_field`
+
+Also make sure these field names already exist on the app.
+
+### `VIEW_APPLY_FAILED`
+
+The backend rejected the normalized view payload. Re-read fields and inspect `request_id` before retrying.
+
+Do not repeat `app_views_apply` with guessed keys. First:
+
+1. check `suggested_next_call`
+2. reuse `canonical_arguments` if present
+3. call `app_get_views` to see whether any requested views landed anyway
+4. if needed, call `builder_tool_contract`
+5. retry only the minimal failed view patch
+
+### `VIEW_FILTER_READBACK_MISMATCH`
+
+The view object was created or updated, but the readback config did not keep the intended filter values.
+
+Treat this as:
+
+- the view exists
+- the filter is **not yet verified**
+
+Do not tell the user the filter is active until the readback verification matches the intended filter.
+
+## Notes
+
+- `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
+- `column_names` should not appear in skill examples
+- `app_get_views` should be treated as canonical readback and now returns `columns`
+- If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_get_views`; then retry with the exact `view_key`
+- `filters` are ANDed together as one flat condition group
+- `app_views_apply` publishes by default
+- For select-style filters, success means the backend preserved the option value in readback, not just that the view name now exists