# LlmProvider Trait 设计

> 本文档从 `9-llm-provider-unified-interface.md` 拆分而来，包含 §4 LlmProvider Trait 设计。
>
> **相关文件：**
> - [9b-ir-type-system.md](9b-ir-type-system.md) — IR 类型定义（MessageRequest、MessageResponse、StreamEvent 等）
> - [9d-provider-implementations.md](9d-provider-implementations.md) — 各 Provider 的具体实现策略
> - [9f-edge-cases.md](9f-edge-cases.md) — Thinking signature 等边界情况（与 StreamEvent 设计关联）

## 4. LlmProvider Trait 设计

### 4.1 核心接口

```rust
#[async_trait]
pub trait LlmProvider: Send + Sync {
    /// 发送消息请求，获取完整响应。
    async fn chat(&self, request: MessageRequest) -> Result<MessageResponse, LlmError>;

    /// 流式消息请求，返回语义化事件流。
    async fn chat_stream(
        &self,
        request: MessageRequest,
    ) -> Result<
        Pin<Box<dyn Stream<Item = Result<StreamEvent, LlmError>> + Send>>,
        LlmError,
    >;

    /// 返回 Provider 的能力描述。
    fn capabilities(&self) -> ProviderCapabilities;
}
```

### 4.2 ProviderCapabilities

```rust
#[derive(Debug, Clone)]
pub struct ProviderCapabilities {
    /// Provider 标识名称
    pub provider_name: &'static str,
    /// 支持的模型列表（None = 不限制）
    pub supported_models: Option<Vec<String>>,
    /// 特性标记
    pub features: ProviderFeatures,
}

#[derive(Debug, Clone, Default)]
pub struct ProviderFeatures {
    pub streaming: bool,
    pub thinking: bool,
    pub vision: bool,
    pub audio_input: bool,
    pub tool_use: bool,
    pub parallel_tool_calls: bool,
    /// true=OpenAI风格(system in messages), false=Anthropic风格(system as param)
    pub system_prompt_in_messages: bool,
    pub max_context_window: u32,
}
```

#### capabilities() 的使用场景

1. **LlmCycle**：根据 `features.thinking` 决定是否启用 thinking 模式
2. **AgentBuilder**：在构建时校验模型是否支持所需特性
3. **UI/CLI**：展示 Provider 的能力矩阵
4. **智能路由**：根据能力自动选择最佳 Provider

### 4.3 流式事件 StreamEvent

```rust
/// 流式事件 —— 流式响应的语义化增量构建过程。
/// 一组 StreamEvent 最终可汇聚为一个完整的 MessageResponse。
#[derive(Debug, Clone)]
pub enum StreamEvent {
    // ── Meta ──
    /// 消息开始
    MessageStart { id: String, model: String },

    // ── Content Block 边界 ──
    /// Content block 开始（index = 全局 content block 序号）
    ContentBlockStart { index: u32, block_type: ContentBlockType },
    /// Content block 结束
    ContentBlockEnd { index: u32 },

    // ── 块内增量（无 index，隐含属于当前活跃 block）──
    /// 文本增量
    TextDelta { text: String },
    /// 思考增量（Anthropic thinking block）
    ThinkingDelta { text: String },
    /// 拒绝增量（OpenAI refusal，汇聚为 ContentBlock::Text）
    RefusalDelta { text: String },

    // ── Tool Call 参数（index = block index）──
    /// 工具参数增量
    ToolCallArgumentsDelta { index: u32, arguments: String },
    /// 工具参数结束，可尝试解析 JSON
    ToolCallEnd { index: u32 },

    // ── 汇总 ──
    /// Token 用量（字段级合并，见 PartialUsage）
    CostUpdate { usage: PartialUsage },
    /// 消息完成（thinking_signature 仅 Anthropic 场景，回填到最后的 Thinking block）
    MessageComplete { stop_reason: StopReason, thinking_signature: Option<String> },

    // ── 错误 ──
    Error { message: String },
}

/// ContentBlock 的类型标识，嵌入在 ContentBlockStart 事件中。
#[derive(Debug, Clone)]
pub enum ContentBlockType {
    Text,
    Thinking,
    Refusal,
    ToolUse { id: String, name: String },
}

/// CostUpdate 中携带的用量数据——只含本次更新中真正下发的字段。
///
/// 汇聚算法做字段级合并（覆盖各字段的 Some 值），而非全量覆盖。
/// 解决 Provider 分多次下发 Usage 的问题：
/// - OpenAI: 一次全量下发（所有字段都有值）
/// - Anthropic: message_start 时下发 input_tokens，message_delta 时下发 output_tokens
#[derive(Debug, Clone, Default)]
pub struct PartialUsage {
    pub prompt_tokens: Option<u32>,
    pub completion_tokens: Option<u32>,
    pub total_tokens: Option<u32>,
    pub completion_tokens_details: Option<CompletionTokensDetails>,
    pub prompt_tokens_details: Option<PromptTokensDetails>,
}
```

