From 4686063ca8444fb037d6695dc04813d4d0517749 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= <midnite@outlook.com>
Date: Thu, 9 Jul 2026 06:19:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=A0=87=E8=AE=B0=20Phase=2013=20?=
 =?UTF-8?q?=E5=AE=8C=E6=88=90=20+=20=E8=BF=BD=E5=8A=A0=20v0.3.0=20CHANGELO?=
 =?UTF-8?q?G=20=E6=9D=A1=E7=9B=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CHANGELOG.md: 追加 v0.3.0 (unreleased) 条目
  - Breaking Changes: 类型路径变更（request.rs/response.rs → provider/openai.rs，
    公共 ToolChoice re-export 路径不变）+ ChatResponse / LegacyStreamEvent 删除
  - Added: ContextSlot::fork / merge + MergeStrategy 枚举（#[non_exhaustive]）
  - Changed: 3 个旧 types 文件删除 + 所有 wire-format 类型迁入 openai.rs
  - Fixed: Phase 9 实施审查修复（PreRequest hook + 死代码清理 + 2 个集成测试）
  - Migration Guide: v0.2.0-rc.1 → v0.3.0 路径迁移示例
  - 修复 M9 里程碑验收 #11（CHANGELOG 条目）和审查结论 CONDITIONAL PASS 条件清单 #1
- docs/roadmap.md:
  - 顶部最后更新日期 → 2026-07-08（Phase 13 完成 + M9 里程碑达成）
  - 末尾"v0.3.0 规划完成"状态行从"Phase 13-19 待逐步实施"更新为"Phase 13 完成，
    Phase 14-19 待实施（Document → 向量存储 → 摘要 → 引擎 → 调度 → 知识图谱）"
---
 CHANGELOG.md    | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/roadmap.md |  4 ++--
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27c3397..e8f7a79 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,69 @@
 
 本项目所有重要变更均记录于此文件。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.3.0] - 未发布
