agcore/docs/roadmap.md

# AG Core Roadmap

> 定稿日期：2026-05-11
> 最后更新：2026-07-08（Phase 13 完成 + M9 里程碑达成）

## 愿景

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

**当前状态**：v0.2.0-rc.1 已打标签。Phase 0-13 全部完成。v0.3.0 实施中，Phase 14-19 共 6 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 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（流式接口前置） |

---

## 分阶段 Roadmap

### Phase 0 — Foundation（基础设施）

**目标**：实现 LLM 调用周期的核心功能，作为所有上层模块的基础。

**交付物**：
1. ✅ `llm/types.rs` — 核心数据类型（Message, ContentBlock, ChatRequest/Response, ToolDefinition, StopReason）
2. ✅ `llm/error.rs` — 错误体系（LlmError 枚举，可重试/不可重试判断）
3. ✅ `llm/provider.rs` + `llm/provider/openai.rs` — Provider 接口 + OpenAI 兼容实现
4. ✅ `llm/provider/registry.rs` — ProviderRegistry（多 Provider 注册发现）
5. ✅ `llm/cycle.rs` + `llm/cycle/{retry,usage}.rs` — 生命周期引擎（重试策略 + 用量追踪）
6. ✅ `llm/hooks.rs` — HookExecutor 接口（生命周期钩子）
7. ✅ `llm/stream.rs` — StreamEvents 流式事件系统（AssistantTextDelta, ToolExecutionStarted 等）
8. ✅ `llm/compact.rs` — Auto-compaction（上下文自动压缩）
9. ✅ `Cargo.toml` — 添加依赖（tokio, reqwest, serde, thiserror, async-trait, tracing）

**依赖**：无

**优先级**：Must Have

**预估规模**：约 1000 行核心代码

**状态**：✅ Phase 0 全部交付物已完成

---

### Phase 1 — Prompt Engineering（提示词工程）

**目标**：提供提示词的组合、模板化与优化能力。

**交付物**：
1. ✅ `prompt.rs` + `prompt/` 模块
2. ✅ `PromptTemplate` — 模板引擎（支持变量插值、条件渲染）
3. ✅ `PromptComposer` — 提示词组合器（拼接 system/user/assistant 消息）
4. ✅ `docs/4-prompt-engineering.md` — 方案文档

**依赖**：无（可与 Phase 0 并行）

**优先级**：Should Have

**预估规模**：约 400 行代码

**状态**：✅ Phase 1 全部交付物已完成

---

### Phase 2 — Tool System（工具系统）

**目标**：实现 MCP 协议集成与自定义工具注册、调用、权限控制。

**交付物**：
1. ✅ `tools.rs` + `tools/` 模块（base/registry/permission/mcp/error）
2. ✅ `ToolRegistry` — 工具注册表（注册、发现、调用、并行执行、超时控制）
3. ✅ `BaseTool` trait — 工具抽象接口（含 ToolContext 执行上下文）
4. ✅ `McpClient` — MCP 协议客户端（stdio transport，StreamableHttp 预留）
5. ✅ `PermissionChecker` — 工具执行权限检查（白名单/黑名单/自定义权限）
6. ✅ `docs/5-tool-system.md` — 方案设计文档
7. ✅ 扩展 `llm/cycle.rs` 支持自动 tool 循环（`submit_with_tools()` + `submit_request()` + `maybe_compact()`）
8. ✅ `ToolError` — 结构化错误体系（含 `is_recoverable()` 分类）

**依赖**：Phase 0（LlmProvider 接口传递 tool definitions）、Phase 1（提示词可能需要注入工具描述）

**优先级**：Should Have

**预估规模**：约 900 行代码（实际约 1500 行）

**状态**：✅ Phase 2 全部交付物已完成

---

### Phase 3 — Memory System（记忆系统）

**目标**：提供对话记忆的存储、检索与管理能力。

**交付物**：
1. ✅ `memory.rs` + `memory/` 模块（store / conversation / knowledge / retriever / error / types）
2. ✅ `MemoryStore` trait + `InMemoryStore` — 记忆存储抽象（可插拔后端）+ 默认实现
3. ✅ `ConversationMemory` — 对话记忆管理（sliding window / 全量），复用 `llm::compact`
4. ✅ `KnowledgeStore` — 知识页面存储（具体 struct，非 trait，基于 MemoryStore）
5. ✅ `MemoryRetriever` — 记忆检索器（TextOverlap Dice 系数评分，单通道）
6. ✅ `docs/6-memory-system.md` — 方案设计文档
7. ✅ `docs/note-knowledge-graph-design.md` — KnowledgeGraph 等 Phase 4 备用设计
8. ✅ `EvictionPolicy` — 支持 None / Ttl / Capacity 三种淘汰策略

**依赖**：Phase 0（llm::compact 复用）、Cargo.toml 新增 `time` 依赖

**优先级**：Could Have

**预估规模**：约 700 行代码（实际约 1242 行，含测试）

**状态**：✅ Phase 3 全部交付物已完成

---

### Phase 4a — Agent Core Glue（核心胶水层）

**目标**：提供最小可用的 Agent Runtime——把 Phase 0-3 的能力"装配"成 `AgentSession::submit_turn`。上层可基于 4a 构建多轮对话应用。

**交付物**：
1. ✅ `agent.rs` + `agent/` 模块（7 个文件：agent/error/runtime/builder/session/task + 模块根）
2. ✅ `Agent` trait — 智能体角色定义（name / system_prompt / tool_definitions）
3. ✅ `AgentSession` — 会话实例（绑定 `Arc<dyn Agent>` + `RuntimeBundle` + 内联 HashMap session_data）
4. ✅ `RuntimeBundle` — 显式依赖注入容器（不含 session_memory_backend）
5. ✅ `AgentBuilder` — 链式构造入口（不含 session_memory_backend）
6. ✅ `AgentError` — 统一错误类型（7 个变体：Llm / Tool / Memory / HookBlocked / LimitExceeded / Config / Other；不含 PlanParse）
7. ✅ `Plan` / `Step` / `StepStatus` — 纯数据结构（不含任何解析逻辑）
8. ✅ Hook 事件扩展：OnTurnStart / OnTurnEnd + turn_index 字段
9. ✅ `docs/7-agent-runtime.md` — 方案设计文档（含 4a/4b/4c 分阶段计划）

**实际新增**：
- 新增文件 7 个（agent.rs + agent/{agent, error, runtime, builder, session, task}.rs）
- 修改文件 3 个（lib.rs +1 行；llm/hooks.rs +13 行追加变体/字段；llm/cycle.rs 内部字段 Box→Arc + 新增 `new_with_arc` 公共方法）
- 实际代码量约 800 行（含测试；纯实现约 470 行——略高于方案预估 440 行，因 AgentSession 的 tests 模块内联 MockProvider/StubAgent 等辅助结构）
- 新增内联测试 22 个；全量测试 84 → 109（0 失败）
- clippy 0 警告（agent 模块）
- 无新增外部依赖

**依赖**：Phase 0, 1, 2, 3

**优先级**：Could Have

**预估规模**：约 440 行代码

**状态**：✅ Phase 4a 全部交付物已完成

---

### Phase 4b — Task Execution（任务执行）

**目标**：在 Phase 4a 基础上，赋予智能体"拆解目标 → 逐步执行"的能力。

**前置条件**：Phase 4a 已完成。

