cardbuddy 0.13.3 → 0.14.1

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

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 // 轮间对比：PASS→FAIL 回归检测、FAIL→PASS 修复确认、指标 delta。
 // 用途：提交/落盘前门禁（存在回归时 exit 1）、训练报告中的轮次演进证据。
-// 用法：node round_diff.mjs --from training/runs/r170 --to training/runs/r171 [--allow-regressions]
+// 用法：node round_diff.mjs --from training/runs/r170 --to training/runs/r171 [--allow-regressions] [--json out.json]
 //       --from/--to 也接受压缩锚点文件（training/anchors/r176.json），干净克隆无 training/runs 时
-//       仍可与冻结锚点对账：node round_diff.mjs --from training/anchors/r176.json --to training/runs/r202
+//       仍可与冻结锚点对账：node round_diff.mjs --from training/anchors/r176.json --to training/runs/r262
+// 读取与对比口径统一走 lib/runs.mjs（score_round / plan_next_round 同源）。
 import fs from 'node:fs'
 import path from 'node:path'
+import { compareRounds, loadRunReports, reportsDirOf } from './lib/runs.mjs'
 
 function parseArgs(argv) {
-  const out = { from: '', to: '', allowRegressions: false }
+  const out = { from: '', to: '', allowRegressions: false, json: '' }
   const camel = (raw) => raw.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase())
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index]
@@ -21,113 +23,92 @@ function parseArgs(argv) {
   return out
 }
 
-function loadReports(runDir) {
-  const resolved = path.resolve(runDir)
-  if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
-    const anchor = JSON.parse(fs.readFileSync(resolved, 'utf8'))
-    const list = Array.isArray(anchor.cases) ? anchor.cases : Object.values(anchor.cases || {})
-    const map = new Map()
-    for (const report of list) if (report && report.caseId) map.set(report.caseId, report)
-    if (!map.size) throw new Error(`No cases in anchor file ${resolved}`)
-    return map
-  }
-  const reportDir = path.join(resolved, 'reports')
-  if (!fs.existsSync(reportDir)) throw new Error(`No reports at ${reportDir}`)
-  const map = new Map()
-  for (const file of fs.readdirSync(reportDir)) {
-    if (!file.endsWith('.json')) continue
-    if (/summary|skipped|review|semantic/.test(file)) continue
-    const report = JSON.parse(fs.readFileSync(path.join(reportDir, file), 'utf8'))
-    if (report.caseId) map.set(report.caseId, report)
-  }
-  return map
-}
-
 const args = parseArgs(process.argv.slice(2))
 if (!args.from || !args.to) throw new Error('--from and --to are required')
 
-const fromReports = loadReports(args.from)
-const toReports = loadReports(args.to)
+const fromReports = loadRunReports(args.from)
+const toReports = loadRunReports(args.to)
+const comparison = compareRounds(fromReports, toReports)
 
-const metric = (report, selector) => selector(report) ?? null
-const selectors = {
-  fidelity: (r) => r.fidelity?.overall,
-  pixel: (r) => r.pixel?.ratio,
-  position: (r) => r.fidelity?.position,
-  structure: (r) => r.pixel?.structure,
-}
-const avg = (values) => {
-  const nums = values.filter((v) => typeof v === 'number')
-  return nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null
-}
-const fmt = (v, pct = true) => v == null ? 'N/A' : pct ? (v * 100).toFixed(1) + '%' : v.toFixed(2)
+const pct = (value) => value == null ? 'N/A' : `${(value * 100).toFixed(1)}%`
+const pp = (value) => value == null ? 'N/A' : `${value > 0 ? '+' : ''}${(value * 100).toFixed(1)}pp`
+const deltaOf = (before, after) =>
+  typeof before === 'number' && typeof after === 'number' ? after - before : null
 
-const fixed = []       // fail -> pass
-const regressed = []   // pass -> fail
-const stillFailing = []
-const added = []
-const removed = []
-const metricDeltas = []
+console.log(`══ 轮间对比 ${path.basename(String(args.from))} → ${path.basename(String(args.to))} ══`)
+console.log(`案例: ${comparison.from.total} → ${comparison.to.total}（新增 ${comparison.added.length} / 移除 ${comparison.removed.length} / 共享 ${comparison.sharedCount}）`)
+console.log('')
+console.log('── 指标 delta（均值）──')
+console.log(`  passRate:   ${pct(comparison.from.passRate)} → ${pct(comparison.to.passRate)}`)
+for (const key of ['fidelity', 'pixel', 'position', 'structure', 'components']) {
+  const before = comparison.from[key]
+  const after = comparison.to[key]
+  console.log(`  ${key.padEnd(10)} ${pct(before)} → ${pct(after)}  (${pp(deltaOf(before, after))})`)
+}
+console.log('')
+console.log('── 状态迁移 ──')
+console.log(`  修复 fail→pass: ${comparison.fixed.length}`)
+for (const item of comparison.fixed) console.log(`    + ${item.caseId} ${item.name}`)
+console.log(`  回归 pass→fail: ${comparison.regressed.length}`)
+for (const item of comparison.regressed) console.log(`    ! ${item.caseId} ${item.name}`)
+console.log(`  持续失败: ${comparison.stillFailing.length}`)
+for (const item of comparison.stillFailing.slice(0, 10)) console.log(`    - ${item.caseId} ${item.name}`)
 
