Arkweb Architect

ArkWeb 架构师 - Subagent 编排流程

环境变量

主 Session 在 Phase 1 开始前确定以下变量值，后续所有 Phase 引用这些变量：

取值逻辑：

1. 主 Session 启动时，SKILL_HOME = 当前工作目录（cwd）
2. 如果用户指定了其他工作目录，则 WORK_HOME = 用户指定路径；否则 WORK_HOME = SKILL_HOME
3. DOCS_REPO 启动时检查（按优先级依次尝试，找到第一个满足条件的即停止）：
   • {SKILL_HOME} 本身（检查是否包含 docs/features/ 和 analysis/ 子目录）
   • {SKILL_HOME}/{DOCS_REPO_DIR}（检查该目录是否存在且包含 docs/ 和 analysis/ 子目录）
   • 从 SKILL_HOME 逐级向上查找包含 docs/features/ 和 analysis/ 子目录的目录
   • 以上均未找到 → 使用 AskUserQuestion 向用户询问："未找到设计文档仓库（需包含 docs/features/ 和 analysis/ 目录），请输入完整路径"
4. 主 Session 在 spawn subagent 时，将上述变量替换为实际绝对路径后注入 task 描述
5. subagent 收到的 task 中不包含变量名，只有实际路径值

重要： 本 SKILL.md 中所有路径引用均使用上述变量。这是为了让不同模型/环境都能无歧义理解路径含义。实际执行时由主 Session 完成变量替换。

核心原则

主 Session = 协调者 + 决策者，不做实际工作。

每个 skill 是一个独立 subagent，拥有自己的上下文和输出。Subagent 之间通过文件系统传递数据（读写共享 workspace），不直接通信。

proposal.md 是核心需求文档。 模板产出物（spec.md）从 proposal.md 中提取生成。评审对象始终是 proposal.md。

架构总览

┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                         🧠 主 Session（协调者）                                                │
│                                                                                              │
│  ┌───────┐ ┌───────┐ ┌───────┐                                                                  │
│  │决策 1 │ │决策 2 │ │决策 3 │                                                                  │
│  │选方案?│ │评审?  │ │审代码?│                                                                  │
│  └───┬───┘ └───┬───┘ └───┬───┘                                                                  │
│      └─────────┴─────────┘                                                                      │
│  ┌──────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                    Subagent 调度器                                                   │  │
│  │         spawn / yield / collect / steer / kill                                       │  │
│  └──────────────────────────────────────────────────────────────────────────────────────┘  │
└──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬────────────────┘
           │          │          │          │          │          │          │
     ┌──────────────────────────────────────────────────────────┐
     │ 专家团（10 专家并行，由主 Session 直接调度）              │
     │ ⚡🎬🔌🔐🎨🖼️✨🌐⚙️🛡️                              │
     │ → 按相关度权重筛选（🟢核心/🟡关联/⚪旁听）              │
     └──────────────────────────────────────────────────────────┘
     ┌──────────────────────────────────────────────────────────┐
     │Sub-1 brainstorm（接收专家意见，输出方案）[Phase 2]          │
     │ → 读取专家团讨论纪要 → 融入方案 → 输出 brainstorm       │
     └──────────────────────────────────────────────────────────┘
     ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
     │Sub-2    │ │Sub-3    │ │Sub-4    │ │Sub-7    │ │Sub-8    │
     │code     │ │design   │ │spec     │ │code     │ │committer│
     │analysis │ │doc      │ │review   │ │gen      │ │review   │
     └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
     ┌─────────┐
     │Sub-9    │
     │gitcode  │
     │pr       │
     │(Phase 9)│
     └─────────┘
     ┌─────────┐
     │Sub-10   │
     │spec-gen │
     │(Phase 6)│
     └─────────┘

     ┌──────────────────────────────────────────────────────────┐
     │ 主 Session 直接生成（不通过 subagent）                    │
     │ → proposal.md (Phase 1 需求录入 + Phase 1.5 澄清 + Phase 3 基线) │
     └──────────────────────────────────────────────────────────┘

Subagent 清单

注： proposal.md（Phase 1 需求录入 + Phase 1.5 澄清记录 + Phase 3 需求基线）由主 Session 直接生成。spec.md + task.md（Phase 6）由 Sub-10 (spec-gen) 生成。

v5 变更： Sub-4 合并了原 Sub-4.5（checklist-review）的功能，评审时同时完成技术评审和 Checklist 规范性检视。Sub-5（spec-extract）和 Sub-6（create-spec）已移除，spec.md 改由 Sub-10 (spec-gen) 在 Phase 6 生成。

专家团 Subagent（由主 Session 直接调度）

在 Phase 2 的 Step 2.2 中，主 Session 直接 spawn 领域专家 subagent，收集意见后传给 brainstorm：

注意：专家团 subagent 由主 Session 在 Phase 2 中直接调度，不在 Sub-1 (brainstorm) 内部 spawn。主 Session 收集专家意见后汇总为「专家团讨论纪要」，作为 brainstorm 的输入。

完整流程

阶段编号规范

Phase 1-9 = 自然数顺序 — 每个阶段对应一个独立步骤，编号连续无跳号。

Phase 1: 初始化与需求录入

