oh-my-knowledge 0.26.0 → 0.28.0

package/dist/src/cli/index.js

@@ -1,1534 +1,61 @@
 #!/usr/bin/env node
-import { resolve } from 'node:path';
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
-import { tCli, getCliLang, parseLangFromArgv, langFromArgv } from './i18n.js';
-import { parseRunConfig, DEFAULT_REPORTS_DIR, COMMON_OPTIONS, } from './parse-run-config.js';
-import { makeOnProgress } from './progress.js';
-import { computeRunTally } from './run-tally.js';
+import { tCli, getCliLang, parseLangFromArgv } from './i18n.js';
 import { checkUpdate } from './update-check.js';
-import { parseArgsStrictOrExit } from './parse-strict.js';
-function requireEvaluationReport(report, id, lang) {
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id }));
-        process.exit(1);
-    }
-    if (report.kind === 'batch-evaluation') {
-        console.error(lang === 'zh'
-            ? `报告 ${id} 是 BatchEvaluationReport。该命令需要单次 EvaluationReport；请使用其中的 child reportId。`
-            : `Report ${id} is a BatchEvaluationReport. This command requires an EvaluationReport; use a child reportId from the batch.`);
-        process.exit(1);
-    }
-    return report;
-}
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-async function main() {
-    const lang = getCliLang(parseLangFromArgv(process.argv));
-    checkUpdate(lang);
-    const [domain, command, ...rest] = process.argv.slice(2);
-    if (!domain || domain === '--help' || domain === '-h') {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    if (domain === 'analyze') {
-        const args = command ? [command, ...rest] : [];
-        await handleAnalyze(args);
-        return;
-    }
-    if (domain === 'doctor') {
-        const args = command ? [command, ...rest] : [];
-        await handleDoctor(args);
-        return;
-    }
-    if (domain !== 'bench') {
-        console.error(tCli('cli.common.unknown_domain', lang, { domain }));
-        process.exit(1);
-    }
-    if (!command || command === '--help' || command === '-h') {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    switch (command) {
-        case 'run':
-            await handleRun(rest);
-            break;
-        case 'report':
-            await handleReport(rest);
-            break;
-        case 'init':
-            await handleInit(rest);
-            break;
-        case 'gate':
-            await handleGate(rest);
-            break;
-        case 'gen-samples':
-            await handleGenSamples(rest);
-            break;
-        case 'evolve':
-            await handleEvolve(rest);
-            break;
-        case 'diff':
-            await handleDiff(rest);
-            break;
-        case 'gold':
-            await handleGold(rest);
-            break;
-        case 'debias-validate':
-            await handleDebiasValidate(rest);
-            break;
-        case 'saturation':
-            await handleSaturation(rest);
-            break;
-        case 'verdict':
-            await handleVerdict(rest);
-            break;
-        case 'diagnose':
-            await handleDiagnose(rest);
-            break;
-        case 'failures':
-            await handleFailures(rest);
-            break;
-        default:
-            console.error(tCli('cli.common.unknown_bench_command', lang, { command }));
-            process.exit(1);
-    }
-}
-// ---------------------------------------------------------------------------
-// Progress callback
-// ---------------------------------------------------------------------------
+import { CliExit } from './cli-exit.js';
+import { PRODUCT_COMMANDS } from './commands/registry.js';
 /**
- * Factory: 闭住 lang, 返回 onProgress callback。evaluation engine 回调时不传
- * 上下文, 所以 lang 必须在 handler 入口处通过 closure 传进来。
+ * --help / -h 在 argv 任意位置都打印对应 helpKey 内容并 exit 0。
+ * 集中在 dispatcher 处理,因为下游 execute 走 parseArgsStrictOrExit,
+ * 那一层 strict:true 不识别 --help 会当 unknown option 报错。
  */
-// ---------------------------------------------------------------------------
-// handleRun
-// ---------------------------------------------------------------------------
-async function handleRun(argv) {
-    const lang = langFromArgv(argv);
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    // 注: 这里**不**给 parseArgs default 值, 否则 values.xxx 永远不为 undefined,
-    // CLI > eval.yaml > hardcoded-default 三级 fallback 区分不开 ("用户没传" vs "用户传了等于 default 值")。
-    // hardcoded default 在下面处理 undefined 时显式给。
-    const { values, config, evalConfig } = parseRunConfig(argv, {
-        blind: { type: 'boolean' },
-        repeat: { type: 'string' },
-        'judge-repeat': { type: 'string' },
-        bootstrap: { type: 'boolean' },
-        'bootstrap-samples': { type: 'string' },
-        'gold-dir': { type: 'string' },
-        'no-debias-length': { type: 'boolean' },
-        'budget-usd': { type: 'string' },
-        'budget-per-sample-usd': { type: 'string' },
-        'budget-per-sample-ms': { type: 'string' },
-    });
-    const { runEvaluation, runMultiple, runBatchEvaluation } = await import('../eval-workflows/run-evaluation.js');
-    if (values.blind !== undefined) {
-        config.blind = values.blind;
-    }
-    config.onProgress = makeOnProgress(lang);
-    // --repeat: CLI > eval.yaml > 1. 非 ≥1 整数时提示并钳到 1。
-    const repeatRaw = values.repeat;
-    const parsedRepeat = repeatRaw !== undefined ? Number(repeatRaw) : (evalConfig?.repeat ?? 1);
-    if (repeatRaw !== undefined && (!Number.isFinite(parsedRepeat) || parsedRepeat < 1)) {
-        process.stderr.write(tCli('cli.run.invalid_repeat', lang, { value: repeatRaw }));
-    }
-    const repeatCount = Math.max(1, Math.floor(parsedRepeat) || 1);
-    // --judge-repeat: CLI > eval.yaml > 1.
-    const judgeRepeatRaw = values['judge-repeat'];
-    const parsedJudgeRepeat = judgeRepeatRaw !== undefined ? Number(judgeRepeatRaw) : (evalConfig?.judgeRepeat ?? 1);
-    if (judgeRepeatRaw !== undefined && (!Number.isFinite(parsedJudgeRepeat) || parsedJudgeRepeat < 1)) {
-        process.stderr.write(tCli('cli.run.invalid_judge_repeat', lang, { value: judgeRepeatRaw }));
-    }
-    const judgeRepeatCount = Math.max(1, Math.floor(parsedJudgeRepeat) || 1);
-    if (judgeRepeatCount > 1)
-        config.judgeRepeat = judgeRepeatCount;
-    // --budget-usd / --budget-per-sample-usd / --budget-per-sample-ms:
-    //  hard budget caps. CLI flags override config-file values. When the
-    // total-USD cap is exceeded mid-run, remaining tasks are skipped and a
-    // partial report is persisted with meta.budgetExhausted=true.
-    const budgetUSD = values['budget-usd'] != null ? Number(values['budget-usd']) : undefined;
-    const budgetPerSampleUSD = values['budget-per-sample-usd'] != null ? Number(values['budget-per-sample-usd']) : undefined;
-    const budgetPerSampleMs = values['budget-per-sample-ms'] != null ? Number(values['budget-per-sample-ms']) : undefined;
-    if (budgetUSD !== undefined || budgetPerSampleUSD !== undefined || budgetPerSampleMs !== undefined) {
-        config.budget = {
-            ...(budgetUSD !== undefined && Number.isFinite(budgetUSD) && budgetUSD >= 0 ? { totalUSD: budgetUSD } : {}),
-            ...(budgetPerSampleUSD !== undefined && Number.isFinite(budgetPerSampleUSD) && budgetPerSampleUSD >= 0 ? { perSampleUSD: budgetPerSampleUSD } : {}),
-            ...(budgetPerSampleMs !== undefined && Number.isFinite(budgetPerSampleMs) && budgetPerSampleMs >= 0 ? { perSampleMs: budgetPerSampleMs } : {}),
-        };
-    }
-    // --no-debias-length / eval.yaml `lengthDebias: false`: opt out of length-controlled prompt。
-    // Default debias-on (judge prompt v3-cot-length); flip off only to reproduce historical reports。
-    // CLI 显式 --no-debias-length > eval.yaml lengthDebias > 默认 true。
-    const lengthDebiasOff = values['no-debias-length'] === true
-        || (values['no-debias-length'] === undefined && evalConfig?.lengthDebias === false);
-    if (lengthDebiasOff) {
-        config.lengthDebias = false;
-        process.stderr.write(tCli('cli.run.no_debias_length_active', lang));
-    }
-    // --bootstrap / --bootstrap-samples: CLI > eval.yaml > default(off / 1000)。
-    const bootstrapEnabled = values.bootstrap === true
-        || (values.bootstrap === undefined && evalConfig?.bootstrap === true);
-    if (bootstrapEnabled) {
-        config.bootstrap = true;
-        const bsRaw = values['bootstrap-samples'];
-        const parsedBs = bsRaw !== undefined ? Number(bsRaw) : (evalConfig?.bootstrapSamples ?? 1000);
-        if (bsRaw !== undefined && (!Number.isFinite(parsedBs) || parsedBs < 100)) {
-            process.stderr.write(tCli('cli.run.invalid_bootstrap_samples', lang, { value: bsRaw }));
-        }
-        const bsCount = Math.max(100, Math.floor(parsedBs) || 1000);
-        if (bsCount > 10000) {
-            process.stderr.write(tCli('cli.run.bootstrap_samples_too_large', lang, { n: bsCount }));
-        }
-        config.bootstrapSamples = bsCount;
-    }
-    // 注入 lang 让 evaluation pipeline 能渲染 doctor 报告(失败时)。
-    config.lang = lang;
-    if (values['skip-connectivity']) {
-        process.stderr.write(tCli('cli.run.skip_connectivity_warning', lang) + '\n');
-    }
-    try {
-        // --batch mode: evaluate each skill independently
-        if (values.batch) {
-            const { report, filePath } = await runBatchEvaluation({
-                ...config,
-                repeat: repeatCount,
-                onSkillProgress({ phase, skill, current, total }) {
-                    if (phase === 'start') {
-                        process.stderr.write(tCli('cli.run.skill_section', lang, {
-                            i: current ?? '', n: total ?? '', skill: skill ?? '',
-                        }));
-                    }
-                },
-            });
-            console.log(JSON.stringify(report, null, 2));
-            if (filePath) {
-                process.stderr.write(tCli('cli.run.batch_complete', lang));
-                const tally = computeRunTally(report);
-                process.stderr.write(tCli('cli.run.tally', lang, tally));
-                process.stderr.write(tCli('cli.run.report_saved', lang, { path: filePath }));
-                if (!values['no-serve'] && process.stdout.isTTY) {
-                    const { createReportServer } = await import('../server/report-server.js');
-                    const server = createReportServer({ reportsDir: config.outputDir });
-                    const serverUrl = await server.start();
-                    const reportUrl = `${serverUrl}/reports/${report.id}`;
-                    process.stderr.write(tCli('cli.run.report_server_running', lang, { url: serverUrl }));
-                    process.stderr.write(tCli('cli.run.report_server_view', lang, { url: reportUrl }));
-                    process.stderr.write(tCli('cli.run.report_server_stop', lang));
-                    const { platform } = await import('node:os');
-                    const openCmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start' : 'xdg-open';
-                    const { execFile: execFileCb } = await import('node:child_process');
-                    execFileCb(openCmd, [reportUrl], () => { });
-                }
-                else if (!values['no-serve']) {
-                    process.stderr.write(tCli('cli.run.no_serve_in_non_tty', lang));
-                    process.stderr.write(tCli('cli.run.no_serve_view_hint', lang, { dir: config.outputDir }));
-                }
-            }
-            return;
-        }
-        let report;
-        let filePath;
-        if (repeatCount > 1) {
-            const result = await runMultiple({
-                ...config,
-                repeat: repeatCount,
-                onRepeatProgress({ run, total }) {
-                    process.stderr.write(tCli('cli.run.run_section', lang, { i: run, n: total }));
-                },
-            });
-            report = result.report;
-            filePath = null;
-        }
-        else {
-            const result = (await runEvaluation(config));
-            report = result.report;
-            filePath = result.filePath;
-        }
-        // --gold-dir / eval.yaml goldDir: compute α/κ/Pearson against gold annotations and re-persist.
-        const goldDir = values['gold-dir'] ?? evalConfig?.goldDir;
-        if (goldDir && filePath) {
-            const { attachGoldAgreementToReport, formatGoldCompare } = await import('../grading/gold-cli.js');
-            const out = attachGoldAgreementToReport({
-                report,
-                goldDir,
-                outputDir: config.outputDir,
-                samples: config.bootstrapSamples,
-            });
-            if (out.result && out.gold) {
-                process.stderr.write(formatGoldCompare(out.result, out.gold));
-                if (out.result.contaminationWarning) {
-                    process.stderr.write(tCli('cli.run.contamination_warning', lang, {
-                        warning: out.result.contaminationWarning,
-                    }));
-                }
-            }
-            else {
-                process.stderr.write(tCli('cli.run.gold_load_failed', lang, { dir: goldDir }));
-                for (const m of out.loadIssues) {
-                    process.stderr.write(tCli('cli.run.gold_load_issue', lang, { message: m }));
-                }
-            }
-        }
-        console.log(JSON.stringify(report, null, 2));
-        if (filePath) {
-            process.stderr.write(tCli('cli.run.eval_complete', lang));
-            const tally = computeRunTally(report);
-            process.stderr.write(tCli('cli.run.tally', lang, tally));
-            process.stderr.write(tCli('cli.run.report_saved', lang, { path: filePath }));
-            if (!values['no-serve'] && process.stdout.isTTY) {
-                // Auto-start report server
-                const { createReportServer } = await import('../server/report-server.js');
-                const server = createReportServer({
-                    reportsDir: config.outputDir,
-                });
-                const serverUrl = await server.start();
-                const reportUrl = `${serverUrl}/reports/${report.id}`;
-                process.stderr.write(tCli('cli.run.report_server_running', lang, { url: serverUrl }));
-                process.stderr.write(tCli('cli.run.report_server_view', lang, { url: reportUrl }));
-                process.stderr.write(tCli('cli.run.report_server_stop', lang));
-                // Auto-open report in browser
-                const { platform } = await import('node:os');
-                const openCmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start' : 'xdg-open';
-                const { execFile: execFileCb } = await import('node:child_process');
-                execFileCb(openCmd, [reportUrl], () => { });
-            }
-            else if (!values['no-serve']) {
-                process.stderr.write(tCli('cli.run.no_serve_in_non_tty', lang));
-                process.stderr.write(tCli('cli.run.no_serve_view_hint', lang, { dir: config.outputDir }));
-            }
-        }
-    }
-    catch (err) {
-        console.error(tCli('cli.common.error_prefix', lang, { message: err.message }));
-        process.exit(1);
-    }
-}
-// ---------------------------------------------------------------------------
-// handleReport
-// ---------------------------------------------------------------------------
-async function handleReport(argv) {
-    const lang = langFromArgv(argv);
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: argv,
-        options: {
-            ...COMMON_OPTIONS,
-            port: { type: 'string', default: '7799' },
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            export: { type: 'string' },
-            dev: { type: 'boolean', default: false },
-        },
-    });
-    // Dev mode: restart server on file changes via node --watch
-    if (values.dev && !process.env.__OMK_DEV_CHILD) {
-        const { spawn } = await import('node:child_process');
-        const { fileURLToPath } = await import('node:url');
-        const cliPath = fileURLToPath(import.meta.url);
-        const libDir = resolve(cliPath, '..', 'lib');
-        const args = [
-            '--watch-path', libDir, cliPath, 'bench', 'report',
-            '--port', values.port,
-            '--reports-dir', values['reports-dir'],
-        ];
-        const child = spawn(process.execPath, args, {
-            stdio: 'inherit',
-            env: { ...process.env, __OMK_DEV_CHILD: '1' },
-        });
-        child.on('exit', (code) => process.exit(code || 0));
-        return;
-    }
-    if (values.export) {
-        const { createFileStore } = await import('../server/report-store.js');
-        const { renderReportDocumentDetail } = await import('../renderer/html-renderer.js');
-        const { writeFileSync } = await import('node:fs');
-        const store = createFileStore(resolve(values['reports-dir']));
-        const report = await store.get(values.export);
-        if (!report) {
-            console.error(tCli('cli.common.report_not_found', lang, { id: values.export }));
-            process.exit(1);
-        }
-        const html = renderReportDocumentDetail(report);
-        const outPath = resolve(`${values.export}.html`);
-        writeFileSync(outPath, html);
-        console.log(`Exported to: ${outPath}`);
-        console.log('Open in browser, or Ctrl+P to save as PDF');
-        return;
-    }
-    const { createReportServer } = await import('../server/report-server.js');
-    const server = createReportServer({
-        port: Number(values.port),
-        reportsDir: resolve(values['reports-dir']),
-    });
-    const url = await server.start();
-    console.log(`Report server running at ${url}`);
-    console.log('Press Ctrl+C to stop');
-}
-// ---------------------------------------------------------------------------
-// handleInit
-// ---------------------------------------------------------------------------
-const INIT_SAMPLES = `[
-  {
-    "sample_id": "s001",
-    "prompt": "审查以下代码",
-    "context": "function authenticate(username, password) {\\n  const query = \`SELECT * FROM users WHERE name='\${username}' AND pass='\${password}'\`;\\n  return db.execute(query);\\n}",
-    "rubric": "应识别 SQL 注入风险，建议使用参数化查询",
-    "assertions": [
-      { "type": "contains", "value": "SQL", "weight": 1 },
-      { "type": "contains", "value": "注入", "weight": 1 },
-      { "type": "contains", "value": "参数化", "weight": 0.5 },
-      { "type": "not_contains", "value": "没有问题", "weight": 0.5 }
-    ],
-    "dimensions": {
-      "security": "是否准确识别出 SQL 注入漏洞并说明其危害",
-      "actionability": "是否给出可直接使用的参数化查询修复代码"
-    }
-  },
-  {
-    "sample_id": "s002",
-    "prompt": "审查以下代码",
-    "context": "async function fetchData(url) {\\n  const res = await fetch(url);\\n  const data = await res.json();\\n  return data;\\n}",
-    "rubric": "应指出缺少错误处理（网络异常、非 JSON 响应、HTTP 错误状态码）",
-    "assertions": [
-      { "type": "contains", "value": "错误处理", "weight": 1 },
-      { "type": "regex", "pattern": "try[\\\\s\\\\S]*catch|错误|异常|error", "flags": "i", "weight": 1 },
-      { "type": "contains", "value": "status", "weight": 0.5 }
-    ],
-    "dimensions": {
-      "robustness": "是否指出了所有缺失的错误处理场景",
-      "actionability": "是否给出了完整的 try-catch 修复代码"
-    }
-  },
-  {
-    "sample_id": "s003",
-    "prompt": "审查以下代码",
-    "context": "function renderComment(comment) {\\n  document.getElementById('output').innerHTML = '<p>' + comment + '</p>';\\n}",
-    "rubric": "应识别 XSS 风险，建议使用 textContent 或转义 HTML",
-    "assertions": [
-      { "type": "contains", "value": "XSS", "weight": 1 },
-      { "type": "regex", "pattern": "textContent|转义|escape|sanitize", "flags": "i", "weight": 1 },
-      { "type": "contains", "value": "innerHTML", "weight": 0.5 }
-    ],
-    "dimensions": {
-      "security": "是否准确识别出 XSS 漏洞并说明攻击方式",
-      "actionability": "是否给出使用 textContent 或转义的修复代码"
-    }
-  }
-]
-`;
-// 模板带 Claude Code SKILL.md 兼容 frontmatter(name + description),让用户
-// 可以把 init 出来的 SKILL.md 直接 deploy 到 ~/.claude/skills/ 给 Claude Code 用,
-// 一份文件双向 dogfood(omk 评测 + Claude 部署)。omk 当前不 strip frontmatter,
-// 它会跟着 leak 进 system prompt — 在 model 行为层面是无害噪声,跨 executor 一致。
-const INIT_SKILL_V1 = `---
-name: code-review-v1
-description: 简单代码审查 skill,识别明显问题
----
-
-# Code review v1
-
-你是一个代码审查助手。请审查用户提供的代码，指出潜在问题。
-`;
-const INIT_SKILL_V2 = `---
-name: code-review-v2
-description: 多维度代码审查,覆盖安全 / 健壮 / 可维护 / 性能,带严重程度标注
----
-
-# Code review v2
-
-你是一个高级代码审查专家。请从以下维度审查用户提供的代码：
-
-1. 安全性：是否存在注入、XSS、敏感信息泄露等风险
-2. 健壮性：是否有适当的错误处理和边界检查
-3. 可维护性：命名是否清晰、结构是否合理
-4. 性能：是否存在明显的性能瓶颈
-
-对每个维度给出具体的改进建议，并标注严重程度（高/中/低）。
-`;
-// ---------------------------------------------------------------------------
-// handleAnalyze (v0.18 skill 健康度日报)
-// ---------------------------------------------------------------------------
-function parseLastWindow(spec) {
-    // "7d" / "24h" / "30m" → ISO timestamp (from = now - spec)
-    const m = /^(\d+)([dhm])$/.exec(spec);
-    if (!m)
-        return null;
-    const n = Number(m[1]);
-    const unit = m[2];
-    const ms = unit === 'd' ? n * 86400_000 : unit === 'h' ? n * 3600_000 : n * 60_000;
-    return new Date(Date.now() - ms).toISOString();
-}
-async function handleDoctor(argv) {
-    const lang = langFromArgv(argv);
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(tCli('cli.help.doctor_usage', lang));
-        process.exit(0);
-    }
-    const { values, positionals } = parseArgsStrictOrExit({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            ...COMMON_OPTIONS,
-            json: { type: 'boolean', default: false },
-            gate: { type: 'boolean', default: false },
-            executor: { type: 'string' },
-            model: { type: 'string' },
-            timeout: { type: 'string' },
-        },
-    });
-    const target = positionals[0] ?? null;
-    const executorName = values.executor ?? 'claude';
-    const model = values.model ?? 'sonnet';
-    const timeoutRaw = values.timeout;
-    const timeoutSec = timeoutRaw != null ? Number(timeoutRaw) : 8;
-    const timeoutMs = Math.max(1000, Math.floor((Number.isFinite(timeoutSec) ? timeoutSec : 8) * 1000));
-    const cwd = process.cwd();
-    const { runDoctor } = await import('../doctor/index.js');
-    const { renderDoctorReportText, renderDoctorReportJson } = await import('../doctor/renderer.js');
-    let report;
-    try {
-        report = await runDoctor({
-            target,
-            cwd,
-            executorName,
-            model,
-            timeoutMs,
-            lang,
-        });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(tCli('cli.doctor.no_skill_found', lang, { path: target ?? cwd }));
-        console.error(`(${msg})`);
-        process.exit(1);
-    }
-    if (report.skills.length === 0) {
-        console.error(tCli('cli.doctor.no_skill_found', lang, { path: target ?? cwd }));
-        process.exit(1);
-    }
-    const isJson = values.json;
-    const isGate = values.gate;
-    if (isJson) {
-        console.log(renderDoctorReportJson(report));
-    }
-    else if (isGate) {
-        // gate 模式: 静默 stdout, fail 时简短 stderr 摘要(供 CI 抓 exit code)
-        if (report.outcome === 'failed') {
-            const summary = lang === 'zh'
-                ? `doctor failed: ${report.totals.fail} 个 skill 未通过 (${report.totals.warn} warn / ${report.totals.pass} pass)`
-                : `doctor failed: ${report.totals.fail} skills did not pass (${report.totals.warn} warn / ${report.totals.pass} pass)`;
-            console.error(summary);
-        }
-    }
-    else {
-        renderDoctorReportText(report, lang);
-    }
-    process.exit(report.outcome === 'failed' ? 1 : 0);
-}
-async function handleAnalyze(argv) {
-    const lang = langFromArgv(argv);
-    const { values: rawValues, positionals } = parseArgsStrictOrExit({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            ...COMMON_OPTIONS,
-            kb: { type: 'string' },
-            last: { type: 'string' },
-            from: { type: 'string' },
-            to: { type: 'string' },
-            skills: { type: 'string' },
-            'output-dir': { type: 'string' },
-        },
-    });
-    // 该 handler options 全是 string-typed (无 boolean), 收紧 cast 让 caller 直接 use values.xxx 当 string 用。
-    const values = rawValues;
-    const dir = positionals[0];
-    if (!dir) {
-        console.error(tCli('cli.help.analyze_usage', lang));
-        process.exit(1);
-    }
-    const tracePath = resolve(dir);
-    const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
-    if (!existsSync(tracePath)) {
-        console.error(`Trace path does not exist: ${tracePath}`);
-        process.exit(1);
-    }
-    // 时间窗: --from/--to 优先, --last fallback
-    let from = values.from;
-    if (!from && values.last) {
-        const inferred = parseLastWindow(values.last);
-        if (!inferred) {
-            console.error(`Invalid --last format: "${values.last}". Expected e.g. "7d" / "24h" / "30m".`);
-            process.exit(1);
-        }
-        from = inferred;
-    }
-    const to = values.to;
-    const skills = values.skills ? values.skills.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
-    console.log(`[omk] analyzing ${tracePath}...`);
-    const { computeSkillHealthReport } = await import('../observability/skill-health-analyzer.js');
-    const report = computeSkillHealthReport(tracePath, {
-        kbRoot: values.kb ? resolve(values.kb) : undefined,
-        from,
-        to,
-        skills,
-    });
-    // JSON 是主产物; HTML 由 report server 的 /analyses/:id 按需渲染 (和 bench run 一致)
-    const outDir = resolve(values['output-dir'] || join(process.env.HOME || '.', '.oh-my-knowledge', 'analyses'));
-    mkdirSync(outDir, { recursive: true });
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const jsonPath = join(outDir, `${timestamp}-skill-health.json`);
-    writeFileSync(jsonPath, JSON.stringify(report, null, 2));
-    // 控制台摘要
-    const { sessionCount, segmentCount, toolCallCount, toolFailureRate } = report.meta;
-    console.log('');
-    console.log(`sessions: ${sessionCount} · segments: ${segmentCount} · tool calls: ${toolCallCount} · fail rate: ${(toolFailureRate * 100).toFixed(1)}%`);
-    console.log(`overall: gapRate ${(report.overall.gapRate * 100).toFixed(1)}% · weightedGapRate ${(report.overall.weightedGapRate * 100).toFixed(1)}% · health: ${report.overall.healthBand}`);
-    console.log('');
-    const skillRows = Object.values(report.bySkill)
-        .sort((a, b) => b.segmentCount - a.segmentCount)
-        .slice(0, 10)
-        .map((s) => `  ${s.skillName.padEnd(24)} segs=${String(s.segmentCount).padStart(4)}  gapRate=${String(Math.round(s.gap.gapRate * 100) + '%').padStart(4)}  weighted=${String(Math.round(s.gap.weightedGapRate * 100) + '%').padStart(4)}${s.coverage ? `  cov=${Math.round(s.coverage.fileCoverageRate * 100)}%` : ''}`);
-    console.log('top skills:');
-    console.log(skillRows.join('\n'));
-    console.log('');
-    console.log(`report written to: ${jsonPath}`);
-    console.log(tCli('cli.analyze.view_in_browser', lang));
-}
-async function handleInit(argv) {
-    const lang = langFromArgv(argv);
-    // 走 helper 让未知 option fail-fast (e.g. `omk bench init --bogus`),
-    // 否则 argv[0] 直接当目录名, --bogus / --lang 都会被当成 dir 写文件。
-    const { positionals } = parseArgsStrictOrExit({
-        args: argv,
-        allowPositionals: true,
-        options: { ...COMMON_OPTIONS },
-    });
-    const targetDir = resolve(positionals[0] || '.');
-    const { writeFileSync, mkdirSync } = await import('node:fs');
-    // omk skill loader 把 `skills/<name>/SKILL.md` 子目录识别为 directory-skill,
-    // cwd 默认锚到 skill 根目录,后续可在同目录下放 assets / 子文档。
-    // 子目录主题化命名(code-review-v1 / code-review-v2)比泛 v1.md / v2.md 心智模型更清晰。
-    mkdirSync(join(targetDir, 'skills', 'code-review-v1'), { recursive: true });
-    mkdirSync(join(targetDir, 'skills', 'code-review-v2'), { recursive: true });
-    writeFileSync(join(targetDir, 'eval-samples.json'), INIT_SAMPLES);
-    writeFileSync(join(targetDir, 'skills', 'code-review-v1', 'SKILL.md'), INIT_SKILL_V1);
-    writeFileSync(join(targetDir, 'skills', 'code-review-v2', 'SKILL.md'), INIT_SKILL_V2);
-    console.log(tCli('cli.init.scaffolded', lang, { dir: targetDir }));
-    console.log('');
-    console.log(tCli('cli.init.next_steps_title', lang));
-    console.log(tCli('cli.init.next_step_edit_samples', lang));
-    console.log(tCli('cli.init.next_step_edit_skills', lang));
-    console.log(tCli('cli.init.next_step_run', lang));
-    console.log(tCli('cli.init.note_codex_executor', lang));
-}
-// ---------------------------------------------------------------------------
-// handleGenSamples
-// ---------------------------------------------------------------------------
-async function handleGenSamples(argv) {
-    const lang = langFromArgv(argv);
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: argv,
-        options: {
-            ...COMMON_OPTIONS,
-            batch: { type: 'boolean', default: false },
-            count: { type: 'string', default: '5' },
-            model: { type: 'string', default: 'sonnet' },
-            'skill-dir': { type: 'string', default: 'skills' },
-        },
-        allowPositionals: true,
-    });
-    const { generateSamples } = await import('../authoring/generator.js');
-    const { readFileSync, writeFileSync } = await import('node:fs');
-    const count = Math.max(1, Number(values.count) || 5);
-    const model = values.model;
-    if (values.batch) {
-        // Batch mode: generate for all skills missing eval-samples
-        const skillDir = resolve(values['skill-dir']);
-        if (!existsSync(skillDir)) {
-            console.error(tCli('cli.common.skill_dir_not_found', lang, { path: skillDir }));
-            process.exit(1);
-        }
-        const { readdirSync, statSync } = await import('node:fs');
-        const entries = readdirSync(skillDir);
-        let generated = 0;
-        for (const entry of entries) {
-            let name;
-            let skillPath;
-            let samplesPath;
-            const fullPath = join(skillDir, entry);
-            if (entry.endsWith('.md') && !entry.endsWith('.eval-samples.json')) {
-                name = entry.slice(0, -3);
-                skillPath = fullPath;
-                samplesPath = join(skillDir, `${name}.eval-samples.json`);
-            }
-            else if (statSync(fullPath).isDirectory()) {
-                const skillMd = join(fullPath, 'SKILL.md');
-                if (!existsSync(skillMd))
-                    continue;
-                name = entry;
-                skillPath = skillMd;
-                samplesPath = join(fullPath, 'eval-samples.json');
-            }
-            else {
-                continue;
-            }
-            if (existsSync(samplesPath)) {
-                process.stderr.write(tCli('cli.gen.skill_skipped_existing', lang, { name }));
-                continue;
-            }
-            process.stderr.write(tCli('cli.gen.skill_generating', lang, { name, count }));
-            try {
-                const skillContent = readFileSync(skillPath, 'utf-8');
-                const { samples, costUSD } = await generateSamples({ skillContent, count, model });
-                writeFileSync(samplesPath, JSON.stringify(samples, null, 2));
-                const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-                process.stderr.write(tCli('cli.gen.skill_done', lang, {
-                    name, n: samples.length, path: samplesPath, cost,
-                }));
-                generated++;
-            }
-            catch (err) {
-                process.stderr.write(tCli('cli.gen.skill_failed', lang, {
-                    name, message: err.message,
-                }));
-            }
-        }
-        if (generated === 0) {
-            console.log(tCli('cli.gen.batch_none_needed', lang));
-        }
-        else {
-            console.log(tCli('cli.gen.batch_summary', lang, { n: generated }));
-        }
-    }
-    else {
-        // Single skill mode
-        const skillPath = argv.find((a) => !a.startsWith('-'));
-        if (!skillPath) {
-            console.error(tCli('cli.gen.specify_skill_path', lang));
-            process.exit(1);
-        }
-        const resolvedPath = resolve(skillPath);
-        if (!existsSync(resolvedPath)) {
-            console.error(tCli('cli.common.skill_file_not_found', lang, { path: resolvedPath }));
-            process.exit(1);
-        }
-        const skillContent = readFileSync(resolvedPath, 'utf-8');
-        const outputPath = resolve('eval-samples.json');
-        if (existsSync(outputPath)) {
-            console.error(tCli('cli.gen.samples_already_exists', lang));
-            process.exit(1);
-        }
-        process.stderr.write(tCli('cli.gen.single_generating', lang, { count }));
-        try {
-            const { samples, costUSD } = await generateSamples({ skillContent, count, model });
-            writeFileSync(outputPath, JSON.stringify(samples, null, 2));
-            const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-            process.stderr.write(tCli('cli.gen.single_done', lang, {
-                n: samples.length, path: outputPath, cost,
-            }));
-            console.log(tCli('cli.gen.review_hint', lang));
-        }
-        catch (err) {
-            console.error(tCli('cli.gen.failed', lang, { message: err.message }));
-            process.exit(1);
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// handleEvolve
-// ---------------------------------------------------------------------------
-async function handleEvolve(argv) {
-    const lang = langFromArgv(argv);
-    const { values, positionals } = parseArgsStrictOrExit({
-        args: argv,
-        options: {
-            ...COMMON_OPTIONS,
-            rounds: { type: 'string', default: '5' },
-            target: { type: 'string' },
-            samples: { type: 'string', default: 'eval-samples.json' },
-            model: { type: 'string', default: 'sonnet' },
-            'judge-models': { type: 'string', default: 'claude:haiku' },
-            'improve-model': { type: 'string', default: 'sonnet' },
-            concurrency: { type: 'string', default: '1' },
-            timeout: { type: 'string', default: '120' },
-            executor: { type: 'string', default: 'claude' },
-            'skip-connectivity': { type: 'boolean', default: false },
-        },
-        allowPositionals: true,
-    });
-    // skill path 走 parseArgs 的 positionals (避免 raw argv.find 把 flag value
-    // 当成 path 误识别 — 例如 `evolve --judge-models openai-api:gpt-4o foo.md`)。
-    const skillPath = positionals[0];
-    if (!skillPath) {
-        console.error(tCli('cli.evolve.specify_skill_path', lang));
-        process.exit(1);
-    }
-    let samplesFile = values.samples ?? 'eval-samples.json';
-    if (samplesFile === 'eval-samples.json' && !existsSync(resolve(samplesFile))) {
-        if (existsSync(resolve('eval-samples.yaml')))
-            samplesFile = 'eval-samples.yaml';
-        else if (existsSync(resolve('eval-samples.yml')))
-            samplesFile = 'eval-samples.yml';
-    }
-    const { evolveSkill } = await import('../authoring/evolver.js');
-    const { parseJudgeModelsArgOrExit } = await import('./parse-run-config.js');
-    const evolveJudges = parseJudgeModelsArgOrExit(values['judge-models']);
-    if (evolveJudges.length > 1) {
-        console.error(tCli('cli.common.judge_models_single_only', lang, { cmd: 'evolve' }));
-        process.exit(2);
-    }
-    process.stderr.write(tCli('cli.evolve.section_header', lang, { path: skillPath }));
-    try {
-        const result = await evolveSkill({
-            skillPath: resolve(skillPath),
-            samplesPath: resolve(samplesFile),
-            rounds: Math.max(1, Number(values.rounds) || 5),
-            target: values.target ? Number(values.target) : null,
-            model: values.model,
-            judgeModels: evolveJudges,
-            improveModel: values['improve-model'],
-            executorName: values.executor,
-            concurrency: Math.max(1, Number(values.concurrency) || 1),
-            timeoutMs: Math.max(1, Number(values.timeout) || 120) * 1000,
-            skipConnectivity: values['skip-connectivity'],
-            onProgress: makeOnProgress(lang),
-            onRoundProgress({ round, totalRounds: _totalRounds, phase, score, delta, accepted, costUSD, costReported, error }) {
-                // costReported=false 时显示「—」而不是 $0.0000(executor 不报 cost,如 codex)。
-                // 缺位 / true 当 reported 走旧格式。
-                const fmtRoundCost = (c, r) => r ? `$${c.toFixed(4)}` : '—';
-                if (phase === 'baseline') {
-                    process.stderr.write(tCli('cli.evolve.round_baseline', lang, {
-                        score: score.toFixed(2), cost: fmtRoundCost(costUSD, costReported !== false),
-                    }));
-                }
-                else if (phase === 'error') {
-                    process.stderr.write(tCli('cli.evolve.round_error', lang, {
-                        round, error: String(error ?? ''),
-                    }));
-                }
-                else if (phase === 'done') {
-                    const delta_ = delta >= 0 ? `+${delta.toFixed(2)}` : delta.toFixed(2);
-                    const status = accepted ? '✓ ACCEPT' : '✗ REJECT';
-                    process.stderr.write(tCli('cli.evolve.round_done', lang, {
-                        round, score: score.toFixed(2), delta: delta_, status, cost: fmtRoundCost(costUSD, costReported !== false),
-                    }));
-                }
-            },
-        });
-        const improvement = result.startScore > 0
-            ? ((result.finalScore - result.startScore) / result.startScore * 100).toFixed(1)
-            : '0';
-        const totalCostStr = result.costReported === false
-            ? '—' // 任一轮的 executor 不报 cost → totalCostUSD 是 lower-bound
-            : `$${result.totalCostUSD.toFixed(4)}`;
-        process.stderr.write(tCli('cli.evolve.summary', lang, {
-            start: result.startScore.toFixed(2), final: result.finalScore.toFixed(2),
-            percent: improvement, rounds: result.totalRounds, cost: totalCostStr,
-        }));
-        process.stderr.write(tCli('cli.evolve.best_path', lang, {
-            best: result.bestSkillPath, target: resolve(skillPath),
-        }));
-        process.stderr.write(tCli('cli.evolve.versions_saved', lang, {
-            dir: join(resolve(skillPath, '..'), 'evolve'),
-        }));
-        if (result.reportId) {
-            process.stderr.write(tCli('cli.evolve.report_link', lang, { id: result.reportId }));
-        }
-        console.log(JSON.stringify(result, null, 2));
-    }
-    catch (err) {
-        console.error(tCli('cli.common.error_prefix', lang, { message: err.message }));
-        process.exit(1);
-    }
-}
-// ---------------------------------------------------------------------------
-// handleGate — 跑评测 + 应用 gate, exit code 0/1 适合 CI/CD pipeline 调用。
-// 内部 = runEvaluation + computeVerdict + formatVerdictText, 与 bench verdict
-// 共用决策内核(只是 verdict 读已有报告, gate 跑完再判)。
-// ---------------------------------------------------------------------------
-async function handleGate(argv) {
-    const lang = langFromArgv(argv);
-    if (argv[0] === '--help' || argv[0] === '-h') {
-        console.log(tCli('cli.help.main', lang).trim());
-        process.exit(0);
-    }
-    const { values, config } = parseRunConfig(argv, {
-        threshold: { type: 'string', default: '3.5' },
-        'trivial-diff': { type: 'string' },
-    });
-    const { runEvaluation } = await import('../eval-workflows/run-evaluation.js');
-    config.onProgress = makeOnProgress(lang);
-    // 注入 lang + skip-connectivity warning(若 flag set);doctor 由 evaluation 强制调, 无 skip 选项。
-    config.lang = lang;
-    if (values['skip-connectivity']) {
-        process.stderr.write(tCli('cli.run.skip_connectivity_warning', lang) + '\n');
-    }
-    try {
-        const { report: document } = (await runEvaluation(config));
-        if (document.dryRun) {
-            console.log('Gate dry-run: no scores to check');
-            process.exit(0);
-        }
-        const report = requireEvaluationReport(document, 'current run', lang);
-        // gate 内核 = run + verdict, 自动覆盖 omk 全部决策维度(三层 layer-gate /
-        // bootstrap diff CI / saturation / Krippendorff α)。computeVerdict 是单一
-        // 决策源, exit code 跟 verdict.level 走 — 数据 underpowered 直接 FAIL,
-        // 堵住"过 PASS 就 deploy"的漏洞。
-        const { computeVerdict, formatVerdictText } = await import('../eval-core/verdict.js');
-        const result = computeVerdict(report, {
-            gateThreshold: Number(values.threshold),
-            triviallySmallDiff: values['trivial-diff'] != null ? Number(values['trivial-diff']) : undefined,
-        });
-        console.log(formatVerdictText(result, { verbose: true }));
-        // exit code 与 handleVerdict 对齐:只有 PROGRESS / SOLO-pass 才 0,
-        // NOISE / UNDERPOWERED / CAUTIOUS / REGRESS 全 1。pipeline `omk bench gate
-        // && deploy` 数据不显著就不会误 deploy。
-        if (result.level === 'PROGRESS') {
-            process.exit(0);
-        }
-        if (result.level === 'SOLO' && result.headline.includes('PASS')) {
-            process.exit(0);
-        }
-        process.exit(1);
-    }
-    catch (err) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
-    }
-}
-// ---------------------------------------------------------------------------
-// handleDiff
-// ---------------------------------------------------------------------------
-async function handleDiff(argv) {
-    const lang = langFromArgv(argv);
-    // Flag-aware split: separate positional report IDs from flags so we can support
-    //   omk bench diff <id>                      — within-report sample-level
-    //   omk bench diff <id1> <id2>               — cross-report variant-level (legacy)
-    // both with optional --regressions-only / --threshold / --variant flags.
-    const positional = [];
-    const flagArgs = [];
+function helpKeyFor(cmd, argv) {
+    if (!cmd.subHelp)
+        return cmd.helpKey;
     for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a.startsWith('--')) {
-            flagArgs.push(a);
-            const next = argv[i + 1];
-            if (next !== undefined && !next.startsWith('--')) {
-                flagArgs.push(next);
-                i++;
-            }
-        }
-        else {
-            positional.push(a);
-        }
-    }
-    if (positional.length === 0) {
-        console.error(tCli('cli.help.diff_usage', lang));
-        process.exit(positional.length === 0 ? 1 : 0);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: flagArgs,
-        options: {
-            ...COMMON_OPTIONS,
-            'regressions-only': { type: 'boolean', default: false },
-            threshold: { type: 'string' },
-            variant: { type: 'string' },
-            top: { type: 'string' },
-        },
-    });
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(DEFAULT_REPORTS_DIR));
-    if (positional.length === 1) {
-        await runSampleLevelDiff(positional[0], store, values, lang);
-        return;
-    }
-    const [id1, id2] = positional;
-    const r1 = requireEvaluationReport(await store.get(id1), id1, lang);
-    const r2 = requireEvaluationReport(await store.get(id2), id2, lang);
-    console.log(`\n  Diff: ${id1} → ${id2}\n`);
-    // Git info — r1/r2 are guaranteed non-null after process.exit() guards above
-    const g1 = r1.meta?.gitInfo;
-    const g2 = r2.meta?.gitInfo;
-    if (g1 || g2) {
-        console.log(`  Git:  ${g1?.commitShort || '?'}${g1?.dirty ? '*' : ''} (${g1?.branch || '?'}) → ${g2?.commitShort || '?'}${g2?.dirty ? '*' : ''} (${g2?.branch || '?'})`);
-    }
-    const { crossReportComparabilityWarnings, formatComparabilityWarnings } = await import('../eval-core/comparability.js');
-    const comparability = formatComparabilityWarnings(crossReportComparabilityWarnings(r1, r2), lang);
-    if (comparability)
-        process.stderr.write(`\n${comparability}\n\n`);
-    // Per-variant comparison
-    const variants = [...new Set([...(r1.meta?.variants || []), ...(r2.meta?.variants || [])])];
-    for (const v of variants) {
-        const s1 = r1.summary?.[v];
-        const s2 = r2.summary?.[v];
-        if (!s1 && !s2)
+        const token = argv[i];
+        if (!token || token === '--help' || token === '-h')
             continue;
-        console.log(`\n  [${v}]`);
-        const score1 = s1?.avgCompositeScore ?? '-';
-        const score2 = s2?.avgCompositeScore ?? '-';
-        const scoreDelta = typeof score1 === 'number' && typeof score2 === 'number'
-            ? ` (${score2 > score1 ? '+' : ''}${(score2 - score1).toFixed(2)})`
-            : '';
-        console.log(`    Score:   ${score1} → ${score2}${scoreDelta}`);
-        const turns1 = s1?.avgNumTurns ?? '-';
-        const turns2 = s2?.avgNumTurns ?? '-';
-        console.log(`    Turns:   ${turns1} → ${turns2}`);
-        // Tool calls comparison (agent metrics)
-        if (s1?.avgToolCalls != null || s2?.avgToolCalls != null) {
-            const tc1 = s1?.avgToolCalls ?? '-';
-            const tc2 = s2?.avgToolCalls ?? '-';
-            console.log(`    Tools:   ${tc1} → ${tc2}`);
-            const sr1 = s1?.toolSuccessRate != null ? `${(s1.toolSuccessRate * 100).toFixed(0)}%` : '-';
-            const sr2 = s2?.toolSuccessRate != null ? `${(s2.toolSuccessRate * 100).toFixed(0)}%` : '-';
-            console.log(`    ToolOK:  ${sr1} → ${sr2}`);
-        }
-        const cost1 = s1?.avgCostPerSample ?? 0;
-        const cost2 = s2?.avgCostPerSample ?? 0;
-        const reported1 = s1?.execCostReported !== false;
-        const reported2 = s2?.execCostReported !== false;
-        const fmt = (c, r) => r ? `$${c.toFixed(4)}` : '—';
-        // 任一边 not reported 就不报增减百分比(没意义)
-        const costPct = (reported1 && reported2 && cost1 > 0)
-            ? ` (${cost2 > cost1 ? '+' : ''}${(((cost2 - cost1) / cost1) * 100).toFixed(0)}%)`
-            : '';
-        console.log(`    Cost:    ${fmt(cost1, reported1)} → ${fmt(cost2, reported2)}${costPct}`);
-        // Skill hash change
-        const h1 = r1.meta?.artifactHashes?.[v];
-        const h2 = r2.meta?.artifactHashes?.[v];
-        if (h1 && h2 && h1 !== h2) {
-            console.log(`    Skill:   ${h1.slice(0, 8)} → ${h2.slice(0, 8)} (changed)`);
-        }
-    }
-    console.log('');
-}
-/**
- * Within-report sample-level diff. Compares two variants' scores on
- * each shared sample and surfaces the worst regressions / biggest wins.
- *
- * Default focus is variants[0] (control) vs variants[1] (treatment), but
- * `--variant` overrides which variant is the "treatment" side.
- */
-async function runSampleLevelDiff(reportId, store, flags, lang) {
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    const { reportComparabilityWarnings, formatComparabilityWarnings } = await import('../eval-core/comparability.js');
-    const comparability = formatComparabilityWarnings(reportComparabilityWarnings(report), lang);
-    if (comparability)
-        process.stderr.write(`\n${comparability}\n\n`);
-    const variants = report.meta?.variants ?? [];
-    if (variants.length < 2) {
-        console.error('Sample-level diff needs at least 2 variants in the report.');
-        process.exit(1);
-    }
-    const control = variants[0];
-    const treatment = flags.variant ?? variants[1];
-    if (!variants.includes(treatment)) {
-        console.error(`Variant "${treatment}" not in report. Available: ${variants.join(', ')}`);
-        process.exit(1);
-    }
-    const threshold = flags.threshold != null ? Number(flags.threshold) : 0;
-    const regressionsOnly = Boolean(flags['regressions-only']);
-    const topN = flags.top != null ? Math.max(1, Number(flags.top) || 0) : undefined;
-    const rows = [];
-    for (const entry of report.results ?? []) {
-        const c = entry.variants?.[control];
-        const t = entry.variants?.[treatment];
-        if (!c || !t)
+        if (token === '--lang') {
+            i++;
             continue;
-        const cComp = c.compositeScore ?? c.llmScore ?? 0;
-        const tComp = t.compositeScore ?? t.llmScore ?? 0;
-        const delta = Number((tComp - cComp).toFixed(3));
-        rows.push({
-            id: entry.sample_id,
-            cFact: c.layeredScores?.factScore, tFact: t.layeredScores?.factScore,
-            cBeh: c.layeredScores?.behaviorScore, tBeh: t.layeredScores?.behaviorScore,
-            cJudge: c.layeredScores?.judgeScore, tJudge: t.layeredScores?.judgeScore,
-            cComp, tComp, delta,
-        });
-    }
-    // Sort by |delta| desc so the most impactful rows surface first.
-    rows.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
-    let filtered = rows;
-    if (regressionsOnly)
-        filtered = filtered.filter((r) => r.delta < threshold);
-    if (topN !== undefined)
-        filtered = filtered.slice(0, topN);
-    console.log(`\n  Sample-level diff: ${treatment} vs ${control} (report ${reportId})`);
-    if (regressionsOnly)
-        console.log(`  Filter: regressions only (Δ < ${threshold})`);
-    console.log('');
-    console.log('  sample_id           Δ      composite (c→t)   fact (c→t)     behavior (c→t)   judge (c→t)');
-    console.log('  ' + '-'.repeat(100));
-    if (filtered.length === 0) {
-        console.log(regressionsOnly ? '  (no regressions found)' : '  (no shared samples)');
-        console.log('');
-        return;
-    }
-    const fmt = (a, b) => {
-        const av = typeof a === 'number' ? a.toFixed(2) : '—';
-        const bv = typeof b === 'number' ? b.toFixed(2) : '—';
-        return `${av} → ${bv}`.padEnd(15);
-    };
-    for (const r of filtered) {
-        const sign = r.delta > 0 ? '+' : '';
-        const idCol = r.id.slice(0, 18).padEnd(20);
-        const deltaCol = `${sign}${r.delta.toFixed(2)}`.padEnd(7);
-        const compCol = `${r.cComp.toFixed(2)} → ${r.tComp.toFixed(2)}`.padEnd(17);
-        console.log(`  ${idCol}${deltaCol}${compCol}${fmt(r.cFact, r.tFact)} ${fmt(r.cBeh, r.tBeh)} ${fmt(r.cJudge, r.tJudge)}`);
-    }
-    console.log('');
-    console.log(`  Showing ${filtered.length} of ${rows.length} samples · sorted by |Δ|`);
-    if (regressionsOnly) {
-        const total = rows.length;
-        const reg = rows.filter((r) => r.delta < threshold).length;
-        console.log(`  Regression rate: ${reg}/${total} samples (${total > 0 ? ((reg / total) * 100).toFixed(0) : 0}%)`);
-    }
-    console.log('');
-}
-// ---------------------------------------------------------------------------
-// handleGold — gold dataset workflow (init / validate / compare)
-// ---------------------------------------------------------------------------
-async function handleGold(argv) {
-    const lang = langFromArgv(argv);
-    const sub = argv[0];
-    const rest = argv.slice(1);
-    if (!sub || sub === '--help' || sub === '-h') {
-        console.log(tCli('cli.help.gold', lang));
-        process.exit(sub ? 0 : 1);
-    }
-    if (sub === 'init') {
-        const { values } = parseArgsStrictOrExit({
-            args: rest,
-            options: {
-                ...COMMON_OPTIONS,
-                out: { type: 'string', default: './gold-dataset' },
-                annotator: { type: 'string' },
-            },
-        });
-        const { initGoldDataset } = await import('../grading/gold-cli.js');
-        try {
-            const written = initGoldDataset(values.out, {
-                annotator: values.annotator,
-            });
-            console.log(tCli('cli.gold.created_files', lang, {
-                n: written.length, dir: values.out,
-            }));
-            for (const p of written)
-                console.log(`  ${p}`);
-            console.log(tCli('cli.gold.next_step_edit_annotations', lang));
-        }
-        catch (err) {
-            console.error(err.message);
-            process.exit(1);
-        }
-        return;
-    }
-    if (sub === 'validate') {
-        // 走 helper 让 `omk bench gold validate <dir> --bogus` 走 unknown option 路径,
-        // 而不是直接执行 validate 后再报 dataset 错。
-        const { positionals } = parseArgsStrictOrExit({
-            args: rest,
-            allowPositionals: true,
-            options: { ...COMMON_OPTIONS },
-        });
-        const dir = positionals[0];
-        if (!dir) {
-            console.error(tCli('cli.common.usage_gold_validate', lang));
-            process.exit(1);
-        }
-        const { validateGoldDataset } = await import('../grading/gold-cli.js');
-        const result = validateGoldDataset(dir);
-        if (result.ok) {
-            console.log(tCli('cli.gold.validate_ok', lang, { n: result.sampleCount }));
-            return;
         }
-        console.error(`✗ gold dataset has ${result.issues.length} issue(s):`);
-        for (const msg of result.issues)
-            console.error(`  - ${msg}`);
-        process.exit(1);
-    }
-    if (sub === 'compare') {
-        const reportId = rest[0];
-        if (!reportId) {
-            console.error('Usage: omk bench gold compare <reportId> --gold-dir <dir>');
-            process.exit(1);
-        }
-        const { values } = parseArgsStrictOrExit({
-            args: rest.slice(1),
-            options: {
-                ...COMMON_OPTIONS,
-                'gold-dir': { type: 'string' },
-                variant: { type: 'string' },
-                'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-                'bootstrap-samples': { type: 'string', default: '1000' },
-                seed: { type: 'string' },
-            },
-        });
-        const goldDir = values['gold-dir'];
-        if (!goldDir) {
-            console.error('--gold-dir is required');
-            process.exit(1);
-        }
-        const { loadGoldDataset } = await import('../grading/gold-dataset.js');
-        const { compareGoldToReport, formatGoldCompare } = await import('../grading/gold-cli.js');
-        const { createFileStore } = await import('../server/report-store.js');
-        const { dataset, issues } = loadGoldDataset(goldDir);
-        if (!dataset) {
-            console.error('Cannot load gold dataset:');
-            for (const i of issues)
-                console.error(`  - ${i.message}`);
-            process.exit(1);
-        }
-        if (issues.length) {
-            // Non-fatal issues (e.g. duplicate already filtered) — surface them.
-            for (const i of issues)
-                console.error(`warn: ${i.message}`);
-        }
-        const store = createFileStore(resolve(values['reports-dir']));
-        const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-        const samples = Math.max(100, Number(values['bootstrap-samples']) || 1000);
-        const seedVal = values.seed != null ? Number(values.seed) : undefined;
-        const result = compareGoldToReport({
-            report,
-            gold: dataset,
-            variant: values.variant,
-            samples,
-            seed: Number.isFinite(seedVal) ? seedVal : undefined,
-        });
-        console.log(formatGoldCompare(result, dataset));
-        return;
-    }
-    console.error(`Unknown subcommand: gold ${sub}. Use init / validate / compare.`);
-    process.exit(1);
-}
-// ---------------------------------------------------------------------------
-// handleDebiasValidate — measure length-debias prompt sensitivity
-// ---------------------------------------------------------------------------
-async function handleDebiasValidate(argv) {
-    const lang = langFromArgv(argv);
-    const sub = argv[0];
-    const rest = argv.slice(1);
-    if (!sub || sub === '--help' || sub === '-h') {
-        console.log(tCli('cli.help.debias_validate', lang));
-        process.exit(sub ? 0 : 1);
-    }
-    if (sub !== 'length') {
-        console.error(`Unknown debias-validate kind: ${sub}. Use "length".`);
-        process.exit(1);
-    }
-    const reportId = rest[0];
-    if (!reportId) {
-        console.error('Usage: omk bench debias-validate length <reportId>');
-        process.exit(1);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: rest.slice(1),
-        options: {
-            ...COMMON_OPTIONS,
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            samples: { type: 'string' },
-            variant: { type: 'string' },
-            'judge-models': { type: 'string' },
-            'bootstrap-samples': { type: 'string', default: '1000' },
-            seed: { type: 'string' },
-        },
-    });
-    // Parse --judge-models 在 load report 之前 fail-fast。重复 entry / 缺 executor /
-    // 空串等参数错误应立即给 friendly error: + exit 2,不要等到 store IO 完成才暴露。
-    const { parseJudgeModelsArgOrExit: parseJudgesA } = await import('./parse-run-config.js');
-    const cliJudgeModelsA = values['judge-models'] !== undefined
-        ? parseJudgesA(values['judge-models'])
-        : undefined;
-    if (cliJudgeModelsA && cliJudgeModelsA.length > 1) {
-        console.error(tCli('cli.common.judge_models_single_only', lang, { cmd: 'debias-validate' }));
-        process.exit(2);
-    }
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(values['reports-dir']));
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    // Resolve samples path: --samples overrides; otherwise read from report.meta.request.
-    const samplesPath = values.samples
-        ?? report.meta?.request?.samplesPath;
-    if (!samplesPath) {
-        console.error('Cannot find samples path. Pass --samples <path> or ensure report has request.samplesPath.');
-        process.exit(1);
-    }
-    const { loadSamples } = await import('../inputs/load-samples.js');
-    const { samples } = loadSamples(samplesPath);
-    const debiasJudges = cliJudgeModelsA
-        ?? (report.meta?.judgeModels?.[0]
-            ? [{ executor: report.meta.judgeModels[0].executor, model: report.meta.judgeModels[0].model }]
-            : []);
-    if (debiasJudges.length === 0) {
-        console.error(tCli('cli.common.no_judge_model', lang));
-        process.exit(1);
-    }
-    process.stderr.write(tCli('cli.debias.warn_cost_doubles', lang));
-    const { createExecutor } = await import('../executors/index.js');
-    const judgeExecutor = createExecutor(debiasJudges[0].executor);
-    const judgeModel = debiasJudges[0].model;
-    const { validateLengthDebias, formatDebiasValidate } = await import('../grading/debias-validate.js');
-    const seedVal = values.seed != null ? Number(values.seed) : undefined;
-    const bsRaw = Number(values['bootstrap-samples']) || 1000;
-    const result = await validateLengthDebias({
-        report,
-        samples,
-        judgeExecutor,
-        judgeModel,
-        variant: values.variant,
-        bootstrapSamples: Math.max(100, bsRaw),
-        seed: Number.isFinite(seedVal) ? seedVal : undefined,
-        onProgress: ({ sample_id, completed, total }) => {
-            process.stderr.write(`  judging ${completed}/${total}: ${sample_id}\n`);
-        },
-    });
-    console.log(formatDebiasValidate(result));
-}
-// ---------------------------------------------------------------------------
-// handleSaturation — re-compute saturation verdict from a finished report
-// ---------------------------------------------------------------------------
-async function handleSaturation(argv) {
-    const lang = langFromArgv(argv);
-    const reportId = argv[0];
-    if (!reportId || reportId === '--help' || reportId === '-h') {
-        console.log(tCli('cli.help.saturation', lang));
-        process.exit(reportId ? 0 : 1);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: argv.slice(1),
-        options: {
-            ...COMMON_OPTIONS,
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            variant: { type: 'string' },
-        },
-    });
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(values['reports-dir']));
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    const saturation = report.variance?.saturation;
-    if (!saturation) {
-        console.error(tCli('cli.saturation.no_data', lang));
-        process.exit(1);
-    }
-    // Print the persisted verdict from the original run. The trace stores
-    // (mean, ciLow, ciHigh) per checkpoint but not raw scores, so re-running
-    // findSaturationPoint with different method/threshold is not possible
-    // here — that would need raw scores, which would have to be persisted
-    // by runMultiple. Future work: opt-in `--persist-saturation-raw` flag at
-    // run time to enable post-hoc parameter sweeps.
-    const variants = report.meta.variants ?? [];
-    const targetVariants = values.variant ? [values.variant] : variants;
-    console.log(tCli('cli.saturation.verdict_header', lang));
-    for (const variant of targetVariants) {
-        const trace = saturation.perVariant[variant];
-        if (!trace || trace.length === 0) {
-            console.log(tCli('cli.saturation.variant_no_trace', lang, { variant }));
+        if (token.startsWith('--lang='))
             continue;
-        }
-        console.log(tCli('cli.saturation.variant_label', lang, { variant }));
-        console.log(tCli('cli.saturation.checkpoints', lang, {
-            n: trace.length, list: trace.map((p) => p.n).join(', '),
-        }));
-        const last = trace[trace.length - 1];
-        console.log(tCli('cli.saturation.last_point', lang, {
-            mean: last.mean.toFixed(3), lo: last.ciLow.toFixed(3), hi: last.ciHigh.toFixed(3),
-        }));
-        if (saturation.verdicts?.[variant]) {
-            const v = saturation.verdicts[variant];
-            const result = v.saturated
-                ? tCli('cli.saturation.persisted_verdict_saturated', lang, { n: v.atN ?? '?' })
-                : tCli('cli.saturation.persisted_verdict_unsaturated', lang);
-            console.log(tCli('cli.saturation.persisted_verdict', lang, {
-                method: v.method, result, reason: v.reason,
-            }));
-        }
-        else if (trace.length < 5) {
-            console.log(tCli('cli.saturation.skipped_too_few_points', lang, { n: trace.length }));
-        }
+        if (token.startsWith('-'))
+            continue;
+        return cmd.subHelp[token] ?? cmd.helpKey;
     }
