From 703151e363754539b8589c6a6d9b0787fba78bfa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Sat, 18 Jul 2026 08:16:38 +0800 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20=E5=A2=9E=E8=A1=A5=20v0.3.2=20?= =?UTF-8?q?Cargo=20features=20=E6=8B=86=E5=88=86=E8=B7=AF=E7=BA=BF?= =?UTF-8?q?=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 16 个 feature（10 模块级 + 5 provider + 1 工具）+ 4 个快捷组合 - agent 不再 imply tools-mcp，MCP 作为可选依赖由用户显式启用 - tokio features 拆细为 rt/sync/time/macros/process/io-util - 8 个 Phase 实施计划（Phase 20-27）+ 7 种 CI 矩阵组合 - default = ["full"] 保持向后兼容，非破坏性变更 --- docs/roadmap-v0.3.2.md | 408 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 docs/roadmap-v0.3.2.md diff --git a/docs/roadmap-v0.3.2.md b/docs/roadmap-v0.3.2.md new file mode 100644 index 0000000..89879f4 --- /dev/null +++ b/docs/roadmap-v0.3.2.md @@ -0,0 +1,408 @@ +# AG Core Roadmap — v0.3.2 + +**状态**：⏳ 全部待实施 + +> 本文件聚焦 **v0.3.2 版本** 的规划与交付（Phase 20–27）。 +> 返回总入口：[`roadmap.md`](./roadmap.md) + +## v0.3.2 愿景 + +通过 Cargo features 拆分，让下游按需选择模块，跳过不需要的编译单元和重型依赖。 + +## v0.3.2 总体范围 + +**版本等级**：patch（v0.3.2），`default = ["full"]` 保持向后兼容，非破坏性变更。 + +**改造基线**：v0.3.0 已交付 23,718 行 Rust 代码，66 个源文件。当前所有依赖全量编译——引用 agcore 就意味着拉入 rusqlite bundled、reqwest、tokio full 等全部重型依赖。 + +**改造目标**：16 个 features（10 模块级 + 5 provider + 1 工具）+ 4 个快捷组合。下游可只选 `chat` 组合跳过 SQLite 和 MCP 的编译，或只选 `document` 实现纯文档分割零外部依赖。 + +**工作性质**：纯 cfg 门控 + Cargo.toml 配置变更，不新增功能代码。 + +**总体规模**：8 个增量 Phase（Phase 20–27），预计新增/修改约 330 行配置与条件编译代码。 + +--- + +## 功能清单 + +### 模块级 features（10 个） + +| Feature | 覆盖内容 | imply | 外部依赖成本 | +|---------|---------|-------|-------------| +| `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 | +| `tools-mcp` | McpClient（Stdio/StreamableHttp） | `tools` | reqwest | +| `memory` | MemoryStore(InMemory) + Conversation + VectorStore(InMemory) + KnowledgeGraph + Retriever | `document` | 无新增 | +| `memory-sqlite` | SqliteStore | `memory` | rusqlite (bundled), time | +| `agent` | Agent + Builder + Session + ContextSlot + Summary | `llm` + `tools` + `memory` | 继承下层 | +| `engine` | SessionManager + Checkpointer + SubAgent + Switch | `agent` | 继承下层 | + +### Provider features（5 个，各自独立） + +| Feature | imply | 外部依赖 | +|---------|-------|---------| +| `provider-openai` | `llm` | reqwest + bytes + futures-util | +| `provider-anthropic` | `llm` | reqwest + bytes + futures-util | +| `provider-deepseek` | `llm` | reqwest | +| `provider-qwen` | `llm` | reqwest | +| `provider-ollama` | `llm` | reqwest | + +### 工具 features（1 个） + +| Feature | 控制 | 依赖 | +|---------|------|------| +| `tracing-init` | `init_tracing()` 函数 | tracing-subscriber | + +### 快捷组合（4 个） + +| 组合 | 定义 | 场景 | +|------|------|------| +| `full`（default） | 全部 16 个 feature | 全栈（兼容 v0.3） | +| `light` | llm + provider-openai + tools + tools-mcp + memory + agent + engine + prompt + document | 生产常用 | +| `chat` | agent + provider-openai | 纯对话（context+session+轻量记忆，跳过 SQLite；MCP 按需加 `tools-mcp`） | +| `multi` | engine + provider-openai | 多 Agent 复合（chat + subagent + switch + checkpointer；MCP 按需加 `tools-mcp`） | + +--- + +## 实施计划 — 8 个增量 Phase + +> **编号说明**：Phase 20-27 接续 v0.3.0 的 Phase 13-19。 + +### Phase 20: Cargo.toml 基础设施改造 + +**目标**：定义完整的 [features] 表，重型依赖改为 optional，建立 imply 链。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **20.1** | 定义 16 个 features + 4 个快捷组合，`default = ["full"]` | `Cargo.toml` | `cargo build --features "full"` 编译通过，行为与原版一致 | +| **20.2** | tokio / reqwest / rusqlite / tracing-subscriber 改为 optional | `Cargo.toml` | `cargo build --no-default-features` 成功（空 crate） | +| **20.3** | tokio-stream / futures / futures-util / futures-core / bytes / async-stream / tokio-util / time 改为 optional | `Cargo.toml` | `cargo build --features "full"` 全量依赖正确拉取 | +| **20.4** | tokio features 拆细：从 `["full"]` 改为 `["rt", "sync", "time", "macros", "process", "io-util"]`，仅保留实际使用的子模块 | `Cargo.toml` | `cargo build --features "llm,provider-openai"` 不拉入 tokio net/http 等无关子模块 | +| **20.5** | feature imply 链配置：`prompt → llm-types`，`llm → llm-types`，`tools → llm-types`，`memory → document`，`agent → llm + tools + memory`（不含 tools-mcp），`engine → agent` | `Cargo.toml` | `cargo build --features "agent,provider-openai"` transitive 依赖自动拉取 | + +**依赖**：无（Cargo.toml 独立改造） +**优先级**：P0 +**预估规模**：约 40 行 +**状态**：⏳ 待实施 + +--- + +### Phase 21: 底层模块 cfg 门控注入 + +**目标**：为 llm-types、document、prompt 三个零/低外部依赖模块添加条件编译门控。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **21.1** | `src/lib.rs` 中所有 `pub mod` 声明加 `#[cfg(feature = "...")]` | `src/lib.rs` | `cargo build --no-default-features` 无模块引入 | +| **21.2** | llm-types 模块条件编译 + 公共类型条件导出 | `src/llm/types/` | `cargo build --no-default-features --features "llm-types"` 编译通过 | +| **21.3** | document 模块条件编译 + `pub use Document` 条件导出 | `src/document.rs` | `cargo build --no-default-features --features "document"` 编译通过 | +| **21.4** | prompt 模块条件编译 | `src/prompt.rs` | `cargo build --no-default-features --features "prompt"` 编译通过 | + +**依赖**：Phase 20（需 feature 定义就绪） +**优先级**：P0 +**预估规模**：约 30 行 +**状态**：⏳ 待实施 + +--- + +### Phase 22: LLM + Provider 门控注入 + +**目标**：llm 模块整体门控 + 5 个 Provider 独立条件编译 + cycle.rs 中 ToolRegistry 引用的 `#[cfg]` 隔离。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **22.1** | llm 模块 cfg + embedding 子模块条件导出 + MockProvider 条件编译 | `src/llm.rs` | `cargo build --no-default-features --features "llm"` 编译通过 | +| **22.2** | `create_provider()` + `build_client_*` 条件编译，按 feature 分别暴露 | `src/llm/provider.rs` | 各 provider feature 单独启用 | +| **22.3** | OpenAI provider `#[cfg(feature = "provider-openai")]` | `src/llm/provider/openai.rs` | `--features "llm,provider-openai"` 编译通过；不含时不编译 | +| **22.4** | Anthropic provider 条件编译 | `src/llm/provider/anthropic.rs` | `--features "llm,provider-anthropic"` 编译通过 | +| **22.5** | DeepSeek + Qwen 共享 `openai_compat.rs` 用 `any(feature = "provider-deepseek", feature = "provider-qwen")` 条件 | `src/llm/provider/openai_compat.rs` | 各自单独编译通过 | +| **22.6** | Ollama provider 条件编译 | `src/llm/provider/ollama.rs` | `--features "llm,provider-ollama"` 编译通过 | +| **22.7** | `cycle.rs` 中 ToolRegistry 引用 + `submit_with_tools` 系列方法 `#[cfg(feature = "tools")]` | `src/llm/cycle.rs` | `--features "llm,provider-openai"` 不含 tools 编译通过 | + +**依赖**：Phase 20 + Phase 21 +**优先级**：P0 +**预估规模**：约 80 行（中复杂度，cycle.rs 门控需精确隔离） +**状态**：⏳ 待实施 + +--- + +### Phase 23: Tools + MCP 门控注入 + +**目标**：tools 模块整体门控 + mcp 子模块条件编译。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **23.1** | tools 模块 cfg + pub use 条件导出 | `src/tools.rs` | `--features "tools"` 编译通过；不含时不编译 | +| **23.2** | `mcp.rs` 整个文件 `#[cfg(feature = "tools-mcp")]` | `src/tools/mcp.rs` | `--features "tools"` 不含 mcp 时编译通过；加 `tools-mcp` 时引入 | +| **23.3** | ToolRegistry 中 McpClient 引用的条件导出 | `src/tools/registry.rs` | `--features "tools"` 不含 mcp 编译通过 | + +**依赖**：Phase 20 + Phase 21 +**优先级**：P0 +**预估规模**：约 20 行 +**状态**：⏳ 待实施 + +--- + +### Phase 24: Memory 门控注入 + +**目标**：memory 模块门控 + vector_store 中 Embedding 引用隔离 + SqliteStore 可选化。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **24.1** | memory 模块 cfg + pub use 条件导出 | `src/memory.rs` | `--features "memory"` imply document 编译通过 | +| **24.2** | vector_store 中 Embedding trait 引用 `#[cfg(feature = "llm")]` | `src/memory/vector_store.rs` | `--features "memory"` 不含 `llm` 编译通过 | +| **24.3** | `sqlite_store.rs` 整个文件 `#[cfg(feature = "memory-sqlite")]` | `src/memory/store/sqlite_store.rs` | `--features "memory"` 不含 sqlite 编译通过 | +| **24.4** | `memory.rs` 中 `pub use SqliteStore` 条件导出 | `src/memory.rs` | `--features "memory-sqlite"` 正确导出 SqliteStore | + +**依赖**：Phase 20 + Phase 21 +**优先级**：P0 +**预估规模**：约 30 行 +**状态**：⏳ 待实施 + +--- + +### Phase 25: Agent + Engine 门控注入 + +**目标**：agent 和 engine 两个高层模块的条件编译门控。注意 agent 不再 imply tools-mcp——MCP 作为可选工具层由用户显式启用。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **25.1** | agent 模块 cfg + pub use 条件导出 | `src/agent.rs` | `--features "agent,provider-openai"` 编译通过 | +| **25.2** | engine 模块 cfg + 子模块条件导出（switch / sub_agent / checkpointer） | `src/engine/` | `--features "engine,provider-openai"` 编译通过 | +| **25.3** | `lib.rs` 中 agent / engine 模块声明 cfg + 条件重导出 | `src/lib.rs` | 验证 `engine` imply `agent` 链正确，transitive 依赖完整 | + +**依赖**：Phase 20-24（全链路依赖就绪后操作） +**优先级**：P0 +**预估规模**：约 20 行 +**状态**：⏳ 待实施 + +--- + +### Phase 26: 快捷组合验证 + 测试矩阵 + +**目标**：验证 4 个快捷组合 + clippy 完整性检查。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **26.1** | `default = ["full"]` 回归验证 | CI | `cargo test --features "full"` 全绿（427 passed） | +| **26.2** | light 组合编译 + 单元测试 | CI | `cargo test --no-default-features --features "light"` 通过 | +| **26.3** | chat 组合（无 MCP）编译 + 单元测试 | CI | `cargo test --no-default-features --features "chat,provider-openai"` 通过 | +| **26.4** | chat + MCP 组合编译 + 单元测试 | CI | `cargo test --no-default-features --features "chat,provider-openai,tools-mcp"` 通过 | +| **26.5** | multi 组合（无 MCP）编译 + 单元测试 | CI | `cargo test --no-default-features --features "multi,provider-openai"` 通过 | +| **26.6** | multi + MCP 组合编译 + 单元测试 | CI | `cargo test --no-default-features --features "multi,provider-openai,tools-mcp"` 通过 | +| **26.7** | clippy `--all-features` 无警告 | CI | `cargo clippy --all-features -- -D warnings` 0 警告 | +| **26.8** | 修复各组合编译中发现的 cfg 遗漏 | 全量 | 7 种组合全部编译 + 测试通过 | + +**依赖**：Phase 20-25（所有门控就绪） +**优先级**：P0 +**预估规模**：约 10 行（CI 配置） +**状态**：⏳ 待实施 + +--- + +### Phase 27: 文档更新 + 示例标注 + README feature 表 + +**目标**：让下游使用者能快速理解 feature 体系并选择合适组合。 + +| Step | 内容 | 文件范围 | 验证标准 | +|------|------|---------|---------| +| **27.1** | README.md 添加 feature 表格 + `Cargo.toml` 使用示例 + 各组合推荐场景 | `README.md` | review 通过 | +| **27.2** | 各示例文件顶部添加所需的 feature 组合标注注释 | `examples/*.rs` | review 通过 | +| **27.3** | 更新 `docs/roadmap.md` 总入口添加 v0.3.2 链接和简要状态 | `docs/roadmap.md` | review 通过 | + +**依赖**：Phase 20-26 +**优先级**：P0 +**预估规模**：约 100 行 +**状态**：⏳ 待实施 + +--- + +## Feature 依赖关系图 + +```mermaid +graph TD + subgraph "快捷组合" + FULL["full (default)"] + LIGHT["light"] + CHAT["chat"] + MULTI["multi"] + end + + subgraph "模块级" + ENGINE["engine"] + AGENT["agent"] + LLM["llm"] + TOOLS["tools"] + TOOLS_MCP["tools-mcp"] + MEMORY["memory"] + MEMORY_SQLITE["memory-sqlite"] + PROMPT["prompt"] + LLM_TYPES["llm-types"] + DOCUMENT["document"] + end + + subgraph "Provider" + P_OPENAI["provider-openai"] + P_ANTHROPIC["provider-anthropic"] + P_DEEPSEEK["provider-deepseek"] + P_QWEN["provider-qwen"] + P_OLLAMA["provider-ollama"] + end + + FULL --> LIGHT & CHAT & MULTI + ENGINE --> AGENT + AGENT --> LLM & TOOLS & MEMORY + CHAT -.-> TOOLS_MCP + MULTI -.-> TOOLS_MCP + MEMORY_SQLITE --> MEMORY + TOOLS_MCP --> TOOLS + MEMORY --> DOCUMENT + LLM --> LLM_TYPES + TOOLS --> LLM_TYPES + PROMPT --> LLM_TYPES + P_OPENAI --> LLM + P_ANTHROPIC --> LLM + P_DEEPSEEK --> LLM + P_QWEN --> LLM + P_OLLAMA --> LLM + + classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a + classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a + classDef provider fill:#93c5fd,stroke:#2563eb,color:#1a1a1a + class P_OPENAI,P_ANTHROPIC,P_DEEPSEEK,P_QWEN,P_OLLAMA provider + class FULL pending + class ENGINE,AGENT,LLM,TOOLS,TOOLS_MCP,MEMORY,MEMORY_SQLITE,PROMPT,LLM_TYPES,DOCUMENT pending + class LIGHT,CHAT,MULTI pending +``` + +## 关键里程碑 + +| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 | +|--------|---------------|-----------|------| +| **M16** | Phase 20 | `cargo build --no-default-features` 成功；`cargo build --features "full"` 与原行为一致 | ⏳ | +| **M17** | Phase 21 | 三种零依赖模块各自独立编译通过 | ⏳ | +| **M18** | Phase 22 | 5 个 provider 各自单独编译；cycle.rs 无 tools 时编译通过 | ⏳ | +| **M19** | Phase 23 | tools 不含 mcp 编译通过；加 tools-mcp 引入 McpClient | ⏳ | +| **M20** | Phase 24 | memory 不含 llm/sqlite 编译通过；加 memory-sqlite 引入 SqliteStore | ⏳ | +| **M21** | Phase 25 | agent + engine 全链路门控编译通过 | ⏳ | +| **M22** | Phase 26 | 7 种 CI 组合全部编译 + 测试通过；clippy --all-features 0 警告 | ⏳ | +| **M23** | Phase 27 | 文档 review 通过 | ⏳ | + +## Cargo.toml [features] 草案 + +```toml +[dependencies] +# 轻量核心依赖（始终编译） +serde = { version = "1", features = ["derive"] } +serde_json = "1" +thiserror = "2" +async-trait = "0.1" +tracing = "0.1" + +# 按 feature 可选的重依赖 +tokio = { version = "1", features = ["rt", "sync", "time", "macros", "process", "io-util"], optional = true } +reqwest = { version = "0.12", features = ["json", "stream"], optional = true } +rusqlite = { version = "0.32", features = ["bundled"], optional = true } +tracing-subscriber = { version = "0.3", features = ["env-filter"], optional = true } +tokio-stream = { version = "0.1", optional = true } +futures = { version = "0.3", optional = true } +futures-util = { version = "0.3", optional = true } +futures-core = { version = "0.3", optional = true } +bytes = { version = "1", optional = true } +async-stream = { version = "0.3", optional = true } +tokio-util = { version = "0.7", features = ["rt"], optional = true } +time = { version = "0.3", features = ["serde", "parsing", "formatting", "macros"], optional = true } +``` + +```toml +[features] +default = ["full"] + +# === 模块级 features === +document = [] +llm-types = [] +prompt = ["llm-types"] +llm = ["llm-types", "tokio", "async-stream", "futures-core", "tokio-stream"] +tools = ["llm-types", "futures", "tokio-util"] +tools-mcp = ["tools", "reqwest"] +memory = ["document"] +memory-sqlite = ["memory", "rusqlite", "time"] +agent = ["llm", "tools", "memory", "futures-util"] +engine = ["agent"] + +# === Provider features === +provider-openai = ["llm", "reqwest", "bytes", "futures-util"] +provider-anthropic = ["llm", "reqwest", "bytes", "futures-util"] +provider-deepseek = ["llm", "reqwest"] +provider-qwen = ["llm", "reqwest"] +provider-ollama = ["llm", "reqwest"] + +# === 工具 features === +tracing-init = ["tracing-subscriber"] + +# === 快捷组合 === +full = [ + "document", "llm-types", "prompt", "llm", + "tools", "tools-mcp", + "memory", "memory-sqlite", + "agent", "engine", + "provider-openai", "provider-anthropic", "provider-deepseek", + "provider-qwen", "provider-ollama", + "tracing-init", +] +light = [ + "llm", "provider-openai", "tools", "tools-mcp", + "memory", "agent", "engine", + "prompt", "document", +] +chat = ["agent", "provider-openai"] +multi = ["engine", "provider-openai"] +``` + +### 依赖 optional 化对照 + +| 依赖 | 启用者 | 当前声明 | +|------|--------|---------| +| `tokio`（features = `rt, sync, time, macros, process, io-util`） | llm, tools-mcp | `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-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` | + +**始终编译**（轻量依赖，不参与 feature 门控）：`serde`、`serde_json`、`thiserror`、`async-trait`、`tracing` + +### 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 +``` + +--- + +返回总入口：[`roadmap.md`](./roadmap.md)