agcore/CHANGELOG.md

Changelog

本项目所有重要变更均记录于此文件。格式参考 Keep a Changelog。

[0.3.0] - 未发布

v0.3.0 首个增量 Phase。技术债清理 + ContextSlot fork/merge + Phase 9 审查修复。

Breaking Changes

类型路径变更（0.3.0）：

• agcore::llm::types::request::ToolChoice → agcore::llm::types::tool::ToolChoice（公共 re-export 路径 agcore::llm::types::ToolChoice 保持不变）
• agcore::llm::types::request::StreamOptions → agcore::llm::provider::openai::StreamOptions
• agcore::llm::types::request::OpenaiChatRequest → agcore::llm::provider::openai::OpenaiChatRequest
• agcore::llm::types::response::OpenaiChatResponse → agcore::llm::provider::openai::OpenaiChatResponse
• agcore::llm::types::response::OpenaiChatChunk → agcore::llm::provider::openai::OpenaiChatChunk
• 其余 request.rs/response.rs 中的 wire-format 类型（OpenaiTool、AudioParam、Choice、Delta、ChunkChoice、Annotation、Logprobs、TokenLogprob、URLCitation 等）同步移入 agcore::llm::provider::openai 模块，可见性 pub(crate)

类型删除：

• agcore::llm::types::ChatResponse 已删除（自 v0.1.0 标记 #[deprecated]，请改用 MessageResponse）
• agcore::llm::types::old_stream::LegacyStreamEvent 已删除（内部死代码）

模块签名变化：

• LlmCycle::convert_request / convert_response 由 pub 降级为 pub(crate)（因依赖的 OpenaiChatRequest / OpenaiChatResponse 已 pub(crate)）

Added

Phase 13 — ContextSlot fork/merge

• ContextSlot::fork(child_id, strategy) — 从父槽派生独立子槽（数据层操作，不持久化；调用方需自行 save()）
• ContextSlot::merge(child, strategy) — 将子槽消息合并回父槽（Append 追加 / Replace 替换两种策略）
• MergeStrategy 枚举（#[non_exhaustive]，Phase 16 可扩展 Summarize）
• MergeStrategy 防御性检查：禁止 self-merge / 跨 session merge / 合并到 Readonly slot
• agcore::agent::MergeStrategy 公共 re-export 路径可用
• AgentSession::derive_slot 重构复用 fork() 消除重复代码（行为不变）

Phase 9 实施审查修复（2026-07-08）

• 2 个集成测试覆盖方案 §4 Step 5：submit_turn_stream_end_to_end + submit_turn_stream_triggers_turn_hooks

Changed

Phase 13 — 技术债清理

• 3 个旧 types 文件删除（src/llm/types/request.rs 187 行 + response.rs 177 行 + old_stream.rs 45 行）
• 所有 OpenAI wire-format 类型迁入 provider/openai.rs，可见性 pub(crate)
• src/llm/stream.rs 简化为 module doc + pub use 重导出（保持 use crate::llm::stream::StreamEvent 路径兼容，零下游破坏）
• ToolChoice 从 request.rs 迁入 tool.rs（serde impl 原样搬入）

Phase 9 实施审查修复

• LlmCycle::run_tool_loop 实现 PreRequest hook（之前 let _ = hook_executor.as_ref() 是空操作，导致 hook-based logging/monitoring 在流式工具循环中失效；现在与 submit_with_tools 行为对齐，含 should_block 检查，阻断时通过 StreamEvent::Error 事件化）

Fixed

Phase 9 实施审查修复

• AgentSession::submit_turn_stream 末尾 let _ = hook_executor; 死代码移除（Arc 引用生命周期由 Arc 自动管理）

Migration Guide (v0.2.0-rc.1 → v0.3.0)

// ❌ v0.2.0-rc.1 — 已删除
use agcore::llm::types::ChatResponse;
use agcore::llm::types::request::OpenaiChatRequest;

// ✅ v0.3.0 — 替代路径
use agcore::llm::types::MessageResponse; // ChatResponse → MessageResponse
// OpenAI wire-format 类型为内部使用，不再公共 re-export
// 如需自定义 Provider，请直接 import agcore::llm::provider::openai::*（当前 pub(crate)）

[0.2.0-rc.1] - 2026-07-05

v0.2.0 候选发布。Phase 5-7 三大 P0 全部交付完成，API 稳定性扫尾，新增 2 个面向新用户的集成示例。

