agcore/docs/roadmap.md

AG Core Roadmap

定稿日期：2026-05-11 最后更新：2026-06-09（Phase 3 完成）

愿景

AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。

当前状态：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，等待 Phase 4 启动。

---

模块完整性评估

功能领域	方案状态	文档位置	实现优先级
LLM 调用周期	✅ 完整	specs/llm-call-lifecycle.md	P0
提示词工程	✅ 完整	docs/4-prompt-engineering.md	P1
工具系统 + 权限	✅ 完整	docs/5-tool-system.md	P1
记忆检索	✅ 完整	docs/6-memory-system.md	P2
Agent 运行时	❌ 缺失	—	P2
生命周期钩子	✅ 完整	docs/3-phase0-remaining.md	P0（LLM Cycle 扩展）
Provider 注册发现	✅ 完整	docs/3-phase0-remaining.md	P0（Provider 接口扩展）
流式事件系统	✅ 完整	docs/3-phase0-remaining.md	P0（流式接口前置）

---

分阶段 Roadmap

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 4 — Agent Runtime（智能体运行时）

目标：实现多轮对话编排与任务规划。

交付物：

1. agent.rs + agent/ 模块
2. Agent trait — 智能体接口定义
3. ConversationAgent — 对话型智能体实现
4. TaskAgent — 任务型智能体（规划 → 执行 → 反馈）
5. specs/agent-runtime.md — 方案文档

依赖：Phase 0, 1, 2, 3（整合所有模块）

优先级：Could Have

预估规模：约 600 行代码

---

依赖关系图

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
    P4["<b>Phase 4: Agent Runtime</b><br/>ConversationAgent<br/>TaskAgent"]:::pending

    P1 --> P0
    P2 --> P0
    P3 --> P0
    P2 --> P1
    P4 --> P1
    P4 --> P2
    P4 --> P3

    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
    classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a

---

扩展计划（v0.2+）

以下功能在 Phase 0 中已实现基础能力，后续可增量优化。

扩展项	所在模块	说明	优先级	状态
Prompt Optimizer	prompt	提示词自动优化	P3	待实现
流式接口优化	llm/stream	流式响应解析与事件化	P0	✅ 已完成基础实现

---

风险与建议

1. Phase 0 已完成：LLM 调用周期基础设施已全部实现，可以支撑后续模块开发
2. 并行可能性：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付
3. MCP 协议复杂性：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节
4. Scope 蔓延风险：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计

---

下一步行动

1. Phase 4 方案启动：启动 Agent Runtime 设计（依赖 Phase 0/1/2/3，整合所有模块）
2. Phase 3 备用设计就绪：docs/note-knowledge-graph-design.md 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，Phase 4 可直接参考

已完成阶段：

• ✅ Phase 0 Foundation — 全部交付物已完成
• ✅ Phase 1 Prompt Engineering — 全部交付物已完成
• ✅ Phase 2 Tool System — 全部交付物已完成
• ✅ Phase 3 Memory System — 全部交付物已完成