oh-my-codex v0.8.4 发布解析：omx setup 默认刷新、安全备份与模型升级确认机制

oh-my-codex v0.8.4 发布解析：omx setup 默认刷新、安全备份与模型升级确认机制

【免费下载链接】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.8.4（发布于 2026-03-06）这一 setup-flow 补丁版本展开，核心讲解omx setup在可重复执行、可安全回滚与可控升级三个维度的行为变化：受管 OMX 工件默认刷新、覆盖前自动备份、以及从gpt-5.3-codex升级模型前的交互确认。读完本文，你将掌握该版本 setup 刷新机制的完整语义、备份目录的落盘位置与命名规则、模型升级提示的触发条件与交互流程，以及对应的回归测试与发布验证门禁。

版本定位：一次聚焦 setup 可重入性的补丁发布

v0.8.4 的定位非常明确——setup-flow patch release，全部变更围绕omx setup命令的刷新（refresh）行为展开，目标是让重复执行omx setup更安全、更可预测、更易重跑。发布说明中给出了四项核心变更与两项伴随性加固：

1. omx setup默认刷新受管的 OMX 工件，不再遗留过期的生成内容；
2. 受管刷新路径在覆盖文件前尽可能保留备份；
3. setup 在把受管 Codex 模型引用从gpt-5.3-codex升级到gpt-5.5之前会主动询问用户；
4. 为 setup 与配置生成路径补充了更深的刷新/幂等性回归测试覆盖。

伴随性加固包括：流式回退测试中 watcher 关闭清理的稳定性修复，以及严格 no-unused 门禁（npm run check:no-unused）暴露出来的死代码清理。

本次发布由两个提交构成：

• fed035b— feat(setup): refresh managed OMX artifacts by default with backups
• 6aa577d— feat(setup): prompt before upgrading gpt-5.3-codex to gpt-5.5

变更一：受管 OMX 工件默认刷新

在 0.8.4 之前，setup 安装的 prompts、skills、native agents、AGENTS.md 等受管工件更接近"一次性投放"（one-time drops）。v0.8.4 改变了这一语义：setup 将这些受管工件视为可刷新的输出（refreshable outputs），重复运行omx setup会一致地更新已交付的工件，使既有安装与当前模板和生成资产保持对齐。

这一改动带来三个直接收益：

• 减少升级后的过期生成文件：模板或生成器升级后，旧的受管文件不再残留；
• 让重复运行 setup 更安全、更有用：修复配置、补齐缺失文件等场景不再需要依赖--force等旁路手段；
• 改善全新安装与刷新安装之间的一致性：无论是首次安装还是事后刷新，落盘产物一致。

从源码结构看，这一语义体现在 setup.ts 的SetupCategorySummary计数体系中：每次运行都会按prompts、skills、nativeAgents、agentsMd、config五个类别分别统计updated（更新）、unchanged（未变化）、backedUp（已备份）、skipped（跳过）、removed（移除）五类结果，并在运行末尾输出汇总日志（例如backed_up=...、skipped=...、removed=...）。这种"分类统计 + 幂等合并"的设计正是为了支撑可重复执行：同一次 setup 只写必要变更，其余保持 unchanged。

在非交互运行场景，omx setup同样会刷新受管模型表等生成内容，无需--force——这一点由 setup-agents-overwrite.test.ts 中的用例refreshes the managed model table in non-interactive runs without requiring --force直接验证。

变更二：刷新路径覆盖前保留备份

当 setup 替换受管工件时，v0.8.4 引入了更强的备份行为，按适用场景分为两类：

1. 时间戳隔离备份（.omx/backups/setup/<timestamp>）

对于 config、hooks、skills、prompts、native agents 等常规受管文件，备份写入独立的备份根目录。由 setup.ts 的getBackupContext实现，按 scope 决定落盘位置：

• user scope：~/.omx/backups/setup/<timestamp>（基目录为 home）
• project scope：<projectRoot>/.omx/backups/setup/<timestamp>（基目录为项目根）

其中<timestamp>由new Date().toISOString()中的冒号替换为连字符生成，保证每次刷新产生独立的备份快照目录。备份实现（ensureBackup、ensureSnapshotBackup）会先mkdir递归创建目标目录，再用copyFile复制原文件，并输出backup <源路径> -> <备份路径>的日志；ensureSnapshotBackup还额外做了写入后的 lstat/内容回读校验，拒绝符号链接与非单链接文件，并拒绝将备份写出受控备份根目录之外（防止路径穿越）。

2. 确定性兄弟备份（.AGENTS.md.bkup递增命名）

对于 AGENTS.md 这类需要就地保留上下文的文件，使用确定性命名：moveExistingAgentsToDeterministicBackup会把现有文件移动为同目录下的.AGENTS.md.bkup，若该名称已存在则依次递增为.bkup1、.bkup2……测试 setup-agents-overwrite.test.ts 专门验证了这一递增行为：预先放置.bkup与.bkup1后，新备份落到.bkup2且内容与原文件一致。

备份行为带来的核心价值：

• 降低刷新既有本地 OMX 受管文件时的风险；
• 提供清晰的恢复路径，用户可随时检查上一状态（时间戳目录）或就地找回被替换的 AGENTS.md（.AGENTS.md.bkup）；
• 让 setup 自动化不再具有破坏性。

变更三：模型升级前的交互确认

当受管配置刷新需要把 Codex 根模型引用从gpt-5.3-codex升级到gpt-5.5时，v0.8.4 要求 setup 先询问用户。该机制在 setup.ts 中的实现链如下：

• LEGACY_SETUP_MODELS = new Set(["gpt-5.3-codex", "gpt-5.5"])（L415）标记"需要确认迁移"的历史模型集合；DEFAULT_SETUP_MODEL指向当前默认前沿模型（在src/config/models.ts中由DEFAULT_FRONTIER_MODEL定义）。
• planManagedConfig（L6304 起）先用getRootModelName(existingConfig)读取现有config.toml的根model字段；若命中LEGACY_SETUP_MODELS，则进入确认分支。
• 确认策略分两种：若调用方注入了modelUpgradePrompt回调（SetupOptions中的可注入钩子，便于测试与集成），则调用该回调；否则在 TTY 环境下降级为promptForModelUpgrade交互提问。若 stdin/stdout 均非 TTY（非交互运行），则不询问、不升级，保持现有模型引用不变。

交互提示由promptForModelUpgrade（L2700-L2723）实现，实际提问为：

Detected model "gpt-5.3-codex". Update to "gpt-5.5"? [Y/n]:

空回车或输入y/yes表示同意升级，此时planManagedConfig会把modelOverride设为DEFAULT_SETUP_MODEL，最终由buildMergedConfig写入合并后的config.toml。

这一设计解决的三个实际问题：

• 避免常规刷新中发生意外的模型升级，刷新与升级两个动作被解耦；
• 保留用户对 setup 修改既有配置的信任，重大变更（换模型）必须显式授权；
• 让受管默认值保持现代——用户拒绝时保留旧模型，同意时则顺滑迁移，不强制静默改写。

值得说明的是，随着项目演进，当前仓库中src/config/models.ts的DEFAULT_FRONTIER_MODEL已演进为gpt-5.6-sol，但"历史模型命中即确认"的机制本身仍然保留，模型集合与目标值均为可配置常量，读者可按当前安装版本的实际情况代入。

变更四：刷新与幂等性回归测试扩展

v0.8.4 围绕以下区域扩展/新增了测试与验证加固：

• setup 刷新行为：如refreshes the managed model table in non-interactive runs without requiring --force、keeps --merge-agents idempotent for already generated AGENTS.md and refreshes stale model rows；
• 限定范围（scoped）的覆盖处理：如refreshes only the explicit OMX-owned model block inside a user-authored AGENTS.md，确保只动 OMX 自有的模型块、不污染用户编写内容；
• setup 受管刷新期间的卸载（uninstall）兼容性：刷新与卸载路径共用文件时行为一致；
• 配置生成器的幂等性与 notify 感知的生成流：重复生成结果字节级稳定，且感知 notify 配置的合并；
• 流式回退测试中的 watcher 关闭/清理同步：针对发布门禁阶段发现的 watcher shutdown 竞态，补充了定向回归。

这些用例集中在 src/cli/tests/setup-agents-overwrite.test.ts，同时 setup 内部还提供了面向故障注入的测试接缝（如setNativeHookTransactionFailureInjectorForTest、setSetupLatePhaseFailureInjectorForTest），用于确定性地验证原子写入、回滚与备份路径在失败注入下的行为。

发布验证与质量门禁

v0.8.4 的发布验证证据记录在 docs/qa/release-readiness-0.8.4.md，验证结论为GO。计划的发布门禁与实测结果如下：

其中setup --dry-run是验证 setup 行为且不改动文件系统的关键手段：SetupOptions中的dryRun标志让整个计划/备份/写入流程只计算不落盘，适合在真实机器上安全预览刷新将产生的变更。

风险说明：这是聚焦omx setup刷新行为与受管模型升级提示的补丁发布，主要回归面是重复运行与限定范围安装场景下的 setup/config 刷新行为。发布门禁阶段还暴露并修复了两个附加质量问题——某个流式测试中的 watcher 关闭清理竞态，以及被严格 no-unused 检查捕获的未使用 setup 提示路径——修复后全部门禁重跑通过。

实操要点速览

1. 升级后重跑omx setup以刷新受管工件：无需--force即可获得最新模板与生成资产，刷新前会自动备份；
2. 备份位置：常规受管文件在~/.omx/backups/setup/<timestamp>（user scope）或<projectRoot>/.omx/backups/setup/<timestamp>（project scope）；被替换的 AGENTS.md 在同目录.AGENTS.md.bkup（依次递增.bkup1、.bkup2……）；
3. 模型升级会先询问：检测到历史模型（gpt-5.3-codex等）且处于 TTY 环境时，回答Y确认升级、n保留旧模型；非交互环境不升级；
4. 预检刷新影响面：使用omx setup --dry-run预览将要发生的变更，不产生任何写入；
5. 遇到异常时：先检查对应 scope 的备份目录恢复旧文件；若确认是回归，请附上复现步骤、日志与 CLI/runtime 信息提交 issue。

总结

v0.8.4 是 oh-my-codex 在"setup 可重入性"上的一次扎实补丁：默认刷新消除了过期生成内容的残留，覆盖前备份提供了明确的恢复路径，模型升级确认机制在"保持受管默认现代"与"不静默改写用户配置"之间取得了平衡，而 1940 项全量测试与覆盖刷新/幂等性/失败注入的定向回归则保证了这些行为变更的安全性。对于任何以自动化方式反复运行omx setup的安装与升级场景，这四项变更共同构成了可预测、可回滚、可审计的刷新模型。

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