@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

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

@@ -0,0 +1,211 @@
+# 阶段 3：获取 Schema + 构建流程输入
+
+## 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` 作为修改基础。
+
+**更新模式下**：如果走 `patch_nodes[]`，直接使用读回的 `spec.nodes[].id` 做局部修改；如果提交完整 `--spec-file`，用 diff 脚本确认变更范围是否符合预期：
+
+```bash
+python3 scripts/workflow/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
+```
+
+新建场景可跳过此步。
+
+## 3.3 主路径：构建 WorkflowSpec
+
+`--spec-file` 用于已经从 `builder flow schema` / `builder flow get` 读回并理解的 WorkflowSpec。节点结构、节点 id、负责人、字段权限和边条件都以 schema/readback 为准。
+
+所有需要继续向下路由的节点都显式写 `sync: true`。Q-Robot 也在 WorkflowSpec 中表达为 `type: "automation"`，由 `attrs.subType` 选择具体能力。
+
+WorkflowSpec 示例：
+
+```json
+{
+  "nodes": [
+    {
+      "id": "n1",
+      "type": "applicant",
+      "name": "员工提交申请",
+      "sync": true,
+      "attrs": {}
+    },
+    {
+      "id": "n2",
+      "type": "approval",
+      "name": "部门经理审批",
+      "sync": true,
+      "attrs": {
+        "responsible": [
+          {"type": "role", "roleId": 123}
+        ],
+        "approveType": "or_signed",
+        "auditUserType": "role",
+        "revert": true,
+        "revertScope": "all",
+        "transferScope": "all"
+      }
+    },
+    {
+      "id": "g1",
+      "type": "gateway",
+      "name": "服务类型判断",
+      "sync": true,
+      "attrs": {"mode": "parallel"}
+    },
+    {
+      "id": "n3",
+      "type": "filling",
+      "name": "补充信息",
+      "sync": true,
+      "attrs": {
+        "responsible": [
+          {"type": "user", "uid": 456}
+        ]
+      }
+    },
+    {
+      "id": "n4",
+      "type": "approval",
+      "name": "技术服务审批",
+      "sync": true,
+      "attrs": {
+        "responsible": [
+          {"type": "role", "roleId": 456}
+        ],
+        "approveType": "or_signed",
+        "auditUserType": "role"
+      }
+    },
+    {
+      "id": "g2",
+      "type": "gateway",
+      "name": "分支汇合",
+      "sync": true,
+      "attrs": {"mode": "join"}
+    }
+  ],
+  "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": ["技术服务"]
+              }
+            ]
+          ]
+        }
+      },
+      {"from": "n3", "to": "g2"},
+      {"from": "n4", "to": "g2"}
+    ]
+  }
+}
+```
+
+## WorkflowSpec 节点类型速查
+
+| type | 说明 | 必要 attrs |
+|------|------|-----------|
+| `applicant` | 工作流入口（仅1个） | 可选: `commentStatus`, `submitText`, `fieldPermissions` |
+| `approval` | 审批节点 | `responsible`, `approveType`, `auditUserType` |
+| `filling` | 填写节点 | `responsible` |
+| `gateway` | 分支/汇合 | `mode`: `parallel`（分支）或 `join`（汇合） |
+| `cc` | 抄送节点 | `receivers` |
+| `automation` | 自动化/Q-Robot | `subType` + 对应配置 |
+
+## 边条件体系
+
+本节属于 `--spec-file` WorkflowSpec 路径。不要凭记忆手写 `autoJudges`、`judgeType` 或 raw `fieldId` 条件；先读 `builder flow schema` / `builder flow get`，再按读回结构修改。
+
+| 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 局部修改 patch_nodes
+
+局部修改现有流程时，先 `builder flow get`，使用读回 `spec.nodes[].id`：
+
+```json
+[
+  {"id": "89160906", "set": {"name": "需求评审（局部改）"}}
+]
+```
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
+```
+
+---
+
+← 上一步：[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,36 @@
+# 阶段 4：验证流程输入
+
+主链路 `--spec-file` 使用本 Skill 自带的 WorkflowSpec 验证脚本；局部修改 `patch_nodes[]` 至少检查节点 id 来自 `builder flow get` 读回，且 `set/unset` 只包含要改的字段。
+
+WorkflowSpec 验证命令：
+
+```bash
+# WorkflowSpec 新建模式
+python3 scripts/workflow/validate_flow_spec.py \
+  tmp/flow_spec.json --schema tmp/flow_schema.json
+
+# WorkflowSpec 更新模式（同时校验最小修改原则）
+python3 scripts/workflow/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. 孤立节点检查
+8. 入口节点和需要继续路由的节点显式 `sync: true`
+
+## 验证不通过时的处理
+
+WorkflowSpec 根据验证脚本错误修正 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,66 @@
+# 阶段 5：Apply + 验证循环
+
+## 5.1 部署工作流
+
+推荐主链路：
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --spec-file tmp/flow_spec.json \
+  --publish \
+  > tmp/flow_apply.json
+```
+
+局部修改已存在节点：
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
+```
+
+### 解读响应
+
+- `status: success` → 进入验证
+- `status: failed` → 查看 `error_code` / `message` / `blocking_issues`，修正后重试
+- `missing_input_node_ids` 警告（新建时常见）→ 可忽略，是正常现象
+- 成功写入应读取 `write_executed=true`、`write_succeeded=true`、`safe_to_retry=false`；不要因中间读回 pending 立刻重放。
+
+## 5.2 验证部署结果
+
+```bash
+qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
+```
+
+### 逐项对比
+
+1. **节点数量与类型**：`nodes` 数量是否一致，每个节点的 `type` 和 `name` 是否正确
+2. **边连通性**：`edges` 数量是否一致，`from`/`to` 关系是否正确
+   - 必须确认 `applicant` 入口节点存在出边，不能只停留在“提交申请”
+3. **分支条件**（WorkflowSpec 路径）：每个 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` 或 `tmp/flow_patch_nodes.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,18 @@
+# 常见问题与排障
+
+`autoJudges` 属于 WorkflowSpec 路径。公开主链路是先读 `builder flow schema` / `builder flow get`，再提交 `--spec-file` 或 `--patch-nodes-file`。
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `autoJudges` apply 后为空 | 使用了一维数组 `[{...}]` 格式 | 改为二维 `[[{...}]]` |
+| 条件分支不生效 | `autoJudges` 中的 `values` 与表单选项 label 不一致 | 核对字段选项文本，确保完全一致 |
+| apply 返回 `missing_input_node_ids` | 新建 flow 首次 apply 的正常提示 | 可忽略，再次 get 验证即可 |
+| 录入数据后只留下“提交申请”日志，不进入下一节点 | WorkflowSpec 入口节点没有出边，或入口/路由节点缺少 `sync: true` | `builder flow get` 读回 spec，确认 applicant 出边和节点 `sync`，修正后用 `--spec-file` 发布 |
+| 回退边（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)

