agcore/docs/roadmap-unsorted.md

AG Core Roadmap — Unsorted

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

已分版本的内容：请查阅

• roadmap-v0.1.0.md — Phase 0–4c + v0.1.0 Release
• roadmap-v0.2.0.md — Phase 5–12 + v0.2.0-rc.1
• roadmap-v0.3.0.md — Phase 13–19（13-18 已完成，19 待实施）

返回总入口：roadmap.md

---

全局愿景

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

当前状态：v0.2.0-rc.1 已打标签。Phase 0-18 全部完成。v0.3.0 实施中，Phase 19 共 1 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 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+ 展望

已规划的功能

功能	说明	预计版本
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+

明确不做（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.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

---

已完成 / 进行中阶段：

• ✅ 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 里程碑达成