openharmonyinsight ArkWeb 需求开发团队 — 实现全流程 Skill
本 Skill 作为纯编排器（Team Lead），调度四个 Agent Teammate 协作完成从需求到代码的全过程。 Team Lead 不参与具体分析、编码、检视——只负责流程编排、门禁检查、用户交互。
团队成员与通信模型
┌─────────────────────────────────────────┐
│ Team Lead: 本 Skill (SKILL.md) │
│ 职责: 创建团队、分配任务、汇总结果、 │
│ 门禁检查、差异对齐、用户交互、 │
│ 编译编排 │
│ 不做: 不分析需求、不写代码、不检视代码 │
└──────────────┬──────────────────────────┘
│ 创建团队 + 分配初始任务
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Teammate #1 │ │ Teammate #2 │ │ Teammate #3 │
│ requirements │◄─►│ arkweb- │◄─►│ arkweb- │
│ -analysis │ │ coder │ │ reviewer │
│ [🔴 opus] │ │ [🔵 opus] │ │ [🟢 sonnet] │
│ │ │ │ │ │
│ 需求分析专家 │ │ 代码实现工程师│ │ 代码检视工程师│
└──────────────┘ └──────────────┘ └──────────────┘
▲
│ 编译结果 + 报错报告
│
┌──────────────┐
│ Teammate #4 │
│ arkweb- │
│ builder │
│ [🟠 sonnet] │
│ │
│ 编译验证工程师│
└──────────────┘
Teammates 之间可以直接通信（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1），不需要经过 Team Lead 中转。
| Teammate | 角色 | 只做 | 禁止 |
|---|---|---|---|
| requirements-analysis | 需求分析专家 | 需求理解、架构分析、代码探查、输出步骤报告、回答队友业务疑问 | 编写业务代码、修改 BUILD.gn |
| arkweb-coder | 代码实现工程师 | 按报告实现代码、修复检视问题、向需求专家请教业务疑问 | 自行分析需求、偏离报告方案 |
| arkweb-reviewer | 代码检视工程师 | 8维度检视、生成 Fix Step、向需求专家确认业务上下文 | 直接修改任何代码文件 |
| arkweb-builder | 编译验证工程师 | 执行编译、分析报错、生成结构化报告 | 修改代码、修复错误、clean/reset |
Team 初始化
Teammate #1: requirements-analysis (model: opus)
Teammate #2: arkweb-coder (model: opus)
Teammate #3: arkweb-reviewer (model: sonnet)
Teammate #4: arkweb-builder (model: sonnet)
共享上下文：需求设计文档路径、分析报告路径、检视报告路径、编译报错报告路径、Teammate 标识。
Team Lead 职责：创建 Team + 传递共享上下文、Phase 2/7/8 的执行与编排、全局进度追踪、异常处理。
流程总览
| Phase | 名称 | 执行者 | 输出 |
|---|---|---|---|
| 0 | 开发环境预检 | Team Lead | 环境检查报告 |
| 1 | 需求分析 | requirements-analysis | 分析报告 |
| 2 | 设计遵从性门禁 | Team Lead | 遵从性检查结果 |
| 3 | 业务对齐 | arkweb-coder ↔ requirements-analysis | 业务对齐确认 |
| 4 | 代码实现 | arkweb-coder | 代码变更 |
| 5 | 代码检视 | arkweb-reviewer | 检视报告 |
| 6 | 修复循环 | arkweb-coder ↔ arkweb-reviewer | 修复后代码 |
| 7 | 设计差异对齐 | Team Lead（交互式） | 差异对齐结果 |
| 8 | 编译-修复循环 | Team Lead + builder + coder + reviewer | 编译通过确认 |
Phase 交接协议
Phase 0 → 1: 环境预检全部通过（Agent Teams 可用、Agent 文件齐全、Claude Code 版本满足）
Phase 1 → 2: 分析报告已生成（含"五、实现步骤"且至少 1 个 Step）
Phase 2 → 3: 无未确认的 [偏离-需用户确认] 项
Phase 3 → 4: arkweb-coder 声明"业务对齐完成" + requirements-analysis 确认
Phase 4 → 5: arkweb-coder 输出变更文件清单
Phase 5 → 6: 检视报告已生成
Phase 6 → 7: BLOCKER/CRITICAL 清零，或达到 5 轮上限
Phase 7 → 8: 所有代码变更已最终确定（设计差异已对齐）
Phase 8 → 完成: 编译成功（exit code 0）或达到 10 轮上限
注意：在
.claude/skills目录中，设计差异对齐已提取为独立 skill（arkweb-design-alignment），由arkweb-architect全流程调度执行。在arkweb-sdd目录中，Phase 6 逻辑内嵌于本文件（见下方 Phase 5 完整内容），因为arkweb-design-alignmentskill 不存在于 arkweb-sdd。
Spec 驱动： 优先依据结构化 Spec（spec.md）生成代码，设计文档作为上下文补充。
知识库驱动规则（离线 + DeepWiki）
通用规则统一引用：../_shared/KB_RULES.md。
本 skill 的增量要求如下：
- 代码实现前必须产出候选子系统/部件/API 证据包。
- 外部接口落地前必须对照离线
apis/*/*.json与本地头文件，避免接口口径漂移。 - 若实现偏离证据包，必须在输出中说明偏离原因与风险。
输入
用户需提供一个需求设计文档路径（必需），可选提供：
- Spec 文件路径（推荐，优先于纯文档驱动）
- 需求分析报告输出路径（默认
{DOCS_REPO}/tmp/arkweb_requirements_analysis.md） - 检视报告输出路径（默认
{DOCS_REPO}/tmp/arkweb_review_report.md） - 编译报错报告路径（默认
{DOCS_REPO}/tmp/arkweb_build_error_report.md）
执行步骤
Phase 0: 开发环境预检
执行者：Team Lead 直接执行（不启动 Agent） 知识：→ Read reference/env-check.md
在启动任何 Teammate 之前，执行环境预检。按 reference/env-check.md 中的检查清单逐项验证（Agent Teams 环境变量、Agent 定义文件、Reference 文件、编译脚本、Claude Code 版本）。未通过项按参考文档中的自动修复流程处理。
输出内容（强制）：
- 候选子系统（1~3）
- 候选部件（3~10）
- 候选 API（5~30）
- 每条证据附来源、路径/URL、命中原因、置信度
【强制持久化】 证据包 Write 到 {DOCS_REPO}/tmp/，详见 _shared/KB_RULES.md 第 10 节。
Phase 0 完成判定：
- 已按标准顺序完成离线检索
- 已形成候选证据包并写入后续分析上下文
- 证据包已持久化到
{DOCS_REPO}/tmp/目录（Write 工具完成，文件存在且内容完整） - 全部环境检查项 PASS。FAIL 时报告阻断原因，停止流程。
Phase 1: 需求分析
执行者：requirements-analysis Agent
指令：
请分析以下需求设计文档，按照你的标准流程执行 Phase 0 ~ Phase 3，
生成完整的实现步骤清单。
需求文档路径：{用户提供的文档路径}
分析报告输出路径：{分析报告路径，默认 {DOCS_REPO}/tmp/arkweb_requirements_analysis.md}
【强制要求】必须先 Read 需求设计文档全文，提取其中的架构方案、技术路径、
接口定义、错误码、参数校验规则等强制约束项，然后基于设计文档的方案
（而非代码库中已有的类似模式）来规划实现步骤。
【知识库要求】需求分析报告必须新增"知识库证据包"章节，包含：
1. 候选子系统、部件、API（含分数与命中原因）
2. 每条证据的来源类型（按 `_shared/KB_RULES.md` 的 source_type）与路径
3. 低置信度项标注"推断项"
请先 Read 需求文档，然后按 Phase 1→2→3 顺序执行，
最终将报告 Write 到指定输出路径。
Phase 1 完成判定：
- 使用 Read 检查分析报告文件已生成
- 报告中包含"五、实现步骤"章节且至少有 1 个 Step
- 报告中"六、自检清单"所有项不为空
- 报告中包含"知识库证据包"章节且存在 LOCAL_KB 主证据
- 证据包已持久化到
{DOCS_REPO}/tmp/目录（Phase 0 的证据包文件存在）
如果 Phase 1 失败（报告未生成或内容不完整）：
- 停止流程
- 向用户说明分析失败的原因
- 展示已获取的部分分析结果
Phase 2: 设计遵从性门禁
执行者：Team Lead 直接执行（不启动 Agent） 知识：→ Read reference/design-conformance-check.md
并行 Read 设计文档和分析报告，按 reference/design-conformance-check.md 中的 5 个维度逐项比对，按 3 级规则分类偏离项。存在 [偏离-需用户确认] 时暂停流程请用户决策（A 接受/B 退回/C 逐项决定）。
完成判定：无未确认的 [偏离-需用户确认] 项。
Phase 3: 业务对齐
执行者：arkweb-coder Agent
指令：
请先完整阅读需求分析报告，整理出所有不确定的业务疑问。
需求设计文档路径：{用户提供的文档路径}
需求分析报告路径：{分析报告路径}
【Phase 3: 业务对齐 — 编码前必做】
1. Read 需求设计文档全文
2. Read 分析报告全文
3. 整理出所有不确定的业务疑问，逐一向 requirements-analysis 请教
4. 等待所有疑问得到解答后，声明"业务对齐完成"
5. 如果阅读后确认无疑问，直接声明"业务对齐完成，无待确认疑问"
有疑问不猜测，宁可多问不要猜错。
完成后报告业务对齐结果（已提问数量 + 已解答数量）。
完成判定：arkweb-coder 声明"业务对齐完成"且 requirements-analysis 确认。 超时时 Team Lead 介入汇总未决问题，请用户一次性解答。
Phase 4: 代码实现
执行者：arkweb-coder Agent
指令：
业务对齐已完成，请按分析报告中的实现步骤逐 Step 执行代码实现。
需求设计文档路径：{用户提供的文档路径}
需求分析报告路径：{分析报告路径}
【强制要求】
1. 需求设计文档是最高优先级的参考，分析报告是执行指南
2. 设计文档中指定的技术路径不可自行替换
3. 设计文档要求修改的所有层级/仓库都必须实现，包括 deps_code/ 目录
【代码规范】严格遵循你内置的代码生成规范和项目模板执行。
请按你的内部 Phase 1→2→3→4 顺序执行。
完成后输出变更文件清单和验证报告。
完成判定：Agent 报告所有 Step 已完成（或部分完成）。 部分失败时记录失败的 Step，继续 Phase 5 检视已完成部分。
Phase 5: 代码检视
执行者：arkweb-reviewer Agent
指令：
请对所有变更文件进行完整的代码检视。
需求设计文档路径：{用户提供的文档路径}
需求分析报告路径：{分析报告路径}
【检视过程中】如果在 H 维度（设计遵从性）有疑问，直接向 requirements-analysis 确认。
【检视报告要求】每个 Issue 给出代码修改建议 + 测试验证建议。
变更文件来源：分析报告中"四、代码探查结果"列出的文件 + git diff 获取的变更文件。
请按你的内部 Phase 1→2→3→4 顺序执行：
1. 收集变更范围
2. 逐文件检视（A~H 共 8 个维度，含 H-设计遵从性）
3. 交叉验证
4. 生成检视报告到 {检视报告路径，默认 {DOCS_REPO}/tmp/arkweb_review_report.md}
特别注意 H 维度：检查实现是否忠实于设计文档的架构方案、错误码定义、实现范围和参数校验规则。
完成判定：检视报告已生成，包含"问题清单"章节和检视摘要。
Phase 6: 修复循环
执行者：arkweb-coder ↔ arkweb-reviewer 直接沟通（Team Lead 不参与细节）
循环逻辑：max_rounds = 5，每轮 coder 修复 → reviewer 复检 → 统计 BLOCKER/CRITICAL。清零则通过，超限则向用户报告剩余问题。分歧涉及业务逻辑时请 requirements-analysis 仲裁。
给 coder 的指令：
请根据代码检视报告中的"附录: 修改指引"章节，逐个 Fix Step 执行修复。
检视报告路径：{检视报告路径}
仅修复报告中列出的问题，不做额外改动。修复完成后直接通知 arkweb-reviewer 复检。
这是第 {current_round}/{max_rounds} 轮修复。
给 reviewer 的指令：
arkweb-coder 已完成第 {current_round} 轮修复，请复检。
上轮修复的文件：{修复轮次变更的文件列表}
检视报告输出路径：{检视报告路径}
Phase 7: 设计差异对齐
执行者：Team Lead 主导（交互式） 知识：→ Read reference/design-diff-alignment.md
循环逻辑：max_diff_rounds = 5。按 reference/design-diff-alignment.md 中的 10 个维度比对设计文档与实际实现，逐一向用户展示差异并请求决策（A 接受/B 重做/C 搁置），执行回写或重做操作。重做后重新比对，无新差异则退出。
完成判定：所有差异已处理（通过或达到最大轮次）。
Phase 8: 编译-修复循环
执行者：Team Lead 编排 + arkweb-builder + arkweb-coder + arkweb-reviewer 知识：→ Read reference/build-verification.md
循环逻辑：max_rounds = 10。按 reference/build-verification.md 中的流程，builder 编译 → 失败则 coder 修复 → reviewer 检视（内层最多 3 轮）→ 重新编译。编译通过则完成。
Read 需求分析报告（{DOCS_REPO}/tmp/arkweb_requirements_analysis.md） → 提取：实现步骤清单、代码探查结果、自检清单
Read 检视报告（{DOCS_REPO}/tmp/arkweb_review_report.md） → 提取：修复过程中产生的技术决策、接口变更、架构调整
**比对维度**：
设计要素 比对方法 差异类型 ───────────────────────────────────────────────────────────────────── 接口/API 签名 设计文档的 API 定义 vs 实际代码的头文件 签名差异 数据结构/枚举 设计文档的字段定义 vs 实际 struct/enum 字段差异 类/继承关系 设计文档的类图 vs 实际 class 定义 结构差异 方法列表 设计文档的方法列表 vs 实际方法列表 增减差异 参数/返回值 设计文档的参数描述 vs 实际参数类型 类型差异 流程/状态机 设计文档的流程图 vs 实际控制流 逻辑差异 错误码/异常 设计文档的错误定义 vs 实际错误处理 异常差异 Feature Flag 设计文档的开关规划 vs 实际 flag 定义 配置差异 多语言绑定范围 设计文档的绑定要求 vs 实际绑定覆盖 范围差异 模块划分 设计文档的模块边界 vs 实际文件组织 架构差异
**执行方式**：对设计文档中描述的每个接口/类/方法，使用 Grep + Read 在实际代码中
查找对应实现，逐项对比。
将所有差异收集为列表，准备进入用户决策环节。
#### Step 5.2: 逐一向用户展示差异并请求决策
对每个差异点，使用 AskUserQuestion 工具向用户展示并请求决策。
**每次仅展示一个差异点**，等待用户明确回复后再处理下一个。
**展示格式**：
差异 {N}/{Total}: {差异标题}
设计文档描述： {设计文档中的原始描述，包含章节引用}
实际实现： {代码中实际的实现情况}
差异分析： {简要说明差异的原因和影响}
请选择处理方式： A) 接受实现 — 将设计文档修改为与实现一致（回写设计文档） B) 要求重做 — 按设计文档的要求重新实现代码（启动 coder+reviewer） C) 暂时搁置 — 记录为遗留事项，后续处理
**用户决策选项说明**：
| 选项 | 含义 | 后续操作 |
|------|------|---------|
| A) 接受实现 | 实现合理，设计文档需要更新 | 直接 Edit 设计文档原始章节 |
| B) 要求重做 | 实现偏离设计意图，需修正代码 | 启动 coder → reviewer 循环 |
| C) 暂时搁置 | 无法立即决策，后续处理 | 记录到遗留事项列表 |
#### Step 5.3: 根据用户决策分类处理
收集所有差异点的用户决策，按处理方式分组：
决策 A（接受实现）的差异数量: {a_count} 决策 B（要求重做）的差异数量: {b_count} 决策 C（暂时搁置）的差异数量: {c_count}
#### Step 5.4: 执行用户决策
##### 对决策 A（接受实现）的差异：直接回写设计文档
**关键原则：直接修改设计文档的原始章节，而不是在末尾追加说明。**
对每个决策 A 的差异：
1. 使用 Read 定位设计文档中对应的原始章节
2. 使用 Edit **就地修改**原始描述，使其与实际实现一致
3. **不在末尾追加汇总章节**，仅在修改处标注修改来源
**修改原则**：
- 仅修改与实现不一致的段落/章节，不改动文档整体结构
- 保持原文档的写作风格和术语
- 使用 Edit 精确替换，不覆盖整个文档
- 每处修改通过行内注释标注变更来源和原因
**修改示例**：
原设计文档（3.1 节）：
不追加末尾总结章节——所有修改直接体现在原始章节中。
对决策 B（要求重做）的差异：启动 coder+reviewer 重做循环
将所有决策 B 的差异整合为重做需求，传递给 arkweb-coder Agent：
请根据以下用户决策，重新实现代码以对齐设计文档。
需求设计文档路径：{用户提供的文档路径}
检视报告路径：{检视报告路径}
用户要求重做的差异点：
差异 1: {差异标题}
设计文档要求：{设计文档的原始描述}
当前实现：{当前代码的实现}
需要修改为：{与设计文档一致}
差异 2: ...
请按以下步骤执行：
1. 读取需求设计文档中对应的章节
2. 使用 TodoWrite 创建修复任务列表
3. 逐个修改代码文件以对齐设计文档
4. 修改完成后输出变更文件清单
重做完成后，启动 arkweb-reviewer Agent 仅检视重做涉及的文件：
请仅检视以下重做涉及的文件，确认代码已正确对齐设计文档。
需求设计文档路径：{用户提供的文档路径}
重做的文件：{重做变更的文件列表}
检视报告输出路径：{检视报告路径}
重点关注：
1. 用户指出的差异是否已修正
2. 修正是否引入了新问题
3. 代码是否与设计文档一致
如果检视仍有 BLOCKER/CRITICAL 问题，按 Phase 4 的修复循环逻辑继续 （最多 3 轮）。
对决策 C（暂时搁置）的差异：记录到遗留事项
不修改设计文档，不修改代码。仅在最终总结中列出。
Step 5.5: 差异对齐循环检查
如果有决策 B 的差异触发了重做：
→ 重新执行 Step 5.1（重新收集信息并比对）
→ 检查重做是否引入了新的差异
→ 如果有新差异 → 回到 Step 5.2（向用户展示新差异）
→ 如果无新差异 → 退出循环
如果无决策 B 的差异：
→ 直接退出循环，所有差异已处理完毕
循环保护：
max_diff_rounds = 5
如果差异对齐循环超过 5 轮：
→ 向用户报告仍有未对齐的差异
→ 列出剩余差异
→ 建议人工介入
Step 5.6: 差异处理总结
完成所有差异处理后，向用户输出总结：
═══════════════════════════════════════════
Phase 5: 设计差异对齐完成
═══════════════════════════════════════════
需求文档: {原始需求文档路径}
本轮差异统计:
总差异点: {N}
用户决策分布:
接受实现（已回写设计文档）: {A_count} 处
要求重做（已重新实现）: {B_count} 处
暂时搁置（记录为遗留）: {C_count} 处
已直接修改的设计文档章节:
- {章节1} ({差异标题}): {修改摘要}
- {章节2} ({差异标题}): {修改摘要}
已重新实现的代码文件:
- {文件1}: {修改说明}
- {文件2}: {修改说明}
遗留事项（用户选择搁置）:
- [ ] {差异标题}: {设计要求 vs 实际实现}
═══════════════════════════════════════════
流程状态追踪
使用 TodoWrite 维护全局进度：
Phase 1: 需求分析 [pending / in_progress / completed]
Phase 2: 设计遵从性门禁 [pending / in_progress / completed / blocked]
Phase 3: 业务对齐 [pending / in_progress / completed]
Phase 4: 代码实现 [pending / in_progress / completed]
Phase 5: 代码检视 [pending / in_progress / completed]
Phase 6: 修复循环 (1~5) [pending / in_progress / completed]
Phase 7: 设计差异对齐 [pending / in_progress / completed]
└─ 差异决策轮次 (1~5) [追踪当前轮次]
Phase 8: 编译-修复循环 (1~10) [pending / in_progress / completed]
└─ 内层检视循环 (1~3) [追踪当前轮次]
异常处理
Phase 1 失败（需求无法分析）
- 停止流程
- 向用户展示错误信息
- 建议检查需求文档格式和内容
Phase 1.5 阻断（设计遵从性检查未通过）
- 停止流程，不进入 Phase 2
- 向用户输出偏离详情（设计文档要求 vs 分析报告方案）
- 提供三个选项：A) 接受偏离继续 B) 退回重新分析 C) 逐项决定
- 等待用户确认后继续或退回
Phase 1.5 退回（用户选择重新分析）
- 将偏离详情作为反馈传递给 requirements-analysis Agent
- 重新执行 Phase 1，在指令中明确要求修正偏离项
- 重新执行 Phase 1.5 验证
Phase 2 部分失败（某些 Step 无法实现）
- 记录失败的 Step
- 继续执行后续可完成的 Step
- 在 Phase 4 检视时标注未完成的步骤
- 设计差异对齐（Phase 6）处理时标注 INCOMPLETE
Phase 4 达到最大轮次仍有问题
- 停止修复循环
- 向用户报告剩余的 BLOCKER/CRITICAL 问题
- 建议人工介入处理
- Phase 5（设计差异对齐）正常执行，标注 PASS_WITH_ISSUES
Phase 5 差异对齐循环超过最大轮次
- 停止差异对齐循环
- 向用户报告仍有未对齐的差异
- 列出剩余差异及建议处理方式
- 保留已完成的差异处理结果
Agent 执行超时或无响应
- 记录当前进度
- 向用户报告已完成的阶段和当前卡住的位置
- 保留已生成的中间文件（分析报告、检视报告）
代码生成规范
以下规范在 Phase 2 调度 arkweb-coder Agent 时，必须作为强制指令传递。
命名规范
类名： PascalCase 例：WebGPUContext
方法名： camelCase 例：initializeContext
成员变量： m_ 前缀 例：m_contextId
常量： k 前缀 例：kMaxTextureSize
文件名： snake_case 例：webgpu_context.h
命名空间： OHOS::ArkWeb::* 例：OHOS::ArkWeb::WebGPU
代码结构（每个 C++ 文件）
// Copyright (c) 2026 Huawei Device Co., Ltd.
// Licensed under the Apache License, Version 2.0
#ifndef {GUARD_NAME}
#define {GUARD_NAME}
#include <memory>
// ... 依赖头文件
namespace OHOS::ArkWeb::{Module} {
class {ClassName} : public {BaseClass} {
public:
{ClassName}();
~{ClassName}() override;
// 接口方法（来自设计文档）
int32_t Initialize(const {Config}& config) override;
void Destroy() override;
private:
// 成员变量
std::unique_ptr<{Impl}> impl_;
};
} // namespace OHOS::ArkWeb::{Module}
#endif // {GUARD_NAME}
关键约束（coder Agent 必须遵守）
- 版权头 — 每个源文件必须包含 Apache 2.0 版权头
- namespace — 必须使用
OHOS::ArkWeb::*命名空间包裹 - RAII — 必须遵循资源获取即初始化原则
- 裸指针 — 禁止裸指针传递所有权，使用
std::unique_ptr/std::shared_ptr - 错误码 — 使用
int32_t返回错误码（ArkWeb 约定，0 表示成功） - 日志 — 使用
WEBGPU_LOGI/LOGE/LOGW或对应的模块日志宏 - 设计文档优先 — 所有接口、类名、参数必须与 requirement.md 一致
- 最小修改 — 能新增文件解决的，不修改已有文件
单元测试规范
覆盖要求：
- 正常路径（Happy Path）：至少 2 个用例
- 边界条件：空输入、最大值、零值
- 错误路径：无效参数、资源不足
- 设备差异：不同设备类型的行为差异（如适用）
测试结构：
// Copyright (c) 2026 Huawei Device Co., Ltd.
#include <gtest/gtest.h>
#include <gmock/gmock.h>
#include "{header_path}"
using namespace testing;
using namespace OHOS::ArkWeb::{Module};
class {ClassName}Test : public testing::Test {
protected:
void SetUp() override { /* 初始化 */ }
void TearDown() override { /* 清理 */ }
};
// 正常路径
TEST_F({ClassName}Test, InitializeSuccess) {
// Arrange
{ClassName} obj;
{Config} config = {.width = 1024, .height = 768};
// Act
int32_t result = obj.Initialize(config);
// Assert
EXPECT_EQ(result, 0);
}
// 边界条件
TEST_F({ClassName}Test, InitializeWithZeroSize) { /* ... */ }
// 错误路径
TEST_F({ClassName}Test, InitializeWithNullConfig) { /* ... */ }
BUILD.gn 规范
新增源文件时按以下格式修改 BUILD.gn：
import("//build/ohos.gni")
ohos_shared_library("{module_name}") {
sources = [
"{new_source}.cpp",
# ... 新增文件
]
include_dirs = [
"//foundation/arkui/ace_engine/interfaces",
"//base/web/webview/interfaces",
]
deps = [
"//third_party/googletest:gtest_main",
]
external_deps = [
"c_utils:utils",
"hilog:libhilog",
]
}
自验证清单（coder Agent 完成编码后必须执行）
- 命名一致性 — 类名与文件名对应、方法名与设计文档一致、命名空间正确
- 接口完整性 — 设计文档中所有接口都已实现、参数类型和返回值与设计文档一致
- 测试覆盖 — 每个公共方法至少 1 个测试、包含正常 + 边界 + 错误路径
- 规范检查 — 版权头完整、namespace 包裹、无裸指针所有权传递、日志使用正确宏
- 头文件包含 — 所有
#include正确，无遗漏、无冗余
代码生成原则
- 设计文档是唯一真理 — 所有接口、类名、参数必须与 requirement.md 一致
- 最小修改 — 能新增不修改，能改小不改大
- 先计划后编码 — 先列文件清单，再逐个生成
- 测试先行 — 每个公共接口必须有测试
- 自验证闭环 — 生成后必须自检，不通过要自动修复
- 遵循现有规范 — 读取 analysis.md 中的命名和结构规范，不另起炉灶
使用示例
示例 1: 完整流程（含差异交互）
用户: 实现需求 /path/to/requirement_design.md
助手: 好的，我将启动需求实现全流程。
需求文档: /path/to/requirement_design.md
分析报告: {DOCS_REPO}/tmp/arkweb_requirements_analysis.md
检视报告: {DOCS_REPO}/tmp/arkweb_review_report.md
Phase 1: 启动需求分析...
→ [requirements-analysis Agent 执行]
→ 分析完成：8 个功能点，12 个实现步骤
Phase 2: 设计遵从性门禁...
→ 比对设计文档与分析报告
→ 3 项一致，0 项偏离 → 检查通过
Phase 2: 启动代码实现...
→ [arkweb-coder Agent 执行]
→ 实现完成：12/12 Step 已完成，变更 18 个文件
Phase 3: 启动代码检视...
→ [arkweb-reviewer Agent 执行]
→ 检视完成：2 CRITICAL，5 MAJOR，3 MINOR
Phase 4: 修复循环 (Round 1/5)...
→ [arkweb-coder 执行修复]
→ [arkweb-reviewer 再次检视]
→ Round 1 完成：0 BLOCKER，0 CRITICAL → 检视通过
Phase 5: 设计差异对齐（交互式）...
→ 比对设计文档与实际实现，发现 3 处差异
差异 1/3: 接口方法签名扩展
### 示例 1.5: 设计遵从性门禁拦截
助手: Phase 2: 设计遵从性门禁... → 比对设计文档与分析报告
⚠ Phase 1.5: 设计遵从性检查未通过
偏离 1: 技术路径偏离
设计文档要求：使用 C++ DOM API (SetValueForUser)
分析报告方案：使用 JS 注入 (ExecuteJavaScript)
偏离 2: 实现范围缺失
设计文档要求：修改 arkui_ace_engine 入口层参数校验
分析报告方案：未涉及 ACE Engine 层修改
偏离 3: 错误码体系未对齐
设计文档要求：定义 -1 至 -10 的专项错误码
分析报告方案：复用已有错误码 102/131/132/133
请确认：
A) 接受偏离，按分析报告方案继续
B) 拒绝偏离，退回 Phase 1 重新分析
C) 逐项决定（告知每项选择）
用户: B
助手: 退回 Phase 1 重新分析，将偏离详情作为反馈... → Phase 1 重新执行（已指示修正 3 项偏离） → Phase 1.5 重新检查 → 检查通过 → 继续 Phase 2...
### 示例 2: 指定文档和自定义输出路径
用户: 按照设计文档 docs/snapshot_api_design.md 实现功能， 分析报告输出到 {DOCS_REPO}/tmp/snapshot_analysis.md
助手: 好的，启动需求实现全流程。 需求文档: docs/snapshot_api_design.md 分析报告: {DOCS_REPO}/tmp/snapshot_analysis.md ...（同上流程）
### 示例 3: 达到最大修复轮次
助手: Phase 4: 修复循环 (Round 5/5)... → [arkweb-coder 执行修复] → [arkweb-reviewer 再次检视] → Round 5 完成：仍有 1 CRITICAL 问题
⚠️ 已达到最大修复轮次(5轮)，以下问题尚未解决：
- Issue 3: [CRITICAL] nweb_snapshot_impl.cc:87 异步回调中
使用 shared_ptr 可能导致循环引用
建议人工介入处理此问题。
Phase 5 将正常执行，状态标注为 PASS_WITH_ISSUES。
### Phase 8 超限（编译验证达到最大轮次）
- 报告最后一轮编译错误摘要
- 建议人工介入
- 保留已生成的所有中间文件
### Phase 8 内层超限（coder 修复轮次耗尽）
- 直接进入下一轮编译
- 让编译器验证当前代码状态