OmniRoute 发布检查清单实战指南从版本号提升到 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本指南以 docs/i18n/de/docs/ops/RELEASE_CHECKLIST.md德语发行版发布清单为骨架并以其英文主文档 docs/ops/RELEASE_CHECKLIST.md 及仓库源码为事实依据完整讲解 OmniRoute 在打 tag、发布 npm 包之前必须执行的版本管理、API 文档同步、运行时校验与自动化检查流程。读完本文你将掌握 OmniRoute 发布体系中的版本号与 CHANGELOG 维护规范、OpenAPI 契约对齐要求、Node.js 运行时安全下限校验、npm 发布产物洁净度校验以及贯穿本地与 CI 的 docs-sync 门禁能据此可靠地完成一次从分支合并到发布的完整操作。一、发布前置理解 OmniRoute 的发布哲学OmniRoute 是一个 MIT 协议开源的多提供商 AI 网关统一端点接入数百个提供商与上千模型支持配额感知自动回退、RTK Caveman 上下文压缩、MCP/A2A、桌面端与 PWA。这样一个面向生产流量、被 Claude Code、Codex、Cursor、OpenCode、Cline 与 Copilot 等客户端接入的网关项目其每一次发布都同时影响npm 包、Docker 镜像、Electron 桌面端、文档站与多语言内容。因此它的发布检查清单并不是一份可选项清单而是一组可执行的质量门禁版本一致性、文档契约、运行时兼容、打包产物洁净度、自动化同步校验。德语版清单即本指南的关联文档以精炼的四段流程概括了这一体系Version and Changelog— 版本号与变更日志维护API Docs— OpenAPI 文档契约对齐Runtime Docs— 运行时文档与 Node.js 版本校验、发布产物校验Automated Check— 本地与 CI 的check:docs-sync同步门禁。下文逐节展开并结合仓库源码说明每一条背后的实现依据。二、版本与 Changelog单一事实来源德语版清单首先要求在 release 分支提升package.json的版本号x.y.z将CHANGELOG.md中## [Unreleased]的发布说明移入带日期的段落## [x.y.z] — YYYY-MM-DD保留## [Unreleased]作为 CHANGELOG 第一个段落用于承载后续工作确保CHANGELOG.md中最新的 semver 段落与package.json版本号一致。2.1 版本号的三处同步点结合英文主清单版本号不是只改一处而是需要保持多处一致根目录 package.json 的version字段当前仓库为3.8.51桌面端 electron/package.json 的版本npm run version-bump技能会同时提升两处docs/openapi.yaml 中info.version经确认当前为3.8.51与根package.json完全一致。实现提示主清单推荐直接运行/version-bump-cc patch|minor|majorClaude Code 技能它会自动完成package.json、electron/package.json的提升、从最近一次 tag 以来的 git commit 重新生成CHANGELOG.md、并更新 README 徽章。手动操作时务必自行核对上述三处。2.2 变更日志的纪律## [Unreleased]必须始终保持在文件头部作为下一个版本的积攒区发布时把已就绪的条目移动为带日期的## [x.y.z] — YYYY-MM-DD段落最终校验最新 semver 段落必须等于package.json版本这是check:docs-sync等门禁之外的硬性人工核对项。仓库还通过 changelog.d/ 目录管理变更碎片features / fixes / maintenance 三分类并由 scripts/release/aggregate-changelog.mjs 与changelog:aggregate命令聚合可有效降低手工整理 CHANGELOG 的遗漏风险。三、API 文档OpenAPI 契约与版本对齐德语版清单的 API Docs 部分要求更新docs/reference/openapi.yaml其中info.version必须等于package.json版本若 API 契约发生变化校验各 endpoint 的示例。3.1 实际文件路径仓库中 OpenAPI 文件的实际路径为 docs/openapi.yaml根级另有 public/openapi.yaml。发布前需要确认其info.version与 package.json 的version一致——这正是德语清单API 文档版本等于包版本这条规则的落点。3.2 相关的自动化校验围绕 OpenAPI 契约仓库在 package.json 中提供了多条脚本用于支撑校验 endpoint 示例的要求npm run check:openapi-coverage # OpenAPI 覆盖率检查 npm run check:openapi-security-tiers # 安全分级检查如 public creds 分层 npm run check:openapi-breaking # 破坏性变更检测防止未打 BREAKING 标记的契约变化 npm run check:openapi-routes # OpenAPI 路由与实现一致性 npm run check:api-docs-refs # API 文档引用完整性其中check:openapi-breaking尤其重要它把API 契约是否发生破坏性变化变成机器可判定的检查避免发布时才发现feat(api)!: drop /v0这类变更没有同步到文档与版本号。四、运行时文档与 Node.js 运行时安全下限德语版清单 Runtime Docs 部分要求逐条核对审阅docs/architecture/ARCHITECTURE.md排查存储/运行时漂移审阅docs/guides/TROUBLESHOOTING.md排查环境变量与运维漂移确认发布/运行所用的 Node.js 版本仍满足受支持的安全下限20.20.2 21或22.22.2 23运行npm run check:node-runtime构建独立包后校验 npm 发布产物npm run build:clinpm run check:pack-artifact确认无app.__qa_backup、scripts/scratch、package-lock.json或其他本地残留若源文档发生显著变化更新本地化文档。4.1 Node.js 运行时下限的实现真相德语清单给出的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;也就是说当前受支持的安全下限是Node.js 22.22.222.x LTS、24.0.024.x LTS、25.x、26.x且该常量与根 package.json 中engines: { node: 22.22.2 23 || 24.0.0 27 }保持一致——这正是清单要求校验SUPPORTED_NODE_RANGE与engines对齐的落点。同时该模块对 Bun 运行时Bun ≥ 1.1.0也有独立的支持判定reason: supported-bun。校验命令npm run check:node-runtime在 package.json 中定义为node --import tsx scripts/check/check-supported-node-runtime.ts它会调用上述工具函数将低于安全下限的版本判定为below-security-floor并输出警告见getNodeRuntimeWarning的实现src/shared/utils/nodeRuntimeSupport.ts。4.2 发布产物洁净度校验npm run check:pack-artifact对应 package.json 中的node --import tsx scripts/build/validate-pack-artifact.ts并已被挂入prepublishOnly生命周期npm run build:cli-api npm run build:cli npm run check:pack-artifact即每次npm publish前自动执行。它检查打包产物中是否混入app.__qa_backupQA 备份目录scripts/scratch临时脚本目录package-lock.json独立发布包不应携带锁文件其他本地残留文件。同时根 package.json 的files白名单显式排除了!**/__tests__/**、!**/*.test.*、!**/*.spec.*、!**/*.nft.json等从来源上保证发布包只包含运行所需代码。五、构建布局dist 与 .build 的边界英文主清单特别强调仓库使用三个互不混淆的输出目录这一点对于校验发布产物至关重要目录用途是否纳入版本管理src/应用源码TypeScript / TSX是.build/构建中间产物next build输出distDir否gitignoreddist/可发布的 npm 包由assembleStandalone组装否gitignored发布时应使用单条命令完成干净重建 哨兵写入npm run build:release # └─ rm -rf .build dist 清空 # └─ next build → .build/next/ 中间产物 # └─ assembleStandalone standalone static public natives → dist/ # └─ writes dist/BUILD_SHA HEAD 哨兵对应 package.json 中的实现为build:release: rm -rf .build dist OMNIROUTE_BUILD_SHA$(git rev-parse --short HEAD) npm run build npm run build:cli node scripts/build/write-build-sha.mjs不要用npm run build之后再单独跑npm run build:cli来部署——这会缺少干净的中间产物清理与dist/BUILD_SHA哨兵。部署前必须确认dist/BUILD_SHA等于git rev-parse --short HEAD确保线上二进制与源码 HEAD 一一对应。另外注意运维细节远程 VPS 的应用目录仍是/usr/lib/node_modules/omniroute/app/只有仓库内构建输出从app/移到了dist/部署技能会通过 rsync 把dist/内容同步进远程app/目录。六、自动化检查docs-sync 同步门禁德语版清单的最后一部分是 Automated Check在开 PR 之前本地运行npm run check:docs-syncCIlint job也会执行同样的检查。6.1 该命令在仓库中的位置package.json 中定义为check:docs-sync: node scripts/check/check-docs-sync.mjs它校验的是文档同步契约仓库的各类文档含 docs/i18n/ 下的多语言副本必须与源文档保持同步防止发布文档漂移——例如德语版清单这类翻译副本在源文档更新后未同步。6.2 更广的文档门禁体系check:docs-sync只是整个文档门禁体系的一员英文主清单要求发布前整体通过npm run check:docs-all该 umbrella 命令见 package.json 的check:docs-all串联了check:docs-all: 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-docscheck:env-doc-sync代码 ↔.env.example↔docs/reference/ENVIRONMENT.md的环境变量契约check:doc-links文档内部 markdown 相对链接无损坏这正是本文所有仓库链接均从根目录出发的原因check:docs-counts各语言文档数量一致check:fabricated-docs--strict防止出现虚构的文档内容。6.3 Husky 钩子把门禁焊进 git 操作仓库的 .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也就是说check:docs-sync在本地每次 commit 时都会被强制运行而不是等到 PR 阶段才被 CI 拦截。.husky/pre-push 则有意保持轻量仅做 PATH/npm 合理性检查把较慢的test:unit与 typecheck 留给 CI 的test-unit任务避免每次 push 都本地跑全量单测。硬性规则钩子失败必须修复根因严禁用git commit --no-verify/git push --no-verify绕过。七、质量门禁与测试体系速查德语版清单虽未展开但英文主清单将发布前质量明确为一组可执行命令。发布分支上建议逐项核对均为 package.json 中已定义的脚本npm run lint # ESLint 0 errors npm run typecheck:core # 核心类型检查 npm run typecheck:noimplicit:core # 严格 noImplicit 检查 npm run check:cycles # 无循环依赖 npm run test:unit # 单元测试 npm run test:vitest # MCP server / autoCombo / cache npm run test:coverage # 覆盖率门禁 60/60/60/60statements/lines/functions/branches npm run test:combo:matrix # 19 种公开路由策略的确定性选择矩阵 npm run test:e2e # UI 变更时 npm run test:protocols:e2e # MCP/A2A 变更时其中test:coverage在 package.json 中通过 c8 的--check-coverage --statements 60 --lines 60 --functions 60 --branches 60强制实现 60/60/60/60 门禁且这是硬规则之一覆盖率不得低于该阈值。八、打 tag、发布与回滚8.1 生成发布推荐直接使用/generate-release-ccClaude Code 技能它会创建 tagvX.Y.Z并推送 tag 与分支打开 GitHub Release 并填充 changelog 正文附加已构建的 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-tag8.2 部署与上线冒烟部署技能使用轻量 rsync 流程不做npm pack、不做npm i -g/deploy-vps-local-cc— 本地 VPS192.168.0.15/deploy-vps-akamai-cc— Akamai VPS69.164.221.35/deploy-vps-both-cc— 两者同时部署。部署后的冒烟检查包括打开/dashboard/health确认版本字符串与本次发布一致对已知提供商发起一次/v1/chat/completions请求验证/api/monitoring/health返回CLOSED熔断器状态确认 MCP 传输可用/mcpHTTP、/mcp-sseSSE。8.3 回滚预案若发布出现严重问题按优先级执行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.(Z1)立即在 GitHub Discussions 与 Discord 同步公告。8.4 不可逾越的硬规则永不直接向main提交永不向main或release/*分支git push --force永不跳过 Husky 钩子--no-verify永不提交密钥、凭据或.env文件覆盖率必须保持 ≥60/60/60/60修改src/、open-sse/、electron/或bin/的生产代码时必须同时新增或更新测试。九、总结把发布清单变成可执行门禁德语版 docs/i18n/de/docs/ops/RELEASE_CHECKLIST.md 用四段话概括了 OmniRoute 发布的核心纪律而它在仓库中的落地远比表面看起来扎实版本与 Changelogpackage.json、electron/package.json、docs/openapi.yaml三处一致## [Unreleased]常驻头部API 文档info.version与包版本对齐check:openapi-breaking等脚本守护契约演进运行时文档Node.js 安全下限由 src/shared/utils/nodeRuntimeSupport.ts 统一裁决当前22.22.2 23 || 24.0.0 27check:node-runtime、check:pack-artifact分别守护运行时与产物洁净度自动化检查check:docs-sync通过 .husky/pre-commit 焊进每次 commitCI lint job 二次兜底。对维护者而言一次合规发布的最小可执行路径就是版本提升 → 本地npm run checkcheck:docs-all→npm run build:release并核对dist/BUILD_SHA→ 校验check:pack-artifact→ 生成 tag 与 Release → 部署并冒烟 → 记录发布证据。每一步都有仓库内可执行的命令与可核对的产物这也正是这份清单能长期被多语言文档保持一致的根本原因——它是可以被机器验证的流程而不只是一页纸上的勾选框。【免费下载链接】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），仅供参考