參與 OmniRoute 貢獻(xiàn)的完整指南開發(fā)環(huán)境、Git 工作流、測試門禁與新增 Provider 全流程【免費(fèi)下載鏈接】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項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一個 MIT 協(xié)議的開源 AI 網(wǎng)關(guān)將數(shù)百家 LLM 提供商統(tǒng)一收斂到一個 OpenAI 兼容端點(diǎn)之后并內(nèi)置配額感知自動回退、壓縮、MCP/A2A 等能力。本文以官方CONTRIBUTING.md倉庫根目錄 CONTRIBUTING.md 及其 阿拉伯語譯文為主體結(jié)合 package.json 等倉庫事實(shí)系統(tǒng)講解從克隆安裝、本地運(yùn)行、分支工作流、測試體系到新增一個 Provider 的六步流程與 PR 硬性門禁幫助你快速成為該項(xiàng)目的一名合格貢獻(xiàn)者。一、開發(fā)環(huán)境搭建前置條件與克隆安裝前置條件貢獻(xiàn) OmniRoute 前需要準(zhǔn)備以下工具鏈Node.js22.22.3 23或24.0.0 27推薦 24 LTS。這一范圍與 package.json 中聲明的engines字段22.22.2 23 || 24.0.0 27一致超出該范圍的 Node 版本會被運(yùn)行時校驗(yàn)拒絕。npm10Gitnpm v11Node 24注意執(zhí)行npm install后應(yīng)驗(yàn)證原生模塊是否安裝成功node -e require(better-sqlite3)。若返回MODULE_NOT_FOUND需運(yùn)行npm approve-scripts better-sqlite3 npm install。詳見 TROUBLESHOOTING.md?？寺∨c安裝git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install安裝過程會執(zhí)行倉庫根目錄的postinstall腳本scripts/build/postinstall.mjs用于處理原生依賴與打包后置工作pnpm-workspace.yaml表明項(xiàng)目以 workspace 方式組織open-sse/與packages/browser-pool兩個子包。二、環(huán)境變量密鑰生成與關(guān)鍵配置從模板創(chuàng)建.env# 根據(jù)模板創(chuàng)建 .env 文件 cp .env.example .env # 生成必需的密鑰 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env倉庫根目錄的 .env.example 是一份環(huán)境變量契約逐條注釋了運(yùn)行時會讀取的每一個變量及其對應(yīng)的源碼位置。例如JWT_SECRET—— 用于簽名/校驗(yàn)儀表盤會話 Cookie由src/lib/auth讀取API_KEY_SECRET—— 用于在 SQLite 中加密存儲 API Key由src/lib/db/apiKeys.ts讀取INITIAL_PASSWORD—— 首次啟動時寫入的初始管理員登錄密碼默認(rèn)CHANGEME首次登錄后可在儀表盤修改。開發(fā)環(huán)境關(guān)鍵變量變量開發(fā)環(huán)境默認(rèn)值說明PORT20128服務(wù)器端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端 Base URLJWT_SECRET通過上方命令生成JWT 簽名密鑰INITIAL_PASSWORDCHANGEME首次登錄密碼APP_LOG_LEVELinfo日志詳細(xì)級別完整的變量清單與使用場景可參閱 ENVIRONMENT.md。儀表盤設(shè)置部分功能既可通過環(huán)境變量配置也可在儀表盤界面中切換設(shè)置位置開關(guān)說明設(shè)置 → 高級調(diào)試模式啟用調(diào)試請求日志界面端設(shè)置 → 常規(guī)側(cè)邊欄可見性顯示/隱藏側(cè)邊欄分區(qū)這些設(shè)置存儲在數(shù)據(jù)庫中重啟后仍然生效并且一旦設(shè)置會覆蓋環(huán)境變量的默認(rèn)值——這也是理解配置優(yōu)先級的關(guān)鍵數(shù)據(jù)庫設(shè)置 環(huán)境變量默認(rèn)值。三、本地運(yùn)行與構(gòu)建產(chǎn)物布局運(yùn)行命令# 開發(fā)模式熱重載 npm run dev # 生產(chǎn)構(gòu)建 npm run build # next build → .build/next/ 然后 assembleStandalone → dist/ npm run start # 貢獻(xiàn)者快速編譯僅編譯校驗(yàn)不組裝發(fā)行包 npm run build:contributor # 發(fā)布構(gòu)建清理重建 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內(nèi)部通過 scripts/dev/run-next.mjs 啟動 Next.js 開發(fā)服務(wù)器并默認(rèn)使用 Turbopack.env.example中的OMNIROUTE_USE_TURBOPACK1npm run build由 scripts/build/build-next-isolated.mjs 驅(qū)動。構(gòu)建產(chǎn)物布局目錄內(nèi)容版本追蹤src/應(yīng)用源碼TypeScript / TSX是.build/中間產(chǎn)物 —next build輸出已 gitignore否dist/可交付的打包產(chǎn)物 — 由assembleStandalone組裝否構(gòu)建流水線為單次執(zhí)行npm run build └─ next build → .build/next/standalone Next.js 輸出 └─ assembleStandalone() 復(fù)制 standalone static public 本地原生資產(chǎn) └─ 輸出: dist/ server.js, .next/static/, public/, node_modules/npm run build:release會額外清理.build/與dist/并寫入dist/BUILD_SHA等于git rev-parse --short HEAD作為部署完整性哨兵——該機(jī)制由 scripts/build/write-build-sha.mjs 實(shí)現(xiàn)。npm run build:contributor則使用后端優(yōu)先backend-only構(gòu)建檔案臨時樁化儀表盤 UI 文件、保留 API 路由處理器、構(gòu)建后還原僅用于編譯校驗(yàn)不能替代正式發(fā)行構(gòu)建。VPS 部署說明遠(yuǎn)程鏡像目錄/usr/lib/node_modules/omniroute/app/保持不變部署腳本會將dist/的內(nèi)容 rsync 到該目錄僅倉庫內(nèi)構(gòu)建輸出路徑由app/變更為dist/。默認(rèn)地址儀表盤http://localhost:20128/dashboardAPIhttp://localhost:20128/v1四、Git 工作流與分支模型鐵律絕不直接提交main??切勿直接提交到main分支。始終使用功能分支且 PR 的 base 應(yīng)指向當(dāng)前活躍的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 # ... 進(jìn)行修改 ... git commit -m feat: 描述你的改動 git push -u origin feat/your-feature-name # 發(fā)起 Pull Requestbase 設(shè)為 release/v3.8.49分支與發(fā)布模型的完整說明見 BRANCHING_MODEL.mdrelease-per-branch tag-at-ship 模型。分支命名前綴用途feat/新功能fix/Bug 修復(fù)refactor/代碼重構(gòu)docs/文檔修改test/測試新增/修復(fù)chore/工具鏈、CI、依賴項(xiàng)提交信息Conventional Commits遵循 Conventional Commits 規(guī)范feat: 為服務(wù)商調(diào)用添加熔斷器 fix: 解決 JWT 密鑰校驗(yàn)的邊界情況 docs: 更新 SECURITY.md 增加 PII 保護(hù)內(nèi)容 test: 添加可觀測性單元測試 refactor(db): 合并速率限制相關(guān)數(shù)據(jù)表作用域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。五、測試體系命令、覆蓋率關(guān)卡與 PR 要求測試命令全景# 全部測試unit vitest ecosystem e2e npm run test:all # 單個測試文件Node.js 原生測試運(yùn)行器 — 大多數(shù)測試使用此方式 node --import tsx/esm --test tests/unit/your-file.test.ts # 只跑本次改動影響的單元測試與 CI 門禁同一 TIA 選擇器 npm run test:scoped # 最近一次提交或工作區(qū)的改動 npm run test:scoped:staged # 僅暫存區(qū)改動 npm run test:scoped:full # 先重建 import 圖新增/移動文件后使用 # VitestMCP server、autoCombo、緩存 npm run test:vitest # E2E 測試需要 Playwright npm run test:e2e # 協(xié)議客戶端 E2EMCP 傳輸、A2A npm run test:protocols:e2e # 生態(tài)兼容性測試 npm run test:ecosystem # 覆蓋率關(guān)卡60% 語句/行/函數(shù)/分支 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會真實(shí)打到上游服務(wù)商、產(chǎn)生少量費(fèi)用絕不進(jìn)入 CI僅在具備 VPS 訪問權(quán)限與真實(shí)服務(wù)商積分時手動運(yùn)行。覆蓋率說明npm run test:coverage衡量主要單元測試套件的源碼覆蓋率排除tests/**包含open-sse/**在 package.json 中可見c8 --check-coverage --statements 60 --lines 60 --functions 60 --branches 60的硬性參數(shù)Pull Request 必須將覆蓋率關(guān)口維持在60%語句/行/函數(shù)/分支若 PR 修改了src/、open-sse/、electron/或bin/中的生產(chǎn)代碼必須在同一 PR 中添加或更新自動化測試npm run coverage:report打印最近一次覆蓋率運(yùn)行后的逐文件詳細(xì)報(bào)告npm run test:coverage:legacy保留舊版指標(biāo)用于歷史對比分階段覆蓋率提升路線圖見 COVERAGE_PLAN.md。Pull Request 要求發(fā)起或合并 PR 前運(yùn)行npm run test:unit運(yùn)行npm run test:coverage確保覆蓋率關(guān)口維持在60%語句/行/函數(shù)/分支涉及生產(chǎn)代碼變更時在 PR 描述中包含新增或修改的測試文件在 CI 中配置了項(xiàng)目密鑰的情況下檢查 PR 上的 SonarQube 結(jié)果官方建議在改動前先閱讀 CONTRIBUTION_GOLDEN_PATH.md——該文檔按 Provider、Routing、UI/UX、i18n、CLI、數(shù)據(jù)庫、構(gòu)建/部署等變更類型分別給出對應(yīng)的契約文件、聚焦測試命令與 CI 覆蓋面并明確本地聚焦循環(huán) vs CI 寬矩陣的分工本地只需運(yùn)行直接覆蓋改動行為的測試與npm run lint完整的單元分片、Vitest、覆蓋率棘輪與生產(chǎn)構(gòu)建交給 CI。當(dāng)前測試狀態(tài)122 個單元測試文件覆蓋范圍包括服務(wù)商翻譯器與格式轉(zhuǎn)換速率限制、熔斷器與容災(zāi)語義緩存、冪等性、進(jìn)度追蹤數(shù)據(jù)庫操作與 Schema21 個 DB 模塊OAuth 流程與認(rèn)證API 端點(diǎn)校驗(yàn)Zod v4MCP Server 工具與權(quán)限域管控記憶與技能系統(tǒng)測試代碼集中在 tests/unit與倉庫當(dāng)前的測試文件組織api、auth、combo、db、mcp、translator等子目錄一一對應(yīng)。六、代碼風(fēng)格與工程質(zhì)量約定ESLint— 提交前運(yùn)行npm run lint倉庫 eslint.config.mjs 還配置了復(fù)雜度棘輪、SonarJS 等額外門禁Prettier— 提交時通過lint-staged自動格式化2 空格、分號、雙引號、100 字符寬、es5 尾逗號配置見 prettier.config.mjsTypeScript— 所有src/代碼使用.ts/.tsxopen-sse/使用.ts/.js用 TSDoc 編寫文檔param、returns、throws禁止eval()— ESLint 強(qiáng)制執(zhí)行no-eval、no-implied-eval、no-new-func規(guī)則Zod 校驗(yàn)— 所有 API 輸入校驗(yàn)使用 Zod v4 Schema依賴聲明見 package.json 的zod: ^4.5.4命名規(guī)范文件 camelCase/kebab-case組件 PascalCase常量 UPPER_SNAKE錯誤處理禁止空 catch 塊catch塊必須分類說明不得無聲吞掉錯誤有意為之自身 best-effort 清理/遙測加一行注釋說明理由不記錄日志。例如} catch {} // closing an already-closed controller after client disconnect is expected應(yīng)當(dāng)記錄外部/調(diào)用方代碼或吞掉會改變控制流保留 catch絕不能打斷流但輸出一條帶上下文的console.debug/warn。例如} catch (e) { console.debug([STREAM] onFailure callback error:, e); }可參考 open-sse/utils/stream.ts 與 open-sse/utils/streamHandler.ts 中的實(shí)際應(yīng)用。七、項(xiàng)目結(jié)構(gòu)地圖src/ # TypeScript.ts / .tsx ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # 控制臺頁面23 個分區(qū) │ ├── api/ # API 路由51 個目錄 │ └── login/ # 認(rèn)證頁面.tsx ├── domain/ # 策略引擎policyEngine、comboResolver、costRules 等 ├── lib/ # 核心業(yè)務(wù)邏輯.ts │ ├── a2a/ # Agent-to-Agent v0.3 協(xié)議服務(wù)器 │ ├── acp/ # Agent Communication Protocol 注冊中心 │ ├── compliance/ # 合規(guī)策略引擎 │ ├── db/ # SQLite 數(shù)據(jù)庫層領(lǐng)域模塊 130 次遷移 │ ├── memory/ # 持久化會話記憶 │ ├── oauth/ # OAuth 服務(wù)商、服務(wù)與工具 │ ├── skills/ # 可擴(kuò)展技能框架 │ ├── usage/ # 用量追蹤與成本計(jì)算 │ └── localDb.ts # 僅作 re-export 層 — 切勿在此添加邏輯 ├── middleware/ # 請求中間件promptInjectionGuard ├── mitm/ # MITM 代理證書、DNS、目標(biāo)路由 ├── shared/ │ ├── components/ # React 組件.tsx │ ├── constants/ # 服務(wù)商定義、MCP 權(quán)限域、路由策略 │ ├── utils/ # 熔斷器、清洗器、認(rèn)證輔助函數(shù) │ └── validation/ # Zod v4 Schema └── sse/ # SSE 代理流水線 open-sse/ # omniroute/open-sse 工作區(qū) ├── executors/ # 服務(wù)商執(zhí)行器實(shí)現(xiàn)模塊可逐個查看如 base.ts、codex.ts 等 ├── handlers/ # 請求處理器chat、responses、embeddings、images 等 ├── mcp-server/ # MCP Server工具、傳輸、權(quán)限域 ├── services/ # 頂層服務(wù)combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻譯器OpenAI ? Claude ? Gemini ? Responses ? Ollama ├── transformer/ # Responses API 變換器 └── utils/ # 工具模塊stream、TLS、proxy、logging electron/ # Electron 桌面應(yīng)用跨平臺 tests/ ├── unit/ # Node.js 測試運(yùn)行器單元測試 ├── integration/ # 集成測試 ├── e2e/ # Playwright 測試 ├── security/ # 安全測試 ├── translator/ # 翻譯器專項(xiàng)測試 └── load/ # 負(fù)載測試 docs/ # 文檔 ├── architecture/ # 系統(tǒng)架構(gòu)與容災(zāi)如 ARCHITECTURE.md ├── frameworks/ # MCP、A2A、OpenCode、記憶、技能 ├── guides/ # 用戶指南、Docker、配置、故障排查 ├── ops/ # 部署、代理、覆蓋率、發(fā)布 ├── reference/ # API 參考、環(huán)境變量、CLI 工具、免費(fèi)層 ├── routing/ # Auto-Combo 引擎等 ├── security/ # 安全護(hù)欄、合規(guī)、Token └── i18n/ # 國際化文檔含本文所依據(jù)的 CONTRIBUTING 譯文src/lib/localDb.ts在 v3.8 中已退化為純 re-export 層——貢獻(xiàn)者應(yīng)直接按模塊導(dǎo)入而不是往其中添加邏輯。八、添加新服務(wù)商六步標(biāo)準(zhǔn)流程新增一個 Provider 是 OmniRoute 最常見的貢獻(xiàn)類型官方流程分六步步驟一注冊服務(wù)商常量在 src/shared/constants/providers.ts 中添加條目——該文件在模塊加載時即通過 Zod 校驗(yàn)。步驟二添加執(zhí)行器如需自定義邏輯在 open-sse/executors 目錄下創(chuàng)建your-provider.ts繼承 open-sse/executors/base.ts 中的基礎(chǔ)執(zhí)行器。倉庫中已有大量可參考的執(zhí)行器實(shí)現(xiàn)如chatgpt-web.ts、codex.ts、azure-openai.ts、claude-web.ts等。步驟三添加翻譯器如非 OpenAI 格式在 open-sse/translator 中創(chuàng)建請求/響應(yīng)翻譯器支持 OpenAI、Claude、Gemini、Responses、Ollama 等多格式互轉(zhuǎn)。步驟四添加 OAuth 配置如為 OAuth 類服務(wù)商在 src/lib/oauth/constants/oauth.ts 中添加 OAuth 憑證在 src/lib/oauth/services 中添加服務(wù)。兩條安全紅線若上游服務(wù)商在其公開的 CLI / 瀏覽器打包產(chǎn)物中分發(fā)公開的 OAuth client_id/secret 或 Firebase Web API Key不要以字符串字面量嵌入代碼必須使用 open-sse/utils/publicCreds.ts 中的resolvePublicCred()并在EMBEDDED_DEFAULTS中添加掩碼字節(jié)條目。完整強(qiáng)制工作流見 PUBLIC_CREDS.md。在處理器/執(zhí)行器內(nèi)部發(fā)往客戶端的錯誤消息必須經(jīng)過 open-sse/utils/error.ts 中的buildErrorBody()/sanitizeErrorMessage()處理——切勿在 Response body 中放入原始err.stack或err.message。參見 ERROR_SANITIZATION.md。步驟五注冊模型在 open-sse/config/providerRegistry.ts 中添加模型定義。步驟六添加測試在 tests/unit 中編寫單元測試至少覆蓋服務(wù)商注冊請求/響應(yīng)翻譯錯誤處理Provider 類改動還建議運(yùn)行npm run check:provider-consistency、npm run check:provider-assets等聚焦門禁詳見 CONTRIBUTION_GOLDEN_PATH.md 的 Provider 章節(jié)。九、Pull Request 檢查清單與硬性規(guī)則提交 PR 前逐項(xiàng)核驗(yàn)測試通過npm test代碼檢查通過npm run lint構(gòu)建成功npm run build為新增的公開函數(shù)與接口添加了 TypeScript 類型無硬編碼的密鑰或兜底值公開的上游憑證通過resolvePublicCred()嵌入見 PUBLIC_CREDS.md嚴(yán)禁字面量形式錯誤響應(yīng)通過buildErrorBody()/sanitizeErrorMessage()處理Response body 中不含原始堆棧信息見 ERROR_SANITIZATION.mdShell 命令exec/spawn通過env傳遞運(yùn)行時值禁止字符串插值所有輸入使用 Zod Schema 校驗(yàn)面向用戶的變更在 changelog.d 下新增fragmentchangelog.d/{features|fixes|maintenance}/PR-slug.md規(guī)范見 changelog.d/README.md——不要直接編輯CHANGELOG.mdfragment 會在發(fā)版時統(tǒng)一聚合從而避免 PR 間沖突文檔已更新如適用未新增 CodeQL / 密鑰掃描告警或每條告警均已附技術(shù)說明予以忽略并引用相關(guān)docs/security/文檔產(chǎn)生子進(jìn)程的路由/api/mcp/、/api/cli-tools/runtime/已在 src/server/authz/routeGuard.ts 中分類為isLocalOnlyPath()—— 見 ROUTE_GUARD_TIERS.md 中的 Hard Rule #15提交信息中不含Co-Authored-By尾部字段 —— 提交必須僅出現(xiàn)在倉庫所有者的 Git 身份下Hard Rule #16其中路由分級守衛(wèi)routeGuard與提交身份歸屬兩條屬于不可協(xié)商的硬性規(guī)則違反會直接阻塞合并。十、發(fā)布流程發(fā)布通過/generate-release工作流管理。當(dāng)新的 GitHub Release 創(chuàng)建時包會通過 GitHub Actions自動發(fā)布到 npm。VPS 部署時請使用npm run build:release而非npm run build——它會執(zhí)行清理重建、將打包產(chǎn)物組裝到dist/并寫入dist/BUILD_SHA哨兵文件隨后通過/deploy-vps-*-cc技能將dist/rsync 到遠(yuǎn)端app/目錄。npm publish前還會執(zhí)行prepublishOnlybuild:cli-api、build:cli、check:pack-artifact確保發(fā)布包表面完整。十一、獲取幫助架構(gòu)參見 docs/architecture/ARCHITECTURE.mdAPI 參考參見 docs/reference/API_REFERENCE.md貢獻(xiàn)黃金路徑docs/ops/CONTRIBUTION_GOLDEN_PATH.md按變更類型給出契約與聚焦測試安全文檔CLI_TOKEN.md、ROUTE_GUARD_TIERS.md、ERROR_SANITIZATION.md、PUBLIC_CREDS.md運(yùn)維文檔docs/ops/SQLITE_RUNTIME.md架構(gòu)決策記錄docs/adr/目錄注倉庫當(dāng)前將 ADR 相關(guān)文檔整理在 docs/architecture 等目錄下請以實(shí)際內(nèi)容為準(zhǔn)掌握以上流程后你就具備了向 OmniRoute 提交高質(zhì)量 PR 的完整能力從環(huán)境搭建、分支工作流、測試門禁到 Provider 新增的六步路線圖再到安全與發(fā)布紅線。無論是修復(fù)一個 bug、翻譯一份文檔還是接入一個新的模型提供商都可以按照本文的檢查清單穩(wěn)步推進(jìn)?！久赓M(fèi)下載鏈接】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項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考