docs(roadmap): 更新 v0.2 规划为 8 个增量 Phase 并细化实施步骤
This commit is contained in:
徐涛
+198
-8
@@ -7,7 +7,7 @@
|
||||
|
||||
AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
|
||||
|
||||
**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-4c 全部完成，Provider IR 重构 + LlmCycle 简化 + 7 个离线示例已交付。v0.2.0 规划已确定，主题为「生产就绪（Production-Ready Core）」。
|
||||
**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-4c 全部完成，Provider IR 重构 + LlmCycle 简化 + 7 个离线示例已交付。v0.2.0 已细分为 8 个增量 Phase（Phase 5-12），本周开发启动。
|
||||
|
||||
---
|
||||
|
||||
@@ -244,9 +244,9 @@ graph BT
|
||||
|
||||
**目标**：解决 Rust Agent 工具箱从"能跑"到"能被人依赖"的鸿沟。持久化、配置层、上下文管理三大块补齐后，开发者可在 30 分钟内写出生产可用的 Agent 服务。
|
||||
|
||||
**交付物**：
|
||||
**总体规模**：8 个增量 Phase（Phase 5-12），17 个可验证 Step。
|
||||
|
||||
### 12 项基础功能
|
||||
### 功能清单
|
||||
|
||||
#### P0 — 必须交付
|
||||
|
||||
@@ -324,6 +324,196 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve }
|
||||
|
||||
---
|
||||
|
||||
### 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 警告 |
|
||||
|
||||
**依赖**：无（三个 Step 互不冲突）
|
||||
**优先级**：P0（5.1）+ P1（5.2）+ P0 前置（5.3）
|
||||
**为何独立成 Phase**：三个改动零文件重叠，可以并行推进。它们是后续所有 Phase 的"门把手"——先做完热身再进入核心工作。
|
||||
|
||||
---
|
||||
|
||||
#### 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
|
||||
|
||||
---
|
||||
|
||||
#### 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
|
||||
|
||||
---
|
||||
|
||||
#### Phase 8: MVP 集成出口（v0.2.0-rc.1 候选）
|
||||
|
||||
**目标**：P0 五项全部交付。开发者 clone 仓库后 10 分钟跑起持久化 Agent。
|
||||
|
||||
| Step | 内容 | 验证标准 |
|
||||
|------|------|---------|
|
||||
| **8.1** | API 稳定性扫尾：`#[deprecated]` 整理 + CHANGELOG v0.2 + 公开类型回顾 | 人工 review + `cargo doc` 无 warning |
|
||||
| **8.2** | Quick Start 示例（30 行 `main.rs`）：MockProvider + EchoTool + 一次 `submit_turn` | `cargo run --example quick_start` exit 0 |
|
||||
| **8.3** | 端到端示例：SqliteStore + Ollama/OpenAI(from_env) + 自定义 Tool + 多轮对话 | `cargo run --example end_to_end`（Mock fallback，无需 API key）|
|
||||
|
||||
**Phase 8 完成后可打 `v0.2.0-rc.1` 标签**。
|
||||
|
||||
**依赖**：Phase 5（ProviderConfig from_env）+ Phase 6（ToolDef）+ Phase 7（SqliteStore）
|
||||
**优先级**：P0
|
||||
|
||||
---
|
||||
|
||||
#### 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
|
||||
|
||||
---
|
||||
|
||||
#### Phase 10: ContextSlot 上下文管理
|
||||
|
||||
**目标**：支持多上下文分区管理，Agent 可在不同 slot 之间切换。
|
||||
|
||||
| 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` |
|
||||
|
||||
**如何保证简单场景无感**：`AgentBuilder::build()` 内部检查，如果用户没手动 `create_slot`，自动创建 `"default"` slot → `submit_turn` 默认写到 default slot。
|
||||
|
||||
**依赖**：Phase 7（SqliteStore 作为推荐持久化后端；`MemoryStore` trait 即可）
|
||||
**优先级**：P1
|
||||
|
||||
---
|
||||
|
||||
#### 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 |
|
||||
|
||||
**依赖**：无（可随时做）
|
||||
**优先级**：P1
|
||||
|
||||
---
|
||||
|
||||
#### 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 依赖关系图
|
||||
|
||||
```mermaid
|
||||
graph BT
|
||||
P5["Phase 5<br/>热身准备"]:::warmup
|
||||
P6["Phase 6<br/>ToolDefinition IR"]:::core
|
||||
P7["Phase 7<br/>SqliteStore"]:::core
|
||||
P8["Phase 8<br/>MVP 出口 (rc.1)"]:::mvp
|
||||
P9["Phase 9<br/>流式体验增强"]:::p1
|
||||
P10["Phase 10<br/>ContextSlot"]:::p1
|
||||
P11["Phase 11<br/>测试与检索"]:::p1
|
||||
P12["Phase 12<br/>P2 锦上添花"]:::p2
|
||||
|
||||
P8 --> P5
|
||||
P8 --> P6
|
||||
P8 --> P7
|
||||
|
||||
P9 --> P6
|
||||
|
||||
P10 --> P7
|
||||
P10 --> P8
|
||||
|
||||
P11 -.-> P7
|
||||
|
||||
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]` 就位 |
|
||||
| **M2** | Phase 6 | `ToolDef` 全量切换，`cargo test --all-targets` 全绿 |
|
||||
| **M3** | Phase 7 | SqliteStore CRUD + 并发测试通过，进程重启数据不丢 |
|
||||
| **M4** | **Phase 8 (rc.1)** | P0 五项全部交付，`cargo run --example quick_start` 跑通 |
|
||||
| **M5** | Phase 9 | `submit_turn_stream` 流式事件序列验证通过 |
|
||||
| **M6** | Phase 10 | ContextSlot 创建/切换/派生集成测试通过 |
|
||||
| **M7** | Phase 11 | wiremock + 并发测试补强，测试总量 200+ |
|
||||
| **M8** | Phase 12（可选） | P2 功能按需交付 |
|
||||
|
||||
---
|
||||
|
||||
## v0.3+ 展望
|
||||
|
||||
### 已规划的功能
|
||||
@@ -363,10 +553,10 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve }
|
||||
|
||||
## 下一步行动
|
||||
|
||||
1. **v0.2 开发启动**：按 P0 → P1 → P2 顺序推进，P0 五项必须全部交付
|
||||
2. **ContextSlot 方案文档**：输出正式方案文档到 `docs/`，记录 SlotConfig / SlotSource / DeriveStrategy 等设计决策
|
||||
3. **示例先行**：每个 P0 功能先编写 `examples/` 中的可运行示例，验证通过后再合入库代码
|
||||
4. **测试覆盖**：SqliteStore 并发测试 + wiremock Provider roundtrip 测试 + ContextSlot 隔离/切换/派生测试
|
||||
1. **Phase 5 启动**：ProviderConfig from_env + Ollama Provider + #[non_exhaustive] 前置，三个 Step 并行推进
|
||||
2. **Phase 6 方案准备**：ToolDef 结构体定义 + 兼容转换，出实施笔记（实施时直接走代码评审）
|
||||
3. **示例先行**：每完成一个 Phase 立即更新对应示例，验证通过后再合入
|
||||
4. **里程碑追踪**：以 Phase 8（MVP 出口）为 v0.2.0-rc.1 节点，逐 Phase 验收
|
||||
|
||||
**已完成 / 进行中阶段**：
|
||||
- ✅ Phase 0 Foundation — 全部交付物已完成
|
||||
@@ -379,7 +569,7 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve }
|
||||
- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen 适配
|
||||
- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
|
||||
- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、7 个离线示例、README + 错误消息友好化、CHANGELOG 初始化
|
||||
- 📋 **v0.2 规划完成** — 生产就绪（Production-Ready Core），ContextSlot 上下文管理，12 项基础功能
|
||||
- 📋 **v0.2 规划细化完成** — 8 个增量 Phase（Phase 5-12），17 个可验证 Step，覆盖 P0-P2 全部 12 项功能 + ContextSlot
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user