BitFun UnifiedResponse：AI Agent 流内语义统一的最深实践

May 29, 2026

如果你维护过一个多模型的 AI Agent，你一定遇到过这个噩梦：OpenAI 的流式响应和 Anthropic 的流式响应，长得完全不一样。

同一个语义——"模型正在产出文本"——在三个提供商的 SSE 流里是三种截然不同的 JSON 路径：

事件	OpenAI	Anthropic	Gemini
文本块	`choices[0].delta.content`	`content_block_delta.text`	`candidates[0].content.parts[0].text`
推理内容	无原生支持	`content_block_delta.thinking`	`thought` 字段
工具调用开始	`delta.tool_calls[0].function.name` 首次非 null	`content_block_start.type == "tool_use"`	`functionCall` null→非null
参数增量	`delta.tool_calls[0].function.arguments`	`content_block_delta.partial_json`	`functionCall.args`
工具调用结束	`finish_reason == "tool_calls"`	`content_block_stop`	`finishReason == "STOP"`
Token 用量	最后一个 chunk	`message_stop` 中	`usageMetadata`
缓存 tokens	`prompt_tokens_details.cached_tokens`	`cache_creation_input_tokens`	不支持

不是简单的字段名差异——是事件语义粒度完全不同。Anthropic 把工具调用拆成 start → delta → stop 三个事件；OpenAI 把工具调用隐藏在 delta.tool_calls 的 null→非null 状态转换里；Gemini 用 finishReason 隐式标记结束。

一个不做统一的 Agent 系统，其 UI 渲染、事件总线、流处理器、压缩引擎——每一层下游代码都要分头理解三套协议。这是一个 O(N×M) 的维护灾难（N=提供商数，M=消费方数）。

BitFun 的答案是一个 Rust 枚举：UnifiedResponse。我认为它是目前同类系统中深度最深的流内语义统一。

UnifiedResponse：把三个世界折叠成一个

BitFun 在 ai-adapters crate 里定义了一个枚举，将 OpenAI、Anthropic、Gemini 的 SSE 事件统一映射：

pub enum UnifiedResponse {
    TextChunk(String),              // 任何提供商产生的文本增量
    ThinkingChunk(String),          // 任何提供商产生的推理/思考内容
    ToolCallStart(ToolCall),        // 工具调用开始（携带函数名和参数）
    ToolCallDelta(ToolCall),        // 工具参数增量
    ToolCallEnd,                    // 工具调用完成
    Usage(UnifiedTokenUsage),       // 统一 Token 用量
    Done,                           // 流结束
    Error(Error),                   // 错误
}

这个枚举表面简洁，但背后有四个关键设计决策：

1. 显式的工具调用生命周期

不是把工具调用当作"特殊的文本块"来 hack，而是用三个独立事件（Start → Delta → End）表达完整生命周期。这个设计来自 Anthropic 的原生支持（content_block_start/delta/stop），但 BitFun 将其提升为通用抽象——OpenAI 和 Gemini 的流也被提升到这个粒度。

在 OpenAI 原始流里没有 ToolCallStart/End——只有 delta.tool_calls 的 null→非null 状态转换。BitFun 的 OpenAI 适配器必须检测这个状态转换并合成 Start/End 事件。这不是简单的字段重命名，而是状态机推断。

2. TextChunk 与 ThinkingChunk 的语义分离

OpenAI 的 SSE 流里，推理内容（如 DeepSeek 的 reasoning_content）和文本内容混在同一个 delta.content 流里。Anthropic 有独立的 thinking 块。Gemini 用 thought 字段。

BitFun 将两者分离为独立的事件类型——UI 层不需要知道当前流来自哪个提供商，就能正确地将推理内容渲染到折叠面板，将文本内容渲染到主对话区。

3. UnifiedTokenUsage 的标准化

pub struct UnifiedTokenUsage {
    pub input_tokens: usize,
    pub output_tokens: Option<usize>,
    pub total_tokens: usize,
    pub cached_tokens: Option<usize>,        // 缓存命中
    pub cache_creation_tokens: Option<usize>, // 缓存写入
    pub reasoning_tokens: Option<usize>,      // 推理 tokens
}

OpenAI 的 cached_tokens 埋在 usage.prompt_tokens_details.cached_tokens 的三层嵌套里。Anthropic 叫 cache_creation_input_tokens。Gemini 不支持缓存统计。BitFun 将它们统一为语义清晰的两个字段。这对前缀缓存优化至关重要——你需要在同一尺度上比较三个提供商的缓存效率。

4. 流重试与超时内置适配器层

每个 provider adapter 都内置了 10 次流重试（指数退避，基准 500ms）、45 秒空闲超时、TTFT 超时（推理模型 45s，标准模型 30s）。这不是在 RoundExecutor 层做的——是在适配器层。意味着任何提供商，只要实现一个 Rust trait，就能免费获得生产级的容错能力。

为什么是"最深"：与其他 Agent 的对比

维度	BitFun	Hermes Agent	OpenCode
文本/推理分离	✅ 独立事件	❌ 传输层判断	❌ 无
工具调用生命周期	✅ Start→Delta→End	❌ 单次检测	❌ 无
Token 用量标准化	✅ 6 字段统一	❌ 提供商原始	❌ 无
流重试	✅ 10次+退避	❌ 无	❌ 无
新提供商成本	实现一个 Rust trait	改 transport + UI + 压缩	改 tool_permits

Hermes Agent 的适配器在传输层。agent/transports/chat_completions.py 处理 OpenAI-compatible 请求，流式响应通过 Python generator 返回，本质上是 dict → dict 的薄封装。没有统一的流内语义——TextChunk/ThinkingChunk/ToolCallStart 的概念不存在。reasoning_content 的处理是传输层硬编码的 bug fix（#15717），不是架构设计。

OpenCode 走工具权限门控路线。流式输出不做语义统一，直接传递。适配层更多关心 tool_permits——特定提供商允许/禁止哪些工具。

两种方案的结果是一样的：UI 层、压缩引擎、session 持久化都直接依赖提供商原始格式。支持一个新提供商要改 N 个地方。

架构全景：统一流的上下游

UnifiedResponse 不是孤立的设计——它解耦了 BitFun 整个执行管线：

flowchart TB subgraph Providers["AI 提供商"] OAI["OpenAI SSE 流"] ANT["Anthropic SSE 流"] GEM["Gemini SSE 流"] end subgraph Adapters["provider adapters"] OA["handle_openai_stream()"] AN["handle_anthropic_stream()"] GE["handle_gemini_stream()"] end subgraph Unified["UnifiedResponse 流"] TC["TextChunk"] TH["ThinkingChunk"] TS["ToolCallStart"] TD["ToolCallDelta"] TE["ToolCallEnd"] US["Usage"] DO["Done/Error"] end subgraph Consumers["下游消费者"] SP["StreamProcessor → StreamResult"] EB["EventBus → AgenticEvent"] CC["ContextCompressor → 语义压缩"] SD["Session 持久化 → ModelRoundData"] end OAI --> OA ANT --> AN GEM --> GE OA --> TC OA --> TS AN --> TH AN --> TE GE --> US TC --> SP TH --> EB TS --> CC TE --> SD

每一层下游消费者都只与 UnifiedResponse 交互：

StreamProcessor 不需要知道当前用的是什么提供商——它只处理 UnifiedResponse 枚举。full_text 和 full_thinking 的分离让它能独立处理"模型思考了什么"和"模型产出了什么"。
EventBus 发出的 TextChunk 和 ThinkingChunk 事件是提供商无关的。前端 React 组件只需要订阅这两种事件类型——不管是 DeepSeek 的 reasoning_content 还是 Claude 的 thinking block。
ContextCompressor 在做上下文压缩时可以区分"思考内容"（压缩时可能丢弃）和"产物内容"（压缩时保留核心）。
Session 持久化 里的 ModelRoundData.text_items 和 thinking_items 分离，意味着未来可以做基于"思考质量"的 session 分析——检测某轮推理是否自相矛盾——而不需要重新解析原始 SSE 格式。

代价：深度统一不是免费的

BitFun 为这个深度统一支付了三个成本：

1. 适配器复杂度

每个 provider adapter 不仅是字段重命名，还要做状态检测。OpenAI 适配器必须追踪 delta.tool_calls 的 null→非null 状态转换来合成 ToolCallStart，追踪 finish_reason 来合成 ToolCallEnd。这个判断可能跨越多个 SSE chunk——你需要缓冲部分数据才能做出决策。

2. 新提供商的工作量

每增加一个提供商（如 DeepSeek 的 reasoning_content），需要实现完整的 handle_xxx_stream() 函数，将所有事件映射到 UnifiedResponse。目前 BitFun 只有 3 个——扩展到 10+ 提供商时维护成本线性增长。Hermes 的薄封装在此处反而有优势——新提供商只要端点是 OpenAI-compatible 就能工作。

3. Rust 的类型安全门槛

UnifiedResponse 是一个 Rust enum——编译器保证每个 match 分支都被覆盖。这是优势（不会漏掉 ToolCallEnd），但也是门槛——每次新增 variant 需要修改所有 match 块。Python 的 Hermes 没有这个编译期约束。

设计启发：什么时候需要深层统一？

BitFun 的架构选择不是"更好"——是在特定约束下的理性权衡：

Rust 的零成本抽象 让 enum 匹配没有运行时开销——每个 variant 的处理在编译期就被内联。Python 做同样的事情会有显著的运行时开销。
多平台部署（Desktop/Server/CLI/Mobile）意味着多个 UI 消费方——如果在适配器层不做统一，每个平台都要自己处理三套协议。统一后，新增平台只消费 UnifiedResponse。
工具调用的首创精神——BitFun 从第一天就原生支持工具调用，而 Hermes 和 OpenCode 的工具调用是后来添加的。在工具调用的流处理上做深层统一是"正确的早期投资"。
10 次流重试 + 指数退避 只有在适配器层统一后才能低成本实现——每个提供商自动继承。

如果你的系统只有 1-2 个提供商，或者工具调用不是核心路径，Hermes 的薄封装模式可能更合适——简单、灵活、新提供商零成本接入。但当你面临 5+ 提供商、4+ 消费方时，BitFun 的 UnifiedResponse 模式就是正确的答案。

技术声明：本文基于 BitFun 开源代码库的架构分析（src/crates/ai-adapters/）和 Hermes Agent v0.12+ 的 transport 层源码阅读。UnifiedResponse 枚举结构来自代码级审计，对比表中的 Hermes/OpenCode 行为基于源码分析和公开文档。三个提供商（OpenAI/Anthropic/Gemini）的 SSE 流格式差异为公开 API 文档可查证的公开知识。所有性能数字（10 次重试、500ms 基准退避、45s 超时）来自 BitFun 配置常量。

发布于 2026 年 5 月 29 日