企业官网建设流程全解析

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

本文以 docs/i18n/id/CONTRIBUTING.md（印尼语版贡献指南，与 CONTRIBUTING.md 英文版同源）为骨架，结合当前仓库的package.json、.env.example与源码目录结构展开。读者将掌握：如何在本机搭建 OmniRoute 3.8.x 开发环境、如何按 Git 分支规范提交改动、如何运行与覆盖测试、如何遵循代码风格，以及如何在 6 个步骤内为 OmniRoute 接入一个新的 AI Provider——这是参与这个由 550+ 贡献者共建的开源 AI 网关（MIT 协议）项目最核心的入门路径。

1. 开发环境搭建（Development Setup）

OmniRoute 是一个基于 Next.js 16 + TypeScript 的全栈项目，前后端同仓。参与开发的第一步是把仓库克隆到本地并跑通开发服务器。

1.1 环境要求（Prerequisites）

贡献指南明确要求以下工具链：

版本说明：贡献指南中的 Node 版本区间随版本演进收窄，判断你本机 Node 是否受支持时，应优先以仓库根目录 package.json 中engines字段的实际约束为准。此外npm install会触发 postinstall 脚本完成原生模块与运行时环境的准备。

1.2 克隆与安装（Clone & Install）

git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install

仓库使用 npm workspaces 组织多个子包（见 package.json 的workspaces字段），open-sse/与packages/browser-pool会在安装时一并解析依赖。

1.3 环境变量配置（Environment Variables）

首次运行前，从模板创建.env并生成两个必需密钥：

# 从模板创建 .env cp .env.example .env # 生成必需密钥 echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env

指南给出的开发期核心变量如下：

这些变量在仓库根目录的 .env.example 中有完整、逐条注释的权威定义（共 3114 行，覆盖密钥、存储、网络、安全、路由策略、URL 与云同步、出站代理、CLI 集成、MCP/A2A 集成等十余个分区）。可以印证的是：

• JWT_SECRET用于src/lib/auth，负责签发/校验所有已登录会话 Cookie；
• API_KEY_SECRET用于src/lib/db/apiKeys.ts，负责对数据库中的 API Key 做静态加密；
• INITIAL_PASSWORD仅在首次启动引导时生效，首次登录后可在 Dashboard → Settings → Security 中修改；
• APP_LOG_LEVEL为debug时会同时开启更多诊断日志。

1.4 Dashboard 设置（数据库持久化）

Dashboard 提供 UI 开关，可以覆盖通过环境变量配置的同类功能：

这些设置写入 SQLite 数据库，重启后依然保留；一旦在 UI 中设置过，就会覆盖环境变量的默认值。

1.5 本地运行（Running Locally）

# 开发模式（热重载） npm run dev # 生产构建 npm run build npm run start # 常用端口配置 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

默认访问地址：

• Dashboard：http://localhost:20128/dashboard
• API：http://localhost:20128/v1

从 package.json 的 scripts 可以看到npm run dev实际执行node scripts/dev/run-next.mjs dev（默认使用 Turbopack 打包，OMNIROUTE_USE_TURBOPACK=0可回退 webpack）；npm run build走scripts/build/build-next-isolated.mjs，产物经assembleStandalone组装到dist/。对仅涉及后端/API 的改动，还可使用更快的npm run build:contributor（仅做编译级校验，不组装可分发产物）。

2. Git 工作流（Git Workflow）

⚠️绝对禁止直接向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.1 分支命名（Branch Naming）

2.2 提交信息（Commit Messages）

遵循 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（英文版 CONTRIBUTING 进一步扩展了providers、executors、translator、compression、guardrails、authz等 scope，提交时以最新 CONTRIBUTING.md 为准）。

英文版指南还补充了一条硬性约定：commit message 中不得出现Co-Authored-By尾注，提交须以仓库所有者的 Git 身份单独呈现（Hard Rule #16）。参与合并前，建议先阅读 docs/ops/BRANCHING_MODEL.md（release-per-branch + tag-at-ship 的发布模型）与 docs/ops/CONTRIBUTION_GOLDEN_PATH.md（按变更类型映射契约、聚焦测试、CI 覆盖与对账步骤的"贡献黄金路径"）。

3. 运行测试（Running Tests）

3.1 测试命令全览

# 全部测试（unit + vitest + ecosystem + e2e） npm run test:all # 单个测试文件（Node.js 原生测试运行器——大多数测试采用此方式） 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 # 覆盖率（语句/行/函数/分支 60% 门槛） npm run test:coverage npm run coverage:report # Lint + 格式检查 npm run lint npm run check

从 package.json 可以看到test:coverage通过c8执行，参数--statements 60 --lines 60 --functions 60 --branches 60与指南的 60% 门槛完全一致；tests/_setup/isolateDataDir.ts等 setup 模块会在测试启动时隔离数据目录，避免测试污染开发者真实的 SQLite 数据库。

3.2 覆盖率说明（Coverage Notes）

• npm run test:coverage只统计主单元测试套件对应的源码覆盖，排除tests/**，并包含open-sse/**；
• PR 必须将整体覆盖率维持在语句、行、函数、分支均 ≥ 60%；
• 若 PR 修改了src/、open-sse/、electron/或bin/下的生产代码，必须在同一 PR 内新增或更新自动化测试；
• npm run coverage:report打印逐文件的详细报告；
• npm run test:coverage:legacy保留旧指标用于历史对比；
• 渐进式覆盖率提升路线见 docs/ops/COVERAGE_PLAN.md。

3.3 Pull Request 要求（PR Requirements）

打开或合并 PR 之前：

• 运行npm run test:unit；
• 运行npm run test:coverage；
• 确保所有覆盖率指标保持在60%+；
• 当生产代码发生变更时，在 PR 描述中列出被修改或新增的测试文件；
• 当项目密钥在 CI 中配置后，检查 PR 上的 SonarQube 结果。

3.4 当前测试覆盖的主题

截至贡献指南撰写时，约 122 个单元测试文件覆盖了以下能力域（随着版本演进，tests/unit目录规模持续增长，当前子树已包含数千个测试文件）：

• Provider 翻译器与格式转换
• 限流（rate limiting）、熔断器（circuit breaker）与韧性（resilience）
• 语义缓存、幂等性、进度跟踪
• 数据库操作与 schema（110 个顶层模块、130 个迁移）
• OAuth 流程与认证
• API 端点校验（Zod v4）
• MCP server 工具与 scope 强制
• Memory 与 Skills 系统

4. 代码风格（Code Style）

• ESLint— 提交前运行npm run lint；
• Prettier— 通过lint-staged在提交时自动格式化（2 空格缩进、分号、双引号、100 字符宽、es5 尾逗号）；
• 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。

5. 项目结构（Project Structure）

src/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # Dashboard 页面（23 个分区） │ ├── api/ # API 路由（51 个目录） │ └── login/ # 认证页面 (.tsx) ├── domain/ # 策略引擎（policyEngine、comboResolver、costRules 等） ├── lib/ # 核心业务逻辑 (.ts) │ ├── a2a/ # Agent-to-Agent v0.3 协议服务器 │ ├── acp/ # Agent Communication Protocol 注册表 │ ├── compliance/ # 合规策略引擎 │ ├── db/ # SQLite 领域模块 + 130 个迁移 │ ├── memory/ # 持久会话记忆 │ ├── oauth/ # OAuth 提供商、服务与工具 │ ├── skills/ # 可扩展技能框架 │ ├── usage/ # 用量跟踪与成本计算 │ └── localDb.ts # 仅做 re-export 的层——严禁在此添加逻辑 ├── middleware/ # 请求中间件（promptInjectionGuard） ├── mitm/ # MITM 代理（证书、DNS、目标路由） ├── shared/ │ ├── components/ # React 组件 (.tsx) │ ├── constants/ # Provider 定义（329）、MCP scope、19 种路由策略 │ ├── utils/ # 熔断器、清洗器、认证辅助 │ └── validation/ # Zod v4 schema └── sse/ # SSE 代理管道 open-sse/ # @omniroute/open-sse workspace ├── executors/ # 89 个 executor 实现模块 ├── handlers/ # 11 个请求 handler（chat、responses、embeddings、images 等） ├── mcp-server/ # MCP 服务器（107 个工具、3 种 transport、32 个 scope） ├── services/ # 178 个顶层服务（combo、autoCombo、rateLimitManager 等） ├── translator/ # 格式翻译器（OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama） ├── transformer/ # Responses API 转换器 └── utils/ # 22 个工具模块（stream、TLS、proxy、logging） electron/ # Electron 桌面应用（跨平台） tests/ ├── unit/ # Node.js 测试运行器（122 个测试文件） ├── integration/ # 集成测试 ├── e2e/ # Playwright 测试 ├── security/ # 安全测试 ├── translator/ # 翻译器专项测试 └── load/ # 负载测试 docs/ # 文档 ├── architecture/ # 系统架构 ├── reference/ # API 参考、环境变量、CLI 工具 ├── guides/ # 用户指南、Docker、安装、排障 ├── ops/ # 部署、代理、覆盖率、发布 └── ...

以上目录树中标注的数字（如 329 个 Provider、89 个 executor、107 个 MCP 工具）随版本持续演进，例如英文版 CONTRIBUTING.md 已更新为 1,574 个单元测试文件、MCP 110 个工具/33 个 scope 等。当前仓库tests/unit子树的真实规模（数千个.ts/.tsx测试文件）也远超指南撰写时的 122 个，说明测试体系随功能扩张持续增长。

6. 添加新 Provider（Adding a New Provider）

新增一个 Provider 是 OmniRoute 生态最常见的贡献场景，贡献指南给出了标准的六步流程：

第 1 步：注册 Provider 常量

添加到src/shared/constants/providers.ts—— 该文件在模块加载时经 Zod 校验（src/shared/constants/providers.ts 为仓库实际文件）。

第 2 步：添加 Executor（需要自定义逻辑时）

在open-sse/executors/your-provider.ts中创建 executor，并继承基础 executor（仓库中 89 个 executor 实现模块均位于 open-sse/executors 目录）。

第 3 步：添加 Translator（非 OpenAI 格式时）

在open-sse/translator/中创建请求/响应翻译器，实现 OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama 等格式互转（open-sse/translator 目录）。

第 4 步：添加 OAuth 配置（基于 OAuth 时）

在src/lib/oauth/constants/oauth.ts添加 OAuth 凭据，在src/lib/oauth/services/添加服务。

第 5 步：注册模型

在open-sse/config/providerRegistry.ts中添加模型定义（open-sse/config/providerRegistry.ts 为仓库实际文件）。

第 6 步：添加测试

在tests/unit/编写单元测试，至少覆盖：

• Provider 注册
• 请求/响应翻译
• 错误处理

安全补充（来自英文版指南，适配时请遵守）：若上游 Provider 在其公开 CLI/浏览器包里分发公共 OAuthclient_id/secret或 Firebase Web API key，不得将其作为字符串字面量硬编码，应使用resolvePublicCred()（open-sse/utils/publicCreds.ts）并在EMBEDDED_DEFAULTS中添加掩码字节条目，完整流程见 docs/security/PUBLIC_CREDS.md；handler/executor 中到达客户端的错误信息必须经过buildErrorBody()/sanitizeErrorMessage()（open-sse/utils/error.ts），禁止把原始err.stack/err.message放进响应体，详见 docs/security/ERROR_SANITIZATION.md。

7. Pull Request 检查清单（PR Checklist）

• 测试通过（npm test）
• Lint 通过（npm run lint）
• 构建成功（npm run build）
• 为新的公共函数和接口补充 TypeScript 类型
• 无硬编码的密钥或回退值
• 所有输入经 Zod schema 校验
• 涉及用户可见变更时更新 CHANGELOG
• 文档已更新（如适用）

英文版指南进一步补充的硬性项还包括：shell 命令（exec/spawn）通过env传递运行时值而非字符串插值；用户可见变更在changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md添加变更片段（而不是直接改CHANGELOG.md，见 changelog.d/README.md）；/api/mcp/、/api/cli-tools/runtime/等派生子进程的路由必须在src/server/authz/routeGuard.ts中归类为isLocalOnlyPath()（Hard Rule #15，见 docs/security/ROUTE_GUARD_TIERS.md）。这些条目应并入你的最终 PR 检查。

8. 发布流程与获取帮助（Releasing & Getting Help）

8.1 发布（Releasing）

发布通过/generate-release工作流管理。当 GitHub Release 创建时，包会经 GitHub Actions自动发布到 npm。部署相关细节（如npm run build:release的干净重建与dist/BUILD_SHA哨兵文件）可查阅 docs/ops/COVERAGE_PLAN.md 同目录下的部署文档。

8.2 获取帮助（Getting Help）

• 架构：参见 docs/architecture/ARCHITECTURE.md
• API 参考：参见 docs/reference/API_REFERENCE.md
• ADR（架构决策记录）：参见docs/下的架构决策记录文档

结语

这份贡献指南覆盖了 OmniRoute 从"本地跑起来"到"提交一个 Provider 级改动"的完整闭环：环境变量以 .env.example 为权威契约、测试体系以 60% 覆盖率门槛与聚焦测试（test:scoped等）保证回归质量、代码规范由 ESLint/Prettier/lint-staged 自动化兜底、新增 Provider 有固定六步流程可循。无论你是想接入一个新模型服务商，还是修复 SSE 管道、熔断器或 MCP 工具的一个缺陷，沿着本文的路径出发，就能以符合项目规范的方式把改动安全地合入这条"永不停止编码"的 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