diff --git a/docs/roadmap.md b/docs/roadmap.md index 63d142c..6aad414 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,13 +1,13 @@ # AG Core Roadmap > 定稿日期：2026-05-11 -> 最后更新：2026-07-09（Phase 14 完成 + M10 里程碑达成） +> 最后更新：2026-07-09（Phase 15 完成 + M11 里程碑达成 + Phase 16 方案推演） ## 愿景 AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。 -**当前状态**：v0.2.0-rc.1 已打标签。Phase 0-14 全部完成。v0.3.0 实施中，Phase 15-19 共 5 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。 +**当前状态**：v0.2.0-rc.1 已打标签。Phase 0-15 全部完成。v0.3.0 实施中，Phase 16-19 共 4 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。 --- @@ -712,16 +712,24 @@ graph BT **设计决策**：不用 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}` +1. 新增 `src/memory/vector_store.rs`（937 行）—— `VectorStore` trait + `InMemoryVectorStore` + `PersistentVectorStore` + `RagPipeline` +2. `VectorStore` trait：`add(&[Document], &[Vec])` 批量 / `search(query, k)` 返回 `(Document, f32)` / `remove(ids)` 幂等 +3. `PersistentVectorStore`：构造时从 `MemoryStore` 全量加载已有索引；`add` 先写持久化后写内存（持久化失败时内存不污染，重启自动恢复）；`search` 纯内存余弦搜索（快照 clone + 锁外计算） +4. `RagPipeline`：组合器封装 `split → embed → store.add`（ingest）和 `embed → store.search`（retrieve）两条管线 +5. 存储格式：`vec:{namespace}:{doc_id}` → JSON `{doc_id, content, metadata, embedding, created_at}`，通过 `MemoryStore` 通用接口读写 +6. `src/memory/vector.rs` 旧 `VectorRetriever` trait + `InMemoryVectorRetriever` 标注 `#[deprecated(since = "0.3.0")]`，迁移路径指向 `VectorStore` / `InMemoryVectorStore` -**依赖**：Phase 14（Document 类型） +**实际新增**（2026-07-09 commit `32d886f`）： +- 新增文件 1 个：`src/memory/vector_store.rs`（937 行，含 19 个内联测试） +- 修改文件 3 个：`src/memory/vector.rs`（+4 行 deprecated 标注）；`src/memory.rs`（+pub mod vector_store + 4 个 pub use re-export）；`examples/document_demo.rs`（迁移到 RagPipeline ingest+retrieve） +- 零新外部依赖（`Cargo.toml` 未修改） +- 全量测试 313 → 335（+22，Phase 15 新增 19 测试 + 部分重叠计数 22 净增）；clippy 0 警告，doc 0 warning +- 设计文档：`docs/21-phase15-vector-store-persistence.md`（1570 行，经 3 轮审查 + 文档-代码不一致修复：`search_orthogonal_vectors` 返回 1 条 score≈0 而非空列表） + +**依赖**：Phase 14（Document 类型 + Embedding trait） **优先级**：P0 -**预估规模**：约 400 行 -**状态**：⏳ 待实施 +**预估规模**：约 400 行（实际约 937 行纯实现 + 测试） +**状态**：✅ Phase 15 全部交付物已完成 --- @@ -730,16 +738,17 @@ graph BT **目标**：闭环长对话能力。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)` +1. `SummaryConfig` 结构体：`trigger_token_ratio`（默认 0.75） / `max_context_tokens`（默认 128_000） / `summary_prompt`（可自定义，含 `{messages}` 占位符） / `debounce_turns`（默认 3） / `summary_model`（默认 `Some("gpt-4o-mini")`） +2. 在 `submit_turn` / `finalize_turn` 中 OnTurnEnd 之后插入**内联检查点**（非 Hook 扩展）：`should_summarize`（水位检测 + 防抖）→ `generate_summary`（新 `LlmCycle` + `submit_messages` 无工具调用）→ 更新 `FocusedConfig.summary_override` + `slot.save()` 持久化 + `SessionMemory::set("conversation_summary", summary)` 全局快照 3. `AgentBuilder` 扩展：`.summary_config(cfg)` 方法 +4. 公开 API：`get_conversation_summary() -> Result, AgentError>` -**为什么放 Hook 而非内置**：可插拔，默认不启用，用户 opt-in。不改变现有 `submit_turn` 行为。 +**设计决策**：内联于 `submit_turn` 流程而非 Hook 扩展（因为 HookContext 无法携带 `&mut self` 引用更新 slot config，且流式路径的 `finalize_turn` 中 `cycle` 已销毁）。`Option` 的 opt-in 机制已足够提供可插拔性，不改变 Hook 系统签名。 -**依赖**：无（Hook 系统 + SessionMemory 已就绪） +**依赖**：无（`submit_turn` 流程 + `CostTracker` + `SessionMemory` + `LlmProvider` 均已就绪） **优先级**：P0 -**预估规模**：约 150 行 -**状态**：⏳ 待实施 +**预估规模**：约 220 行（含测试约 100 行） +**状态**：⏳ 待实施（方案文档已就绪：`docs/22-phase16-summary-auto-generation.md`） --- @@ -829,8 +838,8 @@ graph BT graph BT P13["Phase 13: 热身清理
旧 types 文件删除
ContextSlot fork/merge"]:::done P14["Phase 14: Document + Embedding
Document 类型
RecursiveCharacterSplitter
Embedding trait"]:::done - P15["Phase 15: 向量存储持久化
VectorStore trait
PersistentVectorStore
RagPipeline"]:::pending - P16["Phase 16: 摘要自动生成
SummaryConfig
OnTurnEnd Hook"]:::pending + P15["Phase 15: 向量存储持久化
VectorStore trait
PersistentVectorStore
RagPipeline
19 新测试"]:::done + P16["Phase 16: 摘要自动生成
SummaryConfig
内联检查点
FocusedConfig 自更新"]:::pending P17["Phase 17: 执行引擎
SessionManager
会话树
Time-travel Checkpointer"]:::pending P18["Phase 18: 切换与调度
Agent Switch
SubAgent Dispatch
dispatch_all 并发控制"]:::pending P19["Phase 19: 知识图谱
KnowledgeGraph trait
InMemoryGraph
双通道检索"]:::pending @@ -848,7 +857,7 @@ graph BT |--------|---------------|-----------|------| | **M9** | Phase 13 | 旧 types 文件删除、`cargo test --all-targets` 全绿、`fork`/`merge` 测试通过 | ✅ 2026-07-08 | | **M10** | Phase 14 | `Document` + `RecursiveCharacterSplitter` 分割结果验证、`MockEmbedding` 测试通过 | ✅ 2026-07-09 | -| **M11** | Phase 15 | `PersistentVectorStore` 持久化 roundtrip、`RagPipeline::ingest → retrieve` 端到端验证 | ⏳ | +| **M11** | Phase 15 | `PersistentVectorStore` 持久化 roundtrip、`RagPipeline::ingest → retrieve` 端到端验证 | ✅ 2026-07-09 | | **M12** | Phase 16 | 多轮对话后摘要自动写入 SessionMemory、派生 slot 时摘要正确注入 | ⏳ | | **M13** | **Phase 17 (rc.1)** | `SessionManager` 创建/子树/恢复集成测试通过、`Checkpointer` checkpoint/rollback/fork 验证 | ⏳ | | **M14** | Phase 18 | `switch_agent` 热切换验证、`dispatch`/`dispatch_all` 多轮对话 + 结果回传验证 | ⏳ | @@ -887,7 +896,7 @@ graph BT 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 的边界，业务循环留给上层 +4. **Scope 蔓延**：v0.3 新增 `agent/summary` `document/` `engine/` `memory/vector_store` 模块，功能覆盖扩展到多 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 时也会复制全量。等实际使用中发现存储瓶颈时再改为增量模式 @@ -895,10 +904,10 @@ graph BT ## 下一步行动 -1. **v0.3.0 Phase 15 启动**：向量存储持久化（`VectorStore` trait + `InMemoryVectorStore` + `PersistentVectorStore` + `RagPipeline` 组合器），基于 Phase 14 的 `Document` 类型构建 -2. **Phase 15-19 顺次交付**：按依赖关系推进向量存储 → 摘要 → 引擎 → 调度 → 知识图谱 +1. **v0.3.0 Phase 16 启动**：摘要自动生成（`SummaryConfig` 配置 + 内联检查点 + `FocusedConfig.summary_override` 自动更新 + `SessionMemory` 快照），基于已有 `CostTracker` 水位检测 +2. **Phase 16-19 顺次交付**：按依赖关系推进摘要 → 引擎 → 调度 → 知识图谱 3. **示例先行**：每完成一个 Phase 立即创建/更新对应示例，确保 `cargo run --example` 可验证 -4. **里程碑追踪**：以 M10（Phase 14）为已达成里程碑，逐 Phase 推进 M11-M15 +4. **里程碑追踪**：以 M11（Phase 15）为已达成里程碑，逐 Phase 推进 M12-M15 **已完成 / 进行中阶段**： - ✅ Phase 0 Foundation — 全部交付物已完成 @@ -921,7 +930,8 @@ graph BT - ✅ 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 里程碑达成；Phase 15-19 共 5 个增量 Phase 待实施（向量存储 → 摘要 → 引擎 → 调度 → 知识图谱） +- ✅ **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` + 余弦全量扫描 + 预计算 L2 norm 缓存）+ `PersistentVectorStore`（构造时全量加载，先写持久化后写内存，持久化失败时内存不污染重启自动恢复，`remove` 幽灵数据窗口已知）+ `RagPipeline` 组合器（ingest: split→embed→store.add / retrieve: embed→store.search，`splitter: Option` 灵活切换）；`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 里程碑达成；Phase 16-19 共 4 个增量 Phase 待实施（摘要 → 引擎 → 调度 → 知识图谱） ---