@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/skills/qingflow-cli/reference/builder/workflow/04-stage1-business-modeling.md

@@ -0,0 +1,131 @@
+# 阶段 1：提取业务建模
+
+从用户上下文（对话文本、上传的流程图图片、需求描述等）中提取业务建模。
+
+## 若上下文包含流程图图片
+
+1. 优先使用当前客户端已暴露的图片理解能力读取流程图；不要假定某个跨插件工具名一定存在
+2. 如果当前环境没有图片理解能力，要求用户补充流程文字说明或节点/分支清单
+3. 从图片理解结果或用户补充中提取：节点名称、节点类型、流转顺序、分支条件（字段→选项→目标）
+
+## 建模输出格式
+
+保存到 `tmp/业务建模_<应用名>.md`：
+
+```markdown
+# 业务建模：<流程名称>
+
+## 应用信息
+- APP_KEY: <xxx>
+- 应用名称: <xxx>
+
+## 节点清单
+| id | 名称 | 类型 | 审批人/处理人 | 说明 |
+|----|------|------|--------------|------|
+| n1 | 员工提交申请 | applicant | — | 工作流入门 |
+| n2 | 部门经理审批 | approval | 部门经理 | 或签 |
+| ... | ... | ... | ... | ... |
+
+## 流转路径
+n1 → n2 → [分支:字段=选项]
+  ├─ 选项A → n3
+  └─ 选项B → n4
+...
+
+## 分支条件明细
+| 分支来源 | 条件字段 | 判断符 | 选项值 | 目标节点 |
+|----------|---------|--------|--------|----------|
+| 服务类型 | 服务类型(单选) | equals | 客诉 | 质量部负责人接单 |
+| ... | ... | ... | ... | ... |
+```
+
+**无法提取时**：明确告知用户缺少哪些信息（节点、角色、条件等），要求补充，**禁止臆测**。
+
+---
+
+## 业务完整性自检（建模完成后必须逐项确认）
+
+> ⚠️ **用户指令优先**：如果用户给出了明确的流程设计指令，以用户指令为准，本自检仅作为补充建议。与用户指令冲突的项标记为「用户已明确」并跳过。
+>
+> 当用户未给出明确指令时，本自检从以下七个维度引导思考。回答「否」的项需在建模文件中说明理由。**禁止为了通过自检而添加无业务意义的节点。**
+
+### 一、审批强度与风险匹配
+- 审批层数是否与业务风险匹配？
+- 低风险场景是否走了简化路径？
+- 是否存在冗余审批节点？
+
+### 二、角色策略与审批人指派
+- 审批人是否基于角色而非个人？
+- 不同审批层级是否代表不同能力或权限？
+- 关键节点是否需要多人会签？审批人缺席时是否有替代方案？
+
+### 三、执行顺序与效率
+- 互不依赖的审批是否并行？
+- 是否存在可合并的冗余环节？
+- 串行审批链是否过长？
+
+### 四、条件路由与分支设计
+- 是否需要根据业务数据动态路由？
+- 分支条件是否覆盖所有可能？是否有默认兜底？
+
+### 五、异常处理与纠错机制
+- 审批不通过时是否可以修正重提？
+- 驳回后回到哪个节点？
+- 是否考虑了审批超时？
+- 异常升级是否有终态？
+
+### 六、信息透明与闭环
+- 关键决策节点完成后是否需要抄送？
+- 流程结束后提交人是否能明确知道结果？
+- 是否需要自动化节点更新状态字段？
+
+### 七、流程嵌入与业务衔接
+- 审批通过后是否有后续业务动作？
+- 是否有前置校验需求？
+
+---
+
+## 自检结果格式
+
+追加到建模文件末尾：
+
+```markdown
+## 业务完整性自检
+
+| 维度 | 检查项 | 结果 | 说明 |
+|------|--------|:----:|------|
+| 一、审批强度 | 审批层数是否与风险匹配？ | ✅/❌ | |
+| 一、审批强度 | 低风险是否简化路径？ | ✅/❌ | |
+| 一、审批强度 | 是否存在冗余审批节点？ | ✅/❌ | |
+| 二、角色策略 | 审批人是否基于角色？ | ✅/❌ | |
+| 二、角色策略 | 不同层级是否代表不同能力？ | ✅/❌ | |
+| 二、角色策略 | 是否考虑缺席替代方案？ | ✅/❌ | |
+| 三、执行效率 | 独立审批是否并行化？ | ✅/❌ | |
+| 三、执行效率 | 串行链是否过长？ | ✅/❌ | |
+| 三、执行效率 | 是否存在可合并环节？ | ✅/❌ | |
+| 四、条件路由 | 是否需要动态路由？ | ✅/❌ | |
+| 四、条件路由 | 分支条件是否全覆盖？ | ✅/❌ | |
+| 四、条件路由 | 是否有默认兜底？ | ✅/❌ | |
+| 五、异常处理 | 驳回后是否可修正重提？ | ✅/❌ | |
+| 五、异常处理 | 是否考虑审批超时？ | ✅/❌ | |
+| 五、异常处理 | 异常升级是否有终态？ | ✅/❌ | |
+| 六、信息透明 | 关键节点是否抄送？ | ✅/❌ | |
+| 六、信息透明 | 提交人能否明确结果？ | ✅/❌ | |
+| 六、信息透明 | 状态字段是否自动更新？ | ✅/❌ | |
+| 七、业务衔接 | 是否有前置校验？ | ✅/❌ | |
+| 七、业务衔接 | 审批后是否有后续动作？ | ✅/❌ | |
+```
+
+## 自检不通过时的处理
+
+- 某个维度确实需要但设计中遗漏了 → 回到建模环节补充
+- 某个维度在业务上确实不需要 → 在「说明」列记录理由后放行
+- 与用户明确指令冲突 → 标记「用户已明确」，以用户指令为准
+
+**无法提取时**：明确告知用户缺少哪些信息，要求补充，**禁止臆测**。
+
+---
+
+← 上一步：[03-flow-patterns.md](03-flow-patterns.md)
+← 返回主流程：[../SKILL.md](../../../SKILL.md)
+→ 下一步：[05-stage2-members-roles.md](05-stage2-members-roles.md)

package/skills/qingflow-cli/reference/builder/workflow/05-stage2-members-roles.md

@@ -0,0 +1,29 @@
+# 阶段 2：获取成员/角色信息
+
+在配置节点负责人（`responsible`）前，需要搜索可用成员与角色：
+
+```bash
+# 搜索成员
+qingflow --json builder member search --query "<姓名/关键词>" --page-size 20
+# 搜索角色
+qingflow --json builder role search --keyword "<角色名>" --page-size 20
+```
+
+## 注意事项
+
+- `responsible` 是 **MemberRefDTO 数组**，不是单值对象
+- `type` 字段可取：
+  - `user`（指定人）
+  - `role`（角色）
+  - `dept`（部门）
+  - `applicant` / `leader` / `formEmail` / `formMember` / `formDept` / `nodeLeader`
+- 指定人时使用 `uid` 传入成员 UID（整数）
+- 角色时使用 `roleId` 传入角色 ID（整数）
+- 部门时使用 `deptId` 传入部门 ID（整数），可选 `havingSubDept`
+- 避免硬编码 UID/角色 ID/部门 ID，始终从搜索结果中提取
+
+---
+
+← 上一步：[04-stage1-business-modeling.md](04-stage1-business-modeling.md)
+← 返回主流程：[../SKILL.md](../../../SKILL.md)
+→ 下一步：[06-stage3-build-spec.md](06-stage3-build-spec.md)

package/skills/qingflow-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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)