arkweb-code-gen

# 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-alignment` skill 不存在于 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](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](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](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](reference/build-verification.md) 循环逻辑：max_rounds = 10。按 `reference/build-verification.md` 中的流程，builder 编译 → 失败则 coder 修复 → reviewer 检视（内层最多 3 轮）→ 重新编译。编译通过则完成。 2. Read 需求分析报告（{DOCS_REPO}/tmp/arkweb_requirements_analysis.md） → 提取：实现步骤清单、代码探查结果、自检清单 3. 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++ 文件） ```cpp // 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_; };