@josephyan/qingflow-app-user-mcp 1.0.9 → 1.1.2

package/skills/qingflow-app-builder/references/build-single-app.md

@@ -0,0 +1,530 @@
+# Build Single App（单应用完整搭建）
+
+Use this when the user wants to set up one Qingflow app end-to-end: a rich field schema, grouped layout, approval flow, multiple view types, custom action buttons, in-app charts, associated reports on views, and sample data.
+
+**Signal phrases**: "创建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX表单"、"我需要一个管理XX的应用"
+
+For a multi-app system with cross-app relations and a portal dashboard, use [build-complete-system.md](./build-complete-system.md) instead.
+
+---
+
+## Execution order (never reorder)
+
+```
+Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 → Phase 8 → Phase 9
+ Package   Schema   Layout    Flow      Views    Buttons   Charts  Assoc.   Data    Verify
+                                                                   Res.
+```
+
+- Phase 4 (views) must complete before Phase 7 (associated resources) — `view_key` values must be known first
+- Phase 6 (charts) must complete before Phase 7 (associated resources) — `chart_id`/`chart_key` values must be known first
+- Phase 8 (data) runs after all config phases — fields, flow, and views must be live
+
+---
+
+## Phase 0 — Scan workspace packages
+
+```json
+{"tool_name": "package_list", "arguments": {"profile": "default"}}
+```
+
+- **Package name exists in workspace** → tell the user, wait for explicit confirmation before adding the app into it
+- **Package name not in workspace** → create immediately, no confirmation needed:
+
+```json
+{
+  "tool_name": "package_apply",
+  "arguments": {
+    "profile": "default",
+    "package_name": "合同管理",
+    "create_if_missing": true
+  }
+}
+```
+
+Record the returned `package_id`. All subsequent phases use it.
+
+---
+
+## Phase 1 — Schema (15–20 fields)
+
+> **Read first**: [update-schema.md](./update-schema.md)
+
+### Field type distribution
+
+| Type | Count | Examples |
+|------|-------|---------|
+| `text` | 2–3 | 名称、编号、联系人 |
+| `long_text` | 1–2 | 描述、摘要、备注 |
+| `single_select` | 2–3 | 状态、类型、优先级 |
+| `multi_select` | 1–2 | 标签、关联业务线 |
+| `date` / `datetime` | 2–3 | 签署日期、生效日期、到期日期 |
+| `amount` | 1–2 | 合同金额、已付金额 |
+| `number` | 1–2 | 期限（月）、完成率（%） |
+| `member` | 2 | 负责人、审核人 |
+| `department` | 0–1 | 所属部门 |
+| `phone` | 0–1 | 联系电话 |
+| `attachment` | 1 | 附件（`as_data_cover: true` for cover display） |
+
+### Hard rules
+
+- Exactly one field must have `as_data_title: true`
+- `as_data_cover: true` requires `type: attachment`
+- No `relation` fields in a single-app build — use [build-complete-system.md](./build-complete-system.md) if cross-app links are needed
+- `single_select`/`multi_select` fields must include an `options` array
+
+### Example — 合同管理
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "apps": [
+      {
+        "client_key": "contract",
+        "app_name": "合同",
+        "add_fields": [
+          {"name": "合同名称", "type": "text", "required": true, "as_data_title": true},
+          {"name": "合同编号", "type": "text"},
+          {"name": "合同类型", "type": "single_select", "options": ["服务合同", "采购合同", "劳务合同", "保密协议", "其他"]},
+          {"name": "合同状态", "type": "single_select", "options": ["草稿", "审批中", "已生效", "已到期", "已终止"]},
+          {"name": "优先级", "type": "single_select", "options": ["高", "中", "低"]},
+          {"name": "合同标签", "type": "multi_select", "options": ["重点客户", "续签", "新签", "框架协议"]},
+          {"name": "签署日期", "type": "date"},
+          {"name": "生效日期", "type": "date"},
+          {"name": "到期日期", "type": "date"},
+          {"name": "合同金额", "type": "amount"},
+          {"name": "已付金额", "type": "amount"},
+          {"name": "付款比例", "type": "number"},
+          {"name": "合同期限（月）", "type": "number"},
+          {"name": "负责人", "type": "member"},
+          {"name": "法务审核人", "type": "member"},
+          {"name": "所属部门", "type": "department"},
+          {"name": "甲方联系人", "type": "text"},
+          {"name": "甲方联系电话", "type": "phone"},
+          {"name": "合同内容摘要", "type": "long_text"},
+          {"name": "合同附件", "type": "attachment", "as_data_cover": true}
+        ]
+      }
+    ]
+  }
+}
+```
+
+Record the returned `app_key`. All subsequent phases use it.
+
+---
+
+## Phase 2 — Layout
+
+> **Read first**: [update-layout.md](./update-layout.md)
+
+Group fields into 3–4 logical sections with 2–3 fields per row.
+
+```json
+{
+  "tool_name": "app_layout_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "mode": "merge",
+    "publish": true,
+    "sections": [
+      {
+        "title": "基础信息",
+        "rows": [
+          ["合同名称", "合同编号"],
+          ["合同类型", "合同状态"],
+          ["优先级", "合同标签"]
+        ]
+      },
+      {
+        "title": "时间与金额",
+        "rows": [
+          ["签署日期", "生效日期", "到期日期"],
+          ["合同金额", "已付金额"],
+          ["付款比例", "合同期限（月）"]
+        ]
+      },
+      {
+        "title": "责任人",
+        "rows": [
+          ["负责人", "法务审核人"],
+          ["所属部门"]
+        ]
+      },
+      {
+        "title": "对方信息与附件",
+        "rows": [
+          ["甲方联系人", "甲方联系电话"],
+          ["合同内容摘要"],
+          ["合同附件"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 3 — Flow
+
+> **Read first**: [update-flow.md](./update-flow.md) and [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
+
+Search for roles first; create only if none fits:
+
+```json
+{"tool_name": "role_search", "arguments": {"profile": "default", "query": "法务"}}
+```
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "preset": "basic_approval",
+    "publish": true,
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "法务审核",
+        "assignees": {"role_names": ["法务"]},
+        "permissions": {"editable_fields": ["合同状态", "合同内容摘要"]}
+      },
+      {
+        "id": "approve_2",
+        "type": "approve",
+        "name": "负责人确认",
+        "assignees": {"role_names": ["部门主管"]},
+        "permissions": {"editable_fields": ["合同状态"]}
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 4 — Views (multiple types)
+
+> **Read first**: [update-views.md](./update-views.md)
+
+Build all applicable view types in one call. All views require `query_conditions` with `enabled: true`.
+
+| Type | Build condition | Key config |
+|------|----------------|------------|
+| **table** | Always — build first | `columns` covering title/status/date/amount/member |
+| **board** | App has a `single_select` status or stage field | `group_by` = that field name |
+| **gantt** | App has 2+ date fields | `start_field` + `end_field` |
+| **card** | App has `attachment` with `as_data_cover: true` | Visual browsing |
+| **calendar** | App has a key due/expiry date field | `date_field` = that field name |
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "全部合同",
+        "type": "table",
+        "columns": ["合同名称", "合同编号", "合同类型", "合同状态", "合同金额", "负责人", "签署日期", "到期日期"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同类型"], ["合同状态", "负责人"], ["签署日期", "到期日期"]]
+        }
+      },
+      {
+        "name": "合同看板",
+        "type": "board",
+        "columns": ["合同名称", "合同类型", "合同金额", "负责人", "到期日期"],
+        "group_by": "合同状态",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "负责人"]]
+        }
+      },
+      {
+        "name": "合同甘特图",
+        "type": "gantt",
+        "columns": ["合同名称", "合同状态", "负责人", "合同金额"],
+        "start_field": "生效日期",
+        "end_field": "到期日期",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      },
+      {
+        "name": "合同卡片",
+        "type": "card",
+        "columns": ["合同名称", "合同类型", "合同状态", "合同金额", "到期日期"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      },
+      {
+        "name": "到期日历",
+        "type": "calendar",
+        "columns": ["合同名称", "合同类型", "合同金额", "负责人"],
+        "date_field": "到期日期",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      }
+    ]
+  }
+}
+```
+
+Record all `view_key` values before Phase 7.
+
+---
+
+## Phase 5 — Custom Buttons
+
+> Call `builder_tool_contract(tool="app_custom_buttons_apply")` if the exact button schema is unclear.
+> `app_custom_buttons_apply` publishes automatically — do **not** pass `publish`.
+
+Build 2–3 buttons. Common patterns for a single app:
+
+| Button | Trigger type | Placement | When to use |
+|--------|-------------|-----------|-------------|
+| 快捷创建子记录 | `add_data` | header, detail | When a related app exists in the same package |
+| 外部跳转 | `link` | header, list | Always applicable — jump to external URL or doc |
+| 列表行操作 | `add_data` / `link` | list | Row-level quick action in table view |
+
+**Example — link button (always applicable) + add-data button (requires a related app):**
+
+```json
+{
+  "tool_name": "app_custom_buttons_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_buttons": [
+      {
+        "name": "查看合同模板",
+        "trigger_type": "link",
+        "style": "default",
+        "placements": ["header", "detail"],
+        "trigger_link_config": {
+          "url": "https://your-template-url"
+        }
+      },
+      {
+        "name": "发起变更申请",
+        "trigger_type": "add_data",
+        "style": "primary",
+        "placements": ["header", "detail", "list"],
+        "trigger_add_data_config": {
+          "target_app_key": "CHANGE_REQUEST_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联合同"},
+            {"source_field": "合同名称", "target_field": "合同标题"},
+            {"source_field": "负责人", "target_field": "申请人"}
+          ]
+        }
+      }
+    ],
+    "view_configs": [
+      {
+        "view_key": "TABLE_VIEW_KEY",
+        "mode": "merge",
+        "buttons": ["发起变更申请", "查看合同模板"]
+      }
+    ]
+  }
+}
+```
+
+**Notes:**
+- `placements: ["list"]` maps to the backend row-level `INSIDE` position
+- `view_configs[].buttons` is required in merge mode — do not send a view config with only `view_key`
+- `source_field: "数据ID"` passes the current record's ID to the target relation field
+- If this app has no related app, skip the add-data button and use the link button only
+- Use raw `view_key` from `app_get.views[].view_key`; do not prefix with `custom:`
+
+---
+
+## Phase 6 — Charts
+
+> `app_charts_apply` is immediate-live — no publish step. Record all returned `chart_id`/`chart_key` values before Phase 7.
+
+Build 2–4 charts: 2 indicator cards + 1 distribution chart + 1 trend chart.
+
+```json
+{
+  "tool_name": "app_charts_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_charts": [
+      {
+        "name": "合同总金额",
+        "chart_type": "target",
+        "config": {
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      },
+      {
+        "name": "有效合同数",
+        "chart_type": "target",
+        "config": {
+          "filter": {"合同状态": ["已生效"]},
+          "aggregate": "COUNT"
+        }
+      },
+      {
+        "name": "合同状态分布",
+        "chart_type": "columnar",
+        "config": {
+          "dimension_field": "合同状态",
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      },
+      {
+        "name": "月度签约趋势",
+        "chart_type": "area",
+        "config": {
+          "dimension_field": "签署日期",
+          "time_granularity": "month",
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 7 — Associated Resources
+
+Attach charts to the app's view area so users can see them inline without leaving the app.
+
+Before running `upsert_resources`, check existing resources with the dedicated read tool:
+
+```json
+{"tool_name": "app_get_associated_resources", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+If the result already contains the target chart, use `patch_resources` with its `associated_item_id` instead of re-upserting.
+
+```json
+{
+  "tool_name": "app_associated_resources_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_resources": [
+      {
+        "client_key": "res_status_chart",
+        "resource_type": "chart",
+        "chart_key": "CHART_KEY_FOR_STATUS_DISTRIBUTION",
+        "display_name": "合同状态分布"
+      },
+      {
+        "client_key": "res_trend_chart",
+        "resource_type": "chart",
+        "chart_key": "CHART_KEY_FOR_TREND",
+        "display_name": "月度签约趋势"
+      }
+    ],
+    "view_configs": [
+      {
+        "view_key": "TABLE_VIEW_KEY",
+        "associated_item_refs": ["res_status_chart", "res_trend_chart"]
+      }
+    ]
+  }
+}
+```
+
+**Notes:**
+- `app_associated_resources_apply` publishes automatically — do **not** pass `publish`
+- `client_key` is a same-call alias only; repeated `upsert_resources` without `associated_item_id` creates duplicates
+- On subsequent edits, use `patch_resources` with `associated_item_id` instead
+
+---
+
+## Phase 8 — Sample Data
+
+> **Hand off to `qingflow-record-insert` skill**. Read the record-insert skill docs before inserting.
+
+Insert **5–8 records** covering all status values and realistic amounts. Call `record_insert_schema_get` first.
+
+```json
+{"tool_name": "record_insert_schema_get", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+```json
+{
+  "tool_name": "record_insert",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "items": [
+      {"合同名称": "上海科技服务协议", "合同编号": "HT-2024-001", "合同类型": "服务合同", "合同状态": "已生效", "合同金额": 580000, "已付金额": 290000, "负责人": "张三", "签署日期": "2024-01-15", "生效日期": "2024-02-01", "到期日期": "2025-01-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "北京采购框架合同", "合同编号": "HT-2024-002", "合同类型": "采购合同", "合同状态": "审批中", "合同金额": 1200000, "已付金额": 0, "负责人": "李四", "签署日期": "2024-03-10", "生效日期": "2024-04-01", "到期日期": "2025-03-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "广州运维服务合同", "合同编号": "HT-2024-003", "合同类型": "服务合同", "合同状态": "已生效", "合同金额": 240000, "已付金额": 120000, "负责人": "王五", "签署日期": "2024-02-20", "生效日期": "2024-03-01", "到期日期": "2024-12-31", "优先级": "中", "合同期限（月）": 10},
+      {"合同名称": "深圳保密协议", "合同编号": "HT-2024-004", "合同类型": "保密协议", "合同状态": "已生效", "合同金额": 0, "已付金额": 0, "负责人": "张三", "签署日期": "2024-04-05", "生效日期": "2024-04-05", "到期日期": "2027-04-04", "优先级": "中", "合同期限（月）": 36},
+      {"合同名称": "杭州合作开发合同", "合同编号": "HT-2024-005", "合同类型": "服务合同", "合同状态": "草稿", "合同金额": 850000, "已付金额": 0, "负责人": "李四", "签署日期": "2024-05-01", "生效日期": "2024-06-01", "到期日期": "2025-05-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "成都劳务外包合同", "合同编号": "HT-2023-006", "合同类型": "劳务合同", "合同状态": "已到期", "合同金额": 360000, "已付金额": 360000, "负责人": "王五", "签署日期": "2023-01-01", "生效日期": "2023-01-01", "到期日期": "2023-12-31", "优先级": "低", "合同期限（月）": 12}
+    ]
+  }
+}
+```
+
+Member and department fields accept natural language values — do not look up IDs manually.
+
+---
+
+## Phase 9 — Publish Verify
+
+```json
+{"tool_name": "app_publish_verify", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+Confirm `publish_status` is live and `unplaced_fields` is empty. If `unplaced_fields` is non-empty, run `app_layout_apply` to place them before reporting completion.
+
+---
+
+## Common failures
+
+| Error | Phase | Fix |
+|-------|-------|-----|
+| `VALIDATION_ERROR` on select field | 1 | `single_select`/`multi_select` must include `options` array |
+| `UNKNOWN_LAYOUT_FIELD` | 2 | Re-read with `app_get_fields`; field name in `rows` must match exactly |
+| `FLOW_ASSIGNEE_REQUIRED` | 3 | Run `role_search` first; every approve/fill node must have at least one assignee |
+| View `partial_success` | 4 | Check `verification.view_query_conditions_verified`; read `views_diff.failed` |
+| `calendar` view rejected | 4 | Build calendar only when a date field exists; verify field type |
+| Button `view_configs` blocked | 5 | `buttons` array is required in merge mode; do not send a view config with only `view_key` |
+| Button add-data fails — no related app | 5 | Skip add-data button; use link button only |
+| Chart config rejected | 6 | Call `builder_tool_contract(tool="app_charts_apply")` for exact field/aggregate schema |
+| Associated resource duplicate | 7 | Check `app_get.associated_resources` first; use `patch_resources` with `associated_item_id` if already exists |
+| `unplaced_fields` non-empty on verify | 9 | Run `app_layout_apply` to place the missing fields, then re-verify |

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

@@ -0,0 +1,149 @@
+# Create App
+
+Use this when the user wants one new app inside an existing package.
+This playbook follows the current public builder surface, not legacy package helper tools.
+
+Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
+
+1. read or create the package through `package_get` / `package_apply`
+2. create each app separately
+3. keep package ownership on the public `package_id` path instead of a separate attach step
+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, create it through `package_apply(create_if_missing=true, package_name=...)`.
+
+## Minimal sequence
+
+1. `package_get` if `package_id` is already known; otherwise derive the package from related readback or ask the user for the id
+2. `app_resolve`
+3. `app_schema_apply`
+4. `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_get` or `package_apply(create_if_missing=true, package_name=...)`
+2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
+
+## Example
+
+Create a new package only after the user confirms package creation:
+
+```json
+{
+  "tool_name": "package_apply",
+  "arguments": {
+    "profile": "default",
+    "package_name": "研发项目管理",
+    "create_if_missing": true
+  }
+}
+```
+
+Read the package when `package_id` is already known:
+
+```json
+{
+  "tool_name": "package_get",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950
+  }
+}
+```
+
+Apply schema for a new app:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_name": "客户订单",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "add_fields": [
+      {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
+      {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单封面", "type": "attachment", "as_data_cover": true},
+      {"name": "订单金额", "type": "amount"},
+      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+    ],
+    "update_fields": [],
+    "remove_fields": []
+  }
+}
+```
+
+Apply schema for multiple apps in one call:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "apps": [
+      {
+        "client_key": "customer",
+        "app_name": "客户",
+        "add_fields": [
+          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
+        ]
+      },
+      {
+        "client_key": "order",
+        "app_name": "订单",
+        "add_fields": [
+          {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
+          {
+            "name": "关联客户",
+            "type": "relation",
+            "target_app_ref": "customer",
+            "display_field": {"name": "客户名称"},
+            "visible_fields": [{"name": "客户名称"}]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Data title is required: mark exactly one top-level field with `as_data_title: true`. Data cover is optional and only valid on a top-level `attachment` field.
+
+## Common failures
+
+### `APP_NOT_FOUND`
+
+Expected on create. Continue with `create_if_missing=true`.
+
+### `CREATE_APP_ROUTE_NOT_FOUND`
+
+The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
+
+### 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