cardbuddy 0.13.3 → 0.14.1

package/dist/vendored/skills/card-skill-trainer/scripts/diagnose_case.mjs

@@ -1,241 +1,419 @@
 #!/usr/bin/env node
 /**
- * diagnose_case.mjs — 失败案例一键诊断证据包
+ * diagnose_case.mjs — 失败案例一键诊断证据包（支持批量）
  *
  * 把「肉眼并排 → 像素分带 → 标注几何 vs 渲染盒 → schema 溯源」这条手工诊断
  * 链路产品化为单条命令。输出全部落在该轮 reports/ 目录（训练产物，不入 src）：
  *   <caseId>.side.png   设计稿|渲染 并排图（红色分隔线）
- *   终端打印            像素分带直方图、偏差元素表（dy/dx）、生成器源码行溯源、
- *                       校正器干预记录、失败类建议
+ *   终端打印            门禁未达标维度、失败类归因、掩膜覆盖、上游聚焦门、像素分带直方图、
+ *                       偏差元素表（dy/dx）、生成器源码行溯源、校正器干预记录、失败类建议
  *
  * 用法：
- *   node skills/card-skill-trainer/scripts/diagnose_case.mjs --run training/runs/r171 --case <caseId>
- *   [--dataset training/datasets/v4/train-set.sampled.jsonl]  (缺省自动扫描 datasets)
+ *   node skills/card-skill-trainer/scripts/diagnose_case.mjs --run training/runs/r262 --case <caseId>[,<caseId>...]
+ *   [--dataset training/datasets/v7/train-set.jsonl]  (缺省自动扫描 datasets)
+ *   [--out training/runs/r262/reports/diagnosis.json]  (机器可读，供多模态归因直接消费)
+ *
+ * 批量与口径说明：
+ *   - 多案例共用一套 Chrome 渲染会话与一次生成器 import（此前每例各起一套，白烧 1.5-2s/例）；
+ *   - 标注几何取自「聚焦卡」的 elements（与 run_round 评分同源）。此前读 spec.elements
+ *     （画板级），多卡画板下会把卡外元素算成偏差，产出幻影证据；
+ *   - 门禁与归因口径来自 lib/scoring.mjs，与评分/汇总/计划完全一致。
  */
 import fs from 'node:fs'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { PNG } from 'pngjs'
+import {
+  attributeFailure, evaluatePassGate, exclusionCoverage, failureSignature, MASK_REVIEW_THRESHOLD,
+} from './lib/scoring.mjs'
 
 const repoRoot = path.resolve(import.meta.dirname, '../../..')
 
+/** 绝对路径动态 import（Windows 兼容，说明见 run_round.mjs 同名 helper）。 */
+const importAbs = (target) => import(pathToFileURL(target).href)
+
 function parseArgs(argv) {
-  const out = { run: '', case: '', dataset: '' }
-  for (let index = 0; index < argv.length; index += 2) {
-    const key = argv[index].replace(/^--/, '')
-    out[key] = argv[index + 1]
+  const out = { run: '', case: '', dataset: '', out: '' }
+  const camel = (raw) => raw.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase())
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+    if (!token.startsWith('--')) continue
+    const key = camel(token.replace(/^--/, ''))
+    const next = argv[index + 1]
+    if (next === undefined || next.startsWith('--')) out[key] = true
+    else { out[key] = next; index += 1 }
   }
   return out
 }
+
 const args = parseArgs(process.argv.slice(2))
 if (!args.run || !args.case) {
-  console.error('usage: diagnose_case.mjs --run <roundDir> --case <caseId> [--dataset <jsonl>]')
+  console.error('usage: diagnose_case.mjs --run <roundDir> --case <caseId[,caseId...]> [--dataset <jsonl>] [--out <json>]')
   process.exit(1)
 }
+const caseIds = String(args.case).split(',').map((item) => item.trim()).filter(Boolean)
 const runDir = path.resolve(args.run)
 const reportDir = path.join(runDir, 'reports')