主 Session:
  1. 接收用户需求
  2. 提取关键信息：
     - 需求描述
     - 目标设备（默认：全覆盖）
     - OHOS 版本（默认：全部）
  3. 确定工作目录：
     - docs_dir = {docs_dir}{feature-name}/
     - analysis_dir = {analysis_dir}
     - date = YYYY-MM-DD
     - feature = {从需求中提取的简短英文标识（kebab-case）}
  4. 创建需求目录：
     - mkdir -p {docs_dir}
  5. 生成文件名模板：
     - proposal: {docs_dir}/proposal.md
     - brainstorm: {docs_dir}/{date}-{feature}-brainstorm.md
     - requirement: {docs_dir}/{date}-{feature}-requirement.md
     - design: {docs_dir}/{date}-{feature}-design.md
     - review: {docs_dir}/{date}-{feature}-review.md
     - spec: {docs_dir}/spec.md
     - analysis: {analysis_dir}/{date}-{feature}-analysis.md
     - committer-review: {docs_dir}/{date}-{feature}-committer-review.md

proposal（需求录入+基线）⭐ 必选

在 brainstorm 之前，记录需求的原始上下文，确保追溯链完整。使用 proposal.md 模板格式。

主 Session:
  1. 从用户需求中提取：
     - 来源（MSDP / 内部 / 竞品 / 社区 Issue）
     - 提出人/团队
     - 原始问题描述
     - 用户痛点
     - 竞品/背景证据
     - 初始范围（可能包含 / 明确不包含）
     - 初始假设（待验证的技术假设）
     - 预计流程级别：L0（小改动）/ L1（标准 Feature）/ L2（跨子系统）/ L3（大型 Feature）
     - 判断依据：涉及仓数量、API 级别、是否需要跨团队
     - 目标发行版本：记录版本号或 TBD
     - 版本是否已承诺：是/否/待确认
  3. 保存为 proposal.md

【强制】生成 proposal.md 前，必须先读取模板文件 {DOCS_REPO}/assets/templates/proposal.md，严格按模板的章节结构、中文章节标题、表格格式填充内容。不得自行改为英文结构或英文标题。

模板参考：{DOCS_REPO}/assets/templates/proposal.md

• 基本信息表（需求ID / 来源 / 优先级 / 状态）
• 目标发行版本表（版本 / 判断依据 / 是否已承诺 / 后续事实源）
• 原始问题描述
• 用户/开发者痛点表
• 期望结果列表
• 背景和证据表（竞品分析链接、代码分析链接）
• 初始范围（可能包含 / 明确不包含）
• 初始假设表（假设 / 类型 / 验证方式 / 状态）

Phase 1.5: 需求澄清（多轮对话）⭐ 必选 · 强制决策点

proposal.md 第一章生成后，必须进入需求澄清环节。不允许跳过。

澄清是逐轮对话，不是一次性填表。主 Session 必须主动向用户提问，等待用户回复后再继续。

主 Session:
  1. 从 proposal.md 第一章提取所有"待澄清/待验证"项：
     - 初始假设表中的「待验证」条目
     - 初始范围中的模糊描述
     - 用户痛点中需要确认的细节
     - 目标设备/OHOS 版本的默认值是否正确
     - 初始分级判断是否有依据不足的项
     - 复杂度判断是否需要更多信息
  2. 将待澄清项整理为编号问题清单（Q-1, Q-2, ...），每项包含：
     - 具体问题
     - 为什么需要澄清（对后续设计的影响）
  3. 向用户展示问题清单，**逐条或分批提问**
  4. 记录用户回答到 proposal.md 第二章「澄清记录」：
     - 更新「待澄清问题」表的状态（待澄清 → 已确认/已排除/待定）
     - 追加「讨论记录」
     - 更新「功能范围确认」「子系统影响」「API 变更评估」等表
     - 更新「初始假设」表的状态（待验证 → 已验证/已否定/需补充信息）
  5. 每轮澄清后检查：是否产生了新的待澄清项？
     - 是 → 继续下一轮澄清
     - 否 → 检查进入设计条件

澄清完成条件（全部满足才能进入 Phase 2）：

• 所有待澄清问题状态不为"待澄清"（已确认/已排除/待定但用户已知情）
• 初始假设全部有结论（已验证/已否定/用户接受风险）
• 功能范围确认完毕
• 子系统影响已初步识别
• 复杂度分级有明确判断（或有用户确认的"待定"理由）

澄清原则：

• 不猜测：不确定的一定要问，不要用"默认""推测""大概率"代替用户确认
• 不过载：每轮提问控制在 3-5 个核心问题，避免一次性列出所有问题
• 有优先级：先澄清对方案选型有直接影响的问题，再澄清细节
• 可追溯：每轮澄清的结论都记录到 proposal.md 第二章，不丢信息
• 允许中断：用户可以随时补充新信息，主 Session 回到澄清环节更新记录

注意： proposal.md 模板中「第二章：澄清记录」已包含完整的记录结构（待澄清问题表、讨论记录、功能范围确认、子系统影响、API 变更评估、兼容性需求、依赖与风险等）。主 Session 按模板结构逐项填充即可。

Phase 2: 需求分析 — 知识库检索 + 专家团 + brainstorm + code-analysis

Phase 2 分为五个步骤：

Step 2.0: 知识库检索（主 Session 执行）

【强制】 在 spawn 任何 subagent 之前，主 Session 必须先执行知识库检索，产出「知识库证据包」。

降级策略（按优先级逐级尝试，参见 _shared/KB_RULES.md）：

