企业官网建设流程全解析

oh-my-codex 0.20.5 发布清单解析：补丁版本如何冻结、复现并审计 68 个提交的变更边界

【免费下载链接】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

本篇基于仓库中的发布清单 artifacts/release-0.20.5/inventory.md 展开，讲解 oh-my-codex（OmX）在 0.20.5 这个补丁版本中如何定义"精确冻结范围"、用一条git log命令复现完整提交清单、将 35 个合并 PR 归入七大变更类别，以及每个类别背后对应的源码模块与验证证据；读完后你可以掌握该仓库"冻结候选提交 → 分类审计 → 门禁取证 → 发布通道隔离"这套补丁版本生产流程的具体做法。

发布身份与冻结范围

清单文档开头首先固定了本次发布的五个关键身份参数，这是后续所有审计与复现的基准：

清单提供了复现提交清单的标准命令，任何人都可以在本地仓库重新得到同一份清单：

git log --reverse --format='%H%x09%an%x09%s' v0.20.4..13c08f84cb6c27750b8f5c4a4d5105faad074196

这条命令按拓扑顺序（--reverse）输出范围内每个提交的全量哈希、作者与主题行，制表符分隔便于脚本解析。把范围表达式写成"上一个 tag..冻结候选"而不是某个日期或分支名，是这份清单可复现性的关键：只要两个引用都还在，清单就永远可重放。

需要特别注意的是边界问题。配套的 docs/qa/release-readiness-0.20.5.md 明确记录：v0.20.4并不是冻结候选13c08f8的直接祖先，两者都从合并基229d5dc4fd82aa87e274ddf22dbe197987f2778e派生；维护者显式冻结了上述比较表达式，发布通道（promotion lane）必须先完成"release tag 与 main 的血缘调和"才能打v0.20.5标签，而清单所在的准备通道自身不合并 main、不打标签、不做 npm 发布。这一条把"记录变更范围"和"对外发布"两个动作在流程上做了硬隔离。

变更分类：七大类别及其源码落点

清单把 68 个提交归类为七个主题簇。下面逐一说明每个类别的语义，并给出当前仓库中可继续下钻的源码与测试位置。

1. Darwin 分离式启动的"返回 shell/终结化"收尾

该类别覆盖：live-pane（存活窗格）就绪检查、原子化启动元数据、精确的 HUD/leader 拆除（teardown）、终结化之后的 attach 释放，以及 macOS CI 覆盖。从源码结构看，这条链路的主体在 src/team/tmux-session.ts——该文件同时承载了 leader 与 HUD 窗格的生命周期管理（如captureSourcePaneAuthority在 leader 窗格、HUD 分裂目标、各 team 窗格上的多次调用），补丁版本对"何时才能把控制权交还 shell"这一时序做了严格化。这与 docs/release-notes-0.20.5.md 中"Darwin 分离式启动现在只在精确的 leader/HUD 终结化之后才返回控制权"的表述相互印证（对应 PR #3472）。

2. 会话与 Hook 权限的收紧

该类别覆盖五件事：不确定（indeterminate）绑定的精确终结化、同步的能力再校验、锁检查诊断、schema 安全的 Stop 行为，以及授权失败处理。仓库中与之对应的核心文件包括 src/hooks/session.ts（会话级 hook 状态，源码中直接出现 indeterminate 绑定的处理逻辑）与 src/scripts/codex-native-hook.ts（Codex 原生 hook 的落盘与事务处理，其测试 src/scripts/tests/codex-native-hook.test.ts 覆盖 indeterminate 场景）。claim 日志相关的持久化位于 src/cli/native-hook-claim-journal.ts。该类别对应的 PR 为 #3416、#3421、#3471、#3472。

3. Ralplan 诊断与生命周期

类别内容：保留状态的预检（state-preserving preflight）、结构化的"检测到版本"诊断、陈旧 owner 状态清理、类型化的共识委托，以及对 Codex 0.148 alpha 版本的识别。实现集中在 src/ralplan/ 模块：src/ralplan/advisory.ts 承载 advisory 主逻辑，src/ralplan/documented-leader-preflight.ts 对应预检与版本诊断路径，src/ralplan/advisory-recovery-journal.ts 与 src/ralplan/advisory-storage.ts 负责状态持久化与恢复，team 侧的陈旧 owner 状态则与 src/team/state.ts 相关。对应 PR 为 #3450、#3455、#3456、#3473。该模块的契约性文档可参考 docs/contracts/ralplan-consensus-gate.md。

4. Windows / setup 耐久性

类别内容：目录fsync与 mode 合成差异的容忍、平台感知的测试夹具、以及"启动修复"时保留用户的 notify/reasoning 偏好与项目作用域。这一类别在仓库中有一个非常具体、可直接阅读的落点——src/utils/file-durability.ts：

// src/utils/file-durability.ts（节选） export async function syncDirectory( handle: Pick<FileHandle, "sync">, platform: NodeJS.Platform = process.platform, ): Promise<DirectorySyncOutcome> { try { await handle.sync(); return "synced"; } catch (error) { if (!isUnsupportedWindowsSync(error, platform)) throw error; return "unsupported-windows-eperm"; } }

其设计边界写得非常克制：只有win32平台 +EPERM错误码这一种组合被视为"持久化能力受限"，降级为unsupported-windows-eperm结果并通过emitDegradedDurabilityWarning向 stderr 输出一条[omx] warning: Windows EPERM ...的降级警告；其他任何平台/错误组合仍然按致命错误抛出。同一文件中的syncRegularFile对常规文件句柄做完全对称的处理，RegularFileDurabilityTracker则区分regularFileDegraded与directoryDegraded两个维度。这正是清单中"directoryfsyncand mode-synthesis tolerance"的源码实现，setup 安装路径的入口在 src/cli/setup.ts（对应 PR #3448、#3449、#3467、#3468），诊断入口在 src/cli/doctor.ts。

5. Team / tmux 边界

类别内容：外部（foreign）拓扑诊断，以及"source-authority 分隔符 argv 的精确保持"。后者背后是一份被接受的架构决策记录 docs/adr/3459-team-tmux-argv-separator-boundary.md，其结论是：runSourceAuthorizedTmux()成功分支传给真实 tmux 命令串解析器的 argv 里，命令列表分隔符必须是字面量;而不是\;——真实 tmux 会把\;当作转义后的字面分号，导致display-message被解析为多余参数并报too many arguments。该 ADR 同时把runSourceAuthorizedTmux与其SourcePaneAuthority输入类型导出，让真实 tmux 回归测试直接驱动产品代码的 argv 构造，而不是在测试侧重复一份可能漂移的复制品。

在当前仓库中，这两个符号位于 src/team/tmux-session.ts：

• L274：export type SourcePaneAuthority = { ... }
• L367：export function runSourceAuthorizedTmux(source: SourcePaneAuthority, effect: string, receipt: string = sourceTransactionReceipt()): string

ADR 描述的回归路径由 src/team/tests/tmux-source-authority-realtmux.test.ts 承担：它创建私有 tmux 服务的 PATH shim、保存并前置process.env.PATH后调用导出的 helper，断言实际记录下来的if-shellargv，并用有界的窗格就绪轮询压住夹具启动抖动——生产行为不变。ADR 还明确划出了范围边界：runSourceAuthorizedSplit、Team scaling、HUD helper 等类似位点不在本次修复内，后续需先做独立的真实 tmux 探测。对应 PR 为 #3434、#3460。

6. 插件 / 运行时 / 打包

类别内容：确定性的 packed runtime/cwd 检查、启动上下文的状态绑定、native 身份就绪性（native identity readiness），以及 hermetic 冒烟行为。从仓库结构看，相关实现分布在 src/native-assets/（如 src/native-assets/policy.ts 与 src/native-assets/archive.ts）、目录/编目校验（src/catalog/）以及打包冒烟脚本 src/scripts/smoke-packed-install.ts。QA 记录中对应的门禁证据是：native-agent 校验（22 个 agent、37 个 prompt 资产）、plugin mirror 校验（29 个 skill 目录）、目录检查与npm pack --dry-run通过。对应 PR 为 #3395、#3436、#3454、#3461、#3470。

7. 依赖更新

windows-sys、tar-stream、@types/tar-stream、@biomejs/biome与@types/node五个依赖的更新（PR #3429–#3432）。清单特意把依赖更新单独列为一类，是为了让审计者在核对 package-lock.json 与 Cargo.lock 时能区分"行为变更"与"纯依赖漂移"。

合并 PR 清单

清单文档最后完整列出了本范围内的 35 个合并 PR：