**交付物**：
1. ✅ `TaskAgent` trait — `run(goal)` 自主式 + `execute_plan(plan)` 外部驱动式
2. ✅ `PlanParser` trait + `JsonPlanParser` 参考实现
3. ✅ `AgentError` 追加 PlanParse 变体（共 7 个变体）
4. ✅ Hook 事件扩展：OnPlanStepComplete + plan_step_index 字段

**依赖**：Phase 4a

**优先级**：Could Have

**预估规模**：约 200 行代码（增量）

**实际新增**：
- 修改文件 2 个（llm/hooks.rs +5 行；agent/error.rs +10 行）
- 新增代码约 150 行（含测试；纯实现约 90 行）
- 新增内联测试 4 个；全量测试 109 → 113（0 失败）
- clippy 0 警告
- 无新增外部依赖

**状态**：✅ Phase 4b 全部交付物已完成

---

### Phase 4c — Session Memory（会话级记忆）

**目标**：提供会话级 key-value 记忆，作为 session 内各 context 之间的信息桥接通道。

**前置条件**：Phase 4a 已完成（可与 Phase 4b 并行）。

**交付物**：
1. ✅ `SessionMemory` struct — 基于 `MemoryStore`，按 session_id namespace 隔离
2. ✅ `RuntimeBundle` + `AgentBuilder` 扩展 `session_memory_backend` 字段
3. ✅ `AgentSession` 替换内联 HashMap 为完整 `SessionMemory`

**依赖**：Phase 4a（Phase 3 MemoryStore）

**优先级**：Could Have

**预估规模**：约 115 行代码（增量）

**实际新增**：
- 新增文件 1 个（agent/session_memory.rs）
- 修改文件 4 个（agent/runtime.rs +5 行；agent/builder.rs +10 行；agent/session.rs +30 行；agent.rs +2 行）
- 新增代码约 180 行（含测试；纯实现约 100 行）
- 新增内联测试 3 个；全量测试 113 → 116（0 失败）
- clippy 0 警告
- 无新增外部依赖

**状态**：✅ Phase 4c 全部交付物已完成

---

## 依赖关系图

```mermaid
graph BT
    P0["<b>Phase 0: Foundation</b><br/>LLM Cycle<br/>ProviderRegistry<br/>HookExecutor<br/>StreamEvents<br/>Auto-compaction"]:::done
    P1["<b>Phase 1: Prompt Engineering</b><br/>PromptTemplate<br/>PromptComposer"]:::done
    P2["<b>Phase 2: Tool System</b><br/>Tool Registry<br/>PermissionChecker<br/>MCP Client"]:::done
    P3["<b>Phase 3: Memory System</b><br/>MemoryStore<br/>ConversationMemory<br/>KnowledgeStore"]:::done
    P4a["<b>Phase 4a: Core Glue</b><br/>AgentSession<br/>RuntimeBundle<br/>Plan/Step 纯数据"]:::done
    P4b["<b>Phase 4b: Task Execution</b><br/>TaskAgent<br/>PlanParser<br/>JsonPlanParser"]:::done
    P4c["<b>Phase 4c: Session Memory</b><br/>SessionMemory"]:::done

    P1 --> P0
    P2 --> P0
    P3 --> P0
    P2 --> P1
    P4a --> P1
    P4a --> P2
    P4a --> P3
    P4b --> P4a
    P4c --> P4a

    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
    classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
```

---

## v0.2.0 — 生产就绪（Production-Ready Core）

**目标**：解决 Rust Agent 工具箱从"能跑"到"能被人依赖"的鸿沟。持久化、配置层、上下文管理三大块补齐后，开发者可在 30 分钟内写出生产可用的 Agent 服务。

**总体规模**：8 个增量 Phase（Phase 5-12），17 个可验证 Step。

### 功能清单

#### P0 — 必须交付

| # | 功能 | 模块 | 方案要点 |
|---|------|------|---------|
| 1 | SqliteStore | `memory` | `rusqlite` + `bundled` feature，`MemoryStore` 的 SQLite 实现，进程重启数据不丢 |
| 2 | ProviderConfig 扩展 + `from_env()` | `llm` | 补全 `timeout_secs` / `max_retries` 字段；`AG_LLM_*` 环境变量辅助函数 |
| 3 | ToolDefinition IR 正式化 | `tools` | 移除 deprecated OpenAI wire 格式，替换为自定义 `ToolDef` 结构体 |
| 4 | API 稳定性管理 | `*` | 公开枚举加 `#[non_exhaustive]`；CHANGELOG 记录 Breaking Changes；废弃 API 用 `#[deprecated]` 标记 |
| 5 | Quick Start + 端到端示例 | `examples/` | 30 行 `main.rs` 快速开始；一个"SQLite 持久化 + Provider + 工具调用 + 多轮对话"的可运行示例（`cargo run --example`） |

#### P1 — 重要但不阻塞

| # | 功能 | 模块 | 方案要点 |
|---|------|------|---------|
| 6 | Ollama Provider | `llm/provider` | OpenAI Compat，本地 LLM 支持，实现量极小 |
| 7 | VectorRetriever trait | `memory` | 语义检索 trait 抽象（`index` / `search`），不绑定后端实现 |
| 8 | 流式 `submit_turn_stream` | `agent` | `AgentSession` 新增 `submit_turn_stream()`，返回 `Stream<Item = StreamEvent>` |
| 9 | 测试补强 | `*` | wiremock Provider roundtrip 测试；多线程并发写入 MemoryStore 测试 |

#### P2 — 有时间再做

| # | 功能 | 模块 | 备注 |
|---|------|------|------|
| 10 | MCP StreamableHttp | `tools` | 当前仅预留枚举变体 |
| 11 | Gemini Provider | `llm/provider` | 协议差异大，实现成本较高 |
| 12 | 文件系统 MemoryStore 后端 | `memory` | JSON/JSONL 轻量持久化 |

### ContextSlot 上下文管理

**模块归属**：`src/llm/context.rs`（与 `compact.rs` 同级）

**核心概念**：`ContextSlot` 是一段带策略配置的消息列表，以 `slot_id` 为 namespace 独立持久化到 `MemoryStore`。支持三种模式、三种来源和派生关联（记录 `parent_id`）。

**核心类型**：

```rust
pub struct ContextSlot { id, session_id, config, messages, store }
pub struct SlotConfig { mode: SlotMode, source: SlotSource, budget, compact }
pub enum SlotMode {
    Full,                                               // 完整对话历史
    Focused(FocusedConfig),                             // 聚焦：保持 LLM 注意力
    Readonly,                                           // 只读参考上下文
}
pub struct FocusedConfig { keep_system, recent_turns, inject_summary }
pub enum SlotSource {
    New,                                                // 全新空槽，独立持久化
    Derived { parent_id, strategy: DeriveStrategy },     // 从父 slot 派生
    Static(Vec<Message>),                               // 预置消息，不持久化
}
pub enum DeriveStrategy { Full, Focused(FocusedConfig) }
pub struct ContextBudget { system, history, tools, tool_results, reserve }
```

**持久化 Key 命名**：
- `slot_msg:{session_id}:{slot_id}:{index}` → 消息内容
- `slot_meta:{session_id}:{slot_id}` → `SlotMeta`（含 `parent_id`）
- `slot_rel:{session_id}:{child_id}:parent` → `"{parent_id}"`

**`AgentSession` 扩展**：
- `create_slot(id, config)` — 创建新 slot
- `switch_slot(id)` — 切换当前 slot
- `list_slots()` — 列出所有 slot
- `derive_slot(id, parent_id, strategy)` — 从父 slot 派生

**与 `ConversationMemory` 的关系**：保留不废除。`ConversationMemory` 继续服务传统对话场景。

**v0.2 不做**：
- ❌ `slot.fork()` / `merge()` — 分支方法推迟到 v0.3+
- ❌ `inject_summary` 自动生成 — v0.2 仅消费端（从 `SessionMemory` 读取），生成在 v0.3+
- ❌ 血缘关系图遍历 — 只存 `parent_id`，不做查询

**依赖**：Phase 0（MemoryStore trait）、Phase 3（MemoryStore 持久化）
**优先级**：P1

---

### v0.2.0 实施计划 — 8 个增量 Phase

> **编号说明**：Phase 5-12 接续 v0.1 的 Phase 0-4c，按开发顺序排列。

#### Phase 5: 热身准备（Warmup）

**目标**：快速交付三个互不依赖的独立改动，建立交付节奏。

| Step | 内容 | 文件范围 | 验证标准 |
|------|------|---------|---------|
| **5.1** ✅ | `ProviderConfig` 扩展：补 `timeout_secs`(def=30) + `max_retries`(def=3)；新增 `ProviderConfig::from_env(prefix)` | `llm/provider.rs` + 各 Provider `new()` 构造函数 | `cargo test` + `from_env()` 单元测试 |
| **5.2** ✅ | `OllamaProvider`：基于 `GenericOpenaiProvider` 包装，改 base_url 为 `http://localhost:11434`；`ProviderType` 新增 `Ollama` | `llm/provider/provider.rs` + `llm/provider/ollama.rs`（新增） | `cargo build` — 纯类型级验证 |
| **5.3** ✅ | 公开枚举 `#[non_exhaustive]` 前置标记：`ProviderType` / `StopReason` / `FinishReason` / `EvictionPolicy` / `SlotMode`(预置) | 各枚举定义处 | 编译通过 + `cargo clippy` 0 警告 |

**实际新增**（2026-07-05 commit `98dfe6c`）：
- 新增文件 1 个（`llm/provider/ollama.rs`，72 行）
- 修改文件 2 个（`llm/provider.rs` 加 `from_env` + `Default` + 4 个字段；`memory/store.rs` EvictionPolicy 加 `#[non_exhaustive]`）
- `ProviderType::Ollama` 变体 + `FromStr` 解析（"ollama" → Ollama）
- `OllamaProvider::new(base_url, api_key, model, timeout_secs)` + `with_client()` 构造函数
- `ProviderConfig::from_env(prefix)` 解析 `{prefix}_API_KEY` / `{prefix}_BASE_URL` / `{prefix}_MODEL` 环境变量
- 全量测试 182 → 190（+8，phase 5 新增 from_env 与 Ollama 相关单测）
- clippy 0 警告

**依赖**：无（三个 Step 互不冲突）
**优先级**：P0（5.1）+ P1（5.2）+ P0 前置（5.3）
**为何独立成 Phase**：三个改动零文件重叠，可以并行推进。它们是后续所有 Phase 的"门把手"——先做完热身再进入核心工作。
**状态**：✅ Phase 5 全部交付物已完成

---

#### Phase 6: ToolDefinition IR 正式化

**目标**：引入 `ToolDef` 新类型，替换已标记 `#[deprecated]` 的 `ToolDefinition`（`OpenaiToolDefinition` 别名）。

**这是 v0.2 技术风险最高的 Phase**，影响 4 个模块约 8 个文件。通过 5 个 Step 逐文件切割确保每步可编译。

| Step | 内容 | 验证标准 |
|------|------|---------|
| **6.1** ✅ | `types/tool.rs` 新增 `ToolDef` 结构体 + `From<ToolDef> for OpenaiToolDefinition` + 反向 `From` | 单元测试 roundtrip |
| **6.2** ✅ | `types/mod.rs` 切别名 `pub type ToolDefinition = ToolDef`；`MessageRequest.tools` 改 `Vec<ToolDef>` | `cargo build` 编译断点 |
| **6.3** ✅ | `cycle.rs` 4 个方法签名 + `registry.rs` `definitions()` 签名更新 | `cargo build` |
| **6.4** ✅ | Provider 适配层（openai.rs / anthropic.rs / openai_compat.rs）：`build_request()` 内做 `ToolDef → wire-format` 转换 | `cargo test` 每个 provider 测试 |
| **6.5** ✅ | 所有测试/示例中 `ToolDefinition` → `ToolDef` 修复；移除旧 `#[deprecated]` alias | `cargo test --all-targets` 全绿 |

**边界切割技巧**：
- Step 6.1 → 6.2 之间是安全 checkpoint：新类型存在但旧代码照常编译
- Provider 层不改序列化逻辑，只加一层 `From` 转换
- 当前代码中 `ToolDefinition` 已是 `#[deprecated(since = "0.1.0")]`，用户已有迁移预期

**依赖**：无（仅与 Phase 5.3 有枚举兼容关系）
**优先级**：P0

**实际新增**（2026-07-05 commit `4cf5918` / `9da9b83` / `b187519`，详见 `docs/13-phase6-tooldef-ir.md`）：
- 修改文件 8 个：`llm/types/tool.rs`、`llm/types/mod.rs`、`llm/types/request_v2.rs`、`llm/cycle.rs`、`llm/provider/openai.rs`、`tools/registry.rs`、`tools/mcp.rs`、`agent/agent.rs`
- `ToolDef` IR（name / description / parameters，无 `strict`）新增于 `types/tool.rs`，配套双向 `From` 转换
- `OpenaiToolDefinition` 降级为 `#[doc(hidden)]`，仅供 OpenAI 适配层内部消费
- `MessageRequest.tools` 切换为 `Vec<ToolDef>`
- `ToolDefinition` 别名最终完全移除（直接使用 `ToolDef`）
- 4 处 `#[allow(deprecated)]` 抑制点全部清理（cycle/registry/mcp/agent）；残留 `#[allow(deprecated)]` 均与 `ChatResponse` / `with_system_prompt` 等其他弃用项无关
- 新增 roundtrip 测试 `message_request_with_tools_roundtrip`（断言 `strict` 字段不泄漏到序列化输出）
- Anthropic 适配层字段名一致零改动；openai_compat/ollama 委托 `GenericOpenaiProvider` 零改动
- 全量测试 190 → 191（+1，Phase 6 新增 roundtrip）；clippy 0 警告

**状态**：✅ Phase 6 全部交付物已完成

---

#### Phase 7: SqliteStore 持久化

**目标**：实现 `MemoryStore` 的 SQLite 后端，进程重启数据不丢。

**与 Phase 6 无耦合，可重叠开发。**

| Step | 内容 | 文件 | 验证标准 |
|------|------|-----|---------|
| **7.1** ✅ | 新增 `memory/store/sqlite.rs`：`Mutex<Connection>` + `spawn_blocking`，实现 `save/get/delete/list` + prefix 过滤 | `memory/store/sqlite.rs` + `Cargo.toml`（add `rusqlite`） | 单元测试 CRUD + prefix 查询 |
| **7.2** ✅ | WAL 模式 + 并发安全 + 集成测试（`tokio::spawn` 10 个并发 task） | `sqlite.rs` 扩展 | 并发写入 100 轮无 race |

