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
@@ -1,13 +1,13 @@
 # AG Core Roadmap

 > 定稿日期：2026-05-11
-> 最后更新：2026-06-11（Phase 4c 编码实施完成）
+> 最后更新：2026-07-04（v0.1 发布完成）

 ## 愿景

 AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。

-**当前状态**：Phase 0 基础设施已全部完成，Phase 1 提示词工程已全部完成，Phase 2 工具系统已全部完成，Phase 3 记忆系统已全部完成，Phase 4a 核心胶水层已全部完成，Phase 4b 任务执行已全部完成，Phase 4c 会话级记忆已全部完成（116 个测试通过，0 警告）。
+**当前状态**：Phase 0-4c 全部完成；Provider IR 重构（统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen Provider）已完成；LlmCycle 简化（IR 消息类型切换 + 桥接层移除）已完成；v0.1 发布就绪（**182 个测试通过、0 clippy 警告、7 个离线示例可运行**）。

 ---

@@ -338,3 +338,27 @@ graph BT
 - ✅ Phase 4a Core Glue — 全部交付物已完成
 - ✅ Phase 4b Task Execution — 全部交付物已完成
 - ✅ Phase 4c Session Memory — 全部交付物已完成
+- ✅ Provider IR 重构 — 统一类型系统 + OpenAI/Anthropic/DeepSeek/Qwen 适配（方案：`docs/10-llm-provider-refinement.md`、`docs/10a-phase0-types-and-trait.md`、`docs/10b-phase1-provider-adaptation.md`）
+- ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除（方案：`docs/10c-phase2-llm-cycle-simplify.md`）
+- ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、7 个离线示例、README + 错误消息友好化、Roadmap 同步、CHANGELOG 初始化（计划：`docs/11-v0.1-release-plan.md`）
+
+---
+
+## v0.1 发布里程碑（2026-07-04）
+
+**质量基线**：
+
+| 指标 | 数值 |
+|------|------|
+| `cargo build --all-targets` | ✅ 通过 |
+| `cargo test --all-targets` | ✅ **182 passed / 0 failed** |
+| `cargo clippy --all-targets -- -D warnings` | ✅ 0 警告 |
+| 离线示例（`cargo run --example`） | ✅ 7 个全部 exit 0 |
+
+**关键交付**：
+1. **Provider IR 重构** — 统一 `Message` / `ContentBlock` / `MessageRequest` / `MessageResponse` 类型层；4 个 Provider 适配（OpenAI Chat / Anthropic Messages / DeepSeek / Qwen）；`LlmProvider` trait 签名同步切换
+2. **LlmCycle 简化** — `LlmCycle` 内部消息类型切到 IR 层；移除 Phase 0 的 `OpenaiChatMessage ↔ Message` 桥接；测试从 116 → 182（含 provider 测试）
+3. **`MockProvider` 公开化** — `agcore::llm::mock::MockProvider` 支持 `chat` + `chat_stream`，无需 API key 即可运行示例
+4. **7 个离线示例** — `prompt_composer` / `custom_tool` / `agent_session_demo` / `task_agent_demo` / `conversation_memory_demo` / `knowledge_search_demo` / `streaming_events_demo`
+5. **错误消息友好化** — `AgentError` / `LlmError` / `ToolError` / `MemoryError` / `PromptError` 全部面向最终用户改写（给出可操作的建议）
+6. **文档完整** — README 完整版（快速上手 + 架构图 + 环境变量）、Apache-2.0 LICENSE