OmniRoute 代码库架构指南从模块地图到请求管线的源码级解读【免费下载链接】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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本指南基于 OmniRoute 官方代码库文档英文原版、印尼语版当前版本 v3.8.51编写面向两类读者准备向 OmniRoute 贡献代码的工程师以及希望在其上构建集成的开发者。读完本文你将掌握仓库的完整目录地图、运行时分层Next.js 应用层 /open-sse流式引擎工作区、hub-and-spoke 格式翻译、executor 策略模式、账号回退与组合路由等核心机制并知道新增一个 provider / API 路由 / 数据库模块 / MCP 工具时应该往哪个目录放代码。1. OmniRoute 是什么站在客户端与提供商之间的同声传译OmniRoute 是一个运行在AI 客户端Claude CLI、Codex、Cursor IDE、OpenAI 兼容客户端等与AI 提供商Anthropic、Google、OpenAI、AWS、GitHub 等之间的多提供商代理路由器。它解决的核心痛点是不同的 AI 客户端说不同的语言API 格式不同的提供商也期待不同的语言。OmniRoute 在两者之间自动翻译。可以把它想象成联合国里的同声传译任何一方可以用自己的语言发言路由器负责把它转换成对方听得懂的语言。从仓库证据看这一翻译路由器的角色贯穿始终open-sse/工作区npm 包omniroute/open-sse拥有独立的translator/格式转换、executors/108 个 provider 专用 HTTP 执行器、handlers/请求编排、services/80 业务服务模块详见后文各节。2. 技术栈一览关注点选择Web 框架Next.js 16App Router、standalone 输出、无全局 middleware语言TypeScript 6.0targetES2022module: esnextmoduleResolution: bundler运行时Node.js22.22.2 23或24.0.0 27通过engines与SUPPORTED_NODE_RANGE强制数据库SQLitebetter-sqlite3单例 WAL 日志模式桌面端Electron 41electron-builder26.10独立 workspace 位于electron/测试Node 原生测试运行器unit/integration、VitestMCP、autoCombo、cache、Playwrighte2e protocols-e2e构建Next.js standalone经scripts/build/build-next-isolated.mjs模块系统全 ESMtype: moduleWorkspacesnpm workspaceopen-sse是唯一子工作区路径别名见 tsconfig.json/*→src/*omniroute/open-sse→open-sse/index.tsomniroute/open-sse/*→open-sse/*默认 HTTP 端口为20128API 与仪表盘共享同一进程。数据目录由环境变量DATA_DIR指定默认~/.omniroute/。3. 仓库总体布局OmniRoute/ ├── src/ Next.js 应用App Router、libs、domain、server、shared ├── open-sse/ 流式引擎工作区omniroute/open-sse ├── electron/ 桌面壳Electron 41 main preload ├── bin/ CLI 入口omniroute、reset-password ├── tests/ 单元、集成、e2e、protocols-e2e、translator、security、fixtures ├── scripts/ 构建、同步、检查、迁移、运行时辅助脚本 ├── docs/ 公共文档本文所在目录 ├── public/ 静态资源、PWA manifest、service worker ├── config/ 运行时配置样例 ├── images/ 营销/截图资源 ├── CLAUDE.md Claude Code 的仓库规则 ├── AGENTS.md 面向 Agent 的深层架构参考 ├── package.json v3.8.51workspace 根 └── tsconfig.json 路径别名 核心编译选项4. 核心架构原理Hub-and-Spoke 翻译OmniRoute 所有格式翻译都以 OpenAI 格式作为中枢hub客户端格式 → [OpenAI Hub] → 提供商格式 请求方向 提供商格式 → [OpenAI Hub] → 客户端格式 响应方向这意味着只需要N 个翻译器每种格式一对而不是N²每对格式一个。从源码看这一承诺在 open-sse/translator/index.ts 中被严格执行translateRequest()先尝试直达路径direct translator例如 Claude→Gemini、非 OpenAI 双边场景否则回退到 hub-and-spoke 两段式Step 1: source → openai若 source 非 openai Step 2: openai → target若 target 非 openai值得注意的实现细节源码可证同一格式直达时translateRequest会跳过转换步骤而 translateResponse 在流式响应中维护跨 chunk 的stateinitState()为每个源格式构建基础状态OpenAI Responses 还有专门的seq、responseId、函数调用缓冲等字段并在flushchunk 为 null时也把null传给源格式翻译器——这对openai-responses这类需要在终止事件中输出total_tokens的格式至关重要。5. 模块级详解open-sse 工作区5.1 Configopen-sse/config/—— 提供商的唯一事实来源所有提供商配置的唯一真源。核心文件与职责如下表文件用途constants.tsPROVIDERS对象每个提供商的 base URL、OAuth 凭据默认值、header、默认 system prompt。同时定义HTTP_STATUS、ERROR_TYPES、COOLDOWN_MS、BACKOFF_CONFIG、SKIP_PATTERNScredentialLoader.ts从data/provider-credentials.json加载外部凭据合并覆盖到PROVIDERS中硬编码的默认值之上。让密钥远离源码控制同时保持向后兼容providerModels.ts集中式模型注册表provider 别名 → 模型 ID。提供getModels()、getProviderByAlias()等函数codexInstructions.ts注入到 Codex 请求中的系统指令编辑限制、沙箱规则、审批策略defaultThinkingSignature.tsClaude 与 Gemini 模型的默认思考签名ollamaModels.ts本地 Ollama 模型的 schema 定义名称、大小、家族、量化方式open-sse/config/还包含按格式划分的模型注册表audioRegistry.ts、embeddingRegistry.ts、imageRegistry.ts、musicRegistry.ts、rerankRegistry.ts、searchRegistry.ts、videoRegistry.ts等、身份辅助模块codexIdentity.ts、anthropicHeaders.ts、cliFingerprints.ts以及云适配器azureAi.ts、bedrock.ts、watsonx.ts等。凭据加载流程5.2 Executorsopen-sse/executors/—— Strategy 模式的提供商适配层Executor 使用Strategy 模式封装提供商特有逻辑每个 executor 按需覆写基类方法。基类与主要实现类图当前仓库中 open-sse/executors/ 实际包含108 个 provider 执行器英文原版文档注明未列出的 provider 由default.ts用通用 OpenAI 兼容执行器兜底完整 355 家 provider 目录位于src/shared/constants/providers.ts。代表性执行器Executor提供商主要特化base.ts—抽象基类URL 构建、header、重试逻辑、凭据刷新default.tsClaude、Gemini、OpenAI、GLM、Kimi、MiniMax 等标准提供商通用 OAuth token 刷新antigravity.tsGoogle Cloud CodeAntigravity项目/会话 ID 生成、多 URL 回退、从错误信息解析自定义重试如 reset after 2h7m23scursor.tsCursor IDE最复杂SHA-256 checksum 认证、Protobuf 请求编码、二进制 EventStream → SSE 响应解析codex.tsOpenAI Codex注入系统指令、管理思考层级、删除不支持的参数github.tsGitHub Copilot双 token 体系GitHub OAuth Copilot token、模拟 VSCode 请求头kiro.tsAWS CodeWhispererKiro二进制 AWS EventStream 解析、AMZN 事件帧、token 估算5.3 Handlersopen-sse/handlers/—— 请求编排层Handler 是编排层协调翻译、执行、流式传输与错误处理。核心文件文件用途chatCore.ts中央编排器完整处理请求生命周期——格式检测 → 翻译 → executor 分发 → 流式/非流式响应 → token 更新 → 错误处理 → 用量记录responsesHandler.tsOpenAI Responses API 适配器Responses 格式 → Chat Completions → 送入chatCore→ SSE 再转回 Responses 格式embeddings.ts嵌入生成 handler解析嵌入模型 → 提供商发送给提供商 API返回 OpenAI 兼容嵌入响应。支持 6 提供商imageGeneration.ts图像生成 handler解析图像模型 → 提供商支持 OpenAI 兼容模式、Gemini-imageAntigravity与回退Nebius返回 base64 或 URL 图片audioSpeech.ts/audioTranscription.tsTTS 与 STTvideoGeneration.ts/musicGeneration.ts视频与音乐生成rerank.ts/moderations.ts/search.ts重排序、内容审核、联网搜索sseParser.ts/usageExtractor.ts/responseSanitizer.tsSSE 事件解析、上游 token 统计抽取、剥离提供商噪音字段请求生命周期chatCore.ts5.4 Servicesopen-sse/services/—— 支撑业务逻辑80 个服务模块按关注点划分节选关注点文件Combo 路由combo.ts19 种策略、comboConfig.ts、comboMetrics.ts、comboAgentMiddleware.tsAuto Combo 引擎autoCombo/engine.ts、scoring.ts、taskFitness.ts、virtualFactory.ts、modePacks.ts、selfHealing.ts等弹性/回退accountFallback.ts冷却 锁定、errorClassifier.ts、emergencyFallback.ts、rateLimitManager.ts、accountSelector.ts配额quotaMonitor.ts、quotaPreflight.ts、各*QuotaFetcher.ts、openrouterFreeWindow.ts、antigravityCredits.ts缓存reasoningCache.ts、searchCache.ts、signatureCache.ts、requestDedup.ts路由智能intentClassifier.ts、taskAwareRouter.ts、wildcardRouter.ts、workflowFSM.ts、specificityDetector.ts模型处理model.ts、provider.ts、modelCapabilities.ts、modelDeprecation.ts、modelFamilyFallback.ts、payloadRules.tsToken 与会话tokenRefresh.ts、sessionManager.ts、contextManager.ts、systemPrompt.ts、thinkingBudget.ts压缩compression/完整压缩引擎接线IP / 网络ipFilter.ts、webSearchFallback.tsToken 刷新去重tokenRefresh.ts为每个提供商处理 OAuth 刷新Google、Claude、Codex、GitHub 双 token、Kiro 的 AWS SSO OIDC Social Auth并通过refreshPromiseCache对并发请求做 in-flight promise 去重账号回退状态机当提供商返回 429/401/500 时系统可切换到下一个账号并施加指数退避冷却Combo 模型链一个 combo 把多个provider/model字符串分组首个失败自动切换下一个5.5 Translatoropen-sse/translator/—— 格式翻译引擎采用自注册插件系统。当前仓库的翻译器构成英文原版文档9 个请求翻译器translator/request/antigravity-to-openai、claude-to-gemini、claude-to-openai、gemini-to-openai、openai-responses、openai-to-claude、openai-to-cursor、openai-to-gemini、openai-to-kiro9 个响应翻译器translator/response/claude-to-openai、cursor-to-openai、gemini-to-claude、gemini-to-openai、kiro-to-openai、openai-responses、openai-to-antigravity、openai-to-claude等9 个辅助模块translator/helpers/claudeHelper、geminiHelper、maxTokensHelper、openaiHelper、responsesApiHelper、toolCallHelper、schemaCoercion等顶层bootstrap.ts、formats.ts、registry.ts、index.ts自注册插件设计与源码一致见 open-sse/translator/index.ts 的bootstrapTranslatorRegistry()与register导出// 每个翻译器文件在 import 时调用 register() 注册自己 import { register } from ../registry.js; register(claude, openai, translateClaudeToOpenAI); // bootstrap.ts 导入所有翻译器文件触发注册 import ./request/claude-to-openai.js; // ← 自注册5.6 Utilsopen-sse/utils/—— 流式原语与提供商辅助文件用途stream.tsSSE Transform Stream——管道式流式核心。两种模式TRANSLATE完整格式翻译与PASSTHROUGH规范化 用量抽取。含 chunk 缓冲、用量估算、内容长度跟踪per-stream 的 encoder/decoder 实例避免共享状态streamHelpers.ts底层 SSE 工具parseSSELine容忍空白、hasValuableContent过滤空 chunk、fixInvalidId、formatSSE格式敏感的 SSE 序列化并清理perf_metricsusageTracking.ts从任意格式Claude/OpenAI/Gemini/Responses抽取 token 用量按 tool/message 使用独立字符-token 比率估算并追加安全缓冲2000 token过滤格式特有字段ANSI 彩色控制台输出bypassHandler.ts拦截 Claude CLI 的特定模式标题抽取、预热、计数不调用任何提供商直接返回伪响应。同时支持流式与非流式。刻意限定在 Claude CLI 范围内networkProxy.ts解析指定提供商的出口代理 URL优先级提供商特定配置 → 全局配置 → 环境变量HTTPS_PROXY/HTTP_PROXY/ALL_PROXY。支持NO_PROXY例外配置缓存 30 天error.ts构建错误响应OpenAI 兼容格式、解析上游错误、从错误信息抽取 Antigravity 的重试时间、SSE 错误流式化SSE 流式管道请求日志会话结构翻译中间态可观测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 chunk流式 ├── 5_res_provider.json ← 提供商响应非流式 ├── 6_res_openai.txt ← OpenAI 中间 chunk ├── 7_res_client.txt ← 面向客户端的 SSE chunk └── 6_error.json ← 错误详情若有6. 应用层src/—— Next.js 应用目录用途src/app/App Router 页面 API 路由src/lib/核心库DB、auth、OAuth、skills、memory 等src/domain/纯领域层策略、回退、成本、锁定等无 I/Osrc/server/仅服务端模块authz、cors、auth禁止从客户端组件导入src/shared/类型、常量、校验、契约、工具跨边界安全src/mitm/CLI 集成的中间人代理辅助src/models/本地模型元数据 / 别名src/sse/仍留在src/下的旧版 SSE handler不在open-sse/src/store/客户端状态存储重要 API 路由组src/app/api/auth/、admin/、combos/、compression/、context/、health/、keys/、logs/、mcp/、memory/、models/、oauth/、providers/、rate-limits/、resilience/、sessions/、settings/、skills/、sync/、tunnels/、upstream-proxy/、usage/、v1/OpenAI 兼容公共 API、v1beta/Gemini 风格兼容、webhooks/等。/v1/OpenAI 兼容公共 API覆盖完整能力面chat/completions主端点、completions、embeddings、images/{edits,generations}、audio/{speech,transcriptions}、batches、files、moderations、rerank、responses/[...path]Responses API 兜底路由、search、videos、wsWebSocket 桥等。每个路由文件遵循同一模式Route → CORS preflight → Zod body 校验 → 可选认证 → API key 策略强制 → handler 委托open-sse数据库层src/lib/db/单例 SQLitegetDbInstance()incore.tsWAL 日志模式。规则绝不在路由或 handler 中写裸 SQL——一律通过这些领域模块。领域模块每个负责一张或多张表apiKeys.ts、backup.ts、combos.ts、compression.ts、models.ts、providers.ts、settings.ts、usageHistory.ts、webhooks.ts等 40 个。migrations/下存放168 个版本化.sql文件幂等、事务化启动时由migrationRunner.ts执行累计创建 123 张表含call_logs、routing_decisions、domain_circuit_breakers、semantic_cache、FTS5 内存搜索虚拟表等。领域层src/domain/纯业务逻辑、无 I/OpolicyEngine.ts顶层策略解析、fallbackPolicy.ts回退决策树、costRules.ts成本计算规则、lockoutPolicy.ts模型锁定决策、comboResolver.ts组合解析、modelAvailability.ts模型可用性检查、quotaCache.ts缓存配额决策等。7. 主要设计模式总结Hub-and-Spoke 翻译所有格式经 OpenAI 中枢转换。新增一个提供商只需写一对翻译器到/从 OpenAI而非 N 对。Executor 上的 Strategy 模式每个提供商有继承BaseExecutor的特化 executor 类executors/index.ts的 factory 在运行时选择正确的类当前 108 个。自注册插件系统翻译器模块在 import 时通过register()自注册。新增翻译器只需创建文件并导入它。指数退避账号回退提供商返回 429/401/500 时切换下一账号施加指数冷却1s → 2s → 4s → 上限 2min。Combo 模型链一个 combo 分组多个provider/model首个失败自动切换下一个。带状态流式翻译响应翻译在 SSE chunk 间维护状态thinking block 跟踪、tool call 累积、内容块索引通过initState()机制实现。用量安全缓冲向客户端上报的用量额外加 2000 token 缓冲防止 system prompt 与格式翻译的开销导致客户端触达上下文窗口上限。8. 支持的格式与提供商格式标识符来自open-sse/translator/formats.ts格式方向IdentifierOpenAI Chat Completions源 目标openaiOpenAI Responses API源 目标openai-responsesAnthropic Claude源 目标claudeGoogle Gemini源 目标geminiAntigravity源 目标antigravityAWS Kiro仅目标kiroCursor仅目标cursor提供商与认证方式节选提供商认证方式Executor主要说明Anthropic ClaudeAPI Key 或 OAuthDefault使用x-api-keyheaderGoogle GeminiAPI Key 或 OAuthDefault使用x-goog-api-keyheaderAntigravityOAuthAntigravity多 URL 替换、自定义重试解析OpenAIAPI KeyDefault标准 Bearer 认证CodexOAuthCodex注入系统指令、管理思考GitHub CopilotOAuth Copilot tokenGithub双 token、模拟 VSCode headerKiro (AWS)AWS SSO OIDC 或 SocialKiro二进制 EventStream 解析Cursor IDEChecksum 认证CursorProtobuf 编码、SHA-256 checksumQwen / QoderOAuthDefault标准 / 双 header 认证OpenRouterAPI KeyDefault标准 Bearer 认证GLM、Kimi、MiniMaxAPI KeyDefaultClaude 兼容、使用x-api-keyopenai-compatible-*API KeyDefault动态任意 OpenAI 兼容端点anthropic-compatible-*API KeyDefault动态任意 Claude 兼容端点9. 数据流总结请求管线完整管线对应 docs/architecture/CODEBASE_DOCUMENTATION.md 第 9 节客户端请求 → /v1/chat/completions (route.ts) CORS preflight 检查 Zod 校验shared/validation/schemas.ts 的 chatCompletionsSchema 认证extractApiKey isValidApiKey 或 requireManagementAuth 策略引擎src/server/authz/pipeline.ts GuardrailsPII 掩码、提示注入、vision bridge → handleChatCore()open-sse/handlers/chatCore.ts 缓存检查语义缓存 读取缓存 限流rateLimitManager、accountSemaphore Combo 路由若模型解析为 combo comboResolver → 逐 target 循环 → handleSingleModel() translateRequest()open-sse/translator/request/* getExecutor(providerId).execute()open-sse/executors/* fetch 上游 → 经 accountFallback 重试/退避 translateResponse()open-sse/translator/response/* SSE 流或 JSON 响应 若为 Responses API经 open-sse/transformer/responsesTransformer.ts 的 TransformStream → 合规审计src/lib/compliance/ → 响应给客户端流式请求非流式请求Claude CLI Bypass 流程运行时弹性状态三重机制机制作用域位置Provider 熔断器整个 providersrc/shared/utils/circuitBreaker.ts持久化于domain_circuit_breakers表连接冷却单个账号/密钥src/sse/services/auth.ts的markAccountUnavailable()accountFallback.checkFallbackError()消费模型锁定Provider 连接 模型open-sse/services/accountFallback.ts持久化于domain_lockout_state表详见 RESILIENCE_GUIDE.md。10. 如何贡献四条标准路径新增一个 Provider在src/shared/constants/providers.ts注册加载时经 Zod 校验。若需要自定义逻辑在open-sse/executors/新增 executor继承BaseExecutor。若提供商不讲 OpenAI 格式在open-sse/translator/新增翻译器。若基于 OAuth在src/lib/oauth/providers/与src/lib/oauth/services/增加配置。在open-sse/config/providerRegistry.ts或open-sse/config/下按格式划分的注册表注册模型。在tests/unit/写测试。新增一个 API 路由创建src/app/api/your-route/route.ts。遵循模式CORS → Zod body 校验 → 认证 → handler 委托。若为新的请求形状在src/shared/validation/schemas.ts添加 Zod schema。若仅限管理端将路径加入src/shared/constants/publicApiRoutes.ts公共 API 面的 denylist。在tests/unit/添加测试。更新docs/reference/API_REFERENCE.md与docs/openapi.yaml。新增一个 DB 模块创建src/lib/db/yourModule.ts从./core.ts导入getDbInstance()。为你的领域导出 CRUD 函数。若需新表在src/lib/db/migrations/添加迁移文件顺序编号、幂等、事务化。调用方直接从/lib/db/yourModule导入旧版localDb.tsre-export 层已移除禁止 barrel-import。在tests/unit/添加测试。新增一个 MCP 工具在open-sse/mcp-server/tools/添加工具定义或扩展open-sse/mcp-server/schemas/tools.ts。在src/shared/constants/mcpScopes.ts分配相应 scope。在open-sse/mcp-server/server.ts注册工具。在open-sse/mcp-server/__tests__/添加测试。更新 MCP-SERVER.md。当前open-sse/mcp-server/提供110 个唯一工具、3 种传输stdio、HTTP Streamable、SSE与33 个运行时强制 scope基础列表见src/shared/constants/mcpScopes.ts审计表mcp_tool_audit记录调用。完整目录见 MCP-SERVER.md。11. 工程规范与硬性规则编码风格2 空格缩进、双引号、100 字符行宽、分号、es5 尾逗号Prettier lint-staged 强制。导入顺序外部 → 内部/、omniroute/open-sse→ 相对。命名文件camelCase或kebab-case组件PascalCase常量UPPER_SNAKE。提交Conventional Commits允许 scopedb、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。分支feat/、fix/、refactor/、docs/、test/、chore/前缀禁止直接提交main。硬性规则源自 CLAUDE.md绝不提交密钥或凭据。禁止 barrel-import直接使用具体src/lib/db/*模块。绝不用eval()/new Function()/ 隐含 eval。绝不直接提交main。绝不在路由中写裸 SQL一律走src/lib/db/模块。绝不在 SSE 流中静默吞错。一律用 Zod schema 校验输入。修改生产代码必须带测试。覆盖率必须保持 ≥ 60%statements、lines、functions、branches。Husky 钩子pre-commit 运行lint-stagedcheck:docs-synccheck:any-budget:t11pre-push 运行check:any-budget:t11check:tracked-artifacts快速门禁不含test:unit。测试命令见 package.json命令运行内容npm run test:unit全部tests/unit/*.test.tsNode 测试运行器并发 10npm run test:vitestVitest 套件MCP、autoCombo、cachenpm run test:e2ePlaywright UI 套件npm run test:protocols:e2eMCP A2A 协议 e2enpm run test:coverage覆盖率门禁≥60% lines/statements/functions/branchesnode --import tsx/esm --test tests/unit/file.test.ts单文件运行12. 延伸阅读ARCHITECTURE.md — 高层架构与各子系统设计动机API_REFERENCE.md — 公共与管理 API 参考FEATURES.md — 功能矩阵与版本亮点RESILIENCE_GUIDE.md — 熔断器、冷却、锁定深入解析AUTO-COMBO.md — Auto Combo 评分与策略MCP-SERVER.md — 完整 MCP 工具目录与传输A2A-SERVER.md — A2A 协议技能与发现COMPRESSION_GUIDE.md — RTK Caveman 压缩TROUBLESHOOTING.md — 常见运维问题CONTRIBUTING.md — 贡献者工作流AGENTS.md — 供 Agent 使用的深层架构参考CLAUDE.md — Claude Code 仓库规则诸多约定的权威来源本文基于仓库文档与源码撰写其中源码路径、文件与目录结构均以当前仓库实际内容为准版本 v3.8.51。各链接可直接在仓库中继续深入阅读对应实现。【免费下载链接】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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考