OmniRoute 发布检查清单：从版本号、OpenAPI 契约到 CI 同步守卫的完整发布流程-平芜编程栈

OmniRoute 发布检查清单：从版本号、OpenAPI 契约到 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

发布一个 AI 网关意味着三件事必须同时成立：版本号在所有制品中一致、运行时文档没有漂移、自动化守卫全部通过。OmniRoute 的发布检查清单（docs/ops/RELEASE_CHECKLIST.md，多语言镜像版见挪威语版）把发布前工作压缩为四大板块——版本与 Changelog、API 文档、运行时文档、自动化同步检查——每一条都对应仓库里一个可执行的 npm script 或一个真实存在的文件契约。读完本文，你可以在打 tag 之前独立完成整套核对：从package.json的 semver 提升，到check:node-runtime的安全版本下限验证，再到check:pack-artifact对 npm 产物残留物的扫描，并理解每个检查背后的源码实现。

一、整体流程与 TL;DR

检查清单的顶层约定是：在打 tag 或发布新版本之前跑完全部核对项。清单给出的最小闭环是：

# 版本提升 + 生成 CHANGELOG # （skill 自动化路径见英文版 docs/ops/RELEASE_CHECKLIST.md 的 TL;DR） # 本地质量门 npm run check # lint + tests npm run test:coverage # 覆盖率门 60/60/60/60 # 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 发布后部署 + 证据采集由 Claude Code skills 承担

配套的"发布前保持队列绿色"约定见 RELEASE_GREEN（/green-prs系列 +npm run check:release-green）：发布 PR 在开始之前先保持分支常绿，能显著减少发布日期的返工。

下面按挪威语版清单的四个板块逐一展开，并在每个板块中给出仓库内的实现证据。

二、版本与 Changelog（Version and Changelog）

挪威语版清单在此板块给出四条硬性规则，完整继承如下：

在 release 分支中提升package.json的版本号（x.y.z）；
将CHANGELOG.md中## [Unreleased]下的发布说明迁移到带日期的章节：## [x.y.z] — YYYY-MM-DD；
保留## [Unreleased]作为 changelog 的第一个章节，用于承接后续工作；
确保CHANGELOG.md中最新的 semver 章节版本号等于package.json的版本号。

仓库中的 CHANGELOG.md 实际结构印证了这一点：文件以## [Unreleased]开头，其下按### ✨ New Features等分类累积条目，每次发布时整段平移为带日期的版本章节。

版本号一致性由自动检查兜底。package.json 中当前为"version": "3.8.51"，而 docs/openapi.yaml 的info.version同为3.8.51——两者必须相等，否则 docs-sync 守卫会失败。英文版清单的自动化 skill/version-bump-cc会同时提升根package.json与electron/package.json，并更新 README 徽章；若手动操作，这两处都要自行同步。

三、API 文档（API Docs）

挪威语版清单要求：

更新 OpenAPI 规范文件，其info.version必须等于package.json版本；
若 API 契约发生变化，重新验证端点示例。

这里需要指出一个随仓库演进产生的路径漂移：挪威语版写的是docs/reference/openapi.yaml，而当前仓库中 OpenAPI 契约实际位于 docs/openapi.yaml（此外还有一份对外暴露副本 public/openapi.yaml）。检查脚本以真实文件为准——scripts/check/check-docs-sync.mjs 中硬编码了docs/openapi.yaml作为解析目标：

const openApiPath = path.resolve(cwd, "docs/openapi.yaml");

脚本从info:块中逐行匹配version:字段（支持引号包裹），提取后与package.json比对。因此实操口径是：无论清单哪个语言版本写的路径是什么，以check-docs-sync.mjs中解析的路径为唯一权威，并保证该文件info.version与package.json一致（当前均为3.8.51）。

端点示例验证在契约变更时是人工核对项：对照docs/openapi.yaml中的examples与真实路由处理器行为，确保示例请求/响应仍然成立。

四、运行时文档（Runtime Docs）

这是清单中信息密度最高的板块，包含五项核对：

复查 docs/architecture/ARCHITECTURE.md 是否存在存储/运行时描述漂移；
复查 docs/guides/TROUBLESHOOTING.md 是否存在环境变量与运维描述漂移；
验证发布/运行时 Node.js 版本仍满足支持的安全下限，执行npm run check:node-runtime；
构建独立包后验证 npm 发布产物：npm run build:cli→npm run check:pack-artifact，确认不含app.__qa_backup、scripts/scratch、package-lock.json等本地残留；
若源文档有重大变更，同步更新本地化文档（docs/i18n/下各语言镜像）。

4.1 Node 运行时安全下限：一个"会漂移"的检查项

挪威语版记录的下限是>=20.20.2 <21或>=22.22.2 <23，但这正是需要"复查漂移"的典型项——当前仓库的实际策略已经演进。权威定义在 src/shared/utils/nodeRuntimeSupport.ts：

export const SECURE_NODE_LINES = Object.freeze([ Object.freeze({ major: 22, minor: 22, patch: 2 }), Object.freeze({ major: 24, minor: 0, patch: 0 }), Object.freeze({ major: 25, minor: 0, patch: 0 }), Object.freeze({ major: 26, minor: 0, patch: 0 }), ]); export const RECOMMENDED_NODE_VERSION = "24.14.1"; export const SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27";

从源码结构看，策略是"按 major 划定安全补丁线"（SECURE_NODE_LINES）：Node 22 必须 ≥ 22.22.2，24/25/26 各自有独立底线，而 major ≥ 27 会被判定为unreleased-major不兼容。Bun 运行时被单独放行（Bun >=1.1.0），推荐版本为 v24.14.1。package.json 的engines字段与之对齐："node": ">=22.22.2 <23 || >=24.0.0 <27"。

检查命令本身很薄，是一个判定-退出脚本 scripts/check/check-supported-node-runtime.ts：调用getNodeRuntimeSupport()，若不兼容则打印"支持的运行时区间 + 推荐版本"并以退出码 1 终止；兼容时输出类似Node.js 24.x.x satisfies OmniRoute secure runtime policy的确认行。发布核对时以该脚本的实际判定结果为准，而非任何文档里写死的版本区间。

4.2 npm 产物验证：`check:pack-artifact`到底扫什么

npm run build:cli（对应 scripts/build/prepublish.ts，由build:cli脚本驱动）负责组装可发布的 standalone 包；随后的npm run check:pack-artifact由 scripts/build/validate-pack-artifact.ts 实现，其工作流从源码可以完整还原：

暂存区自检：ensureAppStagingReady()先核对策略文件pack-artifact-policy.ts中声明的PACK_ARTIFACT_REQUIRED_PATHS（dist/前缀项）是否齐备；缺失则自动补跑npm run build:cli；
dry-run 打包：执行npm pack --dry-run --json --ignore-scripts，解析出将要入包的完整文件清单（findPackReport递归定位files[]载荷）；
策略比对：按 scripts/build/pack-artifact-policy.ts 中的允许前缀/精确路径（PACK_ARTIFACT_ALLOWED_PATH_PREFIXES/PACK_ARTIFACT_ALLOWED_EXACT_PATHS）过滤，报出"缺失的必需路径"与"意外的残留路径"——挪威语清单点名的app.__qa_backup、scripts/scratch、package-lock.json就属于这一类本地残留；
MCP 闭包校验：computeMcpClosure/findLeakedTestArtifactPaths还会检查 MCP server 发布闭包是否完整、是否泄漏了测试产物。

清单中的"确认无残留"这一步因此不是目视检查，而是白名单策略 + 自动失败：任何清单之外的路径出现都会让校验以非零退出。

五、自动化检查（Automated Check）

挪威语版清单的最后一节：

在开 PR 之前，本地运行同步守卫：
npm run check:docs-sync
CI 也会在.github/workflows/ci.yml中运行该检查。

结合仓库现状，这条约定有两点值得精确化：

1. pre-commit 钩子已经在本地自动跑它。当前 .husky/pre-commit 实际执行的四道廉价门是：

sh scripts/check/check-git-identity.sh npx lint-staged node scripts/check/check-docs-sync.mjs npm run check:any-budget:t11 node scripts/check/check-tracked-artifacts.mjs

