@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +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
+```
+
+**修复**：合并为一个"获取源码并分析结构"步骤。

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

@@ -0,0 +1,175 @@
+# 集成上下文说明
+
+> task-decomposition SKILL 在 AI Loop 系统中的完整调用链路与消费方式。理解本文件有助于编写更贴合实际执行的 SKILL 指令。
+
+---
+
+## 1. 调用链路
+
+```
+LoopEngine.startLoop()
+  └─ _runBrain()
+       ├─ 首轮 (loop=0):  Brain.planTask()
+       │     ├─ AnalysisStrategies.analyzeTask()          ← 上游：task-analysis
+       │     └─ DecompositionStrategies.decomposeTask()   ← 本 SKILL
+       │           ├─ _decomposeViaCLI()                   ← 主路径（opencode CLI 执行本 SKILL）
+       │           └─ _decomposeViaLLM()                   ← 降级路径（直接 LLM 调用，读 SKILL.md 作为指令）
+       │
+       └─ 后续轮 (loop>0): Brain.replanTask()
+             └─ DecompositionStrategies.decomposeTaskWithContext()
+                   ├─ _decomposeWithContextViaCLI()        ← 重规划路径（CLI 执行本 SKILL）
+                   └── _decomposeWithContextViaLLM()       ← 降级路径
+```
+
+---
+
+## 2. SkillExecutor 调用机制
+
+`SkillExecutor.invokeSkill(skillDir, workDir, resultFilePath, title, contextSections)` 的工作流程：
+
+1. `cli.checkHealth()` — 检查 opencode 服务可用性
+2. `fs.mkdirSync(workDir, {recursive:true})` — 确保工作目录存在（关键：opencode `realPath` 会静默失败）
+3. `buildSkillPrompt()` — 构建 prompt（SKILL 目录 + 工作目录 + 结果路径 + 上下文段落）
+4. `cli.startSession(title, prompt)` — 创建 opencode Session
+5. `pollSession()` — 每 5s 轮询，超时 30 分钟
+6. `readSkillResult(resultFilePath)` — 读取 JSON 结果文件
+
+opencode 收到 prompt 后会读取 SKILL.md 并按指令执行。
+
+---
+
+## 3. Prompt 注入的上下文段落
+
+### 3.1 首轮拆解
+
+调用方（`_decomposeViaCLI`）注入：
+- `## SKILL 目录` — `{skillDir}/task-decomposition`
+- `## 工作目录` — `{taskDir}`
+- `## 结果文件输出路径` — `{taskDir}/brain_decomposition_loop{N}.json`
+- `## 任务描述` — `{taskDescription}`
+- `## 任务分析结果` — task-analysis SKILL 输出（格式化的 intent/domain/keywords/constraints/techStack/complexity/estimatedSteps）
+- `## 验收标准` — 任务级验收标准列表（`[ac1] (type) criterion → 验证: verification`）
+
+> 可用执行 SKILL 列表**不注入**：由本 SKILL 的 `scripts/list-available-skills.cjs` 在拆解时实时扫描获取（黑名单过滤），系统侧（Brain）不硬编码任何 SKILL 清单。
+
+### 3.2 重规划拆解
+
+调用方（`_decomposeWithContextViaCLI`）在首轮基础上额外注入：
+- `## 重规划上下文` — "当前是第 N 轮重规划"
+- `## 上一轮审核摘要` — `prevCheckSummary`
+- `## 未满足的验收标准` — failedCriteria 列表（含 id/criterion/reason）
+- `## 改进建议` — improvementSuggestions 列表
+- `## 重拆解要求` — 固定指令
+
+---
+
+## 4. 结果消费链路
+
+### 4.1 JSON 读取与容错
+
+`SkillExecutor.readSkillResult(resultFilePath)`：
+- 读取文件内容
+- 用 `indexOf('{')` / `lastIndexOf('}')` 提取 JSON（容忍 markdown 包裹）
+- `JSON.parse` 解析
+- 返回 `{ success, json, raw }`
+
+> 即使被 markdown 代码块包裹也能解析，但 SKILL 应输出纯 JSON，不依赖容错。
+
+### 4.2 规范化
+
+`DecompositionStrategies.normalizeSteps(rawSteps)` 对字段兜底：
+
+| 字段 | 兜底值 |
+|------|--------|
+| `stepId` | 保持原值 |
+| `taskDescription` | `''` |
+| `dependId` | `0` |
+| `nextStepId` | `0` |
+| `failStepId` | `0` |
+| `maxRetries` | `3` |
+| `acceptanceCriteria` | `[]` |
+
+### 4.3 下游消费 — Brain
+
+`Brain.planTask` / `replanTask` 将步骤组装为 `taskDef`：
+
+```js
+taskDef = {
+    taskId, taskDir, skillDirectory,
+    acceptanceCriteria: analysis.acceptanceCriteria || [],  // 任务级 AC
+    loopCount: 0,
+    steps: rawSteps.map(s => ({
+        stepId: s.stepId,
+        taskDescription: s.taskDescription,
+        specifiedSkill: s.specifiedSkill || '',             // 步骤绑定的执行 SKILL（可选）
+        dependId: s.dependId ?? 0,
+        nextStepId: s.nextStepId ?? 0,
+        failStepId: s.failStepId ?? 0,
+        maxRetries: s.maxRetries ?? 3,
+        acceptanceCriteria: s.acceptanceCriteria || []
+    }))
+};
+```
+
+> `specifiedSkill` 由拆解时匹配可用 SKILL 列表产生（Phase 1.5 实时扫描 + Phase 2.4 绑定规则），经 `normalizeSteps` 透传（非字符串归一为空串），空串表示未绑定、由 SkillSelector 运行时自动匹配。
+
+重规划时额外记录：
+```js
+taskDef.replanInfo = {
+    loopCount,
+    previousCheckId,
+    failedCriteriaCount,
+    improvementSuggestions
+};
+```
+
+### 4.4 下游消费 — Orchestrator
+
+`Orchestrator.loadTask(taskDef)` 构建 `StepNode` 图：
+
+- **只消费图字段**：`stepId`、`taskDescription`、`dependId`、`nextStepId`、`failStepId`、`maxRetries`、`specifiedSkill`（透传给 FlexRunner）
+- **不消费 `acceptanceCriteria`**：StepNode 构造函数未声明 acceptanceCriteria 实例属性，通过 `...stepDef` 展开后被丢弃
+- **调度逻辑**：
+  - 入口步骤 = `dependId === '0'` 或 dependId 指向不存在节点
+  - 并行执行 = 所有 READY 节点 `Promise.all`
+  - 成功 → 激活 `nextStepId`；失败（重试耗尽）→ 激活 `failStepId`
+  - 循环检测 = `_execPathTrace` Set，重复 stepId → `markBlocked`
+  - 全局上限 = `GLOBAL_EXEC_LIMIT = 200`
+
+`specifiedSkill` 的执行链路：StepNode → `Orchestrator._createFlexRunner` → `FlexRunner.initContext({ specifiedSkill })` → `executeStart` 中 `_resolveSpecifiedSkill` 直接解析该 SKILL（目录名精确匹配优先，其次 frontmatter name 匹配），跳过 SkillSelector 自动匹配；解析失败降级为无 SKILL 模式。
+
+### 4.5 下游消费 — TestCheck / acceptance-check
+
+```
+LoopEngine._runTestCheck()
+  └─ TestCheck.runCheck({ acceptanceCriteria: 任务级AC, orchestratorResult, ... })
+       └─ SkillSelector 匹配 acceptance-check
+            └─ 读取 stepId{N}_result_{loop}.md 产物（FlexRunner 写入）
+            └─ 按 stepId 分组形成产物清单
+            └─ LLM 评估每条任务级 AC → criteriaResults[{id, satisfied, evidence}]
+```
+
+**步骤级 AC 的实际消费路径**：
+- 步骤级 `acceptanceCriteria` 不被 Orchestrator 程序化读取
+- 步骤执行时 FlexRunner 生成 `stepId{N}_result_{loop}.md` 产物文件
+- acceptance-check SKILL 收集这些产物后，参考步骤级 AC 做准出评估
+- `taskACIds` 追溯字段目前仅作为 SKILL 指令中的文档性约束，无代码程序化读取
+
+---
+
+## 5. 两层验收标准体系
+
+| 层级 | 来源 | ID 格式 | 消费者 |
+|------|------|---------|--------|
+| **任务级** `acceptanceCriteria[]` | task-analysis SKILL 输出 → Brain 写入 taskDef | `ac1, ac2...` | TestCheck（准出审核） |
+| **步骤级** `acceptanceCriteria[]` | task-decomposition SKILL 每步生成 | `ac{stepId}_{n}` 如 `ac1_1` | acceptance-check（产物收集时按 stepId 分组） |
+
+设计意图：合并所有步骤 AC 的 `taskACIds` 后应覆盖所有任务级 AC ID。
+
+---
+
+## 6. 结果文件命名
+
+- 首轮：`brain_decomposition_loop0.json`
+- 第1轮重规划：`brain_decomposition_loop1.json`
+- 第N轮：`brain_decomposition_loop{N}.json`

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