#3395, #3396, #3401, #3402, #3403, #3404, #3409, #3410, #3413, #3416, #3419, #3421, #3425, #3429, #3430, #3431, #3432, #3434, #3436, #3446, #3448, #3449, #3450, #3453, #3454, #3455, #3456, #3460, #3461, #3467, #3468, #3470, #3471, #3472, #3473。

并附有一条审计规则：提交主题中的 issue 引用不构成额外的 PR。也就是说，如果有人用"提交里出现的所有 #数字"去数 PR 数量，会多算；清单以合并 PR 编号为准，避免把 issue 追踪号误认为代码变更单元。这份 PR 清单与 docs/release-notes-0.20.5.md 中的 Inventory 段落完全一致，可作为交叉验证源。

门禁证据链：清单之外的可验证性

清单本身只声明"范围与分类"，证明"这个范围是可信的"则由 docs/qa/release-readiness-0.20.5.md 中的门禁表格承担。值得逐条对照的门禁包括：

• 版本载体一致：package.json、package-lock.json、Cargo.toml、Cargo.lock 及插件 manifest 全部为0.20.5，且cargo check --workspace以0.20.5构建全部六个工作区包（工作区布局见 dist-workspace.toml 与 Cargo.toml）。
• 版本同步检查：node dist/scripts/check-version-sync.js --tag v0.20.5报告OK package=0.20.5 workspace=0.20.5 tag=v0.20.5，其源码为 src/scripts/check-version-sync.ts。
• 构建与静态检查：npm ci+npm run build；npm run check:no-unused与npm run lint（793 个文件，无自动修复），静态规则配置在 biome.json。
• 聚焦高风险测试：launch fallback/session、Ralplan、setup install mode、Team/tmux、真实 tmux source-authority、plugin layout 六组测试共 291 个用例通过、0 失败——与上文各分类的源码落点一一对应。
• 发布正文生成器的拒绝行为：RELEASE_BODY.md 的生成器（src/scripts/generate-release-body.ts）因为v0.20.5尚不存在且v0.20.4不是候选的祖先而正确拒绝生成——生成被刻意推迟到发布通道完成血缘调和并打标签之后。
• 未执行项：CI、打标签、npm 发布均显式列为"发布通道职责"，本地准备通道不声明任何对外发布。

这套"准备通道只记录、发布通道只执行"的边界，也体现在仓库根目录的流程文档 RELEASE_PROTOCOL.md 中。

如何复现与审计这份清单

把清单文档当作一次可执行的审计入口，标准操作是三步：

1. 复现范围：运行清单中给出的git log命令，确认得到 68 个提交、作者与主题行的序列，与清单的分类条目逐一对照；
2. 核对 PR 集合：确认合并 PR 列表与 docs/release-notes-0.20.5.md 的 Inventory 段落一致，并记住"issue 引用不算 PR"这条去重规则；
3. 下钻分类落点：按七大分类跳转到对应模块——tmux 传输看 src/team/tmux-session.ts 与 docs/adr/3459-team-tmux-argv-separator-boundary.md，耐久性容忍看 src/utils/file-durability.ts，会话/hook 权限看 src/hooks/session.ts 与 src/scripts/codex-native-hook.ts，Ralplan 生命周期看 src/ralplan/advisory.ts，门禁证据看 docs/qa/release-readiness-0.20.5.md。

这套做法的价值在于：发布清单不是一个"已发布版本"的事后总结，而是一份在打标签之前就可被任意第三方重放验证的冻结凭证——范围表达式、合并基、PR 集合、分类语义与门禁证据全部落在仓库内（本清单、artifacts/ 目录及 docs 下配套文档），任何一条结论都可以沿着仓库内相对路径继续追到源码与测试。

适用前提与限制

• 本文所有版本号、哈希与 PR 编号以 artifacts/release-0.20.5/inventory.md 及其配套文档记录为准；复现git log命令要求本地仓库完整保留了v0.20.4标签与候选提交13c08f84cb6c27750b8f5c4a4d5105faad074196的可达历史；
• QA 文档声明"广泛的跨平台与 native 构建矩阵以 CI 为准"，本地清单无法替代 CI 的平台级验证结论；
• 由于血缘边界（v0.20.4非候选直接祖先），v0.20.4...v0.20.5的三点对比链接只有在发布通道完成调和并打标签后才成立，这是文档明确记录的待办，而非本清单通道的职责。

【免费下载链接】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