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 独立 | 统一命令入口 | --- ## 四、统一目标架构（逻辑） ```text 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 当前实际调用链（审计快照） ```text "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 隔离可配置开启。 演进原则不变：**分阶段、可观测、可回滚**。通过灰度开关保障兼容性，通过审计驱动的实施清单确保每一步都有明确的验收标准。