企业官网建设流程全解析

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

OmniRoute 是一个 MIT 许可的免费 AI 网关（统一路由器），通过单个 OpenAI 兼容端点聚合大量上游提供商，并内置配额感知自动回退、RTK+Caveman 压缩、MCP/A2A 协议服务等功能（参见 README.md 与 package.json）。本篇指南以docs/i18n/ja/CONTRIBUTING.md贡献文档为骨架，系统讲解在 OmniRoute 仓库中进行二次开发、测试、提交流程与新增 Provider 的完整路径，涵盖环境变量、质量门禁、代码规范与发布机制，读完即可上手提交你的第一个 Pull Request。

一、开发环境搭建

1.1 环境前置要求

贡献 OmniRoute 需要以下基础工具：

注意：早期贡献文档中"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 中核实存在）：

仓库还提供npm run env:sync（scripts/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 # 指定端口的常见组合 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

默认地址：

• 仪表盘：http://localhost:20128/dashboard
• OpenAI 兼容 API：http://localhost:20128/v1

npm run dev实际通过scripts/dev/run-next.mjs启动 Next.js 开发服务，并为 Node 预留了--max-old-space-size=8192的堆空间。如需同时调试 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 Request

2.2 分支命名约定

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 # Vitest（MCP server、autoCombo、cache） npm run test:vitest # E2E 测试（需要 Playwright） npm run test:e2e # 协议客户端 E2E（MCP 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 check

3.2 覆盖率门禁解读

• npm run test:coverage使用c8测量主单元测试套件的源码覆盖率，--exclude=tests/**排除测试代码自身，并包含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 lint；ESLint 配置集中在 eslint.config.mjs，并配套config/quality/eslint-suppressions.json管理豁免
• Prettier：通过lint-staged在 commit 阶段自动格式化（2 空格缩进、分号、双引号、100 字符宽度、es5 trailing commas，见 package.json 的lint-staged配置）
• TypeScript：src/全部使用.ts/.tsx；open-sse/使用.ts/.js混合；公共函数需用 TSDoc 注释（@param、@returns、@throws）
• 禁用eval()：ESLint 强制no-eval、no-implied-eval、no-new-func
• Zod 校验：所有 API 输入校验使用 Zod v4 schema
• 命名：文件 = camelCase / kebab-case，组件 = PascalCase，常量 = UPPER_SNAKE

4.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.md
• API 参考：docs/reference/API_REFERENCE.md
• 使用指南：docs/guides/USER_GUIDE.md
• 故障排查：docs/guides/TROUBLESHOOTING.md
• MCP 服务器：docs/frameworks/MCP-SERVER.md
• A2A 协议：docs/frameworks/A2A-SERVER.md
• 自动组合引擎：docs/routing/AUTO-COMBO.md
• CLI 工具集成：docs/reference/CLI-TOOLS.md
• 覆盖率提升计划：docs/ops/COVERAGE_PLAN.md
• OpenAPI 规范：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 test）
• Lint 通过（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.md
• API 细节：参考 docs/reference/API_REFERENCE.md
• 通用排查：参考 docs/guides/TROUBLESHOOTING.md
• 环境变量手册：参考 docs/reference/ENVIRONMENT.md 与 .env.example
• 变更片段管理：changelog.d/目录下按features/、fixes/、maintenance/分类存放，编号命名对应 issue/PR
• Contributing 英文原版：CONTRIBUTING.md；日文版即本文骨架来源 docs/i18n/ja/CONTRIBUTING.md

九、快速回顾：从克隆到首个 PR 的完整路径

1. 安装 Node 22 LTS、npm 10+、Git
2. git clone仓库 →npm install→cp .env.example .env并生成JWT_SECRET与API_KEY_SECRET
3. npm run dev启动开发环境，验证仪表盘（/dashboard）与 API（/v1）
4. 从main检出特性分支（feat/、fix/、docs/等前缀）
5. 按 Conventional Commits 规范提交，commit 前自动执行 Prettier + ESLint（lint-staged）
6. 按需编写/更新tests/unit/下的测试，运行npm run test:unit与npm run test:coverage，确保四项覆盖率 ≥ 60%
7. 对照 PR 清单自查，发起 Pull Request 并在 PR 描述中列出测试变更
8. 等待 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute