oh-my-codex 0.20.2 发布就绪记录：冻结提交盘点、发布门禁与不可变版本验证全解析

导读

本文基于 oh-my-codex 仓库中的 发布就绪记录，完整还原 0.20.2 补丁版本从冻结候选、提交盘点、本地质量门禁、评审、CI、打标签、npm 发布到公共注册表安装验证的全链路发布治理流程。读完本文，你将掌握该项目的发布就绪记录（Release Readiness Record）如何组织证据、如何用一条 git 命令复现 22 个冻结提交的精确清单、8 项发布门禁分别验证什么，以及"不可变 tag + 事后前向纠错"的版本治理原则。文中所有门禁命令均可在仓库 package.json 与 CI 脚本中逐一找到对应实现，可作为任何想为自身项目建立可审计发布流程的工程师的参考样板。

---

一、发布就绪记录：从预打标签声明到发布后对账

docs/qa/release-readiness-0.20.2.md 这份记录的生命周期在文档开篇即被明确：它始于冻结候选 0.20.2 的预打标签（pre-tag）声明，随后不断追加证据，最终在 2026-07-16 收录了本地构建、独立评审、CI、npm 公开发布、公共注册表安装以及发布后证据对账（post-publish reconciliation）的完整闭环证据。

这种"先声明、后对账"的模式与仓库中其他发布记录一脉相承（见 docs/qa 下从 0.8.1 到 0.21.2 的系列 release-readiness-*.md），其核心目的有二：

1. 冻结版本边界：在打 tag 前把"哪些提交算作本次发布"钉死，防止后续开发提交混入发布范围；
2. 证据可审计：每一项门禁都有可验证的证据落点，而不是一句"已通过"的空话。

值得注意的仓库约定（可从 CHANGELOG.md 中 0.20.2 条目的 "Verification" 一节印证）：changelog 本身不宣称任何本地门禁、评审、CI、tag、GitHub release 或 npm 发布结果，这些断言全部集中在发布就绪记录中——即"证据单一来源"原则。这也解释了为什么本文讨论的记录文档是所有门禁状态的唯一权威出口。

---

二、版本身份与冻结范围：22 个提交、20 个合并 PR

记录首先定义版本身份（Release identity）：

• 发布类型：0.20.2（patch 补丁版本）
• 发布日期：2026-07-16
• 前一个 tag：v0.20.1
• 冻结开发基（frozen dev base）：f5e4753135ebc86342e7353300ac3ec5d9ae3d8d
• 精确比较范围：v0.20.1..f5e4753135ebc86342e7353300ac3ec5d9ae3d8d
• 预期范围清单：22 个提交——20 个合并 PR、1 个发布开发准备提交、以及 #3129 发布配套（release collateral）的直接分支提交与合并提交
• 兼容性声明：无有意的 CLI 破坏性变更或 package 布局变更

2.1 用一条命令复现冻结清单

记录给出了可复现范围清单的权威命令：

git log --reverse --format='%H%x09%s' v0.20.1..f5e4753135ebc86342e7353300ac3ec5d9ae3d8d

这条命令以 --reverse 按时间正序输出范围内每个提交的完整 SHA 与主题行，%x09 输出 Tab 分隔符。记录明确要求：清单任何不一致都会阻断发布准备（Any mismatch blocks release preparation）——这是发布治理的第一道硬门禁。

2.2 冻结提交清单逐条解读

记录给出了 22 个提交的完整清单表。按"发布处置"（Release disposition）列可以清晰分成四类：

发布配套（inventory only，不构成产品头条）

提交	分类	说明
c628486896ffa8b9188335b91a76192571e32c9d	#3129 直接分支提交	0.20.1 证据对账
fce27bfd6c17c7665a6f1505b6b8384cc2c8edd5	#3129 合并提交	提升 0.20.1 证据对账结果

发布准备（不构成产品头条）

提交	分类	说明
29bdeb5c5670c133d9f2feda7512ee01e80a63d5	直接提交	启动 0.20.2 开发与版本元数据同步

依赖升级（dependency）

提交	依赖变化
90601c96fca7a69bd65c25e0b66316e188672eb0	TypeScript 6.0.3 → 7.0.2（#3155）
c5f03c3498186bee4d6a97099a43435889ede428	actions/setup-node 6 → 7（#3154）
d6e0349f5aed7ce4702c6c1dbb22190f16862fdf	@biomejs/biome 2.5.2 → 2.5.3（#3157）
9f4f8f09bd2f098c4cbe56ae4798dfbfb7085666	@types/node 26.1.0 → 26.1.1（#3156）

产品功能与修复（product headline）：其余 16 个提交，对应 #3136、#3158、#3164、#3165、#3152、#3168、#3169、#3172、#3151、#3166、#3179、#3140、#3180、#3183、#3184，详见下一节。

关联问题 #3118、#3133、#3162、#3163、#3175、#3177、#3181 属于问题单而非额外 PR，不应重复计数。全部合并 PR 集合为：#3129、#3136、#3140、#3151、#3152、#3154、#3155、#3156、#3157、#3158、#3164、#3165、#3166、#3168、#3169、#3172、#3179、#3180、#3183、#3184。

---

三、0.20.2 的产品变更全貌（结合源码佐证）

发布说明 docs/release-notes-0.20.2.md 与 CHANGELOG.md 中的 [0.20.2] 条目共同构成了对冻结提交的语义化解释。按主题归类如下。

3.1 认证 Ralplan 引导（#3184；issue #3181）

变更内容：全新认证的 App 领导者可以在其第一轮会话内写入 Ralplan 角色意图（role intent），具备持久化领导者证明（durable leader attestation）、原子 tracker 加锁的意图发布（atomic tracker-locked intent publication）、单飞行为（single-flight）、重启恢复，以及在歧义情况下对 subagent/来源证明检查的 fail-closed 处理。

源码佐证：仓库中 src/ralplan/documented-leader-preflight.ts 完整实现了这一能力的 fail-closed 拒绝路径——当无法验证"文档化、非用户可伪造的根身份"时，返回常量 UNSUPPORTED_DOCUMENTED_LEADER_PROOF = 'unsupported_documented_leader_proof'，并在 PreToolUse 阶段以 permissionDecision: 'deny' 拒绝适配的 Ralplan 命令（documented-leader-preflight.ts）。相关的端到端测试位于 role-intent-bootstrap-e2e-3181.test.ts 与 ralplan-bootstrap-3181.test.ts。

重要状态提示（ADR 3212，适用于上述权威性声明）：按发布记录与 CHANGELOG 中一致保留的 supersession 说明，本地领导者证明与适配角色意图不再授权；类型化路由/tracker 证据仅作为生命周期/诊断用途。在 role_routing_unavailable 的适配 Ralplan 权威尝试中，已安装的角色意图/预检会以 unsupported_documented_leader_proof 失败关闭；缺少官方宿主收据时，共识以 documented_host_consensus_receipt_unavailable 不可用。相关 ADR 背景见 docs/adr/3194-codex-01445-documented-leader-proof.md 与 docs/adr/3212-same-user-native-child-auth-boundary.md。

3.2 原生 subagent 与 hooks（#3152、#3166、#3180；issue #3118）

• App spawn_agent 路由遵循表面感知的角色契约（surface-aware role contract）；
• 适配角色 tracker 证据与路由标记事务性绑定，崩溃后可恢复，并清理被遗弃的跨进程锁工件（#3166）；
• 被识别的原生子代理可以停止而不产生自动 nudge（#3180）。

这与文档 docs/contracts/ralph-cancel-contract.md 系列契约所强调的"显式终止语义"方向一致：停止动作应由用户明确发起，而非系统自动推送。

3.3 来源证明、通知与状态隔离（#3168、#3165、#3158、#3172）

• 并发聊天隔离（#3168）：prompt 会话来源证明（provenance）在并发聊天之间相互隔离，避免会话身份串扰；
• 跨进程通知去重（#3165；issue #3162）：fallback 通知投递跨进程去重；
• 规范 Ralplan 会话状态（#3158）：Ralplan 终态状态保持挂在规范会话上，拒绝歧义会话别名；
• 陈旧过渡镜像拒绝（#3172）：外部陈旧的 workflow-transition 镜像不能改写当前工作流状态——对应 src/state/workflow-transition.ts 中状态机写入路径的边界防护。

3.4 Setup、Team 与状态安全（#3164、#3136）

• 持久化显式 AGENTS.md 合并策略（#3164；issue #3163）：setup 在多次刷新之间持久化根级本地 AGENTS.md 合并策略，同时保留"缺失即语义"（absence semantics）与瞬态 --force 行为；
• 显式 Team worker 策略（#3136）：tmux 启动前校验并遵守显式 worker 策略。仓库中 src/team/tmux-session.ts 的 TeamTopology 结构体保留了 workerCount、workerPaneIds、leaderPaneId、teamPaneOwnerId 等字段，从中可以看出 worker 槽位、leader 面板归属与清理权限的强约束设计。

3.5 其他修复（#3140、#3179、#3151、#3169、#3183）

• 显式工作流调用要求（#3140；issue #3133）：工作流激活必须由提示词开头的显式调用触发，杜绝来自引用、否定、文档化、畸形、fenced 或其它非调用文本的误激活；
• 认证 deep-interview 终态写入（#3179；issue #3177）：认证会话的终态写入被接受；
• 外来 Codex hook 坐标保留（#3151）：setup/refresh/doctor/uninstall 全程保留外来 Codex hook 坐标，不认领、不删除；
• BOM 前缀状态输入（#3169）：接受 BOM 前缀的状态输入文件，增强跨平台兼容性；
• tmux 属主 detached 面板环境保留（#3183；issue #3175）：detached 面板保留 tmux 属主的终端环境变量值。

---

四、发布门禁体系：八道关卡逐项拆解

发布记录用一张门禁表（Required gates）汇总了从代码冻结到公共注册表可安装的全部关卡。下表为原记录完整继承：

门禁	证据	状态
配套/范围评审	冻结的 22-commit 范围、全部 20 个合并 PR、分类、亮点、贡献者与 compare 链接在 CHANGELOG.md、docs/release-notes-0.20.2.md、RELEASE_BODY.md 与本记录间一致	本地通过
发布范围评审	候选变更为四个发布配套文件加上既有测试中六处 Darwin 可移植性修正：doctor 警告路径、resume stat 可移植性/UTC、setup hook 信任路径与已安装 Codex 边界跳过、规范化适配角色/tracker cwd 期望。版本元数据保持 0.20.2 同步；不含任何依赖、lockfile、工作流或产品运行时源码变更	本地通过
本地质量门禁	见 4.1 节命令清单	本地通过
评审	Ultragoal 清理零阻断发现；Architect 评审对架构/产品/代码返回 CLEAR 与 APPROVE；executor QA/red-team 针对候选提交 2e666461d4147fa4718691f7b4d9a1a282380f16（tree ef2acf5f20327d23742e8b08827b46802c39751c）通过	通过
CI	dev CI 与 main CI 对精确发货提交 2e666461d4147fa4718691f7b4d9a1a282380f16 均成功	通过
Tag 与发布	注解 tag 对象 4332cc6418430e8cdfc0769bf52e7ecbdfe08afd peel 到发货提交 2e666461d4147fa4718691f7b4d9a1a282380f16；发布工作流完成全部七个原生构建、资产发布/验证、packed-install smoke 与 npm 发布	通过
npm 发布	npm view oh-my-codex@0.20.2 返回版本 0.20.2、tarball 地址与完整性校验 sha512-f48bqkK3UX4D2VfKimiqVpbYV+rqim7jJM6KDI/+gzpKzLtnwNTyc06whrkWBqlah0Tg87rX5rG8mkPcGzoZGQ==	通过
公共注册表安装	从 npm 安装 oh-my-codex@0.20.2 到隔离前缀 /private/tmp/omx-public-install-0.20.2；omx --version 在 Darwin arm64 报告 oh-my-codex v0.20.2，omx --help 输出非空，npm ls -g --prefix ... --json 解析出精确版本 0.20.2；npm 本地 allow-scripts 策略跳过了非关键 postinstall 生命周期，但 CLI 仍成功启动	通过

4.1 本地质量门禁：从 package.json 到 Cargo workspace

记录列出的本地质量门禁命令，逐一对应仓库 package.json 的 scripts 与 Cargo.toml workspace：

命令	作用（对应 package.json script）
npm run build	tsc 编译 TypeScript 到 dist/ 并设置 omx 可执行位
npm run build:full	全量构建：TS + explore-harness + sparkshell + API
npm run sync:plugin:check	校验插件镜像同步（sync-plugin-mirror.js --check）
npm run check:no-unused	基于 tsconfig.no-unused.json 的未使用代码检查
npm run lint	biome lint src
npm test	383 个编译测试文件全量执行
cargo fmt --all --check	Rust workspace 格式检查
cargo clippy --workspace --all-targets -- -D warnings	Rust 静态检查，warning 即失败
cargo test --workspace	Rust 全 workspace 单元/集成测试
npm run smoke:packed-install	打包安装冒烟（smoke-packed-install.js）

