OmniRoute 貢獻(xiàn)者指南本地環(huán)境搭建、測(cè)試體系與新增 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/OmniRoute本文基于 OmniRoute 倉(cāng)庫(kù)的貢獻(xiàn)文檔docs/i18n/de/CONTRIBUTING.md其內(nèi)容與根目錄 CONTRIBUTING.md 同源的開(kāi)發(fā)者貢獻(xiàn)規(guī)范完整梳理參與該項(xiàng)目開(kāi)發(fā)的整套工作流從 Node.js 環(huán)境準(zhǔn)備、環(huán)境變量配置與本地啟動(dòng)到 Git 分支策略、多層測(cè)試體系與 60% 覆蓋率門禁再到新增一個(gè) AI Provider 所必須經(jīng)過(guò)的六個(gè)落地步驟常量注冊(cè) → Executor → Translator → OAuth → 模型注冊(cè) → 測(cè)試。讀完本文你可以在本地把 OmniRoute 跑起來(lái)Dashboard 與/v1API理解其測(cè)試與覆蓋率約束并獨(dú)立完成一次符合規(guī)范的新 Provider 貢獻(xiàn)。一、環(huán)境準(zhǔn)備與本地運(yùn)行1.1 前置依賴貢獻(xiàn)文檔給出的環(huán)境要求如下Node.js文檔標(biāo)注 18 24推薦 22 LTS注意當(dāng)前倉(cāng)庫(kù) package.json 的engines字段已收緊為22.22.2 23 || 24.0.0 27以倉(cāng)庫(kù)實(shí)際聲明為準(zhǔn)npm10Git。1.2 克隆與安裝git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install1.3 環(huán)境變量倉(cāng)庫(kù)提供 .env.example 模板開(kāi)發(fā)環(huán)境從模板復(fù)制后需生成兩個(gè)核心密鑰# Create your .env from the template cp .env.example .env # Generate required secrets echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env開(kāi)發(fā)階段的關(guān)鍵變量如下變量開(kāi)發(fā)默認(rèn)值說(shuō)明PORT20128服務(wù)端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端基礎(chǔ) URLJWT_SECRET需按上文生成JWT 簽名密鑰INITIAL_PASSWORDCHANGEME首次登錄密碼APP_LOG_LEVELinfo日志詳細(xì)級(jí)別1.4 Dashboard 設(shè)置Dashboard 提供了一組 UI 開(kāi)關(guān)可覆蓋同名環(huán)境變量對(duì)應(yīng)的功能默認(rèn)值設(shè)置位置開(kāi)關(guān)說(shuō)明Settings → AdvancedDebug Mode開(kāi)啟調(diào)試請(qǐng)求日志UI 側(cè)Settings → GeneralSidebar Visibility顯示/隱藏側(cè)邊欄分區(qū)從文檔說(shuō)明看這類設(shè)置持久化在數(shù)據(jù)庫(kù)SQLite中重啟后依然生效并且一旦顯式設(shè)置就會(huì)覆蓋環(huán)境變量默認(rèn)值。1.5 本地運(yùn)行以下命令均與 package.json 中scripts定義一一對(duì)應(yīng)可直接復(fù)制使用# Development mode (hot reload) npm run dev # Production build npm run build npm run start # Common port configuration PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run dev啟動(dòng)后的默認(rèn)訪問(wèn)地址Dashboardhttp://localhost:20128/dashboardAPIhttp://localhost:20128/v1二、Git 工作流文檔硬性約束永遠(yuǎn)不要直接向main提交一切變更必須走功能分支。git checkout -b feat/your-feature-name # ... make changes ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # Open a Pull Request on GitHub2.1 分支命名前綴前綴用途feat/新功能fix/缺陷修復(fù)refactor/代碼重構(gòu)docs/文檔變更test/測(cè)試補(bǔ)充/修復(fù)chore/工具鏈、CI、依賴2.2 Commit 消息規(guī)范遵循 Conventional Commits 風(fēng)格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文檔列出的常用 scopedb、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。三、測(cè)試體系命令、覆蓋率門禁與 PR 要求3.1 常用測(cè)試命令貢獻(xiàn)文檔給出的測(cè)試入口如下已對(duì)照 package.json 腳本逐一核實(shí)# All tests (unit vitest ecosystem e2e) npm run test:all # Single test file (Node.js native test runner — most tests use this) node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest (MCP server, autoCombo, cache) npm run test:vitest # E2E tests (requires Playwright) npm run test:e2e # Protocol clients E2E (MCP transports, A2A) npm run test:protocols:e2e # Ecosystem compatibility tests npm run test:ecosystem # Coverage (60% min statements/lines/functions/branches) npm run test:coverage npm run coverage:report # Lint format check npm run lint npm run check其中npm run test即npm test實(shí)際通過(guò) Node.js 原生測(cè)試運(yùn)行器執(zhí)行tests/unit/下全部*.test.ts與*.test.mjs并注入tsx/esm、SSE polyfill 與數(shù)據(jù)目錄隔離等加載器npm run test:all則是 unit vitest ecosystem e2e 的全鏈路組合。3.2 覆蓋率規(guī)則文檔對(duì)覆蓋率給出了明確約束npm run test:coverage度量主單元測(cè)試套件的源碼覆蓋率排除tests/**包含open-sse/**PR 必須讓覆蓋率門禁保持在statements / lines / functions / branches 四項(xiàng) 60% 以上。這一點(diǎn)可以在package.json中對(duì)應(yīng)腳本的參數(shù)里直接驗(yàn)證--check-coverage --statements 60 --lines 60 --functions 60 --branches 60若 PR 改動(dòng)了src/、open-sse/、electron/或bin/下的生產(chǎn)代碼必須在同一 PR 中新增或更新自動(dòng)化測(cè)試npm run coverage:report打印最近一次覆蓋率運(yùn)行的逐文件明細(xì)npm run test:coverage:legacy保留舊口徑指標(biāo)用于歷史對(duì)比分階段覆蓋率改進(jìn)路線圖見(jiàn) docs/ops/COVERAGE_PLAN.md。3.3 PR 前置要求提交 PR 前需要運(yùn)行npm run test:unit與npm run test:coverage確認(rèn)覆蓋率門禁四項(xiàng)指標(biāo)均在 60% 以上生產(chǎn)代碼有變更時(shí)在 PR 描述中列明改動(dòng)或新增的測(cè)試文件若 CI 配置了項(xiàng)目 secrets檢查 PR 上的 SonarQube 結(jié)果。文檔同時(shí)列舉了單元測(cè)試覆蓋的核心面Provider 轉(zhuǎn)換器與格式轉(zhuǎn)換、限流/熔斷/韌性、語(yǔ)義緩存/冪等/進(jìn)度跟蹤、數(shù)據(jù)庫(kù)操作與 schema、OAuth 與認(rèn)證、Zod v4 API 校驗(yàn)、MCP 工具與 scope 強(qiáng)制、Memory 與 Skills 系統(tǒng)。需要說(shuō)明的是文檔寫作時(shí)標(biāo)注122 個(gè)單元測(cè)試文件而當(dāng)前倉(cāng)庫(kù)tests/unit/目錄已擴(kuò)展到數(shù)千個(gè).test.ts文件測(cè)試規(guī)模隨版本持續(xù)擴(kuò)張以上命令在任意時(shí)點(diǎn)均適用。四、代碼風(fēng)格約定ESLint提交前運(yùn)行npm run lintPrettier通過(guò)lint-staged在提交時(shí)自動(dòng)格式化2 空格縮進(jìn)、分號(hào)、雙引號(hào)、100 字符行寬、es5 尾逗號(hào)TypeScriptsrc/全部使用.ts/.tsxopen-sse/使用.ts/.js公共函數(shù)與接口需用 TSDocparam、returns、throws注釋禁止eval()ESLint 強(qiáng)制no-eval、no-implied-eval、no-new-func三條規(guī)則Zod 校驗(yàn)所有 API 輸入校驗(yàn)必須使用 Zod v4 schema命名文件用 camelCase/kebab-case組件 PascalCase常量 UPPER_SNAKE。五、項(xiàng)目結(jié)構(gòu)速覽貢獻(xiàn)文檔給出的目錄地圖以當(dāng)前倉(cāng)庫(kù)實(shí)際布局為準(zhǔn)src/ # TypeScript (.ts / .tsx) ├── app/ # Next.js App Router │ ├── (dashboard)/ # Dashboard 頁(yè)面 │ ├── api/ # API 路由 │ └── login/ # 認(rèn)證頁(yè)面 (.tsx) ├── domain/ # 策略引擎 (policyEngine, comboResolver, costRules 等) ├── lib/ # 核心業(yè)務(wù)邏輯 (.ts) │ ├── a2a/ # Agent-to-Agent 協(xié)議服務(wù) │ ├── acp/ # Agent Communication Protocol 注冊(cè)表 │ ├── compliance/ # 合規(guī)策略引擎 │ ├── db/ # SQLite 數(shù)據(jù)層領(lǐng)域模塊 遷移 │ ├── memory/ # 持久化會(huì)話記憶 │ ├── oauth/ # OAuth 提供商、服務(wù)與工具 │ ├── skills/ # 可擴(kuò)展技能框架 │ ├── usage/ # 用量統(tǒng)計(jì)與成本計(jì)算 │ └── localDb.ts # 僅做再導(dǎo)出 —— 嚴(yán)禁在此添加邏輯 ├── middleware/ # 請(qǐng)求中間件 (promptInjectionGuard) ├── mitm/ # MITM 代理 (證書(shū)、DNS、目標(biāo)路由) ├── shared/ │ ├── components/ # React 組件 (.tsx) │ ├── constants/ # Provider 定義、MCP scopes、路由策略 │ ├── utils/ # 熔斷器、sanitizer、認(rèn)證輔助 │ └── validation/ # Zod v4 schemas └── sse/ # SSE 代理管線 open-sse/ # omniroute/open-sse workspace ├── executors/ # 各 Provider 的執(zhí)行器實(shí)現(xiàn)模塊 ├── handlers/ # 請(qǐng)求處理器 (chat, responses, embeddings, images 等) ├── mcp-server/ # MCP server ├── services/ # 頂層服務(wù) (combo, autoCombo, rateLimitManager 等) ├── translator/ # 格式轉(zhuǎn)換 (OpenAI ? Claude ? Gemini ? Responses ? Ollama) ├── transformer/ # Responses API 變換器 └── utils/ # 工具模塊 (stream, TLS, proxy, logging) electron/ # Electron 桌面應(yīng)用 (跨平臺(tái)) tests/ ├── unit/ # Node.js 原生測(cè)試運(yùn)行器 ├── integration/ # 集成測(cè)試 ├── e2e/ # Playwright 測(cè)試 ├── security/ # 安全測(cè)試 ├── translator/ # 轉(zhuǎn)換器專項(xiàng)測(cè)試 └── load/ # 負(fù)載測(cè)試 docs/ # 架構(gòu)、API 參考、排障、MCP/A2A 等文檔當(dāng)前倉(cāng)庫(kù)中open-sse/executors/下已有 190 個(gè)執(zhí)行器模塊文件含按 Provider 劃分的子目錄tests/unit/的測(cè)試文件數(shù)量為數(shù)千級(jí)別——兩者都遠(yuǎn)超文檔寫作時(shí)的數(shù)字貢獻(xiàn)時(shí)以目錄實(shí)際內(nèi)容為準(zhǔn)即可。六、新增一個(gè) Provider六步流程這是貢獻(xiàn)文檔中最具實(shí)操價(jià)值的一節(jié)每一步都指向了真實(shí)的倉(cāng)庫(kù)位置下面逐一展開(kāi)并附上源碼級(jí)佐證。Step 1注冊(cè) Provider 常量在 src/shared/constants/providers.ts 中注冊(cè)。該文件按認(rèn)證方式把 Provider 分組導(dǎo)入NOAUTH_PROVIDERS、OAUTH_PROVIDERS、APIKEY_PROVIDERS、WEB_COOKIE_PROVIDERS、UPSTREAM_PROXY_PROVIDERS、CLOUD_AGENT_PROVIDERS等分別來(lái)自src/shared/constants/providers/下的分組模塊。Zod-validated at module load 并非空話文件末尾會(huì)依次對(duì)每個(gè)分組調(diào)用validateProviders(...)約第 322–325 行該校驗(yàn)函數(shù)定義在 src/shared/validation/providerSchema.ts其中ProviderSchema基于z.object強(qiáng)制約束id、name、icon、color必須匹配#RRGGBB十六進(jìn)制正則等字段。也就是說(shuō)Provider 定義一旦寫錯(cuò)模塊加載階段就會(huì)直接拋錯(cuò)屬于快速失敗的防御設(shè)計(jì)。Step 2添加 Executor需要自定義邏輯時(shí)在open-sse/executors/your-provider.ts中創(chuàng)建執(zhí)行器繼承基礎(chǔ)執(zhí)行器。目錄中存在 open-sse/executors/base.ts 作為基類還有default/等通用實(shí)現(xiàn)從源碼結(jié)構(gòu)看大多數(shù) Provider 只需要聲明式配置走default路徑僅當(dāng)請(qǐng)求簽名、Cookie 管理、設(shè)備碼流程等邏輯特殊時(shí)才需要獨(dú)立 Executor。Step 3添加 Translator非 OpenAI 格式時(shí)在open-sse/translator/下創(chuàng)建請(qǐng)求/響應(yīng)轉(zhuǎn)換器。該目錄包含bootstrap.ts、open-sse/translator/registry.ts轉(zhuǎn)換器注冊(cè)表以及request/、response/兩個(gè)子目錄分別承載入站請(qǐng)求與出站響應(yīng)的格式轉(zhuǎn)換OmniRoute 支持在 OpenAI、Claude、Gemini、Responses、Ollama 等協(xié)議格式之間互轉(zhuǎn)。Step 4添加 OAuth 配置OAuth 類 Provider在 src/lib/oauth/constants/oauth.ts 中登記憑據(jù)并在src/lib/oauth/services/下實(shí)現(xiàn)對(duì)應(yīng)服務(wù)。當(dāng)前倉(cāng)庫(kù)的src/lib/oauth/providers/下已有 claude、codex、cursor、kimi、kiro、gitlab 等十余個(gè) OAuth 提供商實(shí)現(xiàn)可作為模板參考。Step 5注冊(cè)模型在 open-sse/config/providerRegistry.ts 中添加模型定義。該文件是模型目錄的注冊(cè)入口open-sse/config/目錄還包含freeTierCatalog.ts、embeddingRegistry.ts等配套注冊(cè)表。Step 6添加測(cè)試在tests/unit/下編寫單元測(cè)試至少覆蓋三類場(chǎng)景Provider 注冊(cè)常量與 schema 校驗(yàn)通過(guò)請(qǐng)求/響應(yīng)轉(zhuǎn)換翻譯器輸入輸出正確錯(cuò)誤處理上游失敗時(shí)的降級(jí)與錯(cuò)誤體。由于 PR 受 60% 覆蓋率門禁約束這一步不是可選項(xiàng)而是合并前置條件。七、PR 檢查清單與發(fā)布流程7.1 PR Checklist貢獻(xiàn)文檔給出的合并前清單測(cè)試通過(guò)npm testLint 通過(guò)npm run lint構(gòu)建成功npm run build新增的公共函數(shù)與接口補(bǔ)齊 TypeScript 類型無(wú)硬編碼密鑰或兜底值所有輸入均經(jīng) Zod schema 校驗(yàn)面向用戶的變更更新 CHANGELOG相關(guān)文檔同步更新7.2 發(fā)布機(jī)制發(fā)布由/generate-release工作流托管創(chuàng)建新的 GitHub Release 后包會(huì)經(jīng)由 GitHub Actions 自動(dòng)發(fā)布到 npm。對(duì)貢獻(xiàn)者而言只需保證 PR 進(jìn)入發(fā)布分支并帶上正確的變更記錄。八、延伸閱讀貢獻(xiàn)文檔在 Getting Help 一節(jié)指向了以下倉(cāng)庫(kù)內(nèi)文檔遇到具體問(wèn)題時(shí)可按圖索驥架構(gòu)docs/architecture/ARCHITECTURE.md —— 系統(tǒng)整體架構(gòu)API 參考docs/reference/API_REFERENCE.md —— 全部端點(diǎn)說(shuō)明覆蓋率路線圖docs/ops/COVERAGE_PLAN.md —— 分階段覆蓋率改進(jìn)計(jì)劃錯(cuò)誤處理范例open-sse/utils/stream.ts 與 open-sse/utils/streamHandler.ts —— SSE 流式錯(cuò)誤處理的應(yīng)用示例。整體來(lái)看OmniRoute 的貢獻(xiàn)體系以快失敗為基調(diào)Provider 常量在模塊加載期經(jīng) Zod 校驗(yàn)、覆蓋率門禁卡在 PR 合并前、lint 與類型檢查內(nèi)置于check腳本。對(duì)于想深入理解其 Provider 抽象Executor/Translator/Registry 三層或測(cè)試門禁實(shí)現(xiàn)細(xì)節(jié)的貢獻(xiàn)者上述各節(jié)的文件路徑就是最短的入口?！久赓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），僅供參考