cardbuddy 0.14.3 → 0.16.0

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

@@ -1,10 +1,15 @@
 import { spawnSync } from 'node:child_process'
 
-/** 跨平台 Python 探测：DSL_CARD_PYTHON > WORKBUDDY_PYTHON > python3 > python */
+/**
+ * 跨平台 Python 探测：DSL_CARD_PYTHON > WORKBUDDY_PYTHON > DSL_PYTHON > PYTHON > python3/python/py。
+ * 语义与 `skills/dsl-card-generator/scripts/lib/python.mjs`（权威实现）对齐；trainer 需要能单独
+ * 分发，故不 import 而是照搬。`py` 必须在内：Windows 上 Python 从 Store 安装时往往只有它。
+ */
 function findPython() {
-  if (process.env.DSL_CARD_PYTHON) return process.env.DSL_CARD_PYTHON;
-  if (process.env.WORKBUDDY_PYTHON) return process.env.WORKBUDDY_PYTHON;
-  for (const bin of ['python3', 'python']) {
+  for (const key of ['DSL_CARD_PYTHON', 'WORKBUDDY_PYTHON', 'DSL_PYTHON', 'PYTHON']) {
+    if (process.env[key]) return process.env[key];
+  }
+  for (const bin of ['python3', 'python', 'py']) {
     try {
       if (spawnSync(bin, ['--version'], { stdio: 'ignore' }).status === 0) return bin;
     } catch {}
@@ -15,6 +20,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { PNG } from 'pngjs'
+import { sliceNameMatches } from '../../dsl-card-generator/scripts/lib/slice_dedupe.mjs'
 
 const repoRoot = path.resolve(import.meta.dirname, '../../..')
 
@@ -28,7 +34,7 @@ function parseArgs(argv) {
   const out = {
     dataset: '', round: '', strategy: 'v3', limit: 0, splits: 'train,dev,eval', only: '',
     onlyFailed: '', noCorrect: false, focus: '', focusBelow: 0.85, focusLimit: 0,
-    resume: false, inherit: '', noSummary: false,
+    resume: false, inherit: '', noSummary: false, noSink: false, concurrency: 2,
   }
   const camel = (raw) => raw.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase())
   for (let index = 0; index < argv.length; index += 1) {
@@ -86,6 +92,7 @@ function copyReferencedSlices(schema, sourceSlicesDir, targetSlicesDir) {
     referenced.add(m[1])
   }
   let copied = 0
+  const files = []
   const visit = (dir) => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const full = path.join(dir, entry.name)
@@ -93,15 +100,20 @@ function copyReferencedSlices(schema, sourceSlicesDir, targetSlicesDir) {
         visit(full)
         continue
       }
-      const relative = path.relative(sourceSlicesDir, full).split(path.sep).join('_').replace(/ /g, '_')
-      if (referenced.has(relative)) {
-        fs.mkdirSync(targetSlicesDir, { recursive: true })
-        fs.copyFileSync(full, path.join(targetSlicesDir, relative))
-        copied += 1
-      }
+      // 扁平名（/ → _）；空格等保留字符不再就地替换——匹配统一走 sliceNameMatches
+      // （与 schema 引用名同源消毒，r31c 等式）。旧数据集源文件名可带空格/保留字符。
+      files.push({ relative: path.relative(sourceSlicesDir, full).split(path.sep).join('_'), full })
     }
   }
   visit(sourceSlicesDir)
+  for (const ref of referenced) {
+    const hit = files.find((f) => sliceNameMatches(f.relative, ref))
+    if (!hit) continue
+    // 落盘名 = 引用名（消毒后），URL 才能解析；源名可以带空格/保留字符（历史数据集兼容）
+    fs.mkdirSync(targetSlicesDir, { recursive: true })
+    fs.copyFileSync(hit.full, path.join(targetSlicesDir, ref))
+    copied += 1
+  }
   return copied
 }
 
@@ -111,10 +123,10 @@ function runValidator(cardId, cardsDir) {
     path.join(cardsDir, cardId, 'schema.json'),
   ], { encoding: 'utf8' })
   if (result.error) {
-    return { errors: 1, warnings: 0, output: String(result.error.message || result.error) }
+    return { errors: 1, warnings: 0, output: String(result.error.message || result.error), error: String(result.error.message || result.error) }
   }
   if (result.status !== 0 && !/\[result\]/.test(`${result.stdout || ''}${result.stderr || ''}`)) {
-    return { errors: 1, warnings: 0, output: `${result.stdout || ''}${result.stderr || ''}` }
+    return { errors: 1, warnings: 0, output: `${result.stdout || ''}${result.stderr || ''}`, error: `validator-exit-${result.status}` }
   }
   const output = `${result.stdout || ''}${result.stderr || ''}`
   const errors = (output.match(/\[ERROR\]/g) || []).length
