xt/agcore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4de7db0b2c7b3beb400eabf0143e969542e2286f
agcore/docs/roadmap.md
T

16 KiB
Raw Blame History

AG Core Roadmap

定稿日期：2026-05-11 最后更新：2026-06-11（Phase 4b 编码实施完成；Phase 4c 仍待启动）

愿景

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

当前状态：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，Phase 4a 核心胶水层已全部完成，Phase 4b 任务执行已全部完成（113 个测试通过，0 警告），Phase 4c 待启动。

模块完整性评估

功能领域 方案状态 文档位置 实现优先级
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 运行时（4a 胶水层） ✅ 已实现 docs/7-agent-runtime.md 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 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 行代码（增量）

状态：⏳ 待 Phase 4a 完成后启动

依赖关系图

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"]:::pending

    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.2+）

以下功能在已完成的 phase 中已实现基础能力或在 Phase 4 阶段明确了边界，后续可按维度增量扩展。 设计参考：见 docs/note-agent-harness-references.md（OpenClaw / Hermes / OpenHuman / OpenHarness 横向对比）。 OpenCode 借鉴：见 docs/note-opencode-agent-switching.md（Agent 切换 + System Prompt 拼接机制）。

已有扩展项（沿用）

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

v0.2+ 新增扩展项

以下为基于 Phase 4 设计讨论确定的 v0.2+ 候选扩展方向，按维度分组。 标注为"v0.2 待评估"表示在 Phase 4 完成后再决定是否启动。

Multi-Agent / 协同

扩展项 所在模块 说明 优先级 状态
Multi-Agent 协同（Swarm） agent 子 Agent 委派、并行子任务、结果聚合 P2 v0.2 待评估

技能（Skills）

扩展项 所在模块 说明 优先级 状态
Markdown 技能按需加载 agent / prompt 兼容 SKILL.md 格式（Hermes / OpenHarness 风格），按 prompt 上下文动态加载 P2 v0.2 待评估

记忆（Memory）

扩展项 所在模块 说明 优先级 状态
多通道检索（hybrid） memory/retriever 在 TextOverlap 之上叠加向量检索通道 P2 v0.2 待评估
KnowledgeGraph 深度记忆 memory 实体-关系图、note-knowledge-graph-design.md 已记录设计 P3 v0.2 待评估
TokenJuice 智能压缩 memory / llm/compact 借鉴 OpenHuman TokenJuice，对工具结果做语义压缩而非字节截断 P3 v0.2 待评估

交互层（TUI / Gateway）

扩展项 所在模块 说明 优先级 状态
TUI / 多平台 Gateway 应用层 OpenClaw / Hermes 风格的消息平台桥接（Feishu / Telegram / Discord 等） P3 v0.2+ 应用层

训练基础设施

扩展项 所在模块 说明 优先级 状态
RL 轨迹导出 agent ShareGPT 格式轨迹、Atropos 集成（Hermes 风格） P3 v0.3+ 探索

安全治理

扩展项 所在模块 说明 优先级 状态
Human-in-the-loop 审批 agent / tools/permission 高危工具执行前的异步审批回调（OpenHarness permission_prompt 模式） P2 v0.2 待评估

流式 / 实时

扩展项 所在模块 说明 优先级 状态
流式 submit_turn agent/session Phase 4 v1 只暴露非流式 submit_turn()；v0.2 包装 LlmCycle::submit_stream 暴露流式入口 P2 v0.2 待评估

Agent 切换 / Prompt 动态（OpenCode 借鉴）

扩展项 所在模块 说明 优先级 状态
Agent 身份切换（角色轮换） agent 借鉴 OpenCode Tab 键切换 build/plan：同一 AgentSession 持有可热替换的 Agent 引用，切换时不重置消息历史，在末尾追加 synthetic: true 的状态变更消息。详见 docs/note-opencode-agent-switching.md §4 P2 v0.2 待评估
System Prompt 多层动态拼接 agent/session 借鉴 OpenCode request.ts:58-66：拆分 base_prompt + agent_prompt + env_context 三层，AgentSession::submit_turn 每轮重算（不缓存），便于按 agent 类型动态切换 P2 v0.2 待评估
多 Context 切换 agent Phase 4c 的 SessionMemory 数据结构已预留信息桥接通道，v0.2+ 在其上包装 ContextManager 实现完整的多 context 切换：创建/销毁/切换 context、通过 SessionMemory 桥接关键信息。详见 docs/note-context-switch-design.md P2 v0.2 待评估

风险与建议

  1. Phase 0 已完成：LLM 调用周期基础设施已全部实现，可以支撑后续模块开发
  2. 并行可能性：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付
  3. MCP 协议复杂性：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节
  4. Scope 蔓延风险：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计
  5. Phase 4 抽象化边界：AG Core 定位为"支持库"而非"Agent 产品"，Phase 4（4a/4b/4c）需严格控制范围——只暴露 trait + 最小 reference impl，业务循环（多轮 turn 编排、对话记忆自动回写、Task 拆解策略）留给上层应用。SessionMemory（Phase 4c）提供信息桥接通道但不实现 context 切换逻辑。多 context 切换管理延后至 v0.2+。详细设计决策见 docs/7-agent-runtime.md
  6. 参考项目语言差异：OpenClaw / Hermes / OpenHarness 均为 Python/TypeScript 实现，OpenHuman 虽是 Rust + Tauri 但定位是桌面应用。借鉴时只取架构模式，不照搬具体实现（如 Pydantic 工具校验、SQLite Memory Tree、Node+Python 双进程等）

下一步行动

  1. Phase 4c 启动评估：Phase 4a + 4b 已交付（113 测试通过，0 clippy 警告）。可启动 Phase 4c（会话级记忆：SessionMemory + RuntimeBundle/Builder 扩展 + AgentSession 接入）
  2. Context 切换备忘：docs/note-context-switch-design.md 记录了多 context 切换方案讨论，作为 v0.2+ 扩展项的输入
  3. 参考项目调研沉淀：已完成 OpenClaw / Hermes / OpenHuman / OpenHarness 横向调研，结果沉淀至 docs/note-agent-harness-references.md，作为 v0.2+ 扩展项的输入
  4. Phase 3 备用设计就绪：docs/note-knowledge-graph-design.md 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，v0.2+ 记忆扩展可直接参考

已完成 / 进行中阶段：

  • ✅ Phase 0 Foundation — 全部交付物已完成
  • ✅ Phase 1 Prompt Engineering — 全部交付物已完成
  • ✅ Phase 2 Tool System — 全部交付物已完成
  • ✅ Phase 3 Memory System — 全部交付物已完成
  • ✅ Phase 4a Core Glue — 全部交付物已完成
  • ✅ Phase 4b Task Execution — 全部交付物已完成
  • ⏳ Phase 4c Session Memory — 依赖 4a
Reference in New Issue View Git Blame Copy Permalink