两个 🥇 知识库互补使用：oh-chromium-knowledge 聚焦 Chromium 内核实现，oh-ai-full-design 聚焦鸿蒙组件体系。涉及 Chromium 代码路径优先前者，涉及子系统/部件/API 优先后者。oh-ai-full-design 为私有仓库，无权限时跳过。

执行步骤：

1. 从 Phase 1 的 proposal.md 中提取需求关键词
2. 🥇 读取 skills/oh-chromium-knowledge/SKILL.md 获取知识库读取协议
3. 🥇 按 index.json → search/by_feature.json → routing_table.json 流程检索，匹配需求关键词
4. 🥇 读取 oh-ai-full-design 知识库，按 index.json → search/by_keyword.json → subsystems/ → components/ 流程检索（如无权限跳过）
5. 记录命中结果（相关仓库、模块、代码路径、架构文档、子系统/部件/API）
6. 🥈 对于 🥇 未覆盖的需求关键词，使用 DeepWiki MCP 补充检索
7. 🥉 对于 🥇🥈 都未覆盖的细节，搜索本地文档
8. 🏅 如仍有未覆盖项，按需克隆仓库
9. 汇总为「知识库证据包」，格式如下：

## 知识库证据包

### 🥇 oh-chromium-knowledge
- 匹配的功能类型: {type}（来自 search/by_feature.json）
- 相关代码路径: {paths}（来自 routing_table.json）
- 架构约束: {summary}（来自 architecture.md）
- 未覆盖项: {items}

### 🥇 oh-ai-full-design
- 匹配的子系统/部件: {subsystem/component}
- 相关 API: {apis}
- SystemCapability: {syscap}
- 未覆盖项: {items}（或：无权限，已跳过）

### 🥈 DeepWiki 补充
- 仓库: {repo} → 搜索 "{keyword}" → {发现摘要}
- 未覆盖项: {items}

### 🥉 本地文档补充
- 文档: {path} → {发现摘要}
- 未覆盖项: {items}

### 🏅 克隆仓库（如有）
- 仓库: {repo} → 搜索 "{keyword}" → {发现摘要}

10. 【强制持久化】 将完整证据包（含所有原始检索内容）Write 到 {DOCS_REPO}/tmp/arkweb_kb_evidence_{YYYYMMDD_HHmmss}_{feature}.md。详见 _shared/KB_RULES.md 第 11 节「证据包持久化」。

• 文件必须包含每个数据源的原始检索结果（完整 JSON、文本、代码片段），不允许仅保存摘要
• 先 Write 到 {DOCS_REPO}/tmp/，然后再将证据包内容注入 subagent
• 后续 phase 如需复用证据包，优先从 {DOCS_REPO}/tmp/ 读取已有文件

此证据包将注入到后续所有 subagent（专家团、code-analysis、brainstorm）的 task 描述中。同时，证据包文件路径也会传递给 subagent，以便 subagent 在上下文丢失时可以从文件恢复。

Step 2.1: 专家团相关度权重判定

在 spawn 之前，主 Session 先判定每个专家的相关度级别：

权重规则：

1. 核心专家（权重 3x）：需求直接相关的领域专家，其意见在汇总时优先级最高
2. 关联专家（权重 2x）：需求间接相关的领域专家，其意见有参考价值
3. 旁听专家（权重 1x）：需求基本不相关的领域专家，仅从通用角度补充

判定方式：

• 🟢 核心专家：需求的主要功能直接属于该专家领域 → 直接 spawn
• 🟡 关联专家：需求可能间接影响该专家领域 → 直接 spawn
• ⚪ 旁听专家：需求与该专家领域基本无关 → 超过 5 个则跳过（节省资源）

讨论控制：

• 核心专家的意见篇幅应占总意见的 40%+
• 关联专家的意见篇幅应占 30%
• 旁听专家简短表态即可（1-2 点），不超过 30%

Step 2.2: 并行 — 专家团讨论 + code-analysis

主 Session 同时 spawn 以下 subagent：

专家团（每个专家一个 subagent）

sessions_spawn(
    task="""
    你是 ArkWeb 领域的{角色名}专家。请分析以下需求，从你的专业角度给出意见。

    1. 读取你的 skill 文件：{skill_path}
    2. 按 skill 定义的输出格式给出意见

    ## 用户需求
    {user_requirement}

    ## 约束条件
    - 目标设备：{device_scope}
    - OHOS 版本：{ohos_versions}

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，你必须在意见中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    直接输出你的专家意见，不需要保存文件。
    """,
    mode="run",
    label="expert-{expert_id}"
)

专家 spawn 列表：

根据 Step 1.0 的相关度判定，跳过旁听专家（如超过 5 个）。

Sub-2: code-analysis（不变）

