docs(roadmap): 更新路线图为 v0.2 生产就绪规划

同步 v0.1.0 发布状态，将 v0.2+ 扩展项重
组为 12 项基础功能和 ContextSlot 上下文管
理，明确 v0.3+ 展望及边界范围

docs/roadmap.md

@@ -1,13 +1,13 @@
 # AG Core Roadmap
 
 > 定稿日期：2026-05-11
-> 最后更新：2026-07-04（v0.1 发布完成）
+> 最后更新：2026-07-04
 
 ## 愿景
 
 AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
 
-**当前状态**：Phase 0-4c 全部完成；Provider IR 重构（统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen Provider）已完成；LlmCycle 简化（IR 消息类型切换 + 桥接层移除）已完成；v0.1 发布就绪（**182 个测试通过、0 clippy 警告、7 个离线示例可运行**）。
+**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-4c 全部完成，Provider IR 重构 + LlmCycle 简化 + 7 个离线示例已交付。v0.2.0 规划已确定，主题为「生产就绪（Production-Ready Core）」。
 
 ---
 
@@ -240,95 +240,133 @@ graph BT
 
 ---
 
-## 扩展计划（v0.2+）
+## v0.2.0 — 生产就绪（Production-Ready Core）
 
-> 以下功能在已完成的 phase 中已实现基础能力或在 Phase 4 阶段明确了边界，后续可按维度增量扩展。
-> 设计参考：见 `docs/note-agent-harness-references.md`（OpenClaw / Hermes / OpenHuman / OpenHarness 横向对比）。
-> OpenCode 借鉴：见 `docs/note-opencode-agent-switching.md`（Agent 切换 + System Prompt 拼接机制）。
+**目标**：解决 Rust Agent 工具箱从"能跑"到"能被人依赖"的鸿沟。持久化、配置层、上下文管理三大块补齐后，开发者可在 30 分钟内写出生产可用的 Agent 服务。
 
-### 已有扩展项（沿用）
+**交付物**：
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| Prompt Optimizer | `prompt` | 提示词自动优化 | P3 | 待实现 |
-| 流式接口优化 | `llm/stream` | 流式响应解析与事件化 | P0 | ✅ 已完成基础实现 |
+### 12 项基础功能
 
-### v0.2+ 新增扩展项
+#### P0 — 必须交付
 
