xt/agcore
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
134 Commits 2 Branches 6 Tags
28d6a1c166e10ce85ce175f84db5b6c14be14775
Commit Graph

134 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
徐涛 28d6a1c166 chore(release): 发布 v0.3.0 
- 更新 crate 版本为 0.3.0
v0.3.0 		2026-07-17 16:11:26 +08:00
徐涛 6676322666 fix(core): 修复 v0.3.0 审查发现的 6 项警告问题 
- InMemoryGraph 的 10 处 lock().unwrap() 改为错误传播，避免 Mutex poison 时 panic
- SubTaskResult 添加 Serialize/Deserialize，支持结果序列化
- dispatch_all 移除多余的 task.clone()
- truncate_total_chars 补充字节切片安全性注释
- SessionManager::children 添加 ponytail 注释标记 O(N) 扫描现状
- SessionMemoryEntry.created_at 添加 i64 类型说明注释
 2026-07-17 15:59:02 +08:00
徐涛 9d73f525d0 fix(memory): search_graph 补充 min_score 过滤 
GraphOnly 模式下低分实体不再被返回，与 search_knowledge_store 行为一致
 2026-07-17 14:58:44 +08:00
徐涛 7e72e102a2 feat(memory): 实现知识图谱与双通道检索 
- 新增 KnowledgeGraph trait + InMemoryGraph（BFS 图遍历 + 标签管理）
- 扩展 MemoryRetriever 为双通道检索（Hybrid/KnowledgeOnly/GraphOnly）
- 统一 RetrievalResult 为 RetrievalItem enum 变体
- GraphRelation 使用复合键 + composite_key() 派生 id
- 旧 ScoredItem 标注 #[deprecated]
- 新增 knowledge_graph_demo 示例
- 全量测试 427 passed，clippy/doc 0 警告
 2026-07-17 14:37:49 +08:00
徐涛 5bb349d177 docs(roadmap): 将 roadmap.md 拆分为按版本归档的多文件 
- 替换 docs/roadmap.md 为简短索引入口，列出 4 个子文件导航
- 新增 docs/roadmap-v0.1.0.md（Phase 0–4c + v0.1 Release）
- 新增 docs/roadmap-v0.2.0.md（Phase 5–12 + M1-M8 + v0.2.0-rc.1）
- 新增 docs/roadmap-v0.3.0.md（Phase 13–19 + M9-M15）
- 新增 docs/roadmap-unsorted.md（全局愿景/模块完整性/v0.4+ 展望/风险/下一步/已完成列表）
- 修复 docs/24-phase18-agent-switch-and-dispatch.md 中 2 处具体行号引用改为指向新文件

拆分原则：每个版本文件含目标/Phase/里程碑/依赖图四要素；
跨版本视图、阶段总回顾、未来展望集中于 unsorted
 2026-07-17 11:20:12 +08:00
徐涛 46de111965 feat(engine): 实现 Agent 角色热切换与子代理调度 
新增 SessionManager::switch_agent / dispatch / dispatch_all / dispatch_stream
四个核心方法，补齐多 Agent 基础系统原语。

交付物:
- switch_agent 运行时替换 Arc<dyn Agent>，保留上下文并更新 SessionMeta
- dispatch 单任务派发：create_child → inherit_memory → submit_turn
- dispatch_all 并行派发：Semaphore 并发控制 + 部分成功语义
- dispatch_stream 流式派发：unbounded_channel + spawn task 消息重建 + finalize_turn
- DispatchConfig / SubTaskResult / SubTaskStreamEvent 公开类型
- 4 个端到端示例（agent_switch_demo / sub_agent_dispatch_demo /
  bridge_keys_demo / dispatch_stream_demo）

辅助变更:
- EngineError 新增 DispatchFailed 变体
- CostTracker 实现 From<Usage> 转换
- save_session_meta / load_session_meta 改 pub(crate) 供 switch.rs 使用

测试: +17 个内联测试（4 switch + 5 dispatch + 4 dispatch_all +
4 dispatch_stream），全量 391 passed / 0 failed，
clippy 0 警告，doc 0 warning。
 2026-07-15 11:15:58 +08:00
徐涛 cb922b03de docs(roadmap): 标记 Phase 17 完成 + M13 里程碑达成 + 更新依赖图 
Phase 17 全部交付物已完成（2026-07-15）：
- 状态从 ⏳ 改为 ✅
- 增补实际增量（5 新增文件 + 5 修改 + 1 示例 = 1848 行净增）
- 列出 21 个新内联测试（Checkpointer 6 + SessionManager 15）
- 列举关键设计决策落地（SessionSnapshot 独立 / to_snapshot+from_snapshot+restore_memory
  三段式 / EngineError::Memory 透传 / RwLock 锁契约 / ckpt_id 纳秒+计数器 / 孤儿策略等）
- 记录实施后两轮审查门禁 PASS（第一轮 PM+SA 修复 6 🔴，第二轮 SA 修复 2 🔴，
  实施后 PM+SA+Code Reviewer 联合修复 8 个 🟡）