sessions_spawn(
    task="""
    你是 ArkWeb 代码分析师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-code-analysis/SKILL.md
    2. 按 SKILL.md 的流程执行代码分析

    ## 需求关键词
    {tech_keywords_from_requirement}

    ## 分析范围
    - ace_engine: Web 组件相关代码
    - web_webview: NWeb API 相关代码
    - chromium_src: 内核相关代码（如涉及）

    ## 数据源（按优先级使用）

    降级策略及认证方式详见 `_shared/KB_RULES.md`。

    ### 🥈 DeepWiki 在线索引
    - OpenHarmony ACE Engine: https://deepwiki.com/openharmony/arkui_ace_engine
    - OpenHarmony WebWebView: https://deepwiki.com/openharmony/web_webview
    - Chromium: https://deepwiki.com/niclas-ahden/chromium-source-code

    ### 🥉 本地分析文档（复用）
    - {analysis_dir}arkweb-ace-engine-analysis.md
    - {analysis_dir}web-webview-analysis.md
    - {analysis_dir}chromium-arkweb-analysis.md

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，在分析中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 输出
    将分析结果保存到：
    {analysis_dir}{date}-{feature}-analysis.md

    文档必须包含：
    - 相关文件清单（路径 + 职责）
    - 关键类和接口签名
    - 现有代码中与本需求相关的逻辑
    - 对设计方案的技术可行性评估

    完成后回复文档路径和关键发现摘要。
    """,
    mode="run",
    label="code-analysis"
)

主 Session 等待所有专家 + code-analysis subagent 完成：

sessions_yield()  # 等待 subagent 结果推送

Step 2.3: 收集专家意见

等待所有专家 subagent 完成，主 Session 汇总为「专家团讨论纪要」：

1. 分类整理：将专家意见按"采纳/参考/暂不考虑"分类
2. 提取共识：多个专家共同关注的问题
3. 识别冲突：不同专家之间的意见分歧
4. 权重标注：每个专家意见标注权重级别（🟢/🟡/⚪）

汇总格式：

## 🧠 专家团讨论纪要

### 共识（3+专家一致）
- {共识1}

### 高价值建议（2专家提出）
- {建议1}

### 分歧与权衡
- {分歧1}：{专家A} 认为... vs {专家B} 认为... → 结论：{总架构师裁定}

### 领域特定关切
- ⚡ 性能：{关键点}
- 🎬 多媒体：{关键点}
- ...

### 对方案的影响
- 采纳的专家意见将如何影响方案设计

Step 2.4: brainstorm

spawn brainstorm subagent，task 描述中直接包含专家团讨论纪要：

sessions_spawn(
    task="""
    你是 ArkWeb 需求分析师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-brainstorm/SKILL.md
    2. 按 SKILL.md 的流程执行需求拆解（**跳过专家团讨论步骤**，因为已在 Phase 2 完成）

    ## 用户需求
    {user_requirement}

    ## 约束
    - 目标设备：{device_scope}
    - OHOS 版本：{ohos_versions}

    ## 参考资料（按需读取）
    - 架构参考：{references_dir}arkweb-architecture.md
    - 兼容性检查：{WORK_HOME}/docs/api-compatibility-check-arkweb.md
    - 代码分析报告：{analysis_dir}{date}-{feature}-analysis.md

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，你必须在方案设计中引用相关证据，并在文档末尾输出「知识证据清单」。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 专家团讨论纪要（已由主 Session 收集完成）

    以下是领域专家的意见汇总，你必须在方案设计中标注采纳了哪些专家建议。

    {expert_opinions_summary}

    ## 输出
    将完整的 brainstorm 文档保存到：
    {docs_dir}{feature-name}/{date}-{feature}-brainstorm.md

    文档必须包含：
    - 需求理解（问题现象 + 根因分析）
    - 2-3 个可选方案（含对比矩阵）
    - 推荐方案及理由
    - 交互场景补充分析（如拖拽/滚动等）
    - 专家团讨论纪要（含各专家意见、权重标注及采纳情况）
    - 知识证据清单（引用知识库证据包中的条目）

    完成后回复文档路径和方案摘要。
    """,
    mode="run",
    label="brainstorm"
)

主 Session 等待 brainstorm subagent 完成：

sessions_yield()  # 等待 Sub-1 结果推送

🔀 决策 1: 确认方案（已包含专家团意见）

主 Session:
  1. 读取 Sub-1 输出的 brainstorm.md（内含专家团讨论纪要）
  2. 读取 Sub-2 输出的 analysis.md（关键发现）
  3. 将方案摘要 + 专家团关键建议 + 代码分析发现呈现给用户
  4. 等待用户选择：
     a) 确认方案 X → 进入 Phase 3（需求基线）
     b) 修改方案 → 重新 spawn Sub-1（附修改意见 + 专家纪要）
     c) 需要更多信息 → 补充后重新启动 Phase 2

Phase 3: 需求基线（追加到 proposal.md）⭐ 必选 · 核心文档

方案确认后，生成稳定版需求基线文档。这是核心需求文档——所有后续流程（评审、代码生成、spec 提取）都基于此文档。

主 Session:
  1. 从以下输入提取需求基线：
     - proposal.md 第一章（原始痛点 + 背景）
     - brainstorm.md（确认方案 + 专家意见）
     - analysis.md（技术可行性）
  2. 追加 proposal.md 第二章和第三章：
     - 问题陈述（痛点 + 根因）
     - 目标和成功指标表
     - 用户故事表（Story ID / 故事 / 优先级）
     - 验收标准表（AC编号 / 描述 / 类型 / 关联Story）
     - 不做范围清单
     - 关键假设与验证结果
  3. 保存为 {docs_dir}/proposal.md

文件路径： docs/features/{feature-name}/proposal.md

【强制】追加 proposal.md 基线章节前，必须先读取模板文件 {DOCS_REPO}/assets/templates/proposal.md，严格按模板的章节结构、中文章节标题填充。不得自行改为英文结构或英文标题。

模板参考：{DOCS_REPO}/assets/templates/proposal.md

