参与 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本文以 OmniRoute 官方贡献指南docs/i18n/no/CONTRIBUTING.md原文档同时提供英、中、日、法、德等 50 语言版本为核心骨架结合当前仓库的源码、配置文件与测试实现进行展开系统讲解如何搭建本地开发环境、遵守 Git 与代码规范、运行完整测试矩阵、理解项目目录结构以及最重要的实战场景——如何为这个统一 AI 网关新增一个 Provider。读完本文你将掌握提交一个可合并 PR 的完整路径并能在本地验证每一步改动。OmniRoute 是一个 MIT 许可的开源统一 AI 网关一个端点聚合数百家模型提供商具备配额感知的自动回退、RTKCaveman 上下文压缩、MCP/A2A 协议支持与桌面/PWA 客户端当前仓库 package.json 版本为3.8.51描述中标称聚合 356 家 Provider。它的贡献流程围绕新增/维护 Provider这一核心场景展开下面逐层拆解。开发环境搭建前置条件Node.js贡献指南要求 18 24推荐 22 LTS。需要说明的是当前仓库 package.json 中engines字段的实际约束已收紧为22.22.2 23 || 24.0.0 27因此在本地开发时以仓库声明的运行时为准更稳妥。npm10Git克隆与安装git clone https://gitcode.com/GitHub_Trending/om/OmniRoute.git cd OmniRoute npm install仓库采用 npm workspaces 组织子包见 package.json 的workspaces字段open-sse与packages/browser-pool安装时postinstall脚本会执行原生依赖检查与必要的构建步骤scripts/postinstall.mjs。环境变量从 .env.example 出发# 从模板创建自己的 .env cp .env.example .env # 生成必需密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env.env.example 是仓库内运行时读取的全部环境变量的契约文档其中明确标注变量开发默认值说明PORT20128服务监听端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端页面访问的基础 URLJWT_SECRET按上文生成会话令牌 JWT 签名密钥API_KEY_SECRET按上文生成数据库中 API Key 的静态加密密钥INITIAL_PASSWORDCHANGEME首次登录密码首次使用前必须修改APP_LOG_LEVELinfo日志详细程度对照 .env.example 的注释可知JWT_SECRET由src/lib/auth使用负责签发/校验所有已认证会话 CookieAPI_KEY_SECRET由src/lib/db/apiKeys.ts使用对 SQLite 中落盘的 API Key 进行加密INITIAL_PASSWORD仅在首次启动引导时生效之后可在 Dashboard → Settings → Security 中修改。此外该文件还记录了更多与贡献者相关的变量例如DATA_DIR默认~/.omniroute/控制 SQLite 数据、日志与备份的存放目录、REDIS_URL可选不设置则使用内置内存限流器、STORAGE_ENCRYPTION_KEY可对整库加密等贡献前值得通读一遍。Dashboard 设置与数据库持久化控制台提供的部分功能开关与环境变量等价设置位置开关说明Settings → AdvancedDebug Mode开启调试请求日志UISettings → GeneralSidebar Visibility显示/隐藏侧边栏分区这些设置存储在数据库中重启后依然生效且一旦设置便会覆盖环境变量的默认值。这也是理解环境变量 vs 数据库设置优先级关系的关键点。本地运行# 开发模式热重载 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/v1npm run dev实际通过scripts/dev/run-next.mjs dev启动并设置了较大的堆内存上限--max-old-space-size8192见 package.json说明该项目的 TypeScript Next.js 全量加载对内存有较高要求低配机器可留意。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分支命名规范前缀用途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。其中a2a、mcp、skills、memory分别对应仓库中的 Agent-to-Agent 协议服务、MCP 服务器、可扩展技能框架与持久化会话记忆详见下文项目结构。测试体系提交前的质量底线常用测试命令# 全量测试单元 vitest 生态 e2e npm run test:all # 单文件测试Node.js 原生 test runner多数测试使用 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覆盖率门槛npm run test:coverage度量主单元测试套件对源码的覆盖排除tests/**包含open-sse/**从 package.json 的test:coverage脚本可以看到c8 的--check-coverage明确设置了--statements 60 --lines 60 --functions 60 --branches 60即四个指标均须达到 60% 以上若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码必须在同一 PR 内新增或更新自动化测试npm run coverage:report输出最近一次覆盖率运行的逐文件明细报告npm run test:coverage:legacy保留旧口径指标用于历史对比分阶段提升覆盖率的路线图见 docs/ops/COVERAGE_PLAN.md。PR 前置要求打开或合并 PR 之前必须运行npm run test:unit运行npm run test:coverage确保四个指标的覆盖率门槛保持在60%当生产代码有改动时在 PR 描述中包含新增/修改的测试文件当 CI 中配置了项目密钥时检查 PR 上的 SonarQube 结果按贡献指南的记载测试覆盖范围包括Provider 翻译器与格式转换、限流/熔断/韧性、语义缓存/幂等/进度跟踪、数据库操作与 schema21 个 DB 模块、OAuth 流程与认证、API 端点 Zod 校验、MCP 服务器工具与作用域强制、Memory 与 Skills 系统。当前仓库的 tests/unit 目录规模远超指南记录仅单元测试目录下即包含超过五千个.ts文件分属api、auth、db、combo、compression、mcp、memory、security等子目录说明该指南中的数字属于历史快照实际测试矩阵只增不减。代码风格规范ESLint提交前运行npm run lint脚本使用eslint .并携带缓存的 suppressions 配置见 package.jsonPrettier通过lint-staged在 commit 时自动格式化2 空格缩进、分号、双引号、100 字符行宽、es5 trailing commas见 package.jsonTypeScriptsrc/全部使用.ts/.tsxopen-sse/使用.ts/.js公共函数需编写 TSDocparam、returns、throws禁止eval()ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验所有 API 输入校验必须使用 Zod v4 schema当前仓库依赖为zod: ^4.5.4见 package.json命名文件使用 camelCase/kebab-case组件使用 PascalCase常量使用 UPPER_SNAKE。项目结构导航理解目录结构是定位改动点的前提。贡献指南给出的整体布局如下括号内为当前仓库中的对应路径src/ # TypeScript (.ts / .tsx) —— 实际对应 src/app、src/domain、src/lib 等 ├── app/ # Next.js App Routerdashboard 页面、API 路由、登录页 ├── domain/ # 策略引擎policyEngine、comboResolver、costRules 等 ├── lib/ # 核心业务逻辑 │ ├── a2a/ # Agent-to-Agent v0.3 协议服务器 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 数据层顶层模块 迁移 │ ├── memory/ # 持久化会话记忆 │ ├── oauth/ # OAuth providers、services 与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量追踪与成本计算 │ └── localDb.ts # 仅做再导出禁止新增逻辑 ├── middleware/ # 请求中间件promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ # React 组件、Provider 常量、工具、Zod schema └── sse/ # SSE 代理管道 open-sse/ # omniroute/open-sse workspace ├── executors/ # 各 Provider 的执行器实现 ├── handlers/ # 请求处理器chat、responses、embeddings、images 等 ├── mcp-server/ # MCP 服务器 ├── services/ # 顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 转换器 └── utils/ # 工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 原生 test runner 测试 ├── integration/ # 集成测试 ├── e2e/ # Playwright 测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档 ├── ARCHITECTURE.md # 系统架构 ├── API_REFERENCE.md # 全部端点 ├── USER_GUIDE.md # Provider 设置、CLI 集成 ├── TROUBLESHOOTING.md # 常见问题 ├── MCP-SERVER.md # MCP 服务器 ├── A2A-SERVER.md # A2A Agent 协议 ├── AUTO-COMBO.md # Auto-combo 引擎 ├── CLI-TOOLS.md # CLI 工具集成 ├── COVERAGE_PLAN.md # 测试覆盖率提升计划 ├── openapi.yaml # OpenAPI 规范 └── adr/ # 架构决策记录对照当前仓库src/shared/constants下确有providers.ts、models.ts、routingStrategies.ts、mcpScopes.ts等常量模块见 src/shared/constantsopen-sse/config下确有providerRegistry.ts、freeModelCatalog.ts、geminiRateLimits.json等配置见 open-sse/config。指南中docs/adr/目录在当前仓库中不存在相关架构决策记录以 docs/architecture 下的 ADR 风格文档如admission-lanes.md、cluster-decisions.md承接阅读时可灵活对照。实战新增一个 Provider 的六步流程这是贡献者最高频的场景。OmniRoute 的 Provider 接入遵循常量注册 → 执行器 → 翻译器 → OAuth → 模型注册 → 测试的固定流水线Step 1注册 Provider 常量在src/shared/constants/providers.ts中注册。对照源码src/shared/constants/providers.ts该文件从多个叶子模块聚合 Provider 分类并统一导出NOAUTH_PROVIDERS无需鉴权的 Provider如本地/匿名可用的服务OAUTH_PROVIDERSOAuth 认证的 ProviderWEB_COOKIE_PROVIDERS基于 Web Cookie 的 ProviderAPIKEY_PROVIDERSAPI Key 认证的 ProviderLOCAL_PROVIDERS、SEARCH_PROVIDERS、AUDIO_ONLY_PROVIDERS、UPSTREAM_PROXY_PROVIDERS、CLOUD_AGENT_PROVIDERS、SYSTEM_PROVIDERS等。值得注意的是模块加载时会调用validateProviders来自../validation/providerSchema对全部 Provider 定义做Zod 校验——这意味着常量注册阶段就会暴露 schema 不匹配问题属于第一道防线。Step 2添加执行器如需自定义逻辑在open-sse/executors/your-provider.ts创建执行器继承基类执行器。执行器负责与上游服务的实际通信细节请求构造、认证头、错误映射。Step 3添加翻译器若非 OpenAI 格式若上游不是 OpenAI 兼容格式需要在open-sse/translator/下创建请求/响应翻译器。从仓库结构看open-sse/translator 下共有 61 个.ts模块覆盖 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 等多向转换。Step 4添加 OAuth 配置若基于 OAuth在src/lib/oauth/constants/oauth.ts添加 OAuth 凭据在src/lib/oauth/services/添加服务。对照源码src/lib/oauth/constants/oauth.ts所有凭据都只从环境变量读取默认值匹配.env.example中的公开 CLI client ID由scripts/dev/sync-env.mjs在安装时自动填充且这些公开凭据依赖 PKCERFC 8252保证安全性而非依赖保密性。Step 5注册模型在open-sse/config/providerRegistry.ts添加模型定义。该注册表与 open-sse/config 下的freeModelCatalog.ts、agyModels.ts、imageRegistry.ts等共同构成模型目录。Step 6添加测试在tests/unit/编写单元测试至少覆盖Provider 注册请求/响应翻译错误处理这对应贡献指南中修改生产代码必须在同一 PR 内补测试的硬性要求。Pull Request 清单提交前逐项核对测试通过npm testLint 通过npm run lint构建成功npm run build为新的公共函数与接口补充 TypeScript 类型无硬编码密钥或回退值所有输入均用 Zod schema 校验面向用户的行为变更已更新 CHANGELOG如适用已更新文档发布流程发布由/generate-release工作流管理。当新的 GitHub Release 创建后包会通过 GitHub Actions自动发布到 npm无需人工介入。因此贡献者只需保证 PR 通过质量门槛发布环节由 CI 托管。进一步阅读系统架构docs/architecture/ARCHITECTURE.mdAPI 参考docs/reference/API_REFERENCE.md覆盖率提升路线图docs/ops/COVERAGE_PLAN.md环境变量完整参考docs/reference/ENVIRONMENT.md.env.example 头部亦指向此文档Provider 接入细节docs/guides/PROVIDERS-GUIDE.md、docs/reference/PROVIDER_REFERENCE.md架构决策记录见 docs/architecture 下的 ADR 风格文档多语言版本本文对应文档的挪威语版位于 docs/i18n/no/CONTRIBUTING.md其页面头部提供了指向英语原版 CONTRIBUTING.md 及 50 余个语言版本的导航链接【免费下载链接】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），仅供参考