OmniRoute 代码库文档精读：OpenAI 中枢翻译架构与 open-sse 四层代理引擎设计-平芜编程栈

OmniRoute 代码库文档精读：OpenAI 中枢翻译架构与 open-sse 四层代理引擎设计

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

本文基于 OmniRoute 仓库的代码库文档（Codebase Documentation），带你完整走一遍这个多提供商 AI 代理路由器的内部结构：从 "OpenAI 格式作为翻译中枢" 的 Hub-and-Spoke 设计，到open-sse工作区中 Config / Executors / Handlers / Services / Translator / Utils 六大模块的职责边界，再到 SSE 流式翻译管道、令牌刷新去重、账号回退状态机与 Combo 模型链等核心机制。读完本文，你将能够独立定位任意一个请求在代码中的流转路径，并知道新增一个提供商或一种 API 格式时应该改哪些文件。

1. OmniRoute 是什么：AI 客户端与提供商之间的"万能翻译官"

OmniRoute 是一个代理路由器（proxy router），位于 AI 客户端（Claude CLI、Codex、Cursor IDE 等）与 AI 提供商（Anthropic、Google、OpenAI、AWS、GitHub 等）之间。它解决的核心问题是：

不同的 AI 客户端"说"不同的 API 格式，不同的提供商又"期望"不同的格式。OmniRoute 在这两端之间自动完成翻译。

可以把它想象成联合国的同传翻译：任何代表都可以用任意语言发言，翻译系统负责转换给任何其他代表。这一层"翻译"正是open-sse工作区（@omniroute/open-sse）存在的意义——它是一个可移植、框架无关的核心代理库，上层的 Next.js 应用只是把它接入 HTTP 路由。

2. 总体架构：四层管道 + Hub-and-Spoke 翻译

请求进入 OmniRoute 后依次经过四个逻辑层：

Clients (Claude CLI / Codex / Cursor / OpenAI 兼容端点) → Handler Layer 请求编排（格式检测、翻译、执行、流式/非流式、错误处理、用量记录） → Translator Layer 格式翻译（经过 OpenAI 中枢的双跳转换） → Executor Layer 提供商特定的 URL/Headers/请求体构造与凭证刷新 → Providers (Claude / Gemini / OpenAI / Copilot / Kiro / Antigravity / Cursor) Services Layer 以旁路方式支撑上述各层（鉴权、模型解析、回退、用量查询）

核心原则：以 OpenAI 格式为中枢

所有格式翻译都以OpenAI 格式为中枢（hub）经过两次跳转完成：

客户端格式 → [OpenAI 中枢] → 提供商格式 （请求方向） 提供商格式 → [OpenAI 中枢] → 客户端格式 （响应方向）

带来的直接收益：支持 N 种格式只需N 个翻译器（每种格式一对），而不是 N² 个（两两互转）。

项目结构

按文档描述的目录骨架（并结合当前仓库实际布局核对）：

OmniRoute/ ├── open-sse/ # 核心代理库（可移植、框架无关的 workspace） │ ├── index.ts # 主入口，统一导出 │ ├── config/ # 配置与常量（PROVIDERS、模型注册表、凭证加载） │ ├── executors/ # 提供商特定的请求执行（策略模式） │ ├── handlers/ # 请求处理编排（chatCore 等） │ ├── services/ # 业务逻辑（鉴权、模型解析、回退、用量） │ ├── translator/ # 格式翻译引擎 │ │ ├── request/ # 请求方向翻译器 │ │ ├── response/ # 响应方向翻译器 │ │ └── helpers/ # 共享翻译工具 │ └── utils/ # 工具函数（SSE 流、用量、错误、代理解析） ├── src/ # 应用层（Next.js App Router / 共享库） │ ├── app/ # Web UI、API 路由、中间件 │ ├── lib/ # 数据库、鉴权与共享库代码 │ ├── mitm/ # 中间人代理工具（CLI 集成） │ ├── models/ # 数据库模型 │ ├── shared/ # 共享工具（open-sse 的包装层） │ ├── sse/ # SSE 端点处理器 │ └── store/ # 状态管理 └── data/ # 运行时数据（凭证、日志） └── provider-credentials.json # 外部凭证覆盖（gitignored）

3. 模块逐一解析

3.1 Config（`open-sse/config/`）：提供商配置的唯一事实源

该目录是所有提供商配置的单一事实源（single source of truth）。核心文件：

文件	作用
`constants.ts`	`PROVIDERS`对象：每个提供商的 base URL、OAuth 凭证（默认值）、Headers 与默认系统提示词；同时定义`HTTP_STATUS`、`ERROR_TYPES`、`COOLDOWN_MS`、`BACKOFF_CONFIG`与`SKIP_PATTERNS`
`credentialLoader.ts`	从`data/provider-credentials.json`读取外部凭证，并合并覆盖`PROVIDERS`中的硬编码默认值——把密钥挡在源码之外，同时保持向后兼容
`providerModels.ts`	中央模型注册表：提供商别名 → 模型 ID 的映射，提供`getModels()`、`getProviderByAlias()`等函数
`codexInstructions.ts`	注入 Codex 请求的系统指令（编辑约束、沙箱规则、审批策略）
`defaultThinkingSignature.ts`	Claude 与 Gemini 模型的默认 "thinking" 签名
`ollamaModels.ts`	本地 Ollama 模型的模式定义（名称、大小、系列、量化）

凭证加载流程（来源：credentialLoader.ts）：

应用启动 → constants.ts 定义带硬编码默认值的 PROVIDERS → data/provider-credentials.json 是否存在？ 否 → 直接使用硬编码默认值 是 → 逐个提供商检查： 不在 PROVIDERS 中 → 记录警告并跳过 值不是对象 → 记录警告并跳过 是对象 → 合并 clientId、clientSecret、tokenUrl、authUrl、refreshUrl → PROVIDERS 就绪（已合并外部凭证）

这套"默认值 + 外部覆盖"的设计意味着：源码中的凭证只是占位默认值，真实部署时把密钥放进 gitignore 的 JSON 文件即可，无需改动任何代码。

3.2 Executors（`open-sse/executors/`）：策略模式封装提供商差异

执行器用策略模式（Strategy Pattern）封装每个提供商的私有逻辑：所有执行器继承BaseExecutor，按需覆写基础方法。当前仓库中该目录已扩展到 100+ 个执行器文件（含各 web 端 OAuth 逆向执行器），基础骨架与文档描述一致：

文档中列出的关键执行器一览（均可在 open-sse/executors/ 中找到对应文件）：

执行器	提供商	关键特化
`base.ts`	—	抽象基类：URL 构造、Headers、重试逻辑、凭证刷新
`default.ts`	Claude、Gemini、OpenAI、GLM、Kimi、MiniMax	标准提供商的通用 OAuth 令牌刷新
`antigravity.ts`	Google Cloud Code	项目/会话 ID 生成、多 URL 回退、从错误消息解析自定义重试时长（如 "reset after 2h7m23s"）
`cursor.ts`	Cursor IDE	最复杂：SHA-256 校验和鉴权、Protobuf 请求编码、二进制 EventStream → SSE 响应解析
`codex.ts`	OpenAI Codex	注入系统指令、管理 thinking 等级、剔除不支持的参数
`github.ts`	GitHub Copilot	双令牌体系（GitHub OAuth + Copilot token）、模仿 VSCode 请求头
`kiro.ts`	AWS CodeWhisperer	AWS EventStream 二进制解析、AMZN 事件帧、令牌估算
`index.ts`	—	工厂：提供商名 → 执行器类映射，带默认回退

工厂选择逻辑在executors/index.ts中完成；运行时按请求目标提供商查表，找不到专用执行器时落回DefaultExecutor。

3.3 Handlers（`open-sse/handlers/`）：请求生命周期编排层

Handler 是编排层，负责协调翻译、执行、流式输出与错误处理。核心文件：

文件	作用
`chatCore.ts`	中央编排器（约 600 行）。处理完整请求生命周期：格式检测 → 翻译 → 执行器分发 → 流式/非流式响应 → 令牌刷新 → 错误处理 → 用量记录
`responsesHandler.ts`	OpenAI Responses API 适配器：Responses 格式 → Chat Completions → 交给`chatCore`→ 再把 SSE 转回 Responses 格式
`embeddings.ts`	Embedding 生成：解析 embedding 模型 → 提供商，分发到提供商 API，返回 OpenAI 兼容响应
`imageGeneration.ts`	图像生成：解析图像模型 → 提供商，支持 OpenAI 兼容、Gemini-image（Antigravity）与回退（Nebius）模式，返回 base64 或 URL 图像

chatCore.ts的请求生命周期可归纳为：

客户端请求（任意格式） → 检测源格式 → 检查 bypass 模式（Claude CLI 的标题提取/warmup/count） → 解析模型与提供商 → 翻译请求（source → OpenAI → target） → 获取提供商执行器 → 执行器构造 URL/Headers、转换请求体、按需刷新凭证 → HTTP fetch（流式或非流式） 流式：SSE 流经 Transform Stream 逐块翻译（target → OpenAI → source）后回传 非流式：JSON 响应整体翻译后回传 错误（401/429/500…）：刷新凭证重试 → 账号回退逻辑

3.4 Services（`open-sse/services/`）：支撑各层的业务逻辑

文件	作用
`provider.ts`	格式检测（`detectFormat`）：分析请求体结构识别 Claude/OpenAI/Gemini/Antigravity/Responses 格式（含`max_tokens`启发式判断 Claude）；URL/Header 构造、thinking 配置归一化；支持`openai-compatible-`与`anthropic-compatible-`动态提供商
`model.ts`	模型字符串解析（`claude/model-name`→`{provider, model}`）、别名解析与冲突检测、输入清洗（拒绝路径穿越/控制字符）
`accountFallback.ts`	限流处理：指数退避（1s → 2s → 4s → 上限 2min）、账号冷却管理、错误分类（哪些错误触发回退）
`tokenRefresh.ts`	所有提供商的 OAuth 令牌刷新：Google（Gemini、Antigravity）、Claude、Codex、Qwen、Qoder、GitHub（OAuth + Copilot 双令牌）、Kiro（AWS SSO OIDC + Social Auth）；含在途 promise 去重缓存与指数退避重试
`combo.ts`	Combo 模型：回退模型链。模型 A 遇到可回退错误时依次尝试 B、C……并返回真实的上游状态码
`usage.ts`	从提供商 API 拉取配额/用量（Copilot 配额、Antigravity 模型配额、Codex 限流、Kiro 用量明细、Claude 设置）
`accountSelector.ts`	带评分算法的智能账号选择：综合优先级、健康状态、轮询位置与冷却状态
`contextManager.ts`	每请求上下文生命周期管理（请求 ID、时间戳、提供商信息），用于调试与日志
`ipFilter.ts`	IP 访问控制：白名单/黑名单模式，在 API 请求处理前校验客户端 IP
`sessionManager.ts`	带客户端指纹的会话跟踪：按哈希客户端标识统计活跃会话与请求数
`signatureCache.ts`	基于请求签名的去重缓存：时间窗内相同请求直接返回缓存响应
`systemPrompt.ts`	全局系统提示词注入：对所有请求前置或追加，含逐提供商兼容性处理
`thinkingBudget.ts`	推理令牌预算：passthrough / auto（剥离 thinking 配置）/ custom（固定预算）/ adaptive（按复杂度缩放）四种模式
`wildcardRouter.ts`	通配符模型路由：把`/claude-`等模式解析为具体的提供商/模型对

令牌刷新去重：多个并发请求触发同一提供商令牌刷新时，refreshPromiseCache让后续请求复用已在途的刷新 promise，避免重复打 OAuth 端点，最终所有请求拿到同一枚新令牌后缓存条目被删除。

账号回退状态机：

Active --请求失败(401/429/500)--> Error Error --错误分类：限流/鉴权/瞬态可回退，400 不触发--> Cooldown（指数退避：L0=1s, L1=2s, L2=4s, 上限 2min） Cooldown --到期--> Active Active --请求成功--> Active（重置退避）

Combo 模型链：

带 combo 的请求 → 模型 A A 成功(2xx) → 返回响应 A 失败(429/401/500) → 可回退？ → 是 → 模型 B →（同上递归至 C……） 全部失败 → 返回最后一个上游状态码

3.5 Translator（`open-sse/translator/`）：自注册插件式翻译引擎

翻译引擎采用自注册插件系统。目录结构（当前仓库实际内容）：

