# Phase 2 实施计划：LlmCycle 简化（逻辑重构）

> **所属方案**：[10-llm-provider-refinement.md](10-llm-provider-refinement.md)
>
> **前置条件**：Phase 0 + Phase 1 已完成——新类型已就位，所有 Provider 已适配新 trait 签名
>
> **⚠️ 交叉阶段修复**：审查发现部分关键修复需在 Phase 0 期间处理，否则 Phase 2 无法直接实施。详见下文"审查发现与交叉阶段修复计划"。
>
> **目标**：移除 Phase 0 遗留的临时转换层，将 `LlmCycle` 内部消息存储从 `Vec<OpenaiChatMessage>` 切换为 `Vec<Message>`，利用新类型的表达能力重写核心逻辑

---

## 目标

1. 将 `LlmCycle` 内部消息存储从 `Vec<OpenaiChatMessage>` 切换为 `Vec<Message>`，**移除 Phase 0 引入的 `OpenaiChatMessage ←→ Message` 转换层**
2. 流处理循环重构：利用 `MessageComplete.full_response` 直接拿到完整响应，去掉手动 delta 累积
3. 工具循环清洗：从 `MessageResponse.message` 的 content 中直接提取 `ContentBlock::ToolUse`
4. `compact.rs` 适配新 `Message` 类型
5. `ConversationMemory` 的消息类型同步切换

---

## 审查发现与交叉阶段修复计划

> 本方案于 2026-06-30 经架构审查发现 4 个必须修复的问题和多个需在 Phase 0 提前处理的依赖项。以下修复计划按"所属阶段"分类，标注责任文件和建议修复方式。

### 🔴 交叉阶段修复（Phase 0 期间完成，否则 Phase 2 受阻）

#### FIX-A：`ToolInvocation` 增加 `tool_call_id` 字段

| 属性 | 值 |
|------|-----|
| **严重程度** | 🔴 阻碍性 |
| **影响** | 工具结果回传时 tool_call_id 丢失，Anthropic Provider 上必然失败 |
| **文件** | `src/tools/registry.rs`（`ToolInvocation` 结构体）、`src/llm/cycle.rs`（调用点） |

**问题跟踪**：
- `ToolInvocation`（`registry.rs:17-35`）只有 `tool_name`、`input`、`output` 三个字段，**没有 `tool_call_id`**
- `invoke_all()` 签名（`registry.rs:149-151`）接收 `Vec<(String, Value)>`（name, args），**未传递 id**
- `invoke()` 签名（`registry.rs:131`）是 `(&self, name: &str, args: Value)`，**未传递 id**
- 当前代码用 `result.tool_name` 冒充 `tool_call_id`（`cycle.rs:617`）——对 OpenAI 碰巧可用，Anthropic 必然失败
- `has_tool_calls_in_message`（`cycle.rs:645`）基于旧 `OpenaiChatMessage::Assistant { tool_calls }` 判断，Phase 2 需同步改为检查 `ContentBlock::ToolUse`

**修复方案**：

```rust
// ToolInvocation 增加 tool_call_id（必选，每次调用必有真实值）
pub struct ToolInvocation {
    pub tool_call_id: String,    // 新增
    pub tool_name: String,
    pub input: Value,
    pub output: Result<Value, ToolError>,
}

// ToolContext 不增加 tool_call_id：
// 当前 ToolContext::new(name, "") 中 trace_id 已被设为空串，
// tool_call_id 通过 invoke_all→invoke→ToolInvocation 传递即可，
// 工具实现方不需要感知 tool_call_id。
```

> **关于 `ToolContext` 的决策**：不向 `ToolContext` 增加 `tool_call_id`。理由是 `ToolContext` 目前通过 `invoke()` 内部构造（`registry.rs:140`：`ToolContext::new(name, "")`），传递的是 `tool_name` 而非 `tool_call_id`。若增加 `tool_call_id` 字段会要求所有 `invoke` 调用链都感知 id——这增加了复杂度，而工具实现方实际并不需要 tool_call_id（结果是按调用顺序返回的，工具通过在消息历史中搜索 `ToolUse` 来关联上下文）。**`tool_call_id` 仅在 `ToolInvocation` 中保存，供 `submit_with_tools` 回传时使用。**

**数据流**：`extract_tool_calls_from_message()` 返回 `(id, name, args)` → `invoke_all` 签名改为 `Vec<(String, String, Value)>`（id, name, args）→ `ToolInvocation.tool_call_id` → `submit_with_tools()` 回传工具结果时使用 `result.tool_call_id`。`invoke()` 内部在构造 `ToolInvocation` 时即可获得 tool_call_id。

**建议归属**：Phase 2.2（随 Task 4 统一改 `registry.rs` + `cycle.rs`，避免切割到 Phase 0 导致 scope 漂移）

**影响范围**：
- `ToolInvocation::new()` 签名从 3 参数变为 4 参数（`registry.rs:28`）
- `invoke()` 签名从 `(&self, name, args)` 改为 `(&self, tool_call_id, name, args)` 或内部通过包装传递（`registry.rs:131`）
- `invoke_all()` 签名从 `Vec<(String, Value)>` 改为 `Vec<(String, String, Value)>`（`registry.rs:149-151`）
- `cycle.rs:584-594` 中 `|(_id, name, args)|` → `|(id, name, args)|` 不再丢弃 id
- 测试代码中的 `ToolInvocation` 和 `invoke_all` 调用点同步更新

---

#### FIX-B：`Message` + `ContentBlock` 的 serde 派生在 Phase 0 添加

| 属性 | 值 |
|------|-----|
| **严重程度** | 🔴 阻碍性 |
| **影响** | Phase 0→Phase 2 过渡期 ConversationMemory 无法使用新类型 |

**问题**：Phase 2 的 Task 7（ConversationMemory 适配）依赖 `Message` 实现 `Serialize`/`Deserialize`。如果 Phase 0 定义 `Message` 时未添加 serde 派生，Phase 2 需要回头修改 Phase 0 创建的文件，造成"谁创建谁维护"责任混乱。

