OmniRoute 发布检查清单Release Checklist从版本号到发布工件的全流程质量门禁指南【免费下载链接】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 开源仓库发布流程的完整实操指南以 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md荷兰语翻译版及其英文源文档 docs/ops/RELEASE_CHECKLIST.md 为主体结合仓库内真实脚本、Husky Hooks、CI 配置与源码常量展开。读完本文你将掌握 OmniRoute 在打 tag 或发布新版本前必须完成的全部检查项版本号与 CHANGELOG 同步、API/运行时文档一致性、Node.js 安全版本合规、npm 发布工件验证、自动化文档同步检查以及一套可直接复用的发布命令序列。一、检查清单的定位与触发时机OmniRoute 的发布检查清单Release Checklist是仓库中负责打 tag 或发布新版本之前的统一校验流程。英文源文档明确说明在打 tagtagging或发布publishing一个新的 OmniRoute 版本之前必须执行本清单Use this checklist before tagging or publishing a new OmniRoute release.。当前仓库根目录 package.json 版本为3.8.51electron/package.json 版本同为3.8.51docs/openapi.yaml 的info.version亦为3.8.51三者保持一致这正是本清单版本一致性规则落地的直接证据。整体发布流程可以用一段 TL;DR 概括源自英文源文档# 1. 升级版本号 生成 CHANGELOGClaude Code skill /version-bump-cc patch # 或 minor / major # 2. 本地运行质量门禁 npm run check # lint 测试 npm run test:coverage # 完整覆盖率门禁60/60/60/60 # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成发布skill /generate-release-cc # 5. 部署skill /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 采集发布证据skill /capture-release-evidences-cc二、版本号与变更日志Version and Changelog英文源文档中Version Changelog一节列出了四条硬性操作翻译版 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md 完整保留了这四条升级package.json版本号x.y.z且必须在 release 分支上执行将 CHANGELOG.md 中## [Unreleased]的内容移动到带日期的版本小节格式为## [x.y.z] — YYYY-MM-DD保留## [Unreleased]作为变更日志第一节供后续迭代继续累积确保 CHANGELOG.md 中最新的 semver 小节等于package.json版本号。当前仓库的 CHANGELOG.md 以## [Unreleased]开头其下累积了大量未发布的新功能条目如feat(dashboard)、feat(sse)等完全符合Unreleased 作为第一节的约定。在 OmniRoute 的实际流程中版本号升级通过 Claude Code skill/version-bump-cc patch|minor|major完成它会同时升级根目录 package.json 与 electron/package.json两个版本必须相等这是桌面端发布的前提根据上一次 tag 之后的 git 提交重新生成 CHANGELOG.md更新 README 徽章。完成自动化后还需要人工审阅 CHANGELOG.md 并清理提交信息因为 git 提交信息质量参差。三、API 文档同步API Docs发布前需要更新 docs/openapi.yaml其硬性约束是info.version必须等于package.json版本号。我们可以在仓库中验证这一约束当前docs/openapi.yaml顶部info.version为3.8.51与根package.json一致。如果 API 契约发生了变化新增端点、修改请求/响应结构还应**验证端点示例endpoint examples**的有效性。与之配套的还有 OpenAPI 专项检查脚本见 package.json 中scripts区check:openapi-coverageOpenAPI 覆盖度、check:openapi-security-tiers安全分级、check:openapi-routes路由一致、check:openapi-breaking破坏性变更检测等这些都在 CI 中强制执行。若新功能有 API则 docs/reference/API_REFERENCE.md 与docs/openapi.yaml必须同步更新英文源文档 Documentation 一节明确列出。四、运行时文档与 Node.js 安全版本合规Runtime Docs4.1 检查哪些文档发布前需人工复核以下两份运行时文档是否存在漂移docs/architecture/ARCHITECTURE.md检查存储与运行时设计是否与实际实现脱节storage/runtime driftdocs/guides/TROUBLESHOOTING.md检查环境变量与运维行为描述是否漂移。4.2 Node.js 安全版本下限这是运行时检查中最容易出问题的一项。发布时使用的 Node.js 版本必须满足仓库的安全版本下限secure floor。仓库中实际定义于 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;即当前支持Node.js 22.22.222.x LTS、24.0.024.x LTS、25.0.0、26.0.0推荐版本为 24.14.1同时该模块兼容 BunBun 1.1.0也会被判定为 supported。该范围与根 package.json 的engines字段保持一致。注意荷兰语翻译版中记录的历史范围20.20.2 21/22.22.2 23已随版本演进被更新请以 src/shared/utils/nodeRuntimeSupport.ts 中当前生效的SUPPORTED_NODE_RANGE为准22.x / 24.x / 25.x / 26.x。验证命令源码中确实存在对应脚本npm run check:node-runtime该命令执行scripts/check/check-supported-node-runtime.ts对当前运行环境判定nodeCompatible并给出supported/below-security-floor/unsupported-major/unreleased-major等原因低于安全补丁下限时会提示 below the patched minimum。4.3 npm 发布工件验证在构建独立发布包之后必须验证 npm 发布产物的干净度npm run build:cli # 执行 scripts/build/prepublish.ts npm run check:pack-artifactcheck:pack-artifact对应scripts/build/validate-pack-artifact.ts会检查发布包中是否残留以下本地内容app.__qa_backupQA 备份目录scripts/scratch临时草稿脚本package-lock.json发布产物不应携带 lockfile其他本地残留物。仓库还提供了更强的工件冒烟验证check:pack-bootscripts/check/check-pack-boot.mjs它将打包好的 tarball 装入干净容器并真实启动用于验证发布物可以正常 boot。五、自动化同步检查Automated Check / docs-sync荷兰语版文档同时也是英文源文档的收尾强调在开 PR 之前必须在本地运行文档同步守卫npm run check:docs-syncCI 也会在 .github/workflows/ci.yml 的 lint job实际为docs-sync-strict作业中运行该检查。我们在仓库 .github/workflows/ci.yml 第 420 行可以看到docs-sync-strict:作业定义其通过check:docs-all执行严格同步校验。英文源文档把文档检查扩展为一张伞形清单npm run check:docs-sync— 源码文档 ↔ i18n 文档同步pre-commit 自动运行npm run check:docs-all— 伞形总检包含 docs-sync docs-counts env-doc-sync deprecated-versions doc-links fabricated-docs 等package.jsonscripts区可查证npm run check:env-doc-sync— 代码 ↔ .env.example ↔ docs/reference/ENVIRONMENT.md 三方环境变量契约完整npm run check:doc-links— 内部 Markdown 相对引用无断裂。如果.env.example有改动docs/reference/ENVIRONMENT.md 必须同步更新若新功能带 UIdocs/guides/USER_GUIDE.md 需提及若是破坏性变更docs/guides/TROUBLESHOOTING.md 需有迁移说明。六、i18n 多语言文档同步由于仓库维护了 50 语言的文档镜像荷兰语版即其中之一位于 docs/i18n/nl/发布前对翻译状态有一组专门检查npm run i18n:check # 翻译漂移检查.i18n-state.json 与源文档同步 npm run i18n:check-ui-coverage # 每个 UI locale 达到 80% 覆盖下限 npm run i18n:sync-ui:dry # 报告 42 个 locale 的缺失 key如果英文源文档发生显著变化需要在打 tag 前运行npm run i18n:run需要.env中配置OMNIROUTE_TRANSLATION_API_KEY触发翻译轻微翻译缺口可以推迟到下一版本但要记录在 CHANGELOG 中。对应脚本位于 scripts/i18n/如check-translation-drift.mjs、check-ui-keys-coverage.mjs、sync-ui-keys.mjs。七、代码质量门禁与测试矩阵Code Quality Testing英文源文档为发布定义了完整的质量门禁这里列出与荷兰语版版本与变更日志直接衔接的核心部分7.1 代码质量npm run lint # 0 errorwarning 属存量问题 npm run typecheck:core # 干净 npm run typecheck:noimplicit:core # 严格模式干净 npm run check:cycles # 无循环依赖 npm run check:any-budget:t11 # 预算内 npm run check:route-validation:t06 npm run check:node-runtime # 运行时版本合规见上文7.2 测试矩阵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:integration # 改动涉及 DB / handlers 时 npm run test:combo:matrix # 19 种公开路由策略的确定性选择矩阵 npm run test:e2e # UI 改动时 npm run test:protocols:e2e # MCP/A2A 改动时 npm run test:ecosystem覆盖率 60/60/60/60 是硬性下限英文源文档Hard Rules一节再次强调Coverage must stay ≥60/60/60/60。此外combo 策略矩阵test:combo:matrix用于证明 19 种公开路由策略的选择决策是确定性的凡涉及 combo 路由、策略解析或回退逻辑的改动必须运行。7.3 Husky Hooks不可跳过仓库的 .husky/ 目录包含pre-commit与pre-push两个钩子英文源文档强调绝不能用--no-verify绕过。实际钩子内容已从仓库验证为pre-commitnpx lint-stagednode scripts/check/check-docs-sync.mjsnpm run check:any-budget:t11外加 git 身份检查与 tracked-artifacts 检查pre-push刻意保持轻量任何预算 已跟踪工件已在 pre-commit 执行主要作为 PATH/npm 健全性提醒push release 分支前应手动运行npm run test:unit。7.4 Conventional Commits 约束所有进入发布分支的提交必须遵循type(scope): subject格式。合法类型feat、fix、refactor、docs、test、chore、perf、style、ci合法 scope 覆盖db、sse、oauth、dashboard、api、cli、docker、mcp、a2a、compression、auto-combo、resilience、providers、executors、translator、domain、authz等。破坏性变更需追加BREAKING CHANGE:footer 或在 scope 后加!如feat(api)!: drop /v0。八、构建布局与单构建流Build Layout仓库使用三个职责完全不同的输出目录发布时必须区分清楚目录用途是否入库src/应用源码TypeScript / TSX是.build/构建中间产物next build输出distDir否gitignoreddist/可发布的 npm bundle由assembleStandalone组装否gitignored运维注意远端 VPS 的镜像目录始终是/usr/lib/node_modules/omniroute/app/。只有仓库内的构建输出位置从app/移到了dist/部署 skill 会把dist/内容 rsync 到远端app/目录VPS 路径无需改动。发布必须使用单命令构建流而不是npm run build后再单独跑npm run build:clinpm run build:release └─ rm -rf .build dist 清理 └─ next build → .build/next/ 中间产物 └─ assembleStandalone 拷贝 standalone static public natives 到 dist/ └─ 写入 dist/BUILD_SHA HEAD 哨兵文件对应脚本在 package.json 中可查证build:release会先执行rm -rf .build dist注入OMNIROUTE_BUILD_SHA$(git rev-parse --short HEAD)然后依次构建并调用scripts/build/write-build-sha.mjs写入哨兵。发布前的工件验证断言dist/BUILD_SHAgit rev-parse --short HEADnpm run check:pack-artifact干净无本地残留物dist/server.js存在。九、打标签与发布Tagging Release推荐使用/generate-release-ccClaude Code skill它会创建 tagvX.Y.Z推送 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-tag9.1 npm 发布Trusted PublishingOIDC与 staged 发布自 v3.8.51 起npm-publish.yml默认通过npm Trusted PublishingOIDC发布stage-npm作业用 GitHub 的 id-token 换取当次运行的短期 npm 凭证——仓库 secrets 中不再存长效 npm token、无 2FA 提示、附带 provenance来源证明。这既恢复了 v3.8.48 之前的全自动流程又保留了 WS1.3 保证泄漏的 token 无法单独发布因为根本没有 token。一次性配置ownernpmjs.com → 包omniroute→ Settings →Trusted Publisher→ GitHubowner / repo / workflownpm-publish.yml。配置缺失时自动发布会以ENEEDAUTH失败此时改用publish_modestaged或direct重新调度。Staged 发布按需publish_modestaged将人工 2FA 门槛移动到证据之后npm stage list omniroute找到 stage id验证 staged 字节推荐npm stage download id装入临时 prefix 并 bootCI 中check:pack-boot自动化同样的 pack→install→boot 判定npm stage approve id— 2FA 提示即发布npm stage reject id丢弃发布后验证器WS1.4会在干净容器中从公共 registry 安装已发布版本并 boot。紧急回退workflow_dispatch传publish_modedirect恢复传统即时npm publish仅当 staging 自身异常时使用并记录原因。Docker Hublatest规则docker-publish工作流在每个稳定 SemVer 发布时必须同时打X.Y.Z标签当should-promote-latest.sh判定这是最高稳定版本时还要用同一 digest打:latest。发布后 Hub 上latest的 digest 必须等于新 SemVer 的 digest。Compose 快速上手使用:latestGitOps 应坚持锁定X.Y.Z。详见 docs/guides/DOCKER_GUIDE.md。十、部署与冒烟测试Deploy Smoke部署采用轻量 rsync 流程——不执行npm pack不执行npm i -g。按目标选择部署 skill/deploy-vps-local-cc— 本地 VPS192.168.0.15/deploy-vps-akamai-cc— Akamai VPS/deploy-vps-both-cc— 两者同时。部署前必须确认dist/BUILD_SHAgit 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。十一、回滚预案与硬性规则Rollback Hard Rules11.1 回滚步骤发布出现严重问题时按顺序执行gh release edit vX.Y.Z --prerelease标记为 not latest若用户尚未采用git tag -d vX.Y.Z git push --delete origin vX.Y.Z或在release/vX.Y.0上出 hotfix → 补丁版本vX.Y.(Z1)立即在 GitHub Discussions 与 Discord 同步说明。npm 产物回滚的默认动作是npm deprecate omniroutebad reason — use fixed分钟级、可逆npm unpublish仅限 72 小时/无依赖窗口内且永远不作为第一动作。Docker 侧绝不重写版本 tag——回滚是把latest重新指向最后一个好 digest。11.2 硬性规则绝不直接提交到main绝不git push --force到main或release/*分支绝不跳过 Husky Hooks--no-verify绝不提交 secrets、凭证或.env文件覆盖率必须保持 ≥60/60/60/60修改src/、open-sse/、electron/、bin/生产代码时必须附带或更新测试。十二、发布前 Keep Green 与高级门禁12.1 保持 release 队列常绿在进入本清单之前应周期性运行 docs/ops/RELEASE_GREEN.md 描述的流程/green-prs系列 npm run check:release-green/babysit nightly让 release PR 从一开始就是绿的——这能显著减少发布日的返工。12.2 数据库迁移检查若 src/lib/db/migrations/ 出现新迁移文件当前编号已推进到 175 号call_logs_provider_stats_indexes.sql必须验证每个迁移幂等CREATE TABLE IF NOT EXISTS等迁移包裹在事务中编号连续无空洞仓库有check:migration-numbering脚本与tests/unit/db/no-migration-collisions.test.ts防止未来冲突全新安装与存量升级两条路径都要测试重写表时正确处理 WAL 文件-wal、-shm。12.3 Provider CatalogZod 校验新增 provider 时src/shared/constants/providers.ts 的 Zod schema 必须在加载时通过校验OAuth provider 需在 src/lib/oauth/constants/oauth.ts 注册oauthConfig对应 executor 放在open-sse/executors/非 OpenAI 格式需在open-sse/translator/提供翻译器模型在open-sse/config/providerRegistry.ts注册并在tests/unit/覆盖 provider 分类与路由逻辑。12.4 发布后收尾运行/capture-release-evidences-cc采集新功能的 WebP 截图/录屏附到发布说明更新 GitHub Discussions / Discord 发布公告打开下一版本 milestone若属关键公告可固定讨论或在 news.json 发布应用内横幅注意横幅 ID 采用active标志控制开关仓库中radar-launch-2026-08即为active: false的待激活示例。结语发布不是提交 tag而是证明可发布回到荷兰语版清单的收尾——npm run check:docs-sync同时在本地与 CI lint 作业中执行。这条命令代表了整个发布哲学OmniRoute 的发布检查清单把人为自觉压缩到最小把可自动化的一致性校验版本号、OpenAPI、文档、i18n、Node 版本、工件残留、文档同步全部脚本化再由 Husky Hooks 与 CI 在本地和远端双重把关。发布者需要操心的只剩真正需要判断力的部分CHANGELOG 的语义整理、测试覆盖的真实性以及部署后的冒烟验证。参考路径速查英文源清单 docs/ops/RELEASE_CHECKLIST.md · 荷兰语翻译 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md · 运行时策略源码 src/shared/utils/nodeRuntimeSupport.ts · 钩子目录 .husky/ · CI 配置 .github/workflows/ci.yml【免费下载链接】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），仅供参考