OmniRoute 发布清单（Release Checklist）实战指南：从版本号到 npm 产物的全流程发布核查

OmniRoute 发布清单（Release Checklist）实战指南：从版本号到 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

发布一个新版本对任何多语言、多组件项目都是高风险操作：版本号、变更日志、API 规范、运行时文档、构建产物、CI 检查必须全部保持一致，任何一处漂移都可能导致用户拿到一个"版本对不上号"的包。OmniRoute 用一份发布清单（Release Checklist）把这一流程固化为可执行的核查步骤，配套npm run check:docs-sync等自动化守卫，从 docs/ops/RELEASE_CHECKLIST.md（英文原版）到 docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md（西班牙语镜像）在内的全部文档镜像，共同定义了 tagging 或发布前的强制核查内容。读完本文，你将掌握 OmniRoute 版本发布前必须逐一验证的四大核查域（版本与变更日志、API 文档、运行时文档、自动化检查），以及构建产物校验、npm 信任发布（Trusted Publishing）、Hotfix 快车道等进阶发布机制，并能直接在仓库中定位对应脚本与 CI 配置进行核对。

使用这份清单前：先让发布分支保持绿色

英文原版清单开篇即强调：发布不是起点，而是结果。在跑清单之前，应先通过 docs/ops/RELEASE_GREEN.md 中描述的"release-green 家族"（/green-prs队列扫描、npm run check:release-green校验引擎、/babysit <PR#>单 PR 驱动、nightly-release-green.yml夜间自动校验）周期性地预检整个 PR 队列与活动发布分支，让发布 PR 的首次 CI 运行就是绿的，而不是在发布当天以约 40 分钟一轮的节奏逐层排雷。其中 scripts/quality/validate-release-green.mjs 是核心引擎，它把每条红色结果分类为HARD（真实缺陷，exit 1）与DRIFT（棘轮基线漂移，仅报告、由维护者在发布时重新基线化，永不阻断任何人）。

一、版本与变更日志（Version and Changelog）

发布的第一组核查围绕"版本号一致性"展开，英文原版清单给出的 TL;DR 流程如下：

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

具体核查项包括：

1. 在发布分支上递增package.json版本号（x.y.z）。当前仓库 package.json 的版本为3.8.51。
2. 把CHANGELOG.md中## [Unreleased]下的发布说明移动到带日期的章节：## [x.y.z] — YYYY-MM-DD。
3. 保留## [Unreleased]作为 CHANGELOG 的第一个章节，承接后续工作。
4. 确保CHANGELOG.md中最新 semver 章节与package.json版本一致。

这四条规则并非仅靠自觉——它们正是 scripts/check/check-docs-sync.mjs 的校验逻辑。从源码看，该脚本依次检查：

• package.json的version必须是合法 semver（/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/）；
• CHANGELOG.md的第一节必须是## [Unreleased]；
• CHANGELOG 中最新 semver 章节必须等于package.json版本，否则输出Latest changelog release (...) differs from package.json (...)并最终process.exit(1)。

也就是说，第 4 条"清单核查项"背后有可重复执行的机器守卫，任何人只要跑npm run check:docs-sync就会被强制对齐。

二、API 文档（API Docs）

对外提供 OpenAI 兼容 API 的网关项目，其 OpenAPI 规范是用户集成的重要契约，因此发布前必须同步：

1. 更新docs/openapi.yaml的info.version，使其等于package.json版本。
2. 如果 API 契约发生变化，校验端点示例。

同样，这一项也是自动化的。check-docs-sync.mjs中有专门的extractOpenApiVersion()函数，从docs/openapi.yaml的info:块解析出version字段，并与package.json.version比对，不一致即判失败并输出OpenAPI version (...) differs from package.json (...)。

此外，从 scripts/build/prepublish.ts 可以看到，docs/openapi.yaml还会被复制进 npm 发布包的dist/docs/目录（见build:cli阶段的第 9.5 步），因此它不仅是仓库内契约，更是随发布产物交付给下游用户的运行时契约——版本漂移会直接污染已发布的包。

三、运行时文档（Runtime Docs）

发布前需要审查与运行环境相关的文档是否漂移：

1. 审查 docs/architecture/ARCHITECTURE.md，确认存储/运行时描述没有与实际实现脱节。
2. 审查 docs/guides/TROUBLESHOOTING.md，确认环境变量与运维细节没有漂移。
3. 验证发布/运行时所用 Node.js 版本仍满足支持的安全底线：
   • >=20.20.2 <21或>=22.22.2 <23（英文原版清单给出的安全底线）；当前仓库 package.json 的engines已更新为>=22.22.2 <23 || >=24.0.0 <27，以仓库实际值为准；
   • 运行npm run check:node-runtime。
4. 构建独立包后验证 npm 发布产物：
   • npm run build:cli
   • npm run check:pack-artifact
   • 确认产物中不存在app.__qa_backup、scripts/scratch、package-lock.json或其他本地残留物。
5. 如果源文档有显著变更，更新本地化文档（例如本文所在的docs/i18n/各语言镜像目录）。

Node 运行时底线的实现位于 src/shared/utils/nodeRuntimeSupport.ts：模块导出SECURE_NODE_LINES（22.22.2、24.0.0、25.0.0、26.0.0 各主版本的补丁底线）、SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27"和RECOMMENDED_NODE_VERSION = "24.14.1"。getNodeRuntimeSupport()会把当前process.versions.node与对应主版本的安全底线逐段比较，给出supported/below-security-floor/unsupported-major/unreleased-major四种判定；npm run check:node-runtime即封装了对这一策略的 CLI 检查（见 package.json 中的check:node-runtime脚本指向 scripts/check/check-supported-node-runtime.ts）。Bun 运行时（process.versions.bun存在）则直接判为supported-bun。

四、自动化同步检查（Automated Check）

这是清单中唯一给出明确命令的强制步骤，开 PR 前在本地运行：

npm run check:docs-sync

CI 也会在 .github/workflows/ci.yml 的 lint 作业中运行该检查。从仓库证据看，这一职责在 CI 中已被强化：ci.yml中有独立的docs-sync-strict作业，其执行命令是npm run check:docs-all（伞形检查：docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links），并且被纳入发布 PR 的必过依赖（needs: docs-sync-strict）。

npm run check:docs-sync还承担一个易被忽略的职责——i18n 镜像一致性。从 scripts/check/check-docs-sync.mjs 源码可见，它遍历docs/i18n/下全部语言目录：

• 对llm.txt等镜像文件要求逐字节一致（去掉首行标题后与根文件归一化比较，且每个语言镜像文件必须包含---分隔符）；
• 对CHANGELOG.md镜像，因各语言翻译了章节标题，采用"版本章节集合 + 行数容差"校验：必须包含根 CHANGELOG 的全部## [X.Y.Z]章节且顺序一致，正文行数差异不得超过 25%。

也就是说，本文所在的西班牙语镜像文档之所以能与英文原版结构对齐，正是由这套同步守卫保障的——任何语言镜像与源文档漂移，都会让check:docs-sync在本地与 CI 双双失败。

五、发布产物与构建布局（Artifact Validation）

清单要求在发布前验证构建产物干净、可追溯。仓库当前采用的是"单次构建"流程，不建议把npm run build与单独的npm run build:cli分开跑，而是直接使用：

npm run build:release ├─ rm -rf .build dist （清理） ├─ next build → .build/next/ （中间产物） ├─ assembleStandalone （standalone + static + public + natives → dist/） └─ 写入 dist/BUILD_SHA （HEAD 哨兵）

配套核查：

