@ohos-cpf/3rdloop 0.0.1 → 0.0.3

package/vendor/Server/Skills/task-decomposition/references/ACCEPTANCE_CRITERIA_GUIDE.md

@@ -1,179 +1,179 @@
-# 验收标准编写指南
-
-> 如何生成高质量、可验证的步骤级验收标准。步骤级验收标准是 task-decomposition SKILL 的核心产出之一，直接影响 acceptance-check SKILL 的准出评估准确性。
-
----
-
-## 1. 核心原则
-
-> **每条标准必须能通过检查文件、执行命令或人工审查来判定 pass/fail。**
-
-- ❌ `"分析完成"` — 无法判定"完成"的定义
-- ❌ `"代码质量好"` — "好"是主观的
-- ✅ `"分析报告文件 analysis-report.md 已生成且非空（≥1KB）"` — 可检查文件大小
-- ✅ `"编译无 error 级别错误"` — 可执行编译命令检查
-
----
-
-## 2. type 分类
-
-| type | 说明 | 验证方式 | 示例 |
-|------|------|----------|------|
-| `output` | 产物检查 — 文件/内容是否存在、是否完整 | 检查文件存在性、大小、格式 | "分析报告文件已生成且可解析" |
-| `quality` | 质量要求 — 产物质量是否达标 | 内容审查、规则匹配 | "报告覆盖所有关键维度" |
-| `performance` | 性能指标 — 定量指标 | 执行命令获取数值 | "扫描覆盖率 ≥ 80%" |
-| `compliance` | 合规性 — 是否符合规范 | 规范比对、lint 检查 | "代码符合 ArkTS 编码规范" |
-
----
-
-## 3. ID 命名规则
-
-步骤级验收标准的 ID 格式为 `ac{stepId}_{序号}`：
-
-| 步骤 | 序号 | ID |
-|------|------|----|
-| 步骤1 | 第1条 | `ac1_1` |
-| 步骤1 | 第2条 | `ac1_2` |
-| 步骤2 | 第1条 | `ac2_1` |
-| 步骤3 | 第3条 | `ac3_3` |
-
----
-
-## 4. taskACIds 追溯字段
-
-`taskACIds` 建立步骤级标准 → 任务级标准的追溯关系：
-
-```json
-{
-  "id": "ac1_1",
-  "criterion": "分析报告文件 analysis-report.md 已生成且非空",
-  "type": "output",
-  "verification": "检查 ${taskDir}/analysis-report.md 文件是否存在且文件大小 > 0",
-  "taskACIds": ["ac1"]
-}
-```
-
-**设计意图**：合并所有步骤的 `taskACIds` 后，应覆盖所有任务级 AC 的 ID。
-
-### 覆盖校验
-
-```
-任务级 AC: ac1, ac2, ac3, ac4
-
-步骤1 AC.taskACIds: ["ac1", "ac2"]     → 覆盖 ac1, ac2
-步骤2 AC.taskACIds: ["ac2", "ac3"]     → 覆盖 ac2, ac3
-步骤3 AC.taskACIds: ["ac3", "ac4"]     → 覆盖 ac3, ac4
-
-合并覆盖: ac1, ac2, ac3, ac4 ✅ 全覆盖
-```
-
-> 允许一条步骤级 AC 关联多个任务级 AC（如上例 ac2_1 同时关联 ac2 和 ac3）。
-> 也允许多条步骤级 AC 关联同一个任务级 AC（不同步骤从不同角度验证同一任务级标准）。
-
----
-
-## 5. 每条标准必含字段
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `id` | ✅ | 格式 `ac{stepId}_{序号}` |
-| `criterion` | ✅ | 具体标准描述，非空，可验证 |
-| `type` | ✅ | `output`/`quality`/`performance`/`compliance` |
-| `verification` | ✅ | 验证方式（具体到可执行命令或检查方法） |
-| `taskACIds` | ✅ | 关联的任务级标准 ID 列表（如 `["ac1"]`） |
-
----
-
-## 6. 编写模式
-
-### 6.1 产物检查模式
-
-```
-criterion: "{文件名} 已生成且 {条件}"
-type: "output"
-verification: "检查 {路径} 文件存在，且 {验证条件}"
-taskACIds: ["ac1"]
-```
-
-### 6.2 覆盖率模式
-
-```
-criterion: "{指标} ≥ {阈值}"
-type: "performance"
-verification: "执行 {命令}，解析输出获取 {指标}，判断 ≥ {阈值}"
-taskACIds: ["ac3"]
-```
-
-### 6.3 规范合规模式
-
-```
-criterion: "{产物} 符合 {规范名}"
-type: "compliance"
-verification: "运行 {lint/check工具}，检查 {规则} 错误数为 0"
-taskACIds: ["ac2"]
-```
-
-### 6.4 内容完整性模式
-
-```
-criterion: "{产物} 包含 {必要内容列表}"
-type: "quality"
-verification: "读取 {产物}，逐项检查 {内容项} 均存在且非空"
-taskACIds: ["ac1", "ac4"]
-```
-
----
-
-## 7. 好的验收标准示例
-
-```json
-{
-  "id": "ac1_1",
-  "criterion": "分析报告文件 analysis-report.md 已生成且非空",
-  "type": "output",
-  "verification": "检查 ${taskDir}/analysis-report.md 文件是否存在且文件大小 > 0",
-  "taskACIds": ["ac1"]
-}
-```
-
-```json
-{
-  "id": "ac2_1",
-  "criterion": "编译无 error 级别错误，warning 数量 ≤ 10",
-  "type": "compliance",
-  "verification": "执行编译命令，检查 stderr 中无 'error' 关键字，统计 'warning' 出现次数 ≤ 10",
-  "taskACIds": ["ac2", "ac3"]
-}
-```
-
----
-
-## 8. 差的验收标准示例
-
-```json
-{
-  "id": "ac1_1",
-  "criterion": "分析完成"
-}
-```
-
-**问题**：无法验证、缺少 type/verification/taskACIds 字段。
-
-```json
-{
-  "criterion": "代码质量好",
-  "type": "quality",
-  "verification": "人工检查"
-}
-```
-
-**问题**：标准模糊、验证方式不可自动化、缺少 id 和 taskACIds。
-
----
-
-## 9. 数量建议
-
-- 每个步骤通常 1-3 条验收标准
-- 关键步骤可增加到 3-5 条
-- 简单步骤（如报告生成）1 条即可
-- 总数不宜过多，避免审核成本过高
+# 验收标准编写指南
+
+> 如何生成高质量、可验证的步骤级验收标准。步骤级验收标准是 task-decomposition SKILL 的核心产出之一，直接影响 acceptance-check SKILL 的准出评估准确性。
+
+---
+
+## 1. 核心原则
+
+> **每条标准必须能通过检查文件、执行命令或人工审查来判定 pass/fail。**
+
+- ❌ `"分析完成"` — 无法判定"完成"的定义
+- ❌ `"代码质量好"` — "好"是主观的
+- ✅ `"分析报告文件 analysis-report.md 已生成且非空（≥1KB）"` — 可检查文件大小
+- ✅ `"编译无 error 级别错误"` — 可执行编译命令检查
+
+---
+
+## 2. type 分类
+
+| type | 说明 | 验证方式 | 示例 |
+|------|------|----------|------|
+| `output` | 产物检查 — 文件/内容是否存在、是否完整 | 检查文件存在性、大小、格式 | "分析报告文件已生成且可解析" |
+| `quality` | 质量要求 — 产物质量是否达标 | 内容审查、规则匹配 | "报告覆盖所有关键维度" |
+| `performance` | 性能指标 — 定量指标 | 执行命令获取数值 | "扫描覆盖率 ≥ 80%" |
+| `compliance` | 合规性 — 是否符合规范 | 规范比对、lint 检查 | "代码符合 ArkTS 编码规范" |
+
+---
+
+## 3. ID 命名规则
+
+步骤级验收标准的 ID 格式为 `ac{stepId}_{序号}`：
+
+| 步骤 | 序号 | ID |
+|------|------|----|
+| 步骤1 | 第1条 | `ac1_1` |
+| 步骤1 | 第2条 | `ac1_2` |
+| 步骤2 | 第1条 | `ac2_1` |
+| 步骤3 | 第3条 | `ac3_3` |
+
+---
+
+## 4. taskACIds 追溯字段
+
+`taskACIds` 建立步骤级标准 → 任务级标准的追溯关系：
+
+```json
+{
+  "id": "ac1_1",
+  "criterion": "分析报告文件 analysis-report.md 已生成且非空",
+  "type": "output",
+  "verification": "检查 ${taskDir}/analysis-report.md 文件是否存在且文件大小 > 0",
+  "taskACIds": ["ac1"]
+}
+```
+
+**设计意图**：合并所有步骤的 `taskACIds` 后，应覆盖所有任务级 AC 的 ID。
+
+### 覆盖校验
+
+```
+任务级 AC: ac1, ac2, ac3, ac4
+
+步骤1 AC.taskACIds: ["ac1", "ac2"]     → 覆盖 ac1, ac2
+步骤2 AC.taskACIds: ["ac2", "ac3"]     → 覆盖 ac2, ac3
+步骤3 AC.taskACIds: ["ac3", "ac4"]     → 覆盖 ac3, ac4
+
+合并覆盖: ac1, ac2, ac3, ac4 ✅ 全覆盖
+```
+
+> 允许一条步骤级 AC 关联多个任务级 AC（如上例 ac2_1 同时关联 ac2 和 ac3）。
+> 也允许多条步骤级 AC 关联同一个任务级 AC（不同步骤从不同角度验证同一任务级标准）。
+
+---
+
+## 5. 每条标准必含字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | ✅ | 格式 `ac{stepId}_{序号}` |
+| `criterion` | ✅ | 具体标准描述，非空，可验证 |
+| `type` | ✅ | `output`/`quality`/`performance`/`compliance` |
+| `verification` | ✅ | 验证方式（具体到可执行命令或检查方法） |
+| `taskACIds` | ✅ | 关联的任务级标准 ID 列表（如 `["ac1"]`） |
+
+---
+
+## 6. 编写模式
+
+### 6.1 产物检查模式
+
+```
+criterion: "{文件名} 已生成且 {条件}"
+type: "output"
+verification: "检查 {路径} 文件存在，且 {验证条件}"
+taskACIds: ["ac1"]
+```
+
+### 6.2 覆盖率模式
+
+```
+criterion: "{指标} ≥ {阈值}"
+type: "performance"
+verification: "执行 {命令}，解析输出获取 {指标}，判断 ≥ {阈值}"
+taskACIds: ["ac3"]
+```
+
+### 6.3 规范合规模式
+
+```
+criterion: "{产物} 符合 {规范名}"
+type: "compliance"
+verification: "运行 {lint/check工具}，检查 {规则} 错误数为 0"
+taskACIds: ["ac2"]
+```
+
+### 6.4 内容完整性模式
+
+```
+criterion: "{产物} 包含 {必要内容列表}"
+type: "quality"
+verification: "读取 {产物}，逐项检查 {内容项} 均存在且非空"
+taskACIds: ["ac1", "ac4"]
+```
+
+---
+
+## 7. 好的验收标准示例
+
+```json
+{
+  "id": "ac1_1",
+  "criterion": "分析报告文件 analysis-report.md 已生成且非空",
+  "type": "output",
+  "verification": "检查 ${taskDir}/analysis-report.md 文件是否存在且文件大小 > 0",
+  "taskACIds": ["ac1"]
+}
+```
+
+```json
+{
+  "id": "ac2_1",
+  "criterion": "编译无 error 级别错误，warning 数量 ≤ 10",
+  "type": "compliance",
+  "verification": "执行编译命令，检查 stderr 中无 'error' 关键字，统计 'warning' 出现次数 ≤ 10",
+  "taskACIds": ["ac2", "ac3"]
+}
+```
+
+---
+
+## 8. 差的验收标准示例
+
+```json
+{
+  "id": "ac1_1",
+  "criterion": "分析完成"
+}
+```
+
+**问题**：无法验证、缺少 type/verification/taskACIds 字段。
+
+```json
+{
+  "criterion": "代码质量好",
+  "type": "quality",
+  "verification": "人工检查"
+}
+```
+
+**问题**：标准模糊、验证方式不可自动化、缺少 id 和 taskACIds。
+
+---
+
+## 9. 数量建议
+
+- 每个步骤通常 1-3 条验收标准
+- 关键步骤可增加到 3-5 条
+- 简单步骤（如报告生成）1 条即可
+- 总数不宜过多，避免审核成本过高

