oh-my-knowledge 0.23.0 → 0.25.0

package/dist/src/cli/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { parseArgs } from 'node:util';
 import { resolve } from 'node:path';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
@@ -7,6 +6,20 @@ 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 { 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
 // ---------------------------------------------------------------------------
@@ -23,6 +36,11 @@ async function main() {
         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);
@@ -88,64 +106,46 @@ async function main() {
 // ---------------------------------------------------------------------------
 async function handleRun(argv) {
     const lang = langFromArgv(argv);
-    const { values, config } = parseRunConfig(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', default: '1' },
-        'judge-repeat': { type: 'string', default: '1' },
-        'judge-models': { type: 'string' },
-        bootstrap: { type: 'boolean', default: false },
-        'bootstrap-samples': { type: 'string', default: '1000' },
+        repeat: { type: 'string' },
+        'judge-repeat': { type: 'string' },
+        bootstrap: { type: 'boolean' },
+        'bootstrap-samples': { type: 'string' },
         'gold-dir': { type: 'string' },
-        'no-debias-length': { type: 'boolean', default: false },
+        'no-debias-length': { type: 'boolean' },
         'budget-usd': { type: 'string' },
         'budget-per-sample-usd': { type: 'string' },
         'budget-per-sample-ms': { type: 'string' },
     });
-    const { runEvaluation, runMultiple, runEachEvaluation } = await import('../eval-workflows/run-evaluation.js');
+    const { runEvaluation, runMultiple, runBatchEvaluation } = await import('../eval-workflows/run-evaluation.js');
     if (values.blind !== undefined) {
         config.blind = values.blind;
     }
     config.onProgress = makeOnProgress(lang);
-    // --repeat 输入校验: 非 ≥1 整数时提示并钳到 1, 不静默掩盖用户错字 / 极端输入。
-    // 提前到 --each 分支之前, 保证 each 模式也能读到 repeat (曾经 bug: --each 吞 --repeat)。
+    // --repeat: CLI > eval.yaml > 1. 非 ≥1 整数时提示并钳到 1。
     const repeatRaw = values.repeat;
-    const parsedRepeat = repeatRaw !== undefined ? Number(repeatRaw) : 1;
+    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 同样校验: 非 ≥1 整数时钳到 1
+    // --judge-repeat: CLI > eval.yaml > 1.
     const judgeRepeatRaw = values['judge-repeat'];
-    const parsedJudgeRepeat = judgeRepeatRaw !== undefined ? Number(judgeRepeatRaw) : 1;
+    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;
-    // --judge-models executor:model,executor:model,... -> JudgeConfig[]
-    // 至少 2 个才进 ensemble 模式, 1 个等同于 --judge-model
-    const judgeModelsRaw = values['judge-models'];
-    if (judgeModelsRaw) {
-        const parts = judgeModelsRaw.split(',').map((s) => s.trim()).filter(Boolean);
-        const judges = parts.map((p) => {
-            const [executor, ...modelParts] = p.split(':');
-            const model = modelParts.join(':');
-            if (!executor || !model) {
-                throw new Error(tCli('cli.run.invalid_judge_models_format', lang, { part: p }));
-            }
-            return { executor, model };
-        });
-        if (judges.length >= 2) {
-            config.judgeModels = judges;
-        }
-        else if (judges.length === 1) {
-            // 单 judge 不走 ensemble, 但允许这样写, 等同于 --judge-model + --executor
-            process.stderr.write(tCli('cli.run.judge_models_single_warning', lang, {
-                executor: judges[0].executor, model: judges[0].model,
-            }));
-        }
-    }
     // --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
@@ -160,18 +160,22 @@ async function handleRun(argv) {
             ...(budgetPerSampleMs !== undefined && Number.isFinite(budgetPerSampleMs) && budgetPerSampleMs >= 0 ? { perSampleMs: budgetPerSampleMs } : {}),
         };
     }
-    // --no-debias-length: opt out of v0.21 Phase 3a length-controlled prompt.
-    // Default behavior is debias-on (judge prompt v3-cot-length); flag flips it
-    // off so historical reports (judgePromptHash from v2-cot era) can be reproduced.
-    if (values['no-debias-length']) {
+    // --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
-    if (values.bootstrap) {
+    // --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) : 1000;
+        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 }));
         }
@@ -181,10 +185,15 @@ async function handleRun(argv) {
         }
         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 {
-        // --each mode: evaluate each skill independently
-        if (values.each) {
-            const { report, filePath } = await runEachEvaluation({
+        // --batch mode: evaluate each skill independently
+        if (values.batch) {
+            const { report, filePath } = await runBatchEvaluation({
                 ...config,
                 repeat: repeatCount,
                 onSkillProgress({ phase, skill, current, total }) {
@@ -237,8 +246,8 @@ async function handleRun(argv) {
             report = result.report;
             filePath = result.filePath;
         }
-        // --gold-dir: compute α/κ/Pearson against gold annotations and re-persist.
-        const goldDir = values['gold-dir'];
+        // --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({
@@ -299,7 +308,11 @@ async function handleRun(argv) {
 // ---------------------------------------------------------------------------
 async function handleReport(argv) {
     const lang = langFromArgv(argv);
-    const { values } = parseArgs({
+    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,
@@ -308,7 +321,6 @@ async function handleReport(argv) {
             export: { type: 'string' },
             dev: { type: 'boolean', default: false },
         },
-        strict: false,
     });
     // Dev mode: restart server on file changes via node --watch
     if (values.dev && !process.env.__OMK_DEV_CHILD) {
@@ -330,7 +342,7 @@ async function handleReport(argv) {
     }
     if (values.export) {
         const { createFileStore } = await import('../server/report-store.js');
-        const { renderRunDetail, renderEachRunDetail } = await import('../renderer/html-renderer.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);
@@ -338,7 +350,7 @@ async function handleReport(argv) {
             console.error(tCli('cli.common.report_not_found', lang, { id: values.export }));
             process.exit(1);
         }
-        const html = report.each ? renderEachRunDetail(report) : renderRunDetail(report);
+        const html = renderReportDocumentDetail(report);
         const outPath = resolve(`${values.export}.html`);
         writeFileSync(outPath, html);
         console.log(`Exported to: ${outPath}`);
@@ -429,9 +441,76 @@ function parseLastWindow(spec) {
     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.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.failed ? 1 : 0);
+}
 async function handleAnalyze(argv) {
     const lang = langFromArgv(argv);
-    const { values, positionals } = parseArgs({
+    const { values: rawValues, positionals } = parseArgsStrictOrExit({
         args: argv,
         allowPositionals: true,
         options: {
@@ -444,6 +523,8 @@ async function handleAnalyze(argv) {
             '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));
@@ -499,7 +580,14 @@ async function handleAnalyze(argv) {
 }
 async function handleInit(argv) {
     const lang = langFromArgv(argv);
-    const targetDir = resolve(argv[0] || '.');
+    // 走 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');
     mkdirSync(join(targetDir, 'skills'), { recursive: true });
     writeFileSync(join(targetDir, 'eval-samples.json'), INIT_SAMPLES);
@@ -517,23 +605,26 @@ async function handleInit(argv) {
 // ---------------------------------------------------------------------------
 async function handleGenSamples(argv) {
     const lang = langFromArgv(argv);
-    const { values } = parseArgs({
+    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,
-            each: { type: 'boolean', default: false },
+            batch: { type: 'boolean', default: false },
             count: { type: 'string', default: '5' },
             model: { type: 'string', default: 'sonnet' },
             'skill-dir': { type: 'string', default: 'skills' },
         },
-        strict: false,
         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.each) {
+    if (values.batch) {
         // Batch mode: generate for all skills missing eval-samples
         const skillDir = resolve(values['skill-dir']);
         if (!existsSync(skillDir)) {
@@ -631,7 +722,7 @@ async function handleGenSamples(argv) {
 // ---------------------------------------------------------------------------
 async function handleEvolve(argv) {
     const lang = langFromArgv(argv);
-    const { values } = parseArgs({
+    const { values, positionals } = parseArgsStrictOrExit({
         args: argv,
         options: {
             ...COMMON_OPTIONS,
@@ -639,17 +730,18 @@ async function handleEvolve(argv) {
             target: { type: 'string' },
             samples: { type: 'string', default: 'eval-samples.json' },
             model: { type: 'string', default: 'sonnet' },
-            'judge-model': { type: 'string', default: 'haiku' },
+            '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-preflight': { type: 'boolean', default: false },
+            'skip-connectivity': { type: 'boolean', default: false },
         },
-        strict: false,
         allowPositionals: true,
     });
-    const skillPath = argv.find((a) => !a.startsWith('-'));
+    // 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);
@@ -662,6 +754,12 @@ async function handleEvolve(argv) {
             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({
@@ -670,17 +768,20 @@ async function handleEvolve(argv) {
             rounds: Math.max(1, Number(values.rounds) || 5),
             target: values.target ? Number(values.target) : null,
             model: values.model,
-            judgeModel: values['judge-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,
-            skipPreflight: values['skip-preflight'],
+            skipConnectivity: values['skip-connectivity'],
             onProgress: makeOnProgress(lang),
-            onRoundProgress({ round, totalRounds: _totalRounds, phase, score, delta, accepted, costUSD, error }) {
+            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: costUSD.toFixed(4),
+                        score: score.toFixed(2), cost: fmtRoundCost(costUSD, costReported !== false),
                     }));
                 }
                 else if (phase === 'error') {
@@ -692,7 +793,7 @@ async function handleEvolve(argv) {
                     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: costUSD.toFixed(4),
+                        round, score: score.toFixed(2), delta: delta_, status, cost: fmtRoundCost(costUSD, costReported !== false),
                     }));
                 }
             },
@@ -700,9 +801,12 @@ async function handleEvolve(argv) {
         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: result.totalCostUSD.toFixed(4),
+            percent: improvement, rounds: result.totalRounds, cost: totalCostStr,
         }));
         process.stderr.write(tCli('cli.evolve.best_path', lang, {
             best: result.bestSkillPath, target: resolve(skillPath),
@@ -737,12 +841,18 @@ async function handleGate(argv) {
     });
     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 } = (await runEvaluation(config));
-        if (report.dryRun) {
+        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,
@@ -798,7 +908,7 @@ async function handleDiff(argv) {
         console.error(tCli('cli.help.diff_usage', lang));
         process.exit(positional.length === 0 ? 1 : 0);
     }
-    const { values } = parseArgs({
+    const { values } = parseArgsStrictOrExit({
         args: flagArgs,
         options: {
             ...COMMON_OPTIONS,
@@ -807,7 +917,6 @@ async function handleDiff(argv) {
             variant: { type: 'string' },
             top: { type: 'string' },
         },
-        strict: false,
     });
     const { createFileStore } = await import('../server/report-store.js');
     const store = createFileStore(resolve(DEFAULT_REPORTS_DIR));
@@ -816,16 +925,8 @@ async function handleDiff(argv) {
         return;
     }
     const [id1, id2] = positional;
-    const r1 = await store.get(id1);
-    const r2 = await store.get(id2);
-    if (!r1) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: id1 }));
-        process.exit(1);
-    }
-    if (!r2) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: id2 }));
-        process.exit(1);
-    }
+    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;
@@ -833,6 +934,10 @@ async function handleDiff(argv) {
     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) {
@@ -861,8 +966,14 @@ async function handleDiff(argv) {
         }
         const cost1 = s1?.avgCostPerSample ?? 0;
         const cost2 = s2?.avgCostPerSample ?? 0;
-        const costPct = cost1 > 0 ? ` (${cost2 > cost1 ? '+' : ''}${(((cost2 - cost1) / cost1) * 100).toFixed(0)}%)` : '';
-        console.log(`    Cost:    $${cost1.toFixed(4)} → $${cost2.toFixed(4)}${costPct}`);
+        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];
@@ -880,11 +991,11 @@ async function handleDiff(argv) {
  * `--variant` overrides which variant is the "treatment" side.
  */
 async function runSampleLevelDiff(reportId, store, flags, lang) {
-    const report = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
+    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.');
@@ -967,14 +1078,13 @@ async function handleGold(argv) {
         process.exit(sub ? 0 : 1);
     }
     if (sub === 'init') {
-        const { values } = parseArgs({
+        const { values } = parseArgsStrictOrExit({
             args: rest,
             options: {
                 ...COMMON_OPTIONS,
                 out: { type: 'string', default: './gold-dataset' },
                 annotator: { type: 'string' },
             },
-            strict: false,
         });
         const { initGoldDataset } = await import('../grading/gold-cli.js');
         try {
@@ -995,7 +1105,14 @@ async function handleGold(argv) {
         return;
     }
     if (sub === 'validate') {
-        const dir = rest[0];
+        // 走 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);
@@ -1017,7 +1134,7 @@ async function handleGold(argv) {
             console.error('Usage: omk bench gold compare <reportId> --gold-dir <dir>');
             process.exit(1);
         }
-        const { values } = parseArgs({
+        const { values } = parseArgsStrictOrExit({
             args: rest.slice(1),
             options: {
                 ...COMMON_OPTIONS,
@@ -1027,7 +1144,6 @@ async function handleGold(argv) {
                 'bootstrap-samples': { type: 'string', default: '1000' },
                 seed: { type: 'string' },
             },
-            strict: false,
         });
         const goldDir = values['gold-dir'];
         if (!goldDir) {
@@ -1050,15 +1166,11 @@ async function handleGold(argv) {
                 console.error(`warn: ${i.message}`);
         }
         const store = createFileStore(resolve(values['reports-dir']));
-        const report = await store.get(reportId);
-        if (!report) {
-            console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-            process.exit(1);
-        }
+        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: report,
+            report,
             gold: dataset,
             variant: values.variant,
             samples,
@@ -1071,7 +1183,7 @@ async function handleGold(argv) {
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
-// handleDebiasValidate — measure length-debias prompt sensitivity (Phase 3a)
+// handleDebiasValidate — measure length-debias prompt sensitivity
 // ---------------------------------------------------------------------------
 async function handleDebiasValidate(argv) {
     const lang = langFromArgv(argv);
@@ -1090,27 +1202,31 @@ async function handleDebiasValidate(argv) {
         console.error('Usage: omk bench debias-validate length <reportId>');
         process.exit(1);
     }
-    const { values } = parseArgs({
+    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-executor': { type: 'string', default: 'claude' },
-            'judge-model': { type: 'string' },
+            'judge-models': { type: 'string' },
             'bootstrap-samples': { type: 'string', default: '1000' },
             seed: { type: 'string' },
         },
-        strict: false,
     });
+    // 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 = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
+    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;
@@ -1120,20 +1236,23 @@ async function handleDebiasValidate(argv) {
     }
     const { loadSamples } = await import('../inputs/load-samples.js');
     const { samples } = loadSamples(samplesPath);
-    const judgeModel = values['judge-model']
-        ?? report.meta?.judgeModel;
-    if (!judgeModel) {
+    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(values['judge-executor']);
+    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: report,
+        report,
         samples,
         judgeExecutor,
         judgeModel,
@@ -1156,22 +1275,17 @@ async function handleSaturation(argv) {
         console.log(tCli('cli.help.saturation', lang));
         process.exit(reportId ? 0 : 1);
     }
-    const { values } = parseArgs({
+    const { values } = parseArgsStrictOrExit({
         args: argv.slice(1),
         options: {
             ...COMMON_OPTIONS,
             'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
             variant: { type: 'string' },
         },
-        strict: false,
     });
     const { createFileStore } = await import('../server/report-store.js');
     const store = createFileStore(resolve(values['reports-dir']));
-    const report = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
+    const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
     const saturation = report.variance?.saturation;
     if (!saturation) {
         console.error(tCli('cli.saturation.no_data', lang));
@@ -1225,7 +1339,7 @@ async function handleVerdict(argv) {
         console.log(tCli('cli.help.verdict', lang));
         process.exit(reportId ? 0 : 1);
     }
-    const { values } = parseArgs({
+    const { values } = parseArgsStrictOrExit({
         args: argv.slice(1),
         options: {
             ...COMMON_OPTIONS,
@@ -1234,16 +1348,15 @@ async function handleVerdict(argv) {
             'trivial-diff': { type: 'string' },
             verbose: { type: 'boolean', default: false },
         },
-        strict: false,
     });
     const { createFileStore } = await import('../server/report-store.js');
     const store = createFileStore(resolve(values['reports-dir']));
-    const report = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
+    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,
@@ -1270,7 +1383,7 @@ async function handleDiagnose(argv) {
         console.log(tCli('cli.help.diagnose', lang));
         process.exit(reportId ? 0 : 1);
     }
-    const { values } = parseArgs({
+    const { values } = parseArgsStrictOrExit({
         args: argv.slice(1),
         options: {
             ...COMMON_OPTIONS,
@@ -1283,15 +1396,10 @@ async function handleDiagnose(argv) {
             'latency-k': { type: 'string' },
             flat: { type: 'string' },
         },
-        strict: false,
     });
     const { createFileStore } = await import('../server/report-store.js');
     const store = createFileStore(resolve(values['reports-dir']));
-    const report = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
+    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)
@@ -1320,7 +1428,7 @@ async function handleDiagnose(argv) {
         latencyOutlierK: values['latency-k'] != null ? Number(values['latency-k']) : undefined,
         flatThreshold: values.flat != null ? Number(values.flat) : undefined,
     });
-    console.log(formatSampleDiagnostics(diag, { topN }));
+    console.log(formatSampleDiagnostics(diag, { topN, lang }));
     // Sample design science coverage block. Render after diagnose 主体,因为
     // coverage 是声明式元数据(capability/difficulty/construct/provenance)的整体分布,
     // 跟 issue list 是不同视角的两件事。优先从 samples (现场加载) 算,fallback 到
@@ -1345,36 +1453,43 @@ async function handleFailures(argv) {
         console.log(tCli('cli.help.failures', lang));
         process.exit(reportId ? 0 : 1);
     }
-    const { values } = parseArgs({
+    const { values } = parseArgsStrictOrExit({
         args: argv.slice(1),
         options: {
             ...COMMON_OPTIONS,
             'reports-dir': { type: 'string', default: DEFAULT_REPORTS_DIR },
-            'judge-executor': { type: 'string', default: 'claude' },
-            'judge-model': { type: 'string' },
+            'judge-models': { type: 'string' },
             'max-clusters': { type: 'string', default: '5' },
             threshold: { type: 'string', default: '3' },
             'max-feed': { type: 'string', default: '50' },
         },
-        strict: false,
     });
+    // 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 = await store.get(reportId);
-    if (!report) {
-        console.error(tCli('cli.common.report_not_found', lang, { id: reportId }));
-        process.exit(1);
-    }
-    const judgeModel = values['judge-model'] ?? report.meta?.judgeModel;
-    if (!judgeModel) {
+    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(values['judge-executor']);
+    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: report,
+        report,
         executor,
         judgeModel,
         maxClusters: Number(values['max-clusters']) || 5,