企业官网建设流程全解析

OmX CLI 可发现性加固：从顶层 Help 到嵌套路由、Sparkshell 与 Session-Search 的实战指南

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

导读

本文围绕 OmX（oh-my-codex，omx）CLI 的"命令可发现性（discoverability）加固"专项任务展开，系统讲解如何通过最小改动提升操作者在仅凭 help 文本的情况下，快速找到正确 CLI 入口的能力。文章以仓库内missions/cli-discoverability-pilot/mission.md任务书为骨架，结合 src/cli/index.ts、src/cli/sparkshell.ts、src/cli/session-search.ts 等核心实现与对应测试，覆盖顶层 help、嵌套 help 路由、sparkshell 可发现性、session-search 可发现性四个重点，读完即可掌握该任务的评估口径、测试基线与最小落地方案。

Mission 背景：为什么 CLI 可发现性值得单独立项

missions/cli-discoverability-pilot/mission.md将本次任务定位为一次"可发现性加固（discoverability hardening）"试点：在保持既有命令路由语义（command routing semantics）不变的前提下，找到能够显著提升操作者成功率的最小改动集合——即操作者仅凭 help 文本（help text alone）就能发现并选中正确的 CLI 表面（CLI surface）。

任务书明确划定了四个重点方向：

1. 顶层 help（top-level help）：omx --help输出对命令、选项的覆盖是否完整清晰；
2. 嵌套 help 路由（nested help routing）：omx <subcommand> --help是否能正确路由到子命令自身的局部帮助，而不是退回或混入顶层帮助；
3. sparkshell 可发现性：作为原生侧车（native sidecar）入口的omx sparkshell能否在顶层帮助与子命令帮助中被准确发现；
4. session-search 可发现性：omx session及其search / friction / lock / pointer子能力是否在帮助体系中可见、可理解。

任务书给出的成功要点（Success hints）非常克制：

• 优先做小粒度的 help 文本或路由清晰度改动；
• 避免把范围扩大到无关的命令行为；
• 除非可发现性改进必须配套修改，否则保留既有文档与契约。

同时，missions/cli-discoverability-pilot/sandbox.md提供了沙箱规则与评估策略：

• 改动仅聚焦 CLI 可发现性，追求最小可评审 diff；
• 不新增依赖；
• 保留命令语义——本任务是关于可发现性，不是功能重设计；
• 评估器命令为node scripts/eval-cli-discoverability.js，输出 JSON，keep_policy为score_improvement；
• pass=true表示目标构建与可发现性测试切片全部通过；score为通过检查项占比（0.00～1.00），越高越好。

这一组约束决定了所有改动都应落在 help 文本、Usage 行、选项说明等"对外可读面"，而不是命令的解析与执行逻辑。

顶层 Help：CLI 的"第一道门面"

顶层帮助常量HELP定义于 src/cli/index.ts，是整个 CLI 可发现性的核心载体。其结构分为三块：Usage 命令清单、Options 选项清单、Launch policy 启动策略说明。

Usage：命令清单本身就是可发现性设计

顶层 Usage 对每个命令给出"一行命令 + 一行说明"的紧凑清单，例如：

omx exec Run codex exec non-interactively with OMX AGENTS/overlay injection omx mission <file> Run a prompt/checklist file sequentially through omx exec with durable summary omx sparkshell <command> [args...] omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>] Run native sparkshell sidecar for direct command execution or explicit tmux-pane summarization omx session Search and summarize local session history (--codex-home <path> escape hatch) Includes session lock diagnostics and verified-dead pointer recovery omx help Show this help message

可发现性视角下，这份清单的价值在于"入口即答案"：操作者不需要翻文档，仅凭顶层列表就能判断某个能力是否存在、命令名是什么、大致用途是什么。为可发现性做加固时，任何新增命令或重构命令名，都应同步更新该清单，并保持"命令 + 两行以内的说明"这一稳定排版，避免说明过长导致一屏装不下、命令被挤出视野。

Options：全局选项的语义自解释

Options 部分对每个全局选项给出了完整展开，其中对可发现性影响最大的是一组"shorthand"选项，因为它们直接映射到底层 Codex 参数：

