agcore/design/roadmap/roadmap-v0.4.0.md

AG Core Roadmap — v0.4.0

本文件聚焦 v0.4.0 版本 的规划。Phase A-E 计划中，覆盖多 Agent 编排、Human-in-the-loop 与 Steering、语义压缩、自动校正。 返回总入口：roadmap.md

v0.4.0 愿景

从 v0.3 的"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。补齐高层编排抽象（Swarm/Supervisor/Subgraph）、生产级人工干预能力（HITL + Steering）、工具与消息的语义压缩（TokenJuice），以及自动质量校正（Reflection）。为即将开发的多 Agent 协作产品提供完整的编排、干预与质量保证层。

v0.4.0 总体范围

总体规模：5 个增量 Phase（Phase A-E），总新增代码约 1,950 行，零强制新外部依赖，零破坏性变更。

架构决策

路线选择：采用轻量编排模式（路线 A），不引入通用有向图引擎。通过 Swarm::star() / Swarm::sequential() / Swarm::hierarchical() 等具名模式提供编排能力，底层复用现有 dispatch / create_child / SessionManager 基础设施。预留路线 B（StateGraph 抽象）作为未来版本的升级路径。

模块位置：

• 编排逻辑 → src/engine/supervisor.rs（新增）
• 内建工具 → src/tools/builtin.rs（新增）
• TokenJuice 压缩 → src/llm/compress.rs（新增）
• Steering 机制 → src/engine/steer.rs（新增，或并入 supervisor.rs）

功能清单

P0 — 必须交付

#	功能	模块	方案要点
1	Swarm 编排（Star/Sequential/Hierarchical + Subgraph）	engine/supervisor	Swarm::star().supervisor(A).worker(B) 声明式 API；Swarm::sequential().link(A).link(B) 串联；Swarm::hierarchical().supervisor(root).group("sub", ...) 层次嵌套
2	结果聚合	engine/supervisor	aggregation_prompt 模板将子 Agent 结果合并到 Supervisor 上下文；DispatchConfig 扩展 result_key 字段
3	Human-in-the-loop 审批	engine/steer	interrupt() 暂停执行 + Command(resume=bool) 恢复；HookEvent::OnInterrupt 新变体
4	用户 Steering（运行中校正）	engine/steer	Command(resume=Correction{...}) 结构化校正；Steer 消息在工具批处理边界注入
5	TokenJuice 语义压缩	llm/compress	Compressor trait 统一抽象；覆盖工具结果、对话历史、跨 Agent 消息三层；LLM 摘要压缩 + 确定性兜底

P1 — 推荐交付

#	功能	模块	方案要点
6	自动校正 / Reflection	engine/reflect	Evaluator-Optimizer 循环；Producer-Critic 角色分离；上限 2-3 轮迭代

实施计划 — 5 个增量 Phase

编号说明：Phase A-E 为 v0.4.0 专属编号，接续已完成的 Phase 30。

---

Phase A: Swarm 编排抽象（Star / Sequential / Hierarchical + Subgraph）

目标：在现有 dispatch 原语基础上，提供声明式多 Agent 编排 API。Supervisor 作为 Arc<dyn Agent>，通过内建工具 dispatch_sub_agent 驱动子 Agent 执行。

交付物：

1. src/engine/supervisor.rs 新文件：
   • Swarm 枚举/结构体：Swarm::star()（星型，一个 Supervisor + N 个 Worker）、Swarm::sequential()（顺序链 A→B→C）、Swarm::hierarchical()（层次嵌套，Supervisor 下的 Sub-Supervisor）
   • 各模式的 build() 和 run(input) 方法
   • 底层通过 SessionManager::dispatch() / dispatch_all() 实现
2. src/tools/builtin.rs 新文件：
   • dispatch_sub_agent(name, task, config) 内建工具 — 从 Agent 注册表查找 Agent 工厂 → SessionManager::dispatch()
3. AgentRegistry：HashMap<String, Box<dyn Fn() -> Arc<dyn Agent>>> 轻量工厂注册表（约 50 行）
4. Subgraph 嵌套：Swarm::hierarchical() 支持 group(name, inner_swarm)，内层 Swarm 作为子节点编译后嵌入

设计要点：

• Supervisor 就是 Arc<dyn Agent>，不新增 SupervisorAgent trait
• 路由逻辑写在 Supervisor 的 system prompt 中（LLM 决定的动态路由）
• 三种模式覆盖常见编排拓扑，不引入通用图引擎（路线 B 留作未来）
• Subgraph 编译为独立的 SessionManager 子树（复用 create_child 的父子关系）

依赖：Phase 18（SubAgent dispatch / SessionManager） 优先级：P0 预估规模：约 500 行 状态：📋 待实施

---

Phase B: 结果聚合 + 编排模式完善

