cardbuddy 0.14.3 → 0.16.0

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

@@ -1,14 +1,14 @@
----
-name: card-skill-trainer
-description: 无人值守联合训练 sketch-spec-to-card 与 dsl-card-generator。扫描桌面已确认 Sketch 导出，评估卡片聚焦与标注契约，批量生成 schema/data，渲染截图，执行结构、事实与像素评分，输出失败归因和下一轮规则候选。触发词：卡片训练、自动训练、训练闭环、skill 回归、还原度优化。
----
-
-# Card Skill Trainer
-
-## 定位
-
-本 Skill 联合训练 `sketch-spec-to-card` 和 `dsl-card-generator`：前者负责卡片聚焦与标注契约，后者负责 DSL 还原，两者都被当作被评测对象。
-
+---
+name: card-skill-trainer
+description: 无人值守联合训练 sketch-spec-to-card 与 dsl-card-generator。扫描桌面已确认 Sketch 导出，评估卡片聚焦与标注契约，批量生成 schema/data，渲染截图，执行结构、事实与像素评分，输出失败归因和下一轮规则候选。触发词：卡片训练、自动训练、训练闭环、skill 回归、还原度优化。
+---
+
+# Card Skill Trainer
+
+## 定位
+
+本 Skill 联合训练 `sketch-spec-to-card` 和 `dsl-card-generator`：前者负责卡片聚焦与标注契约，后者负责 DSL 还原，两者都被当作被评测对象。
+
 ```text
 build_dataset.py → build_sample.mjs（结构去重抽样）
                  → run_round.mjs（收尾自动调 score_round：summary.json/md + roundGate）
@@ -20,37 +20,37 @@ build_dataset.py → build_sample.mjs（结构去重抽样）
 人工不阻塞主流程。连续回归、渲染器崩溃或置信度低于阈值的样本会进入 `review-queue.jsonl`（带 `failureClass` 与未达标维度，可直接聚类）；像素/结构失败同时生成 `semantic-review.jsonl`，由执行 Skill 的 Agent 在下一轮自动做多模态归因，再回灌到 `dsl-card-generator` 或 `sketch-spec-to-card` 的文档规则。脚本负责提出证据和复跑回归，不负责把业务语义硬编码。
 
 **口径唯一来源**：单案例门（`PASS_GATE`）、轮级门（`ROUND_GATE_TARGETS`）、盲测门（`GENERALIZATION_GATE`）、失败签名与失败类归因全部定义在 `scripts/lib/scoring.mjs`；轮次/锚点读取与轮间对比定义在 `scripts/lib/runs.mjs`。run_round / score_round / round_diff / plan_next_round / diagnose_case 一律 import 复用，**禁止在脚本里另写一套阈值**——`tools/tests/scoring.test.mjs` 会反向断言本文档验收表里的数字与 `PASS_GATE` 逐条一致，改门必须同步改文档。
-
-## 源码隔离铁律
-
-训练、评测和冒烟测试**绝不写入宿主源码目录**：
-
-- 禁止写 `src/cards/`
-- 禁止写 `src/slices/`
-- 禁止写 `.card-baselines/`
-- 原始桌面设计稿只读
-- 所有生成物落在 `training/datasets/<version>/raw/` 或 `training/runs/<round>/`
-
-执行器必须在动态 import 生成器和渲染器之前设置：
-
-```bash
-DSL_CARD_CARDS_DIR=<training-run>/cards
-DSL_CARD_SLICES_DIR=<training-run>/slices
-```
-
-每轮结束后可用 `git status --short -- src` 验证必须为空。
-
-## 自动化流程
-
-1. 扫描所有包含 `index.html` 的 MeaXure 导出。
+
+## 源码隔离铁律
+
+训练、评测和冒烟测试**绝不写入宿主源码目录**：
+
+- 禁止写 `src/cards/`
+- 禁止写 `src/slices/`
+- 禁止写 `.card-baselines/`
+- 原始桌面设计稿只读
+- 所有生成物落在 `training/datasets/<version>/raw/` 或 `training/runs/<round>/`
+
+执行器必须在动态 import 生成器和渲染器之前设置：
+
+```bash
+DSL_CARD_CARDS_DIR=<training-run>/cards
+DSL_CARD_SLICES_DIR=<training-run>/slices
+```
+
+每轮结束后可用 `git status --short -- src` 验证必须为空。
+
+## 自动化流程
+
+1. 扫描所有包含 `index.html` 的 MeaXure 导出。
 2. 每套导出独立解析到 `training/datasets/<version>/raw/<source>/`，不修改桌面源文件。
-3. 将每个有效画板登记为一个案例，按内容哈希稳定划分 train/dev/eval/holdout。
-4. 使用 `v3` 策略批量生成到隔离的 run 目录（本技能是「多画板必须先选卡」铁律的**显式批量例外**：用户点名跑无人值守训练即等于授权全量画板；产物落隔离 run 目录、不写 `src/cards/`。见 `dsl-card-generator/references/rules.md §十三`）。
-5. 复制 schema 实际引用的 slices 到当前 run 的隔离资源目录。
-6. 执行 Python 结构校验、Node lint、独立 Chrome 渲染、重复内容检测和像素差异计算。
+3. 将每个有效画板登记为一个案例，按内容哈希稳定划分 train/dev/eval/holdout。
+4. 使用 `v3` 策略批量生成到隔离的 run 目录（本技能是「多画板必须先选卡」铁律的**显式批量例外**：用户点名跑无人值守训练即等于授权全量画板；产物落隔离 run 目录、不写 `src/cards/`。见 `dsl-card-generator/references/rules.md §十三`）。
+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）。只重跑失败例用
@@ -75,54 +76,55 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 
 > **继承轮不是锚点**：`--inherit` 轮的 `cards/`、`slices/` 只含本轮重跑案例，因此可用于门禁与
 > 回归对账，但**不能作为冻结锚点载体**——锚点必须整轮全量跑（含全部 cards/slices 证据）。
-
-### 校正器纪律
-
-后置布局校正器是安全网而不是拐杖：
-
-- 校正采纳需**双指标守卫**：position 提升 **且** pixel 不退化（容忍 +0.005），否则回退并记
-  `correctorRejected`；采纳时记 `layoutCorrections` 明细。
-- `summary.json` 的 `correctorCoverage`（触发率）持续 >25% 说明生成器缺陷被校正器掩盖，
-  应把高频校正模式沉淀回生成器规则，而不是放任校正器兜底。
-- 每 3~5 轮安排一次里程碑裸测：`run_round.mjs --no-correct --round <轮次>nc`，与同期
-  正常轮对比 passRate/avgPosition，差值就是校正器的真实贡献与生成器的真实缺口。
-- 模拟否决快路径：纯纵向 rigidSafe 校正的 position 分可精确模拟（22/22 对账逐位一致），
-  模拟不提升即跳过二次渲染，报告记 `correctorRejected.reason=position-not-better-simulated`；
-  可用 `CORR_SIM_VALIDATE=1` 双跑对账复核保真度。
-
-### 分区纪律
-
-- 迭代修复**只用 train/dev**；eval 每 3 轮盲测一次；holdout 只在晋级落地时启用。
-- 同一案例连续出现在诊断视野里超过 2 轮，视为过拟合风险，下一轮诊断必须换一批样本。
-
-## 上游质量门
-
-每个案例先检查 `sketch-spec-to-card` 产物，再进入 DSL 评分：
-
-- `annotationCompleteness`：画板内叶子标注是否被完整归属到聚焦卡。
-- `textRetention`：卡片内文案是否被完整保留。
-- `structuralFocus`：候选是否具备卡片级结构，而不是气泡、按钮条或空壳。
-- `trainingEligible`：弹窗、toast、底部抽屉必须为 false。
-
-任一门失败优先归因 `PARSER`，修复目标是 `vision.py` / `parse_meaxure.py` / `boundary.json` 的通用几何规则，不允许用业务名救某个样本。
-
-## 验收标准（r060 起）
-
-### 单案例通过门（per-case pass gate）
-
-每张卡片必须同时满足以下全部条件才算 PASS：
-
+
+### 校正器纪律
+
+后置布局校正器是安全网而不是拐杖：
+
+- 校正采纳需**双指标守卫**：position 提升 **且** pixel 不退化（容忍 +0.005），否则回退并记
+  `correctorRejected`；采纳时记 `layoutCorrections` 明细。
+- `summary.json` 的 `correctorCoverage`（触发率）持续 >25% 说明生成器缺陷被校正器掩盖，
+  应把高频校正模式沉淀回生成器规则，而不是放任校正器兜底。
+- 每 3~5 轮安排一次里程碑裸测：`run_round.mjs --no-correct --round <轮次>nc`，与同期
+  正常轮对比 passRate/avgPosition，差值就是校正器的真实贡献与生成器的真实缺口。
+- 模拟否决快路径：纯纵向 rigidSafe 校正的 position 分可精确模拟（22/22 对账逐位一致），
+  模拟不提升即跳过二次渲染，报告记 `correctorRejected.reason=position-not-better-simulated`；
+  可用 `CORR_SIM_VALIDATE=1` 双跑对账复核保真度。
+
+### 分区纪律
+
+- 迭代修复**只用 train/dev**；eval 每 3 轮盲测一次；holdout 只在晋级落地时启用。
+- **holdout 污染标记（seq5-l12，2026-09-21）**：用户显式指定训练某个 holdout 分区案例时按指令执行，但该轮结论**必须标记**：此案例此后移出晋级盲测的未见样本池（holdout 只剩晋级落地一次性启用；被点名训练过 = 已见过，继续计入盲测会虚高泛化分）。
+- 同一案例连续出现在诊断视野里超过 2 轮，视为过拟合风险，下一轮诊断必须换一批样本。
+
+## 上游质量门
+
+每个案例先检查 `sketch-spec-to-card` 产物，再进入 DSL 评分：
+
+- `annotationCompleteness`：画板内叶子标注是否被完整归属到聚焦卡。
+- `textRetention`：卡片内文案是否被完整保留。
+- `structuralFocus`：候选是否具备卡片级结构，而不是气泡、按钮条或空壳。
+- `trainingEligible`：弹窗、toast、底部抽屉、纯文本板（`artboardType=text_only`，整板只有对话/问答/提示文字）必须为 false。
+
+任一门失败优先归因 `PARSER`，修复目标是 `vision.py` / `parse_meaxure.py` / `boundary.json` 的通用几何规则，不允许用业务名救某个样本。
+
+## 验收标准（r060 起）
+
+### 单案例通过门（per-case pass gate）
+
+每张卡片必须同时满足以下全部条件才算 PASS：
+
 | 维度 | 门（`lib/scoring.mjs::PASS_GATE`） | 说明 |
 |---|---:|---|
-| 像素差异 (pixelDiff) | **≤ 0.08** | 逐像素差异比；标注缺陷矩形、非标字体字形带、以及「导出素材缺失→画板裁切兜底切图」（reason=crop-fallback-slice，仅掩 schema 真实引用的裁切盒）局部掩膜（报告 pixelExclusions 透明可见） |
-| UI 还原度 (overall) | **≥ 0.85** | 综合像素+结构+组件+文本 |
-| 组件相似度 (components) | **≥ 0.75** | 文本/媒体/富文本计数匹配（ListLayout 按数据项展开计数） |
-| 位置还原度 (position) | **≥ 0.80** | 文本盒对齐（含形状锚点） |
-| 文本溢出 (textOverflow) | **≥ 0.90** | 渲染盒溢出/裁切 |
-| 结构还原度 (structure) | **≥ 0.85** | 轮廓直方图（含 1.25% 容差窗） |
-| 色彩还原度 (color) | **≥ 0.90** | 颜色分布相似度 |
-| 尺寸还原度 (dimension) | **≥ 0.95** | 宽高比匹配 |
-| 重复内容 (duplication) | **≥ 0.95** | 同一文案渲染次数不得超出标注次数 5%；合并渲染（¥+金额 合一）豁免 |
+| 像素差异 (pixelDiff) | **≤ 0.08** | 逐像素差异比；标注缺陷矩形、非标字体字形带、以及「导出素材缺失→画板裁切兜底切图」（reason=crop-fallback-slice，仅掩 schema 真实引用的裁切盒）局部掩膜（报告 pixelExclusions 透明可见） |
+| UI 还原度 (overall) | **≥ 0.85** | 综合像素+结构+组件+文本 |
+| 组件相似度 (components) | **≥ 0.75** | 文本/媒体/富文本计数匹配（ListLayout 按数据项展开计数） |
+| 位置还原度 (position) | **≥ 0.80** | 文本盒对齐（含形状锚点） |
+| 文本溢出 (textOverflow) | **≥ 0.90** | 渲染盒溢出/裁切 |
+| 结构还原度 (structure) | **≥ 0.85** | 轮廓直方图（含 1.25% 容差窗） |
+| 色彩还原度 (color) | **≥ 0.90** | 颜色分布相似度 |
+| 尺寸还原度 (dimension) | **≥ 0.95** | 宽高比匹配 |
+| 重复内容 (duplication) | **≥ 0.95** | 同一文案渲染次数不得超出标注次数 5%；合并渲染（¥+金额 合一）豁免 |
 | validate / lint / render | 0 | 零容忍 |
 
 > **未达标维度按缺口排序落盘**：报告里的 `gateFailures`（全部未过门维度 + 归一化缺口）、
@@ -137,10 +139,10 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 > 取值顺序：逐样本比例 → 同 fontSize 档中位数 → overall 中位数 → 文件缺失回退 `1.35`。
 > 换字体栈、改 `card-editor/styles/app.css` 或改掩膜逻辑后**必须重跑探针**（`node training/tools/probe_font_metrics.mjs`），
 > 否则 pixelDiff 口径漂移、轮间与锚点不可比。
-> **掩膜门环境感知（seq4 起）**：掩膜门不再只看字体家族名——探针实测「回退栈宽/标注宽」
-> `fontMaskWiden > 1.06` 即该字体在本机渲染环境不可得（PingFang SC 在 Windows 同样回退合成），
-> 一律掩膜；探针缺失回退家族名判据。否则设计稿字体与训练环境字体差会把像素门顶在
-> 8% 门外（实测卡 4 文本字形带单带 16-36%），误逼生成器改字重/字号扭曲 spec。
+> **掩膜门环境感知（seq4 起）**：掩膜门不再只看字体家族名——探针实测「回退栈宽/标注宽」
+> `fontMaskWiden > 1.06` 即该字体在本机渲染环境不可得（PingFang SC 在 Windows 同样回退合成），
+> 一律掩膜；探针缺失回退家族名判据。否则设计稿字体与训练环境字体差会把像素门顶在
+> 8% 门外（实测卡 4 文本字形带单带 16-36%），误逼生成器改字重/字号扭曲 spec。
 
 
 
@@ -172,14 +174,14 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 | duplicationFailures | 0 | 重复内容超限（重影）样本数 |
 | lint / validate / render / upstream | 0 | 全零 |
 | 高掩膜 PASS | 需复核 | 掩膜 ≥25% 的通过案例不计入晋级证据（见「掩膜覆盖率护栏」） |
-
+
 > 基线载体是**冻结锚点轮目录**（含 `reports/` 全量证据）+ **入库压缩锚点** `training/anchors/<round>.json`
 > （P0-2 起：干净克隆与 CI 上唯一的锚点载体，`round_diff.mjs` / `plan_next_round.mjs` 都直接吃它）。
 > 本 Skill 目录下的历史 `baselines/v3-r0*.json` 范式已废弃并删除（指标快照改由 summary.json + 压缩锚点承载）。
 > 晋级 = 新轮成为下一冻结锚点候选，在 `training/plans/` 记录轮号与指标，并重新生成压缩锚点入库。
-
-### 泛化盲测门（generalization gate）
-
+
+### 泛化盲测门（generalization gate）
+
 每 **3 轮**锚点回归后（或每次晋级基线前），必须用**未参与修复的新批次数据集**（或 holdout / eval 分区）抽取 **不少于 24 例未见样本** 做盲测（如 v6 sampled 30 例）：
 
 | 门禁 | 目标 | 说明 |
@@ -196,15 +198,15 @@ DSL_CARD_SLICES_DIR=<training-run>/slices
 用 `build_sample.mjs` 从 v6 + v7 全量池各抽代表，合并成 `training/datasets/blindset/train-set.jsonl`
 （≥24 例，结构聚类去重后覆盖列表/表单/结果/媒体/空状态），晋级轮一律用它盲测，
 并在 `training/plans/` 记录该盲测集的 provenance 与轮号。盲测集**不参与任何修复迭代**。
-### 收敛检测与早停
-
-当出现以下任一信号时，**停止脚本微调，转而修订 Skill 文档规则或范式**：
-
-1. **边际收益递减**：连续 3 轮焦点集 avgFidelity 提升 < 1pt（0.01）。
-2. **锚点升但盲测降**：锚点 avgFidelity 提升但盲测 avgFidelity 下降 → 判定过拟合，拒绝晋级。
-3. **同一签名反复出现**：同一失败签名在 ≥ 3 轮中重复出现且未消除 → 说明脚本补丁无效，需升级 Skill 级别范式。
-4. **盲测差扩大**：锚点−盲测差从 ≤5pts 扩大到 ≥10pts → 过拟合风险，强制回退。
-
+### 收敛检测与早停
+
+当出现以下任一信号时，**停止脚本微调，转而修订 Skill 文档规则或范式**：
+
+1. **边际收益递减**：连续 3 轮焦点集 avgFidelity 提升 < 1pt（0.01）。
+2. **锚点升但盲测降**：锚点 avgFidelity 提升但盲测 avgFidelity 下降 → 判定过拟合，拒绝晋级。
+3. **同一签名反复出现**：同一失败签名在 ≥ 3 轮中重复出现且未消除 → 说明脚本补丁无效，需升级 Skill 级别范式。
+4. **盲测差扩大**：锚点−盲测差从 ≤5pts 扩大到 ≥10pts → 过拟合风险，强制回退。
+
 以上 4 类信号由 `plan_next_round.mjs` 自动计算（信号名：`marginal-gain-below-1pt` /
 `anchor-up-blind-down` / `same-signature-3-rounds` / `anchor-blind-gap-over-10pts`，另有 `pass-by-mask`），
 任一触发即写出 `reports/convergence-report.json`。收敛触发后，Agent 必须在该报告基础上给出瓶颈分类和
@@ -213,21 +215,21 @@ Skill 级改进建议，而非继续打脚本补丁。
 > 趋势口径：边际收益按**最近 ≤4 轮的共同案例集**算 avgFidelity 逐轮 delta（跨批次轮次案例集不同，
 > 直接比均值是假信号）；重复签名按 `--history`（默认自动扫 `training/runs/` 最近 8 轮）统计，
 > 老报告没有签名字段时按当前尺子现算，保证跨轮可比。
-
-### 视觉修正回路（模型在环）
-
-当脚本化校正（`correctCardLayout` 的 X/Y 轴 padding 对齐）收敛后仍无法通过门禁时，启用模型多模态回路，遵循「模型视觉判断 > 脚本启发式」的优先级：
-
-1. 对焦点集每例收集 `design.png`、`render.png`、`spec.json`、`schema.json` 与渲染元素盒 `elementBoxes`。
-2. 模型逐区域比对设计稿与渲染图，输出**可执行的布局修正指令**（目标节点 + 属性 + 期望值 + 证据区域），写入 `visual-fix.jsonl`；指令只允许引用结构证据（坐标、尺寸、颜色、文本），禁止出现业务词硬编码。
-3. 脚本按指令修改 schema 并重渲染，仅当 position / pixel / duplication 三项均不退化时才保留，否则回滚。
-4. 同一修正模式在 ≥3 个案例中复现 → 抽象为通用规则回灌 `dsl-card-generator` 或 `sketch-spec-to-card`，并登记 `training/lessons/lessons.jsonl`。
-5. 每轮视觉修正后必须复跑冻结锚点，防止局部修正引发全局回归。
-
-> **lessons 反哺提案**：定期（建议每个训练批次收尾时）跑 `node training/tools/aggregate_lessons.mjs` 聚合 lessons.jsonl——重复签名（同一坑重复踩）、未落盘规则（按 targetFiles 给建议落点）、密集落盘点（规则密集文件需结构性审视）三类提案，人工逐条 yes/no 审批后落盘，工具本身不自动改任何 skill 文件。
-
-## 当前基线与落地门
-
+
+### 视觉修正回路（模型在环）
+
+当脚本化校正（`correctCardLayout` 的 X/Y 轴 padding 对齐）收敛后仍无法通过门禁时，启用模型多模态回路，遵循「模型视觉判断 > 脚本启发式」的优先级：
+
+1. 对焦点集每例收集 `design.png`、`render.png`、`spec.json`、`schema.json` 与渲染元素盒 `elementBoxes`。
+2. 模型逐区域比对设计稿与渲染图，输出**可执行的布局修正指令**（目标节点 + 属性 + 期望值 + 证据区域），写入 `visual-fix.jsonl`；指令只允许引用结构证据（坐标、尺寸、颜色、文本），禁止出现业务词硬编码。
+3. 脚本按指令修改 schema 并重渲染，仅当 position / pixel / duplication 三项均不退化时才保留，否则回滚。
+4. 同一修正模式在 ≥3 个案例中复现 → 抽象为通用规则回灌 `dsl-card-generator` 或 `sketch-spec-to-card`，并登记 `training/lessons/lessons.jsonl`。
+5. 每轮视觉修正后必须复跑冻结锚点，防止局部修正引发全局回归。
+
+> **lessons 反哺提案**：定期（建议每个训练批次收尾时）跑 `node training/tools/aggregate_lessons.mjs` 聚合 lessons.jsonl——重复签名（同一坑重复踩）、未落盘规则（按 targetFiles 给建议落点）、密集落盘点（规则密集文件需结构性审视）三类提案，人工逐条 yes/no 审批后落盘，工具本身不自动改任何 skill 文件。
+
+## 当前基线与落地门
+
 当前冻结锚点 = `training/runs/r176`（v4 sampled 44 例）／入库压缩锚点 `training/anchors/r176.json`（40 例共享）。
 最近一次锚点回归 **r262 = 44/44 PASS，对 r176 0 例 pass→fail**（v7 焦点集双案例过门后收口）；
 r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7% / structure 95.6%。
@@ -247,18 +249,18 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
 > `training/anchors/r176.json`；保真度软门禁走入库 fixture `training/fixtures/ui-drafts/`
 > （`tools/regress-fidelity.mjs` 在 `UI/` 缺失时自动回退）；数据集需用 `build_dataset.py`
 > 从桌面导出重建，provenance 记在 `dataset-summary.json`。
-
-历史演进（baseline JSON 范式时期，仅供追溯）：
-
-| 基线 | 平均还原度 | 最低 | 低于80% | 结构还原度 |
-|---|---:|---:|---:|---:|
-| v3-r050n (08/26) | 79.5% | 73.2% | 26 | 70.4% |
-| v3-r052n (08/27) | 80.5% | 74.1% | 15 | 71.1% |
+
+历史演进（baseline JSON 范式时期，仅供追溯）：
+
+| 基线 | 平均还原度 | 最低 | 低于80% | 结构还原度 |
+|---|---:|---:|---:|---:|
+| v3-r050n (08/26) | 79.5% | 73.2% | 26 | 70.4% |
+| v3-r052n (08/27) | 80.5% | 74.1% | 15 | 71.1% |
 | v3-r058 (08/28) | 85.9% | 82.0% | 0 | 93.2% |
 | 冻结锚点范式 (r176→r198→r262) | 96.2%→96.4% | — | 0 | 95.4%→95.6%（r262 全量 44/44 PASS） |
-
-### 定向还原度迭代协议（r060 起）
-
+
+### 定向还原度迭代协议（r060 起）
+
 基线通过后不直接全量重训。每轮使用「冻结锚点（案例数以锚点载体为准：压缩锚点 40 例 / 冻结轮 44 例）
 + 低分焦点集 + 未见样本盲测」：
 
@@ -267,16 +269,16 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
    `<82%` 必须逐张多模态归因。
 2. Agent 同时读取设计稿、渲染截图、`spec.json` 和 `schema.json`（`diagnose_case.mjs --out` 已把这些
    证据与偏差表打包成 JSON），输出区域级 `agent-audit.jsonl`；结论必须包含失败类、通用规则候选、置信度和目标 Skill。
-3. 修复优先级：可见媒体与重影 → 语义顺序与纵向节奏 → 背景/圆角/留白 → 未见样本泛化。
-4. 缺失/状态错切图优先画板裁切（`cropSlice`，含宽条切图与纯矢量 logo 组；矩形内有文本叠加或背景级大矩形禁裁），裁切不可用才纯色近似并标记缺陷；弥散/光晕类纹理特事特办，计入局部还原度豁免。
+3. 修复优先级：可见媒体与重影 → 语义顺序与纵向节奏 → 背景/圆角/留白 → 未见样本泛化。
+4. 缺失/状态错切图优先画板裁切（`cropSlice`，含宽条切图与纯矢量 logo 组；矩形内有文本叠加或背景级大矩形禁裁），裁切不可用才纯色近似并标记缺陷；弥散/光晕类纹理特事特办，计入局部还原度豁免。
 5. 焦点样本通过后必须复跑冻结锚点全量；每 3 轮做不少于 24 例未见样本盲测（固定跨批次盲测集见上文）。
 6. 晋级门、焦点 ID 和产物路径以 `training/plans/` 下最新 plan 与本轮 `reports/next-round-plan.json` 为准。
-7. 新布局通道（如散点带 §21、段落壳归属 §22、行锚点/尾随切片 §23）落盘生成器后，同步 lessons.jsonl + generation_pitfalls/quickref/previewer_contract，并复跑冻结锚点确认 0 回归；通道判据只认几何/样式结构，不认业务词。
-
-训练清单可记录样本 ID 和画板名作为证据；运行时代码、Skill 判定和校验器不得引用业务词、画板名或样本专属文案。
-
-### 晋级落地检查清单
-
+7. 新布局通道（如散点带 §21、段落壳归属 §22、行锚点/尾随切片 §23）落盘生成器后，同步 lessons.jsonl + generation_pitfalls/quickref/previewer_contract，并复跑冻结锚点确认 0 回归；通道判据只认几何/样式结构，不认业务词。
+
+训练清单可记录样本 ID 和画板名作为证据；运行时代码、Skill 判定和校验器不得引用业务词、画板名或样本专属文案。
+
+### 晋级落地检查清单
+
 新一轮改动落地前必须满足：
 
 1. 失败样本探针全部通过。
@@ -284,8 +286,8 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
    （`plan_next_round.mjs --anchor` 的 `promotionGate.passed = true`）。
 3. validate/lint/render/upstream 失败数均为 0。
 4. `git status --short -- src` 为空。
-5. 批次轮 score_round：duplicationFailures = 0；成熟批次（v4/v5）另要求 passRate 趋势向上且残留失败逐例归因。
-6. 若为晋级轮，盲测 24 例 passRate ≥ 85%，盲测 avgFidelity ≥ 78%，锚点−盲测差 ≤ 10pts。
+5. 批次轮 score_round：duplicationFailures = 0；成熟批次（v4/v5）另要求 passRate 趋势向上且残留失败逐例归因。
+6. 若为晋级轮，盲测 24 例 passRate ≥ 85%，盲测 avgFidelity ≥ 78%，锚点−盲测差 ≤ 10pts。
 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/`；业务词、画板名和样本专属文案不得进入规则。
