@josephyan/qingflow-app-builder-mcp 1.1.26 → 1.1.28

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

@@ -1,530 +1,138 @@
-# Build Single App（单应用完整搭建）
+# 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.
+Use this when the user asks for one app/form, or gives one `app_key`.
+If the request contains several related business objects, use [build-complete-system.md](./build-complete-system.md).
 
-**Signal phrases**: "创建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX表单"、"我需要一个管理XX的应用"
+## Main Chain
 
-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}
-        ]
-      }
-    ]
-  }
-}
+```text
+app_resolve / app_get
+-> app_schema_apply(fields + form.sections)
+-> app_views_apply(views[])
+-> workflow only when requested or required
+-> readback/verify
 ```
 
-Record the returned `app_key`. All subsequent phases use it.
+This is the only recommended chain for a new single app. Do not split layout into a routine second step.
 
----
+## Required Shape
 
-## Phase 2 — Layout
+- Resolve the target package/app with `app_resolve`, `app_get`, or `package_get`.
+- Create or update business fields with `app_schema_apply`.
+- Put form layout directly in `form.sections` in the schema payload.
+- Exactly one readable top-level field must have `as_data_title: true`.
+- Do not create platform fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`.
+- Create at least one business view when the user-facing list/table/card experience matters.
+- If a view needs business actions, put the action configuration directly inside the view item with `action_buttons`.
 
-> **Read first**: [update-layout.md](./update-layout.md)
-
-Group fields into 3–4 logical sections with 2–3 fields per row.
+## Schema Payload Pattern
 
 ```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": [
-          ["甲方联系人", "甲方联系电话"],
-          ["合同内容摘要"],
-          ["合同附件"]
+  "package_id": 123,
+  "create_if_missing": true,
+  "apps": [
+    {
+      "client_key": "contract",
+      "app_name": "合同",
+      "icon": "document-text",
+      "color": "blue",
+      "add_fields": [
+        {"name": "合同名称", "type": "text", "required": true, "as_data_title": true},
+        {"name": "合同编号", "type": "text"},
+        {"name": "合同状态", "type": "select", "options": ["草稿", "审批中", "已生效", "已终止"]},
+        {"name": "合同金额", "type": "amount"},
+        {"name": "负责人", "type": "member"},
+        {"name": "签署日期", "type": "date"},
+        {"name": "合同说明", "type": "multiline"},
+        {"name": "合同附件", "type": "attachment"}
+      ],
+      "form": {
+        "sections": [
+          {"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)
+Agent-friendly field type aliases are allowed: `multiline -> long_text`, `select -> single_select`, `amount -> amount`. Readback may show canonical types; do not treat that as a mismatch.
 
-> **Read first**: [update-views.md](./update-views.md)
+## View Payload Pattern
 
-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 |
+- Use `app_views_apply(views=[...])`.
+- Do not create platform default views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`.
+- Use business-specific view names.
+- `filters` are fixed saved filters.
+- `query_conditions` are frontend query panel fields.
+- Put button configuration in `action_buttons`.
 
 ```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": [["合同名称", "合同类型"], ["合同状态", "负责人"], ["签署日期", "到期日期"]]
-        }
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "合同执行视图",
+      "type": "table",
+      "columns": ["合同名称", "合同状态", "合同金额", "负责人", "签署日期"],
+      "filters": [
+        {"field_name": "合同状态", "operator": "neq", "value": "已终止"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "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": [["合同名称", "合同状态"]]
+      "action_buttons": [
+        {
+          "text": "查看合同模板",
+          "action": "link",
+          "url": "https://example.com/contract-template",
+          "placement": "detail"
         }
+      ]
+    },
+    {
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "合同状态看板",
+      "type": "board",
+      "group_by": "合同状态",
+      "columns": ["合同名称", "合同金额", "负责人", "签署日期"],
+      "query_conditions": {
+        "enabled": true,
+        "rows": [["合同名称", "负责人"]]
       }
-    ]
-  }
+    }
+  ]
 }
 ```
 
-Record all `view_key` values before Phase 7.
-
----
-
-## Phase 5 — Custom Buttons
+## Workflow
 
-> 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`.
+Only add workflow when the user asks for approval, fill, copy, reminders, process routing, or task handling.
 
-Build 2–3 buttons. Common patterns for a single app:
+- Create an explicit business status `select` field first, such as `状态`, `处理状态`, `审批状态`, or `流程阶段`.
+- Do not create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- If no workflow is requested, report it as not requested/not configured.
 
-| 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 |
+## Readback And Verification
 
-**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"}}
-```
+After writing:
 
-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.
+- read fields and confirm `as_data_title`
+- read layout and confirm important fields are placed
+- read views and confirm business view keys exist
+- verify publish/live status only when required by the user or task
 
----
+If a write returns `partial_success`, `write_executed=true`, or `safe_to_retry=false`, read back before retrying. Retry only verified missing or incorrect slices.
 
-## Common failures
+## Stop Conditions
 
-| 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 |
+- If the task actually needs multiple business objects, switch to the complete-system guide.
+- If a same/similar app already exists and the user did not explicitly say update, extend, or create new, stop and ask which target to use.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names in a real business package.
+- If the same validation error repeats twice, re-read `builder_tool_contract` instead of guessing.