OmniRoute 发布检查清单实战指南：从版本号、API 文档到 npm 发布的完整流程

OmniRoute 发布检查清单实战指南：从版本号、API 文档到 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

本文基于仓库发布的官方检查清单（英文原版 与 俄语版）整理而成，结合当前仓库源码与工作流配置，梳理 OmniRoute 在打标签（tagging）与发布（publishing）新版本前必须完成的全部校验项。读完本文，你将掌握 OmniRoute 的版本号与 CHANGELOG 同步规范、API 文档契约、Node.js 安全运行时基线、npm 发布产物校验，以及本地与 CI 的自动化同步检查流程。

发布清单的定位：为什么需要它

OmniRoute 是一个单体仓库式 AI 网关项目，发布面覆盖 npm 包（omniroute）、Electron 桌面端、Docker 镜像与 OpenCode 插件等多个交付物。任何一次发布都牵动package.json、CHANGELOG.md、docs/openapi.yaml、本地化文档与构建产物等多处一致性。官方为此维护了一份"打标签或发布前必须逐项核对"的检查清单，核心目标可以概括为三点：

1. 版本号单一事实来源：package.json、CHANGELOG.md最新 semver 小节与 OpenAPI 文档中的info.version必须严格相等；
2. 文档与运行时零漂移：架构文档、故障排查文档与.env契约必须跟上代码变化；
3. 发布产物可审计：npm 包内不得混入本地残留文件，且必须能干净启动。

版本号与 CHANGELOG：发布的第一步

清单要求按以下顺序完成版本与变更日志的处理：

1. 在发布分支中提升package.json的版本号（格式x.y.z）；
2. 将CHANGELOG.md中## [Unreleased]的内容移动到带日期的正式小节：
   • ## [x.y.z] — YYYY-MM-DD
3. 保留## [Unreleased]作为变更日志的第一节，供下一个版本的开发继续累积；
4. 确认CHANGELOG.md中最新 semver 小节与package.json版本号一致。

从源码看，package.json 当前版本为3.8.51，engines.node声明为>=22.22.2 <23 || >=24.0.0 <27，这四项就是版本同步的锚点。仓库还为版本提升提供了自动化技能入口：/version-bump-cc <patch|minor|major>（Claude Code skill），它会同时提升根package.json与electron/package.json、基于上次 tag 重新生成CHANGELOG.md并更新 README 徽章——发布者仍应人工审阅生成的 CHANGELOG 并清理提交信息。

API 文档契约：info.version 必须等于 package.json 版本

清单在 "API Docs" 一节要求：

1. 更新docs/openapi.yaml，确保info.version等于package.json版本号；
2. 如果 API 契约发生变化，需要验证其中的端点示例。

仓库中实际的 OpenAPI 文件位于 docs/openapi.yaml（注意：俄语版清单中写的是docs/reference/openapi.yaml，而当前仓库的英文原版与真实文件路径均为docs/openapi.yaml，以仓库实际为准）。这一契约约束有专门的 CI 守护：npm run check:openapi-coverage、npm run check:openapi-breaking、npm run check:openapi-routes等一系列检查脚本（见 package.json 的 scripts 段），以及 docs/reference/API_REFERENCE.md 与 OpenAPI 文件的联动更新要求。发布前若改动了 API，务必确认check:openapi-breaking通过，避免破坏既有客户端的向后兼容。

运行时文档与 Node.js 安全基线

发布前需要审阅以下文档，排查与存储/运行时的漂移：

• docs/architecture/ARCHITECTURE.md：核对存储与运行时架构是否与代码一致；
• docs/guides/TROUBLESHOOTING.md：核对环境变量与运维说明是否漂移。

同时，必须验证发布/运行时使用的 Node.js 版本仍然满足项目支持的安全基线，清单给出的校验命令是：

npm run check:node-runtime

关于 Node 版本基线，俄语版清单记录的旧基线为>=20.20.2 <21或>=22.22.2 <23，但当前仓库的实际策略已经演进，请以仓库现状为准：

• src/shared/utils/nodeRuntimeSupport.ts 中定义SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27"，安全版本线（SECURE_NODE_LINES）覆盖22.22.2、24.0.0、25.0.0、26.0.0四条主版本线；
• 推荐版本为RECOMMENDED_NODE_VERSION = "24.14.1"；
• package.json 的engines字段与之一致；
• scripts/check/check-supported-node-runtime.ts 是检查脚本的实现：运行时若不兼容，会打印Unsupported or insecure Node.js runtime detected并以退出码 1 失败；若在 Bun 下运行，则按SUPPORTED_NODE_RANGE + " || Bun >=1.1.0"判定。

从源码结构看，nodeRuntimeSupport.ts被刻意实现为纯 ESM，以便被bin/下的 CLI 入口、src/下的 Next.js 路由处理器和scripts/下的脚本三方复用，这说明运行时基线检查不仅在发布前执行，也贯穿日常启动与运维路径。

npm 发布产物的构建与校验

构建独立包（standalone package）之后，必须验证 npm 发布产物：

npm run build:cli npm run check:pack-artifact

check:pack-artifact（实现见 scripts/build/validate-pack-artifact.ts）会确认产物中不包含以下本地残留：

• app.__qa_backup
• scripts/scratch
• package-lock.json
• 或其他本地残留文件

构建布局方面，仓库明确区分三个目录，切勿混用：

发布部署时推荐使用单一构建命令npm run build:release（先rm -rf .build dist清理，再执行next build、组装 standalone 目录并写入dist/BUILD_SHA哨兵文件），而不是先npm run build再单独npm run build:cli。部署前还需确认dist/BUILD_SHA等于git rev-parse --short HEAD，保证线上运行的就是本次构建的代码。另外需要说明：远程 VPS 上镜像目录仍为/usr/lib/node_modules/omniroute/app/，构建产物目录从仓库内的app/迁移到dist/不影响远程路径，部署技能会把dist/内容 rsync 到远程app/目录。

自动化同步检查：docs-sync

打开 PR 之前，必须在本地运行文档同步守卫：

npm run check:docs-sync

CI 也会在.github/workflows/ci.yml的 lint job 中运行该检查（实现见 scripts/check/check-docs-sync.mjs）。这保证了文档结构与内容的同步性不会被破坏。

深入：发布流程背后的自动化与保障机制

英文原版清单（docs/ops/RELEASE_CHECKLIST.md）对上述流程给出了更完整的自动化补充，以下要点同样属于发布检查清单的组成部分。

TL;DR：一条命令走完的核心链路

# 1. Bump 版本 + 生成 CHANGELOG（skill） /version-bump-cc patch # 或 minor/major # 2. 本地质量门 npm run check # lint + 测试 npm run test:coverage # 覆盖率门（60/60/60/60） # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成发布（skill） /generate-release-cc # 5. 部署（skill） /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 采集发布证据（skill） /capture-release-evidences-cc

npm Trusted Publishing 与 staged 发布

自 v3.8.51 起，.github/workflows/npm-publish.yml 默认通过npm Trusted Publishing（OIDC）发布：stage-npmjob 在 GitHub 托管 runner 上把 GitHub 的 id-token 换成一次性的短时 npm 凭证——仓库 secrets 里不再存长期 npm token，也不需要 2FA 提示，同时附带 provenance（SLSA 级来源证明）。泄漏 token 也无法单独完成发布，因为根本不存在 token。

流程细节：

• staged 模式（publish_mode=staged）：workflow 把打包好的 tarball 先"寄存"在 registry 上（npm stage publish），不可被安装，直到 owner 批准。批准流程为：
  1. npm stage list omniroute找到 stage id；
  2. 建议先校验：npm stage download <id>，把下载的 tarball 装进临时 prefix 并启动（CI 中的npm run check:pack-boot自动化了 pack→install→boot 判定）；
  3. npm stage approve <id>——2FA 提示就是发布本身；npm stage reject <id>则丢弃；
  4. 发布后的校验器会在干净容器中从公共 registry 安装已发布版本并启动验证。
• direct 模式（应急回退）：workflow_dispatch传publish_mode=direct恢复传统的立即npm publish，仅在 staging 本身出问题时使用并需记录原因。

发布流水线中还内置了两道"启动验证"：check:pack-boot（干净安装后必须能启动）与check:install-upgrade（在已有版本之上覆盖安装并启动，覆盖约 110 个 SQLite 迁移在真实数据库上运行的升级路径）。发布前任何一个坏制品都不会到达 registry。

Hotfix 快速通道

标记为hotfix的 PR 会跳过重型 CI 矩阵（9 分片 E2E、覆盖率 ratchet、质量门），只保留高信号门：build、单元测试分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟（check:pack-boot），目标是把绿色时间从约 33 分钟压缩到 ≤15 分钟。入口政策要求同时满足四条：严重性（生产已损坏——发布产物启动即崩溃/安全修复/所有用户受影响）、权限（仅仓库 owner 可打hotfix标签）、证据（PR 正文链接上一次完整绿色重型运行 + 修复自身的失败转通过测试）、范围（仅 cherry-pick 最小修复，不带重构）。被跳过的覆盖率面会在发布分支的下一次完整运行中重新验证——快速通道跳过的是等待，不是验证。

质量门与测试矩阵

清单要求发布分支上的完整校验包括：

