oh-my-codex 0.18.2 发布就绪审计：从问题闭环、验证门禁到 CI 发布证据的完整技术复盘

本文以 oh-my-codex 的 v0.18.2 发布就绪审计文档（docs/qa/release-readiness-0.18.2.md）为主体，完整复盘一次真实补丁版本发布的全过程：如何冻结版本比较范围、审计自上个版本以来关闭的全部 GitHub Issue、逐条核对合并 PR 证据，以及如何在发布前完成本地验证门禁、CI 流水线验证与 npm/GitHub 双通道发布证据采集。读者读完可以掌握一套可直接复用的"发布就绪清单"方法论，并将其与仓库中实际的发布协议脚本、原生 Agent 校验脚本和回归测试集一一对应。

一、发布范围冻结：先锁定 diff，再写发布说明

v0.18.2 的发布就绪审计首先做的是范围冻结，这是整个发布流程的起点。审计文档明确记录了三个关键引用：

• 上一个发布标签：v0.18.1（提交 8f460a0aa353873ea567de4fd00bd1cc84379d9c，创建于 2026-05-21T04:44:28Z）
• 发布元数据提交前的候选引用：dev / origin/dev 分支上的 5bc15d4b613237c97635e525243d5c326f3434fa
• 本次发布标签：v0.18.2

发布比较范围被精确定义为 v0.18.1..dev（发布晋升前）与 v0.18.1..v0.18.2（打标签后）。这与仓库根目录的 RELEASE_PROTOCOL.md 第 1 节"Freeze the release range before writing notes"完全一致：发布协议要求先用 git merge-base --is-ancestor 验证上一标签是候选引用的祖先，再用 git log 精确提取比较范围内的提交与 PR 编号，最后用 gh pr list 交叉核对，确保每个合并提交都在发布说明中有据可查，或被明确标记为仅内部变更。

这一做法的核心意图（见 RELEASE_PROTOCOL.md 开头声明）是防止发布说明、变更日志和 GitHub Release 正文少报实际发布范围——即不能只写"最后修的阻塞问题"，而必须覆盖整个比较范围内的全部变更。

二、Closed Issue 审计：用合并证据区分"已修复"与"不计划处理"

范围冻结后，审计文档给出了自 v0.18.1 以来的 Closed Issue 审计表。筛选条件为：createdAt > 2026-05-21T04:44:28Z 且 state = CLOSED 的 GitHub Issue。

Issue	关闭原因	合并证据	发布处置
#2428	NOT_PLANNED	无需合并	范围过宽而关闭；要求拆分更窄的后续任务
#2429	COMPLETED	PR #2431	已包含
#2430	COMPLETED	PR #2432	已包含
#2433	COMPLETED	PR #2434	已包含
#2435	COMPLETED	PR #2436	已包含
#2438	COMPLETED	PR #2439	已包含
#2440	COMPLETED	PR #2442	已包含
#2443	COMPLETED	PR #2447	已包含
#2445	COMPLETED	PR #2448	已包含
#2449	COMPLETED	PR #2450	已包含
#2451	COMPLETED	PR #2452	已包含
#2453	COMPLETED	PR #2455	已包含
#2456	COMPLETED	PR #2457	已包含
#2460	COMPLETED	PR #2461	已包含
#2462	COMPLETED	PR #2463	已包含
#2465	NOT_PLANNED	无需合并	由贡献门禁关闭，非 0.18.2 执行轨道合并
#2466	COMPLETED	PR #2467	已包含
#2468	COMPLETED	PR #2469	已包含
#2470	COMPLETED	PR #2471	已包含

这张表的审计价值在于**"关闭"不等于"已修复"：审计按 GitHub 的关闭原因区分两类 Issue，只有 COMPLETED 且能对应到合并 PR 的才计入发布范围，NOT_PLANNED 的（#2428、#2465）被明确排除在合并声明之外。这一点在文档末尾的"Known gaps"一节再次强调：这两个 Issue 被有意列入审计表，是为了让发布不声称**它们已被合并。

对应的官方发布说明 docs/release-notes-0.18.2.md 用紧凑形式复述了同一份审计结果（#2429→#2431、#2430→#2432 …… 的 Issue→PR 映射），并单独列出 #2428 与 #2465 两个非执行轨道关闭项，两份文档互为印证。

三、合并 PR 清单：0.18.2 实际携带的变更全貌

审计文档列出了本次发布比较范围内的 21 个合并 PR，覆盖插件诊断、Autopilot 可观测性、tmux/HUD、madmax 锁、通知风暴、Ultragoal 恢复等多个模块：

