参与 OmniRoute 贡献的完整指南开发环境、Git 工作流、测试门禁与新增 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 是一个 MIT 协议的开源 AI 网关将数百家 LLM 提供商统一收敛到一个 OpenAI 兼容端点之后并内置配额感知自动回退、压缩、MCP/A2A 等能力。本文以官方CONTRIBUTING.md仓库根目录 CONTRIBUTING.md 及其 阿拉伯语译文为主体结合 package.json 等仓库事实系统讲解从克隆安装、本地运行、分支工作流、测试体系到新增一个 Provider 的六步流程与 PR 硬性门禁帮助你快速成为该项目的一名合格贡献者。一、开发环境搭建前置条件与克隆安装前置条件贡献 OmniRoute 前需要准备以下工具链Node.js22.22.3 23或24.0.0 27推荐 24 LTS。这一范围与 package.json 中声明的engines字段22.22.2 23 || 24.0.0 27一致超出该范围的 Node 版本会被运行时校验拒绝。npm10Gitnpm v11Node 24注意执行npm install后应验证原生模块是否安装成功node -e require(better-sqlite3)。若返回MODULE_NOT_FOUND需运行npm approve-scripts better-sqlite3 npm install。详见 TROUBLESHOOTING.md。克隆与安装git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install安装过程会执行仓库根目录的postinstall脚本scripts/build/postinstall.mjs用于处理原生依赖与打包后置工作pnpm-workspace.yaml表明项目以 workspace 方式组织open-sse/与packages/browser-pool两个子包。二、环境变量密钥生成与关键配置从模板创建.env# 根据模板创建 .env 文件 cp .env.example .env # 生成必需的密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env仓库根目录的 .env.example 是一份环境变量契约逐条注释了运行时会读取的每一个变量及其对应的源码位置。例如JWT_SECRET—— 用于签名/校验仪表盘会话 Cookie由src/lib/auth读取API_KEY_SECRET—— 用于在 SQLite 中加密存储 API Key由src/lib/db/apiKeys.ts读取INITIAL_PASSWORD—— 首次启动时写入的初始管理员登录密码默认CHANGEME首次登录后可在仪表盘修改。开发环境关键变量变量开发环境默认值说明PORT20128服务器端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端 Base URLJWT_SECRET通过上方命令生成JWT 签名密钥INITIAL_PASSWORDCHANGEME首次登录密码APP_LOG_LEVELinfo日志详细级别完整的变量清单与使用场景可参阅 ENVIRONMENT.md。仪表盘设置部分功能既可通过环境变量配置也可在仪表盘界面中切换设置位置开关说明设置 → 高级调试模式启用调试请求日志界面端设置 → 常规侧边栏可见性显示/隐藏侧边栏分区这些设置存储在数据库中重启后仍然生效并且一旦设置会覆盖环境变量的默认值——这也是理解配置优先级的关键数据库设置 环境变量默认值。三、本地运行与构建产物布局运行命令# 开发模式热重载 npm run dev # 生产构建 npm run build # next build → .build/next/ 然后 assembleStandalone → dist/ npm run start # 贡献者快速编译仅编译校验不组装发行包 npm run build:contributor # 发布构建清理重建 HEAD 哨兵 — 部署必需 npm run build:release # rm -rf .build dist build 写入 dist/BUILD_SHA # 常用端口配置 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run devnpm run dev内部通过 scripts/dev/run-next.mjs 启动 Next.js 开发服务器并默认使用 Turbopack.env.example中的OMNIROUTE_USE_TURBOPACK1npm run build由 scripts/build/build-next-isolated.mjs 驱动。构建产物布局目录内容版本追踪src/应用源码TypeScript / TSX是.build/中间产物 —next build输出已 gitignore否dist/可交付的打包产物 — 由assembleStandalone组装否构建流水线为单次执行npm run build └─ next build → .build/next/standalone Next.js 输出 └─ assembleStandalone() 复制 standalone static public 本地原生资产 └─ 输出: dist/ server.js, .next/static/, public/, node_modules/npm run build:release会额外清理.build/与dist/并写入dist/BUILD_SHA等于git rev-parse --short HEAD作为部署完整性哨兵——该机制由 scripts/build/write-build-sha.mjs 实现。npm run build:contributor则使用后端优先backend-only构建档案临时桩化仪表盘 UI 文件、保留 API 路由处理器、构建后还原仅用于编译校验不能替代正式发行构建。VPS 部署说明远程镜像目录/usr/lib/node_modules/omniroute/app/保持不变部署脚本会将dist/的内容 rsync 到该目录仅仓库内构建输出路径由app/变更为dist/。默认地址仪表盘http://localhost:20128/dashboardAPIhttp://localhost:20128/v1四、Git 工作流与分支模型铁律绝不直接提交main⚠️切勿直接提交到main分支。始终使用功能分支且 PR 的 base 应指向当前活跃的release/vX.Y.Z分支而非main。# 从活跃 release 分支顶端切出功能分支示例release/v3.8.49 git fetch origin git checkout -b feat/your-feature-name origin/release/v3.8.49 # ... 进行修改 ... git commit -m feat: 描述你的改动 git push -u origin feat/your-feature-name # 发起 Pull Requestbase 设为 release/v3.8.49分支与发布模型的完整说明见 BRANCHING_MODEL.mdrelease-per-branch tag-at-ship 模型。分支命名前缀用途feat/新功能fix/Bug 修复refactor/代码重构docs/文档修改test/测试新增/修复chore/工具链、CI、依赖项提交信息Conventional Commits遵循 Conventional Commits 规范feat: 为服务商调用添加熔断器 fix: 解决 JWT 密钥校验的边界情况 docs: 更新 SECURITY.md 增加 PII 保护内容 test: 添加可观测性单元测试 refactor(db): 合并速率限制相关数据表作用域Scope白名单db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz。五、测试体系命令、覆盖率关卡与 PR 要求测试命令全景# 全部测试unit vitest ecosystem e2e npm run test:all # 单个测试文件Node.js 原生测试运行器 — 大多数测试使用此方式 node --import tsx/esm --test tests/unit/your-file.test.ts # 只跑本次改动影响的单元测试与 CI 门禁同一 TIA 选择器 npm run test:scoped # 最近一次提交或工作区的改动 npm run test:scoped:staged # 仅暂存区改动 npm run test:scoped:full # 先重建 import 图新增/移动文件后使用 # VitestMCP server、autoCombo、缓存 npm run test:vitest # E2E 测试需要 Playwright npm run test:e2e # 协议客户端 E2EMCP 传输、A2A npm run test:protocols:e2e # 生态兼容性测试 npm run test:ecosystem # 覆盖率关卡60% 语句/行/函数/分支 npm run test:coverage npm run coverage:report # 代码检查 格式检查 npm run lint npm run check线上 Combo 冒烟测试RUN_COMBO_LIVE1 npm run test:combo:live与npm run test:combo:live:vps会真实打到上游服务商、产生少量费用绝不进入 CI仅在具备 VPS 访问权限与真实服务商积分时手动运行。覆盖率说明npm run test:coverage衡量主要单元测试套件的源码覆盖率排除tests/**包含open-sse/**在 package.json 中可见c8 --check-coverage --statements 60 --lines 60 --functions 60 --branches 60的硬性参数Pull Request 必须将覆盖率关口维持在60%语句/行/函数/分支若 PR 修改了src/、open-sse/、electron/或bin/中的生产代码必须在同一 PR 中添加或更新自动化测试npm run coverage:report打印最近一次覆盖率运行后的逐文件详细报告npm run test:coverage:legacy保留旧版指标用于历史对比分阶段覆盖率提升路线图见 COVERAGE_PLAN.md。Pull Request 要求发起或合并 PR 前运行npm run test:unit运行npm run test:coverage确保覆盖率关口维持在60%语句/行/函数/分支涉及生产代码变更时在 PR 描述中包含新增或修改的测试文件在 CI 中配置了项目密钥的情况下检查 PR 上的 SonarQube 结果官方建议在改动前先阅读 CONTRIBUTION_GOLDEN_PATH.md——该文档按 Provider、Routing、UI/UX、i18n、CLI、数据库、构建/部署等变更类型分别给出对应的契约文件、聚焦测试命令与 CI 覆盖面并明确本地聚焦循环 vs CI 宽矩阵的分工本地只需运行直接覆盖改动行为的测试与npm run lint完整的单元分片、Vitest、覆盖率棘轮与生产构建交给 CI。当前测试状态122 个单元测试文件覆盖范围包括服务商翻译器与格式转换速率限制、熔断器与容灾语义缓存、幂等性、进度追踪数据库操作与 Schema21 个 DB 模块OAuth 流程与认证API 端点校验Zod v4MCP Server 工具与权限域管控记忆与技能系统测试代码集中在 tests/unit与仓库当前的测试文件组织api、auth、combo、db、mcp、translator等子目录一一对应。六、代码风格与工程质量约定ESLint— 提交前运行npm run lint仓库 eslint.config.mjs 还配置了复杂度棘轮、SonarJS 等额外门禁Prettier— 提交时通过lint-staged自动格式化2 空格、分号、双引号、100 字符宽、es5 尾逗号配置见 prettier.config.mjsTypeScript— 所有src/代码使用.ts/.tsxopen-sse/使用.ts/.js用 TSDoc 编写文档param、returns、throws禁止eval()— ESLint 强制执行no-eval、no-implied-eval、no-new-func规则Zod 校验— 所有 API 输入校验使用 Zod v4 Schema依赖声明见 package.json 的zod: ^4.5.4命名规范文件 camelCase/kebab-case组件 PascalCase常量 UPPER_SNAKE错误处理禁止空 catch 块catch块必须分类说明不得无声吞掉错误有意为之自身 best-effort 清理/遥测加一行注释说明理由不记录日志。例如} catch {} // closing an already-closed controller after client disconnect is expected应当记录外部/调用方代码或吞掉会改变控制流保留 catch绝不能打断流但输出一条带上下文的console.debug/warn。例如} catch (e) { console.debug([STREAM] onFailure callback error:, e); }可参考 open-sse/utils/stream.ts 与 open-sse/utils/streamHandler.ts 中的实际应用。七、项目结构地图src/ # TypeScript.ts / .tsx ├── app/ # Next.js 16 App Router │ ├── (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/ # 服务商定义、MCP 权限域、路由策略 │ ├── utils/ # 熔断器、清洗器、认证辅助函数 │ └── validation/ # Zod v4 Schema └── sse/ # SSE 代理流水线 open-sse/ # omniroute/open-sse 工作区 ├── executors/ # 服务商执行器实现模块可逐个查看如 base.ts、codex.ts 等 ├── handlers/ # 请求处理器chat、responses、embeddings、images 等 ├── mcp-server/ # MCP Server工具、传输、权限域 ├── services/ # 顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ├── transformer/ # Responses API 变换器 └── utils/ # 工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 测试运行器单元测试 ├── integration/ # 集成测试 ├── e2e/ # Playwright 测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档 ├── architecture/ # 系统架构与容灾如 ARCHITECTURE.md ├── frameworks/ # MCP、A2A、OpenCode、记忆、技能 ├── guides/ # 用户指南、Docker、配置、故障排查 ├── ops/ # 部署、代理、覆盖率、发布 ├── reference/ # API 参考、环境变量、CLI 工具、免费层 ├── routing/ # Auto-Combo 引擎等 ├── security/ # 安全护栏、合规、Token └── i18n/ # 国际化文档含本文所依据的 CONTRIBUTING 译文src/lib/localDb.ts在 v3.8 中已退化为纯 re-export 层——贡献者应直接按模块导入而不是往其中添加逻辑。八、添加新服务商六步标准流程新增一个 Provider 是 OmniRoute 最常见的贡献类型官方流程分六步步骤一注册服务商常量在 src/shared/constants/providers.ts 中添加条目——该文件在模块加载时即通过 Zod 校验。步骤二添加执行器如需自定义逻辑在 open-sse/executors 目录下创建your-provider.ts继承 open-sse/executors/base.ts 中的基础执行器。仓库中已有大量可参考的执行器实现如chatgpt-web.ts、codex.ts、azure-openai.ts、claude-web.ts等。步骤三添加翻译器如非 OpenAI 格式在 open-sse/translator 中创建请求/响应翻译器支持 OpenAI、Claude、Gemini、Responses、Ollama 等多格式互转。步骤四添加 OAuth 配置如为 OAuth 类服务商在 src/lib/oauth/constants/oauth.ts 中添加 OAuth 凭证在 src/lib/oauth/services 中添加服务。两条安全红线若上游服务商在其公开的 CLI / 浏览器打包产物中分发公开的 OAuth client_id/secret 或 Firebase Web API Key不要以字符串字面量嵌入代码必须使用 open-sse/utils/publicCreds.ts 中的resolvePublicCred()并在EMBEDDED_DEFAULTS中添加掩码字节条目。完整强制工作流见 PUBLIC_CREDS.md。在处理器/执行器内部发往客户端的错误消息必须经过 open-sse/utils/error.ts 中的buildErrorBody()/sanitizeErrorMessage()处理——切勿在 Response body 中放入原始err.stack或err.message。参见 ERROR_SANITIZATION.md。步骤五注册模型在 open-sse/config/providerRegistry.ts 中添加模型定义。步骤六添加测试在 tests/unit 中编写单元测试至少覆盖服务商注册请求/响应翻译错误处理Provider 类改动还建议运行npm run check:provider-consistency、npm run check:provider-assets等聚焦门禁详见 CONTRIBUTION_GOLDEN_PATH.md 的 Provider 章节。九、Pull Request 检查清单与硬性规则提交 PR 前逐项核验测试通过npm test代码检查通过npm run lint构建成功npm run build为新增的公开函数与接口添加了 TypeScript 类型无硬编码的密钥或兜底值公开的上游凭证通过resolvePublicCred()嵌入见 PUBLIC_CREDS.md严禁字面量形式错误响应通过buildErrorBody()/sanitizeErrorMessage()处理Response body 中不含原始堆栈信息见 ERROR_SANITIZATION.mdShell 命令exec/spawn通过env传递运行时值禁止字符串插值所有输入使用 Zod Schema 校验面向用户的变更在 changelog.d 下新增fragmentchangelog.d/{features|fixes|maintenance}/PR-slug.md规范见 changelog.d/README.md——不要直接编辑CHANGELOG.mdfragment 会在发版时统一聚合从而避免 PR 间冲突文档已更新如适用未新增 CodeQL / 密钥扫描告警或每条告警均已附技术说明予以忽略并引用相关docs/security/文档产生子进程的路由/api/mcp/、/api/cli-tools/runtime/已在 src/server/authz/routeGuard.ts 中分类为isLocalOnlyPath()—— 见 ROUTE_GUARD_TIERS.md 中的 Hard Rule #15提交信息中不含Co-Authored-By尾部字段 —— 提交必须仅出现在仓库所有者的 Git 身份下Hard Rule #16其中路由分级守卫routeGuard与提交身份归属两条属于不可协商的硬性规则违反会直接阻塞合并。十、发布流程发布通过/generate-release工作流管理。当新的 GitHub Release 创建时包会通过 GitHub Actions自动发布到 npm。VPS 部署时请使用npm run build:release而非npm run build——它会执行清理重建、将打包产物组装到dist/并写入dist/BUILD_SHA哨兵文件随后通过/deploy-vps-*-cc技能将dist/rsync 到远端app/目录。npm publish前还会执行prepublishOnlybuild:cli-api、build:cli、check:pack-artifact确保发布包表面完整。十一、获取帮助架构参见 docs/architecture/ARCHITECTURE.mdAPI 参考参见 docs/reference/API_REFERENCE.md贡献黄金路径docs/ops/CONTRIBUTION_GOLDEN_PATH.md按变更类型给出契约与聚焦测试安全文档CLI_TOKEN.md、ROUTE_GUARD_TIERS.md、ERROR_SANITIZATION.md、PUBLIC_CREDS.md运维文档docs/ops/SQLITE_RUNTIME.md架构决策记录docs/adr/目录注仓库当前将 ADR 相关文档整理在 docs/architecture 等目录下请以实际内容为准掌握以上流程后你就具备了向 OmniRoute 提交高质量 PR 的完整能力从环境搭建、分支工作流、测试门禁到 Provider 新增的六步路线图再到安全与发布红线。无论是修复一个 bug、翻译一份文档还是接入一个新的模型提供商都可以按照本文的检查清单稳步推进。【免费下载链接】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），仅供参考