徐涛
234 lines
13 KiB
Markdown
234 lines
13 KiB
Markdown
# AG Core Roadmap — v0.4.0
|
||
|
||
> 本文件聚焦 **v0.4.0 版本** 的规划。Phase A-E 计划中，覆盖多 Agent 编排、Human-in-the-loop 与 Steering、语义压缩、自动校正。
|
||
> 返回总入口：[`roadmap.md`](./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 依赖关系图
|
||
|
||
```mermaid
|
||
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 技能按需加载 | 独立功能 |
|