-> 以下为基于 Phase 4 设计讨论确定的 v0.2+ 候选扩展方向，按维度分组。
-> 标注为"v0.2 待评估"表示在 Phase 4 完成后再决定是否启动。
+| # | 功能 | 模块 | 方案要点 |
+|---|------|------|---------|
+| 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`） |
 
-#### Multi-Agent / 协同
+#### P1 — 重要但不阻塞
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| Multi-Agent 协同（Swarm） | `agent` | 子 Agent 委派、并行子任务、结果聚合 | P2 | v0.2 待评估 |
+| # | 功能 | 模块 | 方案要点 |
+|---|------|------|---------|
+| 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 测试 |
 
-#### 技能（Skills）
+#### P2 — 有时间再做
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| Markdown 技能按需加载 | `agent` / `prompt` | 兼容 `SKILL.md` 格式（Hermes / OpenHarness 风格），按 prompt 上下文动态加载 | P2 | v0.2 待评估 |
+| # | 功能 | 模块 | 备注 |
+|---|------|------|------|
+| 10 | MCP StreamableHttp | `tools` | 当前仅预留枚举变体 |
+| 11 | Gemini Provider | `llm/provider` | 协议差异大，实现成本较高 |
+| 12 | 文件系统 MemoryStore 后端 | `memory` | JSON/JSONL 轻量持久化 |
 
-#### 记忆（Memory）
+### ContextSlot 上下文管理
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| 多通道检索（hybrid） | `memory/retriever` | 在 TextOverlap 之上叠加向量检索通道 | P2 | v0.2 待评估 |
-| KnowledgeGraph 深度记忆 | `memory` | 实体-关系图、`note-knowledge-graph-design.md` 已记录设计 | P3 | v0.2 待评估 |
-| TokenJuice 智能压缩 | `memory` / `llm/compact` | 借鉴 OpenHuman TokenJuice，对工具结果做语义压缩而非字节截断 | P3 | v0.2 待评估 |
+**模块归属**：`src/llm/context.rs`（与 `compact.rs` 同级）
 
-#### 交互层（TUI / Gateway）
+**核心概念**：`ContextSlot` 是一段带策略配置的消息列表，以 `slot_id` 为 namespace 独立持久化到 `MemoryStore`。支持三种模式、三种来源和派生关联（记录 `parent_id`）。
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| TUI / 多平台 Gateway | 应用层 | OpenClaw / Hermes 风格的消息平台桥接（Feishu / Telegram / Discord 等） | P3 | v0.2+ 应用层 |
+**核心类型**：
 
-#### 训练基础设施
+```rust
+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 }
+```
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| RL 轨迹导出 | `agent` | ShareGPT 格式轨迹、Atropos 集成（Hermes 风格） | P3 | v0.3+ 探索 |
+**持久化 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 派生
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| Human-in-the-loop 审批 | `agent` / `tools/permission` | 高危工具执行前的异步审批回调（OpenHarness `permission_prompt` 模式） | P2 | v0.2 待评估 |
+**与 `ConversationMemory` 的关系**：保留不废除。`ConversationMemory` 继续服务传统对话场景。
 
-#### 流式 / 实时
+**v0.2 不做**：
+- ❌ `slot.fork()` / `merge()` — 分支方法推迟到 v0.3+
+- ❌ `inject_summary` 自动生成 — v0.2 仅消费端（从 `SessionMemory` 读取），生成在 v0.3+
+- ❌ 血缘关系图遍历 — 只存 `parent_id`，不做查询
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| 流式 `submit_turn` | `agent/session` | Phase 4 v1 只暴露非流式 `submit_turn()`；v0.2 包装 `LlmCycle::submit_stream` 暴露流式入口 | P2 | v0.2 待评估 |
+**依赖**：Phase 0（MemoryStore trait）、Phase 3（MemoryStore 持久化）
+**优先级**：P1
 
-#### Agent 切换 / Prompt 动态（OpenCode 借鉴）
+---
 
-| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
-|-------|---------|------|--------|------|
-| Agent 身份切换（角色轮换） | `agent` | 借鉴 OpenCode Tab 键切换 build/plan：同一 `AgentSession` 持有可热替换的 `Agent` 引用，切换时不重置消息历史，在末尾追加 `synthetic: true` 的状态变更消息。详见 `docs/note-opencode-agent-switching.md` §4 | P2 | v0.2 待评估 |
-| System Prompt 多层动态拼接 | `agent/session` | 借鉴 OpenCode `request.ts:58-66`：拆分 `base_prompt + agent_prompt + env_context` 三层，`AgentSession::submit_turn` 每轮重算（不缓存），便于按 agent 类型动态切换 | P2 | v0.2 待评估 |
-| **多 Context 切换** | `agent` | **Phase 4c 的 SessionMemory 数据结构已预留信息桥接通道，v0.2+ 在其上包装 `ContextManager` 实现完整的多 context 切换：创建/销毁/切换 context、通过 SessionMemory 桥接关键信息。详见 `docs/note-context-switch-design.md`** | P2 | v0.2 待评估 |
+## v0.3+ 展望
+
+### 已规划的功能
+
+| 功能 | 说明 | 预计版本 |
+|------|------|---------|
+| ContextSlot 分支（fork/merge） | 在决策点 fork 出子上下文，分支独立演进，可合并/丢弃 | v0.3 |
+| 摘要自动生成 | Hook 驱动，`OnTurnEnd` 自动将对话摘要写入 `SessionMemory`，`inject_summary` 消费端已在 v0.2 就绪 | v0.3 |
+| 知识图谱 | 实体-关系图，`docs/note-knowledge-graph-design.md` 已记录设计 | v0.3+ |
+| Multi-Agent 协同（Swarm） | 子 Agent 委派、并行子任务、结果聚合 | v0.4+ |
+| 精确 tokenizer 计数 | 绑定具体模型的 tokenizer 计数，替代当前的字符估算 | v0.3+ |
+| 血缘关系图遍历 | 以 `parent_id` 为基础，提供 slot 血缘链查询 | v0.3+ |
+| Markdown 技能按需加载 | 兼容 `SKILL.md` 格式，按 prompt 上下文动态加载 | v0.3+ |
+| TokenJuice 语义压缩 | 对工具结果做语义压缩而非字节截断 | v0.3+ |
+| Human-in-the-loop 审批 | 高危工具执行前的异步审批回调 | v0.3+ |
+| RL 轨迹导出 | ShareGPT 格式轨迹、Atropos 集成 | v0.4+ |
+
+### 明确不做（agcore 范围外）
+
+| 功能 | 原因 |
+|------|------|
+| TUI / 多平台 Gateway | 应用层职责（Feishu / Telegram / Discord 桥接） |
+| 配置自动加载（config/figment） | 配置来源策略应由上游应用决定，agcore 不定义配置格式 |
+| 提示词自动优化 | 属于智能层，不应内建于 core 库 |
 
 ---
 
 ## 风险与建议
 
-1. **Phase 0 已完成**：LLM 调用周期基础设施已全部实现，可以支撑后续模块开发
-2. **并行可能性**：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付
-3. **MCP 协议复杂性**：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节
-4. **Scope 蔓延风险**：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计
-5. **Phase 4 抽象化边界**：AG Core 定位为"支持库"而非"Agent 产品"，Phase 4（4a/4b/4c）需严格控制范围——只暴露 trait + 最小 reference impl，业务循环（多轮 turn 编排、对话记忆自动回写、Task 拆解策略）留给上层应用。`SessionMemory`（Phase 4c）提供信息桥接通道但不实现 context 切换逻辑。多 context 切换管理延后至 v0.2+。详细设计决策见 `docs/7-agent-runtime.md`
-6. **参考项目语言差异**：OpenClaw / Hermes / OpenHarness 均为 Python/TypeScript 实现，OpenHuman 虽是 Rust + Tauri 但定位是桌面应用。借鉴时**只取架构模式**，不照搬具体实现（如 Pydantic 工具校验、SQLite Memory Tree、Node+Python 双进程等）
+1. **持久化依赖**：`rusqlite` + `bundled` 零外部依赖编译，但 SQLite 不适配所有场景（分布式/高并发写）。`MemoryStore` trait 的抽象层允许下游自行实现 Redis / PostgreSQL 后端
+2. **ContextSlot 心智负担**：`ContextSlot` 引入了一等抽象的复杂度。建议通过 `AgentBuilder` 默认创建 `"default"` slot，让简单场景无感使用
+3. **向量检索生态**：`VectorRetriever` trait-only 不绑定实现，需社区贡献或用户自行适配 pgvector / qdrant / lancedb
+4. **Scope 蔓延**：agcore 定位为"支持库"而非"Agent 产品"，始终以 trait + reference impl 为边界，业务循环留给上层
+5. **API 稳定性**：v0.2 引入 `#[non_exhaustive]` 和 `#[deprecated]` 机制，但不承诺 SemVer 稳定——仍在快速迭代期
 
 ---
 
 ## 下一步行动
 
