# AG Core Roadmap — Unsorted

> 本文件存放**尚未归到任何具体版本**的 roadmap 内容：跨版本的全局视图、面向未来的展望、风险与建议、阶段总回顾。
>
> **已分版本的内容**：请查阅
> - [`roadmap-v0.1.0.md`](./roadmap-v0.1.0.md) — Phase 0–4c + v0.1.0 Release
> - [`roadmap-v0.2.0.md`](./roadmap-v0.2.0.md) — Phase 5–12 + v0.2.0-rc.1
> - [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) — Phase 13–19（全部完成）
> - [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) — Phase A-E 多 Agent 编排路线图
>
> 返回总入口：[`roadmap.md`](./roadmap.md)

---

## 全局愿景

AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。

**当前状态**：v0.3.5。Phase 0-30 全部完成。v0.4.0 规划已确定，覆盖 5 个增量 Phase（A-E）：Swarm 编排抽象、结果聚合、Human-in-the-loop + 用户 Steering、TokenJuice 语义压缩、自动校正。目标是从"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。

---

## 模块完整性评估

| 功能领域 | 方案状态 | 文档位置 | 实现优先级 |
|---------|---------|---------|-----------|
| LLM 调用周期 | ✅ 完整 | `specs/llm-call-lifecycle.md` | P0 |
| 提示词工程 | ✅ 完整 | `docs/4-prompt-engineering.md` | P1 |
| 工具系统 + 权限 | ✅ 完整 | `docs/5-tool-system.md` | P1 |
| 记忆检索 | ✅ 完整 | `docs/6-memory-system.md` | P2 |
| Agent 运行时（4a 胶水层） | ✅ 已实现 | `docs/7-agent-runtime.md` | P2 |
| 生命周期钩子 | ✅ 完整 | `docs/3-phase0-remaining.md` | P0（LLM Cycle 扩展） |
| Provider 注册发现 | ✅ 完整 | `docs/3-phase0-remaining.md` | P0（Provider 接口扩展） |
| 流式事件系统 | ✅ 完整 | `docs/3-phase0-remaining.md` | P0（流式接口前置） |


---

## v0.4.0 规划

v0.4.0 的完整规划已移入独立的 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md)，包含 5 个增量 Phase：

| Phase | 内容 | 状态 |
|-------|------|------|
| **Phase A** | Swarm 编排（Star/Sequential/Hierarchical + Subgraph） | 📋 待实施 |
| **Phase B** | 结果聚合 + 编排模式完善 | 📋 待实施 |
| **Phase C** | Human-in-the-loop + 用户 Steering | 📋 待实施 |
| **Phase D** | TokenJuice 语义压缩（工具结果/历史/跨 Agent） | 📋 待实施 |
| **Phase E** | 自动校正 / Reflection | 📋 待实施 |

### 未来版本（v0.5+）

以下功能已从 v0.4 范围移出：

| 功能 | 说明 |
|------|------|
| Agent 自动创生 | LLM 自主决定何时派发子 agent — 设计复杂，v0.4 专注显式声明式编排 |
| 分布式 session 共享（Redis 后端） | 与编排正交，多数用户单进程即可 |
| 精确 tokenizer 计数（tiktoken-rs） | 依赖引入，不在 v0.4 核心范围内 |
| 增量 Checkpoint | 存储优化，当前全量 JSON 够用 |
| 路线 B（StateGraph 通用图引擎） | 预留为路线 A 的未来升级路径 |
| RL 轨迹导出 | 专项需求 |

### 明确不做（agcore 范围外）

| 功能 | 原因 |
|------|------|
| TUI / 多平台 Gateway | 应用层职责（Feishu / Telegram / Discord 桥接） |
| 配置自动加载（config/figment） | 配置来源策略应由上游应用决定，agcore 不定义配置格式 |
| 提示词自动优化 | 属于智能层，不应内建于 core 库 |

---

## 风险与建议

1. **持久化依赖**：`rusqlite` + `bundled` 零外部依赖编译，但 SQLite 不适配所有场景（分布式/高并发写）。`MemoryStore` trait 的抽象层允许下游自行实现 Redis / PostgreSQL 后端
2. **ContextSlot 心智负担**：`ContextSlot` 引入了一等抽象的复杂度。建议通过 `AgentBuilder` 默认创建 `"default"` slot，让简单场景无感使用
3. **向量检索规模上限**：v0.3 的 `PersistentVectorStore` 全量加载到内存做余弦搜索，适合 ≤10 万条向量。超出此规模需换用专用向量库。v0.4 可以评估引入
4. **Scope 蔓延**：v0.3 新增 `agent/summary` `document/` `engine/` `memory/vector_store` 模块，功能覆盖扩展到多 Agent 基础系统。始终保持 trait + reference impl 的边界，业务循环留给上层（Phase 16 已交付 `agent/summary` 摘要生产端 + `format_messages_as_text` 简洁版格式化 + 30K 字符整体截断保留最新；Phase 18 已交付 `engine/switch_agent` 热切换 + `engine/sub_agent` 调度全栈（dispatch / dispatch_all / dispatch_stream）；实施后两轮审查 PASS，0 🔴 阻塞）
5. **API 稳定性**：v0.3 引入 `Checkpointer`、`SessionManager`、`VectorStore` 等新公开 API，v0.2 已有的 `#[non_exhaustive]` 和 `#[deprecated]` 机制继续沿用
6. **Checkpointer 存储效率**：v0.3 使用全量 JSON 序列化存储 checkpoint，每轮对话约几百 KB。`fork` 从历史 checkpoint 创建新 session 时也会复制全量。等实际使用中发现存储瓶颈时再改为增量模式

---

## 下一步行动

1. **v0.4.0 启动**：按 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) 规划，从 Phase A（Swarm 编排）开始实施
2. **Phase A 实施**：engine/supervisor.rs + tools/builtin.rs + Swarm::star/sequential/hierarchical
3. **示例先行**：每个 Phase 交付时同步提交对应的示例程序
4. **里程碑追踪**：以 M16-M20 为目标里程碑，逐 Phase 推进

---

**已完成 / 进行中阶段**：
- ✅ Phase 0 Foundation — 全部交付物已完成
- ✅ Phase 1 Prompt Engineering — 全部交付物已完成
- ✅ Phase 2 Tool System — 全部交付物已完成
- ✅ Phase 3 Memory System — 全部交付物已完成
- ✅ Phase 4a Core Glue — 全部交付物已完成
- ✅ Phase 4b Task Execution — 全部交付物已完成
- ✅ Phase 4c Session Memory — 全部交付物已完成
- ✅ Phase 5 Warmup — ProviderConfig::from_env + OllamaProvider + `#[non_exhaustive]` 前置标记（ProviderType / StopReason / FinishReason / EvictionPolicy）
- ✅ Phase 6 ToolDefinition IR — `ToolDef` 新类型 + 双向 `From` 转换 + 别名彻底移除 + `#[allow(deprecated)]` 清理（cycle/registry/mcp/agent）；Anthropic 零改动；roundtrip 测试覆盖
- ✅ Phase 7 SqliteStore — `rusqlite 0.32` + WAL 模式 + `Arc<Mutex<Connection>>` + `spawn_blocking`；`memory/store.rs` → `store/{in_memory,sqlite_store}.rs` 模块化；9 个内联测试覆盖 CRUD/upsert/过滤/10×10 并发/持久化 round-trip；`InMemoryStore ↔ SqliteStore` trait-box 互换兼容
- ✅ **Phase 8 MVP 集成出口** — 14 个公开枚举追加 `#[non_exhaustive]`（P0 核心 IR + P0 Error + P1 其他） + `StepStatus::Completed(ChatResponse)` → `Completed(MessageResponse)` 迁移 + CHANGELOG v0.2.0-rc.1 + 2 个新示例（`quick_start` 60 行 + `end_to_end` 246 行），10 个离线示例全部 exit 0；**v0.2.0-rc.1 标签已打**；实施后三方审查发现 6 项问题（1 🔴 + 2 🟡 + 3 💭）已全部修复
- ✅ **Phase 9 流式体验增强** — `AgentSession::submit_turn_stream` 流式事件序列 + `LlmCycle::submit_with_tools_stream` spawn + mpsc 状态机 + `StreamEvent::ToolExecutionStarted`/`Completed` 新变体 + 9 单元测试 + 2 集成测试（含 `submit_turn_stream_end_to_end` 端到端 mock 验证 + `submit_turn_stream_triggers_turn_hooks` Hook 触发验证），全量 200 → 211；`CycleConfig` 加 `Clone` derive；方案文档 `docs/16-phase9-streaming-experience.md`（821 行）
- ✅ **Phase 10 ContextSlot 上下文管理** — `src/agent/context.rs` 新增 `ContextSlot` 核心类型（Full / Focused / Readonly 三种模式，New / Derived / Static 三种来源）+ JSON blob 批次持久化（每 slot 3-4 条 MemoryItem，`slot_config` key 自恢复支持旧版本兼容）；`AgentSession` 扩展 slots 字段 + 5 个管理方法（`create_slot` / `switch_slot` / `list_slots` / `derive_slot` / `delete_slot`，自动创建 `"default"` slot，`delete_slot` 双重保护禁止删 default/最后一个）；`submit_turn`/`finalize_turn` 改造为基于当前 slot 的增量追加写回（`cycle.messages()[input_len..]` 提取本轮新增消息，确保 Focused 模式"读时过滤"语义不丢失数据）；`finalize_turn` 签名变更（新增 `new_messages_from_cycle: Vec<Message>` 参数，返回 `Result<(), AgentError>`）；`agent/error.rs` 新增 3 个 Slot 错误变体（`SlotReadonly` / `SlotNotFound` / `SlotAlreadyExists`）；`examples/context_slot_demo.rs` 新增分支对话示例（法律咨询入口 → 两个派生方向 → 切换 → 隔离验证 → 删除保护）；方案文档 `docs/17-phase10-contextslot.md`（1227 行，含 §5 推荐方案、§6 实施建议、§9 实施计划，经过 4 轮方案/计划/实施审查 + 1 轮非阻塞建议修复）；全量 211 → 254（+43 新测试），clippy 0 警告，doc 0 warning，11 个离线示例全部 exit 0
- ✅ **Phase 11 测试与检索补强** — `src/memory/vector.rs` 新增 `VectorRetriever` trait（index + search 抽象）+ `InMemoryVectorRetriever` 引用实现（HashMap + 全量余弦相似度扫描 + 零依赖 `dot()`），6 个内联测试覆盖 basic/empty/zero-vector/k=0/2 个并发；wiremock Provider roundtrip 测试 12 个（OpenAI 8 + Anthropic 4）覆盖请求体/header/401/429/500/529/流式 usage-only/流式错误/ToolUse/结构化错误体；`MemoryStore` 并发测试 5 个（InMemoryStore 3 + SqliteStore 2）覆盖 100 并发写、5 写+5 读混合 2 秒、15 写者容量淘汰；`openai.rs` `handle_error_response` 修复 429 retry-after 解析（5 行，与 anthropic 对齐）；方案文档 `docs/18-phase11-testing-and-retrieval.md`（647 行，含 10 项架构决策 + 2 条实施偏差记录 #6 mid-stream mock 模式 + #7 retry-after 修复）；全量 254 → 277（+23 新测试），clippy 0 警告，doc 0 warning，并发测试 3 次稳定无 flaky
- ✅ **Phase 13 热身清理 + ContextSlot fork/merge** — 3 个旧 types 文件删除（`request.rs` 187 行 + `response.rs` 177 行 + `old_stream.rs` 45 行），所有 OpenAI wire-format 类型迁入 `provider/openai.rs` 可见性 `pub(crate)`（Breaking Change：原 `agcore::llm::types::OpenaiChatRequest/Response/Chunk` 公共 re-export 路径已删除）；`ChatResponse` 自 v0.1.0 标记 `#[deprecated]` 后在 Phase 13 整体删除；`ToolChoice` 从 `request.rs` 迁入 `tool.rs`（公共 `agcore::llm::types::ToolChoice` 路径不变）；`ContextSlot::fork()` 派生独立子 slot（`SlotSource::Derived { parent_id, strategy }` 血缘可追溯）+ `ContextSlot::merge(child, MergeStrategy)` 合入父 slot（`Append` / `Replace` 两种策略，`#[non_exhaustive]` 预留扩展）；`MergeStrategy` 防御性检查（self-merge / 跨 session / Readonly 目标全部阻断）；`AgentSession::derive_slot` 重构复用 `fork()` 消除重复；`agent.rs` 追加 `MergeStrategy` re-export；9 个 fork/merge 内联测试覆盖 happy path 与 error path；`stream.rs` 简化为 module doc + `pub use` 重导出（保持 `use crate::llm::stream::StreamEvent` 路径兼容）；方案文档 `docs/19-phase13-cleanup-and-fork-merge.md`（640 行）；全量 277 → 286（+9 新测试），clippy 0 警告，doc 0 warning
- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen/Ollama 适配
- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、8 个离线示例（含 `simple_visit`）、README + 错误消息友好化、CHANGELOG 初始化
- ✅ **v0.2 规划细化完成** — 8 个增量 Phase（Phase 5-12），17 个可验证 Step，覆盖 P0-P2 全部 12 项功能 + ContextSlot
- ✅ **v0.3.0 Phase 13 完成** — 技术债清理（3 旧 types 文件 + ChatResponse 删除）+ ContextSlot fork/merge（9 新测试），M9 里程碑达成
- ✅ **v0.3.0 Phase 14 完成** — Document 类型（id/content/metadata/mime_type）+ `RecursiveCharacterSplitter` 两阶段算法（按 separator 优先级递归分割 + 贪心合并 overlap，全部 `chars_len()` 字符级比较）+ `Embedding` trait（async + `LlmError` 复用）+ `MockEmbedding`（sin-hash 零依赖伪随机 + L2 归一化）+ 19 Document 测试 + 6 Embedding 测试（含 1 个 split_multibyte_utf8_boundary CJK 边界测试）；`src/document.rs`（580 行）+ `src/llm/embedding.rs`（183 行）+ `examples/document_demo.rs`（74 行）；`pub use document::Document` 在 lib.rs 重导出；CJK 分隔符（`。`/`？`/`！`）加入 `DEFAULT_SEPARATORS`；方案文档 `docs/20-phase14-document-and-embedding.md`（1417 行）；全量 286 → 313（+27 新测试，0 失败），clippy 0 警告，doc 0 warning，零新外部依赖；M10 里程碑达成
- ✅ **v0.3.0 Phase 15 完成** — `VectorStore` trait（`add`/`search`/`remove`/`add_one`，返回 `(Document, f32)` 消除调用方 id→Document 维护开销）+ `InMemoryVectorStore`（`Mutex<HashMap>` + 余弦全量扫描 + 预计算 L2 norm 缓存）+ `PersistentVectorStore`（构造时全量加载，先写持久化后写内存，持久化失败时内存不污染重启自动恢复，`remove` 幽灵数据窗口已知）+ `RagPipeline` 组合器（ingest: split→embed→store.add / retrieve: embed→store.search，`splitter: Option<RecursiveCharacterSplitter>` 灵活切换）；`src/memory/vector_store.rs`（937 行，19 个内联测试覆盖 14 场景含 2 个性能基准）+ 零新外部依赖（纯 Rust `dot()` 余弦）；旧 `VectorRetriever`/`InMemoryVectorRetriever` 标注 `#[deprecated(since = "0.3.0")]` 迁移路径清晰；`search_orthogonal_vectors` 返回 1 条 score≈0（文档已同步修正不过滤低分向量）；方案文档 `docs/21-phase15-vector-store-persistence.md`（1570 行，经 3 轮审查 + 文档-代码一致化修复）；全量 313 → 335（+22 新测试），clippy 0 警告，doc 0 warning；M11 里程碑达成
- ✅ **v0.3.0 Phase 16 完成** — `SummaryConfig` 配置结构体（6 个字段：`trigger_token_ratio=0.75` / `max_context_tokens=32_000` / `summary_prompt` / `debounce_turns=3` / `summary_model=None` / `max_tool_result_chars=500`，默认 `None` 沿用主模型避断裂非 OpenAI 用户）+ `AgentBuilder::summary_config(cfg)` 链式方法 + `AgentConfig.summary_config: Option<SummaryConfig>` 字段；`AgentSession` 新增 `last_summary_turn: Option<u32>` 字段（首次不受防抖约束，`should_summarize` 用 `Option` 哨兵实现）+ `maybe_summarize(current_turn)` 内联检查点（OnTurnEnd 之后 / `turn_index` 之前，对称 `submit_turn` / `finalize_turn` 两个入口，流式路径 `saturating_sub(1)` 修正）+ 关联函数 `generate_summary`（构造独立 `LlmCycle` 调 `submit_messages` 传 `vec![Message::user_text(prompt)]`，`max_tokens=1024`，空消息守卫直接返回空串）+ 公开 API `get_conversation_summary()`；`src/agent/summary.rs`（~240 行，含 8 个 SummaryConfig/`format_messages_as_text` 内联测试——默认值/空输入/系统用户助理/ToolResult（含 `tool_call_id`）/工具调用/Unicode 安全截断/整体 30K 截断保留最新；有效字符数截断多字节安全，droptest 验证保留尾部消息）+ `src/agent/session.rs` 注入 10 个摘要集成测试（默认值不触发 / 超阈值触发 / 防抖阻止重复 / SessionMemory 写入 / Full 模式不注入 / 失败不阻断主流程 / 流式路径触发 / 默认配置零影响 / **Focused `summary_override` 写入正向验证** / **空消息不调用 LLM** / **巨型 `max_context_tokens` 永不触发**）；`format_messages_as_text` 简洁版消息格式化（`[Tool: name]` + `Tool Result [id]:` + ToolResult 字符级 `chars().take(max_tool_result_chars)` 截断 + 整段 30K 总长度截断从头部保留最新）；所有错误静默（失败用 `tracing::error!`，成功用 `tracing::info!(turn, summary_len)`）；`MergeStrategy` 注释中过时 "Summarize 指向"与 `context.rs:78` "v0.3 将支持 Hook 驱动" 过时注释在实施时同步移除/更新；方案文档 `docs/22-phase16-summary-auto-generation.md`（471 行），实施后**两轮审查 PASS**：第一轮 PM/SA 审查 11 项问题修复 + 第二轮实施审查 9 项问题修复（🔴 `generate_summary` 空消息 bug + 🟡 W4 流式路径防抖 + 🟡 W2 模型硬编码 + 🟡 W5 Full 模式无谓 save + 🟡 W3 30K 截断 + 🟡 W6 成功无日志 + 🟡 W1/W7 测试补全 + 💭 注释同步）；零新外部依赖；全量 335 → **353**（+18 新测试，含二次审查增补 4 个），clippy 0 警告，doc 0 warning，`quick_start` 示例正常 exit 0；**M12 里程碑达成** + 第二轮审查门禁 PASS
- ✅ **v0.3.0 Phase 17 完成** — 新建 `src/engine/` 模块（5 文件：`mod.rs`/`error.rs`/`snapshot.rs`/`checkpointer.rs`/`session_manager.rs`），实现 **SessionManager**（10 个公开方法：`create`/`create_child`/`get`/`recover`/`replace`/`children`/`parent`/`destroy`/`submit_turn`/`submit_turn_stream`/`finalize_turn_stream`，内部 `RwLock<HashMap>` + `Arc<tokio::sync::Mutex<AgentSession>>` + `Checkpointer` 组合）和 **Checkpointer**（5 个公开方法：`checkpoint`/`rollback_load`/`list_checkpoints`/`delete_all`/`latest_snapshot`）；`SessionSnapshot` 独立 struct 避开 `Arc<dyn Agent>` 不可序列化，配套 `SessionMemoryEntry` 保留 metadata/created_at；`AgentSession` 扩展三段式快照（`to_snapshot` async 读 MemoryStore + `from_snapshot` 纯同步构造 + `restore_memory` &mut self async 写回持久层）；`SessionMemory` 新增 `list_entries()` 和 `set_with_meta()` 方法（恢复时保留完整 entry 数据）；存储 key 风格统一为 `session:{id}:meta` / `ckpt:{id}:{ckpt_id}`（与 `slot_data:` 风格一致）；`EngineError` 6 个变体（含 `Memory(#[from] MemoryError)` 透传 + `Agent(#[from] AgentError)`）；`CkptMeta` 加 `created_at_nanos` 字段确保同秒内精确降序排序；ckpt_id 用纳秒+单调计数器生成（零外部依赖，ponytail）；session_id 用纳秒+计数器自动生成（统一策略，UUID v4 备选）；自动 checkpoint 失败 `tracing::error!` 不阻断主流程（不提供强持久化保证）；流式 checkpoint 仅在 `finalize_turn_stream` 创建（不留半成品污染）；孤儿策略：`destroy()` 不递归删除子 session，父被销毁后 `parent()` 返回 `Ok(None)`；3 处 derive 改动（`CostTracker` + `ContextSlot` + `MergeStrategy` 加 serde，`CostTracker` 额外加 `Clone`）；`SessionManager::recover` + `replace` 内部自动 `restore_memory` 写回持久层；零新外部依赖；方案文档 `docs/23-phase17-agent-execution-engine.md`（775 行，经两轮 PM+SA 审查 + 实施后第三轮 PM+SA+Code Reviewer 三方联合审查），实施后**两轮审查门禁 PASS**：第一轮修复 6 🔴 + 第二轮修复 2 🔴（to_snapshot 同步→async + Roadmap 同步）+ 实施后修复 8 个 🟡（restore_memory metadata/created_at 完整恢复 + &mut self 签名 + 死代码清理 + 3 个边界测试 + tracing 补全 + 文档语义统一 + 示例 rollback 一致性 assert）；15 个 `SessionManager` 内联测试（CRUD/recover/replace/树形/孤儿/auto_checkpoint on-off）+ 6 个 `Checkpointer` 内联测试（roundtrip/不存在的 ckpt/同秒降序/delete_all 幂等/latest/隔离）+ 1 个 `snapshot_deserialize_with_minimal_fields` 序列化兼容测试；全量 353 → **374**（+21 新测试），clippy 0 警告，doc 0 warning，`engine_demo` 示例端到端演示 create→submit_turn→checkpoint→rollback→replace→destroy 全链路并验证 rollback 一致性；**M13 里程碑达成** + 两轮审查门禁 PASS
- ✅ **v0.3.0 Phase 18 完成** — 新增 `src/engine/switch.rs`（222 行）实现 `SessionManager::switch_agent()` 热切换（替换 `Arc<dyn Agent>`，slot 历史 / `turn_index` / `session_memory` / `cost_so_far` 全部保留，同步更新 `SessionMeta.agent_name` 到持久层，`created_at` / `parent_id` 保持原始不可变）+ 新增 `src/engine/sub_agent.rs`（1071 行）实现 4 个公开方法（`dispatch` / `dispatch_all` / `dispatch_stream` 与前述 `switch_agent` 共 4 个 Phase 18 核心 API）+ 3 个公开类型（`DispatchConfig` / `SubTaskResult` / `SubTaskStreamEvent`）；`DispatchConfig` 4 字段（`max_concurrency=10` / `inherit_session_memory=true` / `bridge_keys=None` / `shared_namespace=None`）+ 三态 `bridge_keys` 语义（`None` = 不继承 / `Some(vec![])` = 全部 / `Some(keys)` = 指定 keys）+ 约定式 `shared_namespace` 子↔子共享（`shared:{prefix}:{key}`）不触发自动注入；`dispatch` 流程：`create_child` → `inherit_session_memory`（快照语义）→ `submit_turn` → 返回 `SubTaskResult`；`dispatch_all` `tokio::sync::Semaphore` 并发控制 + `Vec<Result<...>>` 部分成功语义按输入顺序 indexed 收集；`dispatch_stream` `unbounded_channel` + spawn task 消息重建 + `finalize_turn` 后台落库（明确不参与 `auto_checkpoint` 防重复）；`SubTaskStreamEvent` 事件序列：`ChildCreated` → `Stream(StreamEvent) × N` → `Completed(SubTaskResult)` 或 `Error { child_id, error }`；`EngineError` 新增 `DispatchFailed(#[source] String)` 变体 + `CostTracker` 加 `From<Usage>` 转换；`save_session_meta` / `load_session_meta` 改 `pub(crate)` 供 `switch.rs` 调用；4 个端到端示例：`agent_switch_demo`（115 行）+ `sub_agent_dispatch_demo`（141 行）+ `bridge_keys_demo`（197 行）+ `dispatch_stream_demo`（121 行）全部 exit 0；17 个内联测试（4 switch + 5 dispatch + 4 dispatch_all + 4 dispatch_stream）；零新外部依赖；方案文档 `docs/24-phase18-agent-switch-and-dispatch.md`（700 行）；全量 374 → **391**（+17 新测试，0 失败），clippy 0 警告，doc 0 warning；**M14 里程碑达成**
- ✅ **v0.3.0 Phase 19 完成** — 知识图谱 + 双通道检索，详见 `docs/25-phase19-knowledge-graph-and-retrieval.md`；全量 391 → **427 passed / 0 failed**（+36 新测试）；**M15 里程碑达成**
- ✅ **v0.3.2 Phase 20-27 全部完成** — Cargo features 拆分（16 模块级 + 5 provider + 4 快捷组合），详见 `docs/roadmap-v0.3.2.md`；全量 427 → **427 passed**（不变，门控验证）
- ✅ **Phase 28-30 OpenAI Response API Provider 完成** — 独立 feature `provider-openai-response`，全量约 450 passed
- 📋 **v0.4.0 规划完成** — 5 个增量 Phase（A-E）覆盖多 Agent 编排、HITL + Steering、TokenJuice、自动校正。详见 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md)

---

## 设计笔记

### Checkpointer 分层存储模型

> 来源：v0.4.0 规划讨论中涉及增量 Checkpoint 的技术推演。当前全量 JSON checkpoint 够用，但为未来优化预留设计方案。

#### 分层叠加模型（OverlayFS 模式）

受容器分层文件系统启发，增量 Checkpoint 可以借鉴 overlayfs 的"底层只读 + 上层可写叠加"设计：

**全量基座（只读）**：
```rust
pub struct SnapshotBase {
    pub checkpoint_id: String,
    pub session_id: String,
    pub snapshot: SessionSnapshot,  // 完整 JSON 化状态
}
```

**增量层（叠加 diff）**：
```rust
pub struct SnapshotLayer {
    pub base_checkpoint_id: String,
    pub applies_to_id: String,       // 在哪个 checkpoint 上叠加
    pub diff: Vec<DiffOp>,           // JSON Patch 操作集合
}

pub enum DiffOp {
    MessageAppended { message: Message },
    SlotChanged { slot_id: String, diff: serde_json::Value },
    TurnIndexIncremented { from: u32, to: u32 },
    CostUpdated { diff: CostTracker },
}
```

**重建路径**：
```
rollback_load("session_x", 6)
  → 读取 "ckpt:{session_x}:base"（全量）
  → 读取 "ckpt:{session_x}:layer:1" ~ "ckpt:{session_x}:layer:6"
  → 依次应用 layer.1 → layer.2 → ... → layer.6
  → 得到 session_6 的状态
```

