oh-my-knowledge 0.28.0 → 0.30.0

package/dist/src/renderer/summary.js

@@ -20,11 +20,11 @@ function verdictOneLine(level, lang, treatment, control) {
     const c = control ?? (lang === 'zh' ? '对照组' : 'control');
     if (lang === 'zh') {
         switch (level) {
-            case 'PROGRESS': return `${t} 比 ${c} 明显更好 — 可以发布`;
-            case 'CAUTIOUS': return `${t} 比 ${c} 略好 — 但建议再仔细看,差距很小或某层未达标`;
-            case 'REGRESS': return `${t} 比 ${c} 明显更差 — 不要发布`;
-            case 'NOISE': return `${t} 和 ${c} 没看出明显差别 — 可以多加几条用例再试`;
-            case 'UNDERPOWERED': return `评测用例数太少,看不出 ${t} 和 ${c} 的差别 — 多跑几个再看`;
+            case 'PROGRESS': return `${t} 比 ${c} 明显更好——可以发布`;
+            case 'CAUTIOUS': return `${t} 比 ${c} 略好——但建议再仔细看，差距很小或某层未达标`;
+            case 'REGRESS': return `${t} 比 ${c} 明显更差——不要发布`;
+            case 'NOISE': return `${t} 和 ${c} 没看出明显差别——可以多加几条用例再试`;
+            case 'UNDERPOWERED': return `评测用例数太少，看不出 ${t} 和 ${c} 的差别——多跑几个再看`;
             case 'SOLO': return `只跑了一组,需要加对照组才能对比`;
         }
     }
@@ -76,17 +76,38 @@ export function levelTooltip(level, lang) {
         case 'SOLO': return 'Single variant — no comparison';
     }
 }
