docs(v0.1): 同步 roadmap 并初始化 CHANGELOG

- docs/roadmap.md：更新顶部状态至 v0.1 发布完成（182 测试 / 0 警告 / 7 离线示例），末尾追加 v0.1 发布里程碑章节 - CHANGELOG.md：按 Keep a Changelog 规范记录 0.1.0 的 Added / Changed / Deprecated / Fixed / Removed 及版本基线
2026-07-04 06:54:13 +08:00
parent 602bd43fce
commit 8dcd1f2482
2 changed files with 117 additions and 2 deletions
@@ -0,0 +1,91 @@
+# 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://github.com/anomalyco/agcore/releases/tag/v0.1.0