**修复方案**：Phase 0 定义新类型时直接添加 serde 派生：

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Message {
    System { content: Vec<ContentBlock> },
    User { content: Vec<ContentBlock> },
    UserImage { data: String, mime_type: String, detail: ImageDetail },
    Assistant { content: Vec<ContentBlock> },
    ToolResult { tool_call_id: String, content: Vec<ContentBlock>, is_error: bool },
}
```

`ContentBlock` 同样添加 serde 派生（tag 策略在 Phase 0 设计时决定，建议 `#[serde(rename_all = "snake_case")]` + `tag = "type"` 或 untagged 视用法而定）。

此序列化格式**仅用于内部存储**（ConversationMemory 持久化），不与任何 Provider 协议交互，故无需考虑外部兼容性。`UserImage` 的 JSON 形如 `{"type": "user_image", "data": "...", "mime_type": "image/png", "detail": "auto"}`。

**同步添加构造方法**（`impl Message` 块中的便捷构造函数，FIX-D 的 deprecated shim 和 Phase 2 各 Task 都依赖它们）：

```rust
impl Message {
    pub fn system_text(text: impl Into<String>) -> Self {
        Message::System { content: vec![ContentBlock::Text { text: text.into() }] }
    }
    pub fn user_text(text: impl Into<String>) -> Self {
        Message::User { content: vec![ContentBlock::Text { text: text.into() }] }
    }
    pub fn assistant(text: impl Into<String>) -> Self {
        Message::Assistant { content: vec![ContentBlock::Text { text: text.into() }] }
    }
    pub fn tool_result(tool_call_id: impl Into<String>, text: impl Into<String>, is_error: bool) -> Self {
        Message::ToolResult {
            tool_call_id: tool_call_id.into(),
            content: vec![ContentBlock::Text { text: text.into() }],
            is_error,
        }
    }
}
```

**建议归属**：Phase 0，作为类型定义的一部分（零成本加法）

---

#### FIX-C：`ContentBlock` 变体列表在 Phase 0 设计时明确

| 属性 | 值 |
|------|-----|
| **严重程度** | 🔴 阻碍性 |
| **影响** | 方案中 `estimate_block_tokens` 的 match 分支引用了未定义的 `ContentBlock::ToolResult`，导致 Phase 2 实施时类型不匹配 |

**问题**：方案 §6b 的 `estimate_block_tokens` 中出现 `ContentBlock::ToolResult { content, .. }` 分支（第 374 行），但父方案 `10-llm-provider-refinement.md` §2.1 定义 `ContentBlock` 时并未包含 `ToolResult` 变体。`ToolResult` 是 `Message` 的变体（消息级角色），不是 `ContentBlock` 的变体（内容块级角色）。

**分析**：在 Anthropic 协议中，`Assistant` 消息的 content 可以直接包含 `tool_result` block——这对应 `ContentBlock::ToolResult` 的应用场景（嵌套在其他消息的 content 中）；而 `Message::ToolResult` 对应 OpenAI 的 `role: "tool"` 消息（消息列表的顶层变体）。二者语义层级不同，**可以合理共存**。

**修复方案**：Phase 0 设计 `ContentBlock` 时明确是否包含 `ToolResult` 变体。推荐包含，因为：

1. Anthropic 协议支持 Assistant 消息内嵌 tool_result block
2. 简化 Phase 2 的 `estimate_block_tokens` 实现（不需要在 match 中分流）
3. 让 `compact` 估算函数能递归处理嵌套的 tool result content

Phase 2 的 `estimate_block_tokens` 改为穷尽 match（不再使用 `_ => 50` 兜底），编译器强制检查所有变体覆盖。

**建议归属**：Phase 0 设计决策，Phase 2 代码编写时确认

---

#### FIX-D：`system_prompt` 字段彻底移除

| 属性 | 值 |
|------|-----|
| **严重程度** | 🔴 阻碍性 |
| **影响** | 与父方案 §2.4 设计意图矛盾，"两条路径"（字段 + messages 中的 System 消息）可能导致重复/覆盖 |

**问题**：方案 §2a 保留 `system_prompt: Option<String>` 字段，在 `build_request()` 中转为 `Message::System` 插入 messages 开头。但父方案 §2.4 明确意图："system prompt 通过 `Message::System` 在 messages 中表达，Provider 映射层自行处理差异"。保留字段导致两条路径：

- 路径 1：调用方通过 `with_system_prompt()` 设置纯文本
- 路径 2：调用方直接通过 `with_messages()` 传入 `Message::System`

`build_request()` 中通过 `!messages.iter().any(|m| matches!(m, Message::System { .. }))` 尝试检测"是否已有系统消息"，但本质上无法区分"用户主动传入的 System"和"之前阶段插入的 System"。

**修复方案**：
1. **彻底移除** `system_prompt: Option<String>` 字段
2. **移除** `with_system_prompt()` 方法
3. 调用方改为使用 `Message::system_text()` + `with_messages()` 或 builder 模式
4. `build_request()` 直接使用 `self.messages`，不做任何 System 消息插入

```rust
pub struct LlmCycle {
    provider: Arc<dyn LlmProvider>,
    config: CycleConfig,
    usage: CostTracker,
    messages: Vec<Message>,        // 调用方自行管理所有消息类型
    // system_prompt 已移除
    hook_executor: Option<Arc<HookExecutor>>,
    compact_config: Option<CompactConfig>,
    compact_state: CompactState,
}
```

如需向后兼容（有已有调用方使用 `with_system_prompt`），可在 `LlmCycle::new()` 或 `submit()` 前设置一个短暂的弃用期：

```rust
#[deprecated(since = "0.x.0", note = "请改用 Message::system_text() + with_messages()")]
pub fn with_system_prompt(mut self, prompt: String) -> Self {
    self.messages.insert(0, Message::system_text(prompt));
    self
}
```

**建议归属**：Phase 2.0（与 Task 1 消息切换一步到位，杜绝过渡期。不在 Phase 2.1 留存已废弃字段）

**调用方迁移**（需在 Phase 2.0 实施前确认）：

| 调用位置 | 代码 | 迁移方式 |
|---------|------|---------|
| `src/agent/session.rs:141-143` | `if let Some(prompt) = self.agent.system_prompt() { cycle = cycle.with_system_prompt(prompt.to_string()); }` | 改为 `cycle = cycle.with_messages(vec![Message::system_text(prompt)])`，或在 `submit_turn` 内部直接 push |