@@ -296,15 +298,15 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
    `tools/tests/scoring.test.mjs` 直接拦截；lint 走棘轮（`tools/lint-baseline.json`，error 只减不增，
    治理后 `node tools/lint-ratchet.mjs --update` 收紧）。
 10. 掩膜 ≥25% 的通过案例已人工看图复核（`summary.json::highMaskCases` / plan 的 `pass-by-mask` 信号）。
-
-评分器本身也要参与回归：组件语义升级（如 `Input` 正确承载金额）时，评分器必须把可编辑文本组件计入 text 维度；ListLayout 必须按数据项数展开模板内 Text/Image/Input/Button 计数，避免正确模板复用被当成组件丢失。
-
-结构评分对轮廓直方图使用约 1.25% 尺寸的对称最近邻对齐窗口：1–2 像素渲染偏移不视为结构丢失，明显缺块、错位和错误背景仍会扣分。调整该容差必须同步复跑冻结锚点，不允许用放宽阈值掩盖还原缺陷。
-
-像素对比额外记录 `bestAlignDy`（最佳纵向对齐偏移，仅诊断字段，不参与评分）：用于区分「截图裁切/节奏误差」与「真实布局错误」。**禁止**用对齐搜索后的差异替代零偏移差异参与评分——实测（r125）偏移因案例而异（0 / -4 / -16px 并存），不存在可统一归一化的系统性裁切偏移，统一平移只会掩盖真实的纵向节奏缺陷。
-
-布局自动校正覆盖 X/Y 两轴：`correctCardLayout` 按渲染元素与标注的偏差调整子节点的 `paddingTop`/`paddingLeft`（X 轴钳制 ±48px），仅当校正后 position 总分变好才保留，否则回滚 schema。
-
+
+评分器本身也要参与回归：组件语义升级（如 `Input` 正确承载金额）时，评分器必须把可编辑文本组件计入 text 维度；ListLayout 必须按数据项数展开模板内 Text/Image/Input/Button 计数，避免正确模板复用被当成组件丢失。
+
+结构评分对轮廓直方图使用约 1.25% 尺寸的对称最近邻对齐窗口：1–2 像素渲染偏移不视为结构丢失，明显缺块、错位和错误背景仍会扣分。调整该容差必须同步复跑冻结锚点，不允许用放宽阈值掩盖还原缺陷。
+
+像素对比额外记录 `bestAlignDy`（最佳纵向对齐偏移，仅诊断字段，不参与评分）：用于区分「截图裁切/节奏误差」与「真实布局错误」。**禁止**用对齐搜索后的差异替代零偏移差异参与评分——实测（r125）偏移因案例而异（0 / -4 / -16px 并存），不存在可统一归一化的系统性裁切偏移，统一平移只会掩盖真实的纵向节奏缺陷。
+
+布局自动校正覆盖 X/Y 两轴：`correctCardLayout` 按渲染元素与标注的偏差调整子节点的 `paddingTop`/`paddingLeft`（X 轴钳制 ±48px），仅当校正后 position 总分变好才保留，否则回滚 schema。
+
 ## 命令
 
 ### 运行前置（跨平台）