@@ -152,12 +164,16 @@ async function runMechanicalAutofix(schemaPath) {
 }
 
 import {
-  imageFidelity, positionScore, textOverflowScore, duplicationScore, fidelityScore, fontMaskWiden,
+  positionScore, textOverflowScore, duplicationScore, fidelityScore, fontMaskWiden,
   loadFontMetrics,
   evaluatePassGate, attributeFailure, failureSignature, exclusionCoverage,
   errorKind,
 } from './lib/scoring.mjs'
 import { loadRunReports } from './lib/runs.mjs'
+import { estimateReviewTokens, estimateStructuredReviewTokens, createStageTimer } from './lib/telemetry.mjs'
+import { initPixelWorkers, closePixelWorkers, scorePixel, pixelWorkerStatus } from './lib/pixel-worker.mjs'
+import { buildInlineDiagnosis } from './lib/diagnosis.mjs'
+import { canSimulateReject, simulateLayoutCorrection } from './lib/layout-correction-sim.mjs'
 
 
 function sourceChanges() {
@@ -168,6 +184,9 @@ function sourceChanges() {
   return String(result.stdout || '').split('\n').map((line) => line.trim()).filter(Boolean).sort()
 }
 
+// ── Telemetry helpers 在 lib/telemetry.mjs（pngSize / estimateReviewTokens / createStageTimer，
+//    tools/tests/trainer-telemetry.test.mjs 直测该模块）──
+
 function textRecall(schema, expectedTexts) {
   if (!expectedTexts?.length) return null
   const rendered = new Set()
@@ -777,46 +796,95 @@ async function main() {
     console.log(`[inherit] 从 ${path.basename(inheritFrom)} 继承 ${inheritedCases.length} 例，本轮重跑 ${cases.length} 例`)
   }
   const sourceBefore = sourceChanges()
+  const roundStartedAt = Date.now()
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
-  // 共享渲染会话：整轮复用一个 Chrome + HTTP server。
-  // 此前每卡各启一套（renderCardScreenshot 内部建/拆会话），~1.5-2s/卡全是启停开销。
-  // 冷帧（会话首帧缺背景图）根因已由 render_card.mjs 的 CDP 网络静默等待闭环，整轮无需暖机帧。
-  // 渲染会话懒启动：--resume 续跑「已全部完成」的轮次、或焦点集为空时，
-  // 不必白起一套 Chrome + HTTP server（本机实测 ~2-14s 启停开销）
+  // 渲染会话 per-worker 懒启动（2026-09-25 起支持 --concurrency 并发）：
+  // 每个 worker 持有独立 Chrome + HTTP server（render_card.mjs 的 server.listen(0) 随机端口、
+  // mkdtempSync 唯一 userDataDir，多实例天然安全）。worker=1 时行为与旧单会话串行完全一致。
+  // 上限 4：Chrome 内存线性涨，且 CPU 侧像素评分（同步循环）会互相阻塞事件循环，再多无益。
   if (!cases.length) console.log('[skip] 本轮无待跑案例（选样为空或已全部完成）')
-  let renderSession = null
-  const ensureRenderSession = async () => {
-    if (!renderSession) renderSession = await createRenderSession({ cardsRoot: cardsDir })
-    return renderSession
+  // 像素评分重计算已下沉 worker_threads（P0-2），主事件循环不再被同步评分阻塞，
+  // 故并发上限由 4 提到 6；再高会受 Chrome 内存与 spawnSync 校验/ lint 串行拖累。
+  const workerCount = Math.max(1, Math.min(Number(args.concurrency) || 2, cases.length || 1, 6))
+  // 像素评分 worker 池：池大小与渲染会话数一致，避免 oversubscription；
+  // worker 不可用时 scorePixel 自动同步回退，训练轮不崩。
+  if (cases.length) initPixelWorkers(workerCount)
+  if (workerCount > 1) console.log(`[concurrency] ${workerCount} 个渲染会话并行`)
+  // —— 轮级 telemetry：耗时 / 错误 / token 三类信号，收尾落 reports/telemetry.json ——
+  const telemetry = {
+    round: args.round,
+    startedAt: new Date().toISOString(),
+    concurrency: workerCount,
+    pixelWorker: pixelWorkerStatus(),
+    cases: cases.length,
+    scoredCases: 0,
+    renderCalls: 0,
+    renderRetries: 0,
+    sessionRebuilds: 0,
+    stageMs: {},
+    stageErrors: {},
+    caseErrors: 0,
+    usage: null,
+    reviewTokensEst: { total: 0, cases: 0 },
   }
-  const renderOnce = async (id, w, h) => {
-    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 || ''))) {
-      // Chrome 崩溃/断连：重建会话再试一次，避免整轮作废
-      try { await renderSession.close() } catch {}
-      renderSession = await createRenderSession({ cardsRoot: cardsDir })
-      res = await renderSession.render({
+  const accumulateStage = (name, ms) => {
+    telemetry.stageMs[name] = (telemetry.stageMs[name] || 0) + ms
+  }
+  const recordStageError = (stage, message) => {
+    telemetry.stageErrors[stage] = (telemetry.stageErrors[stage] || 0) + 1
+    return { stage, message: String(message).slice(0, 300) }
+  }
+  const makeWorkerSession = () => {
+    const state = { session: null }
+    const ensureRenderSession = async () => {
+      if (!state.session) state.session = await createRenderSession({ cardsRoot: cardsDir })
+      return state.session
+    }
+    const renderOnce = async (id, w, h) => {
+      telemetry.renderCalls += 1
+      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 || ''))) {
+        // Chrome 崩溃/断连：重建会话再试一次，避免整轮作废
+        telemetry.renderRetries += 1
+        telemetry.sessionRebuilds += 1
+        try { await state.session.close() } catch {}
+        state.session = await createRenderSession({ cardsRoot: cardsDir })
+        res = await state.session.render({
+          id, width: w, captureHeight: h, format: 'png', captureElements: true,
+        })
+      }
+      return res
     }
-    return res
+    return { state, ensureRenderSession, renderOnce }
   }
-  try {
-  for (const [index, testCase] of cases.entries()) {
+  const liveSessions = []
+  const processCase = async (testCase, index, worker) => {
     const started = Date.now()
     const cardId = `${args.round}__${testCase.caseId}`
+    const timer = createStageTimer()
+    const stageErrors = []
+    // try 外提升：catch / 收尾 telemetry 汇总也要读（案例中途失败时可能是 null）
+    let designBuf = null
+    let renderBuf = null
+    let designCard = null
+    // P1-2：失败案例结构化诊断（在环归因证据包），try 内算出、收尾 telemetry / semantic-review 复用
+    let _diag = null
     const report = {
       caseId: testCase.caseId, cardId, source: testCase.source,
       artboardName: testCase.artboardName, split: testCase.split,
       validate: { errors: 0 },
       lint: { errors: 0 },
+      stageErrors,
+      timings: timer.timings,
     }
     try {
+      // 设计稿只读一次（校正守卫 / 最终像素评分 / token 估算三处复用，省重复磁盘 IO）
+      designBuf = timer.time('parse', () => fs.readFileSync(testCase.input.designImage))
       const spec = JSON.parse(fs.readFileSync(testCase.input.specJson, 'utf8'))
       const cardPosition = Number(testCase.cardIndex) || 0
-      const designCard = (spec.cards || [])[cardPosition]
+      designCard = (spec.cards || [])[cardPosition]
       if (!designCard) throw new Error('focus-card-missing-or-skipped')
       // 纯文本区域（对话气泡/回复段落）不是卡片：无富组件（壳/切图/符号）且 ≥3 文本块。
       // 用户规则：对话气泡一律跳过，不计入训练指标（避免污染还原度统计与生成器归因）。
@@ -824,9 +892,9 @@ async function main() {
       if ((_fm.richComponentCount || 0) === 0 && (_fm.textCount || 0) >= 3) {
         console.log('[SKIP] conversation-text ' + testCase.caseId)
         skippedConversationTexts.push({ caseId: testCase.caseId, source: testCase.source, artboardName: testCase.artboardName })
-        continue
+        return
       }
-      report.upstream = upstreamQuality(spec, designCard)
+      report.upstream = timer.time('upstream', () => upstreamQuality(spec, designCard))
       const _cardRectForExcl = designCard.rect || {}
       const _exclCardW = Math.max(1, _cardRectForExcl.width || 1)
       const _exclCardH = Math.max(1, _cardRectForExcl.height || 1)
@@ -879,25 +947,38 @@ async function main() {
       }
       const renderWidth = Math.round(designCard?.rect?.width || spec.size?.width || 375)
       const renderHeight = Math.round(designCard?.rect?.height || spec.size?.height || 0) || null
-      const generated = generate(spec, {
+      const generated = timer.time('generate', () => generate(spec, {
         id: cardId,
         name: testCase.artboardName,
         cardIndex: testCase.cardIndex || 0,
         designImage: testCase.input.designImage,
-      })
+      }))
+      // LLM usage 挂钩（接口预留）：v3 纯规则引擎当前恒无 usage；生成链路未来 LLM 化
+      // （meta.usage = { inputTokens, outputTokens, calls }）后此处自动累计，无需再改 trainer。
+      if (generated.meta?.usage) {
+        report.usage = generated.meta.usage
+        telemetry.usage = telemetry.usage || { inputTokens: 0, outputTokens: 0, calls: 0 }
+        telemetry.usage.inputTokens += generated.meta.usage.inputTokens || 0
+        telemetry.usage.outputTokens += generated.meta.usage.outputTokens || 0
+        telemetry.usage.calls += generated.meta.usage.calls || 1
+      }
       const cardDir = path.join(cardsDir, cardId)
       fs.mkdirSync(cardDir, { recursive: true })
       fs.writeFileSync(path.join(cardDir, 'schema.json'), JSON.stringify(generated.schema, null, 2) + '\n')
       fs.writeFileSync(path.join(cardDir, 'data.json'), JSON.stringify(generated.data, null, 2) + '\n')
-      report.repair = runMechanicalAutofix(path.join(cardDir, 'schema.json'))
-      report.sliceCount = copyReferencedSlices(generated.schema, testCase.input.slicesDir, slicesDir)
-      report.validate = runValidator(cardId, cardsDir)
-      report.lint = runLinter(cardId, cardsDir, slicesDir)
-      let rendered = await renderOnce(cardId, renderWidth, renderHeight)
+      report.repair = timer.time('autofix', () => runMechanicalAutofix(path.join(cardDir, 'schema.json')))
+      report.sliceCount = timer.time('slices', () => copyReferencedSlices(generated.schema, testCase.input.slicesDir, slicesDir))
+      report.validate = timer.time('validate', () => runValidator(cardId, cardsDir))
+      if (report.validate.error) stageErrors.push(recordStageError('validate', report.validate.error))
+      report.lint = timer.time('lint', () => runLinter(cardId, cardsDir, slicesDir))
+      if (report.lint.error) stageErrors.push(recordStageError('lint', report.lint.error))
+      let rendered = await timer.timeAsync('render', () => worker.renderOnce(cardId, renderWidth, renderHeight))
       if (!rendered.ok) {
         report.renderRetry = { firstError: rendered.error || rendered.message }
+        stageErrors.push(recordStageError('render', rendered.message || rendered.error))
+        telemetry.renderRetries += 1
         await sleep(500)
-        rendered = await renderOnce(cardId, renderWidth, renderHeight)
+        rendered = await timer.timeAsync('render', () => worker.renderOnce(cardId, renderWidth, renderHeight))
       }
       if (!rendered.ok) throw new Error(rendered.message || rendered.error || 'render failed')
 
@@ -956,23 +1037,18 @@ async function main() {
       const cardColForSim = generated.schema.view?.components?.[0]
       const corrected = !args.noCorrect && correctCardLayout(generated.schema, rendered.elementBoxes, _deduped, _cr, _adjustments, _sim)
       // ── 模拟否决快路径 ──
-      // 纯纵向 paddingTop 校正在流式 Column 中是精确的刚体平移：
-      // 子树盒 +delta，后续兄弟盒 +累计 delta。模拟 position 分不提升 ⇒ 真实渲染
-      // 必然不提升，可直接回退并跳过二次渲染（每轮省 ~20 次渲染）。
+      // 纵向 paddingTop（Y）与横向 paddingLeft（X）校正，在各自轴向上都是精确的刚体平移：
+      //   Y：子树盒 +delta，后续兄弟盒 +累计 delta（纵向流式堆叠）。
+      //   X：子树盒 +delta，不跨兄弟级联（纵向流里每子项横向独立，各自 paddingLeft）。
+      // 详见 lib/layout-correction-sim.mjs。模拟 position 分不提升 ⇒ 真实渲染必然不提升，
+      // 可直接回退并跳过二次渲染（每轮省 ~20 次渲染）。
+      // 原逻辑仅准入纯 Y 调整，含 X 调整必二次渲染——现放宽到 Y/X 且 rigidSafe 均成立。
       // CORR_SIM_VALIDATE=1 时模拟与真实渲染双跑对账，用于验证模拟器保真。
       let _simRejectPos = null
       let _simLastPos = null
-      if (corrected && _adjustments.length
-        && _adjustments.every((a) => a.axis === 'y' && a.rigidSafe !== false)
-        && _sim.cidToChild
-        && ((cardColForSim?.slots?.[0]?.components) || []).every((c) => c.name !== 'AbsoluteLayout')) {
-        const _deltas = new Map()
-        for (const a of _adjustments) _deltas.set(a.childIndex, (_deltas.get(a.childIndex) || 0) + (a.to - a.from))
-        const _shiftFor = (idx) => { let acc = 0; for (const [i, d] of _deltas) if (i <= idx) acc += d; return acc }
-        const _shifted = (rendered.elementBoxes || []).map((b) => {
-          const idx = _sim.cidToChild.get(b.cid)
-          return idx == null ? b : { ...b, y: b.y + _shiftFor(idx) }
-        })
+      if (corrected && canSimulateReject(_adjustments, _sim.cidToChild, cardColForSim?.slots?.[0]?.components)) {
+        const { shifted: _shifted } = simulateLayoutCorrection(
+          rendered.elementBoxes || [], _adjustments, _sim.cidToChild)
         const _simPos = positionScore(_deduped,
           _shifted.filter((el) => el.text && ['Text', 'Input', 'Button'].includes(el.cls)),
           { cardW: _cr.width || renderWidth, cardH: _cr.height || renderHeight, specShapes: _specShapes })
@@ -989,14 +1065,15 @@ async function main() {
         }
       } else if (corrected) {
         fs.writeFileSync(path.join(cardDir, 'schema.json'), JSON.stringify(generated.schema, null, 2) + '\n')
-        const correctedRendered = await renderOnce(cardId, renderWidth, renderHeight)
+        const correctedRendered = await timer.timeAsync('reRender', () => worker.renderOnce(cardId, renderWidth, renderHeight))
         if (correctedRendered.ok) {
           const _correctedPos = positionScore(_deduped,
             (correctedRendered.elementBoxes || []).filter((el) => el.text && ['Text', 'Input', 'Button'].includes(el.cls)),
             { cardW: _cr.width || renderWidth, cardH: _cr.height || renderHeight, specShapes: _specShapes })
-          const _designBuf0 = fs.readFileSync(testCase.input.designImage)
-          const _pixelBefore = imageFidelity(_designBuf0, Buffer.from(_renderedBackup.base64, 'base64'), exclusionRects)
-          const _pixelAfter = imageFidelity(_designBuf0, Buffer.from(correctedRendered.base64, 'base64'), exclusionRects)
+                const _pixelBefore = await timer.timeAsync('pixel', () =>
+            scorePixel(designBuf, Buffer.from(_renderedBackup.base64, 'base64'), exclusionRects, [], { includeAlignDy: false }))
+          const _pixelAfter = await timer.timeAsync('pixel', () =>
+            scorePixel(designBuf, Buffer.from(correctedRendered.base64, 'base64'), exclusionRects, [], { includeAlignDy: false }))
           const _pixelOk = _pixelAfter.ratio <= _pixelBefore.ratio + 0.005
           if (process.env.CORR_DEBUG) console.error('[corr] initialPos=' + _initialPos.overall.toFixed(4) + ' correctedPos=' + _correctedPos.overall.toFixed(4) + ' pixel ' + _pixelBefore.ratio.toFixed(4) + '→' + _pixelAfter.ratio.toFixed(4))
           if (process.env.CORR_SIM_VALIDATE && _simLastPos != null) {
@@ -1025,7 +1102,8 @@ async function main() {
       }
 
       const renderPath = path.join(reportDir, `${testCase.caseId}.render.png`)
-      fs.writeFileSync(renderPath, Buffer.from(rendered.base64, 'base64'))
+      renderBuf = Buffer.from(rendered.base64, 'base64')
+      fs.writeFileSync(renderPath, renderBuf)
       // 同步保存设计稿参考图到 reports 目录，便于 summary.md 并排对比
       try { fs.copyFileSync(testCase.input.designImage, path.join(reportDir, testCase.caseId + '.design.png')) } catch {}
       // ── 裁切兜底切图掩膜：导出素材缺失 → 只能从画板裁切（__artboard_crop__*）──
@@ -1037,8 +1115,8 @@ async function main() {
         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
+          if (!defect || (defect.type !== 'missing-slice' && defect.type !== 'slice-visual-mismatch') || !cropFile) continue
+          if (!(schemaJson.includes(cropFile) || schemaJson.includes(cropFile.replace(/\s+/g, '-')))) continue
           const pad = 1.5
           const base = toExclRect(element, 1)
           exclusionRects.push({
@@ -1050,12 +1128,13 @@ async function main() {
           })
         }
       }
-      report.pixel = imageFidelity(
-        fs.readFileSync(testCase.input.designImage),
-        fs.readFileSync(renderPath),
+      report.pixel = await timer.timeAsync('pixel', () => scorePixel(
+        designBuf,
+        renderBuf,
         exclusionRects,
         fontRects,
-      )
+        { includeAlignDy: true },
+      ))
       report.pixelExclusions = [...exclusionRects, ...fontRects]
       // 掩膜覆盖率：掩膜是「不计分」而不是「还原对」。覆盖率过高时通过结论不可信，
       // score_round 会把高掩膜案例单列出来要求人工复核（防止靠掩膜虚高过门）。
@@ -1113,22 +1192,24 @@ async function main() {
           return { x: (r.x || 0) - (cardRect.x || 0), y: (r.y || 0) - (cardRect.y || 0), w: r.width || 0, h: r.height || 0 }
         })
         .filter((el) => el.w > 0 && el.h > 0)
-      report.position = positionScore(specTexts, renderedTexts, {
-        cardW: cardRect.width || renderWidth,
-        cardH: cardRect.height || renderHeight,
-        specShapes: _specShapesFinal,
+      timer.time('score', () => {
+        report.position = positionScore(specTexts, renderedTexts, {
+          cardW: cardRect.width || renderWidth,
+          cardH: cardRect.height || renderHeight,
+          specShapes: _specShapesFinal,
+        })
+        report.textOverflow = textOverflowScore(rendered.elementBoxes || [])
+        // 语义重复渲染检测（重影）：同一文案渲染次数不得超出标注次数
+        report.duplication = duplicationScore(specTexts, renderedTexts)
+        report.fidelity = fidelityScore(
+          report.pixel,
+          expectedComponents(designCard),
+          schemaComponents(generated.schema),
+          report.textRecall,
+          report.position,
+          report.textOverflow,
+        )
       })
-      report.textOverflow = textOverflowScore(rendered.elementBoxes || [])
-      // 语义重复渲染检测（重影）：同一文案渲染次数不得超出标注次数
-      report.duplication = duplicationScore(specTexts, renderedTexts)
-      report.fidelity = fidelityScore(
-        report.pixel,
-        expectedComponents(designCard),
-        schemaComponents(generated.schema),
-        report.textRecall,
-        report.position,
-        report.textOverflow,
-      )
       // 单案例门以 lib/scoring.mjs 的 PASS_GATE 为唯一来源（SKILL.md 验收表、score_round 同源，
       // 文档数字由 tools/tests/scoring.test.mjs 反向断言），并把未达标维度按缺口落盘供聚类归因
       const gate = evaluatePassGate(report)
@@ -1140,9 +1221,16 @@ async function main() {
         report.failureClass = attribution.failureClass
         report.failureReason = attribution.reason
       }
+      // P1-2：失败案例在环归因用的轻量结构化证据包（零额外渲染，复用 report / 设计稿 buffer /
+      // 标注文本 / 渲染盒），塞进 semantic-review 队列供 Agent 消费，避免直接读双 PNG 烧图像 token。
+      if (report.pixel?.comparable) {
+        _diag = buildInlineDiagnosis(report, { designBuf, renderBuf, specTexts, renderedTexts })
+      }
     } catch (error) {
       report.error = String(error.message || error)
       report.passed = false
+      stageErrors.push(recordStageError('case', report.error))
+      telemetry.caseErrors += 1
       report.failureSignature = failureSignature(report)
       const attribution = attributeFailure(report)
       if (attribution) {
@@ -1151,6 +1239,21 @@ async function main() {
       }
     }
     report.durationMs = Date.now() - started
+    // —— telemetry 汇总（阶段耗时 / 失败案例归因证据包 token 估算）——
+    telemetry.scoredCases += 1
+    for (const [stage, ms] of Object.entries(timer.timings)) accumulateStage(stage, ms)
+    if (!report.passed) {
+      const specChars = (() => { try { return JSON.stringify(designCard ?? {}).length } catch { return 0 } })()
+      // P1-2：失败案例在环归因默认消费结构化 diagnosis（见下方 semanticReviewQueue 的 diagnosis
+      // 字段），不再强制读取双 PNG；故 token 估算以结构化证据包为主，旧双图估算留存
+      // reviewTokensEstImage 供对照。两者均不参与任何门禁，仅作预算参考。
+      const estImage = estimateReviewTokens({ designBuffer: designBuf, renderBuffer: renderBuf, specChars })
+      const est = _diag ? estimateStructuredReviewTokens(_diag) : estImage
+      report.reviewTokensEst = est
+      report.reviewTokensEstImage = estImage
+      telemetry.reviewTokensEst.total += est.total
+      telemetry.reviewTokensEst.cases += 1
+    }
     fs.writeFileSync(path.join(reportDir, `${testCase.caseId}.json`),
       JSON.stringify(report, null, 2) + '\n')
     if (!report.passed) reviewQueue.push({
@@ -1174,6 +1277,10 @@ async function main() {
         color: report.pixel.color ?? null,
         components: report.fidelity?.components ?? null,
       },
+      // P1-2：结构化证据包（零额外渲染，复用 report/设计稿 buffer/标注文本/渲染盒）。
+      // 在环 Agent 据此做聚类与归因，避免直接加载两张 PNG 烧图像 token。
+      // provenance（cid→生成器源码行）按需由 diagnose_case.mjs 深度补全。
+      diagnosis: _diag,
       evidence: {
         designImage: testCase.input.designImage,
         renderImage: path.join(reportDir, `${testCase.caseId}.render.png`),
@@ -1181,14 +1288,44 @@ async function main() {
         cardIndex: testCase.cardIndex || 0,
         schema: path.join(cardsDir, cardId, 'schema.json'),
       },
-      instruction: 'Classify card boundary and each changed cluster as static-text/display-value/input/action/navigation/list/media/decoration; attribute one primary failure class; propose only a generic UI or DSL rule.',
+      instruction: '优先消费结构化「diagnosis」字段做聚类与归因：gateFailures（按 deficit 降序的未达标维度）、deviations（文本 dy/dx 偏差表）、hotBands（像素热区带）、metrics、hints（已给失败类建议）。仅当结构化证据不足以定位根因时，才打开 evidence.images 两张 PNG 复核。归因只输出通用 UI/DSL 规则，禁止硬编码特定卡片文案或业务实体名称。',
     })
-    console.log(`[${index + 1}/${cases.length}] ${report.passed ? 'PASS' : 'FAIL'} ${testCase.caseId}`)
+    console.log(`[${index + 1}/${cases.length}]${workerCount > 1 ? ` (w${worker.id})` : ''} ${report.passed ? 'PASS' : 'FAIL'} ${testCase.caseId} ${report.durationMs}ms`)
   }
+  // worker 池：cursor 单调分派案例，每 worker 持独立渲染会话；单案例异常已在 processCase 内消化
+  try {
+    let cursor = 0
+    const workerMain = async (workerId) => {
+      const worker = { id: workerId + 1, ...makeWorkerSession() }
+      liveSessions.push(worker.state)
+      while (cursor < cases.length) {
+        const index = cursor++
+        await processCase(cases[index], index, worker)
+      }
+      try { await worker.state.session?.close() } catch {}
+    }
+    await Promise.all(Array.from({ length: workerCount }, (_, i) => workerMain(i)))
   } finally {
-    // 任何异常路径都要关掉 Chrome + HTTP server，杜绝进程残留
-    try { await renderSession?.close() } catch {}
+    // 任何异常路径都要关掉 Chrome + HTTP server，杜绝进程残留（worker 异常中断时兜底）
+    await Promise.all(liveSessions.map(async (s) => { try { await s.session?.close() } catch {} }))
+    try { await closePixelWorkers() } catch {}
   }
+  // —— 轮级 telemetry 落盘：错误 / 耗时 / token 三类信号的唯一轮级出口 ——
+  const wallMs = Date.now() - roundStartedAt
+  const stageAverages = Object.fromEntries(
+    Object.entries(telemetry.stageMs)
+      .map(([stage, ms]) => [stage, Math.round(ms / Math.max(telemetry.scoredCases, 1))]))
+  const telemetryOut = {
+    ...telemetry,
+    finishedAt: new Date().toISOString(),
+    wallMs,
+    stageAverages,
+    wallSecondsPerCase: telemetry.scoredCases ? Number((wallMs / telemetry.scoredCases / 1000).toFixed(2)) : null,
+    casesPerMinute: wallMs > 0 && telemetry.scoredCases ? Number((telemetry.scoredCases / (wallMs / 60000)).toFixed(2)) : null,
+    reviewTokensNote: '失败案例 Agent 在环归因证据包的 input token 估算（图像面积/750 + spec 文本/4 chars）；v3 生成器为纯规则引擎无 LLM 调用，usage 字段为生成链路 LLM 化后预留',
+  }
+  fs.writeFileSync(path.join(reportDir, 'telemetry.json'), JSON.stringify(telemetryOut, null, 2) + '\n')
+  console.log(`[telemetry] ${telemetry.scoredCases} 例 / ${workerCount} 并发 / 墙钟 ${(wallMs / 1000).toFixed(1)}s（${telemetryOut.casesPerMinute ?? '-'} 例/分钟 · 渲染 ${telemetry.renderCalls} 次${telemetry.renderRetries ? ` · 重试 ${telemetry.renderRetries}` : ''}${telemetry.caseErrors ? ` · 案例错误 ${telemetry.caseErrors}` : ''}）`)
   fs.writeFileSync(path.join(reportDir, 'review-queue.jsonl'),
     reviewQueue.map((item) => JSON.stringify(item)).join('\n') + (reviewQueue.length ? '\n' : ''))
   fs.writeFileSync(path.join(reportDir, 'semantic-review.jsonl'),
@@ -1206,6 +1343,58 @@ async function main() {
     if (scored.status !== 0) console.warn(`[WARN] score_round 退出码 ${scored.status}（summary 可能未写出）`)
   }
 
+
+  // —— 轮后落盘：plan_next_round + lesson 草稿自动沉淀 + 训练总结 ——
+  if (!args.noSink) {
+    const planScript = path.join(import.meta.dirname, 'plan_next_round.mjs')
+    const planArgs = [planScript, '--run', runDir, '--history', 'auto']
+    if (args.anchor) planArgs.push('--anchor', String(args.anchor))
+    const planned = spawnSync(process.execPath, planArgs, { encoding: 'utf8', cwd: repoRoot })
+    const planOutput = `${planned.stdout || ''}${planned.stderr || ''}`.trim()
+    if (planOutput) console.log(planOutput)
+    if (planned.status !== 0) console.warn(`[WARN] plan_next_round 退出码 ${planned.status}（落盘可能不完整）`)
+
+    // 自动沉淀 lesson 草稿到 training/lessons/lessons.jsonl（按 signature 去重）
+    const draftsFile = path.join(reportDir, 'lesson-drafts.jsonl')
+    const lessonsFile = path.join(repoRoot, 'training', 'lessons', 'lessons.jsonl')
+    if (fs.existsSync(draftsFile)) {
+      const drafts = fs.readFileSync(draftsFile, 'utf8').split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l))
+      if (drafts.length) {
+        const existingSignatures = new Set()
+        if (fs.existsSync(lessonsFile)) {
+          for (const line of fs.readFileSync(lessonsFile, 'utf8').split('\n').filter(Boolean)) {
+            try { const row = JSON.parse(line); if (row.signature) existingSignatures.add(row.signature.toLowerCase()) } catch {}
+          }
+        }
+        const newLessons = drafts.filter((d) => d.signature && !existingSignatures.has(d.signature.toLowerCase()))
+        if (newLessons.length) {
+          fs.appendFileSync(lessonsFile, newLessons.map((l) => JSON.stringify(l)).join('\n') + '\n')
+          console.log(`[sink] ${newLessons.length} 条新 lesson 沉淀到 ${path.relative(repoRoot, lessonsFile)}`)
+        }
+      }
+    }
+
+    // 回灌规则到目标 skill 文档（lessons → generation_pitfalls.md / SKILL.md 等）
+    const sinkScript = path.join(import.meta.dirname, 'sink_rules.mjs')
+    const sunk = spawnSync(process.execPath, [sinkScript], { encoding: 'utf8', cwd: repoRoot })
+    const sinkOutput = `${sunk.stdout || ''}${sunk.stderr || ''}`.trim()
+    if (sinkOutput) console.log(sinkOutput.split('\n').map((l) => l.startsWith('[') ? l : null).filter(Boolean).join('\n'))
+    if (sunk.status !== 0) console.warn(`[WARN] sink_rules 退出码 ${sunk.status}`)
+
+        // 写 TRAINING-SUMMARY.md（人读训练总结）
+    const summaryFile = path.join(reportDir, 'summary.json')
+    let summaryData = null
+    try { summaryData = JSON.parse(fs.readFileSync(summaryFile, 'utf8')) } catch {}
+    if (summaryData) {
+      const pct = (v) => v == null ? 'N/A' : (v * 100).toFixed(1) + '%'
+      const roundName = path.basename(runDir)
+      const passed = summaryData.roundGatePassed
+      const md = `# 训练总结 — ${roundName}\n\n## 门禁结果：${summaryData.roundGatePassed ? 'PASS' : 'FAIL'}\n\n| 维度 | 分数 | 门禁 | 状态 |\n|------|------|------|------|\n| 还原度 | ${pct(summaryData.avgFidelity)} | >=85% | ${passed ? 'PASS' : 'FAIL'} |\n| 像素差异 | ${pct(summaryData.avgPixelDiff)} | <=8% | ${passed ? 'PASS' : 'FAIL'} |\n| 位置精度 | ${pct(summaryData.avgPositionFidelity)} | >=80% | ${passed ? 'PASS' : 'FAIL'} |\n| 结构还原 | ${pct(summaryData.avgStructureFidelity)} | >=85% | ${passed ? 'PASS' : 'FAIL'} |\n| 通过率 | ${pct(summaryData.passRate)} | >=95% | ${passed ? 'PASS' : 'FAIL'} |\n\n- 案例: ${summaryData.total} / 通过: ${summaryData.passed} / 失败: ${summaryData.total - summaryData.passed}\n- 渲染调用: ${summaryData.telemetry?.renderCalls ?? 'N/A'}\n- 墙钟: ${((summaryData.telemetry?.wallMs ?? 0) / 1000).toFixed(1)}s\n- 失败签名: ${(summaryData.failureSignatures || []).map((s) => s.signature + 'x' + s.count).join(', ') || '无'}\n\n## 产物路径\n- 训练产物: \`training/runs/${roundName}/\`\n- 诊断报告: \`training/runs/${roundName}/reports/\`\n- 下一轮计划: \`training/runs/${roundName}/reports/next-round-plan.json\`\n- Lesson 草稿: \`training/runs/${roundName}/reports/lesson-drafts.jsonl\`\n`
+      fs.writeFileSync(path.join(runDir, 'TRAINING-SUMMARY.md'), md)
+      console.log(`[sink] 训练总结写入 ${path.relative(repoRoot, path.join(runDir, 'TRAINING-SUMMARY.md'))}`)
+    }
+  }
+
   const newSourceChanges = sourceChanges().filter((line) => !sourceBefore.includes(line))
   if (newSourceChanges.length) {
     throw new Error(`SANDBOX_VIOLATION: training wrote into src/: ${newSourceChanges.join(', ')}`)