**依赖**：`Message::system_text()` 构造方法必须在 Phase 0 定义 `Message` 类型时同步添加（见 FIX-B）。`#[deprecated]` shim 中调用的 `Message::system_text(prompt)` 依赖于它。

---

### 🟡 Phase 2 内部修复

#### FIX-E：`submit_stream` 返回类型修正 + 闭包借用问题解决

| 属性 | 值 |
|------|-----|
| **严重程度** | 🟡 必须修复（编译错误 + API 语义断裂） |
| **影响** | 方案代码存在编译错误（yield Ok(event) vs 签名不匹配）；`&mut self` 借用冲突；post_request hook 消息不完整 |

**三个问题**：

1. **返回类型不匹配**（§3a 第 159 行）：`yield Ok(event.clone())` 产生 `Result<StreamEvent, LlmError>`，但函数签名声明 `Item = StreamEvent`。

2. **`&mut self` 借用冲突**（§3a 第 163 行）：`self.messages.push(...)` 在 `stream!` 闭包中需要 `&mut self`，但闭包只能捕获共享引用。

3. **post_request hook 消息不完整**（§3a 第 149 行）：`let post_request = self.build_request(&tools)` 在流启动前执行，此时 `self.messages` 只有 user 消息，不包括即将到来的 Assistant 响应。

**⚠️ 审查结论：mpsc 方案不可行，采用简化方案作为主方案**

**为什么 mpsc 方案不成立**（两次审查确认）：

| 问题 | 描述 | 根本原因 |
|------|------|---------|
| `rx` 竞争 | mpsc `rx` 只能有一个消费者，但代码中两个 `async move` 块都试图消费 | 编译错误 |
| 阻塞破坏流契约 | `response_rx.await` 在返回流前阻塞等待整个流结束 | 不是流式 API |
| `StreamEvent::StreamEnd` 不存在 | 引用了未定义的变体 | 新旧 StreamEvent 均无此变体 |
| `tokio::spawn` task leak | JoinHandle 被丢弃，调用方 drop Stream 后 task 可能永久挂起 | 资源泄漏 |

**核心矛盾**：`stream!` 宏产生的异步生成器无法持有 `&mut self`（Pin 限制），且流是"延迟求值"的——`submit_stream` 返回流对象时流尚未执行。这意味着**没有任何通道方案能让 `submit_stream` 在返回流之前就拿到完整响应**。如果想在流结束后更新 `self.messages`，必须让调用方在流结束后显式调用一个方法。

**采用简化方案作为主方案**：

```rust
pub async fn submit_stream(
    &mut self,
    prompt: String,
    tools: Vec<ToolDefinition>,
) -> Result<Pin<Box<dyn Stream<Item = StreamEvent> + Send>>, LlmError> {
    self.messages.push(Message::user_text(prompt));
    self.maybe_compact();

    let request = self.build_request(&tools);

    // PreRequest hook
    if let Some(ref executor) = self.hook_executor {
        let ctx = HookContext::new(HookEvent::PreRequest).with_request(&request);
        let results = executor.execute(HookEvent::PreRequest, &ctx).await;
        if results.iter().any(|r| r.should_block) {
            return Err(LlmError::Other("Blocked by pre-request hook".to_string()));
        }
    }

    let event_stream = self.provider.chat_stream(request).await?;
    let hook_executor = self.hook_executor.clone();

    Ok(Box::pin(stream! {
        use futures_util::StreamExt;
        let mut event_stream = event_stream;

        while let Some(result) = event_stream.next().await {
            match result {
                Ok(event) => {
                    yield event;
                }
                Err(e) => {
                    if let Some(ref executor) = hook_executor {
                        let ctx = HookContext::new(HookEvent::OnError).with_error(&e);
                        executor.execute(HookEvent::OnError, &ctx).await;
                    }
                    yield StreamEvent::Error { message: e.to_string() };
                    break;
                }
            }
        }

        // PostRequest hook：注意此处的消息列表不包含本次 Assistant 响应
        // （因为在流启动前 request 就已构建完成）
        if let Some(ref executor) = hook_executor {
            let ctx = HookContext::new(HookEvent::PostRequest);
            executor.execute(HookEvent::PostRequest, &ctx).await;
        }
    }))
}
```

**变更**：
1. `yield event` 直接产生 `StreamEvent`（与签名 `Item = StreamEvent` 一致）——移除 `Ok()` 包装
2. 不再在闭包中操作 `self.messages`——调用方在收到 `MessageComplete` 事件后自行调用 `cycle.push_message(full_response.message)`
3. post_request hook 明确文档化限制

**调用方使用模式**：

```rust
let mut stream = cycle.submit_stream(prompt, tools).await?;
let mut final_response: Option<MessageResponse> = None;

while let Some(event) = stream.next().await {
    match &event {
        StreamEvent::MessageComplete { full_response } => {
            final_response = Some(full_response.clone());
        }
        // 处理其他事件...
        _ => {}
    }
}

// 流结束后更新消息历史
if let Some(resp) = final_response {
    cycle.push_message(resp.message.clone());
    // usage update via cycle.usage().add(&resp.usage);
}
```

**建议归属**：Phase 2.2，Task 3 实施时

---

#### FIX-F：`microcompact` 跳过 `is_error: true` 的工具结果

| 属性 | 值 |
|------|-----|
| **严重程度** | 🟡 建议修复 |
| **影响** | 错误结果包含对 LLM 理解失败原因至关重要的信息，压缩后 LLM 无法理解 |

**问题**：§6c 的 `microcompact()` 对所有 `Message::ToolResult` 无条件压缩，包括 `is_error: true` 的结果。

**修复方案**：只压缩 `is_error: false` 的结果：

```rust
// microcompact 压缩阶段
for msg in &messages[..prune_start] {
    if matches!(msg, Message::ToolResult { is_error: false, .. }) {
        freed_tokens += estimate_single_message_tokens(msg);
    }
}

// 替换内容
for msg in &mut messages[..prune_start] {
    if let Message::ToolResult { content, is_error: false } = msg {
        *content = vec![ContentBlock::Text { text: "[pruned]".to_string() }];
    }
}
```

