徐涛
368 lines
31 KiB
Markdown
368 lines
31 KiB
Markdown
# AG Core Roadmap — v0.3.0
|
||
|
||
> 本文件聚焦 **v0.3.0 版本** 的规划与交付（Phase 13–19）。Phase 13-19 全部完成，v0.3.0 交付完毕。
|
||
> 返回总入口：[`roadmap.md`](./roadmap.md)
|
||
|
||
## v0.3.0 愿景
|
||
|
||
从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。补齐 LangChain 7 大组件中缺失的 Document 和 VectorStore 能力，落地笔记设计中的 ContextSlot fork/merge、摘要自动生成、知识图谱，建立 engine 引擎层（会话树 + time-travel Checkpointer + SubAgent Dispatch + Agent Switch），为即将开发的多 Agent 产品提供完整基础。
|
||
|
||
## v0.3.0 总体范围
|
||
|
||
**总体规模**：7 个增量 Phase（Phase 13–19），总新增代码约 2600 行，测试从 277 → 427。7 个 Phase 全部完成（M9-M15 已达成），v0.3.0 交付完毕。
|
||
|
||
---
|
||
|
||
## 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 → 427。
|
||
|
||
### 功能清单
|
||
|
||
#### 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.rs` 新模块（`Document` 类型 + `RecursiveCharacterSplitter`）
|
||
2. `src/llm/embedding.rs`（`Embedding` trait + `MockEmbedding`）
|
||
|
||
**设计要点**：
|
||
- `Document`：id / content / metadata（HashMap<String, String>）/ mime_type
|
||
- `RecursiveCharacterSplitter`：chunk_size（默认 1000）/ chunk_overlap（默认 200）/ separators（`["\n\n", "\n", "。", "？", "！", ".", " ", ""]`，含 CJK 标点）
|
||
- 两阶段算法：按 separator 优先级递归分割（Phase 1）+ 贪心合并 + overlap 滑动窗口（Phase 2）
|
||
- 所有长度比较以 Unicode 字符数为单位（`chars_len()`），非字节数
|
||
- `Embedding` trait：`async fn embed(&self, input: &[String]) -> Result<Vec<Vec<f32>>, LlmError>` + `fn dim()`
|
||
- 复用 `LlmError` 而非新错误类型
|
||
- `MockEmbedding`：sin-hash 零依赖伪随机向量 + L2 归一化
|
||
- 不引入 `DocumentLoader` trait（应用层职责）
|
||
|
||
**实际新增**（2026-07-09 commit `d4c4d8f`，详见 `docs/20-phase14-document-and-embedding.md`）：
|
||
- 新增文件 3 个：
|
||
- `src/document.rs`（580 行）— `Document` 类型（4 字段 + `new`/`from_raw` 构造器，2 个 `new` 接受 `impl Into<String>`） + `RecursiveCharacterSplitter`（两阶段算法：按 separator 优先级递归分割 + 贪心合并 overlap，所有长度比较 `chars_len()` 字符级，overlap 提取 `chars().rev().take().rev()` 字符级安全）+ 19 个内联测试
|
||
- `src/llm/embedding.rs`（183 行）— `Embedding` trait（async + `LlmError`）+ `MockEmbedding`（sin-hash：字节和+长度做种子，`f32::sin(seed + i) * 10000`，L2 归一化到单位长度，零向量防除零）+ 6 个内联测试
|
||
- `examples/document_demo.rs`（74 行）— 端到端演示 Document → RecursiveCharacterSplitter → MockEmbedding → InMemoryVectorRetriever → search
|
||
- 修改文件 2 个：
|
||
- `src/lib.rs`（+3 行：`pub mod document` + `pub use document::Document` + 空行）
|
||
- `src/llm.rs`（+1 行：`pub mod embedding`）
|
||
- 关键设计：
|
||
- **早返回守卫**：`split_text` 在 `chars_len(text) <= self.chunk_size` 时直接返回 `[text]`，避免短文本在 Phase 2 `join("")` 中丢失 separator 边界
|
||
- **`Document::new` 使用 `impl Into<String>`**：接受 `&str` 或 `String`，比规范示例的 `String` 更灵活
|
||
- **`new()` panic + `try_new()` Result 双路径**：与 Rust 库惯例一致
|
||
- **CJK 分隔符扩展**：`DEFAULT_SEPARATORS` 包含 `"。"`/`"？"`/`"！"`，避免中文文本跳过句子级退化为空格分割
|
||
- **chunk_size = 0 校验**：构造器拒绝零值，避免字符级兜底死循环
|
||
- **tracing 埋点**：`split()` 入口 `tracing::debug!` + 每文档/每 chunk `tracing::trace!`
|
||
- **debug_assert 溢出保护**：单文档 chunk 数 < 10000 时 `debug_assert!`
|
||
- **Metadata 键覆盖文档化**：`HashMap::insert()` 静默覆盖 source_id/chunk_index/chunk_count 在 `split()` doc comment 注明
|
||
- 测试：19 个 Document 测试（含 1 个 split_multibyte_utf8_boundary CJK 边界测试）+ 6 个 Embedding 测试，全量 286 → 313（+27 新测试，但部分测试覆盖范围重叠计算约 25 个净增）
|
||
- 方案文档：`docs/20-phase14-document-and-embedding.md`（1417 行，含背景/调研/方案对比/实施计划（详细版）/3 轮审查修复记录），经过 3 轮 PM/SA 审查 + 1 轮实施后修复
|
||
- clippy 0 警告，doc 0 warning
|
||
- 无新增外部依赖（`Cargo.toml` 未修改）
|
||
|
||
**实施后调整**：
|
||
- 实施发现方案算法中 Phase 1 累加器设计与测试期望冲突（"para1\n\npara2" 在 chunk_size=100 时 1 chunk 更合理），简化为"按 separator 切分 + Phase 2 合并"两阶段分工
|
||
- 二次审查发现 `split_text` 缺少早返回守卫 + `current_sep_count` 虚增计数，全部已修复
|
||
|
||
**依赖**：无（纯数据结构 + 零新 crate 依赖）
|
||
**优先级**：P0
|
||
**预估规模**：约 350 行
|
||
**状态**：✅ Phase 14 全部交付物已完成（2026-07-09）
|
||
|
||
---
|
||
|
||
#### Phase 15: 向量存储持久化（SqliteStore 后端）
|
||
|
||
**目标**：实现 VectorStore 持久化，让语义检索支持进程重启后数据恢复。
|
||
|
||
**设计决策**：不用 pgvector。基于已有 SqliteStore（`rusqlite`）做持久化包装——运行时全量加载到 InMemory 索引做余弦搜索，写时同步到 SqliteStore。
|
||
|
||
**交付物**：
|
||
1. 新增 `src/memory/vector_store.rs`（937 行）—— `VectorStore` trait + `InMemoryVectorStore` + `PersistentVectorStore` + `RagPipeline`
|
||
2. `VectorStore` trait：`add(&[Document], &[Vec<f32>])` 批量 / `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`
|
||
|
||
**实际新增**（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 行（实际约 937 行纯实现 + 测试）
|
||
**状态**：✅ Phase 15 全部交付物已完成
|
||
|
||
---
|
||
|
||
#### Phase 16: 摘要自动生成
|
||
|
||
**目标**：闭环长对话能力。v0.2 的 `inject_summary` 消费端（`FocusedConfig.summary_override`）已就绪，缺的是生产端。
|
||
|
||
**交付物**：
|
||
1. `SummaryConfig` 结构体：`trigger_token_ratio`（默认 0.75） / `max_context_tokens`（默认 32_000）/ `summary_prompt`（默认中文 `DEFAULT_SUMMARY_PROMPT` 含 `{messages}`） / `debounce_turns`（默认 3） / `summary_model`（默认 `None` 沿用主模型） / `max_tool_result_chars`（默认 500）
|
||
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)` 方法（不覆盖整个 `AgentConfig`）
|
||
4. 公开 API：`get_conversation_summary() -> Result<Option<String>, AgentError>`
|
||
5. `format_messages_as_text()` 简洁版消息格式化（System/User/Assistant + `[Tool: name]` + `Tool Result [id]:` 截断到 `max_tool_result_chars` 字符）
|
||
|
||
**设计决策**：内联于 `submit_turn` 流程而非 Hook 扩展（因为 HookContext 无法携带 `&mut self` 引用更新 slot config，且流式路径的 `finalize_turn` 中 `cycle` 已销毁）。`Option<SummaryConfig>` 的 opt-in 机制已足够提供可插拔性，不改变 Hook 系统签名。流式路径中 `submit_turn_stream` 已将 `turn_index` 提前 ++1，检查点使用 `saturating_sub(1)` 修正。
|
||
|
||
**依赖**：无（`submit_turn` 流程 + `CostTracker` + `SessionMemory` + `LlmProvider` 均已就绪）
|
||
**优先级**：P0
|
||
**预估规模**：约 220 行（实际约 250 行，含 11 个内联测试）
|
||
**方案文档**：`docs/22-phase16-summary-auto-generation.md`（471 行，经 PM/SA 审查 11 项修复 + 实施后第二轮审查 9 项修复全部完成）
|
||
**状态**：✅ Phase 16 全部交付物已完成（含实施后 PM/SA/Code Reviewer 第二轮审查 PASS）
|
||
|
||
**实施后审查修复记录**（共 9 项）：
|
||
- 🔴 B1：`generate_summary` 调用 `submit_messages(Vec::new(), vec![])` 发送空消息列表 → 移除 `with_messages()`，直接 `submit_messages(vec![Message::user_text(prompt)], vec![])`
|
||
- 🟡 W4：`should_summarize` 使用 `self.turn_index` 而非 `current_turn` 参数 → 改签名接收 `current_turn`，流式路径防抖准确
|
||
- 🟡 W2：`summary_model` 硬编码 `unwrap_or("gpt-4o")` → 改为条件赋值，`None` 时沿用 `CycleConfig::default()`
|
||
- 🟡 W5：Full 模式 `slot.save()` 无谓调用 → 移入 `SlotMode::Focused` 分支内
|
||
- 🟡 W3：`format_messages_as_text` 缺 30K 整体截断 → 新增 `MAX_TOTAL_CHARS=30_000` + `truncate_total_chars`，优先保留最新
|
||
- 🟡 W6：摘要成功无日志 → 添加 `tracing::info!(turn, summary_len, "摘要自动生成成功")`
|
||
- 🟡 W1/W7：缺 3 个测试 → 新增 `format_total_charset_truncation_keeps_recent` / `summary_written_to_focused_slot_config` / `summary_skipped_for_empty_messages` / `summary_not_generated_if_max_context_unreachable`
|
||
- 💭 `context.rs:78` 过时注释（"v0.3 将支持 Hook 驱动"）→ 更新为"v0.3 Phase 16 起 AgentBuilder 内联检查点自动生成摘要"
|
||
|
||
**第二轮审查门禁**：PASS（0 🔴 阻塞）。`cargo test --all-targets` **353 passed / 0 failed**，clippy 0 警告，doc 0 warning。
|
||
|
||
---
|
||
|
||
#### Phase 17: Agent 执行引擎（会话树 + Time-travel Checkpointer）
|
||
|
||
**目标**：建立 `engine/` 模块。解决 v0.2 中"session 在变量里、无法通过 ID 恢复、不支持父子关系"的空白。
|
||
|
||
**方案文档**：`docs/23-phase17-agent-execution-engine.md`
|
||
|
||
**交付物**：
|
||
1. `src/engine/` 新模块（`session_manager.rs` + `checkpointer.rs` + `snapshot.rs` + `error.rs`）
|
||
2. `SessionManager`：
|
||
- `create(agent, bundle) -> Result<String, EngineError>` — 创建根 session（UUID v4 自动生成 ID）
|
||
- `create_child(parent_id, agent) -> Result<String, EngineError>` — 创建子 session（继承父 `RuntimeBundle`，`Arc::clone` 共享引用）
|
||
- `get(session_id) -> Result<Arc<Mutex<AgentSession>>, EngineError>` — 按 ID 查找（仅查内存，不自动从存储恢复）
|
||
- `recover(session_id, agent, bundle) -> Result<Arc<Mutex<AgentSession>>, EngineError>` — 从存储恢复 session
|
||
- `replace(session_id, session) -> Result<(), EngineError>` — 替换已有 session 实例（用于 rollback 后切换）
|
||
- `children(parent_id)` / `parent(child_id)` — 树形查询
|
||
- `destroy(id)` — 生命周期管理（允许孤儿 session 存在，不递归删除子 session）
|
||
3. `Checkpointer`：
|
||
- `checkpoint(session)` — 每个 `submit_turn` 末尾自动保存全量状态快照
|
||
- `rollback_load(session_id, ckpt_id) -> SessionSnapshot` — 读取 checkpoint JSON 为 snapshot（不重建 AgentSession）
|
||
- `list_checkpoints(session_id)` — 列出 checkpoint 列表
|
||
- `delete_all(session_id)` — 清理某 session 所有 checkpoint
|
||
- `fork()` 推迟（底层可拆解为 `rollback` + `create_child`，作为高层 API 等价于约 30 行组合代码，已具备原始能力）
|
||
4. `SessionSnapshot` 独立 struct（位于 `engine/snapshot.rs`）—— 避开 `Arc<dyn Agent>` 不可序列化的限制，通过 `to_snapshot()` / `from_snapshot()` 双向转换实现 AgentSession 快照持久化
|
||
- `to_snapshot()`（async，从 `SessionMemory` 读取完整数据）+ `from_snapshot()`（纯同步构造）+ `restore_memory()`（async 写回持久层）
|
||
5. `EngineError` 枚举（含 `MemoryError` 透传变体 与项目既有 `AgentError` 风格一致）
|
||
|
||
**Checkpoint 存储格式**：`ckpt:{session_id}:{ckpt_id}` → `SessionSnapshot` JSON（全量 session 状态，含所有 slot 消息列表）。Ponytail：全量 JSON 够用，等遇到存储效率问题时再改增量模式。
|
||
|
||
**会话树持久化**：`session:{session_id}:meta` → `SessionMeta` JSON（`{agent_name, parent_id, created_at, turn_count}`）
|
||
|
||
**依赖**：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）
|
||
|
||
---
|
||
|
||
#### 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 行
|
||
|
||
**实际新增**（2026-07-15 commit `46de111`，详见 `docs/24-phase18-agent-switch-and-dispatch.md`）：
|
||
- 方案文档：`docs/24-phase18-agent-switch-and-dispatch.md`（700 行，含 Agent Switch 与 SubAgent Dispatch 的设计推演）
|
||
- 新增文件 2 个：
|
||
- `src/engine/switch.rs`（222 行）— `SessionManager::switch_agent()` 热切换：替换 `Arc<dyn Agent>`，slot 历史 / turn_index / session_memory / cost_so_far 全部保留，同步更新 `SessionMeta.agent_name` 到持久层
|
||
- `src/engine/sub_agent.rs`（1071 行）— SubAgent 调度完整实现：4 个公开方法 + 3 个公开类型
|
||
- 修改文件 4 个：
|
||
- `src/engine/mod.rs`（+5 行：`pub mod switch; pub mod sub_agent;` + `pub use sub_agent::{DispatchConfig, SubTaskResult, SubTaskStreamEvent};`）
|
||
- `src/engine/error.rs`（+1 变体：`DispatchFailed(#[source] String)`）
|
||
- `src/engine/session_manager.rs`（+2 处可见性：`save_session_meta` / `load_session_meta` 改 `pub(crate)` 供 `switch.rs` 使用）
|
||
- `src/llm/types/usage.rs`（+`From<Usage>` 实现供 `SubTaskResult.usage` 字段构造）
|
||
- 新增 4 个示例：
|
||
- `examples/agent_switch_demo.rs`（115 行）— Agent 热切换演示
|
||
- `examples/sub_agent_dispatch_demo.rs`（141 行）— dispatch / dispatch_all 并行派发演示
|
||
- `examples/bridge_keys_demo.rs`（197 行）— bridge_keys 过滤的 SessionMemory 继承演示
|
||
- `examples/dispatch_stream_demo.rs`（121 行）— dispatch_stream 流式派发演示
|
||
- 关键设计：
|
||
- **`switch_agent` 锁契约**：先 `get` session → 锁 `Mutex` 替换 agent 并读取 turn_index → 释放 Mutex → 读/写 `SessionMeta`（无锁 IO），最大限度减少锁竞争
|
||
- **`SessionMeta` 保留原则**：切换 `agent_name` 字段，但 `created_at` / `parent_id` 保留原始（血缘不可变）
|
||
- **`switch_agent` 不自动 checkpoint**：与 `auto_checkpoint` 语义一致（仅 `submit_turn` / `finalize_turn` 触发），避免每次角色切换产生冗余 checkpoint
|
||
- **`inherit_session_memory` 快照语义**：捕获调用时刻的父 session_memory 快照，子 session 写回后即使父被并发写入也不传播（防止非确定性结果）
|
||
- **`bridge_keys` 三态语义**：`None` = 不继承任何（安全默认）/ `Some(vec![])` = 继承全部 / `Some(keys)` = 仅继承指定 key
|
||
- **`shared_namespace` 约定式共享**：纯约定字段，不触发自动注入逻辑，子 agent 显式 `session.set_session_data("shared:{prefix}:{key}", value)` 写入
|
||
- **`dispatch_all` 部分成功语义**：`Vec<Result<SubTaskResult, EngineError>>` 按输入顺序 indexed 收集，task panic 通过 `DispatchFailed` 哨兵占位（不破坏顺序一致性）
|
||
- **`dispatch_stream` 后台 finalize**：spawn task 内部调 `finalize_turn()` 落库，明确不参与 `auto_checkpoint`（避免与流式 checkpoint 重复）
|
||
- **`SubTaskStreamEvent` 事件序列**：`ChildCreated { child_id }` → `Stream(StreamEvent) × N` → `Completed(SubTaskResult)` 或 `Error { child_id, error }`
|
||
- **`SUBTASK_NAMESPACE` 防误注入**：子 session 注入到 SessionManager 时使用 `subtask:` prefix 避免与 SessionMeta 的 `session:{id}:meta` 冲突
|
||
- 测试：+17 内联测试（4 switch + 5 dispatch + 4 dispatch_all + 4 dispatch_stream），全量 374 → **391 passed / 0 failed**（+17，0 失败）
|
||
- 质量基线：`cargo test --all-targets` 391 passed / 0 failed；`cargo clippy --all-targets -- -D warnings` 0 警告；`cargo doc --no-deps` 0 warning；4 个示例全部 exit 0
|
||
- 零新外部依赖（ponytail：与 Phase 17 一致）
|
||
|
||
**状态**：✅ Phase 18 全部交付物已完成
|
||
|
||
---
|
||
|
||
#### 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 行（实际约 720 行核心 + 200 行测试）
|
||
**方案文档**：`docs/25-phase19-knowledge-graph-and-retrieval.md`（652 行，经 PM/SA 双轮审查 PASS）
|
||
**状态**：✅ Phase 19 全部交付物已完成（2026-07-17）
|
||
|
||
**实际新增**（2026-07-17）：
|
||
- 新增文件 2 个：
|
||
- `src/memory/graph.rs`（~580 行）- `GraphEntity`（id/name/entity_type/description/tags/properties）+ `GraphRelation`（无 id 字段，`composite_key()` 派生）+ `RelationDirection`（`#[derive(Default)]` + `#[default]` Outgoing）+ `ScoredEntity`（含 path 路径）+ `TagConstraints`（max_tags_per_entity 默认 8）+ `KnowledgeGraph` trait（10 个 async 方法）+ `InMemoryGraph`（`Mutex<GraphInner>` 单一锁结构，避免嵌套锁死锁）+ BFS 图遍历（visited 防环 + 权重乘积衰减 + 多路径先到先得 + depth=0 返回空）+ 标签管理（tag_index 反向索引）+ 23 个内联测试
|
||
- `examples/knowledge_graph_demo.rs`（~140 行）- 端到端演示：构建图谱 -> BFS 遍历 -> 标签管理 -> Hybrid/GraphOnly 双通道检索
|
||
- 修改文件 3 个：
|
||
- `src/memory/retriever.rs` - `RetrievalStrategy` 枚举（Hybrid 默认 / KnowledgeOnly / GraphOnly）+ `RetrievalItem` enum（统一列表，`score()` 方法）+ `RetrievalResult` 新增 `strategy` 字段（反映实际执行策略）+ `MemoryRetriever` 双通道（`with_knowledge_graph` / `with_strategy` 链式构造）+ `search_knowledge_store` / `search_graph` 私有方法 + `tokio::join!` 并行 + 旧 `ScoredItem` 标注 `#[deprecated]` + `RetrieverConfig` 新增 `graph_depth`（默认 2）+ 13 个内联测试
|
||
- `src/memory.rs` - `pub mod graph` + 重导出 7 个图类型 + 更新 retriever 重导出
|
||
- `examples/knowledge_search_demo.rs` - 适配新 API（`RetrievalItem` enum match + `RetrieverConfig.graph_depth`）
|
||
- 关键设计：
|
||
- **`Mutex<GraphInner>` 单一锁结构** - 避免 `set_entity_tags` 嵌套锁死锁风险（审查修复）
|
||
- **`RetrievalResult.strategy` 反映实际执行策略** - graph 未注入时退化为 `KnowledgeOnly`（审查修复）
|
||
- **`GraphRelation` 无 id 字段** + `composite_key()` 派生方法
|
||
- **BFS**：`visited` 防环 + 权重乘积衰减 + 多路径先到先得 + `depth=0` 返回空
|
||
- **零新外部依赖**（ponytail 风格）
|
||
- 测试：391 -> **427 passed / 0 failed**（+36 新测试：23 graph + 13 retriever）
|
||
- 质量基线：`cargo test --all-targets` 427 passed / 0 failed；`cargo clippy --all-targets -- -D warnings` 0 警告；`cargo doc --no-deps` 0 warning；`cargo run --example knowledge_graph_demo` exit 0
|
||
|
||
---
|
||
|
||
### 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"]:::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<br/>21 新测试"]:::done
|
||
P18["<b>Phase 18: 切换与调度</b><br/>Agent Switch<br/>SubAgent Dispatch<br/>dispatch_all 并发控制<br/>17 新测试"]:::done
|
||
P19["<b>Phase 19: 知识图谱</b><br/>KnowledgeGraph trait<br/>InMemoryGraph<br/>双通道检索"]:::done
|
||
|
||
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` 测试通过 | ✅ 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` 推迟，按需时引入）| ✅ 2026-07-15 |
|
||
| **M14** | Phase 18 | `switch_agent` 热切换验证（slot / turn_index / session_memory 保留）、`dispatch` / `dispatch_all` 并行派发 + Semaphore 顺序、`dispatch_stream` 流事件序列验证 | ✅ 2026-07-15 |
|
||
| **M15** | Phase 19 | `KnowledgeGraph` 实体-关系 CRUD + `get_related` BFS 验证、双通道检索 Hybrid 策略验证 | ✅ 2026-07-17 |
|