docs(roadmap): 标记 Phase 10 ContextSlot 上下文管理已完成
- 顶部状态行更新：Phase 0-10 全部完成，11 个离线示例，254 测试 - Phase 10 状态：Step 10.1/10.2/10.3 全部标记 ✅ - 详细实际新增：agent/context.rs (~430 行) + agent/error.rs 3 个变体 + agent/session.rs 改造（slots 字段 + 5 个管理方法 + submit_turn/finalize_turn 增量追加写回） + context_slot_demo 示例 + 43 个新测试 - finalize_turn 签名变更记录（new_messages_from_cycle 参数 + Result 返回） - 依赖关系图 P10 节点标 ✅ - 里程碑 M6 → ✅ 2026-07-07 - 下一步行动：Phase 10 → Phase 11（测试与检索补强） - 已完成阶段列表追加 Phase 10 完整说明 - 最后更新日期：2026-07-06 → 2026-07-07
This commit is contained in:
徐涛
+29
-11
@@ -1,13 +1,13 @@
|
||||
# AG Core Roadmap
|
||||
|
||||
> 定稿日期：2026-05-11
|
||||
> 最后更新：2026-07-06
|
||||
> 最后更新：2026-07-07
|
||||
|
||||
## 愿景
|
||||
|
||||
AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
|
||||
|
||||
**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-9 全部完成，v0.2.0-rc.1 已打标签。Provider IR 重构 + LlmCycle 简化 + 10 个离线示例（含 `quick_start` 30 行最小示例与 `end_to_end` 完整集成示例）+ SqliteStore 持久化 + 14 个公开枚举 `#[non_exhaustive]` 护栏 + `StepStatus` IR 迁移 + `submit_turn_stream` 流式体验已交付。下一步进入 Phase 10（ContextSlot 上下文管理）。
|
||||
**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-10 全部完成，v0.2.0-rc.1 已打标签。Provider IR 重构 + LlmCycle 简化 + 11 个离线示例（含 `quick_start` 30 行最小示例、`end_to_end` 完整集成示例、`context_slot_demo` 分支对话示例）+ SqliteStore 持久化 + 14 个公开枚举 `#[non_exhaustive]` 护栏 + `StepStatus` IR 迁移 + `submit_turn_stream` 流式体验 + ContextSlot 多上下文分区管理已交付。下一步进入 Phase 11（测试与检索补强）。
|
||||
|
||||
---
|
||||
|
||||
@@ -485,14 +485,31 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve }
|
||||
|
||||
| Step | 内容 | 验证标准 |
|
||||
|------|------|---------|
|
||||
| **10.1** | `src/llm/context.rs`：`ContextSlot` + `SlotConfig` / `SlotMode` / `SlotSource` / `ContextBudget` 核心类型 | `cargo build` |
|
||||
| **10.2** | ContextSlot 持久化：基于 `MemoryStore` trait（不绑定 SqliteStore）实现 save/load/list + slot 命名空间 key 策略 | 单元测试：slot 创建/写入/读取/隔离（不串数据） |
|
||||
| **10.3** | `AgentSession` 扩展：`create_slot` / `switch_slot` / `list_slots` / `derive_slot` + `AgentBuilder` 默认创建 `"default"` slot | 集成测试 + 新示例 `context_slot_demo` |
|
||||
| **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 |
|
||||
|
||||
**如何保证简单场景无感**：`AgentBuilder::build()` 内部检查，如果用户没手动 `create_slot`，自动创建 `"default"` slot → `submit_turn` 默认写到 default slot。
|
||||
**如何保证简单场景无感**：`AgentSession::new()` 内部检查，自动创建 `"default"` slot → `submit_turn` 默认写到 default slot。
|
||||
|
||||
**依赖**：Phase 7（SqliteStore 作为推荐持久化后端；`MemoryStore` trait 即可）
|
||||
**实际新增**（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 全部交付物已完成
|
||||
|
||||
---
|
||||
|
||||
@@ -534,7 +551,7 @@ graph BT
|
||||
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["Phase 10<br/>ContextSlot"]:::p1
|
||||
P10["<b>Phase 10: ContextSlot</b><br/>ContextSlot 类型<br/>JSON blob 持久化<br/>AgentSession 集成<br/>43 个新测试"]:::done
|
||||
P11["Phase 11<br/>测试与检索"]:::p1
|
||||
P12["Phase 12<br/>P2 锦上添花"]:::p2
|
||||
|
||||
@@ -568,7 +585,7 @@ graph BT
|
||||
| **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 创建/切换/派生集成测试通过 | ⏳ |
|
||||
| **M6** | Phase 10 | ContextSlot 创建/切换/派生集成测试通过 | ✅ 2026-07-07 |
|
||||
| **M7** | Phase 11 | wiremock + 并发测试补强，测试总量 200+ | ⏳ |
|
||||
| **M8** | Phase 12（可选） | P2 功能按需交付 | ⏳ |
|
||||
|
||||
@@ -613,9 +630,9 @@ graph BT
|
||||
|
||||
## 下一步行动
|
||||
|
||||
1. **Phase 10 启动**：ContextSlot 上下文管理（`src/llm/context.rs` 多上下文分区 + slot 切换/派生），P1 功能
|
||||
1. **Phase 11 启动**：测试与检索补强（`VectorRetriever` trait + wiremock Provider roundtrip + 并发写入验证），P1 功能
|
||||
2. **示例先行**：每完成一个 Phase 立即更新对应示例，验证通过后再合入
|
||||
3. **里程碑追踪**：以 Phase 9（流式体验，已完成）为最新节点，逐 Phase 验收
|
||||
3. **里程碑追踪**：以 Phase 10（ContextSlot，已完成）为最新节点，逐 Phase 验收
|
||||
4. **v0.2.0 正式版**：Phase 8-11 全部完成后，去掉 rc 后缀打 `v0.2.0` 正式版
|
||||
|
||||
**已完成 / 进行中阶段**：
|
||||
@@ -631,6 +648,7 @@ graph BT
|
||||
- ✅ 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
|
||||
- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen/Ollama 适配
|
||||
- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
|
||||
- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、8 个离线示例（含 `simple_visit`）、README + 错误消息友好化、CHANGELOG 初始化
|
||||
|
||||
Reference in New Issue
Block a user