Added

Phase 5 — 热身准备

• ProviderConfig::from_env(prefix)：从 {prefix}_BASE_URL / {prefix}_API_KEY / {prefix}_MODEL / {prefix}_TIMEOUT_SECS / {prefix}_MAX_RETRIES 环境变量构造配置
• ProviderConfig::timeout_secs / max_retries 字段（默认 30 / 3）
• OllamaProvider：本地推理 Provider（OpenAI-compatible，http://localhost:11434/v1 默认端点）
• ProviderType::Ollama 变体 + FromStr 解析

Phase 6 — ToolDef IR 正式化

• ToolDef 结构体（name / description / parameters）替代已废弃的 OpenaiToolDefinition
• MessageRequest.tools 切换为 Vec<ToolDef>
• OpenaiToolDefinition 降级为 #[doc(hidden)]，仅供 OpenAI 适配层内部消费

Phase 7 — SqliteStore 持久化

• SqliteStore：MemoryStore 的 SQLite 后端实现，基于 rusqlite 0.32 bundled
• WAL 模式 + synchronous=NORMAL + busy_timeout=5s 兼顾崩溃安全与吞吐
• Arc<Mutex<Connection>> + spawn_blocking 卸载 IO；10×10 并发写入无 race
• MemoryStore::save / get / delete / list CRUD + prefix / since / offset+limit 过滤
• 进程重启数据不丢的 round-trip 验证

Phase 8 — MVP 集成出口

• examples/quick_start：30 行最小可运行示例（MockProvider + EchoTool + submit_turn）
• examples/end_to_end：3 工具 + 3 轮对话 + SqliteStore 持久化跨连接验证

Changed

• API 稳定性护栏：14 个公开枚举标记 #[non_exhaustive]，覆盖 P0 核心 IR（Message / ContentBlock / ContentBlockType / StreamEvent / HookEvent）、P0 Error（AgentError / LlmError / ToolError / MemoryError / PromptError）、P1 其他（MemoryStrategy / StepStatus / ToolChoice / ResponseFormat）
• StepStatus::Completed 字段类型：从废弃的 ChatResponse 切换为 IR 层 MessageResponse（同时清理 task_agent_demo.rs 的 ChatResponse / OpenaiChatMessage / FinishReason 三处废弃类型引用）

Non-exhaustive 清单

为防止未来新增变体时下游 exhaustive match 静默失效，14 个枚举追加 #[non_exhaustive]：

优先级	枚举
P0 核心 IR	Message, ContentBlock, ContentBlockType, StreamEvent, HookEvent
P0 Error	AgentError, LlmError, ToolError, MemoryError, PromptError
P1 其他	MemoryStrategy, StepStatus, ToolChoice, ResponseFormat

明确不加：内部 wire-format（OpenaiChatMessage 等）/ 语义已收敛（Role / ServiceTier / Modality / ImageDetail / AudioFormat / StopSequence）/ 使用面窄（Permission / McpTransport 等）。

Deprecated

（继承自 0.1.0，无新增）ChatResponse / ToolDefinition 保持 #[deprecated] 标记。

Fixed

• 修复 StepStatus::Completed(ChatResponse) 字段类型与 IR 体系不一致问题（已完成迁移）

Migration Guide (v0.1 → v0.2.0-rc.1)

1. 枚举 match：14 个 #[non_exhaustive] 枚举在 crate 外必须使用 _ => 通配分支
2. StepStatus::Completed：字段类型从 ChatResponse 切换为 MessageResponse，需做字段映射（参考 docs/15-phase8-mvp-integration.md §3.1.2）
3. ToolDefinition → ToolDef：Phase 6 已彻底替换 #[deprecated] 别名，需全局重命名

---

0.1.0 - 2026-07-04

首个公开版本。涵盖 Phase 0-4c 的全部核心能力、Provider IR 重构、LlmCycle 简化，以及面向用户的 7 个离线示例。

Added

LLM 调用周期（Phase 0）

• 统一 IR 类型层：Message、ContentBlock、MessageRequest、MessageResponse、ToolDefinition、StopReason
• LlmProvider trait + 4 个 Provider 实现：OpenAI Chat Completions、Anthropic Messages、DeepSeek（OpenAI 兼容）、Qwen（OpenAI 兼容）
• ProviderRegistry：多 Provider 注册与发现
• LlmCycle：重试策略 + 用量追踪 + 自动 tool 循环 + Auto-compaction
• HookExecutor：OnTurnStart / OnTurnEnd / OnPlanStepComplete 等生命周期钩子
• StreamEvents：AssistantTextDelta / ToolExecutionStarted / MessageComplete 等流式事件

