@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,190 @@
+# 验收标准编写指南
+
+> 如何生成高质量、可验证的验收标准。验收标准是 task-analysis SKILL 的核心产出，直接影响后续 TestCheck 准出审核的准确性。
+
+---
+
+## 1. 核心原则
+
+> **每条标准必须能通过检查文件、执行命令或人工审查来判定 pass/fail。**
+
+- ❌ `"分析完成"` — 无法判定"完成"的定义
+- ❌ `"代码质量好"` — "好"是主观的
+- ✅ `"分析报告文件已生成且非空（≥1KB）"` — 可检查文件大小
+- ✅ `"扫描覆盖率 ≥ 80%"` — 可执行命令获取数值
+
+---
+
+## 2. type 分类
+
+| type | 说明 | 验证方式 | 示例 |
+|------|------|----------|------|
+| `output` | 产物检查 — 文件/内容是否存在、是否完整 | 检查文件存在性、大小、格式 | "分析报告 JSON 文件已生成且可解析" |
+| `quality` | 质量要求 — 产物质量是否达标 | 内容审查、规则匹配 | "报告覆盖所有关键维度（intent/domain/keywords）" |
+| `performance` | 性能指标 — 定量指标 | 执行命令获取数值 | "扫描覆盖率 ≥ 80%" |
+| `compliance` | 合规性 — 是否符合规范 | 规范比对、lint 检查 | "代码符合 ArkTS 编码规范（无 arkts-no-any 错误）" |
+
+---
+
+## 3. 数量与覆盖
+
+- **数量**：通常 3-8 条
+- **覆盖维度**：
+  - 至少 1 条 `output` 类型（确保有产物）
+  - 至少 1 条 `quality` 或 `compliance` 类型（确保质量）
+  - 高性能要求任务加 `performance` 类型
+- **不宜过多**：超过 8 条会稀释重点，增加审核成本
+- **不宜过少**：少于 3 条可能遗漏关键维度
+
+---
+
+## 4. verification 字段编写
+
+`verification` 描述**如何验证**该标准是否满足，应包含具体的验证方法：
+
+### 好的 verification
+
+```
+"检查 {workDir}/analysis-report.json 文件是否存在且 JSON.parse 成功"
+```
+
+```
+"执行 hosauri lint，检查 arkts-no-any-unknown 错误数为 0"
+```
+
+```
+"读取报告 JSON，确认 acceptanceCriteria 数组长度 ≥ 3"
+```
+
+### 差的 verification
+
+```
+"人工检查"          — 太模糊，无法自动化
+"确保质量"          — 同义反复
+"检查是否完成"      — 没说怎么检查
+```
+
+---
+
+## 5. 编写模式
+
+### 5.1 产物检查模式
+
+```
+criterion: "{文件名} 已生成且 {条件}"
+type: "output"
+verification: "检查 {路径} 文件存在，且 {验证条件}"
+```
+
+### 5.2 覆盖率模式
+
+```
+criterion: "{指标} ≥ {阈值}"
+type: "performance"
+verification: "执行 {命令}，解析输出获取 {指标}，判断 ≥ {阈值}"
+```
+
+### 5.3 规范合规模式
+
+```
+criterion: "{产物} 符合 {规范名}"
+type: "compliance"
+verification: "运行 {lint/check工具}，检查 {规则} 错误数为 0"
+```
+
+### 5.4 内容完整性模式
+
+```
+criterion: "{产物} 包含 {必要内容列表}"
+type: "quality"
+verification: "读取 {产物}，逐项检查 {内容项} 均存在且非空"
+```
+
+---
+
+## 6. 反模式
+
+### 6.1 模糊标准
+
+❌ `"任务完成"` → ✅ `"{具体产物} 已生成且通过 {具体检查}"`
+
+### 6.2 不可验证的主观判断
+
+❌ `"代码可读性好"` → ✅ `"代码通过 eslint 检查，复杂度 < 15"`
+
+### 6.3 标准之间重叠
+
+❌ 同时有 `"报告已生成"` 和 `"报告文件存在"` → 合并为一条
+
+### 6.4 标准过严导致无法通过
+
+- 不要把实现细节写进验收标准（如"必须使用某某算法"）
+- 验收标准应关注 **结果**，不是 **过程**
+
+### 6.5 标准过松导致形同虚设
+
+- `"有输出文件"` 太松 → 补充 `"{文件} 非空且包含 {必要字段}"`
+
+---
+
+## 7. 重规划场景的特殊处理
+
+重规划时，验收标准生成需要额外考虑：
+
+### 7.1 调整已有标准
+
+针对未满足的标准：
+- 如果是 **验证方式不明确** → 重写 verification 使其更具体
+- 如果是 **标准过严** → 适当降低阈值或拆分为多条
+- 如果是 **标准过松** → 提高要求或补充条件
+
+### 7.2 补充新标准
+
+根据失败原因，补充覆盖上轮遗漏维度的标准。
+
+### 7.3 保持目标一致
+
+- **不修改任务目标** — 调整的是标准和策略
+- 已通过的标准可保留（下游会重新审核全部标准）
+- `failureAnalysis` 和 `adjustmentStrategy` 字段必须非空
+
+---
+
+## 8. 示例：完整验收标准集
+
+以"鸿蒙 ArkTS 三方库内存泄漏检测"任务为例：
+
+```json
+[
+  {
+    "id": "ac1",
+    "criterion": "内存泄漏分析报告 JSON 文件已生成且可解析",
+    "type": "output",
+    "verification": "检查 {workDir}/leak-analysis.json 存在，JSON.parse 成功"
+  },
+  {
+    "id": "ac2",
+    "criterion": "报告包含 intent、domain、keywords、techStack 字段且均非空",
+    "type": "quality",
+    "verification": "读取 JSON，逐字段检查存在性和非空"
+  },
+  {
+    "id": "ac3",
+    "criterion": "扫描覆盖目标库所有源文件（覆盖率 100%）",
+    "type": "performance",
+    "verification": "对比源文件列表与扫描结果，确认无遗漏"
+  },
+  {
+    "id": "ac4",
+    "criterion": "每个疑似泄漏点包含位置、类型、严重等级信息",
+    "type": "quality",
+    "verification": "读取报告中 leakPoints 数组，每条含 file/line/level 字段"
+  },
+  {
+    "id": "ac5",
+    "criterion": "分析结果符合 JSON 输出规范（纯 JSON、字段完整）",
+    "type": "compliance",
+    "verification": "运行 validate-output.sh 校验脚本，检查通过"
+  }
+]
+```