**建议归属**：Phase 2，Task 6 实施时一并处理

---

#### FIX-G：`submit_with_tools()` 中 `extract_tool_calls_from_response` 的 `input` 类型修正

| 属性 | 值 |
|------|-----|
| **严重程度** | 🟡 编译类型安全（`serde_json::to_string` 在 `&Value` 上调用） |
| **影响** | 编译通过，但 serde_json::to_string(&input) 在 `&Value` 上调用可能产生意外格式 |

**问题**：§4a 第 231-233 行 `extract_tool_calls_from_response` 中的 `input` 是 `&Value`（来自 `ContentBlock::ToolUse { input, .. }`），调用 `serde_json::to_string(input)` 可能序列化为多余的引号包裹格式。

**修复方案**：使用 `serde_json::to_string(input).unwrap_or_default()` 没问题（`Value` 实现了 `Serialize`），但建议改为 `input.to_string()`（Value 的 Display 实现生成紧凑 JSON）：

```rust
let args = input.to_string(); // 或 serde_json::to_string(input).unwrap_or_default()
```

**建议归属**：Phase 2，Task 4 实施时处理

---

#### FIX-H：测试基础设施迁移清单

| 属性 | 值 |
|------|-----|
| **严重程度** | 🟡 必须覆盖（否则测试无法编译） |
| **影响** | 测试代码使用旧类型，Phase 2 实施后编译失败 |

**需迁移的测试辅助代码**（按文件列出）：

| 文件 | 行号 | 实体 | 当前类型 | 目标类型 |
|------|------|------|---------|---------|
| `src/llm/cycle.rs` | 700-725 | `MockProvider` | `ChatRequest`/`ChatResponse` | `MessageRequest`/`MessageResponse` |
| `src/llm/cycle.rs` | 731-737 | `assistant_text_response()` | 返回 `ChatResponse` | 返回 `MessageResponse` |
| `src/llm/cycle.rs` | 739-765 | `assistant_tool_call_response()` | `OpenaiToolCall` 构造 | `ContentBlock::ToolUse` 构造 |
| `src/agent/session.rs` | 202-224 | `MockProvider` | `ChatRequest`/`ChatResponse` | `MessageRequest`/`MessageResponse` |
| `src/agent/session.rs` | 241-247 | `assistant_text()` | 返回 `ChatResponse` | 返回 `MessageResponse` |
| `src/agent/session.rs` | 141-143 | `with_system_prompt()` 调用点 | `OpenaiChatMessage` | `Message::system_text()` |
| `src/agent/builder.rs` | 126-132 | `StubProvider` | `ChatRequest`/`ChatResponse` | `MessageRequest`/`MessageResponse` |
| `src/tools/registry.rs` | 28 | `ToolInvocation::new()` | 3 参数 | 4 参数（含 `tool_call_id`） |

**建议归属**：Phase 2 尾部，作为一个单独的"测试适配 PR"集中修改（不在各 Task 中随改），避免业务代码和测试代码混杂。Phase 2 业务代码合入后，紧接着提交测试适配 PR。

---

### 🔄 实施顺序调整

原方案的线性顺序（1→2→3→4→5→6→7→8→9）考虑了依赖关系，但存在优化空间。结合交叉修复后，推荐以下实施顺序：

```
[Phase 0] 类型层（含交叉修复）
  FIX-B  Message + ContentBlock serde 派生 + 构造方法      ← 类型定义时添加
  FIX-C  ContentBlock 变体列表明确                          ← 设计决策

[Phase 2.0] 基础设施切换
  Task 1    LlmCycle 消息切换 (Vec<OpenaiChatMessage> → Vec<Message>)
          含 FIX-D  system_prompt 一步到位移除（与消息类型切换同时做）
  Task 7    ConversationMemory 切换                        ← 可并行，依赖 FIX-B

[Phase 2.1] 核心逻辑简化
  Task 5    submit/submit_messages/submit_request           ← 依赖 Phase 2.0，最简单先做
  Task 2    build_request 简化                              ← 依赖 Phase 2.0（system_prompt 已在 Phase 2.0 移除）

[Phase 2.2] 流处理 + 工具循环
  Task 3    submit_stream 简化                              ← 简化方案（非 mpsc），含 FIX-E
  Task 4    工具循环清洗 + FIX-A（tool_call_id）             ← 统一改 registry + cycle

[Phase 2.3] 附属适配 + 清理
  Task 6    compact.rs 适配                                ← 可并行，含 FIX-F
  Task 9    prompt/composer.rs 适配
  Task 8    清理临时转换函数（含 has_tool_calls_in_message）

[Phase 2.4] 收尾
  FIX-H     测试基础设施迁移                                 ← 单独 PR 集中处理
  (可选) FIX-G  代码风格优化
```

---

| 操作 | 文件 | 说明 |
|------|------|------|
| 修改 | `src/llm/cycle.rs` | 主要修改：消息类型切换 + 逻辑简化 |
| 修改 | `src/llm/compact.rs` | 适配 `Message` 类型（`microcompact` / `should_compact` / 估算函数） |
| 修改 | `src/memory/conversation.rs` | 消息类型从 `OpenaiChatMessage` 切换为 `Message` |
| 修改 | `src/prompt/composer.rs` | `validate_messages()` 适配 `Message` 类型 |
| 清理 | 各处 | 删除 Phase 0 引入的临时转换函数 |

**不涉及**：
- `src/llm/cycle/usage.rs` — `Usage` 类型不变
- `src/llm/cycle/retry.rs` — `RetryConfig` 和 `should_retry` 不引用消息类型
- `src/llm/error.rs` — `LlmError` 不引用消息类型

---

## Phase 2 对外影响（breaking changes 汇总）

以下变更影响所有使用 `LlmCycle` 的上游代码。Phase 2 实施前需确认调用方已适配。