**设计决策**：
- 用 `Mutex<Connection>` 而非连接池（ponytail：一个连接够用就不加 r2d2）
- WAL 模式：`PRAGMA journal_mode=WAL` 解决读写锁

**依赖**：`MemoryStore` trait（v0.1 Phase 3 已就绪）
**优先级**：P0

**实际新增**（2026-07-05 commit `13edacd` / `c8a91f6` / `c82af60`，详见 `docs/14-phase7-sqlite-store.md`）：
- 方案文档：`docs/14-phase7-sqlite-store.md`（526 行，Phase 7 设计推演与权衡记录）
- 结构重组：`src/memory/store.rs` 单体文件 → `src/memory/store/{mod.rs(in_memory.rs, sqlite_store.rs)}` 模块目录；外部导入路径 `crate::memory::store::MemoryStore` 不变
- 新增文件 2 个：`src/memory/store/sqlite_store.rs`（545 行 SqliteStore 实现 + 9 个内联测试）、`src/memory/store/in_memory.rs`（266 行，结构搬移）
- 核心实现要点：
  - `Arc<Mutex<Connection>>` 串行化所有 IO；`spawn_blocking` 卸载到阻塞线程池
  - WAL 模式 + `synchronous=NORMAL` + `busy_timeout=5s` + `wal_autocheckpoint=1000`
  - `PRAGMA user_version` schema 版本管理（`INITIAL_USER_VERSION = 1`）
  - `created_at` 归一化为 UTC 的 RFC 3339 TEXT，字典序等价时间序
  - 错误精细映射：`SqliteFailure` / `InvalidQuery` → `InvalidInput`；`FromSqlConversionFailure` → `Serialization`；其他 → `Storage`
- 9 个内联测试覆盖：CRUD、upsert、prefix / since / offset+limit 过滤、10 写者 × 10 次并发写入、持久化 round-trip（重启连接不丢数据）、`InMemoryStore ↔ SqliteStore` trait-box 互换兼容性
- 依赖：`rusqlite = { version = "0.32", features = ["bundled"] }`；`time` 增补 `parsing` / `formatting` / `macros` features；`dev-dependencies` 新增 `tempfile = "3"`
- 全量测试 191 → 200（+9，Phase 7 新增 SqliteStore 单测）；clippy 0 警告

**状态**：✅ Phase 7 全部交付物已完成

---

#### Phase 8: MVP 集成出口（v0.2.0-rc.1 候选）

**目标**：P0 五项全部交付。开发者 clone 仓库后 10 分钟跑起持久化 Agent。

| Step | 内容 | 验证标准 |
|------|------|---------|
| **8.1** ✅ | API 稳定性扫尾：`#[non_exhaustive]` × 14 公开枚举 + `StepStatus::Completed` 切 `MessageResponse` + CHANGELOG v0.2.0-rc.1 + Cargo.toml 0.2.0-rc.1 | `cargo doc --no-deps` 0 warning + 零 deprecated warning |
| **8.2** ✅ | Quick Start 示例（57 行 `main.rs`）：MockProvider + EchoTool + submit_turn 真实工具调用 | `cargo run --example quick_start` exit 0 |
| **8.3** ✅ | 端到端示例：SqliteStore + AG_LLM_* from_env 自动检测 + 3 工具 + 3 轮对话 + 持久化跨连接验证 | `cargo run --example end_to_end`（Mock fallback，无需 API key）|

**Phase 8 全部完成**。**已打 `v0.2.0-rc.1` 标签**。

**实际新增**（2026-07-05，7 commits）：
- `feat(core)` —— 14 个公开枚举追加 `#[non_exhaustive]`（P0 核心 IR + P0 Error + P1 其他）
- `refactor(agent)` —— `StepStatus::Completed(ChatResponse)` → `Completed(MessageResponse)` + `task_agent_demo.rs` 清理 3 处废弃类型
- `docs` —— CHANGELOG v0.2.0-rc.1 条目 + Cargo.toml version 0.1.0 → 0.2.0-rc.1 + README 示例列表 7 → 10
- `test(core)` —— 验证 commit 1-3 零回归（test 200 passed + clippy 0 警告 + doc 0 warning）
- `feat(examples)` —— `quick_start.rs`（60 行）+ `end_to_end.rs`（246 行）
- `docs(roadmap)` —— 标记 Phase 8 全部完成 + M4 里程碑 ✅
- `fix(examples)` —— 实施后 PM/SA/Code Reviewer 三方审查发现 6 项问题（🔴 CalcTool 除零 panic + 🟡 drop 注释准确性 + 🟡 EchoTool 错误处理 + 💭 断言一致性 + 💭 工具两端语义统一 + 💭 trailing newline），全部修复

**依赖**：Phase 5（ProviderConfig from_env）+ Phase 6（ToolDef）+ Phase 7（SqliteStore）
**优先级**：P0
**状态**：✅ Phase 8 全部交付物已完成

---

#### Phase 9: 流式体验增强

**目标**：Agent 会话支持流式输出，开发者看到实时 token。

| Step | 内容 | 文件 | 验证标准 |
|------|------|-----|---------|
| **9.1** ✅ | `AgentSession::submit_turn_stream(user_input) -> impl Stream<Item=StreamEvent>` | `agent/session.rs` | 单元测试验证流事件序列：`TextDelta → ... → MessageComplete` |

**注意**：tool 自动循环时流中插入 `ToolExecutionStarted` 事件，用户端 UI 显示"正在调用工具..."。

**依赖**：Phase 6（ToolDef）+ `LlmProvider.chat_stream`（v0.1 已有）
**优先级**：P1

**实际新增**（2026-07-06 commit `212cfcc`，详见 `docs/16-phase9-streaming-experience.md`）：
- 方案文档：`docs/16-phase9-streaming-experience.md`（821 行，含状态机设计推演与边界情况）
- 修改文件 3 个：`src/agent/session.rs`（+208，含 `submit_turn_stream` / `finalize_turn`）、`src/llm/cycle.rs`（+784，含 `submit_with_tools_stream` / `run_tool_loop` spawn + mpsc 状态机）、`src/llm/types/response_v2.rs`（+21，含 `StreamEvent::ToolExecutionStarted`/`Completed` 变体 + `apply_to` 元事件）
- 关键设计：`CycleConfig` 加 `Clone` derive 以支持 spawn 跨 task；`finalize_turn` 手动同步状态（`submit_turn_stream` 返回流前不落库，避免半成品被 hook 误读）
- 测试：新增 9 个单元测试 + 2 个集成测试（含 `submit_turn_stream_end_to_end` 端到端 mock provider 流消费 + `submit_turn_stream_triggers_turn_hooks` Hook 触发验证），全量 200 → 211（+11，0 失败）
- clippy 0 警告
- 无新增外部依赖

**状态**：✅ Phase 9 全部交付物已完成

---

#### Phase 10: ContextSlot 上下文管理

**目标**：支持多上下文分区管理，Agent 可在不同 slot 之间切换。

