OmniRoute 发布检查清单实践：版本同步守卫、Node 运行时安全基线与 npm 产物校验-北京尧图网络

OmniRoute 发布检查清单实践版本同步守卫、Node 运行时安全基线与 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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute在发布新的 OmniRoute 版本打 tag / 推送 npm 包 / 构建独立部署包之前团队需要一套可重复、可自动校验的发布前检查流程。本文以仓库中的发布检查清单为核心骨架展开其中的四项发布关卡——版本号与 CHANGELOG 同步、OpenAPI 文档对齐、Node.js 运行时安全版本校验、npm 打包产物纯净性校验——并结合scripts/check/、scripts/build/下的守卫脚本源码说明每条检查项在代码层面究竟校验了什么、为什么这样设计。读完后你可以掌握如何在任何发布分支上运行npm run check:docs-sync等守卫命令理解其失败条件并在自己的发布流程中复用同样的文档-版本-产物一致性守卫模式。一、检查清单的定位与总体流程发布检查清单的原始定位只有一句话Use this checklist before tagging or publishing a new OmniRoute release. 即它是打 tag 或发布新版本前的强制前置动作。英文完整版本docs/ops/RELEASE_CHECKLIST.md进一步把它组织为版本与 Changelog → API 文档 → 运行时文档 → 自动化检查四段式流程每段都有明确的通过判据。需要说明的是仓库中存在多语言镜像副本例如本文参考的孟加拉语版本路径docs/i18n/bn/docs/ops/RELEASE_CHECKLIST.md。这些镜像不是手工维护的第二份文档而是被check:docs-sync守卫逐字节对照的镜像文件下文第四节会展开其校验逻辑。清单中列出的全部检查项及对应命令如下均可在仓库根目录直接执行检查项对应命令判据版本号与 CHANGELOG / OpenAPI 同步npm run check:docs-sync三处版本号一致、Unreleased 段在最前、i18n 镜像一致Node.js 运行时安全基线npm run check:node-runtime当前运行 Node/Bun 版本满足安全 floorCLI 独立包构建npm run build:cli产出可发布的 standalone 包结构npm 产物纯净性npm run check:pack-artifact无本地残留、无测试文件泄漏、MCP 闭包完整这些命令都注册在根 package.json 的scripts段build:cli: node --import tsx scripts/build/prepublish.ts, check:docs-sync: node scripts/check/check-docs-sync.mjs, check:node-runtime: node --import tsx scripts/check/check-supported-node-runtime.ts, check:pack-artifact: node --import tsx scripts/build/validate-pack-artifact.ts也就是说清单里的每一条命令背后都是一个真实的仓库脚本而不是约定俗成的口号——这为下文逐项剖析源码细节提供了基础。二、版本与 CHANGELOG三处版本号必须一致清单的 Version and Changelog 小节要求四件事在 release 分支上把package.json的版本号x.y.zbump 到位把CHANGELOG.md中## [Unreleased]下的发布说明移动到带日期的版本段## [x.y.z] — YYYY-MM-DD保持## [Unreleased]作为 changelog 的第一个版本段用于承接后续工作确保CHANGELOG.md中最新的 semver 段与package.json的版本相等。看当前仓库的 CHANGELOG.md 可以验证这一结构的实际形态文件以# Changelog开头紧接着## [Unreleased]其下按### ✨ New Features等分节罗列即将随下一版本发布的内容之后才是各历史版本段。这四条规则不是靠人眼保证的而是由 scripts/check/check-docs-sync.mjs 在每次提交/CI 中自动执行。其核心校验逻辑可以归纳为semver 合法性package.json的version必须匹配X.Y.Z或X.Y.Z-prerelease.N例如3.0.0-rc.1否则直接报package.json version is not valid semver失败OpenAPI 版本提取逐行扫描 docs/openapi.yaml定位info:块内部缩进两格的version:字段extractOpenApiVersion函数要求它严格等于package.json版本CHANGELOG 段序校验用正则/^##\s\[([^\]])\](?:\s[-—–].*)?$/gm提取所有## [版本]标题要求第一个段必须是UnreleasedCHANGELOG.md first section must be ## [Unreleased]过滤出的 semver 段中最新一个必须等于package.json版本否则报Latest changelog release (…) differs from package.json (…)。因此清单第 4 条最新 semver 段等于 package.json 版本实际上是一个机器可判定的断言npm run check:docs-sync全部通过时会输出[docs-sync] PASS - documentation version sync is consistent.任何一条不满足则以退出码 1 结束[docs-sync] FAIL - …。三、API 文档OpenAPI 版本对齐与示例校验清单的 API Docs 小节要求更新docs/reference/openapi.yaml中的info.version使其等于package.json版本如果 API 契约有变化验证端点示例仍然有效。从源码结构看守卫脚本实际读取的路径是仓库根目录下的 docs/openapi.yamldocs/ops/RELEASE_CHECKLIST.md 的 Documentation 一节同样把docs/openapi.yaml与package.json版本的一致性列为文档检查项之一并提到若新功能带有 API需同步更新docs/reference/API_REFERENCE.md与docs/openapi.yaml。两处版本必须同步这正是check:docs-sync中OpenAPI version (x) differs from package.json (y)这条失败信息的来源。对验证端点示例这一步清单给出的判据是API 契约变更时才需要人工核对仓库中 OpenAPI 规范文件同时存在于docs/openapi.yaml与 public/openapi.yaml后者面向服务暴露契约变更时应两者一并检查。四、运行时文档架构漂移复查与 Node 安全版本基线Runtime Docs 小节包含五步其中第 3、4 步对应两个可执行守卫复查 docs/architecture/ARCHITECTURE.md 是否存在存储/运行时描述漂移复查 docs/guides/TROUBLESHOOTING.md 是否存在环境变量与运维描述漂移验证发布/运行使用的 Node.js 版本仍满足受支持的安全 floor运行npm run check:node-runtime构建 standalone 包后验证 npm 产物npm run build:clinpm run check:pack-artifact确认产物中不含app.__qa_backup、scripts/scratch、package-lock.json等本地残留如果源文档有较大变化同步更新本地化文档。4.1 check:node-runtime 的底层实现scripts/check/check-supported-node-runtime.ts 本身只有二十几行它调用共享模块 src/shared/utils/nodeRuntimeSupport.ts 中的getNodeRuntimeSupport()若nodeCompatible为false则打印警告信息含受支持区间与推荐版本并以退出码 1 结束若运行在 Bun 上则直接判定为兼容supported-bun并输出 Bun x.y.z (…) satisfies OmniRoute secure runtime policy.。真正的策略定义在src/shared/utils/nodeRuntimeSupport.ts。该模块按 major 版本维护一张安全 floor 表SECURE_NODE_LINESmajor安全 floorpatched minimum2222.22.22424.0.02525.0.02626.0.0判定逻辑是解析当前process.versions.node找到对应 major 的 floor比较 floor才算兼容major ≥ 27 记为unreleased-major不支持的未发布主线。失败时getNodeRuntimeWarning()会区分两种提示below the patched minimum v22.22.2 for this LTS line低于该 LTS 线的已修补下限与outside the supported LTS lines不在受支持主线内。关于版本区间这里需要指出一个文档与代码的时点差异docs/ops/RELEASE_CHECKLIST.md 中 Runtime Docs 小节写的是20.20.2 21或22.22.2 23而当前仓库的 package.jsonengines字段为22.22.2 23 || 24.0.0 27与nodeRuntimeSupport.ts中的SUPPORTED_NODE_RANGE22.22.2 23 || 24.0.0 27及推荐版本24.14.1完全对齐。清单文档中的旧写法反映的是较早时点的策略以当前仓库实际内容为准Node.js 22.22.222.x LTS、24.0.024.x LTS、25.0.0 或 26.0.0 均可通过守卫Bun 1.1 亦被接受。这个模块的注释也说明了它被刻意写成纯 ESM以便bin/运行时入口、src/路由处理器与scripts/仓库脚本三方复用同一份策略避免检查脚本和运行时守卫各自为政产生漂移。4.2 check:pack-artifact产物纯净性的白名单机制npm run build:cli由 scripts/build/prepublish.ts 执行产出发布用的独立包随后npm run check:pack-artifact由 scripts/build/validate-pack-artifact.ts 执行。它的实现方式是跑一次npm pack --dry-run --json --ignore-scripts拿到将要打入 tarball 的完整文件列表然后做四类断言意外文件黑名单/白名单差集findUnexpectedArtifactPaths依据pack-artifact-policy.ts中的PACK_ARTIFACT_ALLOWED_EXACT_PATHS精确路径白名单与PACK_ARTIFACT_ALLOWED_PATH_PREFIXES前缀白名单计算差集——任何不在白名单内的文件都会让检查失败。清单中点名的app.__qa_backup、scripts/scratch、package-lock.json就属于典型的不应出现在 npm 产物里的本地残留正是这条断言拦截的对象缺失必需文件findMissingArtifactPaths对照PACK_ARTIFACT_REQUIRED_PATHS确保运行必需文件如dist/下的运行时文件真的在产物里若dist/缺失脚本会先自动补跑npm run build:cli再校验测试文件泄漏findLeakedTestArtifactPaths专门禁止*.test.*/__tests__泄漏进产物——宽泛的files前缀如open-sse/、src/lib/容易把测试文件一起带出去所以必须在真实 pack 列表上显式禁止MCP 闭包完整性MCP 服务器从发布的 TypeScript 源码直接运行computeMcpClosure会算出所有可达源文件并确认它们全部被打进产物否则发布后--mcp模式会 404。脚本还支持--policy-only快路径跳过构建与必需文件检查只对照真实 pack 列表做源侧策略检查用于在 PR 快车道上廉价地捕获源侧回归。完整模式下还会做构建溯源provenance校验读取dist/BUILD_SHA通过 git 祖先探测确认该构建确实来自发布线OMNIROUTE_RELEASE_REF默认origin/main杜绝用 feature 分支的旧构建冒充发布产物的事故。五、自动化检查docs-sync 守卫与 CI 集成清单最后一节 Automated Check 要求在开 PR 前本地先跑npm run check:docs-sync并说明 CI 也会运行该检查。核对 scripts/check/check-docs-sync.mjs 的完整检查面可以发现它实际比三个版本号一致覆盖得更多package.json版本必须是合法 semverdocs/openapi.yaml的info.version必须与package.json相等CHANGELOG.md结构首段必须是## [Unreleased]且最新 semver 段必须等于package.json版本i18n 镜像一致性llm.txt 的各语言镜像docs/i18n/locale/llm.txt必须是逐字节精确拷贝去首行标题、归一化换行后比较——因为它是面向 LLM 的机器可读文件不允许翻译各语言CHANGELOG.md镜像则采用宽松校验必须包含根 CHANGELOG 的所有## [X.Y.Z]版本段允许标题被翻译成各语言如 Security → Segurança且正文行数与源文档偏差不得超过 25%防止翻译版本严重过期或缺失。镜像文件本身还必须具备 i18n 镜像分隔线---语言导航条与正文之间的分隔符反回归断言已被取代的旧文档路径如docs/CLI-TOOLS.md→ 现以docs/reference/CLI-TOOLS.md为唯一事实来源若复活即失败。任何一项失败都会打印[docs-sync] FAIL - …并以退出码 1 结束全部通过则输出[docs-sync] PASS - documentation version sync is consistent.。在 CI 侧该守卫由 .github/workflows/ci.yml 中的docs-sync-strict作业执行作业内运行的是超集命令npm run check:docs-all覆盖 docs-sync docs-counts env-doc-sync deprecated-versions doc-links并且被下游聚合作业显式依赖needs列表中可见docs-sync-strict其结果会写入 GitHub Step Summary。清单原文将其描述为CI 在 ci.yml 的 lint 作业中运行该检查属于同一守卫在不同作业编排中的挂载点描述从当前工作流文件看check:docs-sync的严格形态由docs-sync-strict专职作业承担。六、可复制的发布前操作序列把清单与守卫脚本串起来一个可复制的发布前检查序列如下在仓库根目录执行# 1. bump package.json 版本把 CHANGELOG.md 的 [Unreleased] 内容 # 移到 ## [x.y.z] — YYYY-MM-DD 段并保留 Unreleased 段在最前 # 2. 同步 docs/openapi.yaml 的 info.version 为同一版本号 # 3. 文档-版本一致性守卫本地先跑CI 也会跑 npm run check:docs-sync # 4. Node.js 运行时安全基线要求 22.22.2 / 24.0.0 / 25 / 26 或 Bun 1.1 npm run check:node-runtime # 5. 构建 standalone 包并校验 npm 产物 npm run build:cli npm run check:pack-artifact # 确认产物无 app.__qa_backup / scripts/scratch / package-lock.json 等残留若第 3 步失败按[docs-sync] FAIL - …的具体信息定位版本号不一致对齐package.json、CHANGELOG.md、docs/openapi.yaml三处、CHANGELOG 首段不是Unreleased、或某个docs/i18n/locale/镜像与源文档漂移更新对应镜像或重跑翻译同步流程若第 4 步失败按提示切换 Node 版本推荐 24.14.1或升级至各 LTS 线的 patched minimum 之上若第 5 步失败按输出的意外/缺失文件清单收紧package.json的files配置或清理本地残留。七、这套守卫模式的设计要点从仓库实现可以提炼出三点值得借鉴的设计单一事实来源机器断言版本号只允许以package.json为准OpenAPI 与 CHANGELOG 的一致性不做人工承诺而是由check-docs-sync.mjs在每个提交钩子与 CI 上断言失败即阻断共享策略模块Node 运行时安全基线集中在src/shared/utils/nodeRuntimeSupport.ts被 CLI 入口、路由处理器、检查脚本三方复用避免检查脚本认为支持、运行时却拒绝的漂移白名单化的产物审计npm 产物校验以精确路径前缀白名单必需文件泄漏黑名单溯源指纹组合判定把产物里能出现什么变成可静态审计的清单而非依赖npm pack的默认忽略规则。以上命令与判据均以当前仓库的 package.json、scripts/check/check-docs-sync.mjs、src/shared/utils/nodeRuntimeSupport.ts、scripts/build/validate-pack-artifact.ts 为准完整的发布前置项质量门、测试矩阵、Electron、部署与回滚流程可继续参阅 docs/ops/RELEASE_CHECKLIST.md。【免费下载链接】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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OmniRoute 发布检查清单实践：版本同步守卫、Node 运行时安全基线与 npm 产物校验

相关推荐

毕业第一份工作是店群运营：00后的验证码启蒙课

ToolJet Database Editor：可视化建表、CSV 批量导入与数据过滤的完整实践指南

server status

更多资讯

MATLAB中神经网络代理模型与遗传算法混合优化

极限词自查：批量上架前的最后一道闸

CANN/ge图引擎导出API

云优CMS部署智能监控官网：静态生成+前端渲染实战指南

浏览器指纹伪装原理拆解：从Canvas到WebRTC的反检测技术

diagram-design：现代前端可视化工程的核心能力

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？