| 变更 | 旧方式 | 新方式 | 影响文件 |
|------|--------|--------|---------|
| `messages()` 返回类型 | `&[OpenaiChatMessage]` | `&[Message]` | 所有读取消息历史的上游代码 |
| `with_messages()` / `extend_messages()` 参数 | `Vec<OpenaiChatMessage>` | `Vec<Message>` | 使用 builder 模式的代码 |
| `with_system_prompt()` | 设置纯文本，`build_request()` 隐式插入 | **已废弃**（`#[deprecated]`），调用方使用 `Message::system_text()` + `with_messages()` | `src/agent/session.rs:141-143` |
| `submit()` 返回类型 | `Result<ChatResponse, LlmError>` | `Result<MessageResponse, LlmError>` | 所有调用 `submit()` 的代码 |
| `submit_with_tools()` 返回类型 | `Result<ChatResponse, LlmError>` | `Result<MessageResponse, LlmError>` | `AgentSession` |
| `submit_messages()` 签名 | `Vec<OpenaiChatMessage>` 参数 | `Vec<Message>` 参数 | 直接调用方 |
| `submit_stream()` 调用方式 | 流内回传 `StreamEvent`（旧），`submit_stream` 负责 `self.messages.push` | `StreamEvent`（新）透传，调用方需在 `MessageComplete` 后手动调用 `cycle.push_message()` | 调用流式 API 的代码 |
| `compact` 模块接收 | `&[OpenaiChatMessage]` 参数 | `&[Message]` 参数 | 仅在 `LlmCycle` 和 `ConversationMemory` 内部调用，对外无影响 |

**迁移建议**：所有上游变更集中在 `src/agent/session.rs` 和测试代码中。建议 Phase 2.0 实施前先在 `session.rs` 中完成消息类型对齐，然后随 Phase 2 各阶段逐步适配。

---

## 任务 1：LlmCycle 内部消息切换

### 1a：结构体字段变更

```rust
pub struct LlmCycle {
    provider: Arc<dyn LlmProvider>,
    config: CycleConfig,
    usage: CostTracker,
    // 从 Vec<OpenaiChatMessage> 改为 Vec<Message>
    messages: Vec<Message>,
    // system_prompt 字段已移除（审查 FIX-D）：
    // 调用方通过 Message::system_text() + with_messages() 管理系统提示
    // 向后兼容：with_system_prompt() 标记为 #[deprecated]，内部转为 Message::System 后插入
    hook_executor: Option<Arc<HookExecutor>>,
    compact_config: Option<CompactConfig>,
    compact_state: CompactState,
}
```

### 1b：`messages()` 方法签名变更

```rust
// 当前
pub fn messages(&self) -> &[OpenaiChatMessage] { &self.messages }
// 目标
pub fn messages(&self) -> &[Message] { &self.messages }
```

### 1c：`with_messages()` 方法签名变更

```rust
// 当前
pub fn with_messages(mut self, messages: Vec<OpenaiChatMessage>) -> Self
// 目标
pub fn with_messages(mut self, messages: Vec<Message>) -> Self
```

### 1d：`extend_messages()` 方法签名变更

```rust
// 当前
pub fn extend_messages(&mut self, messages: Vec<OpenaiChatMessage>)
// 目标
pub fn extend_messages(&mut self, messages: Vec<Message>)
```

### 1e：新增 `push_message()` 公共方法

供 `submit_stream()` 消费方在收到 `MessageComplete` 事件后手动追加消息：

```rust
/// 追加单条消息到历史尾部（供 submit_stream 消费方使用）。
pub fn push_message(&mut self, msg: Message) {
    self.messages.push(msg);
}
```

---

## 任务 2：简化 `build_request()`

### 2a：移除转换步骤 + 移除 system_prompt 逻辑（审查 FIX-D）

Phase 0 中的 `build_request()` 需要调用 `chat_message_to_message` 将 `self.messages`（`Vec<OpenaiChatMessage>`）转为 `Vec<Message>`。Phase 2 中 `self.messages` 本身就是 `Vec<Message>`，所以这个转换步骤被移除。

同时，`system_prompt` 字段已移除（审查 FIX-D），调用方通过 `Message::system_text()` + `with_messages()` 自主管理系统提示消息。

```rust
fn build_request(&self, tools: &[ToolDefinition]) -> MessageRequest {
    // 直接使用 self.messages，不做任何 System 消息隐式插入
    let messages = self.messages.clone();

    MessageRequest {
        model: self.config.model.clone(),
        messages,
        tools: tools.to_vec(),
        tool_choice: ToolChoice::Auto,
        max_tokens: self.config.max_tokens,
        temperature: self.config.temperature,
        top_p: None,
        stop_sequences: vec![],
        stream: false,
        thinking: None,
        extra: HashMap::new(),
    }
}
```

> **注意**：`tools` 的类型从 `Option<Vec<OpenaiTool>>`（OpenAI 特定包装）变为 `Vec<ToolDefinition>`（`MessageRequest` 中使用的新类型）。Provider 映射层负责将 `ToolDefinition` 转换为协议特定的工具定义格式。`build_request()` 不再需要 `OpenaiTool::Function` 包装。

### 2b：`with_system_prompt()` 弃用过渡

```rust
#[deprecated(since = "0.x.0", note = "请改用 Message::system_text() + with_messages()")]
pub fn with_system_prompt(mut self, prompt: String) -> Self {
    self.messages.insert(0, Message::system_text(prompt));
    self
}
```

此方法保留一个过渡周期（标注 `#[deprecated]`），编译器发出弃用警告但不阻止编译。后续版本中移除。

### 2c：`with_messages()` 中忽略 system_prompt 冲突

`with_messages()` 不再做去重检查或 System 消息过滤——调用方传入什么就是什么。`build_request()` 直接使用 `self.messages`，不插入任何额外消息。

---

## 任务 3：简化 `submit_stream()`

### 3a：流处理循环变更（审查 FIX-E — 简化方案）

Phase 0 中，`submit_stream()` 从 `provider.chat_stream()` 直接获得 `Result<StreamEvent>` 流。但为了在流结束后仍能向 `self.messages`（`Vec<OpenaiChatMessage>`）追加响应，需要通过 `message_to_chat_message` 转换。

Phase 2 中，`self.messages` 已经是 `Vec<Message>`，所以不需要转换了。