| Step | 内容 | 验证标准 |
|------|------|---------|
| **10.1** ✅ | `src/agent/context.rs`：`ContextSlot` + `SlotConfig` / `SlotMode` / `FocusedConfig` / `SlotSource` / `DeriveStrategy` / `ContextBudget` / `SlotMeta` 核心类型 | `cargo build --all-targets` |
| **10.2** ✅ | ContextSlot 持久化：基于 `MemoryStore` trait（不绑定 SqliteStore）实现 save/load/list/delete + slot 命名空间 key 策略 + `load_messages()` Focused 读时过滤 + `append_messages()` Readonly 阻断 + colon 注入防护 | 单元测试：持久化 roundtrip / session 隔离 / Focused 边界 / delete 保护 / 派生 / load_messages() |
| **10.3** ✅ | `AgentSession` 扩展：`create_slot` / `switch_slot` / `list_slots` / `derive_slot` / `delete_slot` + `new()` 自动创建 `"default"` slot + `submit_turn`/`finalize_turn` 改造为基于当前 slot 的增量追加写回 + 新示例 `context_slot_demo` | 集成测试 + `cargo run --example context_slot_demo` exit 0 |

**如何保证简单场景无感**：`AgentSession::new()` 内部检查，自动创建 `"default"` slot → `submit_turn` 默认写到 default slot。

**实际新增**（2026-07-07 commit `6359422`，详见 `docs/17-phase10-contextslot.md`）：
- 方案文档：`docs/17-phase10-contextslot.md`（1227 行，含 §5 推荐方案、§6 实施建议、§9 实施计划，经过 4 轮方案/计划/实施审查 + 1 轮非阻塞建议修复）
- 新增文件 3 个：`src/agent/context.rs`（~430 行 ContextSlot 核心类型 + 持久化方法 + 22 个测试）、`src/agent/context.rs` 中的 `ContextSlot::filter_focused` 静态方法（被 `load_messages` 和 `derive_slot` 复用，消除代码重复）、`examples/context_slot_demo.rs`（~160 行分支对话示例：法律咨询 → 派生两个方向 → 切换 → 隔离验证 → 删除保护）
- 修改文件 3 个：`src/agent.rs`（+5 行 module 声明 + re-export）、`src/agent/error.rs`（+56 行：3 个新变体 `SlotReadonly`/`SlotNotFound`/`SlotAlreadyExists` + 4 个测试）、`src/agent/session.rs`（+825/-197 行：slots 字段 + 6 个管理方法 + submit_turn/finalize_turn 改造 + 17 个测试）
- 关键设计：
  - **模块归属**：`agent/context.rs`（零新依赖方向，遵循 `agent → memory` 已有依赖）
  - **持久化**：JSON blob 批次存储，每 slot 3-4 条 `MemoryItem`（`slot_data` / `slot_meta` / `slot_config` / `slot_rel`）
  - **submit_turn 签名不变**：方案 A（内部 `current_slot_id` 状态），向后兼容
  - **Focused 模式读时过滤**：`load_messages() -> Vec<Message>`，避免 Rust 借用检查问题
  - **增量追加写回**：`cycle.messages()[input_len..]` 提取本轮新增消息，确保 Focused 模式数据不丢失
  - **delete_slot 双重保护**：禁止删 `"default"` + 至少保留一个 slot
  - **colon 注入防护**：`assert_no_colon` 在 key 构造时 panic
  - **错误传播**：`serde_json` / `MemoryStore` 所有错误用 `?` 传播，无静默吞掉
- 验证：211 → 254 测试（+43 新测试），clippy 0 警告，doc 0 warning，10 + 1 示例全部 exit 0
- finalize_turn 签名变更（破坏性）：新增 `new_messages_from_cycle: Vec<Message>` 参数，返回从 `()` 改为 `Result<(), AgentError>`——影响 Phase 9 的 `submit_turn_stream_triggers_turn_hooks` 和 `submit_turn_stream_end_to_end` 2 个测试，已适配

**依赖**：Phase 5（`#[non_exhaustive]` 预置 SlotMode 等枚举）、Phase 7（SqliteStore 推荐持久化后端；`MemoryStore` trait 即可）
**优先级**：P1
**状态**：✅ Phase 10 全部交付物已完成

---

#### Phase 11: 测试与检索补强

**目标**：补全测试覆盖 + 语义检索抽象。

| Step | 内容 | 验证标准 |
|------|------|---------|
| **11.1** ✅ | `VectorRetriever` trait：`index(id, embeddings)` + `search(query, k)` | 编译 + mock 测试 |
| **11.2** ✅ | wiremock Provider roundtrip 测试：模拟 OpenAI/Anthropic HTTP 端点 | `cargo test` 新增 10+ roundtrip 测试 |
| **11.3** ✅ | 并发测试补强：InMemoryStore + SqliteStore 多线程写入验证 | 跑 100 轮无 race |

**实际新增**（2026-07-06 commit `71abe88` / `b4e5c7d`，详见 `docs/18-phase11-testing-and-retrieval.md`）：
- 方案文档：`docs/18-phase11-testing-and-retrieval.md`（647 行，含 11.1/11.2/11.3 设计 + 10 项架构决策 + 实施后补充 2 条偏差记录 #6 mid-stream mock 模式 + #7 429 retry-after 修复）
- 新增文件 1 个：`src/memory/vector.rs`（237 行 — `VectorRetriever` trait + `InMemoryVectorRetriever` 引用实现 + `dot()` 零依赖 + 6 个内联测试）
- 修改文件 5 个：
  - `src/memory.rs`（+2 行：module 声明 + re-export）
  - `src/llm/provider/openai.rs`（+8 wiremock 测试 + `handle_error_response` 429 retry-after 解析修复 5 行）
  - `src/llm/provider/anthropic.rs`（+4 wiremock 测试）
  - `src/memory/store/in_memory.rs`（+3 并发测试：100 并发写、5 写+5 读混合、15 写者容量淘汰）
  - `src/memory/store/sqlite_store.rs`（+2 并发测试：100 并发写、5 写+5 读混合）
- 关键设计：
  - **零依赖 dot()**：手写点积/范数，零新增 crate 依赖
  - **Wiremock 测试自包含**：每个测试独立 `MockServer::start()`，沿用现有模式
  - **429 retry-after 修复**：`openai.rs` 与 `anthropic.rs` 行为对齐（5 行代码）
  - **偏差记录**：方案文档「已否决的方案 #6/#7」记录两处实施偏差，便于后续审计追溯
- 验证：254 → 277 测试（+23 个新测试），clippy 0 警告，doc 0 warning；并发测试连续 3 次运行稳定无 flaky
- **依赖**：无（与方案一致）
- **状态**：✅ Phase 11 全部交付物已完成

---

#### Phase 12: P2 锦上添花（可选）

**目标**：时间允许时按优先级交付。

| 优先级 | 功能 | 实现量估计 | 备注 |
|--------|------|-----------|------|
| **12.1** | 文件系统 MemoryStore（JSON/JSONL） | ~80 行 | 最简单，适合练手 |
| **12.2** | MCP StreamableHttp 传输 | ~150 行 | 协议还在演进 |
| **12.3** | Gemini Provider | ~300 行 | 协议差异大，建议推迟到 v0.3 |

**依赖**：无（独立交付）

---

### v0.2.0 Phase 依赖关系图

