十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

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, RTKCaveman 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 在开始之前先保持分支常绿能显著减少发布日期的返工。下面按挪威语版清单的四个板块逐一展开并在每个板块中给出仓库内的实现证据。二、版本与 ChangelogVersion 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.tsexport 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_LINESNode 22 必须 ≥ 22.22.224/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_PATHSdist/前缀项是否齐备缺失则自动补跑npm run build:clidry-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-syncCI 也会在.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-verifycheck-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-runtimeNode 安全下限判定scripts/check/check-supported-node-runtime.tsnpm run check:pack-artifactnpm 打包产物白名单校验scripts/build/validate-pack-artifact.tsnpm run check:docs-sync版本号/文档同步守卫scripts/check/check-docs-sync.mjsnpm run check:docs-all文档守卫伞形命令7 个子检查package.json scriptsnpm run test:coverage覆盖率门statements/lines/functions/branches 均 ≥ 60c8--check-coverage四项 60npm 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——发布核对因此从凭记忆打勾变成了跑命令看退出码。【免费下载链接】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),仅供参考
返回列表