面向 AI 编码代理的 OmniRoute 仓库开发指南架构脉络、三层韧性机制与硬性规则解析【免费下载链接】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 是一个统一 AI 网关/路由器项目提供单一端点、数百家 LLM 提供商接入与自动故障转移能力。本文基于仓库内的开发指南文档docs/i18n/sk/CLAUDE.md面向 Claude Code 等 AI 编码代理系统梳理仓库的分层架构、请求处理管线、运行时韧性三机制Provider 断路器 / 连接冷却 / 模型锁定、编码与安全约定、常见扩展场景及 Git 工作流并结合仓库源码给出可验证的实现证据帮助开发者在 OmniRoute 中快速定位代码、安全地提交变更。快速开始从安装到质检命令仓库根目录的 package.json 集中定义了全部脚本。开发环境搭建与日常质量检查的完整命令如下npm install # 安装依赖postinstall 会自动从 .env.example 生成 .env npm run dev # 启动开发服务器默认 http://localhost:20128 npm run build # 生产构建Next.js 16 独立构建 npm run lint # ESLint预期 0 错误警告来自历史存量 npm run typecheck:core # TypeScript 核心类型检查应保持干净 npm run typecheck:noimplicit:core # 严格检查不允许隐式 any npm run test:coverage # 单元测试 覆盖率门槛 75/75/75/70语句/行/函数/分支 npm run check # lint test 的组合命令 npm run check:cycles # 循环依赖检测其中typecheck:noimplicit:core对应 tsconfig.typecheck-noimplicit-core.json是比普通类型检查更严格的一道门。npm run check相当于lint test是提交前的基础自检。运行测试仓库的测试体系分为多个运行器视被测模块而异# 单个测试文件Node.js 原生 test runner覆盖大多数测试 node --import tsx/esm --test tests/unit/your-file.test.ts # VitestMCP server、autoCombo、cache 相关 npm run test:vitest # 全部测试套件 npm run test:all完整的测试矩阵见 CONTRIBUTING.md 的 运行测试 一节深入的架构说明见 AGENTS.md。从 package.json 可以看到测试命令的完整形态多数单元测试以node --import tsx/esm --test运行并通过tests/_setup/isolateDataDir.ts隔离数据目录DISABLE_SQLITE_AUTO_BACKUPtrue避免测试期间触发自动备份。项目一览分层架构OmniRoute是一个统一的 AI 代理/路由器单一端点接入数百家 LLM 提供商并具备自动回退能力。关联文档撰写时记载约 329 家提供商而当前 package.json 描述已演进为 356 providers可见目录与生态仍在持续扩充。仓库整体是一个 Monorepo由src/Next.js 16 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/测试、bin/CLI 入口组成。各层职责如下表层次位置职责API Routessrc/app/api/v1/Next.js App Router请求入口Handlersopen-sse/handlers/请求处理chat、embeddings 等Executorsopen-sse/executors/按提供商定制的 HTTP 分发Translatorsopen-sse/translator/格式转换OpenAI ↔ Claude ↔ GeminiTransformeropen-sse/transformer/API 响应 ↔ Chat CompletionsServicesopen-sse/services/组合路由、限流、缓存等Databasesrc/lib/db/SQLite 领域模块与版本化迁移Domain/Policysrc/domain/策略引擎、成本规则、回退逻辑MCP Serveropen-sse/mcp-server/工具服务器多传输、多作用域A2A Serversrc/lib/a2a/JSON-RPC 2.0 代理协议Skillssrc/lib/skills/可扩展技能框架Memorysrc/lib/memory/持久会话记忆从目录结构看open-sse/是一个独立的 npm workspace见 package.json 的 workspaces 字段与 pnpm-workspace.yaml内部再次按 handlers / executors / translator / transformer / services / mcp-server / utils 分模块与文档描述一致。请求管线从客户端到上游文档给出了请求的全链路示意这是理解 OmniRoute 最核心的流程图客户端 → /v1/chat/completions (Next.js 路由) → CORS → Zod 校验 → 认证? → 策略检查 → prompt 注入防护 → handleChatCore() [open-sse/handlers/chatCore.ts] → 缓存检查 → 请求限流 → combo 路由? → resolveComboTargets() → 对每个目标执行 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → fetch() 上游 → 带退避的重试 → 响应翻译 → SSE 流或 JSON → 若为 Responses API: responsesTransformer.ts TransformStream所有 API 路由遵循一致的模式路由 → CORS preflight → Zod 请求体验证 → 可选认证extractApiKey/isValidApiKey→ API 密钥策略强制 → 委托给 handleropen-sse。仓库没有全局 Next.js middleware拦截逻辑全部按路由定制这一点在源码中可以得到印证。两个关键实现点handleChatCore()定义于 open-sse/handlers/chatCore.ts是整个 chat 请求处理的枢纽负责缓存、限流与 combo 路由的编排。Combo 路由open-sse/services/combo.ts提供 19 种公开策略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。每个目标通过handleSingleModel()执行它对handleChatCore()做逐目标错误处理与断路器检查包装。组合打分与弹性层的细节分别见 docs/routing/AUTO-COMBO.md13 因子 Auto-Combo 打分与 docs/architecture/RESILIENCE_GUIDE.md3 层弹性架构。运行时韧性状态三个容易混淆的容错机制OmniRoute 有三套相互关联但范围不同的临时故障处理机制。调试路由行为时务必区分它们的作用域否则容易误判故障来源。文档建议先查看韧性架构图mermaid 源文件见 docs/diagrams/resilience-3layers.mmd。1. 提供商断路器Provider Circuit Breaker作用域整个提供商例如glm、openai、anthropic。目的对在 upstream/服务层面反复失败的提供商停止发送流量防止单个不健康提供商拖慢每一个请求。实现核心类src/shared/utils/circuitBreaker.tsChat 门控/执行接线src/sse/handlers/chatHelpers.ts、src/sse/handlers/chat.ts运行时状态 APIsrc/app/api/monitoring/health/route.ts共享包装open-sse/services/accountFallback.ts持久化状态表domain_circuit_breakers状态机CLOSED正常运行→OPEN提供商被临时屏蔽调用方收到 provider-circuit-open 或 combo 路由转向其他目标→HALF_OPEN重置超时已过放行探针请求成功即闭合失败则再次断开。从源码看circuitBreaker.ts 的状态机还包含DEGRADED过渡态CLOSED → DEGRADED → OPEN → HALF_OPEN → CLOSED并对探针请求数量halfOpenAllowed、成功率恢复等做了精细控制。默认阈值定义于 open-sse/config/constants.tsOAuth 提供商阈值 3重置超时 60s。API Key 提供商阈值 5重置超时 30s。本地提供商阈值 2重置超时 15s。需要说明的是随着仓库演进连接规模扩大当前 constants.ts 中这些默认值已被上调例如 OAuth 阈值提升并新增了OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD、OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD等环境变量覆盖项并引入了 DEGRADED 分级与失败窗口统计操作者可通过OMNIROUTE_CIRCUIT_BREAKER_*系列环境变量调硬或调软。因此上述数值应视为文档记载的基础值实际默认值以当前 constants.ts 为准。触发条件只有提供商层面的失败状态才应触发提供商断路器(408, 500, 502, 503, 504);不要因为普通的账号/密钥/模型错误如大多数401、403、429场景就打开整个提供商断路器——这些通常属于连接冷却或模型锁定。通用的 API Key 提供商403应可恢复除非被归类为提供商/账号的终止性错误。惰性恢复断路器使用惰性恢复而非后台定时器。当OPEN超时后getStatus()、canExecute()、getRetryAfterMs()等读路径会把状态刷新为HALF_OPEN从而保证监控面板和 combo 候选构建器不会永久排除已过期的提供商。2. 连接冷却Connection Cooldown作用域提供商下的单个账号/密钥连接。目的临时跳过某个坏密钥/账号同时同一提供商的其他连接继续正常服务。实现写入/更新路径src/sse/services/auth.ts::markAccountUnavailable()账号选择/过滤src/sse/services/auth.ts::getProviderCredentials...冷却计算open-sse/services/accountFallback.ts::checkFallbackError()设置src/lib/resilience/settings.ts关键字段挂在提供商连接上rateLimitedUntil; testStatus: unavailable; lastError; lastErrorType; errorCode; backoffLevel;选号选择账号时满足以下条件即跳过该连接new Date(rateLimitedUntil).getTime() Date.now();冷却同样是惰性的当rateLimitedUntil落在过去连接重新具备资格。成功使用后clearAccountError()会清空testStatus、rateLimitedUntil、错误字段与backoffLevel。默认行为OAuth 基础冷却5s。API Key 基础冷却3s。API Key 的429应优先遵循上游重试提示Retry-After、reset 头或可解析的 reset 文本。连续可恢复失败使用指数退避baseCooldownMs * 2 ** failureIndex;批量失败保护thundering-herd guard防止同一连接上的并发失败反复延长冷却或重复抬高backoffLevel。终止状态不是冷却banned、expired、credits_exhausted设计为在凭据/设置变更或操作者恢复前保持不可用不得把终止状态改写为临时冷却状态。3. 模型锁定Model Lockout作用域提供商 连接 模型。目的当某个连接上只有一个模型不可用或被配额限制时避免停用整个连接。典型场景按模型配额计费的提供商返回429。本地提供商对单个缺失模型返回404。提供商特有的模式/模型权限失败如 Grok 的选定模式。模型锁定实现于 open-sse/services/accountFallback.ts允许同一连接继续服务其他模型。调试指引若某提供商的所有密钥都被跳过先检查提供商断路器状态以及各自的rateLimitedUntil/testStatus。若提供商在重置窗口后仍被永久排除检查代码是否读取了原始state而非使用getStatus()/canExecute()。若某个密钥失败而其他密钥正常优先怀疑连接冷却而非提供商断路器。若只有单个模型失败优先怀疑模型锁定而非连接冷却。若某个状态应自动恢复它应当具备未来时间戳/重置超时以及能刷新过期状态的读路径永久状态则需要人工修改凭据或配置。关键约定代码、数据库、错误与安全代码风格2 空格缩进、分号、双引号、100 字符宽、es5 尾逗号由 lint-staged 通过 Prettier 强制。Import 顺序外部 → 内部/、omniroute/open-sse→ 相对路径。命名文件 camelCase/kebab组件 PascalCase常量 UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func全局为 errorno-explicit-any在open-sse/与tests/中为 warning。TypeScriptstrict: falsetarget ES2022、module esnext、bundler 解析倾向显式类型。数据库始终通过src/lib/db/的领域模块访问数据库——绝不在路由或 handler 中写裸 SQL。绝不向src/lib/localDb.ts添加逻辑它只是 re-export 层。绝不从localDb.ts导入——改为导入具体的db/模块。DB 单例getDbInstance()来自src/lib/db/core.tsWAL 日志模式。迁移src/lib/db/migrations/下的版本化 SQL 文件幂等、在事务中执行。从目录列表看迁移文件已从001_initial_schema.sql延续到 100如100_cli_access_tokens.sql、102_compression_engines_map.sql等数量仍在增长。错误管理try/catch 使用具体错误类型用带上下文的 pino 日志记录。绝不在 SSE 流中吞掉错误——使用取消信号做清理。返回正确的 HTTP 状态码4xx/5xx。安全绝不使用eval()、new Function()或隐式 eval。所有输入用 Zod schema 校验。凭据静态加密AES-256-GCM。上游头文件黑名单位于src/shared/constants/upstreamHeaders.ts——修改时应同步保持净化逻辑、Zod schema 与单元测试一致。公开上游凭据Gemini/Antigravity/Windsurf 风格的 OAuth client_id/secret以及从公开 CLI 提取的 Firebase Web 密钥必须通过resolvePublicCred()open-sse/utils/publicCreds.ts注入绝不以字符串字面量硬编码。必读 docs/security/PUBLIC_CREDS.md。错误响应HTTP / SSE / executor / MCP handler必须经buildErrorBody()或sanitizeErrorMessage()open-sse/utils/error.ts处理绝不在响应体里塞原始err.stack或err.message。必读 docs/security/ERROR_SANITIZATION.md。由变量拼出的 shell 命令调用exec()/spawn()且脚本需要运行时值时通过env选项传入自动 shell 转义——绝不把不可信/外部路径插值进脚本体。参考src/mitm/cert/install.ts::updateNssDatabases。默认安全的库优先使用 Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink 等经过验证的库而不是在新增安全敏感表面时自研。常见编辑场景六个扩展路径添加新提供商在src/shared/constants/providers.ts注册加载时 Zod 校验。如需自定义逻辑在open-sse/executors/添加 executor继承BaseExecutor。若非 OpenAI 格式在open-sse/translator/添加翻译器。若基于 OAuth在src/lib/oauth/constants/oauth.ts添加 OAuth 配置——若上游 CLI 提供公开 client_id/secret经resolvePublicCred()注入见 docs/security/PUBLIC_CREDS.md绝不写成字面量。在open-sse/config/providerRegistry.ts注册模型。在tests/unit/写测试新增内嵌默认凭据时须包含 publicCreds 形状断言。添加新 API 路由在src/app/api/v1/your-route/下创建目录。创建带GET/POSThandler 的route.ts。遵循模式CORS → Zod 请求体验证 → 可选认证 → handler 委托。handler 放open-sse/handlers/从那里导入不要内联。错误响应用buildErrorBody()/errorResponse()open-sse/utils/error.ts自动净化——绝不输出原始err.stack/err.message。见 docs/security/ERROR_SANITIZATION.md。添加测试——至少包含一条断言错误响应不泄露堆栈!body.error.message.includes(at /)。添加新 DB 模块创建src/lib/db/yourModule.ts从./core.ts导入getDbInstance。为领域表导出 CRUD 函数。如需新表在src/lib/db/migrations/添加迁移。从src/lib/localDb.tsre-export只加进 re-export 列表。写测试。添加新 MCP 工具在open-sse/mcp-server/tools/添加工具定义Zod 输入 schema 异步 handler。在工具注册文件中注册通过createMcpServer()串联。关联到相应作用域。写测试工具调用会记录到mcp_audit表。添加新 A2A 技能在src/lib/a2a/skills/创建技能现有 5 个smart-routing、quota-management、provider-discovery、cost-analysis、health-report。技能接收任务上下文消息、元数据→ 返回结构化结果。在src/lib/a2a/taskExecution.ts的A2A_SKILL_HANDLERS注册。在src/app/.well-known/agent.json/route.ts的 Agent Card 中暴露。在tests/unit/写测试。在 docs/frameworks/A2A-SERVER.md 的技能表补充文档。添加新云代理Cloud Agent在src/lib/cloudAgent/agents/创建继承CloudAgentBase的代理类现有 3 个codex-cloud、devin、jules。实现createTask、getStatus、approvePlan、sendMessage、listSources。在src/lib/cloudAgent/registry.ts注册。如有需要添加 OAuth/凭据处理src/lib/oauth/providers/。写测试并在 docs/frameworks/CLOUD_AGENT.md 补文档。其他扩展点速查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参考文档索引做任何非平凡变更前先读对应领域的深度文档领域文档仓库导航docs/architecture/REPOSITORY_MAP.md架构docs/architecture/ARCHITECTURE.md工程参考docs/architecture/CODEBASE_DOCUMENTATION.mdAuto-Combo13 因子打分、19 公开策略docs/routing/AUTO-COMBO.md韧性3 机制docs/architecture/RESILIENCE_GUIDE.md推理重放docs/routing/REASONING_REPLAY.md技能框架docs/frameworks/SKILLS.md记忆系统FTS5 Qdrantdocs/frameworks/MEMORY.md云代理docs/frameworks/CLOUD_AGENT.md护栏PII/注入/视觉docs/security/GUARDRAILS.md公开上游凭据Gemini 等docs/security/PUBLIC_CREDS.md错误信息净化docs/security/ERROR_SANITIZATION.md评测docs/frameworks/EVALS.md合规/审计docs/security/COMPLIANCE.mdWebhookdocs/frameworks/WEBHOOKS.md授权管线docs/architecture/AUTHZ_GUIDE.md隐身TLS/指纹docs/security/STEALTH_GUIDE.md代理协议A2A/ACP/Clouddocs/frameworks/AGENT_PROTOCOLS_GUIDE.mdMCP serverdocs/frameworks/MCP-SERVER.mdA2A serverdocs/frameworks/A2A-SERVER.mdAPI 参考 OpenAPIdocs/reference/API_REFERENCE.md docs/reference/openapi.yaml提供商目录自动生成docs/reference/PROVIDER_REFERENCE.md发布流程docs/ops/RELEASE_CHECKLIST.md测试矩阵测试类型命令单元测试npm run test:unit单个文件node --import tsx/esm --test tests/unit/file.test.tsVitestMCP、autoCombonpm run test:vitestE2EPlaywrightnpm run test:e2e协议 E2EMCPA2Anpm run test:protocols:e2e生态npm run test:ecosystem覆盖率npm run test:coverage门槛 75/75/75/70——语句/行/函数/分支覆盖率报告npm run coverage:reportPR 规则若你修改了src/、open-sse/、electron/或bin/的生产代码必须在同一 PR 中包含或更新测试。测试层级偏好先单元 → 集成多模块或 DB 状态→ E2E仅 UI/工作流。复现 bug 的代码应在修复之前或随修复一起固化为自动化测试。Copilot 覆盖率政策当 PR 修改生产代码且覆盖率低于 75%语句/行/函数或 70%分支时不要只报告——添加或更新测试、重新运行覆盖率、然后在 PR 描述中请求确认并附上运行的命令、修改的测试文件与最终覆盖率结果。Git 工作流# 绝不直接提交到 main git checkout -b feat/your-feature git commit -m feat: popíšte svoju zmenu git push -u origin feat/your-feature分支前缀feat/、fix/、refactor/、docs/、test/、chore/。提交格式Conventional Commitsfeat(db): pridať obvodový spínač——scope 可选值db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。Husky hookspre-commitlint-staged check-docs-synccheck:any-budget:t11。pre-pushnpm run test:unit。这些 check 命令如check-docs-sync、check:any-budget:t11都定义在 package.json 的 scripts 中分别对应文档同步校验与 any 类型预算检查是防止文档漂移与类型质量退化的自动化闸门。运行环境RuntimeNode.js ESM 模块。关联文档记载支持范围含 ≥20.20.2 21 | ≥22.22.2 23 | ≥24 25当前 package.json 的 engines 字段为22.22.2 23 || 24.0.0 27实际支持范围以当前 package.json 为准。TypeScript5.9当前 devDependencies 中为 ^6.0.3target ES2022、module esnext、bundler 解析。路径别名/*→src/omniroute/open-sse→open-sse/omniroute/open-sse/*→open-sse/*。默认端口20128API 与 dashboard 同端口。数据目录DATA_DIR环境变量默认~/.omniroute/。关键环境变量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。模板见根目录 .env.example。硬性规则Hard Rules绝不提交密钥或凭据。绝不向localDb.ts添加逻辑。绝不使用eval()/new Function()/ 隐式 eval。绝不直接提交到main。绝不在路由中写裸 SQL——使用src/lib/db/模块。绝不在 SSE 流中静默吞掉错误。始终用 Zod schema 校验输入。修改生产代码时始终附带测试。覆盖率必须保持 ≥75%语句、行、函数/ ≥70%分支当前实测约 82%。未经操作者明确批准绝不绕过 Husky hooks--no-verify、--no-gpg-sign。绝不把公开上游 OAuth client_id/secret 或 Firebase Web 密钥写成字符串字面量——始终经resolvePublicCred()open-sse/utils/publicCreds.ts见 docs/security/PUBLIC_CREDS.md。绝不在 HTTP / SSE / executor 响应中返回原始err.stack/err.message——始终经buildErrorBody()或sanitizeErrorMessage()open-sse/utils/error.ts见 docs/security/ERROR_SANITIZATION.md。绝不把外部路径或运行时值插值进传给exec()/spawn()的 shell 脚本——改经env选项传递。参考src/mitm/cert/install.ts::updateNssDatabases。绝不在未先查阅上述模式文档并记录技术驳回理由的情况下忽略 CodeQL / Secret-Scanning 告警。既有先例已在sanitizeErrorMessage()处触发的js/stack-trace-exposure是 CodeQL 已知局限不识别自定义净化器可按 false positive 驳回并引用 docs/security/ERROR_SANITIZATION.md。绝不公开会启动子进程的路由/api/mcp/、/api/cli-tools/runtime/除非经src/server/authz/routeGuard.ts的isLocalOnlyPath()分类。loopback 强制在认证检查之前无条件执行——通过隧道泄露的 JWT 也无法启动进程。见 docs/security/ROUTE_GUARD_TIERS.md。绝不添加把功劳归于 AI 助手/LLM/自动化账号的Co-Authored-By尾注如名字含 Claude、GPT、Copilot、Bot或邮箱落在anthropic.com/openai.com/ 机器人持有的noreply.github.com。这类尾注会把提交归属指向 bot 账号掩盖 PR 历史中的真实作者。人类协作者包括移植到 OmniRoute 的上游 PR 作者与 issue 报告者可以且应当使用标准Co-authored-by: Name email尾注——上游移植工作流/port-upstream-features、/port-upstream-issues依赖于此。以上 16 条硬性规则加上文档中的架构约定、韧性机制与测试政策共同构成了 OmniRoute 面向 AI 编码代理的完整开发契约。在实际协作中任何 AI 助手在动手改代码前都应通读 AGENTS.md仓库规则的唯一权威来源与本指南对应的最新语言版本以确保变更与项目的质量门、安全基线保持一致。【免费下载链接】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），仅供参考