#### 设计决策：为什么移除 ToolCallStart

`ToolCallStart { index, id, name }` 的语义本质是一个 ContentBlock 的开始（类型为 ToolUse），
没有单独存在的必要。合并到 `ContentBlockStart.block_type = ToolUse { id, name }` 后：
- **index 语义统一**：ContentBlockStart.index 是全文档唯一的 content block 序号
- **事件减少**：每次 tool_use block 开始少发一个事件，Anthropic 映射更自然（`content_block_start` → `ContentBlockStart`）
- **#4议题自动解决**：index 在 IR 层面始终为全局序号，OpenAI Provider 内部的局部→全局映射完全封装在 Provider 层，
  不在 IR 中暴露差异

#### 设计决策：为什么 TextDelta 不带 index

- 单 SSE 连接内 TCP 保证字节序，TextDelta 必然属于最后一个 ContentBlockStart 开始的 block
- 不携带 index 可减少事件体积
- 如果未来 LlmCycle 需要跨 Provider 合并流，可向后兼容地添加 index 字段（降级策略：无 index 时默认归属当前活跃 block）

#### 设计决策：CostUpdate 使用 PartialUsage 做字段级合并

覆盖策略（取最新值）在 Anthropic 场景下出错——Anthropic 分两次下发：
```
CostUpdate #1: { prompt_tokens: Some(100), completion_tokens: None,   total_tokens: Some(100) }
CostUpdate #2: { prompt_tokens: None,   completion_tokens: Some(50),  total_tokens: Some(150) }
```
如果直接 `Usage` 全量覆盖，第一次的 prompt_tokens 会被第二次的 `None` 清零。
改为 `PartialUsage`（字段级 `Option`）后，汇聚算法只更新 `Some` 的字段，避免清零。

#### 与当前 StreamEvent 的对比

| 当前 StreamEvent | 新 StreamEvent | 理由 |
|-----------------|---------------|------|
| `AssistantTextDelta { text }` | `TextDelta { text }` | 简洁化 |
| — | `ThinkingDelta { text }` | Anthropic 需要 |
| — | `RefusalDelta { text }` | OpenAI 需要 |
| `ToolExecutionStarted { tool_name, input, tool_call_id }` | `ContentBlockStart { index, ToolUse { id, name } }` + `ToolCallArgumentsDelta { index, arguments }` | 拆分为 block 边界 + 参数增量 |
| `ToolExecutionCompleted` | **移除** | LlmCycle 层事件，非 Provider 层 |
| — | `ContentBlockStart` / `ContentBlockEnd` | 显式 block 边界标记 |
| — | `BlockContentType` | ContentBlock 类型标识 |
| `CostUpdate { usage: Usage }` | `CostUpdate { usage: PartialUsage }` | 字段级合并，兼容多 Provider |
| `TurnComplete { reason }` | `MessageComplete { stop_reason, thinking_signature: Option<String> }` | 语义更准确 + thinking 签名回填 |
| `Error { message }` | 保留 | ✅ |
| — | `MessageStart { id, model }` | Anthropic 需要 |
| — | `ToolCallEnd { index }` | 明确参数完整时间点 |
| `ToolCallStart { index, id, name }` | **移除** | 合并到 ContentBlockStart.ToolUse |

---

### 4.4 PartialMessageResponse —— 流式事件的汇聚算法

> **✅ 推演结论（2026-06-17）：采用方案 B（显式边界）—— ContentBlockStart/End 声明 block 边界，BTreeMap 按 index 分桶组装**
>
> **核心思路：** 放弃"类型切换推断 block 边界"的隐含方案。为 StreamEvent 增加 `ContentBlockStart` 和 `ContentBlockEnd`
> 事件，使每个 block 的开始和结束都有精确的事件标记。汇聚算法由"线性累积 + 隐含 flush + 延迟排序"改为
> **"按 index 分桶 + 排序组装"**，彻底消除对事件到达顺序的依赖。
>
> **决策理由：**
> 1. 类型切换推断在 ToolCallEnd 后跟 TextDelta 的场景下导致顺序错乱（ToolUse 被延迟插入到 Text 之后）
> 2. 显式边界将位置信息绑定到 index，不依赖事件到达时序，容错性更强
> 3. Anthropic 的 `content_block_start/stop` 天然映射为 `ContentBlockStart/End`
> 4. OpenAI 的无边界流式由 Provider 内部分析 delta 类型来合成边界，封装在 Provider 层
> 5. #4（ToolCallStart index 归一化）自动解决——index 统一为全局 content block 序号

#### PartialMessageResponse 结构体

```rust
use std::collections::{BTreeMap, HashMap, HashSet};
use serde_json::Value;

/// 流式事件的累积状态 —— 按 index 分桶，逐个构建 ContentBlock。
#[derive(Debug, Default)]
pub struct PartialMessageResponse {
    // ── 来自 MessageStart ──
    pub id: Option<String>,
    pub model: Option<String>,

    /// 按 index 分桶的 ContentBlock 构建器（BTreeMap 保证升序遍历）
    pub blocks: BTreeMap<u32, ContentBlockBuilder>,

    /// Tool call 参数累积（按 block index 关联）
    pub tool_call_args: HashMap<u32, String>,

    /// 已收到 ContentBlockEnd 的 block index 集合
    pub block_completion: HashSet<u32>,

    /// 当前最后打开的 block index（供无 index 的 TextDelta 定位）
    pub last_open_index: Option<u32>,

    /// Token 用量（字段级合并后的最终值）
    pub usage: Usage,

    /// 结束状态
    pub stop_reason: Option<StopReason>,

    /// MessageComplete 携带的 thinking signature（留待 finalize 回填）
    pub thinking_signature: Option<String>,

    pub is_errored: bool,
    pub is_complete: bool,
}

/// 按 index 分桶的 ContentBlock 构建器。
#[derive(Debug)]
pub enum ContentBlockBuilder {
    Text(String),
    Thinking { buffer: String, signature: Option<String> },
    Refusal(String),
    ToolUse { id: String, name: String },
}
```

#### apply_to 算法

```rust
impl StreamEvent {
    /// 将当前事件应用到 PartialMessageResponse 上。
    /// 返回 true 表示正常处理，false 表示应停止处理后续事件。
    pub fn apply_to(&self, state: &mut PartialMessageResponse) -> bool {
        match self {
            // ──────────────── Meta ────────────────
            StreamEvent::MessageStart { id, model } => {
                state.id = Some(id.clone());
                state.model = Some(model.clone());
                true
            }

            // ──────────────── Block 边界 ────────────────
            StreamEvent::ContentBlockStart { index, block_type } => {
                let builder = match block_type {
                    ContentBlockType::Text => ContentBlockBuilder::Text(String::new()),
                    ContentBlockType::Thinking => ContentBlockBuilder::Thinking {
                        buffer: String::new(),
                        signature: None,
                    },
                    ContentBlockType::Refusal => ContentBlockBuilder::Refusal(String::new()),
                    ContentBlockType::ToolUse { id, name } =>
                        ContentBlockBuilder::ToolUse { id: id.clone(), name: name.clone() },
                };
                state.blocks.entry(*index).or_insert(builder);
                state.last_open_index = Some(*index);
                true
            }

            StreamEvent::ContentBlockEnd { index } => {
                state.block_completion.insert(*index);
                true
            }

            // ──────────────── 块内增量 ────────────────
            StreamEvent::TextDelta { text } => {
                // 定位到最后打开的 block
                if let Some(idx) = state.last_open_index {
                    if let Some(ContentBlockBuilder::Text(ref mut buf)) = state.blocks.get_mut(&idx) {
                        buf.push_str(text);
                    }
                } else {
                    tracing::warn!("TextDelta 到达时无活跃 block");
                }
                true
            }

            StreamEvent::ThinkingDelta { text } => {
                if let Some(idx) = state.last_open_index {
                    if let Some(ContentBlockBuilder::Thinking { ref mut buffer, .. }) =
                        state.blocks.get_mut(&idx)
                    {
                        buffer.push_str(text);
                    }
                } else {
                    tracing::warn!("ThinkingDelta 到达时无活跃 block");
                }
                true
            }

            StreamEvent::RefusalDelta { text } => {
                if let Some(idx) = state.last_open_index {
                    if let Some(ContentBlockBuilder::Refusal(ref mut buf)) =
                        state.blocks.get_mut(&idx)
                    {
                        buf.push_str(text);
                    }
                } else {
                    tracing::warn!("RefusalDelta 到达时无活跃 block");
                }
                true
            }

            // ──────────────── Tool Call 参数 ────────────────
            StreamEvent::ToolCallArgumentsDelta { index, arguments } => {
                state
                    .tool_call_args
                    .entry(*index)
                    .or_default()
                    .push_str(arguments);
                true
            }

            StreamEvent::ToolCallEnd { index } => {
                // ToolCallEnd 只做标记，参数在 finalize 时解析
                state.block_completion.insert(*index);
                true
            }

            // ──────────────── 汇总 ────────────────
            StreamEvent::CostUpdate { usage } => {
                Self::apply_cost_update(state, usage);
                true // 即使 is_complete 后 CostUpdate 仍然可以到达
            }

            StreamEvent::MessageComplete {
                stop_reason,
                thinking_signature,
            } => {
                state.stop_reason = Some(*stop_reason);
                state.thinking_signature = thinking_signature.clone();
                state.is_complete = true;
                true
            }

            // ──────────────── 错误 ────────────────
            StreamEvent::Error { message } => {
                state.is_errored = true;
                tracing::error!("流式处理中发生错误: {}", message);
                false // 终止处理
            }
        }
    }

    /// 字段级合并 CostUpdate（仅覆盖 Some 的字段）。
    fn apply_cost_update(state: &mut PartialMessageResponse, update: &PartialUsage) {
        if let Some(v) = update.prompt_tokens {
            state.usage.prompt_tokens = v;
        }
        if let Some(v) = update.completion_tokens {
            state.usage.completion_tokens = v;
        }
        if let Some(v) = update.total_tokens {
            state.usage.total_tokens = v;
        }
        if update.completion_tokens_details.is_some() {
            state.usage.completion_tokens_details = update.completion_tokens_details;
        }
        if update.prompt_tokens_details.is_some() {
            state.usage.prompt_tokens_details = update.prompt_tokens_details;
        }
    }
}
```