> ⚠️ **审查结论**：mpsc 通道方案因 Rust 的 Pin/借用限制不可行（`&mut self` 无法进入闭包，流是延迟求值的），采用**简化方案**——`submit_stream` 内部不管理消息历史，由调用方在流结束后自行调用 `push_message()`。
>
> 详情见"审查发现与交叉阶段修复计划"中 FIX-E 的分析。

```rust
pub async fn submit_stream(
    &mut self,
    prompt: String,
    tools: Vec<ToolDefinition>,
) -> Result<Pin<Box<dyn Stream<Item = StreamEvent> + Send>>, LlmError> {
    self.messages.push(Message::user_text(prompt));
    self.maybe_compact();

    let request = self.build_request(&tools);

    // PreRequest hook
    if let Some(ref executor) = self.hook_executor {
        let ctx = HookContext::new(HookEvent::PreRequest).with_request(&request);
        let results = executor.execute(HookEvent::PreRequest, &ctx).await;
        if results.iter().any(|r| r.should_block) {
            return Err(LlmError::Other("Blocked by pre-request hook".to_string()));
        }
    }

    let event_stream = self.provider.chat_stream(request).await?;
    let hook_executor = self.hook_executor.clone();

    Ok(Box::pin(stream! {
        use futures_util::StreamExt;
        let mut event_stream = event_stream;

        while let Some(result) = event_stream.next().await {
            match result {
                Ok(event) => {
                    yield event;
                }
                Err(e) => {
                    if let Some(ref executor) = hook_executor {
                        let ctx = HookContext::new(HookEvent::OnError).with_error(&e);
                        executor.execute(HookEvent::OnError, &ctx).await;
                    }
                    yield StreamEvent::Error { message: e.to_string() };
                    break;
                }
            }
        }

        // PostRequest hook：注意此处的消息列表不包含本次 Assistant 响应
        if let Some(ref executor) = hook_executor {
            let ctx = HookContext::new(HookEvent::PostRequest);
            executor.execute(HookEvent::PostRequest, &ctx).await;
        }
    }))
}
```

**调用方使用模式**：

```rust
let mut stream = cycle.submit_stream(prompt, tools).await?;
let mut final_response: Option<MessageResponse> = None;

while let Some(event) = stream.next().await {
    match &event {
        StreamEvent::MessageComplete { full_response } => {
            final_response = Some(full_response.clone());
        }
        // 其他事件（TextDelta, ContentBlockStart 等）透传给 UI/消费方
        _ => {}
    }
}

// 流结束后更新消息历史
if let Some(resp) = final_response {
    cycle.push_message(resp.message.clone());
    // usage 更新：cycle.usage() 返回 &CostTracker，调用方自行 add
}
```

**变更**：
- `yield` 直接产生 `StreamEvent`（签名 `Item = StreamEvent`），不再包裹 `Ok()`
- `self.messages.push(response.message)` 由调用方在流结束后通过 `push_message()` 完成
- `self.usage.add(&response.usage)` 由调用方通过 `cycle.usage().add()` 完成
- 无需 `message_to_chat_message` 转换

### 3b：设计决策记录

**决策**：采用简化方案（已验证 mpsc 方案因 Rust 语言限制不可行）。

**已知限制**（调用方需知晓）：
- post_request hook 收到的消息列表中**不包含本次响应**——如需完整消息列表，调用方应在流结束后手动触发 Hook

**判断标准**（如后续需切换方案）：
- 如果未来有需求要求 `submit_stream` 在流结束后自动推消息到 `self.messages`，可考虑将 `self.messages` 包裹为 `Arc<Mutex<Vec<Message>>>` 并在流闭包内安全修改——但这是 API 层面的 breaking change

---

## 任务 4：清洗工具循环

### 4a：`submit_with_tools()` 中的 tool 循环

当前 `submit_with_tools()` 使用 Phase 0 的临时逻辑：
- `response.message` 是 `Message` 类型（新枚举）
- 使用 `has_tool_calls_in_response` 和 `extract_tool_calls_from_response` 解析 tool calls
- 使用 `OpenaiChatMessage::tool_result()` 推送 tool 结果到 `self.messages`

Phase 2 中：
- `self.messages.push(response.message.clone())` —— 直接推送 `Message`（不需要转换）
- tool 结果回传：`self.messages.push(Message::tool_result(id, content, is_error))`
- 从 `response.message` 提取 tool calls：遍历 `content` 中的 `ContentBlock::ToolUse`

```rust
fn has_tool_calls_in_response(response: &MessageResponse) -> bool {
    match &response.message {
        Message::Assistant { content } => {
            content.iter().any(|b| matches!(b, ContentBlock::ToolUse { .. }))
        }
        _ => false,
    }
}

fn extract_tool_calls_from_response(response: &MessageResponse) -> Vec<(String, String, String)> {
    match &response.message {
        Message::Assistant { content } => {
            content.iter().filter_map(|b| {
                if let ContentBlock::ToolUse { id, name, input } = b {
                    // input 是 &Value，Display 实现生成紧凑 JSON
                    let args = input.to_string();
                    Some((id.clone(), name.clone(), args))
                } else {
                    None
                }
            }).collect()
        }
        _ => vec![],
    }
}
```

### 4b：工具结果回传（依赖 FIX-A）

> ⚠️ **前置依赖**：`ToolInvocation` 必须在 Phase 0/1 期间增加 `tool_call_id` 字段（见 FIX-A），否则以下代码无法编译。

```rust
for result in results {
    let is_error = result.output.is_err();
    let content = match result.output {
        Ok(ref value) => {
            let serialized = serde_json::to_string(value).unwrap_or_default();
            truncate_tool_result(&serialized, max_bytes)
        }
        Err(ref e) if e.is_recoverable() => format!("错误: {}", e),
        Err(ref e) => return Err(LlmError::Other(format!("工具不可恢复错误: {}", e))),
    };
    self.messages.push(Message::tool_result(
        result.tool_call_id.clone(),   // ← 来自 FIX-A 新增字段
        content,
        is_error,
    ));
}
```

**数据流**（FIX-A 修复后）：
1. `extract_tool_calls_from_response()` 返回 `Vec<(String, String, String)>`（id, name, args）
2. `invoke_all()` 接收 `Vec<(String, String, Value)>`（id, name, args）
3. `ToolInvocation.tool_call_id` 保存原始 id
4. 回传时使用 `result.tool_call_id` 关联原始调用

