xt/agcore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(roadmap): 将 Phase 4 拆分为 4a/4b/4c 三个独立子阶段

Browse Source
This commit is contained in:
徐涛
2026-06-10 22:38:32 +08:00
parent be595a6771
commit 59ec0f5597
2 changed files with 350 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/7-agent-runtime.md
+267 -119
View File
@@ -21,15 +21,33 @@ AG Core 已完成 Phase 0（LLM 调用周期）、Phase 1（提示词工程）
### 1.2 目标 ### 1.2 目标
Phase 4 目标是提供一个**薄胶水层 + 一组 trait 抽象**，让上层应用可以基于 AG Core 构建多轮对话、任务规划等智能体行为。具体包括： Phase 4 整体目标是提供一个**薄胶水层 + 一组 trait 抽象**，让上层应用可以基于 AG Core 构建多轮对话、任务规划等智能体行为。为控制 scope、降低交付风险，拆分为三个子阶段实施：
| 子阶段 | 定位 | 交付物 |
|--------|------|--------|
| **Phase 4a（核心胶水层）** | 最小可用 Agent Runtime | `Agent` + `AgentSession` + `submit_turn` + `RuntimeBundle` / `AgentBuilder` / `AgentError` + `Plan`/`Step` 纯数据 + hooks 扩展 |
| **Phase 4b（任务执行）** | 自主任务规划与执行 | `TaskAgent` + `PlanParser` trait + `JsonPlanParser` + `OnPlanStepComplete` hook |
| **Phase 4c（会话级记忆）** | 跨 context 信息桥接 | `SessionMemory`（基于 `MemoryStore`）+ AgentSession 接入 + builder 支持 |
**每个子阶段独立交付**，Phase 4a 完成后上层即可接入；Phase 4b/4c 无相互依赖，可并行或按需延后。
Phase 4a 具体包括：
- **`Agent` trait** — 智能体的"角色"抽象（不绑定 session） - **`Agent` trait** — 智能体的"角色"抽象（不绑定 session）
- **`AgentSession` struct** — 智能体的"会话"实例（绑定 session_id + 状态） - **`AgentSession` struct** — 智能体的"会话"实例（绑定 session_id + 状态）
- **`TaskAgent` trait** — 任务型智能体的"规划/执行"抽象 - **`RuntimeBundle`** — 显式依赖注入容器，集中管理 provider/registry/hook 等依赖
- **`RuntimeBundle`** — 显式依赖注入容器，集中管理 provider/registry/hook/memory 等依赖
- **`SessionMemory`** — 会话级记忆，用于 context 间的信息桥接（基于 `MemoryStore` 后端）
- **`AgentBuilder`** — 链式构造入口 - **`AgentBuilder`** — 链式构造入口
- **`AgentError`** — 统一错误类型，聚合 LlmError / ToolError / MemoryError - **`AgentError`** — 统一错误类型，聚合 LlmError / ToolError / MemoryError
- **`Plan` / `Step` / `StepStatus`** — 任务规划纯数据结构（不做解析逻辑）
Phase 4b 追加：
- **`TaskAgent` trait** — 任务型智能体的"规划/执行"抽象
- **`PlanParser` trait + `JsonPlanParser`** — Plan 解析接口与参考实现
Phase 4c 追加：
- **`SessionMemory`** — 会话级记忆，用于 context 间的信息桥接（基于 `MemoryStore` 后端）
### 1.3 设计原则 ### 1.3 设计原则
@@ -56,7 +74,9 @@ Phase 3 (L2) ── MemoryStore / ConversationMemory / KnowledgeStore / Me
↑ ↑
│ 复用 │ 复用
│ │
Phase 4 (L1→L2) ── Agent trait + AgentSession + TaskAgent + RuntimeBundle（胶水层） Phase 4a (L1→L2) ── Agent trait + AgentSession + submit_turn + RuntimeBundle + Plan/Step 纯数据（胶水层）
Phase 4b (L2) ── TaskAgent + PlanParser + JsonPlanParser（任务执行）
Phase 4c (L2) ── SessionMemory（会话级记忆）
↓ ↓
应用层 (L4) ── 上层 crate / 二进制 / Gateway（不在 Phase 4 范围） 应用层 (L4) ── 上层 crate / 二进制 / Gateway（不在 Phase 4 范围）
``` ```
@@ -67,23 +87,31 @@ Phase 4 (L1→L2) ── Agent trait + AgentSession + TaskAgent + RuntimeBund
### 2.1 功能需求 ### 2.1 功能需求
| ID | 需求 | 优先级 | 说明 | | ID | 需求 | 优先级 | 归属 | 说明 |
|----|------|--------|------| |----|------|--------|------|------|
| F1 | `Agent` trait 抽象 | P0 | 角色定义：name / system_prompt / 工具集 | | F1 | `Agent` trait 抽象 | P0 | 4a | 角色定义：name / system_prompt / 工具集 |
| F2 | `AgentSession` 会话实例 | P0 | 绑定 session_id、bundle、turn_index、cost_so_far | | F2 | `AgentSession` 会话实例 | P0 | 4a | 绑定 session_id、bundle、turn_index、cost_so_far |
| F3 | `submit_turn()` 最小 reference impl | P0 | 组装 LlmCycle → submit → 累计 cost；约 30 行 | | F3 | `submit_turn()` 最小 reference impl | P0 | 4a | 组装 LlmCycle → submit → 累计 cost；~30 行 |
| F4 | `TaskAgent::run(goal)` 自主式入口 | P0 | 内部用 LLM 拆 Plan，再调用 `execute_plan` | | F6 | `Plan` / `Step` / `StepStatus` 数据结构 | P0 | 4a | 含 Pending / Running / Completed / Failed / Skipped 状态机 |
| F5 | `TaskAgent::execute_plan(plan)` 外部驱动式入口 | P0 | 用户预定义 Plan，逐步执行 | | F8 | `RuntimeBundle` 依赖注入容器 | P0 | 4a | 聚合 provider/registry/hook/config（不含 session_memory_backend） |
| F6 | `Plan` / `Step` / `StepStatus` 数据结构 | P0 | 含 Pending / Running / Completed / Failed / Skipped 状态机 | | F9 | `AgentBuilder` 链式构造 | P0 | 4a | 构建 `RuntimeBundle`，retriever 存在时自动注册为 tool |
| F7 | `PlanParser` trait + `JsonPlanParser` 参考实现 | P0 | 注入式，上层可替换 | | F10 | `AgentError` 统一错误类型 | P0 | 4a | 聚合 LlmError / ToolError / MemoryError，含 `is_recoverable()` |
| F8 | `RuntimeBundle` 依赖注入容器 | P0 | 聚合 provider/registry/hook/memory/retriever/config | | F11a | Hook 事件扩展：OnTurnStart / OnTurnEnd + turn_index 字段 | P0 | 4a | 在 `llm/hooks.rs` 中追加 2 个事件 + 1 个字段 |
| F9 | `AgentBuilder` 链式构造 | P0 | 构建 `RuntimeBundle`，retriever 存在时自动注册为 tool | | F12a | 烟雾测试 3-4 个（Phase 4a） | P0 | 4a | trait 可装配 / RuntimeBundle 可构造 / submit_turn 跑通 mock / Plan 数据结构 |
| F10 | `AgentError` 统一错误类型 | P0 | 聚合 LlmError / ToolError / MemoryError，含 `is_recoverable()` | | F13 | `lib.rs` 导出 `pub mod agent;` | P0 | 4a | 一行 |
| F11 | Hook 事件扩展：OnTurnStart / OnTurnEnd / OnPlanStepComplete | P0 | 在 `llm/hooks.rs` 中追加 3 个事件 + 上下文扩展 2 个字段 | | F14 | 方案文档（本文件）+ 决策记录 | P0 | — | ✅ 已完成 |
| F12 | 烟雾测试 2-3 个 | P0 | trait 可装配 / RuntimeBundle 可构造 / `submit_turn` 跑通 mock | | F4 | `TaskAgent::run(goal)` 自主式入口 | P0 | 4b | 内部用 LLM 拆 Plan，再调用 `execute_plan` |
| F13 | `lib.rs` 导出 `pub mod agent;` | P0 | 一行 | | F5 | `TaskAgent::execute_plan(plan)` 外部驱动式入口 | P0 | 4b | 用户预定义 Plan，逐步执行 |
| F14 | 方案文档（本文件）+ 决策记录 | P0 | 已完成 | | F7 | `PlanParser` trait + `JsonPlanParser` 参考实现 | P0 | 4b | 注入式，上层可替换 |
| F15 | Roadmap 状态翻转 | P0 | 实施完成后做 | | F11b | Hook 事件扩展：OnPlanStepComplete + plan_step_index 字段 | P0 | 4b | 在 `llm/hooks.rs` 中追加 1 个事件 + 1 个字段 |
| F12b | 烟雾测试 2-3 个（Phase 4b） | P0 | 4b | TaskAgent + PlanParser 跑通 mock |
| F15a | Roadmap 状态翻转（Phase 4a） | P0 | 4a | 实施完成后做 |
| F15b | Roadmap 状态翻转（Phase 4b） | P0 | 4b | 实施完成后做 |
| F16 | SessionMemory 会话级记忆 | P0 | 4c | 基于 `MemoryStore`，context 间信息桥接 |
| F17 | RuntimeBundle / Builder 扩展 session_memory_backend | P0 | 4c | 追加字段 + setter 方法 |
| F18 | AgentSession 接入 SessionMemory | P0 | 4c | 替换内联 HashMap，接入完整 SessionMemory |
| F12c | 烟雾测试 2-3 个（Phase 4c） | P0 | 4c | SessionMemory set/get/snapshot |
| F15c | Roadmap 状态翻转（Phase 4c） | P0 | 4c | 实施完成后做 |
### 2.2 非功能需求 ### 2.2 非功能需求
@@ -527,30 +555,32 @@ pub struct HookContext {
## 4. 实施计划 ## 4. 实施计划
Phase 4 拆分为三个独立子阶段：**Phase 4a（核心胶水层）** → **Phase 4b（任务执行）** → **Phase 4c（会话级记忆）**。每个子阶段独立交付、独立验证，4b 与 4c 无相互依赖。
### 4.1 文件清单 ### 4.1 文件清单
#### 新增文件（8 个） #### 新增文件（9 个）
``` ```
src/agent.rs # 模块根 + pub use 重导出 src/agent.rs # [4a] 模块根 + pub use 重导出
src/agent/agent.rs # Agent trait src/agent/agent.rs # [4a] Agent trait
src/agent/runtime.rs # RuntimeBundle + AgentConfig src/agent/runtime.rs # [4a] RuntimeBundle + AgentConfig（不含 session_memory_backend）
src/agent/session.rs # AgentSession（含 submit_turn reference impl） src/agent/session.rs # [4a] AgentSession（submit_turn + 内联 session_data HashMap）
src/agent/session_memory.rs # SessionMemory（会话级记忆，基于 MemoryStore） src/agent/task.rs # [4a] Plan / Step / StepStatus 纯数据 / [4b] TaskAgent + PlanParser + JsonPlanParser
src/agent/task.rs # TaskAgent trait + Plan/Step + PlanParser + JsonPlanParser src/agent/builder.rs # [4a] AgentBuilder（不含 session_memory_backend）
src/agent/builder.rs # AgentBuilder src/agent/error.rs # [4a] AgentError（不含 PlanParse 变体）/ [4b] 补充 PlanParse 变体
src/agent/error.rs # AgentError src/agent/session_memory.rs # [4c] SessionMemory（基于 MemoryStore）
``` ```
#### 修改文件（3 个） #### 修改文件（2 个）
``` ```
src/lib.rs # + pub mod agent; src/lib.rs # [4a] + pub mod agent;
src/llm/hooks.rs # + 3 个事件变体 + 2 个 HookContext 字段 src/llm/hooks.rs # [4a] + 2 事件（OnTurnStart/OnTurnEnd）+ 1 字段（turn_index）
docs/roadmap.md # Phase 4 状态 ❌ 缺失 → ✅ # [4b] + 1 事件（OnPlanStepComplete）+ 1 字段（plan_step_index）
``` ```
#### 关联文档（已完成 / 待写） #### 关联文档（已完成）
``` ```
docs/note-agent-harness-references.md # ✅ 已存在 docs/note-agent-harness-references.md # ✅ 已存在
@@ -558,71 +588,140 @@ docs/note-agent-runtime-design.md # ✅ 已存在（与本文件配套）
docs/7-agent-runtime.md # ✅ 本文件 docs/7-agent-runtime.md # ✅ 本文件
``` ```
### 4.2 任务拆解（按依赖顺序） ---
### 4.2 Phase 4a — 核心胶水层（最小 Agent Runtime）
**范围**：Agent trait + AgentSession + submit_turn（内联 HashMap session_data）+ RuntimeBundle/AgentBuilder + AgentError + Plan/Step 纯数据 + hooks 扩展（OnTurnStart/OnTurnEnd）
**任务拆解**：
| 顺序 | 任务 | 涉及文件 | 验证 | | 顺序 | 任务 | 涉及文件 | 验证 |
|------|------|---------|------| |------|------|---------|------|
| 1 | 修改 `llm/hooks.rs` 追加 3 个事件 + 2 个字段 | `src/llm/hooks.rs` | `cargo build` 通过；现有测试不挂 | | a1 | 修改 `llm/hooks.rs` 追加 OnTurnStart / OnTurnEnd + turn_index 字段 | `src/llm/hooks.rs` | `cargo build` 通过；Phase 0 测试不挂 |
| 2 | 新建 `agent/error.rs` 定义 `AgentError` | `src/agent/error.rs` | `cargo build` 通过 | | a2 | 新建 `agent/error.rs` 定义 `AgentError`（不含 PlanParse 变体） | `src/agent/error.rs` | `cargo build` 通过 |
| 3 | 新建 `agent/agent.rs` 定义 `Agent` trait | `src/agent/agent.rs` | `cargo build` 通过 | | a3 | 新建 `agent/agent.rs` 定义 `Agent` trait | `src/agent/agent.rs` | `cargo build` 通过 |
| 4 | 新建 `agent/runtime.rs` 定义 `RuntimeBundle` + `AgentConfig`（含 `session_memory_backend` 字段） | `src/agent/runtime.rs` | `cargo build` 通过 | | a4 | 新建 `agent/runtime.rs` 定义 `RuntimeBundle` + `AgentConfig`（不含 session_memory_backend） | `src/agent/runtime.rs` | `cargo build` 通过 |
| 5 | 新建 `agent/session_memory.rs` 定义 `SessionMemory` | `src/agent/session_memory.rs` | `cargo build` 通过 | | a5 | 新建 `agent/builder.rs` 定义 `AgentBuilder`（不含 session_memory_backend 方法） | `src/agent/builder.rs` | `cargo build` 通过 |
| 6 | 新建 `agent/builder.rs` 定义 `AgentBuilder`（含 `.session_memory_backend()` 方法） | `src/agent/builder.rs` | `cargo build` 通过 | | a6 | 新建 `agent/session.rs` 定义 `AgentSession` + `submit_turn`（内联 `HashMap<String,String>` 做 session_data，不引 MemoryStore） | `src/agent/session.rs` | `cargo build` 通过 |
| 7 | 新建 `agent/session.rs` 定义 `AgentSession` + `submit_turn`（持 `Arc<dyn Agent>` + `SessionMemory`） | `src/agent/session.rs` | `cargo build` 通过 | | a7 | 新建 `agent/task.rs` 定义 `Plan` / `Step` / `StepStatus` 纯数据结构（不含 TaskAgent trait，不含 PlanParser） | `src/agent/task.rs` | `cargo build` 通过 |
| 8 | 新建 `agent/task.rs` 定义 `TaskAgent` + `Plan` / `Step` / `PlanParser` / `JsonPlanParser` | `src/agent/task.rs` | `cargo build` 通过 | | a8 | 新建 `src/agent.rs` 模块根 + `pub use` 重导出 + 修改 `lib.rs` | `src/agent.rs` + `src/lib.rs` | `cargo build` 通过 |
| 9 | 新建 `src/agent.rs` 模块根 + `pub use` 重导出 | `src/agent.rs` | `cargo build` 通过 | | a9 | 编写烟雾测试 3-4 个（Agent trait 可装配 / RuntimeBundle 可构造 / submit_turn 跑通 mock / Plan 数据结构） | `src/agent/*.rs` 内联 | `cargo test` 通过 |
| 10 | 修改 `lib.rs` 导出 `pub mod agent;` | `src/lib.rs` | `cargo build` 通过 | | a10 | 完整 `cargo test` 跑全量回归 + roadmap.md 状态更新 | — | 所有已有测试不挂 |
| 11 | 编写 3-4 个烟雾测试（含 SessionMemory） | `src/agent/*.rs` 内联 | `cargo test` 通过 |
| 12 | 更新 `roadmap.md` 状态翻转 | `docs/roadmap.md` | 文档 review |
| 13 | 完整 `cargo test` 跑全量回归 | — | 所有已有测试不挂 |
### 4.3 依赖关系 **依赖关系**：
``` ```
hooks.rs (1) ──┐ hooks扩展 (a1) ──┐
├──► agent/error.rs (2) ──► agent/agent.rs (3) ├──► agent/error.rs (a2) ──► agent/agent.rs (a3)
│ │ │ │
│ ▼ │ ▼
│ agent/runtime.rs (4) │ agent/runtime.rs (a4)
│ │ │
│ │ ▼
│ │ agent/session_memory.rs (5)
│ │ │
│ ▼ │
│ agent/builder.rs (6)
│ │ │ │
│ ▼ │ ▼
│ agent/session.rs (7) │ agent/builder.rs (a5)
│ │ │ │
│ ▼ │ ▼
└─────────────────► agent/task.rs (8) │ agent/session.rs (a6)
│ │
│ ▼
│ agent/task.rs (a7) [纯数据]
│ │
└──────────────────► src/agent.rs + lib.rs (a8)
│ │
▼ ▼
src/agent.rs (9) cargo test (a9 → a10)
│
▼
src/lib.rs (10)
│
▼
cargo test (11)
│
▼
roadmap.md (12)
│
▼
回归 (13)
``` ```
### 4.4 预估工作量 ---
| 阶段 | 行数 | 说明 | ### 4.3 Phase 4b — 任务执行
|------|------|------|
| 1（hooks 扩展） | ~15 | 3 个变体 + 2 个字段 + 文档 | **范围**：TaskAgent trait + PlanParser trait + JsonPlanParser 参考实现 + OnPlanStepComplete hook + AgentError PlanParse 变体
| 2-8（8 个 agent 文件） | ~640 | 含 import + trait + struct + impl + 文档（+ session_memory.rs ~40 行） |
| 9-10（lib.rs + agent.rs 模块根） | ~20 | 主要是 pub use 重导出 | **前置条件**：Phase 4a 已完成并交付。
| 11（烟雾测试） | ~120 | 3-4 个测试（含 SessionMemory） |
| 12（roadmap 同步） | ~5 | 状态翻转一行 | **任务拆解**：
| **合计** | **~800** | 从 ~740 增加 ~60 行（SessionMemory ~40 + 测试 ~20） |
| 顺序 | 任务 | 涉及文件 | 验证 |
|------|------|---------|------|
| b1 | 修改 `llm/hooks.rs` 追加 OnPlanStepComplete + plan_step_index 字段 | `src/llm/hooks.rs` | `cargo build` 通过；Phase 0 + 4a 测试不挂 |
| b2 | `agent/error.rs` 追加 PlanParse 变体 | `src/agent/error.rs` | `cargo build` 通过 |
| b3 | `agent/task.rs` 追加 `TaskAgent` trait + `PlanParser` trait + `JsonPlanParser` 参考实现 | `src/agent/task.rs` | `cargo build` 通过 |
| b4 | 更新 `agent.rs` 模块根重导出（如有新增公开类型） | `src/agent.rs` | `cargo build` 通过 |
| b5 | 编写烟雾测试 2-3 个（TaskAgent mock 执行 / JsonPlanParser 解析 / PlanParse 错误） | `src/agent/task.rs` 内联 | `cargo test` 通过 |
| b6 | 完整 `cargo test` 跑全量回归 + roadmap.md 状态更新 | — | 所有已有测试不挂 |
**依赖关系**：
```
hooks扩展 (b1) ──┐
├──► error.rs 追加 (b2) ──► task.rs 追加 (b3)
│
▼
agent.rs 更新 (b4)
│
▼
cargo test (b5 → b6)
```
---
### 4.4 Phase 4c — 会话级记忆
**范围**：SessionMemory struct（基于 MemoryStore）+ RuntimeBundle/Build 扩展 session_memory_backend + AgentSession 接入（替换内联 HashMap）
**前置条件**：Phase 4a 已完成并交付（可在 4b 之前、之后或并行实施）。
**任务拆解**：
| 顺序 | 任务 | 涉及文件 | 验证 |
|------|------|---------|------|
| c1 | 新建 `agent/session_memory.rs` 定义 `SessionMemory`（基于 `MemoryStore`，namespace 隔离） | `src/agent/session_memory.rs` | `cargo build` 通过 |
| c2 | `agent/runtime.rs` 追加 `session_memory_backend` 字段到 `RuntimeBundle` | `src/agent/runtime.rs` | `cargo build` 通过 |
| c3 | `agent/builder.rs` 追加 `.session_memory_backend()` 方法 | `src/agent/builder.rs` | `cargo build` 通过 |
| c4 | `agent/session.rs` 替换内联 HashMap 为完整 `SessionMemory` + 更新模块根重导出 | `src/agent/session.rs` + `src/agent.rs` | `cargo build` 通过 |
| c5 | 编写烟雾测试 2-3 个（SessionMemory set/get/snapshot 基于 InMemoryStore） | `src/agent/session_memory.rs` 内联 | `cargo test` 通过 |
| c6 | 完整 `cargo test` 跑全量回归 + roadmap.md 状态更新 | — | 所有已有测试不挂 |
**依赖关系**：
```
session_memory.rs (c1) ──► runtime.rs 追加 (c2) ──► builder.rs 追加 (c3)
│
▼
session.rs 修改 (c4)
│
▼
cargo test (c5 → c6)
```
---
### 4.5 预估工作量（按子阶段）
| 子阶段 | 文件 | 行数 | 说明 |
|--------|------|------|------|
| **Phase 4a** | hooks 扩展（2 事件 + 1 字段） | ~10 | 追加变体 + 字段 + 文档 |
| | agent/error.rs | ~40 | AgentError 枚举 + From + is_recoverable |
| | agent/agent.rs | ~30 | Agent trait + docs |
| | agent/runtime.rs | ~60 | RuntimeBundle + AgentConfig |
| | agent/builder.rs | ~60 | 链式构造 + build 校验 |
| | agent/session.rs | ~100 | AgentSession + submit_turn + 内联 HashMap |
| | agent/task.rs（纯数据） | ~40 | Plan / Step / StepStatus |
| | src/agent.rs + lib.rs | ~20 | 模块根 + 导出 |
| | 烟雾测试 | ~80 | 3-4 个测试 |
| | **小计** | **~440** | **核心胶水层** |
| **Phase 4b** | hooks 扩展（1 事件 + 1 字段） | ~5 | OnPlanStepComplete + plan_step_index |
| | error.rs 追加 PlanParse | ~5 | 1 个变体 |
| | task.rs 追加（TaskAgent + PlanParser + JsonPlanParser） | ~130 | trait + 参考实现 + docs |
| | 烟雾测试 | ~60 | 2-3 个测试 |
| | **小计** | **~200** | **任务执行** |
| **Phase 4c** | session_memory.rs | ~40 | 5 个方法 + docs |
| | runtime.rs / builder.rs / session.rs 修改 | ~35 | 追加字段 + setter + 替换 HashMap |
| | 烟雾测试 | ~40 | 2-3 个测试 |
| | **小计** | **~115** | **会话级记忆** |
| **合计** | | **~755** | 与原始预估 ~800 基本持平 |
## 5. 风险评估 ## 5. 风险评估
@@ -664,73 +763,122 @@ hooks.rs (1) ──┐
### 5.5 实施进度风险 ### 5.5 实施进度风险
**风险描述**：12 项交付物虽然不多，但 `submit_turn` 的 reference impl 需要在"LlmCycle 之上做正确组装"，容易卡在细节。 **风险描述**：拆为 3 个子阶段后每个阶段任务量降低（4a 约 440 行、4b 约 200 行、4c 约 115 行），但阶段间衔接（4b/4c 对 4a 的依赖）可能产生等待。
**缓解措施**： **缓解措施**：
- 任务拆解（§4.2）按依赖顺序排好 - 每个子阶段独立验证，完成即交付，不阻塞后续阶段
- 4b 和 4c 无相互依赖，可并行开工
- 烟雾测试只验证"能跑通"不验证"业务正确"——避免陷入业务循环的细节 - 烟雾测试只验证"能跑通"不验证"业务正确"——避免陷入业务循环的细节
- 必要时先做 `MockProvider`（Phase 0 已有模式），不依赖真实 LLM - 必要时先做 `MockProvider`（Phase 0 已有模式），不依赖真实 LLM
## 6. 验收标准 ## 6. 验收标准
### 6.1 代码验收 ### 6.1 通用代码验收（每个子阶段必须满足）
- [ ] `cargo build --release` 0 错误 0 警告（clippy） - [ ] `cargo build --release` 0 错误 0 警告（clippy）
- [ ] `cargo test` 所有 Phase 0-3 已有测试 + Phase 4 新增测试全部通过 - [ ] `cargo test` 所有已有测试 + 本阶段新增测试全部通过
- [ ] `cargo doc --no-deps` 所有公开 API 有 `///` 文档注释 - [ ] `cargo doc --no-deps` 所有公开 API 有 `///` 文档注释
- [ ] 新增代码 750-850 行（含测试 + 文档注释），与 §4.4 预估一致
- [ ] `src/lib.rs` 新增一行 `pub mod agent;`
- [ ] `src/llm/hooks.rs` 仅追加（不修改现有变体或字段） - [ ] `src/llm/hooks.rs` 仅追加（不修改现有变体或字段）
### 6.2 接口验收 ### 6.2 Phase 4a 验收
#### 6.2a 代码验收
- [ ] 新增代码 ~440 行（含测试 + 文档注释），与 §4.5 预估一致
- [ ] `src/lib.rs` 新增一行 `pub mod agent;`
- [ ] 新增文件：`agent.rs` / `agent/agent.rs` / `agent/runtime.rs` / `agent/builder.rs` / `agent/session.rs` / `agent/task.rs` / `agent/error.rs`（共 7 个文件，不含 `agent/builder.rs` 之外的 builder 则 7 个）
#### 6.2b 接口验收
- [ ] 8 个新文件全部存在（§4.1）
- [ ] `Agent` trait 包含 `name` / `system_prompt` / `tool_definitions` 三个方法 - [ ] `Agent` trait 包含 `name` / `system_prompt` / `tool_definitions` 三个方法
- [ ] `RuntimeBundle` 包含 7 个字段（provider / tool_registry / hook_executor / memory_store? / retriever? / session_memory_backend? / config） - [ ] `RuntimeBundle` 包含 5 个字段：provider / tool_registry / hook_executor / memory_store? / retriever? / config（不含 session_memory_backend）
- [ ] `AgentSession` 持 `Arc<dyn Agent>` 而非 `agent_name: String`，含 `session_memory: SessionMemory` 字段 - [ ] `AgentBuilder` 提供 5 个 setter（不含 session_memory_backend）+ `build()` 校验
- [ ] `AgentSession` 持 `Arc<dyn Agent>` 而非 `agent_name: String`
- [ ] `AgentSession::submit_turn` 实现约 30 行，含 OnTurnStart/End hook 触发 - [ ] `AgentSession::submit_turn` 实现约 30 行，含 OnTurnStart/End hook 触发
- [ ] `SessionMemory` 包含 5 个方法（set / get / snapshot / remove / clear），基于 `MemoryStore` 实现 - [ ] `AgentSession` 用内联 `HashMap<String, String>` 做 session_data（不引 `MemoryStore`）
- [ ] `SessionMemory::snapshot` 返回 `<session-context>` 标签包裹的格式化文本 - [ ] `Plan` / `Step` / `StepStatus` 纯数据结构存在，状态机正确
- [ ] `TaskAgent` 提供双入口 `run` + `execute_plan` - [ ] `AgentError` 聚合 6 个变体：Llm / Tool / Memory / HookBlocked / LimitExceeded / Config / Other（不含 PlanParse）
- [ ] `JsonPlanParser` 实现约 20 行，基于 `serde_json` - [ ] `AgentError::is_recoverable()` 对各变体返回正确分类
- [ ] `AgentError` 聚合 8 个变体，含 `is_recoverable()` - [ ] `HookEvent` 新增 2 个变体：`OnTurnStart` / `OnTurnEnd`
- [ ] `AgentBuilder` 提供 7 个 setter（含 `.session_memory_backend()`）+ `build()` 校验 - [ ] `HookContext` 新增 1 个 `Option` 字段：`turn_index`
- [ ] `HookEvent` 新增 3 个变体：`OnTurnStart` / `OnTurnEnd` / `OnPlanStepComplete`
- [ ] `HookContext` 新增 2 个 `Option` 字段：`turn_index` / `plan_step_index`
### 6.3 测试验收 #### 6.2c 测试验收
至少 3-4 个烟雾测试通过：
- [ ] **测试 1**：`Agent` trait 可实现 + `RuntimeBundle` 可构造（builder 链式调用） - [ ] **测试 1**：`Agent` trait 可实现 + `RuntimeBundle` 可构造（builder 链式调用）
- [ ] **测试 2**：`AgentSession::submit_turn` 跑通 mock provider（Phase 0 `MockProvider` 模式） - [ ] **测试 2**：`AgentSession::submit_turn` 跑通 mock provider（Phase 0 `MockProvider` 模式）
- [ ] **测试 3**：`SessionMemory` set / get / snapshot 基本读写（基于 `InMemoryStore`） - [ ] **测试 3**：`Plan` / `Step` / `StepStatus` 状态机转换正确
- [ ] **测试 4（可选）**：`JsonPlanParser::parse` 能解析合法 JSON，失败时返回 `AgentError::PlanParse` - [ ] **测试 4（可选）**：session_data set/get 基本读写
### 6.4 文档验收 #### 6.2d 行为验收
- [ ] `docs/7-agent-runtime.md`（本文件）完整、6 段式结构齐备
- [ ] `docs/note-agent-runtime-design.md` 与本文件互相引用一致
- [ ] `docs/note-agent-harness-references.md` 与本文件互相引用一致
- [ ] `docs/roadmap.md` Phase 4 状态从 ❌ 缺失 改为 ✅，交付物清单更新
### 6.5 行为验收（人工 review）
- [ ] `AgentSession::submit_turn` 不持有 `ConversationMemory`（grep 验证无 `use crate::memory::ConversationMemory`） - [ ] `AgentSession::submit_turn` 不持有 `ConversationMemory`（grep 验证无 `use crate::memory::ConversationMemory`）
- [ ] `AgentSession` 持 `Arc<dyn Agent>`，可从 agent 获取 `system_prompt()` / `tool_definitions()` - [ ] `AgentSession` 持 `Arc<dyn Agent>`，可从 agent 获取 `system_prompt()` / `tool_definitions()`
- [ ] `RuntimeBundle::new` 当 `retriever` 为 `Some` 时自动注册 `"retrieve"` tool - [ ] `RuntimeBundle::new` 当 `retriever` 为 `Some` 时自动注册 `"retrieve"` tool
- [ ] `AgentBuilder::build` 在必填字段缺失时返回 `AgentError::Config`（而非 panic） - [ ] `AgentBuilder::build` 在必填字段缺失时返回 `AgentError::Config`（而非 panic）
- [ ] `AgentError::is_recoverable()` 对各变体返回正确分类
---
### 6.3 Phase 4b 验收
#### 6.3a 代码验收
- [ ] 追加代码 ~200 行（增量，在 Phase 4a 基础上），与 §4.5 预估一致
- [ ] `src/llm/hooks.rs` 追加 OnPlanStepComplete + plan_step_index（不修改 Phase 4a 新增内容）
#### 6.3b 接口验收
- [ ] `TaskAgent` trait 提供双入口 `run(goal)` + `execute_plan(plan)`
- [ ] `PlanParser` trait 可注入，`JsonPlanParser` 参考实现基于 `serde_json`（~20 行）
- [ ] `AgentError` 追加 PlanParse 变体（共 7 个变体）
- [ ] `HookEvent` 追加 1 个变体：`OnPlanStepComplete`
- [ ] `HookContext` 追加 1 个 `Option` 字段：`plan_step_index`
#### 6.3c 测试验收
- [ ] **测试 1**：`TaskAgent::execute_plan` 跑通 mock provider
- [ ] **测试 2**：`JsonPlanParser::parse` 能解析合法 JSON，失败时返回 `AgentError::PlanParse`
- [ ] **测试 3（可选）**：`OnPlanStepComplete` hook 触发正确
---
### 6.4 Phase 4c 验收
#### 6.4a 代码验收
- [ ] 追加代码 ~115 行（增量，在 Phase 4a 基础上），与 §4.5 预估一致
- [ ] 新增文件：`agent/session_memory.rs`
#### 6.4b 接口验收
- [ ] `SessionMemory` 包含 5 个方法（set / get / snapshot / remove / clear），基于 `MemoryStore` 实现
- [ ] `SessionMemory::snapshot` 返回 `<session-context>` 标签包裹的格式化文本
- [ ] `RuntimeBundle` 追加 `session_memory_backend: Option<Arc<dyn MemoryStore>>` 字段
- [ ] `AgentBuilder` 追加 `.session_memory_backend()` setter
- [ ] `AgentSession` 替换内联 HashMap 为完整 `SessionMemory`，含 `session_memory: SessionMemory` 字段
- [ ] `SessionMemory` 在 `session_memory_backend` 未传入时自动使用 `InMemoryStore` 兜底 - [ ] `SessionMemory` 在 `session_memory_backend` 未传入时自动使用 `InMemoryStore` 兜底
#### 6.4c 测试验收
- [ ] **测试 1**：`SessionMemory` set / get / snapshot 基本读写（基于 `InMemoryStore`）
- [ ] **测试 2**：session_data 内联 HashMap ↔ SessionMemory 替换后 submit_turn 行为不变
---
### 6.5 文档验收
- [ ] `docs/7-agent-runtime.md`（本文件）完整，6 段式结构齐备
- [ ] `docs/note-agent-runtime-design.md` 与本文件互相引用一致
- [ ] `docs/note-agent-harness-references.md` 与本文件互相引用一致
- [ ] `docs/roadmap.md` 各子阶段状态按阶段翻转
### 6.6 风险验收 ### 6.6 风险验收
- [ ] 5.1 抽象化边界：trailt 列表中**不包含** Multi-Agent / Skills / TUI / Gateway 等应用层能力 - [ ] 5.1 抽象化边界：交付物列表中**不包含** Multi-Agent / Skills / TUI / Gateway 等应用层能力
- [ ] 5.2 Phase 0-3 侵入：`git diff` 显示 `src/llm/hooks.rs` 仅追加 - [ ] 5.2 Phase 0-3 侵入：`git diff` 显示 `src/llm/hooks.rs` 仅追加
- [ ] 5.3 语言差异：trait 形状符合 Rust 惯例（无 Python 风格的复杂继承） - [ ] 5.3 语言差异：trait 形状符合 Rust 惯例（无 Python 风格的复杂继承）
- [ ] 5.4 trait 稳定性：决策记录与最终代码一致 - [ ] 5.4 trait 稳定性：决策记录与最终代码一致
- [ ] 5.5 实施进度：实际工作量与 §4.4 预估偏差 < 30% - [ ] 5.5 实施进度：每个子阶段实际工作量与 §4.5 预估偏差 < 30%
## 7. 一句话总结 ## 7. 一句话总结
> **Phase 4 = 1 个 trait（Agent）+ 1 个容器（RuntimeBundle）+ 1 个会话（AgentSession, 持 Arc\<dyn Agent\>）+ 1 个会话级记忆（SessionMemory）+ 1 个任务抽象（TaskAgent）+ 4 个辅助组件（Builder / Error / PlanParser / Hook 扩展），约 800 行代码，把 Phase 0-3 已有能力"装配"成"智能体"的概念。** > **Phase 4 = 3 个子阶段：4a（核心胶水层：Agent + AgentSession + submit_turn + RuntimeBundle + Plan/Step 纯数据，~440 行）→ 4b（任务执行：TaskAgent + PlanParser/JsonPlanParser，~200 行）→ 4c（会话级记忆：SessionMemory + 接入，~115 行），合计 ~755 行，分步交付、逐段验证，把 Phase 0-3 已有能力"装配"成"智能体"的概念。**
docs/roadmap.md
+75 -23
View File
@@ -1,13 +1,13 @@
# AG Core Roadmap # AG Core Roadmap
> 定稿日期：2026-05-11 > 定稿日期：2026-05-11
> 最后更新：2026-06-10（Phase 4 方案定稿 + SessionMemory 扩展 + Context 切换备忘） > 最后更新：2026-06-10（Phase 4 拆分为 4a/4b/4c 三子阶段，方案文档同步更新）
## 愿景 ## 愿景
AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。 AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。
**当前状态**：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，Phase 4 方案文档已完成（含 SessionMemory 扩展），待编码实施。 **当前状态**：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，Phase 4 方案文档已完成（已分拆为 4a/4b/4c 三个子阶段），待 Phase 4a 编码实施。
--- ---
@@ -121,27 +121,71 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可
--- ---
### Phase 4 — Agent Runtime（智能体运行时） ### Phase 4a — Agent Core Glue（核心胶水层）
**目标**：实现多轮对话编排、任务规划与会话级记忆桥接。 **目标**：提供最小可用的 Agent Runtime——把 Phase 0-3 的能力"装配"成 `AgentSession::submit_turn`。上层可基于 4a 构建多轮对话应用。
**交付物**： **交付物**：
1. `agent.rs` + `agent/` 模块（8 个文件） 1. `agent.rs` + `agent/` 模块（7 个文件：agent/error/runtime/builder/session/task + 模块根）
2. `Agent` trait — 智能体角色定义（name / system_prompt / tool_definitions） 2. `Agent` trait — 智能体角色定义（name / system_prompt / tool_definitions）
3. `AgentSession` — 会话实例（绑定 `Arc<dyn Agent>` + `RuntimeBundle` + `SessionMemory`） 3. `AgentSession` — 会话实例（绑定 `Arc<dyn Agent>` + `RuntimeBundle` + 内联 HashMap session_data）
4. `RuntimeBundle` — 显式依赖注入容器（7 个字段，含 `session_memory_backend`） 4. `RuntimeBundle` — 显式依赖注入容器（不含 session_memory_backend）
5. `SessionMemory` — 会话级记忆（基于 `MemoryStore`，context 间信息桥接） 5. `AgentBuilder` — 链式构造入口（不含 session_memory_backend）
6. `TaskAgent` — 任务型智能体（规划 → 执行 → 反馈） 6. `AgentError` — 统一错误类型（6 个变体，不含 PlanParse）
7. `AgentBuilder` — 链式构造入口 7. `Plan` / `Step` / `StepStatus` — 纯数据结构（不含任何解析逻辑）
8. `AgentError` — 统一错误类型（聚合 LlmError / ToolError / MemoryError） 8. Hook 事件扩展：OnTurnStart / OnTurnEnd + turn_index 字段
9. Hook 事件扩展（OnTurnStart / OnTurnEnd / OnPlanStepComplete） 9. `docs/7-agent-runtime.md` — 方案设计文档（含 4a/4b/4c 分阶段计划）
10. `docs/7-agent-runtime.md` — 方案设计文档
**依赖**：Phase 0, 1, 2, 3（整合所有模块） **依赖**：Phase 0, 1, 2, 3
**优先级**：Could Have **优先级**：Could Have
**预估规模**：约 800 行代码 **预估规模**：约 440 行代码
**状态**：✅ 方案已完成，待编码实施
---
### Phase 4b — Task Execution（任务执行）
**目标**：在 Phase 4a 基础上，赋予智能体"拆解目标 → 逐步执行"的能力。
**前置条件**：Phase 4a 已完成。
**交付物**：
1. `TaskAgent` trait — `run(goal)` 自主式 + `execute_plan(plan)` 外部驱动式
2. `PlanParser` trait + `JsonPlanParser` 参考实现
3. `AgentError` 追加 PlanParse 变体
4. Hook 事件扩展：OnPlanStepComplete + plan_step_index 字段
**依赖**：Phase 4a
**优先级**：Could Have
**预估规模**：约 200 行代码（增量）
**状态**：⏳ 待 Phase 4a 完成后启动
---
### 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 完成后启动
--- ---
@@ -153,15 +197,19 @@ graph BT
P1["<b>Phase 1: Prompt Engineering</b><br/>PromptTemplate<br/>PromptComposer"]:::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 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 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 P4a["<b>Phase 4a: Core Glue</b><br/>AgentSession<br/>RuntimeBundle<br/>Plan/Step 纯数据"]:::pending
P4b["<b>Phase 4b: Task Execution</b><br/>TaskAgent<br/>PlanParser<br/>JsonPlanParser"]:::pending
P4c["<b>Phase 4c: Session Memory</b><br/>SessionMemory"]:::pending
P1 --> P0 P1 --> P0
P2 --> P0 P2 --> P0
P3 --> P0 P3 --> P0
P2 --> P1 P2 --> P1
P4 --> P1 P4a --> P1
P4 --> P2 P4a --> P2
P4 --> P3 P4a --> P3
P4b --> P4a
P4c --> P4a
classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
@@ -237,7 +285,7 @@ graph BT
|-------|---------|------|--------|------| |-------|---------|------|--------|------|
| Agent 身份切换（角色轮换） | `agent` | 借鉴 OpenCode Tab 键切换 build/plan：同一 `AgentSession` 持有可热替换的 `Agent` 引用，切换时不重置消息历史，在末尾追加 `synthetic: true` 的状态变更消息。详见 `docs/note-opencode-agent-switching.md` §4 | P2 | v0.2 待评估 | | 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 待评估 | | 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 待评估 | | **多 Context 切换** | `agent` | **Phase 4c 的 SessionMemory 数据结构已预留信息桥接通道，v0.2+ 在其上包装 `ContextManager` 实现完整的多 context 切换：创建/销毁/切换 context、通过 SessionMemory 桥接关键信息。详见 `docs/note-context-switch-design.md`** | P2 | v0.2 待评估 |
--- ---
@@ -247,20 +295,24 @@ graph BT
2. **并行可能性**：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付 2. **并行可能性**：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付
3. **MCP 协议复杂性**：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节 3. **MCP 协议复杂性**：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节
4. **Scope 蔓延风险**：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计 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` 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 双进程等） 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 状态 1. **Phase 4a 实施方案**：`docs/7-agent-runtime.md` 方案文档已完成（拆分为 4a/4b/4c 三阶段），下一步启动 Phase 4a 编码实现，按 10 个任务完成后翻转 Roadmap 状态。4b/4c 待 4a 交付后按需启动
2. **Context 切换备忘**：`docs/note-context-switch-design.md` 记录了多 context 切换方案讨论，作为 v0.2+ 扩展项的输入 2. **Context 切换备忘**：`docs/note-context-switch-design.md` 记录了多 context 切换方案讨论，作为 v0.2+ 扩展项的输入
3. **参考项目调研沉淀**：已完成 OpenClaw / Hermes / OpenHuman / OpenHarness 横向调研，结果沉淀至 `docs/note-agent-harness-references.md`，作为 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+ 记忆扩展可直接参考 4. **Phase 3 备用设计就绪**：`docs/note-knowledge-graph-design.md` 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，v0.2+ 记忆扩展可直接参考
**已完成阶段**： **已完成 / 进行中阶段**：
- ✅ Phase 0 Foundation — 全部交付物已完成 - ✅ Phase 0 Foundation — 全部交付物已完成
- ✅ Phase 1 Prompt Engineering — 全部交付物已完成 - ✅ Phase 1 Prompt Engineering — 全部交付物已完成
- ✅ Phase 2 Tool System — 全部交付物已完成 - ✅ Phase 2 Tool System — 全部交付物已完成
- ✅ Phase 3 Memory System — 全部交付物已完成 - ✅ Phase 3 Memory System — 全部交付物已完成
- ✅ Phase 4 方案已完成（拆分为 4a/4b/4c） — 待 4a 编码实施
- ⏳ Phase 4a Core Glue — 方案就绪，待编码
- ⏳ Phase 4b Task Execution — 依赖 4a
- ⏳ Phase 4c Session Memory — 依赖 4a