From 528a17f5faad05a4388d4851ec5a99d814aceb56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Tue, 21 Jul 2026 22:44:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20=E6=9B=B4=E6=96=B0=20v0.4.0=20?= =?UTF-8?q?=E8=A7=84=E5=88=92=E7=8A=B6=E6=80=81=EF=BC=8C=E5=BD=92=E6=A1=A3?= =?UTF-8?q?=E5=B7=B2=E5=AE=8C=E6=88=90=20Phase?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/roadmap-unsorted.md | 129 +++++++++++++++++++++++++++++++++------ docs/roadmap.md | 5 +- 2 files changed, 113 insertions(+), 21 deletions(-) diff --git a/docs/roadmap-unsorted.md b/docs/roadmap-unsorted.md index a6abea3..f7587cb 100644 --- a/docs/roadmap-unsorted.md +++ b/docs/roadmap-unsorted.md @@ -5,7 +5,8 @@ > **已分版本的内容**：请查阅 > - [`roadmap-v0.1.0.md`](./roadmap-v0.1.0.md) — Phase 0–4c + v0.1.0 Release > - [`roadmap-v0.2.0.md`](./roadmap-v0.2.0.md) — Phase 5–12 + v0.2.0-rc.1 -> - [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) — Phase 13–19（13-18 已完成，19 待实施） +> - [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) — Phase 13–19（全部完成） +> - [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) — Phase A-E 多 Agent 编排路线图 > > 返回总入口：[`roadmap.md`](./roadmap.md) @@ -15,7 +16,7 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。 -**当前状态**：v0.2.0-rc.1 已打标签。Phase 0-18 全部完成。v0.3.0 实施中，Phase 19 共 1 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。 +**当前状态**：v0.3.5。Phase 0-30 全部完成。v0.4.0 规划已确定，覆盖 5 个增量 Phase（A-E）：Swarm 编排抽象、结果聚合、Human-in-the-loop + 用户 Steering、TokenJuice 语义压缩、自动校正。目标是从"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。 --- @@ -35,21 +36,30 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可 --- -## v0.4+ 展望 +## v0.4.0 规划 -### 已规划的功能 +v0.4.0 的完整规划已移入独立的 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md)，包含 5 个增量 Phase： -| 功能 | 说明 | 预计版本 | -|------|------|---------| -| Multi-Agent Swarm 编排 | Supervisor/Subgraph 模式，基于 v0.3 dispatch 构建 | v0.4 | -| Human-in-the-loop 审批 | `interrupt()` + `Command(resume=...)` 异步审批回调 | v0.4 | -| Agent 自动创生 | LLM 自主决定何时派发子 agent、派发什么角色 | v0.4 | -| 分布式 session 共享 | SessionManager Redis 后端支持跨进程 | v0.4 | -| 精确 tokenizer 计数 | 引入 `tiktoken-rs`，绑定模型具体 tokenizer，替换字符估算 | v0.4+ | -| TokenJuice 语义压缩 | 对工具结果做语义压缩而非字节截断 | v0.4+ | -| Markdown 技能按需加载 | 技能注册表 + 按 prompt 上下文动态加载 | v0.4+ | -| 增量 checkpoint | 仅存储变化部分，替换当前全量 JSON 模式 | v0.4+ | -| RL 轨迹导出 | ShareGPT 格式轨迹、Atropos 集成 | v0.4+ | +| Phase | 内容 | 状态 | +|-------|------|------| +| **Phase A** | Swarm 编排（Star/Sequential/Hierarchical + Subgraph） | 📋 待实施 | +| **Phase B** | 结果聚合 + 编排模式完善 | 📋 待实施 | +| **Phase C** | Human-in-the-loop + 用户 Steering | 📋 待实施 | +| **Phase D** | TokenJuice 语义压缩（工具结果/历史/跨 Agent） | 📋 待实施 | +| **Phase E** | 自动校正 / Reflection | 📋 待实施 | + +### 未来版本（v0.5+） + +以下功能已从 v0.4 范围移出： + +| 功能 | 说明 | +|------|------| +| Agent 自动创生 | LLM 自主决定何时派发子 agent — 设计复杂，v0.4 专注显式声明式编排 | +| 分布式 session 共享（Redis 后端） | 与编排正交，多数用户单进程即可 | +| 精确 tokenizer 计数（tiktoken-rs） | 依赖引入，不在 v0.4 核心范围内 | +| 增量 Checkpoint | 存储优化，当前全量 JSON 够用 | +| 路线 B（StateGraph 通用图引擎） | 预留为路线 A 的未来升级路径 | +| RL 轨迹导出 | 专项需求 | ### 明确不做（agcore 范围外） @@ -74,10 +84,10 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可 ## 下一步行动 -1. **v0.3.0 Phase 19 启动**：KnowledgeGraph + 双通道检索，落地 `docs/note-knowledge-graph-design.md` 中记录的知识图谱设计 -2. **Phase 19 收尾**：完成 v0.3.0 最后一个 Phase 后准备 rc.1 标签 + CHANGELOG -3. **示例先行**：完成 Phase 19 后立即创建对应的 knowledge_graph_demo 示例，确保 `cargo run --example` 可验证 -4. **里程碑追踪**：以 M13（Phase 17）+ M14（Phase 18）为已达成里程碑，逐 Phase 推进 M15 +1. **v0.4.0 启动**：按 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) 规划，从 Phase A（Swarm 编排）开始实施 +2. **Phase A 实施**：engine/supervisor.rs + tools/builtin.rs + Swarm::star/sequential/hierarchical +3. **示例先行**：每个 Phase 交付时同步提交对应的示例程序 +4. **里程碑追踪**：以 M16-M20 为目标里程碑，逐 Phase 推进 --- @@ -107,3 +117,84 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可 - ✅ **v0.3.0 Phase 16 完成** — `SummaryConfig` 配置结构体（6 个字段：`trigger_token_ratio=0.75` / `max_context_tokens=32_000` / `summary_prompt` / `debounce_turns=3` / `summary_model=None` / `max_tool_result_chars=500`，默认 `None` 沿用主模型避断裂非 OpenAI 用户）+ `AgentBuilder::summary_config(cfg)` 链式方法 + `AgentConfig.summary_config: Option` 字段；`AgentSession` 新增 `last_summary_turn: Option` 字段（首次不受防抖约束，`should_summarize` 用 `Option` 哨兵实现）+ `maybe_summarize(current_turn)` 内联检查点（OnTurnEnd 之后 / `turn_index` 之前，对称 `submit_turn` / `finalize_turn` 两个入口，流式路径 `saturating_sub(1)` 修正）+ 关联函数 `generate_summary`（构造独立 `LlmCycle` 调 `submit_messages` 传 `vec![Message::user_text(prompt)]`，`max_tokens=1024`，空消息守卫直接返回空串）+ 公开 API `get_conversation_summary()`；`src/agent/summary.rs`（~240 行，含 8 个 SummaryConfig/`format_messages_as_text` 内联测试——默认值/空输入/系统用户助理/ToolResult（含 `tool_call_id`）/工具调用/Unicode 安全截断/整体 30K 截断保留最新；有效字符数截断多字节安全，droptest 验证保留尾部消息）+ `src/agent/session.rs` 注入 10 个摘要集成测试（默认值不触发 / 超阈值触发 / 防抖阻止重复 / SessionMemory 写入 / Full 模式不注入 / 失败不阻断主流程 / 流式路径触发 / 默认配置零影响 / **Focused `summary_override` 写入正向验证** / **空消息不调用 LLM** / **巨型 `max_context_tokens` 永不触发**）；`format_messages_as_text` 简洁版消息格式化（`[Tool: name]` + `Tool Result [id]:` + ToolResult 字符级 `chars().take(max_tool_result_chars)` 截断 + 整段 30K 总长度截断从头部保留最新）；所有错误静默（失败用 `tracing::error!`，成功用 `tracing::info!(turn, summary_len)`）；`MergeStrategy` 注释中过时 "Summarize 指向"与 `context.rs:78` "v0.3 将支持 Hook 驱动" 过时注释在实施时同步移除/更新；方案文档 `docs/22-phase16-summary-auto-generation.md`（471 行），实施后**两轮审查 PASS**：第一轮 PM/SA 审查 11 项问题修复 + 第二轮实施审查 9 项问题修复（🔴 `generate_summary` 空消息 bug + 🟡 W4 流式路径防抖 + 🟡 W2 模型硬编码 + 🟡 W5 Full 模式无谓 save + 🟡 W3 30K 截断 + 🟡 W6 成功无日志 + 🟡 W1/W7 测试补全 + 💭 注释同步）；零新外部依赖；全量 335 → **353**（+18 新测试，含二次审查增补 4 个），clippy 0 警告，doc 0 warning，`quick_start` 示例正常 exit 0；**M12 里程碑达成** + 第二轮审查门禁 PASS - ✅ **v0.3.0 Phase 17 完成** — 新建 `src/engine/` 模块（5 文件：`mod.rs`/`error.rs`/`snapshot.rs`/`checkpointer.rs`/`session_manager.rs`），实现 **SessionManager**（10 个公开方法：`create`/`create_child`/`get`/`recover`/`replace`/`children`/`parent`/`destroy`/`submit_turn`/`submit_turn_stream`/`finalize_turn_stream`，内部 `RwLock` + `Arc>` + `Checkpointer` 组合）和 **Checkpointer**（5 个公开方法：`checkpoint`/`rollback_load`/`list_checkpoints`/`delete_all`/`latest_snapshot`）；`SessionSnapshot` 独立 struct 避开 `Arc` 不可序列化，配套 `SessionMemoryEntry` 保留 metadata/created_at；`AgentSession` 扩展三段式快照（`to_snapshot` async 读 MemoryStore + `from_snapshot` 纯同步构造 + `restore_memory` &mut self async 写回持久层）；`SessionMemory` 新增 `list_entries()` 和 `set_with_meta()` 方法（恢复时保留完整 entry 数据）；存储 key 风格统一为 `session:{id}:meta` / `ckpt:{id}:{ckpt_id}`（与 `slot_data:` 风格一致）；`EngineError` 6 个变体（含 `Memory(#[from] MemoryError)` 透传 + `Agent(#[from] AgentError)`）；`CkptMeta` 加 `created_at_nanos` 字段确保同秒内精确降序排序；ckpt_id 用纳秒+单调计数器生成（零外部依赖，ponytail）；session_id 用纳秒+计数器自动生成（统一策略，UUID v4 备选）；自动 checkpoint 失败 `tracing::error!` 不阻断主流程（不提供强持久化保证）；流式 checkpoint 仅在 `finalize_turn_stream` 创建（不留半成品污染）；孤儿策略：`destroy()` 不递归删除子 session，父被销毁后 `parent()` 返回 `Ok(None)`；3 处 derive 改动（`CostTracker` + `ContextSlot` + `MergeStrategy` 加 serde，`CostTracker` 额外加 `Clone`）；`SessionManager::recover` + `replace` 内部自动 `restore_memory` 写回持久层；零新外部依赖；方案文档 `docs/23-phase17-agent-execution-engine.md`（775 行，经两轮 PM+SA 审查 + 实施后第三轮 PM+SA+Code Reviewer 三方联合审查），实施后**两轮审查门禁 PASS**：第一轮修复 6 🔴 + 第二轮修复 2 🔴（to_snapshot 同步→async + Roadmap 同步）+ 实施后修复 8 个 🟡（restore_memory metadata/created_at 完整恢复 + &mut self 签名 + 死代码清理 + 3 个边界测试 + tracing 补全 + 文档语义统一 + 示例 rollback 一致性 assert）；15 个 `SessionManager` 内联测试（CRUD/recover/replace/树形/孤儿/auto_checkpoint on-off）+ 6 个 `Checkpointer` 内联测试（roundtrip/不存在的 ckpt/同秒降序/delete_all 幂等/latest/隔离）+ 1 个 `snapshot_deserialize_with_minimal_fields` 序列化兼容测试；全量 353 → **374**（+21 新测试），clippy 0 警告，doc 0 warning，`engine_demo` 示例端到端演示 create→submit_turn→checkpoint→rollback→replace→destroy 全链路并验证 rollback 一致性；**M13 里程碑达成** + 两轮审查门禁 PASS - ✅ **v0.3.0 Phase 18 完成** — 新增 `src/engine/switch.rs`（222 行）实现 `SessionManager::switch_agent()` 热切换（替换 `Arc`，slot 历史 / `turn_index` / `session_memory` / `cost_so_far` 全部保留，同步更新 `SessionMeta.agent_name` 到持久层，`created_at` / `parent_id` 保持原始不可变）+ 新增 `src/engine/sub_agent.rs`（1071 行）实现 4 个公开方法（`dispatch` / `dispatch_all` / `dispatch_stream` 与前述 `switch_agent` 共 4 个 Phase 18 核心 API）+ 3 个公开类型（`DispatchConfig` / `SubTaskResult` / `SubTaskStreamEvent`）；`DispatchConfig` 4 字段（`max_concurrency=10` / `inherit_session_memory=true` / `bridge_keys=None` / `shared_namespace=None`）+ 三态 `bridge_keys` 语义（`None` = 不继承 / `Some(vec![])` = 全部 / `Some(keys)` = 指定 keys）+ 约定式 `shared_namespace` 子↔子共享（`shared:{prefix}:{key}`）不触发自动注入；`dispatch` 流程：`create_child` → `inherit_session_memory`（快照语义）→ `submit_turn` → 返回 `SubTaskResult`；`dispatch_all` `tokio::sync::Semaphore` 并发控制 + `Vec>` 部分成功语义按输入顺序 indexed 收集；`dispatch_stream` `unbounded_channel` + spawn task 消息重建 + `finalize_turn` 后台落库（明确不参与 `auto_checkpoint` 防重复）；`SubTaskStreamEvent` 事件序列：`ChildCreated` → `Stream(StreamEvent) × N` → `Completed(SubTaskResult)` 或 `Error { child_id, error }`；`EngineError` 新增 `DispatchFailed(#[source] String)` 变体 + `CostTracker` 加 `From` 转换；`save_session_meta` / `load_session_meta` 改 `pub(crate)` 供 `switch.rs` 调用；4 个端到端示例：`agent_switch_demo`（115 行）+ `sub_agent_dispatch_demo`（141 行）+ `bridge_keys_demo`（197 行）+ `dispatch_stream_demo`（121 行）全部 exit 0；17 个内联测试（4 switch + 5 dispatch + 4 dispatch_all + 4 dispatch_stream）；零新外部依赖；方案文档 `docs/24-phase18-agent-switch-and-dispatch.md`（700 行）；全量 374 → **391**（+17 新测试，0 失败），clippy 0 警告，doc 0 warning；**M14 里程碑达成** +- ✅ **v0.3.0 Phase 19 完成** — 知识图谱 + 双通道检索，详见 `docs/25-phase19-knowledge-graph-and-retrieval.md`；全量 391 → **427 passed / 0 failed**（+36 新测试）；**M15 里程碑达成** +- ✅ **v0.3.2 Phase 20-27 全部完成** — Cargo features 拆分（16 模块级 + 5 provider + 4 快捷组合），详见 `docs/roadmap-v0.3.2.md`；全量 427 → **427 passed**（不变，门控验证） +- ✅ **Phase 28-30 OpenAI Response API Provider 完成** — 独立 feature `provider-openai-response`，全量约 450 passed +- 📋 **v0.4.0 规划完成** — 5 个增量 Phase（A-E）覆盖多 Agent 编排、HITL + Steering、TokenJuice、自动校正。详见 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) + +--- + +## 设计笔记 + +### Checkpointer 分层存储模型 + +> 来源：v0.4.0 规划讨论中涉及增量 Checkpoint 的技术推演。当前全量 JSON checkpoint 够用，但为未来优化预留设计方案。 + +#### 分层叠加模型（OverlayFS 模式） + +受容器分层文件系统启发，增量 Checkpoint 可以借鉴 overlayfs 的"底层只读 + 上层可写叠加"设计： + +**全量基座（只读）**： +```rust +pub struct SnapshotBase { + pub checkpoint_id: String, + pub session_id: String, + pub snapshot: SessionSnapshot, // 完整 JSON 化状态 +} +``` + +**增量层（叠加 diff）**： +```rust +pub struct SnapshotLayer { + pub base_checkpoint_id: String, + pub applies_to_id: String, // 在哪个 checkpoint 上叠加 + pub diff: Vec, // JSON Patch 操作集合 +} + +pub enum DiffOp { + MessageAppended { message: Message }, + SlotChanged { slot_id: String, diff: serde_json::Value }, + TurnIndexIncremented { from: u32, to: u32 }, + CostUpdated { diff: CostTracker }, +} +``` + +**重建路径**： +``` +rollback_load("session_x", 6) + → 读取 "ckpt:{session_x}:base"（全量） + → 读取 "ckpt:{session_x}:layer:1" ~ "ckpt:{session_x}:layer:6" + → 依次应用 layer.1 → layer.2 → ... → layer.6 + → 得到 session_6 的状态 +``` + +**层折叠（类似 docker squash）**： +``` +layer.1 → layer.2 → layer.3 → layer.4 → layer.5 + ↓ 合并 +base.ckpt'（包含 layer.1-3）→ layer.4 → layer.5 +``` + +#### Shadow FS 模型（运行中保护） + +与分层模型互补，shadow 模型适用于运行中的 session 保护而非长期存储： + +```rust +// submit_turn 在 shadow session 上执行，commit 时才原子切换 +let shadow = current_session.fork(); // 复用 ContextSlot::fork +let result = shadow.submit_turn(input).await; +if result.is_ok() { + current_session.commit(shadow); // 原子替换 +} else { + drop(shadow); // 丢弃，当前 session 完好无损 +} +``` + +#### 适用场景对比 + +| 模型 | 适合场景 | 不适合场景 | +|------|---------|-----------| +| **分层叠加（OverlayFS）** | Checkpoint 链长期存储、time-travel、多版本回退 | session 较小（< 10KB/轮）时复杂度不值得 | +| **Shadow FS（CoW）** | 运行中 session 保护、防止 submit_turn 失败污染 | 不能替代 checkpoint 链、不支持多时间点回退 | + +**触发条件**：当单 session checkpoint 超过 500KB 且频繁保存导致性能瓶颈时，考虑实现分层模型。 diff --git a/docs/roadmap.md b/docs/roadmap.md index bc4b036..288d569 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,7 @@ # AG Core Roadmap > 拆分式 roadmap：按版本归档 + 未归类内容 -> 最后更新：2026-07-20（Phase 28-30 OpenAI Response API Provider 交付 — 新增独立 feature `provider-openai-response`，450 测试通过） +> 最后更新：2026-07-21（v0.4.0 规划完成 — Phase A-E 多 Agent 编排路线图制定） ## 文件索引 @@ -12,11 +12,12 @@ | [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) | v0.3.0 计划与交付 - Phase 13–19 | ✅ Phase 13-19 全部完成，v0.3.0 交付完毕 | | [`roadmap-v0.3.2.md`](./roadmap-v0.3.2.md) | v0.3.2 计划与交付 — Phase 20–27（Cargo features 拆分） | ✅ Phase 20-27 全部完成，v0.3.2 交付完毕 | | [`28-phase28-openai-response-api-provider.md`](./28-phase28-openai-response-api-provider.md) | Phase 28-30 OpenAI Response API Provider 实施方案（独立 feature `provider-openai-response`） | ✅ Phase 28-30 已交付 | +| [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) | v0.4.0 计划 — Phase A-E（Swarm 编排、HITL + Steering、TokenJuice 语义压缩、自动校正） | 📋 计划中 | | [`roadmap-unsorted.md`](./roadmap-unsorted.md) | 未归到任何版本的内容 — 全局愿景、当前状态、模块完整性、v0.4+ 展望、风险与建议、下一步行动、阶段总回顾 | — | ## 阅读建议 -- **按版本顺序追溯历史**：v0.1.0 → v0.2.0 → v0.3.0 +- **按版本顺序追溯历史**：v0.1.0 → v0.2.0 → v0.3.0 → v0.4.0 - **了解产品演进全貌**：从 `roadmap-unsorted.md` 顶部开始读 - **查找特定 Phase**：每个版本文件内按 Phase 编号顺序排列 - **了解项目当前关注点**：从 `roadmap-unsorted.md` 的「下一步行动」开始