@@ -324,20 +326,20 @@ r198 记录的共享 40 例均值为 fidelity 96.4% / pixel 3.8% / position 95.7
 > 否则 pixelDiff 口径漂移。
 
 ### 构建数据集
-
-```bash
-python skills/card-skill-trainer/scripts/build_dataset.py \
-  --src "<设计稿导出根目录>" \
-  --out training/datasets/v1 \
-  --max-cases 160
-
-# 聚焦训练（提速首选）：--src 可直接指单份 MeaXure 导出；--artboards 只构建指定画板
-python skills/card-skill-trainer/scripts/build_dataset.py \
-  --src ~/Desktop/某设计稿导出 \
-  --out training/datasets/v7 \
-  --artboards 4,14 --no-artboard-dedup
-```
-
+
+```bash
+python skills/card-skill-trainer/scripts/build_dataset.py \
+  --src "<设计稿导出根目录>" \
+  --out training/datasets/v1 \
+  --max-cases 160
+
+# 聚焦训练（提速首选）：--src 可直接指单份 MeaXure 导出；--artboards 只构建指定画板
+python skills/card-skill-trainer/scripts/build_dataset.py \
+  --src ~/Desktop/某设计稿导出 \
+  --out training/datasets/v7 \
+  --artboards 4,14 --no-artboard-dedup
+```
+
 - `--artboards`：1 起序号或画板名关键词（逗号分隔，可混用）。序号转 parse_meaxure 的 0 起
   `--indices`、关键词走 `--only`；未选画板不进数据集。实测 47 画板整稿 → 2 画板：构建耗时降到 ~43s。
 - `--src` 指向自带 index.html 的单份导出时，它自身即唯一 source（不必再指到父目录把同级稿子全卷进来）。