---

## 任务 5：简化 `submit()` / `submit_messages()` / `submit_request()`

### 5a：`submit()`

```rust
pub async fn submit(
    &mut self,
    prompt: String,
    tools: Vec<ToolDefinition>,
) -> Result<MessageResponse, LlmError> {
    self.messages.push(Message::user_text(prompt));
    self.maybe_compact();

    let mut attempts = 0;
    loop {
        let request = self.build_request(&tools);
        // ... hook 处理 ...
        match self.provider.chat(request).await {
            Ok(response) => {
                // ... hook 处理 ...
                self.messages.push(response.message.clone());
                self.usage.add(&response.usage);
                return Ok(response);
            }
            Err(e) => { /* 重试逻辑 */ }
        }
    }
}
```

**变更**：
- `self.messages.push(OpenaiChatMessage::user_text(prompt))` → `self.messages.push(Message::user_text(prompt))`
- `self.messages.push(response.message.clone())` — `response.message` 已经是 `Message` 类型
- 无需 `message_to_chat_message` 转换

### 5b：`submit_messages()`

```rust
pub async fn submit_messages(
    &mut self,
    messages: Vec<Message>,
    tools: Vec<ToolDefinition>,
) -> Result<MessageResponse, LlmError> {
    let request = MessageRequest {
        model: self.config.model.clone(),
        messages,
        tools: tools.to_vec(),
        tool_choice: ToolChoice::Auto,
        max_tokens: self.config.max_tokens,
        temperature: self.config.temperature,
        ..Default::default()
    };
    // ... hook + provider.chat(request) ...
    match self.provider.chat(request).await {
        Ok(response) => {
            self.usage.add(&response.usage);
            Ok(response)
        }
        Err(e) => Err(e),
    }
}
```

### 5c：`submit_request()`

```rust
async fn submit_request(
    &mut self,
    tools: &[ToolDefinition],
) -> Result<MessageResponse, LlmError> {
    // 逻辑与之前一致，但返回类型改为 MessageResponse
    // ...
}
```

---

## 任务 6：适配 `compact.rs`

### 6a：`estimate_single_message_tokens()`

```rust
fn estimate_single_message_tokens(msg: &Message) -> u32 {
    let role_overhead: u32 = 4;
    let content_tokens = match msg {
        Message::System { content }
        | Message::User { content }
        | Message::Assistant { content } => estimate_content_blocks_tokens(content),
        Message::UserImage { .. } => {
            // UserImage 固定估算
            50
        }
        Message::ToolResult { content, .. } => estimate_content_blocks_tokens(content),
    };
    role_overhead + content_tokens
}
```

**变更**：当前使用 `ContentField`（旧类型，区分 String 和 Array），新类型统一为 `&[ContentBlock]`。

### 6b：`estimate_content_blocks_tokens()`

```rust
fn estimate_content_blocks_tokens(blocks: &[ContentBlock]) -> u32 {
    blocks.iter().map(estimate_block_tokens).sum()
}

fn estimate_block_tokens(block: &ContentBlock) -> u32 {
    match block {
        ContentBlock::Text { text } => estimate_text_tokens(text),
        ContentBlock::ToolResult { content, .. } => estimate_content_blocks_tokens(content),
        ContentBlock::Thinking { text, .. } => estimate_text_tokens(text),
        ContentBlock::ToolUse { input, .. } => {
            // tool_use 的 input 是 JSON Value
            estimate_text_tokens(&serde_json::to_string(input).unwrap_or_default())
        }
        _ => 50, // Image/Audio/File/Extension 固定估算
    }
}
```

### 6c：`microcompact()`（审查 FIX-F）

> ⚠️ **FIX-F**：只压缩 `is_error: false` 的 ToolResult。错误结果包含失败原因，压缩后 LLM 无法理解。

```rust
pub fn microcompact(messages: &mut [Message], keep_recent: usize) -> u32 {
    if messages.len() <= keep_recent {
        return 0;
    }
    let prune_start = messages.len() - keep_recent;
    let mut freed_tokens: u32 = 0;

    // 第一遍：计算可释放的 token（仅非错误结果）
    for msg in &messages[..prune_start] {
        if matches!(msg, Message::ToolResult { is_error: false, .. }) {
            freed_tokens += estimate_single_message_tokens(msg);
        }
    }

    // 第二遍：替换内容（仅非错误结果）
    for msg in &mut messages[..prune_start] {
        if let Message::ToolResult { content, is_error: false } = msg {
            *content = vec![ContentBlock::Text { text: "[pruned]".to_string() }];
        }
    }

    freed_tokens
}
```

**变更**：
- `OpenaiChatMessage::Tool` → `Message::ToolResult`
- `ContentField::Array(vec![OpenaiContentPart::Text { text: "[pruned]" }])` → `vec![ContentBlock::Text { text: "[pruned]".to_string() }]`
- 新增条件：`is_error: false` 时才压缩（保留错误诊断信息）

### 6d：`should_compact()`

```rust
pub fn should_compact(
    messages: &[Message],
    config: &CompactConfig,
    state: &CompactState,
) -> bool {
    // 逻辑不变，只是消息类型改为 &[Message]
    if state.consecutive_failures >= MAX_CONSECUTIVE_FAILURES {
        return false;
    }
    let tokens = estimate_message_tokens(messages);
    tokens >= config.threshold()
}
```

---

## 任务 7：同步适配 `ConversationMemory`

`src/memory/conversation.rs` 的消息类型从 `OpenaiChatMessage` 切换为 `Message`：

### 7a：结构体字段

```rust
pub struct ConversationMemory {
    store: Arc<dyn MemoryStore>,
    session_id: String,
    config: ConversationMemoryConfig,
    messages: Vec<Message>,           // 从 OpenaiChatMessage 改为 Message
    message_ids: Vec<String>,
    compact_state: CompactState,
}
```

### 7b：序列化/反序列化

```rust
// 当前
serde_json::from_str::<OpenaiChatMessage>(&item.content)

// 目标
serde_json::from_str::<Message>(&item.content)
```

**注意**：`Message` 枚举需要实现 `Serialize` / `Deserialize`。

