ADR-AIOS-03 · 前端 4 agent 按 stage 分工 + test-aux 复用
1. 上下文(Context)
1.1 触发事件
2026-05-19 ~ 2026-05-24 期间 · ClaudeA 在 v3 框架下执行"17 phase 全包前端"任务,进展严重不顺: - 用户口头多次推动 toolbar/dock 实现(本应自动按"五段"做) - 卡在底部 ratio 比例显示 / 锁定悬浮模式切换 / split 拖拽等窗口管理细节 - 已派的 PATCH-01(基于 DIAGNOSIS-2026-05-19 起草)有错误前提(把 plan 提案当事实 · 包括"音频引擎组"等)
1.2 二次代码核查(2026-05-24)发现的真值
通过 4 路 use_subagents 并行扫描主仓库 04_development/frontend_vue3/,修正了 3 处认知偏差:
| 项 | DIAGNOSIS-2026-05-19 认为 | 2026-05-24 实际 |
|---|---|---|
| Preset 管理 | 缺失 | ✅ 已完整(presetStore 168 行 + PresetPanel 788 行) |
| Profile 管理 | 缺失 | ✅ 已完整(ProfileSidebar 1046 行) |
| 浮窗管理 🪟 | 完全裸按钮 | ⚠️ XiLink 局部已有多开 dialog 容器 · 缺统一 store + Shell 顶栏 popover |
| 顶栏"音频引擎组"段④ | demo 漏档要做 | ❌ demo 当前 DOM 没有 · 是 REFACTOR-v4-PLAN.md 提案 · 未落地 |
| 4 stage 业务进度 | 一概未实现 | ⚠️ 差异巨大:XiLink 70% / XiForge 50%(业务厚) / XiTune 90%(业务最厚) / XiTest 25% |
1.3 用户的关键洞察
| 用户原话 | 解读 | 影响 |
|---|---|---|
| "shell 通用的基本不用动了 · 每个 stage 实现自己的功能注入就好" | Shell 静态结构 7-8 项已就绪 · 工作重心应转到 stage 协议层 | 单 agent 全包不必要 |
| "三个 agent 应该是可以统一按照 stage 来进行不同的分工" | 目录隔离 + 协议规范 = 多 agent 可并行 | 直接催生本 ADR |
| "从功能验证逻辑上是不是 XiForge → XiTune → XiTest" | 业务数据流序列(模块 → 链路 → 调音 → 测试) | 决定派发顺序 |
| "右侧主要是辅助测试 scope 频响相位 RMS · 后面几个模块通用" | XiTune/XiTest 右 dock 有重叠 | 决定抽公共 test-aux 组件 |
1.4 demo 真值的 dock 重叠分析
基于 4 个 demo stages/stage-*.html 的 dock-inject 调用 · 横向对照:
| 语义 | XiLink | XiForge | XiTune | XiTest | 重叠数 |
|---|---|---|---|---|---|
| 频响 Magnitude | (无 dock-inject) | - | xt-freq |
xtest-freq |
2 |
| 相位 Phase | - | - | xt-phase |
xtest-phase |
2 |
| RMS / Peak 8ch | - | - | xt-rms |
xtest-rms |
2 |
| 参考曲线 Reference | - | - | xt-ref |
xtest-ref |
2 |
| 各 stage 独有 | - | publish(独立) | xical/hist/aux | rta/coh/ir | 0 重叠 |
结论:XiTune 与 XiTest 右侧 7 dock 中有 4 个完全重叠 · 是抽公共组件的最大 ROI 机会。
2. 决议(Decision)
2.1 主决议
废弃 v3"ClaudeA 一人跑 17 phase"路线 · 改为 4 agent 按 stage 目录分工并行。
| Agent | 独占目录 | 任务 | 时长 |
|---|---|---|---|
| ClaudeA | stages/xilink/ + components/shell/ |
XiLink 收尾 + Shell 基建(浮窗+窗口管理 PATCH §A1-A8) | 1.5d |
| ClaudeB | stages/xiforge/ |
XiForge shell 注入(左3+右3 dock + 4 toolbar + 3 mode) | 1.5d |
| ClaudeC | stages/xitune/ + 新建 components/drawers/test-aux/ |
XiTune shell 注入 + 抽 4 个公共测试 dock 组件 | 2d |
| ClaudeD | stages/xitest/ |
XiTest shell 注入 · 复用 ClaudeC 的 test-aux | 1.5d |
总工作量 6.5 工作日 · 4 agent 并行实际墙钟 ~7 天(含 review buffer)。
2.2 子决议 · test-aux 公共组件抽取
ClaudeC 在做 XiTune 时 · 必须把以下 4 个右 dock 抽到 src/components/drawers/test-aux/:
- FreqResponseDrawer.vue(频响 Magnitude · ~150 行)
- PhaseDrawer.vue(相位 Phase · ~120 行)
- RmsDrawer.vue(RMS / Peak 8ch · ~100 行)
- ReferenceCurveDrawer.vue(参考曲线 · ~180 行)
强约束:
- 这 4 个组件只通过 props + 通用 store 取数据 · 不允许 import { ... } from '@/stages/xitune/...'
- ClaudeD 后续做 XiTest 时直接 import + 写 wrapper 适配 testStore 数据 · 一次实现两次用
2.3 子决议 · 派发顺序
按业务依赖链(用户洞察)+ test-aux 复用约束:
第 1 阶段(并行 · Day 6-8):
├── ClaudeA(XiLink + Shell 基建)→ 1.5d
└── ClaudeB(XiForge shell 注入)→ 1.5d
第 2 阶段(Day 9-10):
└── ClaudeC(XiTune + 抽 test-aux)→ 2d
[依赖] ClaudeA Step B 完成(floatingStore.ts)· 否则 Step 5 卡
第 3 阶段(Day 11-12):
└── ClaudeD(XiTest · 复用 test-aux)→ 1.5d
[依赖] ClaudeC Step 2 完成(test-aux 4 组件就绪)
2.4 子决议 · 浮窗管理归 ClaudeA 抽公共
XiLink 当前已有局部多开 dialog 容器(openTuningDialogs[])· ClaudeA 必须把它抽到 src/stores/floatingStore.ts + src/components/shell/FloatManager.vue · 让其他 stage 调用:
- floating.open({ instanceId, moduleId, title, stage })
- 顶栏 🪟 按钮接通 popover 列表(显示所有 stage 当前打开的 dialog)
理由:浮窗是 Shell 级跨 stage 共用基建 · 不属于任何单 stage。
2.5 子决议 · 4 agent 边界铁律
继承 ADR-AIOS-01 的目录独占铁律:
| 资源 | 写权限 | 读权限 |
|---|---|---|
src/stages/xilink/ |
ClaudeA 独占 | 其他 agent 不读 |
src/stages/xiforge/ |
ClaudeB 独占 | 其他 agent 不读 |
src/stages/xitune/ |
ClaudeC 独占 | 其他 agent 不读 |
src/stages/xitest/ |
ClaudeD 独占 | 其他 agent 不读 |
src/components/shell/ |
ClaudeA 独占 | 其他 agent 只读引用 |
src/components/drawers/test-aux/ |
ClaudeC 独占 | ClaudeD 只读引用 |
src/stores/shellSlotsStore.ts |
共享只读(已就绪 · 不改) | 全部 |
src/stores/floatingStore.ts |
ClaudeA 创建后只读 | 全部 |
src/stores/layoutStore.ts |
ClaudeA 可补 setDrawerSplitRatio 等缺失 action · 其他只读 | 全部 |
src/types/protocol.ts |
共享只读 | 全部 |
3. 备选方案(Alternatives Considered)
3.1 方案 A · 继续单 agent 全包(ClaudeA)+ 追加 PATCH
否决。 - ClaudeA 在 v3 下已暴露范围过大问题(诊断报告 R1/R2) - XiTune 12530 行业务 + XiForge 4628 行业务 · 单 agent 串行至少 5-7 工作日 - 无法利用 test-aux 复用 ROI
3.2 方案 B · 2 agent 分前端 / 后端
否决(已是 v3 现状)。 - 前端单 agent 仍然过载 - 不解决 stage 间业务依赖问题
3.3 方案 C · 4 agent 但不抽 test-aux(各做各的)
否决。 - XiTune/XiTest 4 个测试 dock 重写两份 · 浪费 ~600 行代码 · 风险:UI 不一致 - 错过用户洞察的关键 ROI
3.4 方案 D · 4 agent + test-aux 复用(本 ADR)✅
采纳。
3.5 方案 E · 5+ agent(每个 dock 一个 agent)
否决。 - 协调成本爆炸 - 目录隔离粒度不够清晰 - review 困难
4. 后果(Consequences)
4.1 正面后果
- 并行度提升 4 倍(单 agent → 4 agent)· 墙钟时间从 ~6 工作日缩到 ~3 工作日(第 1 阶段)
- test-aux 复用 · 节省 ClaudeD 50% 工作量(4 个右 dock 直接 import)
- 目录隔离 · 4 agent 间零写冲突 · 不需要 lock 协议
- 业务零回退 · 每个 PROMPT 明示"不要改业务逻辑" · 只接通 shell 协议
- 可观测性增强 · 4 个 stage 进度独立可追踪 · KANBAN §1.1-1.4 各自一节
4.2 负面后果
- 协调成本上升 · AIOS 需要同时 review 4 个 agent 的 commit
- 派发依赖链 · ClaudeC 等 ClaudeA Step B / ClaudeD 等 ClaudeC Step 2 · 需要明确节奏
- 公共组件契约风险 · 若 test-aux 4 组件 props 设计不通用 · ClaudeD 复用时会卡
4.3 风险缓解
| 风险 | 触发条件 | 预案 |
|---|---|---|
| ClaudeA Step B 延期 → ClaudeC Step 5 卡 | floatingStore.ts 没按时落 | ClaudeC 先做 Step 1-4 · Step 5 留 buffer |
| ClaudeC test-aux 设计耦合 xitune store | Step 2 review 时发现 import 路径含 /stages/xitune/ |
AIOS 强制打回 · 必须 props 化 |
| ClaudeD 跑通后发现 testStore 字段缺失 | wrapper 取不到 currentResult.{freqResponse, phase, rms, reference} | wrapper 加 ?? [] 兜底 + TODO 注释 · 后续 testStore 补字段 |
| 4 agent 同时改 layoutStore | 罕见 · 仅 ClaudeA 写 setDrawerSplitRatio 时 | ClaudeA 先做 layoutStore 补 action · commit 后其他 agent rebase |
4.4 不影响
- 后端 ClaudeB(此处指后端 CLI · 与 stage 分工的 ClaudeB-XiForge 是不同 CLI)继续 contract-v1 + B5-B13 任务
- Continue 备份 + 文档同步不变
- ADR-AIOS-01 5 角色协作框架仍然适用 · 本 ADR 只是细化前端"ClaudeA"角色为 4 个 sub-agent
5. 命名空间澄清(避免混淆)
ADR-AIOS-01 / KANBAN §2 中的"ClaudeB"指后端 CLI(独占 backend_csharp + dsp_algo + contracts)。
本 ADR 引入的"ClaudeB"指前端 CLI(独占 stages/xiforge)· 是临时按 stage 分工的代号。
为避免混淆,后续 standup / KANBAN / commit msg 需明确: - "ClaudeB-后端" = 原 ClaudeB(B1-B13 任务) - "ClaudeB-XiForge" = 本 ADR 的前端分工 ClaudeB
或者改名为 ClaudeB-FE / ClaudeB-BE 区分。建议人类拍板命名规范(列入 §6 待决议项)。
6. 待决议项(下次 standup 拍板)
- ☐ ClaudeB 命名歧义如何解决?(选项:ClaudeB-FE/BE · ClaudeB-XiForge/contract · 重命名前端为 ClaudeF · ...)
- ☐ 第 2 阶段 ClaudeC 的 CLI 是新开还是接力 ClaudeB-XiForge?(影响 commit 历史归属)
- ☐ 第 3 阶段 ClaudeD 同上
- ☐ test-aux 4 组件的 review 阈值是 props 通用性 · 还是 demo 视觉对照?(决定 review 时长)
- ☐ 是否需要在 contract-v1 中增加"shell-slot-store action 命名空间"?(B1 任务 · 影响后端 ClaudeB 工作量)
7. 实施清单
- 起草 4 份 PROMPT(claudea-xilink-finalize / claudeb-xiforge / claudec-xitune / clauded-xitest)
- 更新 KANBAN §0 § §5 §8 §10
- 起草本 ADR(drafting 状态)
- 人类拍板待决议项 §6 · 决议后改 ADR 状态为 accepted
- 派发 ClaudeA 第 1 阶段任务
- 派发 ClaudeB-XiForge 第 1 阶段任务
- 监控第 1 阶段 commit 进度 · 24h 内 review
- 第 2 阶段派发 ClaudeC(等 ClaudeA Step B 完成 · 或先派非依赖部分)
- 第 3 阶段派发 ClaudeD(等 ClaudeC Step 2 完成)
- 4 阶段全部完成后 · ADR 状态 superseded → 写 ADR-AIOS-04(若有进一步重组)
8. 关联文档
- 上游决议:ADR-AIOS-01(5 角色协作框架)
- 触发诊断:DIAGNOSIS-2026-05-19
- 实施 PROMPT:
PROMPT-claudea-xilink-finalize.mdPROMPT-claudeb-xiforge-shell-inject.mdPROMPT-claudec-xitune-shell-inject.mdPROMPT-clauded-xitest-shell-inject.md- 已废弃:
PROMPT-shell-slot-store-PATCH-01.md(被 ClaudeA-rev2 替代)
ADR-AIOS-03 v1.0 · 2026-05-24 · drafting · 待人类拍板 §6 待决议项后转 accepted