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 全部交付物已完成

---

依赖关系图

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）。

核心类型：

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 依赖关系图

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 依赖关系图

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