徐涛
be595a6771
- 在方案文档中新增 `SessionMemory` 作为会话级记忆桥接组件 - 将 AgentSession 的 `agent_name: String` 改为 `agent: Arc<dyn Agent>` - RuntimeBundle 新增 `session_memory_backend` 可选字段 - 新增 `docs/note-context-switch-design.md` 记录多 context 切换方案 - 更新 Roadmap 状态并补充 Phase 4 范围界定 - Phase 4 仅实现 SessionMemory 数据结构与 API，ContextManager 延后至 v0.2+
267 lines
13 KiB
Markdown
267 lines
13 KiB
Markdown
# AG Core Roadmap
|
||
|
||
> 定稿日期：2026-05-11
|
||
> 最后更新：2026-06-10（Phase 4 方案定稿 + SessionMemory 扩展 + Context 切换备忘）
|
||
|
||
## 愿景
|
||
|
||
AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
|
||
|
||
**当前状态**：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，Phase 4 方案文档已完成（含 SessionMemory 扩展），待编码实施。
|
||
|
||
---
|
||
|
||
## 模块完整性评估
|
||
|
||
| 功能领域 | 方案状态 | 文档位置 | 实现优先级 |
|
||
|---------|---------|---------|-----------|
|
||
| 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 运行时 | ✅ 方案已完成 | `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 4 — Agent Runtime（智能体运行时）
|
||
|
||
**目标**：实现多轮对话编排、任务规划与会话级记忆桥接。
|
||
|
||
**交付物**：
|
||
1. `agent.rs` + `agent/` 模块（8 个文件）
|
||
2. `Agent` trait — 智能体角色定义（name / system_prompt / tool_definitions）
|
||
3. `AgentSession` — 会话实例（绑定 `Arc<dyn Agent>` + `RuntimeBundle` + `SessionMemory`）
|
||
4. `RuntimeBundle` — 显式依赖注入容器（7 个字段，含 `session_memory_backend`）
|
||
5. `SessionMemory` — 会话级记忆（基于 `MemoryStore`，context 间信息桥接）
|
||
6. `TaskAgent` — 任务型智能体（规划 → 执行 → 反馈）
|
||
7. `AgentBuilder` — 链式构造入口
|
||
8. `AgentError` — 统一错误类型（聚合 LlmError / ToolError / MemoryError）
|
||
9. Hook 事件扩展（OnTurnStart / OnTurnEnd / OnPlanStepComplete）
|
||
10. `docs/7-agent-runtime.md` — 方案设计文档
|
||
|
||
**依赖**：Phase 0, 1, 2, 3（整合所有模块）
|
||
|
||
**优先级**：Could Have
|
||
|
||
**预估规模**：约 800 行代码
|
||
|
||
---
|
||
|
||
## 依赖关系图
|
||
|
||
```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
|
||
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 中已实现基础能力或在 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 4 的 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 需严格控制范围——只暴露 trait + 最小 reference impl，业务循环（多轮 turn 编排、对话记忆自动回写、Task 拆解策略）留给上层应用。`SessionMemory`（会话级记忆）已在范围内——它提供信息桥接通道但不实现 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 4 实施方案**：`docs/7-agent-runtime.md` 方案文档已完成（含 SessionMemory 扩展），下一步启动编码实现，按依赖顺序完成 13 个交付任务后翻转 Roadmap 状态
|
||
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 — 全部交付物已完成
|