From 821cea8e60a83d52b8f211d72e93d8a580ef0711 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Sun, 5 Jul 2026 10:49:50 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0=20roadmap?= =?UTF-8?q?=EF=BC=8C=E6=A0=87=E8=AE=B0=20Phase=206=20=E4=BA=A4=E4=BB=98?= =?UTF-8?q?=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 6 ToolDef IR 的 5 个子步骤全部标注已完成，新增实际变更摘要，更新里程碑状态及下一步行动计划 --- docs/roadmap.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 923905f..f5bebde 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -7,7 +7,7 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。 -**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-5 全部完成，Provider IR 重构 + LlmCycle 简化 + 8 个离线示例已交付（新增 `simple_visit.rs`）。v0.2.0 已细分为 8 个增量 Phase（Phase 5-12），其中 Phase 5 已完成（Ollama Provider + `#[non_exhaustive]` 兼容性护栏 + `ProviderConfig::from_env`），下一步进入 Phase 6 (ToolDef IR 正式化)。 +**当前状态**：v0.1.0 已发布（2026-07-04）。Phase 0-6 全部完成，Provider IR 重构 + LlmCycle 简化 + 8 个离线示例已交付（新增 `simple_visit.rs`）。v0.2.0 已细分为 8 个增量 Phase（Phase 5-12），其中 Phase 5（Ollama Provider + `#[non_exhaustive]` 兼容性护栏 + `ProviderConfig::from_env`）与 Phase 6（ToolDef IR 正式化）已完成，下一步进入 Phase 7 (SqliteStore 持久化)。 --- @@ -362,11 +362,11 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve } | Step | 内容 | 验证标准 | |------|------|---------| -| **6.1** | `types/tool.rs` 新增 `ToolDef` 结构体 + `From for OpenaiToolDefinition` + 反向 `From` | 单元测试 roundtrip | -| **6.2** | `types/mod.rs` 切别名 `pub type ToolDefinition = ToolDef`；`MessageRequest.tools` 改 `Vec` | `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` 全绿 | +| **6.1** ✅ | `types/tool.rs` 新增 `ToolDef` 结构体 + `From for OpenaiToolDefinition` + 反向 `From` | 单元测试 roundtrip | +| **6.2** ✅ | `types/mod.rs` 切别名 `pub type ToolDefinition = ToolDef`；`MessageRequest.tools` 改 `Vec` | `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：新类型存在但旧代码照常编译 @@ -376,6 +376,19 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve } **依赖**：无（仅与 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` +- `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 持久化 @@ -481,7 +494,7 @@ pub struct ContextBudget { system, history, tools, tool_results, reserve } ```mermaid graph BT P5["Phase 5: 热身准备
ProviderConfig::from_env
Ollama Provider
#[non_exhaustive] 标记"]:::done - P6["Phase 6
ToolDefinition IR"]:::core + P6["Phase 6: ToolDef IR
Provider 无关工具定义"]:::done P7["Phase 7
SqliteStore"]:::core P8["Phase 8
MVP 出口 (rc.1)"]:::mvp P9["Phase 9
流式体验增强"]:::p1 @@ -515,7 +528,7 @@ graph BT | 里程碑 | Phase 完成条件 | 可验证指标 | 状态 | |--------|---------------|-----------|------| | **M1** | Phase 5 | 热身三项完成：`from_env()` 可用 / Ollama 类型存在 / `#[non_exhaustive]` 就位 | ✅ 2026-07-05 | -| **M2** | Phase 6 | `ToolDef` 全量切换，`cargo test --all-targets` 全绿 | ⏳ 待启动 | +| **M2** | Phase 6 | `ToolDef` 全量切换，`cargo test --all-targets` 全绿 | ✅ 2026-07-05 | | **M3** | Phase 7 | SqliteStore CRUD + 并发测试通过，进程重启数据不丢 | ⏳ 待启动 | | **M4** | **Phase 8 (rc.1)** | P0 五项全部交付，`cargo run --example quick_start` 跑通 | ⏳ | | **M5** | Phase 9 | `submit_turn_stream` 流式事件序列验证通过 | ⏳ | @@ -564,10 +577,9 @@ graph BT ## 下一步行动 -1. **Phase 6 启动**：ToolDef 结构体定义 + 5 步逐文件切割（types → cycle/registry → providers → 适配层 → 测试迁移） -2. **Phase 7 启动**：SqliteStore（`rusqlite` + `bundled`），可与 Phase 6 并行 -3. **示例先行**：每完成一个 Phase 立即更新对应示例，验证通过后再合入 -4. **里程碑追踪**：以 Phase 8（MVP 出口）为 v0.2.0-rc.1 节点，逐 Phase 验收 +1. **Phase 7 启动**：SqliteStore（`rusqlite` + `bundled`），可与 Phase 6 并行 +2. **示例先行**：每完成一个 Phase 立即更新对应示例，验证通过后再合入 +3. **里程碑追踪**：以 Phase 8（MVP 出口）为 v0.2.0-rc.1 节点，逐 Phase 验收 **已完成 / 进行中阶段**： - ✅ Phase 0 Foundation — 全部交付物已完成 @@ -578,6 +590,7 @@ graph BT - ✅ 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 测试覆盖 - ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen/Ollama 适配 - ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除 - ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、8 个离线示例（含 `simple_visit`）、README + 错误消息友好化、CHANGELOG 初始化