package/vendor/Server/Skills/task-analysis/references/ANALYSIS_SCHEMA.md

@@ -0,0 +1,224 @@
+# 任务分析输出 Schema
+
+> 分析结果 JSON 的完整字段规范。SKILL 执行后必须将结果写入 `resultFilePath`，格式为纯 JSON。
+
+---
+
+## 1. 完整 JSON 结构
+
+### 1.1 首轮分析输出
+
+```json
+{
+  "intent": "任务的核心意图（一句话概括）",
+  "domain": "任务所属领域",
+  "keywords": ["关键词1", "关键词2"],
+  "constraints": ["约束条件1", "约束条件2"],
+  "techStack": ["技术栈1", "技术栈2"],
+  "complexity": "low|medium|high",
+  "estimatedSteps": 3,
+  "acceptanceCriteria": [
+    {
+      "id": "ac1",
+      "criterion": "具体的验收标准描述",
+      "type": "output|quality|performance|compliance",
+      "verification": "如何验证该标准是否满足"
+    }
+  ]
+}
+```
+
+### 1.2 重规划分析输出（额外字段）
+
+首轮所有字段 **plus**：
+
+```json
+{
+  "failureAnalysis": "对上一轮失败原因的分析总结",
+  "adjustmentStrategy": "本轮的调整策略说明"
+}
+```
+
+---
+
+## 2. 字段规范
+
+### 2.1 `intent`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string |
+| 必填 | ✅ |
+| 约束 | 非空，一句话（≤100 字符推荐） |
+
+任务的核心意图概括。示例：
+- ✅ `"将 Java 三方库 X 移植到鸿蒙 ArkTS，保持核心 API 兼容"`
+- ❌ `"完成任务"` （过于模糊）
+
+### 2.2 `domain`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string |
+| 必填 | ✅ |
+| 约束 | 非空，使用 kebab-case |
+
+任务所属领域。常见值：
+
+| domain 值 | 适用场景 |
+|-----------|----------|
+| `harmonyos-porting` | 鸿蒙/ArkTS 移植 |
+| `code-quality` | 代码质量检视 |
+| `documentation` | 文档编写/检视 |
+| `testing` | 测试覆盖/测试用例 |
+| `bug-fix` | 缺陷修复 |
+| `feature` | 新功能开发 |
+| `refactoring` | 代码重构 |
+| `general` | 通用/未分类 |
+
+> 也可使用自定义值，但应保持 kebab-case 格式。
+
+### 2.3 `keywords`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string[] |
+| 必填 | ✅ |
+| 约束 | ≥1 个元素，每个非空 |
+
+关键词列表，用于后续 SKILL 匹配。应包含：
+- 技术名词（如 `ArkTS`、`grpc`、`protobuf`）
+- 动作词（如 `porting`、`audit`、`refactor`）
+- 领域词（如 `memory-leak`、`nfc`）
+
+### 2.4 `constraints`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string[] |
+| 必填 | ✅ |
+| 约束 | 可为空数组 |
+
+约束条件列表。如：
+- `"必须兼容 ArkTS 编译规则（arkts-no-any-unknown 等）"`
+- `"不能修改公共 API 签名"`
+- `"输出文件为纯 JSON"`
+
+### 2.5 `techStack`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string[] |
+| 必填 | ✅ |
+| 约束 | ≥1 个元素 |
+
+涉及的技术栈。如 `["ArkTS", "OpenHarmony", "grpc"]`。
+
+### 2.6 `complexity`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string |
+| 必填 | ✅ |
+| 枚举 | `low` / `medium` / `high` |
+
+复杂度评估标准：
+
+| 值 | 步骤数 | 跨模块 | 风险 |
+|----|--------|--------|------|
+| `low` | 1-3 | 单模块 | 低 |
+| `medium` | 4-7 | 2-3 模块 | 中 |
+| `high` | 8+ | 多模块/跨系统 | 高 |
+
+### 2.7 `estimatedSteps`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | number |
+| 必填 | ✅ |
+| 约束 | ≥1 的整数 |
+
+预估步骤数，用于 task-decomposition SKILL 参考。应与 complexity 对应。
+
+### 2.8 `acceptanceCriteria`
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | object[] |
+| 必填 | ✅ |
+| 约束 | 3-8 条，每条含 id/criterion/type/verification |
+
+每条验收标准的字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | ✅ | 从 `ac1` 开始递增 |
+| `criterion` | string | ✅ | 具体的标准描述，非空 |
+| `type` | string | ✅ | `output`/`quality`/`performance`/`compliance` |
+| `verification` | string | ✅ | 验证方式描述 |
+
+> type 分类与编写指南详见 [验收标准编写指南](../references/ACCEPTANCE_CRITERIA_GUIDE.md)
+
+### 2.9 `failureAnalysis`（仅重规划）
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string |
+| 必填 | 重规划时 ✅ |
+| 约束 | 非空（重规划场景） |
+
+对上一轮失败原因的分析总结。应：
+- 逐条分析未满足标准的失败原因
+- 区分"标准未满足"与"执行失败"
+- 指出根因（如环境问题、代码缺陷、标准过严等）
+
+### 2.10 `adjustmentStrategy`（仅重规划）
+
+| 属性 | 值 |
+|------|-----|
+| 类型 | string |
+| 必填 | 重规划时 ✅ |
+| 约束 | 非空（重规划场景） |
+
+本轮的调整策略说明。应：
+- 说明对验收标准做了哪些调整
+- 说明对预期执行路径的调整方向
+- 与改进建议对应
+
+---
+
+## 3. 输出文件规范
+
+### 3.1 格式要求
+
+- 文件必须为 **纯 JSON**（不含 markdown 代码块标记 ```` ```json ``` ``）
+- 不含任何非 JSON 内容（无注释、无前后缀文字）
+- JSON 必须是合法的可解析格式
+- 验收标准的 `id` 从 `ac1` 开始递增
+
+### 3.2 容错机制
+
+下游 `SkillExecutor.readSkillResult` 会尝试从容错提取：
+- 从首个 `{` 到末个 `}` 之间的内容
+- 即使被 markdown 代码块包裹也能解析
+
+**但仍应输出纯 JSON**，不要依赖容错机制。
+
+### 3.3 字段兜底
+
+下游 `normalizeAnalysis` 会对缺失字段兜底：
+
+| 字段 | 兜底值 |
+|------|--------|
+| `intent` | `''` |
+| `domain` | `'general'` |
+| `keywords` | `[]` |
+| `constraints` | `[]` |
+| `techStack` | `[]` |
+| `complexity` | `'medium'` |
+| `estimatedSteps` | `3` |
+| `acceptanceCriteria` | `[]`（空描述条目被过滤） |
+| `failureAnalysis` | `''` |
+| `adjustmentStrategy` | `''` |
+
+> 兜底仅是安全网，SKILL 应尽量输出完整字段，避免依赖兜底。

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

