cardbuddy 0.11.0 → 0.12.1

package/dist/{server-core → vendored/server/core}/index.js

@@ -70,12 +70,14 @@ export {
 /**
  * 把全部卡片中间件挂到 Connect 风格容器（需实现 .use(mw)）。
  * @param {{ use: (mw: Function) => void }} app
- * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void } }} opts
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void }, allowDispatch?: boolean }} opts
  *   - upstream：FinMall 远端站点基址（来自 FINMALL_BASE_URL），资源代理回源用；空串表示不回源。
  *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）；代码桥经它推 bridge 事件，缺省时静默降级。
  *   - watchFile：代码桥单文件监听能力注入（chokidar 版）；缺省代码桥用 fs.watch 兜底。
+ *   - allowDispatch：AI 的 card_patch 是否走 card_write 管线（历史快照 + 校验）。仓库内运行由
+ *     「root === 仓库根」自动成立；cardbuddy 发布态代码快照在包内，需宿主显式开启。
  */
-export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '', notify = null, watchFile = null }) {
+export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '', notify = null, watchFile = null, allowDispatch = false }) {
   app.use(createSyncMiddleware({ root }))
   app.use(createPreviewMiddleware({ root }))
   app.use(createLoginCredentialsMiddleware({ root }))
@@ -110,5 +112,5 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   // upstream 空串时中间件仍会注册，但 /minio 等请求只会走占位图兜底，不会崩溃。
   app.use(createAssetProxyMiddleware({ root, upstream }))
   // AI 聊天：POST /__ai/chat 流式调用用户自带 LLM，工具调度复用 mcp/tools.mjs
-  app.use(createAiChatMiddleware({ root }))
+  app.use(createAiChatMiddleware({ root, allowDispatch }))
 }

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

@@ -0,0 +1,124 @@
+/**
+ * 技能资源（脚本 / 文档）路径解析 —— 「仓库内运行」与「npm 包安装态（cardbuddy）」的唯一差异点。
+ *
+ * 背景：server/core 既被仓库内的 dev server 直接加载，也被 cardbuddy 构建期内联进 npm 包
+ * （发布态落点 <pkg>/dist/vendored/server/core）。两种形态下 skills/ 的位置不同：
+ *   - 仓库内运行：  <repo>/skills                       （本文件的上两级即仓库根）
+ *   - 消费者项目：  <project>/skills                     （跑过 `cardbuddy init` 后由包内快照释放）
+ *   - 包内快照：    <pkg>/dist/vendored/skills           （构建期从仓库 skills/ 内联，随包发布）
+ *
+ * 解析优先级（只读用途）：configureSkillPaths 显式指定 > DSL_SKILLS_ROOT > <root>/skills > 包内快照。
+ * 写入用途（如 FinMall 凭据落盘）一律走 projectSkillsDir(root) —— 绝不写进 node_modules，
+ * 否则重装即丢、且多项目互相污染。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 快照根 = 本文件所在目录的上两级。
+ *   仓库内：<repo>/server/core      → <repo>（真仓库根，skills/ 就在其下）
+ *   发布态：<pkg>/dist/vendored/server/core → <pkg>/dist/vendored（构建期内联的迷你仓库快照）
+ * 两种形态下 `<SNAPSHOT_ROOT>/skills` 都指向「随代码走的那份技能库」，故可作统一兜底。
+ */
+export const SNAPSHOT_ROOT = path.resolve(__dirname, '..', '..')
+
+/**
+ * 候选 skills 根，按优先级排列（去重，只保留磁盘上真实存在的）。
+ * `DSL_SKILLS_ROOT` 为显式覆盖开关（调试 / 非常规布局用）。
+ * @param {string} [root] 项目根（消费者工程 / 仓库根）
+ * @returns {string[]}
+ */
+export function skillsCandidates(root) {
+  const list = []
+  const push = (dir) => {
+    if (!dir) return
+    const abs = path.resolve(dir)
+    if (!list.includes(abs) && fs.existsSync(abs)) list.push(abs)
+  }
+  push(process.env.DSL_SKILLS_ROOT)
+  if (root) push(path.join(path.resolve(root), 'skills'))
+  push(path.join(SNAPSHOT_ROOT, 'skills'))
+  return list
+}
+
+/**
+ * 取一个可用的 skills 根（只读场景）；全都不存在时回退「项目根下的 skills」，
+ * 让调用方拿到符合直觉的路径去报「文件不存在」，而不是 null 引发 TypeError。
+ * @param {string} [root]
+ * @returns {string}
+ */
+export function skillsDirFor(root) {
+  const found = skillsCandidates(root)
+  return found[0] || projectSkillsDir(root)
+}
+
+/**
+ * 写入用的 skills 根：永远是项目根下的 skills/（发布态即消费者工程，不进 node_modules）。
+ * @param {string} [root]
+ * @returns {string}
+ */
+export function projectSkillsDir(root) {
+  return path.join(path.resolve(root || process.cwd()), 'skills')
+}
+
+/** 判断 target 是否仍在 dir 内（防路径穿越；先归一化再前缀比对）。 */
+function isInside(target, dir) {
+  const rel = path.relative(path.resolve(dir), path.resolve(target))
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+/**
+ * 归一化「skills/ 下的相对路径」：允许带或不带 `skills/` 前缀，统一成正斜杠相对路径。
+ * 绝对路径与任何 `..` 片段一律判非法（返回 null）——技能脚本执行与文档读取都靠它把关。
+ * @param {string} rel
+ * @returns {string|null}
+ */
+export function normalizeSkillRel(rel) {
+  const raw = String(rel || '').trim().replace(/\\/g, '/').replace(/^\.\//, '')
+  if (!raw || path.isAbsolute(raw)) return null
+  const withoutPrefix = raw.replace(/^skills\//, '')
+  if (!withoutPrefix) return null
+  const segments = withoutPrefix.split('/').filter((s) => s !== '' && s !== '.')
+  if (!segments.length || segments.some((s) => s === '..')) return null
+  return segments.join('/')
+}
+
+/**
+ * 解析 skills/ 下的资源路径（脚本 / 文档 / 目录），按候选根依次找第一份存在的。
+ * @param {string} root 项目根
+ * @param {string} rel skills/ 下的相对路径（可带 `skills/` 前缀）
+ * @param {{ mustExist?: boolean }} [opts] mustExist=false 时不校验存在性，返回首选根下的拼接结果
+ * @returns {string|null} 绝对路径；非法 rel 或（mustExist 时）找不到则 null
+ */
+export function resolveSkillPath(root, rel, { mustExist = true } = {}) {
+  const clean = normalizeSkillRel(rel)
+  if (!clean) return null
+  const candidates = skillsCandidates(root)
+  if (!mustExist) {
+    const base = candidates[0] || projectSkillsDir(root)
+    return path.join(base, clean)
+  }
+  for (const dir of candidates) {
+    const full = path.join(dir, clean)
+    if (!isInside(full, dir)) continue
+    if (fs.existsSync(full)) return full
+  }
+  return null
+}
+
+/**
+ * 与 resolveSkillPath 同语义，但找不到时回退「项目根 skills/ 下的期望路径」，
+ * 供调用方直接交给子进程 / import 并报出人类可读的「文件不存在」。
+ * @param {string} root
+ * @param {string} rel
+ * @returns {string}
+ */
+export function resolveSkillPathOrProject(root, rel) {
+  const clean = normalizeSkillRel(rel)
+  const hit = resolveSkillPath(root, rel)
+  if (hit) return hit
+  return path.join(projectSkillsDir(root), clean || String(rel || ''))
+}

package/dist/{server-core → vendored/server/core}/sliceUpload.js

@@ -1,6 +1,10 @@
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { log, fmtBytes } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+/** 切图上传脚本相对 skills/ 的路径 */
+const UPLOAD_SCRIPT_REL = 'finmall-card-sync/scripts/slice_upload.mjs'
 
 /**
  * 顶栏「远端 → 切图上传」按钮的服务端处理：把卡片引用的 src/slices 切图上传到 FinMall
@@ -43,14 +47,7 @@ export function createSliceUploadMiddleware({ root }) {
         )
       }
       try {
-        function resolveUploadScript(root) {
-  const primary = path.join(root, 'skills', 'finmall-card-sync', 'scripts', 'slice_upload.mjs')
-  if (fs.existsSync(primary)) return primary
-  const vendored = path.resolve(__dirname, '..', 'vendored', 'skills', 'finmall-card-sync', 'scripts', 'slice_upload.mjs')
-  if (fs.existsSync(vendored)) return vendored
-  return primary
-}
-const skillPath = resolveUploadScript(root)
+        const skillPath = resolveSkillPathOrProject(root, UPLOAD_SCRIPT_REL)
         const { uploadSlices } = await import(pathToFileURL(skillPath).href)
         const summary = await uploadSlices({
           cardId: String(payload.cardId),

package/dist/vendored/skills/README.md

@@ -0,0 +1,93 @@
+# Skills 目录拓扑
+
+> 本仓库的 `skills/` 下共 8 个 skill（含 shared），按依赖关系形成如下拓扑。
+> 新来的 AI 按**从下到上**的顺序读（被依赖的先读），能最快建立全局认知。
+
+## 依赖拓扑
+
+```
+  sketch-spec-to-card ──► dsl-card-generator ◄── dsl-card-ai
+      （设计稿→卡片要素）      │  ▲                （引用 references/、铁律；建卡入口路由 card_route_input → 强制先转 sketch-spec-to-card）
+                             │  │
+        card-doctor ─────────┘  │  （体检报告 → 编排 dsl-card-ai 修复）
+                             │
+        card-skill-trainer ────┘  （训练闭环反哺 generator 与 sketch-spec-to-card）
+                             │
+                dsl-card-generator
+                        │ 接受 finmall-card-sync 同步进来的卡作为"导出实证"
+                        ▼
+                  finmall-card-sync ──────► finmall-session-navigator
+                        │                          │
+                        │ 复用 playwright 依赖      │ 启动 Chrome、维持登录态
+                        ▼                          ▼
+                              shared/
+                          (finmall-config.mjs
+                           auth-model.md)
+```
+
+## 各 skill 职责
+
+| skill | 职责 | 依赖 |
+|---|---|---|
+| **shared/** | 跨 skill 共享代码与文档：环境配置加载器（`finmall-config.mjs`）、鉴权与 Playwright 工程集中陈述（`auth-model.md`） | 无（最底层） |
+| **finmall-session-navigator** | 用 Playwright 独立启动 Chrome、自动登录 FinMall UAT、维持会话。所有需要登录态的下游 skill 都先调它 | shared |
+| **finmall-card-sync** | 通过 API 把 FinMall 卡片同步进 `src/cards/<id>/`（schema/data/封面）。复用 finmall-session-navigator 的登录态与 playwright 依赖 | shared + finmall-session-navigator 的登录态 |
+| **dsl-card-generator** | 从零/图片生成卡片、组件/表达式/事件深度语义、校验脚本库、范式片段库、**整卡模板库与沉淀闭环**（resolve 检索 → register 登记 → build 重建保留 pin）、组件使用分析、**建卡输入路由**（`scripts/route_input.mjs` / MCP `card_route_input` + SKILL.md §8 Workflow 0：识别到 Sketch MeaXure 标注导出时自动先转 sketch-spec-to-card 前处理，再回本 skill 逐卡生成）。是"卡片生成与契约"的权威方 | sketch-spec-to-card（MeaXure 导出输入时的强制上游）；接受 finmall-card-sync 同步进来的卡作为 export-proven 证据 |
+| **dsl-card-ai** | 在已有卡片上用 AI 编辑（修绑定 / 批量改 / 解释卡）+ **建卡入口路由**（Workflow D：MCP `card_route_input` 判输入形态，MeaXure 导出强制先转 sketch-spec-to-card，再交 dsl-card-generator 生成）。纯编排层，所有写卡收口是 `card_write` | dsl-card-generator 的 references + MCP 工具；sketch-spec-to-card（MeaXure 输入时的上游） |
+| **sketch-spec-to-card** | 读取 Sketch MeaXure 标注导出，按画板聚焦提取卡片要素（prompt.md / spec.md / 截图 / 切图），产出到 UI/ 供 dsl-card-generator 消费。**用户把 MeaXure 导出丢给 dsl-card-generator 时会被自动路由到本 skill 前处理**（无需用户显式点名） | dsl-card-generator（下游消费方） |
+| **card-skill-trainer** | 无人值守训练闭环：抽样设计稿 → 生成 → 结构/事实/像素评分 → 失败归因 → 反哺 sketch-spec-to-card 与 dsl-card-generator；lessons 经 `training/tools/aggregate_lessons.mjs` 聚合成提案人工审批落盘 | 被训练的两个 skill + training/ 设施 |
+| **card-doctor** | 存量卡健康巡检编排层：聚合 validate/lint/files/render 输出体检报告，指导按严重度分级修复（修复走 dsl-card-ai 的 card_write 闭环） | tools/card-doctor.mjs + dsl-card-ai 修复闭环 |
+
+## 阅读顺序建议
+
+按场景挑入口，不必全读：
+
+- **生成新卡 / 改组件结构 / 校验**：只读 `dsl-card-generator/SKILL.md` + `references/quickref.md`
+- **AI 编辑已有卡（修绑定、批量改）**：读 `dsl-card-ai/SKILL.md`，需要字段细节时跳到 `dsl-card-generator/references/`
+- **拉取/刷新 FinMall 卡**：先 `finmall-session-navigator` 拿登录态，再 `finmall-card-sync` 同步
+- **跨 skill 排查会话/鉴权问题**：直接读 `shared/auth-model.md`（唯一权威方）
+- **存量卡体检 / 治理 lint 存量**：读 `card-doctor/SKILL.md`，先跑 `node tools/card-doctor.mjs` 再看报告
+- **建卡提速（模板复用/沉淀）**：先 `resolve_card_template.mjs <意图>` 查模板库；新模式交付后经 `register_card_template.mjs --check` 确认再登记
+- **设计稿转卡片要素**：读 `sketch-spec-to-card/SKILL.md`；**训练/还原度优化**：读 `card-skill-trainer/SKILL.md`
+- **拿到 Sketch MeaXure 导出想直接建卡**：入口仍是 `dsl-card-generator`——先 `node skills/dsl-card-generator/scripts/route_input.mjs <导出目录>`（只挂 MCP 时用等价工具 `card_route_input({path})`，见 `dsl-card-ai` Workflow D），它判出 `meaxure-export` 后会给出 sketch-spec-to-card 的前处理命令（已前处理过则跳过），产物就绪再回 `dsl-card-generator` 逐卡生成（`SKILL.md §8 Workflow 0`）
+
+## 文件清单
+
+```
+skills/
+├── README.md                          ← 本文件
+├── shared/
+│   ├── finmall-config.mjs             ← 环境配置加载器（baseUrl/appId/cdpPort/...）
+│   └── auth-model.md                  ← 鉴权模型 + Playwright 工程集中陈述
+├── finmall-session-navigator/
+│   ├── SKILL.md                       ← 自动登录 FinMall
+│   └── scripts/
+│       ├── finmall_login.mjs          ← 主脚本
+│       ├── session-manager.mjs        ← 会话管理辅助
+│       └── package.json               ← playwright 依赖
+├── finmall-card-sync/
+│   ├── SKILL.md                       ← API 同步卡片到 src/cards/
+│   └── scripts/
+│       └── api_batch_sync.mjs         ← 批量同步脚本
+├── dsl-card-generator/
+│   ├── SKILL.md                       ← 卡片生成主入口
+│   ├── docs/                          ← 设计文档
+│   ├── references/                    ← 参考文档 + recipe_snippets/ + card_index.json（意图路由）+ card_templates.json（整卡模板库）
+│   └── scripts/                       ← validate/lint/diff/scaffold 等；route_input（建卡输入路由，MeaXure 导出自动转 sketch-spec-to-card）；模板闭环三件套：build_card_templates / register_card_template / resolve_card_template；analyze_component_usage（使用分析反哺 recipes）
+├── dsl-card-ai/
+│   └── SKILL.md                       ← AI 编辑编排层
+├── sketch-spec-to-card/
+│   ├── SKILL.md                       ← Sketch MeaXure 标注 → 卡片要素
+│   ├── references/
+│   └── scripts/                       ← parse_meaxure.py 等
+├── card-skill-trainer/
+│   ├── SKILL.md                       ← 无人值守训练闭环
+│   ├── baselines/                     ← 冻结基线
+│   └── scripts/                       ← run_round.mjs 等
+└── card-doctor/
+    └── SKILL.md                       ← 存量卡健康巡检编排层（聚合脚本在 tools/card-doctor.mjs）
+```
+
+## 铁律
+
+所有 skill 共享的铁律集中陈述在 `dsl-card-generator/references/rules.md`（十三节，含 §十三「画板聚焦与卡片生成单位」：多画板设计稿未指定画板时必须先列清单请用户选，UI 产物可全量生成、卡片生成以单画板为单位）。任何与该文件冲突的描述以该文件为准。

package/dist/vendored/skills/card-doctor/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: card-doctor
+description: 卡片健康巡检编排层。跑 tools/card-doctor.mjs 聚合 validate（Python 硬契约）/ lint（体验）/ files（封面、data.json、侧车）/ render（可选 SSR）四类检查，输出全卡体检报告，并按严重度分级指导修复——修复一律走 dsl-card-ai 的 card_write 闭环，复检收口。与 ci-gate 的边界：ci-gate 管「能不能合入」（硬门禁），本技能管「卡群健不健康、先修哪张」（报告与治理）。Triggers: 卡片体检, 健康巡检, 全卡检查, 卡片健康报告, 修复存量卡片, 治理 lint, card-doctor, 体检报告, 哪些卡片有问题.
+---
+
+# Card Doctor 卡片健康巡检技能
+
+本技能是**编排层**：巡检 = 跑聚合脚本 → 解读报告 → 编排修复 → 复检收口。绝不重新实现任何检查逻辑（检查规则的唯一真源是 `validate_schema.py` / `lint_card.mjs` / dev server SSR 自检）。
+
+## 0. 铁律
+
+1. **只编排，不实现**：所有检查来自 `tools/card-doctor.mjs` 的聚合输出；不要自己写脚本扫 schema 找问题（会造出第二套规则，必然漂移）。
+2. **修复的唯一收口是 `card_write`**（MCP 工具，写前自动留历史快照、写后自动 validate + render_status）。具体改法遵循 `dsl-card-ai` 的编辑场景范式（card-fix-bindings / card-bulk-edit）与 `dsl-card-generator/references/rules.md` 铁律。
+3. **改坏可回滚**：每次 `card_write` 自动累积快照，用 `card_history` 查看、`card_rollback` 撤销；批量治理时先跑通单卡再推广。
+4. **render_status.ok ≠ 画对了**：doctor 的 render 项只证明「结构合法 + 渲染不抛错」；视觉问题以 `card_screenshot` 为准。
+5. **doctor 默认不拦截**（exit 0），它是报告工具；卡口归 `npm run ci`（ci-gate）管，不要把 doctor 当 CI gate 用（除非显式 `--strict`）。
+
+## 1. 用法
+
+```bash
+node tools/card-doctor.mjs                              # 体检全部卡片
+node tools/card-doctor.mjs --id <cardId>                # 单卡
+node tools/card-doctor.mjs --render                     # 附加 SSR 渲染自检（需先 npm run dev；离线自动 skipped）
+node tools/card-doctor.mjs --out .codex-tmp/doctor.json # 落盘 JSON 报告（.codex-tmp 已 gitignore）
+```
+
+报告结构：`{ generatedAt, totals, cards: { <id>: { validate, lint, files, render? } } }`。
+
+## 2. 检查项语义
+
+| 维度 | 来源 | 性质 | 说明 |
+|---|---|---|---|
+| `validate` | `validate_schema.py`（离线） | 硬契约 | 结构/绑定/data 一致性；error 必须清零 |
+| `lint` | `lint_card.mjs --all --json`（离线） | 体验软规 | error（如按钮缺 click、itemId 错配）应清零；warn/info 按存量分批治理 |
+| `files.cover` | 文件系统 | 完整性 | 缺 `<id>.png` 封面的卡无法走 FinMall 封面上传链路 |
+| `files.data` | 文件系统 | 完整性 | data.json 缺失或 JSON 解析失败 |
+| `render`（可选） | dev server `/__render-status/:id` | SSR 自检 | bindingErrors / runtimeErrors；离线标 `skipped` 不算失败 |
+
+## 3. 治理工作流
+
+1. **体检**：`node tools/card-doctor.mjs --out .codex-tmp/doctor.json`，先看 `totals` 建立全局认知。
+2. **分级**：`validate 失败` > `lint error` > `data.json 异常` > `缺封面` > `lint warn/info`。
+3. **聚类修复**：同一 `lint.code` 跨卡批量出现（如 `text-no-color`、`icon-no-click`）时，先精读该规则在 `lint_card.mjs` 头部的检查说明，再用同一修复范式批量处理；单卡个性问题单独处理。
+4. **修复**：逐卡走 `card_read` → 改 → `card_write`；需要看渲染效果时先 `npm run dev` 再 `--render` / `card_screenshot`。
+5. **复检**：每批修复后重跑 doctor 确认 `totals` 收敛、无新增问题；存量治理目标是把 `lintError` 降到 0，warn/info 可长期分批。
+6. **防回潮**：修复合入前跑 `npm run ci`（硬门禁：card-check + magic-values + regress-data + mcp-doc-sync）。
+
+## 4. 边界
+
+- **不检查视觉还原度**：与设计稿的像素级比对归 `dsl-card-generator` 的 fidelity 工具链（check_fidelity / render_diff）。
+- **不替代训练**：生成质量优化归 `card-skill-trainer`；doctor 管存量卡健康。
+- **不碰 FinMall 远端**：远端一致性归 `finmall-card-sync` / `card_sync`。

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

@@ -0,0 +1,312 @@
+---
+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 → run_round.mjs → score_round.mjs → semantic-review.jsonl → lessons.jsonl
+```
+
+人工不阻塞主流程。连续回归、渲染器崩溃或置信度低于阈值的样本会进入 `review-queue.jsonl`；像素/结构失败同时生成 `semantic-review.jsonl`，由执行 Skill 的 Agent 在下一轮自动做多模态归因，再回灌到 `dsl-card-generator` 或 `sketch-spec-to-card` 的文档规则。脚本负责提出证据和复跑回归，不负责把业务语义硬编码。
+
+## 源码隔离铁律
+
+训练、评测和冒烟测试**绝不写入宿主源码目录**：
+
+- 禁止写 `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/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 渲染、重复内容检测和像素差异计算。
+7. 聚合 Round 报告，并按失败签名生成规则候选。
+8. Agent 自动复核失败对的 `designImage + render.png + spec.json`，把失败归入 PARSER / DSL / STYLE / DATA / INTERACTION / ASSET / EVALUATOR，并只推广通用规则。
+
+## 高效迭代闭环（r172 起）
+
+单案例修复循环按此顺序推进，避免整轮盲跑浪费时间：
+
+1. **诊断**：`diagnose_case.mjs` 对失败/低分案例一键产出证据包（side-by-side、像素热区、
+   元素偏差表、`__prov` 源码行溯源、失败类建议）。先看偏差表与热区，再决定是否动生成器。
+2. **修复**：改动 `spec_to_schema_v3.mjs` / `vision.py` 等的通用几何规则（禁业务词硬编码）。
+3. **增量验证**：`run_round.mjs --only-failed training/runs/<上轮> --round <新轮>` 只重跑上轮
+   失败案例，秒级确认修复有效。
+4. **整轮防回归**：不带开关跑全量，`round_diff.mjs --from <上轮> --to <新轮>` 确认零
+   PASS→FAIL 回归（该脚本存在回归时 exit 1，可直接当提交门禁）。
+5. **门禁汇总**：`score_round.mjs` 出 roundGate；全绿才允许提交并推送。
+
+### 校正器纪律
+
+后置布局校正器是安全网而不是拐杖：
+
+- 校正采纳需**双指标守卫**：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：
+
+| 维度 | 门 (run_round 实现) | 说明 |
+|---|---:|---|
+| 像素差异 (pixelDiff) | **≤ 0.08** | 逐像素差异比；标注缺陷矩形与非标字体字形带局部掩膜（报告 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 | 零容忍 |
+
+> **字体掩膜口径（r201 起）**：非标字体字形带的掩膜扩宽比不再硬编码，取自 `training/reports/font-metrics.json`
+> ——由 `training/tools/probe_font_metrics.mjs`（playwright `measureText` 实测设计稿字体栈的渲染宽 / 标注宽比）产出。
+> 取值顺序：逐样本比例 → 同 fontSize 档中位数 → overall 中位数 → 文件缺失回退 `1.35`。
+> 换字体栈、改 `preview/styles/app.css` 或改掩膜逻辑后**必须重跑探针**（`node training/tools/probe_font_metrics.mjs`），
+> 否则 pixelDiff 口径漂移、轮间与锚点不可比。
+
+### 轮级晋级门（round-level promotion gate）
+
+一轮训练完成后，用 `round_diff.mjs --from <冻结锚点轮> --to <本轮>` 做冻结锚点回归，
+**回归 0 例 PASS→FAIL** 才允许晋级；锚点轮目录即基线载体（当前冻结锚点 = `training/runs/r176`，
+v4 sampled 44 例：与历史锚点共享 40 例 + holdout 新增 4 例计为 new 不计回归）：
+
+| 门禁 | 目标 | 说明 |
+|---|---|---|
+| 回归 pass→fail | **0** | round_diff 状态迁移硬底线；任何 1 例即拒绝晋级 |
+| 均值指标 | 不低于锚点 | fidelity/pixel/position/structure 均值不得退化（round_diff delta 表） |
+| 本轮 passRate | 批次门另计 | 新批次盲测允许低起点（如 v6 r200 = 4/30），靠迭代收敛而非门槛豁免 |
+| duplicationFailures | 0 | 重复内容超限（重影）样本数 |
+| lint / validate / render / upstream | 0 | 全零 |
+
+> 基线载体是**冻结锚点轮目录**（含 reports/ 全量证据），不再维护独立 baseline JSON 文件
+> （历史 `baselines/v3-r058.json` 范式已废弃）。晋级 = 新轮成为下一冻结锚点候选，并在
+> `training/plans/` 记录轮号与指标。
+
+### 泛化盲测门（generalization gate）
+
+每 **3 轮**锚点回归后（或每次晋级基线前），必须用**未参与修复的新批次数据集**（或 holdout / eval 分区）抽取 **不少于 24 例未见样本** 做盲测（如 v6 sampled 30 例）：
+
+| 门禁 | 目标 | 说明 |
+|---|---|---|
+| 盲测样本数 | ≥ 24 | 按结构聚类抽样，覆盖列表卡、表单卡、结果卡、媒体卡和空状态 |
+| 盲测 passRate | ≥ 0.85 | 至少 85% 通过新单案例门 |
+| 盲测 avgFidelity | ≥ 0.78 | 未见样本平均还原度不低于 78% |
+| 锚点 vs 盲测差 | ≤ 10pts | 锚点 avgFidelity − 盲测 avgFidelity ≤ 0.10（防过拟合） |
+
+### 收敛检测与早停
+
+当出现以下任一信号时，**停止脚本微调，转而修订 Skill 文档规则或范式**：
+
+1. **边际收益递减**：连续 3 轮焦点集 avgFidelity 提升 < 1pt（0.01）。
+2. **锚点升但盲测降**：锚点 avgFidelity 提升但盲测 avgFidelity 下降 → 判定过拟合，拒绝晋级。
+3. **同一签名反复出现**：同一失败签名在 ≥ 3 轮中重复出现且未消除 → 说明脚本补丁无效，需升级 Skill 级别范式。
+4. **盲测差扩大**：锚点−盲测差从 ≤5pts 扩大到 ≥10pts → 过拟合风险，强制回退。
+
+收敛触发后，Agent 必须输出 `convergence-report.json`，列出瓶颈分类和 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）。最近一次锚点回归 r198：共享 40 例 **0 回归**，
+fidelity 96.4%、pixel 3.8%、position 95.7%、structure 95.6%（均优于 r176）。
+批次盲测基线：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`）。
+
+历史演进（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) | 96.2%→96.4% | — | 0 | 95.4%→95.6% |
+
+### 定向还原度迭代协议（r060 起）
+
+基线通过后不直接全量重训。每轮使用"冻结 48 例锚点 + 低分焦点集 + 未见样本盲测"：
+
+1. 从最近回归中选取 `<85%` 样本组成焦点集；`<82%` 必须逐张多模态归因。
+2. Agent 同时读取设计稿、渲染截图、`spec.json` 和 `schema.json`，输出区域级 `agent-audit.jsonl`；结论必须包含失败类、通用规则候选、置信度和目标 Skill。
+3. 修复优先级：可见媒体与重影 → 语义顺序与纵向节奏 → 背景/圆角/留白 → 未见样本泛化。
+4. 缺失/状态错切图优先画板裁切（`cropSlice`，含宽条切图与纯矢量 logo 组；矩形内有文本叠加或背景级大矩形禁裁），裁切不可用才纯色近似并标记缺陷；弥散/光晕类纹理特事特办，计入局部还原度豁免。
+5. 焦点样本通过后必须复跑冻结 48 例；每 3 轮做不少于 24 例未见样本盲测。
+6. 晋级门、焦点 ID 和产物路径以 `training/plans/` 下最新 plan JSON 为准。
+
+训练清单可记录样本 ID 和画板名作为证据；运行时代码、Skill 判定和校验器不得引用业务词、画板名或样本专属文案。
+
+### 晋级落地检查清单
+
+新一轮改动落地前必须满足：
+
+1. 失败样本探针全部通过。
+2. 冻结锚点全量回归 round_diff **0 例 pass→fail**，且均值指标不退化、无新增失败签名。
+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。
+7. 通用规则写入 `training/lessons/lessons.jsonl`，并同步到对应 Skill 的 `SKILL.md` 或 `references/`；业务词、画板名和样本专属文案不得进入规则。
+8. 通过后以新轮目录作为下一冻结锚点候选并登记 `training/plans/`；未通过的候选规则保持 `candidate`，不修改正式 Skill 行为。
+
+评分器本身也要参与回归：组件语义升级（如 `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。
+
+## 命令
+
+### 构建数据集
+
+```bash
+python skills/card-skill-trainer/scripts/build_dataset.py \
+  --src "<设计稿导出根目录>" \
+  --out training/datasets/v1 \
+  --max-cases 160
+```
+
+### 运行一轮
+
+```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]>`：只跑指定案例（冒烟用）。
+- `--only-failed training/runs/<上轮>`：只重跑上轮失败案例（修复验证快路径）。
+- `--no-correct`：禁用布局校正器，裸测生成器真实水平（里程碑对照用）。
+- `--splits train,dev`：限定分区（迭代纪律见上文）。
+
+渲染会话（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
+node skills/card-skill-trainer/scripts/diagnose_case.mjs \
+  --run training/runs/r060 \
+  --case <caseId>
+```
+
+产出 `<caseId>.side.png` 并排图、像素热区直方图、元素偏差 Top10、偏差节点→生成器
+源码行（`__prov`）溯源与失败类建议。
+
+### 轮间对比
+
+```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` 可豁免）。
+
+### 汇总报告
+
+```bash
+node skills/card-skill-trainer/scripts/score_round.mjs --run training/runs/r060
+```
+
+### 训练设施工具（`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...]   # 逐样本 spec 文本框 vs 渲染 elementBoxes 配对偏差
+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`）。
+
+## 输出
+
+```text
+training/runs/<round>/
+  cards/
+  slices/
+  reports/
+    <caseId>.json        ← 含 layoutCorrections / correctorRejected 校正明细
+    <caseId>.render.png  ← 最终渲染截图
+    <caseId>.design.png  ← 设计稿参考图
+    <caseId>.side.png    ← diagnose_case 并排对比图（按需生成）
+    summary.json       ← 含 roundGate / roundGatePassed / correctorCoverage
+    summary.md         ← 含晋级门禁表格与截图对比图廊
+    review-queue.jsonl
+    semantic-review.jsonl
+```
+
+`summary.md` 是唯一需要周期性查看的产物；如果所有门禁通过，可以完全不看。