oh-my-codex 0.18.11 发布就绪检查全解析：explore 硬弃用、Spark 路由诊断与版本化验证流程

oh-my-codex 0.18.11 发布就绪检查全解析：explore 硬弃用、Spark 路由诊断与版本化验证流程

【免费下载链接】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 仓库的发布就绪检查文档 docs/qa/release-readiness-0.18.11.md，系统拆解 0.18.11 版本从功能范围、PR 清单、版本同步审计到本地验证与 CI 发布门禁的完整发布流程。读完本文，你将掌握该项目的发布就绪判定标准、omx doctor新增的 Spark/model lane 路由诊断原理、omx explore硬弃用后的迁移路径，以及如何用check-version-sync.js、npm pack --dry-run等命令复现一次可靠的版本发布前验证。

版本范围与发布时间线

0.18.11 是紧跟在v0.18.10之后的一个清理型（cleanup）补丁版本，其版本边界定义非常精确：

• 前一版本 Tag：v0.18.10
• 候选分支：发布准备期使用专用 worktree 分支omx-release-0.18.11，代码源来自origin/dev
• 冻结候选 commit：06baf8f4e41541778835686f7696b95cd2b39316，对应提交信息为fix(doctor): add Spark/model lane routing diagnostic (#2757) (#2758)
• 对比区间：v0.18.10..06baf8f4，共7 个 commit
• 目标发布 Tag：v0.18.11（在分支 CI 与 main 晋升通过后创建）
• 血缘校验：git merge-base --is-ancestor v0.18.10 06baf8f4返回 true，确认前一 Tag 确实是当前候选的祖先，保证版本区间内无分支漂移
• Dev HEAD CI 预检：GitHub Actions run27171589905在06baf8f4上 completed/success

这种"先冻结 commit → 校验血缘 → 预跑 CI → 本地验证 → 再推 tag"的顺序，是该仓库发布流程的固定节奏：任何发布候选都必须先证明自己是基于上一版本之上的线性演进，才能进入后续验证环节。

发布范围：四项清理性变更

0.18.11 打包了0.18.10之后的清理列车（cleanup train），共四个维度：

1. omx explore命令面硬弃用：移除剩余的对omx explore的全局 AGENTS 指引提及
2. omx doctorSpark/model lane 路由诊断：新增诊断项，排查 Spark 配额闲置问题
3. tmux HUD 启动拆分保护：在局促（cramped）的既有 tmux 窗口中跳过启动时的 HUD 拆分
4. Catalog wiki skill manifest 条目：为 wiki skill 补充 catalog 清单条目

这四个变更覆盖了 CLI 面（explore 弃用）、诊断面（doctor）、HUD 运行时面（tmux 拆分）和目录元数据面（catalog），体现了该版本"清理 + 加固"的整体定位。

合并 PR 清单

此外对比区间内还有两个无对应 PR 的直接提交（direct-to-dev docs commit）：

• 0d7a3899— docs(model)：澄清 Codex 模型迁移切换指引（#2748）
• 6567fd3b— docs(model)：回滚被错误归属的模型切换指引（净效果为无文档变更）

两个文档提交一加一减相互抵消，因此最终净变更仍是上述 5 个 PR 覆盖的功能面。Issue 层面，发布准备期没有针对本区间的 open issue 被追踪，closed issue 的覆盖情况由上述 PR 清单代表。

omx explore硬弃用：从命令面到源码实现

本次发布最核心的变更是omx explore命令面的硬弃用。在 src/cli/explore.ts 中可以找到完整的弃用语义：

omx explore is hard-deprecated and the direct command surface has been removed. Use normal Codex repository inspection tools/subagents for read-only repository lookups. Use `omx sparkshell -- <command>` only for explicit shell-native read-only evidence or `--tmux-pane` summaries.

关键点在于**硬弃用（hard-deprecate）**与软弃用的区别：

• 旧的兼容形式（omx explore --prompt "<prompt>"、omx explore --prompt-file <file>）全部有意失败（fail intentionally）
• 唯一保留的入口是omx explore --help，用于展示弃用说明与迁移指引
• 源码层面，exploreCommand仅在参数全部为帮助标志（--help/-h/help）时输出帮助文本，其余任何调用都会直接throw new Error(...)抛出包含弃用信息的错误（见 src/cli/explore.ts）

这种"非帮助即报错"的实现保证了旧脚本一旦触发omx explore会立刻得到明确反馈，而不是静默降级。

迁移路径

按 src/cli/explore.ts 中的EXPLORE_HELP说明，用户应迁移到两条路径：

1. 普通只读仓库查询：直接使用 Codex 标准的仓库检查工具/subagent，无需任何 OMX 扩展命令
2. shell 原生只读取证：使用omx sparkshell -- <command>执行显式的 shell 原生只读命令，或使用--tmux-pane摘要

兼容路由的残留与诊断

虽然命令面已移除，但兼容路由开关USE_OMX_EXPLORE_CMD在 doctor 中仍被检查。src/cli/doctor.ts 中的checkExploreRoutingFromState会区分三种来源：

• 环境变量来源（env）：USE_OMX_EXPLORE_CMD被设置且为启用值时输出 warn，建议"移除USE_OMX_EXPLORE_CMD或置 0"
• 配置文件来源（config）：在config.toml的[shell_environment_policy.set]下设置USE_OMX_EXPLORE_CMD = "0"为推荐做法；若仍为启用值则输出 warn
• 默认来源（default）：config.toml不存在或未设置时，直接判定为"deprecated by default"，状态 pass

与此同时，checkExploreHarness（src/cli/doctor.ts）在既无OMX_EXPLORE_BIN覆盖、又未启用兼容路由时，会输出：

skipped: omx explore is hard-deprecated and explore routing is disabled by default; use omx sparkshell for shell-native read-only evidence

这印证了弃用后的默认行为：explore harness 检查被跳过而非执行，只有显式覆盖（OMX_EXPLORE_BIN）或残留路由开关才触发进一步检查。

omx doctorSpark/model lane 路由诊断（#2758）

本次发布中技术含量最高的新增功能，是 src/cli/doctor.ts 中的checkSparkRouting诊断。它的目标是解决一个真实痛点：Spark lane 配额（如gpt-5.6-luna对应的快速模型配额）已正确接线解析，却始终未被消耗。

诊断输出面：三条 lane 的模型解析

诊断首先汇总当前生效的模型路由全景：

lanes: frontier=`<frontier模型>`, standard=`<standard模型>`, spark=`<spark模型>` (source: <来源>)

• frontier / standard / spark 三条 lane 的默认模型分别由getMainDefaultModel、getStandardDefaultModel、getSparkDefaultModel解析（见 src/agents/native-config.ts 的导入，以及 src/agents/native-config.ts 处 Spark 模型的解析调用）
• spark模型来源通过resolveSparkModelSource单独判定
• 模型类别体系定义在 src/agents/definitions.ts，modelClass取值为'frontier' | 'standard' | 'fast'，其中fast类即 Spark lane 的挂靠目标

四类可诊断问题

诊断会逐一检查所有可安装的 Spark lane agent（getInstallableSparkLaneAgentNames，即modelClass === "fast"的原生 agent），并报告以下问题：

1. agent toml 缺失：<agent>.toml不存在于paths.agentsDir下 → 建议omx setup --force
2. 无 model 字段 / 模型与解析结果不一致：<agent>.toml中的 model 与解析出的 Spark 默认模型不同 → 判定为 stale install，建议omx setup --force
3. 与显式 agentModels 覆盖不一致：agent 存在agentModels.<agent>显式覆盖时，toml 内 model 必须与之吻合
4. provider 路由异常（两类子问题）：
   • toml 内model_provider与 config 根 provider 不一致
   • toml 内model_provider为非默认 provider（非openai）——此时会提示原生 Codex Spark 配额只有在 Spark 由默认 provider 服务时才会消耗

通过时的输出

所有问题清零后，诊断返回 pass，并附带接线汇总：

Spark-lane native agent(s) wired: <agent1> -> `<模型>` (provider: <provider>), ... If Spark quota is still unused, the leader may not be delegating read-only lookups to the Spark lane, or the Codex usage view may lag.

值得注意最后这句：即使一切接线正确，Spark 配额仍可能闲置——此时问题不在配置而在运行时行为（leader 未把只读查询委托给 Spark lane），或 Codex 用量视图存在滞后。这体现了该诊断的设计边界：它只负责验证"配置接线"这一层，不越权声称能诊断所有配额问题。

tmux HUD：局促窗口中的启动拆分保护（#2755）

第三个运行时层面的变更是 HUD 启动逻辑：当用户已身处一个局促（行数不足）的既有 tmux 窗口时，跳过启动时的 HUD 拆分，避免挤压原有工作区。

仓库中存在HUD_TMUX_MIN_LAUNCH_WINDOW_HEIGHT_LINES常量（见 src/hud/constants.ts，并在 src/hud/tests/reconcile.test.ts 中与HUD_TMUX_HEIGHT_LINES、HUD_TMUX_ULTRAGOAL_HEIGHT_LINES一同被测试引用），其语义即"启动 HUD 拆分所需的最小窗口高度"。HUD 相关的窗口几何测试（paneWidth/paneHeight/windowHeight 组合）大量存在于 src/hud/tests/reconcile.test.ts，用于验证各种窗口尺寸下的拆分决策。

这一变更的实战意义是：对在窄小终端窗口内已开启多个 pane 的用户，HUD 启动不应再"强行插入"造成布局被破坏；取而代之地，HUD 会跳过该次拆分，待窗口空间充足时再行初始化。从仓库结构看，HUD 逻辑分散在 src/hud 下的constants.ts、reconcile.ts、tmux.ts等模块，测试则通过reconcile.test.ts中构造的 pane 几何数据模拟真实 tmux 布局。

Catalog wiki skill manifest 条目（#2747）

第四个变更属于元数据层：为 wiki skill 补充 catalog manifest 条目。在 src/catalog/manifest.json 中可以看到：

{ "name": "wiki", "category": "utility", "status": "active" }

• wiki 被归类为utility（工具类）skill，状态为active
• src/catalog/installable.ts 将wiki列为SETUP_ONLY_INSTALLABLE_SKILLS，即仅在 setup 阶段安装的 skill
• 对应测试 src/catalog/tests/schema.test.ts 明确断言"includes wiki as an active utility skill"，并校验其category === 'utility'与status === 'active'
• 生成的公开目录 src/catalog/generated/public-catalog.json 同步包含wiki条目

该变更的意义在于：catalog 是项目 skill 市场的单一事实来源（SSOT），wiki skill 此前可能因 manifest 缺失而无法被安装器正确识别或展示，补齐条目后保证了 catalog 生成的公共目录、schema 校验与安装逻辑三者的自洽。

版本与 lockfile 审计

发布就绪检查中，"版本号在所有声明位置保持一致"是硬性要求。0.18.11 的审计覆盖了：

• 根 package.json 与 package-lock.json：升至0.18.11
• 根 Cargo.toml workspace package 版本及根 Cargo.lock 中的全部 workspace 包：omx-api、omx-explore-harness、omx-mux、omx-runtime、omx-runtime-core、omx-sparkshell均升至0.18.11
• plugins/oh-my-codex/.codex-plugin/plugin.json：同步至0.18.11

版本一致性由专用脚本 src/scripts/check-version-sync.ts 强制校验。该脚本会：

1. 读取根package.json与Cargo.toml的[workspace.package].version
2. 依次检查各 crate（omx-api、omx-explore、omx-runtime-core、omx-mux、omx-runtime、omx-sparkshell）的Cargo.toml是否使用version.workspace = true继承 workspace 版本
3. 传入--tag v0.18.11时，额外校验 tag 必须等于v${package.json 版本}

0.18.11 的校验结果为：

PASS (package=0.18.11 workspace=0.18.11 tag=v0.18.11)

这一环节保证了 npm 包版本、Rust workspace 版本与 Git tag 三者绝不会出现"发布后才发现版本号漂移"的尴尬。

本地验证证据链：八项检查全部 PASS

发布准备在专用 worktreeomx-release-0.18.11中执行，以下为本地验证的完整清单（所有日志留存于.omx/release-0.18.11/logs/）：

几点值得展开的细节：

• node dist/cli/omx.js doctor的"13 passed / 4 warnings / 0 failed"直接反映本文前述的新增诊断（Spark routing、Explore routing 等）已纳入默认诊断套件并在此版本上全绿
• npm pack --dry-run的数字（3.9 MB 压缩包、24.2 MB 解压、3049 文件）可作为该版本包体积的基线，后续版本可据此对比体积漂移
• generate-release-body.js在本地打一个注解v0.18.11tag 后即可生成最终 release body，且必须保留完整对比区间 PR 清单与 Contributors 段——这保证了 GitHub release 正文与合并历史严格对应

CI 与发布门禁：尚未通过的最终关卡

截至该文档定稿，远程侧门禁仍处于 pending 状态，共五道：

1. Release-prepdevCI 绿：等待 push/merge 到 dev 后触发
2. Main promotion CI 绿：等待 main 快进（fast-forward）后触发
3. Tag 触发的 release workflow：等待v0.18.11tag 推送
4. GitHub release 证明：pending
5. npm 发布证明：pending

这一"本地全绿、远程待验"的划分很关键：本地验证只能证明"这份代码在本地是可构建、可安装、可运行的"，而最终的发布结论必须依赖远程 CI 的独立证据——GitHub Actions 在 dev 分支、main 分支、tag 三个触发点上的绿标，以及 GitHub release 与 npm registry 上的实际产物。

就绪结论与可复用的发布流程

0.18.11 的最终裁决是：

本地发布准备已就绪可推送：版本同步、构建、CLI 冒烟（--help、doctor）、包 dry-run、打包安装冒烟、release body 生成全部通过。远程分支 CI、main 晋升、tag 工作流、GitHub release 证明与 npm 证明是剩余的最后发布门禁。

从这个案例可以提炼出该项目可复用的发布准备范式：

1. 冻结与血缘：锁定候选 commit，用git merge-base --is-ancestor证明与前一 tag 的线性关系
2. 范围盘点：通过 PR 清单 + 无 PR 直提交清单，完整界定净变更
3. 版本同步审计：check-version-sync.js统一 npm、Rust workspace 与 tag 三处版本
4. 本地冒烟矩阵：npm ci→npm run build→ CLI--help/doctor→npm pack --dry-run→smoke:packed-install→git diff --check→ release body 生成
5. 远程门禁分离：将"本地就绪"与"远程发布完成"明确区隔，任何一步 pending 都不允许宣布发布完成

对想要复现或扩展该流程的读者，可直接阅读 docs/qa/release-readiness-0.18.11.md 原文、src/scripts/check-version-sync.ts 的版本校验实现，以及 src/cli/doctor.ts 中 Spark 路由诊断的完整判定逻辑——这三处构成了"发布门禁 → 版本一致性 → 运行时健康诊断"的完整证据链。

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