**层折叠（类似 docker squash）**：
```
layer.1 → layer.2 → layer.3 → layer.4 → layer.5
                    ↓ 合并
base.ckpt'（包含 layer.1-3）→ layer.4 → layer.5
```

#### Shadow FS 模型（运行中保护）

与分层模型互补，shadow 模型适用于运行中的 session 保护而非长期存储：

```rust
// submit_turn 在 shadow session 上执行，commit 时才原子切换
let shadow = current_session.fork();  // 复用 ContextSlot::fork
let result = shadow.submit_turn(input).await;
if result.is_ok() {
    current_session.commit(shadow);   // 原子替换
} else {
    drop(shadow);                     // 丢弃，当前 session 完好无损
}
```

#### 适用场景对比

| 模型 | 适合场景 | 不适合场景 |
|------|---------|-----------|
| **分层叠加（OverlayFS）** | Checkpoint 链长期存储、time-travel、多版本回退 | session 较小（< 10KB/轮）时复杂度不值得 |
| **Shadow FS（CoW）** | 运行中 session 保护、防止 submit_turn 失败污染 | 不能替代 checkpoint 链、不支持多时间点回退 |

**触发条件**：当单 session checkpoint 超过 500KB 且频繁保存导致性能瓶颈时，考虑实现分层模型。