#### finalize —— 完成逻辑

```rust
impl PartialMessageResponse {
    /// 将所有累积状态转化为最终的 MessageResponse。
    pub fn finalize(mut self) -> Result<MessageResponse, LlmError> {
        let id = self.id.unwrap_or_else(|| "stream-unknown".to_string());
        let model = self.model.unwrap_or_else(|| "unknown".to_string());
        let stop_reason = self.stop_reason.unwrap_or(StopReason::Other);

        // 1. 按 index 升序遍历所有 blocks，转换为 ContentBlock
        let mut content: Vec<ContentBlock> = Vec::new();
        for (_index, builder) in std::mem::take(&mut self.blocks).into_iter() {
            let block = match builder {
                ContentBlockBuilder::Text(text) => ContentBlock::Text { text },
                ContentBlockBuilder::Thinking { buffer, mut signature } => {
                    // 如果 Thinking block 的 signature 尚未填充，用 MessageComplete 的回填
                    if signature.is_none() {
                        signature = self.thinking_signature.clone();
                    }
                    ContentBlock::Thinking {
                        text: buffer,
                        signature,
                    }
                }
                ContentBlockBuilder::Refusal(text) => ContentBlock::Text { text },
                ContentBlockBuilder::ToolUse { id, name } => {
                    let arguments = self.tool_call_args.remove(&(_index as u32))
                        .unwrap_or_default();
                    let input: Value = serde_json::from_str(&arguments)
                        .unwrap_or(Value::Null);
                    ContentBlock::ToolUse { id, name, input }
                }
            };
            content.push(block);
        }

        Ok(MessageResponse {
            id,
            model,
            message: Message::Assistant { content },
            usage: self.usage,
            stop_reason,
            extra: HashMap::new(),
        })
    }

    /// 检查是否已收到足以构造"有意义"响应的数据。
    pub fn is_meaningful(&self) -> bool {
        self.id.is_some() && (self.is_complete || self.is_errored)
    }
}
```

#### 边界情况处理

| 边界场景 | 处理策略 | 理由 |
|----------|---------|------|
| MessageStart 前收到 TextDelta | warn log，忽略增量 | 不合法流，防御性处理 |
| ToolCallArgumentsDelta 乱序 | HashMap key 天然容忍 | index 作为关联 key，到达顺序不影响最终累积 |
| 多次 CostUpdate | 字段级合并（PartialUsage） | OpenAI 一次全量，Anthropic 分两次，OpenAI Response 可能多次 |
| 同一 index 收到多次 ContentBlockStart | `entry(*index).or_insert()` 幂等 | 第二次不覆盖已有内容 |
| MessageComplete 后 CostUpdate 才到 | 不阻断，仍然合并 | Usage 最终值可能最后才到 |
| ContentBlockEnd 缺失 | finalize 时仍然输出内容 | 不完整的 block 也是内容 |
| 无任何 ContentBlockStart | finalize 返回空的 Assistant 消息 | 边界场景，不阻断 |
| Error 后收到其他事件 | Error 返回 false，上层停止调用 apply_to | 一旦出错，不再处理后续事件 |
| thinking_signature 未填 | Thinking block 的 signature 为 None | 安全降级 |