@@ -357,15 +359,15 @@ node skills/card-skill-trainer/scripts/build_sample.mjs \
 实例：v5 39 画板 → 28 case → **17 代表**；v6 → **30 代表**。
 
 ### 运行一轮
-
-```bash
-node skills/card-skill-trainer/scripts/run_round.mjs \
-  --dataset training/datasets/v3/train-set.jsonl \
-  --round r060 \
-  --strategy v3 \
-  --limit 48
-```
-
+
+```bash
+node skills/card-skill-trainer/scripts/run_round.mjs \
+  --dataset training/datasets/v3/train-set.jsonl \
+  --round r060 \
+  --strategy v3 \
+  --limit 48
+```
+
 常用开关：
 
 - `--only <caseId[,caseId]>`：只跑指定案例（冒烟用）。
@@ -377,15 +379,18 @@ 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` 三者互斥，同时传会直接报错而不是静默取其一。
-
-渲染会话（Chrome + 预览 HTTP server）由 `skills/dsl-card-generator/scripts/render_card.mjs::createRenderSession`
-持有，收尾 `close()` **必须能返回**：CDP `send()` 带 60s 兜底超时、WebSocket `close/error` 立即拒绝全部在途请求、
-`server.close()` 2s 后强制 `closeAllConnections()`（Chrome 的 keep-alive 连接不会自己断）。
-少了任一条，浏览器异常退出时会出现「全案例跑完、`reports/` 齐全，却卡在 finally 写不出
-`review-queue.jsonl` / `summary.json`，node 进程 0% CPU 常驻」的假死（r202 实测），只能 `kill -9` 重跑整轮。
-
+
+渲染会话（Chrome + 预览 HTTP server）由 `skills/dsl-card-generator/scripts/render_card.mjs::createRenderSession`
+持有，收尾 `close()` **必须能返回**：CDP `send()` 带 60s 兜底超时、WebSocket `close/error` 立即拒绝全部在途请求、
+`server.close()` 2s 后强制 `closeAllConnections()`（Chrome 的 keep-alive 连接不会自己断）。
+少了任一条，浏览器异常退出时会出现「全案例跑完、`reports/` 齐全，却卡在 finally 写不出
+`review-queue.jsonl` / `summary.json`，node 进程 0% CPU 常驻」的假死（r202 实测），只能 `kill -9` 重跑整轮。
+
 ### 单案例诊断（支持批量）
 
 ```bash
