OmniRoute 開(kāi)發(fā)者協(xié)作手冊(cè)架構(gòu)分層、請(qǐng)求管線與三層韌性運(yùn)行時(shí)的代碼實(shí)踐【免費(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本篇文章以docs/i18n/ja/CLAUDE.mdOmniRoute 倉(cāng)庫(kù)為 Claude Code 編寫(xiě)的日文協(xié)作指南為骨架結(jié)合倉(cāng)庫(kù)源碼與配置深度展開(kāi)。它面向兩類(lèi)讀者首次接觸該倉(cāng)庫(kù)的開(kāi)發(fā)者——需要在幾分鐘內(nèi)理清目錄分層、請(qǐng)求管線與開(kāi)發(fā)規(guī)范以及計(jì)劃為 OmniRoute 貢獻(xiàn)代碼的工程師——需要掌握新增 Provider、API 路由、DB 模塊、MCP 工具、A2A 技能時(shí)的標(biāo)準(zhǔn)套路。讀完本文你將理解這個(gè)統(tǒng)一 AI 網(wǎng)關(guān)/路由器單端點(diǎn)、多 LLM 提供商、自動(dòng)故障轉(zhuǎn)移的核心架構(gòu)并能在本地跑通開(kāi)發(fā)環(huán)境與測(cè)試流水線。OmniRoute 是一個(gè)統(tǒng)一的 AI 代理/路由器一個(gè)端點(diǎn)、數(shù)百個(gè) LLM 提供商、自動(dòng)故障轉(zhuǎn)移與組合路由combo routing。文檔撰寫(xiě)時(shí)它已接入 329 家 LLM 提供商當(dāng)前項(xiàng)目描述為 352 家含 150 免費(fèi)其代碼倉(cāng)庫(kù)采用 monorepo 結(jié)構(gòu)src/Next.js 16 應(yīng)用、open-sse/流式引擎工作區(qū)、electron/桌面應(yīng)用、tests/測(cè)試與bin/CLI 入口。本手冊(cè)是該項(xiàng)目在 CLAUDE.md 體系中沉淀的單一事實(shí)來(lái)源之一倉(cāng)庫(kù)根目錄的 CLAUDE.md 指向 AGENTS.md全部 AI 助手共享的規(guī)范總綱而各語(yǔ)言版本的 CLAUDE.md本文所依據(jù)的日文版位于 docs/i18n/ja/CLAUDE.md則記錄了面向 Claude Code 的操作性細(xì)化規(guī)則。快速上手從安裝到測(cè)試開(kāi)發(fā)環(huán)境的標(biāo)準(zhǔn)起步流程如下默認(rèn)端口20128API 與儀表盤(pán)共用同一端口npm install # 安裝依賴(lài)會(huì)自動(dòng)從 .env.example 生成 .env npm run dev # 啟動(dòng)開(kāi)發(fā)服務(wù)器監(jiān)聽(tīng) http://localhost:20128 npm run build # 生產(chǎn)構(gòu)建Next.js 16 standalone npm run lint # ESLint預(yù)期 0 錯(cuò)誤警告為既有存量 npm run typecheck:core # TypeScript 類(lèi)型檢查應(yīng)保持干凈 npm run typecheck:noimplicit:core # 嚴(yán)格檢查不允許隱式 any npm run test:coverage # 單元測(cè)試 覆蓋率門(mén)禁75/75/75/70 — 語(yǔ)句/行/函數(shù)/分支 npm run check # lint 測(cè)試的組合 npm run check:cycles # 檢測(cè)循環(huán)依賴(lài)單測(cè)運(yùn)行方式很有特點(diǎn)絕大多數(shù)測(cè)試走Node.js 原生測(cè)試運(yùn)行器通過(guò) tsx 加載 TS# 單個(gè)測(cè)試文件 node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest用于 MCP 服務(wù)器、自動(dòng)組合、緩存相關(guān)測(cè)試 npm run test:vitest # 全部測(cè)試套件 npm run test:all更完整的測(cè)試矩陣見(jiàn) CONTRIBUTING.md 的運(yùn)行測(cè)試章節(jié)深層架構(gòu)分析參考 AGENTS.md。項(xiàng)目總體架構(gòu)分層與目錄文檔用一個(gè)分層表勾勒出整個(gè)系統(tǒng)的職責(zé)邊界這是理解 OmniRoute 的鑰匙層位置職責(zé)API 路由src/app/api/v1/Next.js App Router 入口點(diǎn)處理器open-sse/handlers/請(qǐng)求處理chat、embedding 等執(zhí)行器open-sse/executors/提供商特定的 HTTP 分發(fā)轉(zhuǎn)換器open-sse/translator/格式轉(zhuǎn)換OpenAI ? Claude ? Gemini變換器open-sse/transformer/響應(yīng) API ? 聊天補(bǔ)全服務(wù)open-sse/services/組合路由、限流、緩存等數(shù)據(jù)庫(kù)src/lib/db/110 個(gè)頂層 SQLite 領(lǐng)域模塊、130 個(gè)遷移當(dāng)前倉(cāng)庫(kù)實(shí)際已積累 172 個(gè)遷移文件見(jiàn)src/lib/db/migrations/領(lǐng)域/策略src/domain/策略引擎、成本規(guī)則、故障轉(zhuǎn)移邏輯MCP 服務(wù)器open-sse/mcp-server/107 個(gè)唯一工具、3 種傳輸stdio / SSE / Streamable HTTP、32 個(gè)作用域A2A 服務(wù)器src/lib/a2a/JSON-RPC 2.0 代理協(xié)議技能src/lib/skills/可擴(kuò)展的技能框架記憶src/lib/memory/持久化會(huì)話(huà)記憶其中 A2A 技能、記憶系統(tǒng)等模塊在源碼中均有實(shí)際落盤(pán)src/lib/a2a/skills/下已存在 smartRouting、quotaManagement、providerDiscovery、costAnalysis、healthReport 五個(gè)內(nèi)置技能任務(wù)執(zhí)行注冊(cè)表 將其掛接為A2A_SKILL_HANDLERS記憶后端見(jiàn) src/lib/memory。請(qǐng)求管線從客戶(hù)端到上游的完整鏈路文檔給出了完整請(qǐng)求管線值得逐行拆解Client → /v1/chat/completions (Next.js 路由) → CORS → Zod 校驗(yàn) → 認(rèn)證? → 策略檢查 → 提示注入防護(hù) → handleChatCore() [open-sse/handlers/chatCore.ts] → 緩存檢查 → 限流 → 組合路由? → resolveComboTargets() → 對(duì)每個(gè)目標(biāo)調(diào)用 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → fetch() 上游 → 帶退避的重試 → 響應(yīng)轉(zhuǎn)換 → SSE 流或 JSON → 若為 Responses API: responsesTransformer.ts TransformStreamchatCore.tsopen-sse/handlers/chatCore.ts是這條管線的心臟它先做緩存命中檢查、限流判定再?zèng)Q定是否進(jìn)入組合路由每個(gè)組合目標(biāo)通過(guò)handleSingleModel()包裹handleChatCore()并附加按目標(biāo)隔離的錯(cuò)誤處理與斷路器檢查。API 路由遵循統(tǒng)一模式路由 → CORS 預(yù)檢 → Zod 請(qǐng)求體校驗(yàn) → 可選認(rèn)證extractApiKey/isValidApiKey→ API 密鑰策略強(qiáng)制 → 處理器委托open-sse。值得注意項(xiàng)目沒(méi)有全局 Next.js 中間件所有攔截都是路由級(jí)的。組合路由open-sse/services/combo.ts當(dāng)前支持 19 種公開(kāi)策略priority、weighted、fill-first、round-robin、p2c、random、least-used、cost-optimized、reset-aware、reset-window、headroom、strict-random、auto、lkgp、context-optimized、cache-optimized、context-relay、fusion、pipeline。源碼中strategy作為組合對(duì)象的顯式字段貫穿選擇流程combo.ts并針對(duì)round-robin原生輪轉(zhuǎn)釘扎、quota-share配額份額并發(fā)限制等策略做了特殊分支。13 因子 Auto-Combo 評(píng)分見(jiàn) docs/routing/AUTO-COMBO.md三層韌性見(jiàn) docs/architecture/RESILIENCE_GUIDE.md。韌性運(yùn)行時(shí)三種易混淆的失敗隔離機(jī)制OmniRoute 擁有三個(gè)相關(guān)但作用域不同的臨時(shí)失敗機(jī)制。調(diào)試路由行為時(shí)務(wù)必分清它們各自管什么對(duì)應(yīng)架構(gòu)圖docs/diagrams/exported/resilience-3layers.svg源文件為 docs/diagrams/resilience-3layers.mmd。提供商斷路器Provider Circuit Breaker作用域整個(gè)提供商如glm、openai、anthropic。目的在上游/服務(wù)層面持續(xù)失敗時(shí)停止向該提供商投遞流量防止單個(gè)不健康提供商拖慢所有請(qǐng)求。實(shí)現(xiàn)落點(diǎn)核心類(lèi)src/shared/utils/circuitBreaker.tsCircuitBreaker類(lèi)及CircuitBreakerOpenError聊天門(mén)控/執(zhí)行接線src/sse/handlers/chatHelpers.ts、src/sse/handlers/chat.ts運(yùn)行時(shí)狀態(tài) APIsrc/app/api/monitoring/health/route.ts共享包裝器open-sse/services/accountFallback.ts持久化狀態(tài)表domain_circuit_breakers狀態(tài)機(jī)CLOSED允許正常流量。OPEN提供商被臨時(shí)封禁調(diào)用方收到提供商斷路器打開(kāi)的響應(yīng)或組合路由跳過(guò)該目標(biāo)轉(zhuǎn)向其他目標(biāo)。HALF_OPEN重置超時(shí)已過(guò)放行探測(cè)請(qǐng)求成功則關(guān)閉斷路器失敗則重新打開(kāi)。默認(rèn)參數(shù)定義于 open-sse/config/constants.ts均可通過(guò)環(huán)境變量覆蓋提供商類(lèi)型閾值連續(xù)失敗次數(shù)重置超時(shí)觸頂冷卻環(huán)境變量OAuth 提供商860s5minOMNIROUTE_CIRCUIT_BREAKER_OAUTH_*API 密鑰提供商1230s10minOMNIROUTE_CIRCUIT_BREAKER_API_KEY_*本地提供商215s1minOMNIROUTE_CIRCUIT_BREAKER_LOCAL_*日文文檔早期版本記載為 OAuth 3/60s、API 密鑰 5/30s當(dāng)前源碼默認(rèn)值已調(diào)整為上表數(shù)值并全面支持環(huán)境變量覆蓋。只有提供商級(jí)別的失敗狀態(tài)才能觸發(fā)提供商斷路器(408, 500, 502, 503, 504);而大多數(shù)401、403、429普通賬戶(hù)/密鑰/模型錯(cuò)誤不應(yīng)觸發(fā)整提供商斷路器——它們通常歸連接冷卻或模型鎖定處理。通用 API 密鑰提供商的403只要未被歸類(lèi)為終態(tài)提供商/賬戶(hù)錯(cuò)誤就應(yīng)視為可恢復(fù)。斷路器采用惰性恢復(fù)而非后臺(tái)定時(shí)器OPEN過(guò)期后由getStatus()、canExecute()、getRetryAfterMs()等讀操作將狀態(tài)推進(jìn)到HALF_OPEN從而避免儀表盤(pán)與組合候選構(gòu)建器把已過(guò)期的提供商永久排除在外。連接冷卻Connection Cooldown作用域單個(gè)提供商連接/賬戶(hù)/密鑰。目的在同一個(gè)提供商的其他連接繼續(xù)服務(wù)請(qǐng)求的同時(shí)臨時(shí)跳過(guò)某個(gè)壞密鑰/壞賬戶(hù)。實(shí)現(xiàn)落點(diǎn)寫(xiě)入/更新路徑src/sse/services/auth.ts::markAccountUnavailable()賬戶(hù)選擇/過(guò)濾src/sse/services/auth.ts::getProviderCredentials...冷卻計(jì)算open-sse/services/accountFallback.ts::checkFallbackError()配置src/lib/resilience/settings.ts提供商連接的關(guān)鍵字段rateLimitedUntil; testStatus: unavailable; lastError; lastErrorType; errorCode; backoffLevel;賬戶(hù)選擇期間滿(mǎn)足以下條件的連接會(huì)被跳過(guò)new Date(rateLimitedUntil).getTime() Date.now();冷卻同樣是惰性的當(dāng)rateLimitedUntil已成為過(guò)去時(shí)連接重新進(jìn)入候選池。成功使用后clearAccountError()會(huì)清空testStatus、rateLimitedUntil、錯(cuò)誤字段與backoffLevel見(jiàn) auth.ts 中的標(biāo)記與清理路徑。默認(rèn)連接冷卻行為OAuth 基礎(chǔ)冷卻5sAPI 密鑰基礎(chǔ)冷卻3s。API 密鑰429應(yīng)優(yōu)先遵循上游重試提示Retry-After頭、reset 頭或可解析的 reset 文本若可用。反復(fù)可恢復(fù)失敗采用指數(shù)退避baseCooldownMs * 2 ** failureIndex;防驚群硬門(mén)禁anti-thundering herd同一連接上的并發(fā)失敗不得反復(fù)延長(zhǎng)冷卻或雙重遞增backoffLevel對(duì)應(yīng)src/sse/services/auth.ts中的 per-connection 互斥標(biāo)記邏輯。終態(tài)不是冷卻banned、expired、credits_exhausted意味著在憑證/配置變更或操作者重置之前保持不可用絕不能用臨時(shí)冷卻狀態(tài)覆蓋終態(tài)。模型鎖定Model Lockout作用域提供商 連接 模型。目的單個(gè)模型不可用或配額受限時(shí)不使整個(gè)連接失效。典型觸發(fā)場(chǎng)景按模型配額的提供商返回429本地提供商對(duì)單個(gè)缺失模型返回404提供商特定的模式/模型權(quán)限失敗如選定的 Grok 模式。模型鎖定實(shí)現(xiàn)在 open-sse/services/accountFallback.ts允許同一連接繼續(xù)服務(wù)其他模型。調(diào)試指引文檔給出的排查決策樹(shù)非常實(shí)用若提供商的所有密鑰都被跳過(guò)先看提供商斷路器狀態(tài)、各連接的rateLimitedUntil/testStatus。若重置窗口后提供商仍像被永久排除確認(rèn)代碼用的是getStatus()/canExecute()而非裸讀原始state。若單個(gè)提供商密鑰失敗而其他密鑰應(yīng)正常優(yōu)先排查連接冷卻而非提供商斷路器。若只有單個(gè)模型失敗優(yōu)先排查模型鎖定而非連接冷卻。若狀態(tài)應(yīng)自我恢復(fù)讀路徑必須能更新已過(guò)期的未來(lái)時(shí)間戳/重置超時(shí)狀態(tài)持久化的終態(tài)則必須靠手動(dòng)憑證或設(shè)置變更才能恢復(fù)。開(kāi)發(fā)約定風(fēng)格、數(shù)據(jù)庫(kù)、錯(cuò)誤處理與安全代碼風(fēng)格2 空格縮進(jìn)、分號(hào)、雙引號(hào)、100 字符寬度、es5 尾隨逗號(hào)經(jīng) lint-staged 由 Prettier 強(qiáng)制執(zhí)行。導(dǎo)入順序外部 → 內(nèi)部/、omniroute/open-sse→ 相對(duì)。命名文件駝峰/短橫線組件帕斯卡常量UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func在任何位置均為錯(cuò)誤no-explicit-any在open-sse/與tests/中為警告。TypeScriptstrict: false、target ES2022、module esnext、resolution bundler優(yōu)先顯式類(lèi)型。數(shù)據(jù)庫(kù)鐵律始終通過(guò)src/lib/db/領(lǐng)域模塊訪問(wèn)數(shù)據(jù)庫(kù)——絕不在路由或處理器中寫(xiě)裸 SQL。絕不向 src/lib/localDb.ts 添加邏輯它只是再導(dǎo)出層。絕不從localDb.ts做 barrel 導(dǎo)入——應(yīng)導(dǎo)入具體的db/模塊。DB 單例getDbInstance()來(lái)自 src/lib/db/core.tsWAL 日志模式。遷移src/lib/db/migrations/——版本化 SQL 文件冪等且在事務(wù)內(nèi)執(zhí)行。錯(cuò)誤處理用具體錯(cuò)誤類(lèi)型配合 pino 上下文日志做 try/catch。不在 SSE 流內(nèi)靜默吞掉錯(cuò)誤——用中止信號(hào)做清理。返回恰當(dāng)?shù)?HTTP 狀態(tài)碼4xx/5xx。安全要點(diǎn)絕不使用eval()、new Function()或隱式 eval。所有輸入經(jīng) Zod 模式校驗(yàn)。靜態(tài)憑證使用 AES-256-GCM 加密。上游頭拒斥清單src/shared/constants/upstreamHeaders.ts——修改時(shí)需同步對(duì)齊清理邏輯、Zod 模式與單元測(cè)試。公開(kāi)上游憑證Gemini/Antigravity/Windsurf 風(fēng)格的 OAuth client_id/secret、從公開(kāi) CLI 提取的 Firebase Web 密鑰必須經(jīng)open-sse/utils/publicCreds.ts::resolvePublicCred()嵌入絕不寫(xiě)成字符串字面量。強(qiáng)制模式見(jiàn) docs/security/PUBLIC_CREDS.md。錯(cuò)誤響應(yīng)HTTP/SSE/執(zhí)行器/MCP 處理器必須經(jīng) open-sse/utils/error.ts 的buildErrorBody()或sanitizeErrorMessage()路由絕不把原始err.stack/err.message放進(jìn)響應(yīng)體。詳見(jiàn) docs/security/ERROR_SANITIZATION.md。由變量拼裝的 shell 命令調(diào)用exec()/spawn()時(shí)若腳本需要運(yùn)行時(shí)值通過(guò)env選項(xiàng)傳遞自動(dòng) shell 轉(zhuǎn)義——絕不把不可信/外部路徑字符串插值進(jìn)腳本體。參照src/mitm/cert/install.ts::updateNssDatabases。默認(rèn)安全的庫(kù)新增安全敏感面時(shí)優(yōu)先選擇 Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink 等久經(jīng)驗(yàn)證的庫(kù)而非自研實(shí)現(xiàn)。常見(jiàn)擴(kuò)展場(chǎng)景六條標(biāo)準(zhǔn)套路新增一個(gè)提供商在src/shared/constants/providers.ts注冊(cè)加載時(shí)經(jīng) Zod 校驗(yàn)。如需自定義邏輯在open-sse/executors/添加執(zhí)行器繼承BaseExecutor。非 OpenAI 格式則在open-sse/translator/添加轉(zhuǎn)換器。OAuth 類(lèi)提供商在src/lib/oauth/constants/oauth.ts添加 OAuth 配置——若上游 CLI 公開(kāi)了 client_id/secret經(jīng)resolvePublicCred()嵌入見(jiàn) docs/security/PUBLIC_CREDS.md絕不寫(xiě)成字面量。在open-sse/config/providerRegistry.ts注冊(cè)模型。在tests/unit/寫(xiě)測(cè)試若新增了內(nèi)嵌默認(rèn)值需包含 publicCreds 形狀斷言。新增一條 API 路由在src/app/api/v1/your-route/下建目錄。創(chuàng)建帶GET/POST處理器的route.ts。遵循統(tǒng)一模式CORS → Zod 體校驗(yàn) → 可選認(rèn)證 → 處理器委托。處理器放在open-sse/handlers/從那里導(dǎo)入而非內(nèi)聯(lián)。錯(cuò)誤響應(yīng)使用open-sse/utils/error.ts的buildErrorBody()/errorResponse()自動(dòng)清理響應(yīng)體不放原始err.stack/err.message。參考 docs/security/ERROR_SANITIZATION.md。添加測(cè)試——至少包含一條斷言錯(cuò)誤響應(yīng)不泄漏堆棧軌跡!body.error.message.includes(at /)。新增一個(gè) DB 模塊創(chuàng)建src/lib/db/yourModule.ts——從./core.ts導(dǎo)入getDbInstance。為領(lǐng)域表導(dǎo)出 CRUD 函數(shù)。需要新表時(shí)在src/lib/db/migrations/添加遷移。從src/lib/localDb.ts再導(dǎo)出僅加入再導(dǎo)出列表。寫(xiě)測(cè)試。新增一個(gè) MCP 工具在open-sse/mcp-server/tools/添加工具定義Zod 輸入模式 異步處理器。注冊(cè)進(jìn)工具集由createMcpServer()裝配。分配合適的作用域。寫(xiě)測(cè)試工具調(diào)用會(huì)記入mcp_audit表。新增一個(gè) A2A 技能在src/lib/a2a/skills/創(chuàng)建技能已有 5 個(gè)smart-routing、quota-management、provider-discovery、cost-analysis、health-report。技能接收任務(wù)上下文消息、元數(shù)據(jù)→ 返回結(jié)構(gòu)化結(jié)果。在src/lib/a2a/taskExecution.ts的A2A_SKILL_HANDLERS注冊(cè)。在src/app/.well-known/agent.json/route.ts公開(kāi)agent card。在tests/unit/寫(xiě)測(cè)試。在 docs/frameworks/A2A-SERVER.md 的技能表中補(bǔ)充文檔。新增一個(gè)云代理Cloud Agent在src/lib/cloudAgent/agents/創(chuàng)建繼承CloudAgentBase的代理類(lèi)已有 3 個(gè)codex-cloud、devin、jules。實(shí)現(xiàn)createTask、getStatus、approvePlan、sendMessage、listSources。在src/lib/cloudAgent/registry.ts注冊(cè)。按需添加 OAuth/憑證處理src/lib/oauth/providers/。寫(xiě)測(cè)試并補(bǔ)充 docs/frameworks/CLOUD_AGENT.md。新增 Guardrail / Eval / 技能 / Webhook 事件Guardrailsrc/lib/guardrails/→ 文檔docs/security/GUARDRAILS.mdEval 套件src/lib/evals/→ 文檔docs/frameworks/EVALS.md技能沙箱src/lib/skills/→ 文檔docs/frameworks/SKILLS.mdWebhook 事件src/lib/webhookDispatcher.ts→ 文檔docs/frameworks/WEBHOOKS.md測(cè)試策略與覆蓋率門(mén)禁測(cè)試類(lèi)型命令單元測(cè)試npm run test:unit單個(gè)文件node --import tsx/esm --test tests/unit/file.test.tsVitestMCP、autoCombonpm run test:vitestE2EPlaywrightnpm run test:e2e協(xié)議 E2EMCPA2Anpm run test:protocols:e2e生態(tài)npm run test:ecosystem覆蓋率門(mén)禁npm run test:coverage75/75/75/70 — 語(yǔ)句/行/函數(shù)/分支覆蓋率報(bào)告npm run coverage:reportPR 規(guī)則修改了src/、open-sse/、electron/或bin/下的生產(chǎn)代碼同一 PR 必須包含或更新測(cè)試。測(cè)試層次優(yōu)先級(jí)單元 → 集成多模塊或 DB 狀態(tài)→ E2E僅 UI/工作流。bug 復(fù)現(xiàn)應(yīng)在修復(fù)前或同時(shí)編碼為自動(dòng)化測(cè)試。Copilot 覆蓋率政策若 PR 修改生產(chǎn)代碼且覆蓋率低于 75%語(yǔ)句/行/函數(shù)或 70%分支應(yīng)補(bǔ)充或更新測(cè)試并重跑覆蓋率門(mén)禁而不是只報(bào)告數(shù)字在 PR 報(bào)告中寫(xiě)明執(zhí)行的命令、變更的測(cè)試文件與最終覆蓋率結(jié)果。Git 工作流與本地環(huán)境# 不要直接提交到 main git checkout -b feat/your-feature git commit -m feat: 描述你的改動(dòng) git push -u origin feat/your-feature分支前綴feat/、fix/、refactor/、docs/、test/、chore/。提交格式Conventional Commitsfeat(db): 添加斷路器——作用域db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。Husky 鉤子pre-commit 運(yùn)行 lint-staged check-docs-synccheck:any-budget:t11pre-push 運(yùn)行npm run test:unit。環(huán)境要求運(yùn)行時(shí)Node.js ≥20.20.2 21 | ≥22.22.2 23 | ≥24 25ES Modules。TypeScript5.9target ES2022module esnextresolution bundler。路徑別名/*→src/omniroute/open-sse→open-sse/omniroute/open-sse/*→open-sse/*。默認(rèn)端口20128API 儀表盤(pán)同端口。數(shù)據(jù)目錄DATA_DIR環(huán)境變量默認(rèn)~/.omniroute/。主要環(huán)境變量PORT、JWT_SECRET、API_KEY_SECRET、INITIAL_PASSWORD、REQUIRE_API_KEY、APP_LOG_LEVEL。初始化cp .env.example .env然后生成JWT_SECRETopenssl rand -base64 48與API_KEY_SECRETopenssl rand -hex 32。硬性規(guī)則清單不提交密鑰或憑證。不向localDb.ts添加邏輯。不使用eval()/new Function()/ 隱式 eval。不直接提交到main。不在路由中寫(xiě)裸 SQL——使用src/lib/db/模塊。不在 SSE 流中靜默吞掉錯(cuò)誤。始終用 Zod 模式校驗(yàn)輸入。修改生產(chǎn)代碼時(shí)始終包含測(cè)試。覆蓋率須始終 ≥75%語(yǔ)句、行、函數(shù)/ ≥70%分支當(dāng)前實(shí)測(cè)約 82%。未經(jīng)操作者明確批準(zhǔn)不繞過(guò) Husky 鉤子--no-verify、--no-gpg-sign。不把公開(kāi)上游 OAuth client_id/secret 或 Firebase Web 密鑰作為字符串字面量嵌入——始終經(jīng)resolvePublicCred()open-sse/utils/publicCreds.ts見(jiàn) docs/security/PUBLIC_CREDS.md。不在 HTTP/SSE/執(zhí)行器響應(yīng)中返回原始err.stack/err.message——始終經(jīng)buildErrorBody()或sanitizeErrorMessage()open-sse/utils/error.ts見(jiàn) docs/security/ERROR_SANITIZATION.md。不把外部路徑或運(yùn)行時(shí)值字符串插值進(jìn)傳給exec()/spawn()的 shell 腳本——改用env選項(xiàng)傳遞參照src/mitm/cert/install.ts::updateNssDatabases。不忽略 CodeQL / Secret-Scanning 告警——先核對(duì)上述模式文檔判斷是否有現(xiàn)成助手可應(yīng)用確需忽略時(shí)在注釋中記錄技術(shù)理由已知先例js/stack-trace-exposure在已過(guò)sanitizeErrorMessage()的調(diào)用點(diǎn)上是 CodeQL 限制誤報(bào)按 false positive 忽略并參照 docs/security/ERROR_SANITIZATION.md。不把產(chǎn)生子進(jìn)程的路由/api/mcp/、/api/cli-tools/runtime/在src/server/authz/routeGuard.ts中未作isLocalOnlyPath()分類(lèi)就公開(kāi)——回環(huán)強(qiáng)制在認(rèn)證檢查前無(wú)條件執(zhí)行經(jīng)隧道泄漏的 JWT 無(wú)法觸發(fā)進(jìn)程創(chuàng)建見(jiàn) docs/security/ROUTE_GUARD_TIERS.md。絕不在提交信息中加入承認(rèn) AI 助手/LLM/自動(dòng)化賬戶(hù)的Co-Authored-By尾注如含 Claude、GPT、Copilot、Bot 的名字anthropic.com/openai.com/機(jī)器人所有的noreply.github.com郵箱——這類(lèi)尾注會(huì)把提交歸屬路由到機(jī)器人賬戶(hù)掩蓋真實(shí)作者人類(lèi)協(xié)作者包括上游 PR 作者、移植 issue 的報(bào)告者則可以且應(yīng)該使用標(biāo)準(zhǔn)Co-authored-by: Name email尾注upstream-port 工作流依賴(lài)這一機(jī)制。參考文檔索引非平凡改動(dòng)前先讀對(duì)應(yīng)領(lǐng)域的詳細(xì)文檔領(lǐng)域文檔倉(cāng)庫(kù)導(dǎo)航docs/architecture/REPOSITORY_MAP.md架構(gòu)docs/architecture/ARCHITECTURE.md工程參考docs/architecture/CODEBASE_DOCUMENTATION.mdAuto-Combo因子評(píng)分與策略docs/routing/AUTO-COMBO.md韌性三大機(jī)制docs/architecture/RESILIENCE_GUIDE.md推理重放docs/routing/REASONING_REPLAY.md技能框架docs/frameworks/SKILLS.md記憶系統(tǒng)FTS5 Qdrantdocs/frameworks/MEMORY.md云代理docs/frameworks/CLOUD_AGENT.mdGuardrailsPII/注入/視覺(jué)docs/security/GUARDRAILS.md公開(kāi)上游憑證如 Geminidocs/security/PUBLIC_CREDS.md錯(cuò)誤消息清理docs/security/ERROR_SANITIZATION.mdEvaldocs/frameworks/EVALS.md合規(guī)/審計(jì)docs/security/COMPLIANCE.mdWebhookdocs/frameworks/WEBHOOKS.md授權(quán)管線docs/architecture/AUTHZ_GUIDE.md隱身TLS/指紋docs/security/STEALTH_GUIDE.md代理協(xié)議A2A/ACP/云docs/frameworks/AGENT_PROTOCOLS_GUIDE.mdMCP 服務(wù)器docs/frameworks/MCP-SERVER.mdA2A 服務(wù)器docs/frameworks/A2A-SERVER.mdAPI 參考 OpenAPIdocs/reference/API_REFERENCE.md docs/reference/openapi.yaml提供商目錄自動(dòng)生成docs/reference/PROVIDER_REFERENCE.md發(fā)布流程docs/ops/RELEASE_CHECKLIST.md掌握上述內(nèi)容后你既能在幾分鐘內(nèi)定位任意請(qǐng)求的完整處理鏈路也能安全地新增提供商、路由、數(shù)據(jù)庫(kù)模塊、MCP 工具或 A2A 技能——這正是把 OmniRoute 從一個(gè)端點(diǎn)擴(kuò)展為一套可運(yùn)營(yíng)的 AI 網(wǎng)關(guān)體系所需的核心能力。【免費(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），僅供參考