| name | arkweb-architect |
| description | ArkWeb AI 辅助设计流程编排入口。当用户提到 ArkWeb、chromium、web_webview、WebView、需求分析、设计文档等关键词时触发。每个 skill 对应一个独立 subagent，主 session 仅做调度和决策。 |
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/ | — |
取值逻辑：
- 主 Session 启动时，
SKILL_HOME = 当前工作目录（cwd）
- 如果用户指定了其他工作目录，则
WORK_HOME = 用户指定路径；否则 WORK_HOME = SKILL_HOME
DOCS_REPO 启动时检查（按优先级依次尝试，找到第一个满足条件的即停止）：
{SKILL_HOME} 本身（检查是否包含 docs/features/ 和 analysis/ 子目录）{SKILL_HOME}/{DOCS_REPO_DIR}（检查该目录是否存在且包含 docs/ 和 analysis/ 子目录）- 从
SKILL_HOME 逐级向上查找包含 docs/features/ 和 analysis/ 子目录的目录
- 以上均未找到 → 使用
AskUserQuestion 向用户询问："未找到设计文档仓库（需包含 docs/features/ 和 analysis/ 目录），请输入完整路径"
- 主 Session 在 spawn subagent 时，将上述变量替换为实际绝对路径后注入 task 描述
- 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 为私有仓库，无权限时跳过。
执行步骤：
- 从 Phase 1 的 proposal.md 中提取需求关键词
- 🥇 读取
skills/oh-chromium-knowledge/SKILL.md 获取知识库读取协议
- 🥇 按
index.json → search/by_feature.json → routing_table.json 流程检索，匹配需求关键词
- 🥇 读取 oh-ai-full-design 知识库，按
index.json → search/by_keyword.json → subsystems/ → components/ 流程检索（如无权限跳过）
- 记录命中结果（相关仓库、模块、代码路径、架构文档、子系统/部件/API）
- 🥈 对于 🥇 未覆盖的需求关键词，使用 DeepWiki MCP 补充检索
- 🥉 对于 🥇🥈 都未覆盖的细节，搜索本地文档
- 🏅 如仍有未覆盖项，按需克隆仓库
- 汇总为「知识库证据包」，格式如下：
## 知识库证据包
### 🥇 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}" → {发现摘要}
- 【强制持久化】 将完整证据包（含所有原始检索内容）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 先判定每个专家的相关度级别：
权重规则：
- 核心专家（权重 3x）：需求直接相关的领域专家，其意见在汇总时优先级最高
- 关联专家（权重 2x）：需求间接相关的领域专家，其意见有参考价值
- 旁听专家（权重 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 汇总为「专家团讨论纪要」：
- 分类整理：将专家意见按"采纳/参考/暂不考虑"分类
- 提取共识：多个专家共同关注的问题
- 识别冲突：不同专家之间的意见分歧
- 权重标注：每个专家意见标注权重级别（🟢/🟡/⚪）
汇总格式：
## 🧠 专家团讨论纪要
### 共识（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. 根据结果决定：
┌─ 有 🔴 必须修改项 ──────────────────────────────────────────────────┐
│ 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 必须判断修复路径：
| 🔴 问题特征 | 建议路径 | 理由 |
|---|
| 需求理解偏差 / 用户故事缺失 | 回到 Phase 1 | 需求基线有问题，brainstorm 基础不对 |
| 验收标准不完整 / 范围定义错误 | 回到 Phase 1 | Phase 3 需求基线需要修正 |
| 方案选型错误 / 架构不合理 | 回到 Phase 2 | 文档层面修复无法解决根本问题 |
| 接口设计与需求矛盾 | 回到 Phase 1 | 需求基线和方案都需要重新对齐 |
| 文档格式 / 章节遗漏 / 描述不清晰 | Phase 4 修复 | 不涉及需求/方案变更 |
| 示例代码 / 参数表不完整 | Phase 4 修复 | 补充即可 |
| DFX / 兼容性分析不充分 | Phase 4 修复 | 补充分析即可 |
评审记录追溯
评审记录由 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 时必须遵循以下规则：
-
Issue 分组：同一层级的仓库共用一个 Issue，不同层级使用独立 Issue
- 引擎层（chromium_src）→ 独立 Issue，创建在
openharmony-tpc/chromium_src
- 框架层（web_webview + arkui_ace_engine）→ 共用一个 Issue，创建在
openharmony/web_webview
-
PR 方向：必须从 fork 指向上游原仓，禁止 fork 内部自合并
{FORK_OWNER}/xxx:feat/xxx → openharmony(-tpc)/xxx:{base_branch}- chromium_src 的 base 分支为
132_trunk，其他仓库为 master
-
PR 模板：创建 PR 前必须先读取目标仓库的 PULL_REQUEST_TEMPLATE.md（路径见 gitcode-pr skill），按模板格式填写 body，禁止使用自定义格式
-
关联引用：每个 PR 的 body 中必须包含关联 Issue 链接和其他两个仓库的 PR 链接
-
提交流程：先创建所有 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. 合并完成 → ✅ 输出最终摘要
决策点汇总
| # | 决策 | 时机 | 可选操作 | 默认行为 |
|---|
| 1 | 确认方案 | Phase 2（Sub-1 + Sub-2 完成） | 选方案 / 修改 / 补充信息 | 等待用户 |
| 2 | 评审决策 | Phase 5（Sub-4 完成，含技术评审 + Checklist） | 🔴强制修复 / 回到需求(Phase 1) / 回到方案(Phase 2) / 🟡可选修复 / 有条件通过 | 🔴不可跳过，🟡询问用户 |
| 3 | 代码审查 | Phase 7（Sub-7 完成） | 通过 / 要求修改 / 查看代码 | 等待用户 |
决策点从 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 确认改动范围
- 检查是否有意外文件被修改或删除
模式切换
| 条件 | 模式 |
|---|
sessions_spawn 可用 + 复杂需求 | 模式 A（Subagent 编排） |
sessions_spawn 不可用 | 模式 B（主 session 串行调用 skill） |
| 用户要求串行 | 模式 B |
模式 B 下，主 session 依次 read 各 SKILL.md 并按流程执行，每个 skill 完成后在当前 session 内做决策。
参考资源
| 文档 | 路径 |
|---|
| ACE Engine 分析 | analysis/arkweb-ace-engine-analysis.md |
| WebWebView 分析 | analysis/web-webview-analysis.md |
| 架构参考 | references/arkweb-architecture.md |
| 兼容性检查 | docs/api-compatibility-check-arkweb.md |
| 设备矩阵 | references/device-matrix.md |
| 竞品分析 | references/competitor-analysis.md |
快速入口
| 用户意图 | 启动的 Subagent |
|---|
| "帮我分析这个需求" | 专家团 + Sub-1 brainstorm + Sub-2 code-analysis（并行 → 收集 → brainstorm） |
| "生成设计文档" | Sub-3 design-doc |
| "评审这个文档" | Sub-4 spec-review（含 Checklist 检视） |
| "生成代码" | Sub-7 code-gen |
| "Committer 检视" | Sub-8 committer-review |
| "分析 xxx 仓库" | Sub-2 code-analysis |
| "提交到 GitCode" | Sub-9 gitcode-pr |
| "完整流程" | 专家团 + 8 个 subagent + 3 个决策点 |
