企业官网建设流程全解析

AI Toolbox 是一个开源的个人 AI 工具箱，其中最硬核的模块之一，就是它的AI 协议网关（Proxy Gateway）。它运行在你的本机，负责把 Claude Code、Codex、Grok CLI、Kimi CLI、Gemini CLI 这些 AI 编程工具的请求，转发到任意你选择的模型供应商——哪怕两端说的是"不同的语言"。这篇深度剖析将带你从零理解：四大 AI 协议网关转换架构是如何实现的，为什么它的转换方案既优雅又稳健。

先看它在产品里的位置：每个 CLI 工具的供应商列表里，都可以配置不同协议的 API 端点：

为什么需要 AI 协议网关？

🤔 一个绕不开的现实问题：不同 AI 工具"说"不同的协议。

比如：你的 Claude Code 只会说Anthropic Messages，但你手里 DeepSeek 的端点是OpenAI Chat格式。直接转发？400 错误。这时 AI Toolbox 的协议网关就登场了——它把请求"翻译"成上游听得懂的格式，再把响应"翻译"回来。

而供应商端点的具体协议，在表单里以apiFormat形式选择：

两层架构：runtime 管编排，transformer 管翻译

理解整个网关的关键，是先看清它的分层设计。AI Toolbox 把协议转换拆成两个互不越权的层：

1️⃣ runtime 层（runtime/）：请求编排

负责"流程控制"的一切：匹配入站路由、读取供应商配置、确定源协议/目标协议、决定是否转换、拼接上游 URL 与鉴权头、执行供应商方言兼容、记录日志统计、处理重试与故障转移。

2️⃣ transformer 层（transformer/）：纯协议翻译

负责"内容翻译"的一切：把四种聊天协议的 JSON 请求体、错误体和 SSE 流相互转换。它不读数据库、不拼 URL、不注入 API Key，只接收"源协议 → 目标协议"的转换路由和原始载荷，输出转换后的载荷。

这个边界划得非常干净——协议结构互转换给 transformer，供应商方言兼容（DeepSeek 的 thinking 门控、Bedrock 的路径差异、Ollama 的 wire 格式）全部留在 runtime。新增一家供应商时，永远不用改 transformer 一行代码。

四大协议与 4×4 转换矩阵

协议枚举定义在 transformer/types.rs：

四种协议两两互转，构成12 个非恒等转换方向（4×4 去掉 4 个恒等方向），JSON 请求、JSON 响应、错误体和 SSE 流全部走同一套转换路由语义。

一个值得注意的优化：同协议请求根本不进转换器。当源协议与目标协议相同时，走直通链路，只做模型名改写、鉴权注入等 runtime 处理，保持字节保真。

转换核心：统一中间表示（LLM IR）

如果四种协议两两互写，需要 12 套转换器——这是"蜘蛛网"式的噩梦。AI Toolbox 用了经典而高效的星型架构：所有协议都先翻译成统一中间模型（IR），再由 IR 翻译成目标协议。

源协议 JSON ──入站转换器──▶ LLM IR ──出站转换器──▶ 目标协议 JSON

LLM IR 定义在 llm/model.rs 和 llm/tools.rs，它不是对外 API，只是转换内部的"通用语"，承载：

• 消息列表：角色、文本/图片内容、工具调用与工具结果、推理内容（reasoning）
• 请求参数：model、max_tokens、temperature、top_p、stop、stream 等
• 工具定义：tools、tool_choice、parallel_tool_calls
• 响应元数据：choices、usage、finish_reason

这样每种协议只需要维护"入站 + 出站"两个转换器（双向共 4 个），12 个方向全部由4 个协议 × 2 个方向的组合覆盖。转换内核入口在 transformer/kernel.rs。

一次请求的完整旅程

以"Claude Code 请求转发到 DeepSeek（OpenAI Chat 端点）"为例，整条链路在 runtime/upstream.rs 中编排：

1. 路由匹配：入站前缀/anthropic命中 Claude Code 路由（runtime/routes.rs），推导出源协议 =AnthropicMessages
2. 读取供应商：从供应商配置解析目标协议 =OpenAiChat（runtime/providers.rs）
3. 决策：源 ≠ 目标，创建ConversionRoute
4. 请求转换：源 JSON → LLM IR → 目标 JSON
5. 供应商方言适配：最后一跳执行 DeepSeek 专属规则（thinking 字段门控、JSON schema 降级等）
6. 拼 URL / 鉴权头，发出上游请求
7. 响应回转：响应按反向路由（target → source）翻译回 Anthropic Messages 格式返回客户端

流式响应：SSE 的边读边转

AI 编程工具大量使用流式输出（SSE），这给转换带来了额外挑战：不能把整个流缓冲下来再翻译，必须边读边写。

StreamKernel（transformer/stream.rs）的处理模型：

1. 处理 UTF-8 跨 chunk 边界
2. 解析 SSE 事件块（同时兼容 LF 和 CRLF 行尾）
3. 源协议解析器把各协议事件解析成统一流事件（Start、TextDelta、ReasoningDelta、ToolCall、Finish 等）
4. 目标协议写入器把统一事件写成目标协议的 SSE

各协议流式的"方言"（Chat 的[DONE]、Anthropic 的message_stop、Responses 的终态事件、Gemini 的 finish chunk）都被归一化，且结束事件幂等处理，不会重复输出完成信号。

跨请求状态：Side Stores 的巧妙隔离

多轮对话里有一些状态天然跨越 HTTP 请求。AI Toolbox 把它们统一放在runtime/side_stores/，与 transformer 完全隔离：

• CodexHistoryStore：记录上一轮的工具调用，当 Codex 下一轮只带previous_response_id时，自动补回缺失的前序工具调用
• GeminiShadowStore：回放带thoughtSignature的模型函数调用，保证 Gemini 多轮工具链不断裂
• InvalidResponsesCipherStore：负缓存，记住上游明确拒绝过的加密内容摘要，避免反复撞墙

三者都有容量上限和可靠的会话键，且不落数据库。

供应商方言兼容：runtime 的专属领域

"看起来像协议转换"的逻辑，其实大多属于供应商方言——比如 DeepSeek 不接受 OpenAI 的 JSON Schema wrapper、Ollama 的最后一跳是/api/chat而非标准 Chat。这些规则全部收敛在 runtime 的 outbound body pipeline 中，按providerType + target_protocol识别供应商方言（DeepSeek、Moonshot、GLM、xAI、Bedrock、Vertex、Copilot、Ollama 等十余种），永远不下沉到 transformer。

判断依据是供应商配置里显式声明的 profile 引用，而不是靠模型名或 Base URL "猜"供应商——这意味着自定义供应商不会被误套官方方言，聚合商也不会被当成官方渠道。

有损转换检测：宁可信其有

不是所有字段都能无损翻译。check_lossy_conversion()（transformer/shared/lossy.rs）在转换前检测高风险项——例如 Responses 的 hosted tool、Anthropic 的 server tool、Gemini 专属的 safetySettings 等目标协议无法表达的内容。

它只检测、不决策；是否拒绝由 runtime 策略决定：默认只把警告写入响应头X-Transformer-Lossy，当用户开启"有损拒绝"且请求未带X-Allow-Lossy头时，才返回本地 400。宁可透明地告诉你"这里可能有损失"，也不静默丢字段。

关键源码与文档索引

想继续深挖，这些入口最值得阅读：

完整协议转换源码在 transformer/ 模块，架构主文档见 docs/gateway-protocol-conversion.md，逐供应商兼容细节见 docs/gateway-provider-compatibility.md。

总结

AI Toolbox 的协议网关转换架构，核心思想可以浓缩成三句话：

1. 星型架构：用统一 LLM IR 把 12 个转换方向降维成 4 个协议的入站/出站转换器；
2. 严格分层：transformer 只管协议翻译，runtime 管编排与供应商方言，边界清晰到"新增供应商零改动转换器"；
3. 透明可信：有损检测、字节保真直通、终态精确判定，宁可失败也不伪造成功。

下次当你的 Claude Code 在 Codex 格式的供应商上流畅对话时，背后正是这套四大 AI 协议网关在默默完成无数次双向翻译。🚀