agcore/docs/roadmap-v0.3.2.md

# AG Core Roadmap — v0.3.2

**状态**：✅ Phase 20-25 已交付（Step 1 合并实施）；⏳ Phase 26-27 待实施

> 本文件聚焦 **v0.3.2 版本** 的规划与交付（Phase 20–27）。
> 返回总入口：[`roadmap.md`](./roadmap.md)

> **进度更新（2026-07-19）**：Step 1 合并完成 Phase 20（Cargo.toml features 定义 + 依赖 optional 化）+ Phase 21-25 的全部 cfg 门控（因编译阻塞提前）。验证矩阵 14 条编译命令全部通过，`cargo test -F full` 427 passed。实施方案见 [`docs/26-step1-phase20-cargo-features-implementation.md`](./26-step1-phase20-cargo-features-implementation.md)。下一步：Phase 26（CI 测试矩阵）+ Phase 27（文档更新）。

## 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。

### 实施节奏：4 个 Step

将 8 个 Phase 合并为 4 个实施步骤，平衡变更风险与执行效率。

| Step | Phase | 内容 | 验证方式 | 预估行数 |
|------|-------|------|---------|---------|
| **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 1 单独成步**：Cargo.toml 是基础设施变更，编译通过后打 checkpoint，后续都是纯源文件变更。

**Step 2 合并 Phase 21–25**：全是 `#[cfg(feature = "...")]` 公式化插门控，按依赖顺序（底层模块 → LLM/Provider → Tools/MCP → Memory → Agent/Engine）实施，每插一个 feature 门控就验证。按子模块分批 commit 控制粒度。

---

### 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 行
**状态**：✅ 已交付（2026-07-19）— features 定义 + 依赖 optional 化 + tokio features 拆细（含 `rt-multi-thread` 修正）

---

### 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 行
**状态**：✅ 已交付（2026-07-19，Step 1 合并）— `src/lib.rs` 全部 `pub mod` + `pub use Document` 门控完成

---

### 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 门控需精确隔离）
**状态**：✅ 已交付（2026-07-19，Step 1 合并）— `src/llm.rs` 子模块按 llm-types/llm/provider 三类门控；`cycle.rs` 中 `ToolRegistry` import + `submit_with_tools` / `submit_with_tools_stream` / `run_tool_loop` 加 `#[cfg(feature = "tools")]`（Phase 22.7 提前）

---

### 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 行
**状态**：✅ 已交付（2026-07-19，Step 1 合并）— `src/tools.rs` 中 `pub mod mcp` + `pub use mcp::*` 加 `#[cfg(feature = "tools-mcp")]`

---

### 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 行
**状态**：✅ 部分交付（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 验证时按需补充

---

### 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 行
**状态**：✅ 部分交付（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 修复）

---

### 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,ENGINE,AGENT,LLM,TOOLS,TOOLS_MCP,MEMORY,MEMORY_SQLITE,PROMPT,LLM_TYPES,DOCUMENT,LIGHT,CHAT,MULTI done
```

## 关键里程碑

| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 |
|--------|---------------|-----------|------|
| **M16** | Phase 20 | `cargo build --no-default-features` 成功；`cargo build --features "full"` 与原行为一致 | ✅ 2026-07-19 |
| **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 合并） |
| **M21** | Phase 25 | agent + engine 全链路门控编译通过 | ✅ 2026-07-19（Step 1 合并） |
| **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)