cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,700 @@
+#!/usr/bin/env node
+/**
+ * iterate.mjs — 单进程一条龙迭代闭环（expand → lint → render → pixel-diff）。
+ *
+ * 相比逐脚本调用（expand_ir.mjs + lint_card.mjs + render_card.mjs + render_diff.mjs），
+ * 消除 3 次 Node 进程冷启 + 1 次 Chrome 冷启，单轮从 ~7.7s → ~1.5s。
+ *
+ * 用法（单次）：
+ *   node iterate.mjs --ir <path.json> --out <cardDir> --design <design.png> [--width 343]
+ *
+ * 用法（带 IR 微调）：
+ *   node iterate.mjs --ir <path.json> --out <cardDir> --design <design.png> \
+ *     --set 'children.0.children.2.children.1.s.margin.marginTop="7"'
+ *   --set 可重复；点路径（数字段=数组下标）寻址，原子写回 IR（tmp+rename），
+ *   中间路径不存在则响亮报错且不写文件。
+ *
+ * 用法（keep-alive，迭代间复用 Chrome）：
+ *   node iterate.mjs --keep-alive
+ *   stdin 逐行输入 JSON：
+ *     {"ir":"/tmp/card.ir.json","out":"src/cards/myCard/","design":"UI/.../card-1.png","width":343}
+ *   每行输出一行 JSON 结果。Ctrl-D 结束。
+ *
+ * 输出（stdout JSON）：
+ *   {
+ *     "ok": true,
+ *     "cardId": "myCard",
+ *     "validate": { "errors": 0, "warnings": 2 },
+ *     "lint": { "errors": 0, "warnings": 0, "infos": 1 },
+ *     "render": { "ms": 486, "width": 686, "height": 1234 },
+ *     "pixelDiff": { "match": 89.89, "diffRatio": 0.1011, "totalPixels": 844188, "diffPixels": 85432 },
+ *     "diffImage": ".card-diffs/myCard_diff.png"
+ *   }
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+
+import { expandIR, runAutofixAndValidate, syncReferencedSlices } from './expand_ir.mjs'
+import { rewriteSliceRefs } from './lib/slice_dedupe.mjs'
+import { lint } from './lint_card.mjs'
+import { createRenderSession, renderCardScreenshot } from './render_card.mjs'
+import { copyCardDesignImage } from './lib/design_image.mjs'
+import { cardsDir, cardSchemaPath, cardDataPath, readJson, repoRoot } from './lib/paths.mjs'
+
+const { PNG } = await import('pngjs')
+
+const DEFAULT_DIFF_DIR = path.join(repoRoot, '.card-diffs')
+const DEFAULT_WIDTH = 375
+/** 报告落盘目录：门禁（--gate）只认这里的机器产物，不认模型自述 */
+const SCRATCH_DIR = path.join(repoRoot, '.cache', 'ai-scratch')
+const PREFLIGHT_SCRIPT = path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'preflight.mjs')
+/** 收敛门禁阈值（协议 S5/S6 的机器化版本，改这里即改门禁） */
+const GATE = { match: 95, heightDelta: 0, widthDelta: 0, contentOffset1x: 2 }
+
+/* ── IR 原子编辑（--set）────────────────────────────────────
+ * 点路径寻址，数字段按数组下标：children.0.s.margin.marginTop="7"
+ * 中间节点必须已存在（防拼写错误静默建错分支），末段可新建。
+ * 值先按 JSON.parse 解析（数字/布尔/对象），失败则去引号按字符串。
+ * 写回采用 tmp+rename 原子替换，崩溃不留半状态。 */
+function setByPath(root, dottedPath, rawValue) {
+  const segs = String(dottedPath).split('.').filter(Boolean)
+  if (!segs.length) throw new Error(`空路径: "${dottedPath}"`)
+  let node = root
+  for (let i = 0; i < segs.length - 1; i++) {
+    const k = segs[i]
+    const next = Array.isArray(node) ? node[Number(k)] : node[k]
+    if (next === undefined || next === null || typeof next !== 'object') {
+      throw new Error(`路径中段不存在或不是对象: ${segs.slice(0, i + 1).join('.')}（完整路径 ${dottedPath}）`)
+    }
+    node = next
+  }
+  let value
+  try {
+    value = JSON.parse(rawValue)
+  } catch {
+    value = String(rawValue).replace(/^["']|["']$/g, '')
+  }
+  const lastKey = segs[segs.length - 1]
+  if (Array.isArray(node)) node[Number(lastKey)] = value
+  else node[lastKey] = value
+  return value
+}
+
+function applySetsAtomic(irPath, sets) {
+  const ir = JSON.parse(fs.readFileSync(irPath, 'utf8'))
+  const applied = []
+  for (const expr of sets) {
+    const eq = expr.indexOf('=')
+    if (eq <= 0) throw new Error(`--set 表达式须为 path=value 形式: "${expr}"`)
+    const p = expr.slice(0, eq)
+    const v = expr.slice(eq + 1)
+    applied.push({ path: p, value: setByPath(ir, p, v) })
+  }
+  const tmp = `${irPath}.tmp-${process.pid}`
+  fs.writeFileSync(tmp, JSON.stringify(ir, null, 2) + '\n')
+  fs.renameSync(tmp, irPath)
+  return { ir, applied }
+}
+
+/** 墨迹包围盒：跳过透明与近白底，返回内容的外接矩形（设备像素）。
+ *  threshold 取 48（=与纯白的 RGB 距离和）：浅色背景带（如 #F7F4F1，距离 33）算底不算内容，
+ *  否则「设计有浅色渐变带、渲染没有」会被误报成整体平移。
+ *  用途 = 判断「内容整体平移」：match 卡住时，若渲染与设计的墨迹起点差了几个像素，
+ *  问题在水平/垂直对齐（Root padding、首层 margin），继续逐行调间距纯属浪费轮次。
+ *  实测事故：模型把这类偏移误判成「渲染器顶部蓝条 = 测量噪声」并据此收工。 */
+function inkBounds(png, { threshold = 48 } = {}) {
+  let x0 = png.width
+  let y0 = png.height
+  let x1 = -1
+  let y1 = -1
+  for (let y = 0; y < png.height; y++) {
+    for (let x = 0; x < png.width; x++) {
+      const i = (y * png.width + x) * 4
+      if (png.data[i + 3] < 8) continue
+      const near = Math.abs(255 - png.data[i]) + Math.abs(255 - png.data[i + 1]) + Math.abs(255 - png.data[i + 2])
+      if (near <= threshold) continue
+      if (x < x0) x0 = x
+      if (x > x1) x1 = x
+      if (y < y0) y0 = y
+      if (y > y1) y1 = y
+    }
+  }
+  if (x1 < 0) return null
+  return { x0, y0, x1, y1, w: x1 - x0 + 1, h: y1 - y0 + 1 }
+}
+
+/* ── 像素对比 ──────────────────────────────────────────────── */
+function pixelDiff(renderBuf, designBuf) {
+  const rPng = PNG.sync.read(renderBuf)
+  const dPng = PNG.sync.read(designBuf)
+  // 并集画布对比：只比重叠区会让「删内容 / 高度塌缩」反而提分
+  // （历史事故：match 89.96 但渲染高度比设计少 204px）。超出任一侧的采样点一律计为差异，
+  // 尺寸偏差因此直接体现在 match 上，删元素不可能再刷分。
+  const w = Math.max(rPng.width, dPng.width)
+  const h = Math.max(rPng.height, dPng.height)
+  const idxOf = (png, i, j) => (i < png.height && j < png.width ? (i * png.width + j) * 4 : -1)
+  const isDiff = (i, j) => {
+    const ri = idxOf(rPng, i, j)
+    const di = idxOf(dPng, i, j)
+    if (ri < 0 || di < 0) return true
+    const dr = Math.abs(rPng.data[ri] - dPng.data[di])
+    const dg = Math.abs(rPng.data[ri + 1] - dPng.data[di + 1])
+    const db = Math.abs(rPng.data[ri + 2] - dPng.data[di + 2])
+    return Math.max(dr, dg, db) > 30
+  }
+  const count = (step) => {
+    let diff = 0
+    let sampled = 0
+    for (let i = 0; i < h; i += step) {
+      for (let j = 0; j < w; j += step) {
+        if (isDiff(i, j)) diff++
+        sampled++
+      }
+    }
+    return { diff, sampled }
+  }
+  // 降采样 step=2 只采样 1/4 像素；接近阈值（±3%）时回退全量保证精度
+  const s = count(2)
+  const matchApprox = 100 - (s.diff / s.sampled) * 100
+  const totalPixels = w * h
+  const actualDiffPixels = matchApprox > 82 && matchApprox < 88 ? count(1).diff : Math.round((s.diff / s.sampled) * totalPixels)
+  // 内容偏移：渲染墨迹盒相对设计墨迹盒的位移（设备像素，报告里再折算 1x）
+  const rBox = inkBounds(rPng)
+  const dBox = inkBounds(dPng)
+  const contentOffset = rBox && dBox ? { dx: rBox.x0 - dBox.x0, dy: rBox.y0 - dBox.y0 } : null
+  return {
+    match: Number((100 - (actualDiffPixels / totalPixels) * 100).toFixed(2)),
+    diffRatio: Number(((actualDiffPixels / totalPixels) * 100).toFixed(2)),
+    totalPixels,
+    diffPixels: actualDiffPixels,
+    size: {
+      render: [rPng.width, rPng.height],
+      design: [dPng.width, dPng.height],
+      widthDelta: rPng.width - dPng.width,
+      heightDelta: rPng.height - dPng.height,
+    },
+    contentOffset,
+    inkBox: rBox && dBox ? { render: rBox, design: dBox } : null,
+  }
+}
+
+/* ── diff 热区摘要（AI 免读整张对比图）────────────────────────
+ * 把渲染/设计重叠区划分为 cols×rows 网格，逐格算 diff%，
+ * 返回超过 floorPct 的热格（按差异降序，坐标换算为 1x 设计稿坐标）。
+ * AI 据此直接定位差异区域（如 "热区 [16,288,96,142] diff 18%"），
+ * 无需每轮 view_image 整张 1080×726 并排对比图。 */
+function diffHotspots(renderPng, designPng, { cols = 4, rows = 8, floorPct = 3, maxCells = 8, scale = 2 } = {}) {
+  const w = Math.min(renderPng.width, designPng.width)
+  const h = Math.min(renderPng.height, designPng.height)
+  const cellW = Math.max(1, Math.floor(w / cols))
+  const cellH = Math.max(1, Math.floor(h / rows))
+  const step = 2
+  const diff = new Float64Array(cols * rows)
+  const seen = new Float64Array(cols * rows)
+  for (let y = 0; y < h; y += step) {
+    const cellRow = Math.min(rows - 1, Math.floor(y / cellH))
+    for (let x = 0; x < w; x += step) {
+      const cellCol = Math.min(cols - 1, Math.floor(x / cellW))
+      const ci = cellRow * cols + cellCol
+      const idx = (y * w + x) * 4
+      const dr = Math.abs(renderPng.data[idx] - designPng.data[idx])
+      const dg = Math.abs(renderPng.data[idx + 1] - designPng.data[idx + 1])
+      const db = Math.abs(renderPng.data[idx + 2] - designPng.data[idx + 2])
+      if (Math.max(dr, dg, db) > 30) diff[ci]++
+      seen[ci]++
+    }
+  }
+  const cells = []
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const ci = r * cols + c
+      if (!seen[ci]) continue
+      const pct = (diff[ci] / seen[ci]) * 100
+      if (pct < floorPct) continue
+      cells.push({
+        x: Math.round((c * cellW) / scale),
+        y: Math.round((r * cellH) / scale),
+        w: Math.round(cellW / scale),
+        h: Math.round(cellH / scale),
+        diffPct: Number(pct.toFixed(1)),
+      })
+    }
+  }
+  cells.sort((a, b) => b.diffPct - a.diffPct)
+  return cells.slice(0, maxCells)
+}
+
+/* ── 合成并排对比图（内存，可选写盘） ──────────────────────── */
+function composeSideBySide(designBuf, renderBuf) {
+  const designPng = PNG.sync.read(designBuf)
+  const renderPng = PNG.sync.read(renderBuf)
+  const targetH = Math.min(designPng.height, renderPng.height, 700)
+  const ds = targetH / designPng.height
+  const rs = targetH / renderPng.height
+  const dW = Math.round(designPng.width * ds)
+  const rW = Math.round(renderPng.width * rs)
+  const HEADER_H = 24
+  const GAP = 4
+  const PAD = 1
+  const totalW = PAD + dW + GAP + rW + PAD
+  const totalH = PAD + HEADER_H + targetH + PAD
+  const canvas = new PNG({ width: totalW, height: totalH })
+  for (let i = 0; i < canvas.data.length; i += 4) {
+    canvas.data[i] = 255
+    canvas.data[i + 1] = 255
+    canvas.data[i + 2] = 255
+    canvas.data[i + 3] = 255
+  }
+  function setPx(x, y, rgba) {
+    if (x < 0 || x >= totalW || y < 0 || y >= totalH) return
+    const idx = (totalW * y + x) * 4
+    canvas.data[idx] = rgba[0]
+    canvas.data[idx + 1] = rgba[1]
+    canvas.data[idx + 2] = rgba[2]
+    canvas.data[idx + 3] = 255
+  }
+  // headers
+  for (let dy = 0; dy < HEADER_H; dy++)
+    for (let dx = 0; dx < dW; dx++) setPx(PAD + dx, PAD + dy, [102, 102, 102])
+  for (let dy = 0; dy < HEADER_H; dy++)
+    for (let dx = 0; dx < rW; dx++) setPx(PAD + dW + GAP + dx, PAD + dy, [41, 98, 255])
+  // blit
+  function blit(src, dstX, dstY, dstW, dstH) {
+    const sw = src.width, sh = src.height
+    for (let y = 0; y < dstH; y++) {
+      const sy = Math.min(sh - 1, Math.floor(y / (dstH / sh)))
+      for (let x = 0; x < dstW; x++) {
+        const sx = Math.min(sw - 1, Math.floor(x / (dstW / sw)))
+        const sIdx = (sw * sy + sx) * 4
+        setPx(dstX + x, dstY + y, [src.data[sIdx], src.data[sIdx + 1], src.data[sIdx + 2], src.data[sIdx + 3]])
+      }
+    }
+  }
+  blit(designPng, PAD, PAD + HEADER_H, dW, Math.round(targetH))
+  blit(renderPng, PAD + dW + GAP, PAD + HEADER_H, rW, Math.round(targetH))
+  return { buffer: PNG.sync.write(canvas), width: totalW, height: totalH }
+}
+
+/* ── 机器门禁基础设施 ────────────────────────────────────────
+ * 历史事故（all-components-test / 07 画板）：模型在 match=93.11、heightDelta=-6 的情况下
+ * 正文宣称「门禁全绿」，还编了条「渲染图顶部蓝条是迭代器标注、属测量噪声」的假因果
+ * （蓝条只是 composeSideBySide 的标题栏，pixelDiff 根本不读合成图）。
+ * 结论：门禁不能由模型自述，必须由脚本落盘 + 机器判定，正文只能引用判定结果。 */
+function hashFile(p) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex').slice(0, 16)
+  } catch {
+    return null
+  }
+}
+
+/** preflight.mjs = quickref「Pre-flight Checklist」12 条里可机械化的 10 条。
+ *  此前它没被任何协议阶段点名，模型从来不知道它存在 —— 这里直接并进每轮迭代报告。 */
+function runPreflight({ cardId, specPath }) {
+  if (!fs.existsSync(PREFLIGHT_SCRIPT)) return null
+  const args = [PREFLIGHT_SCRIPT, '--id', cardId, '--json']
+  if (specPath) args.push('--spec', specPath)
+  try {
+    const r = spawnSync(process.execPath, args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 })
+    const text = String(r.stdout || '')
+    const j = JSON.parse(text.slice(text.indexOf('{')))
+    const errors = Array.isArray(j.errors) ? j.errors : []
+    const warnings = Array.isArray(j.warnings) ? j.warnings : []
+    return {
+      errors: errors.length,
+      warnings: warnings.length,
+      details: errors.slice(0, 6).map((e) => `${e.code}: ${e.message}`),
+      warningDetails: warnings.slice(0, 4).map((e) => `${e.code}: ${e.message}`),
+    }
+  } catch {
+    return null
+  }
+}
+
+/** 门禁判定：全部数值项来自本轮报告，任何一项不达标 passed=false。 */
+function evaluateGate(r) {
+  const pd = r.pixelDiff || {}
+  const co = r.contentOffset1x || null
+  const checks = [
+    { name: 'validate.errors', value: r.validate?.errors ?? null, required: '=0', ok: (r.validate?.errors ?? 1) === 0 },
+    { name: 'lint.errors', value: r.lint?.errors ?? null, required: '=0', ok: (r.lint?.errors ?? 1) === 0 },
+  ]
+  if (r.preflight) checks.push({ name: 'preflight.errors', value: r.preflight.errors, required: '=0', ok: r.preflight.errors === 0 })
+  if (pd.match != null) checks.push({ name: 'pixelDiff.match', value: pd.match, required: `>=${GATE.match}`, ok: pd.match >= GATE.match })
+  if (pd.size) {
+    checks.push({ name: 'pixelDiff.size.heightDelta', value: pd.size.heightDelta, required: `=${GATE.heightDelta}`, ok: pd.size.heightDelta === GATE.heightDelta })
+    checks.push({ name: 'pixelDiff.size.widthDelta', value: pd.size.widthDelta, required: `=${GATE.widthDelta}`, ok: pd.size.widthDelta === GATE.widthDelta })
+  }
+  if (co) checks.push({ name: 'contentOffset1x', value: `${co.dx}/${co.dy}`, required: `|dx|,|dy|<=${GATE.contentOffset1x}`, ok: Math.abs(co.dx) <= GATE.contentOffset1x && Math.abs(co.dy) <= GATE.contentOffset1x })
+  const failed = checks.filter((c) => !c.ok)
+  return {
+    passed: failed.length === 0,
+    checks,
+    failed: failed.map((c) => `${c.name}=${c.value}（要求 ${c.required}）`),
+    verdict: failed.length === 0 ? 'PASS' : `FAIL：${failed.map((c) => `${c.name}=${c.value}`).join('，')}`,
+  }
+}
+
+/** 报告落盘 + 轮次历史 + 停滞检测（同热区连调多轮 = 微调已无收益，必须换证据链）。 */
+function persistReport(result, { sp, dp }) {
+  try {
+    fs.mkdirSync(SCRATCH_DIR, { recursive: true })
+    const reportPath = path.join(SCRATCH_DIR, `${result.cardId}.iterate.json`)
+    let prev = null
+    try {
+      prev = JSON.parse(fs.readFileSync(reportPath, 'utf8'))
+    } catch {}
+    const pd = result.pixelDiff || {}
+    const hotSig = (pd.hotspots || []).slice(0, 3).map((h) => `${h.x},${h.y}`).join('|')
+    const history = Array.isArray(prev?.history) ? prev.history.slice(-9) : []
+    const last = history[history.length - 1]
+    let stalledRounds = 1
+    if (last && pd.match != null && last.match != null) {
+      const sameScore = Math.abs(last.match - pd.match) < 0.3
+      const sameHot = hotSig && last.hotSig === hotSig
+      if (sameScore && sameHot) stalledRounds = (prev?.stalled?.rounds || 1) + 1
+    }
+    history.push({
+      ts: Date.now(),
+      match: pd.match ?? null,
+      heightDelta: pd.size?.heightDelta ?? null,
+      contentOffset1x: result.contentOffset1x || null,
+      lintErrors: result.lint?.errors ?? null,
+      validateErrors: result.validate?.errors ?? null,
+      hotSig,
+      sets: (result.appliedSets || []).map((a) => a.path),
+    })
+    const persisted = {
+      ...result,
+      elements: undefined,
+      schemaHash: hashFile(sp),
+      dataHash: hashFile(dp),
+      history,
+      stalled: stalledRounds >= 2 ? { rounds: stalledRounds } : undefined,
+    }
+    persisted.gate = evaluateGate(persisted)
+    fs.writeFileSync(reportPath, JSON.stringify(persisted, null, 2) + '\n')
+    return { reportPath, stalled: persisted.stalled, gate: persisted.gate, rounds: history.length }
+  } catch {
+    return null
+  }
+}
+
+/* ── 核心管线 ──────────────────────────────────────────────── */
+async function runPipeline({ ir: irPath, out: outDir, design: designPath, width, session, alwaysDiffImage, withElements, sets, specPath, skipPreflight, slicesDir: slicesDirArg }) {
+  const t0 = performance.now()
+
+  // 1. Read IR（可选 --set 编辑，原子写回）→ expand
+  let ir
+  let appliedSets = null
+  if (sets && sets.length) {
+    const r = applySetsAtomic(irPath, sets)
+    ir = r.ir
+    appliedSets = r.applied
+  } else {
+    ir = JSON.parse(fs.readFileSync(irPath, 'utf8'))
+  }
+  const { schema, data } = expandIR(ir)
+
+  // 2. Write schema + data
+  fs.mkdirSync(outDir, { recursive: true })
+  const sp = path.join(outDir, 'schema.json')
+  const dp = path.join(outDir, 'data.json')
+  fs.writeFileSync(sp, JSON.stringify(schema, null, 2) + '\n')
+  fs.writeFileSync(dp, JSON.stringify(data, null, 2) + '\n')
+
+  // 1b. 切图汇聚 + 同内容去重（与 expand_ir CLI 同源，slices_convention.md §3.1）：
+  //     src/slices 已有同内容文件 → 不重复导入，引用改写到既有语义名并回写 schema/data。
+  const sliceSync = syncReferencedSlices(schema, irPath, slicesDirArg)
+  if (sliceSync.rewrites.length) {
+    rewriteSliceRefs(data, sliceSync.rewrites)
+    fs.writeFileSync(sp, JSON.stringify(schema, null, 2) + '\n')
+    fs.writeFileSync(dp, JSON.stringify(data, null, 2) + '\n')
+  }
+
+  const cardId = ir.id || path.basename(path.dirname(outDir))
+
+  // 归档设计稿：card-*.png → <outDir>/<cardId>.png（复制而非移动，保留 UI 原件）
+  const designImage = copyCardDesignImage({ designPath, outDir, cardId })
+
+  // 3. Lint (in-process)
+  const lintFindings = lint(schema, data)
+  const lintErrors = lintFindings.filter((f) => f.severity === 'error')
+  const lintWarns = lintFindings.filter((f) => f.severity === 'warn')
+  const lintInfos = lintFindings.filter((f) => f.severity === 'info')
+
+  // 3.5 真校验门禁：autofix（机械修复）+ validate_schema.py。
+  // 历史事故：这里曾硬编码 validate:{errors:0}，模型信任它把 flexEnd 之类的硬错误 ship 了出去。
+  let validateReport = { errors: 0, warnings: 0, details: [] }
+  try {
+    const v = runAutofixAndValidate(sp)
+    const errs = Array.isArray(v.errors) ? v.errors : []
+    const warns = Array.isArray(v.warnings) ? v.warnings : []
+    validateReport = { ok: !!v.ok, errors: errs.length, warnings: warns.length, details: errs.slice(0, 5) }
+  } catch (e) {
+    validateReport = { ok: false, errors: 1, warnings: 0, details: [`validate 执行异常: ${e.message || e}`] }
+  }
+
+  // 4. Render (reuse session if provided, else cold start)
+  const renderWidth = width || Number(schema.view?.width) || DEFAULT_WIDTH
+  let renderRes
+  if (session) {
+    renderRes = await session.render({ id: cardId, width: renderWidth, format: 'png', hotReload: true, captureElements: !!withElements })
+  } else {
+    renderRes = await renderCardScreenshot({ id: cardId, width: renderWidth, format: 'png', captureElements: !!withElements })
+  }
+
+  if (renderRes.error) {
+    return {
+      ok: false,
+      cardId,
+      error: renderRes.error,
+      message: renderRes.message || 'render failed',
+      validate: validateReport,
+      lint: { errors: lintErrors.length, warnings: lintWarns.length, infos: lintInfos.length },
+    }
+  }
+
+  const renderBuf = Buffer.from(renderRes.base64, 'base64')
+
+  // 5. Pixel diff vs design (if provided) — 仅计算 match%，对比图每轮都重写（历史事故：
+  //    旧对比图只在 match<90 时更新，模型/用户读到的是上一轮的坏产物，误判收敛状态）
+  let pixelDiffResult = null
+  let diffImagePath = null
+  let renderImagePath = null
+  if (designPath && fs.existsSync(designPath)) {
+    const designBuf = fs.readFileSync(designPath)
+    pixelDiffResult = pixelDiff(renderBuf, designBuf)
+    // diff 热区摘要：AI 直接读坐标定位差异，不必每轮查看整张并排对比图
+    try {
+      const renderPng = PNG.sync.read(renderBuf)
+      const designPng = PNG.sync.read(designBuf)
+      const scale = renderWidth ? renderPng.width / renderWidth : 2
+      pixelDiffResult.hotspots = diffHotspots(renderPng, designPng, { scale })
+    } catch {}
+    if (true) {
+      const composed = composeSideBySide(designBuf, renderBuf)
+      diffImagePath = path.join(DEFAULT_DIFF_DIR, `${cardId}_diff.png`)
+      fs.mkdirSync(DEFAULT_DIFF_DIR, { recursive: true })
+      fs.writeFileSync(diffImagePath, composed.buffer)
+    }
+  }
+
+  // 渲染原图（无标题栏、无并排合成）落到 scratch，供像素取证与 diff_bands --render 复用
+  try {
+    fs.mkdirSync(SCRATCH_DIR, { recursive: true })
+    renderImagePath = path.join(SCRATCH_DIR, `${cardId}.render.png`)
+    fs.writeFileSync(renderImagePath, renderBuf)
+  } catch {
+    renderImagePath = null
+  }
+
+  const elapsed = Math.round(performance.now() - t0)
+
+  // 5.5 preflight（quickref Pre-flight Checklist 的机械化 10 条）并入本轮报告
+  const preflight = skipPreflight ? null : runPreflight({ cardId, specPath })
+
+  const result = {
+    ok: true,
+    cardId,
+    appliedSets: appliedSets || undefined,
+    validate: validateReport,
+    lint: {
+      errors: lintErrors.length,
+      warnings: lintWarns.length,
+      infos: lintInfos.length,
+      details: lintErrors.length ? lintErrors.slice(0, 5) : [],
+      // 预警也要回喂：以前只给 errors，warnings 只有计数没有内容，
+      // 模型永远看不到「快出事」的信号（例如装饰条宽度未绑标题长度）。
+      warningDetails: lintWarns.length ? lintWarns.slice(0, 5).map((f) => `${f.code}: ${f.message}`) : [],
+    },
+    render: { ms: renderRes.ms, width: renderRes.width, height: renderRes.height },
+    pixelDiff: pixelDiffResult,
+    diffImage: diffImagePath,
+    // 渲染原图落盘并回报路径：模型要做像素取证时有确定入口，
+    // 不必再把卡片目录下的 <cardId>.png（那是设计稿归档）误当渲染产物。
+    renderImage: renderImagePath,
+    // 并排图的图例说明：顶部 24px 灰/蓝色条是工具标题栏，不属于卡片内容。
+    // 缺这句时模型会把蓝条当成「渲染器标注/测量噪声」，据此放弃收敛。
+    diffImageNote: diffImagePath
+      ? '并排对比图：左=设计稿(灰标题栏) 右=渲染(蓝标题栏)；顶部 24px 色条是工具标题栏，不是卡片内容，也不参与 pixelDiff 计算（match 用渲染原图 vs 设计稿原图算）。要看渲染本体用 renderImage。'
+      : undefined,
+    designImage,
+    preflight: preflight || undefined,
+    ...(withElements ? { elements: renderRes.elementBoxes || [] } : {}),
+    elapsedMs: elapsed,
+  }
+
+  // 内容偏移折算到 1x 设计像素 + 对齐提示
+  if (pixelDiffResult?.contentOffset) {
+    const scale = renderWidth ? (renderRes.width || renderWidth) / renderWidth : 2
+    const co = pixelDiffResult.contentOffset
+    result.contentOffset1x = {
+      dx: Math.round(co.dx / (scale || 1)),
+      dy: Math.round(co.dy / (scale || 1)),
+    }
+    const { dx, dy } = result.contentOffset1x
+    if (Math.abs(dx) > GATE.contentOffset1x || Math.abs(dy) > GATE.contentOffset1x) {
+      result.contentOffsetHint = `内容整体偏移 dx=${dx} dy=${dy}（1x 设计像素，渲染相对设计）——这是对齐问题不是间距微调问题：先查 Root/首层容器的左右与上下 padding、首个子节点的 margin、以及是否漏了 marginType/paddingType:"1"；继续逐行调 gap/padding 不会收敛。`
+    }
+  }
+
+  // 报告落盘 + 门禁判定 + 停滞检测
+  const saved = persistReport(result, { sp, dp })
+  if (saved) {
+    result.report = saved.reportPath
+    result.rounds = saved.rounds
+    result.gate = saved.gate
+    if (saved.stalled) {
+      result.stalled = {
+        rounds: saved.stalled.rounds,
+        hint: `连续 ${saved.stalled.rounds} 轮 match 与热区几乎没变：--set 微调已无收益，禁止继续盲调。改按证据推进——① 跑 diff_bands.mjs（args=["--id","${cardId}","--design","${designPath || '<设计稿>'}","--render","${renderImagePath || '<renderImage>'}"]）拿逐带 dy/dh、内容底边、分区主色；② 对照 references/generation_pitfalls.md 的「类型开关+值」「静默丢弃」清单排查样式被忽略（marginType/paddingType/backgroundType/isBorder/isShadow）；③ 读报告里的 contentOffset1x 与 hotspots 判断是整体平移还是局部差异；④ 有 --spec 时看 preflight.details。`,
+      }
+    }
+  }
+
+  return result
+}
+
+/* ── CLI ───────────────────────────────────────────────────── */
+function parseArgs(argv) {
+  const out = { ir: '', out: '', design: '', width: 0, keepAlive: false, diffImage: false, elements: false, sets: [], spec: '', gate: false, id: '', skipPreflight: false, slicesDir: '' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--ir') out.ir = argv[++i] || ''
+    else if (a === '--out') out.out = argv[++i] || ''
+    else if (a === '--design') out.design = argv[++i] || ''
+    else if (a === '--width') out.width = Number(argv[++i]) || 0
+    else if (a === '--set') out.sets.push(argv[++i] || '')
+    else if (a === '--spec') out.spec = argv[++i] || ''
+    else if (a === '--slices-dir') out.slicesDir = argv[++i] || ''
+    else if (a === '--id') out.id = argv[++i] || ''
+    else if (a === '--gate') out.gate = true
+    else if (a === '--no-preflight') out.skipPreflight = true
+    else if (a === '--keep-alive') out.keepAlive = true
+    else if (a === '--diff-image') out.diffImage = true
+    else if (a === '--elements') out.elements = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: node iterate.mjs --ir <IR.json> --out <cardDir> [--design <design.png>] [--width 343] [--elements]
+                          [--spec <spec.json>]（跑 preflight 元素清单比对） [--no-preflight] [--slices-dir <要素包 slices 目录>]
+                          [--set 'children.0.s.margin.marginTop="7"']（可重复；点路径数字段=数组下标；原子写回 IR）
+       node iterate.mjs --gate --out <cardDir>（或 --id <cardId>）：读最近一轮落盘报告做机器门禁判定，未达标 exit 1
+       node iterate.mjs --keep-alive  (stdin JSON lines → stdout JSON lines)
+
+门禁（--gate / 报告里的 gate 字段）：validate.errors=0 ∧ lint.errors=0 ∧ preflight.errors=0 ∧ match>=${GATE.match}
+  ∧ heightDelta=${GATE.heightDelta} ∧ widthDelta=${GATE.widthDelta} ∧ |contentOffset1x|<=${GATE.contentOffset1x}，且 schema 未在报告之后被改过。
+报告落盘：.cache/ai-scratch/<cardId>.iterate.json（含 gate / history / stalled）。`)
+      process.exit(0)
+    }
+  }
+  return out
+}
+
+/** --gate：只读最近一轮落盘报告做判定，不重渲染。
+ *  schema 在报告之后被改过 ⇒ 报告失效，直接判 FAIL（防止拿旧报告宣称门禁全绿）。 */
+function runGateMode({ id, out: outDir }) {
+  let cardId = id
+  if (!cardId && outDir) cardId = path.basename(String(outDir).replace(/\/+$/, ''))
+  if (!cardId) {
+    console.log(JSON.stringify({ ok: false, gate: { passed: false, verdict: 'FAIL：--gate 需要 --id <cardId> 或 --out <cardDir>' } }))
+    process.exit(1)
+  }
+  const reportPath = path.join(SCRATCH_DIR, `${cardId}.iterate.json`)
+  if (!fs.existsSync(reportPath)) {
+    console.log(JSON.stringify({
+      ok: false,
+      cardId,
+      gate: { passed: false, verdict: `FAIL：没有 ${cardId} 的迭代报告（${reportPath}）—— 先跑一轮 iterate.mjs，门禁只认脚本落盘的报告，不认自述` },
+    }))
+    process.exit(1)
+  }
+  const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'))
+  const schemaHash = hashFile(cardSchemaPath(cardId))
+  const stale = schemaHash && report.schemaHash && schemaHash !== report.schemaHash
+  const gate = evaluateGate(report)
+  if (stale) {
+    gate.passed = false
+    gate.verdict = `FAIL：报告已过期（schema.json 在报告之后被改过：${report.schemaHash} → ${schemaHash}）—— 重跑一轮 iterate.mjs 再判门禁`
+    gate.checks.push({ name: 'reportFreshness', value: 'stale', required: 'schema 未变更', ok: false })
+  }
+  const out = {
+    ok: gate.passed,
+    cardId,
+    report: reportPath,
+    gate,
+    summary: {
+      match: report.pixelDiff?.match ?? null,
+      heightDelta: report.pixelDiff?.size?.heightDelta ?? null,
+      widthDelta: report.pixelDiff?.size?.widthDelta ?? null,
+      contentOffset1x: report.contentOffset1x || null,
+      validateErrors: report.validate?.errors ?? null,
+      lintErrors: report.lint?.errors ?? null,
+      preflightErrors: report.preflight?.errors ?? null,
+      rounds: (report.history || []).length,
+      reportAge: Date.now() - (report.history?.[report.history.length - 1]?.ts || Date.now()),
+    },
+  }
+  console.log(JSON.stringify(out, null, 2))
+  process.exit(gate.passed ? 0 : 1)
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.gate) {
+    runGateMode({ id: args.id, out: args.out })
+    return
+  }
+
+  if (args.keepAlive) {
+    const session = await createRenderSession()
+    const rl = readline.createInterface({ input: process.stdin, terminal: false })
+    try {
+      for await (const line of rl) {
+        const text = line.trim()
+        if (!text) continue
+        try {
+          const req = JSON.parse(text)
+          const result = await runPipeline({ ...req, specPath: req.spec || req.specPath, session, alwaysDiffImage: req.diffImage || req.alwaysDiffImage, withElements: req.elements })
+          console.log(JSON.stringify(result))
+        } catch (e) {
+          console.log(JSON.stringify({ ok: false, error: 'request-failed', message: e.message }))
+        }
+      }
+    } finally {
+      await session.close()
+    }
+    return
+  }
+
+  if (!args.ir || !args.out) {
+    console.error('用法: node iterate.mjs --ir <IR.json> --out <cardDir> [--design <design.png>] [--width 343]')
+    process.exit(1)
+  }
+
+  const result = await runPipeline({
+    ir: args.ir,
+    out: args.out,
+    design: args.design,
+    width: args.width,
+    alwaysDiffImage: args.diffImage,
+    withElements: args.elements,
+    sets: args.sets,
+    specPath: args.spec,
+    skipPreflight: args.skipPreflight,
+    slicesDir: args.slicesDir,
+  })
+
+  console.log(JSON.stringify(result, null, 2))
+  if (!result.ok) process.exit(1)
+  // 门禁未达标不算脚本失败（报告照常回喂），但退出码要让调用方一眼看出没收敛
+  if (result.gate && result.gate.passed === false) process.exitCode = 2
+}
+
+main().catch((e) => {
+  console.error(`iterate.mjs 未预期错误: ${e.message || e}`)
+  process.exit(1)
+})