目标：让 Supervisor 能智能地合并 Worker 结果。完善三种编排模式的容错性和易用性。

交付物：

1. aggregation_prompt 模板系统 — 内建 DEFAULT_AGGREGATION_PROMPT，用户可自定义聚合逻辑
2. DispatchConfig 扩展：
   • result_key: Option<String> — 将子结果存入 session_memory 的指定 key，供后续阶段使用
   • aggregate_strategy: AggregateStrategy — Concatenate / Summarize / Custom(Value)
3. 编排模式增强：
   • Swarm::sequential() 支持失败时停止 / 跳过 / 重试策略
   • Swarm::star() 支持 Worker 超时
4. 端到端示例 3 个：
   • swarm_star_demo.rs — 星型编排 + 并发派发 + 结果聚合
   • swarm_sequential_demo.rs — 串联流水线
   • swarm_hierarchical_demo.rs — 层次嵌套（Supervisor → Sub-Supervisor → Worker）

依赖：Phase A 优先级：P0 预估规模：约 200 行 状态：📋 待实施

---

Phase C: Human-in-the-loop + 用户 Steering

目标：生产级多 Agent 系统的关键门禁。提供执行中暂停-审批-恢复机制，以及用户运行中校正方向的能力。

交付物：

1. src/engine/steer.rs 新文件：
   • interrupt(value) 函数 — 在工具循环中插入暂停点，持久化当前状态后返回控制权
   • Command 枚举：
     • Command::Resume(bool) — 二元审批（批准/拒绝）
     • Command::ResumeWith(Correction) — 结构化校正（修改工具参数 / 调整方向）
2. LlmCycle 扩展：可中断工具循环模式
   • submit_with_tools_interruptible() — 支持在工具批处理边界检查中断信号
   • 中断时保存当前 LlmCycle 状态到 checkpoint
3. HookEvent::OnInterrupt / OnSteer 新变体 — 监听中断和校正事件
4. SessionManager::resume_turn(session_id, resume_data) — 从 checkpoint 恢复并注入审批结果
5. tools/builtin.rs 扩展：
   • request_approval(question, context) — 请求用户审批
   • emit_steer(correction) — 用户校正
6. Steering 生命周期：
   • interrupt → 用户收到提示 → 用户决定方向 → Command::ResumeWith(correction) → Agent 在新方向上继续

设计要点：

• User Steering 不是简单的"批准/拒绝"，而是 Correction { action, reason, amended_params } 结构化指令
• Steering 消息在工具批处理边界（Worker 返回后、Supervisor 决策前）注入，不中断正在执行的工具
• 继承 ContextSlot::fork/merge 模式，steer 前 fork 快照，允许用户回退到 steer 前状态

依赖：Phase A（Swarm 编排） 优先级：P0 预估规模：约 500 行 状态：📋 待实施

---

Phase D: TokenJuice 语义压缩

目标：替代当前字节级截断（microcompact 的 [pruned]），提供语义级别的压缩。在三层管道中接入：工具结果压缩、对话历史压缩、跨 Agent 消息压缩。

交付物：

1. src/llm/compress.rs 新文件：
   • Compressor trait（async fn compress(&self, input: &str, ctx: &CompressionContext) -> Result<String>）
   • CompressionContext：target_tokens / preserve_keys / strategy
   • CompressionStrategy 枚举：Semantic { model }（LLM 摘要）、Extractive { ratio }（抽取式）、Hybrid { semantic_first }（混合）
   • SemanticCompressor 实现（复用已有 provider 做 LLM 摘要压缩）
   • ExtractiveCompressor 实现（确定性关键句提取，零 LLM 调用）
2. 三层接入点：
   • 工具结果压缩：在 run_tool_loop 中，tool.execute() 后插入 compress_result()，压缩结果再 push ToolResult
   • 对话历史压缩：在 load_messages() 后插入 compress_history()，替代/补充 microcompact
   • 跨 Agent 消息压缩：在 inherit_session_memory 的子 memory 写入前压缩（减少子 Agent 的 context 水位）
3. CycleConfig / CompactConfig 扩展：
   • token_compression: Option<CompressionConfig> — 可选语义压缩配置
   • fallback_to_microcompact: bool（默认 true）— LLM 压缩失败时退化为字节截断
4. TokenJuice 与现有 microcompact 的关系：
   • microcompact 保留为最轻量级兜底（零 LLM 调用）
   • TokenJuice 是可选增强层（默认关闭，用户 opt-in）

设计要点：

• 零新外部依赖：LLM 摘要压缩复用已有 provider，抽取式压缩纯 Rust 实现
• 与现有 CompactState 断路器模式兼容（LLM 压缩失败 3 次后自动降级到 microcompact）
• preserve_keys 确保关键数据（数字、ID、SQL、代码片段）不被压缩掉

