ArkWeb 架构师 - Subagent 编排流程

环境变量

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

变量	含义	取值规则	示例
SKILL_HOME	只读资源路径（skill 定义、模板、参考资料、已有分析）	默认 = 主 Session 当前工作目录（cwd）。即 skill 定义的根路径	—
WORK_HOME	产出物路径（设计文档、分析报告、生成代码）	默认 = SKILL_HOME。用户可指定为目标代码仓库（跨仓库场景）	—
DOCS_REPO	设计文档仓库路径（产出物存放位置）	启动时自动发现，找不到则询问用户：按优先级查找 → 找到即使用 → 均未找到则通过 AskUserQuestion 要求用户直接输入路径	—
docs_dir	特性产出物目录	{DOCS_REPO}/docs/features/{feature-name}/	—
analysis_dir	代码分析缓存目录	{DOCS_REPO}/analysis/	—
references_dir	参考资料	{DOCS_REPO}/references/	—

取值逻辑：

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 清单

ID	Skill	职责	输入	输出
Sub-1	arkweb-brainstorm	需求拆解与方案设计	用户需求 + 约束	brainstorm.md
Sub-2	arkweb-code-analysis	代码仓库分析	技术关键词	analysis.md
Sub-3	arkweb-design-doc	设计文档生成	确认方案 + 代码索引 + 不涉及项	requirement.md + design.md
Sub-4	arkweb-spec-review	文档评审（含 Checklist 检视）	设计文档 + 代码索引	review.md
Sub-7	arkweb-code-gen	代码生成（Spec 驱动）	设计文档 + spec.md + 代码索引	实现代码 + 测试
Sub-8	arkweb-committer-review	Committer 代码检视	设计文档 + 生成代码	review-report.md
Sub-9	gitcode-pr	GitCode 提交	文档 + 代码 + 提交信息	Issue + PR
Sub-10	arkweb-spec-gen	统一 Spec + 执行计划生成	proposal + requirement + design + review + analysis	spec.md + task.md

注： 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：

ID	Skill	角色	触发条件
Exp-1	arkweb-expert-performance	⚡ 性能专家	brainstorm 自动触发
Exp-2	arkweb-expert-multimedia	🎬 多媒体专家	brainstorm 自动触发
Exp-3	arkweb-expert-peripheral	🔌 外设服务专家（传感器/电池/唤醒锁/震动/屏幕）	brainstorm 自动触发
Exp-4	arkweb-expert-interaction-security	🔐 交互安全专家	brainstorm 自动触发
Exp-5	arkweb-expert-rendering	🎨 渲染引擎专家	brainstorm 自动触发
Exp-6	arkweb-expert-compositing	🖼️ 渲染合成专家	brainstorm 自动触发
Exp-7	arkweb-expert-interaction-motion	✨ 交互专家（滚动/缩放/菜单/选择/拖拽/上传/焦点/填充/AI化）	brainstorm 自动触发
Exp-8	arkweb-expert-network	🌐 网络加载专家	brainstorm 自动触发
Exp-9	arkweb-expert-js-engine	⚙️ JS 引擎专家	brainstorm 自动触发
Exp-10	arkweb-expert-stability	🛡️ 稳定性与 DFX 专家	brainstorm 自动触发

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

完整流程

阶段编号规范

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

编号	阶段	类型	必选/可选	说明
1	proposal（需求录入+基线）	独立	必选	Phase 1 录入原始需求，Phase 3 追加需求基线，一份文件
1.5	需求澄清（多轮对话）	独立	必选	逐轮向用户提问，澄清待验证假设、范围、子系统影响等，全部澄清后才可进入 Phase 2
2	需求分析	独立	必选	知识库检索 + 专家团 + brainstorm + code-analysis，触发决策 1
3	design（设计文档）	独立	必选	产出 requirement.md + design.md
4	设计文档	独立	必选	产出完整设计文档
5	spec-review	独立	必选	技术评审 + Checklist 一次完成，触发决策 2
6	spec（统一规格文档）	独立	必选	Sub-10 生成 spec.md（4 合 1）+ task.md，code-gen 输入
7	代码生成	独立	必选	Spec 驱动代码生成，触发决策 3
8	Committer 检视	独立	必选	产出检视报告
9	提交 PR	独立	必选	产出 Issue + PR

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	GitCode API 读取 index.json → search/by_feature.json → routing_table.json
🥇 首选	oh-ai-full-design	GitCode API 读取 index.json → search/by_keyword.json → subsystems/ → components/
🥈 次选	DeepWiki MCP	read_wiki_structure → read_wiki_contents → ask_question
🥉 兜底	本地文档	grep 搜索 {DOCS_REPO}/analysis/*.md 和 {DOCS_REPO}/references/*.md
🏅 最终	克隆仓库	git clone --depth=1 到 {DOCS_REPO}/tmp/ 后搜索

两个 🥇 知识库互补使用：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 列表：

#	Expert ID	角色	Skill 路径
1	arkweb-expert-performance	⚡ 性能专家	.skills/arkweb-experts/arkweb-expert-performance/SKILL.md
2	arkweb-expert-multimedia	🎬 多媒体专家	.skills/arkweb-experts/arkweb-expert-multimedia/SKILL.md
3	arkweb-expert-peripheral	🔌 外设服务专家	.skills/arkweb-experts/arkweb-expert-peripheral/SKILL.md
4	arkweb-expert-interaction-security	🔐 交互安全专家	.skills/arkweb-experts/arkweb-expert-interaction-security/SKILL.md
5	arkweb-expert-rendering	🎨 渲染引擎专家	.skills/arkweb-experts/arkweb-expert-rendering/SKILL.md
6	arkweb-expert-compositing	🖼️ 渲染合成专家	.skills/arkweb-experts/arkweb-expert-compositing/SKILL.md
7	arkweb-expert-interaction-motion	✨ 交互专家（滚动/缩放/菜单/选择/拖拽/上传/焦点/填充/AI化）	.skills/arkweb-experts/arkweb-expert-interaction-motion/SKILL.md
8	arkweb-expert-network	🌐 网络加载专家	.skills/arkweb-experts/arkweb-expert-network/SKILL.md
9	arkweb-expert-js-engine	⚙️ JS 引擎专家	.skills/arkweb-experts/arkweb-expert-js-engine/SKILL.md
10	arkweb-expert-stability	🛡️ 稳定性与 DFX 专家	.skills/arkweb-experts/arkweb-expert-stability/SKILL.md

根据 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 向用户展示需求涉及的各个维度，让用户逐项确认哪些是不涉及的：

标准确认清单

#	维度	选项	说明
1	目标设备	全覆盖 / 指定设备	手机/平板/PC/2in1/智慧屏/手表/车机/IoT
2	OHOS 版本	全部 / 指定版本	API Level 范围
3	性能指标	涉及 / 不涉及	是否有明确的性能基线要求
4	安全隐私	涉及 / 不涉及	沙箱/权限/数据安全
5	无障碍	涉及 / 不涉及	大字体/屏幕朗读/适老化
6	全球化	涉及 / 不涉及	多语言/镜像布局
7	1+8 设备差异	涉及 / 不涉及	是否需要逐设备填写差异表
8	兼容性	涉及 / 不涉及	对现有 API 的影响
9	DFX（崩溃/ANR/日志）	涉及 / 不涉及	稳定性相关设计
10	功耗	涉及 / 不涉及	电池/发热影响

用户确认后，将"不涉及"的维度标记为 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. 根据结果决定：