oh-my-knowledge 0.21.0 → 0.23.0

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

@@ -1,208 +1,12 @@
 #!/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' },
-};
-// ---------------------------------------------------------------------------
-// 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;
-    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,
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// 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 pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), '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,
-            }));
-        }
-    }
-    catch { /* 静默失败,不影响正常使用 */ }
-}
+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';
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -279,66 +83,13 @@ 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);
     const { values, config } = parseRunConfig(argv, {
-        blind: { type: 'boolean', default: false },
+        blind: { type: 'boolean' },
         repeat: { type: 'string', default: '1' },
         'judge-repeat': { type: 'string', default: '1' },
         'judge-models': { type: 'string' },
@@ -350,8 +101,10 @@ 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');
-    config.blind = values.blind;
+    const { runEvaluation, runMultiple, runEachEvaluation } = 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)。
@@ -394,7 +147,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;
@@ -447,10 +200,10 @@ 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}/run/${report.id}`;
+                    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));
@@ -487,7 +240,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,
@@ -515,12 +268,12 @@ 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,
                 });
                 const serverUrl = await server.start();
-                const reportUrl = `${serverUrl}/run/${report.id}`;
+                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));
@@ -576,8 +329,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 { renderRunDetail, renderEachRunDetail } = 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);
@@ -592,7 +345,7 @@ async function handleReport(argv) {
         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']),
@@ -715,7 +468,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,
@@ -776,7 +529,7 @@ 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;
@@ -908,7 +661,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({
@@ -982,7 +735,7 @@ 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));
@@ -994,7 +747,7 @@ async function handleGate(argv) {
         // 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,
@@ -1022,7 +775,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 = [];
@@ -1056,7 +809,7 @@ 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);
@@ -1120,7 +873,7 @@ 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
@@ -1223,7 +976,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,
@@ -1247,7 +1000,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 }));
@@ -1281,9 +1034,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:');
@@ -1351,7 +1104,7 @@ 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) {
@@ -1365,7 +1118,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;
@@ -1374,9 +1127,9 @@ 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({
@@ -1412,7 +1165,7 @@ 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) {
@@ -1463,7 +1216,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);
@@ -1483,14 +1236,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 { computeVerdict, formatVerdictText } = await import('../eval-core/verdict.js');
     const result = computeVerdict(report, {
         gateThreshold: values.threshold != null ? Number(values.threshold) : undefined,
         triviallySmallDiff: values['trivial-diff'] != null ? Number(values['trivial-diff']) : undefined,
@@ -1532,7 +1285,7 @@ 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) {
@@ -1547,7 +1300,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) {
@@ -1558,7 +1311,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,
@@ -1568,6 +1321,14 @@ async function handleDiagnose(argv) {
         flatThreshold: values.flat != null ? Number(values.flat) : undefined,
     });
     console.log(formatSampleDiagnostics(diag, { topN }));
+    // 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);
@@ -1597,7 +1358,7 @@ 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) {
@@ -1609,9 +1370,9 @@ async function handleFailures(argv) {
         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,
         executor,
@@ -1626,4 +1387,4 @@ async function handleFailures(argv) {
 // Entry
 // ---------------------------------------------------------------------------
 main();
-//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=index.js.map