徐涛
243 lines
10 KiB
Markdown
243 lines
10 KiB
Markdown
# AG Core Roadmap — v0.1.0
|
||
|
||
> 本文件聚焦 **v0.1.0 版本** 的规划与交付（Phase 0–4c），已于 2026-07-04 完成发布。
|
||
> 返回总入口：[`roadmap.md`](./roadmap.md)
|
||
|
||
## v0.1.0 愿景
|
||
|
||
AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
|
||
|
||
## v0.1.0 总体范围
|
||
|
||
**总体规模**：5 个主体 Phase（Phase 0–4c）+ Provider IR 重构 + LlmCycle 简化 + v0.1 Release 收尾，182 个测试全绿，clippy 0 警告，7 个离线示例全 exit 0。
|
||
|
||
---
|
||
|
||
### Phase 0 — Foundation（基础设施）
|
||
|
||
**目标**：实现 LLM 调用周期的核心功能，作为所有上层模块的基础。
|
||
|
||
**交付物**：
|
||
1. ✅ `llm/types.rs` — 核心数据类型（Message, ContentBlock, ChatRequest/Response, ToolDefinition, StopReason）
|
||
2. ✅ `llm/error.rs` — 错误体系（LlmError 枚举，可重试/不可重试判断）
|
||
3. ✅ `llm/provider.rs` + `llm/provider/openai.rs` — Provider 接口 + OpenAI 兼容实现
|
||
4. ✅ `llm/provider/registry.rs` — ProviderRegistry（多 Provider 注册发现）
|
||
5. ✅ `llm/cycle.rs` + `llm/cycle/{retry,usage}.rs` — 生命周期引擎（重试策略 + 用量追踪）
|
||
6. ✅ `llm/hooks.rs` — HookExecutor 接口（生命周期钩子）
|
||
7. ✅ `llm/stream.rs` — StreamEvents 流式事件系统（AssistantTextDelta, ToolExecutionStarted 等）
|
||
8. ✅ `llm/compact.rs` — Auto-compaction（上下文自动压缩）
|
||
9. ✅ `Cargo.toml` — 添加依赖（tokio, reqwest, serde, thiserror, async-trait, tracing）
|
||
|
||
**依赖**：无
|
||
|
||
**优先级**：Must Have
|
||
|
||
**预估规模**：约 1000 行核心代码
|
||
|
||
**状态**：✅ Phase 0 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 1 — Prompt Engineering（提示词工程）
|
||
|
||
**目标**：提供提示词的组合、模板化与优化能力。
|
||
|
||
**交付物**：
|
||
1. ✅ `prompt.rs` + `prompt/` 模块
|
||
2. ✅ `PromptTemplate` — 模板引擎（支持变量插值、条件渲染）
|
||
3. ✅ `PromptComposer` — 提示词组合器（拼接 system/user/assistant 消息）
|
||
4. ✅ `docs/4-prompt-engineering.md` — 方案文档
|
||
|
||
**依赖**：无（可与 Phase 0 并行）
|
||
|
||
**优先级**：Should Have
|
||
|
||
**预估规模**：约 400 行代码
|
||
|
||
**状态**：✅ Phase 1 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 2 — Tool System（工具系统）
|
||
|
||
**目标**：实现 MCP 协议集成与自定义工具注册、调用、权限控制。
|
||
|
||
**交付物**：
|
||
1. ✅ `tools.rs` + `tools/` 模块（base/registry/permission/mcp/error）
|
||
2. ✅ `ToolRegistry` — 工具注册表（注册、发现、调用、并行执行、超时控制）
|
||
3. ✅ `BaseTool` trait — 工具抽象接口（含 ToolContext 执行上下文）
|
||
4. ✅ `McpClient` — MCP 协议客户端（stdio transport，StreamableHttp 预留）
|
||
5. ✅ `PermissionChecker` — 工具执行权限检查（白名单/黑名单/自定义权限）
|
||
6. ✅ `docs/5-tool-system.md` — 方案设计文档
|
||
7. ✅ 扩展 `llm/cycle.rs` 支持自动 tool 循环（`submit_with_tools()` + `submit_request()` + `maybe_compact()`）
|
||
8. ✅ `ToolError` — 结构化错误体系（含 `is_recoverable()` 分类）
|
||
|
||
**依赖**：Phase 0（LlmProvider 接口传递 tool definitions）、Phase 1（提示词可能需要注入工具描述）
|
||
|
||
**优先级**：Should Have
|
||
|
||
**预估规模**：约 900 行代码（实际约 1500 行）
|
||
|
||
**状态**：✅ Phase 2 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 3 — Memory System（记忆系统）
|
||
|
||
**目标**：提供对话记忆的存储、检索与管理能力。
|
||
|
||
**交付物**：
|
||
1. ✅ `memory.rs` + `memory/` 模块（store / conversation / knowledge / retriever / error / types）
|
||
2. ✅ `MemoryStore` trait + `InMemoryStore` — 记忆存储抽象（可插拔后端）+ 默认实现
|
||
3. ✅ `ConversationMemory` — 对话记忆管理（sliding window / 全量），复用 `llm::compact`
|
||
4. ✅ `KnowledgeStore` — 知识页面存储（具体 struct，非 trait，基于 MemoryStore）
|
||
5. ✅ `MemoryRetriever` — 记忆检索器（TextOverlap Dice 系数评分，单通道）
|
||
6. ✅ `docs/6-memory-system.md` — 方案设计文档
|
||
7. ✅ `docs/note-knowledge-graph-design.md` — KnowledgeGraph 等 Phase 4 备用设计
|
||
8. ✅ `EvictionPolicy` — 支持 None / Ttl / Capacity 三种淘汰策略
|
||
|
||
**依赖**：Phase 0（llm::compact 复用）、Cargo.toml 新增 `time` 依赖
|
||
|
||
**优先级**：Could Have
|
||
|
||
**预估规模**：约 700 行代码（实际约 1242 行，含测试）
|
||
|
||
**状态**：✅ Phase 3 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 4a — Agent Core Glue（核心胶水层）
|
||
|
||
**目标**：提供最小可用的 Agent Runtime——把 Phase 0-3 的能力"装配"成 `AgentSession::submit_turn`。上层可基于 4a 构建多轮对话应用。
|
||
|
||
**交付物**：
|
||
1. ✅ `agent.rs` + `agent/` 模块（7 个文件：agent/error/runtime/builder/session/task + 模块根）
|
||
2. ✅ `Agent` trait — 智能体角色定义（name / system_prompt / tool_definitions）
|
||
3. ✅ `AgentSession` — 会话实例（绑定 `Arc<dyn Agent>` + `RuntimeBundle` + 内联 HashMap session_data）
|
||
4. ✅ `RuntimeBundle` — 显式依赖注入容器（不含 session_memory_backend）
|
||
5. ✅ `AgentBuilder` — 链式构造入口（不含 session_memory_backend）
|
||
6. ✅ `AgentError` — 统一错误类型（7 个变体：Llm / Tool / Memory / HookBlocked / LimitExceeded / Config / Other；不含 PlanParse）
|
||
7. ✅ `Plan` / `Step` / `StepStatus` — 纯数据结构（不含任何解析逻辑）
|
||
8. ✅ Hook 事件扩展：OnTurnStart / OnTurnEnd + turn_index 字段
|
||
9. ✅ `docs/7-agent-runtime.md` — 方案设计文档（含 4a/4b/4c 分阶段计划）
|
||
|
||
**实际新增**：
|
||
- 新增文件 7 个（agent.rs + agent/{agent, error, runtime, builder, session, task}.rs）
|
||
- 修改文件 3 个（lib.rs +1 行；llm/hooks.rs +13 行追加变体/字段；llm/cycle.rs 内部字段 Box→Arc + 新增 `new_with_arc` 公共方法）
|
||
- 实际代码量约 800 行（含测试；纯实现约 470 行——略高于方案预估 440 行，因 AgentSession 的 tests 模块内联 MockProvider/StubAgent 等辅助结构）
|
||
- 新增内联测试 22 个；全量测试 84 → 109（0 失败）
|
||
- clippy 0 警告（agent 模块）
|
||
- 无新增外部依赖
|
||
|
||
**依赖**：Phase 0, 1, 2, 3
|
||
|
||
**优先级**：Could Have
|
||
|
||
**预估规模**：约 440 行代码
|
||
|
||
**状态**：✅ Phase 4a 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 4b — Task Execution（任务执行）
|
||
|
||
**目标**：在 Phase 4a 基础上，赋予智能体"拆解目标 → 逐步执行"的能力。
|
||
|
||
**前置条件**：Phase 4a 已完成。
|
||
|
||
**交付物**：
|
||
1. ✅ `TaskAgent` trait — `run(goal)` 自主式 + `execute_plan(plan)` 外部驱动式
|
||
2. ✅ `PlanParser` trait + `JsonPlanParser` 参考实现
|
||
3. ✅ `AgentError` 追加 PlanParse 变体（共 7 个变体）
|
||
4. ✅ Hook 事件扩展：OnPlanStepComplete + plan_step_index 字段
|
||
|
||
**依赖**：Phase 4a
|
||
|
||
**优先级**：Could Have
|
||
|
||
**预估规模**：约 200 行代码（增量）
|
||
|
||
**实际新增**：
|
||
- 修改文件 2 个（llm/hooks.rs +5 行；agent/error.rs +10 行）
|
||
- 新增代码约 150 行（含测试；纯实现约 90 行）
|
||
- 新增内联测试 4 个；全量测试 109 → 113（0 失败）
|
||
- clippy 0 警告
|
||
- 无新增外部依赖
|
||
|
||
**状态**：✅ Phase 4b 全部交付物已完成
|
||
|
||
---
|
||
|
||
### Phase 4c — Session Memory（会话级记忆）
|
||
|
||
**目标**：提供会话级 key-value 记忆，作为 session 内各 context 之间的信息桥接通道。
|
||
|
||
**前置条件**：Phase 4a 已完成（可与 Phase 4b 并行）。
|
||
|
||
**交付物**：
|
||
1. ✅ `SessionMemory` struct — 基于 `MemoryStore`，按 session_id namespace 隔离
|
||
2. ✅ `RuntimeBundle` + `AgentBuilder` 扩展 `session_memory_backend` 字段
|
||
3. ✅ `AgentSession` 替换内联 HashMap 为完整 `SessionMemory`
|
||
|
||
**依赖**：Phase 4a（Phase 3 MemoryStore）
|
||
|
||
**优先级**：Could Have
|
||
|
||
**预估规模**：约 115 行代码（增量）
|
||
|
||
**实际新增**：
|
||
- 新增文件 1 个（agent/session_memory.rs）
|
||
- 修改文件 4 个（agent/runtime.rs +5 行；agent/builder.rs +10 行；agent/session.rs +30 行；agent.rs +2 行）
|
||
- 新增代码约 180 行（含测试；纯实现约 100 行）
|
||
- 新增内联测试 3 个；全量测试 113 → 116（0 失败）
|
||
- clippy 0 警告
|
||
- 无新增外部依赖
|
||
|
||
**状态**：✅ Phase 4c 全部交付物已完成
|
||
|
||
---
|
||
```mermaid
|
||
graph BT
|
||
P0["<b>Phase 0: Foundation</b><br/>LLM Cycle<br/>ProviderRegistry<br/>HookExecutor<br/>StreamEvents<br/>Auto-compaction"]:::done
|
||
P1["<b>Phase 1: Prompt Engineering</b><br/>PromptTemplate<br/>PromptComposer"]:::done
|
||
P2["<b>Phase 2: Tool System</b><br/>Tool Registry<br/>PermissionChecker<br/>MCP Client"]:::done
|
||
P3["<b>Phase 3: Memory System</b><br/>MemoryStore<br/>ConversationMemory<br/>KnowledgeStore"]:::done
|
||
P4a["<b>Phase 4a: Core Glue</b><br/>AgentSession<br/>RuntimeBundle<br/>Plan/Step 纯数据"]:::done
|
||
P4b["<b>Phase 4b: Task Execution</b><br/>TaskAgent<br/>PlanParser<br/>JsonPlanParser"]:::done
|
||
P4c["<b>Phase 4c: Session Memory</b><br/>SessionMemory"]:::done
|
||
|
||
P1 --> P0
|
||
P2 --> P0
|
||
P3 --> P0
|
||
P2 --> P1
|
||
P4a --> P1
|
||
P4a --> P2
|
||
P4a --> P3
|
||
P4b --> P4a
|
||
P4c --> P4a
|
||
|
||
classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
|
||
classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
|
||
```
|
||
|
||
---
|
||
|
||
## v0.1 发布里程碑（2026-07-04）
|
||
|
||
**质量基线**：
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| `cargo build --all-targets` | ✅ 通过 |
|
||
| `cargo test --all-targets` | ✅ **182 passed / 0 failed** |
|
||
| `cargo clippy --all-targets -- -D warnings` | ✅ 0 警告 |
|
||
| 离线示例（`cargo run --example`） | ✅ 7 个全部 exit 0 |
|
||
|
||
**关键交付**：
|
||
1. **Provider IR 重构** — 统一 `Message` / `ContentBlock` / `MessageRequest` / `MessageResponse` 类型层；4 个 Provider 适配（OpenAI Chat / Anthropic Messages / DeepSeek / Qwen）；`LlmProvider` trait 签名同步切换
|
||
2. **LlmCycle 简化** — `LlmCycle` 内部消息类型切到 IR 层；移除 Phase 0 的 `OpenaiChatMessage ↔ Message` 桥接；测试从 116 → 182（含 provider 测试）
|
||
3. **`MockProvider` 公开化** — `agcore::llm::mock::MockProvider` 支持 `chat` + `chat_stream`，无需 API key 即可运行示例
|
||
4. **7 个离线示例** — `prompt_composer` / `custom_tool` / `agent_session_demo` / `task_agent_demo` / `conversation_memory_demo` / `knowledge_search_demo` / `streaming_events_demo`
|
||
5. **错误消息友好化** — `AgentError` / `LlmError` / `ToolError` / `MemoryError` / `PromptError` 全部面向最终用户改写（给出可操作的建议）
|
||
6. **文档完整** — README 完整版（快速上手 + 架构图 + 环境变量）、Apache-2.0 LICENSE
|