@@ -0,0 +1,195 @@
+# 重规划上下文处理指南
+
+> 重规划场景下如何处理上一轮失败信息，调整步骤设计与验收标准。重规划由 LoopEngine 触发：当 TestCheck 准出审核未通过时，进入下一轮循环，调用 `decomposeTaskWithContext`。
+
+---
+
+## 1. 重规划触发条件
+
+```
+LoopEngine 大循环:
+  Round 0: Brain.planTask → Orchestrator → TestCheck
+    ├─ passed=true  → PASSED, 结束
+    └─ passed=false → currentLoop++ → Round 1
+  Round 1: Brain.replanTask → Orchestrator → TestCheck
+    ├─ passed=true  → PASSED, 结束
+    └─ passed=false → currentLoop++ → Round 2
+  ... 直到 currentLoop >= maxLoops (默认3) → FAILED
+```
+
+---
+
+## 2. 重规划上下文字段
+
+重规划时，调用方通过 contextSections 注入以下信息：
+
+| 上下文段落 | 内容 | 来源 |
+|------------|------|------|
+| `## 重规划上下文` | "当前是第 N 轮重规划" | loopCount |
+| `## 上一轮审核摘要` | 审核结果总结 | prevCheckSummary |
+| `## 上一轮步骤执行详情` | 已完成步骤(含产物路径) + 失败步骤(含原因) + 未执行步骤 | completedSteps / failedSteps / pendingSteps |
+| `## 未满足的验收标准` | 失败标准列表（id + criterion + reason） | failedCriteria |
+| `## 改进建议` | 上轮建议列表 | improvementSuggestions |
+| `## 重拆解要求` | 固定指令 | 固定文本 |
+
+### completedSteps / failedSteps / pendingSteps 结构
+
+上一轮步骤执行详情包含三类步骤：
+
+**已完成的步骤**（无需重做，产物可直接引用）：
+```
+- 步骤3: 源码分析与分析报告生成
+    产物: db/task/task_xxx/stepId3_loop0_result_0.md
+```
+
+**失败的步骤**（需重点修复或替代方案）：
+```
+- 步骤8: JS Bundle 加载验证
+    失败原因: JS Bundle loading failure
+    部分产物: db/task/task_xxx/stepId8_loop0_result_0.md
+```
+
+**未执行的步骤**（因依赖步骤失败而未执行）：
+```
+- 步骤9: 生成升级文档
+```
+
+### failedCriteria 结构
+
+每条未满足标准包含：
+```
+- [ac1] 标准描述 → 原因: 失败原因/证据
+```
+
+---
+
+## 3. 重拆解要求
+
+1. **保持原始任务目标不变** — 不修改任务的核心意图
+2. **已完成的步骤无需重新执行** — 已完成步骤的产物已生成且可用，重拆解时不应再包含这些步骤，但在新步骤描述中应注明引用了上一轮哪个步骤的产物（如"基于上一轮步骤3的产物…"）
+3. **针对失败的步骤和未满足的标准，调整相关步骤** — 使步骤描述更明确，或新增替代步骤
+4. **增加验证步骤** — 强化对失败点的验证
+5. **考虑改进建议** — 新增必要的步骤
+6. **保持依赖关系合理** — 步骤间依赖关系需逻辑自洽
+7. **新步骤 ID 从 1 开始重新编号** — 但在步骤描述中注明引用了上一轮哪个步骤的产物
+
+### 已完成步骤复用原则
+
+重拆解时遵循以下原则复用上一轮已完成的工作：
+
+1. **识别可复用的产物** — 检查上一轮已完成步骤的 resultPath，确认产物文件是否存在
+2. **不在新计划中重复已完成步骤** — 如果上一轮步骤3"源码分析"已完成，新计划中不应再包含源码分析步骤
+3. **在新步骤中引用产物** — 新步骤的 taskDescription 中应注明"基于上一轮步骤N的产物（路径）…"
+4. **处理失败步骤** — 失败步骤可能需要拆分为更细的步骤，或换一种方法重做
+5. **处理未执行步骤** — 因依赖失败而未执行的步骤，在新计划中仍需包含，但依赖关系应指向新的前置步骤
+
+### 示例：重拆解对比
+
+**错误做法（重来一遍）：**
+```
+新步骤1: 克隆仓库并检查版本
+新步骤2: 源码分析与分析报告生成  ← 上一轮已完成，重复了！
+新步骤3: 环境配置
+新步骤4: 编译验证
+...
+```
+
+**正确做法（仅针对未完成部分）：**
+```
+新步骤1: 修复 JS Bundle 加载失败问题（基于上一轮步骤7的产物…）
+新步骤2: JS Bundle 加载验证（强化验证步骤）
+新步骤3: 设备验证（上一轮未执行步骤9）
+新步骤4: 生成升级文档（上一轮未执行步骤8）
+```
+
+---
+
+## 4. 失败原因分析框架
+
+分析失败原因时，区分以下类别：
+
+### 4.1 步骤设计问题
+
+| 原因 | 表现 | 调整 |
+|------|------|------|
+| 步骤过粗 | 一个步骤包含多个任务，部分未完成 | 拆分为多个步骤 |
+| 步骤过细 | 步骤间耦合过紧，难以独立执行 | 合并相关步骤 |
+| 步骤遗漏 | 某些必要操作未包含 | 新增步骤 |
+| 依赖错误 | 步骤执行顺序不合理 | 调整 dependId/nextStepId |
+
+### 4.2 验收标准问题
+
+| 原因 | 表现 | 调整 |
+|------|------|------|
+| 标准模糊 | verification 不明确 | 重写为具体可执行验证 |
+| 标准遗漏 | 关键维度未覆盖 | 补充新标准 |
+| 标准过严 | 正常也达不到 | 调整阈值 |
+| taskACIds 未覆盖 | 步骤级 AC 未覆盖所有任务级 AC | 补充关联 |
+
+### 4.3 执行问题
+
+| 原因 | 表现 | 调整 |
+|------|------|------|
+| SKILL 匹配失败 | 步骤描述无法匹配到执行 SKILL | 调整 taskDescription 措辞 |
+| 环境问题 | 执行环境不具备 | 记录为约束条件 |
+| 重试不足 | maxRetries 低于 3 | 统一为 3 |
+
+---
+
+## 5. 重规划调整策略示例
+
+### 场景：上轮 ac2（编译验证）未通过
+
+```
+failureAnalysis:
+  "上一轮 ac2 编译验证未通过：
+   - 失败原因：编译步骤缺少依赖安装前置步骤
+   - 根因：首轮步骤1直接编译，未安装鸿蒙 NDK"
+
+adjustmentStrategy:
+  "1. 新增步骤0：安装鸿蒙 NDK 和构建依赖
+   2. 原步骤1 dependId 改为指向新步骤
+   3. 编译步骤 maxRetries 统一为 3
+   4. ac2_1 verification 补充具体编译命令"
+```
+
+### 调整后的步骤图
+
+```
+步骤1 (新增): 安装鸿蒙 NDK 和构建依赖 (dependId=0)
+  → 成功 → 步骤2    → 失败 → 终止
+
+步骤2 (原步骤1): 源码分析 (dependId=1)
+  → 成功 → 步骤3    → 失败 → 终止
+
+步骤3: 编译验证 (dependId=2, maxRetries=3)
+  → 成功 → 步骤5    → 失败 → 步骤4
+
+步骤4: 问题修复 (dependId=3)
+  → 成功 → 步骤3(重试)  → 失败 → 步骤5
+
+步骤5: 生成报告 (终止, nextStepId=0)
+```
+
+---
+
+## 6. 保持目标一致的原则
+
+| 可调整 | 不可调整 |
+|--------|----------|
+| 步骤数量与设计 | 任务的核心意图 |
+| 步骤的 taskDescription | 任务的预期产出类型 |
+| dependId/nextStepId/failStepId | — |
+| maxRetries | — |
+| 步骤级 acceptanceCriteria | — |
+| 步骤 ID 重新编号 | — |
+
+> 如果认为任务目标本身需要修改，说明任务描述有误，应在拆解结果中标注并建议用户重新提交任务。
+
+---
+
+## 7. 重规划结果文件
+
+结果文件路径与首轮相同模式，按 loopCount 区分：
+- 首轮：`brain_decomposition_loop0.json`
+- 第1轮重规划：`brain_decomposition_loop1.json`