徐涛
336 lines
13 KiB
Markdown
336 lines
13 KiB
Markdown
# Phase 4 Agent Runtime — 设计决策记录
|
||
|
||
> 决策固化日期：2026-06-09
|
||
> 用途：记录 Phase 4 设计阶段的关键决策、接口签名草案、文件清单，作为 `docs/7-agent-runtime.md` 方案文档的输入约束。
|
||
> 关联：
|
||
> - `docs/7-agent-runtime.md` — 完整方案文档（待写 / 已写）
|
||
> - `docs/note-agent-harness-references.md` — 参考项目调研（OpenClaw / Hermes / OpenHuman / OpenHarness）
|
||
> - `docs/roadmap.md` — 项目总 Roadmap
|
||
> - `docs/2-llm-call-lifecycle.md` / `3-phase0-remaining.md` / `4-prompt-engineering.md` / `5-tool-system.md` / `6-memory-system.md` — Phase 0-3 方案
|
||
|
||
本文件是 Phase 4 设计阶段的"事实基础"——所有决策都有明确的对话出处与依据。后续 Phase 4 实施时应与本记录保持一致；如需调整，应先更新本记录再改代码。
|
||
|
||
---
|
||
|
||
## 1. 设计目标
|
||
|
||
AG Core Phase 4 的定位是**「Phase 0-3 的薄胶水层 + 一组 trait 抽象」**，遵循 OpenHarness 的"显式依赖注入"模式 + Hermes 的"两层实体/会话"模型。**不**实现业务循环，**不**做产品级功能，**不**假设上层如何使用 memory。
|
||
|
||
## 2. 范围与边界
|
||
|
||
### 2.1 必须实现（12 项）
|
||
|
||
| # | 交付物 | 文件 | 关键决策 |
|
||
|---|--------|------|---------|
|
||
| 1 | `Agent` trait | `src/agent/agent.rs` | 角色定义：name / system_prompt / 工具集 / 引用 session 句柄 |
|
||
| 2 | `RuntimeBundle` | `src/agent/runtime.rs` | 依赖注入容器（OpenHarness 风格） |
|
||
| 3 | `AgentSession` | `src/agent/session.rs` | 会话实例 + **最小 reference impl**（`submit_turn` ~30 行） |
|
||
| 4 | `TaskAgent` + `Plan` / `Step` | `src/agent/task.rs` | 双入口：`run(goal)` 自主式 + `execute_plan(plan)` 外部驱动式 |
|
||
| 5 | `PlanParser` trait + `JsonPlanParser` 参考实现 | `src/agent/task.rs` | 注入式（澄清 3 选项 C） |
|
||
| 6 | `AgentError` | `src/agent/error.rs` | 聚合 LlmError / ToolError / MemoryError，含 `is_recoverable()` |
|
||
| 7 | `AgentConfig` / `AgentBuilder` | `src/agent/builder.rs` | 链式构造 `RuntimeBundle` |
|
||
| 8 | Hook 事件扩展 | `src/llm/hooks.rs` | 追加 `OnTurnStart` / `OnTurnEnd` / `OnPlanStepComplete` 3 个事件 + 上下文扩展（澄清 4） |
|
||
| 9 | `lib.rs` 导出 | `src/lib.rs` | 一行 `pub mod agent;` |
|
||
| 10 | 烟雾测试 | `src/agent/tests.rs` 或内联 | 2-3 个：trait 可装配 / RuntimeBundle 可构造 / `submit_turn` 跑通 mock |
|
||
| 11 | 方案文档 | `docs/7-agent-runtime.md` | 编号 `7`（最大编号是 `6`，已确认无冲突） |
|
||
| 12 | Roadmap 同步 | `docs/roadmap.md` | 状态从 ❌ 缺失 改为 ✅ |
|
||
|
||
### 2.2 明确不做（v0.2+ 边界）
|
||
|
||
| 推迟项 | 理由 |
|
||
|--------|------|
|
||
| 完整 `BasicAgent` 多轮 turn 循环 | core 库不假设业务循环 |
|
||
| `ConversationAgent` 自动回写 | 记忆在独立 task 处理，由上层回写 |
|
||
| 强绑定 `ConversationMemory` 字段 | 改 `Option<Arc<dyn MemoryStore>>` 弱引用 |
|
||
| Plan 拆解的提示词模板 | 由上层注入 `PlanParser` |
|
||
| Multi-Agent / Swarm | 接口未稳定，独立 phase |
|
||
| Markdown 技能按需加载 | 属于知识层 |
|
||
| 三级权限模式 UI | 应用层 |
|
||
| 干运行 / TUI / Gateway | 应用层 |
|
||
| 完整的集成测试套件 | 2-3 个烟雾测试足够（呼应"最小范围"） |
|
||
|
||
详细 v0.2+ 候选项见 `docs/roadmap.md` 扩展计划（v0.2+）小节与 `docs/note-agent-harness-references.md` 第 8 节。
|
||
|
||
## 3. 核心架构
|
||
|
||
### 3.1 分层（与 OpenHarness 5 层一致）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 应用层 （上层 crate / 二进制 / Gateway） │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Agent Runtime ← Phase 4：trait + RuntimeBundle + Session │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ LLM / Tool / Prompt / Memory ← Phase 0/1/2/3（已完成） │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 实体关系
|
||
|
||
```
|
||
┌────────────┐ ┌──────────────────┐
|
||
│ Agent │ 1 * │ AgentSession │
|
||
│ (trait) ├────────►│ (struct) │
|
||
│ - name │ │ - session_id │
|
||
│ - prompt │ │ - bundle: Arc │
|
||
│ - tools │ │ - turn_index │
|
||
└────────────┘ │ - cost_so_far │
|
||
└──────────────────┘
|
||
│
|
||
▼ 共享
|
||
┌──────────────────┐
|
||
│ RuntimeBundle │
|
||
│ - provider │
|
||
│ - tool_registry │
|
||
│ - hook_executor │
|
||
│ - memory_store? │ ◄── 弱引用（澄清 2 选项 B）
|
||
│ - retriever? │
|
||
│ - config │
|
||
└──────────────────┘
|
||
│
|
||
▼ 注册为 tool
|
||
┌──────────────────┐
|
||
│ "retrieve" tool │ ◄── 如果 retriever 存在则自动注册
|
||
└──────────────────┘
|
||
```
|
||
|
||
### 3.3 决策对照表
|
||
|
||
| 决策点 | 选择 | 来源 |
|
||
|--------|------|------|
|
||
| 实体 vs 会话 | 两层模型（`Agent` + `AgentSession`） | 讨论第 4 轮第 1 条 / OpenHarness / Hermes |
|
||
| 范围控制 | trait + 最小 reference impl（~30 行） | 讨论第 4 轮第 2 条 / 澄清 1 选项 B |
|
||
| 记忆处理 | 弱引用 + 自动注册 retriever 为 tool | 讨论第 4 轮第 3 条 / 澄清 2 选项 B |
|
||
| Hook 扩展 | 3 个新事件 + 上下文扩展 | 讨论第 4 轮第 4 条 / 澄清 4 |
|
||
| 方案文档位置 | `docs/7-agent-runtime.md` | 讨论第 4 轮第 5 条 |
|
||
| TaskAgent 入口 | 双入口（自主 + 外部驱动） | 讨论第 4 轮第 6 条 |
|
||
| 自主式 Plan 解析 | 注入式 `PlanParser` trait + `JsonPlanParser` 参考实现 | 澄清 3 选项 C |
|
||
| 依赖注入 | `RuntimeBundle` 显式容器 | 讨论第 4 轮第 7 条 / OpenHarness |
|
||
| 文档撰写 | 推迟到 Proposal 阶段 | 讨论第 4 轮第 8 条 |
|
||
|
||
## 4. 接口签名草案
|
||
|
||
> ⚠️ **这些是"设计约束"，不是最终代码**。方案文档（`docs/7-agent-runtime.md`）与实施阶段可微调字段顺序、文档注释、错误变体等，但**核心 trait 形状**和**方法名**应保持稳定。
|
||
|
||
### 4.1 `Agent` trait
|
||
|
||
```rust
|
||
pub trait Agent: Send + Sync {
|
||
fn name(&self) -> &str;
|
||
fn system_prompt(&self) -> Option<&str>;
|
||
/// 列出该 Agent 想要暴露给 LLM 的工具定义。
|
||
/// 默认实现：从 RuntimeBundle.tool_registry 取全部（最常用）。
|
||
/// 子 trait 可覆盖做白名单/过滤。
|
||
fn tool_definitions(&self, bundle: &RuntimeBundle) -> Vec<ToolDefinition>;
|
||
}
|
||
```
|
||
|
||
### 4.2 `RuntimeBundle`
|
||
|
||
```rust
|
||
pub struct RuntimeBundle {
|
||
pub provider: Arc<dyn LlmProvider>,
|
||
pub tool_registry: Arc<ToolRegistry>,
|
||
pub hook_executor: Arc<HookExecutor>,
|
||
pub memory_store: Option<Arc<dyn MemoryStore>>, // 弱引用（澄清 2 选项 B）
|
||
pub retriever: Option<Arc<MemoryRetriever>>, // 弱引用（澄清 2 选项 B）
|
||
pub config: AgentConfig,
|
||
}
|
||
|
||
impl RuntimeBundle {
|
||
/// 构造时如果 retriever 存在，自动注册为 "retrieve" tool。
|
||
pub fn new(/* ... */) -> Self;
|
||
}
|
||
```
|
||
|
||
### 4.3 `AgentSession`
|
||
|
||
```rust
|
||
pub struct AgentSession {
|
||
pub session_id: String,
|
||
pub agent_name: String,
|
||
bundle: Arc<RuntimeBundle>,
|
||
turn_index: u32,
|
||
cost_so_far: CostTracker,
|
||
}
|
||
|
||
impl AgentSession {
|
||
pub fn new(agent: &dyn Agent, session_id: impl Into<String>, bundle: Arc<RuntimeBundle>) -> Self;
|
||
|
||
/// 最小 reference impl：组装 LlmCycle + submit + 累计 cost。
|
||
/// 不做 memory 回写（呼应"记忆在独立 task 处理"原则）。
|
||
pub async fn submit_turn(
|
||
&mut self,
|
||
user_input: impl Into<String>,
|
||
) -> Result<ChatResponse, AgentError>;
|
||
|
||
pub fn usage(&self) -> &CostTracker;
|
||
pub fn turn_index(&self) -> u32;
|
||
}
|
||
```
|
||
|
||
### 4.4 `TaskAgent` + `Plan` + `Step`
|
||
|
||
```rust
|
||
pub struct Plan {
|
||
pub id: String,
|
||
pub goal: String,
|
||
pub steps: Vec<Step>,
|
||
}
|
||
|
||
pub struct Step {
|
||
pub index: usize,
|
||
pub description: String,
|
||
pub status: StepStatus,
|
||
}
|
||
|
||
pub enum StepStatus {
|
||
Pending,
|
||
Running,
|
||
Completed(ChatResponse),
|
||
Failed(AgentError),
|
||
Skipped,
|
||
}
|
||
|
||
/// 注入式 Plan 解析器。
|
||
#[async_trait]
|
||
pub trait PlanParser: Send + Sync {
|
||
async fn parse(&self, raw: &str, goal: &str) -> Result<Plan, AgentError>;
|
||
}
|
||
|
||
/// 基于 serde_json 的参考实现（约 20 行）。
|
||
pub struct JsonPlanParser;
|
||
|
||
#[async_trait]
|
||
impl PlanParser for JsonPlanParser { /* ... */ }
|
||
|
||
/// TaskAgent 双入口。
|
||
#[async_trait]
|
||
pub trait TaskAgent: Agent {
|
||
/// 自主式：内部用 LLM 拆 Plan → execute_plan
|
||
async fn run(&mut self, session: &mut AgentSession, goal: &str) -> Result<Plan, AgentError>;
|
||
|
||
/// 外部驱动式：用户预定义 Plan → 逐步执行
|
||
async fn execute_plan(
|
||
&mut self,
|
||
session: &mut AgentSession,
|
||
plan: Plan,
|
||
) -> Result<Plan, AgentError>;
|
||
}
|
||
```
|
||
|
||
### 4.5 `AgentError`
|
||
|
||
```rust
|
||
pub enum AgentError {
|
||
Llm(LlmError),
|
||
Tool(ToolError),
|
||
Memory(MemoryError),
|
||
PlanParse(String),
|
||
HookBlocked(String),
|
||
LimitExceeded(String),
|
||
Config(String),
|
||
Other(String),
|
||
}
|
||
|
||
impl AgentError {
|
||
pub fn is_recoverable(&self) -> bool { /* ... */ }
|
||
}
|
||
```
|
||
|
||
### 4.6 `AgentConfig` + `AgentBuilder`
|
||
|
||
```rust
|
||
pub struct AgentConfig {
|
||
pub max_turns: u32,
|
||
pub max_tool_turns: u32,
|
||
pub session_ttl: Option<Duration>,
|
||
pub compact_config: Option<CompactConfig>,
|
||
}
|
||
|
||
pub struct AgentBuilder { /* ... */ }
|
||
|
||
impl AgentBuilder {
|
||
pub fn new() -> Self;
|
||
pub fn provider(self, p: Arc<dyn LlmProvider>) -> Self;
|
||
pub fn tool_registry(self, r: Arc<ToolRegistry>) -> Self;
|
||
pub fn hook_executor(self, h: Arc<HookExecutor>) -> Self;
|
||
pub fn memory_store(self, m: Arc<dyn MemoryStore>) -> Self; // 选填
|
||
pub fn retriever(self, r: Arc<MemoryRetriever>) -> Self; // 选填
|
||
pub fn config(self, c: AgentConfig) -> Self;
|
||
pub fn build(self) -> Result<RuntimeBundle, AgentError>;
|
||
}
|
||
```
|
||
|
||
### 4.7 Hook 扩展（`src/llm/hooks.rs` 改动）
|
||
|
||
```rust
|
||
pub enum HookEvent {
|
||
// ... 现有 4 个 ...
|
||
|
||
// 新增 3 个：
|
||
OnTurnStart,
|
||
OnTurnEnd,
|
||
OnPlanStepComplete,
|
||
}
|
||
|
||
// HookContext 扩展 2 个 Option 字段（澄清 4）：
|
||
pub struct HookContext {
|
||
// ... 现有字段 ...
|
||
pub turn_index: Option<u32>, // OnTurnStart/End 用
|
||
pub plan_step_index: Option<usize>, // OnPlanStepComplete 用
|
||
}
|
||
```
|
||
|
||
## 5. 文件清单
|
||
|
||
### 5.1 新增文件（7 个）
|
||
|
||
```
|
||
src/agent.rs # 模块根 + pub use 重导出
|
||
src/agent/agent.rs # Agent trait
|
||
src/agent/runtime.rs # RuntimeBundle + AgentConfig
|
||
src/agent/session.rs # AgentSession
|
||
src/agent/task.rs # TaskAgent trait + Plan/Step + PlanParser + JsonPlanParser
|
||
src/agent/builder.rs # AgentBuilder
|
||
src/agent/error.rs # AgentError
|
||
```
|
||
|
||
### 5.2 修改文件（3 个）
|
||
|
||
```
|
||
src/lib.rs # + pub mod agent;
|
||
src/llm/hooks.rs # + 3 个事件变体 + 2 个上下文字段（极小改）
|
||
docs/roadmap.md # 状态翻转 + Phase 4 交付物清单更新（实施时再做）
|
||
```
|
||
|
||
### 5.3 关联文档（已存在 / 待写）
|
||
|
||
```
|
||
docs/note-agent-harness-references.md # 参考项目调研（已存在）
|
||
docs/7-agent-runtime.md # 完整方案文档（路径 A 输出）
|
||
docs/note-agent-runtime-design.md # 本文件
|
||
```
|
||
|
||
## 6. 预估规模
|
||
|
||
- **新增代码**：约 **600-700 行**（含 2-3 个烟雾测试）
|
||
- **修改代码**：约 **10-20 行**（`hooks.rs` 改动 + `lib.rs` + `roadmap.md`）
|
||
- **方案文档**：约 **450-550 行 Markdown**（沿用 6-memory-system.md 的 6 段式结构）
|
||
|
||
## 7. 待办事项（按依赖顺序）
|
||
|
||
1. ✅ Phase 4 范围已收窄（§2.1）
|
||
2. ✅ 核心架构已对齐 OpenHarness / Hermes（§3）
|
||
3. ✅ 接口签名草案已固化（§4）
|
||
4. ✅ 文件清单已确定（§5）
|
||
5. ✅ 编号冲突已验证（最大是 `6`，新文件用 `7`）
|
||
6. ⏳ 写 `docs/7-agent-runtime.md` 方案文档
|
||
7. ⏳ 按文档实施 7 个新文件 + 3 个修改
|
||
8. ⏳ 跑通 2-3 个烟雾测试
|
||
9. ⏳ 更新 `docs/roadmap.md` 状态翻转
|
||
|
||
## 8. 一句话总结
|
||
|
||
> **Phase 4 = Phase 0-3 的薄胶水层 + 一组 trait 抽象**。**不**实现业务循环，**不**做产品级功能，**不**假设上层如何使用 memory。借鉴 OpenHarness 的"显式依赖注入容器"与 Hermes 的"实体/会话分离"模型，记忆以弱引用方式接入，`MemoryRetriever` 在 `RuntimeBundle::new()` 时自动注册为 LLM 可调用的 `retrieve` 工具。
|