docs(roadmap): 标记 Phase 17 完成 + M13 里程碑达成 + 更新依赖图

Phase 17 全部交付物已完成（2026-07-15）：
- 状态从 ⏳ 改为 ✅
- 增补实际增量（5 新增文件 + 5 修改 + 1 示例 = 1848 行净增）
- 列出 21 个新内联测试（Checkpointer 6 + SessionManager 15）
- 列举关键设计决策落地（SessionSnapshot 独立 / to_snapshot+from_snapshot+restore_memory
  三段式 / EngineError::Memory 透传 / RwLock 锁契约 / ckpt_id 纳秒+计数器 / 孤儿策略等）
- 记录实施后两轮审查门禁 PASS（第一轮 PM+SA 修复 6 🔴，第二轮 SA 修复 2 🔴，
  实施后 PM+SA+Code Reviewer 联合修复 8 个 🟡）

M13 里程碑达成 ✅ 2026-07-15（依赖图节点从 pending 改为 done）

Phase 17 rc.1 完成 → 下一步 Phase 18（Agent Switch + SubAgent Dispatch）
- 「下一步行动」重定向到 Phase 18
- 「里程碑追踪」更新为 M12+M13 已达成，剩余 M14-M15
- 已完成阶段列表追加 Phase 17 完成项（详细列出 11 个 SessionManager API +
  5 个 Checkpointer API + 关键实现细节 + 审查修复记录）

docs/roadmap.md

@@ -799,7 +799,34 @@ graph BT
 **依赖**：Phase 10（ContextSlot 持久化 — 消息由 slot 自己管，Checkpointer 管执行状态）
 **优先级**：P0
 **预估规模**：约 700 行（5 新增文件 + 5 修改文件）
-**状态**：⏳ 方案已通过审查，待实施
+**状态**：✅ Phase 17 全部交付物已完成
+
+---
+
+**实际新增**（2026-07-15，3 commits + 实施审查修复一轮）：
+
+- **新增 5 文件（`src/engine/`）**：`mod.rs`（19 行）+ `error.rs`（43 行）+ `snapshot.rs`（35 行）+ `checkpointer.rs`（373 行）+ `session_manager.rs`（910 行含测试）
+- **修改 5 文件**：
+  - `src/llm/types/usage.rs` — `CostTracker` 加 `Clone, Serialize, Deserialize`（3 行）
+  - `src/agent/context.rs` — `ContextSlot` + `MergeStrategy` 加 `Serialize, Deserialize`（4 行）
+  - `src/agent/session_memory.rs` — 新增 `list_entries()` + `set_with_meta()` 方法
+  - `src/agent/session.rs` — 新增 `to_snapshot()` (async) / `from_snapshot()` (sync) / `restore_memory()` (&mut self, async) / `has_pending_memory_restore()` + 公开 `bundle()` accessor
+  - `src/lib.rs` — `pub mod engine`
+- **新增 1 示例**：`examples/engine_demo.rs`（~210 行，端到端演示 create → submit_turn → checkpoint → list → rollback_load → from_snapshot → restore_memory → replace → destroy 全链路，含 rollback 一致性 assert）
+- **依赖**：零新外部依赖（ponytail：ckpt_id 用纳秒+计数器生成，session_id 同理）
+- **测试**：353 → **374**（+21 引擎内联测试：Checkpointer 6 个 + SessionManager 15 个）
+- **质量基线**：`cargo test --all-targets` 374 passed / 0 failed；`cargo clippy --all-targets -- -D warnings` 0 警告；`cargo doc --no-deps` 0 warning；`cargo run --example engine_demo` exit 0
+- **关键设计决策落地**：
+  - `SessionSnapshot` 独立 struct（避开 `Arc<dyn Agent>` 不可序列化）
+  - `to_snapshot` async + `from_snapshot` 纯同步 + `restore_memory` async 三段式分离
+  - `session_memory_data` 改用 `HashMap<String, SessionMemoryEntry>`（保留 metadata/created_at）
+  - `EngineError::Memory(#[from] MemoryError)` 透传变体
+  - `EngineManager` 锁契约：所有写操作先 HashMap 再 I/O（或反之，destroy 反向）
+  - 自动 checkpoint 失败 `tracing::error!` 不阻断主流程（不提供强持久化保证）
+  - ckpt_id 时间戳+纳秒+计数器无外部依赖（`created_at_nanos` 字段确保同秒内精确排序）
+  - 孤儿策略：`destroy()` 不递归删除子 session；父被销毁后 `parent()` 返回 `Ok(None)`
+- **实施审查通过**：经过 PM + SA + Code Reviewer 三方联合审查 → 1 轮修复 → 全部 🟡 警告关闭
+- **M13 里程碑达成** — Phase 17 rc.1 标签可打（v0.3.0 第二个 Phase）
 
 ---
 
