企业官网建设流程全解析

oh-my-codex 0.20.3 发布就绪记录解析：从冻结提交范围到门禁与发布序列的完整实践

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

导读

本篇技术文章以 oh-my-codex 仓库中v0.20.3的发布就绪记录（docs/qa/release-readiness-0.20.3.md）为骨架，系统讲解一次 patch 版本发布从“冻结提交范围”、“必过门禁”、“已知缺口”到“发布序列”的完整操作实践。读完本文，你将掌握：如何用git merge-base与git log精确界定发布范围并交叉核对 PR 清单；如何用generate-release-body.js生成并校验 GitHub 发布正文；如何在本地门禁与 CI 门禁之间划分职责、记录环境性测试缺口；以及如何按RELEASE_PROTOCOL.md完成 tag、npm 发布与 dev 分支回填。文中所有关键结论均可回到本仓库源码与发布协议中逐条验证。

发布身份：一次带新增特性的 patch 发布

0.20.3是一个patch 版本，发布于 2026-07-19。它的核心特征在记录的开头被一次性写清：

• 版本类型：patch，且“包含一个附加的、向后兼容的特性”（PR #3143）；
• 前一 tag：v0.20.2；
• 冻结开发基线：f967cfed64ec57614af136f75d7cb81509808f7e；
• 精确比较范围：v0.20.2..f967cfed64ec57614af136f75d7cb81509808f7e；
• 范围规模：99 个提交——13 个已合并的产品 PR、4 个 v0.20.2 发布后证据修正、1 个发布开发准备提交，以及 PR #3153、#3196、#3215、#3217、#3218 的 squash 化组成提交；
• 兼容性声明：没有有意的破坏性 CLI 或包布局变更。

值得注意的细节是“版本元数据同步”：发布准备提交4b557d13会同步package.json与Cargo.toml中的版本元数据。这一点在当前仓库中可以验证——package.json 与根 Cargo.toml 中版本号始终保持一致（当前 dev 基线为0.21.2），这正是 RELEASE_PROTOCOL.md 第 5 节要求“立即将 dev 元数据 bump 到下一个开发基线版本”的结果。

冻结范围与再基线：为什么范围会从 90 个提交变成 99 个

发布记录专门写了一节Re-baseline note，解释范围漂移的处理方式：

1. 第一遍冻结基线为a03da9c0（90 个提交）；
2. 在发布前，origin/dev推进到f967cfed，新增了 9 个提交（PR #3143、#3215、#3217、#3218）；
3. 由于a03da9c0仍是f967cfed的祖先（没有分叉），整个范围与所有 collateral（发布配套物）被重新基线到当前 tip。

这里有一个关键教训：第一遍审查中发现的 ralplan 门禁诊断措辞回归，已在 #3218 中于上游修复，因此发布中不需要携带任何本地测试修改。这说明发布就绪记录不是静态快照，而是会随上游推进动态再基线的“活文档”。

用命令复现提交清单

发布记录给出了精确的可复现命令：

git log --reverse --format='%H%x09%s' v0.20.2..f967cfed64ec57614af136f75d7cb81509808f7e

输出结果必须与下述清单完全一致，任何不匹配都会阻塞发布准备：

• 已合并产品 PR 集：#3135、#3143、#3153、#3186、#3187、#3191、#3192、#3196、#3201、#3211、#3215、#3217、#3218；
• 关联 issue（非额外 PR）：#3121、#3127、#3181、#3194、#3195、#3199、#3203、#3204。

完整清单存于 docs/release-notes-0.20.3.md 与artifacts/release-0.20.3/inventory.md（提交级分类）。在 CHANGELOG.md 的[0.20.3] - 2026-07-19一节同样保留了这份 PR 清单。

必过门禁：一张表讲清“本地 vs CI vs 发布期”

发布记录用一张门禁表定义了本次发布的证据边界，这张表是整个记录的骨架，逐条复述如下：

这张表揭示了一个设计原则：发布就绪记录只对“现在能证明的事”给出 Passed，把 CI、tag、npm 发布等外部证据标记为 Pending，等发布序列完成后回填。这正是 CHANGELOG.md 中“本变更日志不断言任何超出该记录所记载的 CI run、tag、GitHub 发布或 npm 发布结果”的原因。

release-body 生成：证据而非记忆

RELEASE_PROTOCOL.md 第 2 节明确要求“发布 collateral 必须基于 compare-range 清单，而不是基于发布评审中最后修复的 blocker”。第 3 节进一步规定：RELEASE_BODY.md是模板，由dist/scripts/generate-release-body.js消费，tag 推送前必须运行：

node dist/scripts/generate-release-body.js \ --template RELEASE_BODY.md \ --out /tmp/RELEASE_BODY.generated.md \ --current-tag "$NEXT" \ --previous-tag "$PREV" \ --repo Yeachan-Heo/oh-my-codex

硬性要求包括：模板必须包含## Contributors；生成的正文必须包含全部主要 compare-range 变更与正确的**Full Changelog**行；贡献者列表必须对照合并 PR 作者复核，不能盲目接受被 release-prep 提交扭曲的 shortlog 生成名。脚本本体位于 src/scripts/generate-release-body.ts。

已知缺口：把“本地失败”与“版本回归”区分开

发布记录最值得工程团队借鉴的部分是Known gaps一节——它诚实记录本地工作站的失败套件，同时用基线对比证明它们不是本次发布引入的回归：

• 环境/平台受限的本地测试套件：在默认codex-cli 0.142.3的 macOS 工作站上，以下套件在 v0.20.2 基线上以相同方式失败，因此不是 v0.20.3 回归，在 Linux CI 边界上均为绿色：

  • src/cli/__tests__/uninstall.test.ts——macOS 路径/语法模拟用例（在 v0.20.2 基线即有 21 个失败）；
  • src/scripts/__tests__/codex-native-hook.test.ts与src/scripts/__tests__/smoke-packed-install.test.ts——live-CLI/版本边界用例；smoke-packed-install因Codex version resolution exceeded the 5000ms global deadline失败，因为工作站默认是0.142.3（0.20.2 出于同样原因需要一个隔离的@openai/codex@0.142.5）；
  • src/team/__tests__/runtime.test.ts与src/team/__tests__/scaling.test.ts——tmux 时序敏感套件，超出本地 wall-clock 预算。
  • 结论：dev/mainCI 门禁（Linux、钉死 Codex 边界）对这些套件具有权威性。

• 发布时贡献者去重：本范围所有提交都来自唯一维护者（Yeachan Heo，GitHub @Yeachan-Heo），以本地身份Yeachan-Heo、Bellman、bellman提交。本地（无 GitHub API）的generate-release-body.jsshortlog 会渲染成 “Thanks to Bellman and Yeachan-Heo …”。按 RELEASE_PROTOCOL.md 第 3 节，发布正文要折叠为先前的 release-train 单句格式。本范围无外部贡献者或 dependabot 提交。

这段记录的工程价值在于：门禁失败必须分类——要么是修复后重跑，要么是环境性例外并给出权威门禁的替代位置，要么是发布阻塞。发布记录对此给出了明确的判别方法（与基线对比 + 平台边界划分）。

0.20.3 发布内容：13 个 PR 的主题归纳

虽然就绪记录本身不展开产品内容，但它引用的 docs/release-notes-0.20.3.md 与 CHANGELOG.md 提供了发布主题的权威归纳，可用作理解门禁为何覆盖这些表面：

• Max per-agent reasoning effort——通过团队模型契约按 agent 上限控制推理努力（#3143），这是本版本唯一的新特性，属附加且向后兼容；
• Team exact live-pane authority——Team 在施加显式生命周期效果前验证精确的实时 tmux pane，并在启动、扩缩、回滚、恢复、teardown 中保持 pane 所有权，成员与扩缩事务持久且失败原子化，notify 分发绑定到所属 worker pane pid（#3153；issue #3121）；
• Ralplan review integrity——要求严格的直接评审顺序（#3186）、缺少已记录 leader proof 时 fail closed（#3196；issue #3194）、在PreToolUse中证明 reconciled leader 以关闭 live-exec 回归（#3187；issue #3181）、通过结构化解析协作结果解决 App leader-proof 回归（#3218；issue #3204）；
• Team mailbox 与会话恢复——mailbox wakeup 合并且每个 wake 都被确认（#3217；issue #3195），并新增精确的会话指针锁恢复（#3215；issue #3203）；
• Native hook 与配置安全——跨 native hook、code-intel、wiki MCP 表面加固 native 子写入身份（#3135；issue #3127），配置生成器幂等调和重复的项目信任表（#3201；issue #3199）；
• 插件与平台鲁棒性——插件 native hook 对超大 tool-hook 载荷返回结构化响应（#3211），Windows 上容忍常规文件fsync的EPERM（#3191）；
• 文档——在 CLI 与 README 中记录隔离的标准启动方式（#3192）。

