跳转至
ACCEPTED

ADR-AIOS-01 · 5 角色协作框架(方案 A · v3 · 跨栈职能解耦)

状态:accepted · 2026-05-19 傍晚晚(v3 修订)· 由人类(项目总指挥)拍板

演进:v1(4 智能体) → v2(phase 时间窗解耦 · 串行错误) → v3(跨栈职能解耦 · Day 1 真正并行)

1. 背景

D4 Frontend-Vue3 实施进入 17 phase 阶段(详见 ../../30-frontend-vue3/00-master-plan.md),单智能体独立推进存在以下瓶颈:

  1. 上下文窗口压力:跨前端 / 后端 / DSP 的细节同时装入单个会话,频繁触发上下文截断
  2. 串行执行瓶颈:17 phase 顺序执行,预计 8-10 周
  3. 领域切换成本:每次从架构思考切到实施细节都有 token 浪费
  4. 没有冲突隔离机制:智能体与人类手动改动混在同一仓库,commit 历史混乱

同时,可用 AI 工具有 5 种载体可并行: - Cline 插件(VSCode 侧边栏 · 即本会话的载体) - Claude Code CLI 终端 #1(可独立登录一个工作目录) - Claude Code CLI 终端 #2(可独立登录另一个工作目录) - Continue 插件(VSCode 侧边栏 · 同款 Sonnet 但卡顿) - Copilot(GitHub Copilot Pro · IDE 行内补全)

2. 候选方案对比

方案 描述 加速比 复杂度
方案 A v3(已选) 5 角色协作 · 跨栈职能解耦 · Cline=AIOS 调度内核 + ClaudeA 前端独占 + ClaudeB 后端+DSP+契约独占 + Continue + Copilot · Day 1 起真正并行 ~20-25% 高(需文档体系)
方案 A v2(已废弃) 同 v3 但用 phase 1-8 vs 9-17 时间窗解耦 实际 ~5%(串行错误) 高
方案 B 仅 2 角色(单 Claude Code + Cline) ~15% 中
方案 C 单一智能体串行 17 phase 0%(基线) 低
方案 D 全异步(无调度 · 自由协作) 不可预测(可能负加速) 低(但风险高)

3. 决策

采纳方案 A v3 · 5 角色协作模式 · 跨栈职能解耦:Cline 作为 AIOS 调度内核的化身;Claude Code 拆成 ClaudeA / ClaudeB 两个 CLI 终端按跨栈职能解耦(ClaudeA 独占 frontend_vue3/ · ClaudeB 独占 backend_csharp/ + dsp_algo/ + contracts/);Day 1 起即并行;Continue 异步备份;Copilot 人类增益。

3.1 角色与工作量分配(v3 · 2026-05-19 傍晚晚 修订)

角色 载体 工作量占比 主战场
AIOS / Cline Cline 插件(VSCode 侧边栏 · 本会话) 10%(调度成本) 调度内核:派任务 / 仲裁 / ADR / KANBAN · 不写业务代码
ClaudeA Claude Code CLI 终端 #1(Sonnet 4.6) 50% frontend_vue3/ 全程独占 · 17 phase 全部前端
ClaudeB Claude Code CLI 终端 #2(Sonnet 4.6) 30% backend_csharp/ + dsp_algo/ + contracts/ 全程独占 · 后端 + DSP + 契约 + XiForge MC 融合
Continue Continue 插件(VSCode 侧边栏) 5% 文档同步 + 备份 + 周复盘
Copilot GitHub Copilot Pro(IDE 行内补全) 5% 人类增益(被动)

v3 关键变化(原 v2 已废弃): - 废弃 v2 "phase 1-8 vs phase 9-17 时间窗解耦"(实际是串行 · 不能同时干活) - 改为 跨栈职能解耦:目录天然隔离 · 双 CLI Day 1 起即可全程并行 - ClaudeB 全程在线 · "提前铺路"为 ClaudeA 准备契约/API/DSP