-1. **Phase 4c 已完成**：Phase 4a + 4b + 4c 已交付（116 测试通过，0 clippy 警告）。可启动 v0.2+ 扩展评估（如多 Context 切换、Multi-Agent 协同等）
-2. **Context 切换备忘**：`docs/note-context-switch-design.md` 记录了多 context 切换方案讨论，作为 v0.2+ 扩展项的输入
-3. **参考项目调研沉淀**：已完成 OpenClaw / Hermes / OpenHuman / OpenHarness 横向调研，结果沉淀至 `docs/note-agent-harness-references.md`，作为 v0.2+ 扩展项的输入
-4. **Phase 3 备用设计就绪**：`docs/note-knowledge-graph-design.md` 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，v0.2+ 记忆扩展可直接参考
+1. **v0.2 开发启动**：按 P0 → P1 → P2 顺序推进，P0 五项必须全部交付
+2. **ContextSlot 方案文档**：输出正式方案文档到 `docs/`，记录 SlotConfig / SlotSource / DeriveStrategy 等设计决策
+3. **示例先行**：每个 P0 功能先编写 `examples/` 中的可运行示例，验证通过后再合入库代码
+4. **测试覆盖**：SqliteStore 并发测试 + wiremock Provider roundtrip 测试 + ContextSlot 隔离/切换/派生测试
 
 **已完成 / 进行中阶段**：
 - ✅ Phase 0 Foundation — 全部交付物已完成
@@ -338,9 +376,10 @@ graph BT
 - ✅ Phase 4a Core Glue — 全部交付物已完成
 - ✅ Phase 4b Task Execution — 全部交付物已完成
 - ✅ Phase 4c Session Memory — 全部交付物已完成
-- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen 适配（方案：`docs/10-llm-provider-refinement.md`、`docs/10a-phase0-types-and-trait.md`、`docs/10b-phase1-provider-adaptation.md`）
-- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除（方案：`docs/10c-phase2-llm-cycle-simplify.md`）
-- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、7 个离线示例、README + 错误消息友好化、Roadmap 同步、CHANGELOG 初始化（计划：`docs/11-v0.1-release-plan.md`）
+- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen 适配
+- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
+- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、7 个离线示例、README + 错误消息友好化、CHANGELOG 初始化
+- 📋 **v0.2 规划完成** — 生产就绪（Production-Ready Core），ContextSlot 上下文管理，12 项基础功能
 
 ---