-    console.log('');
+    return cmd.helpKey;
 }
-// ---------------------------------------------------------------------------
-// handleVerdict — one-line ship/no-ship verdict
-// ---------------------------------------------------------------------------
-async function handleVerdict(argv) {
-    const lang = langFromArgv(argv);
-    const reportId = argv[0];
-    if (!reportId || reportId === '--help' || reportId === '-h') {
-        console.log(tCli('cli.help.verdict', lang));
-        process.exit(reportId ? 0 : 1);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: argv.slice(1),
-        options: {
-            ...COMMON_OPTIONS,
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            threshold: { type: 'string' },
-            'trivial-diff': { type: 'string' },
-            verbose: { type: 'boolean', default: false },
-        },
-    });
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(values['reports-dir']));
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    const { computeVerdict, formatVerdictText } = await import('../eval-core/verdict.js');
-    const { reportComparabilityWarnings, formatComparabilityWarnings } = await import('../eval-core/comparability.js');
-    const comparability = formatComparabilityWarnings(reportComparabilityWarnings(report), lang);
-    if (comparability)
-        process.stderr.write(`${comparability}\n`);
-    const result = computeVerdict(report, {
-        gateThreshold: values.threshold != null ? Number(values.threshold) : undefined,
-        triviallySmallDiff: values['trivial-diff'] != null ? Number(values['trivial-diff']) : undefined,
-    });
-    console.log(formatVerdictText(result, { verbose: Boolean(values.verbose) }));
-    // Exit code reflects ship recommendation: 0 only on PROGRESS / SOLO-pass.
-    // NOISE / UNDERPOWERED / CAUTIOUS / REGRESS all exit 1 so this composes
-    // with shell `&&` chains in CI.
-    if (result.level === 'PROGRESS') {
-        process.exit(0);
-    }
-    if (result.level === 'SOLO' && result.headline.includes('PASS')) {
-        process.exit(0);
+function dispatchOrPrintHelp(cmd, argv, lang) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(tCli(helpKeyFor(cmd, argv), lang).trim());
+        throw new CliExit(0);
     }
-    process.exit(1);
+    return cmd.execute(argv);
 }
-// ---------------------------------------------------------------------------
-// handleDiagnose — per-sample quality diagnostics (v0.23 A)
-// ---------------------------------------------------------------------------
-async function handleDiagnose(argv) {
-    const lang = langFromArgv(argv);
-    const reportId = argv[0];
-    if (!reportId || reportId === '--help' || reportId === '-h') {
-        console.log(tCli('cli.help.diagnose', lang));
-        process.exit(reportId ? 0 : 1);
-    }
-    const { values } = parseArgsStrictOrExit({
-        args: argv.slice(1),
-        options: {
-            ...COMMON_OPTIONS,
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            samples: { type: 'string' },
-            top: { type: 'string', default: '10' },
-            'duplicate-rouge': { type: 'string' },
-            'ambiguous-stddev': { type: 'string' },
-            'cost-k': { type: 'string' },
-            'latency-k': { type: 'string' },
-            flat: { type: 'string' },
-        },
-    });
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(values['reports-dir']));
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    // Try to read the samples file for near-duplicate detection. Source order:
-    //  1. --samples <path> override
-    //  2. report.meta.request.samplesPath (recorded at run time)
-    // If neither resolves to a readable file, skip near-duplicate gracefully.
-    let samples;
-    const samplesPath = values.samples ?? report.meta?.request?.samplesPath;
-    if (samplesPath && existsSync(samplesPath)) {
-        try {
-            const { loadSamples } = await import('../inputs/load-samples.js');
-            samples = loadSamples(samplesPath).samples;
-        }
-        catch (err) {
-            process.stderr.write(tCli('cli.common.warn_load_samples_failed', lang, {
-                path: samplesPath, message: err.message,
-            }));
-        }
+async function main() {
+    const lang = getCliLang(parseLangFromArgv(process.argv));
+    checkUpdate(lang);
+    const [command, ...rest] = process.argv.slice(2);
+    if (!command || command === '--help' || command === '-h') {
+        console.log(tCli('cli.help.product_main', lang).trim());
+        throw new CliExit(0);
     }
-    const topRaw = Number(values.top);
-    const topN = Number.isFinite(topRaw) && topRaw > 0 ? topRaw : undefined;
-    const { diagnoseSamples, formatSampleDiagnostics } = await import('../analysis/sample-diagnostics.js');
-    const diag = diagnoseSamples(report, {
-        samples,
-        duplicateRouge: values['duplicate-rouge'] != null ? Number(values['duplicate-rouge']) : undefined,
-        ambiguousStddev: values['ambiguous-stddev'] != null ? Number(values['ambiguous-stddev']) : undefined,
-        costOutlierK: values['cost-k'] != null ? Number(values['cost-k']) : undefined,
-        latencyOutlierK: values['latency-k'] != null ? Number(values['latency-k']) : undefined,
-        flatThreshold: values.flat != null ? Number(values.flat) : undefined,
-    });
-    console.log(formatSampleDiagnostics(diag, { topN, lang }));
-    // Sample design science coverage block. Render after diagnose 主体,因为
-    // coverage 是声明式元数据(capability/difficulty/construct/provenance)的整体分布,
-    // 跟 issue list 是不同视角的两件事。优先从 samples (现场加载) 算,fallback 到
-    // report.analysis.sampleQuality(报告里持久化的数据)。
-    const { renderSampleDesignCoverage } = await import('./coverage-renderer.js');
-    const coverageBlock = renderSampleDesignCoverage(samples, report.analysis?.sampleQuality, lang);
-    if (coverageBlock)
-        console.log(coverageBlock);
-    // Exit code: 0 if health ≥ 70 and no errors; 1 otherwise. CI-friendly.
-    if (diag.totals.errors === 0 && diag.healthScore >= 70) {
-        process.exit(0);
+    const cmd = PRODUCT_COMMANDS[command];
+    if (!cmd) {
+        console.error(tCli('cli.common.unknown_domain', lang, { domain: command }));
+        throw new CliExit(1);
     }
-    process.exit(1);
+    await dispatchOrPrintHelp(cmd, rest, lang);
 }
-// ---------------------------------------------------------------------------
-// handleFailures — LLM-driven failure clustering (v0.23 B)
-// ---------------------------------------------------------------------------
-async function handleFailures(argv) {
-    const lang = langFromArgv(argv);
-    const reportId = argv[0];
-    if (!reportId || reportId === '--help' || reportId === '-h') {
-        console.log(tCli('cli.help.failures', lang));
-        process.exit(reportId ? 0 : 1);
+main().catch((err) => {
+    // CliExit = 命令显式终止(--help / 业务失败 / parse 错误等),透传 exit code。
+    // 其他 throw 是未处理的运行时错误,打印 stack 后 exit 1。
+    if (err instanceof CliExit) {
+        process.exit(err.code);
     }
-    const { values } = parseArgsStrictOrExit({
-        args: argv.slice(1),
-        options: {
-            ...COMMON_OPTIONS,
-            'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            'judge-models': { type: 'string' },
-            'max-clusters': { type: 'string', default: '5' },
-            threshold: { type: 'string', default: '3' },
-            'max-feed': { type: 'string', default: '50' },
-        },
-    });
-    // Parse --judge-models 在 load report 之前 fail-fast(同 debias-validate)。
-    const { parseJudgeModelsArgOrExit: parseJudgesB } = await import('./parse-run-config.js');
-    const cliJudgeModelsB = values['judge-models'] !== undefined
-        ? parseJudgesB(values['judge-models'])
-        : undefined;
-    if (cliJudgeModelsB && cliJudgeModelsB.length > 1) {
-        console.error(tCli('cli.common.judge_models_single_only', lang, { cmd: 'failures' }));
-        process.exit(2);
-    }
-    const { createFileStore } = await import('../server/report-store.js');
-    const store = createFileStore(resolve(values['reports-dir']));
-    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
-    const failuresJudges = cliJudgeModelsB
-        ?? (report.meta?.judgeModels?.[0]
-            ? [{ executor: report.meta.judgeModels[0].executor, model: report.meta.judgeModels[0].model }]
-            : []);
-    if (failuresJudges.length === 0) {
-        console.error(tCli('cli.common.no_judge_model', lang));
-        process.exit(1);
-    }
-    const { createExecutor } = await import('../executors/index.js');
-    const executor = createExecutor(failuresJudges[0].executor);
-    const judgeModel = failuresJudges[0].model;
-    const { clusterFailures, formatFailureClusterReport } = await import('../analysis/failure-clusterer.js');
-    const out = await clusterFailures({
-        report,
-        executor,
-        judgeModel,
-        maxClusters: Number(values['max-clusters']) || 5,
-        failureThreshold: Number(values.threshold) || 3,
-        maxFailuresFed: Number(values['max-feed']) || 50,
-    });
-    console.log(formatFailureClusterReport(out));
-}
-// ---------------------------------------------------------------------------
-// Entry
-// ---------------------------------------------------------------------------
-main();
+    console.error(err);
+    process.exit(1);
+});
 //# sourceMappingURL=index.js.map