oh-my-knowledge 0.22.0 → 0.24.0

package/dist/src/{cli.js → cli/index.js}

@@ -1,241 +1,24 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { resolve } from 'node:path';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { tCli, getCliLang, parseLangFromArgv, langFromArgv } from './cli/i18n.js';
-import { discoverVariants, parseVariantCwd } from './inputs/skill-loader.js';
-import { loadEvalConfig, configVariantsToSpecs } from './inputs/eval-config.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const DEFAULT_REPORTS_DIR = join(homedir(), '.oh-my-knowledge', 'reports');
-// Shared CLI options for run/ci commands.
-// Defaults are applied inside parseRunConfig (after config-file merge) so that
-// CLI `undefined` can be reliably distinguished from "user passed the default value".
-// Priority order resolved in parseRunConfig: CLI arg > --config file > hard-coded default.
-/**
- * 所有子命令都接受的通用 flag。新增 --lang 让 parseArgs strict:false 模式下
- * 仍能把值类型化到 values.lang 上(否则未声明的 flag 会被丢弃)。
- */
-const COMMON_OPTIONS = {
-    lang: { type: 'string' },
-};
-const RUN_OPTIONS = {
-    ...COMMON_OPTIONS,
-    samples: { type: 'string' },
-    'skill-dir': { type: 'string' },
-    control: { type: 'string' },
-    treatment: { type: 'string' },
-    config: { type: 'string' },
-    model: { type: 'string' },
-    'judge-model': { type: 'string' },
-    'output-dir': { type: 'string' },
-    'no-judge': { type: 'boolean' },
-    'no-cache': { type: 'boolean' },
-    'dry-run': { type: 'boolean' },
-    concurrency: { type: 'string' },
-    timeout: { type: 'string' },
-    executor: { type: 'string' },
-    'judge-executor': { type: 'string' },
-    each: { type: 'boolean' },
-    'skip-preflight': { type: 'boolean' },
-    'mcp-config': { type: 'string' },
-    'no-serve': { type: 'boolean' },
-    verbose: { type: 'boolean' },
-    retry: { type: 'string' },
-    resume: { type: 'string' },
-    'layered-stats': { type: 'boolean' },
-    // v0.22 — strict-baseline default true. Declare both forms; reconcile in
-    // parseRunConfig (后者赢)。strict-baseline 没传 + no-strict-baseline 没传 = default true。
-    'strict-baseline': { type: 'boolean' },
-    'no-strict-baseline': { type: 'boolean' },
-};
-// ---------------------------------------------------------------------------
-// parseRunConfig
-// ---------------------------------------------------------------------------
-function parseRunConfig(argv, extraOptions = {}) {
-    const { values } = parseArgs({
-        args: argv,
-        options: { ...RUN_OPTIONS, ...extraOptions },
-        strict: false,
-    });
-    if (values.variants !== undefined) {
-        throw new Error(`--variants 已在 v0.16 废除，请改用 --control <expr> 与 --treatment <v1,v2,...>\n`
-            + `  迁移示例：--variants baseline,my-skill  →  --control baseline --treatment my-skill\n`
-            + `  复杂场景可用 --config eval.yaml（参见 docs/terminology-spec.md）`);
-    }
-    // 1) Load --config (if provided). All subsequent fields fall back to it when CLI is silent.
-    const evalConfig = values.config
-        ? loadEvalConfig(values.config)
-        : null;
-    // 2) Resolve samples path: CLI > config > auto-detect .json/.yaml/.yml in cwd.
-    const cliSamples = values.samples;
-    let samplesFile;
-    if (cliSamples) {
-        samplesFile = cliSamples;
-    }
-    else if (evalConfig?.samples) {
-        samplesFile = evalConfig.samples; // already resolved against config file dir
-    }
-    else {
-        samplesFile = 'eval-samples.json';
-        if (!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 skillDir = resolve(values['skill-dir'] ?? 'skills');
-    // 3) Resolve variantSpecs: CLI > config. If neither, error with a helpful hint.
-    const controlExpr = values.control;
-    const treatmentExprs = values.treatment
-        ? values.treatment.split(',').map((v) => v.trim()).filter(Boolean)
-        : [];
-    let variantSpecs;
-    if (controlExpr || treatmentExprs.length > 0) {
-        // CLI roles present → CLI entirely replaces config.variants (no merging).
-        variantSpecs = [];
-        if (controlExpr) {
-            variantSpecs.push({ name: parseVariantCwd(controlExpr).name, role: 'control', expr: controlExpr });
-        }
-        for (const expr of treatmentExprs) {
-            variantSpecs.push({ name: parseVariantCwd(expr).name, role: 'treatment', expr });
-        }
-    }
-    else if (evalConfig) {
-        variantSpecs = configVariantsToSpecs(evalConfig.variants);
-    }
-    else if (values.each) {
-        // --each 模式自动用 baseline (control) vs 每个 skill (treatment),
-        // 不需要用户显式传 --control / --treatment,校验跳过。
-        variantSpecs = [];
-    }
-    else {
-        const discovered = discoverVariants(skillDir);
-        const hint = discovered.length > 0 ? `\n  skill-dir (${skillDir}) 下发现的候选：${discovered.join(', ')}` : '';
-        throw new Error(`请通过 --control / --treatment 或 --config eval.yaml 声明 variant 角色。\n`
-            + `  示例：omk bench run --control baseline --treatment my-skill${hint}\n`
-            + `  --each 模式下自动用 baseline vs 每个 skill,无需显式声明\n`
-            + `  术语见 docs/terminology-spec.md（v0.16 起废除 --variants，改用 experiment role 显式声明）`);
-    }
-    const seenNames = new Set();
-    for (const spec of variantSpecs) {
-        if (seenNames.has(spec.name)) {
-            throw new Error(`variant "${spec.name}" 重复出现——同一 variant 不能同时属于 --control 与 --treatment，也不能在 --treatment 中重复。`);
-        }
-        seenNames.add(spec.name);
-    }
-    // 4) Apply CLI > config > hard-coded default for all other fields.
-    const executorName = values.executor ?? evalConfig?.executor ?? 'claude';
-    const judgeExecutorName = values['judge-executor'] ?? evalConfig?.judgeExecutor ?? executorName;
-    const model = values.model ?? evalConfig?.model ?? 'sonnet';
-    const judgeModelRaw = values['judge-model'] !== undefined
-        ? values['judge-model']
-        : evalConfig?.judgeModel ?? 'haiku';
-    const judgeModel = judgeModelRaw ?? 'haiku';
-    const outputDir = resolve(values['output-dir'] ?? DEFAULT_REPORTS_DIR);
-    const concurrencyRaw = values.concurrency !== undefined
-        ? Number(values.concurrency)
-        : evalConfig?.concurrency ?? 1;
-    const concurrency = Math.max(1, Number(concurrencyRaw) || 1);
-    const timeoutSec = values.timeout !== undefined
-        ? Number(values.timeout)
-        : evalConfig?.timeoutMs
-            ? evalConfig.timeoutMs / 1000
-            : 120;
-    const timeoutMs = Math.max(1, Number(timeoutSec) || 120) * 1000;
-    const noJudge = values['no-judge'] ?? false;
-    const noCache = values['no-cache'] ?? evalConfig?.noCache ?? false;
-    const dryRun = values['dry-run'] ?? false;
-    const skipPreflight = values['skip-preflight'] ?? false;
-    const mcpConfig = values['mcp-config'] ?? evalConfig?.mcpConfig;
-    const verbose = values.verbose ?? false;
-    const retry = Math.max(0, Number(values.retry ?? 0) || 0);
-    const resume = values.resume;
-    const blind = values.blind ?? evalConfig?.blind ?? false;
-    const layeredStats = values['layered-stats'] ?? false;
-    // v0.22 — strict-baseline default true. Reconcile both flag forms.
-    // Priority: --no-strict-baseline > --strict-baseline > undefined(=true).
-    const noStrictFlag = values['no-strict-baseline'];
-    const strictFlag = values['strict-baseline'];
-    const strictBaseline = noStrictFlag === true ? false : (strictFlag ?? true);
-    // v0.22 — extract eval.yaml variant.allowedSkills overrides (per-variant). Always
-    // wins over strictBaseline default. Empty object when no eval.yaml or no overrides.
-    const variantAllowedSkills = {};
-    if (evalConfig?.variants) {
-        for (const v of evalConfig.variants) {
-            if (v.allowedSkills !== undefined) {
-                variantAllowedSkills[v.name] = v.allowedSkills;
-            }
-        }
+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';
+function requireEvaluationReport(report, id, lang) {
+    if (!report) {
+        console.error(tCli('cli.common.report_not_found', lang, { id }));
+        process.exit(1);
     }
-    return {
-        values,
-        config: {
-            samplesPath: resolve(samplesFile),
-            skillDir,
-            variantSpecs,
-            model,
-            judgeModel,
-            outputDir,
-            noJudge,
-            noCache,
-            dryRun,
-            concurrency,
-            timeoutMs,
-            executorName,
-            judgeExecutorName,
-            skipPreflight,
-            mcpConfig,
-            verbose,
-            retry,
-            resume,
-            blind,
-            layeredStats,
-            budget: evalConfig?.budget,
-            strictBaseline,
-            ...(Object.keys(variantAllowedSkills).length > 0 && { variantAllowedSkills }),
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Update check
-// ---------------------------------------------------------------------------
-async function checkUpdate(lang) {
-    try {
-        const { readFileSync } = await import('node:fs');
-        const { fileURLToPath } = await import('node:url');
-        const { dirname, join } = await import('node:path');
-        const __dirname = dirname(fileURLToPath(import.meta.url));
-        const findPackageJson = (startDir) => {
-            let dir = startDir;
-            for (let i = 0; i < 5; i++) {
-                const candidate = join(dir, 'package.json');
-                if (existsSync(candidate))
-                    return candidate;
-                dir = dirname(dir);
-            }
-            return null;
-        };
-        const pkgPath = findPackageJson(__dirname);
-        if (!pkgPath)
-            return;
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        const registry = pkg.publishConfig?.registry || 'https://registry.npmjs.org';
-        const res = await fetch(`${registry}/${pkg.name}/latest`, { signal: AbortSignal.timeout(3000) });
-        if (!res.ok)
-            return;
-        const data = await res.json();
-        if (data.version && data.version !== pkg.version) {
-            process.stderr.write(tCli('cli.update.new_version_available', lang, {
-                old: pkg.version, new: data.version, pkg: pkg.name,
-            }));
-        }
+    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);
     }
-    catch { /* 静默失败,不影响正常使用 */ }
+    return report;
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -313,64 +96,15 @@ async function main() {
  * Factory: 闭住 lang, 返回 onProgress callback。evaluation engine 回调时不传
  * 上下文, 所以 lang 必须在 handler 入口处通过 closure 传进来。
  */
-function makeOnProgress(lang) {
-    return ({ phase, completed, total, sample_id, variant, durationMs, inputTokens, outputTokens, costUSD, score, outputPreview, judgePhase: _judgePhase, judgeDim, skipped, attempt, maxAttempts, error, }) => {
-        const ctx = { i: completed ?? '', n: total ?? '', sample: sample_id ?? '', variant: variant ?? '' };
-        if (phase === 'preflight') {
-            process.stderr.write(tCli('cli.progress.preflight_starting', lang));
-            return;
-        }
-        if (phase === 'retry') {
-            process.stderr.write(tCli('cli.progress.sample_retry', lang, {
-                ...ctx, attempt: attempt ?? '', max: maxAttempts ?? '',
-            }));
-            return;
-        }
-        if (phase === 'error') {
-            process.stderr.write(tCli('cli.progress.sample_error', lang, { ...ctx, error: error ?? '' }));
-            return;
-        }
-        if (phase === 'start') {
-            process.stderr.write(tCli('cli.progress.sample_executing', lang, ctx));
-        }
-        else if (phase === 'exec_done') {
-            const cost = costUSD != null && costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-            process.stderr.write(tCli('cli.progress.sample_exec_done', lang, {
-                ...ctx, ms: durationMs ?? '', input: inputTokens ?? '', output: outputTokens ?? '', cost,
-            }));
-            if (outputPreview) {
-                process.stderr.write(tCli('cli.progress.output_preview', lang, {
-                    preview: outputPreview.slice(0, 150).replace(/\n/g, ' '),
-                }));
-            }
-        }
-        else if (phase === 'grading') {
-            const dim = judgeDim ? ` [${judgeDim}]` : '';
-            process.stderr.write(tCli('cli.progress.judging', lang, { ...ctx, dim }));
-        }
-        else if (phase === 'judge_done') {
-            const dim = judgeDim ? ` [${judgeDim}]` : '';
-            process.stderr.write(tCli('cli.progress.judged', lang, { ...ctx, dim, score: score ?? '' }));
-        }
-        else if (phase === 'done' && skipped) {
-            if (sample_id)
-                process.stderr.write(tCli('cli.progress.skipped', lang, ctx));
-        }
-        else {
-            const cost = costUSD != null && costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-            const scoreInfo = typeof score === 'number' ? ` score=${score}` : '';
-            process.stderr.write(tCli('cli.progress.sample_done', lang, {
-                ...ctx, ms: durationMs ?? '', input: inputTokens ?? '', output: outputTokens ?? '',
-                cost, score: scoreInfo,
-            }));
-        }
-    };
-}
 // ---------------------------------------------------------------------------
 // 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);
+    }
     const { values, config } = parseRunConfig(argv, {
         blind: { type: 'boolean' },
         repeat: { type: 'string', default: '1' },
@@ -384,13 +118,13 @@ async function handleRun(argv) {
         '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)。
+    // 提前到 --batch 分支之前, 保证 batch 模式也能读到 repeat。
     const repeatRaw = values.repeat;
     const parsedRepeat = repeatRaw !== undefined ? Number(repeatRaw) : 1;
     if (repeatRaw !== undefined && (!Number.isFinite(parsedRepeat) || parsedRepeat < 1)) {
@@ -430,7 +164,7 @@ async function handleRun(argv) {
         }
     }
     // --budget-usd / --budget-per-sample-usd / --budget-per-sample-ms:
-    // v0.22 hard budget caps. CLI flags override config-file values. When the
+    //  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;
@@ -465,9 +199,9 @@ async function handleRun(argv) {
         config.bootstrapSamples = bsCount;
     }
     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 }) {
@@ -483,7 +217,7 @@ async function handleRun(argv) {
                 process.stderr.write(tCli('cli.run.batch_complete', lang));
                 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 { createReportServer } = await import('../server/report-server.js');
                     const server = createReportServer({ reportsDir: config.outputDir });
                     const serverUrl = await server.start();
                     const reportUrl = `${serverUrl}/reports/${report.id}`;
@@ -523,7 +257,7 @@ async function handleRun(argv) {
         // --gold-dir: compute α/κ/Pearson against gold annotations and re-persist.
         const goldDir = values['gold-dir'];
         if (goldDir && filePath) {
-            const { attachGoldAgreementToReport, formatGoldCompare } = await import('./grading/gold-cli.js');
+            const { attachGoldAgreementToReport, formatGoldCompare } = await import('../grading/gold-cli.js');
             const out = attachGoldAgreementToReport({
                 report,
                 goldDir,
@@ -551,7 +285,7 @@ async function handleRun(argv) {
             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 { createReportServer } = await import('../server/report-server.js');
                 const server = createReportServer({
                     reportsDir: config.outputDir,
                 });
@@ -582,6 +316,10 @@ async function handleRun(argv) {
 // ---------------------------------------------------------------------------
 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 } = parseArgs({
         args: argv,
         options: {
@@ -612,8 +350,8 @@ async function handleReport(argv) {
         return;
     }
     if (values.export) {
-        const { createFileStore } = await import('./server/report-store.js');
-        const { renderRunDetail, renderEachRunDetail } = await import('./renderer/html-renderer.js');
+        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);
@@ -621,14 +359,14 @@ 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}`);
         console.log('Open in browser, or Ctrl+P to save as PDF');
         return;
     }
-    const { createReportServer } = await import('./server/report-server.js');
+    const { createReportServer } = await import('../server/report-server.js');
     const server = createReportServer({
         port: Number(values.port),
         reportsDir: resolve(values['reports-dir']),
@@ -751,7 +489,7 @@ async function handleAnalyze(argv) {
     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 { computeSkillHealthReport } = await import('../observability/skill-health-analyzer.js');
     const report = computeSkillHealthReport(tracePath, {
         kbRoot: values.kb ? resolve(values.kb) : undefined,
         from,
@@ -800,11 +538,15 @@ async function handleInit(argv) {
 // ---------------------------------------------------------------------------
 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 } = parseArgs({
         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' },
@@ -812,11 +554,11 @@ async function handleGenSamples(argv) {
         strict: false,
         allowPositionals: true,
     });
-    const { generateSamples } = await import('./authoring/generator.js');
+    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)) {
@@ -944,7 +686,7 @@ async function handleEvolve(argv) {
         else if (existsSync(resolve('eval-samples.yml')))
             samplesFile = 'eval-samples.yml';
     }
-    const { evolveSkill } = await import('./authoring/evolver.js');
+    const { evolveSkill } = await import('../authoring/evolver.js');
     process.stderr.write(tCli('cli.evolve.section_header', lang, { path: skillPath }));
     try {
         const result = await evolveSkill({
@@ -960,10 +702,13 @@ async function handleEvolve(argv) {
             timeoutMs: Math.max(1, Number(values.timeout) || 120) * 1000,
             skipPreflight: values['skip-preflight'],
             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') {
@@ -975,7 +720,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),
                     }));
                 }
             },
@@ -983,9 +728,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),
@@ -1018,19 +766,20 @@ async function handleGate(argv) {
         threshold: { type: 'string', default: '3.5' },
         'trivial-diff': { type: 'string' },
     });
-    const { runEvaluation } = await import('./eval-workflows/run-evaluation.js');
+    const { runEvaluation } = await import('../eval-workflows/run-evaluation.js');
     config.onProgress = makeOnProgress(lang);
     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,
         // 堵住"过 PASS 就 deploy"的漏洞。
-        const { computeVerdict, formatVerdictText } = await import('./eval-core/verdict.js');
+        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,
@@ -1058,7 +807,7 @@ async function handleGate(argv) {
 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 (v0.22)
+    //   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 = [];
@@ -1092,23 +841,15 @@ async function handleDiff(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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 = 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;
@@ -1116,6 +857,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) {
@@ -1144,8 +889,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];
@@ -1156,18 +907,18 @@ async function handleDiff(argv) {
     console.log('');
 }
 /**
- * Within-report sample-level diff (v0.22). Compares two variants' scores on
+ * 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 = 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.');
@@ -1259,7 +1010,7 @@ async function handleGold(argv) {
             },
             strict: false,
         });
-        const { initGoldDataset } = await import('./grading/gold-cli.js');
+        const { initGoldDataset } = await import('../grading/gold-cli.js');
         try {
             const written = initGoldDataset(values.out, {
                 annotator: values.annotator,
@@ -1283,7 +1034,7 @@ async function handleGold(argv) {
             console.error(tCli('cli.common.usage_gold_validate', lang));
             process.exit(1);
         }
-        const { validateGoldDataset } = await import('./grading/gold-cli.js');
+        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 }));
@@ -1317,9 +1068,9 @@ async function handleGold(argv) {
             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 { 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:');
@@ -1333,15 +1084,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,
@@ -1387,13 +1134,9 @@ async function handleDebiasValidate(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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;
@@ -1401,7 +1144,7 @@ async function handleDebiasValidate(argv) {
         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 { loadSamples } = await import('../inputs/load-samples.js');
     const { samples } = loadSamples(samplesPath);
     const judgeModel = values['judge-model']
         ?? report.meta?.judgeModel;
@@ -1410,13 +1153,13 @@ async function handleDebiasValidate(argv) {
         process.exit(1);
     }
     process.stderr.write(tCli('cli.debias.warn_cost_doubles', lang));
-    const { createExecutor } = await import('./executors/index.js');
+    const { createExecutor } = await import('../executors/index.js');
     const judgeExecutor = createExecutor(values['judge-executor']);
-    const { validateLengthDebias, formatDebiasValidate } = await import('./grading/debias-validate.js');
+    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,
@@ -1448,13 +1191,9 @@ async function handleSaturation(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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));
@@ -1499,7 +1238,7 @@ async function handleSaturation(argv) {
     console.log('');
 }
 // ---------------------------------------------------------------------------
-// handleVerdict — one-line ship/no-ship verdict (v0.22)
+// handleVerdict — one-line ship/no-ship verdict
 // ---------------------------------------------------------------------------
 async function handleVerdict(argv) {
     const lang = langFromArgv(argv);
@@ -1519,14 +1258,14 @@ async function handleVerdict(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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 { computeVerdict, formatVerdictText } = await import('./eval-core/verdict.js');
+    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,
@@ -1568,13 +1307,9 @@ async function handleDiagnose(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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)
@@ -1583,7 +1318,7 @@ async function handleDiagnose(argv) {
     const samplesPath = values.samples ?? report.meta?.request?.samplesPath;
     if (samplesPath && existsSync(samplesPath)) {
         try {
-            const { loadSamples } = await import('./inputs/load-samples.js');
+            const { loadSamples } = await import('../inputs/load-samples.js');
             samples = loadSamples(samplesPath).samples;
         }
         catch (err) {
@@ -1594,7 +1329,7 @@ async function handleDiagnose(argv) {
     }
     const topRaw = Number(values.top);
     const topN = Number.isFinite(topRaw) && topRaw > 0 ? topRaw : undefined;
-    const { diagnoseSamples, formatSampleDiagnostics } = await import('./analysis/sample-diagnostics.js');
+    const { diagnoseSamples, formatSampleDiagnostics } = await import('../analysis/sample-diagnostics.js');
     const diag = diagnoseSamples(report, {
         samples,
         duplicateRouge: values['duplicate-rouge'] != null ? Number(values['duplicate-rouge']) : undefined,
@@ -1603,7 +1338,15 @@ 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 到
+    // 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);
@@ -1633,23 +1376,19 @@ async function handleFailures(argv) {
         },
         strict: false,
     });
-    const { createFileStore } = await import('./server/report-store.js');
+    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 judgeModel = values['judge-model'] ?? report.meta?.judgeModel;
     if (!judgeModel) {
         console.error(tCli('cli.common.no_judge_model', lang));
         process.exit(1);
     }
-    const { createExecutor } = await import('./executors/index.js');
+    const { createExecutor } = await import('../executors/index.js');
     const executor = createExecutor(values['judge-executor']);
-    const { clusterFailures, formatFailureClusterReport } = await import('./analysis/failure-clusterer.js');
+    const { clusterFailures, formatFailureClusterReport } = await import('../analysis/failure-clusterer.js');
     const out = await clusterFailures({
-        report: report,
+        report,
         executor,
         judgeModel,
         maxClusters: Number(values['max-clusters']) || 5,
@@ -1662,4 +1401,4 @@ async function handleFailures(argv) {
 // Entry
 // ---------------------------------------------------------------------------
 main();
-//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=index.js.map