@@ -0,0 +1,162 @@
+# 集成上下文说明
+
+> task-analysis SKILL 在 AI Loop 系统中的完整调用链路与消费方式。理解本文件有助于编写更贴合实际执行的 SKILL 指令。
+
+---
+
+## 1. 调用链路
+
+```
+LoopEngine.startLoop()
+  └─ _runBrain()
+       ├─ 首轮 (loop=0):  Brain.planTask()
+       │     └─ AnalysisStrategies.analyzeTask()
+       │           ├─ _analyzeViaCLI()        ← 主路径（opencode CLI 执行本 SKILL）
+       │           └─ _analyzeViaLLM()        ← 降级路径（直接 LLM 调用，不经过 SKILL）
+       │
+       └─ 后续轮 (loop>0): Brain.replanTask()
+             └─ AnalysisStrategies.analyzeTaskWithContext()
+                   ├─ _analyzeWithContextViaCLI()  ← 重规划路径（CLI 执行本 SKILL）
+                   └─ _analyzeWithContextViaLLM()  ← 降级路径
+```
+
+---
+
+## 2. SkillExecutor 调用机制
+
+`SkillExecutor.invokeSkill(skillDir, workDir, resultFilePath, title, contextSections)` 的工作流程：
+
+1. `cli.checkHealth()` — 检查 opencode 服务可用性
+2. `fs.mkdirSync(workDir, {recursive:true})` — 确保工作目录存在
+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 首轮分析
+
+调用方（`_analyzeViaCLI`）注入：
+- `## SKILL 目录` — `{skillDir}/task-analysis`
+- `## 工作目录` — `{taskDir}`
+- `## 结果文件输出路径` — `{taskDir}/brain_analysis_loop{N}.json`
+- `## 任务描述` — `{taskDescription}`
+- `## 用户提供的验收标准`（如有）或 `## 验收标准`（自动生成提示）
+
+### 3.2 重规划分析
+
+调用方（`_analyzeWithContextViaCLI`）在首轮基础上额外注入：
+- `## 重规划上下文` — "当前是第 N 轮重规划"
+- `## 上一轮审核摘要` — `prevCheckSummary`
+- `## 上一轮编排状态` — `prevOrchStatus`
+- `## 未满足的验收标准` — failedCriteria 列表（含 id/criterion/reason）
+- `## 改进建议` — improvementSuggestions 列表
+- `## 重分析要求` — 6 条固定指令
+
+---
+
+## 4. 结果消费链路
+
+### 4.1 JSON 读取与容错
+
+`SkillExecutor.readSkillResult(resultFilePath)`：
+- 读取文件内容
+- 用 `indexOf('{')` / `lastIndexOf('}')` 提取 JSON（容忍 markdown 包裹）
+- `JSON.parse` 解析
+- 返回 `{ success, json, raw }`
+
+### 4.2 规范化
+
+`AnalysisStrategies.normalizeAnalysis(json)` 对字段兜底：
+
+| 字段 | 兜底值 |
+|------|--------|
+| `intent` | `''` |
+| `domain` | `'general'` |
+| `keywords` | `[]` |
+| `constraints` | `[]` |
+| `techStack` | `[]` |
+| `complexity` | `'medium'` |
+| `estimatedSteps` | `3` |
+| `acceptanceCriteria[].id` | `ac{idx+1}` |
+| `acceptanceCriteria[].type` | `'output'` |
+| `acceptanceCriteria[].verification` | `''` |
+| `failureAnalysis` | `''` |
+| `adjustmentStrategy` | `''` |
+
+> 空描述的 acceptanceCriteria 条目会被 `.filter(c => c.criterion)` 过滤。
+
+### 4.3 下游消费 — DecompositionStrategies
+
+`DecompositionStrategies` 将分析结果格式化后传给 `task-decomposition` SKILL：
+- `acceptanceCriteria` → 格式化为 `[ac1] (type) criterion → 验证: verification` 列表
+- `intent/domain/keywords/constraints/techStack/complexity/estimatedSteps` → 写入拆解 prompt
+
+### 4.4 最终组装 — Brain
+
+`Brain.planTask` / `replanTask` 将 `acceptanceCriteria` 写入 `taskDef`：
+```js
+taskDef = {
+    taskId, taskDir, skillDirectory,
+    acceptanceCriteria: analysis.acceptanceCriteria || [],
+    loopCount: 0,
+    steps: rawSteps.map(...)
+};
+```
+
+重规划时额外记录：
+```js
+taskDef.replanInfo = {
+    loopCount,
+    previousCheckId,
+    failedCriteriaCount,
+    improvementSuggestions
+};
+```
+
+### 4.5 准出审核 — TestCheck
+
+`taskDef.acceptanceCriteria` 最终传给 `acceptance-check` SKILL / `TestCheck`，用于每轮执行后的准出审核。审核结果决定是否进入下一轮重规划。
+
+---
+
+## 5. 循环终止条件
+
+| 条件 | 结果 |
+|------|------|
+| `checkResult.passed === true` | `LoopStatus.PASSED`，结束 |
+| `currentLoop >= maxLoops`（默认 3） | `LoopStatus.FAILED` |
+| `ctx.aborted` | `LoopStatus.ABORTED` |
+
+---
+
+## 6. 目录命名约定
+
+- **物理目录名**：`task-analysis`（Brain 硬编码拼接 `path.join(skillDir, 'task-analysis')`）
+- **frontmatter name**：`task-analysis`（SkillSelector 体系下的逻辑标识）
+- 两者一致 — Brain 用物理目录名定位，frontmatter name 作为逻辑标识
+
+> ⚠️ 重命名物理目录需要同步修改 Brain 中 `AnalysisStrategies.js` 的 `path.join(skillDir, 'task-analysis')`。
+
+---
+
+## 7. 结果文件命名
+
+- 首轮：`brain_analysis_loop0.json`
+- 第 1 轮重规划：`brain_analysis_loop1.json`
+- 第 N 轮重规划：`brain_analysis_loop{N}.json`
+
+文件路径由调用方通过 prompt 注入，SKILL 只需写入指定路径。
+
+---
+
+## 8. 持久化
+
+`Brain.planTask` / `replanTask` 末尾调用 `PlanPersistence.persistPlan(plan)`：
+- 完整 `analysis` 对象写入 `brain.json` 快照
+- `loadPlanHistory(taskId)` 可按轮次加载历史分析结果