```mermaid
graph BT
    P5["<b>Phase 5: 热身准备</b><br/>ProviderConfig::from_env<br/>Ollama Provider<br/>#[non_exhaustive] 标记"]:::done
    P6["<b>Phase 6: ToolDef IR</b><br/>Provider 无关工具定义"]:::done
    P7["<b>Phase 7: SqliteStore</b><br/>rusqlite + WAL<br/>9 个内联测试<br/>持久化 round-trip"]:::done
    P8["<b>Phase 8: MVP 出口</b><br/>rc.1 标签<br/>14 枚举 #[non_exhaustive]<br/>StepStatus IR 迁移<br/>quick_start + end_to_end"]:::done
    P9["<b>Phase 9: 流式体验增强</b><br/>submit_turn_stream<br/>submit_with_tools_stream<br/>9 单元测试 + 2 集成测试"]:::done
    P10["<b>Phase 10: ContextSlot</b><br/>ContextSlot 类型<br/>JSON blob 持久化<br/>AgentSession 集成<br/>43 个新测试"]:::done
    P11["<b>Phase 11: 测试与检索补强</b><br/>VectorRetriever trait<br/>12 wiremock tests<br/>5 并发测试"]:::done
    P12["Phase 12<br/>P2 锦上添花"]:::p2

    P8 --> P5
    P8 --> P6
    P8 --> P7

    P9 --> P6

    P10 --> P7
    P10 --> P8

    P11 -.-> P7

    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
    classDef warmup fill:#e2e8f0,stroke:#94a3b8
    classDef core fill:#fbbf24,stroke:#d97706
    classDef mvp fill:#4ade80,stroke:#16a34a
    classDef p1 fill:#93c5fd,stroke:#2563eb
    classDef p2 fill:#c4b5fd,stroke:#7c3aed
```

---

### 关键里程碑

| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 |
|--------|---------------|-----------|------|
| **M1** | Phase 5 | 热身三项完成：`from_env()` 可用 / Ollama 类型存在 / `#[non_exhaustive]` 就位 | ✅ 2026-07-05 |
| **M2** | Phase 6 | `ToolDef` 全量切换，`cargo test --all-targets` 全绿 | ✅ 2026-07-05 |
| **M3** | Phase 7 | SqliteStore CRUD + 并发测试通过，进程重启数据不丢 | ✅ 2026-07-05 |
| **M4** | **Phase 8 (rc.1)** | P0 五项全部交付，`cargo run --example quick_start` 跑通 | ✅ 2026-07-05 |
| **M5** | Phase 9 | `submit_turn_stream` 流式事件序列验证通过 | ✅ 2026-07-06 |
| **M6** | Phase 10 | ContextSlot 创建/切换/派生集成测试通过 | ✅ 2026-07-07 |
| **M7** | Phase 11 | wiremock + 并发测试补强，测试总量 200+ | ✅ 2026-07-06 |
| **M8** | Phase 12（可选） | P2 功能按需交付 | ⏳ |

---

## v0.3.0 — 多 Agent 基础系统（Multi-Agent Foundation）

**目标**：从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。补齐 LangChain 7 大组件中缺失的 Document 和 VectorStore 能力，落地笔记设计中的 ContextSlot fork/merge、摘要自动生成、知识图谱，建立 engine 引擎层（会话树 + time-travel Checkpointer + SubAgent Dispatch + Agent Switch），为即将开发的多 Agent 产品提供完整基础。

**总体规模**：7 个增量 Phase（Phase 13-19），总新增代码约 2600 行，测试从 277 → 380+。

### 功能清单

#### P0 — 必须交付

| # | 功能 | 模块 | 方案要点 |
|---|------|------|---------|
| 1 | 技术债清理（旧 types 文件） | `llm/types` | `request.rs` / `response.rs` / `old_stream.rs` 三个 Phase 0 旧文件删除；内部类型移入 `provider/openai.rs` |
| 2 | ContextSlot fork/merge | `agent/context` | `fork(child_id, strategy)` 别名 + `merge(child, MergeStrategy)` 三种策略（Append/Replace/Summarize） |
| 3 | Document 系统 | `document/`（新模块） | `Document` 核心类型 + `RecursiveCharacterSplitter`（递归字符分割，支持 chunk_size/chunk_overlap/separators） |
| 4 | Embedding 抽象 | `llm/embedding` | `Embedding` trait（`embed` / `dim`）+ `MockEmbedding` 测试实现 |
| 5 | 向量存储持久化 | `vector/`（新模块） | `VectorStore` trait + `InMemoryVectorStore`（读写）+ `PersistentVectorStore`（SqliteStore 后端）+ `RagPipeline` 组合器 |
| 6 | 摘要自动生成 | `agent` / `llm/hooks` | `SummaryConfig` 配置 + `OnTurnEnd` Hook 自动检测 token 水位 → 调 LLM 生成摘要 → `SessionMemory::set("conversation_summary", ...)` |
| 7 | SessionManager + 会话树 | `engine/`（新模块） | Session 工厂（`create`/`create_child`）+ 按 ID 恢复（`get`）+ 子树管理（`children`/`parent`/`destroy_subtree`）+ 元数据持久化（MemoryStore） |
| 8 | Time-travel Checkpointer | `engine/checkpointer` | `checkpoint(session)` 全量序列化 + `rollback(session_id, ckpt_id)` 回滚 + `fork(session_id, ckpt_id, new_id)` 分支 + `list_checkpoints` |
| 9 | Agent Switch | `engine/switch` | 热切换 `session.agent`（替换 `Arc<dyn Agent>`），slot 历史 / turn_index / session_memory 全保留 |
| 10 | SubAgent Dispatch | `engine/sub_agent` | `dispatch(parent, sub_agent, task, config)` 单任务 + `dispatch_all(parent, tasks, config)` 并行派发（Semaphore 并发控制）+ 子 SessionMemory 继承 + `SubTaskResult` 结构化回传 |
| 11 | 知识图谱 | `memory/graph` | `KnowledgeGraph` trait（`add_entity` / `add_relation` / `get_related` / `find_by_keywords`）+ `InMemoryGraph` 实现 + `tag_index` 标签管理 |
| 12 | 双通道检索 | `memory/retriever` | `MemoryRetriever` 扩展为双通道（`KnowledgeStore` + `KnowledgeGraph`）+ `RetrievalStrategy::Hybrid` |

### 实施计划 — 7 个增量 Phase

> **编号说明**：Phase 13-19 接续 v0.2 的 Phase 5-12，按开发顺序排列。

#### Phase 13: 热身清理 + ContextSlot fork/merge

**目标**：清除 Phase 0 遗留的旧 types 文件，交付超低价功能建立节奏。

| Step | 内容 | 文件范围 | 验证标准 |
|------|------|---------|---------|
| **13.1** | `OpenaiChatRequest` 移入 `provider/openai.rs`，`types/request.rs` 删除 | `llm/types/request.rs` + `llm/provider/openai.rs` | `cargo build --all-targets` |
| **13.2** | `OpenaiChatResponse/Chunk` 移入 `provider/openai.rs`，`types/response.rs` 删除 | `llm/types/response.rs` + `llm/provider/openai.rs` | `cargo build --all-targets` |
| **13.3** | `old_stream.rs` 删除 + `types/mod.rs` 中 `ChatResponse` 删除 | `llm/types/old_stream.rs` + `llm/types/mod.rs` | `cargo build` + 确认 3 个旧文件不存在 |
| **13.4** | `ToolChoice` 从 `request.rs` 搬到 `tool.rs` | `llm/types/tool.rs` + `llm/types/request_v2.rs` | `cargo test --all-targets` 全绿 |
| **13.5** | `ContextSlot::fork(child_id, strategy)` 别名 + `merge(child, MergeStrategy)` | `agent/context.rs` | 单元测试：fork → 子 slot 消息 = 父 slot 副本；merge(Append) → 消息按序追加 |