• 基本信息表（需求ID / 关联原始需求 / 基线版本 / 确认人）
• 问题陈述（一段话概括痛点 + 根因 + 竞品差距）
• 目标和成功指标表（目标 / 指标 / 验证方式）
• 用户故事表
• 验收标准表（含正常/异常/兼容性反例）
• 不做范围清单
• 初始假设表（假设 / 类型 / 验证方式 / 负责人 / 状态）

不涉及项确认

主 Session 向用户展示需求涉及的各个维度，让用户逐项确认哪些是不涉及的：

标准确认清单

用户确认后，将"不涉及"的维度标记为 N/A，传递给 Sub-3 (design-doc)，设计文档中对应章节只需填写"不涉及"即可。

Phase 4: 设计文档

spawn Sub-3：

sessions_spawn(
    task="""
    你是 ArkWeb 设计文档撰写者。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-design-doc/SKILL.md
    2. 按 SKILL.md 的流程生成两个设计文档

    ## 确认的方案（来自决策 1）
    {confirmed_plan_details}

    ## 不涉及项确认
    以下维度已确认为"不涉及"，对应章节只需填写"不涉及"即可：
    {na_dimensions_list}

    ## 需求基线（读取此文件）
    docs/features/{feature-name}/proposal.md

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 参考资料（按需读取）
    - 架构参考：{references_dir}arkweb-architecture.md
    - ACE Engine 索引：{analysis_dir}arkweb-ace-engine-analysis.md
    - 兼容性检查：{WORK_HOME}/docs/api-compatibility-check-arkweb.md
    - brainstorm 文档：{docs_dir}{feature-name}/{date}-{feature}-brainstorm.md

    ## 知识库证据包（主 Session 已在 Phase 2 检索完成）

    以下是通过知识库降级策略检索到的证据，在设计文档中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 输出
    【强制】生成文档前，必须先读取以下模板文件，严格按模板的章节结构、中文章节标题、表格格式填充内容：
    1. `{DOCS_REPO}/assets/templates/requirement.md`
    2. `{DOCS_REPO}/assets/templates/design.md`
    不得自行改为英文结构或英文标题。

    按设计文档 skill 的产出规范，生成两个文档：
    1. requirement.md：需求基线评审文档
    2. design.md：架构设计文档

    保存到：docs/features/{feature-name}/

    requirement.md 必须包含：
    - 需求描述（功能范围 + 典型场景 + 验收标准）
    - 功能设计（ASCII 架构图 + 类图 + 时序图）
    - 接口设计（参数表 + 示例代码）
    - 设备矩阵（1+8 设备差异表）
    - DFX 六维度分析
    - 性能功耗设计
    - 安全隐私设计

    design.md 必须包含：
    - 设计元数据
    - 涉及仓和模块
    - 关键设计决策（ADR）
    - 设计骨架（架构图 + 骨架 Spec 拆分）
    - 风险和开放问题

    注意：不涉及项对应章节填写"不涉及"即可，无需展开。

    完成后回复两个文档的路径和结构摘要。
    """,
    mode="run",
    label="design-doc"
)

Phase 5: 文档评审⭐ 必选

将原 Phase 3（技术评审）和 Phase 3.5（Checklist 规范性检视）合并为一次评审。Sub-4 同时执行技术评审和 14 条 Checklist 检视，产出一份统一的 review.md。

spawn Sub-4：

sessions_spawn(
    task="""
    你是 ArkWeb 文档评审专家。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-spec-review/SKILL.md
    2. 按 SKILL.md 的流程评审设计文档

    ## 待评审文档
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 代码分析结果（用于交叉验证）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 参考资料（按需读取）
    - ACE Engine 索引：{analysis_dir}arkweb-ace-engine-analysis.md
    - WebWebView 分析：{analysis_dir}web-webview-analysis.md

    ## 评审维度

    ### Part A: 技术评审（原 Phase 3）
    1. 完整性检查（10 项）
    2. 一致性检查（6 项）
    3. 技术可行性检查（5 项）
    4. DFX 完整性（6 项）
    5. 文档规范（4 项）

    ### Part B: Checklist 规范性检视（原 Phase 3.5）
    按 14 条 Checklist 规则验证功能设计说明书的符合性，以资深软件设计质量分析师视角检视。

    ## 输出
    将评审报告保存到：
    {docs_dir}{feature-name}/{date}-{feature}-review.md

    报告必须包含：
    - 评审结果：通过 / 需修改 / 不通过
    - Part A 问题清单（🔴必须修改 / 🟡建议修改 / 🟢优秀实践）
    - Part B Checklist 检视结果（🔴必须修改 / 🟡建议修改 / ✅通过）
    - 统计数据（总检查项 / 通过 / 问题数）

    完成后回复文档路径和评审结果摘要。
    """,
    mode="run",
    label="spec-review"
)

🔀 决策 2: 评审决策（强制质量门禁）