• npm run build:release成功后dist/BUILD_SHA必须等于git rev-parse --short HEAD；
• npm run check:pack-artifact必须干净——不得出现app.__qa_backup、scripts/scratch、package-lock.json等本地残留；
• dist/server.js必须存在。

三个输出目录的职责在清单中有明确区分（发布布局表）：src/是应用源码（被 git 跟踪）；.build/是next build的中间产物目录（distDir，gitignore）；dist/是可由assembleStandalone组装、可发布的 npm bundle（gitignore）。运维上需要注意：远端 VPS 的镜像目录仍是/usr/lib/node_modules/omniroute/app/，仅仓库内构建输出从app/移到了dist/，部署 skill 通过 rsync 把dist/内容同步到远端app/，因此 VPS 路径无需变更。

npm run check:pack-artifact的实现见 scripts/build/validate-pack-artifact.ts，它执行npm pack --dry-run --json并从四个方面审计发布包：意外文件（不在允许的精确路径/前缀白名单内）、必需运行时文件缺失、测试文件泄漏（*.test.*、__tests__等，由package.json的files否定规则兜底）、以及MCP 闭包完整性（computeMcpClosure()遍历 MCP 可达的 TypeScript 源文件，逐文件确认被打包，防止--mcp运行时 404）。此外，从buildProvenance.ts的证据链看，它还会校验dist/BUILD_SHA对应的提交是origin/main的祖先，防止从旧分支构建出"假发布"（2026-08-14 网关事故的教训），只有OMNIROUTE_ALLOW_CANARY_BUILD=1才能绕过。

六、npm 信任发布与分阶段发布（Trusted Publishing / Staged）

自 v3.8.51 起，npm 发布默认走npm Trusted Publishing（OIDC）：npm-publish.yml的stage-npm作业在 GitHub 托管的 runner 上用 id-token 换取该次运行的短期 npm 凭证，仓库 secrets 里不再存放长期 npm token，也无 2FA 提示，且自动附加 provenance 来源证明。这意味着即使 token 泄露也无法单独完成发布——根本没有 token 存在。

与之配合的是"先暂存、后批准"的分阶段发布模式（publish_mode=staged）：工作流启动打包产物（check:pack-boot）后执行npm stage publish，字节先停在 registry 上但不可安装，等所有者人工 2FA 放行。发布者（owner）在工作流变绿后的流程：

1. npm stage list omniroute找到 stage id（工作流摘要中也会打印）；
2. （推荐）npm stage download <id>验证暂存字节，装进临时 prefix 并启动；
3. npm stage approve <id>——这一步的 2FA 提示就是发布动作；npm stage reject <id>则丢弃；
4. 发布后由后置验证器从公共 registry 在干净容器里安装并启动刚发布的版本。

紧急回退：workflow_dispatch传publish_mode=direct恢复传统立即npm publish（仅当暂存机制本身异常时使用，并记录原因）。这一机制在 .github/workflows/npm-publish.yml 中有完整实现，publish_mode参数的可选值与语义（auto/staged/direct）也定义在同一工作流中。此外，每次稳定 SemVer 发布时docker-publish工作流必须同时给X.Y.Z打标签，并在should-promote-latest.sh判定其为最高稳定版本时以相同 digest更新:latest，避免latest停留在老构建上。

七、Hotfix 快车道与硬规则

当生产环境被打破（发布产物启动即崩 / 安全修复 / 影响该版本所有用户）时，带hotfix标签的 PR 可以跳过重型 CI 矩阵（9 分片 E2E、覆盖率棘轮、quality-gate、quality-extended），只保留高信号门：build、单元分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟（check:pack-boot），目标是把绿灯时间从约 33 分钟压到 15 分钟以内。该车道有严格准入策略（仿照 Chromium/VS Code/Node 的应急车道）：严重性（生产确实 broken，"重要"不等于"broken"）、权限（只有仓库所有者能贴hotfix标签，标签本身就是批准）、证据（PR 正文必须链接上一次全绿的 heavy 运行记录 + 该修复自身的"先红后绿"测试）、范围（只允许 cherry-pick 最小修复，禁止重构与搭便车改动）。被跳过的覆盖率/棘轮面由发布分支上下一轮全量运行重新验证——车道跳过的是"等待"，不是"验证"。