其中 packed-install smoke 有一个容易被忽略的细节：因为工作站默认的 Codex 可执行文件是 0.142.3，冒烟测试使用了隔离的 @openai/codex@0.142.5 可执行文件来保证边界版本一致。这一"版本钉死"的实践在源码中得到印证：src/scripts/smoke-packed-install.ts 中定义了 PINNED_CODEX_VERSION = '0.142.5' 与 PINNED_CODEX_VERSION_OUTPUT = codex-cli 0.142.5，确保冒烟测试面对的是精确已知的 Codex 行为边界（smoke-packed-install.ts）。

4.2 评审与 CI：双层独立验证

• 独立评审链：Ultragoal 清理 → Architect 评审（CLEAR/APPROVE）→ executor QA/red-team，全部绑定到精确候选提交/树；
• CI 双线验证：dev 与 main 两条分支线都对精确发货提交 2e666461d4147fa4718691f7b4d9a1a282380f16 成功，排除"发布与分支线漂移"的风险。

4.3 Tag 与 npm 发布：不可变锚点 + 完整性校验

• 注解 tag 对象 4332cc6418430e8cdfc0769bf52e7ecbdfe08afd peel 到与 CI 验证完全一致的提交，形成"代码 → tag → 发布资产"的单链锚定；
• npm 侧通过 npm view 校验版本、tarball 与 integrity（sha512 校验和），再以隔离前缀（/private/tmp/omx-public-install-0.20.2）模拟全新用户安装，验证 omx --version、omx --help 与精确依赖解析。即便 npm 的 allow-scripts 策略跳过了非关键 postinstall 生命周期，CLI 也能正常启动——这验证了包对 postinstall 副作用零依赖。

---

五、外部证据要求：不可变发布与事后纠错的分工

记录明确划分了两类证据的存放策略：

• 稳定公共证据：CI 运行、不可变 tag、GitHub release、发布工作流、npm 包元数据与注册表 tarball，均在记录中以链接给出（本文不展开外部链接，可对照原记录查阅）；
• 本地可验证证据：本地验证、清理与独立评审绑定到 Ultragoal 账本（ledger）中的精确候选提交/树；
• 发布后纠错原则：发布后的修正使用正常前向提交（forward commits），绝不改写不可变 tag。这也解释了上一节中"当前 main 分支线 = 候选提交 + 前向发布证据修正"的表述：当前 main 血统是该候选提交后仅跟随前向发布证据修正；当前 dev 血统是该候选提交后跟随 0.20.3 开发基提升与对应前向证据修正。 分支尖端的 CI 状态在 Ultragoal 完成前由外部核实，而不是在本文件中嵌入自指提交哈希——避免记录文件自身产生自我引用循环。

---

六、发布说明、Changelog 与贡献者

0.20.2 的三份对外/对内文本分工明确：

文件	定位
docs/release-notes-0.20.2.md	面向产品的发布说明：亮点、修复清单、依赖与范围清单、兼容性、验证状态、贡献者
RELEASE_BODY.md	GitHub 发布正文模板
CHANGELOG.md	变更日志条目，只陈述变更事实，不断言门禁结果

提交证据识别出的贡献者包括 Bellman（@Yeachan-Heo）、@cristph、@terwox 与 @dependabot[bot]——其中依赖升级提交由 dependabot 机器人完成，与 4 个依赖 bump 提交一一对应。

---

七、结语：一份可复用的发布治理样板

从 0.20.2 发布就绪记录可以提炼出这套流程的三个关键设计：

1. 先冻结、后验证：以精确 commit 范围（v0.20.1..f5e475...）冻结发布边界，任何清单不一致直接阻断；
2. 证据单一来源 + 分层门禁：changelog 不断言门禁结果，发布就绪记录是唯一权威出口；本地质量门禁（TS/Rust 双栈 + packed-install smoke + 钉死的 Codex 边界版本）、独立评审、双线 CI、不可变 tag、npm 完整性校验、隔离前缀公共安装六层递进；
3. 不可变与纠错分离：tag 一旦创建即不可变，发布后问题一律走前向提交修正，保证任何历史发布都可被精确复现与审计。

对于希望为自身项目引入"可审计、可复现、可回滚"发布流程的工程团队，docs/qa/release-readiness-0.20.2.md 连同其后的 0.20.x–0.21.x 系列记录，就是一套可以直接借鉴的完整范本：记录的每一条断言，最终都能在 CHANGELOG.md、docs/release-notes-*.md、package.json scripts 与 Rust workspace 构建配置中追溯到具体落点。