3.2 命名规范

  • ❌ 不使用代号 A/B/C/D
  • ✅ 使用具体名字:ClaudeA(CLI #1) / ClaudeB(CLI #2) / Continue / Copilot
  • ✅ 调度内核名:AIOS / Cline(同一物 · 两个名字)
  • ✅ 人类阅读文档前缀:Human-*(如 Human-README.md)

3.3 核心机制(5 件套)

  1. 仓库分区铁律:详见 ../agents/Repository-Partition.md · v3 改为跨栈职能解耦(ClaudeA 独占 frontend_vue3/ · ClaudeB 独占 backend_csharp/ + dsp_algo/ + contracts/)
  2. 协议契约 contract-first:ClaudeB 写 ../contracts/protocol-v1.md · Day 5 freeze 后全员遵守
  3. commit 串行:同一目录同一时刻只允许一个角色 commit(v3 由于目录已天然隔离 · 实际上不需要锁)
  4. 决策升级链:子智能体 → AIOS / Cline 仲裁 → 人类拍板 → ADR
  5. 资源隔离:5173(ClaudeA vite) / 5000(ClaudeB dotnet) / 8000(Continue mkdocs) · 端口互不冲突

3.4 文档落地

  • 新建 docs/08-implementation/40-aios/ 子目录
  • 17 文档(v2 重构后)全部按 mkdocs frontmatter 规范
  • 通过 mkdocs nav 可访问 · 路径 08-implementation/40-aios/

4. 真实加速比测算

理论加速 = 双 Claude Code CLI 真正并行 + Continue 异步 ≈ 2.5×
实际加速 = 理论加速 × (1 - 各种损耗)
        = 2.5× × (1 - 0.25 - 0.15 - 0.10 - 0.10)
        = 2.5× × 0.40
        ≈ 1.0× (相对单智能体的并行收益)

但因为消除了串行瓶颈(单智能体 17 phase 顺序跑 → ClaudeA 全程跑前端 + ClaudeB 全程跑后端/DSP/契约 并行铺路),
真实周期压缩 ≈ 20-25%
即 8-10 周 → 6-8 周

关键约束： - 必须 Week 1 完成 contract-v1 freeze · 否则加速比降为 ~10% - KANBAN 必须每日维护 · 否则智能体派活精度降为 ~70%

5. 后果与风险

5.1 正面后果

  • ✅ 周期压缩 20-25%
  • ✅ ClaudeB 上下文压力下降(只装契约/后端/DSP 内容,不装前端 Vue 实现细节)
  • ✅ 决策有据可查(ADR 永久存档)
  • ✅ commit 历史清晰(ClaudeA 全在 frontend_vue3/ · ClaudeB 全在 backend_csharp/+dsp_algo/+contracts/ · 跨栈边界明确)
  • ✅ 可扩展:未来可加 ClaudeC / ClaudeD(在本框架内 · 继续按职能切分如 ClaudeC=测试 / ClaudeD=部署)

5.2 负面后果 / 风险

  • ❌ 引入文档维护成本(17 篇 + 持续更新 KANBAN)
  • ❌ 需要人类每日 10 分钟 standup
  • ❌ Token 成本上升(~\(50/天 vs 单干 ~\)20/天)
  • ❌ 出现"调度漂移"风险(AIOS 派活不准 → 重复劳动)
  • ❌ 双 Claude Code CLI 启动可能遇到 token 共享 / 工作目录隔离问题(Day 1 必须验证)

5.3 缓解措施

  • 文档维护成本 → 用 prompts/templates 复用 · 减少手写
  • standup 成本 → 4 行模板 · ≤ 10 分钟
  • Token 成本 → Week 1 监控 · 超支则降级到 3 角色(砍 Continue 或合并 ClaudeA/ClaudeB)
  • 调度漂移 → KANBAN 严格按日更新 · 每周一复盘
  • 双 CLI 启动 → Day 1 先用两个独立工作目录 + 不同 git 用户名验证可并行

6. 替代方案否决理由

方案 B(2 角色 · 单 Claude Code + Cline)

  • 加速比仅 15% · 不显著高于单干
  • 没有 Continue 备份,任一角色宕机即停摆
  • 单 Claude Code 实例仍受单线程瓶颈
  • 否决

方案 C(单干)

  • 基线 · 不解决任何瓶颈
  • 否决

方案 D(全异步无调度)

  • 没有冲突隔离 · commit 必然打架
  • 无法仲裁分歧 · 决策漂移
  • 否决

7. 实施动作(v3 重构后)

  • 创建 docs/08-implementation/40-aios/ 目录
  • 写入 17 文档(Human × 4 + agents × 4 + 调度 × 3 + prompts × 4 + contracts × 1 + ADR × 1 + index × 1)
  • 初始化 KANBAN.md(17 phase 全部由 ClaudeA 跑 + ClaudeB 13 项后端横切主线 + Continue 主线 + AIOS 主线)
  • 写 WEEK-1-PLAN.md(5 角色每日任务分配 · 双 CLI Day 1 起即并行)
  • 起 contract-v1.md 占位(待 ClaudeB 填)
  • 更新 mkdocs.yml nav 增加 40-aios 入口 + 重命名 prompt 模板(claude-c → claude-a / claude-a → claude-b)
  • 在 30-frontend-vue3/00-master-plan.md 末尾追加交叉引用
  • 在 02-products/P1-xistudio/v1.2-ide-architecture.md §13 末尾追加 §13.11 AIOS 预告
  • mkdocs build 0 errors 验证(待最终 build 确认)
  • v2 命名重构(2026-05-19 傍晚:Cline=AIOS 化身 + 双 Claude Code CLI)
  • v3 架构修正(2026-05-19 傍晚晚:废弃 phase 时间窗 · 改为跨栈职能解耦 · Day 1 真正并行)
  • 一次性 commit refactor(aios): rebuild to 5-role architecture v3 (cross-stack functional decoupling)

8. 复盘节点

时间 复盘事项
Week 1 末 contract freeze 是否如期 · 加速比初步估算
Week 2 末 KANBAN 维护精度 · 仲裁次数统计
Week 4 末 是否进入预算告警 · 是否需降级
Week 6 末 周期压缩是否达标（vs 8-10 周基线）

每次复盘结果若改变本 ADR 决议 → 写新 ADR-AIOS-NN（不修改本 ADR · 状态可改 superseded）。

9. 相关文档

10. 决议者

  • 提案者:AIOS / Cline(本会话)· 2026-05-19 上午
  • 决议者:人类(项目总指挥)· 2026-05-19 下午(v1) + 2026-05-19 傍晚(v2 命名澄清) + 2026-05-19 傍晚晚(v3 跨栈职能解耦)
  • 执行者:AIOS / Cline + ClaudeA(CLI #1 · 前端独占) + ClaudeB(CLI #2 · 后端+DSP+契约独占) + Continue + Copilot
版本 日期 变化
v1.0 2026-05-19 上午 初始决议 · accepted(4 智能体命名)(已被 v2 取代)
v2.0 2026-05-19 傍晚 5 角色 v2:Cline=AIOS 化身 + Claude Code 拆 ClaudeA/ClaudeB + phase 时间窗解耦(已被 v3 取代 · 串行错误)
v3.0 2026-05-19 傍晚晚 5 角色 v3:跨栈职能解耦 · ClaudeA 独占 frontend_vue3 全程 · ClaudeB 独占 backend+DSP+contracts 全程 · Day 1 起真正并行