Crush Agent 体系统一演进路线图

> 版本：v2.0 > 日期：2026-04-17（基于代码库全面审计更新） > 适用范围：internal/agent、internal/agent/subagent、internal/agent/multiagent、internal/a2a、工具与 UI 协同层、基础设施模块

---

进度标识（持续更新）

> 最近更新：2026-04-18

阶段 1–4：已完成

[x] 阶段 1：统一委派抽象层基础落地（Delegator、DelegationRequest、DelegationResult、delegationstatus 子包、错误映射）
[x] 阶段 2：agent 工具兼容桥基础落地（AgentParams = AgentToolV2Input 类型别名、统一状态/模式字段、默认值收敛、DelegationResultMetadata 响应构建管线）
[x] 阶段 2：subagent/notify/agent_tool_v2 的委派状态语义对齐与测试覆盖补齐
[x] 测试工程化：agent_tool_v2 与 SendMessageTool 的表驱动与共享 case 收敛
[x] 工具层：subagent_status 委派字段（delegation_*）与 subagent_cancel 错误/成功文案常量化；表驱动单测覆盖校验与取消路径
[x] 阶段 3：subagent 任务引擎治理全部完成（持久化 memory/sqlite、幂等、背压、中间件链、失败归因、SQLite WAL/busy_timeout/synchronous 配置化、migration registry、原生查询、/subagent list 等 30+ 子项）
[x] 阶段 3 交付件：docs/subagent-stage3-state-machine-spec.md、docs/subagent-stage3-middleware-extension-guide.md、docs/subagent-stage3-concurrency-failure-injection-report.md
[x] 阶段 4：multiagent 编排层统一委派（DelegationExecutor 接口 + 灰度开关、executeDelegationWithSession 统一入口、task_state 元数据映射、可配置超时/取消传播）
[x] 阶段 4 交付件：docs/multiagent-messagebus-taskstate-mapping-spec.md

阶段 5–7：待推进（本次审计新规划）

[x] 阶段 5（子项）：multiagent DelegationExecutor 真正接入 subagent Executor（当前两实现行为一致，仅占位）
[x] 阶段 5（子项）：Delegator 与 MultiAgentDelegator 接口合并或明确边界规范（代码注释界定职责，保留双接口）
[x] 阶段 5（子项）：A2A Server 路由层统一——按 agentType 路由到 subagent/multiagent 的委派路径标准化
[x] 阶段 5（子项）：Worktree 隔离产品化启用——coordinator 初始化时传入 WorktreeConfig（当前功能完整但未启用）
[x] 阶段 5（子项）：send_message 工具注册上线——当前仅有类型定义，未加入 allToolNames 和 populateToolRegistry
[x] 阶段 5（子项）：TokenUsageMiddleware 真实接入——在 LLM runner 回调中调用 RecordTokens()（当前 CostUSD 始终为 0）
[x] 阶段 5（子项）：LoopDetectionMiddleware.CheckState 真实接入——在多轮对话每轮调用（当前方法存在但未被调用）
[x] 阶段 5（子项）：子代理费用追踪——subagent 经 SessionAgent 步进回调写入会话成本；TokenUsageMiddleware.After 不再覆盖已由 CostTracker 聚合的 CostUSD
[x] 阶段 5（子项）：产品入口统一——/subagent 为标准委派入口，文档与 /agents、/team 收敛
[x] 阶段 5（子项）：UI 统一展示 task_id / 状态流转 / 结果摘要与成本
[x] 阶段 6（子项）：internal/metrics 接入核心业务指标——tool_call 耗时、active_sessions、token_cost_total 等（当前仅 3 个 cache 计数器）
[x] 阶段 6（子项）：PostHog 遥测补充——工具使用频次、subagent 执行、cost 维度上报
[x] 阶段 6（子项）：subagent EventMetrics 从纯内存态升级为可持久化/可上报（.crush/subagent_event_metrics.json + Prometheus SubagentEventTotal等）
[x] 阶段 6（子项）：multiagent 测试补强——Manager/CoordinatorAdapter/MessageBus/HotReloader/Recovery 单测与集成测试
[x] 阶段 6（子项）：multiagent HotReloader 与 RecoveryManager 在 app.go 装配中实际启用
[x] 阶段 6（子项）：multiagent Persistence Store 在 Manager 正常流程中调用（当前仅 Recovery 路径使用）
[x] 阶段 6（子项）：agent 工具 deprecation 提示（可配置开关）
[x] 阶段 6（子项）：遗留代码清理——两套 Registry（基础 + Advanced）收敛、ForkAdapter 按里程碑下线（Registry 收敛已完成，ForkAdapter 继续评估）
[x] 阶段 7（子项）：internal/distributed 接入——Leader 选举、分布式锁、集群管理（当前 EXPERIMENTAL 骨架）
[x] 阶段 7（子项）：internal/scaling 接入——CRUSH_SCALING_EXPERIMENTAL=true 时启动 AutoScaler，按队列指标调用 Executor.ResizeMaxWorkers（仅默认 unlimited并发）
[x] 阶段 7（子项）：internal/pool 接入——CRUSH_POOL_EXPERIMENTAL=true 时装配通用连接池骨架（当前 noop 工厂，便于后续替换为 LLM/DB）
[x] 阶段 7（子项）：internal/market 上线——CRUSH_MARKET_EXPERIMENTAL=true 时初始化 App.Market与 /market 斜杠命令（registries / skills|plugins 搜索）
[x] 阶段 7（子项）：跨进程事件总线——PubSub 从纯内存升级为可持久化/跨节点（桥接能力与基础测试已落地）

