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导读本文围绕 OmXoh-my-codexomxCLI 的命令可发现性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。任务书明确划定了四个重点方向顶层 helptop-level helpomx --help输出对命令、选项的覆盖是否完整清晰嵌套 help 路由nested help routingomx subcommand --help是否能正确路由到子命令自身的局部帮助而不是退回或混入顶层帮助sparkshell 可发现性作为原生侧车native sidecar入口的omx sparkshell能否在顶层帮助与子命令帮助中被准确发现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输出 JSONkeep_policy为score_improvementpasstrue表示目标构建与可发现性测试切片全部通过score为通过检查项占比0.001.00越高越好。这一组约束决定了所有改动都应落在 help 文本、Usage 行、选项说明等对外可读面而不是命令的解析与执行逻辑。顶层 HelpCLI 的第一道门面顶层帮助常量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_efforthigh) --xhigh Launch Codex with xhigh reasoning effort (shorthand for: -c model_reasoning_effortxhigh) --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_efforthigh--xhigh→-c model_reasoning_effortxhigh同时出现多个 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_POLICYauto Use the default policy: detached tmux when supported, direct otherwise OMX_LAUNCH_POLICYdirect Run without OMX tmux/HUD management OMX_LAUNCH_POLICYtmux Force OMX-managed detached tmux launch OMX_LAUNCH_POLICYdetached-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_UPDATE0、OMX_NOTIFY_FALLBACK0、OMX_HOOK_DERIVED_SIGNALS0以隔离副作用。路由判定基准该测试对一组[argv, expectedUsage]组合逐一断言两件事状态码为 0命令成功执行stdout 匹配该子命令的专属 Usage 模式stdout 不得出现顶层帮助标题oh-my-codex (omx) - Multi-agent orchestration for Codex CLI。也就是说嵌套 help 路由正确的定义是omx cmd --help必须命中命令自己的局部帮助而不是把顶层帮助再打一遍。部分已覆盖的子命令与匹配模式如下调用期望的局部帮助模式omx adapt --helpUsage: omx adapt target probe\|status\|init\|envelope\|doctoromx ask --helpUsage: omx ask claude\|gemini question or taskomx question --helpomx question - OMX-owned blocking user question entrypointomx state --helpUsage: omx state read\|write\|clear\|list-active\|get-statusomx hud --helpUsage:后接omx hud Show current HUD stateomx hooks --helpUsage:后接omx hooks initomx notepad --helpUsage: omx notepad tool-name且包含Available tools:与notepad_readomx trace --helpUsage: omx trace tool-name且包含trace_timelineomx code-intel --helpUsage: omx code-intel tool-name且包含lsp_diagnosticsomx mcp-serve --helpUsage: omx mcp-serve targetomx ralph --helpomx ralph - Launch Codex with ralph persistence mode active值得注意的是explore与autoresearch两个命令被标记为 hard-deprecated其局部帮助必须包含hard-deprecated legacy command surface字样并向用户指路到替代入口explore指向omx sparkshellautoresearch指向$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 中的 sparkshellsrc/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 两行 一一对应说明顶层可发现性的最终评判标准就是帮助文本与测试断言的一致性——测试即契约。子命令 helpsparkshell 的局部 Usageomx 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 binaryOMX_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...、stateglibc-incompatible、remediation...形式的诊断。可发现性视角下这套回退诊断本身就是用户用不了原生侧车时帮助他理解为什么的机制值得在帮助文本与错误信息两个层面同时打磨。二进制解析优先级源码佐证resolveSparkShellBinaryPath与resolveSparkShellBinaryPathWithHydrationsrc/cli/sparkshell.ts的解析顺序在测试中体现得很清楚OMX_SPARKSHELL_BIN显式覆盖最高优先级打包二进制Linux 下按linux-x64-musl→linux-x64-glibc→linux-x64的候选顺序探测packagedSparkShellBinaryCandidatePaths仓库本地构建产物repoLocalSparkShellBinaryPath与嵌套仓库本地产物都不存在时通过 native-release manifest 下载并缓存到OMX_NATIVE_CACHE_DIRhydration全部失败且 manifest 不可用时抛native binary not found未显式覆盖时走 raw 回退。这一层源码细节对可发现性任务的启发是帮助文本中描述的能力必须与实际解析行为一致例如写明--tail-lines取值区间为 1001000parseSparkShellFallbackInvocation对非整数取值会抛--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 recoverysrc/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 与各入口联动。二级子命令 helpomx 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选项说明--limit n最大返回条数默认 10--session id限定到某个会话 id 或 id 片段--since spec按时效过滤示例7d、24h、2026-03-10--project scope按项目上下文过滤current|all|cwd-fragment--codex-home path只搜索指定 Codex homeescape hatch--context n摘要上下文字符数默认 80--case-sensitive精确大小写匹配--json输出结构化 JSON-h, --help显示帮助friction子命令的选项类似但--limit默认值为 5、--since默认值为14dlock与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.tssparkshell 帮助与回退src/cli/tests/session-search-help.test.tssession 帮助与锁/指针恢复。4. 评估口径回顾sandbox.md给出的评估策略是passtrue代表目标构建与全部可发现性测试通过score为通过占比01.00keep_policyscore_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考