OmniRoute 仓库开发指南面向 Claude Code 的代码库架构、弹性机制与硬性规则解析【免费下载链接】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导读本文基于仓库内的瑞典语版 CLAUDE.md 展开系统讲解 OmniRoute统一 AI 网关/路由器仓库的结构、请求处理流水线、三层运行时弹性机制供应商熔断器、连接冷却、模型锁定问题以及面向 Claude Code 等 AI 编程助手与人类开发者的编码规范、扩展场景与硬性规则。读完本文你将掌握在 OmniRoute 仓库中快速定位模块、正确添加供应商/路由/数据库模块/MCP 工具、排查路由故障并遵守其测试、安全与 Git 工作流约束的完整实操路径。项目全景一个端点的多供应商 AI 网关OmniRoute是一个统一的 AI 代理/路由器对外只暴露一个 OpenAI 兼容端点对内聚合 329 LLM 供应商支持自动回退、负载均衡与格式翻译。仓库为 monorepo 结构核心工作区与职责划分如下层级位置职责API 路由src/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 ↔ 聊天补全转换服务open-sse/services/组合路由、速率限制、缓存等数据库src/lib/db/SQLite 领域模块与迁移域/策略src/domain/策略引擎、成本规则、回退逻辑MCP 服务器open-sse/mcp-server/多个工具、三种传输stdio/SSE/Streamable HTTP、多级作用域A2A 服务器src/lib/a2a/JSON-RPC 2.0 智能体协议技能src/lib/skills/可扩展技能框架记忆src/lib/memory/持久化对话记忆仓库顶层同时包含src/Next.js 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/测试套件以及bin/CLI 入口。项目级总规则统一收敛在 AGENTS.md而 CLAUDE.md 只保留 Claude Code 特有的运行细节本瑞典语文档则是面向国际贡献者的一站式操作指南。快速上手与开发环境常用命令npm install # 安装依赖自动从 .env.example 生成 .env npm run dev # 开发服务器http://localhost:20128 npm run build # 生产构建Next.js 独立产物 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 # 检测循环依赖运行测试# 单个测试文件Node.js 内置测试运行器——大多数测试 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。运行环境要求运行时Node.js20.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/*。默认端口20128API 与 dashboard 同端口。数据目录由DATA_DIR环境变量指定默认~/.omniroute/。关键环境变量PORT、JWT_SECRET、API_KEY_SECRET、INITIAL_PASSWORD、REQUIRE_API_KEY、APP_LOG_LEVEL。初始化cp .env.example .env然后用openssl rand -base64 48生成JWT_SECRET、用openssl rand -hex 32生成API_KEY_SECRET。请求处理流水线从客户端到上游再到响应OmniRoute 的请求路径遵循清晰的分层结构瑞典语文档给出了完整链路客户端 → /v1/chat/completions (Next.js 路由) → CORS → Zod 校验 → 认证? → 策略检查 → 提示注入防护 → handleChatCore() [open-sse/handlers/chatCore.ts] → 缓存检查 → 速率限制 → 组合路由? → resolveComboTargets() → 每个目标执行 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → fetch() 上游 → 带退避的重试 → 响应翻译 → SSE 流或 JSON → 若为 Responses API: responsesTransformer.ts TransformStream从源码看chatCore.ts 中handleChatCore()正是请求处理的中枢它在 translator/index.ts 中通过translateRequest()将请求转换为目标供应商的格式needsTranslation()判定是否真的需要转换再经由 executor 分发到上游。每条 API 路由遵循一致模式路由 → CORS preflight → Zod 体校验 → 可选认证extractApiKey/isValidApiKey→ API 密钥策略应用 → handler 分发open-sse。值得注意项目没有全局 Next.js 中间件——所有拦截都是路由级route-specific的。组合路由Combo routing位于 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()包装并叠加每目标错误处理与熔断器检查。策略详细评分可参阅 AUTO-COMBO.md13 因子 Auto-Combo 评分与 RESILIENCE_GUIDE.md3 层弹性。三层运行时弹性机制熔断、冷却与模型锁定OmniRoute 针对瞬时故障设计了三个相关但彼此独立的机制。调试路由行为时务必区分它们的作用域否则很容易误判供应商坏了。总览图见 resilience-3layers.svg源文件 resilience-3layers.mmd。第一层供应商级熔断器Provider Circuit Breaker作用域整个供应商例如glm、openai、anthropic。目的当某供应商在上游/服务层面反复失败时停止向其发送流量避免不健康的供应商拖慢每一个请求。实现位置核心类circuitBreaker.tsCircuitBreaker类、getCircuitBreaker(name, options)工厂、getAllCircuitBreakerStatuses()状态汇总。Chat 端口/接线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 响应或组合路由跳到另一目标。HALF_OPEN重置超时已到期放行一次试探请求。成功则关闭熔断器失败则再次打开。从源码看circuitBreaker.ts 还定义了DEGRADED状态故障计数达到降级阈值后先进入降级态再升级为 OPEN并支持按故障类型FailureKind分别设定阈值与冷却实现每种错误单独计数的精细控制kindFailureCounts。配置阈值定义于 open-sse/config/constants.ts 的PROVIDER_PROFILES可通过OMNIROUTE_CIRCUIT_BREAKER_*环境变量覆盖供应商类型熔断阈值默认重置窗口默认OAuth 供应商8OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD60s..._OAUTH_RESET_MSAPI 密钥供应商12OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD30s..._API_KEY_RESET_MS本地供应商2OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD15s..._LOCAL_RESET_MS注仓库当前版本2026-09已将 OAuth 默认阈值从文档时代的 3 上调到 8、API 密钥从 5 上调到 12适应 500 连接的规模并新增providerFailureThreshold整供应商冷却、providerCooldownMs、degradationThreshold、maxBackoffMultiplier等参数。文档与源码存在演进差异以 constants.ts 为最终事实。触发规则只有供应商级错误状态才应触发供应商熔断器(408, 500, 502, 503, 504);不要为常规账户/密钥/模型错误如大多数401、403、429触发整供应商熔断——这些通常属于连接冷却或模型锁定问题。一个常规 API 密钥供应商的403若未被分类为终结性供应商/账户错误应可恢复。惰性恢复熔断器使用惰性恢复而非后台定时器。当OPEN到期后getStatus()、canExecute()、getRetryAfterMs()等读取路径会将状态更新为HALF_OPEN从而保证仪表盘与组合候选构建器不会永远排除一个已过期的供应商。第二层连接冷却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 密钥基础冷却3s。API 密钥429应优先采用上游重试提示Retry-After、重置响应头或可解析的重置文本。反复的可恢复错误使用指数退避baseCooldownMs * 2 ** failureIndex;防惊群anti-thundering-herd保护用于防止同一连接上的并发失败反复延长冷却或对backoffLevel重复加一。终结性状态不是冷却banned、expired、credits_exhausted应保持不可用直到凭据/设置变更或操作员重置。不得用临时冷却状态覆盖终结性状态。第三层模型锁定问题Model Lockout作用域供应商 连接 模型最精细粒度。目的当仅某个模型对该连接不可用或配额受限时避免停用整条连接。典型场景按模型配额计费的供应商返回429。本地供应商对缺失模型返回404。供应商特定的模式/模型权限错误如选定的 Grok 模式。模型锁定问题实现在 open-sse/services/accountFallback.ts允许同一条连接继续服务其他模型。故障排查指引若某供应商的所有密钥都被跳过请同时检查供应商熔断器状态与每条连接的rateLimitedUntil/testStatus。若某供应商在重置窗口后仍被永久排除检查代码是否读取原始state而非使用getStatus()/canExecute()。若某供应商密钥失败但其他密钥正常应优先连接冷却而非供应商熔断器。若只有某个模型失败应优先模型锁定问题而非连接冷却。若某状态应自愈它应当带未来时间戳/重置超时并有读取路径去更新过期状态永久状态需要人工修改凭据或配置。编码规范与数据库约束代码风格2 空格缩进、分号、双引号、100 字符宽度、ES5 尾逗号由 lint-staged 经 Prettier 强制。导入顺序外部 → 内部/、omniroute/open-sse→ 相对。命名文件 camelCase/kebab组件 PascalCase常量 UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func全局为错误no-explicit-any在open-sse/与tests/中为警告。TypeScriptstrict: falsetarget ES2022module esnextresolution bundler优先显式类型。数据库约定始终经由src/lib/db/领域模块访问数据库——绝不在路由或 handler 中写裸 SQL。绝不向src/lib/localDb.ts添加逻辑它只是 re-export 层。绝不从localDb.ts做 barrel 导入——应导入具体的db/模块。DB 单例getDbInstance()来自src/lib/db/core.tsWAL journaling。迁移src/lib/db/migrations/—— 版本化 SQL 文件、幂等、在事务中执行。错误处理try/catch 使用具体错误类型用 pino 上下文记录日志。绝不在 SSE 流中吞掉错误——用中止信号做清理。返回正确的 HTTP 状态码4xx/5xx。安全红线瑞典语文档中针对安全列出了明确的强制要求均可在源码与文档中印证绝不使用eval()、new Function()或隐式 eval。所有输入用 Zod schema 校验。凭据静态加密AES-256-GCM。上游 header denylist 位于src/shared/constants/upstreamHeaders.ts——编辑时保持净化、Zod schema 与单元测试同步。公开上游凭据Gemini/Antigravity/Windsurf 风格 OAuth client_id/secret 从公开 CLI 提取的 Firebase Web 密钥必须通过open-sse/utils/publicCreds.ts的resolvePublicCred()内嵌绝不允许写成字符串字面量。参见 PUBLIC_CREDS.md。错误响应HTTP / SSE / executor / MCP handler必须经由open-sse/utils/error.ts的buildErrorBody()或sanitizeErrorMessage()路由——绝不允许把裸err.stack或err.message放进响应体。参见 ERROR_SANITIZATION.md。基于变量拼接的 Shell 命令调用exec()/spawn()时如需传入运行时值请通过env选项传递自动做 shell 转义——绝不在脚本体中字符串插值不可信/外部路径。参考src/mitm/cert/install.ts::updateNssDatabases。新增安全敏感面时优先采用安全默认库如 Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink而不是自研实现。常见扩展场景五条实战操作路径1. 添加新供应商在src/shared/constants/providers.ts注册加载时 Zod 校验。若需自定义逻辑在open-sse/executors/添加 executor继承BaseExecutor。非 OpenAI 格式则在open-sse/translator/添加 translator。若基于 OAuth在src/lib/oauth/constants/oauth.ts添加 OAuth 配置——若上游 CLI 下发公开 client_id/secret通过resolvePublicCred()内嵌见 PUBLIC_CREDS.md绝不用字面量。在open-sse/config/providerRegistry.ts注册模型。在tests/unit/编写测试若添加了新的内嵌默认值务必包含 publicCreds 形式。2. 添加新 API 路由在src/app/api/v1/your-route/下建目录。创建带GET/POSThandler 的route.ts。遵循模式CORS → Zod 体校验 → 可选认证 → handler 分发。handler 放在open-sse/handlers/从那里导入不要内联。错误响应使用open-sse/utils/error.ts的buildErrorBody()/errorResponse()自动净化——绝不要把err.stack或err.message裸放进响应体。参见 ERROR_SANITIZATION.md。添加测试——至少包含一条确认错误响应不泄漏堆栈的断言!body.error.message.includes(at /)。3. 添加新 DB 模块创建src/lib/db/yourModule.ts—— 从./core.ts导入getDbInstance。为你的领域表导出 CRUD 函数。若需新表在src/lib/db/migrations/添加迁移。从src/lib/localDb.tsre-export仅加入 re-export 列表。编写测试。4. 添加新 MCP 工具在open-sse/mcp-server/tools/添加工具定义Zod 输入 schema 异步 handler。注册进工具集由createMcpServer()接线。分配到合适的作用域。编写测试工具调用会记录到mcp_audit表。5. 添加新 A2A 技能 / 云智能体 / 护栏等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.tsAgent Card暴露 → 在tests/unit/写测试 → 在 A2A-SERVER.md 的技能表补充文档。云智能体在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/→ 测试并文档化到 CLOUD_AGENT.md。护栏/评测/技能/Webhook 事件guardrail →src/lib/guardrails/→ GUARDRAILS.mdeval 套件 →src/lib/evals/→ EVALS.md沙箱技能 →src/lib/skills/→ SKILLS.mdwebhook 事件 →src/lib/webhookDispatcher.ts→ WEBHOOKS.md。测试矩阵与 PR 规则内容命令单元测试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: beskriv din ändring git push -u origin feat/your-feature分支前缀feat/、fix/、refactor/、docs/、test/、chore/。提交格式Conventional Commitsfeat(db): lägg till kretsbrytare—— 领域范围包括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。任何非平凡的改动应先阅读对应主题的深度文档详见 docs/architecture/REPOSITORY_MAP.md 的索引架构总览 ARCHITECTURE.md、工程参考 CODEBASE_DOCUMENTATION.md、Auto-Combo 13 因子评分 AUTO-COMBO.md、3 层弹性 RESILIENCE_GUIDE.md、推理重放 REASONING_REPLAY.md、记忆系统FTS5 QdrantMEMORY.md、授权管道 AUTHZ_GUIDE.md、MCP 服务器 MCP-SERVER.md、A2A 服务器 A2A-SERVER.md、API 参考 API_REFERENCE.md 与 openapi.yaml、发布流程 RELEASE_CHECKLIST.md 等。十六条硬性规则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参见 PUBLIC_CREDS.md。绝不在 HTTP / SSE / executor 响应中返回裸err.stack/err.message——始终经由buildErrorBody()或sanitizeErrorMessage()open-sse/utils/error.ts参见 ERROR_SANITIZATION.md。绝不在传给exec()/spawn()的 shell 脚本中字符串插值外部路径或运行时值——改经env选项传递参考src/mitm/cert/install.ts::updateNssDatabases。驳回 CodeQL / Secret-Scanning 告警时须先核对上述模式文档是否适用并在驳回注释中记录技术理由js/stack-trace-exposure在已路由sanitizeErrorMessage()的调用点属已知 CodeQL 局限可标注false positive并引用 ERROR_SANITIZATION.md。绝不暴露会创建子进程的路由/api/mcp/、/api/cli-tools/runtime/除非在src/server/authz/routeGuard.ts中完成isLocalOnlyPath()分类loopback 强制在任何认证之前无条件执行——经隧道泄漏的 JWT 也无法触发进程创建。参见 ROUTE_GUARD_TIERS.md。绝不添加将提交归属到 AI 助手、LLM 或自动化账户的Co-Authored-By尾注如含 Claude、GPT、Copilot、Bot 的名字anthropic.com/openai.com邮箱或 bot 拥有的noreply.github.com地址否则会掩盖真实作者人类贡献者——包括移植到 OmniRoute 的上游 PR 作者与 issue 报告者——可以且应该使用标准Co-authored-by: Name email尾注上游移植工作流/port-upstream-features、/port-upstream-issues依赖这一点。结语OmniRoute 仓库为 AI 助手与人类开发者同时准备了一套可操作、可验证的协作契约请求流水线把路由、翻译、执行与弹性机制分层解耦三层运行时弹性供应商熔断器、连接冷却、模型锁定问题覆盖了从整个供应商宕机到单条密钥失效再到单个模型配额耗尽的全部故障粒度而数据库、安全与 Git 规则则保证了 500 贡献者在同一仓库上的长期可维护性。以本文为地图配合 AGENTS.md、REPOSITORY_MAP.md 与 RESILIENCE_GUIDE.md 深度阅读即可安全高效地在这个规模庞大的 monorepo 中开展开发与排障工作。【免费下载链接】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），仅供参考