• #2415 — 新增 clean-room Prometheus Strict planner
• #2427 — 防止 deep-interview 隐式交接实现
• #2431 — 修复 doctor 插件钩子诊断
• #2432 — 修复 autopilot 链状态可观测性
• #2434 — 修复 tmux 3.2a HUD resize 钩子注册
• #2436 — 修复 madmax 独立启动的分离锁身份
• #2437 — feat(prometheus-strict)：以 omx question 路由重建规范表面
• #2439 — 修复团队启动直接触发证据门禁
• #2442 — 向 tmux HUD 监视窗格转发 OMX_ROOT
• #2447 — 保护 autopilot ralplan 共识交接（评审修复）
• #2448 — 在原生子代理中抑制工作流关键词状态（评审修复）
• #2450 — 隔离团队停止状态
• #2452 — 修复 madmax 分离锁过期失效
• #2455 — 使 ralplan 交接文档与 Ultragoal 默认值对齐
• #2457 — 约束 notify dispatcher 回合结束风暴
• #2461 — 保持 tmux HUD 窗格限定于 leader 会话
• #2463 — 澄清 madmax 同目录锁诊断
• #2467 — 修复缺少目标存储时的 ultragoal get_goal 恢复
• #2469 — 澄清研究规划边界
• #2471 — 修复项目作用域启动的原生钩子重复与信任状态丢失
• #2472 — 在 HUD 中显示 Ultragoal 进度并收紧评审后续

从这些 PR 可以归纳出 0.18.2 的四大用户可见变更（与 docs/release-notes-0.18.2.md 的 Highlights 一一对应）：

1. 后 0.18.1 封闭缺陷列车全部合并：doctor/plugin 钩子诊断、Autopilot 链可见性、tmux/HUD/madmax 回归、团队 Stop 泄漏、通知回合结束风暴、Ultragoal 目标存储恢复、研究规划措辞、项目作用域原生钩子重复等全部包含。
2. Prometheus Strict 作为配方工作流可用：planner 表面现在具备 omx question 路由、原生 Agent 定义、目录条目、插件镜像与 dogfood 文档。对应的实战证据见 docs/recipes/prometheus-strict/dogfood-2026-05-22.md，其中用"trivial / simple / architecture"三个场景记录了 omx question 调用次数、每轮问题数、吸收计数与扇出策略；需要说明的是，该配方文档同时声明 $prometheus-strict 并非随包交付的规范技能（见 docs/recipes/prometheus-inspired-deliberation.md 的 Boundaries 节）。
3. HUD 中可见 Ultragoal 进度：长时工作流中展示活动持久目标进度与评审后续状态。
4. 工作流交接更显式：deep-interview 保持需求边界、Autopilot 记录持久阶段状态、ralplan 共识要求 Architect/Critic 证据、ralplan 示例默认以 Ultragoal 做持久执行。

四、本地验证门禁：发布前必须跑通的全部检查

发布就绪文档记录了发布晋升前完成的本地验证门禁清单，这是判断候选提交是否可发布的关键判据：

检查项	结果
npm run build	PASS
npm run verify:native-agents	PASS（21 个可安装原生 Agent，36 个 setup 提示资源）
npm run verify:plugin-bundle	PASS（在 npm run sync:plugin 将插件元数据更新到 0.18.2 之后）
净化环境下的 npm run test:recent-bug-regressions:compiled	PASS（627 个测试）
聚焦回归测试组（HUD authority、notify-fallback-watcher、notify-dispatcher、ultragoal artifacts、codex-plugin-layout、setup-install-mode、keyword-detector、team runtime）	PASS（436 个测试）
node --test dist/scripts/__tests__/notify-dispatcher.test.js	PASS（15/15）
npm run sync:plugin:check	PASS
cargo check --workspace	PASS
npm pack --dry-run --json	PASS（产出 oh-my-codex-0.18.2.tgz，entryCount=2893，unpackedSize=21598080，无 .omx 包泄漏）
git diff --check	PASS
发布正文生成器 + 本地注解标签	PASS（生成的正文含 Contributors 与 v0.18.1...v0.18.2 changelog 链接）
$code-review 终审	APPROVE / CLEAR（code-reviewer APPROVE；architect CLEAR）

其中有两个非常值得借鉴的工程细节：

1. 环境净化重跑：首次未净化环境的回归测试失败，原因是在跑的 OMX 运行时 OMX_ROOT 污染了临时根目录的团队测试；使用 env -u OMX_ROOT -u OMX_STATE_ROOT -u OMX_SESSION_ID -u CODEX_SESSION_ID -u SESSION_ID npm run test:recent-bug-regressions:compiled 清除环境变量后重跑即通过（627 个测试）。这提醒我们：CI 与本地环境不一致时，环境变量本身就是测试污染源。
2. 聚焦门禁真的抓到过缺陷：那组 436 个测试的聚焦回归门禁此前暴露过一个真实的慢分发合并缺口，发布候选通过"完成锚定的身份作用域合并 + 清理"修复了它，并保留了净化重跑记录——说明这条门禁不是走过场。

这些命令都能在 package.json 的 scripts 中找到对应实现。以 verify:native-agents 为例，其底层脚本 src/scripts/verify-native-agents.ts 会逐一校验每个可安装原生 Agent 的 TOML 结构：name/description/model_reasoning_effort 必须与定义一致、developer_instructions 必须非空、必须包含 ## OMX Agent Metadata 元数据块与 role/posture/model_class/routing_role 字段，并且按"是否允许委派"强制施加或禁止 <native_subagent_leaf_guard> 防递归守卫；同时校验提示文件必须已被目录收录、插件清单不得越界持有 agents/prompts。

