xt/agcore
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
28ca43ccb2b62b48cad5b2e1c6037ba6cb6ffa12
agcore/design/roadmap/roadmap-unsorted.md
T
徐涛 28ca43ccb2 chore(docs): 将设计文档从 docs 移至 design 目录 
将 note、pdd、prd、roadmap 四类文档分别归入 `design/` 下对应子目录中，并新增 `.gitkeep` 占位文件
2026-07-23 05:45:53 +08:00

25 KiB
Raw Blame History

AG Core Roadmap — Unsorted

本文件存放尚未归到任何具体版本的 roadmap 内容：跨版本的全局视图、面向未来的展望、风险与建议、阶段总回顾。

已分版本的内容：请查阅

返回总入口：roadmap.md

全局愿景

AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。

当前状态：v0.3.5。Phase 0-30 全部完成。v0.4.0 规划已确定，覆盖 5 个增量 Phase（A-E）：Swarm 编排抽象、结果聚合、Human-in-the-loop + 用户 Steering、TokenJuice 语义压缩、自动校正。目标是从"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。

模块完整性评估

功能领域 方案状态 文档位置 实现优先级
LLM 调用周期 ✅ 完整 specs/llm-call-lifecycle.md P0
提示词工程 ✅ 完整 docs/4-prompt-engineering.md P1
工具系统 + 权限 ✅ 完整 docs/5-tool-system.md P1
记忆检索 ✅ 完整 docs/6-memory-system.md P2
Agent 运行时（4a 胶水层） ✅ 已实现 docs/7-agent-runtime.md P2
生命周期钩子 ✅ 完整 docs/3-phase0-remaining.md P0（LLM Cycle 扩展）
Provider 注册发现 ✅ 完整 docs/3-phase0-remaining.md P0（Provider 接口扩展）
流式事件系统 ✅ 完整 docs/3-phase0-remaining.md P0（流式接口前置）

v0.4.0 规划

v0.4.0 的完整规划已移入独立的 roadmap-v0.4.0.md，包含 5 个增量 Phase：

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 范围外）

功能 原因
TUI / 多平台 Gateway 应用层职责（Feishu / Telegram / Discord 桥接）
配置自动加载（config/figment） 配置来源策略应由上游应用决定，agcore 不定义配置格式
提示词自动优化 属于智能层，不应内建于 core 库

风险与建议

  1. 持久化依赖：rusqlite + bundled 零外部依赖编译，但 SQLite 不适配所有场景（分布式/高并发写）。MemoryStore trait 的抽象层允许下游自行实现 Redis / PostgreSQL 后端
  2. ContextSlot 心智负担：ContextSlot 引入了一等抽象的复杂度。建议通过 AgentBuilder 默认创建 "default" slot，让简单场景无感使用
  3. 向量检索规模上限：v0.3 的 PersistentVectorStore 全量加载到内存做余弦搜索，适合 ≤10 万条向量。超出此规模需换用专用向量库。v0.4 可以评估引入
  4. Scope 蔓延：v0.3 新增 agent/summary document/ engine/ memory/vector_store 模块，功能覆盖扩展到多 Agent 基础系统。始终保持 trait + reference impl 的边界，业务循环留给上层（Phase 16 已交付 agent/summary 摘要生产端 + format_messages_as_text 简洁版格式化 + 30K 字符整体截断保留最新；Phase 18 已交付 engine/switch_agent 热切换 + engine/sub_agent 调度全栈（dispatch / dispatch_all / dispatch_stream）；实施后两轮审查 PASS，0 🔴 阻塞）
  5. API 稳定性：v0.3 引入 Checkpointer、SessionManager、VectorStore 等新公开 API，v0.2 已有的 #[non_exhaustive] 和 #[deprecated] 机制继续沿用
  6. Checkpointer 存储效率：v0.3 使用全量 JSON 序列化存储 checkpoint，每轮对话约几百 KB。fork 从历史 checkpoint 创建新 session 时也会复制全量。等实际使用中发现存储瓶颈时再改为增量模式

下一步行动

  1. v0.4.0 启动：按 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 推进

已完成 / 进行中阶段：

  • ✅ Phase 0 Foundation — 全部交付物已完成
  • ✅ Phase 1 Prompt Engineering — 全部交付物已完成
  • ✅ Phase 2 Tool System — 全部交付物已完成
  • ✅ Phase 3 Memory System — 全部交付物已完成
  • ✅ Phase 4a Core Glue — 全部交付物已完成
  • ✅ Phase 4b Task Execution — 全部交付物已完成
  • ✅ Phase 4c Session Memory — 全部交付物已完成
  • ✅ Phase 5 Warmup — ProviderConfig::from_env + OllamaProvider + #[non_exhaustive] 前置标记（ProviderType / StopReason / FinishReason / EvictionPolicy）
  • ✅ Phase 6 ToolDefinition IR — ToolDef 新类型 + 双向 From 转换 + 别名彻底移除 + #[allow(deprecated)] 清理（cycle/registry/mcp/agent）；Anthropic 零改动；roundtrip 测试覆盖
  • ✅ Phase 7 SqliteStore — rusqlite 0.32 + WAL 模式 + Arc<Mutex<Connection>> + spawn_blocking；memory/store.rs → store/{in_memory,sqlite_store}.rs 模块化；9 个内联测试覆盖 CRUD/upsert/过滤/10×10 并发/持久化 round-trip；InMemoryStore ↔ SqliteStore trait-box 互换兼容
  • ✅ Phase 8 MVP 集成出口 — 14 个公开枚举追加 #[non_exhaustive]（P0 核心 IR + P0 Error + P1 其他） + StepStatus::Completed(ChatResponse) → Completed(MessageResponse) 迁移 + CHANGELOG v0.2.0-rc.1 + 2 个新示例（quick_start 60 行 + end_to_end 246 行），10 个离线示例全部 exit 0；v0.2.0-rc.1 标签已打；实施后三方审查发现 6 项问题（1 🔴 + 2 🟡 + 3 💭）已全部修复
  • ✅ Phase 9 流式体验增强 — AgentSession::submit_turn_stream 流式事件序列 + LlmCycle::submit_with_tools_stream spawn + mpsc 状态机 + StreamEvent::ToolExecutionStarted/Completed 新变体 + 9 单元测试 + 2 集成测试（含 submit_turn_stream_end_to_end 端到端 mock 验证 + submit_turn_stream_triggers_turn_hooks Hook 触发验证），全量 200 → 211；CycleConfig 加 Clone derive；方案文档 docs/16-phase9-streaming-experience.md（821 行）
  • ✅ Phase 10 ContextSlot 上下文管理 — src/agent/context.rs 新增 ContextSlot 核心类型（Full / Focused / Readonly 三种模式，New / Derived / Static 三种来源）+ JSON blob 批次持久化（每 slot 3-4 条 MemoryItem，slot_config key 自恢复支持旧版本兼容）；AgentSession 扩展 slots 字段 + 5 个管理方法（create_slot / switch_slot / list_slots / derive_slot / delete_slot，自动创建 "default" slot，delete_slot 双重保护禁止删 default/最后一个）；submit_turn/finalize_turn 改造为基于当前 slot 的增量追加写回（cycle.messages()[input_len..] 提取本轮新增消息，确保 Focused 模式"读时过滤"语义不丢失数据）；finalize_turn 签名变更（新增 new_messages_from_cycle: Vec<Message> 参数，返回 Result<(), AgentError>）；agent/error.rs 新增 3 个 Slot 错误变体（SlotReadonly / SlotNotFound / SlotAlreadyExists）；examples/context_slot_demo.rs 新增分支对话示例（法律咨询入口 → 两个派生方向 → 切换 → 隔离验证 → 删除保护）；方案文档 docs/17-phase10-contextslot.md（1227 行，含 §5 推荐方案、§6 实施建议、§9 实施计划，经过 4 轮方案/计划/实施审查 + 1 轮非阻塞建议修复）；全量 211 → 254（+43 新测试），clippy 0 警告，doc 0 warning，11 个离线示例全部 exit 0
  • ✅ Phase 11 测试与检索补强 — src/memory/vector.rs 新增 VectorRetriever trait（index + search 抽象）+ InMemoryVectorRetriever 引用实现（HashMap + 全量余弦相似度扫描 + 零依赖 dot()），6 个内联测试覆盖 basic/empty/zero-vector/k=0/2 个并发；wiremock Provider roundtrip 测试 12 个（OpenAI 8 + Anthropic 4）覆盖请求体/header/401/429/500/529/流式 usage-only/流式错误/ToolUse/结构化错误体；MemoryStore 并发测试 5 个（InMemoryStore 3 + SqliteStore 2）覆盖 100 并发写、5 写+5 读混合 2 秒、15 写者容量淘汰；openai.rs handle_error_response 修复 429 retry-after 解析（5 行，与 anthropic 对齐）；方案文档 docs/18-phase11-testing-and-retrieval.md（647 行，含 10 项架构决策 + 2 条实施偏差记录 #6 mid-stream mock 模式 + #7 retry-after 修复）；全量 254 → 277（+23 新测试），clippy 0 警告，doc 0 warning，并发测试 3 次稳定无 flaky
  • ✅ Phase 13 热身清理 + ContextSlot fork/merge — 3 个旧 types 文件删除（request.rs 187 行 + response.rs 177 行 + old_stream.rs 45 行），所有 OpenAI wire-format 类型迁入 provider/openai.rs 可见性 pub(crate)（Breaking Change：原 agcore::llm::types::OpenaiChatRequest/Response/Chunk 公共 re-export 路径已删除）；ChatResponse 自 v0.1.0 标记 #[deprecated] 后在 Phase 13 整体删除；ToolChoice 从 request.rs 迁入 tool.rs（公共 agcore::llm::types::ToolChoice 路径不变）；ContextSlot::fork() 派生独立子 slot（SlotSource::Derived { parent_id, strategy } 血缘可追溯）+ ContextSlot::merge(child, MergeStrategy) 合入父 slot（Append / Replace 两种策略，#[non_exhaustive] 预留扩展）；MergeStrategy 防御性检查（self-merge / 跨 session / Readonly 目标全部阻断）；AgentSession::derive_slot 重构复用 fork() 消除重复；agent.rs 追加 MergeStrategy re-export；9 个 fork/merge 内联测试覆盖 happy path 与 error path；stream.rs 简化为 module doc + pub use 重导出（保持 use crate::llm::stream::StreamEvent 路径兼容）；方案文档 docs/19-phase13-cleanup-and-fork-merge.md（640 行）；全量 277 → 286（+9 新测试），clippy 0 警告，doc 0 warning
  • ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen/Ollama 适配
  • ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
  • ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、8 个离线示例（含 simple_visit）、README + 错误消息友好化、CHANGELOG 初始化
  • ✅ v0.2 规划细化完成 — 8 个增量 Phase（Phase 5-12），17 个可验证 Step，覆盖 P0-P2 全部 12 项功能 + ContextSlot
  • ✅ v0.3.0 Phase 13 完成 — 技术债清理（3 旧 types 文件 + ChatResponse 删除）+ ContextSlot fork/merge（9 新测试），M9 里程碑达成
  • ✅ v0.3.0 Phase 14 完成 — Document 类型（id/content/metadata/mime_type）+ RecursiveCharacterSplitter 两阶段算法（按 separator 优先级递归分割 + 贪心合并 overlap，全部 chars_len() 字符级比较）+ Embedding trait（async + LlmError 复用）+ MockEmbedding（sin-hash 零依赖伪随机 + L2 归一化）+ 19 Document 测试 + 6 Embedding 测试（含 1 个 split_multibyte_utf8_boundary CJK 边界测试）；src/document.rs（580 行）+ src/llm/embedding.rs（183 行）+ examples/document_demo.rs（74 行）；pub use document::Document 在 lib.rs 重导出；CJK 分隔符（。/？/！）加入 DEFAULT_SEPARATORS；方案文档 docs/20-phase14-document-and-embedding.md（1417 行）；全量 286 → 313（+27 新测试，0 失败），clippy 0 警告，doc 0 warning，零新外部依赖；M10 里程碑达成
  • ✅ v0.3.0 Phase 15 完成 — VectorStore trait（add/search/remove/add_one，返回 (Document, f32) 消除调用方 id→Document 维护开销）+ InMemoryVectorStore（Mutex<HashMap> + 余弦全量扫描 + 预计算 L2 norm 缓存）+ PersistentVectorStore（构造时全量加载，先写持久化后写内存，持久化失败时内存不污染重启自动恢复，remove 幽灵数据窗口已知）+ RagPipeline 组合器（ingest: split→embed→store.add / retrieve: embed→store.search，splitter: Option<RecursiveCharacterSplitter> 灵活切换）；src/memory/vector_store.rs（937 行，19 个内联测试覆盖 14 场景含 2 个性能基准）+ 零新外部依赖（纯 Rust dot() 余弦）；旧 VectorRetriever/InMemoryVectorRetriever 标注 #[deprecated(since = "0.3.0")] 迁移路径清晰；search_orthogonal_vectors 返回 1 条 score≈0（文档已同步修正不过滤低分向量）；方案文档 docs/21-phase15-vector-store-persistence.md（1570 行，经 3 轮审查 + 文档-代码一致化修复）；全量 313 → 335（+22 新测试），clippy 0 警告，doc 0 warning；M11 里程碑达成
  • ✅ 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

设计笔记

Checkpointer 分层存储模型

来源：v0.4.0 规划讨论中涉及增量 Checkpoint 的技术推演。当前全量 JSON checkpoint 够用，但为未来优化预留设计方案。

分层叠加模型（OverlayFS 模式）

受容器分层文件系统启发，增量 Checkpoint 可以借鉴 overlayfs 的"底层只读 + 上层可写叠加"设计：

全量基座（只读）：

pub struct SnapshotBase {
    pub checkpoint_id: String,
    pub session_id: String,
    pub snapshot: SessionSnapshot,  // 完整 JSON 化状态
}

增量层（叠加 diff）：

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 保护而非长期存储：

// 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 且频繁保存导致性能瓶颈时，考虑实现分层模型。

Reference in New Issue View Git Blame Copy Permalink