OmniRoute 贡献指南从本地开发环境搭建到新增 AI Provider 的完整实战流程【免费下载链接】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/OmniRouteOmniRoute 是一个开源的统一 AI 网关MIT License通过单一端点聚合数百家 AI Provider 并提供配额感知的自动故障转移、RTKCaveman 上下文压缩、MCP/A2A 协议支持等功能。本文是面向开发者的完整贡献指南覆盖从环境准备、本地调试、Git 工作流、测试与覆盖率门槛到新增一个 AI Provider的全链路实操步骤并以仓库源码为佐证说明每一步背后真实存在的模块与调用关系。读完本文你可以独立完成一次从 fork、开发、测试到提交 PR 的 OmniRoute 贡献闭环。开发环境搭建环境要求Prerequisites贡献 OmniRoute 需要以下基础工具链Node.js版本要求为18 24推荐 22 LTS。需要注意当前仓库 package.json 中engines字段实际标注的是22.22.2 23 || 24.0.0 27即新版本对运行时下限有所收紧开发时建议以仓库engines声明为准npm10Git用于分支管理与提交流程。克隆与安装Clone Installgit clone https://gitcode.com/GitHub_Trending/om/OmniRoute.git cd OmniRoute npm install仓库采用 npm workspaces 组织子包见 package.json工作区包含open-sse与packages/browser-pool因此npm install会一并安装所有工作区依赖。若使用 Node 24 自带的 npm v11安装后建议验证原生模块是否就绪node -e require(better-sqlite3)若报MODULE_NOT_FOUND可执行npm approve-scripts better-sqlite3 npm install重装详见 Troubleshooting。环境变量与 Dashboard 设置初始化 .env仓库根目录提供.env.example模板可直接参考 .env.example首次开发时执行# 从模板创建 .env cp .env.example .env # 生成所需密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env核心环境变量变量开发默认值说明PORT20128服务监听端口见 .env.exampleNEXT_PUBLIC_BASE_URLhttp://localhost:20128前端页面的基础 URLJWT_SECRET按上文生成JWT 签名密钥API_KEY_SECRET按上文生成API Key 加密/签名密钥INITIAL_PASSWORDCHANGEME首次登录密码见 .env.exampleAPP_LOG_LEVELinfo日志详细程度设为debug会连带开启更多调试输出见 .env.exampleDashboard 设置项部分功能既可通过环境变量配置也可在 Dashboard 界面中切换设置会持久化到数据库并在重启后保留一旦设置会覆盖环境变量默认值设置位置开关说明Settings → AdvancedDebug Mode开启调试请求日志UI 层面控制Settings → GeneralSidebar Visibility显示/隐藏侧边栏分区本地运行# 开发模式热重载 npm run dev # 生产构建 npm run build npm run start # 常见端口配置组合 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run devnpm run dev实际调用的是node scripts/dev/run-next.mjs dev见 package.json底层基于 Next.js 16 App Router 开发服务器并预设较大堆内存上限。启动后的默认访问地址Dashboard 控制台http://localhost:20128/dashboardAPI 端点http://localhost:20128/v1Git 工作流重要禁止直接向main分支提交代码所有改动必须基于特性分支。git checkout -b feat/your-feature-name # ... 进行代码修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在代码托管平台创建 Pull Request分支命名规范前缀用途feat/新功能fix/缺陷修复refactor/代码重构docs/文档变更test/测试新增/修复chore/工具链、CI、依赖维护Commit Message 规范遵循 Conventional Commits 约定式提交推荐格式示例feat: add circuit breaker for provider calls fix: resolve JWT secret validation edge case docs: update SECURITY.md with PII protection test: add observability unit tests refactor(db): consolidate rate limit tables推荐使用的scope作用域db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。仓库同时使用changelog.d/目录按变更类型features/、fixes/、maintenance/存放带编号的变更片段用户可见的功能变更需要在发布前汇总进 CHANGELOG.md。运行测试与覆盖率门槛测试命令全家桶# 全部测试单元 vitest 生态兼容 e2e npm run test:all # 单个测试文件Node.js 原生测试运行器多数测试走这条路径 node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest 专项MCP server、autoCombo、cache 等 npm run test:vitest # E2E 测试需要 Playwright npm run test:e2e # 协议客户端 E2EMCP transports、A2A npm run test:protocols:e2e # 生态兼容性测试 npm run test:ecosystem # 覆盖率门槛statements/lines/functions/branches 均不低于 60% npm run test:coverage npm run coverage:report # Lint 格式检查 npm run lint npm run check对照 package.json 可以看到单元测试使用node --testtsx/esm组合配合tests/_setup/isolateDataDir.ts隔离数据目录、open-sse/utils/setupPolyfill.ts提供 polyfill测试按tests/unit/下的api、auth、db、mcp、memory、translator、usage等子目录分派还提供 CI 分片--test-shard与并发控制。覆盖率规则说明npm run test:coverage基于 c8 度量源码覆盖率--excludetests/**排除测试自身包含open-sse/**四类指标均要求 60% 以上才通过PR 必须将整体覆盖率维持在statements/lines/functions/branches ≥ 60%若 PR 改动了src/、open-sse/、electron/或bin/中的生产代码必须在同一 PR 内补充或更新自动化测试npm run coverage:report输出最新一次覆盖率运行的逐文件明细npm run test:coverage:legacy保留旧口径用于历史对比旧口径会把open-sse排除在外、数值偏高仅作参考分阶段覆盖率提升路线图详见 docs/ops/COVERAGE_PLAN.mdPhase 1–560%→80%已完成当前处于 Phase 6≥85%与 Phase 7≥90%阶段。测试覆盖的业务领域当前单元测试已覆盖如下核心能力域Provider 格式转换器translator与格式互转限流、熔断circuit breaker与韧性机制语义缓存、幂等性、进度追踪数据库操作与 schema覆盖 21 个 DB 模块src/lib/db/实际包含约 125 个顶层模块与 170 个迁移文件OAuth 流程与认证API 端点校验Zod v4MCP server 工具与作用域scope强制Memory 与 Skills 系统PR 提交前要求运行npm run test:unit运行npm run test:coverage保证四项覆盖率指标 ≥ 60%生产代码有改动时在 PR 描述中列出新增或变更的测试文件若 CI 中配置了项目密钥检查 PR 上的 SonarQube 结果代码风格规范ESLint提交前必须运行npm run lint。仓库使用 ESLint 10 与扁平配置见 eslint.config.mjs并通过 config/quality/eslint-suppressions.json 管理豁免项Prettier提交时由lint-staged自动格式化见 package.json规则为2 空格缩进、分号、双引号、行宽 100 字符、ES5 trailing commasTypeScriptsrc/下所有代码使用.ts/.tsxopen-sse/下使用.ts/.js公共函数需编写 TSDocparam、returns、throws禁止eval()ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验所有 API 入参校验统一使用 Zod v4 schema命名约定文件使用 camelCase/kebab-caseReact 组件使用 PascalCase常量使用 UPPER_SNAKE。项目结构仓库采用核心网关 open-sse 子包 Electron 桌面端的分层结构结构细节以当前仓库实际布局为准src/ # TypeScript.ts / .tsx ├── app/ # Next.js 16 App Router含 103 个 api 路由目录、dashboard 页面等 ├── domain/ # 策略引擎policyEngine、comboResolver、costRules、fallbackPolicy 等 ├── lib/ # 核心业务逻辑 │ ├── a2a/ # Agent-to-Agent v0.3 协议服务 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 数据层约 125 个顶层模块 170 个迁移 │ ├── memory/ # 持久化对话记忆 │ ├── oauth/ # OAuth Provider 常量与业务服务 │ ├── skills/ # 可扩展技能框架 │ └── usage/ # 用量追踪与成本计算 ├── middleware/ # 请求中间件如 promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ # 共享代码 │ ├── constants/ # Provider 定义、MCP scopes、路由策略 │ ├── utils/ # 熔断器、清理器、认证辅助 │ └── validation/ # Zod v4 schema └── sse/ # SSE 代理管线 open-sse/ # omniroute/open-sse 工作区 ├── config/ # providerRegistryProvider 注册表单一事实来源 ├── executors/ # 各 Provider 执行器实现模块 ├── handlers/ # 请求处理器chat、responses、embeddings、images 等 ├── mcp-server/ # MCP server含 scopeEnforcement、toolSearch、server.ts 等 ├── services/ # 服务层combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式转换器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 转换器 └── utils/ # 流、TLS、代理、日志等工具 electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 原生测试运行器 ├── integration/ # 集成测试 ├── e2e/ # Playwright 端到端测试 ├── security/ # 安全测试 ├── translator/ # 转换器专项测试 └── load/ # 压测 docs/ # 文档 ├── architecture/ARCHITECTURE.md # 系统架构 ├── reference/API_REFERENCE.md # 全部端点 ├── guides/USER_GUIDE.md # Provider 配置与 CLI 集成 ├── guides/TROUBLESHOOTING.md # 常见问题 ├── frameworks/MCP-SERVER.md # MCP server ├── frameworks/A2A-SERVER.md # A2A 代理协议 ├── getting-started/AUTO-COMBO-GUIDE.md # Auto-combo 引擎 ├── ops/COVERAGE_PLAN.md # 测试覆盖率提升计划 └── openapi.yaml # OpenAPI 规范注意src/lib/localDb.ts是纯再导出层re-export only严禁在其中添加业务逻辑。新增一个 AI Provider六步走新增 Provider 是 OmniRoute 最常见的贡献类型之一官方流程分为六步Step 1注册 Provider 常量在src/shared/constants/providers.ts中登记 Provider 常量。该模块在加载时通过validateProviders来自 src/shared/validation/providerSchema.ts做 Zod 校验。从源码看Provider 按认证方式分为多个集合providers.ts 中导入了NOAUTH_PROVIDERS、OAUTH_PROVIDERS、WEB_COOKIE_PROVIDERS、APIKEY_PROVIDERS、LOCAL_PROVIDERS、SEARCH_PROVIDERS、AUDIO_ONLY_PROVIDERS、UPSTREAM_PROXY_PROVIDERS、CLOUD_AGENT_PROVIDERS、SYSTEM_PROVIDERS新增 Provider 时应根据其认证形态选择对应的集合文件登记并注意是否属于免 Key 白名单FREE_APIKEY_PROVIDER_IDS或双认证 ProviderDUAL_AUTH_PROVIDER_IDS见 providers.ts。Step 2添加 Executor需要自定义逻辑时若该 Provider 需要自定义请求/响应处理逻辑在open-sse/executors/下创建your-provider.ts并继承基础执行器open-sse/executors/base.ts。仓库中已存在大量示例例如azure-openai.ts、bedrock.ts、cloudflare-ai.ts、claude-web.ts等见 open-sse/executors可参照同类 Provider 的实现模式。Step 3添加 Translator非 OpenAI 格式时若 Provider 使用非 OpenAI 兼容的请求/响应格式需要在open-sse/translator/下创建请求/响应转换器。该目录已按 request/response 拆分子目录并提供registry.ts注册机制见 open-sse/translator转换器负责完成 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 之间的格式互转。Step 4配置 OAuth基于 OAuth 时若 Provider 走 OAuth 认证需要在src/lib/oauth/constants/oauth.ts中添加 OAuth 凭据配置并在src/lib/oauth/services/下新增对应服务。仓库的 OAuth 常量文件已内置多家 Provider 的客户端配置见 src/lib/oauth/constants/oauth.ts新增时应保持一致的 schema 与错误处理约定。Step 5注册模型在open-sse/config/providerRegistry.ts中添加模型定义。该文件是所有 Provider 配置的单一事实来源见 providerRegistry.ts通过REGISTRY聚合open-sse/config/providers/下按 Provider 拆分的注册表条目并基于RegistryModel、RegistryOAuth、RegistryEntry等类型描述 baseUrl、模型上下文长度、能力位reasoning、codex capabilities 等。添加后还可运行npm run gen:provider-reference与各类check:provider-*脚本验证一致性。Step 6补充测试在tests/unit/中编写单元测试至少覆盖Provider 注册注册表条目可正确解析、Zod 校验通过请求/响应格式转换translator 往返转换正确错误处理上游异常、超时、限流时的行为符合预期新增 Provider 或改动src/、open-sse/生产代码时测试必须与生产代码处于同一 PR见上文 PR 要求。Pull Request 检查清单提交 PR 前逐项确认测试通过npm testLint 通过npm run lint构建成功npm run build新公开函数与接口已补充 TypeScript 类型无硬编码密钥或 fallback 值所有输入均已使用 Zod schema 校验涉及用户可见变更时已更新 CHANGELOG涉及文档时已同步更新文档发布流程版本发布由/generate-release工作流驱动当代码托管平台创建新的 GitHub Release 后GitHub Actions 会自动将构建产物发布到 npm仓库npm-publish.yml、docker-publish.yml、electron-release.yml等工作流共同支撑发布链路见 .github/workflows可对照 scripts/release 下的聚合与校验脚本了解发布细节。获取帮助系统架构见 docs/architecture/ARCHITECTURE.mdAPI 参考见 docs/reference/API_REFERENCE.md贡献 Golden Path仓库根目录的 CONTRIBUTING.md 还指向 docs/ops/CONTRIBUTION_GOLDEN_PATH.md它将 provider、routing、UI/UX、i18n、CLI、数据库与构建部署类改动分别映射到对应契约、聚焦测试、CI 覆盖与对账步骤是逐变更执行的官方路径架构决策记录ADR在既有文档索引中可通过 docs/architecture 目录下的 meta.json 与各类设计文档追踪架构决策的历史脉络从克隆仓库、跑通本地 Dashboard到理解 Provider 注册表、翻译器、执行器与 OAuth 模块之间的协作关系再到用覆盖率为 60% 门槛兜底的测试体系交付一个全新 Provider——以上就是 OmniRoute 贡献者的完整技术路径。遵循本文的流程与代码风格约束你的改动就能顺畅通过 CI 各道质量关卡并合入主分支。【免费下载链接】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），仅供参考 OmniRoute 贡献指南：从本地开发环境搭建到新增 AI Provider 的完整实战流程
OmniRoute 贡献指南从本地开发环境搭建到新增 AI Provider 的完整实战流程【免费下载链接】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/OmniRouteOmniRoute 是一个开源的统一 AI 网关MIT License通过单一端点聚合数百家 AI Provider 并提供配额感知的自动故障转移、RTKCaveman 上下文压缩、MCP/A2A 协议支持等功能。本文是面向开发者的完整贡献指南覆盖从环境准备、本地调试、Git 工作流、测试与覆盖率门槛到新增一个 AI Provider的全链路实操步骤并以仓库源码为佐证说明每一步背后真实存在的模块与调用关系。读完本文你可以独立完成一次从 fork、开发、测试到提交 PR 的 OmniRoute 贡献闭环。开发环境搭建环境要求Prerequisites贡献 OmniRoute 需要以下基础工具链Node.js版本要求为18 24推荐 22 LTS。需要注意当前仓库 package.json 中engines字段实际标注的是22.22.2 23 || 24.0.0 27即新版本对运行时下限有所收紧开发时建议以仓库engines声明为准npm10Git用于分支管理与提交流程。克隆与安装Clone Installgit clone https://gitcode.com/GitHub_Trending/om/OmniRoute.git cd OmniRoute npm install仓库采用 npm workspaces 组织子包见 package.json工作区包含open-sse与packages/browser-pool因此npm install会一并安装所有工作区依赖。若使用 Node 24 自带的 npm v11安装后建议验证原生模块是否就绪node -e require(better-sqlite3)若报MODULE_NOT_FOUND可执行npm approve-scripts better-sqlite3 npm install重装详见 Troubleshooting。环境变量与 Dashboard 设置初始化 .env仓库根目录提供.env.example模板可直接参考 .env.example首次开发时执行# 从模板创建 .env cp .env.example .env # 生成所需密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env核心环境变量变量开发默认值说明PORT20128服务监听端口见 .env.exampleNEXT_PUBLIC_BASE_URLhttp://localhost:20128前端页面的基础 URLJWT_SECRET按上文生成JWT 签名密钥API_KEY_SECRET按上文生成API Key 加密/签名密钥INITIAL_PASSWORDCHANGEME首次登录密码见 .env.exampleAPP_LOG_LEVELinfo日志详细程度设为debug会连带开启更多调试输出见 .env.exampleDashboard 设置项部分功能既可通过环境变量配置也可在 Dashboard 界面中切换设置会持久化到数据库并在重启后保留一旦设置会覆盖环境变量默认值设置位置开关说明Settings → AdvancedDebug Mode开启调试请求日志UI 层面控制Settings → GeneralSidebar Visibility显示/隐藏侧边栏分区本地运行# 开发模式热重载 npm run dev # 生产构建 npm run build npm run start # 常见端口配置组合 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run devnpm run dev实际调用的是node scripts/dev/run-next.mjs dev见 package.json底层基于 Next.js 16 App Router 开发服务器并预设较大堆内存上限。启动后的默认访问地址Dashboard 控制台http://localhost:20128/dashboardAPI 端点http://localhost:20128/v1Git 工作流重要禁止直接向main分支提交代码所有改动必须基于特性分支。git checkout -b feat/your-feature-name # ... 进行代码修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在代码托管平台创建 Pull Request分支命名规范前缀用途feat/新功能fix/缺陷修复refactor/代码重构docs/文档变更test/测试新增/修复chore/工具链、CI、依赖维护Commit Message 规范遵循 Conventional Commits 约定式提交推荐格式示例feat: add circuit breaker for provider calls fix: resolve JWT secret validation edge case docs: update SECURITY.md with PII protection test: add observability unit tests refactor(db): consolidate rate limit tables推荐使用的scope作用域db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。仓库同时使用changelog.d/目录按变更类型features/、fixes/、maintenance/存放带编号的变更片段用户可见的功能变更需要在发布前汇总进 CHANGELOG.md。运行测试与覆盖率门槛测试命令全家桶# 全部测试单元 vitest 生态兼容 e2e npm run test:all # 单个测试文件Node.js 原生测试运行器多数测试走这条路径 node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest 专项MCP server、autoCombo、cache 等 npm run test:vitest # E2E 测试需要 Playwright npm run test:e2e # 协议客户端 E2EMCP transports、A2A npm run test:protocols:e2e # 生态兼容性测试 npm run test:ecosystem # 覆盖率门槛statements/lines/functions/branches 均不低于 60% npm run test:coverage npm run coverage:report # Lint 格式检查 npm run lint npm run check对照 package.json 可以看到单元测试使用node --testtsx/esm组合配合tests/_setup/isolateDataDir.ts隔离数据目录、open-sse/utils/setupPolyfill.ts提供 polyfill测试按tests/unit/下的api、auth、db、mcp、memory、translator、usage等子目录分派还提供 CI 分片--test-shard与并发控制。覆盖率规则说明npm run test:coverage基于 c8 度量源码覆盖率--excludetests/**排除测试自身包含open-sse/**四类指标均要求 60% 以上才通过PR 必须将整体覆盖率维持在statements/lines/functions/branches ≥ 60%若 PR 改动了src/、open-sse/、electron/或bin/中的生产代码必须在同一 PR 内补充或更新自动化测试npm run coverage:report输出最新一次覆盖率运行的逐文件明细npm run test:coverage:legacy保留旧口径用于历史对比旧口径会把open-sse排除在外、数值偏高仅作参考分阶段覆盖率提升路线图详见 docs/ops/COVERAGE_PLAN.mdPhase 1–560%→80%已完成当前处于 Phase 6≥85%与 Phase 7≥90%阶段。测试覆盖的业务领域当前单元测试已覆盖如下核心能力域Provider 格式转换器translator与格式互转限流、熔断circuit breaker与韧性机制语义缓存、幂等性、进度追踪数据库操作与 schema覆盖 21 个 DB 模块src/lib/db/实际包含约 125 个顶层模块与 170 个迁移文件OAuth 流程与认证API 端点校验Zod v4MCP server 工具与作用域scope强制Memory 与 Skills 系统PR 提交前要求运行npm run test:unit运行npm run test:coverage保证四项覆盖率指标 ≥ 60%生产代码有改动时在 PR 描述中列出新增或变更的测试文件若 CI 中配置了项目密钥检查 PR 上的 SonarQube 结果代码风格规范ESLint提交前必须运行npm run lint。仓库使用 ESLint 10 与扁平配置见 eslint.config.mjs并通过 config/quality/eslint-suppressions.json 管理豁免项Prettier提交时由lint-staged自动格式化见 package.json规则为2 空格缩进、分号、双引号、行宽 100 字符、ES5 trailing commasTypeScriptsrc/下所有代码使用.ts/.tsxopen-sse/下使用.ts/.js公共函数需编写 TSDocparam、returns、throws禁止eval()ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验所有 API 入参校验统一使用 Zod v4 schema命名约定文件使用 camelCase/kebab-caseReact 组件使用 PascalCase常量使用 UPPER_SNAKE。项目结构仓库采用核心网关 open-sse 子包 Electron 桌面端的分层结构结构细节以当前仓库实际布局为准src/ # TypeScript.ts / .tsx ├── app/ # Next.js 16 App Router含 103 个 api 路由目录、dashboard 页面等 ├── domain/ # 策略引擎policyEngine、comboResolver、costRules、fallbackPolicy 等 ├── lib/ # 核心业务逻辑 │ ├── a2a/ # Agent-to-Agent v0.3 协议服务 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 数据层约 125 个顶层模块 170 个迁移 │ ├── memory/ # 持久化对话记忆 │ ├── oauth/ # OAuth Provider 常量与业务服务 │ ├── skills/ # 可扩展技能框架 │ └── usage/ # 用量追踪与成本计算 ├── middleware/ # 请求中间件如 promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ # 共享代码 │ ├── constants/ # Provider 定义、MCP scopes、路由策略 │ ├── utils/ # 熔断器、清理器、认证辅助 │ └── validation/ # Zod v4 schema └── sse/ # SSE 代理管线 open-sse/ # omniroute/open-sse 工作区 ├── config/ # providerRegistryProvider 注册表单一事实来源 ├── executors/ # 各 Provider 执行器实现模块 ├── handlers/ # 请求处理器chat、responses、embeddings、images 等 ├── mcp-server/ # MCP server含 scopeEnforcement、toolSearch、server.ts 等 ├── services/ # 服务层combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式转换器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 转换器 └── utils/ # 流、TLS、代理、日志等工具 electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 原生测试运行器 ├── integration/ # 集成测试 ├── e2e/ # Playwright 端到端测试 ├── security/ # 安全测试 ├── translator/ # 转换器专项测试 └── load/ # 压测 docs/ # 文档 ├── architecture/ARCHITECTURE.md # 系统架构 ├── reference/API_REFERENCE.md # 全部端点 ├── guides/USER_GUIDE.md # Provider 配置与 CLI 集成 ├── guides/TROUBLESHOOTING.md # 常见问题 ├── frameworks/MCP-SERVER.md # MCP server ├── frameworks/A2A-SERVER.md # A2A 代理协议 ├── getting-started/AUTO-COMBO-GUIDE.md # Auto-combo 引擎 ├── ops/COVERAGE_PLAN.md # 测试覆盖率提升计划 └── openapi.yaml # OpenAPI 规范注意src/lib/localDb.ts是纯再导出层re-export only严禁在其中添加业务逻辑。新增一个 AI Provider六步走新增 Provider 是 OmniRoute 最常见的贡献类型之一官方流程分为六步Step 1注册 Provider 常量在src/shared/constants/providers.ts中登记 Provider 常量。该模块在加载时通过validateProviders来自 src/shared/validation/providerSchema.ts做 Zod 校验。从源码看Provider 按认证方式分为多个集合providers.ts 中导入了NOAUTH_PROVIDERS、OAUTH_PROVIDERS、WEB_COOKIE_PROVIDERS、APIKEY_PROVIDERS、LOCAL_PROVIDERS、SEARCH_PROVIDERS、AUDIO_ONLY_PROVIDERS、UPSTREAM_PROXY_PROVIDERS、CLOUD_AGENT_PROVIDERS、SYSTEM_PROVIDERS新增 Provider 时应根据其认证形态选择对应的集合文件登记并注意是否属于免 Key 白名单FREE_APIKEY_PROVIDER_IDS或双认证 ProviderDUAL_AUTH_PROVIDER_IDS见 providers.ts。Step 2添加 Executor需要自定义逻辑时若该 Provider 需要自定义请求/响应处理逻辑在open-sse/executors/下创建your-provider.ts并继承基础执行器open-sse/executors/base.ts。仓库中已存在大量示例例如azure-openai.ts、bedrock.ts、cloudflare-ai.ts、claude-web.ts等见 open-sse/executors可参照同类 Provider 的实现模式。Step 3添加 Translator非 OpenAI 格式时若 Provider 使用非 OpenAI 兼容的请求/响应格式需要在open-sse/translator/下创建请求/响应转换器。该目录已按 request/response 拆分子目录并提供registry.ts注册机制见 open-sse/translator转换器负责完成 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 之间的格式互转。Step 4配置 OAuth基于 OAuth 时若 Provider 走 OAuth 认证需要在src/lib/oauth/constants/oauth.ts中添加 OAuth 凭据配置并在src/lib/oauth/services/下新增对应服务。仓库的 OAuth 常量文件已内置多家 Provider 的客户端配置见 src/lib/oauth/constants/oauth.ts新增时应保持一致的 schema 与错误处理约定。Step 5注册模型在open-sse/config/providerRegistry.ts中添加模型定义。该文件是所有 Provider 配置的单一事实来源见 providerRegistry.ts通过REGISTRY聚合open-sse/config/providers/下按 Provider 拆分的注册表条目并基于RegistryModel、RegistryOAuth、RegistryEntry等类型描述 baseUrl、模型上下文长度、能力位reasoning、codex capabilities 等。添加后还可运行npm run gen:provider-reference与各类check:provider-*脚本验证一致性。Step 6补充测试在tests/unit/中编写单元测试至少覆盖Provider 注册注册表条目可正确解析、Zod 校验通过请求/响应格式转换translator 往返转换正确错误处理上游异常、超时、限流时的行为符合预期新增 Provider 或改动src/、open-sse/生产代码时测试必须与生产代码处于同一 PR见上文 PR 要求。Pull Request 检查清单提交 PR 前逐项确认测试通过npm testLint 通过npm run lint构建成功npm run build新公开函数与接口已补充 TypeScript 类型无硬编码密钥或 fallback 值所有输入均已使用 Zod schema 校验涉及用户可见变更时已更新 CHANGELOG涉及文档时已同步更新文档发布流程版本发布由/generate-release工作流驱动当代码托管平台创建新的 GitHub Release 后GitHub Actions 会自动将构建产物发布到 npm仓库npm-publish.yml、docker-publish.yml、electron-release.yml等工作流共同支撑发布链路见 .github/workflows可对照 scripts/release 下的聚合与校验脚本了解发布细节。获取帮助系统架构见 docs/architecture/ARCHITECTURE.mdAPI 参考见 docs/reference/API_REFERENCE.md贡献 Golden Path仓库根目录的 CONTRIBUTING.md 还指向 docs/ops/CONTRIBUTION_GOLDEN_PATH.md它将 provider、routing、UI/UX、i18n、CLI、数据库与构建部署类改动分别映射到对应契约、聚焦测试、CI 覆盖与对账步骤是逐变更执行的官方路径架构决策记录ADR在既有文档索引中可通过 docs/architecture 目录下的 meta.json 与各类设计文档追踪架构决策的历史脉络从克隆仓库、跑通本地 Dashboard到理解 Provider 注册表、翻译器、执行器与 OAuth 模块之间的协作关系再到用覆盖率为 60% 门槛兜底的测试体系交付一个全新 Provider——以上就是 OmniRoute 贡献者的完整技术路径。遵循本文的流程与代码风格约束你的改动就能顺畅通过 CI 各道质量关卡并合入主分支。【免费下载链接】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），仅供参考