五、CI 与发布证据：dev → main → 标签 → npm 的完整链路

文档记录了晋升与发布的完整证据链，三个 GitHub Actions 运行 ID 可复现对应阶段的 CI 状态：

1. dev CI（候选提交 29e87a24a0ed354283604bfc1ba995d1245813c4）：PASS，运行 ID 26334978724。
2. main CI（fast-forward 合并到同一提交后）：PASS，运行 ID 26335226535。
3. v0.18.2 发布工作流（标签 29e87a24a0ed354283604bfc1ba995d1245813c4）：PASS，运行 ID 26335367646。首次尝试在 Build native (aarch64-unknown-linux-gnu) 阶段出现瞬时 checkout 凭据失败，重跑失败任务后工作流完整成功。

发布终态核实：

• GitHub Release：v0.18.2 已发布，非 draft、非 prerelease，目标分支 main，附带 57 个资产，包括 native-release-manifest.json 及原生归档/校验和。
• npm 发布：npm view oh-my-codex version dist-tags --json 返回版本 0.18.2 且 latest: 0.18.2。
• 最终分支/标签状态：origin/main、origin/dev、本地 HEAD 与标签 v0.18.2^{} 均指向 29e87a24a0ed354283604bfc1ba995d1245813c4。

文档还特别附了一条发布后修正说明：CI 与发布证据一节是在 npm 发布完成后，用最终证据替换发布前占位符而补写的；已发布的 npm provenance 标签没有移动，这次纯文档修正会让 main/dev 在修正晋升后领先于发布标签。这与 RELEASE_PROTOCOL.md 第 6 节"Post-publish corrections"的约定一致：不移动已发布的 npm provenance 标签（除非发布产物本身失效且维护者明确选择紧急重打标签），修正只走 dev → 正常 CI → main 通道，并记录在就绪文档中。

六、发布正文生成器：从模板到带 Contributors 的 Release Body

发布就绪文档中的一项关键验证是运行发布正文生成器：

node dist/scripts/generate-release-body.js \
  --template RELEASE_BODY.md \
  --out /tmp/RELEASE_BODY.generated.md \
  --current-tag v0.18.2 \
  --previous-tag v0.18.1 \
  --repo Yeachan-Heo/oh-my-codex

其实现位于 src/scripts/generate-release-body.ts，核心逻辑包括：解析 --current-tag/--previous-tag 参数（也可从 GITHUB_REF_NAME 或 git describe --tags --exact-match 推断当前标签）、按语义版本排序标签列表并验证前一标签确实是当前标签的祖先（verifyCompareRange）、调用 GitHub compare API 收集提交作者以生成 Contributors 名单、最后套用 RELEASE_BODY.md 模板输出正文。审计要求生成的正文必须保留全部主要比较范围变更、包含正确的 **Full Changelog** 行，且 Contributors 名单要对照合并 PR 作者人工复核，不能盲信仅由 shortlog 生成的名单（RELEASE_PROTOCOL.md 第 3 节）。

七、已知差距：诚实披露 NOT_PLANNED 项

文档以"Known gaps"收尾，明确列出：

• #2428 与 #2465 以 NOT_PLANNED 关闭，不是已完成的修复。它们被有意列入审计表，以确保发布不声称这两个 Issue 已被合并。

这种"把未完成项也写进发布审计"的做法，保证了发布文档的事实边界：读者可以据此区分"本次发布真正修复了什么"与"只是被关闭但从未合入"。

八、总结：0.18.2 发布就绪方法论的可复用要点

纵观 docs/qa/release-readiness-0.18.2.md，这次发布审计给出了一个可复用的发布就绪闭环，与 RELEASE_PROTOCOL.md 第 7 节"Stop condition"完全呼应——一个发布只有在以下条件全部成立时才视为完成：

1. main 与发布标签指向预期发布提交，dev 要么仍指向该提交，要么只包含已记录的发布后修正 + 下一个开发基础版本号提升；
2. 范围冻结先行——先用 v0.18.1..dev 锁定比较范围，所有发布说明基于比较范围清单而非记忆；
3. Issue 审计按关闭原因区分 COMPLETED（要求 PR 证据）与 NOT_PLANNED（明确披露），杜绝"关闭即修复"的误报；
4. 本地验证覆盖构建、原生 Agent 结构、插件捆绑、回归测试（含净化环境重跑）、Rust workspace 与打包干跑，并保留真实的失败-修复-重跑记录；
5. CI 证据覆盖 dev、main 与发布标签三个阶段的运行 ID，发布终态通过 GitHub Release 资产、npm dist-tags 与分支/标签哈希三方核实；
6. 发布后修正走独立通道且不动 provenance 标签，并在原就绪文档中留痕。

这套流程不仅适用于 oh-my-codex 自身，也可以作为任何"问题驱动型"开源项目补丁版本发布的质量门禁模板。读者若想继续深入，可对照 docs/qa/release-readiness-0.18.2.md、docs/release-notes-0.18.2.md、RELEASE_PROTOCOL.md 三份文档，以及 package.json 中对应的验证脚本逐一演练。