主 Session:
  1. 读取 Sub-4 输出的 review.md
  2. 将评审结果呈现给用户：
     - Part A：🔴 必须修改项 + 🟡 建议修改项 + 🟢 优秀实践
     - Part B：Checklist 检视结果
     - 统计数据（总检查项 / 通过 / 问题数）
  3. 根据结果决定：

     ┌─ 有 🔴 必须修改项 ──────────────────────────────────────────────────┐
     │ a) 强制修复：必须修复所有 🔴 项后才能继续。                          │
     │    → 回到 Phase 4 修改设计文档（附评审报告 + 修复清单）           │
     │    → 修复后必须重新 spawn Sub-4 复审                           │
     │    → 复审仍有 🔴 → 继续修复，直到所有 🔴 清零                      │
     │    → 此路径不允许跳过                                          │
     ├──────────────────────────────────────────────────────────────────┤
     │ b) 回到需求/方案阶段（Phase 1 或 Phase 2）：                         │
     │    如果 🔴 问题不是文档层面的，而是涉及需求理解或方案设计：          │
     │                                                                   │
     │    → 回到 Phase 1（需求基线）：                                   │
     │      - 需求理解偏差、用户故事不完整、验收标准缺失                  │
     │      - 目标发行版本/优先级/范围定义错误                            │
     │      → 保留 brainstorm 和 code-analysis 结果（不需要重做）          │
     │      → 仅追加/修改 proposal.md 的需求基线部分                    │
     │                                                                   │
     │    → 回到 Phase 2（方案设计）：                                   │
     │      - 方案选型错误、架构设计不合理、接口设计有问题                  │
     │      - 多个方案都有严重缺陷，需要重新设计                          │
     │      → 保留 proposal.md 和 code-analysis 结果                   │
     │      → 重新 brainstorm 时附上：上次方案的问题 + 评审报告          │
     │                                                                   │
     │    → 判断依据（定性为主，数量为辅）：                             │
     │      - 问题性质 > 问题数量（一个关键架构 🔴 > 十个文档格式 🔴）     │
     │      - 🔴 涉及需求/方案/架构/接口 → 回到 Phase 1 或 2               │
     │      - 🔴 仅涉及文档格式/遗漏/描述 → Phase 4 修复即可              │
     │    → 回到 Phase 1 或 2 时，保留已有分析结果和评审记录               │
     ├──────────────────────────────────────────────────────────────────┤
     │ c) 仅 🟡 建议修改项 ───────────────────────────────────────────────┤
     │    → 询问用户：                                                  │
     │      1) 修改后继续 → 回到 Phase 4 修改 → 可选复审                │
     │      2) 接受现状继续 → 进入 Phase 6（记录为「有条件通过」）         │
     │      3) 回到需求/方案 → 回到 Phase 1 或 Phase 2（理由记录）         │
     ├──────────────────────────────────────────────────────────────────┤
     │ d) 全部通过（无 🔴，🟡 可选） ────────────────────────────────────┤
     │    → 进入 Phase 6                                                │
     │    → 如果有 🟡 未处理项，记录到 spec.md 的「已知限制」章节        │
     └──────────────────────────────────────────────────────────────────┘

评审决策判断依据

当评审结果为「需修改」时，主 Session 必须判断修复路径：

评审记录追溯

评审记录由 Sub-4（spec-review）的 review.md 承载，不额外修改 proposal.md。

每次评审决策后，review.md 追加评审决策记录：

## 评审决策记录

### 评审 1（Phase 5）
- 日期：YYYY-MM-DD
- 评审结果：需修改（🔴 3 项 / 🟡 5 项 / 🟢 12 项）
- 决策：Phase 4 修复（文档层面问题，不涉及方案变更）
- 🔴 修改项：[简要列出]

### 评审 2（Phase 5 复审）
- 日期：YYYY-MM-DD
- 评审结果：有条件通过（🟡 2 项未处理）
- 决策：进入 Phase 6
- 🟡 未处理项：[简要列出，记录到 spec.md 已知限制章节]

注意： review.md 是 Sub-4 的产出物，评审记录追加在 review.md 末尾即可，不需要新建文件。 如果决策为「回到 Phase 1 或 Phase 2」，在 proposal.md 中追加一条简要记录说明回退原因和日期。

修复回路： 评审发现的问题可以回到 Phase 1（需求基线）、Phase 2（方案设计）或 Phase 4（设计文档）。修改后必须重新走 Phase 5 评审。不允许跳过 🔴 必须修改项直接进入 Phase 6。

防跳过机制： 当 Sub-4 返回 🔴 必须修改项时，主 Session 必须明确展示修复方案并等待用户确认。不提供「忽略并继续」选项。

Phase 6: 统一 Spec 生成⭐ 必选

评审通过后，spawn Sub-10 生成统一的 spec.md 和 task.md。spec.md 是 4 合 1 的结构化规格文档，作为 Sub-7（code-gen）的唯一 Spec 输入。task.md 是 AC→Task 追溯的执行计划。

spawn Sub-10：

sessions_spawn(
    task="""
    你是 ArkWeb Spec 生成工程师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-spec-gen/SKILL.md
    2. 按 SKILL.md 的流程生成统一 Spec 和执行计划

    ## 输入文档（全部读取）
    - proposal.md：{DOCS_REPO}/docs/features/{feature-name}/proposal.md
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md
    - review.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-review.md
    - analysis.md：{DOCS_REPO}/analysis/{date}-{feature}-analysis.md

    ## 评审遗留项
    如果 review.md 中有 🟡 未处理项，记录到 spec.md 的「已知限制」章节。

    ## 输出
    【强制】生成文档前，必须先读取以下模板文件，严格按模板的章节结构、中文章节标题填充内容：
    1. `{DOCS_REPO}/assets/templates/spec.md`
    2. `{DOCS_REPO}/assets/templates/task.md`
    不得自行改为英文结构或英文标题。

    1. spec.md（4 合 1：架构设计 / 接口规格 / 特性规格 / 任务规格）
       保存到：docs/features/{feature-name}/spec.md
    2. task.md（AC→Task 追溯 + Task 详情 + 停止条件）
       保存到：docs/features/{feature-name}/task.md

    完成后回复两个文档的路径和结构摘要。
    """,
    mode="run",
    label="spec-gen"
)