-const report = JSON.parse(fs.readFileSync(path.join(reportDir, `${args.case}.json`), 'utf8'))
-
-// —— 数据集条目定位（spec 路径 + cardIndex）——
-function findDatasetEntry() {
-  const candidates = args.dataset
-    ? [path.resolve(args.dataset)]
-    : (() => {
-        const rootDir = path.join(repoRoot, 'training/datasets')
-        const files = []
-        for (const ver of fs.readdirSync(rootDir)) {
-          const dir = path.join(rootDir, ver)
-          if (!fs.statSync(dir).isDirectory()) continue
-          for (const f of fs.readdirSync(dir)) {
-            if (f.endsWith('.jsonl')) files.push(path.join(dir, f))
-          }
-        }
-        return files
-      })()
-  for (const file of candidates) {
-    const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean)
-    for (const line of lines) {
-      const item = JSON.parse(line)
-      if (item.caseId === args.case) return { entry: item, datasetFile: file }
+
+// 渲染器/切图落点在 import 时就被 lib/paths.mjs 固化，必须先设环境变量再动态 import
+process.env.DSL_CARD_CARDS_DIR = path.join(runDir, 'cards')
+process.env.DSL_CARD_SLICES_DIR = path.join(runDir, 'slices')
+process.env.SCHEMA_PROV = '1'
+
+// —— 数据集索引（一次扫描，多案例复用）——
+function buildDatasetIndex() {
+  const files = []
+  if (args.dataset) files.push(path.resolve(String(args.dataset)))
+  else {
+    const rootDir = path.join(repoRoot, 'training/datasets')
+    for (const version of fs.existsSync(rootDir) ? fs.readdirSync(rootDir) : []) {
+      const dir = path.join(rootDir, version)
+      if (!fs.statSync(dir).isDirectory()) continue
+      for (const file of fs.readdirSync(dir)) if (file.endsWith('.jsonl')) files.push(path.join(dir, file))
     }
   }
-  throw new Error(`caseId ${args.case} not found in ${args.dataset || 'training/datasets/*'}`)
-}
-const { entry } = findDatasetEntry()
-const spec = JSON.parse(fs.readFileSync(entry.input.specJson, 'utf8'))
-const cardMeta = (spec.cards || [])[entry.cardIndex ?? 0] || (spec.cards || [])[0]
-const cardRect = cardMeta?.rect || { x: 0, y: 0, width: 343, height: 200 }
-
-// —— 1. 并排图（持久化到 reports/）——
-const designPng = PNG.sync.read(fs.readFileSync(path.join(reportDir, `${args.case}.design.png`)))
-const renderPng = PNG.sync.read(fs.readFileSync(path.join(reportDir, `${args.case}.render.png`)))
-const sideW = designPng.width + renderPng.width + 8
-const sideH = Math.max(designPng.height, renderPng.height)
-const side = new PNG({ width: sideW, height: sideH, colorType: 2 })
-for (let y = 0; y < sideH; y++) {
-  for (let x = 0; x < sideW; x++) {
-    const di = (y * sideW + x) * 4
-    side.data[di] = 255; side.data[di + 1] = 0; side.data[di + 2] = 0; side.data[di + 3] = 255
-  }
-}
-const blit = (src, xOff) => {
-  for (let y = 0; y < src.height; y++) {
-    for (let x = 0; x < src.width; x++) {
-      const si = (y * src.width + x) * 4
-      const di = (y * sideW + x + xOff) * 4
-      side.data[di] = src.data[si]; side.data[di + 1] = src.data[si + 1]
-      side.data[di + 2] = src.data[si + 2]; side.data[di + 3] = 255
+  const index = new Map()
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue
+    for (const line of fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)) {
+      try {
+        const item = JSON.parse(line)
+        if (item.caseId && !index.has(item.caseId)) index.set(item.caseId, { entry: item, datasetFile: file })
+      } catch {}
     }
   }
+  return index
 }
-blit(designPng, 0); blit(renderPng, designPng.width + 8)
-const sidePath = path.join(reportDir, `${args.case}.side.png`)
-fs.writeFileSync(sidePath, PNG.sync.write(side))
-
-// —— 2. 像素分带直方图（含豁免区掩码）——
-const w = Math.min(designPng.width, renderPng.width)
-const h = Math.min(designPng.height, renderPng.height)
-const mask = new Uint8Array(w * h)
-for (const rc of report.pixelExclusions || []) {
-  const x0 = Math.floor((rc.x ?? 0) * w), y0 = Math.floor((rc.y ?? 0) * h)
-  const x1 = Math.min(w, Math.ceil(((rc.x ?? 0) + (rc.width ?? 0)) * w))
-  const y1 = Math.min(h, Math.ceil(((rc.y ?? 0) + (rc.height ?? 0)) * h))
-  for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) mask[y * w + x] = 1
+const datasetIndex = buildDatasetIndex()
+
+const norm = (value) => String(value || '').replace(/\s+/g, '')
+const num = (value, digits = 4) => typeof value === 'number' && Number.isFinite(value) ? value.toFixed(digits) : 'N/A'
+
+function readPngIfExists(file) {
+  try { return fs.existsSync(file) ? PNG.sync.read(fs.readFileSync(file)) : null } catch { return null }
 }
-const BANDS = 20
-const bandDiff = new Array(BANDS).fill(0)
-const bandTotal = new Array(BANDS).fill(0)
-let totalDiff = 0
-let totalCount = 0
-for (let y = 0; y < h; y++) {
-  const band = Math.min(BANDS - 1, Math.floor((y / h) * BANDS))
-  for (let x = 0; x < w; x++) {
-    if (mask[y * w + x]) continue
-    const i = (y * designPng.width + x) * 4
-    const j = (y * renderPng.width + x) * 4
-    const diff = Math.abs(designPng.data[i] - renderPng.data[j]) > 15
-      || Math.abs(designPng.data[i + 1] - renderPng.data[j + 1]) > 15
-      || Math.abs(designPng.data[i + 2] - renderPng.data[j + 2]) > 15
-    if (diff) { bandDiff[band]++; totalDiff++ }
-    bandTotal[band]++; totalCount++
+
+function buildSideImage(designPng, renderPng, sidePath) {
+  const sideW = designPng.width + renderPng.width + 8
+  const sideH = Math.max(designPng.height, renderPng.height)
+  const side = new PNG({ width: sideW, height: sideH, colorType: 2 })
+  for (let y = 0; y < sideH; y++) {
+    for (let x = 0; x < sideW; x++) {
+      const di = (y * sideW + x) * 4
+      side.data[di] = 255; side.data[di + 1] = 0; side.data[di + 2] = 0; side.data[di + 3] = 255
+    }
+  }
+  const blit = (src, xOff) => {
+    for (let y = 0; y < src.height; y++) {
+      for (let x = 0; x < src.width; x++) {
+        const si = (y * src.width + x) * 4
+        const di = (y * sideW + x + xOff) * 4
+        side.data[di] = src.data[si]; side.data[di + 1] = src.data[si + 1]
+        side.data[di + 2] = src.data[si + 2]; side.data[di + 3] = 255
+      }
+    }
   }
+  blit(designPng, 0); blit(renderPng, designPng.width + 8)
+  fs.writeFileSync(sidePath, PNG.sync.write(side))
+  return sidePath
 }
-const bandPct = bandDiff.map((c, i) => (bandTotal[i] ? c / bandTotal[i] : 0))
-const hotBands = bandPct.map((p2, i) => ({ band: i, y: Math.round((i / BANDS) * h), pct: p2 }))
-  .filter((b) => b.pct >= 0.05).sort((a, b) => b.pct - a.pct)
 
-// —— 3. 标注几何 vs 渲染盒（文本元素，按 |dy| 排序）——
-process.env.DSL_CARD_CARDS_DIR = path.join(runDir, 'cards')
-process.env.DSL_CARD_SLICES_DIR = path.join(runDir, 'slices')
-const { createRenderSession } = await import(repoRoot + '/skills/dsl-card-generator/scripts/render_card.mjs')
-const session = await createRenderSession({ cardsRoot: path.join(runDir, 'cards') })
-const scaleX = designPng.width / (cardRect.width || 343)
-const cardId = report.cardId || `${path.basename(runDir)}__${args.case}`
-const rendered = await session.render({ id: cardId, width: cardRect.width || 343, captureHeight: Math.ceil(h / scaleX), format: 'png', captureElements: true })
-await session.close()
-if (!rendered.ok) { console.error('re-render failed:', rendered.error); process.exit(1) }
-const renderTexts = (rendered.elementBoxes || [])
-  .filter((b) => b.text && ['Text', 'Input', 'Button'].includes(b.cls))
-const specTexts = (spec.elements || [])
-  .filter((el) => el.type === 'text' && (el.text || '').trim())
-  .map((el) => ({
-    text: String(el.text).trim().replace(/\s+/g, ''),
-    x: (el.rect?.x || 0) - (cardRect.x || 0),
-    y: (el.rect?.y || 0) - (cardRect.y || 0),
-    w: el.rect?.width || 0,
-    h: el.rect?.height || 0,
-    fs: el.textStyle?.fontSize || 14,
-    lineHeight: el.textStyle?.lineHeight ?? null,
-  }))
-const norm = (s) => String(s || '').replace(/\s+/g, '')
-const usedSpec = new Set()
-const deviations = []
-for (const rt of renderTexts) {
-  const key = norm(rt.text)
-  if (!key) continue
-  let best = null
-  let bestScore = 0
-  for (let i = 0; i < specTexts.length; i++) {
-    if (usedSpec.has(i)) continue
-    const st = specTexts[i]
-    let score = 0
-    if (st.text === key) score = 1
-    else if (st.text.includes(key) || key.includes(st.text)) score = 0.9
-    if (score > bestScore) { bestScore = score; best = { ...st, idx: i } }
+function pixelBands(designPng, renderPng, exclusions) {
+  const w = Math.min(designPng.width, renderPng.width)
+  const h = Math.min(designPng.height, renderPng.height)
+  const mask = new Uint8Array(w * h)
+  for (const rc of exclusions || []) {
+    const x0 = Math.floor((rc.x ?? 0) * w), y0 = Math.floor((rc.y ?? 0) * h)
+    const x1 = Math.min(w, Math.ceil(((rc.x ?? 0) + (rc.width ?? 0)) * w))
+    const y1 = Math.min(h, Math.ceil(((rc.y ?? 0) + (rc.height ?? 0)) * h))
+    for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) mask[y * w + x] = 1
   }
-  if (!best || bestScore < 0.9) continue
-  usedSpec.add(best.idx)
-  deviations.push({
-    text: key.slice(0, 18),
-    dy: +(rt.y - best.y).toFixed(1),
-    dx: +(rt.x - best.x).toFixed(1),
-    dw: +((rt.w || 0) - best.w).toFixed(1),
-    dh: +((rt.h || 0) - best.h).toFixed(1),
-    render: { x: rt.x, y: rt.y, w: rt.w, h: rt.h },
-    spec: { x: best.x, y: best.y, w: best.w, h: best.h, fs: best.fs, lineHeight: best.lineHeight },
-    cid: rt.cid,
-  })
-}
-deviations.sort((a, b) => (Math.abs(b.dy) + Math.abs(b.dx)) - (Math.abs(a.dy) + Math.abs(a.dx)))
-
-// —— 4. 生成器源码行溯源（SCHEMA_PROV 重生成，仅偏差 TopN）——
-let provHits = []
-try {
-  process.env.SCHEMA_PROV = '1'
-  const { generate } = await import(repoRoot + '/skills/dsl-card-generator/scripts/spec_to_schema_v3.mjs')
-  const out = generate(spec, { id: 'diagnose', name: 'diagnose', cardIndex: entry.cardIndex ?? 0, designImage: entry.input.designImage })
-  const provByCid = new Map()
-  const textByCid = new Map()
-  const walkProv = (node) => {
-    if (!node) return
-    if (node.componentId) {
-      if (node.__prov) provByCid.set(node.componentId, node.__prov)
-      const prop = (node.properties || []).find((pp) => pp.itemKey === 'value')
-      const val = norm(prop?.itemDefaultValue || prop?.itemValue)
-      if (val && !textByCid.has(node.componentId)) textByCid.set(node.componentId, val)
+  const BANDS = 20
+  const bandDiff = new Array(BANDS).fill(0)
+  const bandTotal = new Array(BANDS).fill(0)
+  let totalDiff = 0
+  let totalCount = 0
+  for (let y = 0; y < h; y++) {
+    const band = Math.min(BANDS - 1, Math.floor((y / h) * BANDS))
+    for (let x = 0; x < w; x++) {
+      if (mask[y * w + x]) continue
+      const i = (y * designPng.width + x) * 4
+      const j = (y * renderPng.width + x) * 4
+      const diff = Math.abs(designPng.data[i] - renderPng.data[j]) > 15
+        || Math.abs(designPng.data[i + 1] - renderPng.data[j + 1]) > 15
+        || Math.abs(designPng.data[i + 2] - renderPng.data[j + 2]) > 15
+      if (diff) { bandDiff[band]++; totalDiff++ }
+      bandTotal[band]++; totalCount++
     }
-    for (const c of node.components || []) walkProv(c)
-    for (const sl of node.slots || []) for (const c of sl.components || []) walkProv(c)
   }
-  walkProv(out.schema.view)
-  const topCids = [...new Set(deviations.slice(0, 6).map((d) => d.cid).filter(Boolean))]
-  provHits = topCids.map((cid) => ({ cid, prov: provByCid.get(cid) || '(未登记/由组装层创建)', text: (textByCid.get(cid) || '').slice(0, 18) }))
-} catch (e) {
-  provHits = [{ error: String(e.message || e) }]
+  const bandPct = bandDiff.map((c, i) => (bandTotal[i] ? c / bandTotal[i] : 0))
+  const hotBands = bandPct.map((pct, i) => ({ band: i, y: Math.round((i / BANDS) * h), pct }))
+    .filter((b) => b.pct >= 0.05).sort((a, b) => b.pct - a.pct)
+  return { hotBands, diffRatio: totalCount ? totalDiff / totalCount : null }
 }
 
-// —— 5. 汇总输出 ——
-const px = report.pixel || {}
-const fid = report.fidelity || {}
-console.log('═══════════════════════════════════════════════════════════')
-console.log(`诊断 ${args.case} | ${report.artboardName || ''}`)
-console.log(`side-by-side: ${path.relative(repoRoot, sidePath)}`)
-console.log(`passed=${report.passed}  pix=${px.ratio?.toFixed(4)} struct=${px.structure?.toFixed(4)} dy=${px.bestAlignDy} fid=${fid.overall?.toFixed(4)} pos=${fid.position?.toFixed(4)} comp=${fid.components?.toFixed(4)}`)
-if (report.layoutCorrections?.length) {
-  console.log(`校正器干预 ${report.layoutCorrections.length} 处（守卫通过）:`, JSON.stringify(report.layoutCorrections.slice(0, 5)))
-}
-if (report.correctorRejected) {
-  console.log(`校正器干预被守卫拒绝（${report.correctorRejected.reason}）:`, JSON.stringify(report.correctorRejected.adjustments?.slice(0, 5) || []))
-}
-console.log('── 像素热区 (band≥5%) ──')
-for (const b of hotBands) {
-  console.log(`  y≈${String(b.y).padStart(4)}  ${(b.pct * 100).toFixed(1)}%  ${'#'.repeat(Math.round(b.pct * 50))}`)
-}
-console.log('── 元素偏差 Top10 (|dy|+|dx| 降序, pt@343宽) ──')
-for (const d of deviations.slice(0, 10)) {
-  console.log(`  dy=${String(d.dy).padStart(5)} dx=${String(d.dx).padStart(5)} dw=${String(d.dw).padStart(5)} dh=${String(d.dh).padStart(5)}  '${d.text}'  spec[y=${d.spec.y} h=${d.spec.h} fs=${d.spec.fs} lh=${d.spec.lineHeight ?? '-'}] render[y=${d.render.y} h=${d.render.h}]`)
+function pairDeviations(specTexts, renderTexts) {
+  const usedSpec = new Set()
+  const deviations = []
+  for (const rt of renderTexts) {
+    const key = norm(rt.text)
+    if (!key) continue
+    let best = null
+    let bestScore = 0
+    for (let i = 0; i < specTexts.length; i++) {
+      if (usedSpec.has(i)) continue
+      const st = specTexts[i]
+      let score = 0
+      if (st.text === key) score = 1
+      else if (st.text.includes(key) || key.includes(st.text)) score = 0.9
+      if (score > bestScore) { bestScore = score; best = { ...st, idx: i } }
+    }
+    if (!best || bestScore < 0.9) continue
+    usedSpec.add(best.idx)
+    deviations.push({
+      text: key.slice(0, 18),
+      dy: +(rt.y - best.y).toFixed(1),
+      dx: +(rt.x - best.x).toFixed(1),
+      dw: +((rt.w || 0) - best.w).toFixed(1),
+      dh: +((rt.h || 0) - best.h).toFixed(1),
+      render: { x: rt.x, y: rt.y, w: rt.w, h: rt.h },
+      spec: { x: best.x, y: best.y, w: best.w, h: best.h, fs: best.fs, lineHeight: best.lineHeight },
+      cid: rt.cid,
+    })
+  }
+  deviations.sort((a, b) => (Math.abs(b.dy) + Math.abs(b.dx)) - (Math.abs(a.dy) + Math.abs(a.dx)))
+  return deviations
 }
-console.log('── 偏差节点 → 生成器源码行 ──')
-for (const phit of provHits) {
-  if (phit.error) { console.log('  溯源失败:', phit.error); continue }
-  console.log(`  ${phit.cid} '${phit.text}' → ${phit.prov}`)
+
+async function main() {
+  const results = []
+  let session = null
+  let generate = null
+  const ensureSession = async () => {
+    if (session) return session
+    const { createRenderSession } = await importAbs(
+      path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'render_card.mjs'))
+    session = await createRenderSession({ cardsRoot: path.join(runDir, 'cards') })
+    return session
+  }
+  const ensureGenerator = async () => {
+    if (generate) return generate
+    const mod = await importAbs(
+      path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'spec_to_schema_v3.mjs'))
+    generate = mod.generate
+    return generate
+  }
+
+  for (const caseId of caseIds) {
+    const result = { caseId }
+    try {
+      const reportPath = path.join(reportDir, `${caseId}.json`)
+      if (!fs.existsSync(reportPath)) throw new Error(`报告不存在：${reportPath}`)
+      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'))
+      const found = datasetIndex.get(caseId)
+      if (!found) throw new Error(`caseId ${caseId} 不在 ${args.dataset || 'training/datasets/*'} 里`)
+      const { entry } = found
+      const spec = JSON.parse(fs.readFileSync(entry.input.specJson, 'utf8'))
+      const cardMeta = (spec.cards || [])[entry.cardIndex ?? 0] || (spec.cards || [])[0] || {}
+      const cardRect = cardMeta.rect || { x: 0, y: 0, width: 343, height: 200 }
+      // 与评分同源：只用聚焦卡自己的元素，避免把画板上其它卡的文本算成本卡偏差
+      const cardElements = cardMeta.elements || spec.elements || []
+
+      // —— 门禁与归因（口径来自 lib/scoring.mjs）——
+      const gate = Array.isArray(report.gateFailures) && report.gateFailures.length
+        ? report.gateFailures : evaluatePassGate(report).failures
+      const attribution = report.failureClass
+        ? { failureClass: report.failureClass, reason: report.failureReason || '' }
+        : attributeFailure({ ...report, passed: false })
+      const coverage = report.exclusionCoverage || exclusionCoverage(report.pixelExclusions || [])
+
+      // —— 1. 并排图（设计稿 / 渲染截图任一缺失则跳过，不再整条命令失败）——
+      const designPng = readPngIfExists(path.join(reportDir, `${caseId}.design.png`))
+      const renderPng = readPngIfExists(path.join(reportDir, `${caseId}.render.png`))
+      let sidePath = null
+      if (designPng && renderPng) {
+        sidePath = buildSideImage(designPng, renderPng, path.join(reportDir, `${caseId}.side.png`))
+      }
+
+      // —— 2. 像素分带直方图（含掩膜区剔除）——
+      const bands = designPng && renderPng
+        ? pixelBands(designPng, renderPng, report.pixelExclusions)
+        : { hotBands: [], diffRatio: null }
+
+      // —— 3. 标注几何 vs 渲染盒（重渲一次拿 elementBoxes）——
+      const cardId = report.cardId || `${path.basename(runDir)}__${caseId}`
+      const captureHeight = designPng && renderPng
+        ? Math.ceil(Math.min(designPng.height, renderPng.height) / (designPng.width / (cardRect.width || 343)))
+        : Math.ceil(cardRect.height || 400)
+      let deviations = []
+      let renderError = null
+      try {
+        const activeSession = await ensureSession()
+        const rendered = await activeSession.render({
+          id: cardId, width: cardRect.width || 343, captureHeight, format: 'png', captureElements: true,
+        })
+        if (!rendered.ok) renderError = String(rendered.error || rendered.message || 'render failed')
+        else {
+          const renderTexts = (rendered.elementBoxes || [])
+            .filter((b) => b.text && ['Text', 'Input', 'Button'].includes(b.cls))
+          const specTexts = cardElements
+            .filter((el) => el.type === 'text' && String(el.text || '').trim())
+            .map((el) => ({
+              text: norm(el.text),
+              x: (el.rect?.x || 0) - (cardRect.x || 0),
+              y: (el.rect?.y || 0) - (cardRect.y || 0),
+              w: el.rect?.width || 0,
+              h: el.rect?.height || 0,
+              fs: el.textStyle?.fontSize || 14,
+              lineHeight: el.textStyle?.lineHeight ?? null,
+            }))
+          deviations = pairDeviations(specTexts, renderTexts)
+        }
+      } catch (error) {
+        renderError = String(error?.message || error)
+      }
+
+      // —— 4. 生成器源码行溯源（SCHEMA_PROV 重生成，仅偏差 TopN）——
+      let provHits = []
+      try {
+        const generateFn = await ensureGenerator()
+        const out = generateFn(spec, {
+          id: 'diagnose', name: 'diagnose', cardIndex: entry.cardIndex ?? 0, designImage: entry.input.designImage,
+        })
+        const provByCid = new Map()
+        const textByCid = new Map()
+        const walkProv = (node) => {
+          if (!node) return
+          if (node.componentId) {
+            if (node.__prov) provByCid.set(node.componentId, node.__prov)
+            const prop = (node.properties || []).find((pp) => pp.itemKey === 'value')
+            const val = norm(prop?.itemDefaultValue || prop?.itemValue)
+            if (val && !textByCid.has(node.componentId)) textByCid.set(node.componentId, val)
+          }
+          for (const c of node.components || []) walkProv(c)
+          for (const sl of node.slots || []) for (const c of sl.components || []) walkProv(c)
+        }
+        walkProv(out.schema.view)
+        const topCids = [...new Set(deviations.slice(0, 6).map((d) => d.cid).filter(Boolean))]
+        provHits = topCids.map((cid) => ({
+          cid, prov: provByCid.get(cid) || '(未登记/由组装层创建)', text: (textByCid.get(cid) || '').slice(0, 18),
+        }))
+      } catch (e) {
+        provHits = [{ error: String(e.message || e) }]
+      }
+
+      // —— 5. 失败类建议 ——
+      const px = report.pixel || {}
+      const fid = report.fidelity || {}
+      const hints = []
+      if (attribution) hints.push(`归因 ${attribution.failureClass}：${attribution.reason}`)
+      if (px.bestAlignDy && Math.abs(px.bestAlignDy) >= 4) hints.push(`全局纵向偏移 dy=${px.bestAlignDy}：查行高/行距累积（Input 高度、行距标注优先、分割线渲染盒高）`)
+      if (bands.hotBands.length && bands.hotBands[0].pct >= 0.2) hints.push(`单带高热 (${(bands.hotBands[0].pct * 100).toFixed(0)}%@y≈${bands.hotBands[0].y})：查该区域语义块（换行折点/缺组件/结构错配）`)
+      if ((fid.components ?? 1) < 0.9) hints.push(`组件计数缺失 comp=${num(fid.components, 2)}：查语义消费（媒体未渲染/文本被吞/重复消费）`)
+      if ((report.duplication?.overall ?? 1) < 0.95) {
+        hints.push(`重影：查同源按钮/文本双路径渲染（${(report.duplication?.offenders || []).map((o) => `「${o.text}」x${o.rendered}/${o.annotated}`).join(' ')}）`)
+      }
+      if ((coverage.total ?? 0) >= MASK_REVIEW_THRESHOLD) {
+        hints.push(`掩膜覆盖 ${(coverage.total * 100).toFixed(1)}% ≥ ${(MASK_REVIEW_THRESHOLD * 100).toFixed(0)}%：得分不代表整卡，必须看图复核`)
+      }
+      const bigDy = deviations.filter((d) => Math.abs(d.dy) >= 3)
+      if (bigDy.length >= 3) hints.push(`${bigDy.length} 个文本 |dy|≥3：纵向节奏问题（行距/padding 体系），非单点`)
+      if (!hints.length) hints.push('像素差异弥散且量级低：多为 1-2px 抗锯齿/字体度量差异，接近噪声底')
+
+      // —— 6. 输出 ——
+      console.log('═══════════════════════════════════════════════════════════')
+      console.log(`诊断 ${caseId} | ${report.artboardName || ''}`)
+      if (sidePath) console.log(`side-by-side: ${path.relative(repoRoot, sidePath)}`)
+      else console.log('side-by-side: (缺 design.png / render.png，已跳过并排图与像素分带)')
+      console.log(`passed=${report.passed}  pix=${num(px.ratio)} struct=${num(px.structure)} dy=${px.bestAlignDy ?? 'N/A'} fid=${num(fid.overall)} pos=${num(fid.position)} comp=${num(fid.components)}`)
+      console.log('── 门禁未达标维度（缺口降序）──')
+      if (!gate.length) console.log('  （全部门通过）')
+      for (const failure of gate) {
+        console.log(`  ${failure.key.padEnd(13)} ${failure.label}=${num(failure.actual)}  门 ${failure.op} ${failure.target}  缺口 ${(failure.deficit * 100).toFixed(1)}%`)
+      }
+      console.log(`  主签名: ${report.failureSignature || failureSignature(report) || '（无）'}`)
+      if (coverage.total != null) {
+        const byReason = Object.entries(coverage.byReason || {}).map(([reason, value]) => `${reason} ${(value * 100).toFixed(1)}%`).join(' / ')
+        console.log(`── 掩膜覆盖 ${(coverage.total * 100).toFixed(1)}%${byReason ? `（${byReason}）` : ''} ──`)
+      }
+      const upstream = report.upstream
+      if (upstream) {
+        const defects = upstream.annotationDefects || []
+        console.log(`── 上游聚焦门 passed=${upstream.passed} 标注完整性=${num(upstream.annotationCompleteness, 3)} 文本保留=${num(upstream.textRetention, 3)} 结构聚焦=${upstream.structuralFocus} 标注缺陷=${defects.length}${defects.length ? `（${[...new Set(defects.map((d) => d.type))].join(',')}）` : ''} ──`)
+      }
+      if (report.layoutCorrections?.length) {
+        console.log(`校正器干预 ${report.layoutCorrections.length} 处（守卫通过）:`, JSON.stringify(report.layoutCorrections.slice(0, 5)))
+      }
+      if (report.correctorRejected) {
+        console.log(`校正器干预被守卫拒绝（${report.correctorRejected.reason}）:`, JSON.stringify(report.correctorRejected.adjustments?.slice(0, 5) || []))
+      }
+      console.log('── 像素热区 (band≥5%) ──')
+      if (!bands.hotBands.length) console.log('  （无高热区或截图缺失）')
+      for (const b of bands.hotBands) {
+        console.log(`  y≈${String(b.y).padStart(4)}  ${(b.pct * 100).toFixed(1)}%  ${'#'.repeat(Math.round(b.pct * 50))}`)
+      }
+      console.log('── 元素偏差 Top10 (|dy|+|dx| 降序, pt@卡宽) ──')
+      if (renderError) console.log(`  重渲失败：${renderError}`)
+      for (const d of deviations.slice(0, 10)) {
+        console.log(`  dy=${String(d.dy).padStart(5)} dx=${String(d.dx).padStart(5)} dw=${String(d.dw).padStart(5)} dh=${String(d.dh).padStart(5)}  '${d.text}'  spec[y=${d.spec.y} h=${d.spec.h} fs=${d.spec.fs} lh=${d.spec.lineHeight ?? '-'}] render[y=${d.render.y} h=${d.render.h}]`)
+      }
+      console.log('── 偏差节点 → 生成器源码行 ──')
+      for (const phit of provHits) {
+        if (phit.error) { console.log('  溯源失败:', phit.error); continue }
+        console.log(`  ${phit.cid} '${phit.text}' → ${phit.prov}`)
+      }
+      console.log('── 失败类建议 ──')
+      for (const hint of hints) console.log('  •', hint)
+
+      results.push({
+        ...result,
+        artboardName: report.artboardName || null,
+        passed: !!report.passed,
+        signature: report.failureSignature || failureSignature(report) || null,
+        failureClass: attribution?.failureClass || null,
+        failureReason: attribution?.reason || null,
+        gateFailures: gate,
+        exclusionCoverage: coverage,
+        upstream: upstream ? {
+          passed: upstream.passed,
+          annotationCompleteness: upstream.annotationCompleteness,
+          textRetention: upstream.textRetention,
+          structuralFocus: upstream.structuralFocus,
+          annotationDefects: (upstream.annotationDefects || []).length,
+        } : null,
+        metrics: {
+          fidelity: fid.overall ?? null, pixel: px.ratio ?? null, structure: px.structure ?? null,
+          position: fid.position ?? null, components: fid.components ?? null,
+          duplication: report.duplication?.overall ?? null, bestAlignDy: px.bestAlignDy ?? null,
+        },
+        sideImage: sidePath ? path.relative(repoRoot, sidePath).split(path.sep).join('/') : null,
+        hotBands: bands.hotBands.slice(0, 8),
+        deviations: deviations.slice(0, 10),
+        provenance: provHits,
+        layoutCorrections: report.layoutCorrections || [],
+        correctorRejected: report.correctorRejected || null,
+        hints,
+      })
+    } catch (error) {
+      console.error(`[diagnose] ${caseId} 失败：${String(error?.message || error)}`)
+      results.push({ ...result, error: String(error?.message || error) })
+    }
+  }
+
+  try { await session?.close() } catch {}
+
+  if (args.out) {
+    const outPath = path.resolve(String(args.out))
+    fs.mkdirSync(path.dirname(outPath), { recursive: true })
+    fs.writeFileSync(outPath, JSON.stringify({ run: path.basename(runDir), results }, null, 2) + '\n')
+    console.log('')
+    console.log(`诊断 JSON: ${path.relative(repoRoot, outPath).split(path.sep).join('/')}`)
+  }
+  const failed = results.filter((item) => item.error)
+  if (failed.length && failed.length === results.length) process.exit(1)
 }
-console.log('── 失败类建议 ──')
-const hints = []
-if (px.bestAlignDy && Math.abs(px.bestAlignDy) >= 4) hints.push(`全局纵向偏移 dy=${px.bestAlignDy}：查行高/行距累积（Input 高度、行距标注优先、分割线渲染盒高）`)
-if (hotBands.length && hotBands[0].pct >= 0.2) hints.push(`单带高热 (${(hotBands[0].pct * 100).toFixed(0)}%@y≈${hotBands[0].y})：查该区域语义块（换行折点/缺组件/结构错配）`)
-if ((fid.components ?? 1) < 0.9) hints.push(`组件计数缺失 comp=${fid.components?.toFixed(2)}：查语义消费（媒体未渲染/文本被吞/重复消费）`)
-if ((report.duplication?.overall ?? 1) < 0.95) hints.push('重影：查同源按钮/文本双路径渲染')
-const bigDy = deviations.filter((d) => Math.abs(d.dy) >= 3)
-if (bigDy.length >= 3) hints.push(`${bigDy.length} 个文本 |dy|≥3：纵向节奏问题（行距/padding 体系），非单点`)
-if (!hints.length) hints.push('像素差异弥散且量级低：多为 1-2px 抗锯齿/字体度量差异，接近噪声底')
-for (const hint of hints) console.log('  •', hint)
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})