OmniRoute 发布检查清单实战指南从版本号、API 文档到 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 在打标签tagging与发布publishing新版本前必须完成的全部校验项。读完本文你将掌握 OmniRoute 的版本号与 CHANGELOG 同步规范、API 文档契约、Node.js 安全运行时基线、npm 发布产物校验以及本地与 CI 的自动化同步检查流程。发布清单的定位为什么需要它OmniRoute 是一个单体仓库式 AI 网关项目发布面覆盖 npm 包omniroute、Electron 桌面端、Docker 镜像与 OpenCode 插件等多个交付物。任何一次发布都牵动package.json、CHANGELOG.md、docs/openapi.yaml、本地化文档与构建产物等多处一致性。官方为此维护了一份打标签或发布前必须逐项核对的检查清单核心目标可以概括为三点版本号单一事实来源package.json、CHANGELOG.md最新 semver 小节与 OpenAPI 文档中的info.version必须严格相等文档与运行时零漂移架构文档、故障排查文档与.env契约必须跟上代码变化发布产物可审计npm 包内不得混入本地残留文件且必须能干净启动。版本号与 CHANGELOG发布的第一步清单要求按以下顺序完成版本与变更日志的处理在发布分支中提升package.json的版本号格式x.y.z将CHANGELOG.md中## [Unreleased]的内容移动到带日期的正式小节## [x.y.z] — YYYY-MM-DD保留## [Unreleased]作为变更日志的第一节供下一个版本的开发继续累积确认CHANGELOG.md中最新 semver 小节与package.json版本号一致。从源码看package.json 当前版本为3.8.51engines.node声明为22.22.2 23 || 24.0.0 27这四项就是版本同步的锚点。仓库还为版本提升提供了自动化技能入口/version-bump-cc patch|minor|majorClaude Code skill它会同时提升根package.json与electron/package.json、基于上次 tag 重新生成CHANGELOG.md并更新 README 徽章——发布者仍应人工审阅生成的 CHANGELOG 并清理提交信息。API 文档契约info.version 必须等于 package.json 版本清单在 API Docs 一节要求更新docs/openapi.yaml确保info.version等于package.json版本号如果 API 契约发生变化需要验证其中的端点示例。仓库中实际的 OpenAPI 文件位于 docs/openapi.yaml注意俄语版清单中写的是docs/reference/openapi.yaml而当前仓库的英文原版与真实文件路径均为docs/openapi.yaml以仓库实际为准。这一契约约束有专门的 CI 守护npm run check:openapi-coverage、npm run check:openapi-breaking、npm run check:openapi-routes等一系列检查脚本见 package.json 的 scripts 段以及 docs/reference/API_REFERENCE.md 与 OpenAPI 文件的联动更新要求。发布前若改动了 API务必确认check:openapi-breaking通过避免破坏既有客户端的向后兼容。运行时文档与 Node.js 安全基线发布前需要审阅以下文档排查与存储/运行时的漂移docs/architecture/ARCHITECTURE.md核对存储与运行时架构是否与代码一致docs/guides/TROUBLESHOOTING.md核对环境变量与运维说明是否漂移。同时必须验证发布/运行时使用的 Node.js 版本仍然满足项目支持的安全基线清单给出的校验命令是npm run check:node-runtime关于 Node 版本基线俄语版清单记录的旧基线为20.20.2 21或22.22.2 23但当前仓库的实际策略已经演进请以仓库现状为准src/shared/utils/nodeRuntimeSupport.ts 中定义SUPPORTED_NODE_RANGE 22.22.2 23 || 24.0.0 27安全版本线SECURE_NODE_LINES覆盖22.22.2、24.0.0、25.0.0、26.0.0四条主版本线推荐版本为RECOMMENDED_NODE_VERSION 24.14.1package.json 的engines字段与之一致scripts/check/check-supported-node-runtime.ts 是检查脚本的实现运行时若不兼容会打印Unsupported or insecure Node.js runtime detected并以退出码 1 失败若在 Bun 下运行则按SUPPORTED_NODE_RANGE || Bun 1.1.0判定。从源码结构看nodeRuntimeSupport.ts被刻意实现为纯 ESM以便被bin/下的 CLI 入口、src/下的 Next.js 路由处理器和scripts/下的脚本三方复用这说明运行时基线检查不仅在发布前执行也贯穿日常启动与运维路径。npm 发布产物的构建与校验构建独立包standalone package之后必须验证 npm 发布产物npm run build:cli npm run check:pack-artifactcheck:pack-artifact实现见 scripts/build/validate-pack-artifact.ts会确认产物中不包含以下本地残留app.__qa_backupscripts/scratchpackage-lock.json或其他本地残留文件构建布局方面仓库明确区分三个目录切勿混用目录用途是否入库src/应用源码TypeScript / TSX是.build/构建中间产物next build的distDir否gitignoreddist/可发布的 npm 包由assembleStandalone组装否gitignored发布部署时推荐使用单一构建命令npm run build:release先rm -rf .build dist清理再执行next build、组装 standalone 目录并写入dist/BUILD_SHA哨兵文件而不是先npm run build再单独npm run build:cli。部署前还需确认dist/BUILD_SHA等于git rev-parse --short HEAD保证线上运行的就是本次构建的代码。另外需要说明远程 VPS 上镜像目录仍为/usr/lib/node_modules/omniroute/app/构建产物目录从仓库内的app/迁移到dist/不影响远程路径部署技能会把dist/内容 rsync 到远程app/目录。自动化同步检查docs-sync打开 PR 之前必须在本地运行文档同步守卫npm run check:docs-syncCI 也会在.github/workflows/ci.yml的 lint job 中运行该检查实现见 scripts/check/check-docs-sync.mjs。这保证了文档结构与内容的同步性不会被破坏。深入发布流程背后的自动化与保障机制英文原版清单docs/ops/RELEASE_CHECKLIST.md对上述流程给出了更完整的自动化补充以下要点同样属于发布检查清单的组成部分。TL;DR一条命令走完的核心链路# 1. Bump 版本 生成 CHANGELOGskill /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-ccnpm Trusted Publishing 与 staged 发布自 v3.8.51 起.github/workflows/npm-publish.yml 默认通过npm Trusted PublishingOIDC发布stage-npmjob 在 GitHub 托管 runner 上把 GitHub 的 id-token 换成一次性的短时 npm 凭证——仓库 secrets 里不再存长期 npm token也不需要 2FA 提示同时附带 provenanceSLSA 级来源证明。泄漏 token 也无法单独完成发布因为根本不存在 token。流程细节staged 模式publish_modestagedworkflow 把打包好的 tarball 先寄存在 registry 上npm stage publish不可被安装直到 owner 批准。批准流程为npm stage list omniroute找到 stage id建议先校验npm stage download id把下载的 tarball 装进临时 prefix 并启动CI 中的npm run check:pack-boot自动化了 pack→install→boot 判定npm stage approve id——2FA 提示就是发布本身npm stage reject id则丢弃发布后的校验器会在干净容器中从公共 registry 安装已发布版本并启动验证。direct 模式应急回退workflow_dispatch传publish_modedirect恢复传统的立即npm publish仅在 staging 本身出问题时使用并需记录原因。发布流水线中还内置了两道启动验证check:pack-boot干净安装后必须能启动与check:install-upgrade在已有版本之上覆盖安装并启动覆盖约 110 个 SQLite 迁移在真实数据库上运行的升级路径。发布前任何一个坏制品都不会到达 registry。Hotfix 快速通道标记为hotfix的 PR 会跳过重型 CI 矩阵9 分片 E2E、覆盖率 ratchet、质量门只保留高信号门build、单元测试分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟check:pack-boot目标是把绿色时间从约 33 分钟压缩到 ≤15 分钟。入口政策要求同时满足四条严重性生产已损坏——发布产物启动即崩溃/安全修复/所有用户受影响、权限仅仓库 owner 可打hotfix标签、证据PR 正文链接上一次完整绿色重型运行 修复自身的失败转通过测试、范围仅 cherry-pick 最小修复不带重构。被跳过的覆盖率面会在发布分支的下一次完整运行中重新验证——快速通道跳过的是等待不是验证。质量门与测试矩阵清单要求发布分支上的完整校验包括npm run lint0 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:t06npm run test:unit、npm run test:vitestMCP server、autoCombo、cache、npm run test:coverage覆盖率门 60/60/60/60statements/lines/functions/branchesnpm run test:integration改动涉及 DB/handlers 时、npm run test:combo:matrix覆盖全部 19 种公共路由策略的选择判定触碰组合路由/策略解析/回退逻辑时必跑npm run test:e2eUI 改动、npm run test:protocols:e2eMCP/A2A 改动、npm run test:ecosystem。其中test:combo:live与test:combo:live:vps是可选/手动的线上冒烟会真实打上游 provider、消耗额度绝不在 CI 中运行无 gate 时可干净跳过。Husky 钩子与会话提交规范Husky 钩子位于.husky/在 git 操作时自动运行pre-commitnpx lint-staged node scripts/check/check-docs-sync.mjs npm run check:any-budget:t11pre-push快速确定性门——npm run check:any-budget:t11 npm run check:tracked-artifacts刻意排除慢速的test:unit由 CI 的test-unitjob 覆盖推送发布分支前请手动运行npm run test:unit。钩子失败时应修复底层问题不要用--no-verify绕过。所有进入发布的提交必须遵循type(scope): subject约定合法类型为feat|fix|refactor|docs|test|chore|perf|style|ci合法 scope 包括db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz。破坏性变更需加BREAKING CHANGE:脚注或在 scope 后加!如feat(api)!: drop /v0。数据库迁移与 Provider 目录若src/lib/db/migrations/出现新文件每个迁移必须幂等CREATE TABLE IF NOT EXISTS等、包裹在事务中、编号连续无缺口分别测试全新安装删除~/.omniroute/omniroute.db后npm run dev与已有安装备份 DB → 跑迁移 → 验证 schema若迁移重写表需正确处理 WAL 文件-wal、-shm。Provider 目录由 Zod schema 在加载时校验src/shared/constants/providers.ts所有 provider 必须有必填字段id、label、kind等新免费 provider 需提供freeNoteOAuth provider 需在src/lib/oauth/constants/oauth.ts注册oauthConfig新增 provider 时对应 executor 在open-sse/executors/、非 OpenAI 格式需在open-sse/translator/增加 translator模型注册在open-sse/config/providerRegistry.ts并在tests/unit/中补充 provider 分类与路由的单测。打标签、部署与回滚发布版本前运行/generate-release-cc创建并推送 tagvX.Y.Z、以 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按目标选择/deploy-vps-local-cc本地 VPS、/deploy-vps-akamai-ccAkamai VPS或/deploy-vps-both-cc。部署后冒烟检查打开/dashboard/health版本号字符串与发布一致对已知 provider 发起一个/v1/chat/completions请求验证/api/monitoring/health返回CLOSED熔断状态确认 MCP 传输通道响应/mcpHTTP、/mcp-sseSSE。若发布出现严重问题回滚路径为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 同步信息。硬性规则Hard Rules发布流程的底线约束绝不直接向main提交绝不对main或release/*分支使用git push --force绝不跳过 Husky 钩子--no-verify绝不提交密钥、凭据或.env文件覆盖率必须保持 ≥60/60/60/60statements/lines/functions/branches修改src/、open-sse/、electron/或bin/下的生产代码时必须同步新增或更新测试。小结OmniRoute 的发布检查清单把发布一个版本从手工记忆变成了一套可执行、可自动化、可审计的工程流程版本号与 CHANGELOG、OpenAPI 契约、Node.js 安全运行时基线、npm 产物校验、docs-sync 守卫、hotfix 快速通道与 staged 发布一起构成了多层防线。对本仓库的维护者而言最实用的三件事是发布前跑一遍npm run check:docs-sync与npm run check:node-runtime、用npm run build:release保证dist/BUILD_SHA与 HEAD 一致、以及理解 Trusted Publishing 下2FA 即发布的 staged 批准模型。【免费下载链接】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），仅供参考