docs(roadmap): 同步 v0.3.2 roadmap 与实际实施状态

- Step 3/4 标记 ✅，补充验证结果（427/416/363/369/401/407 passed） - 功能清单 imply 列与 Cargo.toml 对齐（llm +futures-util，tools +tokio，memory +llm/tokio/time） - Phase 24/25 状态从"部分交付"改为"已交付"（Phase 26 已验证） - Cargo.toml [features] 草案与实际实现一致 - CI 测试矩阵草案替换为已实施的 ci.yml - 依赖 optional 化对照表修正（tokio 启用者 +tools/memory，futures-util +llm，time +memory）
2026-07-19 09:20:29 +08:00
parent 5baa170508
commit 0cfd401579
1 changed files with 84 additions and 33 deletions
@@ -5,7 +5,16 @@
 > 本文件聚焦 **v0.3.2 版本** 的规划与交付（Phase 20–27）。
 > 返回总入口：[`roadmap.md`](./roadmap.md)

-> **进度更新（2026-07-19）**：v0.3.2 全部交付。Step 1 完成 Phase 20-25（Cargo features 定义 + 依赖 optional 化 + 全模块 cfg 门控）；Step 3 完成 Phase 26-27（CI 测试矩阵固化 + LlmProvider trait 归属修正 + examples required-features + 文档更新）。验证矩阵 6 种组合全部通过，clippy 0 警告。实施方案见 [`docs/26-step1-phase20-cargo-features-implementation.md`](./26-step1-phase20-cargo-features-implementation.md) 和 [`docs/27-step3-phase26-ci-verification.md`](./27-step3-phase26-ci-verification.md)。
+> **进度更新（2026-07-19）**：v0.3.2 全部交付。Step 1 完成 Phase 20-25（Cargo features 定义 + 依赖 optional 化 + 全模块 cfg 门控）；Step 3 完成 Phase 26-27（CI 测试矩阵固化 + LlmProvider trait 归属修正 + examples required-features + 文档更新）。验证矩阵 6 种组合全部通过（427/416/363/369/401/407 passed），clippy 0 警告，18 个 example 单独编译通过。
+>
+> **Step 3 实施中的关键调整**（超出原方案的发现）：
+> - `LlmProvider` trait + `ProviderCapabilities` + `ProviderFeatures` 从 `provider.rs` 移至新建的 `provider_trait.rs`，归属 `#[cfg(feature = "llm")]`（ADR-1，纯 Mock 场景不再需要 provider feature）
+> - `llm` feature 补充 imply `futures-util`（修复 `cycle.rs` 隐式依赖）
+> - `bundle()` 方法加 `#[cfg(feature = "engine")]` 门控修复 dead_code 警告
+> - `prompt_composer` / `custom_tool` 的 required-features 需额外 `llm`（`response_v2.rs` 依赖 `LlmError`，预存耦合）
+> - cargo fmt 全量格式化（修复预存格式问题，CI format job 可通过）
+>
+> 实施方案见 [`docs/26-step1-phase20-cargo-features-implementation.md`](./26-step1-phase20-cargo-features-implementation.md) 和 [`docs/27-step3-phase26-ci-verification.md`](./27-step3-phase26-ci-verification.md)。

 ## v0.3.2 愿景

@@ -34,10 +43,10 @@
 | `document` | Document + RecursiveCharacterSplitter | — | 无 |
 | `llm-types` | Message, ToolDef, Usage, ToolChoice 等 IR 类型 | — | 无（只 serde + thiserror） |
 | `prompt` | PromptTemplate + PromptComposer | `llm-types` | 无 |
-| `llm` | Provider trait + LlmCycle + hooks + compact + embedding + mock | `llm-types` | tokio, async-stream, futures-core, tokio-stream |
-| `tools` | BaseTool + ToolRegistry | `llm-types` | futures, tokio-util |
+| `llm` | Provider trait + LlmCycle + hooks + compact + embedding + mock | `llm-types` | tokio, async-stream, futures-core, futures-util, tokio-stream |
+| `tools` | BaseTool + ToolRegistry | `llm-types` | futures, tokio-util, tokio |
 | `tools-mcp` | McpClient（Stdio/StreamableHttp） | `tools` | reqwest |
-| `memory` | MemoryStore(InMemory) + Conversation + VectorStore(InMemory) + KnowledgeGraph + Retriever | `document` | 无新增 |
+| `memory` | MemoryStore(InMemory) + Conversation + VectorStore(InMemory) + KnowledgeGraph + Retriever | `document` + `llm` | tokio, time（继承 llm 的依赖） |
 | `memory-sqlite` | SqliteStore | `memory` | rusqlite (bundled), time |
 | `agent` | Agent + Builder + Session + ContextSlot + Summary | `llm` + `tools` + `memory` | 继承下层 |
 | `engine` | SessionManager + Checkpointer + SubAgent + Switch | `agent` | 继承下层 |