> ✅ **已在 Phase 0 处理**（审查 FIX-B）：Phase 0 定义 `Message` 和 `ContentBlock` 类型时直接添加 `#[derive(Serialize, Deserialize)]` 和 `#[serde(tag = "type", rename_all = "snake_case")]`。Phase 2 直接使用即可。

序列化格式示例（仅用于内部存储，不与 Provider 协议交互）：

```json
{"type": "user", "content": [{"type": "text", "text": "hello"}]}
{"type": "user_image", "data": "...", "mime_type": "image/png", "detail": "auto"}
{"type": "assistant", "content": [{"type": "text", "text": "Hi!"}, {"type": "tool_use", "id": "call_1", "name": "get_weather", "input": {"city": "Beijing"}}]}
{"type": "tool_result", "tool_call_id": "call_1", "content": [{"type": "text", "text": "Sunny, 25°C"}], "is_error": false}
```

### 7c：消息 ID 前缀兼容

```rust
fn session_prefix(&self) -> String {
    format!("conv:{}:", self.session_id) // 格式不变
}
```

序列化格式变化后，旧消息无法反序列化为新类型。由于项目尚未 release，可以接受这个不兼容。

---

## 任务 8：清理临时转换函数

删除 Phase 0 引入的以下函数（确认不再被引用后删除）：

1. **`chat_message_to_message()`** — 在 `build_request()` 中已不再需要（`self.messages` 已是 `Vec<Message>`）
2. **`message_to_chat_message()`** — 在 `submit_stream()` 中已不再需要（流结束后直接使用 `full_response.message`）
3. **`content_to_blocks()`** — 如果只在上述两个函数中使用，一并删除
4. **`blocks_to_content_field()`** — 同上
5. **`has_tool_calls_in_message()`** — `cycle.rs:645`，基于 `OpenaiChatMessage::Assistant { tool_calls }` 判断。Phase 2 中由 `has_tool_calls_in_response()`（基于 `ContentBlock::ToolUse`）替代
6. **`extract_tool_calls_from_message()`** — `cycle.rs:658`，基于 `OpenaiToolCall` 提取。Phase 2 中由 `extract_tool_calls_from_response()`（基于 `ContentBlock::ToolUse`）替代

**验证方法**：
- 全局搜索函数名（`git grep`），确认在所有文件中的引用计数归零
- `cargo build` 通过（编译器对非 pub 的未使用函数报 warning，pub 函数不报 warning。用 `git grep` 做精准确认）
- `cargo clippy` 无 `dead_code` 级别警告

---

## 任务 9：适配 `prompt/composer.rs`（如需要）

`validate_messages()` 当前检查 `OpenaiChatMessage` 序列中的 role 顺序规则。如果该函数被 `AgentSession` 或 `LlmCycle` 调用，需要适配新 `Message` 类型。

检查步骤：
1. 搜索 `validate_messages` 的调用者
2. 如果被上游调用且上游已切换为 `Vec<Message>`，则适配
3. 适配内容：match 分支从 `OpenaiChatMessage::Tool { .. }` 改为 `Message::ToolResult { .. }`，从 `OpenaiChatMessage::Assistant { tool_calls: Some(..) }` 改为检查 `ContentBlock::ToolUse`

---

## 验证方式

1. **编译检查**：`cargo build` 通过
2. **单元测试**：`cargo test` 全部通过
3. **集成测试**：
   - 多轮对话（`submit` + `submit_with_tools`）端到端正常
   - 工具调用循环正常（含 `tool_call_id` 正确关联）
   - 流式响应（`submit_stream`）正常
   - 上下文压缩（`compact`）超过 token 阈值后正确压缩
   - **错误路径**：`provider.chat()` 返回错误时，消息历史不被污染（`self.messages.push` 在确认成功后才执行）
   - **序列化 roundtrip**：`Message` → JSON → `Message` 保持所有字段（含 `UserImage`、`ToolResult.is_error`）
   - **边界情况**：`submit_with_tools` 收到空 content 的 `ContentBlock`、包含 `UserImage` 的消息
   - **hook 集成**：PreRequest hook 正确收到 `MessageRequest`（而非旧的 `ChatRequest`）
4. **clippy 检查**：`cargo clippy` 无新增警告
5. **diff 确认**：`git diff` 确认 Phase 0 引入的临时转换函数已被删除

## 回滚方案

⚠️ **审查评估**：feature flag 方案在两套 StreamEvent 类型共存时工程量大，实际安全网依赖 checkpoint 打 tag。

| 回退对象 | 可行策略 | 复杂度 | 说明 |
|---------|---------|-------|------|
| `submit_stream()` | feature flag `legacy_stream` | 🔴 高 | 需要同时保留旧 `StreamEvent` 类型和旧 `chat_stream` Provider 调用路径。除非新旧 StreamEvent 完全兼容，否则工程量大。**不推荐** |
| `compact.rs` | 模块同步回退 | 🟢 低 | `should_compact`/`microcompact` 只在 `LlmCycle` 和 `ConversationMemory` 中调用，签名变化后可整体回退 |
| 全局 | git checkout + 重做 | 🟢 极低 | 项目尚未 release，无外部消费者。每个子阶段完成后打 tag（`phase2-taskX-checkpoint`），允许跳跃回退 |

**推荐回退策略**：不在代码层面做 feature flag，而是：
1. 每个子阶段（Phase 2.0/2.1/2.2/2.3）完成后创建 git tag
2. 如果某一子阶段出现问题，`git revert` 该子阶段的所有 commit
3. 修复后重新提交，不保留两套实现共存

## 开放事项

- [已解决] `Message` 的 `Serialize` / `Deserialize` 派生设计 → **移至 Phase 0**（FIX-B）
- [已解决] `system_prompt` 字段的最终去留 → **Phase 2 彻底移除**（FIX-D）
- `ConversationMemory` 序列化格式变更后的数据兼容性（项目未 release，可接受）
- `submit_with_tools_stream()` 未来设计：流式响应 + 自动工具循环的组合场景
- `ToolContext` 是否增加 `tool_call_id` 字段（FIX-A 方案二中可选）
- `ContentBlock::Extension` 逃生舱的具体使用场景
- Thinking signature 的端到端测试