+
+v0.3.0 首个增量 Phase。技术债清理 + ContextSlot fork/merge + Phase 9 审查修复。
+
+### Breaking Changes
+
+**类型路径变更（0.3.0）：**
+- `agcore::llm::types::request::ToolChoice` → `agcore::llm::types::tool::ToolChoice`（公共 re-export 路径 `agcore::llm::types::ToolChoice` 保持不变）
+- `agcore::llm::types::request::StreamOptions` → `agcore::llm::provider::openai::StreamOptions`
+- `agcore::llm::types::request::OpenaiChatRequest` → `agcore::llm::provider::openai::OpenaiChatRequest`
+- `agcore::llm::types::response::OpenaiChatResponse` → `agcore::llm::provider::openai::OpenaiChatResponse`
+- `agcore::llm::types::response::OpenaiChatChunk` → `agcore::llm::provider::openai::OpenaiChatChunk`
+- 其余 `request.rs`/`response.rs` 中的 wire-format 类型（`OpenaiTool`、`AudioParam`、`Choice`、`Delta`、`ChunkChoice`、`Annotation`、`Logprobs`、`TokenLogprob`、`URLCitation` 等）同步移入 `agcore::llm::provider::openai` 模块，可见性 `pub(crate)`
+
+**类型删除：**
+- `agcore::llm::types::ChatResponse` 已删除（自 v0.1.0 标记 `#[deprecated]`，请改用 `MessageResponse`）
+- `agcore::llm::types::old_stream::LegacyStreamEvent` 已删除（内部死代码）
+
+**模块签名变化：**
+- `LlmCycle::convert_request` / `convert_response` 由 `pub` 降级为 `pub(crate)`（因依赖的 `OpenaiChatRequest` / `OpenaiChatResponse` 已 `pub(crate)`）
+
+### Added
+
+**Phase 13 — ContextSlot fork/merge**
+- `ContextSlot::fork(child_id, strategy)` — 从父槽派生独立子槽（数据层操作，不持久化；调用方需自行 `save()`）
+- `ContextSlot::merge(child, strategy)` — 将子槽消息合并回父槽（`Append` 追加 / `Replace` 替换两种策略）
+- `MergeStrategy` 枚举（`#[non_exhaustive]`，Phase 16 可扩展 `Summarize`）
+- `MergeStrategy` 防御性检查：禁止 self-merge / 跨 session merge / 合并到 Readonly slot
+- `agcore::agent::MergeStrategy` 公共 re-export 路径可用
+- `AgentSession::derive_slot` 重构复用 `fork()` 消除重复代码（行为不变）
+
+**Phase 9 实施审查修复（2026-07-08）**
+- 2 个集成测试覆盖方案 §4 Step 5：`submit_turn_stream_end_to_end` + `submit_turn_stream_triggers_turn_hooks`
+
+### Changed
+
+**Phase 13 — 技术债清理**
+- 3 个旧 types 文件删除（`src/llm/types/request.rs` 187 行 + `response.rs` 177 行 + `old_stream.rs` 45 行）
+- 所有 OpenAI wire-format 类型迁入 `provider/openai.rs`，可见性 `pub(crate)`
+- `src/llm/stream.rs` 简化为 module doc + `pub use` 重导出（保持 `use crate::llm::stream::StreamEvent` 路径兼容，零下游破坏）
+- `ToolChoice` 从 `request.rs` 迁入 `tool.rs`（serde impl 原样搬入）
+
+**Phase 9 实施审查修复**
+- `LlmCycle::run_tool_loop` 实现 `PreRequest` hook（之前 `let _ = hook_executor.as_ref()` 是空操作，导致 hook-based logging/monitoring 在流式工具循环中失效；现在与 `submit_with_tools` 行为对齐，含 `should_block` 检查，阻断时通过 `StreamEvent::Error` 事件化）
+
+### Fixed
+
+**Phase 9 实施审查修复**
+- `AgentSession::submit_turn_stream` 末尾 `let _ = hook_executor;` 死代码移除（Arc 引用生命周期由 Arc 自动管理）
+
+### Migration Guide (v0.2.0-rc.1 → v0.3.0)
+
+```rust
+// ❌ v0.2.0-rc.1 — 已删除
+use agcore::llm::types::ChatResponse;
+use agcore::llm::types::request::OpenaiChatRequest;
+
+// ✅ v0.3.0 — 替代路径
+use agcore::llm::types::MessageResponse; // ChatResponse → MessageResponse
+// OpenAI wire-format 类型为内部使用，不再公共 re-export
+// 如需自定义 Provider，请直接 import agcore::llm::provider::openai::*（当前 pub(crate)）
+```
+
 ## [0.2.0-rc.1] - 2026-07-05
 
 v0.2.0 候选发布。Phase 5-7 三大 P0 全部交付完成，API 稳定性扫尾，新增 2 个面向新用户的集成示例。
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c4aa2ea..c0b8bf9 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -1,7 +1,7 @@
 # AG Core Roadmap
 
 > 定稿日期：2026-05-11
-> 最后更新：2026-07-06（v0.3.0 规划更新）
+> 最后更新：2026-07-08（Phase 13 完成 + M9 里程碑达成）
 
 ## 愿景
 
@@ -891,7 +891,7 @@ graph BT
 - ✅ LlmCycle 简化 — IR 消息类型切换 + Phase 0 桥接层移除
 - ✅ v0.1 Release — 技术债扫清、MockProvider 公开化、8 个离线示例（含 `simple_visit`）、README + 错误消息友好化、CHANGELOG 初始化
 - ✅ **v0.2 规划细化完成** — 8 个增量 Phase（Phase 5-12），17 个可验证 Step，覆盖 P0-P2 全部 12 项功能 + ContextSlot
-- 📋 **v0.3.0 规划完成** — Phase 13-19 共 7 个增量 Phase 已推演，覆盖技术债清理、Document 系统、向量存储持久化、摘要自动生成、Agent 执行引擎、SubAgent Dispatch、知识图谱。待逐步实施
+- ✅ **v0.3.0 Phase 13 完成** — 技术债清理（3 旧 types 文件 + ChatResponse 删除）+ ContextSlot fork/merge（9 新测试），M9 里程碑达成；Phase 14-19 共 6 个增量 Phase 待实施（Document → 向量存储 → 摘要 → 引擎 → 调度 → 知识图谱）
 
 ---