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/OmniRoute本篇文章以docs/i18n/ja/CLAUDE.mdOmniRoute 仓库为 Claude Code 编写的日文协作指南为骨架结合仓库源码与配置深度展开。它面向两类读者首次接触该仓库的开发者——需要在几分钟内理清目录分层、请求管线与开发规范以及计划为 OmniRoute 贡献代码的工程师——需要掌握新增 Provider、API 路由、DB 模块、MCP 工具、A2A 技能时的标准套路。读完本文你将理解这个统一 AI 网关/路由器单端点、多 LLM 提供商、自动故障转移的核心架构并能在本地跑通开发环境与测试流水线。OmniRoute 是一个统一的 AI 代理/路由器一个端点、数百个 LLM 提供商、自动故障转移与组合路由combo routing。文档撰写时它已接入 329 家 LLM 提供商当前项目描述为 352 家含 150 免费其代码仓库采用 monorepo 结构src/Next.js 16 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/测试与bin/CLI 入口。本手册是该项目在 CLAUDE.md 体系中沉淀的单一事实来源之一仓库根目录的 CLAUDE.md 指向 AGENTS.md全部 AI 助手共享的规范总纲而各语言版本的 CLAUDE.md本文所依据的日文版位于 docs/i18n/ja/CLAUDE.md则记录了面向 Claude Code 的操作性细化规则。快速上手从安装到测试开发环境的标准起步流程如下默认端口20128API 与仪表盘共用同一端口npm install # 安装依赖会自动从 .env.example 生成 .env npm run dev # 启动开发服务器监听 http://localhost:20128 npm run build # 生产构建Next.js 16 standalone 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 测试的组合 npm run check:cycles # 检测循环依赖单测运行方式很有特点绝大多数测试走Node.js 原生测试运行器通过 tsx 加载 TS# 单个测试文件 node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest用于 MCP 服务器、自动组合、缓存相关测试 npm run test:vitest # 全部测试套件 npm run test:all更完整的测试矩阵见 CONTRIBUTING.md 的运行测试章节深层架构分析参考 AGENTS.md。项目总体架构分层与目录文档用一个分层表勾勒出整个系统的职责边界这是理解 OmniRoute 的钥匙层位置职责API 路由src/app/api/v1/Next.js App Router 入口点处理器open-sse/handlers/请求处理chat、embedding 等执行器open-sse/executors/提供商特定的 HTTP 分发转换器open-sse/translator/格式转换OpenAI ↔ Claude ↔ Gemini变换器open-sse/transformer/响应 API ↔ 聊天补全服务open-sse/services/组合路由、限流、缓存等数据库src/lib/db/110 个顶层 SQLite 领域模块、130 个迁移当前仓库实际已积累 172 个迁移文件见src/lib/db/migrations/领域/策略src/domain/策略引擎、成本规则、故障转移逻辑MCP 服务器open-sse/mcp-server/107 个唯一工具、3 种传输stdio / SSE / Streamable HTTP、32 个作用域A2A 服务器src/lib/a2a/JSON-RPC 2.0 代理协议技能src/lib/skills/可扩展的技能框架记忆src/lib/memory/持久化会话记忆其中 A2A 技能、记忆系统等模块在源码中均有实际落盘src/lib/a2a/skills/下已存在 smartRouting、quotaManagement、providerDiscovery、costAnalysis、healthReport 五个内置技能任务执行注册表 将其挂接为A2A_SKILL_HANDLERS记忆后端见 src/lib/memory。请求管线从客户端到上游的完整链路文档给出了完整请求管线值得逐行拆解Client → /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 TransformStreamchatCore.tsopen-sse/handlers/chatCore.ts是这条管线的心脏它先做缓存命中检查、限流判定再决定是否进入组合路由每个组合目标通过handleSingleModel()包裹handleChatCore()并附加按目标隔离的错误处理与断路器检查。API 路由遵循统一模式路由 → CORS 预检 → Zod 请求体校验 → 可选认证extractApiKey/isValidApiKey→ API 密钥策略强制 → 处理器委托open-sse。值得注意项目没有全局 Next.js 中间件所有拦截都是路由级的。组合路由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。源码中strategy作为组合对象的显式字段贯穿选择流程combo.ts并针对round-robin原生轮转钉扎、quota-share配额份额并发限制等策略做了特殊分支。13 因子 Auto-Combo 评分见 docs/routing/AUTO-COMBO.md三层韧性见 docs/architecture/RESILIENCE_GUIDE.md。韧性运行时三种易混淆的失败隔离机制OmniRoute 拥有三个相关但作用域不同的临时失败机制。调试路由行为时务必分清它们各自管什么对应架构图docs/diagrams/exported/resilience-3layers.svg源文件为 docs/diagrams/resilience-3layers.mmd。提供商断路器Provider Circuit Breaker作用域整个提供商如glm、openai、anthropic。目的在上游/服务层面持续失败时停止向该提供商投递流量防止单个不健康提供商拖慢所有请求。实现落点核心类src/shared/utils/circuitBreaker.tsCircuitBreaker类及CircuitBreakerOpenError聊天门控/执行接线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提供商被临时封禁调用方收到提供商断路器打开的响应或组合路由跳过该目标转向其他目标。HALF_OPEN重置超时已过放行探测请求成功则关闭断路器失败则重新打开。默认参数定义于 open-sse/config/constants.ts均可通过环境变量覆盖提供商类型阈值连续失败次数重置超时触顶冷却环境变量OAuth 提供商860s5minOMNIROUTE_CIRCUIT_BREAKER_OAUTH_*API 密钥提供商1230s10minOMNIROUTE_CIRCUIT_BREAKER_API_KEY_*本地提供商215s1minOMNIROUTE_CIRCUIT_BREAKER_LOCAL_*日文文档早期版本记载为 OAuth 3/60s、API 密钥 5/30s当前源码默认值已调整为上表数值并全面支持环境变量覆盖。只有提供商级别的失败状态才能触发提供商断路器(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见 auth.ts 中的标记与清理路径。默认连接冷却行为OAuth 基础冷却5sAPI 密钥基础冷却3s。API 密钥429应优先遵循上游重试提示Retry-After头、reset 头或可解析的 reset 文本若可用。反复可恢复失败采用指数退避baseCooldownMs * 2 ** failureIndex;防惊群硬门禁anti-thundering herd同一连接上的并发失败不得反复延长冷却或双重递增backoffLevel对应src/sse/services/auth.ts中的 per-connection 互斥标记逻辑。终态不是冷却banned、expired、credits_exhausted意味着在凭证/配置变更或操作者重置之前保持不可用绝不能用临时冷却状态覆盖终态。模型锁定Model Lockout作用域提供商 连接 模型。目的单个模型不可用或配额受限时不使整个连接失效。典型触发场景按模型配额的提供商返回429本地提供商对单个缺失模型返回404提供商特定的模式/模型权限失败如选定的 Grok 模式。模型锁定实现在 open-sse/services/accountFallback.ts允许同一连接继续服务其他模型。调试指引文档给出的排查决策树非常实用若提供商的所有密钥都被跳过先看提供商断路器状态、各连接的rateLimitedUntil/testStatus。若重置窗口后提供商仍像被永久排除确认代码用的是getStatus()/canExecute()而非裸读原始state。若单个提供商密钥失败而其他密钥应正常优先排查连接冷却而非提供商断路器。若只有单个模型失败优先排查模型锁定而非连接冷却。若状态应自我恢复读路径必须能更新已过期的未来时间戳/重置超时状态持久化的终态则必须靠手动凭证或设置变更才能恢复。开发约定风格、数据库、错误处理与安全代码风格2 空格缩进、分号、双引号、100 字符宽度、es5 尾随逗号经 lint-staged 由 Prettier 强制执行。导入顺序外部 → 内部/、omniroute/open-sse→ 相对。命名文件驼峰/短横线组件帕斯卡常量UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func在任何位置均为错误no-explicit-any在open-sse/与tests/中为警告。TypeScriptstrict: false、target ES2022、module esnext、resolution bundler优先显式类型。数据库铁律始终通过src/lib/db/领域模块访问数据库——绝不在路由或处理器中写裸 SQL。绝不向 src/lib/localDb.ts 添加逻辑它只是再导出层。绝不从localDb.ts做 barrel 导入——应导入具体的db/模块。DB 单例getDbInstance()来自 src/lib/db/core.tsWAL 日志模式。迁移src/lib/db/migrations/——版本化 SQL 文件幂等且在事务内执行。错误处理用具体错误类型配合 pino 上下文日志做 try/catch。不在 SSE 流内静默吞掉错误——用中止信号做清理。返回恰当的 HTTP 状态码4xx/5xx。安全要点绝不使用eval()、new Function()或隐式 eval。所有输入经 Zod 模式校验。静态凭证使用 AES-256-GCM 加密。上游头拒斥清单src/shared/constants/upstreamHeaders.ts——修改时需同步对齐清理逻辑、Zod 模式与单元测试。公开上游凭证Gemini/Antigravity/Windsurf 风格的 OAuth client_id/secret、从公开 CLI 提取的 Firebase Web 密钥必须经open-sse/utils/publicCreds.ts::resolvePublicCred()嵌入绝不写成字符串字面量。强制模式见 docs/security/PUBLIC_CREDS.md。错误响应HTTP/SSE/执行器/MCP 处理器必须经 open-sse/utils/error.ts 的buildErrorBody()或sanitizeErrorMessage()路由绝不把原始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/添加执行器继承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/POST处理器的route.ts。遵循统一模式CORS → Zod 体校验 → 可选认证 → 处理器委托。处理器放在open-sse/handlers/从那里导入而非内联。错误响应使用open-sse/utils/error.ts的buildErrorBody()/errorResponse()自动清理响应体不放原始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.ts再导出仅加入再导出列表。写测试。新增一个 MCP 工具在open-sse/mcp-server/tools/添加工具定义Zod 输入模式 异步处理器。注册进工具集由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。新增 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测试策略与覆盖率门禁测试类型命令单元测试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:coverage75/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: 描述你的改动 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 运行 lint-staged check-docs-synccheck:any-budget:t11pre-push 运行npm run test:unit。环境要求运行时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/*。默认端口20128API 仪表盘同端口。数据目录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。硬性规则清单不提交密钥或凭证。不向localDb.ts添加逻辑。不使用eval()/new Function()/ 隐式 eval。不直接提交到main。不在路由中写裸 SQL——使用src/lib/db/模块。不在 SSE 流中静默吞掉错误。始终用 Zod 模式校验输入。修改生产代码时始终包含测试。覆盖率须始终 ≥75%语句、行、函数/ ≥70%分支当前实测约 82%。未经操作者明确批准不绕过 Husky 钩子--no-verify、--no-gpg-sign。不把公开上游 OAuth client_id/secret 或 Firebase Web 密钥作为字符串字面量嵌入——始终经resolvePublicCred()open-sse/utils/publicCreds.ts见 docs/security/PUBLIC_CREDS.md。不在 HTTP/SSE/执行器响应中返回原始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 告警——先核对上述模式文档判断是否有现成助手可应用确需忽略时在注释中记录技术理由已知先例js/stack-trace-exposure在已过sanitizeErrorMessage()的调用点上是 CodeQL 限制误报按 false positive 忽略并参照 docs/security/ERROR_SANITIZATION.md。不把产生子进程的路由/api/mcp/、/api/cli-tools/runtime/在src/server/authz/routeGuard.ts中未作isLocalOnlyPath()分类就公开——回环强制在认证检查前无条件执行经隧道泄漏的 JWT 无法触发进程创建见 docs/security/ROUTE_GUARD_TIERS.md。绝不在提交信息中加入承认 AI 助手/LLM/自动化账户的Co-Authored-By尾注如含 Claude、GPT、Copilot、Bot 的名字anthropic.com/openai.com/机器人所有的noreply.github.com邮箱——这类尾注会把提交归属路由到机器人账户掩盖真实作者人类协作者包括上游 PR 作者、移植 issue 的报告者则可以且应该使用标准Co-authored-by: Name email尾注upstream-port 工作流依赖这一机制。参考文档索引非平凡改动前先读对应领域的详细文档领域文档仓库导航docs/architecture/REPOSITORY_MAP.md架构docs/architecture/ARCHITECTURE.md工程参考docs/architecture/CODEBASE_DOCUMENTATION.mdAuto-Combo因子评分与策略docs/routing/AUTO-COMBO.md韧性三大机制docs/architecture/RESILIENCE_GUIDE.md推理重放docs/routing/REASONING_REPLAY.md技能框架docs/frameworks/SKILLS.md记忆系统FTS5 Qdrantdocs/frameworks/MEMORY.md云代理docs/frameworks/CLOUD_AGENT.mdGuardrailsPII/注入/视觉docs/security/GUARDRAILS.md公开上游凭证如 Geminidocs/security/PUBLIC_CREDS.md错误消息清理docs/security/ERROR_SANITIZATION.mdEvaldocs/frameworks/EVALS.md合规/审计docs/security/COMPLIANCE.mdWebhookdocs/frameworks/WEBHOOKS.md授权管线docs/architecture/AUTHZ_GUIDE.md隐身TLS/指纹docs/security/STEALTH_GUIDE.md代理协议A2A/ACP/云docs/frameworks/AGENT_PROTOCOLS_GUIDE.mdMCP 服务器docs/frameworks/MCP-SERVER.mdA2A 服务器docs/frameworks/A2A-SERVER.mdAPI 参考 OpenAPIdocs/reference/API_REFERENCE.md docs/reference/openapi.yaml提供商目录自动生成docs/reference/PROVIDER_REFERENCE.md发布流程docs/ops/RELEASE_CHECKLIST.md掌握上述内容后你既能在几分钟内定位任意请求的完整处理链路也能安全地新增提供商、路由、数据库模块、MCP 工具或 A2A 技能——这正是把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考