主 Session 等待 Sub-10 完成：

sessions_yield()

Phase 7: 代码生成（Spec 驱动）

spawn Sub-7：

sessions_spawn(
    task="""
    你是 ArkWeb 代码生成工程师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-code-gen/SKILL.md
    2. 按 SKILL.md 的流程生成实现代码

    ## 设计文档（读取这些文件）
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 统一 Spec（读取此文件）
    {docs_dir}{feature-name}/spec.md

    **重要：代码生成时优先依据 spec.md 中的结构化定义，设计文档作为上下文补充。接口签名、参数约束、行为场景必须与 Spec 一致。**

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 目标仓库
    - 路径：{SKILL_HOME}/
    - 分支：feat/{feature-name}

    ## 生成范围
    - 核心实现代码（.cpp / .h / .ts / .ets 等）
    - 单元测试代码
    - BUILD.gn 修改（如需要）

    ## 输出
    1. 生成计划（文件清单）
    2. 实现代码文件
    3. 单元测试
    4. 自验证报告

    完成后回复生成摘要和验证结果。
    """,
    mode="run",
    label="code-gen"
)

主 Session 等待 Sub-7 完成：

sessions_yield()

🔀 决策 3: 代码审查

主 Session:
  1. 读取 Sub-7 输出的验证报告
  2. 将生成摘要 + 验证结果呈现给用户
  3. 等待用户审查：
     a) 通过 → 进入 Phase 8（Committer 检视）
     b) 要求修改 → 重新 spawn Sub-7（附修改意见）
     c) 需要查看具体代码 → 展示关键文件内容

Phase 8: Committer 检视

代码生成后，spawn Sub-8 以 Committer 视角检视代码质量。

Sub-8: committer-review

sessions_spawn(
    task="""
    你是 ArkWeb 项目的 Committer。请对以下代码进行检视。

    1. 读取 skill 文件：.skills/arkweb-committer-review/SKILL.md
    2. 按 SKILL.md 的流程执行 Committer 检视

    ## 设计文档（读取这些文件）
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 生成代码目录
    {WORK_HOME}/implementation/{feature-name}/

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 输出
    将检视报告保存到：
    {docs_dir}{feature-name}/{date}-{feature}-committer-review.md

    完成后回复文档路径和检视结果摘要。
    """,
    mode="run",
    label="committer-review"
)

主 Session:
  1. 读取 Sub-8 输出的检视报告
  2. 呈现检视结果（问题清单 + 严重程度）
  3. 等待用户决定：
     a) 通过 → 进入 Phase 9（提交 PR）
     b) 要求修复 → 重新 spawn Sub-7（附检视报告）

Phase 9: 提交 PR

多仓库 PR 协调规则（强制遵守）：

本项目的代码分布在 3 个仓库中，提交 PR 时必须遵循以下规则：

1. Issue 分组：同一层级的仓库共用一个 Issue，不同层级使用独立 Issue

   • 引擎层（chromium_src）→ 独立 Issue，创建在 openharmony-tpc/chromium_src
   • 框架层（web_webview + arkui_ace_engine）→ 共用一个 Issue，创建在 openharmony/web_webview

2. PR 方向：必须从 fork 指向上游原仓，禁止 fork 内部自合并

   • {FORK_OWNER}/xxx:feat/xxx → openharmony(-tpc)/xxx:{base_branch}
   • chromium_src 的 base 分支为 132_trunk，其他仓库为 master

3. PR 模板：创建 PR 前必须先读取目标仓库的 PULL_REQUEST_TEMPLATE.md（路径见 gitcode-pr skill），按模板格式填写 body，禁止使用自定义格式

4. 关联引用：每个 PR 的 body 中必须包含关联 Issue 链接和其他两个仓库的 PR 链接

5. 提交流程：先创建所有 Issue → 读取所有模板 → 创建所有 PR → 互相引用

spawn Sub-9：

sessions_spawn(
    task="""
    你是 GitCode PR 提交助手。请执行以下任务：

    1. 读取 skill 文件：.skills/gitcode-pr/SKILL.md
    2. 按 SKILL.md 的流程执行提交流程

    ## 待提交文件
    {all_document_files_and_code_files}

    ## 提交信息
    - Issue 标题：feat: {feature-name} — {description}
    - Commit message: feat: {description}\n\n- {change_1}\n- {change_2}
    - PR body: 方案概述 + 评审记录 + Closes #{issue_number}
    - 分支名：docs/{feature-name}

    ## 仓库配置
    - 仓库：{owner}/{docs_repo}
    - 本地路径：{SKILL_HOME}/
    - Token：从环境变量读取（优先 `GITCODE_TOKEN`，回退 `GITLAB_TOKEN`）

    ## 输出
    1. Issue URL
    2. PR URL
    3. 提交状态

    完成后回复提交结果。
    """,
    mode="run",
    label="gitcode-pr"
)