package/skills/qingflow-cli/reference/builder/workflow/README.md

@@ -0,0 +1,88 @@
+# Qingflow CLI 工作流搭建
+
+## 快速索引
+
+| 主题 | 文件 |
+|------|------|
+| 依赖命令、能力边界 | [01-overview.md](./01-overview.md) |
+| 更新模式与最小修改原则 | [02-update-mode.md](./02-update-mode.md) |
+| 流程模式速查（线性/分支/回退） | [03-flow-patterns.md](./03-flow-patterns.md) |
+| 阶段 1：业务建模与自检 | [04-stage1-business-modeling.md](./04-stage1-business-modeling.md) |
+| 阶段 2：成员/角色搜索 | [05-stage2-members-roles.md](./05-stage2-members-roles.md) |
+| 阶段 3：Schema + 构建流程输入 | [06-stage3-build-spec.md](./06-stage3-build-spec.md) |
+| 阶段 4：验证流程输入 | [07-stage4-validate-spec.md](./07-stage4-validate-spec.md) |
+| 阶段 5：Apply + 验证循环 | [08-stage5-apply-verify.md](./08-stage5-apply-verify.md) |
+| 阶段 6：总结报告与回退 | [09-stage6-summary.md](./09-stage6-summary.md) |
+| 节点配置参考 | [10-node-config-reference.md](./10-node-config-reference.md) |
+| 常见问题与排障 | [11-troubleshooting.md](./11-troubleshooting.md) |
+
+---
+
+## 一、思考（Thought）：何时启用与前置条件
+
+### 触发条件
+
+当用户要求**在轻流应用中搭建工作流**时阅读本节，典型触发语：
+
+- "帮我搭建审批流程"
+- "在这个应用里创建工作流"
+- "按照这张流程图实现工作流"
+- "配置流程分支条件"
+- "给这个应用加一个审批节点"
+
+### 前提检查（进入行动前必须完成）
+
+在开始任何搭建操作前，按顺序确认以下条件：
+
+1. **应用存在性**：`qingflow --json app get --app-key <APP_KEY>` 成功返回
+2. **字段就绪**：`qingflow --json builder app get --app-key <APP_KEY> fields` 返回字段列表，确认业务建模所需字段（如单选框、成员、部门字段）均已存在；流程应用还需要明确的业务状态单选字段（如 `状态`、`处理状态`、`审批状态`、`工单状态`、`计划状态`、`报工状态`、`单据状态`），不要只用 `检验结论` 这类结果字段替代状态字段
+3. **未启用已有流程**（新建场景）：`qingflow --json builder app get --app-key <APP_KEY> flow` 查看 `enabled` 状态，若已有流程则为**更新模式**
+
+**不满足时的处理**：
+- 应用不存在 → 先完成应用搭建和字段配置，再继续工作流搭建
+- 字段缺失 → 先补充缺失的字段定义，再继续工作流搭建
+- 应用已启用流程 → 进入更新模式（读取现有 spec 再修改）
+
+### 能力边界
+
+| 在范围内 | 超出范围 |
+|----------|----------|
+| 基于已有应用搭建工作流 | 从零创建应用 |
+| WorkflowSpec 生成与 apply；`patch_nodes` 仅用于已有节点局部维护 | 操作复杂命令拼接 |
+| 审批/填写/抄送/自动化/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+完整命令与依赖说明见 [01-overview.md](./01-overview.md)。
+辅助脚本已合并到 `qingflow-cli/scripts/workflow/`。
+
+---
+
+## 二、行动（Action）：核心 SOP
+
+按顺序执行以下阶段，每个阶段详见对应 reference 文件：
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 0 | 判断是否为更新模式，确认最小修改原则 | [02-update-mode.md](./02-update-mode.md) |
+| 阶段 1 | 提取业务建模，完成七维度业务自检 | [04-stage1-business-modeling.md](./04-stage1-business-modeling.md) |
+| 阶段 2 | 搜索成员/角色，用于节点负责人配置 | [05-stage2-members-roles.md](./05-stage2-members-roles.md) |
+| 阶段 3 | 获取 Schema、读取现有流程、构建 WorkflowSpec；已有节点小改才用 patch_nodes | [06-stage3-build-spec.md](./06-stage3-build-spec.md) |
+| 阶段 4 | 验证 WorkflowSpec / patch_nodes | [07-stage4-validate-spec.md](./07-stage4-validate-spec.md) |
+| 阶段 5 | Apply 工作流并验证部署结果 | [08-stage5-apply-verify.md](./08-stage5-apply-verify.md) |
+
+构建流程输入前，若对流程模式有疑问，先查阅 [03-flow-patterns.md](./03-flow-patterns.md)。
+
+---
+
+## 三、反思（Reflection）：验证与总结
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 6 | 输出结构化搭建报告，回顾业务完整性 | [references/09-stage6-summary.md](./09-stage6-summary.md) |
+
+搭建失败时的回退策略、节点配置细节、常见问题排障分别见：
+- [references/09-stage6-summary.md](./09-stage6-summary.md)
+- [references/10-node-config-reference.md](./10-node-config-reference.md)
+- [references/11-troubleshooting.md](./11-troubleshooting.md)