[Architecture Review] 当前多 Agent 架构与实现主路径不一致（需先收敛基础闭环）

[xu75]

背景

目标是参考 cat-cafe-tutorials，构建多 Agent 协作编程平台。当前对照 docs/Architecture/multi-agent-architecture.md 与现有实现后，发现"架构承诺"与"执行主路径"存在明显偏差。

主要问题（按优先级）

P0-1 编排层绕过 Engine/Provider 抽象

• 现状：src/coordinator.js 直接调用 runClaude，未走 ProviderAdapter + Engine 主链路。
• 风险：后续多模型路由、fallback、统一事件语义会被迫重构主干。

P0-2 存在两套并行执行引擎

• 现状：src/engine/claude.js 与 src/engine/runner.js 都在处理 spawn/超时/信号。
• 风险：同类任务日志语义分叉，回放与排障成本上升。

P1-1 Orchestrator 仅 demo，未形成 FSM

• 现状：只有"一次问答 + reviewer stub"，缺少 intake/plan/build/review/test/iterate/finalize 状态与终止条件。
• 风险：无法形成可持续的多 Agent 闭环。

P1-2 Agent 输出契约未结构化

• 现状：Reviewer 仍是纯文本 stub，未输出 must_fix/nice_to_have/tests/security 等结构化字段。
• 风险：无法自动决策迭代、无法稳定衔接 test gate。

P1-3 事件元数据不足

• 现状：RunEvent 缺少 task_id/round_id/agent_role/attempt 等关键维度。
• 风险：多角色并发时难以按任务-回合聚合与回放。

P2-1 安全隔离未落地

• 现状：文档提到 worktree/临时分支隔离，但执行面尚未实现。
• 风险：自动改码过程对工作区污染与误操作风险偏高。

P2-2 文档目录命名不一致

• 现状：文档中 docs/architecture/ 与仓库实际 docs/Architecture/ 不一致。
• 风险：跨平台（大小写敏感）下路径约定失效。

建议落地顺序（最小闭环）

1. 收敛到单一执行主链：统一走 ProviderAdapter -> Engine，冻结/移除直连 runClaude 路径。
2. 先实现最小 FSM：build <-> review 两状态 + 迭代上限 + 失败可视化。
3. 为 Reviewer 引入 JSON schema 校验与自动纠偏重试。
4. 扩充 RunEvent 元数据（task/round/role/attempt），打通可回放索引。
5. 再引入 Tester 阶段和 worktree 隔离，最后扩展多 Provider 路由。

参考

• https://github.com/zts212653/cat-cafe-tutorials
• docs/Architecture/multi-agent-architecture.md