package/vendor/Server/Skills/task-decomposition/references/DEPENDENCY_GRAPH_GUIDE.md

@@ -1,152 +1,152 @@
-# 依赖图设计指南
-
-> 如何设计高质量的步骤依赖图。依赖图是 task-decomposition SKILL 的核心产出，直接决定 Orchestrator 的调度行为。
-
----
-
-## 1. 图字段定义
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `dependId` | number | 当前步骤依赖哪个步骤（0 = 入口步骤，无前置依赖；-1 = 修复步骤哨兵，仅由 failStepId 触发） |
-| `nextStepId` | number | 成功后执行哪个步骤（0 = 终止，任务完成） |
-| `failStepId` | number | 失败后跳转到哪个步骤（0 = 失败即终止） |
-| `maxRetries` | number | 单个步骤的最大重试次数（默认 3） |
-
----
-
-## 2. 基本图结构
-
-### 2.1 线性流程
-
-```
-步骤1 (入口, dependId=0)
-  → 成功 → 步骤2 (dependId=1)
-  → 失败 → 终止 (failStepId=0)
-
-步骤2
-  → 成功 → 步骤3 (dependId=2)
-  → 失败 → 终止
-
-步骤3 (终止, nextStepId=0)
-```
-
-### 2.2 带失败回退的流程
-
-```
-步骤1 (入口)
-  ├─ 成功 → 步骤2
-  └─ 失败 → 步骤3 (回退/修复, dependId=-1)
-
-步骤2
-  ├─ 成功 → 步骤4 (终止)
-  └─ 失败 → 步骤3
-
-步骤3 (修复步骤, dependId=-1)
-  ├─ 成功 → 步骤2 (重试)
-  └─ 失败 → 步骤4 (终止)
-
-步骤4 (终止, nextStepId=0)
-```
-
-> ⚠️ **修复步骤 `dependId` 必须设为 `-1`（强制约定）**：被某步骤 `failStepId` 指向的修复步骤（如上例步骤 3），其 `dependId` **必须设为 `-1`**——表示"仅由 failStepId 触发、无入口身份、无并行依赖"。**不能设为 0 或空**：0 或空会被 Orchestrator 与校验脚本误判为"入口步骤"，导致修复步骤与任务真实入口一步骤并行启动、提前误执行。修复成功后通过 `nextStepId` 指回触发它的步骤（如上例 `步骤3.nextStepId=2`），配合 `maxRetries` 形成有限重试循环。
->
-> `dependId=-1` 语义上等价于"无成功依赖"，但显式标记了修复身份，区别于普通入口步骤的 `dependId=0`。Brain 生成侧 `sanitizeFixChainDependId` 会自动将修复步骤的 dependId 规范化为 `-1`，LLM 原始输出无需手工设置此字段。
-
-### 2.3 并行执行流程
-
-```
-步骤1 (入口)
-  ├─ 成功 → 步骤2 和 步骤3 同时执行
-  └─ 失败 → 终止
-
-步骤2 (dependId=1) ──┐
-                      ├─ 都成功 → 步骤4 (终止)
-步骤3 (dependId=1) ──┘
-
-步骤4 (终止, nextStepId=0)
-```
-
-> 并行条件：多个步骤的 `dependId` 指向同一个步骤，Orchestrator 会在前置步骤成功后并行执行。
-
----
-
-## 3. 常见任务拆解模板
-
-> 常见任务拆解模板已拆分至 [常见任务拆解模板](TASK_DECOMPOSITION_TEMPLATES.md)
-
----
-
-## 4. maxRetries 设置指南
-
-所有步骤统一使用 `maxRetries = 3`，保证执行稳定性与重试兜底的一致性。
-
----
-
-## 5. 图结构校验规则
-
-拆解完成后，Brain 会对结果进行以下校验：
-
-| # | 校验项 | 规则 |
-|---|--------|------|
-| 1 | stepId 唯一性 | 不允许重复的步骤 ID |
-| 2 | 入口步骤存在 | 至少有一个 `dependId=0` 的步骤（`dependId=-1` 的修复步骤不计入入口） |
-| 3 | 终止步骤存在 | 至少有一个 `nextStepId=0` 的步骤 |
-| 4 | 引用有效性 | `dependId`/`nextStepId`/`failStepId` 引用的 stepId 必须存在（0 与 -1 除外，-1 为修复步骤哨兵） |
-| 5 | 描述非空 | 每个步骤的 `taskDescription` 不能为空字符串 |
-
-### 死锁校验规则（`validate-step-graph.cjs`，强制）
-
-除上述字段级校验外，拆解输出**必须**通过 `node scripts/validate-step-graph.cjs <resultFile>` 的死锁校验，检测项：
-
-| # | 校验项 | 规则 | 反例 |
-|---|--------|------|------|
-| 1 | 成功链环（nextStepId） | `nextStepId` 边不能成环 | `step4→step5→step4` |
-| 2 | 失败链环（failStepId） | `failStepId` 边不能成环；自身回退 `failStepId==自己` 配合 `maxRetries` 合法 | `A 失败→B`、`B 失败→A` |
-| 3 | 依赖环（dependId） | `dependId` 边不能成环 | `A 依赖 B`、`B 依赖 A` |
-| 4 | 可达性 | 所有步骤必须从入口沿 `nextStepId` 链可达 | 孤立步骤（无任何 nextStepId 指向它） |
-| 5 | 成功链终止 | 至少一个步骤 `nextStepId=0` | 所有 nextStepId 均非 0 |
-
-任一项不通过则脚本非零退出，**必须修正步骤图后重新校验直至全部通过**。
-
----
-
-## 6. 反模式
-
-### 6.1 死循环
-
-**失败链死循环：**
-```
-步骤1 → 失败 → 步骤2
-步骤2 → 失败 → 步骤1   ← 无限循环！
-```
-
-**成功链死循环（toggle 死锁）：**
-```
-步骤4 → 成功 → 步骤5
-步骤5 → 成功 → 步骤4   ← 成功后永远无法结束，死锁！
-```
-
-**修复**：确保 failStepId / nextStepId 链最终能到达终止步骤，配合 maxRetries 限制。
-
-> **强制校验**：以上死锁由 `node scripts/validate-step-graph.cjs <resultFile>` 强制检测，检测到环/孤立步骤/无终止时脚本非零退出，必须修正后重新校验直至通过。
-
-### 6.2 孤立步骤
-
-```
-步骤1 → 成功 → 步骤3
-步骤2 (dependId=0, 但没有任何步骤指向它)  ← 永远不会被执行
-```
-
-**修复**：确保每个步骤要么是入口，要么被某个步骤的 nextStepId/failStepId 引用。
-
-### 6.3 步骤过细
-
-```
-步骤1: git clone
-步骤2: cd 进入目录
-步骤3: ls 查看文件
-步骤4: cat README
-```
-
-**修复**：合并为一个"获取源码并分析结构"步骤。
+# 依赖图设计指南
+
+> 如何设计高质量的步骤依赖图。依赖图是 task-decomposition SKILL 的核心产出，直接决定 Orchestrator 的调度行为。
+
+---
+
+## 1. 图字段定义
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `dependId` | number | 当前步骤依赖哪个步骤（0 = 入口步骤，无前置依赖；-1 = 修复步骤哨兵，仅由 failStepId 触发） |
+| `nextStepId` | number | 成功后执行哪个步骤（0 = 终止，任务完成） |
+| `failStepId` | number | 失败后跳转到哪个步骤（0 = 失败即终止） |
+| `maxRetries` | number | 单个步骤的最大重试次数（默认 3） |
+
+---
+
+## 2. 基本图结构
+
+### 2.1 线性流程
+
+```
+步骤1 (入口, dependId=0)
+  → 成功 → 步骤2 (dependId=1)
+  → 失败 → 终止 (failStepId=0)
+
+步骤2
+  → 成功 → 步骤3 (dependId=2)
+  → 失败 → 终止
+
+步骤3 (终止, nextStepId=0)
+```
+
+### 2.2 带失败回退的流程
+
+```
+步骤1 (入口)
+  ├─ 成功 → 步骤2
+  └─ 失败 → 步骤3 (回退/修复, dependId=-1)
+
+步骤2
+  ├─ 成功 → 步骤4 (终止)
+  └─ 失败 → 步骤3
+
+步骤3 (修复步骤, dependId=-1)
+  ├─ 成功 → 步骤2 (重试)
+  └─ 失败 → 步骤4 (终止)
+
+步骤4 (终止, nextStepId=0)
+```
+
+> ⚠️ **修复步骤 `dependId` 必须设为 `-1`（强制约定）**：被某步骤 `failStepId` 指向的修复步骤（如上例步骤 3），其 `dependId` **必须设为 `-1`**——表示"仅由 failStepId 触发、无入口身份、无并行依赖"。**不能设为 0 或空**：0 或空会被 Orchestrator 与校验脚本误判为"入口步骤"，导致修复步骤与任务真实入口一步骤并行启动、提前误执行。修复成功后通过 `nextStepId` 指回触发它的步骤（如上例 `步骤3.nextStepId=2`），配合 `maxRetries` 形成有限重试循环。
+>
+> `dependId=-1` 语义上等价于"无成功依赖"，但显式标记了修复身份，区别于普通入口步骤的 `dependId=0`。Brain 生成侧 `sanitizeFixChainDependId` 会自动将修复步骤的 dependId 规范化为 `-1`，LLM 原始输出无需手工设置此字段。
+
+### 2.3 并行执行流程
+
+```
+步骤1 (入口)
+  ├─ 成功 → 步骤2 和 步骤3 同时执行
+  └─ 失败 → 终止
+
+步骤2 (dependId=1) ──┐
+                      ├─ 都成功 → 步骤4 (终止)
+步骤3 (dependId=1) ──┘
+
+步骤4 (终止, nextStepId=0)
+```
+
+> 并行条件：多个步骤的 `dependId` 指向同一个步骤，Orchestrator 会在前置步骤成功后并行执行。
+
+---
+
+## 3. 常见任务拆解模板
+
+> 常见任务拆解模板已拆分至 [常见任务拆解模板](TASK_DECOMPOSITION_TEMPLATES.md)
+
+---
+
+## 4. maxRetries 设置指南
+
+所有步骤统一使用 `maxRetries = 3`，保证执行稳定性与重试兜底的一致性。
+
+---
+
+## 5. 图结构校验规则
+
+拆解完成后，Brain 会对结果进行以下校验：
+
+| # | 校验项 | 规则 |
+|---|--------|------|
+| 1 | stepId 唯一性 | 不允许重复的步骤 ID |
+| 2 | 入口步骤存在 | 至少有一个 `dependId=0` 的步骤（`dependId=-1` 的修复步骤不计入入口） |
+| 3 | 终止步骤存在 | 至少有一个 `nextStepId=0` 的步骤 |
+| 4 | 引用有效性 | `dependId`/`nextStepId`/`failStepId` 引用的 stepId 必须存在（0 与 -1 除外，-1 为修复步骤哨兵） |
+| 5 | 描述非空 | 每个步骤的 `taskDescription` 不能为空字符串 |
+
+### 死锁校验规则（`validate-step-graph.cjs`，强制）
+
+除上述字段级校验外，拆解输出**必须**通过 `node scripts/validate-step-graph.cjs <resultFile>` 的死锁校验，检测项：
+
+| # | 校验项 | 规则 | 反例 |
+|---|--------|------|------|
+| 1 | 成功链环（nextStepId） | `nextStepId` 边不能成环 | `step4→step5→step4` |
+| 2 | 失败链环（failStepId） | `failStepId` 边不能成环；自身回退 `failStepId==自己` 配合 `maxRetries` 合法 | `A 失败→B`、`B 失败→A` |
+| 3 | 依赖环（dependId） | `dependId` 边不能成环 | `A 依赖 B`、`B 依赖 A` |
+| 4 | 可达性 | 所有步骤必须从入口沿 `nextStepId` 链可达 | 孤立步骤（无任何 nextStepId 指向它） |
+| 5 | 成功链终止 | 至少一个步骤 `nextStepId=0` | 所有 nextStepId 均非 0 |
+
+任一项不通过则脚本非零退出，**必须修正步骤图后重新校验直至全部通过**。
+
+---
+
+## 6. 反模式
+
+### 6.1 死循环
+
+**失败链死循环：**
+```
+步骤1 → 失败 → 步骤2
+步骤2 → 失败 → 步骤1   ← 无限循环！
+```
+
+**成功链死循环（toggle 死锁）：**
+```
+步骤4 → 成功 → 步骤5
+步骤5 → 成功 → 步骤4   ← 成功后永远无法结束，死锁！
+```
+
+**修复**：确保 failStepId / nextStepId 链最终能到达终止步骤，配合 maxRetries 限制。
+
+> **强制校验**：以上死锁由 `node scripts/validate-step-graph.cjs <resultFile>` 强制检测，检测到环/孤立步骤/无终止时脚本非零退出，必须修正后重新校验直至通过。
+
+### 6.2 孤立步骤
+
+```
+步骤1 → 成功 → 步骤3
+步骤2 (dependId=0, 但没有任何步骤指向它)  ← 永远不会被执行
+```
+
+**修复**：确保每个步骤要么是入口，要么被某个步骤的 nextStepId/failStepId 引用。
+
+### 6.3 步骤过细
+
+```
+步骤1: git clone
+步骤2: cd 进入目录
+步骤3: ls 查看文件
+步骤4: cat README
+```
+
+**修复**：合并为一个"获取源码并分析结构"步骤。