OmniRoute 工程指南：请求管线、三层弹性恢复机制与 AI 编码协作规范

OmniRoute 工程指南请求管线、三层弹性恢复机制与 AI 编码协作规范【免费下载链接】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 仓库内面向 AI 编码助手Claude Code的协作文档Filipino 语言版docs/i18n/phi/CLAUDE.md结合当前仓库源码逐一核实并展开。读完后你将掌握 OmniRoute 的构建/测试/类型检查命令矩阵、从/v1/chat/completions入口到上游 Provider 的完整请求管线以及 Provider 断路器、连接冷却、模型锁定这三层临时故障恢复机制的参数默认值、实现位置与调试手法并了解在该项目中新增 Provider、API 路由、DB 模块、MCP 工具等改动场景的标准步骤与安全红线。快速开始与命令矩阵OmniRoute 以 npm scripts 组织日常开发工作流常用命令如下来自文档快速开始章节npm install # 安装依赖自动从 .env.example 生成 .env npm run dev # 启动开发服务器监听 http://localhost:20128 npm run build # 生产构建Next.js standalone npm run lint # ESLint预期 0 errorswarnings 为历史遗留 npm run typecheck:core # TypeScript 检查应保持干净 npm run typecheck:noimplicit:core # 严格检查禁止 implicit any npm run test:coverage # 单元测试 覆盖率门禁75/75/75/70 — 语句/行/函数/分支 npm run check # lint test 的组合入口 npm run check:cycles # 检测循环依赖测试执行方式按测试栈区分——大部分测试使用 Node.js 原生 test runnerMCP server、autoCombo、cache 相关测试使用 Vitest# 单个测试文件Node.js native 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完整的测试矩阵见文末“测试矩阵与覆盖率门禁”一节完整 test matrix 在 CONTRIBUTING.md 的“Pagsasagawa ng Mga Pagsubok”章节深入架构见 AGENTS.md。项目一览分层结构与 Monorepo 布局OmniRoute是一个统一 AI 代理/路由器proxy/router一个 OpenAI 兼容端点接入数百个 LLM Provider文档快照写作 329当前项目描述为 352内置配额感知的自动回退auto-fallback。文档给出的分层结构如下各层路径均与当前仓库一致层位置职责API Routessrc/app/api/v1/Next.js App Router 入口Handlersopen-sse/handlers/请求处理chat、embeddings 等Executorsopen-sse/executors/Provider 特定的 HTTP 分发Translatorsopen-sse/translator/格式转换OpenAI↔Claude↔GeminiTransformeropen-sse/transformer/Responses API ↔ Chat CompletionsServicesopen-sse/services/Combo 路由、限流、缓存等Databasesrc/lib/db/SQLite 领域模块当前仓库为 127 个顶层 .ts 模块src/lib/db/migrations/下 173 个迁移 SQL 文件Domain/Policysrc/domain/策略引擎、成本规则、回退逻辑MCP Serveropen-sse/mcp-server/MCP 工具集3 种传输stdio / SSE / Streamable HTTPA2A Serversrc/lib/a2a/JSON-RPC 2.0 智能体协议Skillssrc/lib/skills/可扩展技能框架Memorysrc/lib/memory/持久化会话记忆Monorepo 布局src/Next.js 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/以及 CLI 入口。请求管线Request Pipeline一次/v1/chat/completions请求的完整处理链路如下原文档管线图路径均与当前仓库吻合Client → /v1/chat/completions (Next.js route) → CORS → Zod 校验 → 认证? → 策略检查 → 提示注入防护 → handleChatCore() [open-sse/handlers/chatCore.ts] → 缓存检查 → 限流 → combo 路由? → resolveComboTargets() → 对每个目标 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → 上游 fetch() → 带退避的重试 → 响应翻译 → SSE 流或 JSON → 若为 Responses API: responsesTransformer.ts 的 TransformStream其中 open-sse/handlers/chatCore.ts 已确认存在是 chat 请求的核心处理入口。所有 API 路由遵循统一模式Route → CORS 预检 → Zod body 校验 → 可选认证extractApiKey/isValidApiKey→ API key 策略执行 → 委托 Handleropen-sse。项目没有全局 Next.js middleware——拦截逻辑都写在各路由内部。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从 open-sse/services/combo.ts 的文件头注释可印证其中 16 种命名策略fusion/pipeline 作为分发前置分支dispatch prelude单独处理。每个 combo 目标都会调用handleSingleModel()它在每个目标之上包裹独立的错误处理与断路器检查。13 因子 Auto-Combo 评分见 docs/routing/AUTO-COMBO.md三层弹性机制总览见 docs/architecture/RESILIENCE_GUIDE.md。弹性运行时状态三层临时故障恢复机制OmniRoute 有三套相关但彼此独立的临时故障处理机制。调试路由行为异常时务必把它们的作用范围区分开。上图即三层机制的快速地图源文件为 docs/diagrams/resilience-3layers.mmd。1. Provider 断路器作用范围整个 Provider目的当一个 Provider 在 upstream/服务层面反复失败时如glm、openai、anthropic整体不可用停止向其发送流量避免不健康的 Provider 拖慢每一个请求。实现位置文档所列关键文件均已确认存在核心类src/shared/utils/circuitBreaker.ts共享包装open-sse/services/accountFallback.ts运行时状态 APIsrc/app/api/monitoring/health/route.ts状态机文档描述三态CLOSED放行正常流量→OPEN临时阻断该 Provider调用方收到 provider-circuit-open 响应或 combo 路由切换到其他目标→HALF_OPENreset 超时已到放行一个探测请求成功则闭合、失败则重新打开。从 src/shared/utils/circuitBreaker.ts 当前的文件头注释看状态机已演进为CLOSED → DEGRADED → OPEN → HALF_OPEN → CLOSED四态——DEGRADED 表示失败率抬升流量仍放行但记录告警。此外从源码结构看断路器还支持按失败类型区分的阈值per-failure-kind thresholds与自适应退避escalation 后 reset 窗口最多放大若干倍。默认参数open-sse/config/constants.ts 中的PROVIDER_PROFILES定义了账户级断路器与 Provider 级断路器两层参数且均可通过OMNIROUTE_CIRCUIT_BREAKER_*/OMNIROUTE_PROVIDER_BREAKER_*环境变量覆盖envInt解析器保证非法值回退到默认值档位账户级 threshold账户级 resetProvider 级失败阈值统计窗口Provider 冷却OAuth860s1015 分钟5 分钟API-key1230s1530 分钟10 分钟Local215s25 分钟1 分钟注意文档快照中列的3 / 5 / 2是 Provider 级断路器早期的失败阈值源码注释标明这些值后来“Scaled for 500 connections”为 500 连接规模上调当前值即上表。触发条件只有 Provider 服务层的失败状态码才应触发 Provider 级断路器(408, 500, 502, 503, 504);常规的账号/密钥/模型错误大多数401、403、429不应触发整个 Provider 的断路器——它们通常落入连接冷却connection cooldown或模型锁定model lockout。一个通用 API-key Provider 的403应当可恢复除非被归类为终端性 Provider/账号错误。惰性恢复lazy recovery断路器不使用后台定时器。当OPEN过期后getStatus()、canExecute()、getRetryAfterMs()这类读操作会把状态刷新为HALF_OPEN——这正是三个方法在 src/shared/utils/circuitBreaker.ts 中同时承担“读状态 自愈”的原因。由此保证 dashboard 与 combo 候选构建器不会永久排除一个已经过期的 Provider。2. 连接冷却 Connection Cooldown作用范围单个 Provider 连接/账号/密钥目的临时跳过某个坏掉的 key/账号同时让同一 Provider 的其他连接继续服务请求。实现位置写入/更新路径markAccountUnavailable()src/sse/services/auth.ts已确认定义于该文件文件内注释明确其带有“Anti-Thundering Herd: per-connection mutex”保护冷却计算checkFallbackError()open-sse/services/accountFallback.ts已确认导出冷却配置src/lib/resilience/settings.tsProvider 连接上的关键字段rateLimitedUntil; testStatus: unavailable; lastError; lastErrorType; errorCode; backoffLevel;选账号时的跳过条件new Date(rateLimitedUntil).getTime() Date.now();冷却同样是惰性的rateLimitedUntil一旦落在过去连接自动恢复资格。成功使用后clearAccountError()会清掉testStatus、rateLimitedUntil、各 error 字段和backoffLevel。默认行为与 open-sse/config/constants.ts 的PROVIDER_PROFILES一致OAuth 基础冷却5stransientCooldown: 5000API-key 基础冷却3stransientCooldown: 3000API-key 的429优先采用上游重试提示Retry-After、reset 头或可解析的 reset 文本rateLimitCooldown: 0即“尊重上游头”可重复恢复的失败使用指数退避baseCooldownMs * 2 ** failureIndex防“惊群”anti-thundering-herd保护防止对同一连接的并发失败反复延长冷却或重复递增backoffLevel终端状态不是冷却banned、expired、credits_exhausted会保持不可用直到凭据/配置变更或操作者手动重置——不得用临时冷却状态覆盖终端状态。3. 模型锁定 Model Lockout作用范围Provider 连接 模型目的当某个连接只有一个模型不可用或配额受限时避免把整个连接禁用。典型场景按模型限配的 Provider 返回429本地 Provider 对缺失模型返回404特定于 Provider 的 mode/model 权限失败例如某 Grok 模式。模型锁定逻辑位于 open-sse/services/accountFallback.ts允许同一连接继续服务其他模型。调试指引某 Provider 的所有key 都被跳过时同时检查 Provider 断路器状态与每个连接的rateLimitedUntil/testStatus某 Provider 在 reset 窗口后仍像被永久排除检查代码是否在直接读裸state字段而没用getStatus()/canExecute()后者会触发惰性刷新某个 Provider 的一条 key 失败而其他 key 正常优先归因于连接冷却而非 Provider 断路器只有一个模型失败优先归因于模型锁定而非连接冷却一个状态若应自愈就必须带有未来时间戳/reset 超时且有一个会刷新过期状态的读路径永久状态则需要人工变更凭据或配置。编码约定与工程规范代码风格2 空格缩进、分号、双引号、100 字符行宽、es5 尾逗号lint-staged 经 Prettier 强制执行导入顺序external → internal/、omniroute/open-sse→ relative命名文件 camelCase/kebab-case组件 PascalCase常量 UPPER_SNAKEESLintno-eval、no-implied-eval、no-new-func全域 errorno-explicit-any在open-sse/与tests/中为 warnTypeScriptstrict: falsetarget ES2022module esnextresolution bundler倾向显式类型标注数据库约定一律经由src/lib/db/领域模块访问数据——禁止在路由或 handler 中写 raw SQL不要往src/lib/localDb.ts里加逻辑它只是 re-export 层也不要从它做 barrel import而是直接 import 具体的db/模块DB 单例getDbInstance()src/lib/db/core.tsWAL 日志模式迁移src/lib/db/migrations/——版本化 SQL 文件幂等在事务中执行错误处理try/catch 携带具体错误类型用 pino 上下文记录日志不要把 error 抛进 SSE 流——用 abort signal 做清理返回正确的 HTTP 状态码4xx/5xx安全约定禁止eval()、new Function()或 implied eval所有输入用 Zod schema 校验静态凭据加密存储AES-256-GCM上游头 denylistsrc/shared/constants/upstreamHeaders.ts——修改时保持 sanitize、Zod schema 与单测对齐公开上游凭据Gemini/Antigravity/Windsurf 风格 OAuth client_id/secret以及来自公开 CLI 的 Firebase Web key必须通过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已确认存在于 src/mitm/cert/install.tsSecure-by-default 库新增安全敏感面时优先采用社区公认的安全默认实现Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink 等而非自研常见改动场景的标准步骤新增 Provider在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()注入不要写字面量在open-sse/config/providerRegistry.ts注册模型在tests/unit/写测试若新增了 embedded 默认凭据包含 publicCreds shape 断言新增 API 路由在src/app/api/v1/your-route/下建目录建route.ts实现GET/POSThandler遵循模式CORS → Zod body 校验 → 可选认证 → handler 委托handler 放到open-sse/handlers/从那里 import不要内联错误响应用buildErrorBody()/errorResponse()open-sse/utils/error.ts自动 sanitize——不要把err.stack/err.message原样放进 body添加测试——至少一条断言确保错误响应不泄漏 stack trace如!body.error.message.includes(at /)新增 DB 模块建src/lib/db/yourModule.ts——从./core.tsimportgetDbInstance导出该领域表的 CRUD 函数需要新表时在src/lib/db/migrations/添加迁移从src/lib/localDb.tsre-export只加进 re-export 列表写测试新增 MCP 工具在open-sse/mcp-server/tools/添加工具定义Zod input schema async handler注册进工具集由createMcpServer()接线分配到对应 scope写测试工具调用会落mcp_audit表新增 A2A Skill在src/lib/a2a/skills/建 skill文档写作时已有 5 个smart-routing、quota-management、provider-discovery、cost-analysis、health-reportskill 接收 task context消息、metadata→ 返回结构化结果注册进src/lib/a2a/taskExecution.ts的A2A_SKILL_HANDLERS在src/app/.well-known/agent.json/route.tsAgent Card中暴露在tests/unit/写测试在 docs/frameworks/A2A-SERVER.md 的 skill 表中补充文档新增 Cloud Agent在src/lib/cloudAgent/agents/建 agent 类扩展CloudAgentBase文档写作时已有 3 个codex-cloud、devin、jules实现createTask、getStatus、approvePlan、sendMessage、listSources注册进src/lib/cloudAgent/registry.ts需要时在src/lib/oauth/providers/添加 OAuth/凭据处理写测试并补充 docs/frameworks/CLOUD_AGENT.mdGuardrail / Eval / Skill / Webhook 事件Guardrailsrc/lib/guardrails/→ docs/security/GUARDRAILS.mdEval 套件src/lib/evals/→ docs/frameworks/EVALS.mdSkill沙箱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.mdReasoning replaydocs/routing/REASONING_REPLAY.md技能框架docs/frameworks/SKILLS.md记忆系统FTS5 Qdrantdocs/frameworks/MEMORY.md云端 agentdocs/frameworks/CLOUD_AGENT.mdGuardrailsPII / 注入 / visiondocs/security/GUARDRAILS.md公开上游凭据Gemini 等docs/security/PUBLIC_CREDS.md错误消息 sanitizedocs/security/ERROR_SANITIZATION.mdEvalsdocs/frameworks/EVALS.md合规 / 审计docs/security/COMPLIANCE.mdWebhooksdocs/frameworks/WEBHOOKS.md授权管线docs/architecture/AUTHZ_GUIDE.mdStealthTLS / 指纹docs/security/STEALTH_GUIDE.mdAgent 协议A2A / ACP / Clouddocs/frameworks/AGENT_PROTOCOLS_GUIDE.mdMCP serverdocs/frameworks/MCP-SERVER.mdA2A serverdocs/frameworks/A2A-SERVER.mdAPI 参考 OpenAPIdocs/reference/API_REFERENCE.md docs/openapi.yamlProvider 目录自动生成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:e2eEcosystemnpm run test:ecosystem覆盖率门禁npm run test:coverage75/75/75/70 — 语句/行/函数/分支覆盖率报告npm run coverage:reportPR 规则改动src/、open-sse/、electron/或bin/的生产代码时必须在同一 PR 中附带或更新对应测试。测试层级偏好unit 优先 → integration跨模块或 DB 状态→ e2e仅 UI/工作流。bug 复现在修复之前或同时固化为自动化测试。Copilot 覆盖率策略若 PR 改了生产代码且覆盖率低于 75%语句/行/函数或 70%分支不能只报告——要补充/更新测试、重跑覆盖率门禁再请求确认PR 报告中附上运行过的命令、改动的测试文件与最终覆盖率结果。Git 工作流# 永远不要直接 commit 到 main git checkout -b feat/your-feature git commit -m feat: 描述你的改动 git push -u origin feat/your-feature分支前缀feat/、fix/、refactor/、docs/、test/、chore/提交格式Conventional Commitsfeat(db): add circuit breaker——可用 scopedb、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skillsHusky hookspre-commitlint-staged check-docs-synccheck:any-budget:t11pre-pushnpm run test:unit运行环境与关键配置Node 版本当前 package.json 的engines声明为22.22.2 23 || 24.0.0 27文档快照写作 ≥20.20.221 / ≥22.22.223 / ≥2425以当前 package.json 为准ES ModulesTypeScript5.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然后生成JWT_SECRETopenssl rand -base64 48与API_KEY_SECRETopenssl rand -hex 32硬性规则16 条红线永远不提交机密或凭据永远不往localDb.ts添加逻辑永远不使用eval()/new Function()/ implied eval永远不直接 commit 到main永远不在路由中写 raw SQL——用src/lib/db/模块永远不静默吞掉 SSE 流中的错误永远用 Zod schema 校验输入改动生产代码时必须附带测试覆盖率保持 ≥75%语句/行/函数与 ≥70%分支文档写作时实测约 82%永远不在未经操作者明确批准的情况下跳过 Husky hooks--no-verify、--no-gpg-sign永远不把公开上游 OAuth client_id/secret 或 Firebase Web key 写成字符串字面量——一律经resolvePublicCred()open-sse/utils/publicCreds.ts见 docs/security/PUBLIC_CREDS.md永远不把原始err.stack/err.message返回到 HTTP / SSE / executor 响应中——一律经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 告警(a) 先查上文模式文档确认是否有对应 helper(b) 在 dismissal 评论中记录技术理由。先例已通过sanitizeErrorMessage()的调用点被报js/stack-trace-exposure是已知 CodeQL 局限不识别自定义 sanitizer应按指向 docs/security/ERROR_SANITIZATION.md 的false positive忽略永远不在没有 src/server/authz/routeGuard.ts 中isLocalOnlyPath()分级的情况下暴露会派生子进程的路由/api/mcp/、/api/cli-tools/runtime/——loopback 强制在任何 auth 检查之前无条件执行隧道泄漏的 JWT 也不能触发进程派生见 docs/security/ROUTE_GUARD_TIERS.md永远不添加把提交署名路由给 AI 助手、LLM 或自动化账号的Co-Authored-Bytrailer名称含 Claude/GPT/Copilot/Bot或anthropic.com/openai.com/noreply.github.com的 bot 邮箱——这会掩盖真实作者diegosouzapw在 PR 历史中的归属而人类协作者包括被移植到 OmniRoute 的上游 PR 作者与 issue 报告者可以且应当用标准Co-authored-by: Name email署名上游移植工作流/port-upstream-features、/port-upstream-issues依赖于此小结这份指南把 OmniRoute 的日常开发压缩成可执行的四件事用统一的 npm 命令矩阵保持质量门禁lint、typecheck、覆盖率常绿沿“Route → Zod → auth → policy → handleropen-sse”的固定管线处理请求把临时故障按“Provider 断路器 / 连接冷却 / 模型锁定”的三层范围正确归因并用getStatus()/canExecute()这类会惰性自愈的读路径观察状态以及遵守数据库分层、错误 sanitize、凭据注入与 shell 安全四条安全红线。所有参数与实现位置均可在文中给出的仓库相对路径中复核。【免费下载链接】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），仅供参考