agcore/CHANGELOG.md

Changelog

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

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