cardbuddy 0.15.0 → 0.16.0

package/dist/vendored/server/core/cardValidate.js

@@ -17,7 +17,8 @@ const VALIDATE_SCRIPT_REL = 'dsl-card-generator/scripts/validate_schema.py'
  * - GET /__validate       ：全量校验，逐卡跑 Python 校验器，汇总返回
  *
  * 实现：子进程调用 `skills/dsl-card-generator/scripts/validate_schema.py --json`。
- * Python 解释器解析顺序：`DSL_PYTHON` → `python3` → `python`，都不存在时返回
+ * Python 解释器解析顺序：`DSL_CARD_PYTHON`（权威）→ `WORKBUDDY_PYTHON` → `DSL_PYTHON`
+ * → `PYTHON` → 探测 `python3` / `python` / `py`；都不存在时返回
  * **503 {error:'python-not-found'}** 而非 500，让 Agent / CI 能区分「环境没装」和「卡片有问题」。
  *
  * @param {{ root: string }} opts
@@ -32,10 +33,20 @@ export function scriptPath(root) {
   return resolveSkillPathOrProject(root, VALIDATE_SCRIPT_REL)
 }
 
-/** 解析可用的 python 解释器；找不到返回 null（导出供 MCP 复用） */
+/**
+ * 解析可用的 python 解释器；找不到返回 null（导出供 MCP 复用）。
+ *
+ * 能力对齐 `skills/dsl-card-generator/scripts/lib/python.mjs`（权威实现）：环境变量链
+ * 四个键 + 自动探测含 `py`。此前只认 `DSL_PYTHON` 且不含 `py` —— Windows 上 Python 从
+ * Store 安装时往往只有 `py` 启动器，会在这里被判成「环境没装 Python」并回 503，
+ * 而 skill 脚本侧其实是能跑的（同一台机器两种结论）。
+ */
 export function resolvePython() {
-  if (process.env.DSL_PYTHON) return process.env.DSL_PYTHON
-  for (const cmd of ['python3', 'python']) {
+  for (const key of ['DSL_CARD_PYTHON', 'WORKBUDDY_PYTHON', 'DSL_PYTHON', 'PYTHON']) {
+    const val = process.env[key]
+    if (val) return val
+  }
+  for (const cmd of ['python3', 'python', 'py']) {
     try {
       execFileSync(cmd, ['--version'], { stdio: 'ignore', timeout: 5000 })
       return cmd
@@ -92,7 +103,7 @@ export function createValidateMiddleware({ root }) {
       res.setHeader('Content-Type', 'application/json')
       return res.end(JSON.stringify({
         error: 'python-not-found',
-        message: '未找到 python3/python，请在 PATH 中安装 Python 或设置 DSL_PYTHON 环境变量',
+        message: '未找到 python3/python/py，请在 PATH 中安装 Python 或设置 DSL_CARD_PYTHON 环境变量',
       }))
     }
 

package/dist/vendored/skills/card-skill-trainer/SKILL.md

@@ -49,7 +49,7 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 5. 复制 schema 实际引用的 slices 到当前 run 的隔离资源目录。
 6. 执行 Python 结构校验、Node lint、独立 Chrome 渲染、重复内容检测和像素差异计算。
 7. 聚合 Round 报告（`run_round.mjs` 收尾自动调用 `score_round.mjs`），按主失败签名与失败类出直方图。
-8. `plan_next_round.mjs` 把「归因 → 聚类 → 焦点集 → 门禁判定 → 收敛信号 → lesson 草稿」一次算完，产出 `next-round-plan.json` 与 `lesson-drafts.jsonl`（`status=candidate`，人工审批后才落盘 lessons）。Agent 按聚类逐例复核 `designImage + render.png + spec.json`，把失败归入 PARSER / DSL / STYLE / DATA / INTERACTION / ASSET / EVALUATOR，并只推广通用规则。
+8. **轮后自动落盘**（`run_round.mjs` 收尾自动执行，`--no-sink` 跳过）：`plan_next_round.mjs` 把「归因 → 聚类 → 焦点集 → 门禁判定 → 收敛信号 → lesson 草稿」一次算完，产出 `next-round-plan.json` 与 `lesson-drafts.jsonl`（`status=candidate`）；lesson 草稿按 signature 去重后自动追加到 `training/lessons/lessons.jsonl`；最后写 `TRAINING-SUMMARY.md`（人读训练总结含门禁结果表）。Agent 按聚类逐例复核 `designImage + render.png + spec.json`，把失败归入 PARSER / DSL / STYLE / DATA / INTERACTION / ASSET / EVALUATOR，并只推广通用规则。
 
 ## 高效迭代闭环（r172 起；r263 补自动归因与增量轮补齐）
 
@@ -62,8 +62,9 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
    （多案例共用一套渲染会话）：门禁未达标维度（按缺口降序）、失败类归因、掩膜覆盖率、上游聚焦门、
    side-by-side、像素热区、元素偏差表、`__prov` 源码行溯源、失败类建议。先看偏差表与热区，
    再决定是否动生成器。
-3. **修复**：改动 `spec_to_schema_v3.mjs` / `vision.py` / `parse_meaxure.py` 的通用几何规则
-   （禁业务词硬编码）。
+3. **修复**：改动 v3 生成器的通用几何规则——`scripts/lib/v3_extract.mjs`（识别）/ `v3_shared.mjs`
+   （共享 helper）/ `v3_assemble.mjs`（组装），2026-09-21 起自 `spec_to_schema_v3.mjs`（现为 CLI 编排壳）
+   拆出——以及 `vision.py` / `parse_meaxure.py`（禁业务词硬编码）。
 4. **增量验证**：`run_round.mjs --round <新轮> --focus training/runs/<上轮> --inherit training/runs/<上轮>`
    只重跑焦点集（失败例 + 低分通过例），其余案例报告与截图从上一轮继承 → 新轮仍是**完整可比轮**
    （passRate 分母正确、`round_diff` 不会把未重跑案例算成 removed）。只重跑失败例用
@@ -378,6 +379,9 @@ node skills/card-skill-trainer/scripts/run_round.mjs \
 - `--resume`：续跑既有轮目录（已有报告的案例跳过，渲染会话懒启动）；进程被 kill 或渲染假死后不必整轮重来。
 - `--no-correct`：禁用布局校正器，裸测生成器真实水平（里程碑对照用）。
 - `--no-summary`：跳过收尾自动汇总（默认自动调 `score_round.mjs --quiet`，直接打出 pass/avgFid/roundGate）。
+- `--concurrency N`：并行渲染会话数（默认 2，上限 4；`1` 即旧串行行为）。每个 worker 持独立
+  Chrome + HTTP server（随机端口 / 唯一 userDataDir，多实例安全），worker 池按案例分派；
+  单案例异常隔离不变。吞吐敏感的全量轮保持默认，内存受限环境降为 1。
 - `--splits train,dev`：限定分区（迭代纪律见上文）。
 - `--only` / `--only-failed` / `--focus` 三者互斥，同时传会直接报错而不是静默取其一。
 
@@ -471,13 +475,18 @@ training/runs/<round>/
   slices/
   reports/
     <caseId>.json        ← 含 gateFailures / failureSignature / failureClass / exclusionCoverage
-                           与 layoutCorrections / correctorRejected 校正明细
+                           与 layoutCorrections / correctorRejected 校正明细；
+                           telemetry 字段：timings（阶段耗时 ms）/ stageErrors（阶段化错误）/
+                           usage（生成链路 LLM usage，预留）/ reviewTokensEst（归因证据包 token 估算）
     <caseId>.render.png  ← 最终渲染截图
     <caseId>.design.png  ← 设计稿参考图
     <caseId>.side.png    ← diagnose_case 并排对比图（按需生成）
     summary.json         ← 含 roundGate / roundGatePassed / correctorCoverage /
-                           gateFailureHistogram / failureClasses / highMaskCases
-    summary.md           ← 含晋级门禁表格、归因直方图与截图对比图廊
+                           gateFailureHistogram / failureClasses / highMaskCases /
+                           avgCaseMs / p50CaseMs / p95CaseMs / telemetry（速度·错误·token 汇总）
+    summary.md           ← 含晋级门禁表格、归因直方图、「速度与消耗」段与截图对比图廊
+    telemetry.json       ← 轮级 telemetry：墙钟 / 并发 / 阶段耗时聚合 / 渲染次数与会话重建 /
+                           阶段错误直方图 / LLM usage / 归因证据包 token 估算（run_round 收尾落盘）
     review-queue.jsonl
     semantic-review.jsonl
     inherited.json         ← --inherit 轮：继承来源与案例清单
@@ -487,4 +496,50 @@ training/runs/<round>/
     diagnosis.json         ← diagnose_case --out：批量诊断的机器可读证据包
 ```
 
+### 效率观测（telemetry，2026-09-25 起）
+
+训练的三类效率信号由 `run_round.mjs` 自动采集、`score_round.mjs` 聚合进 summary（口径实现：
+`lib/telemetry.mjs`，直测 `tools/tests/trainer-telemetry.test.mjs`）：
+
+1. **耗时**：每案例按阶段计时（parse / upstream / generate / autofix / slices / validate / lint /
+   render / reRender / pixel / score），轮级 `telemetry.json` 出阶段均值与墙钟吞吐
+   （`casesPerMinute`）。瓶颈定位：`render` 占比高 → 提 `--concurrency`；`reRender` 次数多 →
+   校正器覆盖率高，按「校正器纪律」沉淀规则；`pixel` 占比高 → 检查掩膜数量与图像尺寸。
+2. **错误**：阶段化登记（`stageErrors`，validate/lint/render/case 分开计次），轮级直方图区分
+   「工具链坏了」与「生成质量差」——前者修环境，后者走归因闭环。
+3. **token**：v3 生成器是纯规则引擎（0 LLM 调用），`usage` 字段为生成链路 LLM 化后预留（自动
+   累计 `meta.usage`）；训练闭环中真实发生的消耗是**失败案例的 Agent 在环多模态归因**——
+   `reviewTokensEst` 按「双图面积/750 + spec 文本/4 chars」估算归因证据包 input token（预算
+   参考，不进门禁）。降 token 的正道 = 提高还原度减少失败案例，而不是压缩证据包。
+
+> 口径只作效率观测，不参与 PASS_GATE / ROUND_GATE 任何判定；旧轮次报告缺字段时对应聚合自动跳过。
+
 `summary.md` 与 `next-round-plan.json` 是需要周期性查看的两份产物；如果所有门禁通过，可以完全不看。
+
+---
+### Input component was invisible to text-component fidelity（r038n 训练回灌）
+> lesson: `LESSON-20260826-043`  status: `promoted`
+
+Input 是可编辑文本承载组件，组件相似度应计入 text 与 controls 两个维度；不能只把 className=Text 当作文本组件，否则会反向奖励 display-text 而惩罚正确 Input 语义。
+
+
+---
+### ListLayout template reuse was scored as missing components（r039n 训练回灌）
+> lesson: `LESSON-20260826-046`  status: `promoted`
+
+组件评分必须按 ListLayout 数据项数展开模板内 Text/Image/Input/Button 计数；模板复用是正确实现，不能因 schema 只保存一份模板而判为组件丢失。
+
+
+---
+### card focus needs visual, annotation and agent semantic cross（r039n 训练回灌）
+> lesson: `LESSON-20260826-047`  status: `promoted`
+
+卡片候选由截图视觉、标注几何和 Agent 语义三方交叉验证；完整业务容器才可接受，对话气泡、单按钮、弹窗、toast 和底部抽屉必须拒绝或跳过。规则只使用通用结构信号，禁止业务词硬编码。
+
+
+---
+### pixel-diff-over-8%（seq4 训练回灌）
+> lesson: `seq4-l06`  status: `promoted`
+
+像素掩膜门必须环境感知：探针实测「回退栈宽/标注宽」fontMaskWiden > 1.06 即该字体在本机渲染环境不可得（PingFang SC 在 Windows 同样回退合成粗体/换族），家族名豁免会让最大像素热带（文本字形带 16-36%/带）漏掩，把像素门顶在 8% 门外并误逼生成器改字重/字号扭曲 spec；探针缺失回退家族名判据。掩膜只进像素 ratio 通道（pixelOnlyRects），structure/color 剖面仍只用硬排除掩膜，否则大掩膜会把 structure 打穿（实测 87→67）。
+

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

@@ -24,8 +24,9 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { PNG } from 'pngjs'
 import {
-  attributeFailure, evaluatePassGate, exclusionCoverage, failureSignature, MASK_REVIEW_THRESHOLD,
+  attributeFailure, evaluatePassGate, exclusionCoverage, failureSignature,
 } from './lib/scoring.mjs'
+import { pixelBands, pairDeviations, deriveHints } from './lib/diagnosis.mjs'
 
 const repoRoot = path.resolve(import.meta.dirname, '../../..')
 
@@ -118,72 +119,8 @@ function buildSideImage(designPng, renderPng, sidePath) {
   return sidePath
 }
 
-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
-  }
-  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++
-    }
-  }
-  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 }
-}
-
-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
-}
+// pixelBands / pairDeviations / deriveHints 已迁至 lib/diagnosis.mjs（run_round 与
+// diagnose_case 共用单一来源，避免两处漂移）；本脚本仅按需引入。
 
 async function main() {
   const results = []
@@ -302,23 +239,18 @@ async function main() {
         provHits = [{ error: String(e.message || e) }]
       }
 
-      // —— 5. 失败类建议 ——
+      // —— 5. 失败类建议（与 run_round 在环归因共用 deriveHints，单一口径）——
       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 抗锯齿/字体度量差异，接近噪声底')
+      const hints = deriveHints({
+        attribution: attribution ? { failureClass: attribution.failureClass, reason: attribution.reason } : null,
+        pixel: px,
+        fidelity: fid,
+        duplication: report.duplication || null,
+        coverage,
+        hotBands: bands.hotBands,
+        deviations,
+      })
 
       // —— 6. 输出 ——
       console.log('═══════════════════════════════════════════════════════════')

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * diagnosis.mjs — 失败案例结构化证据包的纯函数核心（2026-09-25）。
+ *
+ * 单一来源：run_round.mjs（在环归因，零额外渲染复用已有数据）与 diagnose_case.mjs
+ * （按需深度诊断，含 provenance 溯源）共用本模块，避免两处漂移。
+ *
+ * 导出：
+ *   - decodeBufferToPng(buf)         Buffer → PNG.sync 对象（失败返回 null）
+ *   - pixelBands(design, render, exclusions)   逐带像素差异率 + 热区带
+ *   - pairDeviations(specTexts, renderTexts)    标注几何 vs 渲染盒偏差表（dy/dx）
+ *   - deriveHints(ctx)               失败类建议（与评分口径同源）
+ *   - buildInlineDiagnosis(report, ctx)   run_round 在环归因用的轻量结构化包
+ *
+ * 设计约束：本模块只做纯计算，不触碰 Chrome / 文件系统 / 任何门禁口径。
+ * 图像解码只在 buildInlineDiagnosis 内按需发生，且仅针对「确实失败且像素可比对」的案例。
+ */
+import { PNG } from 'pngjs'
+import { MASK_REVIEW_THRESHOLD, exclusionCoverage } from './scoring.mjs'
+
+const norm = (value) => String(value || '').replace(/\s+/g, '')
+
+export function decodeBufferToPng(buf) {
+  try { return buf ? PNG.sync.read(buf) : null } catch { return null }
+}
+
+export 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
+  }
+  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++
+    }
+  }
+  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 }
+}
+
+export 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
+    let bestDist = Infinity
+    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
+      // Geometric tiebreaker: when multiple specs have same similarity (e.g. identical texts
+      // like two "转账计划"), prefer the nearest by center distance — crossed matching produces
+      // false huge dy/dx that misleads the diagnosis.
+      const dist = Math.hypot(((st.x||0)+(st.w||0)/2)-((rt.x||0)+(rt.w||0)/2), ((st.y||0)+(st.h||0)/2)-((rt.y||0)+(rt.h||0)/2))
+      if (score > bestScore + 1e-9 || (score >= bestScore - 1e-9 && dist < bestDist)) {
+        bestScore = score; best = { ...st, idx: i }; bestDist = dist
+      }
+    }
+    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
+}
+
+/**
+ * 失败类建议：与 lib/scoring.mjs 的归因/门禁口径同源，run_round 与 diagnose_case 共用。
+ * ctx: { attribution:{failureClass,reason}, pixel, fidelity, duplication, coverage, hotBands, deviations }
+ */
+export function deriveHints(ctx) {
+  const {
+    attribution = null, pixel = {}, fidelity = {}, duplication = null,
+    coverage = {}, hotBands = [], deviations = [],
+  } = ctx || {}
+  const num = (v, d = 4) => (typeof v === 'number' && Number.isFinite(v)) ? v.toFixed(d) : 'N/A'
+  const hints = []
+  if (attribution) hints.push(`归因 ${attribution.failureClass}：${attribution.reason}`)
+  if (pixel.bestAlignDy && Math.abs(pixel.bestAlignDy) >= 4) hints.push(`全局纵向偏移 dy=${pixel.bestAlignDy}：查行高/行距累积（Input 高度、行距标注优先、分割线渲染盒高）`)
+  if (hotBands.length && hotBands[0].pct >= 0.2) hints.push(`单带高热 (${(hotBands[0].pct * 100).toFixed(0)}%@y≈${hotBands[0].y})：查该区域语义块（换行折点/缺组件/结构错配）`)
+  if ((fidelity.components ?? 1) < 0.9) hints.push(`组件计数缺失 comp=${num(fidelity.components, 2)}：查语义消费（媒体未渲染/文本被吞/重复消费）`)
+  if ((duplication?.overall ?? 1) < 0.95) {
+    hints.push(`重影：查同源按钮/文本双路径渲染（${(duplication?.offenders || []).map((o) => `「${o.text}」x${o.rendered}/${o.annotated}`).join(' ')}）`)
+  }
+  const covTotal = coverage?.total ?? 0
+  if (covTotal >= MASK_REVIEW_THRESHOLD) {
+    hints.push(`掩膜覆盖 ${(covTotal * 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 抗锯齿/字体度量差异，接近噪声底')
+  return hints
+}
+
+function annDefectCount(upstream) {
+  if (!upstream) return 0
+  const ad = upstream.annotationDefects
+  if (Array.isArray(ad)) return ad.length
+  return typeof ad === 'number' ? ad : 0
+}
+
+/**
+ * run_round 在环归因用的轻量结构化包：复用 processCase 已算出的 report / 设计稿 buffer /
+ * 标注文本 / 渲染盒，零额外 Chrome 渲染。provenance（cid→生成器源码行）因需 SCHEMA_PROV
+ * 重生成，不在本包内——按需由 diagnose_case.mjs 深度补全。
+ *
+ * ctx: { designBuf, renderBuf, specTexts, renderedTexts }
+ *   specTexts:  run_round 过滤后的标注文本数组（含 rawText/x/y/w/h/fs）
+ *   renderedTexts: 渲染盒数组（含 text/x/y/w/h/cid，已过滤 Text/Input/Button）
+ */
+export function buildInlineDiagnosis(report, ctx) {
+  const { designBuf = null, renderBuf = null, specTexts = [], renderedTexts = [] } = ctx || {}
+  const designPng = designBuf ? decodeBufferToPng(designBuf) : null
+  const renderPng = renderBuf ? decodeBufferToPng(renderBuf) : null
+  const exclusions = report?.pixelExclusions || []
+  const bands = (designPng && renderPng)
+    ? pixelBands(designPng, renderPng, exclusions)
+    : { hotBands: [], diffRatio: null }
+
+  const specForDev = specTexts.map((el) => ({
+    text: norm(el.rawText ?? el.text ?? ''),
+    x: el.x ?? 0, y: el.y ?? 0, w: el.w ?? 0, h: el.h ?? 0,
+    fs: el.fs ?? el.textStyle?.fontSize ?? 14, lineHeight: el.lineHeight ?? null,
+  }))
+  const renderForDev = renderedTexts.map((el) => ({
+    text: el.text ?? '', x: el.x ?? 0, y: el.y ?? 0, w: el.w ?? 0, h: el.h ?? 0, cid: el.cid,
+  }))
+  const deviations = pairDeviations(specForDev, renderForDev)
+
+  const coverage = report?.exclusionCoverage || exclusionCoverage(exclusions)
+  const attribution = report?.failureClass
+    ? { failureClass: report.failureClass, reason: report.failureReason || '' }
+    : null
+  const hints = deriveHints({
+    attribution,
+    pixel: report?.pixel || {},
+    fidelity: report?.fidelity || {},
+    duplication: report?.duplication || null,
+    coverage,
+    hotBands: bands.hotBands,
+    deviations,
+  })
+
+  return {
+    gateFailures: report?.gateFailures || [],
+    failureClass: attribution?.failureClass || null,
+    failureReason: attribution?.reason || null,
+    metrics: {
+      fidelity: report?.fidelity?.overall ?? null,
+      pixel: report?.pixel?.ratio ?? null,
+      structure: report?.pixel?.structure ?? null,
+      dimension: report?.pixel?.dimension ?? null,
+      color: report?.pixel?.color ?? null,
+      position: report?.position?.overall ?? null,
+      components: report?.fidelity?.components ?? null,
+      duplication: report?.duplication?.overall ?? null,
+      bestAlignDy: report?.pixel?.bestAlignDy ?? null,
+    },
+    exclusionCoverage: coverage,
+    upstream: report?.upstream ? {
+      passed: report.upstream.passed,
+      annotationCompleteness: report.upstream.annotationCompleteness,
+      textRetention: report.upstream.textRetention,
+      structuralFocus: report.upstream.structuralFocus,
+      annotationDefects: annDefectCount(report.upstream),
+    } : null,
+    hotBands: bands.hotBands.slice(0, 8),
+    deviations: deviations.slice(0, 10),
+    layoutCorrections: report?.layoutCorrections || [],
+    correctorRejected: report?.correctorRejected || null,
+    hints,
+  }
+}

package/dist/vendored/skills/card-skill-trainer/scripts/lib/layout-correction-sim.mjs

@@ -0,0 +1,62 @@
+// Layout-correction rigid-body simulation for the trainer's reject fast-path.
+//
+// When correctCardLayout only adjusts paddingTop (Y axis) inside a vertical Column,
+// the correction is an exact rigid body shift: shifting child#i by Δ also shifts every
+// later sibling by the cumulative Δ. The same logic extends to paddingLeft (X axis):
+// a child's paddingLeft change shifts that child's whole subtree horizontally, but —
+// unlike Y — does NOT cascade to later siblings in a vertical flow (each child keeps
+// its own independent horizontal padding). So X deltas are per-child and non-cumulative,
+// while Y deltas accumulate across siblings.
+//
+// Keeping this here (instead of inline in run_round.mjs) makes the admit/translate rules
+// unit-testable without spinning up Chrome. Zero gate behavior changes: the simulator
+// only decides whether a real re-render can be skipped; the final keep/revert decision
+// always goes through the real position + pixel guard.
+
+/**
+ * Whether the rigid-body reject fast-path may replace a real re-render.
+ * @param {Array} adjustments entries pushed by correctCardLayout (axis 'y'|'x', rigidSafe)
+ * @param {Map} cidToChild cid -> child index (built inside correctCardLayout)
+ * @param {Array} [children] card column direct children (to exclude AbsoluteLayout)
+ */
+export function canSimulateReject(adjustments, cidToChild, children) {
+  if (!adjustments?.length || !cidToChild) return false
+  if (!adjustments.every((a) => a.rigidSafe !== false && (a.axis === 'y' || a.axis === 'x'))) return false
+  // AbsoluteLayout children break the simple rigid model (their own left/positioning
+  // context means paddingLeft/paddingTop do not translate the subtree predictably).
+  if (children && !children.every((c) => c.name !== 'AbsoluteLayout')) return false
+  return true
+}
+
+/**
+ * Apply the rigid-body deltas to rendered boxes, returning shifted copies.
+ * Boxes whose cid is not mapped to a child are returned unchanged.
+ * @returns {{ shifted: Array, appliedAxes: Set<string> }}
+ */
+export function simulateLayoutCorrection(boxes, adjustments, cidToChild) {
+  const deltasY = new Map()
+  const deltasX = new Map()
+  const appliedAxes = new Set()
+  for (const a of adjustments || []) {
+    if (a.axis === 'y') {
+      deltasY.set(a.childIndex, (deltasY.get(a.childIndex) || 0) + (a.to - a.from))
+      appliedAxes.add('y')
+    } else if (a.axis === 'x') {
+      // X is per-child, no cross-sibling cascade.
+      deltasX.set(a.childIndex, (deltasX.get(a.childIndex) || 0) + (a.to - a.from))
+      appliedAxes.add('x')
+    }
+  }
+  const shiftForY = (idx) => {
+    let acc = 0
+    for (const [i, d] of deltasY) if (i <= idx) acc += d
+    return acc
+  }
+  const shiftForX = (idx) => deltasX.get(idx) || 0
+  const shifted = (boxes || []).map((b) => {
+    const idx = cidToChild.get(b.cid)
+    if (idx == null) return b
+    return { ...b, y: b.y + shiftForY(idx), x: b.x + shiftForX(idx) }
+  })
+  return { shifted, appliedAxes }
+}

package/dist/vendored/skills/card-skill-trainer/scripts/lib/paradigm-router.mjs

@@ -0,0 +1,76 @@
+// paradigm-router.mjs — 把高频失败签名映射到已沉淀的生成器通用范式引用。
+//
+// 用途：plan_next_round 的 `same-signature-3-rounds` 信号原本只说「脚本补丁无效，
+// 需升级 Skill 级范式」——笼统、Agent 仍需从零救火。本模块把维度级签名（不认业务词）
+// 路由到已落盘的 recipes 章节 / v3 链路铁律 / 生成器识别 intent，让 Agent 直接套用范式，
+// 把迭代预算从「每失败例救火」转向「每签名沉淀一条通用规则」（对应 trainer 效率维度三）。
+//
+// 失败签名 key 形如 `${failureClass}/${signature}`：
+//   failureClass ∈ {PARSER, DSL, STYLE, DATA, ASSET, EVALUATOR}
+//   signature   是门维度（structure/position/overall/color/pixelDiff/components/...）
+// 纯维度信号粗分模式，契合 skill 纯净铁律（禁硬编码业务实体名称）。
+
+export const PARADIGMS = {
+  // STYLE + 结构/位置/整体维度低 = 整块漏建（图表/雷达/分区）
+  'chart-radar-block': {
+    label: '图表/雷达/分区整块漏建',
+    recipeSections: [
+      'recipes.md §1 Canvas 画布标题头（onMeasured 自绘）',
+      'recipes.md §10 Canvas 甜甜圈/环形比例图（donut chart）',
+      'v3_assemble.mjs 散点带拓扑（中心媒体 + 环绕胶囊簇）',
+    ],
+    generatorIntents: [
+      'extract_handcrafted.py canvas_chart（Canvas+onMeasured 识别）',
+      'resolve_card_template.mjs 「雷达图 仪表盘」模板',
+      'v3_shared.mjs R62 图表绘制层序铁律（坐标/参考系/数据图元分层）',
+    ],
+    action: '套用图表通用范式（Canvas 自绘 + onMeasured），禁止用 Text/Image 堆砌或整块漏建；治本在 IR 路径强制把图表几何信号路由到 canvas_chart 识别',
+  },
+  // STYLE + 像素/色维度低 = 底色整层错涂
+  'bg-fill': {
+    label: '底色/背景整层错涂',
+    recipeSections: ['spec_audit.mjs 底色采样（角部 + gutter 众数聚类，禁用 center 采样）'],
+    generatorIntents: ['spec_audit fill 角部 + gutter 众数聚类'],
+    action: '底色取角部/边缘众数，禁止照抄 center 点（雷达/图表中心色常被误当卡底色）；治本在 spec_audit 采样逻辑',
+  },
+  // DSL + 组件计数缺口 = 媒体/列表漏建
+  'list-or-chart-missing': {
+    label: '组件/图表计数缺口（媒体或列表漏建）',
+    recipeSections: ['ir-format.md §2f 列表数组化', 'recipes.md §10 图表范式'],
+    generatorIntents: ['bindings.mjs collectArrayConsumption', 'canvas_chart intent'],
+    action: '先查 canvas_chart 识别与雷达/环图数据绑定（radarData/donutData），再查列表数组化；禁止静态展开或整块漏建',
+  },
+  // 兜底：仍要求沉淀通用规则，但无既有范式可直引
+  generic: {
+    label: '通用门维度失败',
+    recipeSections: [],
+    generatorIntents: [],
+    action: '升级 Skill 级范式：沉淀一条通用规则而非逐例救火',
+  },
+}
+
+/** 基于 failureClass + 门维度签名粗分范式模式（不依赖业务词）。 */
+export function classifyParadigm(signatureKey) {
+  const [failureClass = '', signature = ''] = String(signatureKey || '').split('/')
+  const sig = signature.toLowerCase()
+  if (failureClass === 'STYLE' && /^(structure|position|overall)$/.test(sig)) return 'chart-radar-block'
+  if (failureClass === 'STYLE' && /^(pixeldiff|color)$/.test(sig)) return 'bg-fill'
+  if (failureClass === 'DSL' && sig === 'components') return 'list-or-chart-missing'
+  return 'generic'
+}
+
+/** 取范式引用详情，未知 key 回退 generic。 */
+export function paradigmRefs(key) {
+  return PARADIGMS[key] || PARADIGMS.generic
+}
+
+/** 给 same-signature-3-rounds 信号生成增强 detail（含范式模式 + 引用 + 行动项）。 */
+export function enrichSameSignatureDetail(item) {
+  const patternKey = classifyParadigm(item.signature)
+  const refs = paradigmRefs(patternKey)
+  const base = `签名 ${item.signature} 在 ${item.occurrences} 轮重复出现（${item.rounds.join(' → ')}）：脚本补丁无效，需升级 Skill 级范式。`
+  const parts = [base, `模式=${refs.label}。${refs.action}。`]
+  if (refs.recipeSections.length) parts.push(`参照：${refs.recipeSections.join('；')}。`)
+  if (refs.generatorIntents.length) parts.push(`生成器侧已沉淀：${refs.generatorIntents.join('；')}。`)
+  return { pattern: patternKey, detail: parts.join('') }
+}

package/dist/vendored/skills/card-skill-trainer/scripts/lib/pixel-worker-runner.mjs

@@ -0,0 +1,31 @@
+// 像素评分 worker 运行器（P0-2）：在独立线程内执行 imageFidelity，避免阻塞主事件循环。
+// 纯 JS + pngjs，无 DOM 依赖，可直接在 worker_threads 内 import。
+// 计算异常就地捕获并回传 error，由主侧 scorePixel 触发同步回退，保证训练轮不崩。
+import { parentPort } from 'node:worker_threads'
+import { imageFidelity } from './scoring.mjs'
+
+parentPort.on('message', ({ id, payload }) => {
+  try {
+    // Buffer 经 worker_threads 结构化克隆后可能退化为 Uint8Array，PNG.sync.read 仍需真 Buffer；
+    // Buffer.from 对已是 Buffer 的入参仅复制、对 Uint8Array 则还原，两路都安全。
+    const designBuffer = Buffer.isBuffer(payload.designBuffer)
+      ? payload.designBuffer
+      : Buffer.from(payload.designBuffer)
+    const renderBuffer = Buffer.isBuffer(payload.renderBuffer)
+      ? payload.renderBuffer
+      : Buffer.from(payload.renderBuffer)
+    const result = imageFidelity(
+      designBuffer,
+      renderBuffer,
+      payload.exclusionRects,
+      payload.pixelOnlyRects,
+      payload.opts,
+    )
+    parentPort.postMessage({ id, result })
+  } catch (error) {
+    parentPort.postMessage({
+      id,
+      error: { message: String(error?.message || error), stack: String(error?.stack || '') },
+    })
+  }
+})