agcore/CHANGELOG.md

# Changelog

本项目所有重要变更均记录于此文件。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。

## [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 |

[0.1.0]: https://git.archgrid.xyz/xt/agcore/releases/tag/v0.1.0