目录/文件	内容
`request/`	请求体翻译器（Claude→OpenAI、Gemini→OpenAI、Antigravity→OpenAI、OpenAI Responses→OpenAI、OpenAI→Claude/Gemini/Kiro/Cursor/Clova、Claude→Gemini 等，部分复杂翻译拆分子目录）
`response/`	流式响应块翻译器（SSE 事件类型、thinking 块、工具调用的跨格式转换）
`helpers/`	共享工具：`claudeHelper`（系统提示词提取、thinking 配置）、`geminiHelper`（parts/contents 映射）、`openaiHelper`（格式过滤）、`toolCallHelper`（ID 生成、缺失响应注入）、`maxTokensHelper`、`responsesApiHelper`
`index.ts`	翻译引擎：`translateRequest()`/`translateResponse()`、状态管理、注册表入口
`formats.ts`	格式常量：`OPENAI`、`CLAUDE`、`GEMINI`、`ANTIGRAVITY`、`KIRO`、`CURSOR`、`OPENAI_RESPONSES`
`registry.ts`	底层注册表实现

关键设计：自注册插件。注册表的核心实现只有几十行（见 registry.ts）：

const requestRegistry = new Map<string, RequestTranslator>(); const responseRegistry = new Map<string, ResponseTranslator>(); function makeKey(from: string, to: string) { return `${from}:${to}`; // 以 "from:to" 作为注册键 } export function register(from, to, requestFn?, responseFn?) { const key = makeKey(from, to); if (requestFn) requestRegistry.set(key, requestFn); if (responseFn) responseRegistry.set(key, responseFn); }

每个翻译器文件在模块被 import 时调用register()完成自我登记：

// 翻译器文件在 import 时自注册： import { register } from "../registry.js"; register("claude", "openai", translateClaudeToOpenAI); // bootstrap 模块显式 import 所有翻译器文件，触发注册：

bootstrap.ts 就是这份"注册清单"——它逐一 import 每个 request/response 翻译器文件，并在文件末尾以注释声明该模块本身是 no-op，"import 即注册"：

import "./request/claude-to-openai.ts"; import "./request/openai-to-claude.ts"; import "./request/gemini-to-openai.ts"; import "./request/openai-to-gemini.ts"; import "./request/antigravity-to-openai.ts"; import "./request/openai-responses.ts"; import "./request/openai-to-kiro.ts"; import "./request/openai-to-cursor.ts"; // ... response 方向同理

因此新增一个翻译器 = 建一个文件 + 在 bootstrap 中加一行 import，无需改动引擎代码。

3.6 Utils（`open-sse/utils/`）：流式管道与横切工具

文件	作用
`error.ts`	OpenAI 兼容格式的错误响应构造、上游错误解析、Antigravity 重试时长提取、SSE 错误流式输出
`stream.ts`	SSE Transform Stream——核心流式管道。两种模式：`TRANSLATE`（完整格式翻译）与`PASSTHROUGH`（仅归一化 + 提取 usage）。负责块缓冲、用量估算、内容长度跟踪；每条流独享 encoder/decoder 实例，避免共享状态
`streamHelpers.ts`	底层 SSE 工具：`parseSSELine`（容忍空白）、`hasValuableContent`（过滤 OpenAI/Claude/Gemini 空块）、`fixInvalidId`、`formatSSE`（感知格式的 SSE 序列化，含`perf_metrics`清理）
`usageTracking.ts`	从任意格式（Claude/OpenAI/Gemini/Responses）提取令牌用量；工具/消息文本使用不同的字符-令牌比率估算；附加安全缓冲；按格式过滤字段；带 ANSI 颜色的控制台日志
`requestLogger.ts`	遗留的文件式请求日志助手（保留兼容性）
`bypassHandler.ts`	拦截 Claude CLI 的特定请求（标题提取、warmup、count），不调用任何提供商直接返回伪造响应；刻意限定在 Claude CLI 范围内
`networkProxy.ts`	解析某提供商的出站代理 URL，优先级：提供商专属配置 → 全局配置 → 环境变量（`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`）；支持`NO_PROXY`排除，配置缓存 30s

SSE 流式管道（源码中STREAM_MODE即translate/passthrough两种取值，见 stream.ts）：

提供商 SSE 流 → TextDecoder（每流独立实例） → 按换行缓冲 → parseSSELine()（trim 空白、解析 JSON） → 模式分支： TRANSLATE → translateResponse()（target → OpenAI → source） PASSTHROUGH → fixInvalidId()（归一化块） → hasValuableContent()（过滤空块；无内容则跳过） → extractUsage()（跟踪令牌计数） → formatSSE()（序列化 + 清理 perf_metrics） → TextEncoder（每流独立实例） → 写入客户端流

用量安全缓冲的落地细节：在 usageTracking.ts 中，默认缓冲为 2000 令牌，可用环境变量USAGE_TOKEN_BUFFER覆盖、设为 0 可完全禁用；缓冲值会写入context_budget_*字段，避免把预算膨胀算进真实的 provider 计量字段。设计意图是：客户端（尤其代码代理类客户端）在计算上下文窗口占用时预留出系统提示词与格式转换带来的额外开销，防止撞墙。

请求日志的会话结构（遗留日志格式，每个请求一个会话目录）：

logs/ └── claude_gemini_claude-sonnet_20260208_143045/ ├── 1_req_client.json # 原始客户端请求 ├── 2_req_source.json # 初次转换后 ├── 3_req_openai.json # OpenAI 中间格式 ├── 4_req_target.json # 最终目标格式 ├── 5_res_provider.txt # 提供商 SSE 块（流式） ├── 5_res_provider.json # 提供商响应（非流式） ├── 6_res_openai.txt # OpenAI 中间块 ├── 7_res_client.txt # 客户端可见的 SSE 块 └── 6_error.json # 错误详情（如有）

这套"同一请求在不同翻译阶段各存一份"的结构，是排查翻译 bug 时最有价值的工具：任何一层的格式错误都能精确定位到对应文件。

3.7 应用层（`src/`）：把引擎接到 HTTP 上

目录	作用
`src/app/`	Web UI、API 路由、中间件、OAuth 回调处理
`src/lib/`	数据库访问（`localDb.ts`、`usageDb.ts`）、鉴权、共享代码
`src/mitm/`	中间人代理工具，用于拦截提供商流量（CLI 集成）
`src/models/`	数据库模型定义
`src/shared/`	open-sse 函数的包装层（provider、stream、error 等）
`src/sse/`	把 open-sse 库接入路由的 SSE 端点处理器
`src/store/`	应用状态管理

文档列出的重点 API 路由：

路由	方法	用途
`/api/provider-models`	GET/POST/DELETE	逐提供商自定义模型的 CRUD
`/api/models/catalog`	GET	按提供商分组的全量模型目录（chat/embedding/image/custom）
`/api/settings/proxy`	GET/PUT/DELETE	分层出站代理配置（global/providers/combos/keys）
`/api/settings/proxy/test`	POST	校验代理连通性，返回公网 IP/延迟
`/v1/providers/[provider]/chat/completions`	POST	指定提供商的 chat completions（含模型校验）
`/v1/providers/[provider]/embeddings`	POST	指定提供商的 embeddings（含模型校验）
`/v1/providers/[provider]/images/generations`	POST	指定提供商的图像生成（含模型校验）
`/api/settings/ip-filter`	GET/PUT	IP 白名单/黑名单管理
`/api/settings/thinking-budget`	GET/PUT	推理令牌预算配置（passthrough/auto/custom/adaptive）
`/api/settings/system-prompt`	GET/PUT	全局系统提示词注入
`/api/sessions`	GET	活跃会话跟踪与指标
`/api/rate-limits`	GET	逐账号限流状态

4. 关键设计模式总结

Hub-and-Spoke 翻译：所有格式经过 OpenAI 中枢互转。新增提供商只写一对翻译器（到/自 OpenAI），而不是 N 对。
执行器策略模式：每个提供商一个继承自BaseExecutor的专用类，工厂（executors/index.ts）在运行时按提供商选择。
自注册插件系统：翻译器模块 import 时经register()自我登记；新增翻译器只需建文件 + 加 import。
指数退避的账号回退：提供商返回 429/401/500 时可切换到下一个账号，冷却按 1s → 2s → 4s → 上限 2min 指数增长（BACKOFF_CONFIG定义于 constants.ts，消费逻辑在 accountFallback.ts）。
Combo 模型链：一个 combo 聚合多个provider/model字符串，首个失败自动落到下一个。
有状态的流式翻译：响应翻译在 SSE 块之间保持状态（thinking 块跟踪、工具调用累积、内容块索引），通过initState()机制实现。
用量安全缓冲：对上报用量附加 2000 令牌缓冲（USAGE_TOKEN_BUFFER可覆盖），防止客户端因系统提示词与格式转换开销撞上上下文窗口上限。

5. 支持的格式与提供商

支持格式

格式	方向	标识符
OpenAI Chat Completions	source + target	`openai`
OpenAI Responses API	source + target	`openai-responses`
Anthropic Claude	source + target	`claude`
Google Gemini	source + target	`gemini`
Antigravity	source + target	`antigravity`
AWS Kiro	仅 target	`kiro`
Cursor	仅 target	`cursor`

Kiro 与 Cursor 只能作为"上游目标"：它们没有标准客户端会主动发送这两种格式，所以只需 OpenAI → 目标（请求）与目标 → OpenAI（响应）两个方向的翻译器。

支持提供商

提供商	鉴权方式	执行器	备注
Anthropic Claude	API key 或 OAuth	Default	使用`x-api-key`头
Google Gemini	API key 或 OAuth	Default	使用`x-goog-api-key`头
Antigravity	OAuth	Antigravity	多 URL 回退、自定义重试解析
OpenAI	API key	Default	标准 Bearer 鉴权
Codex	OAuth	Codex	注入系统指令、管理 thinking
GitHub Copilot	OAuth + Copilot token	Github	双令牌、模仿 VSCode 请求头
Kiro (AWS)	AWS SSO OIDC 或 Social	Kiro	二进制 EventStream 解析
Cursor IDE	Checksum 鉴权	Cursor	Protobuf 编码、SHA-256 校验和
Qwen	OAuth	Default	标准鉴权
Qoder	OAuth（Basic + Bearer）	Default	双鉴权头
OpenRouter	API key	Default	标准 Bearer 鉴权
GLM、Kimi、MiniMax	API key	Default	Claude 兼容，使用`x-api-key`
`openai-compatible-*`	API key	Default	动态：任意 OpenAI 兼容端点
`anthropic-compatible-*`	API key	Default	动态：任意 Claude 兼容端点

注意：当前仓库的open-sse/config/目录已扩展出远多于上表的提供商注册文件（如 azureAi.ts、bedrock.ts、vertex 相关注册等），上表反映的是本文档版本时点的基础集合；动态前缀提供商（openai-compatible-*/anthropic-compatible-*）允许把任意兼容端点零配置接入。

6. 端到端数据流总览

流式请求：

客户端 → detectFormat() → translateRequest()（source → OpenAI → target） → Executor（buildUrl + buildHeaders） → fetch(providerURL) → createSSEStream()（TRANSLATE 模式） → parseSSELine() → translateResponse()（target → OpenAI → source） → extractUsage() + 安全缓冲 → formatSSE() → 客户端收到已翻译的 SSE → logUsage() / saveRequestUsage()

非流式请求：

客户端 → detectFormat() → translateRequest()（source → OpenAI → target） → Executor.execute() → translateResponse()（target → OpenAI → source） → 返回 JSON 响应

Bypass 流（Claude CLI 专属）：

Claude CLI 请求 → 匹配 bypass 模式？ 匹配（Title/Warmup/Count）→ 生成伪造 OpenAI 响应 → 翻译回源格式 → 不调用提供商直接返回 不匹配 → 正常流程

Bypass 的意义：Claude CLI 会发出一些"探针式"请求（会话标题生成、连接预热等），如果真打上游会浪费配额甚至触发限流；bypassHandler.ts让这些请求在网关内闭环消化。

7. 给贡献者的定位指南

结合本文的模块划分，常见修改场景对应关系：

新增一个 API 格式：在open-sse/translator/写一对翻译器（to/from OpenAI），在 bootstrap.ts 注册 import，在formats.ts加格式常量；
新增一个提供商：在open-sse/config/注册其配置，在open-sse/executors/提供专用执行器（或复用default.ts），在executors/index.ts工厂中映射；
调整回退/冷却行为：改open-sse/config/constants.ts的BACKOFF_CONFIG或open-sse/services/accountFallback.ts的错误分类；
排查某次翻译错误：利用请求日志会话目录中按阶段编号的请求/响应文件，对照translator/request/与translator/response/中对应翻译器逐层比对；
理解某请求为何走了某个账号：入口在services/accountSelector.ts的评分逻辑与accountFallback.ts的冷却状态。

整套架构的取舍可以浓缩为一句话：把"格式差异"收敛到自注册的翻译器里，把"提供商差异"收敛到策略模式的执行器里，让编排层（handlers）与业务层（services）保持薄而稳定——这正是 Hub-and-Spoke 思想从翻译层推广到整个代码库的结果。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OmniRoute 代码库文档精读：OpenAI 中枢翻译架构与 open-sse 四层代理引擎设计