# 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 技能按需加载 | 独立功能 |