CLI 架构与启动编排：omx 的命令路由与启动流水线

CLI 架构与启动编排：omx 的命令路由与启动流水线

学习目标

• 理解 omx CLI 的命令路由和分发机制
• 掌握标志规范化（--madmax → 底层 Codex 标志）
• 了解三级启动策略决策树（direct / inside-tmux / detached-tmux）
• 理解 preLaunch → runCodex → postLaunch 三阶段启动流水线

前置知识

本章聚焦 Oh-My-Codex 的具体工程实践，无需前置阅读。

---

项目实践

入口点

src/cli/omx.ts（薄包装）：
import { main } from "./index.js"
main(process.argv.slice(2))

所有逻辑在 src/cli/index.ts（187KB，5000+ 行）。

命令路由

伪代码（resolveCliInvocation）：
function resolveCliInvocation(args):
  if args[0] in ["--help", "-h"]:
    return { command: "help", launchArgs: [] }
  if args[0] in ["--version", "-v"]:
    return { command: "version", launchArgs: [] }
  if args.length == 0 or args[0].startsWith("--"):
    return { command: "launch", launchArgs: args }  // 默认启动
  if args[0] == "launch":
    return { command: "launch", launchArgs: args.slice(1) }
  if args[0] == "exec":
    return { command: "exec", launchArgs: args.slice(1) }
  if args[0] == "resume":
    return { command: "resume", launchArgs: args.slice(1) }
  // 已知子命令
  if args[0] in KNOWN_COMMANDS:
    return { command: args[0], launchArgs: args.slice(1) }
  // 未知命令
  return { command: "unknown", raw: args[0] }

KNOWN_COMMANDS = [
  "setup", "doctor", "team", "update", "uninstall",
  "ralph", "ultragoal", "performance-goal", "ask", "question",
  "adapt", "explore", "api", "sparkshell", "session", "auth",
  "cleanup", "list", "agents", "agents-init", "hud", "sidecar",
  "state", "mcp-serve", "tmux-hook", "hooks", "status", "cancel",
  "reasoning"
]

关键设计：如果第一个参数以 - 开头但不是已知命令，仍然被视为启动调用。这使得 omx --yolo 或 omx --high 无需 launch 子命令即可启动。

标志规范化

伪代码（normalizeCodexLaunchArgs）：
function normalizeCodexLaunchArgs(args):
  result = []

  for arg in args:
    if arg == "--madmax":
      // 翻译为 Codex 的底层标志
      if not result.contains("--dangerously-bypass-approvals-and-sandbox"):
        result.push("--dangerously-bypass-approvals-and-sandbox")
    else if arg == "--high":
      // 翻译为推理强度配置
      result.push('-c', 'model_reasoning_effort="high"')
    else if arg == "--xhigh":
      result.push('-c', 'model_reasoning_effort="xhigh"')
    else if arg == "--spark" or arg == "--madmax-spark":
      // Spark 模型标志，分离给 worker 路由
      sparkModel = resolveSparkModel()
    else:
      result.push(arg)

  return result

Worktree 解析

伪代码（parseWorktreeMode）：
function parseWorktreeMode(args):
  for i, arg in args:
    if arg == "-w":
      return { enabled: true, detached: true, name: null, remainingArgs: args.remove(i) }
    if arg.startsWith("-w="):
      name = arg.slice(3)
      return { enabled: true, detached: false, name: name, remainingArgs: args.remove(i) }
    if arg == "--worktree":
      next = args[i+1]
      if next and not next.startsWith("-"):
        return { enabled: true, detached: false, name: next, remainingArgs: args.remove(i, i+1) }
      return { enabled: true, detached: true, name: null, remainingArgs: args.remove(i) }

  return { enabled: false }

Worktree 路径规划：

伪代码（planWorktreeTarget）：
function planWorktreeTarget(name, detached):
  repoRoot = findGitRoot()
  parentDir = `${repoRoot}/../${basename(repoRoot)}.omx-worktrees`

  if detached:
    return `${parentDir}/launch-detached`
  else:
    return `${parentDir}/${name}`

启动策略决策树

伪代码（resolveCodexLaunchPolicy）：
function resolveCodexLaunchPolicy(explicitPolicy, env):
  // 优先级从高到低
  if explicitPolicy == "direct":
    return "direct"
  if env.TMUX is set:
    return "inside-tmux"
  if explicitPolicy == "detached-tmux":
    return tmuxAvailable() ? "detached-tmux" : "direct"
  if platform == "win32":
    return "direct"
  if not stdin.isTTY or not stdout.isTTY:
    return "direct"
  if tmuxAvailable():
    return "detached-tmux"
  return "direct"

OMX_LAUNCH_POLICY 环境变量（auto、direct、tmux、detached-tmux）提供低优先级覆盖，CLI 标志优先。

三阶段启动流水线

Phase 2 的三种路径：

策略	Codex 运行方式	HUD
inside-tmux	当前窗口格	底部窗口格 omx hud --watch
direct	直接阻塞式运行	无 HUD
detached-tmux	新的 detached tmux 会话	底部窗口格 omx hud --watch

Madmax 隔离

伪代码（activateMadmaxIsolationIfNeeded）：
function activateMadmaxIsolationIfNeeded():
  if not hasMadmaxFlag():
    return

  // 创建隔离根目录
  isoRoot = mktempDir()
  env.OMX_ROOT = isoRoot
  env.OMXBOX_ACTIVE = "1"
  env.OMX_SOURCE_CWD = process.cwd()

  // 所有状态重定向到隔离目录
  process.chdir(isoRoot)

会话作用域 Codex Home

伪代码（prepareCodexHomeForLaunch）：
function prepareCodexHomeForLaunch(sessionId):
  originalHome = resolveCodexHome()
  sessionHome = mktempDir()  // 或 ~/.codex/sessions/<sessionId>

  // 复制关键文件
  copyIfExists(`${originalHome}/config.toml`, `${sessionHome}/config.toml`)
  copyIfExists(`${originalHome}/AGENTS.md`, `${sessionHome}/AGENTS.md`)

  env.CODEX_HOME = sessionHome
  return sessionHome

问题与规避

问题	后果	OMX 的规避策略
Worktree 目标已存在且脏	并发修改冲突	脏检查 + 警告，用户确认
Detached worktree 源 HEAD 前进	后续启动因 worktree_target_mismatch 失败	使用 named worktree 代替
tmux 不可用但请求 detached-tmux	启动失败	自动回退到 direct
Codex Home 配置不一致	认证失败	会话作用域 Codex Home 复制原始配置

设计取舍

为什么 CLI 将所有逻辑集中在 index.ts（187KB）？

OMX 的 src/cli/index.ts 是一个 187KB 的巨型文件，包含命令路由、标志解析、启动编排和所有内联命令处理。

优势：

• 导入简单：一个文件包含所有 CLI 逻辑
• 共享状态容易：无需跨文件传递上下文
• 构建简单：TypeScript 编译一个文件即可

代价：

• 可维护性差：5000+ 行难以导航
• 编译慢：TypeScript 编译器处理大文件较慢
• 测试困难：难以隔离测试单个命令

替代方案：

• 每个命令独立模块 + 路由器导入（更模块化但增加了上下文传递的复杂度）

参考来源

• Oh-My-Codex v0.18.9 源码 — src/cli/index.ts（187KB，主 CLI 逻辑）
• Oh-My-Codex v0.18.9 源码 — src/cli/omx.ts（入口点）
• Oh-My-Codex v0.18.9 源码 — src/cli/constants.ts（标志常量）
• Oh-My-Codex v0.18.9 源码 — src/team/worktree.ts（Worktree 管理）