@@ -860,7 +887,7 @@ graph BT
     P14["<b>Phase 14: Document + Embedding</b><br/>Document 类型<br/>RecursiveCharacterSplitter<br/>Embedding trait"]:::done
     P15["<b>Phase 15: 向量存储持久化</b><br/>VectorStore trait<br/>PersistentVectorStore<br/>RagPipeline<br/>19 新测试"]:::done
     P16["<b>Phase 16: 摘要自动生成</b><br/>SummaryConfig<br/>内联检查点<br/>首次防抖跳过<br/>18 新测试"]:::done
-    P17["<b>Phase 17: 执行引擎</b><br/>SessionManager<br/>会话树<br/>Time-travel Checkpointer"]:::pending
+    P17["<b>Phase 17: 执行引擎</b><br/>SessionManager<br/>会话树<br/>Time-travel Checkpointer<br/>21 新测试"]:::done
     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
 
@@ -879,7 +906,7 @@ graph BT
 | **M10** | Phase 14 | `Document` + `RecursiveCharacterSplitter` 分割结果验证、`MockEmbedding` 测试通过 | ✅ 2026-07-09 |
 | **M11** | Phase 15 | `PersistentVectorStore` 持久化 roundtrip、`RagPipeline::ingest → retrieve` 端到端验证 | ✅ 2026-07-09 |
 | **M12** | Phase 16 | 多轮对话后摘要自动写入 SessionMemory、派生 slot 时摘要正确注入 + 第二轮实施审查 PASS | ✅ 2026-07-10 |
-| **M13** | **Phase 17 (rc.1)** | `SessionManager` 创建/recover/replace/子树/销毁集成测试通过、`Checkpointer` checkpoint/rollback/list_checkpoints 验证（`fork` 推迟至 Phase 18）| ⏳ |
+| **M13** | **Phase 17 (rc.1)** | `SessionManager` 创建/recover/replace/子树/销毁集成测试通过、`Checkpointer` checkpoint/rollback/list_checkpoints 验证（`fork` 推迟至 Phase 18）| ✅ 2026-07-15 |
 | **M14** | Phase 18 | `switch_agent` 热切换验证、`dispatch`/`dispatch_all` 多轮对话 + 结果回传验证 | ⏳ |
 | **M15** | Phase 19 | `KnowledgeGraph` 实体-关系 CRUD + `get_related` BFS 验证、双通道检索 Hybrid 策略验证 | ⏳ |
 
@@ -924,10 +951,10 @@ graph BT
 
 ## 下一步行动
 
-1. **v0.3.0 Phase 17 启动**：Agent 执行引擎（`SessionManager` 会话树 + `Checkpointer` time-travel），基于 Phase 10 的 `ContextSlot` 持久化层构建
-2. **Phase 17-19 顺次交付**：按依赖关系推进引擎 → 调度 → 知识图谱
+1. **v0.3.0 Phase 18 启动**：Agent Switch + SubAgent Dispatch + Agent 间交互，基于 Phase 17 的 `SessionManager` 会话树构建
+2. **Phase 18-19 顺次交付**：按依赖关系推进调度 → 知识图谱
 3. **示例先行**：每完成一个 Phase 立即创建/更新对应示例，确保 `cargo run --example` 可验证
-4. **里程碑追踪**：以 M12（Phase 16）为已达成里程碑，逐 Phase 推进 M13-M15
+4. **里程碑追踪**：以 M12（Phase 16）+ M13（Phase 17）为已达成里程碑，逐 Phase 推进 M14-M15
 
 **已完成 / 进行中阶段**：
 - ✅ Phase 0 Foundation — 全部交付物已完成
@@ -952,7 +979,8 @@ graph BT
 - ✅ **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；Phase 17-19 共 3 个增量 Phase 待实施（引擎 → 调度 → 知识图谱）
+- ✅ **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；Phase 18-19 共 2 个增量 Phase 待实施（调度 → 知识图谱）
 
 ---