@josephyan/qingflow-app-builder-mcp 1.0.8 → 1.1.1

package/skills/qingflow-workflow-builder/references/06-stage3-build-spec.md

@@ -0,0 +1,165 @@
+# 阶段 3：获取 Schema + 构建 Spec
+
+## 3.1 获取当前工作流 Schema
+
+```bash
+qingflow builder flow schema --json > tmp/flow_schema.json
+```
+
+> 注意：若已在阶段 1 前执行过，可复用。建议每次搭建前刷新以获取最新 schema。
+
+## 3.2 读取现有 Flow Spec（更新模式下必须执行）
+
+```bash
+qingflow --json builder flow get --app-key <APP_KEY> > tmp/current_flow.json
+```
+
+从返回的 `spec` 中提取 `nodes` 和 `edges` 作为修改基础。
+
+**更新模式下**：构建新 spec 后，用 diff 脚本确认变更范围是否符合预期：
+
+```bash
+python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
+```
+
+新建场景可跳过此步。
+
+## 3.3 构建 WorkflowSpec
+
+按照以下结构构建 `spec.json`：
+
+```json
+{
+  "nodes": [
+    {
+      "id": "n1",
+      "type": "applicant",
+      "name": "员工提交申请",
+      "attrs": {}
+    },
+    {
+      "id": "n2",
+      "type": "approval",
+      "name": "部门经理审批",
+      "attrs": {
+        "responsible": [
+          {"type": "role", "roleId": 123}
+        ],
+        "approveType": "or_signed",
+        "auditUserType": "role",
+        "revert": true,
+        "revertScope": "all",
+        "transferScope": "all"
+      }
+    },
+    {
+      "id": "g1",
+      "type": "gateway",
+      "name": "服务类型判断",
+      "attrs": {"mode": "parallel"}
+    },
+    {
+      "id": "n3",
+      "type": "filling",
+      "name": "补充信息",
+      "attrs": {
+        "responsible": [
+          {"type": "user", "uid": 456}
+        ]
+      }
+    }
+  ],
+  "edges": {
+    "edges": [
+      {"from": "n1", "to": "n2"},
+      {"from": "n2", "to": "g1"},
+      {
+        "from": "g1",
+        "to": "n3",
+        "label": "客诉",
+        "condition": {
+          "kind": "rules",
+          "autoJudges": [
+            [
+              {
+                "fieldId": 343290994,
+                "fieldType": "single_select",
+                "matchType": "literal",
+                "judgeType": "equals",
+                "values": ["客诉"]
+              }
+            ]
+          ]
+        }
+      },
+      {
+        "from": "g1",
+        "to": "n4",
+        "label": "技术服务",
+        "condition": {
+          "kind": "rules",
+          "autoJudges": [
+            [
+              {
+                "fieldId": 343290994,
+                "fieldType": "single_select",
+                "matchType": "literal",
+                "judgeType": "equals",
+                "values": ["技术服务"]
+              }
+            ]
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## 节点类型速查
+
+| type | 说明 | 必要 attrs |
+|------|------|-----------|
+| `applicant` | 工作流入口（仅1个） | 可选: `commentStatus`, `submitText`, `fieldPermissions` |
+| `approval` | 审批节点 | `responsible`, `approveType`, `auditUserType` |
+| `filling` | 填写节点 | `responsible` |
+| `gateway` | 分支/汇合 | `mode`: `parallel`（分支）或 `join`（汇合） |
+| `cc` | 抄送节点 | `receivers` |
+| `automation` | 自动化/Q-Robot | `subType` + 对应配置 |
+
+## 边条件体系
+
+| condition.kind | 含义 | 要求 |
+|---------------|------|------|
+| `rules` | 条件选路 | 必须含 `autoJudges`（OR-of-AND 二维数组） |
+| `default` | 兜底边 | 无 `autoJudges` |
+| 省略 | 无条件线性边 | — |
+
+## autoJudges 结构
+
+OR-of-AND 二维数组：
+
+```json
+"autoJudges": [
+  [  // OR 组 1
+    {"fieldId": N, "fieldType": "single_select", "matchType": "literal", "judgeType": "equals", "values": ["选项"]}
+  ],
+  [  // OR 组 2
+    {"fieldId": M, "fieldType": "single_select", "matchType": "literal", "judgeType": "equals", "values": ["另一个选项"]}
+  ]
+]
+```
+
+**关键约束：`autoJudges` 必须是 `[[{...}]]` 二维数组！一维数组 `[{...}]` 格式会被后端静默吞掉。**
+
+**judgeType 常用值**：`equals`, `not_equals`, `equals_any`, `includes`, `greater_than` 等（共21种，详见 schema）。
+
+## 3.4 保存 Spec 到文件
+
+将构建好的完整 Spec 以 JSON 格式保存到文件 `tmp/flow_spec.json`，确保使用 UTF-8 编码、缩进格式化，以便后续验证和 apply 使用。
+
+---
+
+← 上一步：[05-stage2-members-roles.md](05-stage2-members-roles.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[07-stage4-validate-spec.md](07-stage4-validate-spec.md)

package/skills/qingflow-workflow-builder/references/07-stage4-validate-spec.md

@@ -0,0 +1,33 @@
+# 阶段 4：验证 Spec
+
+使用本 Skill 自带的验证脚本：
+
+```bash
+# 新建模式
+python3 scripts/validate_flow_spec.py \
+  tmp/flow_spec.json --schema tmp/flow_schema.json
+
+# 更新模式（同时校验最小修改原则）
+python3 scripts/validate_flow_spec.py \
+  tmp/flow_spec.json --schema tmp/flow_schema.json --previous tmp/current_flow.json
+```
+
+## 验证内容
+
+1. JSON Schema 结构校验（基于 `qingflow builder flow schema` 的官方 schema）
+2. DAG 无环检查
+3. 单 applicant 节点检查
+4. Gateway 出边条件完整性检查（rules 边必须有 autoJudges）
+5. 审批/填写/抄送节点必要字段检查
+6. 自动化节点配置检查
+7. 孤立节点检查
+
+## 验证不通过时的处理
+
+根据错误信息修正 spec，重新验证，直到全部通过再进入 apply。
+
+---
+
+← 上一步：[06-stage3-build-spec.md](06-stage3-build-spec.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[08-stage5-apply-verify.md](08-stage5-apply-verify.md)

package/skills/qingflow-workflow-builder/references/08-stage5-apply-verify.md

@@ -0,0 +1,51 @@
+# 阶段 5：Apply + 验证循环
+
+## 5.1 部署工作流
+
+```bash
+qingflow builder flow apply \
+  --app-key <APP_KEY> \
+  --spec-file tmp/flow_spec.json \
+  --publish
+```
+
+### 解读响应
+
+- `status: success` → 进入验证
+- `status: failed` → 查看 `error_code` / `message` / `blocking_issues`，修正后重试
+- `missing_input_node_ids` 警告（新建时常见）→ 可忽略，是正常现象
+
+## 5.2 验证部署结果
+
+```bash
+qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
+```
+
+### 逐项对比
+
+1. **节点数量与类型**：`nodes` 数量是否一致，每个节点的 `type` 和 `name` 是否正确
+2. **边连通性**：`edges` 数量是否一致，`from`/`to` 关系是否正确
+3. **分支条件**（核心关注点）：每个 gateway 出边是否有正确的 `autoJudges`
+   - 检查 `condition.kind` 是否为 `rules`
+   - 检查 `autoJudges` 中的 `fieldId`、`judgeType`、`values` 是否正确
+   - **`autoJudges` 必须是非空二维数组 `[[{...}]]`，空数组或一维数组说明条件未生效**
+4. **自动化节点**：`automation` 节点的 `subType`、`appKey`、`fieldMappings` 等是否正确
+   - 必要时拉取其他应用数据验证：`qingflow --json builder app get --app-key <目标APP_KEY> fields`
+5. **审批节点**：`responsible`、`approveType`、`revert` 等是否与建模一致
+
+## 5.3 不一致时的循环
+
+若验证发现不一致：
+1. 分析差异原因（条件格式错误、节点缺失、边遗漏等）
+2. 修正 `tmp/flow_spec.json`
+3. 重新验证 → apply → 对比
+4. **最多循环 3 次**；若 3 次后仍有不可修复的差异，告知用户并列出：
+   - 已成功配置的部分
+   - 仍存在差异的部分及可能原因
+   - 建议用户在 Web 端手动调整的部分
+
+---
+
+← 上一步：[07-stage4-validate-spec.md](07-stage4-validate-spec.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[09-stage6-summary.md](09-stage6-summary.md)

package/skills/qingflow-workflow-builder/references/09-stage6-summary.md

@@ -0,0 +1,88 @@
+# 阶段 6：总结搭建结果
+
+搭建完成后，输出结构化的总结报告到文件 `tmp/工作流搭建报告_<应用名>.md`：
+
+```markdown
+# 工作流搭建报告
+
+## 业务描述
+<一段话概括流程业务场景，如"工单从员工提交开始，经部门领导审批，根据服务类型分流至不同处理部门...">
+
+## 应用信息
+- 应用名称: <xxx>
+- APP_KEY: <xxx>
+
+## Mermaid 流程图
+
+\`\`\`mermaid
+graph TD
+    n1[员工提交工单申请] --> n2[申请部门领导逐级审批]
+    n2 --> g1{服务类型}
+    g1 -->|客诉| n3[质量部负责人接单]
+    g1 -->|技术服务| n4[技术服务部负责人接单]
+    ...
+\`\`\`
+
+## 节点统计
+- 总节点数: N
+- applicant: 1
+- approval: X
+- filling: Y
+- gateway: Z
+- cc: W
+
+## 分支条件配置
+| Gateway | 分支 | 字段 | 条件 | 目标 |
+|---------|------|------|------|------|
+| ... | ... | ... | ... | ... |
+
+## 业务完整性回顾
+
+> 对照阶段 1 的七维度自检清单，逐项回顾部署结果。如有不一致，说明原因（如后端不支持、用户要求修改等）。
+
+| 维度 | 检查项 | 建模时 | 部署后 | 一致 |
+|------|--------|:------:|:------:|:----:|
+| 一、审批强度 | 审批层数是否与风险匹配？ | ✅/❌ | ✅/❌ | ✅ |
+| 一、审批强度 | 低风险是否简化路径？ | ✅/❌ | ✅/❌ | ✅ |
+| 一、审批强度 | 是否存在冗余审批节点？ | ✅/❌ | ✅/❌ | ✅ |
+| 二、角色策略 | 审批人是否基于角色？ | ✅/❌ | ✅/❌ | ✅ |
+| 二、角色策略 | 不同层级是否代表不同能力？ | ✅/❌ | ✅/❌ | ✅ |
+| 二、角色策略 | 是否考虑缺席替代方案？ | ✅/❌ | ✅/❌ | ✅ |
+| 三、执行效率 | 独立审批是否并行化？ | ✅/❌ | ✅/❌ | ✅ |
+| 三、执行效率 | 串行链是否过长？ | ✅/❌ | ✅/❌ | ✅ |
+| 三、执行效率 | 是否存在可合并环节？ | ✅/❌ | ✅/❌ | ✅ |
+| 四、条件路由 | 是否需要动态路由？ | ✅/❌ | ✅/❌ | ✅ |
+| 四、条件路由 | 分支条件是否全覆盖？ | ✅/❌ | ✅/❌ | ✅ |
+| 四、条件路由 | 是否有默认兜底？ | ✅/❌ | ✅/❌ | ✅ |
+| 五、异常处理 | 驳回后是否可修正重提？ | ✅/❌ | ✅/❌ | ✅ |
+| 五、异常处理 | 是否考虑审批超时？ | ✅/❌ | ✅/❌ | ✅ |
+| 五、异常处理 | 异常升级是否有终态？ | ✅/❌ | ✅/❌ | ✅ |
+| 六、信息透明 | 关键节点是否抄送？ | ✅/❌ | ✅/❌ | ✅ |
+| 六、信息透明 | 提交人能否明确结果？ | ✅/❌ | ✅/❌ | ✅ |
+| 六、信息透明 | 状态字段是否自动更新？ | ✅/❌ | ✅/❌ | ✅ |
+| 七、业务衔接 | 是否有前置校验？ | ✅/❌ | ✅/❌ | ✅ |
+| 七、业务衔接 | 审批后是否有后续动作？ | ✅/❌ | ✅/❌ | ✅ |
+| 七、业务衔接 | 是否涉及上下游系统？ | ✅/❌ | ✅/❌ | ✅ |
+
+## 部署状态
+- ✅ 部署成功 / ⚠️ 部分差异 / ❌ 失败
+- <详情>
+```
+
+## 搭建失败时的回退策略
+
+| 失败类型 | 处理 |
+|----------|------|
+| 应用不存在 | 先完成应用搭建和字段配置，再继续工作流搭建 |
+| 字段缺失 | 查阅 qingflow CLI 相关 Skill 先补充缺失字段 |
+| 条件多次无法生效（autoJudges 被吞） | 告知用户这是已知限制，需在 Web 端手动补条件 |
+| 验证脚本持续性报错 | 检查 schema 是否需要刷新（`builder flow schema --json`） |
+| apply 返回 blocking_issues | 逐一排查并修复 |
+
+**回退原则**：不删除用户应用、不修改已有字段，仅告知差异和推荐操作。
+
+---
+
+← 上一步：[08-stage5-apply-verify.md](08-stage5-apply-verify.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 扩展参考：[10-node-config-reference.md](10-node-config-reference.md)

package/skills/qingflow-workflow-builder/references/10-node-config-reference.md

@@ -0,0 +1,93 @@
+# 节点配置参考
+
+## `responsible` 数组结构
+
+审批、填写节点的 `responsible` 必须是 **MemberRefDTO 数组**（`minItems: 1`），而不是单值对象。
+
+```json
+"responsible": [
+  {"type": "role", "roleId": 123},
+  {"type": "user", "uid": 456},
+  {"type": "dept", "deptId": 789, "havingSubDept": true}
+]
+```
+
+### MemberRefDTO 字段
+
+| 字段 | 类型 | 必填场景 | 说明 |
+|------|------|----------|------|
+| `type` | string | always | `user` / `dept` / `role` / `applicant` / `leader` / `formEmail` / `formMember` / `formDept` / `nodeLeader` |
+| `uid` | integer | `type="user"` | 成员 ID |
+| `deptId` | integer | `type="dept"` | 部门 ID |
+| `roleId` | integer | `type="role"` | 角色 ID |
+| `queId` | integer | `leader` / `formEmail` / `formMember` / `formDept` | 字段/队列 ID |
+| `havingSubDept` | boolean | `type="dept"` | 是否包含子部门 |
+
+> ⚠️ **关键区别**：
+> - 成员类型 `type` 必须是 `"user"`，不是 `"member"`
+> - 用户 ID 字段是 `"uid"`（整数），不是 `"uids"`（字符串数组）
+> - 角色 ID 字段是 `"roleId"`（整数），不是 `"roleIds"`（字符串数组）
+
+---
+
+## 审批节点（approval）完整 attrs
+
+```json
+{
+  "responsible": [
+    {"type": "role", "roleId": 123}
+  ],
+  "approveType": "or_signed",
+  "auditUserType": "role",
+  "revert": true,
+  "revertScope": "all",
+  "transferScope": "all",
+  "auditFeedback": false,
+  "commentStatus": "not_required",
+  "timeoutConfig": {"duration": {"value": 24, "unit": "hour"}, "autoExecute": "approved"}
+}
+```
+
+| 字段 | 说明 | 可选值 |
+|------|------|--------|
+| `responsible` | 审批人（MemberRefDTO 数组） | 见上方 MemberRefDTO |
+| `approveType` | 审批模式 | `or_signed`(或签) / `countersigned`(会签) |
+| `auditUserType` | 审批人来源 | `role` / `user` / `dept` |
+| `revert` | 允许驳回 | `true` / `false` |
+| `revertScope` | 驳回范围 | `all`（可回退到任意节点） |
+| `transferScope` | 转交范围 | `all` |
+
+## 填写节点（filling）完整 attrs
+
+```json
+{
+  "responsible": [
+    {"type": "user", "uid": 456}
+  ],
+  "auditFeedback": false,
+  "timeoutConfig": null,
+  "fieldPermissions": [
+    {"fieldId": 343290996, "permission": "editable"}
+  ]
+}
+```
+
+## Gateway 节点
+
+```json
+{
+  "id": "g1",
+  "type": "gateway",
+  "name": "分支名称",
+  "attrs": {"mode": "parallel"}
+}
+```
+
+`mode` 取值：
+- `parallel`：并行分支（出边 ≥ 2，每条边可选择 `rules` 或 `default`）
+- `join`：汇合节点（多入边、单出边）
+
+---
+
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 排障参考：[11-troubleshooting.md](11-troubleshooting.md)

package/skills/qingflow-workflow-builder/references/11-troubleshooting.md

@@ -0,0 +1,15 @@
+# 常见问题与排障
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `autoJudges` apply 后为空 | 使用了一维数组 `[{...}]` 格式 | 改为二维 `[[{...}]]` |
+| 条件分支不生效 | `autoJudges` 中的 `values` 与表单选项 label 不一致 | 核对字段选项文本，确保完全一致 |
+| apply 返回 `missing_input_node_ids` | 新建 flow 首次 apply 的正常提示 | 可忽略，再次 get 验证即可 |
+| 回退边（gateway → 前序节点）不生效 | 引擎不支持通过 gateway 实现回退 | 改用审批节点 `revert: true` |
+| 审批节点无审批人 | `responsible` 中的 UID/角色 ID 无效或缺失 | 使用 `builder member search` / `role search` 确认 |
+| `fieldType` 不匹配 | 单选用了 `text` 而非 `single_select` | 确认字段实际类型后更正 |
+
+---
+
+← 上一步：[10-node-config-reference.md](10-node-config-reference.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)