无论常规发布还是 hotfix，以下硬规则始终有效：

• 永远不要直接提交到main；
• 永远不要对main或release/*分支使用git push --force；
• 永远不要跳过 Husky hooks（--no-verify）；
• 永远不要提交 secrets、凭证或.env文件；
• 覆盖率必须保持在 ≥60/60/60/60（statements/lines/functions/branches）；
• 修改src/、open-sse/、electron/或bin/中的生产代码时，必须同时新增或更新测试。

Husky hooks 位于.husky/：pre-commit 运行npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11；pre-push 运行快速确定性门（check:any-budget:t11+check:tracked-artifacts），刻意不含慢速的test:unit（由 CI 的 test-unit 作业覆盖），因此在推送发布分支前应手动跑一次npm run test:unit。Hook 失败就修复根因，不要用--no-verify绕过。

八、发布、回滚与发布后动作

发布动作本身可通过 Claude Code skill/generate-release-cc完成（创建vX.Y.Ztag、推送 tag 与分支、以 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），按目标选择 skill：/deploy-vps-local-cc（本地 VPS 192.168.0.15）、/deploy-vps-akamai-cc（Akamai VPS 69.164.221.35）、/deploy-vps-both-cc（两者）。部署前必须确认dist/BUILD_SHA等于git rev-parse --short HEAD，且构建必须在node_modules真实存在的环境进行（主 checkout 或npm ci过的 worktree，而非符号链接 worktree）。部署后冒烟测试：打开/dashboard/health核对版本串；对已知 provider 发起/v1/chat/completions请求；确认/api/monitoring/health返回CLOSED熔断状态；确认 MCP 传输（/mcpHTTP、/mcp-sseSSE）正常响应。

发布后：运行/capture-release-evidences-cc捕获新功能的 WebP 截图/录像并附到发布说明；更新社区公告；开启下一版本 milestone；关键发布可在 news.json 中登记用于应用内横幅。

回滚预案（发布后发现严重问题时按序执行）：

1. gh release edit vX.Y.Z --prerelease（标记为非最新）；
2. 若尚未被用户采用：git tag -d vX.Y.Z && git push --delete origin vX.Y.Z；
3. 或在release/vX.Y.0上出 hotfix → 打补丁版vX.Y.(Z+1)；
4. 立即在社区渠道同步沟通。

对于坏产物，npm deprecate omniroute@<bad> "<reason> — use <fixed>"是默认反应（几分钟内可逆）；npm unpublish仅限 72 小时且无依赖者的窗口，且永远不作为第一步。Docker 镜像永远不要重写版本 tag——回滚就是把latest重新指向最后一个好 digest。

九、从清单到工程实践：三个可立即落地的动作

1. 把npm run check:docs-sync变成肌肉记忆：它是版本号、CHANGELOG、OpenAPI、i18n 镜像四方对齐的统一守卫，本地失败就不该开 PR。
2. 发布前先跑npm run build:release+npm run check:pack-artifact：前者一次完成干净重建并写入BUILD_SHA哨兵，后者从意外文件、必需文件、测试泄漏、MCP 闭包与构建溯源五个维度审计 tarball，是发布包可用的最后防线。
3. 用 release-green 家族把发布日的红色风险前移：定期运行/green-prs与npm run check:release-green，让发布 PR 的首次 CI 运行即为绿色，而不是在发布当天逐层排雷。

相关资源：完整英文版清单、发布分支常绿指南、docs 同步守卫实现、npm 产物审计实现、Node 运行时策略、npm 发布工作流、主 CI 工作流。

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