---

一、背景与问题定义

1.1 当前系统能力布局

当前系统存在多套 Agent 相关能力并行发展：

主会话执行链路：Coordinator -> SessionAgent——唯一 LLM 执行内核，已稳定
会话内委托：agent 工具（v2）——通过 Delegator.DelegateSync() 创建子会话执行，v1 已退化为纯类型别名
任务级委托：subagent——异步任务引擎，含状态机（6 态）、中间件链（5 种）、SQLite/Memory 持久化、WorkerPool、可选 Worktree 隔离
组织级协作：multiagent——多角色 Agent 管理，含 Registry（7 种角色）、MessageBus（8 种消息类型）、Workspace 隔离、Persistence、Recovery/HotReload 骨架
跨实例互通：a2a——Google A2A 协议服务端，桥接外部 Agent 调用到 Coordinator/subagent/multiagent

此外，已预研但未集成的基础设施模块：

模块	路径	成熟度	用途
`distributed`	`internal/distributed/`	骨架	Leader 选举、分布式锁、服务发现
`scaling`	`internal/scaling/`	骨架	HPA 风格自动伸缩
`pool`	`internal/pool/`	进行中	通用连接池
`metrics`	`internal/metrics/`	进行中	Prometheus 兼容指标（仅注册 3 个计数器）
`market`	`internal/market/`	骨架	Skills/Plugins 市场
`sandbox`	`internal/sandbox/`	已集成	命令/文件/网络过滤
`registry`	`internal/registry/`	已集成	ServiceRegistry（DI 容器，18+ 命名服务）
`hooks`	`internal/hooks/`	已集成	12 种事件类型 + 条件表达式引擎
`permission/v2`	`internal/permission/v2/`	已集成	4 模式权限引擎 + 增强规则 + SQLite 持久化

1.2 核心问题

这种并行演进在探索期是合理的，但在工程化阶段带来下列问题：

能力重叠：agent 与 subagent 均可做"委派"，语义边界不清；Delegator、MultiAgentDelegator、DelegationExecutor 三套并行接口
维护成本高：并发、超时、取消、统计、事件在多处重复实现（multiagent 的 execMu vs subagent 的 WorkerPool）
功能架空：Worktree 隔离完整实现但未启用；send_message 工具有类型定义但未注册；TokenUsage/LoopDetection 中间件方法存在但未被调用
可观测性碎片化：PostHog 仅覆盖会话级事件；internal/metrics 基础设施完善但仅 3 个计数器；subagent EventMetrics 纯内存态
测试覆盖不均衡：核心路径（subagent/delegation/config）覆盖强；multiagent Manager/CoordinatorAdapter/MessageBus/HotReloader/Recovery 缺乏单测
用户心智复杂：何时用哪个 Agent 系统缺乏统一入口

---

二、统一演进愿景

2.1 目标愿景（Target State）

建立三层统一架构：

1. 执行内核层（Execution Core） 以 SessionAgent 为唯一 LLM 执行内核（流式、多轮、工具调用、会话存储、hooks）。

2. 任务编排层（Task Orchestration） 以 subagent Executor 为统一委派引擎（同步/异步、状态机、中间件、限流、取消、超时、可选隔离）。

3. 组织协作层（Organization / Teaming） 以 multiagent Manager 为多角色协作治理层（角色注册、生命周期、消息总线、workspace 管理）。

统一后：

agent 工具语义收敛为 subagent 的兼容别名或迁移桥
委派统一走任务模型，状态可观测、行为可治理
多角色协作统一复用任务编排能力，避免两套调度逻辑

2.2 架构原则

单一执行内核：LLM 调用、消息落库、hooks 只保留一套权威实现
能力分层，不交叉污染：执行层不感知组织层；组织层不重复执行细节
兼容优先，渐进替换：保留旧接口，先桥接再淘汰
可观测先行：每一阶段先补事件和指标，再做行为迁移
开关化发布：关键改动必须可回滚、可灰度

---

三、现状与目标能力映射

维度	当前状态（2026-04-17 审计）	目标状态
主执行	`SessionAgent` 稳定，唯一 LLM 内核	✅ 保持
委派入口	`agent`（v2，走 `Delegator`）+ `subagent`（走 Executor）+ `agent_delegate`（走 `MultiAgentDelegator`）三路并存	`subagent` 为主，其余兼容桥接
委派模型	子会话模型（`sessionDelegator`）与任务模型（Executor）并存；multiagent 的 `DelegationExecutor` 两实现行为一致（占位）	统一任务模型
并发控制	subagent WorkerPool（semaphore + queue）与 multiagent `execMu`（TryLock 拒忙）分立	汇聚到 subagent 中间件/worker pool
持久化	subagent: memory/sqlite 双后端完善；multiagent: sqlite persistence 仅 Recovery 路径使用	统一走 subagent Store
角色协作	multiagent Registry（7 种角色）+ MessageBus + Workspace 完整但部分组件未启用	编排层复用统一委派
跨实例	A2A Server 已集成，支持按 `agentType` 路由	A2A 路由标准化
可观测性	PostHog 仅会话级；`internal/metrics` 仅 3 个计数器；subagent `EventMetrics` 纯内存	统一指标 + 遥测 + tracing
安全治理	Permission v2（4 模式）+ Sandbox + Hooks 均已集成	✅ 保持，按需扩展
Worktree 隔离	`WorktreeManager` 完整实现，但 coordinator 未传入 `WorktreeConfig`，功能被架空	产品化启用
工具注册	28 个工具名，`send_message` 未注册；两套 Registry（基础 + Advanced）并存	收敛注册，清理死代码
中间件	5 种已注册，但 `TokenUsage.RecordTokens()` 和 `LoopDetection.CheckState()` 未被实际调用	全部真实接入
分布式	`distributed`/`scaling`/`pool`/`market` 为骨架预研	按需启用
用户体验	`/subagent` 完整（run/list/status/cancel/types）；`/agents`、`/team` 与 multiagent 独立	统一命令入口

---

四、统一目标架构（逻辑）

External A2A Clients                  User / UI / Slash Commands
        |                                      |
        v                                      v
   A2A Server ─────────────────────> Coordinator (主入口与装配)
   (internal/a2a)                              |
   按 agentType 路由                            |
        |                            +---------+---------+
        |                            |                   |
        |                            v                   v
        |                   SessionAgent          Delegation API
        |                  (唯一执行内核)         (统一委派接口)
        |                                              |
        +─── subagent route ──────────>  Subagent Executor (任务编排)
        |                                |
        |                                +--> Middleware Chain
        |                                |    (timeout/limit/token/log/loop)
        |                                +--> Worker Pool (semaphore + queue)
        |                                +--> Store (memory/sqlite)
        |                                +--> Optional Worktree Isolation
        |
        +─── multiagent route ────────>  Multiagent Manager (组织治理)
                                         |
                                         +--> Role Registry (7 种角色)
                                         +--> Message Bus (8 种消息类型)
                                         +--> Workspace Isolation
                                         +--> 通过统一委派接口触发执行
                                         +--> Persistence / Recovery / HotReload

─── 横切关注点 ──────────────────────────────────────────────────────
  ServiceRegistry (DI)  │  Hooks (12 事件)  │  Permission v2 (4 模式)
  Sandbox (安全过滤)    │  PubSub (13 Broker) │  Metrics (待填充)

4.1 当前实际调用链（审计快照）

"agent" 工具 (v2)                  "subagent" 工具            "agent_delegate" 工具
AgentToolV2()                     SubagentTaskTool()         NewAgentDelegateTool()
      │                                 │                           │
      ▼                                 ▼                           ▼
coordinator.                      executor.                   MultiAgentDelegator
runSubAgent()                     ExecuteAsync()              .DelegateTaskSync()
      │                                 │                           │
      ▼                                 ▼                           ▼
Delegator.DelegateSync()          WorkerPool →                CoordinatorAdapter →
(sessionDelegator)                AgentRunner.Execute()       Manager.executeDelegation
      │                                                       WithSession()
      ▼                                                            │
SessionAgent.Run()                                                 ▼
                                                            DelegationExecutor.Execute()
                                                            (当前委托 legacySessionExecutor)
                                                                   │
                                                                   ▼
                                                            SessionAgent.Run()

关键发现：三条路径最终均汇聚到 SessionAgent.Run()，但中间的治理层（并发/超时/状态机/中间件）各自实现，尚未统一。

---

五、分阶段演进计划（7 阶段，前 4 阶段已完成）

阶段 0–4 ✅ 已完成（详见进度标识与上方各阶段审计）

阶段 0 基线观测：PubSub 13+ Broker 覆盖核心解耦；PostHog 会话级遥测可用；subagent EventMetrics 5 维计数器可用。

阶段 1 统一委派抽象：Delegator + sessionDelegator + DelegationRequest/DelegationResult + delegationstatus 子包。类型分散于 agent/delegationstatus/multiagent/tools 四包。

阶段 2 agent 工具兼容桥：AgentParams = AgentToolV2Input 类型别名；v2 走 Delegator.DelegateSync()；DelegationResultMetadata 封装 UI 元数据。

阶段 3 subagent 统一任务引擎：30+ 子项完成：SQLite/Memory 双后端、幂等、背压、5 种中间件 + 失败归因、migration registry、原生 SQL 查询、配置化 18 字段。

阶段 4 multiagent 编排复用：DelegationExecutor + 灰度开关 + executeDelegationWithSession + task_state 元数据 + 可配置超时/取消。

---

阶段 5：执行引擎深度融合与产品化 ✅

目标

multiagent DelegationExecutor 真正接入 subagent Executor，消除两套执行治理
被架空的功能（Worktree、TokenUsage、LoopDetection）真正接入运行时
对外只暴露清晰的一套委派心智模型

5.1 执行融合

[x] multiagent DelegationExecutor 接入 subagent Executor：sessionAgentDelegationExecutor.Execute() 改为创建 subagent Task、走 Executor 中间件链，而非直接委托 legacy。保留灰度开关
[x] 并发控制统一：multiagent 从自建 execMu.TryLock() 迁移到 subagent WorkerPool 信号量模型
[x] 接口收敛规范：明确 Delegator（coordinator 级同步入口）/ MultiAgentDelegator（工具层高层委派）/ DelegationExecutor（改为调用 subagent Executor）三者边界

5.2 中间件真实接入

[x] TokenUsageMiddleware 接入：在 AgentRunner.Execute() 的 OnStepFinish 回调中调用 RecordTokens()
[x] LoopDetectionMiddleware.CheckState 接入：在 subagent 多轮对话循环每一轮末尾调用
[x] 子代理费用追踪：subagent 执行路径接入 CostTracker

5.3 Worktree 产品化

[x] coordinator 传入 WorktreeConfig：在 NewExecutor 时根据 SubagentConfig 构建
[ ] 启用策略：按任务类型（refactor/code-reviewer 等）自动建议或强制启用
[x] WorktreeManager 持久化：从纯内存升级为持久化

5.4 工具与入口统一

[x] send_message 工具：决策——注册上线或清理死代码
[x] 产品入口统一：/subagent 为标准委派入口；更新 /agents、/team 关系说明
[x] UI 统一展示：task_id / 状态流转 / 结果摘要与成本

5.5 A2A 路由标准化

[x] A2A Processor 按 agentType 路由到 subagent/multiagent 的委派路径标准化

交付件

执行融合 PR 集（含灰度开关与回滚能力）
中间件接入验证报告、Worktree 产品化配置文档
新版架构文档与迁移 FAQ

验收标准

multiagent 执行路径走 subagent Executor，中间件链完整生效
TokenUsageMiddleware 输出真实 CostUSD
Worktree 隔离可通过配置开启并正确工作

---

阶段 6：可观测性补齐与遗留清理 ✅

目标

可观测性从"有骨架"升级为"可运维"；清理历史包袱

6.1 可观测性

[x] internal/metrics 接入核心指标：tool_call_duration_seconds、active_sessions、token_cost_total_usd、subagent_task_total、delegation_duration_seconds、middleware_failure_total（>= 10 个）
[x] subagent EventMetrics 持久化/上报
[x] PostHog 补充：工具使用频次、subagent 执行、cost 维度
[x] trace_id 贯穿：session_id → task_id → tool_call_id 端到端关联
[ ] 统一日志字段：session_id、task_id、agent_type（持续收敛）

6.2 multiagent 组件补强

[x] 启用 HotReloader（multi_agent.hot_reload_enabled）
[x] 启用 RecoveryManager（崩溃恢复路径验证）
[x] Persistence Store 正常流程集成
[x] app.go 中 multiagent adapter 创建需检查 multi_agent.enabled

6.3 测试补强

[x] multiagent 单测：Manager/CoordinatorAdapter/MessageBus/HotReloader/Recovery
[x] PubSub 单测：Broker 路由/满 channel 丢弃/并发安全
[x] E2E 主流程：主会话 → 委派 → UI 渲染完整链路
[x] 性能基准：高并发任务提交、取消风暴、长任务稳定性

6.4 遗留清理

[x] agent v1 标记 deprecated（可配置开关）
[x] 两套 Registry 收敛（基础 + Advanced）
[ ] ForkAdapter 按使用率评估是否下线 legacy 路径
[x] send_message 决策：注册上线或删除死代码
[x] SubagentConfig → subagent.Config 自动映射函数
[x] Store cleanup 泄漏修复（NewExecutor 部分失败路径）

验收标准

internal/metrics >= 10 个核心业务指标
multiagent 核心组件测试覆盖率 >= 80%
无残留死代码

---

阶段 7：分布式与生态扩展（长期）🔮

目标

预研模块从骨架推向可用；建立 Skills/Plugins 市场生态

7.1 分布式基础设施

[x] internal/distributed 集成：Leader 选举 + 分布式锁 + 集群管理（CRUSH_DISTRIBUTED_EXPERIMENTAL）
[x] internal/scaling 集成：AutoScaler 与 subagent WorkerPool 动态伸缩（CRUSH_SCALING_EXPERIMENTAL，见 ResizeMaxWorkers）
[x] internal/pool 集成：实验性通用池装配（CRUSH_POOL_EXPERIMENTAL；生产路径仍以 sql.DB 内建池为主）
[x] PubSub 跨进程扩展：从纯内存升级为可持久化/跨节点（桥接能力与基础测试已落地）

7.2 市场生态

[x] internal/market 上线：App.Market + /market（CRUSH_MARKET_EXPERIMENTAL；下载/安装待扩展）
[ ] Plugin 运行时贡献成熟化

7.3 智能路由与编排

[ ] 策略路由：根据任务类型/复杂度自动选择 subagent type/model
[ ] QoS：按任务优先级分配并发槽位与 Token 预算
[ ] 任务依赖图（DAG）：多任务编排与依赖等待
[ ] 跨会话/跨项目团队协作拓扑

验收标准

多节点部署下任务调度正确（至少 2 节点验证）
Market 可搜索/安装第三方 Skills

---

六、里程碑计划

里程碑	对应阶段	状态	目标
M1	阶段 0	✅ 已完成	基线冻结与观测补齐
M2	阶段 1	✅ 已完成	统一委派抽象层（`Delegator` / `DelegationExecutor` / subagent 接口）
M3	阶段 2	✅ 已完成	`agent` 工具兼容桥迁移（v2 上线，v1 降为 type alias）
M4	阶段 3-4	✅ 已完成	`subagent` 生产级强化 + `multiagent` 编排复用
M5	阶段 5	✅ 已完成	执行引擎深度融合与产品化
M6	阶段 6	✅ 已完成	可观测性补齐与遗留清理
M7	阶段 7	进行中	分布式与生态扩展（实验开关、`/market` 等已落地）

---

七、向后兼容策略

7.1 接口兼容

保留 agent 工具输入字段，内部映射到统一请求结构
输出中保留老字段，新增标准字段（如 task_id、status）

7.2 行为兼容

默认策略与原行为一致（超时、maxTurns、工具白名单）
差异行为通过 feature flag 开启

7.3 发布策略

Canary：先对内部/开发模式启用
灰度：按用户/项目/会话维度逐步放量
全量：指标稳定后切换默认路径

---

八、风险清单与缓解

风险 A：迁移导致行为漂移

表现：同 prompt 结果质量波动，工具调用序列变化
缓解：
基准回放集（固定样本）
关键路径差异报告（turn/tool/cost）

风险 B：并发与取消回归

表现：任务卡死、取消不生效、状态错乱
缓解：
失败注入测试（超时、取消、断网）
强制状态机校验（非法状态迁移报警）

风险 C：多层日志口径不一致

表现：难以串联 session、task、agent runtime
缓解：
强制透传 trace_id / session_id / task_id
统一日志字段与采样策略

风险 D：worktree 资源泄漏

表现：磁盘膨胀、孤儿 worktree
缓解：
TTL 清理 + 启动清理
容量阈值告警

风险 E：中间件功能架空（审计新增）

表现：TokenUsageMiddleware.RecordTokens() 和 LoopDetectionMiddleware.CheckState() 从未被调用；CostUSD 始终为 0，循环检测形同虚设
缓解：
阶段 5.2 中集成中间件调用点
添加集成测试验证中间件链路端到端生效
CI 中增加"中间件覆盖率"检查

风险 F：可观测性碎片化（审计新增）

表现：internal/metrics 仅 3 个缓存计数器注册；subagent EventMetrics 纯内存无持久化；PostHog 仅会话级事件
缓解：
阶段 6.1 统一注册核心业务指标（>= 10 个）
EventMetrics 接入持久化 / 上报通道
定义指标字典（名称、标签、采样率）

风险 G：配置与运行时脱节（审计新增）

表现：multi_agent.enabled 配置存在但 app.go 未检查；DelegationExecutor 灰度开关两条路径行为完全相同
缓解：
app.go 中 adapter 创建增加 multi_agent.enabled 守卫
DelegationExecutor 灰度开关接入 subagent Executor（阶段 5.1）

---

九、测试与验收体系

9.1 测试分层

单元测试：接口适配、中间件顺序、状态机转换
集成测试：Coordinator → Delegation → Subagent 全链路
E2E 测试：主会话委派、多角色协作、异常恢复
性能测试：高并发任务提交、取消风暴、长任务稳定性

9.2 当前覆盖现状（审计）

模块	测试文件数	覆盖评估	薄弱点
agent/subagent	~30	✅ 强	中间件集成测试缺失（TokenUsage/LoopDetection 从未调用）
config	~10	✅ 强	—
multiagent (Manager/Adapter/MessageBus)	~2	❌ 弱	Manager/CoordinatorAdapter/MessageBus/HotReloader/Recovery 无测试
PubSub	0	❌ 无	13+ Broker 无单测
hooks	~4	✅ 中	—
permission/v2	~3	✅ 中	—
a2a	~4	✅ 强	—

9.3 核心验收指标（建议阈值）