-for (const [caseId, toReport] of toReports) {
-  const fromReport = fromReports.get(caseId)
-  if (!fromReport) { added.push(caseId); continue }
-  if (fromReport.passed && !toReport.passed) {
-    regressed.push({ caseId, name: toReport.name || fromReport.name || '' })
-  } else if (!fromReport.passed && toReport.passed) {
-    fixed.push({ caseId, name: toReport.name || '' })
-  } else if (!fromReport.passed && !toReport.passed) {
-    stillFailing.push({ caseId, name: toReport.name || '' })
-  }
-  const delta = {}
-  for (const [key, pick] of Object.entries(selectors)) {
-    const before = metric(fromReport, pick)
-    const after = metric(toReport, pick)
-    if (typeof before === 'number' && typeof after === 'number') delta[key] = after - before
+const worst = comparison.metricDeltas
+  .filter((item) => typeof item.delta.fidelity === 'number')
+  .sort((a, b) => a.delta.fidelity - b.delta.fidelity)
+  .slice(0, 5)
+  .filter((item) => item.delta.fidelity < -0.005)
+if (worst.length) {
+  console.log('')
+  console.log('── 还原度下滑 Top5（仍通过的也需关注）──')
+  for (const item of worst) {
+    console.log(`  ${item.caseId} fidelity ${pp(item.delta.fidelity)} pixel ${pp(item.delta.pixel ?? 0)}`)
   }
-  if (Object.keys(delta).length) metricDeltas.push({ caseId, delta })
-}
-for (const caseId of fromReports.keys()) {
-  if (!toReports.has(caseId)) removed.push(caseId)
 }
 
-const fromList = [...fromReports.values()]
-const toList = [...toReports.values()]
-console.log(`══ 轮间对比 ${path.basename(args.from)} → ${path.basename(args.to)} ══`)
-console.log(`案例: ${fromReports.size} → ${toReports.size}（新增 ${added.length} / 移除 ${removed.length}）`)
-console.log('')
-console.log('── 指标 delta（均值）──')
-console.log(`  passRate:   ${fmt(avg(fromList.map((r) => r.passed ? 1 : 0)))} → ${fmt(avg(toList.map((r) => r.passed ? 1 : 0)))}`)
-for (const [key, pick] of Object.entries(selectors)) {
-  const before = avg(fromList.map((r) => metric(r, pick)))
-  const after = avg(toList.map((r) => metric(r, pick)))
-  const sign = after != null && before != null && after > before ? '+' : ''
-  console.log(`  ${key.padEnd(9)} ${fmt(before)} → ${fmt(after)}  (${sign}${after != null && before != null ? ((after - before) * 100).toFixed(1) : 'N/A'}pp)`)
+// 均值退化清单：晋级门要求 fidelity/pixel/position/structure 均值不低于基线轮
+const degraded = []
+for (const [key, betterWhenHigher] of [['fidelity', true], ['position', true], ['structure', true], ['components', true], ['pixel', false]]) {
+  const delta = deltaOf(comparison.from[key], comparison.to[key])
+  if (delta == null) continue
+  const worse = betterWhenHigher ? delta < -1e-9 : delta > 1e-9
+  if (worse) degraded.push({ metric: key, delta: Number(delta.toFixed(5)) })
+}
+if (degraded.length) {
+  console.log('')
+  console.log('── 均值退化（晋级门「不低于锚点」不满足）──')
+  for (const item of degraded) console.log(`  ${item.metric} ${pp(item.delta)}`)
 }
-console.log('')
-console.log(`── 状态迁移 ──`)
-console.log(`  修复 fail→pass: ${fixed.length}`)
-for (const item of fixed) console.log(`    + ${item.caseId} ${item.name}`)
-console.log(`  回归 pass→fail: ${regressed.length}`)
-for (const item of regressed) console.log(`    ! ${item.caseId} ${item.name}`)
-console.log(`  持续失败: ${stillFailing.length}`)
-for (const item of stillFailing.slice(0, 10)) console.log(`    - ${item.caseId} ${item.name}`)
 
-if (metricDeltas.length) {
-  const worst = [...metricDeltas]
-    .filter((item) => typeof item.delta.fidelity === 'number')
-    .sort((a, b) => a.delta.fidelity - b.delta.fidelity)
-    .slice(0, 5)
-    .filter((item) => item.delta.fidelity < -0.005)
-  if (worst.length) {
-    console.log('')
-    console.log('── 还原度下滑 Top5（仍通过的也需关注）──')
-    for (const item of worst) console.log(`  ${item.caseId} fidelity ${(item.delta.fidelity * 100).toFixed(1)}pp pixel ${(item.delta.pixel ?? 0) >= 0 ? '+' : ''}${((item.delta.pixel ?? 0) * 100).toFixed(1)}pp`)
+// --json 支持裸开关（不带路径）：默认落进 --to 轮的 reports/，避免把产物写进仓库根目录。
+const jsonTarget = args.json === true
+  ? path.join(reportsDirOf(args.to), 'round-diff.json')
+  : (typeof args.json === 'string' && args.json ? args.json : '')
+if (jsonTarget) {
+  const payload = {
+    from: String(args.from),
+    to: String(args.to),
+    metrics: { from: comparison.from, to: comparison.to },
+    degraded,
+    fixed: comparison.fixed,
+    regressed: comparison.regressed,
+    stillFailing: comparison.stillFailing,
+    added: comparison.added,
+    removed: comparison.removed,
+    promotionBlockers: {
+      regressions: comparison.regressed.length,
+      degradedMetrics: degraded.map((item) => item.metric),
+    },
   }
+  fs.mkdirSync(path.dirname(path.resolve(jsonTarget)), { recursive: true })
+  fs.writeFileSync(path.resolve(jsonTarget), JSON.stringify(payload, null, 2) + '\n')
+  console.log('')
+  console.log(`JSON: ${path.resolve(jsonTarget)}`)
 }
 
-if (regressed.length && !args.allowRegressions) {
+if (comparison.regressed.length && !args.allowRegressions) {
   console.log('')
-  console.log(`REGRESSION: ${regressed.length} 例 PASS→FAIL，退出码 1（--allow-regressions 可豁免）`)
+  console.log(`REGRESSION: ${comparison.regressed.length} 例 PASS→FAIL，退出码 1（--allow-regressions 可豁免）`)
   process.exit(1)
 }

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

@@ -13,15 +13,22 @@ function findPython() {
 }
 import fs from 'node:fs'
 import path from 'node:path'
-import { spawnSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
 import { PNG } from 'pngjs'
 
 const repoRoot = path.resolve(import.meta.dirname, '../../..')
 
+/**
+ * 绝对路径动态 import：Windows 下裸盘符路径会被 ESM 加载器当成 `d:` 协议 URL，
+ * 抛 ERR_UNSUPPORTED_ESM_URL_SCHEME（训练轮在启动阶段就整体失败）。
+ */
+const importAbs = (target) => import(pathToFileURL(target).href)
+
 function parseArgs(argv) {
   const out = {
     dataset: '', round: '', strategy: 'v3', limit: 0, splits: 'train,dev,eval', only: '',
-    onlyFailed: '', noCorrect: false,
+    onlyFailed: '', noCorrect: false, focus: '', focusBelow: 0.85, focusLimit: 0,
+    resume: false, inherit: '', noSummary: false,
   }
   const camel = (raw) => raw.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase())
   for (let index = 0; index < argv.length; index += 1) {
@@ -144,7 +151,13 @@ async function runMechanicalAutofix(schemaPath) {
   return { repairedNodes: 0, repairs: [], autofixChanged: !autofix.error && autofixOutput.includes('修复'), autofixOutput }
 }
 
-import { imageFidelity, positionScore, textOverflowScore, duplicationScore, fidelityScore, fontMaskWiden } from './lib/scoring.mjs'
+import {
+  imageFidelity, positionScore, textOverflowScore, duplicationScore, fidelityScore, fontMaskWiden,
+  loadFontMetrics,
+  evaluatePassGate, attributeFailure, failureSignature, exclusionCoverage,
+  errorKind,
+} from './lib/scoring.mjs'
+import { loadRunReports } from './lib/runs.mjs'
 
 
 function sourceChanges() {
@@ -382,21 +395,56 @@ function expectedComponents(card) {
     if (width <= 0 || height <= 0) return 0
     return (width * height) / Math.min((ar.width || 1) * (ar.height || 1), (br.width || 1) * (br.height || 1))
   }
-  const controlShapes = (card?.elements || []).filter((element) => {
+  const qualRowShell = (element) => {
     const rect = rectOf(element)
     return element.type === 'shape'
       && (rect.width || 0) >= 80 && (rect.height || 0) >= 30 && (rect.height || 0) <= 80
       && (element.style?.radius?.borderRadius || 0) >= 10
-      && (() => {
-        const inner = (card?.elements || []).filter((child) => {
-          if (child.type !== 'text' || !(child.text || child.value)) return false
-          const childRect = rectOf(child)
-          return (childRect.x || 0) >= (rect.x || 0) && (childRect.y || 0) >= (rect.y || 0)
-            && ((childRect.x || 0) + (childRect.width || 0)) <= ((rect.x || 0) + (rect.width || 0))
-            && ((childRect.y || 0) + (childRect.height || 0)) <= ((rect.y || 0) + (rect.height || 0))
-        })
-        return inner.length > 0 && new Set(inner.map((child) => Math.round((rectOf(child).y || 0) / 18))).size <= 1
-      })()
+  }
+  // 同尺寸壳竖直重复堆叠 = 列表/入口行栈（非按钮）：按钮不会同尺寸成栈重复出现。
+  const stackedRowShells = new Set()
+  {
+    const bySize = new Map()
+    for (const element of (card?.elements || [])) {
+      if (!qualRowShell(element)) continue
+      const r = rectOf(element)
+      const key = `${Math.round(r.width || 0)}x${Math.round(r.height || 0)}`
+      if (!bySize.has(key)) bySize.set(key, [])
+      bySize.get(key).push(element)
+    }
+    for (const group of bySize.values()) {
+      if (group.length < 2) continue
+      const sorted = group.sort((a, b) => (rectOf(a).y || 0) - (rectOf(b).y || 0))
+      const gaps = sorted.slice(1).map((el, i) => (rectOf(el).y || 0)
+        - ((rectOf(sorted[i]).y || 0) + (rectOf(sorted[i]).height || 0)))
+      if (gaps.every((g) => g >= 0 && g <= 80)) sorted.forEach((el) => stackedRowShells.add(el))
+    }
+  }
+  const controlShapes = (card?.elements || []).filter((element) => {
+    const rect = rectOf(element)
+    if (!qualRowShell(element)) return false
+    const inner = (card?.elements || []).filter((child) => {
+      if (child.type !== 'text' || !(child.text || child.value)) return false
+      const childRect = rectOf(child)
+      return (childRect.x || 0) >= (rect.x || 0) && (childRect.y || 0) >= (rect.y || 0)
+        && ((childRect.x || 0) + (childRect.width || 0)) <= ((rect.x || 0) + (rect.width || 0))
+        && ((childRect.y || 0) + (childRect.height || 0)) <= ((rect.y || 0) + (rect.height || 0))
+    })
+    if (!(inner.length > 0 && new Set(inner.map((child) => Math.round((rectOf(child).y || 0) / 18))).size <= 1)) return false
+    // 左锚定单文本 + 右端小亲和件（箭头/勾选）+ 同尺寸成栈 = 导航入口行（列表行），
+    // 不是按钮/输入控件：误判会把行内文本与箭头从期望组件中剔除，组件相似度系统性低估正确渲染。
+    const leftAnchored = inner.length === 1
+      && ((rectOf(inner[0]).x || 0) - (rect.x || 0)) <= (rect.width || 0) * 0.2
+    const rightAffordance = (card?.elements || []).some((e2) => {
+      if (!['slice', 'symbol', 'shape'].includes(e2.type)) return false
+      const r2 = rectOf(e2)
+      const w = r2.width || 0
+      const h = r2.height || 0
+      if (w < 4 || w > 32 || h < 4 || h > 32) return false
+      return (r2.x || 0) + w >= (rect.x || 0) + (rect.width || 0) - 28
+        && Math.abs(((r2.y || 0) + h / 2) - ((rect.y || 0) + (rect.height || 0) / 2)) <= (rect.height || 0) / 2
+    })
+    return !(leftAnchored && rightAffordance && stackedRowShells.has(element))
   })
   const insideControl = (element) => {
     const center = centerOf(element)
@@ -596,7 +644,14 @@ async function main() {
   const cardsDir = path.join(runDir, 'cards')
   const slicesDir = path.join(runDir, 'slices')
   const reportDir = path.join(runDir, 'reports')
-  fs.rmSync(runDir, { recursive: true, force: true })
+  // --resume：保留既有轮目录续跑（渲染假死 / kill -9 之后不必整轮重来，r202 的实际痛点）；
+  // 默认仍是干净重建，避免上一轮残留报告混进本轮统计
+  if (args.resume) {
+    if (!fs.existsSync(reportDir)) throw new Error(`--resume: 既有轮目录不存在 ${runDir}`)
+    console.log(`[resume] 续跑 ${args.round}：已产出报告的案例跳过`)
+  } else {
+    fs.rmSync(runDir, { recursive: true, force: true })
+  }
   fs.mkdirSync(cardsDir, { recursive: true })
   fs.mkdirSync(reportDir, { recursive: true })
   process.env.DSL_CARD_CARDS_DIR = cardsDir
@@ -606,10 +661,10 @@ async function main() {
   if (args.strategy === 'geo') {
     console.warn('[WARN] --strategy geo 已废弃（geo 生成器已删除），回退 v3')
   }
-  const generatorFile = repoRoot + '/skills/dsl-card-generator/scripts/spec_to_schema_v3.mjs'
-  const { generate } = await import(generatorFile)
-  const { createRenderSession } = await import(repoRoot +
-    '/skills/dsl-card-generator/scripts/render_card.mjs')
+  const generatorFile = path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'spec_to_schema_v3.mjs')
+  const { generate } = await importAbs(generatorFile)
+  const { createRenderSession } = await importAbs(
+    path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'render_card.mjs'))
 
   const splits = String(args.splits).split(',').filter(Boolean)
   const allCases = readDataset(path.resolve(args.dataset), splits)
@@ -621,28 +676,54 @@ async function main() {
     return false
   })
 
-  // 增量回归：只重跑指定上轮的失败案例（修复验证快路径）；
-  // 全量防回归仍用不带该开关的整轮
-  let failedSet = null
-  if (args.onlyFailed) {
-    const prevReportsDir = path.join(path.resolve(args.onlyFailed), 'reports')
-    let failedIds = []
+  // 选样模式（互斥）：--only 手点案例 / --only-failed 上轮失败例 / --focus 上轮焦点集。
+  // 焦点集 = 失败例 + 「通过但低于 --focus-below」的刚过线样本，按还原度升序，对应 SKILL
+  // 「定向还原度迭代协议」步骤 1；此前要人工翻 summary.md 抄 caseId，低分通过例常被漏掉。
+  const modes = ['only', 'onlyFailed', 'focus'].filter((key) => args[key])
+  if (modes.length > 1) throw new Error(`--only / --only-failed / --focus 互斥（同时传入：${modes.join(', ')}）`)
+  let selectedSet = null
+  if (args.onlyFailed || args.focus) {
+    const prevRun = String(args.onlyFailed || args.focus)
+    let prevReports
     try {
-      failedIds = fs.readdirSync(prevReportsDir)
-        .filter((f) => f.endsWith('.json') && !/skipped|review|semantic|summary/.test(f))
-        .map((f) => JSON.parse(fs.readFileSync(path.join(prevReportsDir, f), 'utf8')))
-        .filter((r) => !r.passed)
-        .map((r) => r.caseId)
-    } catch (e) { throw new Error('--only-failed: cannot read ' + prevReportsDir + ': ' + e.message) }
-    failedSet = new Set(failedIds)
-    console.log(`[only-failed] ${path.basename(args.onlyFailed)} 失败 ${failedIds.length} 例，本轮增量重跑`)
+      prevReports = loadRunReports(prevRun)
+    } catch (error) {
+      throw new Error(`${args.onlyFailed ? '--only-failed' : '--focus'}: 读不到 ${prevRun}: ${error.message}`)
+    }
+    if (args.onlyFailed) {
+      selectedSet = new Set([...prevReports.values()].filter((report) => !report.passed).map((report) => report.caseId))
+      console.log(`[only-failed] ${path.basename(prevRun)} 失败 ${selectedSet.size} 例，本轮增量重跑`)
+    } else {
+      const threshold = Number(args.focusBelow) || 0.85
+      const cap = Number(args.focusLimit) || 0
+      const ranked = [...prevReports.values()]
+        .map((report) => ({
+          caseId: report.caseId,
+          fidelity: typeof report.fidelity?.overall === 'number' ? report.fidelity.overall : 0,
+          passed: !!report.passed,
+        }))
+        .filter((item) => !item.passed || item.fidelity < threshold)
+        .sort((a, b) => a.fidelity - b.fidelity || String(a.caseId).localeCompare(String(b.caseId)))
+      const picked = cap > 0 ? ranked.slice(0, cap) : ranked
+      selectedSet = new Set(picked.map((item) => item.caseId))
+      console.log(`[focus] ${path.basename(prevRun)} 焦点集 ${selectedSet.size} 例（未通过或 fidelity<${threshold}${cap > 0 ? `，上限 ${cap}` : ''}）`)
+      if (picked.length) console.log(`[focus] 等价命令：--only ${picked.map((item) => item.caseId).join(',')}`)
+    }
+  } else if (args.only) {
+    selectedSet = new Set(String(args.only).split(',').filter(Boolean))
+  }
+
+  // --resume：已有报告的案例（含 --inherit 搬进来的）不再重跑，只补缺口
+  let doneSet = null
+  if (args.resume) {
+    try { doneSet = new Set(loadRunReports(runDir).keys()) } catch { doneSet = new Set() }
+    if (doneSet.size) console.log(`[resume] 跳过已完成 ${doneSet.size} 例`)
   }
 
   const cases = casePool.filter((testCase) => {
-    if (failedSet) return failedSet.has(testCase.caseId)
-    if (!args.only) return true
-    const selected = new Set(String(args.only).split(',').filter(Boolean))
-    return selected.has(testCase.caseId)
+    if (selectedSet && !selectedSet.has(testCase.caseId)) return false
+    if (doneSet && doneSet.has(testCase.caseId)) return false
+    return true
   }).slice(0, Number(args.limit) || undefined)
   const skippedPopups = allCases.filter((testCase) =>
     (testCase.tags || []).some((tag) => popupTypes.has(String(tag).toLowerCase())))
@@ -657,14 +738,59 @@ async function main() {
   })
   const reviewQueue = []
   const semanticReviewQueue = []
+  // --inherit：把上轮「本轮不重跑」的案例报告与截图搬进本轮，让增量轮成为完整可比轮。
+  // 否则 score_round 的 passRate 分母只剩失败例、round_diff 把未重跑案例全算成 removed，
+  // 快路径轮的指标读起来像整轮崩了。cards/slices 仍只含本轮重跑案例，
+  // 所以继承轮可用于门禁与回归对账，但不作冻结锚点载体（锚点必须整轮全量跑）。
+  const inheritedCases = []
+  if (args.inherit) {
+    const inheritFrom = path.resolve(String(args.inherit))
+    const inheritReportsDir = path.join(inheritFrom, 'reports')
+    let inheritReports
+    try {
+      inheritReports = loadRunReports(inheritFrom)
+    } catch (error) {
+      throw new Error(`--inherit: 读不到 ${inheritFrom}: ${error.message}`)
+    }
+    const rerunIds = new Set(cases.map((testCase) => testCase.caseId))
+    for (const [caseId, report] of inheritReports) {
+      if (rerunIds.has(caseId)) continue
+      if (fs.existsSync(path.join(reportDir, `${caseId}.json`))) continue
+      for (const suffix of ['.json', '.render.png', '.design.png']) {
+        const source = path.join(inheritReportsDir, `${caseId}${suffix}`)
+        if (fs.existsSync(source)) fs.copyFileSync(source, path.join(reportDir, `${caseId}${suffix}`))
+      }
+      inheritedCases.push(caseId)
+      if (!report.passed) {
+        reviewQueue.push({
+          caseId,
+          priority: report.validate?.errors ? 1 : 2,
+          reason: report.failureSignature || (report.error ? `case-error:${errorKind(report.error)}` : 'metric-gate'),
+          failureClass: report.failureClass || null,
+          round: args.round,
+          inherited: true,
+        })
+      }
+    }
+    fs.writeFileSync(path.join(reportDir, 'inherited.json'),
+      JSON.stringify({ from: inheritFrom, count: inheritedCases.length, caseIds: inheritedCases }, null, 2) + '\n')
+    console.log(`[inherit] 从 ${path.basename(inheritFrom)} 继承 ${inheritedCases.length} 例，本轮重跑 ${cases.length} 例`)
+  }
   const sourceBefore = sourceChanges()
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
   // 共享渲染会话：整轮复用一个 Chrome + HTTP server。
   // 此前每卡各启一套（renderCardScreenshot 内部建/拆会话），~1.5-2s/卡全是启停开销。
   // 冷帧（会话首帧缺背景图）根因已由 render_card.mjs 的 CDP 网络静默等待闭环，整轮无需暖机帧。
-  let renderSession = await createRenderSession({ cardsRoot: cardsDir })
+  // 渲染会话懒启动：--resume 续跑「已全部完成」的轮次、或焦点集为空时，
+  // 不必白起一套 Chrome + HTTP server（本机实测 ~2-14s 启停开销）
+  if (!cases.length) console.log('[skip] 本轮无待跑案例（选样为空或已全部完成）')
+  let renderSession = null
+  const ensureRenderSession = async () => {
+    if (!renderSession) renderSession = await createRenderSession({ cardsRoot: cardsDir })
+    return renderSession
+  }
   const renderOnce = async (id, w, h) => {
-    let res = await renderSession.render({
+    let res = await (await ensureRenderSession()).render({
       id, width: w, captureHeight: h, format: 'png', captureElements: true,
     })
     if (!res.ok && /session-closed|Target|WebSocket|Chrome|浏览器|超时/i.test(String(res.error || '') + String(res.message || ''))) {
@@ -716,6 +842,7 @@ async function main() {
         }
       }
       const exclusionRects = (designCard.elements || [])
+  const fontRects = []
         .filter((element) => ['missing-slice', 'background-slice-unavailable']
           .includes(element.annotationDefect?.type))
         .filter((element) => {
@@ -731,17 +858,23 @@ async function main() {
       for (const element of designCard.elements || []) {
         if (element.type !== 'text') continue
         const family = String(element.textStyle?.fontFamily || element.textStyle?.fontFace || '')
-        if (family && !/^PingFang/i.test(family)) {
+        // 环境感知掩膜门：探针实测「回退栈宽/标注宽」>1.06 即该字体在本机渲染环境不可得
+        // （PingFang SC 在 Windows 同样回退合成，家族名豁免会让最大像素热带漏掩）；
+        // 探针缺失时回退家族名判据。掩膜只豁免字形度量差，位置/结构/颜色仍覆盖这些文本。
+        const widen = fontMaskWiden(element)
+        const familyUnsupported = family && !/^PingFang/i.test(family)
+        const envUnsupported = !!loadFontMetrics() && widen > 1.06
+        if (familyUnsupported || envUnsupported) {
           // 掩膜按标注对齐方式锚定扩宽：居中窄体文本的渲染字形向两侧溢出设计层框，
           // 只向右扩会漏掩左半溢出带（实测单带热区可达 66%）。
           const base = toExclRect(element, 1)
-          const widened = toExclRect(element, fontMaskWiden(element))
+          const widened = toExclRect(element, widen)
           if (String(element.textStyle?.textAlign || 'left') === 'center') {
             const shift = (widened.width - base.width) / 2
             widened.x = Math.max(0, base.x - shift)
             widened.width = Math.min(1 - widened.x, widened.width + shift)
           }
-          exclusionRects.push({ ...widened, reason: 'unsupported-font' })
+          fontRects.push({ ...widened, reason: 'unsupported-font' })
         }
       }
       const renderWidth = Math.round(designCard?.rect?.width || spec.size?.width || 375)
@@ -895,12 +1028,38 @@ async function main() {
       fs.writeFileSync(renderPath, Buffer.from(rendered.base64, 'base64'))
       // 同步保存设计稿参考图到 reports 目录，便于 summary.md 并排对比
       try { fs.copyFileSync(testCase.input.designImage, path.join(reportDir, testCase.caseId + '.design.png')) } catch {}
+      // ── 裁切兜底切图掩膜：导出素材缺失 → 只能从画板裁切（__artboard_crop__*）──
+      // 裁切块自带周边底色/圆角残边/邻件像素，与「导出素材」的渲染差异属素材来源差距，
+      // 不是生成缺陷 → 按设计稿标注盒精确掩膜（外扩 1.5px 吸收抗锯齿边），
+      // 仅掩「生成 schema 真实引用了该裁切文件」的元素（未引用=生成端已另行还原，差异仍计分）。
+      {
+        const schemaJson = JSON.stringify(generated.schema)
+        for (const element of designCard.elements || []) {
+          const defect = element.annotationDefect
+          const cropFile = defect?.cropSlice || (defect?.resolution === 'artboard-crop' ? defect?.name : null)
+          if (!defect || defect.type !== 'missing-slice' || !cropFile) continue
+          if (!schemaJson.includes(cropFile)) continue
+          const pad = 1.5
+          const base = toExclRect(element, 1)
+          exclusionRects.push({
+            x: Math.max(0, base.x - pad / _exclCardW),
+            y: Math.max(0, base.y - pad / _exclCardH),
+            width: Math.min(1, base.width + (pad * 2) / _exclCardW),
+            height: Math.min(1, base.height + (pad * 2) / _exclCardH),
+            reason: 'crop-fallback-slice',
+          })
+        }
+      }
       report.pixel = imageFidelity(
         fs.readFileSync(testCase.input.designImage),
         fs.readFileSync(renderPath),
         exclusionRects,
+        fontRects,
       )
-      report.pixelExclusions = exclusionRects
+      report.pixelExclusions = [...exclusionRects, ...fontRects]
+      // 掩膜覆盖率：掩膜是「不计分」而不是「还原对」。覆盖率过高时通过结论不可信，
+      // score_round 会把高掩膜案例单列出来要求人工复核（防止靠掩膜虚高过门）。
+      report.exclusionCoverage = exclusionCoverage([...exclusionRects, ...fontRects])
       report.textRecall = textRecall(generated.schema, testCase.expected?.requiredTexts)
       // ── Element-level position scoring ──
       const cardRect = designCard?.rect || {}
@@ -970,33 +1129,38 @@ async function main() {
         report.position,
         report.textOverflow,
       )
-      report.passed =
-        report.validate.errors === 0 &&
-        report.lint.errors === 0 &&
-        report.pixel.ratio <= 0.08 &&
-        report.fidelity.overall >= 0.85 &&
-        report.fidelity.components >= 0.75 &&
-        report.fidelity.position >= 0.80 &&
-        report.fidelity.textOverflow >= 0.90 &&
-        (report.duplication?.overall ?? 1) >= 0.95 &&
-        report.pixel.dimension >= 0.95 &&
-        report.pixel.color >= 0.90 &&
-        report.pixel.structure >= 0.85
+      // 单案例门以 lib/scoring.mjs 的 PASS_GATE 为唯一来源（SKILL.md 验收表、score_round 同源，
+      // 文档数字由 tools/tests/scoring.test.mjs 反向断言），并把未达标维度按缺口落盘供聚类归因
+      const gate = evaluatePassGate(report)
+      report.gateFailures = gate.failures
+      report.passed = gate.passed
+      report.failureSignature = failureSignature(report)
+      const attribution = attributeFailure(report)
+      if (attribution) {
+        report.failureClass = attribution.failureClass
+        report.failureReason = attribution.reason
+      }
     } catch (error) {
       report.error = String(error.message || error)
       report.passed = false
+      report.failureSignature = failureSignature(report)
+      const attribution = attributeFailure(report)
+      if (attribution) {
+        report.failureClass = attribution.failureClass
+        report.failureReason = attribution.reason
+      }
     }
     report.durationMs = Date.now() - started
     fs.writeFileSync(path.join(reportDir, `${testCase.caseId}.json`),
       JSON.stringify(report, null, 2) + '\n')
     if (!report.passed) reviewQueue.push({
       caseId: testCase.caseId, priority: report.validate.errors ? 1 : 2,
-      reason: report.error ||
-        (report.upstream && !report.upstream.passed
-          ? `parser:${report.upstream.annotationCompleteness?.toFixed(3) || 'N/A'}`
-          : (report.duplication?.overall ?? 1) < 0.95
-            ? `duplicate-content:${report.duplication.excessCount}`
-            : `fidelity:${report.fidelity?.overall?.toFixed(3) || 'N/A'}`),
+      // reason 用主失败签名（归一化缺口最大的维度），并带失败类与全部未达标维度，
+      // 复核队列因此可直接聚类，不必逐例打开报告
+      reason: report.error || report.failureSignature || 'metric-gate',
+      failureClass: report.failureClass || null,
+      gateFailures: (report.gateFailures || []).map((item) => item.key),
+      fidelity: report.fidelity?.overall ?? null,
       round: args.round,
     })
     if (!report.passed && report.pixel?.comparable) semanticReviewQueue.push({
@@ -1023,7 +1187,7 @@ async function main() {
   }
   } finally {
     // 任何异常路径都要关掉 Chrome + HTTP server，杜绝进程残留
-    try { await renderSession.close() } catch {}
+    try { await renderSession?.close() } catch {}
   }
   fs.writeFileSync(path.join(reportDir, 'review-queue.jsonl'),
     reviewQueue.map((item) => JSON.stringify(item)).join('\n') + (reviewQueue.length ? '\n' : ''))
@@ -1031,6 +1195,17 @@ async function main() {
     semanticReviewQueue.map((item) => JSON.stringify(item)).join('\n') +
     (semanticReviewQueue.length ? '\n' : ''))
 
+  // 一轮跑完直接出门禁汇总：此前还要人工再敲一次 score_round，忘了就没有 summary.json / roundGate
+  if (!args.noSummary) {
+    const scoreScript = path.join(import.meta.dirname, 'score_round.mjs')
+    const scored = spawnSync(process.execPath, [scoreScript, '--run', runDir, '--quiet'], {
+      encoding: 'utf8', cwd: repoRoot,
+    })
+    const output = `${scored.stdout || ''}${scored.stderr || ''}`.trim()
+    if (output) console.log(output)
+    if (scored.status !== 0) console.warn(`[WARN] score_round 退出码 ${scored.status}（summary 可能未写出）`)
+  }
+
   const newSourceChanges = sourceChanges().filter((line) => !sourceBefore.includes(line))
   if (newSourceChanges.length) {
     throw new Error(`SANDBOX_VIOLATION: training wrote into src/: ${newSourceChanges.join(', ')}`)