[x.y.z] — YYYY-MM-DD【免费下载链接】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### 3. 保持 Unreleased 始终在首位 ## [Unreleased] 必须始终作为 CHANGELOG 的第一个小节保留供下一个迭代继续积累变更。 ### 4. 最新 SemVer 段必须等于 package.json 版本 这是发布检查清单中反复强调的硬性一致性要求。它的底层校验在 [scripts/check/check-docs-sync.mjs](https://link.gitcode.com/i/54822f3edf1a481ad5468387130b2c96) 中实现脚本用正则 /^##\s\[([^\]])\]/ 提取 CHANGELOG 中所有版本段依次校验 - 第一个小节必须是 Unreleased - 必须存在至少一个 SemVer 版本段支持 X.Y.Z 与 X.Y.Z-prerelease.N 形式的预发布版本 - **最新版本段必须与 package.json 的 version 完全相等**否则输出 Latest changelog release (…) differs from package.json (…) 并退出码为 1。 bash # 本地验证命令 node scripts/check/check-docs-sync.mjs三、API 文档版本同步1. 更新 OpenAPI 规范发布时必须更新 docs/openapi.yaml注意英文权威源清单中记录的实际路径是docs/openapi.yaml它是docs/目录下的顶层文件info.version必须等于package.json的版本若 API 契约contracts发生变化必须重新校验所有端点示例。check-docs-sync.mjs中的extractOpenApiVersion()函数会解析 OpenAPI 文件info:块下的version字段与package.json比对。仓库当前docs/openapi.yaml中记录的版本为3.8.51与 package.json 的version一致。2. 相关 API 门禁除了版本号发布前还建议运行 API 相关的专项检查脚本npm run check:openapi-coverage # OpenAPI 路由覆盖 npm run check:openapi-breaking # 破坏性变更检测 npm run check:openapi-security-tiers # 安全分级四、运行时文档审查1. 审查架构与排障文档审查 docs/architecture/ARCHITECTURE.md确认存储/运行时描述没有漂移审查 docs/guides/TROUBLESHOOTING.md确认环境变量与运维描述没有漂移若.env.example发生变化同步更新 docs/reference/ENVIRONMENT.md。2. 验证 Node.js 运行时下限这是发布检查清单中最容易过时的一项。当前仓库的英文权威清单与 package.jsonengines字段一致地声明22.22.2 23 || 24.0.0 27即支持 Node.js 22.22.222.x LTS与 24.0.024.x LTS以及 25.x、26.x 系列。具体的“安全补丁下限”由 src/shared/utils/nodeRuntimeSupport.ts 中的SECURE_NODE_LINES常量定义22.22.2、24.0.0、25.0.0、26.0.0四条安全线推荐版本为24.14.1。发布前必须确认当前运行/构建环境仍满足该下限npm run check:node-runtime该命令读取 scripts/check/check-supported-node-runtime.ts底层调用getNodeRuntimeSupport()对当前进程的 Node 版本做判定低于安全下限below-security-floor、超出已发布主版本unreleased-major或未知主版本都会导致退出码 1。脚本同样支持 Bun 运行时Bun 1.1 视为兼容。注意较旧的本地化镜像文档如斯洛伐克语版清单中可能仍写着20.20.2 21或22.22.2 23的历史值。以当前仓库实际内容为准——Node 20 系列已不再受支持发布前请务必以 package.json 的engines与nodeRuntimeSupport.ts的SUPPORTED_NODE_RANGE为最终依据。五、构建产物净化与 npm 发布校验发布清单要求构建独立发布包standalone package后必须校验 npm 发布产物中没有混入本地残留文件npm run build:cli npm run check:pack-artifactcheck:pack-artifact由 scripts/build/validate-pack-artifact.ts 实现重点确认打包产物中不存在以下本地残留app.__qa_backupQA 备份目录scripts/scratch临时脚本目录package-lock.json发布包不应携带锁文件其他由findLeakedTestArtifactPaths()、findUnexpectedArtifactPaths()检测到的测试残留与越界文件。该脚本还基于PACK_ARTIFACT_REQUIRED_PATHS校验dist/必须包含的运行时文件如dist/server.js缺失时会自动先执行npm run build:cli补齐再校验。它还会通过makeGitAncestryProbe/readBuildSha校验dist/BUILD_SHA与 git HEAD 是否一致确保发布产物来自当前提交而非陈旧构建。另外发布前应通过构建脚本生成并验证 sentinel 文件npm run build:release # 校验 dist/BUILD_SHA git rev-parse --short HEADbuild:release是一条整合命令见 package.json清理.build与dist→ 触发 next build 到.build/next/→ 调用assembleStandalone组装独立运行包到dist/→ 写入dist/BUILD_SHA。发布时不要分别运行npm run build再接npm run build:cli而是直接使用npm run build:release保证一次干净的构建。六、本地化镜像同步OmniRoute 的文档系统维护着 50 语言的镜像docs/i18n 目录如sk、zh-CN、ja等。若源英文文档发生显著变化发布前必须更新本地化文档。本地化镜像的强一致性由check-docs-sync.mjs保证对llm.txt等“精确镜像”文件要求各语言版本正文与根版本逐字节一致normalizeMirrorBody比较对CHANGELOG.md这类“翻译型”文件因章节标题被翻译如 Security → 对应语言跳过逐字节比较改为校验所有版本段## [X.Y.Z]都在译本中出现且顺序一致并限制正文行数与源文档的偏差在 25% 以内同时作为防回归手段检查已被替代的旧文档副本如docs/CLI-TOOLS.md的遗留重复不得重新出现。七、自动化同步检查与 CI 门禁发布清单的最后一步是本地运行同步守门脚本然后再打开 PRnpm run check:docs-sync该命令的完整链路为npm run check:docs-all它聚合了多个子检查见 package.json 的 scripts 定义check:docs-sync # 版本同步package.json / openapi / CHANGELOG / i18n 镜像 check:docs-frontmatter check:docs-counts check:env-doc-sync # 代码 ↔ .env.example ↔ ENVIRONMENT.md 契约 check:deprecated-versions check:doc-links # 内部 Markdown 引用无死链 check:fabricated-docs在 CI 侧英文权威清单注明检查运行于 .github/workflows/ci.yml在当前仓库实现中check:docs-sync位于 CI 的docs-sync-strictjob通过npm run check:docs-all执行并且已经提前在本地 Husky 钩子中拦截.husky/pre-commit 每次提交时依次运行npx lint-staged、node scripts/check/check-docs-sync.mjs、npm run check:any-budget:t11、node scripts/check/check-tracked-artifacts.mjs.husky/pre-push 作为快速确定性门禁运行。清单明确要求钩子失败必须修复底层问题禁止用--no-verify绕过。八、完整发布流程补充从英文权威清单看进阶环节斯洛伐克语镜像版是发布清单的核心精简骨架英文权威源 docs/ops/RELEASE_CHECKLIST.md 在此基础上补充了更完整的发布环节整理如下可与本地化镜像版配合使用1. 发布前Pre-release所有面向本版本的 PR 已合入release/vX.Y.0分支对应 Linear/issue 全部关闭或推至下一里程碑release/vX.Y.0分支 CI 全绿无TODO(release)残留grep -r TODO(release) src/ open-sse/Docker 基础镜像保持最新当前为node:24.15.0-trixie-slim。2. 质量门禁与测试矩阵npm run lint # 0 error 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 # 运行时下限测试方面按改动范围取舍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 改动test:combo:live与test:combo:live:vps是可选手动项它们会真实请求上游供应商、消耗额度绝不在 CI 中运行。3. Conventional Commits 规范所有进入发布的提交必须遵循type(scope): subject格式有效类型feat、fix、refactor、docs、test、chore、perf、style、ci有效范围db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz破坏性变更在 footer 中写BREAKING CHANGE:或在 scope 后加!如feat(api)!: drop /v0。4. 构建布局三目录约定目录用途是否入库src/应用源码TypeScript / TSX是.build/next build 中间产物distDir否gitignoreddist/可发布的 npm 包由assembleStandalone组装否gitignored注意远程 VPS 镜像目录仍是/usr/lib/node_modules/omniroute/app/只是仓库内构建输出从app/移动到了dist/部署 skill 会把dist/内容 rsync 到远端app/VPS 路径无需变更。5. 标记、发布与部署# 手动打标签 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部署按目标选择 skill/deploy-vps-local-cc本地 VPS192.168.0.15、/deploy-vps-akamai-ccAkamai VPS、/deploy-vps-both-cc两者。部署前后必须确认dist/BUILD_SHA git rev-parse --short HEAD。部署后的冒烟测试包括打开/dashboard/health确认版本字符串与发布一致对已知供应商发起一次/v1/chat/completions请求验证/api/monitoring/health返回的熔断器circuit breaker为CLOSED确认 MCP 传输通道/mcpHTTP、/mcp-sseSSE正常响应。6. 回滚与硬性规则若发布出现严重问题按优先级回滚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禁止--no-verify跳过 Husky 钩子禁止提交密钥、凭据或.env文件覆盖率必须保持 ≥60/60/60/60改动src/、open-sse/、electron/、bin/生产代码时必须同步更新测试。九、发布清单速查以斯洛伐克语镜像清单为主线最终发布前的核心动作收敛为# 1. 版本与变更日志 npm run check:docs-sync # package.json / openapi / CHANGELOG 三方版本一致 # 2. 运行时与文档 npm run check:node-runtime # Node 运行时下限22.22.2 23 || 24.0.0 27 npm run check:docs-all # 文档全量检查含 doc-links、env-doc-sync # 3. 构建产物 npm run build:release # 一次干净的构建.build → dist BUILD_SHA npm run check:pack-artifact # 无 app.__qa_backup / scripts/scratch / package-lock.json 残留 # 4. 质量与测试 npm run check npm run test:coverage # 60/60/60/60【免费下载链接】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），仅供参考