cardbuddy 0.15.0 → 0.17.0

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

@@ -49,6 +49,22 @@ async function getBrowser() {
   return browserPromise
 }
 
+/** 立即关闭单例浏览器并复位（测试 / 脚本收尾用；生产路径靠空闲 5 分钟自动关） */
+async function closeBrowser() {
+  if (idleTimer) {
+    clearTimeout(idleTimer)
+    idleTimer = null
+  }
+  const p = browserPromise
+  browserPromise = null
+  if (p) {
+    try {
+      const b = await p
+      if (b && typeof b.close === 'function') await b.close()
+    } catch (_) { /* 关闭失败忽略 */ }
+  }
+}
+
 function resetIdleTimer() {
   if (idleTimer) clearTimeout(idleTimer)
   idleTimer = setTimeout(async () => {
@@ -112,6 +128,7 @@ export {
   NAV_TIMEOUT_MS,
   SETTLE_MS,
   getBrowser,
+  closeBrowser,
   serialize,
   openCardScreen,
 }

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

@@ -8,6 +8,54 @@ import { deleteJournal, turnsDir } from './turnJournal.js'
 import { log } from './logger.js'
 import { buildDataFromSchema } from './buildDataFromSchema.js'
 
+/**
+ * 空白卡根样式：margin / padding / gap 显式归零（而非「未设置」）。
+ * 渲染器对无显式样式的容器会注入默认值（padding:2px / gap:4px / justify-content:center），
+ * 空白卡必须显式归零压掉注入，否则新卡自带隐性间距且属性面板显示「未设置」。
+ * 形状取自存量卡根节点（见 style-meta.json：marginType / paddingType，'0' = 全边统一值）。
+ * 同一形状还有两份内联副本（禁跨包 import）：skills/dsl-card-generator lib/scaffold.mjs、
+ * skills/finmall-card-sync api_batch_sync.mjs 的 buildBlankSchema —— 改这里必须同步改那两处。
+ */
+function blankResetStyle() {
+  return {
+    properties: [
+      {
+        itemId: '100',
+        itemKey: 'flex',
+        itemValueFrom: '0',
+        itemValue: {},
+        itemChildren: {
+          properties: [{ itemId: '003', itemKey: 'gap', itemValueFrom: '0', itemValue: '0' }],
+        },
+      },
+      {
+        itemId: '400',
+        itemKey: 'padding',
+        itemValueFrom: '0',
+        itemValue: {},
+        itemChildren: {
+          properties: [
+            { itemId: '001', itemKey: 'paddingType', itemValueFrom: '0', itemValue: '0' },
+            { itemId: '002', itemKey: 'padding', itemValueFrom: '0', itemValue: '0' },
+          ],
+        },
+      },
+      {
+        itemId: '500',
+        itemKey: 'margin',
+        itemValueFrom: '0',
+        itemValue: {},
+        itemChildren: {
+          properties: [
+            { itemId: '001', itemKey: 'marginType', itemValueFrom: '0', itemValue: '0' },
+            { itemId: '002', itemKey: 'margin', itemValueFrom: '0', itemValue: '0' },
+          ],
+        },
+      },
+    ],
+  }
+}
+
 /**
  * 单张卡片 / 卡片列表的按需读取 / 写回服务端处理（dev 下实时读磁盘，无缓存）。
  * - GET  /__cards ：实时扫描 src/cards/* 目录，返回卡片列表 [{id,name,pageId}]。
@@ -344,7 +392,7 @@ export function createCardFilesMiddleware({ root, notify = null }) {
             view: {
               width: '375',
               className: 'Root',
-              style: { properties: [] },
+              style: blankResetStyle(),
               properties: [],
               eventactions: [],
               components: [],

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

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { takeScreenshot } from './screenshot.js'
+import { takeScreenshot, generateCardCover } from './screenshot.js'
+import { serialize, MAX_QUEUED } from './browser.js'
 
 /**
  * 卡片预览图本地静态服务：把卡片目录下的「同名预览图」映射为
@@ -14,6 +15,15 @@ import { takeScreenshot } from './screenshot.js'
  * 若卡片目录没有同名预览图，则回退到实时无头截图（takeScreenshot，复用 /__screenshot
  * 同一套渲染内核），保证任何卡片都能出预览。截图失败（如缺 Chrome）则 404，
  * 由调用方回退占位。仅服务 src/cards 下的卡片预览图，禁止目录穿越。
+ *
+ * POST /__card-image/<id>：为该卡生成封面预览图并写盘（顶栏「预览图」按钮触发）。
+ * 无头渲染磁盘态 schema → 透明底、与卡片实际渲染尺寸 1:1 的 PNG → 覆盖写 src/cards/<id>/<id>.png。
+ * 用于手动搭建 / 生成卡片后补齐封面：省去手工截图 + 裁切。约定：
+ * - 未保存的编辑器改动不参与渲染，前端负责先落盘再调用；
+ * - 同 id 其它扩展名的旧预览图（jpg/webp 等）一并清除，保证「同名预览图」单一来源
+ *   （GET 按 readdir 顺序取第一个同名位图，双封面并存会让新 PNG 输给陈旧旧图）；
+ * - 空白卡（schema 无 components）拒绝生成（422），与 GET 回退 404 的语义一致；
+ * - 原子写（临时文件 + rename），并发读取不会拿到半截 PNG。
  */
 
 const MIME = {
@@ -46,6 +56,98 @@ export function createCardImageMiddleware({ root }) {
     if (!dir.startsWith(cardsRoot + path.sep) && dir !== cardsRoot) return next()
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return next()
 
+    // POST：生成封面预览图并覆盖写 <id>.png（顶栏「预览图」按钮触发，见文件头注释）
+    if ((req.method || 'GET').toUpperCase() === 'POST') {
+      // 空白卡（schema 无 components）截出来是无意义纯透明图：直接拒绝
+      let cardWidth = 375
+      try {
+        const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+        const comps = schema && schema.view && schema.view.components
+        if (Array.isArray(comps) && !comps.length) {
+          res.statusCode = 422
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(
+            JSON.stringify({ error: 'empty-card', message: '空白卡（无组件）没有可预览的内容，不生成预览图' }),
+          )
+        }
+        const w = parseInt((schema && schema.view && schema.view.width) || '', 10)
+        if (w > 0) cardWidth = w
+      } catch {
+        /* schema 缺失 / 损坏：按默认卡宽走，渲染失败会有结构化报错 */
+      }
+
+      const shot = await serialize(() => generateCardCover(id, { width: cardWidth }))
+      if (shot.tooBusy) {
+        res.statusCode = 429
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify({ error: 'too-busy', message: '截图队列已满（并发上限 ' + MAX_QUEUED + '），请稍后重试' }),
+        )
+      }
+      if (!shot.buffer) {
+        res.statusCode = shot.code || 503
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ error: shot.error, message: shot.message, fix: shot.fix }))
+      }
+
+      const file = path.join(dir, id + '.png')
+      const overwritten = fs.existsSync(file)
+      // 原子写：先落临时文件再 rename，并发读取（网格缩略图）不会拿到半截 PNG
+      const tmp = file + '.tmp'
+      fs.writeFileSync(tmp, shot.buffer)
+      fs.renameSync(tmp, file)
+      // 清掉同 id 其它扩展名的旧预览图：GET 按 readdir 顺序取第一个同名位图，
+      // 双封面并存会让「刚生成的 PNG」可能输给陈旧的 jpg/webp（单一来源纪律）
+      for (const entry of fs.readdirSync(dir)) {
+        const dot = entry.lastIndexOf('.')
+        if (dot < 0) continue
+        const base = entry.slice(0, dot)
+        const ext = entry.slice(dot).toLowerCase()
+        if (base.toLowerCase() === id.toLowerCase() && MIME[ext] && entry !== id + '.png') {
+          try {
+            fs.unlinkSync(path.join(dir, entry))
+          } catch {
+            /* 清理失败不阻塞：多一张旧图只是回退序靠前，不影响本次交付 */
+          }
+        }
+      }
+
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(
+        JSON.stringify({
+          ok: true,
+          id,
+          width: shot.width,
+          height: shot.height,
+          file: 'src/cards/' + id + '/' + id + '.png',
+          overwritten,
+        }),
+      )
+    }
+
+    // GET ?probe=1：轻量探测「同名预览图是否已存在」——只 readdir、命中即返回，
+    // 不触发回退截图。供顶栏「截图」按钮在覆盖已有封面之前弹二次确认。
+    const q = new URL(req.url, 'http://localhost')
+    if (q.searchParams.get('probe') === '1') {
+      let found = null
+      for (const entry of fs.readdirSync(dir)) {
+        const dot = entry.lastIndexOf('.')
+        if (dot < 0) continue
+        const base = entry.slice(0, dot)
+        const ext = entry.slice(dot).toLowerCase()
+        if (base.toLowerCase() === id.toLowerCase() && MIME[ext]) {
+          found = 'src/cards/' + id + '/' + entry
+          break
+        }
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify({ exists: !!found, file: found }))
+    }
+
     // 取与 id 同名的位图（大小写不敏感，扩展名见 MIME）
     let file = null
     for (const entry of fs.readdirSync(dir)) {
@@ -84,7 +186,6 @@ export function createCardImageMiddleware({ root }) {
 
     // 无同名预览图：回退实时无头截图（复用 /__screenshot 渲染内核）。
     // width 由查询参数决定（默认 390），与 /__screenshot 一致。
-    const q = new URL(req.url, 'http://localhost')
     const width = parseInt(q.searchParams.get('width') || '390', 10) || 390
     const shot = await takeScreenshot(id, width, 'png')
     if (!shot || !shot.buffer) {

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/server/core/screenshot.js

@@ -12,6 +12,25 @@ import { getBrowser, serialize, openCardScreen, MAX_QUEUED } from './browser.js'
  * 浏览器单例/页面加载逻辑已抽到 ./browser.js，与 /__bbox 共用同一实例。
  */
 
+/**
+ * 压掉编辑器壳层的悬浮物（AI FAB / toast / 抽屉面板 / 右键菜单等 position:fixed 元素）。
+ * 元素截图（ElementHandle.screenshot）截的是页面合成结果：任何叠在目标区域上的
+ * fixed 悬浮物都会被一起画进去 —— 「封面截图把 ai-fab 圆钮截进去」事故的根因。
+ * 按 computed position 判定而非类名清单：悬浮组件会不断增加，清单式每加一个就漏一个。
+ * 卡片自身（.ce_root 子树内）的 fixed 定位属于卡片设计，保留。页面随后即 close，无需恢复。
+ * （导出仅为测试可断言其 DOM 语义。）
+ */
+export async function hideFloatingOverlays(page) {
+  await page.evaluate(() => {
+    document.querySelectorAll('body *').forEach((el) => {
+      if (el.closest('.ce_root')) return
+      if (getComputedStyle(el).position === 'fixed') {
+        el.style.setProperty('visibility', 'hidden', 'important')
+      }
+    })
+  })
+}
+
 /**
  * 对单卡截图。纯函数、无 HTTP。任何失败都返回 { error, code, message, ... } 而非抛出。
  * @param {string} id 卡片 id
@@ -42,6 +61,7 @@ export async function takeScreenshot(id, width, format) {
       if (!screen) {
         return { error: 'capture-target-not-found', code: 500, message: '.phone__screen 元素未找到' }
       }
+      await hideFloatingOverlays(page)
 
       const buf = await screen.screenshot({ type: 'png' })
       if (format === 'json') {
@@ -76,6 +96,80 @@ export async function takeScreenshot(id, width, format) {
   }
 }
 
+/**
+ * 生成卡片封面预览图：透明底（不含编辑器外壳背景色）、尺寸 = 卡片实际渲染尺寸 1:1。
+ * 与 takeScreenshot 的三点差异：
+ * - deviceScaleFactor:1 —— 截图像素 = CSS 像素（takeScreenshot 是 2 倍视网膜）；
+ * - 截图目标是卡片根元素 .ce_root —— .phone__screen 是固定高度的手机屏滚动容器，
+ *   直截会带大片空白；.ce_root 高度即内容实际高度；
+ * - omitBackground + 透明化外壳底色（chrome=off 下手机屏固定挂 --bg-white），
+ *   产出透明底 PNG；卡片自身根节点的背景 / 渐变属于卡片设计，保留。
+ * 纯函数、无 HTTP、不写盘：返回 { buffer, width, height }，落盘由调用方（/__card-image POST）负责。
+ * 任何失败返回 { error, code, message, fix? } 结构化结果，不抛出（与 takeScreenshot 同约定）。
+ */
+export async function generateCardCover(id, { width: cardWidth = 375 } = {}) {
+  let browser
+  try {
+    browser = await getBrowser()
+  } catch (e) {
+    return {
+      error: 'browser-launch-failed',
+      code: 503,
+      message: String((e && e.message) || e),
+      fix: '系统 Chrome 未找到或未启动。请安装 Google Chrome，并确保 playwright 以 channel:"chrome" 启动（本端点固定使用该通道）。',
+    }
+  }
+
+  let context
+  try {
+    context = await browser.newContext({
+      viewport: { width: cardWidth + 80, height: 900 },
+      deviceScaleFactor: 1,
+    })
+    const { page, screen } = await openCardScreen(context, id)
+    try {
+      if (!screen) {
+        return { error: 'capture-target-not-found', code: 500, message: '.phone__screen 元素未找到' }
+      }
+      // 压掉编辑器外壳的底色与投影：omitBackground 只能去掉「页面默认白底」，管不到
+      // 元素自己的样式 —— .app（深色）/.phone（径向渐变）/.phone__screen--bg-white 这些
+      // 祖先/外壳会把不透明底画在卡片后面，整条祖先链必须一并透明化。
+      await page.addStyleTag({
+        content:
+          'html,body,.app,.app__stage,.phone,.phone__frame,.phone__scaler,.phone-viewport,.phone__screen' +
+          '{background:transparent!important;background-image:none!important;box-shadow:none!important}',
+      })
+      await hideFloatingOverlays(page)
+      const cardEl = await page.$('.phone__screen .ce_root')
+      if (!cardEl) {
+        return { error: 'card-root-not-found', code: 500, message: '.ce_root 卡片根元素未找到' }
+      }
+      const buf = await cardEl.screenshot({ type: 'png', omitBackground: true })
+      const box = await cardEl.boundingBox()
+      return {
+        buffer: buf,
+        width: box ? Math.round(box.width) : null,
+        height: box ? Math.round(box.height) : null,
+      }
+    } finally {
+      await page.close().catch(() => {})
+    }
+  } catch (e) {
+    // 导航超时 / data-card-ready 未出现 / 截图异常：转成结构化错误，绝不向上抛
+    const isTimeout = /Timeout\s*\d+ms exceeded/.test(String((e && e.message) || e))
+    return {
+      error: isTimeout ? 'render-wait-timeout' : 'screenshot-failed',
+      code: isTimeout ? 504 : 500,
+      message: String((e && e.message) || e),
+      fix: isTimeout
+        ? '卡片首帧未在限定时间内挂载（data-card-ready 未出现）。检查该卡是否在 chrome=off 模式下渲染报错，或卡片依赖真实运行时数据（customAction/RPC）而无法在纯渲染模式落定。'
+        : undefined,
+    }
+  } finally {
+    if (context) await context.close().catch(() => {})
+  }
+}
+
 export function createScreenshotMiddleware({ root }) {
   return async function screenshotMiddleware(req, res, next) {
     const pathname = decodeURIComponent((req.url || '').split('?')[0])

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）。只重跑失败例用
@@ -102,7 +103,7 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 
 - `annotationCompleteness`：画板内叶子标注是否被完整归属到聚焦卡。
 - `textRetention`：卡片内文案是否被完整保留。
-- `structuralFocus`：候选是否具备卡片级结构，而不是气泡、按钮条或空壳。
+- `structuralFocus`：候选是否具备卡片级结构，而不是气泡、按钮条或空壳。**图像卡通道（r264 起）**：整卡被设计稿导成一张大切图时（解析器兜底产 1 张卡、卡内只有该 slice），`sliceAreaRatio ≥ 0.6` 即视为结构成立，按正常像素/尺寸门评分。
 - `trainingEligible`：弹窗、toast、底部抽屉、纯文本板（`artboardType=text_only`，整板只有对话/问答/提示文字）必须为 false。
 
 任一门失败优先归因 `PARSER`，修复目标是 `vision.py` / `parse_meaxure.py` / `boundary.json` 的通用几何规则，不允许用业务名救某个样本。
@@ -177,7 +178,7 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 > 基线载体是**冻结锚点轮目录**（含 `reports/` 全量证据）+ **入库压缩锚点** `training/anchors/<round>.json`
 > （P0-2 起：干净克隆与 CI 上唯一的锚点载体，`round_diff.mjs` / `plan_next_round.mjs` 都直接吃它）。
 > 本 Skill 目录下的历史 `baselines/v3-r0*.json` 范式已废弃并删除（指标快照改由 summary.json + 压缩锚点承载）。
-> 晋级 = 新轮成为下一冻结锚点候选，在 `training/plans/` 记录轮号与指标，并重新生成压缩锚点入库。
+> 晋级 = 新轮成为下一冻结锚点候选，通用规则回灌 `training/lessons/lessons.jsonl`（`sink_rules.mjs`），并重新生成压缩锚点入库。
 
 ### 泛化盲测门（generalization gate）
 
@@ -196,7 +197,7 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 **固定跨批次晋级盲测集**（解决单批次 eval/holdout 只有 2 例、凑不出 24 例的问题）：
 用 `build_sample.mjs` 从 v6 + v7 全量池各抽代表，合并成 `training/datasets/blindset/train-set.jsonl`
 （≥24 例，结构聚类去重后覆盖列表/表单/结果/媒体/空状态），晋级轮一律用它盲测，
-并在 `training/plans/` 记录该盲测集的 provenance 与轮号。盲测集**不参与任何修复迭代**。
+并在 `training/lessons/lessons.jsonl` 记录该盲测集的 provenance 与轮号。盲测集**不参与任何修复迭代**。
 ### 收敛检测与早停
 
 当出现以下任一信号时，**停止脚本微调，转而修订 Skill 文档规则或范式**：
@@ -237,7 +238,7 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
 
 - v5（转账二批次 17 代表）r199 = 14/17、avgFid 95.8%、avgPix 4.0%；
 - v6（存款+理财 30 代表）r200 = 4/30、avgFid 81.7%——新布局族缺口，仍是泛化主战场
-  （见 `training/plans/v6-dataset-baseline.md`、`v6-iteration-plan.md`）；
+  （见 `training/datasets/v6/dataset-summary.json` 与本节指标水位）；
 - v7（焦点集）r243→r262 逐例收敛：`945b562caad1f0f4` 散点带/段落壳/评分仪表盘通道落地后
   pix 0.1348→0.0681、pos 0.532→0.905、comp 0.852；`86ae6d41957935d8` 渐变壳绑定修正后 pix 0.055。
   对应规则见 `dsl-card-generator/references/generation_pitfalls.md §21-24` 与 lessons `r255-l01..l05` / `r261-l01`。
@@ -271,7 +272,7 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
 3. 修复优先级：可见媒体与重影 → 语义顺序与纵向节奏 → 背景/圆角/留白 → 未见样本泛化。
 4. 缺失/状态错切图优先画板裁切（`cropSlice`，含宽条切图与纯矢量 logo 组；矩形内有文本叠加或背景级大矩形禁裁），裁切不可用才纯色近似并标记缺陷；弥散/光晕类纹理特事特办，计入局部还原度豁免。
 5. 焦点样本通过后必须复跑冻结锚点全量；每 3 轮做不少于 24 例未见样本盲测（固定跨批次盲测集见上文）。
-6. 晋级门、焦点 ID 和产物路径以 `training/plans/` 下最新 plan 与本轮 `reports/next-round-plan.json` 为准。
+6. 晋级门、焦点 ID 和产物路径以本轮 `reports/summary.json` 与 `training/anchors/<最新>.json` 为准。
 7. 新布局通道（如散点带 §21、段落壳归属 §22、行锚点/尾随切片 §23）落盘生成器后，同步 lessons.jsonl + generation_pitfalls/quickref/previewer_contract，并复跑冻结锚点确认 0 回归；通道判据只认几何/样式结构，不认业务词。
 
 训练清单可记录样本 ID 和画板名作为证据；运行时代码、Skill 判定和校验器不得引用业务词、画板名或样本专属文案。
@@ -290,7 +291,7 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
 7. 通用规则写入 `training/lessons/lessons.jsonl`（新格式 `{lessonId, signature, failureClass, evidenceCases,
    rule, targetFiles, status, round}`；`plan_next_round.mjs` 产的 `lesson-drafts.jsonl` 是待补 rule 的草稿），
    并同步到对应 Skill 的 `SKILL.md` 或 `references/`；业务词、画板名和样本专属文案不得进入规则。
-8. 通过后以新轮目录作为下一冻结锚点候选并登记 `training/plans/`，同时重生成压缩锚点入库
+8. 通过后以新轮目录作为下一冻结锚点候选，回灌 lessons 并重生成压缩锚点入库
    （`training/anchors/<round>.json`）；未通过的候选规则保持 `candidate`，不修改正式 Skill 行为。
 9. `npm run ci` 全绿（9 硬门禁：card-check / smoke-preview / verify-event-model / verify-model-expose /
    magic-values / regress-data / unit-tests / mcp-doc-sync / lint-ratchet；另有 regress-fidelity、lint 两道软门禁）：评分尺子改动被
@@ -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` 三者互斥，同时传会直接报错而不是静默取其一。
 
@@ -459,7 +463,7 @@ python3 training/tools/split_report.py <runDir> [topN]    # 按 split 聚合指
 
 > `training/datasets/`、`training/runs/` 仍被 gitignore（体积 + 源稿版权）。数据集可复现性靠
 > `dataset-summary.json` 的 `provenance`（sourceRoot / sourceNames / toolchainRev / 解析器参数）
-> 与 `training/plans/` 的轮次记录；锚点回归靠冻结轮目录（`training/runs/r176`）**或入库压缩锚点**
+> 与 `training/lessons/lessons.jsonl` 的轮次记录；锚点回归靠冻结轮目录（`training/runs/r176`）**或入库压缩锚点**
 > （`training/anchors/r176.json`，干净克隆唯一可用载体）。已入库的训练设施还有
 > `training/tools/*`、`training/reports/font-metrics.json`、`training/fixtures/ui-drafts/`（保真度软门禁兜底稿）。
 
@@ -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）。
+