--yolo Launch Codex in yolo mode (shorthand for: omx launch --yolo) --high Launch Codex with high reasoning effort (shorthand for: -c model_reasoning_effort="high") --xhigh Launch Codex with xhigh reasoning effort (shorthand for: -c model_reasoning_effort="xhigh") --madmax DANGEROUS: bypass Codex approvals and sandbox (alias for --dangerously-bypass-approvals-and-sandbox) --spark Use the Codex spark model (~1.3x faster) for team workers only Workers get the configured low-complexity team model; leader model unchanged --madmax-spark spark model for workers + bypass approvals for leader and workers (shorthand for: --spark --madmax)

源码层面，这些 shorthand 由normalizeCodexLaunchArgs统一翻译为 Codex 实际参数，测试见 src/cli/tests/index.test.ts。例如：

• --madmax→--dangerously-bypass-approvals-and-sandbox；
• --high→-c model_reasoning_effort="high"，--xhigh→-c model_reasoning_effort="xhigh"；
• 同时出现多个 shorthand 时按"最后一个生效"处理（--high --xhigh得到xhigh）；
• 重复的 bypass 相关参数会被去重；
• --之后的所有参数作为字面 Codex 参数原样保留，不再参与 OMX 层解析。

可发现性加固在这里的落点很典型：当用户试图使用并不存在的 shorthand 时，报错信息要指向正确出口。index.test.ts中专门验证了--max、--ultra两个"看似合理但不存在"的 shorthand 会抛出带指引的错误：

Unsupported OMX launch shorthand "--max". No --max shorthand exists; use agentReasoning for per-agent "max" or pass -c model_reasoning_effort=... directly to Codex. Run "omx help" for usage.

这类"错误信息即导航"的设计，正是 help 文本之外的第二层可发现性保障，也是本任务最小改动可以投入的地方：让任何入口的报错都落到Run "omx help" for usage或对应子命令的提示上。

Launch policy：环境变量入口的可发现性

顶层 help 的第三块是启动策略（Launch policy）说明，列出了OMX_LAUNCH_POLICY的取值与优先级：

OMX_LAUNCH_POLICY=auto Use the default policy: detached tmux when supported, direct otherwise OMX_LAUNCH_POLICY=direct Run without OMX tmux/HUD management OMX_LAUNCH_POLICY=tmux Force OMX-managed detached tmux launch OMX_LAUNCH_POLICY=detached-tmux Force OMX-managed detached tmux launch CLI policy flags (--direct/--tmux) override OMX_LAUNCH_POLICY; the last flag before -- wins. Unset or empty OMX_LAUNCH_POLICY returns to auto/default behavior.

这里明确写明"本版本有意不使用配置文件决定启动策略（Config files are intentionally not used for launch policy in this release）"。对于可发现性任务而言，这类"负空间说明"同样重要：它让操作者知道环境变量与命令行 flag 的优先级关系（flag 覆盖环境变量，且--之前的最后一个 flag 生效），避免在配置文件中寻找不存在的开关。

嵌套 Help 路由：让每个子命令拥有自己的帮助

顶层 help 解决"知道有什么命令"，嵌套 help 解决"知道某个命令怎么用"。src/cli/__tests__/nested-help-routing.test.ts是整个可发现性任务中约束最强的测试切片，它通过真实 spawndist/cli/omx.js子进程来验证路由行为，测试环境会设置OMX_AUTO_UPDATE=0、OMX_NOTIFY_FALLBACK=0、OMX_HOOK_DERIVED_SIGNALS=0以隔离副作用。

路由判定基准

该测试对一组[argv, expectedUsage]组合逐一断言两件事：

1. 状态码为 0（命令成功执行）；
2. stdout 匹配该子命令的专属 Usage 模式；
3. stdout 不得出现顶层帮助标题oh-my-codex (omx) - Multi-agent orchestration for Codex CLI。

也就是说，"嵌套 help 路由正确"的定义是：omx <cmd> --help必须命中命令自己的局部帮助，而不是把顶层帮助再打一遍。部分已覆盖的子命令与匹配模式如下：

值得注意的是explore与autoresearch两个命令被标记为 hard-deprecated，其局部帮助必须包含hard-deprecated legacy command surface字样，并向用户指路到替代入口（explore指向omx sparkshell，autoresearch指向$autoresearch）。可发现性任务中，"废弃命令也要被讲清楚出路"是容易遗漏但价值很高的点。

路由之外的语义保持

测试还验证了omx state read --input ... --json会穿过顶层 CLI 正常执行并输出{"exists":false,...}形式的 JSON，且 stdout 不出现Unknown command: state。这提醒我们：嵌套路由的正确性不只是 help 分发，还包括真实命令参数继续按原语义路由，任何可发现性改动都不能破坏这条链路。

Sparkshell 可发现性：原生侧车入口的"显形"

omx sparkshell是 OmX 的原生侧车（native sidecar）入口，用于直接执行命令或对指定 tmux pane 做摘要，并充当部分只读 explore 任务的 adaptive 后端。它在本任务中被单列为可发现性重点，是因为它同时涉及二进制解析链路与两层 help。

顶层 help 中的 sparkshell

src/cli/__tests__/sparkshell-cli.test.ts中omx sparkshell测试组通过真实运行omx --help断言：

• omx explore行必须包含DEPRECATED compatibility command; use normal repo inspection or omx sparkshell（把流量导向 sparkshell）；
• 必须出现omx sparkshell <command> [args...]；
• 必须出现omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>]；
• 必须出现explicit tmux-pane summarization说明。

这与顶层HELP常量中 sparkshell 两行 一一对应，说明顶层可发现性的最终评判标准就是帮助文本与测试断言的一致性——测试即契约。

子命令 help：sparkshell 的局部 Usage

omx sparkshell --help的局部帮助由sparkshellCommand分发：当第一个参数是--help或-h时输出SPARKSHELL_USAGE，否则在参数为空时抛出带 Usage 的Missing command to run错误。测试断言其局部帮助必须包含：

• Usage: omx sparkshell <command> [args...]；
• or: omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>]；
• 环境变量说明OMX_SPARKSHELL_BIN overrides the native binary；
• OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE overrides packaged summary instructions。

从 sparkshellCommand 实现 可以看到其执行链路与可发现性直接相关：先检查显式OMX_SPARKSHELL_BIN覆盖，否则走resolveSparkShellBinaryPathWithHydration()解析打包二进制或仓库本地构建产物；解析失败、spawn 报 missing/blocked、或检测到 GLIBC 不兼容（isSparkShellNativeCompatibilityFailure，例如 stderr 中出现version `GLIBC_2.39' not found）时，在没有显式覆盖的前提下回退到原始命令执行（runSparkShellFallback），并输出cause=...、path=...、state=glibc-incompatible、remediation=...形式的诊断。可发现性视角下，这套回退诊断本身就是"用户用不了原生侧车时，帮助他理解为什么"的机制，值得在帮助文本与错误信息两个层面同时打磨。

二进制解析优先级（源码佐证）

resolveSparkShellBinaryPath与resolveSparkShellBinaryPathWithHydration（src/cli/sparkshell.ts）的解析顺序在测试中体现得很清楚：

1. OMX_SPARKSHELL_BIN显式覆盖（最高优先级）；
2. 打包二进制：Linux 下按linux-x64-musl→linux-x64-glibc→linux-x64的候选顺序探测（packagedSparkShellBinaryCandidatePaths）；
3. 仓库本地构建产物repoLocalSparkShellBinaryPath与嵌套仓库本地产物；
4. 都不存在时，通过 native-release manifest 下载并缓存到OMX_NATIVE_CACHE_DIR（hydration）；
5. 全部失败且 manifest 不可用时抛native binary not found，未显式覆盖时走 raw 回退。

这一层源码细节对可发现性任务的启发是：帮助文本中描述的能力必须与实际解析行为一致，例如写明--tail-lines取值区间为 100～1000（parseSparkShellFallbackInvocation对非整数取值会抛--tail-lines must be an integer between 100 and 1000），写明--shell不接受额外参数，这些边界在局部 Usage 里说清楚，就能显著降低误用率。

Session-Search 可发现性：把历史会话能力讲清楚

omx session提供本地会话历史搜索与摘要，其局部帮助定义于 src/cli/session-search.ts，顶层 help 中对应条目为：

omx session Search and summarize local session history (--codex-home <path> escape hatch) Includes session lock diagnostics and verified-dead pointer recovery

src/cli/__tests__/session-search-help.test.ts对 session 可发现性做了三层验证：顶层 help、二级子命令 help、以及真实 lock/pointer 恢复行为。

顶层可见性

顶层帮助必须包含omx resume的--project/--codex-home说明、omx autoresearch [DEPRECATED] Use $autoresearch、以及omx session的完整一行说明。这再次印证了任务书强调的"顶层 help 与各入口联动"。

二级子命令 help

omx session --help必须输出：

Usage: omx session search <query> [options] omx session friction [options] omx session lock <inspect|recover> [--cwd <path>] [--json] omx session pointer recover [--cwd <path>] [--json]

其中search的选项完整清单（来自 session-search.ts）：

friction子命令的选项类似，但--limit默认值为 5、--since默认值为14d；lock与pointer子命令则接受--cwd与--json。测试同时要求omx session lock --help输出Usage: omx session lock <inspect|recover>、omx session pointer --help输出Usage: omx session pointer recover——即二级命令之下还有三级 help 路由，每一级都要有专属 Usage 行。

行为与帮助的一致性

该测试还演示了 session 命令在可发现性之外的语义保真：

• omx session lock inspect --cwd <dir> --json输出{ lockPath, safeToRecover }，且不会改动指针或锁文件内容；
• 当锁仍被持有者占用（owner.json.tmp-stalled）时，omx session lock recover --cwd <dir> --json返回action: none、recovered: false、reason: not safe to recover，退出码 1；
• 对"verified-dead"指针（pid 已不可能存活），omx session pointer recover会将其隔离（quarantine）到存档路径并保留精确字节（测试用OMX_RUNTIME_BINARY指向自定义 runtime 来模拟原子 rename），重复执行时给出status: absent/action: none。

这些行为恰好印证了 help 文本中 "Includes session lock diagnostics and verified-dead pointer recovery" 的措辞：help 写什么，行为就必须是什么，可发现性任务应当把帮助文本当作对行为的承诺来维护。

最小改动落地方案与评估闭环

综合 mission 目标、sandbox 规则与上述源码证据，可发现性加固的最小改动集应围绕"help 文本 + 路由清晰度"收敛：

1. 顶层 help 的自检清单

• 每个已存在命令都在HELP的 Usage 清单中有且仅有一行入口；
• 每个全局 shorthand（--high、--xhigh、--madmax、--spark等）都写出其展开语义或别名；
• 每个 deprecated 命令都写明替代入口（如explore→omx sparkshell）；
• 环境变量入口（如OMX_LAUNCH_POLICY）说明取值范围与优先级；
• 错误信息统一以Run "omx help" for usage或对应子命令 Usage 收尾。

2. 嵌套 help 的自检清单

• 每个子命令（尤其adapt、ask、state、hud、hooks、ralph、各 MCP 工具面）的局部帮助第一行必须是Usage:；
• omx <cmd> --help输出不得混入顶层标题；
• 三级命令（如session lock、session pointer）也要有专属 Usage 行。

3. 保持测试切片绿色

所有改动必须让以下测试继续通过，它们即评估器（node scripts/eval-cli-discoverability.js）实际运行的检查切片：

• src/cli/tests/index.test.ts（顶层 help 与参数归一化语义）；
• src/cli/tests/nested-help-routing.test.ts（嵌套路由契约）；
• src/cli/tests/sparkshell-cli.test.ts（sparkshell 帮助与回退）；
• src/cli/tests/session-search-help.test.ts（session 帮助与锁/指针恢复）。

4. 评估口径回顾

sandbox.md给出的评估策略是：pass=true代表目标构建与全部可发现性测试通过，score为通过占比（0～1.00），keep_policy=score_improvement意味着只接受分数提升的改动。因此任何改动都应先跑目标构建，再跑上述测试切片确认分数不降反升；新增 help 文本时同步更新对应测试断言，避免出现"文档写了但测试不认"的漂移。

小结

CLI 可发现性不是一句"help 写得详细点"能概括的工程，它在 OmX 仓库中有着明确的验收契约：顶层HELP常量、各子命令局部 Usage、sparkshell 的二进制解析与回退诊断、session 的三级帮助路由，四者由四组测试文件钉死。missions/cli-discoverability-pilot/mission.md教给我们的方法论可以复用：以最小 diff、零新依赖、零语义变更的方式，只改"帮助文本与路由清晰度"，就能让操作者在仅凭 help 的情况下完成从"知道有这个能力"到"知道怎么调用"的完整发现路径。

# 查看顶层帮助 omx --help # 查看任意子命令的局部帮助 omx sparkshell --help omx session --help omx session lock --help # 体验 session 搜索与健康检查 omx session search "worker inbox path" --since 7d --limit 5 omx session friction --project current omx session lock inspect --json

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