OmniRoute 贡献指南从本地开发环境搭建到新增 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/OmniRoute本文以 docs/i18n/id/CONTRIBUTING.md印尼语版贡献指南与 CONTRIBUTING.md 英文版同源为骨架结合当前仓库的package.json、.env.example与源码目录结构展开。读者将掌握如何在本机搭建 OmniRoute 3.8.x 开发环境、如何按 Git 分支规范提交改动、如何运行与覆盖测试、如何遵循代码风格以及如何在 6 个步骤内为 OmniRoute 接入一个新的 AI Provider——这是参与这个由 550 贡献者共建的开源 AI 网关MIT 协议项目最核心的入门路径。1. 开发环境搭建Development SetupOmniRoute 是一个基于 Next.js 16 TypeScript 的全栈项目前后端同仓。参与开发的第一步是把仓库克隆到本地并跑通开发服务器。1.1 环境要求Prerequisites贡献指南明确要求以下工具链工具要求Node.js指南原文为 18 24推荐 22 LTS以当前仓库 package.json 的engines字段为准为22.22.2 23 || 24.0.0 27推荐 24 LTSnpm10Git任意现代版本版本说明贡献指南中的 Node 版本区间随版本演进收窄判断你本机 Node 是否受支持时应优先以仓库根目录 package.json 中engines字段的实际约束为准。此外npm install会触发 postinstall 脚本完成原生模块与运行时环境的准备。1.2 克隆与安装Clone Installgit clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install仓库使用 npm workspaces 组织多个子包见 package.json 的workspaces字段open-sse/与packages/browser-pool会在安装时一并解析依赖。1.3 环境变量配置Environment Variables首次运行前从模板创建.env并生成两个必需密钥# 从模板创建 .env cp .env.example .env # 生成必需密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env指南给出的开发期核心变量如下变量开发默认值说明PORT20128服务器端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端基础 URLJWT_SECRET按上方命令生成JWT 会话签名密钥INITIAL_PASSWORDCHANGEME首次登录密码APP_LOG_LEVELinfo日志详细程度这些变量在仓库根目录的 .env.example 中有完整、逐条注释的权威定义共 3114 行覆盖密钥、存储、网络、安全、路由策略、URL 与云同步、出站代理、CLI 集成、MCP/A2A 集成等十余个分区。可以印证的是JWT_SECRET用于src/lib/auth负责签发/校验所有已登录会话 CookieAPI_KEY_SECRET用于src/lib/db/apiKeys.ts负责对数据库中的 API Key 做静态加密INITIAL_PASSWORD仅在首次启动引导时生效首次登录后可在 Dashboard → Settings → Security 中修改APP_LOG_LEVEL为debug时会同时开启更多诊断日志。1.4 Dashboard 设置数据库持久化Dashboard 提供 UI 开关可以覆盖通过环境变量配置的同类功能设置位置开关说明Settings → AdvancedDebug Mode启用请求级调试日志UI 层Settings → GeneralSidebar Visibility显示/隐藏侧边栏分区这些设置写入 SQLite 数据库重启后依然保留一旦在 UI 中设置过就会覆盖环境变量的默认值。1.5 本地运行Running Locally# 开发模式热重载 npm run dev # 生产构建 npm run build npm run start # 常用端口配置 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run dev默认访问地址Dashboardhttp://localhost:20128/dashboardAPIhttp://localhost:20128/v1从 package.json 的 scripts 可以看到npm run dev实际执行node scripts/dev/run-next.mjs dev默认使用 Turbopack 打包OMNIROUTE_USE_TURBOPACK0可回退 webpacknpm run build走scripts/build/build-next-isolated.mjs产物经assembleStandalone组装到dist/。对仅涉及后端/API 的改动还可使用更快的npm run build:contributor仅做编译级校验不组装可分发产物。2. Git 工作流Git Workflow⚠️绝对禁止直接向main提交一律使用功能分支。git checkout -b feat/your-feature-name # ... 进行修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在 GitHub 上打开 Pull Request2.1 分支命名Branch Naming前缀用途feat/新功能fix/Bug 修复refactor/代码重构docs/文档变更test/新增/修复测试chore/工具链、CI、依赖2.2 提交信息Commit Messages遵循 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英文版 CONTRIBUTING 进一步扩展了providers、executors、translator、compression、guardrails、authz等 scope提交时以最新 CONTRIBUTING.md 为准。英文版指南还补充了一条硬性约定commit message 中不得出现Co-Authored-By尾注提交须以仓库所有者的 Git 身份单独呈现Hard Rule #16。参与合并前建议先阅读 docs/ops/BRANCHING_MODEL.mdrelease-per-branch tag-at-ship 的发布模型与 docs/ops/CONTRIBUTION_GOLDEN_PATH.md按变更类型映射契约、聚焦测试、CI 覆盖与对账步骤的贡献黄金路径。3. 运行测试Running Tests3.1 测试命令全览# 全部测试unit vitest ecosystem e2e npm run test:all # 单个测试文件Node.js 原生测试运行器——大多数测试采用此方式 node --import tsx/esm --test tests/unit/your-file.test.ts # VitestMCP 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 # 覆盖率语句/行/函数/分支 60% 门槛 npm run test:coverage npm run coverage:report # Lint 格式检查 npm run lint npm run check从 package.json 可以看到test:coverage通过c8执行参数--statements 60 --lines 60 --functions 60 --branches 60与指南的 60% 门槛完全一致tests/_setup/isolateDataDir.ts等 setup 模块会在测试启动时隔离数据目录避免测试污染开发者真实的 SQLite 数据库。3.2 覆盖率说明Coverage Notesnpm run test:coverage只统计主单元测试套件对应的源码覆盖排除tests/**并包含open-sse/**PR 必须将整体覆盖率维持在语句、行、函数、分支均 ≥ 60%若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码必须在同一 PR 内新增或更新自动化测试npm run coverage:report打印逐文件的详细报告npm run test:coverage:legacy保留旧指标用于历史对比渐进式覆盖率提升路线见 docs/ops/COVERAGE_PLAN.md。3.3 Pull Request 要求PR Requirements打开或合并 PR 之前运行npm run test:unit运行npm run test:coverage确保所有覆盖率指标保持在60%当生产代码发生变更时在 PR 描述中列出被修改或新增的测试文件当项目密钥在 CI 中配置后检查 PR 上的 SonarQube 结果。3.4 当前测试覆盖的主题截至贡献指南撰写时约 122 个单元测试文件覆盖了以下能力域随着版本演进tests/unit目录规模持续增长当前子树已包含数千个测试文件Provider 翻译器与格式转换限流rate limiting、熔断器circuit breaker与韧性resilience语义缓存、幂等性、进度跟踪数据库操作与 schema110 个顶层模块、130 个迁移OAuth 流程与认证API 端点校验Zod v4MCP server 工具与 scope 强制Memory 与 Skills 系统4. 代码风格Code StyleESLint— 提交前运行npm run lintPrettier— 通过lint-staged在提交时自动格式化2 空格缩进、分号、双引号、100 字符宽、es5 尾逗号TypeScript—src/下全部代码使用.ts/.tsxopen-sse/使用.ts/.js公共函数使用 TSDoc 注释param、returns、throws禁用eval()— ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验— 所有 API 输入校验统一使用 Zod v4 schema命名规范— 文件 camelCase/kebab-case、组件 PascalCase、常量 UPPER_SNAKE。5. 项目结构Project Structuresrc/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # Dashboard 页面23 个分区 │ ├── api/ # API 路由51 个目录 │ └── login/ # 认证页面 (.tsx) ├── domain/ # 策略引擎policyEngine、comboResolver、costRules 等 ├── lib/ # 核心业务逻辑 (.ts) │ ├── a2a/ # Agent-to-Agent v0.3 协议服务器 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 领域模块 130 个迁移 │ ├── memory/ # 持久会话记忆 │ ├── oauth/ # OAuth 提供商、服务与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量跟踪与成本计算 │ └── localDb.ts # 仅做 re-export 的层——严禁在此添加逻辑 ├── middleware/ # 请求中间件promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ │ ├── components/ # React 组件 (.tsx) │ ├── constants/ # Provider 定义329、MCP scope、19 种路由策略 │ ├── utils/ # 熔断器、清洗器、认证辅助 │ └── validation/ # Zod v4 schema └── sse/ # SSE 代理管道 open-sse/ # omniroute/open-sse workspace ├── executors/ # 89 个 executor 实现模块 ├── handlers/ # 11 个请求 handlerchat、responses、embeddings、images 等 ├── mcp-server/ # MCP 服务器107 个工具、3 种 transport、32 个 scope ├── services/ # 178 个顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 转换器 └── utils/ # 22 个工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 测试运行器122 个测试文件 ├── integration/ # 集成测试 ├── e2e/ # Playwright 测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档 ├── architecture/ # 系统架构 ├── reference/ # API 参考、环境变量、CLI 工具 ├── guides/ # 用户指南、Docker、安装、排障 ├── ops/ # 部署、代理、覆盖率、发布 └── ...以上目录树中标注的数字如 329 个 Provider、89 个 executor、107 个 MCP 工具随版本持续演进例如英文版 CONTRIBUTING.md 已更新为 1,574 个单元测试文件、MCP 110 个工具/33 个 scope 等。当前仓库tests/unit子树的真实规模数千个.ts/.tsx测试文件也远超指南撰写时的 122 个说明测试体系随功能扩张持续增长。6. 添加新 ProviderAdding a New Provider新增一个 Provider 是 OmniRoute 生态最常见的贡献场景贡献指南给出了标准的六步流程第 1 步注册 Provider 常量添加到src/shared/constants/providers.ts—— 该文件在模块加载时经 Zod 校验src/shared/constants/providers.ts 为仓库实际文件。第 2 步添加 Executor需要自定义逻辑时在open-sse/executors/your-provider.ts中创建 executor并继承基础 executor仓库中 89 个 executor 实现模块均位于 open-sse/executors 目录。第 3 步添加 Translator非 OpenAI 格式时在open-sse/translator/中创建请求/响应翻译器实现 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 等格式互转open-sse/translator 目录。第 4 步添加 OAuth 配置基于 OAuth 时在src/lib/oauth/constants/oauth.ts添加 OAuth 凭据在src/lib/oauth/services/添加服务。第 5 步注册模型在open-sse/config/providerRegistry.ts中添加模型定义open-sse/config/providerRegistry.ts 为仓库实际文件。第 6 步添加测试在tests/unit/编写单元测试至少覆盖Provider 注册请求/响应翻译错误处理安全补充来自英文版指南适配时请遵守若上游 Provider 在其公开 CLI/浏览器包里分发公共 OAuthclient_id/secret或 Firebase Web API key不得将其作为字符串字面量硬编码应使用resolvePublicCred()open-sse/utils/publicCreds.ts并在EMBEDDED_DEFAULTS中添加掩码字节条目完整流程见 docs/security/PUBLIC_CREDS.mdhandler/executor 中到达客户端的错误信息必须经过buildErrorBody()/sanitizeErrorMessage()open-sse/utils/error.ts禁止把原始err.stack/err.message放进响应体详见 docs/security/ERROR_SANITIZATION.md。7. Pull Request 检查清单PR Checklist测试通过npm testLint 通过npm run lint构建成功npm run build为新的公共函数和接口补充 TypeScript 类型无硬编码的密钥或回退值所有输入经 Zod schema 校验涉及用户可见变更时更新 CHANGELOG文档已更新如适用英文版指南进一步补充的硬性项还包括shell 命令exec/spawn通过env传递运行时值而非字符串插值用户可见变更在changelog.d/{features|fixes|maintenance}/PR-slug.md添加变更片段而不是直接改CHANGELOG.md见 changelog.d/README.md/api/mcp/、/api/cli-tools/runtime/等派生子进程的路由必须在src/server/authz/routeGuard.ts中归类为isLocalOnlyPath()Hard Rule #15见 docs/security/ROUTE_GUARD_TIERS.md。这些条目应并入你的最终 PR 检查。8. 发布流程与获取帮助Releasing Getting Help8.1 发布Releasing发布通过/generate-release工作流管理。当 GitHub Release 创建时包会经 GitHub Actions自动发布到 npm。部署相关细节如npm run build:release的干净重建与dist/BUILD_SHA哨兵文件可查阅 docs/ops/COVERAGE_PLAN.md 同目录下的部署文档。8.2 获取帮助Getting Help架构参见 docs/architecture/ARCHITECTURE.mdAPI 参考参见 docs/reference/API_REFERENCE.mdADR架构决策记录参见docs/下的架构决策记录文档结语这份贡献指南覆盖了 OmniRoute 从本地跑起来到提交一个 Provider 级改动的完整闭环环境变量以 .env.example 为权威契约、测试体系以 60% 覆盖率门槛与聚焦测试test:scoped等保证回归质量、代码规范由 ESLint/Prettier/lint-staged 自动化兜底、新增 Provider 有固定六步流程可循。无论你是想接入一个新模型服务商还是修复 SSE 管道、熔断器或 MCP 工具的一个缺陷沿着本文的路径出发就能以符合项目规范的方式把改动安全地合入这条永不停止编码的 AI 路由主干。【免费下载链接】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 贡献指南：从本地开发环境搭建到新增 Provider 的完整工程工作流
OmniRoute 贡献指南从本地开发环境搭建到新增 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/OmniRoute本文以 docs/i18n/id/CONTRIBUTING.md印尼语版贡献指南与 CONTRIBUTING.md 英文版同源为骨架结合当前仓库的package.json、.env.example与源码目录结构展开。读者将掌握如何在本机搭建 OmniRoute 3.8.x 开发环境、如何按 Git 分支规范提交改动、如何运行与覆盖测试、如何遵循代码风格以及如何在 6 个步骤内为 OmniRoute 接入一个新的 AI Provider——这是参与这个由 550 贡献者共建的开源 AI 网关MIT 协议项目最核心的入门路径。1. 开发环境搭建Development SetupOmniRoute 是一个基于 Next.js 16 TypeScript 的全栈项目前后端同仓。参与开发的第一步是把仓库克隆到本地并跑通开发服务器。1.1 环境要求Prerequisites贡献指南明确要求以下工具链工具要求Node.js指南原文为 18 24推荐 22 LTS以当前仓库 package.json 的engines字段为准为22.22.2 23 || 24.0.0 27推荐 24 LTSnpm10Git任意现代版本版本说明贡献指南中的 Node 版本区间随版本演进收窄判断你本机 Node 是否受支持时应优先以仓库根目录 package.json 中engines字段的实际约束为准。此外npm install会触发 postinstall 脚本完成原生模块与运行时环境的准备。1.2 克隆与安装Clone Installgit clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install仓库使用 npm workspaces 组织多个子包见 package.json 的workspaces字段open-sse/与packages/browser-pool会在安装时一并解析依赖。1.3 环境变量配置Environment Variables首次运行前从模板创建.env并生成两个必需密钥# 从模板创建 .env cp .env.example .env # 生成必需密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env指南给出的开发期核心变量如下变量开发默认值说明PORT20128服务器端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端基础 URLJWT_SECRET按上方命令生成JWT 会话签名密钥INITIAL_PASSWORDCHANGEME首次登录密码APP_LOG_LEVELinfo日志详细程度这些变量在仓库根目录的 .env.example 中有完整、逐条注释的权威定义共 3114 行覆盖密钥、存储、网络、安全、路由策略、URL 与云同步、出站代理、CLI 集成、MCP/A2A 集成等十余个分区。可以印证的是JWT_SECRET用于src/lib/auth负责签发/校验所有已登录会话 CookieAPI_KEY_SECRET用于src/lib/db/apiKeys.ts负责对数据库中的 API Key 做静态加密INITIAL_PASSWORD仅在首次启动引导时生效首次登录后可在 Dashboard → Settings → Security 中修改APP_LOG_LEVEL为debug时会同时开启更多诊断日志。1.4 Dashboard 设置数据库持久化Dashboard 提供 UI 开关可以覆盖通过环境变量配置的同类功能设置位置开关说明Settings → AdvancedDebug Mode启用请求级调试日志UI 层Settings → GeneralSidebar Visibility显示/隐藏侧边栏分区这些设置写入 SQLite 数据库重启后依然保留一旦在 UI 中设置过就会覆盖环境变量的默认值。1.5 本地运行Running Locally# 开发模式热重载 npm run dev # 生产构建 npm run build npm run start # 常用端口配置 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run dev默认访问地址Dashboardhttp://localhost:20128/dashboardAPIhttp://localhost:20128/v1从 package.json 的 scripts 可以看到npm run dev实际执行node scripts/dev/run-next.mjs dev默认使用 Turbopack 打包OMNIROUTE_USE_TURBOPACK0可回退 webpacknpm run build走scripts/build/build-next-isolated.mjs产物经assembleStandalone组装到dist/。对仅涉及后端/API 的改动还可使用更快的npm run build:contributor仅做编译级校验不组装可分发产物。2. Git 工作流Git Workflow⚠️绝对禁止直接向main提交一律使用功能分支。git checkout -b feat/your-feature-name # ... 进行修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在 GitHub 上打开 Pull Request2.1 分支命名Branch Naming前缀用途feat/新功能fix/Bug 修复refactor/代码重构docs/文档变更test/新增/修复测试chore/工具链、CI、依赖2.2 提交信息Commit Messages遵循 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英文版 CONTRIBUTING 进一步扩展了providers、executors、translator、compression、guardrails、authz等 scope提交时以最新 CONTRIBUTING.md 为准。英文版指南还补充了一条硬性约定commit message 中不得出现Co-Authored-By尾注提交须以仓库所有者的 Git 身份单独呈现Hard Rule #16。参与合并前建议先阅读 docs/ops/BRANCHING_MODEL.mdrelease-per-branch tag-at-ship 的发布模型与 docs/ops/CONTRIBUTION_GOLDEN_PATH.md按变更类型映射契约、聚焦测试、CI 覆盖与对账步骤的贡献黄金路径。3. 运行测试Running Tests3.1 测试命令全览# 全部测试unit vitest ecosystem e2e npm run test:all # 单个测试文件Node.js 原生测试运行器——大多数测试采用此方式 node --import tsx/esm --test tests/unit/your-file.test.ts # VitestMCP 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 # 覆盖率语句/行/函数/分支 60% 门槛 npm run test:coverage npm run coverage:report # Lint 格式检查 npm run lint npm run check从 package.json 可以看到test:coverage通过c8执行参数--statements 60 --lines 60 --functions 60 --branches 60与指南的 60% 门槛完全一致tests/_setup/isolateDataDir.ts等 setup 模块会在测试启动时隔离数据目录避免测试污染开发者真实的 SQLite 数据库。3.2 覆盖率说明Coverage Notesnpm run test:coverage只统计主单元测试套件对应的源码覆盖排除tests/**并包含open-sse/**PR 必须将整体覆盖率维持在语句、行、函数、分支均 ≥ 60%若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码必须在同一 PR 内新增或更新自动化测试npm run coverage:report打印逐文件的详细报告npm run test:coverage:legacy保留旧指标用于历史对比渐进式覆盖率提升路线见 docs/ops/COVERAGE_PLAN.md。3.3 Pull Request 要求PR Requirements打开或合并 PR 之前运行npm run test:unit运行npm run test:coverage确保所有覆盖率指标保持在60%当生产代码发生变更时在 PR 描述中列出被修改或新增的测试文件当项目密钥在 CI 中配置后检查 PR 上的 SonarQube 结果。3.4 当前测试覆盖的主题截至贡献指南撰写时约 122 个单元测试文件覆盖了以下能力域随着版本演进tests/unit目录规模持续增长当前子树已包含数千个测试文件Provider 翻译器与格式转换限流rate limiting、熔断器circuit breaker与韧性resilience语义缓存、幂等性、进度跟踪数据库操作与 schema110 个顶层模块、130 个迁移OAuth 流程与认证API 端点校验Zod v4MCP server 工具与 scope 强制Memory 与 Skills 系统4. 代码风格Code StyleESLint— 提交前运行npm run lintPrettier— 通过lint-staged在提交时自动格式化2 空格缩进、分号、双引号、100 字符宽、es5 尾逗号TypeScript—src/下全部代码使用.ts/.tsxopen-sse/使用.ts/.js公共函数使用 TSDoc 注释param、returns、throws禁用eval()— ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验— 所有 API 输入校验统一使用 Zod v4 schema命名规范— 文件 camelCase/kebab-case、组件 PascalCase、常量 UPPER_SNAKE。5. 项目结构Project Structuresrc/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # Dashboard 页面23 个分区 │ ├── api/ # API 路由51 个目录 │ └── login/ # 认证页面 (.tsx) ├── domain/ # 策略引擎policyEngine、comboResolver、costRules 等 ├── lib/ # 核心业务逻辑 (.ts) │ ├── a2a/ # Agent-to-Agent v0.3 协议服务器 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 领域模块 130 个迁移 │ ├── memory/ # 持久会话记忆 │ ├── oauth/ # OAuth 提供商、服务与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量跟踪与成本计算 │ └── localDb.ts # 仅做 re-export 的层——严禁在此添加逻辑 ├── middleware/ # 请求中间件promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ │ ├── components/ # React 组件 (.tsx) │ ├── constants/ # Provider 定义329、MCP scope、19 种路由策略 │ ├── utils/ # 熔断器、清洗器、认证辅助 │ └── validation/ # Zod v4 schema └── sse/ # SSE 代理管道 open-sse/ # omniroute/open-sse workspace ├── executors/ # 89 个 executor 实现模块 ├── handlers/ # 11 个请求 handlerchat、responses、embeddings、images 等 ├── mcp-server/ # MCP 服务器107 个工具、3 种 transport、32 个 scope ├── services/ # 178 个顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 转换器 └── utils/ # 22 个工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 测试运行器122 个测试文件 ├── integration/ # 集成测试 ├── e2e/ # Playwright 测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档 ├── architecture/ # 系统架构 ├── reference/ # API 参考、环境变量、CLI 工具 ├── guides/ # 用户指南、Docker、安装、排障 ├── ops/ # 部署、代理、覆盖率、发布 └── ...以上目录树中标注的数字如 329 个 Provider、89 个 executor、107 个 MCP 工具随版本持续演进例如英文版 CONTRIBUTING.md 已更新为 1,574 个单元测试文件、MCP 110 个工具/33 个 scope 等。当前仓库tests/unit子树的真实规模数千个.ts/.tsx测试文件也远超指南撰写时的 122 个说明测试体系随功能扩张持续增长。6. 添加新 ProviderAdding a New Provider新增一个 Provider 是 OmniRoute 生态最常见的贡献场景贡献指南给出了标准的六步流程第 1 步注册 Provider 常量添加到src/shared/constants/providers.ts—— 该文件在模块加载时经 Zod 校验src/shared/constants/providers.ts 为仓库实际文件。第 2 步添加 Executor需要自定义逻辑时在open-sse/executors/your-provider.ts中创建 executor并继承基础 executor仓库中 89 个 executor 实现模块均位于 open-sse/executors 目录。第 3 步添加 Translator非 OpenAI 格式时在open-sse/translator/中创建请求/响应翻译器实现 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 等格式互转open-sse/translator 目录。第 4 步添加 OAuth 配置基于 OAuth 时在src/lib/oauth/constants/oauth.ts添加 OAuth 凭据在src/lib/oauth/services/添加服务。第 5 步注册模型在open-sse/config/providerRegistry.ts中添加模型定义open-sse/config/providerRegistry.ts 为仓库实际文件。第 6 步添加测试在tests/unit/编写单元测试至少覆盖Provider 注册请求/响应翻译错误处理安全补充来自英文版指南适配时请遵守若上游 Provider 在其公开 CLI/浏览器包里分发公共 OAuthclient_id/secret或 Firebase Web API key不得将其作为字符串字面量硬编码应使用resolvePublicCred()open-sse/utils/publicCreds.ts并在EMBEDDED_DEFAULTS中添加掩码字节条目完整流程见 docs/security/PUBLIC_CREDS.mdhandler/executor 中到达客户端的错误信息必须经过buildErrorBody()/sanitizeErrorMessage()open-sse/utils/error.ts禁止把原始err.stack/err.message放进响应体详见 docs/security/ERROR_SANITIZATION.md。7. Pull Request 检查清单PR Checklist测试通过npm testLint 通过npm run lint构建成功npm run build为新的公共函数和接口补充 TypeScript 类型无硬编码的密钥或回退值所有输入经 Zod schema 校验涉及用户可见变更时更新 CHANGELOG文档已更新如适用英文版指南进一步补充的硬性项还包括shell 命令exec/spawn通过env传递运行时值而非字符串插值用户可见变更在changelog.d/{features|fixes|maintenance}/PR-slug.md添加变更片段而不是直接改CHANGELOG.md见 changelog.d/README.md/api/mcp/、/api/cli-tools/runtime/等派生子进程的路由必须在src/server/authz/routeGuard.ts中归类为isLocalOnlyPath()Hard Rule #15见 docs/security/ROUTE_GUARD_TIERS.md。这些条目应并入你的最终 PR 检查。8. 发布流程与获取帮助Releasing Getting Help8.1 发布Releasing发布通过/generate-release工作流管理。当 GitHub Release 创建时包会经 GitHub Actions自动发布到 npm。部署相关细节如npm run build:release的干净重建与dist/BUILD_SHA哨兵文件可查阅 docs/ops/COVERAGE_PLAN.md 同目录下的部署文档。8.2 获取帮助Getting Help架构参见 docs/architecture/ARCHITECTURE.mdAPI 参考参见 docs/reference/API_REFERENCE.mdADR架构决策记录参见docs/下的架构决策记录文档结语这份贡献指南覆盖了 OmniRoute 从本地跑起来到提交一个 Provider 级改动的完整闭环环境变量以 .env.example 为权威契约、测试体系以 60% 覆盖率门槛与聚焦测试test:scoped等保证回归质量、代码规范由 ESLint/Prettier/lint-staged 自动化兜底、新增 Provider 有固定六步流程可循。无论你是想接入一个新模型服务商还是修复 SSE 管道、熔断器或 MCP 工具的一个缺陷沿着本文的路径出发就能以符合项目规范的方式把改动安全地合入这条永不停止编码的 AI 路由主干。【免费下载链接】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），仅供参考