OmniRoute 开发者贡献指南从开发环境搭建到新增 Provider 的完整工作流【免费下载链接】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 是一个 MIT 许可的免费 AI 网关统一路由器通过单个 OpenAI 兼容端点聚合大量上游提供商并内置配额感知自动回退、RTKCaveman 压缩、MCP/A2A 协议服务等功能参见 README.md 与 package.json。本篇指南以docs/i18n/ja/CONTRIBUTING.md贡献文档为骨架系统讲解在 OmniRoute 仓库中进行二次开发、测试、提交流程与新增 Provider 的完整路径涵盖环境变量、质量门禁、代码规范与发布机制读完即可上手提交你的第一个 Pull Request。一、开发环境搭建1.1 环境前置要求贡献 OmniRoute 需要以下基础工具工具版本要求Node.js以仓库 package.json 的engines字段为准22.22.2 23 || 24.0.0 27建议使用 22 LTSnpm10Git任意现代版本注意早期贡献文档中Node.js 18 24的表述已经过时。当前仓库通过engines严格约束运行时版本并配有scripts/check/check-supported-node-runtime.ts在安装与启动阶段自动校验请以仓库实际声明为准。1.2 克隆与安装git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install仓库采用 npm workspaces 组织open-sse网关核心实现与packages/browser-pool作为工作区子包见 package.json 的workspaces字段npm install会自动完成依赖安装。原生依赖如better-sqlite3、sharp通过postinstall钩子与pnpm.onlyBuiltDependencies白名单管理。1.3 环境变量配置仓库提供了完整的.env.example模板复制并生成密钥即可# 从模板创建 .env cp .env.example .env # 生成必需的密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env关键开发变量均已在 .env.example 中核实存在变量开发默认值说明PORT20128服务监听端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端基础 URLOAuth 回调地址以此为基准拼接/callbackJWT_SECRET自行生成JWT 签名密钥泄露会导致凭据伪造风险API_KEY_SECRET自行生成API Key 加密/校验密钥INITIAL_PASSWORDCHANGEME首次登录密码生产环境必须修改APP_LOG_LEVELinfo日志详细级别仓库还提供npm run env:syncscripts/dev/sync-env.mjs用于同步环境变量模板check:env-doc-sync会在 CI 中校验环境变量文档与.env.example的一致性防止文档漂移。1.4 仪表盘 UI 设置部分功能除了环境变量外还可以在仪表盘界面中通过开关控制如 Settings → Advanced 的 Debug Mode、Settings → General 的 Sidebar Visibility。这些设置存储在数据库中对应 src/lib/db/databaseSettings.ts持久化于重启之间当 UI 设置被显式设置时会覆盖环境变量默认值。1.5 本地运行# 开发模式热重载 npm run dev # 生产构建与启动 npm run build npm run start # 指定端口的常见组合 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run dev默认地址仪表盘http://localhost:20128/dashboardOpenAI 兼容 APIhttp://localhost:20128/v1npm run dev实际通过scripts/dev/run-next.mjs启动 Next.js 开发服务并为 Node 预留了--max-old-space-size8192的堆空间。如需同时调试 Electron 桌面端可运行npm run electron:dev。二、Git 工作流与分支规范2.1 严禁直接提交 main⚠️ 贡献文档明确要求永远不要直接向main分支提交必须使用特性分支。git checkout -b feat/your-feature-name # ... 进行修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在 GitHub 上发起 Pull Request2.2 分支命名约定前缀用途feat/新功能fix/缺陷修复refactor/代码重构docs/文档变更test/测试新增/修复chore/工具链、CI、依赖2.3 提交信息规范遵循 Conventional Commits 规范feat: add circuit breaker for provider calls fix: resolve JWT secret validation edge case docs: update SECURITY.md with PII protection test: add observability unit tests refactor(db): consolidate rate limit tables可用的 scope 包括db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。仓库通过changelog.d/目录下的变更片段fragments管理 changelog发布时由scripts/release/aggregate-changelog.mjs聚合。三、测试体系与质量门禁3.1 测试命令全集OmniRoute 采用Node.js 原生 test runner 为主、Vitest 为辅、Playwright 负责端到端的分层测试策略所有脚本均在 package.json 中核实存在# 全部测试单元 vitest 生态 e2e npm run test:all # 单个测试文件Node.js 原生 test runner绝大多数测试走这里 node --import tsx/esm --test tests/unit/your-file.test.ts # VitestMCP server、autoCombo、cache npm run test:vitest # E2E 测试需要 Playwright npm run test:e2e # 协议客户端 E2EMCP transports、A2A npm run test:protocols:e2e # 生态兼容测试 npm run test:ecosystem # 覆盖率statements/lines/functions/branches 最低 60% npm run test:coverage npm run coverage:report # 代码检查 npm run lint npm run check3.2 覆盖率门禁解读npm run test:coverage使用c8测量主单元测试套件的源码覆盖率--excludetests/**排除测试代码自身并包含open-sse/**网关核心实现也被纳入统计PR 必须将语句statements、行lines、函数functions、分支branches四项覆盖率均保持在 60% 或以上低于门禁时c8 --check-coverage会直接令命令失败若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码必须在同一 PR 内新增或更新自动化测试npm run coverage:report输出最新一次覆盖率运行的逐文件明细报告npm run test:coverage:legacy保留旧口径指标排除open-sse、门槛 50%用于历史对比分阶段覆盖率提升路线图见 docs/ops/COVERAGE_PLAN.md。3.3 Pull Request 前置要求合并 PR 前必须完成运行npm run test:unit运行npm run test:coverage确认四项覆盖率指标均 ≥ 60%修改了生产代码时在 PR 描述中列出新增/变更的测试文件当 CI 中配置了项目密钥时检查 PR 上的 SonarQube 结果关于测试规模的说明贡献文档中提到122 个单元测试文件属于历史快照。当前仓库tests/unit/下已有数千个测试文件含tests/unit/dashboard/、tests/unit/serial/等子目录并配有 config/quality/test-discovery-baseline.json 基线约束测试发现数量防止测试被意外遗漏。单元测试覆盖的典型领域对应tests/unit/下api、auth、db、mcp、memory、translator、usage等子目录提供商翻译器与格式转换OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama见 open-sse/translator/限流、熔断与弹性rateLimitManager、circuit breaker 等见 open-sse/services/语义缓存、幂等性与进度跟踪数据库操作与 schema对应 src/lib/db/ 的 110 顶层模块与 src/lib/db/migrations/ 的 170 迁移OAuth 流程与认证API 端点校验Zod v4 schema见 src/shared/validation/MCP 服务端工具与作用域强制见 open-sse/mcp-server/Memory 与 Skills 系统见 src/lib/memory/ 与 src/lib/skills/四、代码风格与项目结构4.1 编码规范ESLint提交前运行npm run lintESLint 配置集中在 eslint.config.mjs并配套config/quality/eslint-suppressions.json管理豁免Prettier通过lint-staged在 commit 阶段自动格式化2 空格缩进、分号、双引号、100 字符宽度、es5 trailing commas见 package.json 的lint-staged配置TypeScriptsrc/全部使用.ts/.tsxopen-sse/使用.ts/.js混合公共函数需用 TSDoc 注释param、returns、throws禁用eval()ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验所有 API 输入校验使用 Zod v4 schema命名文件 camelCase / kebab-case组件 PascalCase常量 UPPER_SNAKE4.2 目录结构速览src/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # 仪表盘页面 │ ├── api/ # API 路由 │ └── login/ # 认证页面 (.tsx) ├── domain/ # 策略引擎comboResolver、costRules 等 ├── lib/ # 核心业务逻辑 (.ts) │ ├── a2a/ # Agent-to-Agent v0.3 协议服务 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 数据层含 170 迁移 │ ├── memory/ # 持久化会话记忆 │ ├── oauth/ # OAuth providers 与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量跟踪与成本计算 │ └── localDb.ts # 仅做重导出禁止在此添加逻辑 ├── middleware/ # 请求中间件promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ │ ├── components/ # React 组件 (.tsx) │ ├── constants/ # Provider 定义、MCP scopes、路由策略 │ ├── utils/ # 熔断器、sanitizer、auth 工具 │ └── validation/ # Zod v4 schemas └── sse/ # SSE 代理管线 open-sse/ # omniroute/open-sse 工作区网关核心 ├── executors/ # 各提供商执行器每个上游一个模块 ├── handlers/ # 请求处理器chat、responses、embeddings 等 ├── mcp-server/ # MCP 服务器多工具、多传输、多作用域 ├── services/ # 顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ … ├── transformer/ # Responses API 转换器 └── utils/ # 工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 原生 test runner 单元测试 ├── integration/ # 集成测试含 combo-matrix、chaos 等 ├── e2e/ # Playwright 端到端测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档架构、API 参考、使用指南等注文档中提到的docs/adr/目录在当前仓库中已不存在架构决策类内容请以 docs/architecture/ARCHITECTURE.md 为准。4.3 深入了解各模块文档中引用的核心文档在当前仓库中的实际位置如下均为根目录相对路径系统架构docs/architecture/ARCHITECTURE.mdAPI 参考docs/reference/API_REFERENCE.md使用指南docs/guides/USER_GUIDE.md故障排查docs/guides/TROUBLESHOOTING.mdMCP 服务器docs/frameworks/MCP-SERVER.mdA2A 协议docs/frameworks/A2A-SERVER.md自动组合引擎docs/routing/AUTO-COMBO.mdCLI 工具集成docs/reference/CLI-TOOLS.md覆盖率提升计划docs/ops/COVERAGE_PLAN.mdOpenAPI 规范docs/openapi.yaml五、新增一个 Provider六步流程这是贡献 OmniRoute 最常见的任务类型。以下六步流程在原文档基础上结合仓库真实文件逐一对应涉及的核心文件均已核实存在。Step 1注册 Provider 常量在 src/shared/constants/providers.ts 中添加 Provider 定义。该文件在模块加载时即通过 Zod schema 校验非法定义会直接导致启动失败从源头保证 Provider 元数据的类型安全。Step 2添加 Executor需要自定义逻辑时在 open-sse/executors/ 下创建your-provider.ts继承基础 executor。executors目录当前已有大量实现如antigravity.ts、claude-web.ts、gemini-web.ts、grok-web.ts等可参考同类上游的写法。Executor 负责与上游 API 的通信细节认证头、SSE 流解析、工具调用适配等。Step 3添加 Translator非 OpenAI 格式时在 open-sse/translator/ 下创建请求/响应翻译器。Translator 负责在 OmniRoute 内部规范格式与各上游专有格式之间互转OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama翻译器都有配套的单元测试位于tests/unit/translator/。Step 4添加 OAuth 配置基于 OAuth 时在 src/lib/oauth/constants/oauth.ts 中添加 OAuth 凭据常量并在 src/lib/oauth/services/ 下添加对应 service该目录已有cursor.ts、codexImport.ts等实现。Step 5注册模型在 open-sse/config/providerRegistry.ts 中添加模型定义。模型生命周期与一致性由check:model-lifecycle、check:provider-consistency等检查脚本约束见 config/quality/model-lifecycle.json。Step 6添加测试在tests/unit/下编写单元测试至少覆盖Provider 注册registration请求/响应翻译translation错误处理error handling六、Pull Request 提交清单提交 PR 前逐项确认测试通过npm testLint 通过npm run lint构建成功npm run build为新的公共函数/接口补充 TypeScript 类型无硬编码密钥或回退值所有输入均通过 Zod schema 校验有用户可见变更时更新 CHANGELOG如有必要更新文档七、发布机制OmniRoute 的发布由/generate-release工作流管理。当在 GitHub 上创建新的 Release 时GitHub Actions 会自动将打包产物发布到 npm。发布前的一系列质量校验check:release-green、check:ratchet-bank、check:lockfile等会作为门禁在 CI 中执行。八、常见问题与求助渠道架构问题参考 docs/architecture/ARCHITECTURE.mdAPI 细节参考 docs/reference/API_REFERENCE.md通用排查参考 docs/guides/TROUBLESHOOTING.md环境变量手册参考 docs/reference/ENVIRONMENT.md 与 .env.example变更片段管理changelog.d/目录下按features/、fixes/、maintenance/分类存放编号命名对应 issue/PRContributing 英文原版CONTRIBUTING.md日文版即本文骨架来源 docs/i18n/ja/CONTRIBUTING.md九、快速回顾从克隆到首个 PR 的完整路径安装 Node 22 LTS、npm 10、Gitgit clone仓库 →npm install→cp .env.example .env并生成JWT_SECRET与API_KEY_SECRETnpm run dev启动开发环境验证仪表盘/dashboard与 API/v1从main检出特性分支feat/、fix/、docs/等前缀按 Conventional Commits 规范提交commit 前自动执行 Prettier ESLintlint-staged按需编写/更新tests/unit/下的测试运行npm run test:unit与npm run test:coverage确保四项覆盖率 ≥ 60%对照 PR 清单自查发起 Pull Request 并在 PR 描述中列出测试变更等待 CI 校验Lint、测试、覆盖率、构建、SonarQube合入后由/generate-release工作流随下一次 Release 自动发布到 npm【免费下载链接】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 开发者贡献指南：从开发环境搭建到新增 Provider 的完整工作流
OmniRoute 开发者贡献指南从开发环境搭建到新增 Provider 的完整工作流【免费下载链接】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 是一个 MIT 许可的免费 AI 网关统一路由器通过单个 OpenAI 兼容端点聚合大量上游提供商并内置配额感知自动回退、RTKCaveman 压缩、MCP/A2A 协议服务等功能参见 README.md 与 package.json。本篇指南以docs/i18n/ja/CONTRIBUTING.md贡献文档为骨架系统讲解在 OmniRoute 仓库中进行二次开发、测试、提交流程与新增 Provider 的完整路径涵盖环境变量、质量门禁、代码规范与发布机制读完即可上手提交你的第一个 Pull Request。一、开发环境搭建1.1 环境前置要求贡献 OmniRoute 需要以下基础工具工具版本要求Node.js以仓库 package.json 的engines字段为准22.22.2 23 || 24.0.0 27建议使用 22 LTSnpm10Git任意现代版本注意早期贡献文档中Node.js 18 24的表述已经过时。当前仓库通过engines严格约束运行时版本并配有scripts/check/check-supported-node-runtime.ts在安装与启动阶段自动校验请以仓库实际声明为准。1.2 克隆与安装git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install仓库采用 npm workspaces 组织open-sse网关核心实现与packages/browser-pool作为工作区子包见 package.json 的workspaces字段npm install会自动完成依赖安装。原生依赖如better-sqlite3、sharp通过postinstall钩子与pnpm.onlyBuiltDependencies白名单管理。1.3 环境变量配置仓库提供了完整的.env.example模板复制并生成密钥即可# 从模板创建 .env cp .env.example .env # 生成必需的密钥 echo JWT_SECRET$(openssl rand -base64 48) .env echo API_KEY_SECRET$(openssl rand -hex 32) .env关键开发变量均已在 .env.example 中核实存在变量开发默认值说明PORT20128服务监听端口NEXT_PUBLIC_BASE_URLhttp://localhost:20128前端基础 URLOAuth 回调地址以此为基准拼接/callbackJWT_SECRET自行生成JWT 签名密钥泄露会导致凭据伪造风险API_KEY_SECRET自行生成API Key 加密/校验密钥INITIAL_PASSWORDCHANGEME首次登录密码生产环境必须修改APP_LOG_LEVELinfo日志详细级别仓库还提供npm run env:syncscripts/dev/sync-env.mjs用于同步环境变量模板check:env-doc-sync会在 CI 中校验环境变量文档与.env.example的一致性防止文档漂移。1.4 仪表盘 UI 设置部分功能除了环境变量外还可以在仪表盘界面中通过开关控制如 Settings → Advanced 的 Debug Mode、Settings → General 的 Sidebar Visibility。这些设置存储在数据库中对应 src/lib/db/databaseSettings.ts持久化于重启之间当 UI 设置被显式设置时会覆盖环境变量默认值。1.5 本地运行# 开发模式热重载 npm run dev # 生产构建与启动 npm run build npm run start # 指定端口的常见组合 PORT20128 NEXT_PUBLIC_BASE_URLhttp://localhost:20128 npm run dev默认地址仪表盘http://localhost:20128/dashboardOpenAI 兼容 APIhttp://localhost:20128/v1npm run dev实际通过scripts/dev/run-next.mjs启动 Next.js 开发服务并为 Node 预留了--max-old-space-size8192的堆空间。如需同时调试 Electron 桌面端可运行npm run electron:dev。二、Git 工作流与分支规范2.1 严禁直接提交 main⚠️ 贡献文档明确要求永远不要直接向main分支提交必须使用特性分支。git checkout -b feat/your-feature-name # ... 进行修改 ... git commit -m feat: describe your change git push -u origin feat/your-feature-name # 在 GitHub 上发起 Pull Request2.2 分支命名约定前缀用途feat/新功能fix/缺陷修复refactor/代码重构docs/文档变更test/测试新增/修复chore/工具链、CI、依赖2.3 提交信息规范遵循 Conventional Commits 规范feat: add circuit breaker for provider calls fix: resolve JWT secret validation edge case docs: update SECURITY.md with PII protection test: add observability unit tests refactor(db): consolidate rate limit tables可用的 scope 包括db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills。仓库通过changelog.d/目录下的变更片段fragments管理 changelog发布时由scripts/release/aggregate-changelog.mjs聚合。三、测试体系与质量门禁3.1 测试命令全集OmniRoute 采用Node.js 原生 test runner 为主、Vitest 为辅、Playwright 负责端到端的分层测试策略所有脚本均在 package.json 中核实存在# 全部测试单元 vitest 生态 e2e npm run test:all # 单个测试文件Node.js 原生 test runner绝大多数测试走这里 node --import tsx/esm --test tests/unit/your-file.test.ts # VitestMCP server、autoCombo、cache npm run test:vitest # E2E 测试需要 Playwright npm run test:e2e # 协议客户端 E2EMCP transports、A2A npm run test:protocols:e2e # 生态兼容测试 npm run test:ecosystem # 覆盖率statements/lines/functions/branches 最低 60% npm run test:coverage npm run coverage:report # 代码检查 npm run lint npm run check3.2 覆盖率门禁解读npm run test:coverage使用c8测量主单元测试套件的源码覆盖率--excludetests/**排除测试代码自身并包含open-sse/**网关核心实现也被纳入统计PR 必须将语句statements、行lines、函数functions、分支branches四项覆盖率均保持在 60% 或以上低于门禁时c8 --check-coverage会直接令命令失败若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码必须在同一 PR 内新增或更新自动化测试npm run coverage:report输出最新一次覆盖率运行的逐文件明细报告npm run test:coverage:legacy保留旧口径指标排除open-sse、门槛 50%用于历史对比分阶段覆盖率提升路线图见 docs/ops/COVERAGE_PLAN.md。3.3 Pull Request 前置要求合并 PR 前必须完成运行npm run test:unit运行npm run test:coverage确认四项覆盖率指标均 ≥ 60%修改了生产代码时在 PR 描述中列出新增/变更的测试文件当 CI 中配置了项目密钥时检查 PR 上的 SonarQube 结果关于测试规模的说明贡献文档中提到122 个单元测试文件属于历史快照。当前仓库tests/unit/下已有数千个测试文件含tests/unit/dashboard/、tests/unit/serial/等子目录并配有 config/quality/test-discovery-baseline.json 基线约束测试发现数量防止测试被意外遗漏。单元测试覆盖的典型领域对应tests/unit/下api、auth、db、mcp、memory、translator、usage等子目录提供商翻译器与格式转换OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama见 open-sse/translator/限流、熔断与弹性rateLimitManager、circuit breaker 等见 open-sse/services/语义缓存、幂等性与进度跟踪数据库操作与 schema对应 src/lib/db/ 的 110 顶层模块与 src/lib/db/migrations/ 的 170 迁移OAuth 流程与认证API 端点校验Zod v4 schema见 src/shared/validation/MCP 服务端工具与作用域强制见 open-sse/mcp-server/Memory 与 Skills 系统见 src/lib/memory/ 与 src/lib/skills/四、代码风格与项目结构4.1 编码规范ESLint提交前运行npm run lintESLint 配置集中在 eslint.config.mjs并配套config/quality/eslint-suppressions.json管理豁免Prettier通过lint-staged在 commit 阶段自动格式化2 空格缩进、分号、双引号、100 字符宽度、es5 trailing commas见 package.json 的lint-staged配置TypeScriptsrc/全部使用.ts/.tsxopen-sse/使用.ts/.js混合公共函数需用 TSDoc 注释param、returns、throws禁用eval()ESLint 强制no-eval、no-implied-eval、no-new-funcZod 校验所有 API 输入校验使用 Zod v4 schema命名文件 camelCase / kebab-case组件 PascalCase常量 UPPER_SNAKE4.2 目录结构速览src/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # 仪表盘页面 │ ├── api/ # API 路由 │ └── login/ # 认证页面 (.tsx) ├── domain/ # 策略引擎comboResolver、costRules 等 ├── lib/ # 核心业务逻辑 (.ts) │ ├── a2a/ # Agent-to-Agent v0.3 协议服务 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 数据层含 170 迁移 │ ├── memory/ # 持久化会话记忆 │ ├── oauth/ # OAuth providers 与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量跟踪与成本计算 │ └── localDb.ts # 仅做重导出禁止在此添加逻辑 ├── middleware/ # 请求中间件promptInjectionGuard ├── mitm/ # MITM 代理证书、DNS、目标路由 ├── shared/ │ ├── components/ # React 组件 (.tsx) │ ├── constants/ # Provider 定义、MCP scopes、路由策略 │ ├── utils/ # 熔断器、sanitizer、auth 工具 │ └── validation/ # Zod v4 schemas └── sse/ # SSE 代理管线 open-sse/ # omniroute/open-sse 工作区网关核心 ├── executors/ # 各提供商执行器每个上游一个模块 ├── handlers/ # 请求处理器chat、responses、embeddings 等 ├── mcp-server/ # MCP 服务器多工具、多传输、多作用域 ├── services/ # 顶层服务combo、autoCombo、rateLimitManager 等 ├── translator/ # 格式翻译器OpenAI ↔ Claude ↔ Gemini ↔ … ├── transformer/ # Responses API 转换器 └── utils/ # 工具模块stream、TLS、proxy、logging electron/ # Electron 桌面应用跨平台 tests/ ├── unit/ # Node.js 原生 test runner 单元测试 ├── integration/ # 集成测试含 combo-matrix、chaos 等 ├── e2e/ # Playwright 端到端测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档架构、API 参考、使用指南等注文档中提到的docs/adr/目录在当前仓库中已不存在架构决策类内容请以 docs/architecture/ARCHITECTURE.md 为准。4.3 深入了解各模块文档中引用的核心文档在当前仓库中的实际位置如下均为根目录相对路径系统架构docs/architecture/ARCHITECTURE.mdAPI 参考docs/reference/API_REFERENCE.md使用指南docs/guides/USER_GUIDE.md故障排查docs/guides/TROUBLESHOOTING.mdMCP 服务器docs/frameworks/MCP-SERVER.mdA2A 协议docs/frameworks/A2A-SERVER.md自动组合引擎docs/routing/AUTO-COMBO.mdCLI 工具集成docs/reference/CLI-TOOLS.md覆盖率提升计划docs/ops/COVERAGE_PLAN.mdOpenAPI 规范docs/openapi.yaml五、新增一个 Provider六步流程这是贡献 OmniRoute 最常见的任务类型。以下六步流程在原文档基础上结合仓库真实文件逐一对应涉及的核心文件均已核实存在。Step 1注册 Provider 常量在 src/shared/constants/providers.ts 中添加 Provider 定义。该文件在模块加载时即通过 Zod schema 校验非法定义会直接导致启动失败从源头保证 Provider 元数据的类型安全。Step 2添加 Executor需要自定义逻辑时在 open-sse/executors/ 下创建your-provider.ts继承基础 executor。executors目录当前已有大量实现如antigravity.ts、claude-web.ts、gemini-web.ts、grok-web.ts等可参考同类上游的写法。Executor 负责与上游 API 的通信细节认证头、SSE 流解析、工具调用适配等。Step 3添加 Translator非 OpenAI 格式时在 open-sse/translator/ 下创建请求/响应翻译器。Translator 负责在 OmniRoute 内部规范格式与各上游专有格式之间互转OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama翻译器都有配套的单元测试位于tests/unit/translator/。Step 4添加 OAuth 配置基于 OAuth 时在 src/lib/oauth/constants/oauth.ts 中添加 OAuth 凭据常量并在 src/lib/oauth/services/ 下添加对应 service该目录已有cursor.ts、codexImport.ts等实现。Step 5注册模型在 open-sse/config/providerRegistry.ts 中添加模型定义。模型生命周期与一致性由check:model-lifecycle、check:provider-consistency等检查脚本约束见 config/quality/model-lifecycle.json。Step 6添加测试在tests/unit/下编写单元测试至少覆盖Provider 注册registration请求/响应翻译translation错误处理error handling六、Pull Request 提交清单提交 PR 前逐项确认测试通过npm testLint 通过npm run lint构建成功npm run build为新的公共函数/接口补充 TypeScript 类型无硬编码密钥或回退值所有输入均通过 Zod schema 校验有用户可见变更时更新 CHANGELOG如有必要更新文档七、发布机制OmniRoute 的发布由/generate-release工作流管理。当在 GitHub 上创建新的 Release 时GitHub Actions 会自动将打包产物发布到 npm。发布前的一系列质量校验check:release-green、check:ratchet-bank、check:lockfile等会作为门禁在 CI 中执行。八、常见问题与求助渠道架构问题参考 docs/architecture/ARCHITECTURE.mdAPI 细节参考 docs/reference/API_REFERENCE.md通用排查参考 docs/guides/TROUBLESHOOTING.md环境变量手册参考 docs/reference/ENVIRONMENT.md 与 .env.example变更片段管理changelog.d/目录下按features/、fixes/、maintenance/分类存放编号命名对应 issue/PRContributing 英文原版CONTRIBUTING.md日文版即本文骨架来源 docs/i18n/ja/CONTRIBUTING.md九、快速回顾从克隆到首个 PR 的完整路径安装 Node 22 LTS、npm 10、Gitgit clone仓库 →npm install→cp .env.example .env并生成JWT_SECRET与API_KEY_SECRETnpm run dev启动开发环境验证仪表盘/dashboard与 API/v1从main检出特性分支feat/、fix/、docs/等前缀按 Conventional Commits 规范提交commit 前自动执行 Prettier ESLintlint-staged按需编写/更新tests/unit/下的测试运行npm run test:unit与npm run test:coverage确保四项覆盖率 ≥ 60%对照 PR 清单自查发起 Pull Request 并在 PR 描述中列出测试变更等待 CI 校验Lint、测试、覆盖率、构建、SonarQube合入后由/generate-release工作流随下一次 Release 自动发布到 npm【免费下载链接】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），仅供参考