@@ -81,8 +90,8 @@
 |------|-------|------|---------|---------|
 | **Step 1** ✅ | Phase 20-25 | Cargo.toml features 定义 + 依赖 optional 化 + 全模块 cfg 门控（合并实施） | 14 条编译验证全通过 + `cargo test -F full` 427 passed | ~100 |
 | **Step 2** | （已合并至 Step 1） | — | — | — |
-| **Step 3** | Phase 26 | 测试矩阵验证 + 修复 cfg 遗漏 | 7 种组合全部测试通过 | ~10 |
-| **Step 4** | Phase 27 | README + 示例标注 + 总入口同步 | review 通过 | ~100 |
+| **Step 3** ✅ | Phase 26 | 测试矩阵验证 + 修复 cfg 遗漏 + LlmProvider trait 归属修正 + examples required-features | 6 种组合全部测试通过 + clippy 0 警告 + 18 个 example 单独编译通过 | ~80 |
+| **Step 4** ✅ | Phase 27 | README + 示例标注 + 总入口同步 | review 通过 | ~100 |

 **Step 1 单独成步**：Cargo.toml 是基础设施变更，编译通过后打 checkpoint，后续都是纯源文件变更。

@@ -179,7 +188,7 @@
 **依赖**：Phase 20 + Phase 21
 **优先级**：P0
 **预估规模**：约 30 行
-**状态**：✅ 部分交付（2026-07-19，Step 1 合并）— Phase 24.3（`sqlite_store` 模块门控）+ Phase 24.4（`pub use SqliteStore` 门控）已完成；Phase 24.1（memory 模块 pub use）由 `src/lib.rs` 的 `#[cfg(feature = "memory")]` 覆盖；Phase 24.2（vector_store 中 Embedding 引用隔离）待 Phase 26 验证时按需补充
+**状态**：✅ 已交付（2026-07-19，Step 1 合并）— Phase 24.3（`sqlite_store` 模块门控）+ Phase 24.4（`pub use SqliteStore` 门控）已完成；Phase 24.1（memory 模块 pub use）由 `src/lib.rs` 的 `#[cfg(feature = "memory")]` 覆盖；Phase 24.2（vector_store 中 Embedding 引用隔离）经 Phase 26 验证无需补充——`memory` feature imply `llm`，`Embedding` trait 在 `memory` 启用时一定可用

 ---

@@ -196,7 +205,7 @@
 **依赖**：Phase 20-24（全链路依赖就绪后操作）
 **优先级**：P0
 **预估规模**：约 20 行
-**状态**：✅ 部分交付（2026-07-19，Step 1 合并）— Phase 25.3（`src/lib.rs` 中 agent/engine 模块声明 cfg）已完成；Phase 25.1/25.2（agent/engine 内部子模块条件导出）由 `src/lib.rs` 顶层门控覆盖；`src/agent/session.rs` 中 engine 相关 import + `to_snapshot` / `from_snapshot` / `restore_memory` / `has_pending_memory_restore` + `pending_memory_restore` 字段加 `#[cfg(feature = "engine")]`（阻塞 B3 修复）
+**状态**：✅ 已交付（2026-07-19，Step 1 合并）— Phase 25.3（`src/lib.rs` 中 agent/engine 模块声明 cfg）已完成；Phase 25.1/25.2（agent/engine 内部子模块条件导出）由 `src/lib.rs` 顶层门控覆盖；`src/agent/session.rs` 中 engine 相关 import + `to_snapshot` / `from_snapshot` / `restore_memory` / `has_pending_memory_restore` + `pending_memory_restore` 字段加 `#[cfg(feature = "engine")]`；Phase 26 验证 `bundle()` 方法加 `#[cfg(feature = "engine")]` 门控修复 dead_code 警告

 ---

@@ -303,7 +312,7 @@ graph TD
 | **M17** | Phase 21 | 三种零依赖模块各自独立编译通过 | ✅ 2026-07-19（Step 1 合并） |
 | **M18** | Phase 22 | 5 个 provider 各自单独编译；cycle.rs 无 tools 时编译通过 | ✅ 2026-07-19（Step 1 合并） |
 | **M19** | Phase 23 | tools 不含 mcp 编译通过；加 tools-mcp 引入 McpClient | ✅ 2026-07-19（Step 1 合并） |
-| **M20** | Phase 24 | memory 不含 llm/sqlite 编译通过；加 memory-sqlite 引入 SqliteStore | ✅ 2026-07-19（Step 1 合并） |
+| **M20** | Phase 24 | memory imply document+llm 编译通过；不含 sqlite 编译通过；加 memory-sqlite 引入 SqliteStore | ✅ 2026-07-19（Step 1 合并） |
 | **M21** | Phase 25 | agent + engine 全链路门控编译通过 | ✅ 2026-07-19（Step 1 合并） |
 | **M22** | Phase 26 | 7 种 CI 组合全部编译 + 测试通过；clippy --all-features 0 警告 | ✅ 2026-07-19 |
 | **M23** | Phase 27 | 文档 review 通过 | ✅ 2026-07-19 |
@@ -342,10 +351,10 @@ default = ["full"]
 document = []
 llm-types = []
 prompt = ["llm-types"]
-llm = ["llm-types", "tokio", "async-stream", "futures-core", "tokio-stream"]
-tools = ["llm-types", "futures", "tokio-util"]
+llm = ["llm-types", "tokio", "async-stream", "futures-core", "futures-util", "tokio-stream"]
+tools = ["llm-types", "futures", "tokio-util", "tokio"]
 tools-mcp = ["tools", "reqwest"]
-memory = ["document"]
+memory = ["document", "llm", "tokio", "time"]
 memory-sqlite = ["memory", "rusqlite", "time"]
 agent = ["llm", "tools", "memory", "futures-util"]
 engine = ["agent"]
@@ -383,43 +392,85 @@ multi = ["engine", "provider-openai"]

 | 依赖 | 启用者 | 当前声明 |
 |------|--------|---------|
-| `tokio`（features = `rt, sync, time, macros, process, io-util`） | llm, tools-mcp | `optional = true` |
+| `tokio`（features = `rt, rt-multi-thread, sync, time, macros, process, io-util`） | llm, tools, memory | `optional = true` |
 | `reqwest`（features = ["json", "stream"]） | provider-*, tools-mcp | `optional = true` |
 | `rusqlite`（features = ["bundled"]） | memory-sqlite | `optional = true` |
 | `tracing-subscriber`（features = ["env-filter"]） | tracing-init | `optional = true` |
 | `tokio-stream` | llm | `optional = true` |
 | `futures` | tools | `optional = true` |
-| `futures-util` | provider-*, agent | `optional = true` |
+| `futures-util` | llm, provider-*, agent | `optional = true` |
 | `futures-core` | llm | `optional = true` |
 | `bytes` | provider-openai, provider-anthropic | `optional = true` |
 | `async-stream` | llm | `optional = true` |
 | `tokio-util`（features = ["rt"]） | tools | `optional = true` |
-| `time`（features = ["serbe","parsing","formatting","macros"]） | memory-sqlite | `optional = true` |
+| `time`（features = ["serde","parsing","formatting","macros"]） | memory, memory-sqlite | `optional = true` |

 **始终编译**（轻量依赖，不参与 feature 门控）：`serde`、`serde_json`、`thiserror`、`async-trait`、`tracing`

-### CI 测试矩阵草案
+### CI 测试矩阵（已实施）

 ```yaml
-# .github/workflows/ci.yml（或类似配置）
-matrix:
-  include:
-    - name: full
-      run: cargo test --features "full"
-    - name: light
-      run: cargo test --no-default-features --features "light"
-    - name: chat
-      run: cargo test --no-default-features --features "chat,provider-openai"
-    - name: chat+mcp
-      run: cargo test --no-default-features --features "chat,provider-openai,tools-mcp"
-    - name: multi
-      run: cargo test --no-default-features --features "multi,provider-openai"
-    - name: multi+mcp
-      run: cargo test --no-default-features --features "multi,provider-openai,tools-mcp"
-    - name: clippy
-      run: cargo clippy --all-features -- -D warnings
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+env:
+  RUSTFLAGS: "-D warnings"
+jobs:
+  test-matrix:
+    strategy:
+      fail-fast: false
+      matrix:
+        features:
+          - "full"
+          - "light"
+          - "chat,provider-openai"
+          - "chat,provider-openai,tools-mcp"
+          - "multi,provider-openai"
+          - "multi,provider-openai,tools-mcp"
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly
+      - run: cargo test --no-default-features --features "${{ matrix.features }}" --lib
+  clippy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly
+      - run: cargo clippy --all-features --lib -- -D warnings
+  format:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+      - run: cargo fmt --check
+  examples:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly
+      - run: cargo test --features "full"
 ```

+**关键设计决策**：
+- 矩阵使用 `--lib` 避免 examples 编译干扰模块测试验证
+- `RUSTFLAGS=-D warnings` 强制零警告
+- format job 使用 stable toolchain（`cargo fmt --check` 无需 nightly）
+- 独立 `examples` job 验证所有 example 在完整 features 下编译
+- 每个 job 设置 `timeout-minutes` 兜底
+
 ---

 返回总入口：[`roadmap.md`](./roadmap.md)