源码佐证：按 agent 的推理努力覆盖

“Max per-agent reasoning effort”特性在源码中有清晰实现。配置侧，src/config/models.ts 定义了推理努力的规范值域：

export const PER_AGENT_REASONING_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'] as const; export type PerAgentReasoningEffort = (typeof PER_AGENT_REASONING_EFFORTS)[number];

并提供了readAgentReasoningOverrides()/getAgentReasoningOverride()，从 omx 配置文件的agentReasoning字段按规范化 agent 名解析每 agent 覆盖值（src/config/models.ts）。团队侧，src/team/model-contract.ts 通过TeamReasoningEffort = PerAgentReasoningEffort把这一能力接入团队 worker 启动参数解析：它识别model_reasoning_effort=形式的配置覆盖，并区分推理来源explicit | role-default | none，将解析结果写入ResolvedTeamWorkerLaunchDiagnostics（src/team/model-contract.ts）。也就是说，团队成员的推理努力可以按角色显式封顶（max仅对 agent 合法，根配置只支持low/medium/high/xhigh），这与发布说明中“finer control over model behavior across a team”的表述一致。

发布序列：六步走完 tag 到 npm

发布记录引用 RELEASE_PROTOCOL.md 第 5 节，列出了完整发布序列：

1. 将候选 collateral 提交推到dev，等待devCI 在发布提交上变绿；
2. 通过正常 CI 路径将候选提升到main，等待mainCI 变绿；
3. 创建并推送注解v0.20.3tag，等待 tag 触发的发布 workflow（native 构建、资产发布/验证、packed-install smoke、npm 发布）；
4. 验证非 draft 的 GitHub release 附带 native 资产/清单，且npm view oh-my-codex version==0.20.3；
5. 将devfast-forward 到已发布的main提交，等待最终devCI 变绿；
6. 将dev元数据 bump 到下一个开发基线版本（0.20.4）。

这六步体现了两条铁律：先 collateral 后 tag（发布配套物不完备不创建 tag），发布后立即回填与 bump（dev要么指向发布提交，要么只含文档化的 post-publish 修正加上下一个开发基线版本 bump）。RELEASE_PROTOCOL.md 第 7 节给出了发布的“停止条件”：main与 tag 指向预期发布提交、发布 workflow 绿色、npm 显示预期版本、GitHub 正文准确概括完整 compare 范围、就绪记录包含 CI 与发布证明——五项全部为真才算完成。

配套文档与可追溯链

本次发布的全部配套物形成一条完整的可追溯链，读者可按需回溯：

• 产品面摘要：docs/release-notes-0.20.3.md（亮点、PR 清单、兼容性、验证指引）；
• GitHub 发布正文模板：RELEASE_BODY.md（由 src/scripts/generate-release-body.ts 消费）；
• 变更日志条目：CHANGELOG.md 中[0.20.3] - 2026-07-19一节；
• 发布协议：RELEASE_PROTOCOL.md（第 2 节要求上述文件齐备，第 3 节要求 tag 前生成并校验正文，第 5 节定义发布序列，第 6 节定义发布后修正流程）；
• 提交级分类：artifacts/release-0.20.3/inventory.md。

0.20.3就绪记录的意义不在于“这是一次顺利的发布”，而在于它示范了如何用可复现命令、可交叉核对的清单、按阶段划分的门禁证据和诚实的已知缺口，把一次 99 提交的 patch 发布变成完全可审计的过程。对任何维护多模块、多语言（TypeScript + Rust）且带 native 构建与 npm 发布的仓库来说，这套“冻结范围 → 证据化 collateral → 分阶段门禁 → 序列化发布 → 基线回填”的方法都值得直接复用。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex