OmX 0.16.3 可靠性版本深度解析Codex Native-Hook 配置、Team 运行时状态边界与生命周期修复实践【免费下载链接】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-codex0.16.3是 OmXoh-my-codex在0.16.2之后的可靠性补丁版本聚焦于 Codex native-hook 安装配置、Team/Ralph 运行时状态边界、已批准交接上下文approved handoff context、规划上下文包context-pack指引以及发布前审查发现的阻塞问题修复。通过本文你将掌握[features].hooks特性开关的迁移原理、通知钩子所有权保护机制、Team 启动签名与交接上下文的持久化策略以及原生钩子在 PreCompact/PostCompact 生命周期中的 JSON 输出约束并能在实际项目中复现这些修复的验证路径。版本定位一次“提升前可靠性”的硬化版本0.16.3的定位非常明确——它不是新增功能版本而是对0.16.2引入的 native-hook/setup/runtime 硬化链路hardening train的收尾版本。版本声明中明确列出四个修复方向Codex native-hook setup 与受支持的 feature flag 对齐用户自有的通知钩子在 setup/uninstall 过程中更安全Team、planning 与已批准交接上下文更持久Ralph/autoresearch/native compact 钩子避免陈旧或畸形生命周期行为。这种“post-release 可靠性修复”的节奏意味着如果你正运行0.16.2升级到0.16.3将直接获得钩子信任状态、镜像去重、Windows 命令生成、交接上下文持久化等一揽子稳定性收益。一、Codex native-hook setup特性开关从codex_hooks迁移到[features].hooks1.1 修复的核心受支持的 feature flag 精确生成0.16.3最重要的基础设施修复是让生成的 setup/runtime 配置发出并迁移到[features].hooks true同时移除 features 表内陈旧的codex_hooks true旧别名保留用户自有的 hook 状态并让项目运行时CODEX_HOME的 hook 信任指向镜像后的hooks.json。这一逻辑在源码中有完整对应。查看 src/config/codex-feature-flags.ts 可以看到export const CODEX_HOOK_FEATURE_FLAGS [hooks, codex_hooks] as const; export const DEFAULT_CODEX_HOOK_FEATURE_FLAG: CodexHookFeatureFlag hooks; export function normalizeCodexHookFeatureFlag( value: string | null | undefined, ): CodexHookFeatureFlag { return value codex_hooks ? codex_hooks : DEFAULT_CODEX_HOOK_FEATURE_FLAG; }关键点在于normalizeCodexHookFeatureFlag的语义只有显式探测到旧版 CLI 仅支持codex_hooks拼写时才保留旧拼写否则默认值恒为规范名hooks。这正是“生成的配置只发出受支持 flag”的底层实现。1.2 探测逻辑从 CLI 输出解析真实能力resolveCodexHookFeatureFlag同一文件给出了完整的分级判定策略export function resolveCodexHookFeatureFlag(options: { featuresListOutput?: string | null; versionOutput?: string | null; fallback?: CodexHookFeatureFlag; } {}): CodexHookFeatureFlag { const featureNames parseCodexFeatureNames(options.featuresListOutput); if (featureNames.has(hooks)) return hooks; if (featureNames.has(codex_hooks)) return codex_hooks; if (isCodexCliVersionAtLeast(options.versionOutput, [0, 130, 0])) { return hooks; } return options.fallback ?? DEFAULT_CODEX_HOOK_FEATURE_FLAG; }判定顺序为先解析codex features list输出parseCodexFeatureNames按行正则^([A-Za-z0-9_])\s提取特性名→ 命中hooks优先 → 命中codex_hooks次之 → 再按 CLI 版本≥ 0.130.0 判为支持hooks→ 最后回退默认值。这段代码直接印证了 release notes 中“生成的 setup/runtime config 现在 emits 并 migrates 到[features].hooks true”的表述也解释了为什么旧别名只在“唯一报告项”时被保留——这正是迁移的兼容性边界。1.3 与 0.16.2 训练的关系修复信任放置与镜像去重回归release notes 的 “Fixes and compatibility notes” 指出项目级发布审查修复了0.16.2训练引入的 hook 信任放置与运行时镜像去重dedupe回归。相关 PR 包括[#2190] 修复运行时 hook 镜像去重与 hooks feature flag[#2199] 去重托管 hook 信任状态[#2201] 修复hooks.json信任状态放置[#2216] 迁移 Codex hooks feature flag。源码侧src/config/codex-hooks.ts 定义了信任状态的数据结构与去重分类export interface ManagedCodexHookTrustState { trusted_hash: string; } export interface DedupedCodexHookConfigPath { path: string; reason: unique; } export interface SkippedCodexHookConfigPath { path: string; reason: runtime_codex_home_mirror | duplicate_realpath; canonicalPath?: string; }这里的reason枚举直接对应修复方向runtime_codex_home_mirror运行时 CODEX_HOME 镜像路径不应重复计算信任与duplicate_realpath同一真实路径的符号链接别名构成了去重规则的全部语义防止同一 hook 配置文件被写入多份信任记录。二、用户自有通知钩子的所有权保护2.1 项目级 setup 不再动用户的 notify 命令0.16.3明确“project setup withnotifyCommand: falsepreserves non-OMXnotifycommands”。在 src/cli/setup.ts 的buildNotifyMergePlan中可以看到async function buildNotifyMergePlan( existingConfig: string, pkgRoot: string, codexHomeDir: string, scope: SetupScope, metadataSnapshot?: NativeHookTransactionArtifactSnapshot, ): PromiseNotifyMergePlan { if (scope project) { return { notifyCommand: false }; } // ... }scope project时直接返回notifyCommand: false意味着项目作用域的 setup 不写入任何 notify 命令从而完整保留用户既有的[notify]配置。这解决了此前项目级 setup 可能覆盖用户 notify 命令的隐患。2.2 托管检测不再依赖 basename-only 匹配release notes 强调“managed notify detection no longer relies on basename-only matches”。源码中对应的是两个判定函数function isOmxDispatcherNotifyCommand( notifyCommand: readonly string[] | null | undefined, pkgRoot: string, ): boolean { return Boolean( isOmxManagedNotifyCommand(notifyCommand, pkgRoot) notifyCommand?.some((part) /(?:^|[\\/])notify-dispatcher\.js$/.test(part), ), ); }判定不再只看命令的最后一段 basename而是同时校验isOmxManagedNotifyCommand对 pkgRoot 的路径归属校验与完整路径正则(?:^|[\\/])notify-dispatcher\.js$。配合 PR [#2196]修复 notify setup scope 处理与 [#2200]卸载时保留用户 hook enablement用户自定义的notify命令不会再被误判为 OMX 托管而被覆盖。2.3 陈旧空目录不再被误判为 OMX 所有另一个细节修复notify-hook 的 managed-CWD 检测不再把裸露的陈旧.omx/state或.omx/logs空目录当作 OMX 所有。这意味着在缺少实际元数据文件的情况下钩子不会误进入“托管”路径从而避免误删或误迁移用户目录结构。2.4 Windows/全局安装避免不安全的自我更新PR [#2212] 在 Windows/全局安装下延迟启动期自我更新defer startup self-updates。这与 src/config/codex-hooks.ts 中 Windows 钩子命令生成逻辑相辅相成if (platform win32) { const codexHomeDir options.codexHomeDir ?? dirname(pkgRoot); const shimPath buildManagedCodexNativeHookWindowsShimPath(codexHomeDir); const powerShellPath resolveWindowsPowerShellPath(options.env); return ${quotePowerShellLiteral(powerShellPath)} -NoProfile -ExecutionPolicy Bypass -File ${quotePowerShellLiteral(shimPath)}; }生成器通过resolveWindowsPowerShellPath优先取SystemRoot/windir环境变量定位powershell.exe避免 PATH 被运行时 shim 截断后 barepowershell.exe无法解析生成的.ps1shimbuildManagedCodexNativeHookWindowsShimContent以 UTF-8 BOM 开头防止 PowerShell 5.1 按系统 ANSI 代码页解码导致非 ASCII 安装路径乱码这正是 PR [#2191] Windows Codex hook command generation 修复的背景。三、Team、规划与已批准交接的持久化增强3.1 已批准交接上下文注入 workerPR [#2208] 引入 approved handoff context section。在 src/team/worker-bootstrap.ts 中可以看到 worker 启动时如何注入该上下文const approvedContextSection options.approvedContextSection ? \n## Approved Handoff Context\n\n${options.approvedContextSection}\n : ;此外还支持approvedContextSummary含sourcePath与truncated截断标记的降级路径: options.approvedContextSummary ? Source: ${options.approvedContextSummary.sourcePath}${options.approvedContextSummary.truncated ? (bounded/truncated) : } ${options.approvedContextSummary.content} 这意味着已批准交接的上下文会被显式标记来源路径并且在内容超限时标注(bounded/truncated)worker 能够据此判断上下文的完整性与可信度。3.2 符号化 Team 启动签名跨规划存活PR [#2202] 修复规划过程保留 Team 启动签名launch signatures。配套的 PR [#2204] 暴露就绪 context-pack 的角色引用ready context-pack role refs。测试侧在 src/team/tests/runtime.test.ts 中给出了针对性用例例如startTeam carries explicit baseline-ready approved bindings without context-pack metadata无 context-pack 元数据时仍携带基线就绪的已批准绑定startTeam carries explicit baseline-ready bindings despite obsolete context-pack markers即使存在过期 context-pack 标记也携带绑定。这两个用例直接验证了“符号化启动签名在规划后不丢失”以及“对旧标记的容忍”。3.3 角色无关的已批准提示与本地状态根PR [#2203] 保证角色无关的已批准提示role-agnostic approved hints被保留同时 Team 启动证据测试startup-evidence tests将本地状态根与全局 OMX 状态隔离规划产物读取与 Team 运行时状态根优先使用仓库本地.omx路径除非显式配置了 Team 状态根。这一点在 release notes 的兼容性说明中也有明确表述Planning artifact reads and Team runtime state roots now prefer repository-local.omxpaths unless an explicit Team state root is configured.这套设计避免了全局 OMX 状态污染仓库级 Team 运行时的隐患。四、Ralph、autoresearch 与原生 compact 钩子的生命周期修复4.1 陈旧 Ralph 会话不再自动恢复PR [#2220] 防止陈旧 Ralph 会话自动恢复auto-resume。此前残留的 Ralph 会话可能在新的对话周期被意外拉回执行产生语义错乱的续跑。0.16.3通过会话新鲜度判定阻止这种自动恢复相关测试覆盖在 src/state/tests/stale-state-neutralization.test.ts 等状态中立化测试中。4.2 受阻 autoresearch Stop 的显式对账PR [#2213] 修复受阻判定下的 autoresearch Stop 对账reconciliation当 autoresearch 因阻塞判定无法正常推进时Stop 语义不再被吞掉而是显式执行对账路径保证会话可被明确终止而不悬空。4.3 PreCompact/PostCompact 原生钩子保持合法 JSONPR [#2207] 与 [#2217] 分别修复 PostCompact、PreCompact 原生钩子的 JSON 输出。在 src/scripts/codex-native-hook.ts 中可以看到相关事件的分支处理case PreCompact: return pre-compact; case PostCompact: return post-compact;以及 PreCompact 的专有逻辑约第 22616 行附近当前 Codex 原生 PreCompact 只接受公共的续写continuation字段代码注释明确“除非 Codex 定义了受支持的 PreCompact 输出契约否则保持保守输出”同时构建 Wiki PreCompact 上下文。这条约束保证了 compact 生命周期内钩子输出始终是可被 Codex 解析的合法 JSON避免因畸形输出中断会话压缩。五、兼容性与清理策略0.16.3对旧别名采取“保留迁移覆盖但不作为现行指引”的策略继续为旧的不受支持的 hook 别名保留 legacy cleanup/migration 覆盖但不再把它们写进当前 setup 指导文档避免用户在新安装中继续依赖旧拼写。这在 src/config/codex-feature-flags.ts 的注释中得到印证旧版 Codex CLI 使用[features].codex_hooks当前版本默认hooks仅在探测确认旧拼写是唯一能力时才回退。也就是说codex_hooks从“文档化能力”降级为“迁移兼容路径”。六、发布验证与升级建议6.1 本地发布审查门禁0.16.3的 Validation 章节给出了可复现的本地验证清单npm run build npm run lint npm run check:no-unused git diff --check覆盖对象包括 setup/config/uninstall/hook/Team 相关的定向 Node 测试。发布主体release collateral由v0.16.2...v0.16.3比较区间生成并在打 tag 前用generate-release-body.js校验。6.2 官方发布就绪证据完整的发布就绪判定记录在 docs/qa/release-readiness-0.16.3.md判定结果为PREPARED FOR RELEASE其中官方 Codex 文档检查 PASS确认生命周期钩子使用[features].hooks true本地阻塞套件 PASS。该文档同时列出发布面release surface四大块hook setup/config、setup/uninstall 所有权、Team/planning/runtime、workflow 生命周期。6.3 升级建议若你正在0.16.2升级到0.16.3直接修复 hook 信任放置与运行时镜像去重的回归是最低风险的跳板若你正在更早版本且使用codex_hooks旧拼写0.16.3会在 setup 时自动探测并迁移到[features].hooks true迁移过程保留你自有的 hook 状态Windows 用户0.16.3修复了钩子命令生成PowerShell 定位与 BOM 编码和启动期自我更新延迟建议优先验证SessionStart/Stop事件在 PowerShell 5.1 下的执行。结语0.16.3是一个教科书式的“可靠性收尾版本”它以特性开关规范化、钩子所有权保护、Team 交接上下文持久化、compact 生命周期 JSON 合法性四条主线把0.16.2训练遗留的边界问题逐一收口。源码层面src/config/codex-feature-flags.ts 与 src/config/codex-hooks.ts 构成了钩子配置与信任管理的核心src/cli/setup.ts 承载了通知合并与所有权保护而 src/team/worker-bootstrap.ts 则体现了已批准交接上下文在 worker 侧的注入机制——理解这些实现细节将帮助你在升级、排障或二次开发时快速定位行为来源。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考