提示词工程（Phase 1）

• PromptTemplate：变量插值 + 条件渲染
• PromptComposer：system/user/assistant/tool_result 消息链组合

工具系统（Phase 2）

• ToolRegistry：注册、发现、并行调用、超时控制
• BaseTool trait（含 ToolContext 执行上下文）
• McpClient：stdio transport（StreamableHttp 已预留接口）
• PermissionChecker：白名单 / 黑名单 / 自定义权限

记忆系统（Phase 3）

• MemoryStore trait + InMemoryStore 默认实现
• ConversationMemory：sliding window / 全量模式，集成 llm::compact
• KnowledgeStore：知识页面存储
• MemoryRetriever：TextOverlap Dice 系数评分
• EvictionPolicy：None / Ttl / Capacity 三种淘汰策略

Agent 运行时（Phase 4a/b/c）

• Agent trait：name / system_prompt / tool_definitions
• AgentSession + RuntimeBundle + AgentBuilder：链式构造 + 依赖注入
• AgentError：Llm / Tool / Memory / HookBlocked / LimitExceeded / Config / PlanParse / Other 8 个变体
• TaskAgent trait + JsonPlanParser：自主执行 + 外部驱动
• Plan / Step / StepStatus：纯数据结构
• SessionMemory：基于 MemoryStore 的会话级 key-value 桥接

面向用户的资产

• agcore::llm::mock::MockProvider：公开的 Mock Provider，支持 chat + chat_stream，无需 API key 即可运行示例
• 7 个离线可运行示例（cargo run --example ...）：
  • prompt_composer — 模板变量插值 + 消息链构建
  • custom_tool — 工具注册 + 权限检查
  • agent_session_demo — AgentBuilder → AgentSession → submit_turn 完整链路
  • task_agent_demo — JsonPlanParser → Plan → Step 状态机
  • conversation_memory_demo — SessionMemory 命名空间隔离
  • knowledge_search_demo — KnowledgeStore + 停用词过滤
  • streaming_events_demo — 流式事件消费

Changed

• LlmCycle 切换到 IR 消息类型：内部消息从 OpenaiChatMessage 切到统一 Message 类型，移除 Phase 0 的桥接转换层（方案：docs/10c-phase2-llm-cycle-simplify.md）
• Provider IR 重构：LlmProvider trait 签名同步切到 MessageRequest / MessageResponse；新增 Anthropic / DeepSeek / Qwen Provider（方案：docs/10-llm-provider-refinement.md、docs/10b-phase1-provider-adaptation.md）
• AgentBuilder 扩展 session_memory_backend：Phase 4c 接入会话级记忆
• 错误消息面向最终用户友好化：AgentError / LlmError / ToolError / MemoryError / PromptError 全部改写为带可操作建议的友好消息
• composer.rs IR 迁移：PromptComposer 内部从 OpenaiChatMessage 切到 Message / ContentBlock，与新类型系统保持一致
• knowledge.rs 锁修复：std::sync::Mutex → tokio::sync::Mutex，避免 MutexGuard 跨 .await 持有

Deprecated

• ChatResponse — 自 0.1.0 起标记为 deprecated，请改用 MessageResponse
• ToolDefinition — 自 0.1.0 起标记为 deprecated（仍直接对应 OpenAI wire-format）；v0.2 将引入 IR 工具类型

Fixed

• 修复 Provider IR 重构后 session.rs / cycle.rs 测试模块的导入缺失回归
• 修复 knowledge.rs::search() 中 MutexGuard 跨 .await 持有的潜在阻塞
• 清零全部 clippy 警告（#[allow(dead_code)] 已在最低必要范围使用）

Removed

• 移除 Phase 0 的 OpenaiChatMessage ↔ Message 桥接层（LlmCycle 简化后已无外部调用方）

---

版本基线

指标	数值
cargo build --all-targets	✅ 通过
cargo test --all-targets	✅ 182 passed / 0 failed
cargo clippy --all-targets -- -D warnings	✅ 0 警告
离线示例	✅ 7 个全部 cargo run 退出码 0
许可证	Apache-2.0