尧图网页设计 
OmniRoute 发布清单Release Checklist实战指南从版本号到 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发布一个新版本对任何多语言、多组件项目都是高风险操作版本号、变更日志、API 规范、运行时文档、构建产物、CI 检查必须全部保持一致任何一处漂移都可能导致用户拿到一个版本对不上号的包。OmniRoute 用一份发布清单Release Checklist把这一流程固化为可执行的核查步骤配套npm run check:docs-sync等自动化守卫从 docs/ops/RELEASE_CHECKLIST.md英文原版到 docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md西班牙语镜像在内的全部文档镜像共同定义了 tagging 或发布前的强制核查内容。读完本文你将掌握 OmniRoute 版本发布前必须逐一验证的四大核查域版本与变更日志、API 文档、运行时文档、自动化检查以及构建产物校验、npm 信任发布Trusted Publishing、Hotfix 快车道等进阶发布机制并能直接在仓库中定位对应脚本与 CI 配置进行核对。使用这份清单前先让发布分支保持绿色英文原版清单开篇即强调发布不是起点而是结果。在跑清单之前应先通过 docs/ops/RELEASE_GREEN.md 中描述的release-green 家族/green-prs队列扫描、npm run check:release-green校验引擎、/babysit PR#单 PR 驱动、nightly-release-green.yml夜间自动校验周期性地预检整个 PR 队列与活动发布分支让发布 PR 的首次 CI 运行就是绿的而不是在发布当天以约 40 分钟一轮的节奏逐层排雷。其中 scripts/quality/validate-release-green.mjs 是核心引擎它把每条红色结果分类为HARD真实缺陷exit 1与DRIFT棘轮基线漂移仅报告、由维护者在发布时重新基线化永不阻断任何人。一、版本与变更日志Version and Changelog发布的第一组核查围绕版本号一致性展开英文原版清单给出的 TL;DR 流程如下# 1. 升级版本号 生成 CHANGELOGClaude Code skill /version-bump-cc patch # 或 minor / major # 2. 本地跑质量门 npm run check # lint tests npm run test:coverage # 全量覆盖率门60/60/60/60 # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成 releaseskill /generate-release-cc # 5. 部署skill /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 捕获发布证据skill /capture-release-evidences-cc具体核查项包括在发布分支上递增package.json版本号x.y.z。当前仓库 package.json 的版本为3.8.51。把CHANGELOG.md中## [Unreleased]下的发布说明移动到带日期的章节## [x.y.z] — YYYY-MM-DD。保留## [Unreleased]作为 CHANGELOG 的第一个章节承接后续工作。确保CHANGELOG.md中最新 semver 章节与package.json版本一致。这四条规则并非仅靠自觉——它们正是 scripts/check/check-docs-sync.mjs 的校验逻辑。从源码看该脚本依次检查package.json的version必须是合法 semver/^\d\.\d\.\d(-[a-zA-Z0-9.])?$/CHANGELOG.md的第一节必须是## [Unreleased]CHANGELOG 中最新 semver 章节必须等于package.json版本否则输出Latest changelog release (...) differs from package.json (...)并最终process.exit(1)。也就是说第 4 条清单核查项背后有可重复执行的机器守卫任何人只要跑npm run check:docs-sync就会被强制对齐。二、API 文档API Docs对外提供 OpenAI 兼容 API 的网关项目其 OpenAPI 规范是用户集成的重要契约因此发布前必须同步更新docs/openapi.yaml的info.version使其等于package.json版本。如果 API 契约发生变化校验端点示例。同样这一项也是自动化的。check-docs-sync.mjs中有专门的extractOpenApiVersion()函数从docs/openapi.yaml的info:块解析出version字段并与package.json.version比对不一致即判失败并输出OpenAPI version (...) differs from package.json (...)。此外从 scripts/build/prepublish.ts 可以看到docs/openapi.yaml还会被复制进 npm 发布包的dist/docs/目录见build:cli阶段的第 9.5 步因此它不仅是仓库内契约更是随发布产物交付给下游用户的运行时契约——版本漂移会直接污染已发布的包。三、运行时文档Runtime Docs发布前需要审查与运行环境相关的文档是否漂移审查 docs/architecture/ARCHITECTURE.md确认存储/运行时描述没有与实际实现脱节。审查 docs/guides/TROUBLESHOOTING.md确认环境变量与运维细节没有漂移。验证发布/运行时所用 Node.js 版本仍满足支持的安全底线20.20.2 21或22.22.2 23英文原版清单给出的安全底线当前仓库 package.json 的engines已更新为22.22.2 23 || 24.0.0 27以仓库实际值为准运行npm run check:node-runtime。构建独立包后验证 npm 发布产物npm run build:clinpm run check:pack-artifact确认产物中不存在app.__qa_backup、scripts/scratch、package-lock.json或其他本地残留物。如果源文档有显著变更更新本地化文档例如本文所在的docs/i18n/各语言镜像目录。Node 运行时底线的实现位于 src/shared/utils/nodeRuntimeSupport.ts模块导出SECURE_NODE_LINES22.22.2、24.0.0、25.0.0、26.0.0 各主版本的补丁底线、SUPPORTED_NODE_RANGE 22.22.2 23 || 24.0.0 27和RECOMMENDED_NODE_VERSION 24.14.1。getNodeRuntimeSupport()会把当前process.versions.node与对应主版本的安全底线逐段比较给出supported/below-security-floor/unsupported-major/unreleased-major四种判定npm run check:node-runtime即封装了对这一策略的 CLI 检查见 package.json 中的check:node-runtime脚本指向 scripts/check/check-supported-node-runtime.ts。Bun 运行时process.versions.bun存在则直接判为supported-bun。四、自动化同步检查Automated Check这是清单中唯一给出明确命令的强制步骤开 PR 前在本地运行npm run check:docs-syncCI 也会在 .github/workflows/ci.yml 的 lint 作业中运行该检查。从仓库证据看这一职责在 CI 中已被强化ci.yml中有独立的docs-sync-strict作业其执行命令是npm run check:docs-all伞形检查docs-sync docs-counts env-doc-sync deprecated-versions doc-links并且被纳入发布 PR 的必过依赖needs: docs-sync-strict。npm run check:docs-sync还承担一个易被忽略的职责——i18n 镜像一致性。从 scripts/check/check-docs-sync.mjs 源码可见它遍历docs/i18n/下全部语言目录对llm.txt等镜像文件要求逐字节一致去掉首行标题后与根文件归一化比较且每个语言镜像文件必须包含---分隔符对CHANGELOG.md镜像因各语言翻译了章节标题采用版本章节集合 行数容差校验必须包含根 CHANGELOG 的全部## [X.Y.Z]章节且顺序一致正文行数差异不得超过 25%。也就是说本文所在的西班牙语镜像文档之所以能与英文原版结构对齐正是由这套同步守卫保障的——任何语言镜像与源文档漂移都会让check:docs-sync在本地与 CI 双双失败。五、发布产物与构建布局Artifact Validation清单要求在发布前验证构建产物干净、可追溯。仓库当前采用的是单次构建流程不建议把npm run build与单独的npm run build:cli分开跑而是直接使用npm run build:release ├─ rm -rf .build dist 清理 ├─ next build → .build/next/ 中间产物 ├─ assembleStandalone standalone static public natives → dist/ └─ 写入 dist/BUILD_SHA HEAD 哨兵配套核查npm run build:release成功后dist/BUILD_SHA必须等于git rev-parse --short HEADnpm run check:pack-artifact必须干净——不得出现app.__qa_backup、scripts/scratch、package-lock.json等本地残留dist/server.js必须存在。三个输出目录的职责在清单中有明确区分发布布局表src/是应用源码被 git 跟踪.build/是next build的中间产物目录distDirgitignoredist/是可由assembleStandalone组装、可发布的 npm bundlegitignore。运维上需要注意远端 VPS 的镜像目录仍是/usr/lib/node_modules/omniroute/app/仅仓库内构建输出从app/移到了dist/部署 skill 通过 rsync 把dist/内容同步到远端app/因此 VPS 路径无需变更。npm run check:pack-artifact的实现见 scripts/build/validate-pack-artifact.ts它执行npm pack --dry-run --json并从四个方面审计发布包意外文件不在允许的精确路径/前缀白名单内、必需运行时文件缺失、测试文件泄漏*.test.*、__tests__等由package.json的files否定规则兜底、以及MCP 闭包完整性computeMcpClosure()遍历 MCP 可达的 TypeScript 源文件逐文件确认被打包防止--mcp运行时 404。此外从buildProvenance.ts的证据链看它还会校验dist/BUILD_SHA对应的提交是origin/main的祖先防止从旧分支构建出假发布2026-08-14 网关事故的教训只有OMNIROUTE_ALLOW_CANARY_BUILD1才能绕过。六、npm 信任发布与分阶段发布Trusted Publishing / Staged自 v3.8.51 起npm 发布默认走npm Trusted PublishingOIDCnpm-publish.yml的stage-npm作业在 GitHub 托管的 runner 上用 id-token 换取该次运行的短期 npm 凭证仓库 secrets 里不再存放长期 npm token也无 2FA 提示且自动附加 provenance 来源证明。这意味着即使 token 泄露也无法单独完成发布——根本没有 token 存在。与之配合的是先暂存、后批准的分阶段发布模式publish_modestaged工作流启动打包产物check:pack-boot后执行npm stage publish字节先停在 registry 上但不可安装等所有者人工 2FA 放行。发布者owner在工作流变绿后的流程npm stage list omniroute找到 stage id工作流摘要中也会打印推荐npm stage download id验证暂存字节装进临时 prefix 并启动npm stage approve id——这一步的 2FA 提示就是发布动作npm stage reject id则丢弃发布后由后置验证器从公共 registry 在干净容器里安装并启动刚发布的版本。紧急回退workflow_dispatch传publish_modedirect恢复传统立即npm publish仅当暂存机制本身异常时使用并记录原因。这一机制在 .github/workflows/npm-publish.yml 中有完整实现publish_mode参数的可选值与语义auto/staged/direct也定义在同一工作流中。此外每次稳定 SemVer 发布时docker-publish工作流必须同时给X.Y.Z打标签并在should-promote-latest.sh判定其为最高稳定版本时以相同 digest更新:latest避免latest停留在老构建上。七、Hotfix 快车道与硬规则当生产环境被打破发布产物启动即崩 / 安全修复 / 影响该版本所有用户时带hotfix标签的 PR 可以跳过重型 CI 矩阵9 分片 E2E、覆盖率棘轮、quality-gate、quality-extended只保留高信号门build、单元分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟check:pack-boot目标是把绿灯时间从约 33 分钟压到 15 分钟以内。该车道有严格准入策略仿照 Chromium/VS Code/Node 的应急车道严重性生产确实 broken重要不等于broken、权限只有仓库所有者能贴hotfix标签标签本身就是批准、证据PR 正文必须链接上一次全绿的 heavy 运行记录 该修复自身的先红后绿测试、范围只允许 cherry-pick 最小修复禁止重构与搭便车改动。被跳过的覆盖率/棘轮面由发布分支上下一轮全量运行重新验证——车道跳过的是等待不是验证。无论常规发布还是 hotfix以下硬规则始终有效永远不要直接提交到main永远不要对main或release/*分支使用git push --force永远不要跳过 Husky hooks--no-verify永远不要提交 secrets、凭证或.env文件覆盖率必须保持在 ≥60/60/60/60statements/lines/functions/branches修改src/、open-sse/、electron/或bin/中的生产代码时必须同时新增或更新测试。Husky hooks 位于.husky/pre-commit 运行npx lint-staged node scripts/check/check-docs-sync.mjs npm run check:any-budget:t11pre-push 运行快速确定性门check:any-budget:t11check:tracked-artifacts刻意不含慢速的test:unit由 CI 的 test-unit 作业覆盖因此在推送发布分支前应手动跑一次npm run test:unit。Hook 失败就修复根因不要用--no-verify绕过。八、发布、回滚与发布后动作发布动作本身可通过 Claude Code skill/generate-release-cc完成创建vX.Y.Ztag、推送 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-tag部署使用轻量 rsync 流程不用npm pack、不用npm i -g按目标选择 skill/deploy-vps-local-cc本地 VPS 192.168.0.15、/deploy-vps-akamai-ccAkamai VPS 69.164.221.35、/deploy-vps-both-cc两者。部署前必须确认dist/BUILD_SHA等于git 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正常响应。发布后运行/capture-release-evidences-cc捕获新功能的 WebP 截图/录像并附到发布说明更新社区公告开启下一版本 milestone关键发布可在 news.json 中登记用于应用内横幅。回滚预案发布后发现严重问题时按序执行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)立即在社区渠道同步沟通。对于坏产物npm deprecate omniroutebad reason — use fixed是默认反应几分钟内可逆npm unpublish仅限 72 小时且无依赖者的窗口且永远不作为第一步。Docker 镜像永远不要重写版本 tag——回滚就是把latest重新指向最后一个好 digest。九、从清单到工程实践三个可立即落地的动作把npm run check:docs-sync变成肌肉记忆它是版本号、CHANGELOG、OpenAPI、i18n 镜像四方对齐的统一守卫本地失败就不该开 PR。发布前先跑npm run build:releasenpm run check:pack-artifact前者一次完成干净重建并写入BUILD_SHA哨兵后者从意外文件、必需文件、测试泄漏、MCP 闭包与构建溯源五个维度审计 tarball是发布包可用的最后防线。用 release-green 家族把发布日的红色风险前移定期运行/green-prs与npm run check:release-green让发布 PR 的首次 CI 运行即为绿色而不是在发布当天逐层排雷。相关资源完整英文版清单、发布分支常绿指南、docs 同步守卫实现、npm 产物审计实现、Node 运行时策略、npm 发布工作流、主 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辅助生成（AIGC），仅供参考 OmniRoute 发布清单（Release Checklist）实战指南：从版本号到 npm 产物的全流程发布核查
OmniRoute 发布清单Release Checklist实战指南从版本号到 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发布一个新版本对任何多语言、多组件项目都是高风险操作版本号、变更日志、API 规范、运行时文档、构建产物、CI 检查必须全部保持一致任何一处漂移都可能导致用户拿到一个版本对不上号的包。OmniRoute 用一份发布清单Release Checklist把这一流程固化为可执行的核查步骤配套npm run check:docs-sync等自动化守卫从 docs/ops/RELEASE_CHECKLIST.md英文原版到 docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md西班牙语镜像在内的全部文档镜像共同定义了 tagging 或发布前的强制核查内容。读完本文你将掌握 OmniRoute 版本发布前必须逐一验证的四大核查域版本与变更日志、API 文档、运行时文档、自动化检查以及构建产物校验、npm 信任发布Trusted Publishing、Hotfix 快车道等进阶发布机制并能直接在仓库中定位对应脚本与 CI 配置进行核对。使用这份清单前先让发布分支保持绿色英文原版清单开篇即强调发布不是起点而是结果。在跑清单之前应先通过 docs/ops/RELEASE_GREEN.md 中描述的release-green 家族/green-prs队列扫描、npm run check:release-green校验引擎、/babysit PR#单 PR 驱动、nightly-release-green.yml夜间自动校验周期性地预检整个 PR 队列与活动发布分支让发布 PR 的首次 CI 运行就是绿的而不是在发布当天以约 40 分钟一轮的节奏逐层排雷。其中 scripts/quality/validate-release-green.mjs 是核心引擎它把每条红色结果分类为HARD真实缺陷exit 1与DRIFT棘轮基线漂移仅报告、由维护者在发布时重新基线化永不阻断任何人。一、版本与变更日志Version and Changelog发布的第一组核查围绕版本号一致性展开英文原版清单给出的 TL;DR 流程如下# 1. 升级版本号 生成 CHANGELOGClaude Code skill /version-bump-cc patch # 或 minor / major # 2. 本地跑质量门 npm run check # lint tests npm run test:coverage # 全量覆盖率门60/60/60/60 # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成 releaseskill /generate-release-cc # 5. 部署skill /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 捕获发布证据skill /capture-release-evidences-cc具体核查项包括在发布分支上递增package.json版本号x.y.z。当前仓库 package.json 的版本为3.8.51。把CHANGELOG.md中## [Unreleased]下的发布说明移动到带日期的章节## [x.y.z] — YYYY-MM-DD。保留## [Unreleased]作为 CHANGELOG 的第一个章节承接后续工作。确保CHANGELOG.md中最新 semver 章节与package.json版本一致。这四条规则并非仅靠自觉——它们正是 scripts/check/check-docs-sync.mjs 的校验逻辑。从源码看该脚本依次检查package.json的version必须是合法 semver/^\d\.\d\.\d(-[a-zA-Z0-9.])?$/CHANGELOG.md的第一节必须是## [Unreleased]CHANGELOG 中最新 semver 章节必须等于package.json版本否则输出Latest changelog release (...) differs from package.json (...)并最终process.exit(1)。也就是说第 4 条清单核查项背后有可重复执行的机器守卫任何人只要跑npm run check:docs-sync就会被强制对齐。二、API 文档API Docs对外提供 OpenAI 兼容 API 的网关项目其 OpenAPI 规范是用户集成的重要契约因此发布前必须同步更新docs/openapi.yaml的info.version使其等于package.json版本。如果 API 契约发生变化校验端点示例。同样这一项也是自动化的。check-docs-sync.mjs中有专门的extractOpenApiVersion()函数从docs/openapi.yaml的info:块解析出version字段并与package.json.version比对不一致即判失败并输出OpenAPI version (...) differs from package.json (...)。此外从 scripts/build/prepublish.ts 可以看到docs/openapi.yaml还会被复制进 npm 发布包的dist/docs/目录见build:cli阶段的第 9.5 步因此它不仅是仓库内契约更是随发布产物交付给下游用户的运行时契约——版本漂移会直接污染已发布的包。三、运行时文档Runtime Docs发布前需要审查与运行环境相关的文档是否漂移审查 docs/architecture/ARCHITECTURE.md确认存储/运行时描述没有与实际实现脱节。审查 docs/guides/TROUBLESHOOTING.md确认环境变量与运维细节没有漂移。验证发布/运行时所用 Node.js 版本仍满足支持的安全底线20.20.2 21或22.22.2 23英文原版清单给出的安全底线当前仓库 package.json 的engines已更新为22.22.2 23 || 24.0.0 27以仓库实际值为准运行npm run check:node-runtime。构建独立包后验证 npm 发布产物npm run build:clinpm run check:pack-artifact确认产物中不存在app.__qa_backup、scripts/scratch、package-lock.json或其他本地残留物。如果源文档有显著变更更新本地化文档例如本文所在的docs/i18n/各语言镜像目录。Node 运行时底线的实现位于 src/shared/utils/nodeRuntimeSupport.ts模块导出SECURE_NODE_LINES22.22.2、24.0.0、25.0.0、26.0.0 各主版本的补丁底线、SUPPORTED_NODE_RANGE 22.22.2 23 || 24.0.0 27和RECOMMENDED_NODE_VERSION 24.14.1。getNodeRuntimeSupport()会把当前process.versions.node与对应主版本的安全底线逐段比较给出supported/below-security-floor/unsupported-major/unreleased-major四种判定npm run check:node-runtime即封装了对这一策略的 CLI 检查见 package.json 中的check:node-runtime脚本指向 scripts/check/check-supported-node-runtime.ts。Bun 运行时process.versions.bun存在则直接判为supported-bun。四、自动化同步检查Automated Check这是清单中唯一给出明确命令的强制步骤开 PR 前在本地运行npm run check:docs-syncCI 也会在 .github/workflows/ci.yml 的 lint 作业中运行该检查。从仓库证据看这一职责在 CI 中已被强化ci.yml中有独立的docs-sync-strict作业其执行命令是npm run check:docs-all伞形检查docs-sync docs-counts env-doc-sync deprecated-versions doc-links并且被纳入发布 PR 的必过依赖needs: docs-sync-strict。npm run check:docs-sync还承担一个易被忽略的职责——i18n 镜像一致性。从 scripts/check/check-docs-sync.mjs 源码可见它遍历docs/i18n/下全部语言目录对llm.txt等镜像文件要求逐字节一致去掉首行标题后与根文件归一化比较且每个语言镜像文件必须包含---分隔符对CHANGELOG.md镜像因各语言翻译了章节标题采用版本章节集合 行数容差校验必须包含根 CHANGELOG 的全部## [X.Y.Z]章节且顺序一致正文行数差异不得超过 25%。也就是说本文所在的西班牙语镜像文档之所以能与英文原版结构对齐正是由这套同步守卫保障的——任何语言镜像与源文档漂移都会让check:docs-sync在本地与 CI 双双失败。五、发布产物与构建布局Artifact Validation清单要求在发布前验证构建产物干净、可追溯。仓库当前采用的是单次构建流程不建议把npm run build与单独的npm run build:cli分开跑而是直接使用npm run build:release ├─ rm -rf .build dist 清理 ├─ next build → .build/next/ 中间产物 ├─ assembleStandalone standalone static public natives → dist/ └─ 写入 dist/BUILD_SHA HEAD 哨兵配套核查npm run build:release成功后dist/BUILD_SHA必须等于git rev-parse --short HEADnpm run check:pack-artifact必须干净——不得出现app.__qa_backup、scripts/scratch、package-lock.json等本地残留dist/server.js必须存在。三个输出目录的职责在清单中有明确区分发布布局表src/是应用源码被 git 跟踪.build/是next build的中间产物目录distDirgitignoredist/是可由assembleStandalone组装、可发布的 npm bundlegitignore。运维上需要注意远端 VPS 的镜像目录仍是/usr/lib/node_modules/omniroute/app/仅仓库内构建输出从app/移到了dist/部署 skill 通过 rsync 把dist/内容同步到远端app/因此 VPS 路径无需变更。npm run check:pack-artifact的实现见 scripts/build/validate-pack-artifact.ts它执行npm pack --dry-run --json并从四个方面审计发布包意外文件不在允许的精确路径/前缀白名单内、必需运行时文件缺失、测试文件泄漏*.test.*、__tests__等由package.json的files否定规则兜底、以及MCP 闭包完整性computeMcpClosure()遍历 MCP 可达的 TypeScript 源文件逐文件确认被打包防止--mcp运行时 404。此外从buildProvenance.ts的证据链看它还会校验dist/BUILD_SHA对应的提交是origin/main的祖先防止从旧分支构建出假发布2026-08-14 网关事故的教训只有OMNIROUTE_ALLOW_CANARY_BUILD1才能绕过。六、npm 信任发布与分阶段发布Trusted Publishing / Staged自 v3.8.51 起npm 发布默认走npm Trusted PublishingOIDCnpm-publish.yml的stage-npm作业在 GitHub 托管的 runner 上用 id-token 换取该次运行的短期 npm 凭证仓库 secrets 里不再存放长期 npm token也无 2FA 提示且自动附加 provenance 来源证明。这意味着即使 token 泄露也无法单独完成发布——根本没有 token 存在。与之配合的是先暂存、后批准的分阶段发布模式publish_modestaged工作流启动打包产物check:pack-boot后执行npm stage publish字节先停在 registry 上但不可安装等所有者人工 2FA 放行。发布者owner在工作流变绿后的流程npm stage list omniroute找到 stage id工作流摘要中也会打印推荐npm stage download id验证暂存字节装进临时 prefix 并启动npm stage approve id——这一步的 2FA 提示就是发布动作npm stage reject id则丢弃发布后由后置验证器从公共 registry 在干净容器里安装并启动刚发布的版本。紧急回退workflow_dispatch传publish_modedirect恢复传统立即npm publish仅当暂存机制本身异常时使用并记录原因。这一机制在 .github/workflows/npm-publish.yml 中有完整实现publish_mode参数的可选值与语义auto/staged/direct也定义在同一工作流中。此外每次稳定 SemVer 发布时docker-publish工作流必须同时给X.Y.Z打标签并在should-promote-latest.sh判定其为最高稳定版本时以相同 digest更新:latest避免latest停留在老构建上。七、Hotfix 快车道与硬规则当生产环境被打破发布产物启动即崩 / 安全修复 / 影响该版本所有用户时带hotfix标签的 PR 可以跳过重型 CI 矩阵9 分片 E2E、覆盖率棘轮、quality-gate、quality-extended只保留高信号门build、单元分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟check:pack-boot目标是把绿灯时间从约 33 分钟压到 15 分钟以内。该车道有严格准入策略仿照 Chromium/VS Code/Node 的应急车道严重性生产确实 broken重要不等于broken、权限只有仓库所有者能贴hotfix标签标签本身就是批准、证据PR 正文必须链接上一次全绿的 heavy 运行记录 该修复自身的先红后绿测试、范围只允许 cherry-pick 最小修复禁止重构与搭便车改动。被跳过的覆盖率/棘轮面由发布分支上下一轮全量运行重新验证——车道跳过的是等待不是验证。无论常规发布还是 hotfix以下硬规则始终有效永远不要直接提交到main永远不要对main或release/*分支使用git push --force永远不要跳过 Husky hooks--no-verify永远不要提交 secrets、凭证或.env文件覆盖率必须保持在 ≥60/60/60/60statements/lines/functions/branches修改src/、open-sse/、electron/或bin/中的生产代码时必须同时新增或更新测试。Husky hooks 位于.husky/pre-commit 运行npx lint-staged node scripts/check/check-docs-sync.mjs npm run check:any-budget:t11pre-push 运行快速确定性门check:any-budget:t11check:tracked-artifacts刻意不含慢速的test:unit由 CI 的 test-unit 作业覆盖因此在推送发布分支前应手动跑一次npm run test:unit。Hook 失败就修复根因不要用--no-verify绕过。八、发布、回滚与发布后动作发布动作本身可通过 Claude Code skill/generate-release-cc完成创建vX.Y.Ztag、推送 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-tag部署使用轻量 rsync 流程不用npm pack、不用npm i -g按目标选择 skill/deploy-vps-local-cc本地 VPS 192.168.0.15、/deploy-vps-akamai-ccAkamai VPS 69.164.221.35、/deploy-vps-both-cc两者。部署前必须确认dist/BUILD_SHA等于git 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正常响应。发布后运行/capture-release-evidences-cc捕获新功能的 WebP 截图/录像并附到发布说明更新社区公告开启下一版本 milestone关键发布可在 news.json 中登记用于应用内横幅。回滚预案发布后发现严重问题时按序执行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)立即在社区渠道同步沟通。对于坏产物npm deprecate omniroutebad reason — use fixed是默认反应几分钟内可逆npm unpublish仅限 72 小时且无依赖者的窗口且永远不作为第一步。Docker 镜像永远不要重写版本 tag——回滚就是把latest重新指向最后一个好 digest。九、从清单到工程实践三个可立即落地的动作把npm run check:docs-sync变成肌肉记忆它是版本号、CHANGELOG、OpenAPI、i18n 镜像四方对齐的统一守卫本地失败就不该开 PR。发布前先跑npm run build:releasenpm run check:pack-artifact前者一次完成干净重建并写入BUILD_SHA哨兵后者从意外文件、必需文件、测试泄漏、MCP 闭包与构建溯源五个维度审计 tarball是发布包可用的最后防线。用 release-green 家族把发布日的红色风险前移定期运行/green-prs与npm run check:release-green让发布 PR 的首次 CI 运行即为绿色而不是在发布当天逐层排雷。相关资源完整英文版清单、发布分支常绿指南、docs 同步守卫实现、npm 产物审计实现、Node 运行时策略、npm 发布工作流、主 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辅助生成（AIGC），仅供参考