依赖：Phase 14（Embedding trait 可选参考） 优先级：P0 预估规模：约 400 行 状态：📋 待实施

---

Phase E: 自动校正 / Reflection

目标：实现 Agent 输出后的自我质量评估与自动修正循环。基于 interrupt/resume 基础设施，构建 Producer-Critic 闭环。

交付物：

1. src/engine/reflect.rs 新文件：
   • ReflectionConfig：max_cycles（默认 2）/ critic_agent（可选不同模型）/ criteria: Vec<String>（评估标准）
   • Reflectable trait：fn reflection_criteria(&self) -> Vec<String> + fn needs_refinement(&self, critique: &Critique) -> bool
   • ReflectionLoop：evaluate(output) → Critique → should_refine? → yes: refine(output, critique) → 循环 / no: 返回
2. Swarm 内建 Reflection 模式：
   • Swarm::reflect(producer_agent, critic_agent) — 专用 Reflection Swarm
   • 可在 Supervisor 流程中嵌入 reflect_on(worker_result) — 对 Worker 结果自动过一遍质量检查
3. Critique 结构体：issues: Vec<Issue> / score: f32 / should_refine: bool / suggestions: Vec<String>
4. tools/builtin.rs 扩展：verify_output(claim, evidence) 工具 — 让 Agent 自行验证输出真实性

设计要点：

• Producer 和 Critic 使用不同模型（避免同一模型的自我审查盲区 bias）
• 上限 2-3 轮（第一轮修正捕获 70–80% 改善空间，第 4+ 轮收益递减）
• 基于已有 HookEvent::OnTurnEnd 或扩展 HookEvent::OnOutputGenerated 触发反思
• 失败静默：Reflection 失败不阻断主流程（tracing::warn! 后继续交付原始输出）

依赖：Phase C（interrupt/resume 基础设施） 优先级：P0 预估规模：约 350 行 状态：📋 待实施

---

v0.4.0 Phase 依赖关系图

graph BT
    PA["<b>Phase A: Swarm 编排</b><br/>Swarm::star/sequential/hierarchical<br/>Subgraph 嵌套<br/>内建 dispatch_sub_agent 工具<br/>~500 行"]:::pending
    PB["<b>Phase B: 结果聚合</b><br/>aggregation_prompt 模板<br/>DispatchConfig result_key<br/>编排模式完善<br/>3 个端到端示例<br/>~200 行"]:::pending
    PC["<b>Phase C: HITL + Steering</b><br/>interrupt/resume<br/>Command(ResumeWith Correction)<br/>HookEvent::OnInterrupt<br/>~500 行"]:::pending
    PD["<b>Phase D: TokenJuice</b><br/>Compressor trait<br/>工具结果/历史/跨 Agent 压缩<br/>Semantic + Extractive 策略<br/>~400 行"]:::pending
    PE["<b>Phase E: 自动校正</b><br/>ReflectionLoop<br/>Producer-Critic<br/>上限 2-3 轮<br/>~350 行"]:::pending

    PB --> PA
    PC --> PA
    PE --> PC

    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
    classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
    classDef future fill:#94a3b8,stroke:#64748b,color:#1a1a1a

关键里程碑

里程碑	Phase 完成条件	可验证指标	状态
M16	Phase A	Swarm::star().supervisor(A).worker(B).run(input) 端到端验证；dispatch_sub_agent 内建工具注册并可用；2 个示例 exit 0	📋 待启动
M17	Phase B	Swarm::sequential() 串联执行验证；Swarm::hierarchical() 层次嵌套验证；结果聚合正确合并；3 个新示例 exit 0	📋 待启动
M18	Phase C	interrupt() 暂停 + Command::Resume(bool) 恢复全链路验证；Command::ResumeWith(Correction) 结构化校正验证；HookEvent 触发验证	📋 待启动
M19	Phase D	工具结果经语义压缩后保留关键信息（验证压缩比 ≥ 3:1）；microcompact 降级路径验证；对话历史压缩验证	📋 待启动
M20	Phase E	ReflectionLoop 正确性验证：已知缺陷的输出被修复、无缺陷的输出不被修改（不变性保证）；2 轮迭代上限验证；Critic 不同模型配置验证	📋 待启动

不做（v0.5+）

功能	原因
Agent 自动创生（LLM 驱动动态分派）	设计复杂且不确定性高，v0.4 专注显式声明式编排
分布式 Session 共享（Redis 后端）	与编排正交，大多数用户单进程即可
精确 tokenizer 计数（tiktoken-rs）	依赖引入，v0.4 专注编排与压缩能力本身
增量 Checkpoint	存储优化，当前全量 JSON 够用
路线 B（StateGraph 通用图引擎）	当前编排需求在路线 A 范围内，图引擎留给未来版本
RL 轨迹导出	专项需求，非通用
Markdown 技能按需加载	独立功能