-// v0.21 B.4 — Verdict pill 重写. 行业领先 status banner 三段式:
-//   1. Banner: 强信号(色 + 词) + 核心 metric (Δ + CI) + meta (pair / N / α)
-//   2. CTA: emoji + 加粗 action + 详情 (从 shipRecommendation 拆)
-//   3. Layers strip: fact/behavior/judge 一行带过, 不堆 bullets
-// 去掉旧版 headline 和 significance 的内容重复 (perPair[0].headline 是干净的
-// Δ+CI 核心, headline 拼装版只在 SOLO mode 用).
-//
-// computeVerdict 在历史混合批量 report 上有 NPE 风险 (顶层 summary
-// 缺 variant 数据时 evaluateLayerGates 访问 .avgFactScore 炸). 加 try/catch
-// 让 renderer 不 crash, 改为静默 skip pill — 这是 v0.21 B.4 的 scope 范围,
-// verdict.ts/layer-gates.ts 的 defensive 修复留作单独 task.
+// Verdict hero — verdict 是报告的「答案」，应在头部抢眼可读：
+//   行 1: 状态 badge (明显进步 / PROGRESS) + 自然语言句子 (含 ship action)
+//   行 2: 分差 + 评测规模 — 最直观的两个数字, "差多少 / 跑了多少"
+// machine-readable enum 通过 data-verdict-level 属性挂在 section 上，给 CI/工具用；
+// ship-action token 写进 aria-label 给 screen reader,但不放进 badge 显示文字 ——
+// 因为 verdictOneLine 的中文句子已经包含 "可以发布 / 不要发布" 这类 action,
+// badge 再放一遍是重复。CI / CV 这种统计学专名挪到 variance 表 + tooltip,hero
+// 不堆 jargon. 想看精确边界值的工程师下滑到下方的配对对比 / 波动检验表里看。
+// computeVerdict 在历史混合批量 report 上有 NPE 风险，try/catch 让 renderer 不 crash。
+const SHIP_LABEL = {
+    PROGRESS: { zh: '可发布', en: 'SHIP' },
+    CAUTIOUS: { zh: '需排查', en: 'INVESTIGATE' },
+    REGRESS: { zh: '勿发布', en: 'DO NOT SHIP' },
+    NOISE: { zh: '不下结论', en: 'NO CALL' },
+    UNDERPOWERED: { zh: '数据不足', en: 'INSUFFICIENT DATA' },
+    SOLO: { zh: '缺对照', en: 'ADD CONTROL' },
+};
+function computeMedianCVPercent(report) {
+    const variance = report.variance;
+    if (!variance || (variance.runs ?? 0) < 2)
+        return null;
+    const cvs = [];
+    for (const v of Object.values(variance.perVariant ?? {})) {
+        if (typeof v.stddev === 'number' && typeof v.mean === 'number' && v.mean > 0) {
+            cvs.push((v.stddev / v.mean) * 100);
+        }
+    }
+    if (cvs.length === 0)
+        return null;
+    cvs.sort((a, b) => a - b);
+    return cvs[Math.floor(cvs.length / 2)];
+}
 export function renderVerdictPill(report, lang) {
     let result;
     try {
@@ -100,13 +121,39 @@ export function renderVerdictPill(report, lang) {
     const oneLine = verdictOneLine(level, lang, pair?.treatment, pair?.control);
     const tooltip = levelTooltip(level, lang);
     const prefix = lang === 'zh' ? '测评结论' : 'Verdict';
-    // v0.21 B.4 — verdict 融入标题副标. 去 icon, 用 "测评结论:" 前缀引导, 让用户
-    // 一眼读到 "label : 结论" 的语义结构. 状态色信号通过 verdictOneLine 的中文
-    // 措辞 ("明显更好" / "明显更差" / "没看出差别") 传达, 不再依赖颜色 dot.
-    return `<p class="page-verdict verdict-${level}" role="status" aria-label="${e(prefix)}: ${e(oneLine)}" title="${e(tooltip)}">
-    <span class="page-verdict-label">${e(prefix)}:</span>
-    <span class="page-verdict-text">${e(oneLine)}</span>
-  </p>`;
+    // 机器可读 enum 永远是 level token; 显示给用户的文字按 lang i18n.
+    const levelDisplay = lang === 'zh' ? levelLabel(level, lang) : level;
+    const shipAria = lang === 'zh' ? SHIP_LABEL[level].zh : SHIP_LABEL[level].en;
+    // hero 只放「答案」: 分差是 verdict 的核心证据数字, 单独一枚 chip。
+    // 评测规模 (用例数 × 轮次) 走「实验配置」section 的 subtitle 那条 canonical 路径,
+    // 不在 hero 里重复; CV / CI 走 chip tooltip + 方法学审计 / 波动表。
+    const ci = report.meta?.pairComparisons?.[0]?.diffBootstrapCI;
+    const cvPct = computeMedianCVPercent(report);
+    const metrics = [];
+    if (ci) {
+        const sign = ci.estimate >= 0 ? '+' : '';
+        const cvSuffix = cvPct != null
+            ? (lang === 'zh' ? `;多轮稳定性 CV=${cvPct.toFixed(1)}% (${cvPct < 5 ? '稳' : cvPct < 15 ? '中' : '不稳'})` : `; CV=${cvPct.toFixed(1)}% (${cvPct < 5 ? 'stable' : cvPct < 15 ? 'moderate' : 'unstable'})`)
+            : '';
+        const ciTipBase = lang === 'zh'
+            ? `实验组与对照组综合分均值差(Δ)。bootstrap 95% 可信区间 [${ci.low}, ${ci.high}]，${ci.significant ? '不含 0 = 差异显著' : '跨过 0 = 差异不显著'}${cvSuffix}`
+            : `Treatment minus control mean composite score (Δ). Bootstrap 95% CI [${ci.low}, ${ci.high}], ${ci.significant ? 'excludes 0 ⇒ significant' : 'spans 0 ⇒ not significant'}${cvSuffix}`;
+        metrics.push({
+            label: lang === 'zh' ? '分差' : 'Δ',
+            value: `${sign}${ci.estimate}`,
+            tip: ciTipBase,
+        });
+    }
+    const metricChips = metrics.map((m) => `<span class="verdict-metric"${m.tip ? ` title="${e(m.tip)}"` : ''}>` +
+        `<span class="verdict-metric-label">${e(m.label)}</span>` +
+        `<span class="verdict-metric-value">${e(m.value)}</span></span>`).join('');
+    return `<section class="page-verdict verdict-${level}" role="status" data-verdict-level="${e(level)}" aria-label="${e(prefix)}: ${e(levelDisplay)} · ${e(shipAria)} · ${e(oneLine)}" title="${e(tooltip)}">
+    <div class="page-verdict-head">
+      <span class="page-verdict-badge"><span class="page-verdict-badge-dot" aria-hidden="true">●</span>${e(levelDisplay)}</span>
+      <span class="page-verdict-text">${e(oneLine)}</span>
+    </div>
+    ${metricChips ? `<div class="page-verdict-metrics">${metricChips}</div>` : ''}
+  </section>`;
 }
 /**
  * Pairwise diff (treatment vs control) bootstrap CI table — populated only when
@@ -170,11 +217,11 @@ export function renderHumanAgreement(agreement, lang) {
     const interpret = lang === 'zh'
         ? (Number.isNaN(a.alpha)
             ? '评分多样性不足，α 未定义'
-            : a.alpha >= 0.8 ? '高度一致 — 结论可放心使用'
-                : a.alpha >= 0.667 ? '可接受 — 谨慎结论'
-                    : a.alpha >= 0.4 ? '较弱一致 — 结论需配合 CI 与人工抽检'
-                        : a.alpha >= 0 ? '偏差较大 — 排查 rubric / prompt'
-                            : '系统性反向 — 重新审视判分逻辑')
+            : a.alpha >= 0.8 ? '高度一致——结论可放心使用'
+                : a.alpha >= 0.667 ? '可接受——谨慎结论'
+                    : a.alpha >= 0.4 ? '较弱一致——结论需配合 CI 与人工抽检'
+                        : a.alpha >= 0 ? '偏差较大——排查 rubric / prompt'
+                            : '系统性反向——重新审视判分逻辑')
         : (Number.isNaN(a.alpha)
             ? 'insufficient rating variance for α'
             : a.alpha >= 0.8 ? 'high agreement — conclusions trustworthy'
@@ -323,7 +370,10 @@ export function renderSummaryCards(variants, summary, lang, variance) {
     //
     // composite 合成分 (= (fact + behavior + judge) / 3) 从 v0.16 起不再在此表主视觉呈现,
     // 仅保留在 report JSON 数据层 + Variance & Significance 表顶层 flat 字段(legacy)。
-    // 理由见 docs/terminology-spec.md 三-6 节:三层独立呈现避免合成分掩盖结构性差异。
+    // 综合分放在第一列, 紧贴 实验分组. 它是 fact/behavior/judge 三层的等权均值,
+    // 在 omk 内部承担「跨 run 排序 / bootstrap CI / verdict 比较信号」三个角色 ——
+    // 这里展示 + 表头 ? button 弹 modal 公开计算方式 + 局限, 让用户知情消费。
+    // 其余六列保持 layer-first (fact / behavior / judge / cost / efficiency / stability)。
     const headerCols = [
         { key: 'dimFact', label: t('dimFact', lang) },
         { key: 'dimBehavior', label: t('dimBehavior', lang) },
@@ -332,18 +382,23 @@ export function renderSummaryCards(variants, summary, lang, variance) {
         { key: 'dimEfficiency', label: t('dimEfficiency', lang) },
         { key: 'dimStability', label: t('dimStability', lang) },
     ];
+    const scoringModalId = 'guide-scoring';
+    // v0.30 — 拆 hero(每变体综合分一行)+ heatmap 表(去 composite,加色块)。
+    // composite 从表里挪出来当 hero,大字号 + delta 跟 baseline 对比;
+    // 维度细节继续用表,但每格按 score 浅色填充,便于扫读弱维度。
     const thead = `<tr><th data-i18n="variants">${t('variants', lang)}</th>${headerCols.map((c) => `<th data-i18n="${c.key}">${c.label}</th>`).join('')}</tr>`;
-    // 渲染单层分数 cell(事实/行为/LLM 评价通用)。
-    // 优先读跨 run 均值(byLayer[key].mean),fallback 到 summary 的单 run avg。
-    // 缺数据时显示 "—" + 灰色,让读者明确看到"这一层这批用例/评委没测到",不假装有值。
+    // 渲染单层分数 cell(事实/行为/LLM 评价通用)— 加 heatmap 浅色背景
     function renderLayerCell(varianceMean, summaryValue, detailHtml = '') {
         const v = varianceMean ?? summaryValue;
         const hasValue = typeof v === 'number' && v > 0;
+        const heatClass = hasValue
+            ? (v >= 4 ? 'sm-heat-pass' : v >= 3 ? 'sm-heat-warn' : 'sm-heat-fail')
+            : '';
         const color = hasValue
             ? (v >= 4 ? 'var(--green)' : v >= 3 ? 'var(--yellow)' : 'var(--red)')
             : 'var(--text-muted)';
         const display = hasValue ? v.toFixed(2) : '—';
-        return `<td class="summary-cell"><div class="summary-value summary-value-primary" style="color:${color}">${display}</div>${detailHtml}</td>`;
+        return `<td class="summary-cell ${heatClass}"><div class="summary-value summary-value-primary" style="color:${color}">${display}</div>${detailHtml}</td>`;
     }
     const rows = variants.map((v, i) => {
         const s = summary[v] || {};
@@ -451,6 +506,41 @@ export function renderSummaryCards(variants, summary, lang, variance) {
         const stabCell = `<td class="summary-cell"><div class="summary-value" style="color:${stabColor}">${stabValue}</div>${stabDetail}</td>`;
         return `<tr><td style="border-left:3px solid ${color};padding-left:12px"><strong>${e(v)}</strong></td>${factCell}${behaviorCell}${judgeCell}${costCell}${effCell}${stabCell}</tr>`;
     }).join('');
+    // ──────────── Hero 行:每 variant 一行,综合分大字号 + delta vs baseline ────────────
+    // 每变体一行,左 variant 名 + 颜色条;中 大字号 composite;右 delta(vs variants[0])
+    const baselineComposite = summary[variants[0]]?.avgCompositeScore;
+    const heroRows = variants.map((v, i) => {
+        const s = summary[v] || {};
+        const composite = s.avgCompositeScore;
+        const compositeHasValue = typeof composite === 'number' && composite > 0;
+        const compositeColor = compositeHasValue
+            ? (composite >= 4 ? 'var(--green)' : composite >= 3 ? 'var(--yellow)' : 'var(--red)')
+            : 'var(--text-muted)';
+        const compositeDisplay = compositeHasValue ? composite.toFixed(2) : '—';
+        const color = COLORS[i % COLORS.length];
+        let deltaHtml = '';
+        if (i > 0 && compositeHasValue && typeof baselineComposite === 'number' && baselineComposite > 0) {
+            const diff = composite - baselineComposite;
+            if (Math.abs(diff) >= 0.01) {
+                const sign = diff > 0 ? '+' : '';
+                const dColor = diff > 0 ? 'var(--green)' : 'var(--red)';
+                const arrow = diff > 0 ? '↑' : '↓';
+                deltaHtml = `<span class="sm-hero-delta" style="color:${dColor}">${sign}${diff.toFixed(2)} ${arrow}</span>`;
+            }
+        }
+        return `<div class="sm-hero" style="border-left:3px solid ${color}">
+      <div class="sm-hero-name">${e(v)}</div>
+      <div class="sm-hero-score" style="color:${compositeColor}">${compositeDisplay}<span class="sm-hero-unit">/ 5</span></div>
+      ${deltaHtml || '<span class="sm-hero-delta-placeholder"></span>'}
+    </div>`;
+    }).join('');
+    const heroBlock = `<div class="sm-hero-list">
+    <div class="sm-hero-h">
+      ${lang === 'zh' ? '综合分' : 'Composite'}
+      <button type="button" class="hint-btn" onclick="openModal('${scoringModalId}')" aria-label="${e(lang === 'zh' ? '综合分怎么算的？' : 'How is composite computed?')}" aria-haspopup="dialog">?</button>
+    </div>
+    ${heroRows}
+  </div>`;
     const guideModalId = 'guide-six-dims';
     const guideTitle = lang === 'zh' ? '如何阅读六维对比？' : 'How to read this six-dimension comparison?';
     const guideIntro = lang === 'zh'
@@ -487,6 +577,7 @@ export function renderSummaryCards(variants, summary, lang, variance) {
     <tr><td ${sub}>CV</td><td ${subDesc}>Score swing as a percentage of the mean (e.g., CV 2% = swings are about 2% of the mean)</td></tr>
     <tr><td ${sub}>95% CI</td><td ${subDesc}>If you ran infinitely many times, the true mean has a 95% chance of falling in this range — narrower = you can trust the measured mean more</td></tr>
   `;
+    const scoringModalHtml = renderScoringModal(scoringModalId, lang);
     return `
     <h2 style="display:flex;align-items:center;gap:4px">${lang === 'zh' ? '六维对比' : 'Six-Dimension Comparison'} <button type="button" class="hint-btn" onclick="openModal('${guideModalId}')" aria-label="${e(guideTitle)}" aria-haspopup="dialog">?</button></h2>
     <div id="${guideModalId}" class="modal-overlay" role="dialog" aria-modal="true" aria-labelledby="${guideModalId}-title" onclick="if(event.target===this)closeModal('${guideModalId}')">
@@ -499,13 +590,94 @@ export function renderSummaryCards(variants, summary, lang, variance) {
         <table class="modal-table"><tbody>${guideRows}</tbody></table>
       </div>
     </div>
+    ${scoringModalHtml}
+    ${heroBlock}
     <div class="table-wrap">
     <table class="summary-table">
       <thead>${thead}</thead>
       <tbody>${rows}</tbody>
     </table>
     </div>
-    ${renderJudgeAgreementBlock(variants, summary, lang)}`;
+    <style>
+    /* 六维对比 — Hero 区(每 variant 综合分 + delta) */
+    .sm-hero-list { display:flex;flex-direction:column;gap:8px;margin:14px 0 18px }
+    .sm-hero-h { font-size:13px;color:var(--text-muted);margin-bottom:4px;letter-spacing:0.02em }
+    .sm-hero { display:flex;align-items:baseline;gap:16px;padding:14px 18px;background:var(--bg-surface);border-radius:var(--radius);box-shadow:var(--shadow-sm) }
+    .sm-hero-name { flex:1;font-size:14.5px;font-weight:500;color:var(--text-primary) }
+    .sm-hero-score { font-size:28px;font-weight:600;font-variant-numeric:tabular-nums;line-height:1 }
+    .sm-hero-unit { font-size:13px;color:var(--text-muted);margin-left:4px;font-weight:400 }
+    .sm-hero-delta { font-size:14px;font-weight:600;font-variant-numeric:tabular-nums;font-family:"SF Mono",Menlo,monospace;min-width:60px;text-align:right }
+    .sm-hero-delta-placeholder { display:inline-block;min-width:60px }
+    /* 六维 heatmap — 每格按分数浅色填充,便于远看识别弱维度 */
+    .sm-heat-pass { background:linear-gradient(0deg,var(--green-bg),var(--green-bg)) }
+    .sm-heat-warn { background:linear-gradient(0deg,var(--yellow-bg),var(--yellow-bg)) }
+    .sm-heat-fail { background:linear-gradient(0deg,var(--red-bg),var(--red-bg)) }
+    </style>`;
+}
+/**
+ * 评分说明 modal — 公开 composite 计算方式 + 局限,所有展示综合分的地方都通向同一份说明
+ * (六维对比表头 / 列表页 score 列 / 趋势页 chart caption)。
+ *
+ * 测量学诚实性 ≠ 藏起来怕用户误用,而是展示 + 说清楚边界。这个 modal 是简版 (~10 行),
+ * 完整推导 (五层评分管道架构 / ratioToScore 公式 / 多层 gate 与 composite 关系)
+ * 在 docs/zh/scoring.md。
+ */
+export function renderScoringModal(id, lang) {
+    const title = lang === 'zh' ? '综合分怎么算的？' : 'How is composite computed?';
+    const intro = lang === 'zh'
+        ? '综合分（composite）= 等权均值（{事实, 行为, LLM 评价}）。1-5 制。'
+        : 'Composite = unweighted mean of {fact, behavior, LLM judge}. Scale 1-5.';
+    const sectionHead = (text) => `<tr><td colspan="2" style="padding:14px 0 6px;color:var(--text-primary);font-weight:600;font-size:13px;border-top:1px solid var(--border)">${e(text)}</td></tr>`;
+    const row = (label, body) => `<tr><td style="padding:6px 12px 6px 0;color:var(--text-secondary);font-size:12px;font-weight:500;white-space:nowrap;vertical-align:top;width:120px">${e(label)}</td><td style="padding:6px 0;color:var(--text-secondary);font-size:12px;line-height:1.6">${body}</td></tr>`;
+    const calcRows = lang === 'zh' ? [
+        row('事实 / 行为', '断言通过率经 <code>1 + 通过率 × 4</code> 线性映射到 1-5 制'),
+        row('LLM 评价', '评委模型直接给 1-5 分'),
+        row('缺失某层', '自动降维（参与计算的层取均值）'),
+    ] : [
+        row('Fact / Behavior', 'Assertion pass-rate mapped to 1-5 via <code>1 + ratio × 4</code>'),
+        row('LLM judge', 'Judge model returns 1-5 score directly'),
+        row('Missing layer', 'Auto-collapse (mean over present layers)'),
+    ];
+    const limitRows = lang === 'zh' ? [
+        row('① 等权聚合', '三层各 1/3 权重不是从需求 derive 的，无显式构造效度论证'),
+        row('② 量尺不一致', '事实是 binary 通过率 stretch 到 1-5；评委是真序数评分。直接均值违反量表理论（measurement scale homogeneity）'),
+        row('③ 缺失自动降维', '不同 variant / skill 配的层数不同时，综合分数字相同但 construct 不同，<strong>不可机械跨 variant / 跨 skill 比较</strong>'),
+    ] : [
+        row('① Equal-weight aggregation', 'The 1/3 weight per layer is ad hoc, not derived from stakeholder needs; no explicit construct validity argument'),
+        row('② Mixed scales added directly', 'Fact is binary pass-rate stretched to 1-5; judge is true ordinal. Direct mean violates measurement scale homogeneity'),
+        row('③ Auto-collapse on missing', 'When variants/skills have different layer coverage, composite numbers look same but represent different constructs — <strong>not mechanically comparable across variants/skills</strong>'),
+    ];
+    const usageRows = lang === 'zh' ? [
+        row('✓ 适用', '同一份 eval-samples 上 A/B 比较，看「分差 + bootstrap CI + 三层独立 gate」联合判断'),
+        row('✗ 不适用', '当作 absolute psychometric measure（说「这 skill 4.28/5 分」）'),
+    ] : [
+        row('✓ Use for', 'A/B comparison on same eval-samples — read "diff + bootstrap CI + per-layer gate" jointly'),
+        row('✗ Don\'t use as', 'Absolute psychometric measure (claiming "this skill is 4.28/5")'),
+    ];
+    const calcSection = lang === 'zh' ? '怎么算的' : 'How it\'s computed';
+    const limitSection = lang === 'zh' ? '局限（直白说）' : 'Limitations (frankly)';
+    const usageSection = lang === 'zh' ? '推荐用法' : 'Recommended usage';
+    const docsLink = lang === 'zh'
+        ? '完整推导 / 五层评分管道架构 / 多层 gate 与综合分的关系：<a href="https://github.com/lizhiyao/oh-my-knowledge/blob/main/docs/zh/scoring.md" target="_blank" rel="noopener">docs/zh/scoring.md</a>'
+        : 'Full derivation / five-layer scoring pipeline / multi-layer gate & composite relationship: <a href="https://github.com/lizhiyao/oh-my-knowledge/blob/main/docs/zh/scoring.md" target="_blank" rel="noopener">docs/zh/scoring.md</a>';
+    return `<div id="${id}" class="modal-overlay" role="dialog" aria-modal="true" aria-labelledby="${id}-title" onclick="if(event.target===this)closeModal('${id}')">
+    <div class="modal-content">
+      <div class="modal-header">
+        <strong id="${id}-title" style="font-size:1rem">${e(title)}</strong>
+        <button type="button" class="modal-close" onclick="closeModal('${id}')" aria-label="${lang === 'zh' ? '关闭' : 'Close'}">✕</button>
+      </div>
+      <p style="font-size:13px;color:var(--text-secondary);margin:4px 0 12px">${e(intro)}</p>
+      <table class="modal-table"><tbody>
+        ${sectionHead(calcSection)}
+        ${calcRows.join('')}
+        ${sectionHead(limitSection)}
+        ${limitRows.join('')}
+        ${sectionHead(usageSection)}
+        ${usageRows.join('')}
+      </tbody></table>
+      <p style="font-size:11px;color:var(--text-muted);margin:14px 0 0;line-height:1.6">${docsLink}</p>
+    </div>
+  </div>`;
 }
 /**
  * Cross-sample inter-judge agreement table — only renders when at least one variant
@@ -513,7 +685,7 @@ export function renderSummaryCards(variants, summary, lang, variance) {
  * Pearson + MAD across the whole sample set, the metric that refutes "Claude judge
  * Claude same-modality bias".
  */
-function renderJudgeAgreementBlock(variants, summary, lang) {
+export function renderJudgeAgreementBlock(variants, summary, lang) {
     const variantsWithEnsemble = variants.filter((v) => summary[v]?.judgeAgreement);
     if (variantsWithEnsemble.length === 0)
         return '';
@@ -551,6 +723,116 @@ function renderJudgeAgreementBlock(variants, summary, lang) {
     </table>
     </div>`;
 }
+function badgeIcon(status) {
+    switch (status) {
+        case 'pass': return '✓';
+        case 'warn': return '⚠';
+        case 'fail': return '✗';
+        case 'skip': return '—';
+    }
+}
+function computeJudgeAgreementBadge(variants, summary, lang) {
+    const treatment = variants[1] ?? variants[0];
+    const ag = summary[treatment]?.judgeAgreement;
+    if (!ag || ag.pearson == null)
+        return null;
+    const p = ag.pearson;
+    const status = p >= 0.7 ? 'pass' : p >= 0.4 ? 'warn' : 'fail';
+    const verdict = status === 'pass'
+        ? (lang === 'zh' ? '评委一致' : 'judges agree')
+        : status === 'warn'
+            ? (lang === 'zh' ? '评委偏弱一致' : 'judges weakly agree')
+            : (lang === 'zh' ? '评委分歧大' : 'judges diverge');
+    return {
+        key: 'judge',
+        label: verdict,
+        status,
+        detail: lang === 'zh' ? `Pearson ${p}（≥0.7 一致 / 0.4-0.7 偏弱 / <0.4 分歧）` : `Pearson ${p} (≥0.7 agree / 0.4-0.7 weak / <0.4 diverge)`,
+    };
+}
+function computeSignificanceBadge(report, lang) {
+    const ci = report.meta?.pairComparisons?.[0]?.diffBootstrapCI;
+    if (!ci)
+        return null;
+    const status = ci.significant ? 'pass' : 'warn';
+    const label = ci.significant
+        ? (lang === 'zh' ? '差异显著' : 'significant')
+        : (lang === 'zh' ? '差异不显著' : 'not significant');
+    return {
+        key: 'sig',
+        label,
+        status,
+        detail: lang === 'zh' ? `bootstrap 95% CI [${ci.low}, ${ci.high}]${ci.significant ? '（不含 0）' : '（跨过 0）'}` : `Bootstrap 95% CI [${ci.low}, ${ci.high}]${ci.significant ? ' (excludes 0)' : ' (spans 0)'}`,
+    };
+}
+function computeSaturationBadge(report, variants, lang) {
+    const sat = report.variance?.saturation?.verdicts;
+    if (!sat)
+        return null;
+    const treatment = variants[1] ?? variants[0];
+    const v = sat[treatment];
+    if (!v)
+        return null;
+    const status = v.saturated
+        ? (v.confidence === 'high' ? 'pass' : 'warn')
+        : 'warn';
+    const label = v.saturated
+        ? (lang === 'zh' ? '已饱和' : 'saturated')
+        : (lang === 'zh' ? '未饱和' : 'not saturated');
+    return {
+        key: 'sat',
+        label,
+        status,
+        detail: lang === 'zh'
+            ? `${v.saturated ? `于 N=${v.atN ?? '?'} 饱和` : '尚未饱和'}（${v.confidence} confidence）`
+            : `${v.saturated ? `saturates at N=${v.atN ?? '?'}` : 'not yet saturated'} (${v.confidence} confidence)`,
+    };
+}
+function computeHumanAlignmentBadge(report, lang) {
+    const a = report.meta?.humanAgreement;
+    if (!a || a.sampleCount === 0 || Number.isNaN(a.alpha))
+        return null;
+    const status = a.alpha >= 0.667 ? 'pass' : a.alpha >= 0.4 ? 'warn' : 'fail';
+    const label = status === 'pass'
+        ? (lang === 'zh' ? '人工对齐' : 'aligns with humans')
+        : status === 'warn'
+            ? (lang === 'zh' ? '人工对齐偏弱' : 'weakly aligns')
+            : (lang === 'zh' ? '与人工分歧' : 'diverges from humans');
+    return {
+        key: 'human',
+        label,
+        status,
+        detail: lang === 'zh' ? `Krippendorff α=${a.alpha.toFixed(3)} vs ${a.goldAnnotator}` : `Krippendorff α=${a.alpha.toFixed(3)} vs ${a.goldAnnotator}`,
+    };
+}
+export function renderMethodologyAudit(report, variants, summary, lang) {
+    const judgeBlock = renderJudgeAgreementBlock(variants, summary, lang);
+    const pairwiseBlock = renderPairwiseDiff(report.meta?.pairComparisons, lang);
+    const humanBlock = renderHumanAgreement(report.meta?.humanAgreement, lang);
+    const saturationBlock = renderSaturationCurve(report.variance?.saturation, variants, lang);
+    if (!judgeBlock && !pairwiseBlock && !humanBlock && !saturationBlock)
+        return '';
+    const badges = [
+        computeJudgeAgreementBadge(variants, summary, lang),
+        computeSignificanceBadge(report, lang),
+        computeSaturationBadge(report, variants, lang),
+        computeHumanAlignmentBadge(report, lang),
+    ].filter((b) => b !== null);
+    // 默认折叠;只有 ✗ fail (红色 badge) 才强制展开 — summary 行已经显示
+    // ⚠ warn 状态, 用户能自决是否展开; 但 fail 是危险信号必须让用户看证据。
+    const hasFailure = badges.some((b) => b.status === 'fail');
+    const openAttr = hasFailure ? ' open' : '';
+    const summaryLabel = lang === 'zh' ? '测评可信度' : 'Reliability check';
+    const summaryHint = lang === 'zh' ? '点击展开看支撑证据(评委一致 / 差异显著 / 饱和度 / 人工对齐)' : 'click to expand evidence (judge agreement / significance / saturation / human alignment)';
+    const badgesHtml = badges.length > 0
+        ? `<span class="methodology-badges">${badges.map((b) => `<span class="methodology-badge methodology-badge-${b.status}" title="${e(b.detail)}">${badgeIcon(b.status)} ${e(b.label)}</span>`).join('')}</span>`
+        : '';
+    const innerSections = [judgeBlock, pairwiseBlock, humanBlock, saturationBlock].filter(Boolean).join('');
+    return `<details class="methodology-audit"${openAttr}>
+    <summary><span class="methodology-summary-label">${e(summaryLabel)}</span>${badgesHtml}<span class="methodology-summary-hint">${e(summaryHint)}</span></summary>
+    <div class="methodology-body">${innerSections}</div>
+  </details>`;
+}
 function buildDiagnostic(metric, cfg, winner, lang) {
     const es = metric.effectSize;
     if (!es || es.primary === 'none') {
@@ -1203,56 +1485,39 @@ export function renderAgentOverview(variants, summary, lang) {
     const hasAgentData = variants.some((variant) => summary[variant]?.avgToolCalls != null && summary[variant].avgToolCalls > 0);
     if (!hasAgentData)
         return '';
-    const variantCards = variants.map((variant, i) => {
+    // v0.30 — Agent 执行概览弱化为 ctx-row(单行 inline)样式,跟实验配置并排放在 context-strip 里。
+    // 主要数字:轮次 / 工具调用数 / 成功率,加 tooltip 显示工具分布。
+    const variantRows = variants.map((variant, i) => {
         const stats = summary[variant];
         if (!stats)
             return '';
         const color = COLORS[i % COLORS.length];
         const avgTools = stats.avgToolCalls ?? 0;
-        const successRate = stats.toolSuccessRate != null ? `${(stats.toolSuccessRate * 100).toFixed(0)}%` : '-';
+        const successRate = stats.toolSuccessRate != null ? `${(stats.toolSuccessRate * 100).toFixed(0)}%` : '—';
         const successRateColor = (stats.toolSuccessRate ?? 1) >= 0.8 ? 'var(--green)' : 'var(--red)';
         const turns = stats.avgFullNumTurns ?? stats.avgNumTurns ?? 0;
         const distributionEntries = Object.entries(stats.toolDistribution || {}).sort((a, b) => b[1] - a[1]);
-        const maxCount = distributionEntries.length > 0 ? distributionEntries[0][1] : 0;
-        const distributionBars = distributionEntries.map(([tool, count]) => {
-            const pct = maxCount > 0 ? Math.max(8, (count / maxCount) * 100) : 0;
-            return `<div style="display:flex;align-items:center;gap:6px;margin:2px 0">
-        <span style="font-size:11px;color:var(--text-muted);width:100px;text-align:right;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex-shrink:0" title="${e(tool)}">${e(tool)}</span>
-        <div style="flex:1;height:8px;background:var(--bg-surface);border-radius:4px">
-          <div style="width:${pct}%;height:100%;background:${color};border-radius:4px"></div>
-        </div>
-        <span style="font-size:11px;color:var(--text-secondary);min-width:20px">${count}</span>
-      </div>`;
-        }).join('');
-        return `<div style="flex:1;min-width:240px;padding:16px;background:var(--bg-surface);border:1px solid var(--border);border-radius:var(--radius);border-left:3px solid ${color}">
-      <div style="font-weight:600;margin-bottom:12px">${e(variant)}</div>
-      <div style="display:grid;grid-template-columns:1fr 1fr;gap:8px;margin-bottom:12px">
-        <div>
-          <div style="font-size:11px;color:var(--text-muted)">${t('agentAvgTurns', lang)}</div>
-          <div style="font-size:20px;font-weight:600">${turns}</div>
-        </div>
-        <div>
-          <div style="font-size:11px;color:var(--text-muted)">${t('agentAvgTools', lang)}</div>
-          <div style="font-size:20px;font-weight:600">${avgTools}</div>
-        </div>
-        <div>
-          <div style="font-size:11px;color:var(--text-muted)">${t('agentToolSuccess', lang)}</div>
-          <div style="font-size:20px;font-weight:600;color:${successRateColor}">${successRate}</div>
-        </div>
-      </div>
-      ${distributionEntries.length > 0 ? `
-        <div style="font-size:11px;color:var(--text-muted);margin-bottom:4px">${t('agentToolDist', lang)}</div>
-        ${distributionBars}
-      ` : ''}
+        const distSummary = distributionEntries.length > 0
+            ? distributionEntries.slice(0, 5).map(([tool, count]) => `${tool}×${count}`).join(' · ')
+            : '';
+        const tooltip = distSummary ? `${t('agentToolDist', lang)}: ${distSummary}` : '';
+        return `<div class="ctx-row" style="border-left:3px solid ${color}"${tooltip ? ` title="${e(tooltip)}"` : ''}>
+      <span class="ctx-row-name">${e(variant)}</span>
+      <span class="ctx-row-bits">
+        <span>${turns} ${t('turnsPerReq', lang)}</span>
+        <span class="ctx-sep">·</span>
+        <span>${avgTools} ${lang === 'zh' ? '工具/次' : 'tools/req'}</span>
+        <span class="ctx-sep">·</span>
+        <span style="color:${successRateColor}">${successRate} OK</span>
+      </span>
     </div>`;
     }).join('');
     return `
-    <section style="margin-top:24px">
-      <h2>${t('agentOverview', lang)}</h2>
-      <div style="display:flex;gap:16px;flex-wrap:wrap">
-        ${variantCards}
-      </div>
-    </section>
+    <div class="ctx-block">
+      <div class="ctx-h">${t('agentOverview', lang)}</div>
+      <div class="ctx-sub">${lang === 'zh' ? '工具调用统计 · 轮次 / 调用数 / 成功率' : 'Tool call stats · turns / calls / success rate'}</div>
+      <div class="ctx-rows">${variantRows}</div>
+    </div>
   `;
 }
 export function renderCoverageSection(coverage, lang) {
@@ -1343,6 +1608,13 @@ export function renderKnowledgeInteractionSection(coverage, gapReports, lang) {
     const hasGap = gapReports && Object.keys(gapReports).length > 0;
     if (!hasCov && !hasGap)
         return '';
+    // 所有 variant 的 coverage 都不可用 (filesTotal === 0) 且所有 gap 都是 0%(无信号)
+    // 时,整个 section 没有可读信息 — 渲染只会占大段纵向空间显示「数据不可用 / 0%」
+    // 干扰用户阅读流。直接跳过比强行展示「显式无信号」更尊重读者。
+    const usefulCoverage = hasCov && Object.values(coverage).some((c) => c.filesTotal > 0);
+    const usefulGap = hasGap && Object.values(gapReports).some((g) => g.gapRate > 0 || g.signals.length > 0);
+    if (!usefulCoverage && !usefulGap)
+        return '';
     const title = lang === 'zh' ? '本次测评：评测用例 × 知识库' : 'This Evaluation: Test Set × Knowledge Base';
     const desc = lang === 'zh'
         ? '展示本次评测用例和知识库的交互画像——用到哪些知识（使用情况）· 哪些知识想找但没找到或任务执行模型表达不确定（盲区）。'