徐涛
1c89d23ba2
- 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 确认版本号与示例数对齐。
152 lines
8.1 KiB
Markdown
152 lines
8.1 KiB
Markdown
# Changelog
|
||
|
||
本项目所有重要变更均记录于此文件。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
|
||
|
||
## [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 |
|
||
|
||
[0.1.0]: https://git.archgrid.xyz/xt/agcore/releases/tag/v0.1.0 |