refactor(cli): 拆 17 个 handle* 到 commands/<name>.ts，index.ts 改为 dispatcher

[lizhiyao]

Summary

• src/cli/index.ts 1748 → 99 行，纯 dispatcher（domain/command 路由 + i18n + 顶层错误处理）
• 17 个内联 handle* 函数全部抽到 src/cli/commands/<name>.ts，每个文件 export 一个 execute(argv: string[])
• 共享类型 / helper（EvalResult / ReportServer / requireEvaluationReport / parseLastWindow）下沉到 src/cli/commands/_shared.ts

用户影响

无。纯代码组织重构：

• CLI 命令、flag、输出、exit code 全部不变
• 测量学不变量未触碰：judge prompt、Report schema、五层评分管道、Bootstrap CI、Krippendorff α、length-debias toggle 全部未改
• yarn lint && yarn build && yarn test 全绿（1062/1062）

迁移说明

无。对外 CLI 表面无变化。后续添加新命令的工序：

1. 新建 src/cli/commands/<name>.ts，export async function execute(argv)
2. 在 src/cli/index.ts 加一行 import + 一个 case

文件清单

src/cli/commands/
  _shared.ts            # 共享类型 + helper
  run.ts  doctor.ts  report.ts  init.ts  gate.ts  gen-samples.ts
  evolve.ts  diff.ts  gold.ts  debias-validate.ts  saturation.ts
  verdict.ts  diagnose.ts  failures.ts  analyze.ts

🤖 Generated with Claude Code

[lizhiyao]

P2: --dev 分支里 cliPath 现在会指向 commands/report.ts 对应的编译产物，而不是 CLI 入口。child args 会变成类似 node --watch-path ... dist/src/cli/commands/report.js bench report ...；这个 module 只 export execute，没有 top-level main()，所以子进程会直接退出，omk bench report --dev 不会启动 report server。这里需要恢复为真正的 CLI entrypoint（例如从 command module resolve 到 ../index.js，或使用当前 process.argv[1]），最好再补一个覆盖 --dev spawn argv 的回归测试。

[lizhiyao]

已修，commit 2a1f4f1：

const cliPath = resolve(fileURLToPath(import.meta.url), '..', '..', 'index.js');

import.meta.url 指 commands/report.js，往上两层到 cli/index.js — 这是真 CLI 入口，child 跑那里的 main()。

补了 test/cli/dev-spawn-argv.test.ts，mock spawn 断言 child argv 的 entrypoint 是 cli/index.js 不是 commands/report.js — 以后有人「简化」回 fileURLToPath(import.meta.url) 直接 fail。

附带观察（不在本 PR 修）：libDir = resolve(cliPath, '..', 'lib') 算出来是 dist/src/cli/lib，这个目录不存在，是重构前就有的。--dev 启动不会 crash（node --watch-path 对不存在路径静默），但 hot reload 应该一直没在工作。可以另开 fix PR 处理（建议改成 dist/src/）。

[lizhiyao]

补充建议（不阻塞）：

1. bench report --dev 修复后建议补一个定向回归测试，断言 spawn 出去的 entrypoint 是 CLI index.js 而不是 commands/report.js。现有 test/cli.test.ts 只覆盖 help / dry-run，抓不到这类 child process argv 回归。

2. 这次拆成 17 个 commands/<name>.ts 后，后续可以加一个轻量 dispatcher smoke test 或命令 registry 测试，覆盖 index.ts 里每个公开命令都能路由到对应 module。这样以后新增/移动 command 时，不容易出现文件存在但 switch 没接上的问题。

除前面那条 P2 外，我没有再看到需要阻塞合并的行为问题。

[lizhiyao]

建议两条都 follow up 了，commit 2a1f4f1：

