DeepSeek-Reasonix 发布流程全解：三标签原子发布、受保护 Stable 中继与恢复机制-育师

DeepSeek-Reasonix 发布流程全解：三标签原子发布、受保护 Stable 中继与恢复机制

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

导读

本文以 docs/RELEASING.md 为核心，完整讲解 DeepSeek-Reasonix 的官方X.Y.Z版本发布体系：CLI、npm、Desktop 三条发布面如何通过vX.Y.Z、npm-vX.Y.Z、desktop-vX.Y.Z三个不可变 Git 标签绑定到main-v2的同一个提交，并借助单一受保护编排工作流完成从版本输入、双语 Notes 评审到全网发布与事后验证的全过程。读完本文，你将掌握发布前的本地校验脚本scripts/release-stable.sh的完整行为、受保护 Stable 工作流的 preflight/approve/publish/postflight 结构，以及部分发布失败时的恢复操作与第一版 cutover 后的独立验证清单。

一、发布体系概览：一条用户可见的发布线与三个不可变标签

Reasonix 只有一条面向用户的正式发布线：官方X.Y.Z版本。整个发布引擎沿用了已验证的 Stable 发布拓扑：一个main-v2提交 + 三个不可变 Git 标签 + 一个受保护编排工作流。

发布面（Surface）	不可变标签	公开产物
CLI	`vX.Y.Z`	GitHub Release 与 Homebrew
npm	`npm-vX.Y.Z`	根包与各平台包；`latest`、`canary`、`next`兼容别名
Desktop	`desktop-vX.Y.Z`	签名 GitHub Release、不可变 R2 目录与`latest/latest.json`

三个标签是实现身份（implementation identities），不是用户可选的分发渠道。它们必须始终解析到同一个提交，且绝不允许被移动或删除。从源码看，这一约束同时存在于两处：

本地脚本 scripts/release-stable.sh 在推送前逐一检查三个标签在远端是否已存在，存在即报错退出；
受保护工作流的前置校验 scripts/resolve-stable-release.sh 会重新解析三个标签，任何一个指向不同 SHA 都会立即失败。

Go SDK 模块（sdk/go）独立于三条产品线进行版本管理：其标签形如sdk/go/vX.Y.Z（首个为sdk/go/v1.0.0），指向首次发布对应 Extension Protocol major 版本的发布提交。SDK 标签不会触发产品发布、不会移动、也不改变上述三标签契约。

二、日常发布流程：一个版本号 → 一个 Notes PR → 一条命令 → 一次环境审批

正常开发路径只有一个版本输入、一个待评审 Notes PR、一条终端命令和一次环境审批：

打开 Actions →Prepare release，输入X.Y.Z；
评审并合并自动生成的中英双语 release-notes PR；
在已认证的维护者检出目录中运行：
```
./scripts/release-stable.sh X.Y.Z
```
在release环境中一次性审批产生的Release stable运行；
等待其 postflight 验证 CLI、npm、Desktop、R2、Homebrew 与 changelog。

2.1 版本号与分支的规范校验

Prepare release工作流（.github/workflows/prepare-release-notes.yml）对输入版本做严格正则校验：必须满足MAJOR.MINOR.PATCH三段式语义化版本，否则立即报错退出。它基于main-v2创建/复用release-notes/vX.Y.Z评审分支，并在该分支上运行 scripts/generate-release-notes.mjs 从已合并 PR 元数据生成双语、产品导向的更新日志草稿，随后执行release-notes.mjs validate与单元测试，最后把渲染结果作为 PR 正文。

2.2 本地推送前的全部校验

./scripts/release-stable.sh X.Y.Z（scripts/release-stable.sh）在创建任何公共引用之前，会在失败时中止，除非满足全部条件：

版本号是规范的MAJOR.MINOR.PATCH；
远端main-v2的 HEAD 就是引入或更新完整、已评审 Stable catalog 记录的提交；
该精确提交的main-v2push CI 已成功完成；
vX.Y.Z、npm-vX.Y.Z、desktop-vX.Y.Z三个标签当前全部不存在。

具体到实现：脚本先校验入参与本地依赖（git、gh、jq、node），再用git ls-remote解析远端main-v2的 40 位 SHA，调用 scripts/validate-stable-candidate.sh 验证候选提交：候选必须是可达的 commit、必须存在 first parent，且候选与父提交都包含release-notes/releases.json，最后通过 scripts/validate-stable-release-record.mjs 比对当前与上一版本的记录，确认该版本确实由已评审的 Notes 变更引入。

随后 scripts/verify-release-push-ci.sh 以轮询方式等待ci.yml在该精确 SHA 上的 push 运行成功（默认等待上限 1800 秒、每 10 秒轮询一次；failure/cancelled等结论立即失败退出）。

2.3 一次原子 Git 事务推送三标签

全部校验通过后，脚本执行一次原子推送：

git push --atomic "$remote" \ "$candidate:refs/heads/main-v2" \ "$candidate:refs/tags/v$version" \ "$candidate:refs/tags/npm-v$version" \ "$candidate:refs/tags/desktop-v$version"

关键设计（见 scripts/release-stable.sh）：本次事务同时包含一个no-op 的main-v2更新守卫。如果 CI 运行期间main-v2已经前移，则该 refspec 变成非快进更新，服务器会拒绝整笔事务，三个标签一个都不会被打上——因此"部分标签集"不是正常的失败模式。推送后脚本还会用git ls-remote逐个回读验证每个标签确实解析到候选 SHA。

vX.Y.Z标签事件由 .github/workflows/release-stable-trigger.yml 捕获（仅匹配v*且排除v*-*），并中继触发受保护的 release-stable.yml。标签事件本身是"标签形状"的来源，中继到main-v2上执行，是为了让生产环境的 SignPath 签名策略只信任唯一一个受保护分支名，而不必信任通配符形式的类标签分支。维护者不需要手动派发子级 CLI、npm 或 Desktop 发布器。

2.3.1 补充：Notes PR 无法自动创建时的可恢复交接

如果仓库策略禁止 Actions 打开 Notes PR，工作流仍会推送release-notes/vX.Y.Z分支并打印如下可恢复的手动交接命令：

gh pr create --repo esengine/DeepSeek-Reasonix \ --base main-v2 --head release-notes/vX.Y.Z --fill

注意：不要仅仅因为 PR 创建被拒绝就重新运行 Notes 生成。

三、发布与审批：受保护 Stable 工作流的五段结构

.github/workflows/release-stable.yml 是发布引擎的核心编排器，采用preflight → authorize → signpath-preflight → cli/npm/desktop → postflight的流水线结构：

preflight（校验稳定发布集合）：在受保护的main-v2控制平面检出上，通过 scripts/resolve-stable-release.sh 解析vX.Y.Z、npm-vX.Y.Z、desktop-vX.Y.Z三个标签必须指向main-v2历史中的同一个 SHA；然后对正常候选重新执行 scripts/validate-stable-candidate.sh 与 scripts/verify-release-push-ci.sh，确认候选引入过已评审 Notes 且精确 SHA 的 push CI 通过；再渲染并上传评审过的 release notes 产物，最后运行缓存守卫 scripts/cache-guard.sh。
authorize（唯一人工审批门）：environment: release，这是整个发布流程唯一的 GitHub 环境门禁；preflight 的所有结论被记录为已批准版本、三个标签与 SHA，交给后续各发布器。
signpath-preflight（零发布签名预检）：以signing_preflight: true复用 Desktop 发布工作流，在不产生任何公开发布的前提下验证两个架构与签名阶段，保证正式签名阶段可信。
cli / npm / desktop（并行发布）：分别调用 release.yml、release-npm.yml、release-desktop.yml 复用工作流，三者都 checkout 不可变的已批准标签 SHA。
postflight（公开产物验证）：要求每个被选中的发布器都成功，然后运行 scripts/verify-stable-release-artifacts.sh 验证全部公开渠道，最后发布精确的 Stable release 记录事件并刷新公开 changelog（pages.yml）。

3.1 候选可以滞后于 main-v2

main-v2可以在原子标签事务完成后安全前移，而不会使该候选失效：resolve-stable-release.sh只要求标签 SHA 是main-v2历史的祖先（merge-base --is-ancestor），发布仍针对不可变候选执行。发布器也会在 preflight 阶段由控制平面携带已验证的 release notes 文件，保证恢复场景下也能使用评审过的正文。

3.2 npm 别名的唯一用途

npm 发布器会把latest、canary、next同时推进到同一个官方版本。canary与next保留下来仅为了让历史脚本能继续安装到受支持的构建——它们不是测试渠道，也不对外宣传。postflight 会显式等待npm view reasonix dist-tags.latest等于目标版本（默认最多重试 6 次、间隔 10 秒）。

3.3 无需额外设施

整个发布过程不需要自定义 GitHub App、App 私钥、仓库 Owner 设置变更、手动标签 UI 或子工作流审批——唯一的人工环节就是release环境的一次批准。

四、部分发布失败的恢复

对于部分完成的 Stable 发布，恢复步骤为：

在受保护的main-v2上打开Release stable；
输入已有的vX.Y.Z；
只勾选缺失的发布面（publish_cli/publish_npm/publish_desktop）；
在release环境批准一次。

恢复流程的约束（见 release-stable.yml 的workflow_dispatch输入与 scripts/resolve-stable-release.sh）：

恢复只接受仍然位于main-v2历史中的不可变三标签集合；
必须复用匹配的公开内容，并在校验和、签名、manifest、npm provenance 或 R2 对象冲突时关闭失败（fail closed）；
恢复模式下控制平面仍保持当前main-v2，允许目标为较早的已打标签提交。

绝对不要移动、删除或重建已发布的标签。产品修正应作为更高的 patch 版本发布。

五、已退役的预发布路径

常规 Preview、Canary 与 RC 发布入口已被禁用。历史标签、Releases、包版本、changelog 页面以及最后的桥接端点仍保留以兼容旧客户端，但不会出现在当前下载导航或发布准备流程中。

旧的 CLI 与 Desktop 渠道设置会解析到官方发布线。冻结的 Preview 端点继续把旧客户端引导到桥接构建，桥接构建随后可升级到当前官方发布版本（对应仓库中的 cmd/reasonix-legacy-migrator 与release-notes兼容机制）。

六、cutover 后的首次发布：独立验证清单

对于本次变更后的第一次发布，需要独立证明以下每一项（直到每个公开面都达到终端、已验证状态，否则本次发布视为未完成）：

三个标签解析到已评审 Notes 合并的 SHA；
两个 GitHub Release 都包含完整预期资产（CLI 侧须含SHA256SUMS与 darwin/linux/windows 六个平台的压缩包/zip，Desktop 侧须含latest.json、dmg/deb/tar.gz/installer 及其.minisig签名，具体见 scripts/verify-stable-release-artifacts.sh）；
npm 根包与全部六个平台包报告该 SHA，且latest == canary == next；
R2 不可变目录与 latest manifest逐字节一致，且每个 URL 可用；
Homebrew 与 reasonix.io 显示相同版本；
旧桥接客户端可升级到官方发布版本。

七、源码地图：想深入时看哪里

docs/RELEASING.md：本文依据的权威发布文档；
scripts/release-stable.sh：本地"校验 + 原子推送三标签"入口；
scripts/validate-stable-candidate.sh 与 scripts/validate-stable-release-record.mjs：候选提交与已评审 Notes 记录绑定校验；
scripts/verify-release-push-ci.sh：精确 SHA 的 push CI 轮询验证；
scripts/resolve-stable-release.sh：工作流侧三标签一致性解析（含恢复模式）；
scripts/verify-stable-release-artifacts.sh：postflight 公开产物核对；
.github/workflows/release-stable.yml：受保护编排工作流；
.github/workflows/release-stable-trigger.yml：v*标签事件到受保护控制平面的中继；
.github/workflows/prepare-release-notes.yml 与 scripts/generate-release-notes.mjs：双语 Notes 生成与评审 PR；
.github/workflows/release.yml、release-npm.yml、release-desktop.yml：三个发布面的复用工作流。

总结

DeepSeek-Reasonix 的发布体系把"不可变性"与"原子性"贯彻到了每一次发布中：三个标签永远指向同一提交、一次git push --atomic保证要么全有要么全无、唯一受保护编排器集中所有门禁、恢复路径只接受留在main-v2历史中的既有标签。日常发布只需"一个版本号、一个 Notes PR、一条命令、一次审批"，而 cutover 后的首次发布则要求对 CLI、npm、Desktop、R2、Homebrew 与 changelog 做全量独立验证——这正是把发布从"手工操作"升级为"可审计、可恢复的工程流程"的关键。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考