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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

本篇文章以docs/i18n/ja/CLAUDE.md（OmniRoute 仓库为 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 的操作性细化规则。

快速上手：从安装到测试

开发环境的标准起步流程如下（默认端口20128，API 与仪表盘共用同一端口）：

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 的钥匙：

其中 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 TransformStream

chatCore.ts（open-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.ts（CircuitBreaker类及CircuitBreakerOpenError）
• 聊天门控/执行接线：src/sse/handlers/chatHelpers.ts、src/sse/handlers/chat.ts
• 运行时状态 API：src/app/api/monitoring/health/route.ts
• 共享包装器：open-sse/services/accountFallback.ts
• 持久化状态表：domain_circuit_breakers

状态机：

• CLOSED：允许正常流量。
• OPEN：提供商被临时封禁；调用方收到"提供商断路器打开"的响应，或组合路由跳过该目标转向其他目标。
• HALF_OPEN：重置超时已过，放行探测请求；成功则关闭断路器，失败则重新打开。

默认参数（定义于 open-sse/config/constants.ts，均可通过环境变量覆盖）：

（日文文档早期版本记载为 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 基础冷却：5s；API 密钥基础冷却：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。
• ESLint：no-eval、no-implied-eval、no-new-func在任何位置均为错误；no-explicit-any在open-sse/与tests/中为警告。
• TypeScript：strict: 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.ts，WAL 日志模式）。
• 迁移：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 等久经验证的库，而非自研实现。

常见扩展场景：六条标准套路

新增一个提供商

1. 在src/shared/constants/providers.ts注册（加载时经 Zod 校验）。
2. 如需自定义逻辑，在open-sse/executors/添加执行器（继承BaseExecutor）。
3. 非 OpenAI 格式则在open-sse/translator/添加转换器。
4. OAuth 类提供商在src/lib/oauth/constants/oauth.ts添加 OAuth 配置——若上游 CLI 公开了 client_id/secret，经resolvePublicCred()嵌入（见 docs/security/PUBLIC_CREDS.md），绝不写成字面量。
5. 在open-sse/config/providerRegistry.ts注册模型。
6. 在tests/unit/写测试（若新增了内嵌默认值，需包含 publicCreds 形状断言）。

新增一条 API 路由

1. 在src/app/api/v1/your-route/下建目录。
2. 创建带GET/POST处理器的route.ts。
3. 遵循统一模式：CORS → Zod 体校验 → 可选认证 → 处理器委托。
4. 处理器放在open-sse/handlers/（从那里导入，而非内联）。
5. 错误响应使用open-sse/utils/error.ts的buildErrorBody()/errorResponse()（自动清理，响应体不放原始err.stack/err.message）。参考 docs/security/ERROR_SANITIZATION.md。
6. 添加测试——至少包含一条断言错误响应不泄漏堆栈轨迹（!body.error.message.includes("at /")）。

新增一个 DB 模块

1. 创建src/lib/db/yourModule.ts——从./core.ts导入getDbInstance。
2. 为领域表导出 CRUD 函数。
3. 需要新表时，在src/lib/db/migrations/添加迁移。
4. 从src/lib/localDb.ts再导出（仅加入再导出列表）。
5. 写测试。

新增一个 MCP 工具

1. 在open-sse/mcp-server/tools/添加工具定义（Zod 输入模式 + 异步处理器）。
2. 注册进工具集（由createMcpServer()装配）。
3. 分配合适的作用域。
4. 写测试（工具调用会记入mcp_audit表）。

新增一个 A2A 技能

1. 在src/lib/a2a/skills/创建技能（已有 5 个：smart-routing、quota-management、provider-discovery、cost-analysis、health-report）。
2. 技能接收任务上下文（消息、元数据）→ 返回结构化结果。
3. 在src/lib/a2a/taskExecution.ts的A2A_SKILL_HANDLERS注册。
4. 在src/app/.well-known/agent.json/route.ts公开（agent card）。
5. 在tests/unit/写测试。
6. 在 docs/frameworks/A2A-SERVER.md 的技能表中补充文档。

新增一个云代理（Cloud Agent）