1. --dev spawn 回归：test/cli/dev-spawn-argv.test.ts，vi.mock spawn，断言 child argv 第三项（cliPath）匹配 cli/index.js$，且不含 commands/。
2. dispatcher smoke：test/cli/dispatcher-routing.test.ts，遍历 commands/*.ts（除 _shared），断言每个 module 都被 index.ts import。这层只验 import 行，不验 case 名（analyze/doctor 走 domain 分支不在 switch 里），但够兜「文件存在但忘接」这种回归。

P2 inline thread 里也回了 — 顺带看到 libDir 指向不存在的 dist/src/cli/lib 是重构前的旧 bug，--dev 的 hot reload 一直没在工作。建议另开 fix PR，不混本次 refactor。

[lizhiyao]

顺手把 libDir 也修了，commit bb2f777：

const libDir: string = resolve(cliPath, '..', '..');  // dist/src/

旧值 dist/src/cli/lib 不存在，--dev 启动不会 crash 但 hot reload 一直没在工作。改成 dist/src/ 覆盖整个编译产物根（server / renderer / eval-core 都在那，report server 依赖它们）。

dev-spawn-argv 测试加了一条断言 libDir 不以 /lib 结尾，防止以后被「恢复」。

[lizhiyao]

按短期路线把 registry 也并进来了，commit 26e4b07：

• src/cli/commands/registry.ts — 两张 Record<string, CommandModule>：BENCH_COMMANDS（13 个 bench 子命令）+ DOMAIN_COMMANDS（analyze / doctor）
• src/cli/index.ts 99 → 43 行，17-case switch 换成查表。新增子命令只在 registry 加一行，不再回 index.ts 改两处
• dispatcher-routing.test.ts 改成验「commands 文件 ⊆ registry 注册」+「每个 entry 有 execute 函数」，比之前扫 import 行更直接。registry 自己漏注册也能抓到

CommandModule 形状先只 { execute }。--help 集中化和 process.exit 收敛走 follow-up——前者要把 15 处 if (argv.includes('--help')) 抽出来加 helpKey，后者动到所有 handler 改 exit code → throw / return，工作量都大，单独排期更稳。

[lizhiyao]

短期路线最后两件事都做完，分两个 commit：

b9d8c43 — --help 集中化 + helpKey 元数据

• CommandModule 加 helpKey: CliMessageKey
• dispatcher (index.ts) 在调 execute 前扫 --help / -h，命中就 print + exit 0
• 删 11 处 inline if (argv.includes('--help'))
• 顺手修两个旧 bug：
  • bench evolve --help / bench init --help 之前会被 parseArgsStrictOrExit 当 unknown option 报错（这俩没 inline 拦），现在响应 main help
  • bench gate --foo --help 之前只查 argv[0]，中间位置的 --help 会被 parseArgs 拒，现在任何位置都响应

11f6c84 — process.exit → throw CliExit

• 新加 src/cli/cli-exit.ts 暴露 CliExit Error 类
• 命令文件 / parse-strict / _shared 里 ~62 处 process.exit(N) 替换为 throw new CliExit(N)
• index.ts main().catch 兜底：CliExit → process.exit(code)，其他 throw 打印 stack + exit 1
• 唯一保留 process.exit 的：bench report --dev 子进程 spawn 的 exit listener（async callback，不在 main 调用栈）
• execute() 现在可以单测直接 try/catch 命中 CliExit 拿 code，不 kill 测试进程
• 补 test/cli/cli-exit.test.ts 演示三条 path

CLI 用户感知 exit code 完全一致（0/1/2 全部保留）。1071/1071 测试全绿。

[lizhiyao]

P1: 这里会把上面正常的 throw new CliExit(0) / throw new CliExit(1) 全部吞掉并改成 exit 1。process.exit(0) 改成 CliExit 后不再会绕过 catch，所以 gate 的 dry-run、PROGRESS、SOLO PASS 路径都会进入这个 catch，打印 Error: CliExit(0)，最终失败。omk bench gate && deploy 会因此在通过时也挡住。这里需要先 if (err instanceof CliExit) throw err;，只把真实运行错误包装成 CliExit(1)，并补一个 gate pass/dry-run 的 exit-code 回归测试。

[lizhiyao]

P1 + P3 都修了，commit f908ac6：

gate / run / evolve / doctor 的 catch 全部加 if (err instanceof CliExit) throw err;，只把真正运行时错误包成 CliExit(1)。gate 是真 bug——verdict 路径的 CliExit(0) 之前会被 catch 改成 CliExit(1)，PROGRESS / SOLO PASS / dry-run 全 exit 1，omk bench gate && deploy 在 PASS 时也会挡住部署。

parseJudgeModelsArgOrExit 改成 throw new CliExit(2)（之前漏改）。

回归测试两条：

• test/cli.test.ts：bench gate --dry-run 退 0（反例：旧代码会被 catch 改成 exit 1）
• test/cli/cli-exit.test.ts：parseJudgeModelsArgOrExit('claude') 抛 CliExit(2)

1073/1073 全绿。

[lizhiyao]

补充一个 P3（一致性，不阻塞）：

CliExit 收敛还漏了 src/cli/parse-run-config.ts 里的 parseJudgeModelsArgOrExit()，现在它仍然直接 process.exit(2)。所以 bench run --judge-models bad、bench evolve --judge-models bad、bench failures --judge-models bad、bench debias-validate ... --judge-models bad 这些路径在直接单测 execute() 时仍会 kill 测试进程，和本 PR 「execute() 可以 try/catch CliExit」的目标不完全一致。

建议把这个 helper 也改成 throw new CliExit(2)，并补一条 invalid --judge-models 的 CliExit(2) 测试。CLI 用户侧 exit code 不变。

[lizhiyao]

复查最新 head f908ac6：前面两条已解决。

• P1 gate 的 CliExit(0/1) 被 catch 吞掉的问题已修：gate / run / evolve / doctor 的 catch 都先透传 CliExit。
• P3 parseJudgeModelsArgOrExit() 仍直接 process.exit(2) 的一致性问题已修：现在改为 throw new CliExit(2)，并补了 invalid --judge-models 测试。
• bench gate --dry-run exits 0 回归测试覆盖了这次最关键的 gate pass-through 场景。

我本地跑了定向测试：yarn test test/cli.test.ts test/cli/cli-exit.test.ts test/cli/dev-spawn-argv.test.ts test/cli/dispatcher-routing.test.ts，21/21 pass。GitHub CI Node 22 / 24 也都 pass。

本轮没有新的阻塞发现。