Compare commits
4
Commits
v0.3.5
...
c5afa4b31e
| Author | SHA1 | Date | |
|---|---|---|---|
 徐涛
|
c5afa4b31e | ||
|
徐涛
|
28ca43ccb2 | ||
|
徐涛
|
528a17f5fa | ||
|
徐涛
|
d48286a942 |
@@ -186,29 +186,64 @@ pub use vector_store::VectorStore;
|
||||
|
||||
## 文档规范
|
||||
|
||||
### 方案规范 (docs/)
|
||||
### 文档编号规范（design/pdd/ + design/prd/）
|
||||
|
||||
**编号规则**：创建新方案前必须先通过 shell 命令确认当前实际最大编号（Unix: `ls docs/` / Windows: `dir docs\`），禁止使用上下文中缓存的编号，如遇冲突自动递增
|
||||
`design/pdd/`（方案文档）和 `design/prd/`（需求文档）使用相同的命名格式，但**各自独立编号**：
|
||||
|
||||
**方案文档结构**（6 项）：
|
||||
1. **背景与目标** - 问题描述、预期目标
|
||||
2. **需求分析** - 功能需求、非功能需求
|
||||
3. **方案设计** - 架构设计、模块划分、接口定义
|
||||
4. **实现计划** - 任务拆解、优先级、时间估算
|
||||
5. **风险评估** - 潜在风险、缓解措施
|
||||
6. **验收标准** - 可验证的完成条件
|
||||
```
|
||||
<序号>-<简短描述>.md
|
||||
```
|
||||
|
||||
### 进度同步规范 (docs/roadmap.md)
|
||||
规则：
|
||||
- 序号使用数字，从 1 开始递增。**创建前必须通过 shell 命令确认目标目录当前实际最大编号再加 1：**
|
||||
```bash
|
||||
# 查 design/pdd/ 的最大编号
|
||||
ls design/pdd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
|
||||
# 查 design/prd/ 的最大编号
|
||||
ls design/prd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
|
||||
# 无输出则从 1 开始
|
||||
```
|
||||
禁止使用上下文中缓存的编号。
|
||||
- 描述：中文，简短概括主题
|
||||
- 两个目录各自独立编号——`design/pdd/` 已有 `3-` 时，`design/prd/` 的新文件仍从当前最大号 +1 开始，互不影响
|
||||
|
||||
完成一项实施后，必须检查 `docs/roadmap.md` 是否存在对应内容；若存在，必须同步标记为完成：
|
||||
方案文档（`design/pdd/`）应包含：
|
||||
- 背景与目标
|
||||
- 需求推演概要（需求拆解、边界识别、关键假设的简要推演）
|
||||
- 当前问题分析
|
||||
- 架构决策记录（重大技术选型、架构变更的决策过程与理由）
|
||||
- 设计方案（含架构图/流程图）
|
||||
- 实施步骤
|
||||
- 验证标准
|
||||
- 回滚方案（如适用）
|
||||
|
||||
- **Step / Phase 状态行**：对应 Step 加 ✅ 标记；Phase 章节末尾「状态」行从 ⏳ 改为 ✅ Phase X 全部交付物已完成
|
||||
- **里程碑表**：更新对应里程碑状态从 ⏳ 改为 ✅ + 完成日期
|
||||
- **依赖关系图（Mermaid）**：节点 `class` 从 `pending` / `core` 改为 `done`，必要时更新节点摘要
|
||||
- **文末「已完成 / 进行中阶段」列表**：追加一行 `- ✅ Phase X — 一句话要点`
|
||||
- **顶部「当前状态」**：补充新完成 Phase，更新「下一步」指向
|
||||
示例：
|
||||
- `design/pdd/1-ui-components重构方案.md`
|
||||
- `design/prd/1-用户认证需求.md`
|
||||
- `design/pdd/2-数据库迁移方案.md`
|
||||
|
||||
参考案例：2026-07-05 完成 Phase 7 SqliteStore 时同步更新 6 处（顶部状态 / Phase 章节 / 依赖图 / M3 / 下一步行动 / 已完成列表）。
|
||||
---
|
||||
|
||||
### 设计目录（design/）
|
||||
|
||||
项目根下的 `design/` 目录集中管理所有设计相关的文件，供人类和 agent 共同读写。
|
||||
|
||||
| 子目录 | 内容 | 谁写 | 谁读 |
|
||||
|--------|------|------|------|
|
||||
| `design/pdd/` | 方案设计文档（PDD）→ 架构方案、设计决策、转换方案 | proposal→writer pipeline | Think 参考、Build 实现、Vet 审查 |
|
||||
| `design/prd/` | 需求文档（PRD）→ 功能需求、用户故事、验收标准 | 人写 | Think 分析、Proposal 写方案时参考 |
|
||||
| `design/prototype/` | **OD 导出的原型 HTML** → 视觉稿、交互原型、页面 layout | OD 桌面版导出 | Think 分析结构、Build 对照实现 |
|
||||
| `design/notes/` | 笔记记录 → 零散想法、会议纪要、调研速记 | 人写 | 各 agent 参考 |
|
||||
| `design/roadmap/` | 路线图 → 里程碑规划、版本计划、优先级列表 | 人写 | Proposal 排期参考 |
|
||||
| `design/DESIGN.md` | 设计系统（品牌规范）→ 色板、字体、间距、语气 | OD 导出 / 人维护 | Think 提取 token、Build 同步到 `src/` |
|
||||
| `design/tokens.css` | 设计 Token CSS → 从 DESIGN.md 提取的 CSS 变量 | 人同步 / agent 同步 | 所有 Svelte 组件引用 |
|
||||
|
||||
**访问规则：**
|
||||
- 读：所有 agent 默认可读（`read_file` 不需要额外权限）
|
||||
- 写：writer agent 可通过 `"design/**": allow` 写入 `design/` 下任意子目录
|
||||
- 注意：`prototype/` 由 OD 桌面版导出，agent 只读不写；`DESIGN.md` 和 `tokens.css` 建议手动维护或 agent 写入时确认后再改
|
||||
|
||||
**兜底规则：** 文档类型不在上表时（如教程、接口文档、临时记录），或目标目录不存在时 → **向用户提问确认路径**。不允许自行推断存放位置。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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<SummaryConfig>` 字段；`AgentSession` 新增 `last_summary_turn: Option<u32>` 字段（首次不受防抖约束，`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<HashMap>` + `Arc<tokio::sync::Mutex<AgentSession>>` + `Checkpointer` 组合）和 **Checkpointer**（5 个公开方法：`checkpoint`/`rollback_load`/`list_checkpoints`/`delete_all`/`latest_snapshot`）；`SessionSnapshot` 独立 struct 避开 `Arc<dyn Agent>` 不可序列化，配套 `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<dyn Agent>`，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<Result<...>>` 部分成功语义按输入顺序 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<Usage>` 转换；`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<DiffOp>, // 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 且频繁保存导致性能瓶颈时，考虑实现分层模型。
|
||||
@@ -0,0 +1,233 @@
|
||||
# AG Core Roadmap — v0.4.0
|
||||
|
||||
> 本文件聚焦 **v0.4.0 版本** 的规划。Phase A-E 计划中，覆盖多 Agent 编排、Human-in-the-loop 与 Steering、语义压缩、自动校正。
|
||||
> 返回总入口：[`roadmap.md`](./roadmap.md)
|
||||
|
||||
## v0.4.0 愿景
|
||||
|
||||
从 v0.3 的"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。补齐高层编排抽象（Swarm/Supervisor/Subgraph）、生产级人工干预能力（HITL + Steering）、工具与消息的语义压缩（TokenJuice），以及自动质量校正（Reflection）。为即将开发的多 Agent 协作产品提供完整的编排、干预与质量保证层。
|
||||
|
||||
## v0.4.0 总体范围
|
||||
|
||||
**总体规模**：5 个增量 Phase（Phase A-E），总新增代码约 1,950 行，零强制新外部依赖，零破坏性变更。
|
||||
|
||||
### 架构决策
|
||||
|
||||
**路线选择**：采用轻量编排模式（路线 A），不引入通用有向图引擎。通过 `Swarm::star()` / `Swarm::sequential()` / `Swarm::hierarchical()` 等具名模式提供编排能力，底层复用现有 `dispatch` / `create_child` / `SessionManager` 基础设施。预留路线 B（StateGraph 抽象）作为未来版本的升级路径。
|
||||
|
||||
**模块位置**：
|
||||
- 编排逻辑 → `src/engine/supervisor.rs`（新增）
|
||||
- 内建工具 → `src/tools/builtin.rs`（新增）
|
||||
- TokenJuice 压缩 → `src/llm/compress.rs`（新增）
|
||||
- Steering 机制 → `src/engine/steer.rs`（新增，或并入 supervisor.rs）
|
||||
|
||||
### 功能清单
|
||||
|
||||
#### P0 — 必须交付
|
||||
|
||||
| # | 功能 | 模块 | 方案要点 |
|
||||
|---|------|------|---------|
|
||||
| 1 | Swarm 编排（Star/Sequential/Hierarchical + Subgraph） | `engine/supervisor` | `Swarm::star().supervisor(A).worker(B)` 声明式 API；`Swarm::sequential().link(A).link(B)` 串联；`Swarm::hierarchical().supervisor(root).group("sub", ...)` 层次嵌套 |
|
||||
| 2 | 结果聚合 | `engine/supervisor` | `aggregation_prompt` 模板将子 Agent 结果合并到 Supervisor 上下文；`DispatchConfig` 扩展 `result_key` 字段 |
|
||||
| 3 | Human-in-the-loop 审批 | `engine/steer` | `interrupt()` 暂停执行 + `Command(resume=bool)` 恢复；`HookEvent::OnInterrupt` 新变体 |
|
||||
| 4 | 用户 Steering（运行中校正） | `engine/steer` | `Command(resume=Correction{...})` 结构化校正；Steer 消息在工具批处理边界注入 |
|
||||
| 5 | TokenJuice 语义压缩 | `llm/compress` | `Compressor` trait 统一抽象；覆盖工具结果、对话历史、跨 Agent 消息三层；LLM 摘要压缩 + 确定性兜底 |
|
||||
|
||||
#### P1 — 推荐交付
|
||||
|
||||
| # | 功能 | 模块 | 方案要点 |
|
||||
|---|------|------|---------|
|
||||
| 6 | 自动校正 / Reflection | `engine/reflect` | Evaluator-Optimizer 循环；Producer-Critic 角色分离；上限 2-3 轮迭代 |
|
||||
|
||||
### 实施计划 — 5 个增量 Phase
|
||||
|
||||
> **编号说明**：Phase A-E 为 v0.4.0 专属编号，接续已完成的 Phase 30。
|
||||
|
||||
---
|
||||
|
||||
#### Phase A: Swarm 编排抽象（Star / Sequential / Hierarchical + Subgraph）
|
||||
|
||||
**目标**：在现有 `dispatch` 原语基础上，提供声明式多 Agent 编排 API。Supervisor 作为 `Arc<dyn Agent>`，通过内建工具 `dispatch_sub_agent` 驱动子 Agent 执行。
|
||||
|
||||
**交付物**：
|
||||
1. `src/engine/supervisor.rs` 新文件：
|
||||
- `Swarm` 枚举/结构体：`Swarm::star()`（星型，一个 Supervisor + N 个 Worker）、`Swarm::sequential()`（顺序链 A→B→C）、`Swarm::hierarchical()`（层次嵌套，Supervisor 下的 Sub-Supervisor）
|
||||
- 各模式的 `build()` 和 `run(input)` 方法
|
||||
- 底层通过 `SessionManager::dispatch()` / `dispatch_all()` 实现
|
||||
2. `src/tools/builtin.rs` 新文件：
|
||||
- `dispatch_sub_agent(name, task, config)` 内建工具 — 从 Agent 注册表查找 Agent 工厂 → `SessionManager::dispatch()`
|
||||
3. `AgentRegistry`：`HashMap<String, Box<dyn Fn() -> Arc<dyn Agent>>>` 轻量工厂注册表（约 50 行）
|
||||
4. Subgraph 嵌套：`Swarm::hierarchical()` 支持 `group(name, inner_swarm)`，内层 Swarm 作为子节点编译后嵌入
|
||||
|
||||
**设计要点**：
|
||||
- Supervisor 就是 `Arc<dyn Agent>`，不新增 `SupervisorAgent` trait
|
||||
- 路由逻辑写在 Supervisor 的 system prompt 中（LLM 决定的动态路由）
|
||||
- 三种模式覆盖常见编排拓扑，不引入通用图引擎（路线 B 留作未来）
|
||||
- Subgraph 编译为独立的 `SessionManager` 子树（复用 `create_child` 的父子关系）
|
||||
|
||||
**依赖**：Phase 18（SubAgent dispatch / SessionManager）
|
||||
**优先级**：P0
|
||||
**预估规模**：约 500 行
|
||||
**状态**：📋 待实施
|
||||
|
||||
---
|
||||
|
||||
#### Phase B: 结果聚合 + 编排模式完善
|
||||
|
||||
**目标**：让 Supervisor 能智能地合并 Worker 结果。完善三种编排模式的容错性和易用性。
|
||||
|
||||
**交付物**：
|
||||
1. `aggregation_prompt` 模板系统 — 内建 `DEFAULT_AGGREGATION_PROMPT`，用户可自定义聚合逻辑
|
||||
2. `DispatchConfig` 扩展：
|
||||
- `result_key: Option<String>` — 将子结果存入 `session_memory` 的指定 key，供后续阶段使用
|
||||
- `aggregate_strategy: AggregateStrategy` — `Concatenate` / `Summarize` / `Custom(Value)`
|
||||
3. 编排模式增强：
|
||||
- `Swarm::sequential()` 支持失败时停止 / 跳过 / 重试策略
|
||||
- `Swarm::star()` 支持 Worker 超时
|
||||
4. 端到端示例 3 个：
|
||||
- `swarm_star_demo.rs` — 星型编排 + 并发派发 + 结果聚合
|
||||
- `swarm_sequential_demo.rs` — 串联流水线
|
||||
- `swarm_hierarchical_demo.rs` — 层次嵌套（Supervisor → Sub-Supervisor → Worker）
|
||||
|
||||
**依赖**：Phase A
|
||||
**优先级**：P0
|
||||
**预估规模**：约 200 行
|
||||
**状态**：📋 待实施
|
||||
|
||||
---
|
||||
|
||||
#### Phase C: Human-in-the-loop + 用户 Steering
|
||||
|
||||
**目标**：生产级多 Agent 系统的关键门禁。提供执行中暂停-审批-恢复机制，以及用户运行中校正方向的能力。
|
||||
|
||||
**交付物**：
|
||||
1. `src/engine/steer.rs` 新文件：
|
||||
- `interrupt(value)` 函数 — 在工具循环中插入暂停点，持久化当前状态后返回控制权
|
||||
- `Command` 枚举：
|
||||
- `Command::Resume(bool)` — 二元审批（批准/拒绝）
|
||||
- `Command::ResumeWith(Correction)` — 结构化校正（修改工具参数 / 调整方向）
|
||||
2. `LlmCycle` 扩展：可中断工具循环模式
|
||||
- `submit_with_tools_interruptible()` — 支持在工具批处理边界检查中断信号
|
||||
- 中断时保存当前 `LlmCycle` 状态到 checkpoint
|
||||
3. `HookEvent::OnInterrupt` / `OnSteer` 新变体 — 监听中断和校正事件
|
||||
4. `SessionManager::resume_turn(session_id, resume_data)` — 从 checkpoint 恢复并注入审批结果
|
||||
5. `tools/builtin.rs` 扩展：
|
||||
- `request_approval(question, context)` — 请求用户审批
|
||||
- `emit_steer(correction)` — 用户校正
|
||||
6. Steering 生命周期：
|
||||
- `interrupt` → 用户收到提示 → 用户决定方向 → `Command::ResumeWith(correction)` → Agent 在新方向上继续
|
||||
|
||||
**设计要点**：
|
||||
- User Steering 不是简单的"批准/拒绝"，而是 `Correction { action, reason, amended_params }` 结构化指令
|
||||
- Steering 消息在工具批处理边界（Worker 返回后、Supervisor 决策前）注入，不中断正在执行的工具
|
||||
- 继承 `ContextSlot::fork/merge` 模式，steer 前 fork 快照，允许用户回退到 steer 前状态
|
||||
|
||||
**依赖**：Phase A（Swarm 编排）
|
||||
**优先级**：P0
|
||||
**预估规模**：约 500 行
|
||||
**状态**：📋 待实施
|
||||
|
||||
---
|
||||
|
||||
#### Phase D: TokenJuice 语义压缩
|
||||
|
||||
**目标**：替代当前字节级截断（`microcompact` 的 `[pruned]`），提供语义级别的压缩。在三层管道中接入：工具结果压缩、对话历史压缩、跨 Agent 消息压缩。
|
||||
|
||||
**交付物**：
|
||||
1. `src/llm/compress.rs` 新文件：
|
||||
- `Compressor` trait（`async fn compress(&self, input: &str, ctx: &CompressionContext) -> Result<String>`）
|
||||
- `CompressionContext`：`target_tokens` / `preserve_keys` / `strategy`
|
||||
- `CompressionStrategy` 枚举：`Semantic { model }`（LLM 摘要）、`Extractive { ratio }`（抽取式）、`Hybrid { semantic_first }`（混合）
|
||||
- `SemanticCompressor` 实现（复用已有 provider 做 LLM 摘要压缩）
|
||||
- `ExtractiveCompressor` 实现（确定性关键句提取，零 LLM 调用）
|
||||
2. 三层接入点：
|
||||
- **工具结果压缩**：在 `run_tool_loop` 中，`tool.execute()` 后插入 `compress_result()`，压缩结果再 `push ToolResult`
|
||||
- **对话历史压缩**：在 `load_messages()` 后插入 `compress_history()`，替代/补充 `microcompact`
|
||||
- **跨 Agent 消息压缩**：在 `inherit_session_memory` 的子 memory 写入前压缩（减少子 Agent 的 context 水位）
|
||||
3. `CycleConfig` / `CompactConfig` 扩展：
|
||||
- `token_compression: Option<CompressionConfig>` — 可选语义压缩配置
|
||||
- `fallback_to_microcompact: bool`（默认 `true`）— LLM 压缩失败时退化为字节截断
|
||||
4. TokenJuice 与现有 `microcompact` 的关系：
|
||||
- `microcompact` 保留为最轻量级兜底（零 LLM 调用）
|
||||
- TokenJuice 是可选增强层（默认关闭，用户 opt-in）
|
||||
|
||||
**设计要点**：
|
||||
- 零新外部依赖：LLM 摘要压缩复用已有 provider，抽取式压缩纯 Rust 实现
|
||||
- 与现有 `CompactState` 断路器模式兼容（LLM 压缩失败 3 次后自动降级到 `microcompact`）
|
||||
- `preserve_keys` 确保关键数据（数字、ID、SQL、代码片段）不被压缩掉
|
||||
|
||||
**依赖**：Phase 14（Embedding trait 可选参考）
|
||||
**优先级**：P0
|
||||
**预估规模**：约 400 行
|
||||
**状态**：📋 待实施
|
||||
|
||||
---
|
||||
|
||||
#### Phase E: 自动校正 / Reflection
|
||||
|
||||
**目标**：实现 Agent 输出后的自我质量评估与自动修正循环。基于 `interrupt/resume` 基础设施，构建 Producer-Critic 闭环。
|
||||
|
||||
**交付物**：
|
||||
1. `src/engine/reflect.rs` 新文件：
|
||||
- `ReflectionConfig`：`max_cycles`（默认 2）/ `critic_agent`（可选不同模型）/ `criteria: Vec<String>`（评估标准）
|
||||
- `Reflectable` trait：`fn reflection_criteria(&self) -> Vec<String>` + `fn needs_refinement(&self, critique: &Critique) -> bool`
|
||||
- `ReflectionLoop`：`evaluate(output) → Critique` → `should_refine? → yes: refine(output, critique) → 循环 / no: 返回`
|
||||
2. Swarm 内建 Reflection 模式：
|
||||
- `Swarm::reflect(producer_agent, critic_agent)` — 专用 Reflection Swarm
|
||||
- 可在 Supervisor 流程中嵌入 `reflect_on(worker_result)` — 对 Worker 结果自动过一遍质量检查
|
||||
3. `Critique` 结构体：`issues: Vec<Issue>` / `score: f32` / `should_refine: bool` / `suggestions: Vec<String>`
|
||||
4. `tools/builtin.rs` 扩展：`verify_output(claim, evidence)` 工具 — 让 Agent 自行验证输出真实性
|
||||
|
||||
**设计要点**：
|
||||
- Producer 和 Critic 使用**不同模型**（避免同一模型的自我审查盲区 bias）
|
||||
- 上限 2-3 轮（第一轮修正捕获 70–80% 改善空间，第 4+ 轮收益递减）
|
||||
- 基于已有 `HookEvent::OnTurnEnd` 或扩展 `HookEvent::OnOutputGenerated` 触发反思
|
||||
- 失败静默：Reflection 失败不阻断主流程（`tracing::warn!` 后继续交付原始输出）
|
||||
|
||||
**依赖**：Phase C（interrupt/resume 基础设施）
|
||||
**优先级**：P0
|
||||
**预估规模**：约 350 行
|
||||
**状态**：📋 待实施
|
||||
|
||||
---
|
||||
|
||||
### v0.4.0 Phase 依赖关系图
|
||||
|
||||
```mermaid
|
||||
graph BT
|
||||
PA["<b>Phase A: Swarm 编排</b><br/>Swarm::star/sequential/hierarchical<br/>Subgraph 嵌套<br/>内建 dispatch_sub_agent 工具<br/>~500 行"]:::pending
|
||||
PB["<b>Phase B: 结果聚合</b><br/>aggregation_prompt 模板<br/>DispatchConfig result_key<br/>编排模式完善<br/>3 个端到端示例<br/>~200 行"]:::pending
|
||||
PC["<b>Phase C: HITL + Steering</b><br/>interrupt/resume<br/>Command(ResumeWith Correction)<br/>HookEvent::OnInterrupt<br/>~500 行"]:::pending
|
||||
PD["<b>Phase D: TokenJuice</b><br/>Compressor trait<br/>工具结果/历史/跨 Agent 压缩<br/>Semantic + Extractive 策略<br/>~400 行"]:::pending
|
||||
PE["<b>Phase E: 自动校正</b><br/>ReflectionLoop<br/>Producer-Critic<br/>上限 2-3 轮<br/>~350 行"]:::pending
|
||||
|
||||
PB --> PA
|
||||
PC --> PA
|
||||
PE --> PC
|
||||
|
||||
classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
|
||||
classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
|
||||
classDef future fill:#94a3b8,stroke:#64748b,color:#1a1a1a
|
||||
```
|
||||
|
||||
### 关键里程碑
|
||||
|
||||
| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 |
|
||||
|--------|---------------|-----------|------|
|
||||
| **M16** | Phase A | `Swarm::star().supervisor(A).worker(B).run(input)` 端到端验证；`dispatch_sub_agent` 内建工具注册并可用；2 个示例 exit 0 | 📋 待启动 |
|
||||
| **M17** | Phase B | `Swarm::sequential()` 串联执行验证；`Swarm::hierarchical()` 层次嵌套验证；结果聚合正确合并；3 个新示例 exit 0 | 📋 待启动 |
|
||||
| **M18** | Phase C | `interrupt()` 暂停 + `Command::Resume(bool)` 恢复全链路验证；`Command::ResumeWith(Correction)` 结构化校正验证；HookEvent 触发验证 | 📋 待启动 |
|
||||
| **M19** | Phase D | 工具结果经语义压缩后保留关键信息（验证压缩比 ≥ 3:1）；`microcompact` 降级路径验证；对话历史压缩验证 | 📋 待启动 |
|
||||
| **M20** | Phase E | ReflectionLoop 正确性验证：已知缺陷的输出被修复、无缺陷的输出不被修改（不变性保证）；2 轮迭代上限验证；Critic 不同模型配置验证 | 📋 待启动 |
|
||||
|
||||
### 不做（v0.5+）
|
||||
|
||||
| 功能 | 原因 |
|
||||
|------|------|
|
||||
| Agent 自动创生（LLM 驱动动态分派） | 设计复杂且不确定性高，v0.4 专注显式声明式编排 |
|
||||
| 分布式 Session 共享（Redis 后端） | 与编排正交，大多数用户单进程即可 |
|
||||
| 精确 tokenizer 计数（tiktoken-rs） | 依赖引入，v0.4 专注编排与压缩能力本身 |
|
||||
| 增量 Checkpoint | 存储优化，当前全量 JSON 够用 |
|
||||
| 路线 B（StateGraph 通用图引擎） | 当前编排需求在路线 A 范围内，图引擎留给未来版本 |
|
||||
| RL 轨迹导出 | 专项需求，非通用 |
|
||||
| Markdown 技能按需加载 | 独立功能 |
|
||||
@@ -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` 的「下一步行动」开始
|
||||
Reference in New Issue
Block a user