1. 在src/lib/cloudAgent/agents/创建继承CloudAgentBase的代理类（已有 3 个：codex-cloud、devin、jules）。
2. 实现createTask、getStatus、approvePlan、sendMessage、listSources。
3. 在src/lib/cloudAgent/registry.ts注册。
4. 按需添加 OAuth/凭证处理（src/lib/oauth/providers/）。
5. 写测试并补充 docs/frameworks/CLOUD_AGENT.md。

新增 Guardrail / Eval / 技能 / Webhook 事件

• Guardrail：src/lib/guardrails/→ 文档：docs/security/GUARDRAILS.md
• Eval 套件：src/lib/evals/→ 文档：docs/frameworks/EVALS.md
• 技能（沙箱）：src/lib/skills/→ 文档：docs/frameworks/SKILLS.md
• Webhook 事件：src/lib/webhookDispatcher.ts→ 文档：docs/frameworks/WEBHOOKS.md

测试策略与覆盖率门禁

PR 规则：修改了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 Commits）：feat(db): 添加断路器——作用域：db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。
• Husky 钩子：pre-commit 运行 lint-staged +check-docs-sync+check:any-budget:t11；pre-push 运行npm run test:unit。

环境要求：

• 运行时：Node.js ≥20.20.2 <21 | ≥22.22.2 <23 | ≥24 <25，ES Modules。
• TypeScript：5.9+，target ES2022，module esnext，resolution bundler。
• 路径别名：@/*→src/，@omniroute/open-sse→open-sse/，@omniroute/open-sse/*→open-sse/*。
• 默认端口：20128（API + 仪表盘同端口）。
• 数据目录：DATA_DIR环境变量，默认~/.omniroute/。
• 主要环境变量：PORT、JWT_SECRET、API_KEY_SECRET、INITIAL_PASSWORD、REQUIRE_API_KEY、APP_LOG_LEVEL。
• 初始化：cp .env.example .env，然后生成JWT_SECRET（openssl rand -base64 48）与API_KEY_SECRET（openssl rand -hex 32）。

硬性规则清单

1. 不提交密钥或凭证。
2. 不向localDb.ts添加逻辑。
3. 不使用eval()/new Function()/ 隐式 eval。
4. 不直接提交到main。
5. 不在路由中写裸 SQL——使用src/lib/db/模块。
6. 不在 SSE 流中静默吞掉错误。
7. 始终用 Zod 模式校验输入。
8. 修改生产代码时始终包含测试。
9. 覆盖率须始终 ≥75%（语句、行、函数）/ ≥70%（分支），当前实测约 82%。
10. 未经操作者明确批准，不绕过 Husky 钩子（--no-verify、--no-gpg-sign）。
11. 不把公开上游 OAuth client_id/secret 或 Firebase Web 密钥作为字符串字面量嵌入——始终经resolvePublicCred()（open-sse/utils/publicCreds.ts），见 docs/security/PUBLIC_CREDS.md。
12. 不在 HTTP/SSE/执行器响应中返回原始err.stack/err.message——始终经buildErrorBody()或sanitizeErrorMessage()（open-sse/utils/error.ts），见 docs/security/ERROR_SANITIZATION.md。
13. 不把外部路径或运行时值字符串插值进传给exec()/spawn()的 shell 脚本——改用env选项传递，参照src/mitm/cert/install.ts::updateNssDatabases。
14. 不忽略 CodeQL / Secret-Scanning 告警——先核对上述模式文档判断是否有现成助手可应用；确需忽略时在注释中记录技术理由（已知先例：js/stack-trace-exposure在已过sanitizeErrorMessage()的调用点上是 CodeQL 限制误报，按 false positive 忽略并参照 docs/security/ERROR_SANITIZATION.md）。
15. 不把产生子进程的路由（/api/mcp/、/api/cli-tools/runtime/）在src/server/authz/routeGuard.ts中未作isLocalOnlyPath()分类就公开——回环强制在认证检查前无条件执行，经隧道泄漏的 JWT 无法触发进程创建，见 docs/security/ROUTE_GUARD_TIERS.md。
16. 绝不在提交信息中加入承认 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 工作流依赖这一机制。

参考文档索引

非平凡改动前，先读对应领域的详细文档：

掌握上述内容后，你既能在几分钟内定位任意请求的完整处理链路，也能安全地新增提供商、路由、数据库模块、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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute