OmX post-v0.4.4 迁移指南：catalog 整合、setup 作用域与 Spark 路由升级实战

导读

本文以 OmX（Oh My codeX）仓库中 docs/migration-mainline-post-v0.4.4.md 为核心骨架，系统梳理从 v0.4.4 合并到当前 mainline（含 PR #137 及后续修复）之后的关键破坏性变更与迁移路径。你将掌握：已移除的 prompts/skills 如何映射到新 catalog、omx setup 的 user/project 作用域安装模型与旧值自动迁移机制、团队工作流新增的 Spark worker 路由、通知器 verbosity 控制，以及升级后的一整套可执行验证清单。文中所有结论均有当前仓库源码与测试用例佐证，可直接对照 prompts/、skills/、src/cli/、src/notifications/ 等目录继续深入。

谁需要关注这次迁移

按照原文档的界定，以下场景会直接受到 v0.4.4 之后 mainline 变更的影响：

• 在旧笔记或脚本中调用了已移除的 prompts 或 skills；
• 依赖合并前（pre-consolidation）的 catalog 名称；
• 使用 omx setup 并需要可预期的安装作用域行为；
• 运行 omx team / tmux 工作流并希望获得最新可靠性修复；
• 使用 notifier 输出并需要粒度化的 verbosity 控制。

如果你不属于上述任何一类，升级影响面较小，但依然建议通读下文“验证清单”以确保环境一致性。

高层变更一览

mainline 相对 v0.4.4 的核心变化可归纳为六点：

1. prompts / skills catalog 整合：对 prompts 与 skills 进行合并整理，并清理废弃条目；
2. setup 作用域感知安装：omx setup 新增 user、project 两种安装模式，遗留的 project-local 值会被自动迁移；
3. Spark worker 路由：团队 worker 新增 --spark、--madmax-spark 标志；
4. 通知器 verbosity 控制：notifier 输出支持分级控制；
5. tmux 运行时加固：包括评审后 pane 捕获/输入（post-review pane capture/input）加固在内的一批更新落地；
6. 遗留引用清理：移除的 scientist / pipeline 相关陈旧引用被清扫。

其中，第 2 点与第 5 点在仓库中有最直接的实现证据：omx setup 的完整安装逻辑位于 src/cli/setup.ts，tmux 运行时与 pane 捕获相关加固可参考 src/hud/tmux.ts 与 src/team 目录下的实现。

已移除的 prompts 与 skills 全清单

已移除的 prompts

旧名称	迁移去向
deep-executor	见下表映射为 /prompts:executor
scientist	见下表映射为 /prompts:researcher

对照当前仓库 prompts/ 目录，可见目录中仅保留 executor.md、researcher.md 等活跃条目，已无 deep-executor 或 scientist，与文档陈述一致。

已移除的 skills

被移除的 skills 共九个：

• deepinit
• learn-about-omx
• learner
• pipeline
• project-session-manager
• psm
• release
• ultrapilot
• writer-memory

需要注意的一个细节：虽然 pipeline 已从正式功能中移除，但仓库 skills/pipeline/SKILL.md 仍保留了一个 Sunset stub（名称声明为 “Sunset stub — use $plan and $team directly instead”），其中明确写道：`$pipeline在 OMX 0.21 中已被移除，其可配置的阶段编排能力与$plan`（规划）和 `$team（执行）重叠且没有独立运行时。因此你在 ls skills时仍会看到pipeline/目录，这属于预期的“移除提示”行为，而非功能残留——它存在的意义是引导用户改用$plan`、`$team、$ultragoal`。

旧引用到新引用的映射表

文档给出了官方映射表，升级后在文档、脚本与个人快捷方式中应按下表替换：

旧引用	现在使用	说明
/prompts:deep-executor	/prompts:executor	deep-executor 是 executor 行为的废弃别名
/prompts:scientist	/prompts:researcher	研究型工作流统一走 researcher
$pipeline	$team（或显式 /prompts:* 排序）	team 是默认的编排 pipeline 表面
$ultrapilot	$team	使用基于团队的并行编排
$psm / $project-session-manager	仓库内无替代	从自动化中移除，或维护仓库外工具
$release	仓库内无替代	直接使用你自己的项目发布流程
$deepinit	omx agents-init [path]	仅用于 AGENTS.md 引导的轻量 CLI 继任者；只处理直接子目录，未托管文件在无 --force 时保留
$learn-about-omx / $learner / $writer-memory	仓库内无替代	从工作流/文档中移除陈旧引用

表格中有三处值得展开说明，它们都对应仓库中的真实实现。

$deepinit → omx agents-init：轻量引导继任者

deepinit 的官方继任者是 src/cli/agents-init.ts 中的 agents-init 子命令。从源码头部的用法说明可以看到它支持完整的参数面：

Usage: omx agents-init [path] [--dry-run] [--force] [--verbose]
       omx deepinit [path] [--dry-run] [--force] [--verbose]

Options:
  --dry-run   Show planned file updates without writing files
  --force     Overwrite existing unmanaged AGENTS.md files after taking a backup
  --verbose   Print per-file actions and skip reasons
  --help      Show this message

同时，omx agents-init 在解析时也会兼容 deepinit 调用形式。实现细节进一步印证了文档描述：

• 只处理直接子目录：默认列表上限为 12 个（DEFAULT_LIST_LIMIT = 12），并且内置了一组忽略目录名（.git、.omx、.codex、node_modules、dist、build、coverage、.next、.nuxt、.turbo、.cache、__pycache__、vendor、target、tmp、temp），避免污染构建产物与依赖目录；
• 托管标记机制：写入的 AGENTS.md 会带 <!-- OMX:AGENTS-INIT:MANAGED --> 标记，用户手写内容可置于 <!-- OMX:AGENTS-INIT:MANUAL:START --> 与 <!-- OMX:AGENTS-INIT:MANUAL:END --> 之间，保证后续刷新不被覆盖；
• 未托管文件保护：默认情况下未托管（无管理标记）的 AGENTS.md 不会被动，只有显式传 --force 才会在备份后覆盖——这正是文档所说 “unmanaged files preserved unless --force” 的源码级依据。

无仓库内替代的条目：不要自行脑补

$psm / $project-session-manager、$release、$learn-about-omx / $learner / $writer-memory 在映射表中明确标注 “No in-repo replacement”。这属于有意为之的设计决定：会话管理、发布、教程类记忆能力被判定为不适合纳入 catalog，官方建议要么移除自动化引用，要么由用户在仓库外自行维护工具链。升级时不应寻找“隐藏的等价命令”，直接清理即可。

$pipeline / $ultrapilot → $team

编排语义收敛为 $team 是本次 catalog 整合的核心理念。当前 src/team 目录包含 96 个源码文件，是整个仓库中体量最大的功能模块之一，其团队编排、worker 分发与状态机实现为“team 作为默认编排表面”提供了坚实的运行时基础。原文档还提示可退化为显式 /prompts:* 排序，即自行组合 prompts/ 目录中的单角色 prompt（如 planner.md → executor.md → verifier.md）实现串行流水线。

升级后的验证清单

拉取最新 mainline 后，文档建议按以下顺序逐项验证。每条命令都对应当前仓库可复现的行为：

1. 确认本地遗留引用已清除

rg -n "deep-executor|scientist|pipeline|project-session-manager|\bpsm\b|ultrapilot|learn-about-omx|writer-memory|learner|deepinit|\brelease\b" README.md docs scripts .omx -S

该命令对 README、docs、scripts 与 .omx 目录做大小写敏感的全文搜索（-S 表示 smart case）。注意：由于 skills/pipeline/SKILL.md 属于移除提示 stub，若扫描范围包含 skills/ 目录会命中 pipeline 字样，属预期结果，不代表功能残留。

2. 确认 prompts catalog 不含已移除条目

ls prompts

对照上文清单，应看不到 deep-executor、scientist。

3. 确认 skills catalog 不含已移除条目

ls skills

同样地，九个已移除 skill 不应出现在列表中（pipeline/ 的 sunset stub 除外，见上文说明）。

4. 验证 setup 作用域选项可用

omx help | rg -e "--scope|project"

5. 验证团队/tmux 健康检查

omx doctor --team

6. 若使用 Spark worker 路由，验证标志存在

omx --help | rg "spark|madmax-spark"

深入源码：omx setup 的 scope 模型与自动迁移

本次迁移中最容易被忽略却又影响最深的变化，是 omx setup 从“单一全局安装”演进为作用域感知安装模型。

两种作用域的定义

从 src/cli/setup.ts 的交互提示可以看到两种模式的官方描述：

• user（默认）：安装到 codex home 目录（~/.codex 体系，skills 默认落在 ~/.codex/skills），对所有项目生效；
• project：安装到项目本地的 ./.codex，仅对当前项目生效。

源码中 DEFAULT_SETUP_SCOPE: SetupScope = "user" 明确了默认值，setupScopePrompt() 会读取持久化偏好并给出带 (default) 标注的选择项。project 作用域下还会对 AGENTS.md 模板做路径重写（applyScopePathRewritesToAgentsTemplate），把 skills 路径改写为 `./.codex/skills`，确保生成的内容指向项目本地目录。

遗留 project-local 的自动迁移

旧版本持久化的 project-local 值在升级后会触发自动迁移。源码与测试给出了确凿证据：

• src/cli/agents.ts 中 agents add/remove 的参数解析将 project 与遗留的 project-local 一律归一为 project；
• src/cli/tests/setup-scope.test.ts 测试用例直接断言“Migrating persisted setup scope "project-local"”的日志输出；
• src/cli/tests/index.test.ts 验证了旧 project-local 持久化 scope 的迁移，以及迁移后 CODEX_HOME 的解析行为；
• src/cli/tests/update.test.ts 覆盖了升级时构造 update setup refresh 参数的迁移路径。

换言之，只要你之前用 project-local 语义做过项目级安装，升级后 omx setup / omx update 都会自动把它当作 project 处理，无需手工改配置。

scope 行为的可预期性保障

作用域语义还被多个测试锁定：setup-scope.test.ts、setup-preferences.test.ts、setup-refresh.test.ts、update.test.ts 分别验证了偏好持久化、刷新时作用域解析与更新路径的一致性，确保“预测性安装行为”不是口头承诺而是被 CI 持续守护的契约。

通知器 verbosity 控制

notifier 新增的 verbosity 控制在 src/notifications/config.ts 中有完整实现：

• 四级 verbosity：verbose、agent、session、minimal（VALID_VERBOSITY_LEVELS），并按数值分级排序（verbose: 3 最高）；
• 事件级门槛：每种通知事件类型（如 session-start、session-stop、session-end、session-idle、ask-user-question 等）声明最低要求的 verbosity 等级，通过 VERBOSITY_RANK[verbosity] >= VERBOSITY_RANK[required] 判定是否放行；
• 环境变量覆盖：OMX_NOTIFY_VERBOSITY 环境变量可覆盖配置文件中的 verbosity（见 src/notifications/tests/verbosity.test.ts 中的相关断言）；
• tmux tail 联动：shouldIncludeTmuxTail(verbosity) 决定当前等级下是否附带 tmux 输出尾部，verbose 等级下恒为 true。

配置从 ~/.codex/.omx-config.json 读取，并保留对旧 stopHookCallbacks 格式的向后兼容迁移。这意味着升级后你可以用更细的粒度控制通知噪音：minimal 只保留关键事件，verbose 全量输出。

tmux 运行时加固

文档提到的 tmux 运行时加固（含 post-review pane 捕获/输入硬化）与 omx doctor --team 的健康检查能力相互配合。相关实现分布在 src/hud/tmux.ts（tmux 会话管理）、src/hud 的 render/state/reconcile 模块以及 src/team 的团队状态机中。如果你日常使用 omx team + tmux 组合，升级后应优先运行 omx doctor --team 验证 pane 状态机、捕获与输入路径均处于健康状态。

升级后的落地建议

1. 先扫后改：用上文 rg 命令全局扫描，把旧引用替换为映射表中的新名称，注意区分“无替代条目”（直接移除）与“有替代条目”（改写调用）；
2. 再验环境：依次执行 prompts/skills 目录检查、omx help 的 scope 标志检查、omx doctor --team 健康检查；
3. 验证 Spark 路由：团队 worker 若需要 Spark 快速通道，确认 --spark / --madmax-spark 标志在 omx --help 中可见（标志常量定义于 src/cli/constants.ts）；
4. 更新自动化：把 $deepinit 类调用改写为 omx agents-init，并利用 --dry-run 预览、--force 谨慎覆盖；
5. 回归通知配置：按需设置 verbosity 等级，必要时用 OMX_NOTIFY_VERBOSITY 做临时覆盖。

延伸阅读

• 版本变更历史：CHANGELOG.md
• 项目总览：README.md
• setup 安装实现：src/cli/setup.ts
• agents-init 引导实现：src/cli/agents-init.ts
• notifier 配置与 verbosity：src/notifications/config.ts
• scope 迁移测试：src/cli/tests/setup-scope.test.ts
• sunset stub 示例：skills/pipeline/SKILL.md