**依赖**：无
**优先级**：P0
**预估规模**：约 200 行
**状态**：✅ Phase 13 全部交付物已完成（2026-07-08）

---

#### Phase 14: Document 系统 + Embedding 抽象

**目标**：补齐 LangChain 7 大组件中最明显的缺口——Document 类型和分割器。不搞 Loader 框架，用户用 `fs::read_to_string` 自行加载。

**交付物**：
1. `src/document/` 新模块（`Document` 类型 + `RecursiveCharacterSplitter`）
2. `src/llm/embedding.rs`（`Embedding` trait + `MockEmbedding`）

**设计要点**：
- `Document`：id / content / metadata（HashMap）/ mime_type
- `RecursiveCharacterSplitter`：chunk_size（默认 1000）/ chunk_overlap（默认 200）/ separators（`["\n\n", "\n", ".", " ", ""]`）
- 递归分割算法：优先按 `\n\n` 切，不行按 `\n`，再不行按 `.`，最后按字符级
- `Embedding` trait：`async fn embed(&self, input: &[String]) -> Result<Vec<Vec<f32>>>` + `fn dim()`
- 不引入 `DocumentLoader` trait（应用层职责）

**依赖**：无（纯数据结构，零依赖）
**优先级**：P0
**预估规模**：约 350 行
**状态**：⏳ 待实施

---

#### Phase 15: 向量存储持久化（SqliteStore 后端）

**目标**：实现 VectorStore 持久化，让语义检索支持进程重启后数据恢复。

**设计决策**：不用 pgvector。基于已有 SqliteStore（`rusqlite`）做持久化包装——运行时全量加载到 InMemory 索引做余弦搜索，写时同步到 SqliteStore。

**交付物**：
1. `src/vector/` 新模块：`VectorStore` trait + `InMemoryVectorStore` + `PersistentVectorStore` + `RagPipeline`
2. `VectorStore` trait：`add(docs, embeddings)` / `search(query, k)` / `remove(ids)`
3. `PersistentVectorStore`：构造时从 SqliteStore 加载已有索引；`add` 双向写入；`search` 纯内存搜索
4. `RagPipeline`：组合器封装 `split` → `embed` → `store.add` 的 ingest 流程，以及 `embed` → `store.search` 的 retrieve 流程
5. SqliteStore 存储格式：`vec:{namespace}:{doc_id}` → JSON `{doc_id, content, metadata, embedding}`

**依赖**：Phase 14（Document 类型）
**优先级**：P0
**预估规模**：约 400 行
**状态**：⏳ 待实施

---

#### Phase 16: 摘要自动生成

**目标**：闭环长对话能力。v0.2 的 `inject_summary` 消费端（`FocusedConfig.summary_override`）已就绪，缺的是生产端。

**交付物**：
1. `SummaryConfig` 结构体：`enabled` / `trigger_token_ratio`（默认 0.75）/ `summary_prompt`（可自定义）
2. 在 `OnTurnEnd` Hook 中插检查点：检测 token 水位超过 `trigger_token_ratio` → 调 LLM 生成摘要 → `SessionMemory::set("conversation_summary", summary)`
3. `AgentBuilder` 扩展：`.summary_config(cfg)` 方法

**为什么放 Hook 而非内置**：可插拔，默认不启用，用户 opt-in。不改变现有 `submit_turn` 行为。

**依赖**：无（Hook 系统 + SessionMemory 已就绪）
**优先级**：P0
**预估规模**：约 150 行
**状态**：⏳ 待实施

---

#### Phase 17: Agent 执行引擎（会话树 + Time-travel Checkpointer）

**目标**：建立 `engine/` 模块。解决 v0.2 中"session 在变量里、无法通过 ID 恢复、不支持父子关系"的空白。

**交付物**：
1. `src/engine/` 新模块（`session_manager.rs` + `checkpointer.rs` + `error.rs`）
2. `SessionManager`：
   - `create(agent, bundle) -> session_id` — 创建根 session
   - `create_child(parent_id, child_id, agent)` — 创建子 session（继承父 `RuntimeBundle`）
   - `get(session_id) -> Arc<Mutex<AgentSession>>` — 按 ID 查找（支持从持久化恢复）
   - `children(parent_id)` / `parent(child_id)` — 树形查询
   - `destroy(id)` / `destroy_subtree(id)` — 生命周期管理
   - `tree() -> SessionTreeSnapshot` — 树结构快照
3. `Checkpointer`：
   - `checkpoint(session)` — 每个 `submit_turn` 末尾自动保存全量状态快照
   - `rollback(session_id, ckpt_id)` — 回滚到任意历史 checkpoint
   - `fork(session_id, ckpt_id, new_id)` — 从历史 checkpoint 分支出新 session
   - `list_checkpoints(session_id)` — 列出 checkpoint 列表
4. `AgentSession` 新增 `Serialize + Deserialize` 以支持 checkpoint 序列化

**Checkpoint 存储格式**：`checkpoint:{session_id}:{ckpt_id}` → JSON（完整 AgentSession，含所有 slot 消息列表）。Ponytail：全量 JSON 够用，等遇到存储效率问题时再改增量模式。

**会话树持久化**：`session_meta:{session_id}` → `{agent_name, parent_id, created_at, turn_count}`；`session_rel:{child_id}` → `"parent_id"`

**依赖**：Phase 10（ContextSlot 持久化 — 消息由 slot 自己管，Checkpointer 管执行状态）
**优先级**：P0
**预估规模**：约 600 行
**状态**：⏳ 待实施

---

#### Phase 18: Agent Switch + SubAgent Dispatch + Agent 间交互

**目标**：在 SessionManager 基础上，提供 Agent 角色热切换和子代理调度能力。

**交付物**：
1. `engine/switch.rs` — `switch_agent(session_id, new_agent)`：替换 `Arc<dyn Agent>`，slot 历史 / turn_index / session_memory 全保留
2. `engine/sub_agent.rs` — SubAgent Dispatch 核心：
   - `DispatchConfig`：`max_concurrency`（默认 10）/ `inherit_session_memory`（默认 true）/ `bridge_keys`
   - `dispatch(parent_id, sub_agent, task, config) -> SubTaskResult`：创建子 session → 继承父 SessionMemory → `submit_turn` → 返回结构化结果
   - `dispatch_stream(parent_id, sub_agent, task, config) -> SubTaskStream`：流式版
   - `dispatch_all(parent_id, tasks, config) -> Vec<SubTaskResult>`：并行派发，`tokio::sync::Semaphore` 控制并发数
3. `SubTaskResult`：`child_id` / `response` / `usage` / `summary` + `child_memory(sm)` 读取子 SessionMemory

**Agent 间交互三层级**：
- 父→子：继承 SessionMemory 快照 + `bridge_keys` 指定 key 强制注入 system prompt
- 子→父：`SubTaskResult` 结构化回传 + `SessionMemory["result_summary"]` 结论摘要
- 子↔子（间接）：通过公共 `MemoryStore` namespace（`shared:{parent_session_id}`）共享数据

**依赖**：Phase 17（SessionManager + 会话树）
**优先级**：P0
**预估规模**：约 500 行
**状态**：⏳ 待实施

---

#### Phase 19: 知识图谱 + 双通道检索

**目标**：落地 `docs/note-knowledge-graph-design.md` 中记录的知识图谱设计，提供实体-关系图检索能力。扩展 `MemoryRetriever` 为双通道。