package/vendor/Server/Skills/task-analysis/references/LESSONS_LEARNED.md

@@ -0,0 +1,55 @@
+# 经验总结：task-analysis SKILL 规范化重生成
+
+## 背景
+
+对已有的 task-analysis SKILL 进行 skill-generator 规范化重生成。原 SKILL 仅有单文件 SKILL.md，无 references/assets/scripts，未采用渐进式披露结构。
+
+## 关键发现
+
+### 1. 目录命名与 frontmatter name 不一致是设计如此
+
+- Brain 模块硬编码 `path.join(skillDir, 'task-analysis')` 定位 SKILL
+- frontmatter `name: task-analysis` 是 SkillSelector 体系下的逻辑标识
+- 两者现在保持一致，物理目录名与逻辑标识同名
+
+### 2. SKILL 执行通过 opencode CLI 间接调用
+
+- SkillExecutor 不是直接执行 SKILL 代码，而是创建 opencode Session
+- opencode 读取 SKILL.md 后按指令执行
+- SKILL.md 实际上是给 LLM 看的指令文档，不是可执行脚本
+- prompt 中注入的上下文段落是 SKILL 的实际输入
+
+### 3. 结果输出有容错机制但仍应输出纯 JSON
+
+- `readSkillResult` 用 `indexOf('{')`/`lastIndexOf('}')` 容错提取
+- 即使被 markdown 包裹也能解析
+- 但 SKILL 应输出纯 JSON，不依赖容错
+
+### 4. normalizeAnalysis 提供字段兜底
+
+- 所有字段有兜底值（intent='', domain='general', complexity='medium' 等）
+- 空描述的验收标准会被 `.filter(c => c.criterion)` 过滤
+- SKILL 应尽量输出完整字段，避免依赖兜底
+
+### 5. 重规划上下文通过 prompt 段落注入
+
+- 不是通过参数传递，而是通过 `## 重规划上下文` 等 markdown 段落
+- SKILL 需要从 prompt 文本中解析这些段落
+- 6 条"重分析要求"是固定文本，由调用方注入
+
+## 最佳实践
+
+- SKILL.md body 保持在 200 行以内，详细内容拆分到 references/
+- 输出 JSON 的 Schema 文档独立为 references/ANALYSIS_SCHEMA.md
+- 验收标准编写指南独立为 references/ACCEPTANCE_CRITERIA_GUIDE.md
+- 提供完整的输出示例（assets/OUTPUT_EXAMPLES.md）供 LLM 参考格式
+- 提供校验脚本（scripts/）用于自动化验证输出合规性
+- 在 SKILL.md 中明确标注调用方式与下游消费方，便于理解集成关系
+
+## 注意事项
+
+- 不要重命名 task-analysis 物理目录（如需重命名须同步修改 Brain 的 AnalysisStrategies.js）
+- 不要修改输出 JSON 的字段名（下游 normalizeAnalysis 依赖固定字段名）
+- `acceptanceCriteria[].id` 必须从 `ac1` 递增（下游格式化依赖）
+- `failureAnalysis`/`adjustmentStrategy` 仅重规划场景必填
+- complexity 必须是 `low`/`medium`/`high` 之一（兜底为 medium 但应显式输出）