也就是说，只要正常走 git 提交流程（不用--no-verify），check-docs-sync.mjs在每次 commit 时就会自动执行；pre-push钩子则被有意做成了轻量的 PATH 检查（见 .husky/pre-push 注释：慢速门交由 CI 的test-unit等作业负责）。清单要求"开 PR 前本地手动跑一遍"的价值在于验证最终 PR 合并点的状态，尤其是手动改过文档或版本号之后。

2. CI 侧的执行位置。.github/workflows/ci.yml 中，check:docs-sync由专门的 docs-sync-strict 作业通过check:docs-all运行（见 ci.yml 第 165 行附近注释）。而check:docs-all在 package.json 中是一个伞形命令：

npm run check:docs-sync && npm run check:docs-frontmatter && npm run check:docs-counts \ && npm run check:env-doc-sync && npm run check:deprecated-versions \ && npm run check:doc-links && npm run check:fabricated-docs

即：版本/契约同步只是文档守卫家族的第一环，frontmatter、文档计数、.env.example↔ 文档 ↔ 代码三方环境契约、废弃版本、文档内链、伪造文档检测都会在 CI 中依次把关。

关联质量门速查

与发布核对直接相关的其他自动化门（均来自 package.json 实际脚本定义）：

命令	作用	实现
`npm run check:node-runtime`	Node 安全下限判定	scripts/check/check-supported-node-runtime.ts
`npm run check:pack-artifact`	npm 打包产物白名单校验	scripts/build/validate-pack-artifact.ts
`npm run check:docs-sync`	版本号/文档同步守卫	scripts/check/check-docs-sync.mjs
`npm run check:docs-all`	文档守卫伞形命令（7 个子检查）	package.json scripts
`npm run test:coverage`	覆盖率门：statements/lines/functions/branches 均 ≥ 60	c8`--check-coverage`四项 60
`npm run check:cycles`	循环依赖检查	scripts/check/check-cycles.mjs

其中覆盖率门与清单硬规则"Coverage must stay ≥ 60/60/60/60"一一对应，test:coverage脚本直接以--check-coverage --statements 60 --lines 60 --functions 60 --branches 60强制执行。

六、实操顺序与核对要点

把以上四板块落成一个可执行的发布前检查序列：

# 1. 版本号一致（package.json == openapi info.version == CHANGELOG 最新 semver 章节） grep -m1 '"version"' package.json grep -m2 'version:' docs/openapi.yaml | head -2 head -3 CHANGELOG.md # 2. Node 运行时下限 npm run check:node-runtime # 3. 构建独立包 + 产物残留校验 npm run build:cli npm run check:pack-artifact # 4. 文档同步守卫（commit 前钩子会自动跑，开 PR 前再手动确认一次） npm run check:docs-sync

核对要点：

三处版本号必须相等：package.json、docs/openapi.yaml的info.version、CHANGELOG.md最新 semver 章节；
文档路径以脚本为准：清单语言镜像中的路径可能滞后（如 OpenAPI 文件位置），check-docs-sync.mjs与pack-artifact-policy.ts才是行为权威；
不要把check:pack-artifact当作目视检查：它校验的是 npm pack dry-run 的完整文件清单对策略白名单的偏差，任何本地残留（备份目录、scratch 脚本、lock 文件）都会失败；
本地化文档同步是清单第五项的隐含前提：源文档大改后需更新docs/i18n/<locale>/镜像，否则 i18n 漂移检查（npm run i18n:check）会在打 tag 前报警。

七、小结

OmniRoute 的发布检查清单本质是一张"文档-代码-制品三方一致性"的核对表：版本与 Changelog 板块保证 semver 唯一事实源，API 文档板块保证契约同步，运行时文档板块保证架构/排障描述与 Node 安全下限、npm 产物白名单等硬约束对齐，自动化检查板块则把最容易遗忘的一致性项（check:docs-sync）前置到 pre-commit 钩子和 CI 作业中双重兜底。其工程价值不在条目数量，而在于每一项都能映射到一个可执行脚本（scripts/check/、scripts/build/）或一个真实文件契约（package.json、docs/openapi.yaml、CHANGELOG.md）——发布核对因此从"凭记忆打勾"变成了"跑命令看退出码"。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OmniRoute 发布检查清单：从版本号、OpenAPI 契约到 CI 同步守卫的完整发布流程