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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 是一个开源的统一 AI 网关（MIT License），通过单一端点聚合数百家 AI Provider 并提供配额感知的自动故障转移、RTK+Caveman 上下文压缩、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声明为准；
• npm10+；
• Git，用于分支管理与提交流程。

克隆与安装（Clone & Install）

git 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

核心环境变量

Dashboard 设置项

部分功能既可通过环境变量配置，也可在 Dashboard 界面中切换，设置会持久化到数据库并在重启后保留，一旦设置会覆盖环境变量默认值：

本地运行

# 开发模式（热重载） npm run dev # 生产构建 npm run build npm run start # 常见端口配置组合 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

npm run dev实际调用的是node scripts/dev/run-next.mjs dev（见 package.json），底层基于 Next.js 16 App Router 开发服务器，并预设较大堆内存上限。启动后的默认访问地址：

• Dashboard 控制台：http://localhost:20128/dashboard
• API 端点：http://localhost:20128/v1

Git 工作流

重要：禁止直接向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

分支命名规范

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 # 协议客户端 E2E（MCP 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 --test+tsx/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 度量源码覆盖率，--exclude=tests/**排除测试自身，包含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.md：Phase 1–5（60%→80%）已完成，当前处于 Phase 6（≥85%）与 Phase 7（≥90%）阶段。

测试覆盖的业务领域

当前单元测试已覆盖如下核心能力域：

• Provider 格式转换器（translator）与格式互转
• 限流、熔断（circuit breaker）与韧性机制
• 语义缓存、幂等性、进度追踪
• 数据库操作与 schema（覆盖 21 个 DB 模块；src/lib/db/实际包含约 125 个顶层模块与 170 个迁移文件）
• OAuth 流程与认证
• API 端点校验（Zod v4）
• MCP 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 commas；
• TypeScript：src/下所有代码使用.ts/.tsx；open-sse/下使用.ts/.js；公共函数需编写 TSDoc（@param、@returns、@throws）；
• 禁止eval()：ESLint 强制no-eval、no-implied-eval、no-new-func；
• Zod 校验：所有 API 入参校验统一使用 Zod v4 schema；
• 命名约定：文件使用 camelCase/kebab-case，React 组件使用 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/ # providerRegistry（Provider 注册表，单一事实来源） ├── 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）或双认证 Provider（DUAL_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 test）
• Lint 通过（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.md
• API 参考：见 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute