From 93de86e02d56da425c0b8230012d3f37f6885e47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Mon, 11 May 2026 14:51:00 +0800 Subject: [PATCH] =?UTF-8?q?docs(specs):=20=E6=B7=BB=E5=8A=A0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AERoadmap=E6=96=87=E6=A1=A3=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specs/roadmap.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 specs/roadmap.md diff --git a/specs/roadmap.md b/specs/roadmap.md new file mode 100644 index 0000000..c350a64 --- /dev/null +++ b/specs/roadmap.md @@ -0,0 +1,179 @@ +# AG Core Roadmap + +> 定稿日期：2026-05-11 + +## 愿景 + +AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。 + +**当前状态**：代码为空壳，specs 目录有 1 份方案（LLM 调用周期）。 + +--- + +## 模块完整性评估 + +| 功能领域 | 方案状态 | 文档位置 | 实现优先级 | +|---------|---------|---------|-----------| +| LLM 调用周期 | ✅ 完整 | `specs/llm-call-lifecycle.md` | P0 | +| 提示词工程 | ❌ 缺失 | — | P1 | +| 工具系统 + 权限 | ❌ 缺失 | — | P1 | +| 记忆检索 | ❌ 缺失 | — | P2 | +| Agent 运行时 | ❌ 缺失 | — | P2 | +| 生命周期钩子 | ❌ 缺失 | — | P0（LLM Cycle 扩展） | +| Provider 注册发现 | ❌ 缺失 | — | P0（Provider 接口扩展） | +| 流式事件系统 | ❌ 缺失 | — | 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 1 — Prompt Engineering（提示词工程） + +**目标**：提供提示词的组合、模板化与优化能力。 + +**交付物**： +1. `prompt.rs` + `prompt/` 模块 +2. `PromptTemplate` — 模板引擎（支持变量插值、条件渲染） +3. `PromptComposer` — 提示词组合器（拼接 system/user/assistant 消息） +4. `specs/prompt-design.md` — 方案文档 + +**依赖**：无（可与 Phase 0 并行） + +**优先级**：Should Have + +**预估规模**：约 400 行代码 + +--- + +### Phase 2 — Tool System（工具系统） + +**目标**：实现 MCP 协议集成与自定义工具注册、调用、权限控制。 + +**交付物**： +1. `tools.rs` + `tools/` 模块 +2. `ToolRegistry` — 工具注册表（注册、发现、调用） +3. `BaseTool` trait — 工具抽象接口 +4. `McpClient` — MCP 协议客户端 +5. `PermissionChecker` — 工具执行权限检查（读/写/删除/网络等） +6. `specs/tool-call-loop.md` — Tool 自动执行循环设计 +7. 扩展 `llm/cycle.rs` 支持自动 tool 循环（参考 OpenHarness `run_query()`） + +**依赖**：Phase 0（LlmProvider 接口传递 tool definitions）、Phase 1（提示词可能需要注入工具描述） + +**优先级**：Should Have + +**预估规模**：约 900 行代码 + +--- + +### Phase 3 — Memory System（记忆系统） + +**目标**：提供对话记忆的存储、检索与管理能力。 + +**交付物**： +1. `memory.rs` + `memory/` 模块 +2. `MemoryStore` trait — 记忆存储抽象（可插拔后端） +3. `VectorStore` — 向量存储实现（支持 embedding 检索） +4. `ConversationMemory` — 对话记忆管理（sliding window / 全量） +5. `MemoryRetriever` — 记忆检索器（similarity search） +6. `specs/memory-system.md` — 方案文档 + +**依赖**：Phase 0（LLM 调用可能用于 embedding 生成） + +**优先级**：Could Have + +**预估规模**：约 700 行代码 + +--- + +### 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 行代码 + +--- + +## 依赖关系图 + +``` + Phase 4: Agent Runtime + │ + ┌─────────────────┼─────────────────┐ + ▼ ▼ ▼ + Phase 1 Phase 2 Phase 3 + Prompt Tool System Memory + Engineering + Permission System + + HookExecutor + │ │ │ + └────────┬────────┴────────┬────────┘ + ▼ ▼ + Phase 0 ─────────────────┘ + LLM Cycle + + ProviderRegistry + + HookExecutor + + StreamEvents + + Auto-compaction + (Foundation) +``` + +--- + +## 扩展计划（v0.2+） + +> 以下功能已在 Phase 0 中实现，流式接口为后续增量优化。 + +| 扩展项 | 所在模块 | 说明 | 优先级 | +|-------|---------|------|--------| +| Prompt Optimizer | `prompt` | 提示词自动优化 | P3 | + +--- + +## 风险与建议 + +1. **Phase 0 尚未实现**：项目代码是空壳，建议优先完成 LLM 调用周期，避免后续模块依赖不存在的底层 +2. **并行可能性**：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付 +3. **MCP 协议复杂性**：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节 +4. **Scope 蔓延风险**：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计 + +--- + +## 下一步行动 + +1. **Phase 0 方案评审**：对齐 LLM 模块设计（`specs/llm-call-lifecycle.md` 已在 2026-05-11 更新） +2. **Phase 1 方案启动**：启动 `specs/prompt-design.md` 设计 +3. **Phase 2 方案启动**：启动 `specs/tool-call-loop.md` 设计（含 PermissionChecker） \ No newline at end of file