企业官网建设流程全解析

oh-my-codex 0.16.3 发布门禁解析：从 Release Readiness 文档看版本发布验证与发布面硬化的完整流程

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

本文以docs/qa/release-readiness-0.16.3.md为核心，解析 oh-my-codex 在 0.16.3 版本（0.16.2 之后的 native-hook/setup/runtime 硬化列车）上如何组织一次发布就绪判定：发布面（release surface）包含哪些四大类变更、哪些本地验证门禁被标记为 PASS、哪些 CI 与发布证据需要在打 tag 之后回填。读完后，你将掌握该项目“先冻结对比范围 → 跑通本地门禁 → 生成发布说明 → 打 tag 触发发布工作流 → 回填发布证据”的标准发布流程，并理解 0.16.3 涉及的 hook feature flag、hook trust 状态、Ralph 会话恢复等改动的源码落点。

0.16.3 的发布就绪判定：PREPARED FOR RELEASE

0.16.3 的 release-readiness 文档位于 docs/qa/release-readiness-0.16.3.md，其核心结论（Verdict）是：

PREPARED FOR RELEASE.0.16.3is the release candidate for the post-0.16.2native-hook/setup/runtime hardening train. Publication evidence must be filled after CI/tag workflows complete.

要点有三：

1. 目标版本：0.16.3，日期 2026-05-09，对比范围为v0.16.2...v0.16.3；
2. 版本定位：这是 0.16.2 发布列车之后的可靠性补丁版本，聚焦 Codex 原生 hook 安装/配置、setup/uninstall 所有权边界与 Team/Ralph 运行时状态边界（与 docs/release-notes-0.16.3.md 中的版本定位一致）；
3. 证据分两段：本地门禁（build/lint/测试）在打 tag 前完成并记录为 PASS，而 Dev CI、Main CI、release workflow、GitHub release 与 npm 五项发布证据在 tag 推送之后验证并回填。

这种“先判定、后回填”的结构是该仓库 RELEASE_PROTOCOL.md 第 4 节（Release-readiness gate）的直接产物：readiness 文档必须记录对比范围、PR 清单、本地门禁、CI run ID 与已知缺口（known gaps）。

发布面（Release surface）：0.16.3 改了哪些东西

文档的 Release surface 一节将 0.16.3 的变更归纳为四个方向。下面逐条继承原文档描述，并结合仓库源码说明每个方向落在哪些实现上。

1. Codex hook 安装/配置：feature flag 对齐与 hook trust 放置

原文档描述：

supported[features].hooks = true，runtime hook trust placement，dedupe，Windows command generation，and native compact hook JSON validity.

这一条是 0.16.3 的主线：把生成的 Codex 配置对齐到官方支持的 feature flag。从源码结构看，其落点在 src/config/codex-feature-flags.ts：

• CODEX_HOOK_FEATURE_FLAGS = ["hooks", "codex_hooks"]同时承认当前规范名hooks与旧版别名codex_hooks，而DEFAULT_CODEX_HOOK_FEATURE_FLAG固定为"hooks"——这与发布说明中“生成配置默认输出[features].hooks = true”一致；
• resolveCodexHookFeatureFlag()的探测顺序是：先解析codex features list风格的输出，若包含hooks就选hooks，若只包含codex_hooks就降级选旧名；两者都探测不到时，再用 CLI 版本号做兜底（[0, 130, 0]及以上选hooks），否则回退到fallback或默认值。这就是发布门禁表中“Official Codex docs check: PASS — lifecycle hooks use[features].hooks = true”的实现依据；
• 配置实际写入发生在 src/config/generator.ts 的[features]upsert 逻辑中：生成器调用formatCodexHookFeatureFlagLine()产出hooks = true行，并维护[features]段的 upsert 与清理（含“移除 OMX 拥有的 feature flag 后若 section 为空则连表头一并删除”的幂等行为，对应发布说明中“迁移旧的codex_hooks = true别名”的修复）。

hook trust 的“placement 与 dedupe”对应 src/config/codex-hooks.ts：该模块管理 OMX 拥有的hooks.json信任状态（以trusted_hash为键的ManagedCodexHookTrustState），提供冲突检测（managed_trust_key_conflict，即“根状态与 hooks.state 中出现互相冲突的历史信任状态”时报错）、重复路径去重（dedupeCodexHookConfigPaths()）等能力。0.16.3 的 #2201（Fix hooks.json trust state placement）、#2199（dedupe managed hook trust state）、#2190（runtime hook mirror dedupe）三个 PR 正是围绕这些函数修复的回归：项目运行时CODEX_HOME的 hook trust 被重映射到运行时的 mirrorhooks.json，而不是留在用户主目录的原始位置。

2. Setup/uninstall 的所有权边界：用户状态不被工具覆盖

原文档描述：

user notify preservation, user hook enablement preservation, managed notify detection hardening, and project-scope runtime mirror boundaries.

即：OMX 的安装/卸载只管理“自己拥有的”部分，用户自有的 notify 命令和 hook 启用状态必须原样保留。相关 PR 包括 #2196（notify setup scope handling）、#2200（uninstall 保留用户 hook enablement）、#2212（Windows/global 安装推迟启动时自更新）。实现分布在 src/cli/setup.ts 与 src/cli/uninstall.ts，测试面包括src/cli/__tests__/setup-hooks-shared-ownership.test.ts、src/cli/__tests__/uninstall.test.ts等。0.16.3 的 release notes 还补充了两个细节：notifyCommand: false的项目级安装不再误伤非 OMX 的notify命令；managed notify 的检测不再依赖 basename 单字段匹配（避免把只含陈旧.omx/state或.omx/logs目录的仓库误判为 OMX 拥有）。

3. Team/规划/运行时：approved handoff 与状态根隔离

原文档描述：

approved handoff context, ready context-pack role refs, launch signature preservation, role-agnostic hints, startup-evidence state-root isolation, and local planning artifact reads.

对应 PR #2202（planning 保留 Team launch signature）、#2203（保留角色无关的 approved hints）、#2204（context-pack role refs 暴露）、#2208（approved handoff context 段落）。其中“startup-evidence state-root isolation”与“local planning artifact reads”解决的是同一类问题：Team 启动证据与规划产物的读取默认优先仓库本地.omx路径，只有显式配置了 Team state root 时才走全局路径，避免全局 OMX 状态污染（见 CHANGELOG.md 0.16.3 的 Changed 条目）。

4. 工作流生命周期：Ralph 陈旧会话与 autoresearch 阻塞裁决

原文档描述：

stale Ralph resume prevention and blocked autoresearch Stop reconciliation.

即：陈旧的 Ralph 会话不再被自动恢复（#2220），autoresearch 遇到 blocked 裁决时的 Stop 对账逻辑显式化（#2213）。Ralph 的持久化与契约实现位于 src/ralph/persistence.ts 和 src/ralph/contract.ts，autoresearch 的运行时对账位于 src/autoresearch/runtime.ts。

验证证据表：PASS 与 PENDING 的分界

文档的 Verification evidence 表是 0.16.3 就绪判定的量化依据，完整继承如下：

这张表可以读出该仓库发布门禁的三层结构：

1. 打 tag 前必须 PASS 的三项：官方文档一致性（feature flag 与 Codex 官方文档一致）、本地阻塞套件（npm run build、npm run lint、npm run check:no-unused等，均可在 package.json 的 scripts 中查到对应命令）、发布说明生成（用RELEASE_BODY.md模板 + 对比范围生成正文）。
2. CI 晋升链：dev 分支 CI → 合并 main 后 main CI → tag 触发 release workflow，与 RELEASE_PROTOCOL.md 第 5 节“Publish sequence”（合并候选 → 等 main CI → 打注解 tag → 等 tag 工作流 → 验证）一一对应。
3. 发布后验证：GitHub release 状态（非 draft/非 prerelease）、native assets 与 manifest 是否挂载、npm registry 上的版本号。

关于本地阻塞套件的细节：npm run build是“清空 dist + tsc 编译 + 设置dist/cli/omx.js可执行位”；check:no-unused是基于tsconfig.no-unused.json的独立 TS 检查；npm run lint走 Biome（biome lint src，配置见 biome.json）。发布说明生成脚本则是dist/scripts/generate-release-body.js，接受--template RELEASE_BODY.md --out <path> --current-tag $NEXT --previous-tag $PREV --repo ...参数，生成物必须包含## Contributors与正确的**Full Changelog**行——这正是表中“Release body generation: PASS”的具体判据。

原生 compact hook 的 JSON 有效性：验证表背后的一个具体修复

Release surface 提到 “native compact hook JSON validity”。在 0.16.3 中，PreCompact/PostCompact 这两个 Codex 生命周期事件的输出必须是合法 JSON（否则 Codex 侧解析失败会导致压缩流程异常）。从源码结构看，事件名到内部阶段名（pre-compact/post-compact）的归一化、以及基于JSON.stringify的状态/日志写入都集中在 src/scripts/codex-native-hook.ts，对应 PR #2207（PostCompact JSON 输出）与 #2217（PreCompact JSON 输出）；回归测试位于 src/scripts/tests/codex-native-hook.test.ts。这类“hook 输出必须是合法 JSON”的约束也进入了仓库的长期回归套件test:recent-bug-regressions（见 package.json）。

发布备注：凭据边界与发布后文档漂移

文档 Notes 一节继承如下两条操作约束：

1. 凭据边界：发布执行环境中没有本地 npm 凭据，发布预期走仓库发布工作流/trusted publishing 路径，在签名/注解 tag 推送之后自动完成。这与验证表中 npm 门禁为 PENDING 的原因一致——发布证据只能在工作流跑完后验证。
2. 发布后修正的文档漂移规则：如果 tag 之后才补交发布后证据，需按 RELEASE_PROTOCOL.md 第 6 节记录“有意为之的 docs-only divergence”：修正的发布物先提交到dev，经正常 CI 路径晋升main，再重新生成并编辑 GitHub release 正文，最后在 readiness 文档中记录这次修正。该协议还明确“不得移动已发布的 npm provenance tag，除非发布物本身无效且维护者明确选择紧急 retag”。

小结：从一份 readiness 文档能读出什么

0.16.3 的 readiness 文档看似简短，但它完整体现了 oh-my-codex 的发布治理方式：

• 范围冻结：所有发布说明从v0.16.2...v0.16.3的精确对比范围生成，而非凭记忆（RELEASE_PROTOCOL.md 第 1、2 节）；
• 门禁分层：本地阻塞套件在 tag 前 PASS，CI 与发布证据在 tag 后 PENDING→回填，停止条件（Stop condition）要求 main/tag 指向目标提交、GitHub release 工作流为绿、npm 版本号正确、release 正文准确覆盖完整对比范围、readiness 证据含 CI 与发布证明；
• 变更可溯源：四大发布面均可回溯到 docs/release-notes-0.16.3.md 中的 PR 清单（#2186、#2190–#2191、#2196、#2199–#2208、#2212、#2213、#2216–#2217、#2220），并在 CHANGELOG.md 的 0.16.3 条目中再次引用本 readiness 文档作为验证证据。

对于维护类似多智能体编排工具的仓库，这份文档提供了一个可复制的模板：docs/qa/release-readiness-<version>.md记录判定与门禁表，docs/release-notes-<version>.md记录面向用户的变更与 PR 清单，RELEASE_BODY.md提供可再生成的 GitHub release 正文，RELEASE_PROTOCOL.md约束整个流程——四者共同保证发布说明、Changelog 与实际对比范围三者不漂移。

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