• npm run lint（0 error，warning 为存量）；
• npm run typecheck:core与npm run typecheck:noimplicit:core（严格模式）全绿；
• npm run check:cycles（无循环依赖）、npm run check:any-budget:t11、npm run check:route-validation:t06；
• npm run test:unit、npm run test:vitest（MCP server、autoCombo、cache）、npm run test:coverage（覆盖率门 60/60/60/60：statements/lines/functions/branches）；
• npm run test:integration（改动涉及 DB/handlers 时）、npm run test:combo:matrix（覆盖全部 19 种公共路由策略的选择判定，触碰组合路由/策略解析/回退逻辑时必跑）；
• npm run test:e2e（UI 改动）、npm run test:protocols:e2e（MCP/A2A 改动）、npm run test:ecosystem。

其中test:combo:live与test:combo:live:vps是可选/手动的线上冒烟（会真实打上游 provider、消耗额度，绝不在 CI 中运行），无 gate 时可干净跳过。

Husky 钩子与会话提交规范

Husky 钩子位于.husky/，在 git 操作时自动运行：

• pre-commit：npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11；
• pre-push：快速确定性门——npm run check:any-budget:t11 && npm run check:tracked-artifacts（刻意排除慢速的test:unit，由 CI 的test-unitjob 覆盖；推送发布分支前请手动运行npm run test:unit）。

钩子失败时应修复底层问题，不要用--no-verify绕过。所有进入发布的提交必须遵循type(scope): subject约定，合法类型为feat|fix|refactor|docs|test|chore|perf|style|ci，合法 scope 包括db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz。破坏性变更需加BREAKING CHANGE:脚注或在 scope 后加!（如feat(api)!: drop /v0）。

数据库迁移与 Provider 目录

• 若src/lib/db/migrations/出现新文件：每个迁移必须幂等（CREATE TABLE IF NOT EXISTS等）、包裹在事务中、编号连续无缺口；分别测试全新安装（删除~/.omniroute/omniroute.db后npm run dev）与已有安装（备份 DB → 跑迁移 → 验证 schema）；若迁移重写表，需正确处理 WAL 文件（-wal、-shm）。
• Provider 目录由 Zod schema 在加载时校验（src/shared/constants/providers.ts）：所有 provider 必须有必填字段（id、label、kind等）；新免费 provider 需提供freeNote；OAuth provider 需在src/lib/oauth/constants/oauth.ts注册oauthConfig；新增 provider 时对应 executor 在open-sse/executors/、非 OpenAI 格式需在open-sse/translator/增加 translator，模型注册在open-sse/config/providerRegistry.ts，并在tests/unit/中补充 provider 分类与路由的单测。

打标签、部署与回滚

发布版本前运行/generate-release-cc（创建并推送 tagvX.Y.Z、以 changelog 正文打开 GitHub Release、附加 Electron 安装包），或手动执行：

git tag -a vX.Y.Z -m "Release vX.Y.Z" git push origin vX.Y.Z gh release create vX.Y.Z --notes-from-tag

部署使用轻量 rsync 流程（无npm pack、无npm i -g），按目标选择/deploy-vps-local-cc（本地 VPS）、/deploy-vps-akamai-cc（Akamai VPS）或/deploy-vps-both-cc。部署后冒烟检查：

• 打开/dashboard/health，版本号字符串与发布一致；
• 对已知 provider 发起一个/v1/chat/completions请求；
• 验证/api/monitoring/health返回CLOSED熔断状态；
• 确认 MCP 传输通道响应（/mcpHTTP、/mcp-sseSSE）。

若发布出现严重问题，回滚路径为：gh release edit vX.Y.Z --prerelease标记为非最新；若用户尚未采用，git tag -d vX.Y.Z && git push --delete origin vX.Y.Z；否则在release/vX.Y.0上做 hotfix 并发布补丁版本vX.Y.(Z+1)，同时立即在 GitHub Discussions 与 Discord 同步信息。

硬性规则（Hard Rules）

发布流程的底线约束：

• 绝不直接向main提交；
• 绝不对main或release/*分支使用git push --force；
• 绝不跳过 Husky 钩子（--no-verify）；
• 绝不提交密钥、凭据或.env文件；
• 覆盖率必须保持 ≥60/60/60/60（statements/lines/functions/branches）；
• 修改src/、open-sse/、electron/或bin/下的生产代码时，必须同步新增或更新测试。

小结

OmniRoute 的发布检查清单把"发布一个版本"从手工记忆变成了一套可执行、可自动化、可审计的工程流程：版本号与 CHANGELOG、OpenAPI 契约、Node.js 安全运行时基线、npm 产物校验、docs-sync 守卫、hotfix 快速通道与 staged 发布一起构成了多层防线。对本仓库的维护者而言，最实用的三件事是：发布前跑一遍npm run check:docs-sync与npm run check:node-runtime、用npm run build:release保证dist/BUILD_SHA与 HEAD 一致、以及理解 Trusted Publishing 下"2FA 即发布"的 staged 批准模型。

【免费下载链接】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