cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/skills/dsl-card-generator/scripts/preflight.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * preflight.mjs — 生成前/后一键机械检查（替代 AI 手动过 Pre-flight Checklist）。
+ *
+ * 检查项（对应 quickref.md Pre-flight Checklist 12 条中可机械化的 10 条）：
+ *   1. 元素清单：spec text/slice/shape 数 vs schema 节点数（R29）
+ *   2. 组件白名单：className ∈ component-meta.json（R28）
+ *   3. Image itemValueFrom：静态路径必须 "2"，变量 "1"（R25）
+ *   4. Image rect.height：必须有显式高度（R32，否则被 aspect-ratio:16/9 压缩）
+ *   5. 切图文件名：含空格/特殊字符必须重命名（R31）
+ *   6. Icon eventaction：嵌套格式 event.eventKey（R30）
+ *   7. 百分比表达式：必须 Math.round（R23）
+ *   8. 分割线用 Divider：禁止 Row 模拟分割线（R28）
+ *   9. 卡片根样式全量提取：bg shape 有 border 但 schema 根容器未设（R33）
+ *  10. 空样式 itemId：style 子项 itemId 为空串 → 运行时静默丢弃
+ *
+ * 用法：
+ *   node preflight.mjs --spec UI/<画板>/spec.json --id <卡id>
+ *   node preflight.mjs --id <卡id>                        # 跳过 spec 比对（改卡时）
+ *   node preflight.mjs --id <卡id> --json                 # 机器可读输出
+ *
+ * 退出码：0 = 通过，1 = 有 ERROR
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { metaDir, cardsDir, slicesDir } from './lib/paths.mjs'
+
+/* ── args ── */
+const args = {}
+for (let i = 2; i < process.argv.length; i++) {
+  if (process.argv[i] === '--spec') args.spec = process.argv[++i]
+  else if (process.argv[i] === '--id') args.id = process.argv[++i]
+  else if (process.argv[i] === '--json') args.json = true
+}
+
+function loadJSONSafe(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')) } catch { return null } }
+
+const results = []
+function check(code, severity, message, detail) {
+  results.push({ code, severity, message, detail: detail || '' })
+}
+
+/* ── Load schema ── */
+const schemaDir = path.join(cardsDir, args.id || '')
+const schemaPath = path.join(schemaDir, 'schema.json')
+const schema = loadJSONSafe(schemaPath)
+if (!schema) {
+  console.error(`[preflight] 找不到 schema: ${schemaPath}`)
+  process.exit(1)
+}
+
+/* ── Load spec (optional) ── */
+const spec = args.spec ? loadJSONSafe(args.spec) : null
+const specCards = spec?.cards || []
+
+/* ── Load meta ── */
+const CM = loadJSONSafe(path.join(metaDir, 'component-meta.json'))
+const SM = loadJSONSafe(path.join(metaDir, 'style-meta.json'))
+const knownClasses = new Set(Object.keys(CM?.components || {}))
+
+/* ── helpers ── */
+function getStyleChild(node, groupKey, childKey) {
+  for (const sp of node?.style?.properties || []) {
+    if (sp.itemKey === groupKey) {
+      for (const c of sp.itemChildren?.properties || []) {
+        if (c.itemKey === childKey) return c
+      }
+    }
+  }
+  return null
+}
+function getProp(node, key) {
+  for (const p of node?.properties || []) {
+    if (p.itemKey === key) return p
+  }
+  return null
+}
+
+/* ── Walk all nodes ── */
+const allNodes = []
+function walkNode(node) {
+  if (!node || typeof node !== 'object') return
+  allNodes.push(node)
+  for (const c of node.components || []) walkNode(c)
+  for (const s of node.slots || []) for (const c of s.components || []) walkNode(c)
+}
+for (const c of schema.view?.components || []) walkNode(c)
+const viewNode = schema.view
+
+/* ══ Check 1: Element count vs schema nodes (R29) ══ */
+if (specCards.length > 0) {
+  const cardIdx = Math.min(1, specCards.length - 1) // main card
+  const card = specCards[cardIdx]
+  const elements = card.elements || []
+  const specTexts = elements.filter(e => e.type === 'text').length
+  const specSlices = elements.filter(e => e.type === 'slice').length
+  const specShapes = elements.filter(e => e.type === 'shape').length
+  const schemaTexts = allNodes.filter(n => n.className === 'Text').length
+  const schemaImages = allNodes.filter(n => n.className === 'Image').length
+  const schemaDividers = allNodes.filter(n => n.className === 'Divider').length
+  // Node count should be >= spec element count (merging is OK, missing is not)
+  const specTotal = specTexts + specSlices + specShapes
+  const schemaTotal = allNodes.length
+  if (schemaTotal < specTotal * 0.5) {
+    check('r29-element-count', 'warn', `Schema 节点数(${schemaTotal}) 远少于 spec 元素数(${specTotal}) → 可能遗漏元素（R29）`, `spec: text=${specTexts} slice=${specSlices} shape=${specShapes} | schema: Text=${schemaTexts} Image=${schemaImages} Divider=${schemaDividers} total=${schemaTotal}`)
+  }
+}
+
+/* ══ Check 2: Component whitelist (R28) ══ */
+for (const n of allNodes) {
+  if (n.className && !knownClasses.has(n.className)) {
+    check('r28-unknown-class', 'error', `${n.className} "${n.componentId}" 不在 component-meta.json 中 → 渲染空白（R28）`)
+  }
+}
+
+/* ══ Check 3: Image itemValueFrom (R25) ══ */
+for (const n of allNodes.filter(n => n.className === 'Image')) {
+  const valProp = getProp(n, 'value')
+  if (!valProp) continue
+  const from = String(valProp.itemValueFrom || '')
+  const val = String(valProp.itemValue || '')
+  if (from === '0' && !val.startsWith('$')) {
+    check('r25-image-from-0', 'error', `Image "${n.componentId}" itemValueFrom="0"(常量) 但值是路径 → 渲染器不走图片逻辑，空白（R25）。静态路径用 "2"`)
+  }
+  if (from === '1' && !val.startsWith('$')) {
+    check('r25-image-from-1', 'error', `Image "${n.componentId}" itemValueFrom="1"(变量) 但值不以 $ 开头 → 表达式求值失败，空白（R25）`)
+  }
+}
+
+/* ══ Check 4: Image rect.height (R32) ══ */
+for (const n of allNodes.filter(n => n.className === 'Image')) {
+  const h = getStyleChild(n, 'rect', 'height')
+  if (!h || !String(h.itemValue).trim()) {
+    check('r32-image-no-height', 'error', `Image "${n.componentId}" 缺 rect.height → CSS aspect-ratio:16/9 会压缩图片高度（R32）。设显式高度`)
+  }
+}
+
+/* ══ Check 5: Slice filename spaces (R31) ══ */
+for (const n of allNodes.filter(n => n.className === 'Image')) {
+  const valProp = getProp(n, 'value')
+  if (!valProp) continue
+  const val = String(valProp.itemValue || '')
+  if (val.includes('/slices/') && /\s/.test(val.replace('/slices/', ''))) {
+    check('r31-slice-filename-space', 'error', `Image "${n.componentId}" 引用路径含空格: "${val}" → CSS url() 空格断裂 → background-image:none（R31）。重命名为纯 ASCII`)
+  }
+}
+
+/* ══ Check 6: Icon eventaction format (R30) ══ */
+for (const n of allNodes.filter(n => n.className === 'Icon')) {
+  const eas = n.eventactions || []
+  for (const ea of eas) {
+    if (ea.event?.eventKey && !ea.action) {
+      check('r30-icon-no-action', 'warn', `Icon "${n.componentId}" 有 event 但无 action → 可能双触发（R30）`)
+    }
+  }
+}
+
+/* ══ Check 7: Percentage expression Math.round (R23) ══ */
+function walkExprs(node) {
+  const props = [...(node.properties || [])]
+  for (const sp of node.style?.properties || []) {
+    for (const c of sp.itemChildren?.properties || []) props.push(c)
+  }
+  for (const p of props) {
+    if (String(p.itemValueFrom) === '1' && typeof p.itemValue === 'string') {
+      if (/\*\s*100/.test(p.itemValue) && !/Math\.round/.test(p.itemValue)) {
+        check('r23-no-math-round', 'error', `"${node.componentId}" 表达式含 *100 但无 Math.round → JS 浮点精度问题（R23）: ${p.itemValue.slice(0, 50)}`)
+      }
+    }
+  }
+}
+for (const n of allNodes) walkExprs(n)
+
+/* ══ Check 8: Divider for separators (R28) ══ */
+// Heuristic: Row with height ≤2 and background color but no children = likely a divider
+for (const n of allNodes.filter(n => n.className === 'Row')) {
+  const h = getStyleChild(n, 'rect', 'height')
+  const bg = getStyleChild(n, 'background', 'backgroundColor')
+  const hasChildren = (n.slots || []).some(s => (s.components || []).length > 0)
+  const hVal = h ? parseFloat(String(h.itemValue)) : NaN
+  if (!hasChildren && !isNaN(hVal) && hVal > 0 && hVal <= 2 && bg) {
+    check('r28-row-as-divider', 'warn', `Row "${n.componentId}" height=${hVal} + bg 色块但无子节点 → 疑似分割线，应用 Divider 组件（R28）`)
+  }
+}
+
+/* ══ Check 9: Card root style completeness (R33) ══ */
+if (specCards.length > 0) {
+  const card = specCards[0]
+  // Find card bg shape
+  const bgShape = (card.elements || []).find(e =>
+    e.type === 'shape' &&
+    Math.abs(e.rect?.width - card.rect?.width) < 2 &&
+    Math.abs(e.rect?.height - card.rect?.height) < 2
+  )
+  if (bgShape?.style) {
+    const st = bgShape.style
+    // Check border
+    if (st.border?.isBorder) {
+      const rootBorder = getStyleChild(viewNode, 'border', 'isBorder')
+      // Also check first-level card container
+      const cardContainer = (viewNode?.components || [])[0]
+      const ccBorder = cardContainer ? getStyleChild(cardContainer, 'border', 'isBorder') : null
+      if (!rootBorder && !ccBorder) {
+        check('r33-root-missing-border', 'warn', `spec 卡片 bg shape 有 border(isBorder=true, w=${st.border.width}, color=${st.border.color}) 但 schema 根容器未设 border → 视觉缺失（R33）`)
+      }
+    }
+    // Check shadow
+    if (st.shadow?.isShadow) {
+      const rootShadow = getStyleChild(viewNode, 'shadow', 'isShadow')
+      const cardContainer = (viewNode?.components || [])[0]
+      const ccShadow = cardContainer ? getStyleChild(cardContainer, 'shadow', 'isShadow') : null
+      if (!rootShadow && !ccShadow) {
+        check('r33-root-missing-shadow', 'warn', `spec 卡片 bg shape 有 shadow 但 schema 根容器未设 → 视觉缺失（R33）`)
+      }
+    }
+  }
+}
+
+/* ══ Check 10: Empty style itemId ══ */
+for (const n of allNodes) {
+  for (const sp of n.style?.properties || []) {
+    for (const c of sp.itemChildren?.properties || []) {
+      if (c.itemId !== undefined && String(c.itemId).trim() === '') {
+        check('empty-style-itemid', 'error', `"${n.componentId}" style.${sp.itemKey}.${c.itemKey} itemId 为空 → 运行时静默丢弃该样式`)
+      }
+    }
+  }
+}
+
+/* ── Output ── */
+const errors = results.filter(r => r.severity === 'error')
+const warns = results.filter(r => r.severity === 'warn')
+
+if (args.json) {
+  console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings: warns }, null, 2))
+} else {
+  if (results.length === 0) {
+    console.log(`[preflight] ✅ ${args.id || ''} 全部检查通过（0 error, 0 warn）`)
+  } else {
+    console.log(`[preflight] ${args.id || ''} 共 ${results.length} 条：${errors.length} error / ${warns.length} warn`)
+    for (const r of [...errors, ...warns]) {
+      const icon = r.severity === 'error' ? '❌' : '⚠️'
+      console.log(`  ${icon} ${r.code}: ${r.message}`)
+      if (r.detail) console.log(`     ${r.detail}`)
+    }
+  }
+}
+
+process.exit(errors.length > 0 ? 1 : 0)

package/dist/vendored/skills/dsl-card-generator/scripts/register_card_template.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * register_card_template.mjs — 模板沉淀闭环的「登记时刻」。
+ *
+ * 首次做出一种新卡片模式（布局/交互在模板库中没有近亲）并交付后，用本工具把它
+ * 登记进整卡模板库：下次同类需求直接 scaffold --from 克隆秒出，不再走完整生成链路。
+ *
+ * 两种用法：
+ *   ① 新颖性检查（登记前先问一句，只报告不写入）：
+ *      node register_card_template.mjs --id <cardId> --check [--threshold 0.6]
+ *      → 输出本卡与各簇代表的结构签名相似度（Jaccard），给出「新模式/已有近亲」结论；
+ *        相似度 < 阈值 = 新模式，建议新建簇登记；否则建议顶替该簇或不登记。
+ *
+ *   ② 登记（人工确认后执行）：
+ *      node register_card_template.mjs --id <cardId> --cluster <簇key> [--keywords a,b,c]
+ *      → 健康门禁（validate 0 error + lint 0 error，模板必须是健康卡）→
+ *        簇已存在：顶替代表卡并 pin（重建不被打分覆盖）；簇不存在：新建自定义簇。
+ *
+ * 安全语义：--check 永不写盘；登记前必须过健康门禁；重建（build_card_templates.mjs）
+ * 保留 pinned 代表与 keywords。本工具不做自动登记——是否沉淀永远由人决定。
+ *
+ * 退出码：0 = 正常；1 = 健康门禁未过 / 参数错误。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { cardsDir, skillRoot } from './lib/paths.mjs'
+import { extractCardFeatures, loadRegistry } from './build_card_templates.mjs'
+
+const OUT = path.join(skillRoot, 'references', 'card_templates.json')
+const VALIDATOR = path.join(skillRoot, 'scripts', 'validate_schema.py')
+const LINTER = path.join(skillRoot, 'scripts', 'lint_card.mjs')
+const DEFAULT_THRESHOLD = 0.6
+
+function parseArgs(argv) {
+  const out = { id: '', cluster: '', keywords: [], check: false, threshold: DEFAULT_THRESHOLD }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--check') out.check = true
+    else if (a === '--id') out.id = argv[++i] || ''
+    else if (a === '--cluster') out.cluster = argv[++i] || ''
+    else if (a === '--keywords') out.keywords = (argv[++i] || '').split(/[,，]/).map((s) => s.trim()).filter(Boolean)
+    else if (a === '--threshold') out.threshold = Number(argv[++i]) || DEFAULT_THRESHOLD
+  }
+  return out
+}
+
+function resolvePython() {
+  if (process.env.DSL_PYTHON) return process.env.DSL_PYTHON
+  for (const cmd of ['python3', 'python']) {
+    try {
+      execFileSync(cmd, ['--version'], { stdio: 'ignore', timeout: 5000 })
+      return cmd
+    } catch { /* try next */ }
+  }
+  return null
+}
+
+/** 健康门禁：validate 0 error + lint 0 error。返回 { ok, reasons[] } */
+function healthGate(id) {
+  const reasons = []
+  const schemaPath = path.join(cardsDir, id, 'schema.json')
+  const python = resolvePython()
+  if (!python) {
+    reasons.push('python-not-found：无法跑 validate 门禁')
+  } else {
+    try {
+      const raw = execFileSync(python, [VALIDATOR, schemaPath, '--json'], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 })
+      const v = JSON.parse(raw)
+      if (!v.ok) reasons.push(`validate ${v.errors.length} 个 error：${(v.errors[0] || '').slice(0, 80)}`)
+    } catch (e) {
+      reasons.push(`validate 执行失败：${String(e.message).slice(0, 120)}`)
+    }
+  }
+  try {
+    const raw = execFileSync(process.execPath, [LINTER, '--id', id, '--json'], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 })
+    const l = JSON.parse(raw)
+    const findings = (l.reports && l.reports[0] && l.reports[0].findings) || []
+    const errors = findings.filter((f) => f.severity === 'error')
+    if (errors.length) reasons.push(`lint ${errors.length} 个 error：${(errors[0].message || '').slice(0, 80)}`)
+  } catch (e) {
+    // lint 有 error 时 exit≠0，stdout 仍在 error 对象上
+    const raw = e && e.stdout
+    if (raw) {
+      try {
+        const l = JSON.parse(raw)
+        const findings = (l.reports && l.reports[0] && l.reports[0].findings) || []
+        const errors = findings.filter((f) => f.severity === 'error')
+        if (errors.length) reasons.push(`lint ${errors.length} 个 error：${(errors[0].message || '').slice(0, 80)}`)
+        else reasons.push(`lint 执行异常：exit ${e.code}`)
+      } catch { reasons.push('lint 输出解析失败') }
+    } else {
+      reasons.push(`lint 执行失败：${String(e.message).slice(0, 120)}`)
+    }
+  }
+  return { ok: reasons.length === 0, reasons }
+}
+
+/** 结构签名 → 可比集合（comp:xxx / recipe:xxx 前缀区分两域） */
+function signatureSet(f) {
+  return new Set([...f.components.map((c) => `comp:${c}`), ...f.recipes.map((r) => `recipe:${r}`)])
+}
+
+function jaccard(a, b) {
+  let inter = 0
+  for (const x of a) if (b.has(x)) inter++
+  const union = a.size + b.size - inter
+  return union === 0 ? 1 : inter / union
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  if (!opts.id) {
+    console.error('[usage] --id <cardId> --check [--threshold 0.6]   （新颖性检查，只报告）')
+    console.error('[usage] --id <cardId> --cluster <簇key> [--keywords a,b,c]   （登记，过健康门禁）')
+    process.exit(1)
+  }
+  const features = extractCardFeatures(opts.id)
+  if (!features) {
+    console.error(`[error] 卡片不存在或 schema 无法解析：${opts.id}`)
+    process.exit(1)
+  }
+  const registry = loadRegistry()
+  const clusters = registry.clusters || []
+  const sig = signatureSet(features)
+
+  // ---- ① 新颖性检查 ----
+  if (opts.check) {
+    const scored = clusters
+      .map((c) => ({
+        key: c.key,
+        sourceCard: c.template.sourceCard,
+        similarity: jaccard(sig, signatureSet(c.template)),
+      }))
+      .sort((a, b) => b.similarity - a.similarity)
+    console.log(`\n🔍 新颖性检查：${opts.id}（${features.name}，${features.nodeCount} 节点）`)
+    console.log(`   签名：components=[${features.components.join(',')}] recipes=[${features.recipes.join(',') || '无'}]`)
+    for (const s of scored.slice(0, 5)) {
+      console.log(`   vs ${s.key.padEnd(12)}（${s.sourceCard}）  相似度 ${(s.similarity * 100).toFixed(1)}%`)
+    }
+    const top = scored[0]
+    if (!top || top.similarity < opts.threshold) {
+      console.log(`\n   ✅ 结论：新模式（最高相似度 ${top ? (top.similarity * 100).toFixed(1) + '%' : '无簇'} < ${opts.threshold * 100}%）。`)
+      console.log(`   建议登记为新簇：node register_card_template.mjs --id ${opts.id} --cluster <新簇key> --keywords <意图词,逗号分隔>`)
+    } else {
+      console.log(`\n   ℹ️ 结论：已有近亲（${top.key} 簇 / ${top.sourceCard}，相似度 ${(top.similarity * 100).toFixed(1)}%）。`)
+      console.log(`   若本卡版式明显更优，可顶替该簇代表：node register_card_template.mjs --id ${opts.id} --cluster ${top.key}`)
+    }
+    return
+  }
+
+  // ---- ② 登记 ----
+  if (!opts.cluster) {
+    console.error('[error] 登记需要 --cluster <簇key>（先用 --check 判断新建还是顶替）')
+    process.exit(1)
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(opts.cluster)) {
+    console.error('[error] 簇 key 必须是小写字母/数字/连字符（如 progress-drawer）')
+    process.exit(1)
+  }
+  const gate = healthGate(opts.id)
+  if (!gate.ok) {
+    console.error(`\n🚫 健康门禁未过，模板必须是健康卡：`)
+    for (const r of gate.reasons) console.error(`   - ${r}`)
+    process.exit(1)
+  }
+
+  const existing = clusters.find((c) => c.key === opts.cluster)
+  const template = {
+    sourceCard: features.id,
+    name: features.name,
+    tags: features.tags,
+    recipes: features.recipes,
+    components: features.components,
+    nodeCount: features.nodeCount,
+    pinned: true,
+  }
+  if (existing) {
+    existing.template = template
+    existing.keywords = [...new Set([...(existing.keywords || []), ...opts.keywords])]
+    if (!existing.members.includes(features.id)) existing.members.push(features.id)
+    existing.cardCount = existing.members.length
+    console.log(`\n📌 已顶替并 pin：簇 ${opts.cluster} 代表卡 → ${features.id}（${features.name}）`)
+    if (!existing.custom && features.cluster !== opts.cluster) {
+      console.log(`   ⚠️ 注意：该卡结构签名自动归类为「${features.cluster}」簇，与目标簇不同——已按你的人工意图 pin，重建不会回退。`)
+    }
+  } else {
+    clusters.push({
+      key: opts.cluster,
+      custom: true,
+      keywords: [...opts.keywords],
+      cardCount: 1,
+      template,
+      members: [features.id],
+    })
+    console.log(`\n🌱 已新建自定义簇 ${opts.cluster}：代表卡 ${features.id}（${features.name}）`)
+  }
+  if (opts.keywords.length) console.log(`   意图关键词：${opts.keywords.join(' / ')}`)
+
+  registry.generatedAt = new Date().toISOString()
+  fs.mkdirSync(path.dirname(OUT), { recursive: true })
+  fs.writeFileSync(OUT, JSON.stringify({ ...registry, clusters }, null, 2) + '\n')
+  console.log(`   注册表已更新：${OUT}`)
+  console.log(`   下次同类需求：scaffold_card.mjs --from ${features.id} --id <新卡id>`)
+}
+
+main()

package/dist/vendored/skills/dsl-card-generator/scripts/render_baseline.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * render_baseline.mjs — 渲染回归基线生成 + 像素 diff。
+ *
+ * 用途：
+ *   改了某个组件的 Vue 渲染器后，没人发现某张卡视觉变了。
+ *   本工具给每张导出卡在固定数据/视口下存一份 PNG 基线，
+ *   后续任何时候重跑都能比对当前渲染 vs 基线的像素差异。
+ *
+ * 两种模式：
+ *   --snapshot        生成/刷新基线（首次建立、渲染器改完后更新基线）
+ *   --diff            对比当前渲染与基线（CI 回归检测）
+ *   --snapshot --diff 先快照再立即对比（与上次的差异）
+ *
+ * 实现：复用同目录 render_card.mjs 的独立渲染器（vendor/preview 构建产物 + 系统 Chrome CDP），
+ *      不依赖 npm run dev、vite/vue/playwright，也不占用 5180/8787。
+ *
+ * 基线存放：<project>/.card-baselines/<cardId>.png
+ * diff 输出：<project>/.card-baselines/__diff__/<cardId>.png（红色高亮差异区）+ 控制台汇总
+ *
+ * 用法：
+ *   node render_baseline.mjs --snapshot                 # 全部卡建立基线
+ *   node render_baseline.mjs --snapshot --id <cardId>   # 单卡刷新基线
+ *   node render_baseline.mjs --diff                     # 全部卡对比基线
+ *   node render_baseline.mjs --diff --threshold 0.05    # 差异像素比例 > 5% 才报警
+ *   node render_baseline.mjs --json                     # JSON 输出（CI 友好）
+ *
+ * 前置条件：
+ *   - 系统 Chrome 已安装（独立渲染器用 CDP 启动 headless Chrome）
+ *   - 可选：sharp 已装（用于真实像素 diff；未装时降级为文件大小比较）
+ *
+ * 退出码：
+ *   0 成功 / 无差异；1 参数错；3 IO 错；
+ *   --diff 模式下有差异时退出 70（CI 可识别）
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { cardsDir, baselinesDir } from './lib/paths.mjs'
+import { renderCardScreenshot } from './render_card.mjs'
+
+const BASELINE_DIR = baselinesDir
+const DIFF_DIR = path.join(BASELINE_DIR, '__diff__')
+const DEFAULT_WIDTH = 390
+const CARD_SCREEN_WIDTH = 375
+const DEFAULT_THRESHOLD = 0.01 // 差异像素占比 > 1% 报警
+
+/* ------------------------------------------------------------------ */
+/* 参数解析                                                            */
+/* ------------------------------------------------------------------ */
+function parseArgs(argv) {
+  const out = { snapshot: false, diff: false, id: '', threshold: DEFAULT_THRESHOLD, json: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--snapshot') out.snapshot = true
+    else if (a === '--diff') out.diff = true
+    else if (a === '--id') out.id = argv[++i]
+    else if (a === '--threshold') out.threshold = parseFloat(argv[++i])
+    else if (a === '--json') out.json = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: node render_baseline.mjs [options]
+
+Options:
+  --snapshot               生成/刷新基线（写入 <project>/.card-baselines/<id>.png）
+  --diff                   对比当前渲染与基线（输出差异报告）
+  --id <cardId>            只处理单张卡（缺省全部 src/cards/*）
+  --threshold <0-1>        diff 模式下差异像素占比阈值（缺省 0.01 = 1%）
+  --json                   JSON 输出（CI 友好）
+  -h, --help               显示本帮助
+
+Examples:
+  node render_baseline.mjs --snapshot               # 首次建立基线
+  node render_baseline.mjs --diff                   # 改完渲染器后回归检测
+  node render_baseline.mjs --snapshot --id account  # 单卡刷新`)
+      process.exit(0)
+    }
+  }
+  if (!out.snapshot && !out.diff) {
+    console.error('[error] 必须指定 --snapshot 或 --diff（或两者）')
+    process.exit(1)
+  }
+  return out
+}
+
+/* ------------------------------------------------------------------ */
+/* 截图获取（复用 render_card.mjs 的独立渲染器）                        */
+/* ------------------------------------------------------------------ */
+async function fetchScreenshot(id, width = DEFAULT_WIDTH) {
+  // 旧截图端点 width=390 表示外层视口；卡片屏幕实际固定 375。独立渲染器按卡宽收参。
+  const cardWidth = width === DEFAULT_WIDTH ? CARD_SCREEN_WIDTH : width
+  const r = await renderCardScreenshot({ id, width: cardWidth, format: 'png' })
+  if (r.error) throw new Error(r.message || r.error)
+  return Buffer.from(r.base64, 'base64')
+}
+
+/* ------------------------------------------------------------------ */
+/* 像素 diff（用 sharp；若未装则降级为文件大小/hash 比较）              */
+/* ------------------------------------------------------------------ */
+async function pixelDiff(baselineBuf, currentBuf, threshold) {
+  // 快速路径：字节完全一致 → 0 差异
+  if (Buffer.compare(baselineBuf, currentBuf) === 0) {
+    return { diffRatio: 0, diffPixels: 0, totalPixels: 0, note: 'byte-identical' }
+  }
+  // 尝试加载 sharp 做真实像素 diff
+  try {
+    const sharp = (await import('sharp')).default
+    const a = sharp(baselineBuf).ensureAlpha().raw()
+    const b = sharp(currentBuf).ensureAlpha().raw()
+    const [metaA, metaB] = await Promise.all([a.metadata(), b.metadata()])
+    if (metaA.width !== metaB.width || metaA.height !== metaB.height) {
+      return {
+        diffRatio: 1,
+        diffPixels: -1,
+        totalPixels: -1,
+        note: `size-changed: ${metaA.width}x${metaA.height} → ${metaB.width}x${metaB.height}`,
+      }
+    }
+    const w = metaA.width
+    const h = metaA.height
+    const total = w * h
+    const dataA = await a.toBuffer()
+    const dataB = await b.toBuffer()
+    let diffPixels = 0
+    const channels = Math.min(metaA.channels, metaB.channels, 3)
+    // 简单像素差异：任一通道差 > 16 算差异
+    for (let i = 0; i < total; i++) {
+      const off = i * metaA.channels
+      let isDiff = false
+      for (let c = 0; c < channels; c++) {
+        if (Math.abs(dataA[off + c] - dataB[off + c]) > 16) {
+          isDiff = true
+          break
+        }
+      }
+      if (isDiff) diffPixels++
+    }
+    const ratio = diffPixels / total
+    return { diffRatio: ratio, diffPixels, totalPixels: total, note: 'pixel-diff' }
+  } catch {
+    // sharp 未装：降级为文件大小比较
+    return {
+      diffRatio: baselineBuf.length === currentBuf.length ? 0 : 1,
+      diffPixels: -1,
+      totalPixels: -1,
+      note: 'fallback-size-diff（装 sharp 可启用真实像素 diff）',
+    }
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* 主流程                                                              */
+/* ------------------------------------------------------------------ */
+function listCardIds(filterId) {
+  if (filterId) return [filterId]
+  return fs
+    .readdirSync(cardsDir)
+    .filter((d) => fs.existsSync(path.join(cardsDir, d, 'schema.json')))
+}
+
+async function snapshotOne(id) {
+  const buf = await fetchScreenshot(id)
+  const outFile = path.join(BASELINE_DIR, `${id}.png`)
+  fs.mkdirSync(BASELINE_DIR, { recursive: true })
+  fs.writeFileSync(outFile, buf)
+  return { id, bytes: buf.length, path: outFile }
+}
+
+async function diffOne(id, threshold) {
+  const baselinePath = path.join(BASELINE_DIR, `${id}.png`)
+  if (!fs.existsSync(baselinePath)) {
+    return { id, skipped: true, reason: 'no-baseline（先跑 --snapshot）' }
+  }
+  const baselineBuf = fs.readFileSync(baselinePath)
+  const currentBuf = await fetchScreenshot(id)
+  const r = await pixelDiff(baselineBuf, currentBuf, threshold)
+  // 差异超阈值时保存当前截图到 __diff__/ 便于人工查看
+  if (r.diffRatio > threshold) {
+    fs.mkdirSync(DIFF_DIR, { recursive: true })
+    fs.writeFileSync(path.join(DIFF_DIR, `${id}.current.png`), currentBuf)
+    fs.writeFileSync(path.join(DIFF_DIR, `${id}.baseline.png`), baselineBuf)
+  }
+  return { id, ...r, overThreshold: r.diffRatio > threshold }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  fs.mkdirSync(BASELINE_DIR, { recursive: true })
+  const ids = listCardIds(args.id)
+  const results = []
+
+  for (const id of ids) {
+    try {
+      if (args.snapshot) {
+        const r = await snapshotOne(id)
+        if (!args.json) console.log(`[snapshot] ${id} → ${r.bytes} bytes`)
+        results.push({ op: 'snapshot', ...r })
+      }
+      if (args.diff) {
+        const r = await diffOne(id, args.threshold)
+        if (!args.json) {
+          if (r.skipped) console.log(`[diff] ${id}: 跳过（${r.reason}）`)
+          else if (r.overThreshold) {
+            const pct = (r.diffRatio * 100).toFixed(2)
+            console.log(`[diff] ${id}: ❌ 差异 ${pct}% (${r.diffPixels}/${r.totalPixels} px) — 已存 ${DIFF_DIR}/${id}.{current,baseline}.png`)
+          } else {
+            console.log(`[diff] ${id}: ✅ 一致 (${r.note})`)
+          }
+        }
+        results.push({ op: 'diff', ...r })
+      }
+    } catch (e) {
+      if (!args.json) console.error(`[error] ${id}: ${e.message}`)
+      results.push({ op: args.snapshot ? 'snapshot' : 'diff', id, error: e.message })
+    }
+  }
+
+  if (args.json) console.log(JSON.stringify({ results }, null, 2))
+
+  // diff 模式下，有任何差异 → exit 70（CI 可识别）
+  if (args.diff) {
+    const overCount = results.filter((r) => r.op === 'diff' && r.overThreshold).length
+    if (!args.json && overCount) {
+      console.log(`\n共 ${overCount} 张卡差异超阈值（${args.threshold * 100}%）`)
+    }
+    if (overCount) process.exit(70)
+  }
+  process.exit(0)
+}
+
+main()