**交付物**：
1. `src/memory/graph.rs`（新文件）：
   - `GraphEntity` / `GraphRelation` / `ScoredEntity` 核心类型
   - `RelationDirection` 枚举（Outgoing / Incoming / Both）
   - `KnowledgeGraph` trait：`add_entity` / `get_entity` / `remove_entity` / `add_relation` / `remove_relation` / `get_related` / `find_by_keywords` / `find_tags` / `set_entity_tags`
   - `InMemoryGraph` 实现：`HashMap<String, GraphEntity>` + `Vec<GraphRelation>` + BFS 图遍历
   - `TagConstraints`（`max_tags_per_entity` 默认 8）
2. `src/memory/retriever.rs` 扩展：
   - `MemoryRetriever` 增加 `knowledge_graph` 可选字段
   - `RetrievalStrategy` 枚举：`Hybrid`（默认）/ `KnowledgeOnly` / `GraphOnly`

**与 Document 系统的关系**：知识图谱提供实体级检索（"这个实体和什么相关"），VectorStore 提供语义相似度检索（"哪些文档最相似"），两者互补。

**依赖**：MemoryStore 持久化（v0.1 Phase 3）
**优先级**：P0
**预估规模**：约 400 行
**状态**：⏳ 待实施

---

### v0.3.0 Phase 依赖关系图

```mermaid
graph BT
    P13["<b>Phase 13: 热身清理</b><br/>旧 types 文件删除<br/>ContextSlot fork/merge"]:::done
    P14["<b>Phase 14: Document + Embedding</b><br/>Document 类型<br/>RecursiveCharacterSplitter<br/>Embedding trait"]:::pending
    P15["<b>Phase 15: 向量存储持久化</b><br/>VectorStore trait<br/>PersistentVectorStore<br/>RagPipeline"]:::pending
    P16["<b>Phase 16: 摘要自动生成</b><br/>SummaryConfig<br/>OnTurnEnd Hook"]:::pending
    P17["<b>Phase 17: 执行引擎</b><br/>SessionManager<br/>会话树<br/>Time-travel Checkpointer"]:::pending
    P18["<b>Phase 18: 切换与调度</b><br/>Agent Switch<br/>SubAgent Dispatch<br/>dispatch_all 并发控制"]:::pending
    P19["<b>Phase 19: 知识图谱</b><br/>KnowledgeGraph trait<br/>InMemoryGraph<br/>双通道检索"]:::pending

    P15 --> P14
    P18 --> P17

    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
    classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
```

### 关键里程碑

| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 |
|--------|---------------|-----------|------|
| **M9** | Phase 13 | 旧 types 文件删除、`cargo test --all-targets` 全绿、`fork`/`merge` 测试通过 | ✅ 2026-07-08 |
| **M10** | Phase 14 | `Document` + `RecursiveCharacterSplitter` 分割结果验证、`MockEmbedding` 测试通过 | ⏳ |
| **M11** | Phase 15 | `PersistentVectorStore` 持久化 roundtrip、`RagPipeline::ingest → retrieve` 端到端验证 | ⏳ |
| **M12** | Phase 16 | 多轮对话后摘要自动写入 SessionMemory、派生 slot 时摘要正确注入 | ⏳ |
| **M13** | **Phase 17 (rc.1)** | `SessionManager` 创建/子树/恢复集成测试通过、`Checkpointer` checkpoint/rollback/fork 验证 | ⏳ |
| **M14** | Phase 18 | `switch_agent` 热切换验证、`dispatch`/`dispatch_all` 多轮对话 + 结果回传验证 | ⏳ |
| **M15** | Phase 19 | `KnowledgeGraph` 实体-关系 CRUD + `get_related` BFS 验证、双通道检索 Hybrid 策略验证 | ⏳ |

---

## v0.4+ 展望

### 已规划的功能

| 功能 | 说明 | 预计版本 |
|------|------|---------|
| Multi-Agent Swarm 编排 | Supervisor/Subgraph 模式，基于 v0.3 dispatch 构建 | v0.4 |
| Human-in-the-loop 审批 | `interrupt()` + `Command(resume=...)` 异步审批回调 | v0.4 |
| Agent 自动创生 | LLM 自主决定何时派发子 agent、派发什么角色 | v0.4 |
| 分布式 session 共享 | SessionManager Redis 后端支持跨进程 | v0.4 |
| 精确 tokenizer 计数 | 引入 `tiktoken-rs`，绑定模型具体 tokenizer，替换字符估算 | v0.4+ |
| TokenJuice 语义压缩 | 对工具结果做语义压缩而非字节截断 | v0.4+ |
| Markdown 技能按需加载 | 技能注册表 + 按 prompt 上下文动态加载 | v0.4+ |
| 增量 checkpoint | 仅存储变化部分，替换当前全量 JSON 模式 | v0.4+ |
| RL 轨迹导出 | ShareGPT 格式轨迹、Atropos 集成 | v0.4+ |

### 明确不做（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 新增 `engine/` `vector/` `document/` 三个模块，功能覆盖扩展到多 Agent 基础系统。始终保持 trait + reference impl 的边界，业务循环留给上层
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.3.0 Phase 14 启动**：Document 系统（`Document` 类型 + `RecursiveCharacterSplitter` + `Embedding` trait），按物理文件切割逐步推进
2. **Phase 14-19 顺次交付**：按依赖关系推进 Document → 向量存储 → 摘要 → 引擎 → 调度 → 知识图谱
3. **示例先行**：每完成一个 Phase 立即创建/更新对应示例，确保 `cargo run --example` 可验证
4. **里程碑追踪**：以 M9（Phase 13）为 v0.3 第一个里程碑，逐 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]` 为 Phase 16 `Summarize` 预留）；`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 里程碑达成；Phase 14-19 共 6 个增量 Phase 待实施（Document → 向量存储 → 摘要 → 引擎 → 调度 → 知识图谱）

---

## v0.1 发布里程碑（2026-07-04）

**质量基线**：

| 指标 | 数值 |
|------|------|
| `cargo build --all-targets` | ✅ 通过 |
| `cargo test --all-targets` | ✅ **182 passed / 0 failed** |
| `cargo clippy --all-targets -- -D warnings` | ✅ 0 警告 |
| 离线示例（`cargo run --example`） | ✅ 7 个全部 exit 0 |

**关键交付**：
1. **Provider IR 重构** — 统一 `Message` / `ContentBlock` / `MessageRequest` / `MessageResponse` 类型层；4 个 Provider 适配（OpenAI Chat / Anthropic Messages / DeepSeek / Qwen）；`LlmProvider` trait 签名同步切换
2. **LlmCycle 简化** — `LlmCycle` 内部消息类型切到 IR 层；移除 Phase 0 的 `OpenaiChatMessage ↔ Message` 桥接；测试从 116 → 182（含 provider 测试）
3. **`MockProvider` 公开化** — `agcore::llm::mock::MockProvider` 支持 `chat` + `chat_stream`，无需 API key 即可运行示例
4. **7 个离线示例** — `prompt_composer` / `custom_tool` / `agent_session_demo` / `task_agent_demo` / `conversation_memory_demo` / `knowledge_search_demo` / `streaming_events_demo`
5. **错误消息友好化** — `AgentError` / `LlmError` / `ToolError` / `MemoryError` / `PromptError` 全部面向最终用户改写（给出可操作的建议）
6. **文档完整** — README 完整版（快速上手 + 架构图 + 环境变量）、Apache-2.0 LICENSE