M13 里程碑达成 ✅ 2026-07-15（依赖图节点从 pending 改为 done）

Phase 17 rc.1 完成 → 下一步 Phase 18（Agent Switch + SubAgent Dispatch）
- 「下一步行动」重定向到 Phase 18
- 「里程碑追踪」更新为 M12+M13 已达成，剩余 M14-M15
- 已完成阶段列表追加 Phase 17 完成项（详细列出 11 个 SessionManager API +
  5 个 Checkpointer API + 关键实现细节 + 审查修复记录）
 2026-07-15 09:00:02 +08:00
徐涛 34eec9f546 feat(engine): 实现 Agent 执行引擎（SessionManager + Checkpointer + SessionSnapshot） 
Phase 17 主体交付：解决 v0.2 中 session 在变量里、无父子关系、无 checkpoint、
不可序列化的空白。

新增模块 src/engine/（5 文件，约 1300 行纯实现 + 21 个内联测试）：

- error.rs（46 行）—— EngineError 枚举（6 变体）
  - SessionNotFound / SessionAlreadyExists / CheckpointNotFound
  - Memory(#[from] MemoryError) 透传（与 AgentError 风格一致）
  - Serialization / Agent(#[from] AgentError)

- snapshot.rs（36 行）—— SessionSnapshot + SessionMemoryEntry
  - 独立 struct 避开 Arc<dyn Agent> 不可序列化限制
  - SessionMemoryEntry 保留 value/metadata/created_at 完整信息
  - 所有字段 #[serde(default)] 宽松反序列化保证前向兼容

- checkpointer.rs（377 行）—— Time-travel 检查点管理器
  - checkpoint() / rollback_load() / list_checkpoints() / delete_all() / latest_snapshot()
  - 存储 key：ckpt:{session_id}:{ckpt_id}
  - ckpt_id 纳秒+计数器（无外部依赖，ponytail）
  - CkptMeta.created_at_nanos 字段确保同秒内精确降序
  - 6 个内联测试覆盖 roundtrip / 不存在 ckpt / 降序排序 / delete_all 幂等 /
    latest_snapshot / 跨 session 隔离

- session_manager.rs（906 行）—— SessionManager 会话树管理
  - 内部 RwLock<HashMap> + Arc<tokio::sync::Mutex<AgentSession>> 双重锁
  - create / create_child / get / recover / replace / children / parent /
    destroy / submit_turn / submit_turn_stream / finalize_turn_stream 共 11 个公开方法
  - SessionManagerConfig.auto_checkpoint 默认 true（同步写入 +
    tracing::error! 失败不阻断主流程，不提供强持久化保证）
  - 孤儿策略：destroy 不递归删除子 session；父被销毁后 parent() 返回 None
  - create_child 限制：父 session 必须先 get/recover 到内存（bundle 不可序列化）
  - 15 个内联测试覆盖 CRUD / recover / replace / 树形 / 孤儿 / auto_checkpoint 开关 /
    序列化兼容性 / 幂等 / 10 并发创建

- mod.rs（20 行）—— 统一 pub use 重导出 EngineError / SessionManager /
  SessionManagerConfig / Checkpointer / CkptMeta / SessionSnapshot /
  SessionMemoryEntry

AgentSession 扩展（src/agent/session.rs，+152 行）：
- to_snapshot() pub async —— 从 MemoryStore 拍平 session_memory 全量数据
- from_snapshot() pub fn Result —— 纯同步构造器（pending_memory_restore 暂存）
- restore_memory() pub async &mut self —— 写回持久层并清空 pending
- has_pending_memory_restore() —— 查询 pending 状态
- pub(crate) fn bundle() —— accessor 供 SessionManager::create_child 继承

SessionMemory 扩展（src/agent/session_memory.rs，+57 行）：
- list_entries() —— 返回 Vec<(key, value, metadata, created_at_unix_secs)>
- set_with_meta() —— 保留 metadata/created_at 写入（供 restore_memory 完整恢复）

src/lib.rs —— pub mod engine 声明

examples/engine_demo.rs（+251 行）：
端到端演示 create → submit_turn → checkpoint → list_checkpoints →
rollback_load → from_snapshot → restore_memory → replace → destroy 完整链路，
含 rollback 一致性 assert（turn_index 和 cost 恢复到 checkpoint 时刻）。

零新外部依赖（serde_json 已有）。全量 353 → 374（+21 新测试）。
clippy 0 警告，doc 0 warning，example exit 0。

Phase 17: Agent 执行引擎 — Step 2-7（合并提交）
 2026-07-15 08:59:46 +08:00
徐涛 1d51dcdfe0 feat(core): 为 CostTracker/ContextSlot/MergeStrategy 加 Clone+Serialize+Deserialize 
Phase 17 前置 derive 改动：
- CostTracker 加 Clone + Serialize + Deserialize（3 行）—— 用于 SessionSnapshot
  序列化 cost_so_far 字段
- ContextSlot 加 Serialize + Deserialize（1 行）—— 用于 SessionSnapshot
  序列化 slots HashMap
- MergeStrategy 加 Serialize + Deserialize（1 行）—— 与 ContextSlot 一致

零破坏性：派生仅为新增能力，不修改现有行为。ContextSlot 的 save()
路径独立序列化 messages/meta/config，不走整体 serde，两组路径可共存。

Phase 17: Agent 执行引擎 — Step 1
 2026-07-15 08:58:43 +08:00
徐涛 fbbf8bf6e5 docs(roadmap): 同步 Phase 17 方案审查后的交付物与里程碑定义 2026-07-15 06:52:05 +08:00
徐涛 cc1c68b69d feat(agent): 实现摘要自动生成（SummaryConfig + 内联检查点） 
SummaryConfig 6 字段配置（trigger_token_ratio / max_context_tokens /
summary_prompt / debounce_turns / summary_model / max_tool_result_chars），
AgentBuilder 链式 summary_config()；AgentSession 在 submit_turn /
finalize_turn 的 OnTurnEnd 之后内联检查点：水位 + 防抖（首次不受
约束）→ 独立 LlmCycle 调 submit_messages 生成摘要 → 写入
FocusedConfig.summary_override + slot.save() + SessionMemory 全局快照。

should_summarize 接收 current_turn 参数避免流式路径 turn_index 偏差；
format_messages_as_text 简洁版格式化含 30K 整体截断保留最新；空消息
守卫直接返回空串。所有错误静默 tracing::error!，成功路径
tracing::info!。

src/agent/summary.rs 新增 ~240 行；agent/session.rs +428 行（双路径
检查点 + 关联函数 + 测试 + 公开 API）。零新外部依赖。全量 335 → 353
测试（+18 新测试），clippy 0 警告，doc 0 warning。两轮审查 PASS——
第一轮 PM/SA 修复 11 项，第二轮 Code Reviewer 修复 9 项（含 🔴
generate_summary 空消息 bug + 🟡 5 项 + 💭 2 项）。方案文档 docs/
22-phase16-summary-auto-generation.md（471 行）；roadmap.md 标记
Phase 16 完成 + M12 里程碑达成。
 2026-07-10 06:43:06 +08:00
徐涛 209932e3b5 feat(docs): 标记 Phase 15 完成并更新 roadmap 状态 2026-07-09 22:46:29 +08:00
徐涛 32d886f870 feat(memory): 新增 VectorStore 抽象与 RagPipeline 持久化管线 
- 新增 src/memory/vector_store.rs（约 660 行）：

  - VectorStore trait：批量 add / search / remove + add_one 默认实现

  - InMemoryVectorStore：Mutex<HashMap> + 余弦全量扫描（锁内克隆、锁外计算）

  - PersistentVectorStore：MemoryStore 包装，JSON blob 持久化，先持久化后内存

  - RagPipeline：split → embed → store 组合器（具体 struct，非 trait）

- 22 个内联测试覆盖 InMemory（10）/ Persistent（6）/ RagPipeline（4）/ 性能基准（2）

- 性能断言：search 10K 条 <100ms，PersistentVectorStore::new 加载 <500ms

- 标记 VectorRetriever / InMemoryVectorRetriever 为 #[deprecated(since="0.3.0")]

- memory.rs 追加 VectorStore 等 4 个类型的 re-export

- document_demo 从手动 VectorRetriever 循环迁移到 RagPipeline 两行调用

- 零新增外部依赖
 2026-07-09 16:51:29 +08:00
徐涛 b04427e83f docs(roadmap): 标记 Phase 14 完成 + M10 里程碑达成 
Phase 14 全部交付物已完成（commit d4c4d8f）：
- Document 类型 + RecursiveCharacterSplitter 分割器
- Embedding trait + MockEmbedding
- 19 Document 测试 + 6 Embedding 测试
- 全量测试 286 → 313，clippy 0 警告，零新外部依赖

Roadmap 同步 6 处：
- 顶部最后更新日期 + 当前状态（Phase 14 完成，Phase 15-19 待实施）
- §Phase 14 章节新增实际新增段落（commit hash + 文件清单 + 设计决策 + 测试覆盖）
- v0.3.0 依赖图 P14 节点 pending → done
- M10 里程碑 ⏳ → ✅ 2026-07-09
- 下一步行动从 Phase 14 启动改为 Phase 15 启动
- 已完成/进行中阶段列表追加 Phase 14 完成条目
 2026-07-09 13:27:36 +08:00
徐涛 d4c4d8fa3c feat(document): 实现 Document 类型与 RecursiveCharacterSplitter 分割器 
新增 Phase 14 核心模块，为 RAG 管线提供 split → embed 阶段的底层支撑。

新增内容：
- Document 类型（id/content/metadata/mime_type 四字段 + new/from_raw 构造器）
- RecursiveCharacterSplitter（两阶段算法：按 separator 优先级递归分割 + 贪心合并 overlap 滑动窗口）
- Embedding trait（异步向量化抽象，复用 LlmError）+ MockEmbedding（sin-hash 零依赖伪随机实现）
- 19 个 Document 单元测试 + 6 个 Embedding 单元测试
- document_demo 示例（Document → Splitter → MockEmbedding → InMemoryVectorRetriever 端到端演示）

模块注册：
- src/lib.rs: pub mod document + pub use Document
- src/llm.rs: pub mod embedding

设计文档：docs/20-phase14-document-and-embedding.md（1417 行，含背景/调研/方案对比/实施计划）

零新外部依赖，所有长度比较以 Unicode 字符为单位（chars_len），CJK 文本行为正确。
 2026-07-09 13:08:35 +08:00
徐涛 4686063ca8 docs: 标记 Phase 13 完成 + 追加 v0.3.0 CHANGELOG 条目 
- CHANGELOG.md: 追加 v0.3.0 (unreleased) 条目
  - Breaking Changes: 类型路径变更（request.rs/response.rs → provider/openai.rs，
    公共 ToolChoice re-export 路径不变）+ ChatResponse / LegacyStreamEvent 删除
  - Added: ContextSlot::fork / merge + MergeStrategy 枚举（#[non_exhaustive]）
  - Changed: 3 个旧 types 文件删除 + 所有 wire-format 类型迁入 openai.rs
  - Fixed: Phase 9 实施审查修复（PreRequest hook + 死代码清理 + 2 个集成测试）
  - Migration Guide: v0.2.0-rc.1 → v0.3.0 路径迁移示例
  - 修复 M9 里程碑验收 #11（CHANGELOG 条目）和审查结论 CONDITIONAL PASS 条件清单 #1
- docs/roadmap.md:
  - 顶部最后更新日期 → 2026-07-08（Phase 13 完成 + M9 里程碑达成）
  - 末尾"v0.3.0 规划完成"状态行从"Phase 13-19 待逐步实施"更新为"Phase 13 完成，
    Phase 14-19 待实施（Document → 向量存储 → 摘要 → 引擎 → 调度 → 知识图谱）"
 2026-07-09 06:19:43 +08:00
徐涛 c36668071e fix(agent): Phase 9 实施审查修复 
- cycle.rs: run_tool_loop 实现 PreRequest hook（之前 `let _ = hook_executor.as_ref()` 是空操作，
  导致 hook-based logging/monitoring 在流式工具循环中失效；现在与 submit_with_tools 行为对齐，
  含 should_block 检查，阻断时通过 StreamEvent::Error 事件化）
- session.rs: 删除 submit_turn_stream 末尾的 `let _ = hook_executor;` 死代码（Arc 引用生命周期
  由 Arc 自动管理）
- session.rs: 新增 2 个集成测试覆盖方案 §4 Step 5：
  - submit_turn_stream_end_to_end：mock provider → 消费流 → finalize_turn 后 cost_so_far
    正确更新（10/5 tokens）+ turn_index=1 + default slot 包含 user/assistant 消息
  - submit_turn_stream_triggers_turn_hooks：OnTurnStart 在 submit_turn_stream 返回流前
    触发（计数=1）+ OnTurnEnd 在 finalize_turn 前不触发（计数=0）+ finalize_turn 后触发（计数=1）
- docs/16-phase9-streaming-experience.md: 标注 finalize_turn Phase 10 签名变更（new_messages_from_cycle
  + Result 返回），Step 5 测试实现位置
- 测试 288 passed / 0 failed（基线 286 + 2 新增），clippy 0 警告，doc 0 warning
 2026-07-08 23:19:24 +08:00
徐涛 d4f27b5865 refactor(types): 删除旧类型文件和 ChatResponse 
- 删除 src/llm/types/old_stream.rs（45 行，LegacyStreamEvent 内部死代码）
- types/mod.rs 删除 pub mod old_stream; 与 ChatResponse 结构体定义
- 前置验证 A 通过：parse_chunk_stream / map_legacy_to_ir / LegacyToIrEventStream /
  ChunkToLegacyEventStream / LegacyStreamEvent 零外部调用方
- 前置验证 B 通过：cargo doc --no-deps 中无 ChatResponse 引用
- cycle.rs:88 的 #[allow(deprecated)] 保留（LlmCycle impl 中无 ChatResponse 引用，
  与 ChatResponse 无关；按方案文档"若不相关则无需改动"原则保留原状）
- stream.rs 已在 Step 13.2 commit 中同步简化为 module doc + pub use
- 同步更新 docs/roadmap.md：Phase 13 状态 ⏳→✅，M9 里程碑 + 完成日期，
  Mermaid 依赖图 P13 pending→done，"下一步"指向 Phase 14
- Breaking Change：agcore::llm::types::ChatResponse 已删除
  （v0.1.0 起标记 #[deprecated]，请改用 MessageResponse）
 2026-07-08 22:59:31 +08:00
徐涛 1c0e1e0ed1 refactor(types): response.rs 类型移入 provider/openai.rs 
- 删除 types/response.rs（177 行）
- 所有 OpenAI wire-format 响应类型迁入 provider/openai.rs，可见性 pub(crate)：
  TokenLogprob / TopLogprob / Logprobs / URLCitation / Annotation / OpenaiAudio /
  Choice / OpenaiChatResponse / Delta / ChunkChoice / OpenaiChatChunk
- From<OpenaiChatMessage> for Delta 与 From<OpenaiChatResponse> for OpenaiChatChunk
  同步迁入 openai.rs
- types/mod.rs 删除 pub mod response; 与对应 re-export
- convert_response 同步降级为 pub(crate) 以匹配 OpenaiChatResponse 可见性
- stream.rs: OpenaiChatChunk import 路径改为 crate::llm::provider::openai
- stream.rs 同步简化为 module doc + pub use 重导出（合并 Step 13.3 的清理动作，
  避免遗留 dead_code 警告来回）
- mod.rs: ChatResponse 的两个 From impl 同步删除（impl 内引用的 OpenaiChatResponse
  / OpenaiChatChunk / Delta / ChunkChoice 已不在 types 模块），结构体保留到 Step 13.3
- 公共 re-export 路径 agcore::llm::types::OpenaiChatResponse/Chunk 等已删除
  （Breaking Change，见 CHANGELOG）
 2026-07-08 22:58:18 +08:00
徐涛 760de46623 refactor(types): request.rs 类型移入 provider/openai.rs 
- 删除 types/request.rs（187 行）
- 所有 OpenAI wire-format 类型迁入 provider/openai.rs，可见性 pub(crate)：
  StreamOptions / OpenaiTool / AudioParam / PredictionContent / UserLocation /
  Approximate / WebSearchOptions / OpenaiChatRequest
- types/mod.rs 删除 pub mod request; 与对应 re-export
- convert_request 同步降级为 pub(crate) 以匹配 OpenaiChatRequest 可见性
- 公共 re-export 路径 agcore::llm::types::OpenaiChatRequest 等已删除（Breaking Change，见 CHANGELOG）
 2026-07-08 22:55:17 +08:00
徐涛 f8df6a9421 refactor(types): ToolChoice 移入 tool.rs 
- ToolChoice 枚举与 serde impl 从 types/request.rs 迁入 types/tool.rs
- mod.rs re-export 从 request::ToolChoice 改为 tool::ToolChoice（公共 agcore::llm::types::ToolChoice 路径保持不变）
- request_v2.rs import 路径更新为 crate::llm::types::tool::ToolChoice
- OpenaiChatRequest 字段类型引用更新为 super::tool::ToolChoice（Step 13.1 删除 request.rs 后此临时 import 同步消除）
 2026-07-08 22:53:46 +08:00
徐涛 802518b5fe feat(agent): 实现 ContextSlot fork/merge 
- 新增 MergeStrategy 枚举（#[non_exhaustive]，为 Phase 16 Summarize 预留）
- 新增 ContextSlot::fork() 从父 slot 派生独立子 slot（Full / Focused 策略）
- 新增 ContextSlot::merge() 将子 slot 消息合入父 slot（Append / Replace 策略）
- 防御性检查：禁止 self-merge、跨 session merge、合并到 Readonly slot
- 重构 AgentSession::derive_slot 复用 fork() 消除重复代码
- 新增 9 个内联测试覆盖 fork/merge happy path 与 error path
- agent.rs 追加 MergeStrategy re-export（agcore::agent::MergeStrategy 路径可用）
 2026-07-08 22:52:38 +08:00
徐涛 993118f661 docs(roadmap): 将 v0.3+ 展望更新为 v0.3.0 详细规划 
新增 Phase 13-19 共 7 个增量交付阶段，覆盖技术债清理、Document 系统、向量
存储持久化、摘要自动生成、Agent 执行引擎、Agent Switch 与 SubAgent 调度、
知识图谱及双通道检索。同步更新里程碑、依赖关系图及风险说明
 2026-07-06 23:10:18 +08:00
徐涛 4348e4bf3e docs: 添加 LangChain & LangGraph 功能调研笔记 2026-07-06 21:55:03 +08:00
徐涛 0dc91faa43 docs(roadmap): 标记 Phase 11 测试与检索补强已完成 2026-07-06 15:30:52 +08:00
徐涛 b4e5c7d651 docs(phase11): 记录 Phase 11 方案文档与实施偏差 2026-07-06 14:53:00 +08:00
徐涛 71abe881ed feat(core): 完成 Phase 11 测试与检索补强 
- 新增 VectorRetriever trait 与 InMemoryVectorRetriever 引用实现
- 补充 Provider roundtrip wiremock 测试与 MemoryStore 并发测试共 23 个
- 修复 openai 429 retry-after header 解析（与 anthropic 对齐）
 2026-07-06 14:52:49 +08:00
徐涛 2af92cd554 docs(roadmap): 标记 Phase 10 ContextSlot 上下文管理已完成 
- 顶部状态行更新：Phase 0-10 全部完成，11 个离线示例，254 测试
- Phase 10 状态：Step 10.1/10.2/10.3 全部标记 ✅
- 详细实际新增：agent/context.rs (~430 行) + agent/error.rs 3 个变体 +
  agent/session.rs 改造（slots 字段 + 5 个管理方法 + submit_turn/finalize_turn
  增量追加写回） + context_slot_demo 示例 + 43 个新测试
- finalize_turn 签名变更记录（new_messages_from_cycle 参数 + Result 返回）
- 依赖关系图 P10 节点标 ✅
- 里程碑 M6 → ✅ 2026-07-07
- 下一步行动：Phase 10 → Phase 11（测试与检索补强）
- 已完成阶段列表追加 Phase 10 完整说明
- 最后更新日期：2026-07-06 → 2026-07-07
 2026-07-06 09:53:44 +08:00
徐涛 635942248b feat(core): 新增 Phase 10 ContextSlot 多上下文分区管理 
- 新增 ContextSlot 类型（Full / Focused / Readonly 三种模式，
  New / Derived / Static 三种来源），支持 JSON blob 批次持久化
- AgentSession 新增 slots 字段与 5 个管理方法
  （create_slot / switch_slot / list_slots / derive_slot / delete_slot），
  自动创建 "default" slot
- submit_turn / finalize_turn 改造为基于当前 slot 的增量追加写回，
  确保 Focused 模式"读时过滤"语义不丢失数据
- finalize_turn 签名变更（新增 new_messages_from_cycle 参数，
  返回 Result<(), AgentError>），向后兼容列于 docs/17
- 新增 3 个 AgentError 变体（SlotReadonly / SlotNotFound / SlotAlreadyExists）
- 新增分支对话示例 context_slot_demo（法律咨询→两个派生方向→切换→隔离验证）
- 新增 43 个测试覆盖持久化、Focused 过滤、Readonly 阻断、delete 保护、
  派生逻辑、流式 finalize_turn、key 注入防护等场景
- 方案文档：docs/17-phase10-contextslot.md（含 §5 推荐方案、§6 实施建议、
  §9 实施计划，经过 4 轮方案/计划/实施审查 + 1 轮非阻塞建议修复）
 2026-07-06 09:46:04 +08:00
徐涛 fe51961202 docs(roadmap): 标记 Phase 9 流式体验增强已完成 
- 顶部「当前状态」「最后更新」同步到 Phase 0-9 完成
- Phase 9 Step 9.1 标记完成并新增「实际新增」段落
- Mermaid 依赖图 P9 节点 class 从 p1 切换为 done
- 里程碑 M5 标记 ✅ 2026-07-06
- 下一步行动与已完成列表同步更新（指向 Phase 10）
 2026-07-06 05:43:47 +08:00
徐涛 212cfcc916 feat(core): 新增 Phase 9 流式体验增强 submit_turn_stream 
- 新增 StreamEvent::ToolExecutionStarted/Completed 变体（apply_to 元事件）
- 新增 LlmCycle::submit_with_tools_stream + run_tool_loop（spawn + mpsc 状态机）
- 新增 AgentSession::submit_turn_stream + finalize_turn（手动同步状态）
- CycleConfig 加 Clone derive

- 新增 9 个单元测试 + 2 个集成测试（211 passed）
- clippy 0 警告，存量 0 回归

docs: 追加 Phase 9 实施方案（docs/16-phase9-streaming-experience.md）
 2026-07-05 23:37:37 +08:00
徐涛 88d00ac927 docs(roadmap): 补充 Phase 8 修复 commit 85b92ae 与最终行数 
Phase 8 章节实际新增小节从 6 commits 改为 7 commits（含 docs(roadmap)
自身 + 实施后修复 commit 85b92ae），并同步行数：

- quick_start 57 → 60 行（追加 trailing newline + 错误处理改进）
- end_to_end 237 → 246 行（除零修复 + drop 注释 + EchoTool 一致化）
- 新增 docs(roadmap) commit 项（标记 Phase 8 + M4 里程碑）
- 新增 fix(examples) commit 项（6 项审查问题：1 🔴 + 2 🟡 + 3 💭）

'已完成 / 进行中阶段' 列表同步补充 Phase 8 行末的三方审查修复标注。
 2026-07-05 21:10:24 +08:00
徐涛 358e971094 feat(core): 新增 Phase 8 MVP 集成出口方案文档 2026-07-05 21:04:31 +08:00
徐涛 85b92ae9d4 fix(examples): 修复 Phase 8 端到端示例审查发现的 6 项问题 
按 PM/SA/Code Reviewer 三方审计报告修复：

🔴 阻塞修复:
- CalcTool 除零 panic: `a / b` 改 `a.checked_div(b).ok_or_else(...)`,
  b=0 时返回 ToolError::InvalidArguments 而非 panic

🟡 警告修复:
- end_to_end.rs 持久化验证注释与实际不符: 显式 drop(backend) 让注释
  描述与 Arc 释放顺序一致
- quick_start EchoTool 参数验证: 用 args.get("text").and_then().ok_or_else()
  替换 as_str().unwrap_or("") 静默降级, 缺失/类型错误时返回显式错误

💭 一致性修复:
- end_to_end.rs EchoTool 与 quick_start 一致化 (format!("收到: {text}"))
- quick_start mock 响应文本 "已通过 echo 回传" → "EchoTool 已收到并完成回传"
- quick_start 断言改为检查 "收到", 与方案字面要求一致
- quick_start 末尾追加 POSIX trailing newline

验收: cargo test 200/0 + clippy 0 警告 + doc 0 warning + 10 示例 exit 0
 2026-07-05 21:00:36 +08:00
徐涛 57b2fbaaed docs(roadmap): 标记 Phase 8 MVP 集成出口已完成，v0.2.0-rc.1 标签 
Phase 8 全部 Step 完成（8.1 API 稳定性扫尾 + 8.2 quick_start + 8.3
end_to_end），更新 roadmap 同步：

- 顶部「当前状态」补充 v0.2.0-rc.1 标签信息
- Phase 8 章节 3 个 Step 全标 ✅；新增「实际新增」6 commits 小节
- 依赖关系图 P8 节点 class 从 mvp 改为 done
- M4 里程碑标 ✅ 2026-07-05
- 「下一步行动」从 Phase 8 改为 Phase 9 + v0.2.0 正式版规划
- 「已完成 / 进行中阶段」列表追加 ✅ Phase 8
 2026-07-05 20:06:43 +08:00
徐涛 2c8e31919d feat(examples): 新增 end_to_end 端到端集成示例 
展示真实场景集成: 3 工具 (EchoTool + CalcTool + NoteTool) +
3 轮对话 (计算 → 记笔记 → 回忆) + SqliteStore 持久化跨连接验证。

关键设计:
- Provider 自动检测: AG_LLM_* 环境变量齐全时用真实 LLM (from_env),
  否则降级 MockProvider + 9 条预设响应 (含真实工具调用序列)
- NoteTool 展示 MemoryStore trait 解耦: 直接持有 Arc<dyn MemoryStore>,
  绕过 AgentSession 封装 (key 前缀 "note:" + list 过滤)
- CalcTool ponytail 方案: 手写 'a op b' 解析, 不引入 rhai 依赖
- 持久化验证: drop(bundle) + drop(session) → backend Arc 引用归零 →
  SqliteStore Connection 自动 close → 重开连接读取数据存活

规模: 237 行 (含完整注释); clippy 0 警告; cargo run exit 0。
 2026-07-05 20:04:44 +08:00
徐涛 c6651c9b75 feat(examples): 新增 quick_start 最小可运行示例 
展示 Agent / BaseTool / AgentBuilder / AgentSession 四层抽象的
最小可行集成：MockProvider + EchoTool + submit_turn("你好")，
EchoTool 真正被 LLM 调用并产出 "收到" 字样，零外部配置。

规模: 57 行（含注释），clippy 0 警告 + cargo run exit 0。
 2026-07-05 20:01:13 +08:00
徐涛 e636e16820 test(core): 验证 Phase 8 Step 8.1 commit 1-3 零回归 
cargo test --all-targets: 200 passed / 0 failed
cargo clippy --all-targets -- -D warnings: 0 警告
cargo doc --no-deps: 0 warning

Step 8.1 四个增量 commit 全部交付，零 deprecated warning。
 2026-07-05 19:50:57 +08:00
徐涛 1c89d23ba2 docs: v0.2.0-rc.1 CHANGELOG + 版本号 + README 示例列表 
- CHANGELOG.md 新增 [0.2.0-rc.1] 条目（Added/Changed/Non-exhaustive/
  Deprecated/Fixed/Migration Guide 六节）
- Cargo.toml version: 0.1.0 → 0.2.0-rc.1
- README 示例列表: 7 → 10（新增 quick_start / end_to_end /
  simple_visit），依赖版本 0.1 → 0.2

验收: 人工 review + git diff 确认版本号与示例数对齐。
 2026-07-05 19:50:10 +08:00
徐涛 5b4343a051 refactor(agent): StepStatus::Completed 切换至 MessageResponse 
StepStatus::Completed 字段类型从废弃的 ChatResponse 切换为 IR 层
MessageResponse，同时清理 task_agent_demo.rs 的 3 处废弃类型引用：

- ChatResponse → MessageResponse (字段映射见 §3.1.2)
- OpenaiChatMessage::assistant_text(t) → Message::assistant(t)
- FinishReason::Stop → StopReason::Stop (Option 包裹同步移除)

移除 src/agent/task.rs 的两处 #[allow(deprecated)] 与
examples/task_agent_demo.rs 顶部 #![allow(deprecated)]，零
deprecated warning。

验收: cargo build + clippy -D warnings + test --all-targets 全绿；
cargo run --example task_agent_demo exit 0。
 2026-07-05 19:48:59 +08:00
徐涛 6e1182e64c feat(core): 14 个公开枚举标记 #[non_exhaustive] 
为 v0.2.0-rc.1 API 稳定性收尾。覆盖：
- P0 核心 IR: Message / ContentBlock / ContentBlockType / StreamEvent / HookEvent
- P0 Error: AgentError / LlmError / ToolError / MemoryError / PromptError
- P1 其他: MemoryStrategy / StepStatus / ToolChoice / ResponseFormat

明确不加的: 内部 wire-format (OpenaiChatMessage 等) /
语义已收敛 (Role/ServiceTier 等) / 使用面窄 (Permission 等)。

示例侧的 3 处 Message exhaustive match (prompt_composer /
conversation_memory_demo) 补全 `_` 通配分支，零行为变化。

验收: cargo build + clippy -D warnings + test --all-targets 全绿 (200 passed)
 2026-07-05 19:47:03 +08:00
徐涛 b8f4fe0fe3 docs(AGENTS.md): 添加进度同步规范，明确 roadmap 更新要求 2026-07-05 17:40:22 +08:00
徐涛 7574f9c24c docs(roadmap): 标记 Phase 7 SqliteStore 已完成 
更新当前状态描述、Phase 7 交付物详情、里程碑 M3 状态、依赖性图谱及下一步行动
 2026-07-05 17:25:32 +08:00
徐涛 c82af60f81 feat(memory): 实现 SqliteStore 持久化 
- 新增 src/memory/store/sqlite_store.rs（SqliteStore + 9 个内联测试）
- 基于 rusqlite 0.32（bundled），使用 Arc<Mutex<Connection>> + spawn_blocking
- WAL 模式 + synchronous=NORMAL + busy_timeout=5s + PRAGMA user_version
  schema 版本管理
- created_at 归一化为 UTC 的 RFC 3339 TEXT，字典序等价时间序
- 错误精细映射：SqliteFailure/InvalidQuery → InvalidInput；
  FromSqlConversionFailure → Serialization；其他 → Storage
- 9 个测试覆盖 CRUD、upsert、prefix/since/offset+limit 过滤、
  10 写者 × 10 次并发、持久化 round-trip、trait-box 互换兼容性

依赖：
- rusqlite = { version = "0.32", features = ["bundled"] }
- time 增补 features: parsing, formatting, macros
- dev-dependencies: tempfile = "3"

测试：199 → 200 pass（191 原有 + 9 新增）
 2026-07-05 17:13:28 +08:00
徐涛 c8a91f6eaf refactor(memory): 将 store.rs 拆分为模块目录，仅结构搬移 
- 将 src/memory/store.rs 单体文件拆分为模块根 + store/ 目录结构
- InMemoryStore（struct + impl + Default + 6 个内联测试）整体提取到
  src/memory/store/in_memory.rs
- store.rs 保留 MemoryStore trait 与 EvictionPolicy/EvictionConfig
- 外部消费者导入路径 crate::memory::store::MemoryStore 不变
 2026-07-05 17:09:45 +08:00
徐涛 13edacd775 feat(memory): 添加 SqliteStore 持久化方案文档 2026-07-05 16:54:29 +08:00
徐涛 821cea8e60 feat(docs): 更新 roadmap，标记 Phase 6 交付完成 
Phase 6 ToolDef IR 的 5 个子步骤全部标注已完成，新增实际变更摘要，更新里程碑状态及下一步行动计划
 2026-07-05 10:49:50 +08:00
徐涛 517ef7db32 docs: 添加 Phase 6 ToolDefinition IR 正式化实施方案 2026-07-05 10:46:46 +08:00
徐涛 4cf5918b9c refactor(llm): 移除 ToolDefinition 别名与遗留 deprecation 抑制点 
完成 ToolDef IR 切换的最后清理：移除 ToolDefinition 别名与
OpenaiToolDefinition 的公共 re-export；各调用点（cycle/registry/mcp/agent）
直接使用 ToolDef 并清理对应的 #[allow(deprecated)] 抑制点；新增
roundtrip 测试验证 ToolDef 序列化兼容性。
 2026-07-05 10:32:35 +08:00
徐涛 9da9b83167 feat(llm): 切换至 ToolDef IR 并适配 OpenAI Provider 
将 MessageRequest.tools 切换为 Provider 无关的 ToolDef IR；
ToolDefinition 别名切换指向 ToolDef，registry/mcp 构造去掉
strict 字段；OpenAI 适配层通过 From 转换将 ToolDef 转为
OpenaiToolDefinition wire format。Anthropic 适配层字段名一致
无需改动，openai_compat/ollama 委托 GenericOpenaiProvider 无影响。
 2026-07-05 10:14:32 +08:00