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