@@ -403,13 +408,13 @@ node skills/card-skill-trainer/scripts/diagnose_case.mjs \
 标注几何取「聚焦卡」的 elements（与评分同源，避免多卡画板下产出幻影偏差）。
 
 ### 轮间对比
-
-```bash
-node skills/card-skill-trainer/scripts/round_diff.mjs \
-  --from training/runs/r060 \
-  --to   training/runs/r061
-```
-
+
+```bash
+node skills/card-skill-trainer/scripts/round_diff.mjs \
+  --from training/runs/r060 \
+  --to   training/runs/r061
+```
+
 列出指标 delta、fail→pass 修复清单、pass→fail 回归清单；存在回归时 exit 1，
 可作为提交前门禁（`--allow-regressions` 可豁免）。
 `--from` / `--to` 都可以是压缩锚点文件（干净克隆唯一可用的基线）：
@@ -446,37 +451,42 @@ node skills/card-skill-trainer/scripts/plan_next_round.mjs \
 可直接粘贴的下一轮命令、以及 `lesson-drafts.jsonl`（`status=candidate` 草稿，人工补 rule 后落盘）。
 归因只认指标与标注缺陷证据，不认业务词。
 
-### 训练设施工具（`training/tools/`，已入库）
-
-```bash
-node training/tools/aggregate_lessons.mjs                 # lessons 聚合 → 反哺提案（P-B 未落盘规则 / P-C 密集落盘点）
-node training/tools/probe_font_metrics.mjs                # 非标字体回退字宽探针 → training/reports/font-metrics.json（掩膜扩宽比）
+### 训练设施工具（`training/tools/`，已入库）
+
+```bash
+node training/tools/aggregate_lessons.mjs                 # lessons 聚合 → 反哺提案（P-B 未落盘规则 / P-C 密集落盘点）
+node training/tools/probe_font_metrics.mjs                # 非标字体回退字宽探针 → training/reports/font-metrics.json（掩膜扩宽比）
 node training/tools/analyze_position.mjs <round> [caseIdPrefix...] [--dataset <jsonl>]   # 逐样本 spec 文本框 vs 渲染 elementBoxes 配对偏差（缺省扫 training/datasets/*/*.jsonl）
-node training/tools/probe_offsets.mjs <cardsRoot> <cardId> <width> [captureHeight]  # 实测渲染页 DOM 几何（padding / content box / 偏移）
-python3 training/tools/split_report.py <runDir> [topN]    # 按 split 聚合指标并列出最差 N 例
-```
-
+node training/tools/probe_offsets.mjs <cardsRoot> <cardId> <width> [captureHeight]  # 实测渲染页 DOM 几何（padding / content box / 偏移）
+python3 training/tools/split_report.py <runDir> [topN]    # 按 split 聚合指标并列出最差 N 例
+```
+
 > `training/datasets/`、`training/runs/` 仍被 gitignore（体积 + 源稿版权）。数据集可复现性靠
 > `dataset-summary.json` 的 `provenance`（sourceRoot / sourceNames / toolchainRev / 解析器参数）
 > 与 `training/plans/` 的轮次记录；锚点回归靠冻结轮目录（`training/runs/r176`）**或入库压缩锚点**
 > （`training/anchors/r176.json`，干净克隆唯一可用载体）。已入库的训练设施还有
 > `training/tools/*`、`training/reports/font-metrics.json`、`training/fixtures/ui-drafts/`（保真度软门禁兜底稿）。
-
-## 输出
-
+
+## 输出
+
 ```text
 training/runs/<round>/
   cards/
   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 轮：继承来源与案例清单
@@ -486,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）。
+