主 Session:
  1. 读取 Sub-9 的提交结果
  2. 将 PR 信息呈现给用户
  3. 等待用户确认：
     a) 合并 → 执行合并 API
     b) 修改 → 重新 spawn Sub-9
     c) 拒绝 → 结束
  4. 合并完成 → ✅ 输出最终摘要

决策点汇总

决策点从 9 个缩减为 3 个。原决策点精简为 3 个：方案确认（Phase 2 后）、评审结果（Phase 5 后）、代码审查（Phase 7 后）。Spec 审阅决策点移除（spec 是机器消费的，不需要人工审）。Committer 检视和 PR 提交作为流程内步骤处理。决策 2 新增「回到需求/方案设计」路径和防跳过机制。

数据流

主 Session 直接生成（不通过 subagent）:
  Phase 1:   proposal.md 第一章（原始需求录入）
  Phase 1.5: proposal.md 第二章（澄清记录，多轮对话填充）
  Phase 3:   proposal.md 第三章（需求基线，追加到同一文件）
  Phase 2 Step 2.0: 知识库检索 → 产出「知识库证据包」（注入到后续所有 subagent）
  Phase 2 Step 2.0: 知识库证据包持久化 → Write 到 {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md
  Phase 6:   spec.md（统一规格文档，4 合 1：架构设计/接口规格/特性规格/任务规格）

专家团（主 Session 直接调度，并行 spawn，接收知识库证据包）
  → 按相关度权重筛选专家（🟢核心/🟡关联/⚪旁听，旁听超 5 个跳过）
  → 各专家输出意见 → 主 Session 收集汇总
  → 生成「专家团讨论纪要」（含权重标注 + 共识/分歧/采纳情况）

Sub-1 (brainstorm)
  ← 输入: 专家团讨论纪要 + 用户需求 + 约束 + code-analysis 路径 + 知识库证据包
  → 读取专家纪要，将采纳的意见融入方案设计
  → 写入: docs/features/{feature-name}/{date}-{feature}-brainstorm.md（含专家讨论纪要 + 权重标注）
  → 主 Session 读取 → 呈现给用户 → 决策 1

Sub-2 (code-analysis)
  → 数据源：oh-chromium-knowledge + oh-ai-full-design（🥇）→ DeepWiki MCP（🥈）→ 本地文档（🥉）→ 克隆仓库（🏅）
  → 写入: analysis/{date}-{feature}-analysis.md
  → Sub-3 读取（作为参考资料）
  → Sub-4 读取（作为交叉验证）

Sub-3 (design-doc)
  → 读取: proposal.md + brainstorm.md + analysis.md + 不涉及项确认 + 参考资料
  → 写入: docs/features/{feature-name}/{date}-{feature}-requirement.md + {date}-{feature}-design.md
  → Sub-4 读取（作为评审对象）
  → Sub-7 读取（作为代码生成的依据）
  → Sub-8 读取（作为 Committer 检视的依据）

Sub-4 (spec-review) — v5 合并了原 Sub-4.5 的 Checklist 检视
  → 读取: requirement.md + design.md + analysis.md
  → 写入: docs/features/{feature-name}/{date}-{feature}-review.md
  → 主 Session 读取 → 呈现给用户 → 决策 2

Sub-10 (spec-gen)
  ← 读取: proposal.md + requirement.md + design.md + analysis.md + review.md
  → 写入: docs/features/{feature-name}/spec.md（统一规格文档，4 合 1）+ task.md
  → Sub-7 读取（作为代码生成的主要依据）

Sub-7 (code-gen)
  → 读取: requirement.md + design.md + spec.md + analysis.md
  → 写入: 实现代码 + 单元测试 + BUILD.gn
  → 主 Session 读取验证报告 → 呈现给用户 → 决策 3

Sub-8 (committer-review)
  → 读取: requirement.md + design.md + analysis.md + 生成代码
  → 写入: docs/features/{feature-name}/{date}-{feature}-committer-review.md

Sub-9 (gitcode-pr)
  → 读取: 所有文档文件 + 所有代码文件
  → 写入: GitCode Issue + PR

完整文档产出链路（核心）:
  proposal.md(Ch1) → [Phase 1.5 澄清] → proposal.md(Ch2) → brainstorm.md → requirement.md + design.md → review.md
  → spec.md → 实现代码 → committer-review.md → Issue + PR
  proposal.md(Ch3 需求基线) 在决策 1 后追加

⚠️ 问题预防规则

在执行流程时，必须遵守以下规则：

规则 1：需求澄清不可跳过

• Phase 1 生成 proposal.md 第一章后，必须进入 Phase 1.5 需求澄清
• 不允许用"默认值""推测""大概率"代替用户确认
• 每轮澄清控制在 3-5 个核心问题，记录所有结论到 proposal.md 第二章
• 澄清完成条件全部满足后才能进入 Phase 2

规则 2：subagent 任务描述要明确文件路径

• 在 subagent task 中明确写明"保存到 X 路径"，不要写"保存文档"这种模糊描述
• 如果要生成多个文件，在 task 中列出每个文件的完整路径

规则 3：commit 前检查 git diff

• 在 git commit 前，执行 git diff --stat 确认改动范围
• 检查是否有意外文件被修改或删除

模式切换

模式 B 下，主 session 依次 read 各 SKILL.md 并按流程执行，每个 skill 完成后在当前 session 内做决策。

参考资源

快速入口