任务成功率 >= 99%
取消成功率 >= 99.5%
委派链路 P95 延迟不劣于现网基线 10%
严重故障（卡死/状态错乱）= 0
新增：中间件链路端到端覆盖率 100%（每个中间件至少 1 个集成测试验证调用）
新增：核心业务指标 >= 10 个且可在监控面板观测

---

十、实施清单（基于审计的可落地任务）

A. 阶段 5 — 执行融合（高优先级）

[x] sessionAgentDelegationExecutor.Execute() 接入 subagent Executor（含灰度开关）
[x] multiagent 并发控制从 execMu.TryLock() 迁移到 WorkerPool
[x] TokenUsageMiddleware.RecordTokens() 接入 AgentRunner.Execute() 的回调
[x] LoopDetectionMiddleware.CheckState() 接入 subagent 多轮对话循环
[x] coordinator 传入 WorktreeConfig 到 NewExecutor
[x] 决策并处理 send_message 工具（注册或删除死代码）
[x] A2A Processor agentType 路由标准化

B. 阶段 6 — 可观测与清理（中优先级）

[x] internal/metrics 注册 >= 10 个核心业务指标
[x] subagent EventMetrics 接入持久化
[x] PostHog 补充工具/subagent/cost 维度事件
[x] trace_id 贯穿 session → task → tool_call
[x] app.go 增加 multi_agent.enabled 检查守卫
[x] 启用 HotReloader 和 RecoveryManager
[x] 两套 Registry 收敛为一套
[x] Store cleanup 泄漏修复（managedStore 在 Executor 创建失败时）

C. 测试补强（贯穿阶段 5-6）

[x] multiagent 单测：Manager / CoordinatorAdapter / MessageBus
[x] PubSub 单测：Broker 路由 / 满 channel / 并发安全
[x] 中间件集成测试：验证 RecordTokens/CheckState 被调用
[x] E2E：主会话 → 委派 → subagent Executor → UI 渲染
[x] 性能基准：并发任务提交、取消风暴

D. 文档与体验

[x] 更新 /help、/subagent、/agents 说明
[x] 增加迁移文档与 FAQ
[x] UI 统一展示 task 状态与结果摘要
[x] 指标字典文档（名称、标签、采样率）
[x] 故障排查手册（Runbook）

---

十一、角色分工建议

架构负责人：统一接口与迁移边界把控
执行引擎负责人：subagent 稳定性与中间件治理
协作系统负责人：multiagent 编排收敛
产品与文档负责人：用户入口、文档、迁移引导
质量负责人：回放基准、门禁阈值、回归看板

---

十二、决策记录建议（ADR）

已有或建议新增的 ADR：

1. ADR-001：为何采用三层统一架构 2. ADR-002：为何以 SessionAgent 作为唯一执行内核 3. ADR-003：为何以 subagent 作为统一委派引擎 4. ADR-004：agent 工具兼容与下线策略 5. ADR-005（建议）：DelegationExecutor 灰度开关与执行融合策略 6. ADR-006（建议）：中间件链路接入规范（何时/何处调用 RecordTokens/CheckState） 7. ADR-007（建议）：send_message 工具去留决策

---

十三、长期演进方向（Beyond v1）

> 以下方向已在阶段 7 中初步规划，此处保留战略视角。

策略路由：根据任务类型/复杂度自动选择 subagent type / model
QoS：按任务优先级分配并发槽位与 Token 预算
任务依赖图（DAG）：多任务编排与依赖等待
跨会话/跨项目团队协作拓扑
分布式调度：internal/distributed + internal/scaling 从骨架推向生产
市场生态：internal/market Skills/Plugins 搜索、下载、安装上线
A2A 联邦：跨实例 agent 协作标准化

---

十四、结论

本路线图 v2.0 基于对代码库的系统性审计更新。核心发现：阶段 0-4 的架构框架已基本就绪，但"最后一公里"集成（中间件链路、可观测性、配置-运行时一致性）仍有显著差距。

下一步重点（阶段 5）：将 multiagent DelegationExecutor 真正接入 subagent Executor，激活被架空的中间件，使 Worktree 隔离可配置开启。

演进原则不变：分阶段、可观测、可回滚。通过灰度开关保障兼容性，通过审计驱动的实施清单确保每一步都有明确的验收标准。