arkweb-architect

# 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） ```python 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 路径 |