尧图网页设计 
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 代理/路由器一个接入点统一代理 300 LLM 提供商提供自动回退、配额感知路由与组合Combo路由能力。本文以仓库根目录的CLAUDE.md开发指南阿塞拜疆语版docs/i18n/az/CLAUDE.md英文原文见 CLAUDE.md为骨架结合open-sse/、src/下的真实源码与tests/unit/中的测试用例系统讲解它的请求管线、三级容错机制提供商熔断器 / 连接冷却 / 模型阻断、代码规范、常见扩展场景、测试体系与硬性规则。读完你将掌握 OmniRoute 的架构脉络、容错机制的底层实现原理以及如何遵循其规范安全地新增提供商、API 路由、数据库模块、MCP 工具、A2A 技能与云代理。一、项目概览与快速上手OmniRoute 采用 monorepo 结构主要包含src/Next.js 16 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/测试以及bin/CLI 入口。开发环境要求 Node.js ≥20.20.2 21、≥22.22.2 23 或 ≥24 25ES ModulesTypeScript 5.9目标 ES2022模块esnext解析器bundler。在仓库根目录按顺序执行以下命令即可完成本地开发环境的搭建与校验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 # 严格检查不允许 implicit any npm run test:coverage # 单元测试 覆盖率门槛75/75/75/70 — 语句/行/函数/分支 npm run check # lint 测试的组合检查 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。二、架构分层总览文档给出了一张清晰的分层 → 位置 → 职责对照表是理解代码库的第一把钥匙层位置职责API 路由src/app/api/v1/Next.js App Router — 入口端点处理器Handlersopen-sse/handlers/请求处理chat、embedding 等执行器Executorsopen-sse/executors/提供商特定的 HTTP 发送逻辑翻译器Translatoropen-sse/translator/格式转换OpenAI ↔ Claude ↔ Gemini转换器Transformeropen-sse/transformer/响应 API ↔ Chat Completions服务层Servicesopen-sse/services/Combo 路由、速率限制、缓存等数据库src/lib/db/110 个顶层 SQLite 领域模块、130 迁移脚本领域/策略src/domain/策略引擎、成本规则、回退逻辑MCP Serveropen-sse/mcp-server/107 个独立工具、3 种传输stdio / SSE / Streamable HTTP、32 个作用域A2A Serversrc/lib/a2a/JSON-RPC 2.0 代理协议技能Skillssrc/lib/skills/可扩展的技能框架记忆Memorysrc/lib/memory/持久会话记忆仓库实际迁移文件位于 src/lib/db/migrations/编号从001_initial_schema.sql一路推进到 170覆盖记忆 FTS5 索引、quota 池、webhook、插件、雷达缓存等能力印证了110 个领域模块 130 迁移的分层描述。数据库单例由 src/lib/db/core.ts 的getDbInstance()提供WAL 日志模式。三、请求处理管线Request Pipeline文档给出了端到端的请求链路这是 OmniRoute 路由行为的核心骨架客户端 → /v1/chat/completions (Next.js 路由) → CORS → Zod 校验 → auth? → 策略检查 → prompt injection 防护 → handleChatCore() [open-sse/handlers/chatCore.ts] → 缓存检查 → 速率限制 → Combo 路由 → resolveComboTargets() → 按目标调用 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → fetch() 上游 → 带退避的重试 → 响应翻译 → SSE 流或 JSON → 若为 Responses API: responsesTransformer.ts TransformStream所有 API 路由都遵循统一模式路由 → CORS 预检 → Zod 请求体校验 → 请求相关认证extractApiKey/isValidApiKey→ API 密钥策略执行 → 处理器委派open-sse。项目没有全局 Next.js middleware拦截是路由特定route-specific的。核心处理入口 open-sse/handlers/chatCore.ts 承接上述链路。Combo 路由组合路由open-sse/services/combo.ts实现 Combo 路由引擎当前公开19 种策略priority优先级、weighted加权、fill-first先填满、round-robin轮询、p2cPower of Two Choices、random随机、least-used最少使用、cost-optimized成本优化、reset-aware重置感知、reset-window重置窗口、headroom余量、strict-random严格随机、auto自动、lkgp、context-optimized上下文优化、cache-optimized缓存优化、context-relay上下文中继、fusion融合、pipeline流水线。每个目标调用handleSingleModel()后者包装handleChatCore()并附加按目标per-target的错误处理与熔断器检查。13 因子 Auto-Combo 打分见 docs/routing/AUTO-COMBO.md3 层容错架构见 docs/architecture/RESILIENCE_GUIDE.md。四、三级容错机制Resilience Implementation这是文档的核心技术章节。OmniRoute 拥有三个相互关联但作用域不同的临时故障机制。排查路由行为时务必保持它们的作用域边界清晰。三者的关系可参考官方导出的 3 层容错架构图源文件为 docs/diagrams/resilience-3layers.mmd4.1 提供商熔断器Provider Circuit Breaker作用域整个提供商例如glm、openai、anthropic。目标停止向上游/服务级别反复失败的提供商发送流量避免一个不健康的提供商拖慢每一个请求。实现核心类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提供商被临时封锁调用方收到提供商-熔断-打开响应或 Combo 路由切换到其他目标。HALF_OPEN重置时间已过允许一个探针请求。成功则闭合熔断器失败则再次打开。从源码结构看实际实现 src/shared/utils/circuitBreaker.ts 还引入了第四个状态DEGRADED渐进式降级当失败数达到阈值 60% 时先进入DEGRADED并记录告警而不是立即打开同时具备按失败类型FailureKind区分的阈值kindThresholds、打开→半开→打开循环次数递增的自适应退避_effectiveResetTimeout()按2 ** (openCycleCount - backoffEscalationCount)指数放大上限maxBackoffMultiplier默认 16 倍以及基于domainState的 DB 持久化与 20 条状态迁移历史。文档给出的默认阈值定义于open-sse/config/constants.tsOAuth 提供商阈值 3重置时间 60s。API-Key 提供商阈值 5重置时间 30s。本地提供商阈值 2重置时间 15s。需要说明的是当前仓库 open-sse/config/constants.ts 中的PROVIDER_PROFILES已按500 连接规模上调默认值注释明确标注was 3、was 5OAuth 默认 8/60s、API-Key 默认 12/30s、本地 2/15s且全部支持通过环境变量覆盖circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD, 8), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS, 60000), circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD, 12), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS, 30000), circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD, 2), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS, 15000),触发条件只有提供商级别的失败状态才应触发提供商熔断器(408, 500, 502, 503, 504);注意当前源码accountFallback.ts中的PROVIDER_FAILURE_ERROR_CODES new Set([408, 429, 500, 502, 503, 504])还纳入了 429用于在持续 429 时也能打开熔断器同时配合按错误类型的冷却策略。但对正常的账户/密钥/模型错误不要触发整个提供商的熔断器例如绝大多数401、403或429情形——它们通常与连接冷却或模型封锁相关。一个常见的 API-Key 提供商403如果没有被归类为终态提供商/账户错误则可能是可恢复的。惰性恢复lazy recovery熔断器不使用后台定时器。当OPEN时长到期后getStatus()、canExecute()、getRetryAfterMs()等读取操作会把状态更新为HALF_OPEN从而让仪表盘和 Combo 候选构建器不会无限期排除一个冷却已到期的提供商。这一行为在 src/shared/utils/circuitBreaker.ts 的_refreshOpenState()中实现。相关测试可见tests/unit/circuit-breaker-resolved-5xx-12254.test.ts、tests/unit/circuit-breaker-failure-kind.test.ts、tests/unit/provider-breaker-halfopen-recovery.test.ts、tests/unit/provider-breaker-env-overrides.test.ts。4.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 头或可解析的重试文本。重复的可恢复失败使用指数退避baseCooldownMs * 2 ** failureIndex;源码accountFallback.ts中的getQuotaCooldown(backoffLevel)具体为Level 0 1s、Level 1 2s、Level 2 4s……上限 2 分钟。防惊群anti-thundering-herd保护同一连接上并发发生的失败不得重复延长冷却或双倍递增backoffLevel。这在 src/sse/services/auth.ts 中通过 per-connection 互斥锁markMutexes实现如果连接已被并发请求标记为不可用rateLimitedUntil在未来则跳过重复标记避免重置冷却计时器。终态terminal不做冷却banned、expired、credits_exhausted凭证在凭证改变或操作员重置之前应保持不可用终态不得与临时冷却状态重叠。markAccountUnavailable()中会先检查isTerminalConnectionStatus(conn)终态连接不会被临时冷却覆盖。4.3 模型阻断Model Blocking作用域提供商 连接 模型。目标仅在某个模型不可用或该连接对该模型的配额受限时不将整个连接禁用。典型场景按模型配额per-model quota的提供商返回429。对缺失模型返回404的本地提供商。某些 Grok 模式等提供商特定的模型/模式授权失败。模型阻断实现于open-sse/services/accountFallback.ts并允许同一连接上的其他模型继续被服务。相关回归测试包括tests/unit/account-fallback-anthropic-quota.test.ts、tests/unit/accountfallback-model-unhealthy.test.ts、tests/unit/ollama-404-model-lockout-11071.test.ts等。4.4 排障指引Fix Guidance文档给出四条实用的诊断规则可直接用于定位路由异常如果某提供商的所有密钥都被跳过同时检查提供商熔断器状态与每个连接的rateLimitedUntil/testStatus。如果某提供商在重置窗口过后仍被持续排除检查代码是否读取了原始state而非使用getStatus()/canExecute()后者才会触发惰性 HALF_OPEN 刷新。如果某个提供商密钥失败但其他密钥应该正常优先排查连接冷却而非提供商熔断器。如果只有某个模型失败优先排查模型阻断而非连接冷却。如果某状态应该自愈它必须有一个未来时间戳/重置时间并有到期刷新状态的读取路径永久状态则需要手工凭证或配置变更。五、代码规范与工程约定Core Conventions代码风格2 空格缩进、分号、双引号、100 字符宽度、es5 尾逗号通过 lint-staged 由 Prettier 强制。导入顺序外部 → 内部/、omniroute/open-sse→ 相对导入。命名文件 camelCase/kebab-case组件 PascalCase常量 UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func在任何位置都是错误no-explicit-any在open-sse/和tests/内是警告。TypeScriptstrict: false目标 ES2022模块esnext解析器bundler。优先使用清晰类型。数据库始终通过src/lib/db/领域模块访问数据库——绝不在路由或 handler 中写裸 SQL。绝不向src/lib/localDb.ts添加逻辑它只是 re-export 层。绝不从localDb.ts做 barrel-import——应导入具体的db/模块。DB 单例getDbInstance()来自src/lib/db/core.tsWAL 日志模式。迁移src/lib/db/migrations/——版本化 SQL 文件幂等在事务中执行。错误处理使用 try/catch 配合具体错误类型用 pino 上下文记录日志。不要吞掉 SSE 流中的错误——使用 abort 信号进行清理。返回正确的 HTTP 状态码4xx/5xx。安全绝不使用eval()、new Function()或签名 eval。所有输入必须用 Zod 模式校验。密钥在静态存储时加密AES-256-GCM。上游头禁用清单src/shared/constants/upstreamHeaders.ts——编辑时保持 sanitization、Zod 模式与单元测试一致。公共上游凭证Gemini/Antigravity/Windsurf 风格的 OAuth client_id/secret以及从公共 CLI 中提取的 Firebase Web 密钥必须通过open-sse/utils/publicCreds.ts的resolvePublicCred()放置绝不作为字符串字面量。参见 docs/security/PUBLIC_CREDS.md。错误响应HTTP / SSE / executor / MCP handler必须通过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 等业界公认的库而非自研实现。六、常见变更场景操作手册新增提供商Provider在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 形式校验。open-sse/executors/目前包含上百个 executor如gemini-web.ts、kimi.ts、deepseek-web.ts、antigravity.ts等印证了该扩展点就是一提供商一 executor的组织方式。新增 API 路由在src/app/api/v1/your-route/下创建目录。创建带GET/POSThandler 的route.ts。遵循模式CORS → Zod 请求体校验 → 可选 auth → handler 委派。Handler 位于open-sse/handlers/从那里导入不要内联。错误响应通过open-sse/utils/error.ts的buildErrorBody()/errorResponse()自动 sanitization——绝不在裸响应体中放置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 输入模式 异步 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的 agent 类文档记载已有 3 个codex-cloud、devin、jules当前源码目录还包含 cursor扩展点随版本演进。实现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七、参考文档索引对于任何不常见的变更请先阅读对应的深度调研文档领域文档仓库导航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.mdGuardrail 框架PII / 注入 / 视觉docs/security/GUARDRAILS.md公共上游凭证Gemini 等docs/security/PUBLIC_CREDS.md错误消息 sanitizationdocs/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 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:coverage75/75/75/70 — 语句/行/函数/分支覆盖率报告npm run coverage:reportPR 规则如果你修改了src/、open-sse/、electron/或bin/中的生产代码必须在同一 PR 中包含或更新测试。测试层级优先级先是单元测试 → 集成测试多模块或 DB 状态→ e2e仅 UI/工作流。在修复之前或与修复同步将 bug 复现编写为自动化测试。Copilot 覆盖率策略当 PR 修改生产代码且覆盖率低于 75%语句/行/函数或 70%分支时不要只报告——添加或更新测试重新运行覆盖率门槛然后请求批准。PR 报告中需包含执行的命令、修改的测试文件与最终覆盖率结果。仓库tests/unit/中有超过 4800 个测试文件涵盖从熔断器circuit-breaker-*.test.ts到账户回退account-fallback-*.test.ts、从组合路由combo-*.test.ts到错误 sanitizationerror-message-sanitization.test.ts的完整矩阵可以作为新增代码的行为契约模板。九、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-commitlint-staged check-docs-synccheck:any-budget:t11pre-pushnpm run test:unit十、运行环境与配置运行环境Node.js ≥20.20.2 21 | ≥22.22.2 23 | ≥24 25ES Modules。TypeScript5.9目标 ES2022模块 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。十一、硬性规则Hard Rules绝不提交机密或凭证。绝不向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 / 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。绝不未经a先检查上述模式文档以确认 helper 是否适用、b在拒绝评论中说明技术理由就拒绝 CodeQL / Secret-Scan 告警。先例js/stack-trace-exposure在经sanitizeErrorMessage()转发的调用点处被标记这是 CodeQL 已知的限制无法识别自定义 sanitizer可引用 docs/security/ERROR_SANITIZATION.md 作为 false positive 拒绝。绝不将产生子进程的路由/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 历史中的真实作者diegosouzapw。人类协作者——包括上游 PR 作者和移植到 OmniRoute 的 issue 报告者——可以且应该使用标准的Co-authored-by: Name email追加获得署名上游移植工作流/port-upstream-features、/port-upstream-issues依赖于此。总结OmniRoute 的开发契约可以被概括为一句话一切流量走统一管线CORS → Zod → auth → 策略 → handler 委派一切故障按提供商熔断器 / 连接冷却 / 模型阻断三级作用域隔离一切扩展遵循注册表 executor/translator 测试的证据闭环。理解本文的请求管线与三级容错机制后你既能在排障时快速定位是整提供商不可用、单账户被冷却、还是单模型被阻断也能按照六类变更场景手册安全地扩展这个拥有 300 提供商与 1200 模型的网关。更深层的实现细节请继续阅读 docs/architecture/RESILIENCE_GUIDE.md、docs/routing/AUTO-COMBO.md 与 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），仅供参考 OmniRoute 开发指南：请求管线、三级容错机制与贡献规范全解析
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 代理/路由器一个接入点统一代理 300 LLM 提供商提供自动回退、配额感知路由与组合Combo路由能力。本文以仓库根目录的CLAUDE.md开发指南阿塞拜疆语版docs/i18n/az/CLAUDE.md英文原文见 CLAUDE.md为骨架结合open-sse/、src/下的真实源码与tests/unit/中的测试用例系统讲解它的请求管线、三级容错机制提供商熔断器 / 连接冷却 / 模型阻断、代码规范、常见扩展场景、测试体系与硬性规则。读完你将掌握 OmniRoute 的架构脉络、容错机制的底层实现原理以及如何遵循其规范安全地新增提供商、API 路由、数据库模块、MCP 工具、A2A 技能与云代理。一、项目概览与快速上手OmniRoute 采用 monorepo 结构主要包含src/Next.js 16 应用、open-sse/流式引擎工作区、electron/桌面应用、tests/测试以及bin/CLI 入口。开发环境要求 Node.js ≥20.20.2 21、≥22.22.2 23 或 ≥24 25ES ModulesTypeScript 5.9目标 ES2022模块esnext解析器bundler。在仓库根目录按顺序执行以下命令即可完成本地开发环境的搭建与校验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 # 严格检查不允许 implicit any npm run test:coverage # 单元测试 覆盖率门槛75/75/75/70 — 语句/行/函数/分支 npm run check # lint 测试的组合检查 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。二、架构分层总览文档给出了一张清晰的分层 → 位置 → 职责对照表是理解代码库的第一把钥匙层位置职责API 路由src/app/api/v1/Next.js App Router — 入口端点处理器Handlersopen-sse/handlers/请求处理chat、embedding 等执行器Executorsopen-sse/executors/提供商特定的 HTTP 发送逻辑翻译器Translatoropen-sse/translator/格式转换OpenAI ↔ Claude ↔ Gemini转换器Transformeropen-sse/transformer/响应 API ↔ Chat Completions服务层Servicesopen-sse/services/Combo 路由、速率限制、缓存等数据库src/lib/db/110 个顶层 SQLite 领域模块、130 迁移脚本领域/策略src/domain/策略引擎、成本规则、回退逻辑MCP Serveropen-sse/mcp-server/107 个独立工具、3 种传输stdio / SSE / Streamable HTTP、32 个作用域A2A Serversrc/lib/a2a/JSON-RPC 2.0 代理协议技能Skillssrc/lib/skills/可扩展的技能框架记忆Memorysrc/lib/memory/持久会话记忆仓库实际迁移文件位于 src/lib/db/migrations/编号从001_initial_schema.sql一路推进到 170覆盖记忆 FTS5 索引、quota 池、webhook、插件、雷达缓存等能力印证了110 个领域模块 130 迁移的分层描述。数据库单例由 src/lib/db/core.ts 的getDbInstance()提供WAL 日志模式。三、请求处理管线Request Pipeline文档给出了端到端的请求链路这是 OmniRoute 路由行为的核心骨架客户端 → /v1/chat/completions (Next.js 路由) → CORS → Zod 校验 → auth? → 策略检查 → prompt injection 防护 → handleChatCore() [open-sse/handlers/chatCore.ts] → 缓存检查 → 速率限制 → Combo 路由 → resolveComboTargets() → 按目标调用 handleSingleModel() → translateRequest() → getExecutor() → executor.execute() → fetch() 上游 → 带退避的重试 → 响应翻译 → SSE 流或 JSON → 若为 Responses API: responsesTransformer.ts TransformStream所有 API 路由都遵循统一模式路由 → CORS 预检 → Zod 请求体校验 → 请求相关认证extractApiKey/isValidApiKey→ API 密钥策略执行 → 处理器委派open-sse。项目没有全局 Next.js middleware拦截是路由特定route-specific的。核心处理入口 open-sse/handlers/chatCore.ts 承接上述链路。Combo 路由组合路由open-sse/services/combo.ts实现 Combo 路由引擎当前公开19 种策略priority优先级、weighted加权、fill-first先填满、round-robin轮询、p2cPower of Two Choices、random随机、least-used最少使用、cost-optimized成本优化、reset-aware重置感知、reset-window重置窗口、headroom余量、strict-random严格随机、auto自动、lkgp、context-optimized上下文优化、cache-optimized缓存优化、context-relay上下文中继、fusion融合、pipeline流水线。每个目标调用handleSingleModel()后者包装handleChatCore()并附加按目标per-target的错误处理与熔断器检查。13 因子 Auto-Combo 打分见 docs/routing/AUTO-COMBO.md3 层容错架构见 docs/architecture/RESILIENCE_GUIDE.md。四、三级容错机制Resilience Implementation这是文档的核心技术章节。OmniRoute 拥有三个相互关联但作用域不同的临时故障机制。排查路由行为时务必保持它们的作用域边界清晰。三者的关系可参考官方导出的 3 层容错架构图源文件为 docs/diagrams/resilience-3layers.mmd4.1 提供商熔断器Provider Circuit Breaker作用域整个提供商例如glm、openai、anthropic。目标停止向上游/服务级别反复失败的提供商发送流量避免一个不健康的提供商拖慢每一个请求。实现核心类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提供商被临时封锁调用方收到提供商-熔断-打开响应或 Combo 路由切换到其他目标。HALF_OPEN重置时间已过允许一个探针请求。成功则闭合熔断器失败则再次打开。从源码结构看实际实现 src/shared/utils/circuitBreaker.ts 还引入了第四个状态DEGRADED渐进式降级当失败数达到阈值 60% 时先进入DEGRADED并记录告警而不是立即打开同时具备按失败类型FailureKind区分的阈值kindThresholds、打开→半开→打开循环次数递增的自适应退避_effectiveResetTimeout()按2 ** (openCycleCount - backoffEscalationCount)指数放大上限maxBackoffMultiplier默认 16 倍以及基于domainState的 DB 持久化与 20 条状态迁移历史。文档给出的默认阈值定义于open-sse/config/constants.tsOAuth 提供商阈值 3重置时间 60s。API-Key 提供商阈值 5重置时间 30s。本地提供商阈值 2重置时间 15s。需要说明的是当前仓库 open-sse/config/constants.ts 中的PROVIDER_PROFILES已按500 连接规模上调默认值注释明确标注was 3、was 5OAuth 默认 8/60s、API-Key 默认 12/30s、本地 2/15s且全部支持通过环境变量覆盖circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD, 8), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS, 60000), circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD, 12), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS, 30000), circuitBreakerThreshold: envInt(OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD, 2), circuitBreakerReset: envInt(OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS, 15000),触发条件只有提供商级别的失败状态才应触发提供商熔断器(408, 500, 502, 503, 504);注意当前源码accountFallback.ts中的PROVIDER_FAILURE_ERROR_CODES new Set([408, 429, 500, 502, 503, 504])还纳入了 429用于在持续 429 时也能打开熔断器同时配合按错误类型的冷却策略。但对正常的账户/密钥/模型错误不要触发整个提供商的熔断器例如绝大多数401、403或429情形——它们通常与连接冷却或模型封锁相关。一个常见的 API-Key 提供商403如果没有被归类为终态提供商/账户错误则可能是可恢复的。惰性恢复lazy recovery熔断器不使用后台定时器。当OPEN时长到期后getStatus()、canExecute()、getRetryAfterMs()等读取操作会把状态更新为HALF_OPEN从而让仪表盘和 Combo 候选构建器不会无限期排除一个冷却已到期的提供商。这一行为在 src/shared/utils/circuitBreaker.ts 的_refreshOpenState()中实现。相关测试可见tests/unit/circuit-breaker-resolved-5xx-12254.test.ts、tests/unit/circuit-breaker-failure-kind.test.ts、tests/unit/provider-breaker-halfopen-recovery.test.ts、tests/unit/provider-breaker-env-overrides.test.ts。4.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 头或可解析的重试文本。重复的可恢复失败使用指数退避baseCooldownMs * 2 ** failureIndex;源码accountFallback.ts中的getQuotaCooldown(backoffLevel)具体为Level 0 1s、Level 1 2s、Level 2 4s……上限 2 分钟。防惊群anti-thundering-herd保护同一连接上并发发生的失败不得重复延长冷却或双倍递增backoffLevel。这在 src/sse/services/auth.ts 中通过 per-connection 互斥锁markMutexes实现如果连接已被并发请求标记为不可用rateLimitedUntil在未来则跳过重复标记避免重置冷却计时器。终态terminal不做冷却banned、expired、credits_exhausted凭证在凭证改变或操作员重置之前应保持不可用终态不得与临时冷却状态重叠。markAccountUnavailable()中会先检查isTerminalConnectionStatus(conn)终态连接不会被临时冷却覆盖。4.3 模型阻断Model Blocking作用域提供商 连接 模型。目标仅在某个模型不可用或该连接对该模型的配额受限时不将整个连接禁用。典型场景按模型配额per-model quota的提供商返回429。对缺失模型返回404的本地提供商。某些 Grok 模式等提供商特定的模型/模式授权失败。模型阻断实现于open-sse/services/accountFallback.ts并允许同一连接上的其他模型继续被服务。相关回归测试包括tests/unit/account-fallback-anthropic-quota.test.ts、tests/unit/accountfallback-model-unhealthy.test.ts、tests/unit/ollama-404-model-lockout-11071.test.ts等。4.4 排障指引Fix Guidance文档给出四条实用的诊断规则可直接用于定位路由异常如果某提供商的所有密钥都被跳过同时检查提供商熔断器状态与每个连接的rateLimitedUntil/testStatus。如果某提供商在重置窗口过后仍被持续排除检查代码是否读取了原始state而非使用getStatus()/canExecute()后者才会触发惰性 HALF_OPEN 刷新。如果某个提供商密钥失败但其他密钥应该正常优先排查连接冷却而非提供商熔断器。如果只有某个模型失败优先排查模型阻断而非连接冷却。如果某状态应该自愈它必须有一个未来时间戳/重置时间并有到期刷新状态的读取路径永久状态则需要手工凭证或配置变更。五、代码规范与工程约定Core Conventions代码风格2 空格缩进、分号、双引号、100 字符宽度、es5 尾逗号通过 lint-staged 由 Prettier 强制。导入顺序外部 → 内部/、omniroute/open-sse→ 相对导入。命名文件 camelCase/kebab-case组件 PascalCase常量 UPPER_SNAKE。ESLintno-eval、no-implied-eval、no-new-func在任何位置都是错误no-explicit-any在open-sse/和tests/内是警告。TypeScriptstrict: false目标 ES2022模块esnext解析器bundler。优先使用清晰类型。数据库始终通过src/lib/db/领域模块访问数据库——绝不在路由或 handler 中写裸 SQL。绝不向src/lib/localDb.ts添加逻辑它只是 re-export 层。绝不从localDb.ts做 barrel-import——应导入具体的db/模块。DB 单例getDbInstance()来自src/lib/db/core.tsWAL 日志模式。迁移src/lib/db/migrations/——版本化 SQL 文件幂等在事务中执行。错误处理使用 try/catch 配合具体错误类型用 pino 上下文记录日志。不要吞掉 SSE 流中的错误——使用 abort 信号进行清理。返回正确的 HTTP 状态码4xx/5xx。安全绝不使用eval()、new Function()或签名 eval。所有输入必须用 Zod 模式校验。密钥在静态存储时加密AES-256-GCM。上游头禁用清单src/shared/constants/upstreamHeaders.ts——编辑时保持 sanitization、Zod 模式与单元测试一致。公共上游凭证Gemini/Antigravity/Windsurf 风格的 OAuth client_id/secret以及从公共 CLI 中提取的 Firebase Web 密钥必须通过open-sse/utils/publicCreds.ts的resolvePublicCred()放置绝不作为字符串字面量。参见 docs/security/PUBLIC_CREDS.md。错误响应HTTP / SSE / executor / MCP handler必须通过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 等业界公认的库而非自研实现。六、常见变更场景操作手册新增提供商Provider在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 形式校验。open-sse/executors/目前包含上百个 executor如gemini-web.ts、kimi.ts、deepseek-web.ts、antigravity.ts等印证了该扩展点就是一提供商一 executor的组织方式。新增 API 路由在src/app/api/v1/your-route/下创建目录。创建带GET/POSThandler 的route.ts。遵循模式CORS → Zod 请求体校验 → 可选 auth → handler 委派。Handler 位于open-sse/handlers/从那里导入不要内联。错误响应通过open-sse/utils/error.ts的buildErrorBody()/errorResponse()自动 sanitization——绝不在裸响应体中放置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 输入模式 异步 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的 agent 类文档记载已有 3 个codex-cloud、devin、jules当前源码目录还包含 cursor扩展点随版本演进。实现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七、参考文档索引对于任何不常见的变更请先阅读对应的深度调研文档领域文档仓库导航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.mdGuardrail 框架PII / 注入 / 视觉docs/security/GUARDRAILS.md公共上游凭证Gemini 等docs/security/PUBLIC_CREDS.md错误消息 sanitizationdocs/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 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:coverage75/75/75/70 — 语句/行/函数/分支覆盖率报告npm run coverage:reportPR 规则如果你修改了src/、open-sse/、electron/或bin/中的生产代码必须在同一 PR 中包含或更新测试。测试层级优先级先是单元测试 → 集成测试多模块或 DB 状态→ e2e仅 UI/工作流。在修复之前或与修复同步将 bug 复现编写为自动化测试。Copilot 覆盖率策略当 PR 修改生产代码且覆盖率低于 75%语句/行/函数或 70%分支时不要只报告——添加或更新测试重新运行覆盖率门槛然后请求批准。PR 报告中需包含执行的命令、修改的测试文件与最终覆盖率结果。仓库tests/unit/中有超过 4800 个测试文件涵盖从熔断器circuit-breaker-*.test.ts到账户回退account-fallback-*.test.ts、从组合路由combo-*.test.ts到错误 sanitizationerror-message-sanitization.test.ts的完整矩阵可以作为新增代码的行为契约模板。九、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-commitlint-staged check-docs-synccheck:any-budget:t11pre-pushnpm run test:unit十、运行环境与配置运行环境Node.js ≥20.20.2 21 | ≥22.22.2 23 | ≥24 25ES Modules。TypeScript5.9目标 ES2022模块 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。十一、硬性规则Hard Rules绝不提交机密或凭证。绝不向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 / 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。绝不未经a先检查上述模式文档以确认 helper 是否适用、b在拒绝评论中说明技术理由就拒绝 CodeQL / Secret-Scan 告警。先例js/stack-trace-exposure在经sanitizeErrorMessage()转发的调用点处被标记这是 CodeQL 已知的限制无法识别自定义 sanitizer可引用 docs/security/ERROR_SANITIZATION.md 作为 false positive 拒绝。绝不将产生子进程的路由/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 历史中的真实作者diegosouzapw。人类协作者——包括上游 PR 作者和移植到 OmniRoute 的 issue 报告者——可以且应该使用标准的Co-authored-by: Name email追加获得署名上游移植工作流/port-upstream-features、/port-upstream-issues依赖于此。总结OmniRoute 的开发契约可以被概括为一句话一切流量走统一管线CORS → Zod → auth → 策略 → handler 委派一切故障按提供商熔断器 / 连接冷却 / 模型阻断三级作用域隔离一切扩展遵循注册表 executor/translator 测试的证据闭环。理解本文的请求管线与三级容错机制后你既能在排障时快速定位是整提供商不可用、单账户被冷却、还是单模型被阻断也能按照六类变更场景手册安全地扩展这个拥有 300 提供商与 1200 模型的网关。更深层的实现细节请继续阅读 docs/architecture/RESILIENCE_GUIDE.md、docs/routing/AUTO-COMBO.md 与 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），仅供参考