cardbuddy 0.14.3 → 0.16.0

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * gate.mjs — 卡片校验门禁一条命令（2026-09-21 优化方案 1.3）。
+ *
+ * 把 Workflow A 步骤 4 的 5 条门禁命令合并成一次调用，消除 4 次 LLM 工具
+ * 调用往返。依次执行（任一步 FAIL 立即短路后续非修复步骤）：
+ *
+ *   1. autofix    python autofix_schema.py <schema>      机械修复（写回）
+ *   2. validate   python validate_schema.py <schema>     结构合法性（0 ERROR 0 WARN）
+ *   3. data       python derive_data_json.py <schema> --check   data.json 一致性
+ *   4. lint       node lint_card.mjs --id <id>           行为规则 0 ERROR
+ *   5. preflight  node preflight.mjs --spec <spec> --id <id>   14 项机械检查（给了 --spec 才跑）
+ *
+ * 用法：
+ *   node scripts/gate.mjs --id <卡id> [--spec UI/<画板>/spec.json] [--json] [--project-root <dir>]
+ *
+ * 退出码：0 = 全部通过；1 = 任一门禁 FAIL；2 = 用法/路径错误。
+ * --json 输出机器可读汇总：{ ok, steps: { autofix: {ok, output}, validate: {...}, ... }, summary }
+ *
+ * 自包含：只依赖 Node 内置模块 + Python3（validate/autofix/derive 是 .py）。
+ */
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { cardSchemaPath, cardsDir, skillRoot } from './lib/paths.mjs'
+import { resolvePython } from './lib/python.mjs'
+
+// ---------- CLI ----------
+const argv = process.argv.slice(2)
+function argOf(name) {
+  const i = argv.indexOf(name)
+  return i >= 0 ? argv[i + 1] : undefined
+}
+const hasFlag = (name) => argv.includes(name)
+
+const id = argOf('--id')
+const specPath = argOf('--spec')
+const asJson = hasFlag('--json')
+const projectRoot = argOf('--project-root')
+
+if (!id || argv.includes('--help') || argv.includes('-h')) {
+  console.error('Usage: node scripts/gate.mjs --id <卡id> [--spec UI/<画板>/spec.json] [--json] [--project-root <dir>]')
+  process.exit(2)
+}
+
+const schema = cardSchemaPath(id)
+let fs
+try {
+  fs = await import('node:fs')
+  if (!fs.existsSync(schema)) {
+    console.error(`[gate] schema not found: ${schema}`)
+    process.exit(2)
+  }
+} catch {
+  // fs import always succeeds; placeholder for symmetry
+}
+
+if (projectRoot) process.env.DSL_CARD_PROJECT_ROOT = projectRoot
+
+const scriptsDir = path.join(skillRoot, 'scripts')
+// 此前是 `process.env.PYTHON || 'python3'`：既不认 DSL_CARD_PYTHON，也不做探测，
+// 于是在 Windows 上会钉住 Store 假别名 python3，autofix/validate 静默不执行。
+const py = resolvePython()
+
+/** 跑一步门禁。返回 { ok, code, output }；output 只保留尾部的关键行（错误/摘要）。 */
+function runStep(name, cmd, args) {
+  const res = spawnSync(cmd, args, {
+    cwd: projectRoot || process.cwd(),
+    encoding: 'utf8',
+    env: { ...process.env, PYTHONIOENCODING: 'utf-8' },
+    timeout: 120_000,
+  })
+  const out = `${res.stdout || ''}${res.stderr || ''}`.trim()
+  const ok = res.status === 0
+  // 只保留含 ERROR/WARN/✗/failed/关键字样的行 + 最后 8 行，控制输出体积
+  const lines = out.split('\n')
+  const key = lines.filter((l) =>
+    /ERROR|WARN|✗|✘|FAIL|failed|not found|missing|Invalid|invalid|error/i.test(l)
+  )
+  const brief = [...new Set([...key, ...lines.slice(-8)])].slice(-24).join('\n')
+  return { step: name, ok, code: res.status, output: brief || out.slice(0, 2000), full: out }
+}
+
+// ---------- 门禁序列 ----------
+const steps = []
+
+steps.push(
+  runStep('autofix', py, [path.join(scriptsDir, 'autofix_schema.py'), schema])
+)
+steps.push(
+  runStep('validate', py, [path.join(scriptsDir, 'validate_schema.py'), schema])
+)
+steps.push(
+  runStep('data', py, [path.join(scriptsDir, 'derive_data_json.py'), schema, '--check'])
+)
+steps.push(
+  runStep('lint', process.execPath, [path.join(scriptsDir, 'lint_card.mjs'), '--id', id])
+)
+if (specPath) {
+  steps.push(
+    runStep('preflight', process.execPath, [
+      path.join(scriptsDir, 'preflight.mjs'),
+      '--spec',
+      specPath,
+      '--id',
+      id,
+    ])
+  )
+}
+
+const failed = steps.filter((s) => !s.ok)
+const ok = failed.length === 0
+
+// ---------- 输出 ----------
+if (asJson) {
+  const summary = {
+    id,
+    schema,
+    ok,
+    failedSteps: failed.map((s) => s.step),
+    stepCount: steps.length,
+  }
+  console.log(
+    JSON.stringify(
+      { ok, summary, steps: Object.fromEntries(steps.map((s) => [s.step, { ok: s.ok, code: s.code, output: s.output }])) },
+      null,
+      2
+    )
+  )
+} else {
+  console.log(`\n=== gate: ${id} ===`)
+  for (const s of steps) {
+    const mark = s.ok ? '✓' : '✗'
+    console.log(`${mark} ${s.step}${s.ok ? '' : ` (exit ${s.code})`}`)
+  }
+  if (ok) {
+    console.log(`\n[PASS] 全部 ${steps.length} 项门禁通过 → 可进入渲染/视觉闭环`)
+  } else {
+    for (const f of failed) {
+      console.log(`\n--- ${f.step} 输出（关键行）---`)
+      console.log(f.output)
+    }
+    console.log(`\n[FAIL] ${failed.length}/${steps.length} 项未过：${failed.map((f) => f.step).join(', ')}`)
+    console.log('按 lint/validate 输出的规则号逐条修复后重跑本命令；修复手法见规则号对应文档（rules.md / generation_pitfalls.md / component_rules.md）。')
+  }
+}
+
+process.exit(ok ? 0 : 1)

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

@@ -26,7 +26,7 @@ import { spawnSync } from 'node:child_process'
 import { generate as generateV3 } from './spec_to_schema_v3.mjs'
 import { copyCardDesignImage, findCardDesignImage } from './lib/design_image.mjs'
 import { cardsDir, projectRoot, slicesDir } from './lib/paths.mjs'
-import { buildContentIndex, rewriteSliceRefs, sha256File } from './lib/slice_dedupe.mjs'
+import { buildContentIndex, rewriteSliceRefs, sha256File, sliceNameMatches } from './lib/slice_dedupe.mjs'
 
 const CHECK_FIDELITY = path.join(projectRoot, 'skills', 'dsl-card-generator', 'scripts', 'check_fidelity.mjs')
 
@@ -121,20 +121,24 @@ function collectSlicesToSrcSlices(artboardDir, schema, cardDir, data) {
       if (!/\.(png|jpe?g|webp|svg)$/i.test(ent.name)) continue
       const rel = path.relative(srcDir, full).split(path.sep).join('/')
       const flat = rel.replace(/\//g, '_')
-      if (!referenced.has(flat)) continue
-      const target = path.join(slicesDir, flat)
-      referenced.delete(flat)
+      // 源文件可能仍是设计稿原名（`警示-#999.png`），而 schema 引用是消毒名（`警示-999.png`）
+      // → 归一后匹配。**落盘名一律取 schema 引用的名字**（wanted），保证「引用 = 磁盘名」这条等式成立，
+      // 否则引用与磁盘名各写各的，r31c 会报悬空、图空白。
+      const wanted = [...referenced].find((r) => sliceNameMatches(flat, r))
+      if (!wanted) continue
+      const target = path.join(slicesDir, wanted)
+      referenced.delete(wanted)
       if (fs.existsSync(target)) continue
       const sha = sha256File(full)
       const twin = (contentIndex.get(sha) || [])[0]
-      if (twin && twin !== flat) {
-        rewrites.push([`/slices/${flat}`, `/slices/${twin}`])
+      if (twin && twin !== wanted) {
+        rewrites.push([`/slices/${wanted}`, `/slices/${twin}`])
         continue
       }
       fs.copyFileSync(full, target)
       const list = contentIndex.get(sha)
-      if (list) list.push(flat)
-      else contentIndex.set(sha, [flat])
+      if (list) list.push(wanted)
+      else contentIndex.set(sha, [wanted])
       n++
     }
   }

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

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * ir_merge.mjs — 把「分片 IR 片段」合并进主 IR（分片落盘的后半段）。
+ *
+ * 为什么需要它：IR 一直是一次 fs_write 写完整份。工具是在**流结束后**才执行的，所以那一刻之前
+ * 盘上什么都没有——实测一次建卡 fs_write 花了 88s 纯吐参数（8.9KB IR），这 88s 里任何一次
+ * 输出截断（finish_reason=length）/ 网关静默 / 墙钟到点，整份 IR 全废，连「写了一半」都没有。
+ * 拆成「骨架 + 逐区块片段」以后：每片一个步骤落盘（一小段输出），某片失败只丢那一片，
+ * 已落盘的片段继续有效，合并一次即可继续跑 expand_ir。
+ *
+ * 用法：
+ *   node ir_merge.mjs --ir .cache/ai-scratch/<id>.ir.json --part .cache/ai-scratch/<id>.p1.json [--part <p2.json> ...]
+ *   node ir_merge.mjs --ir <ir.json> --parts-dir .cache/ai-scratch/<id>.parts   # 目录里 *.json 按文件名排序全部合并
+ *
+ * 片段格式（一个文件 = 一片，ops 可多条）：
+ *   {
+ *     "ops": [
+ *       { "path": "root.children",   "append": [ {…IR 节点…}, {…} ] },
+ *       { "path": "root.children.0.s", "merge": { "paddingType": "1", "paddingTop": "12" } }
+ *     ]
+ *   }
+ *   也接受单条 op 的简写（顶层直接 {path, append|merge}）与 ops 数组。
+ *
+ * 捆绑包（2026-09-21 起，省 LLM 往返）：一次 fs_write 写多片 + 一次 merge 全收——
+ *   { "parts": [ { "ops": [...] }, { "ops": [...] } ] }   或直接 [ { "ops": [...] }, ... ]
+ * 幂等粒度 = 整个捆绑文件名（记入 _parts，重发整包跳过）。
+ *
+ * path 与 iterate.mjs --set 同一套点路径（数字段=数组下标）：**中间段必须已存在**，
+ * 末段指向的对象必须已存在（append 要数组、merge 要对象）。刻意不做「自动建中间节点」——
+ * 拼错一个键就静默建出一条没人会发现的错分支，比报错贵得多。
+ *
+ * 幂等：合并过的片段名记在 IR 的 `_parts` 里，重复合并同一个文件直接跳过。
+ * 这一条是给「网关静默重试 / 模型重发同一次调用」兜底的——append 天然不幂等，
+ * 没有这层保护就会把同一段子树加两遍（实测同类事故：同一次 iterate 被原样重发）。
+ *
+ * 原子性：所有 op 先内存里全部应用成功，再 tmp+rename 写回；任何一条失败即整体不写。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 分片落盘的记账键：合并过的片段名（basename），用于幂等跳过 */
+const PARTS_KEY = '_parts'
+
+/* ── 点路径寻址（与 iterate.mjs --set 同口径）──────────────── */
+function resolveParent(ir, dottedPath) {
+  const segs = String(dottedPath).split('.').filter(Boolean)
+  if (!segs.length) throw new Error(`空路径: "${dottedPath}"`)
+  let node = ir
+  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}）` +
+          `；这一级可用的键：${describeKeys(node)}`,
+      )
+    }
+    node = next
+  }
+  const lastKey = segs[segs.length - 1]
+  const parent = node
+  const target = Array.isArray(parent) ? parent[Number(lastKey)] : parent?.[lastKey]
+  return { parent, lastKey, target }
+}
+
+/** 报错时把「这一级实际有什么」列出来：模型据此一次改对，不用靠猜（实测拼错键名会连撞两次） */
+function describeKeys(node) {
+  if (Array.isArray(node)) return `数组(len=${node.length})`
+  if (!node || typeof node !== 'object') return `（${node === null ? 'null' : typeof node}）`
+  const keys = Object.keys(node)
+  return keys.length ? keys.slice(0, 12).join(' / ') + (keys.length > 12 ? ' …' : '') : '（空对象）'
+}
+
+/** 一条 op → 应用到 ir。返回 { kind, path, n, created? }；不合法就抛错（信息里带上可用键） */
+function applyOp(ir, op) {
+  if (!op || typeof op !== 'object') throw new Error(`op 必须是对象：${JSON.stringify(op)}`)
+  const p = String(op.path || '').trim()
+  if (!p) throw new Error(`op 缺 path：${JSON.stringify(op).slice(0, 120)}`)
+  const { parent, lastKey, target } = resolveParent(ir, p)
+  if ('append' in op) {
+    const items = Array.isArray(op.append) ? op.append : [op.append]
+    // append 要求数组已存在：`chidren.0` 这类拼错会静默建出一条没人会发现的空数组，比报错贵得多
+    if (target === undefined) {
+      throw new Error(`路径不存在：${p}（这一级可用的键：${describeKeys(parent)}）—— append 不会自动创建容器，骨架里要先建好`)
+    }
+    if (!Array.isArray(target)) {
+      throw new Error(`append 的 path 必须指向已存在的数组：${p} 实际是 ${Array.isArray(target) ? 'array' : typeof target}（要改对象里的字段请用 merge）`)
+    }
+    target.push(...items)
+    return { kind: 'append', path: p, n: items.length }
+  }
+  if ('merge' in op) {
+    if (!op.merge || typeof op.merge !== 'object' || Array.isArray(op.merge)) {
+      throw new Error(`merge 需要对象（想追加数组请用 append）：${p}`)
+    }
+    // merge 允许「末段键还不存在」（某节点在第一片里没写 s，后一片补样式）：这是幂等的对象字段
+    // 合并，不会像 append 那样加出重复子树；但仍如实报成 created —— 拼错的键也长这样，
+    // 列出来模型一眼能看出是不是新建了奇怪的键。
+    if (target === undefined) {
+      if (Array.isArray(parent)) {
+        throw new Error(`merge 指到数组里还不存在的下标：${p}（该数组长度 ${parent.length}）`)
+      }
+      parent[lastKey] = { ...op.merge }
+      return { kind: 'merge', path: p, n: Object.keys(op.merge).length, created: true }
+    }
+    if (typeof target !== 'object' || Array.isArray(target)) {
+      throw new Error(`merge 的 path 必须指向对象：${p} 实际是 ${Array.isArray(target) ? 'array' : typeof target}`)
+    }
+    Object.assign(target, op.merge)
+    return { kind: 'merge', path: p, n: Object.keys(op.merge).length }
+  }
+  throw new Error(`op 必须带 append 或 merge 之一：${JSON.stringify(op).slice(0, 120)}`)
+}
+/** 片段里的 ops（四种写法都认：{ops} / {parts} 捆绑 / ops 数组 / 单条 op。宁可宽容解析、不为格式再烧一轮） */
+export function opsOf(part) {
+  if (Array.isArray(part)) {
+    // 捆绑包：[片段, 片段, …]（每个元素是 {ops:[…]} 形状的片段）→ 拼接全部 ops
+    if (part.length && part.every((p) => p && typeof p === 'object' && Array.isArray(p.ops))) {
+      return part.flatMap((p) => opsOf(p))
+    }
+    return part
+  }
+  if (part && Array.isArray(part.parts)) return part.parts.flatMap((p) => opsOf(p)) // 捆绑包：{parts:[…]}
+  if (part && Array.isArray(part.ops)) return part.ops
+  if (part && typeof part === 'object' && ('path' in part)) return [part]
+  throw new Error('片段里没有 ops：应为 {ops:[…]}、{parts:[…]}（捆绑包）、单条 {path,append|merge} 或 ops 数组')
+}
+
+/** 形状体检（合并前，硬拦）：IR 契约里 c（className）是必填，缺了必被 expand/validate 拦下来。
+ *  放在写盘之前拦：盘上永远只有「能进管线」的内容，模型也在这一步就知道是哪一片写错了。 */
+function shapeProblems(partName, ops) {
+  const out = []
+  ops.forEach((op, oi) => {
+    if (!('append' in op)) return
+    const items = Array.isArray(op.append) ? op.append : [op.append]
+    items.forEach((it, ii) => {
+      const at = `${partName} ops[${oi}].append[${ii}]`
+      if (!it || typeof it !== 'object' || Array.isArray(it)) out.push(`${at} 不是对象`)
+      else if (!it.c) out.push(`${at} 缺 c（组件类型，IR 必填）`)
+    })
+  })
+  return out
+}
+
+export function countNodes(ir) {
+  let n = 0
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return
+    n++
+    for (const c of node.children || []) walk(c)
+    for (const list of Object.values(node.slots || {})) for (const c of list || []) walk(c)
+  }
+  for (const c of ir.children || []) walk(c)
+  return n
+}
+
+/**
+ * 把若干片段合并进 irPath（原地原子写回）。
+ *
+ * 三条不变量：
+ *   ① 幂等：合并过的片段名（basename）记在 IR 的 _parts 里，重复合并直接跳过 —— append 天然不幂等，
+ *      而「原样重发同一次调用」在本项目是常态（网关静默重试 / 模型重发），没有这层保护会加两遍；
+ *   ② 先校验后写：所有片段的形状体检、所有 op 的应用都在内存里做完，任何一步失败即整份不写，
+ *      盘上永远是上一次成功合并的合法状态；
+ *   ③ 片段名只在整批成功后记账：失败的那批改完可以原样重跑（不会被误判成「已合并」而跳过）。
+ */
+export function mergeParts(irPath, partPaths) {
+  const ir = JSON.parse(fs.readFileSync(irPath, 'utf8'))
+  const seen = new Set(Array.isArray(ir[PARTS_KEY]) ? ir[PARTS_KEY].map((x) => path.basename(String(x))) : [])
+  const applied = []
+  const skipped = []
+  const pending = []
+  for (const p of partPaths) {
+    const name = path.basename(p)
+    if (seen.has(name)) {
+      skipped.push(name)
+      continue
+    }
+    const part = JSON.parse(fs.readFileSync(p, 'utf8'))
+    const list = opsOf(part)
+    if (!list.length) throw new Error(`${name}: ops 为空，没有可合并的内容`)
+    const problems = shapeProblems(name, list)
+    if (problems.length) {
+      throw new Error(`片段形状不对（本次未写盘，改好可原样重跑）：${problems.join('；')}`)
+    }
+    pending.push({ name, list })
+  }
+  const ops = []
+  for (const { name, list } of pending) {
+    for (const op of list) ops.push({ part: name, ...applyOp(ir, op) })
+    applied.push(name)
+  }
+  ir[PARTS_KEY] = [...(ir[PARTS_KEY] || []), ...applied]
+  const bytes = Buffer.byteLength(JSON.stringify(ir))
+  if (applied.length) {
+    const tmp = `${irPath}.tmp-${process.pid}`
+    fs.writeFileSync(tmp, JSON.stringify(ir, null, 2) + '\n')
+    fs.renameSync(tmp, irPath)
+  }
+  return { ir, applied, skipped, ops, nodes: countNodes(ir), bytes }
+}
+/* ── CLI ───────────────────────────────────────────────────── */
+function parseArgs(argv) {
+  const out = { ir: '', parts: [], partsDir: '', quiet: false, ignored: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--ir') out.ir = argv[++i] || ''
+    else if (a === '--part') out.parts.push(argv[++i] || '')
+    else if (a === '--parts-dir') out.partsDir = argv[++i] || ''
+    else if (a === '--quiet') out.quiet = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: node ir_merge.mjs --ir <IR.json> --part <p1.json> [--part <p2.json> ...]
+       node ir_merge.mjs --ir <IR.json> --parts-dir <目录>   # 目录内片段 *.json 按文件名排序合并（骨架自己与不像片段的 JSON 跳过，列在 ignored）
+
+片段格式：{ "ops": [ { "path": "root.children", "append": [ …IR 节点… ] },
+                     { "path": "root.children.0.s", "merge": { "paddingType": "1" } } ] }
+path 与 iterate.mjs --set 同口径（数字段=数组下标）；中间段必须已存在。
+已合并过的片段名记在 IR 的 _parts 里，重复合并自动跳过（append 不幂等，防重发）。
+输出 JSON：{ ok, applied[], skipped[], ops[], warnings[], nodes, bytes }；任何一条 op 失败即整体不写。`)
+      process.exit(0)
+    }
+  }
+  if (!out.ir) {
+    console.error('缺少 --ir')
+    process.exit(2)
+  }
+  if (out.partsDir) {
+    // 目录模式：骨架与片段常在同一目录（.cache/ai-scratch/），这里只排除 --ir 自己；
+    // 同目录里别的 JSON（别的卡的 .ir/.audit/.iterate）不是片段 —— 跳过并列进 ignored，不静默吞。
+    const irAbs = path.resolve(out.ir)
+    for (const f of fs.readdirSync(out.partsDir).filter((n) => n.endsWith('.json')).sort()) {
+      const full = path.join(out.partsDir, f)
+      if (path.resolve(full) === irAbs) continue
+      let looksLikePart = false
+      try {
+        const j = JSON.parse(fs.readFileSync(full, 'utf8'))
+        looksLikePart = Array.isArray(j) || Boolean(j && (Array.isArray(j.ops) || j.path))
+      } catch {
+        looksLikePart = false
+      }
+      if (looksLikePart) out.parts.push(full)
+      else out.ignored.push(f)
+    }
+  }
+  if (!out.parts.length) {
+    console.error('至少要给一个 --part 或 --parts-dir')
+    process.exit(2)
+  }
+  return out
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (!fs.existsSync(args.ir)) {
+    console.log(JSON.stringify({ ok: false, error: `IR 不存在：${args.ir}（先 fs_write 骨架：{id,name,width,children:[]}）` }))
+    process.exit(1)
+  }
+  const missing = args.parts.filter((p) => !fs.existsSync(p))
+  if (missing.length) {
+    console.log(JSON.stringify({ ok: false, error: `片段文件不存在：${missing.join(' / ')}` }))
+    process.exit(1)
+  }
+  try {
+    const r = mergeParts(args.ir, args.parts)
+    console.log(
+      JSON.stringify({
+        ok: true,
+        ir: args.ir,
+        applied: r.applied,
+        skipped: r.skipped,
+        ignored: args.ignored,
+        ops: r.ops.map((o) => `${o.part}:${o.kind} ${o.path} +${o.n}${o.created ? '（新建键）' : ''}`),
+        nodes: r.nodes,
+        bytes: r.bytes,
+        hint:
+          r.applied.length === 0
+            ? '这批片段都合并过了（幂等跳过），IR 未改动；还缺区块就写下一片再合并，结构完整就直接 expand_ir.mjs'
+            : '结构完整就跑 expand_ir.mjs 展开；还缺区块就继续写下一片再合并；合并后要改细节一律 iterate.mjs --set（改内容别重写已合并的片段名：那会被当成已合并而跳过，改结构就用新名字的片段 + merge 覆盖容器键）',
+      }),
+    )
+  } catch (e) {
+    // 形状不对 / 一条 op 失败 = 整份不写：盘上仍是上一次成功合并的合法状态，改片段可原样重跑
+    console.log(JSON.stringify({ ok: false, error: String(e?.message || e), ir: args.ir, applied: [] }))
+    process.exit(1)
+  }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main()

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

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * ir_restore.mjs — 把 IR 回退到某一轮（默认「历史最好成绩」那轮）的结构。
+ *
+ * 存在的理由（2026-09-21 建卡回合实测）：iterate 的 round 历史里 match 一路震荡下滑
+ * （79.6 → 92.42 → 90.04），模型发现「越改越差」时**没有任何历史版本可退**，
+ * 唯一的办法是凭记忆全量重写整份 IR —— 16 次重写、12.4 万字符，约占该轮全部输出的一半。
+ * iterate 现在每轮落一份 <id>.ir.rNN.json、刷新最好成绩时另存 <id>.ir.best.json，
+ * 本脚本负责把其中一份原子写回工作 IR（回退前先把当前态备份，回退本身也可撤销）。
+ *
+ * 用法：
+ *   node ir_restore.mjs --best .cache/ai-scratch/<id>.ir.best.json --ir .cache/ai-scratch/<id>.ir.json
+ *   node ir_restore.mjs --round 10 --id <cardId> --ir .cache/ai-scratch/<id>.ir.json
+ *   node ir_restore.mjs --list --id <cardId>          # 只列可用快照与各轮 match，不改文件
+ *
+ * 退出码：0 成功；1 参数 / 文件错误；3 目标不是合法 JSON（拒绝写坏工作 IR）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { repoRoot } from './lib/paths.mjs'
+
+const SCRATCH_DIR = path.join(repoRoot, '.cache', 'ai-scratch')
+
+function parseArgs(argv) {
+  const out = { best: '', round: 0, id: '', ir: '', list: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--best') out.best = argv[++i] || ''
+    else if (a === '--round') out.round = Number(argv[++i]) || 0
+    else if (a === '--id') out.id = argv[++i] || ''
+    else if (a === '--ir') out.ir = argv[++i] || ''
+    else if (a === '--list') out.list = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage:
+  node ir_restore.mjs --best <ir.best.json> --ir <工作IR.json>
+  node ir_restore.mjs --round <NN> --id <cardId> --ir <工作IR.json>
+  node ir_restore.mjs --list --id <cardId>
+
+快照来源：iterate.mjs 每轮落 <卡>.ir.rNN.json，刷新最好成绩时另存 <卡>.ir.best.json（均在 .cache/ai-scratch/）。`)
+      process.exit(0)
+    }
+  }
+  return out
+}
+
+/** 报告里的轮次历史：--list 与「按轮次回退」都靠它 */
+function readReport(cardId) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(SCRATCH_DIR, `${cardId}.iterate.json`), 'utf8'))
+  } catch {
+    return null
+  }
+}
+function readHistory(cardId) {
+  const report = readReport(cardId)
+  return Array.isArray(report?.history) ? report.history : []
+}
+
+function listSnapshots(cardId) {
+  const report = readReport(cardId)
+  const history = Array.isArray(report?.history) ? report.history : []
+  const rows = history.map((h) => ({
+    round: h.round ?? null,
+    match: h.match ?? null,
+    heightDelta: h.heightDelta ?? null,
+    snapshot: h.irSnapshot || null,
+    exists: h.irSnapshot ? fs.existsSync(path.join(SCRATCH_DIR, h.irSnapshot)) : false,
+  }))
+  const bestIr = path.join(SCRATCH_DIR, `${cardId}.ir.best.json`)
+  // 最好成绩认报告里**单独持久化**的 best：history 只留最近几条，按它算会把更早的最好成绩算丢
+  const best = report?.best || null
+  return {
+    ok: rows.length > 0 || Boolean(best),
+    cardId,
+    bestIr: fs.existsSync(bestIr) ? bestIr : null,
+    bestRound: best?.round ?? null,
+    bestMatch: best?.match ?? null,
+    bestInWindow: best ? rows.some((r) => r.round === best.round) : false,
+    note: 'rounds 只列最近几轮；更早轮次的快照文件仍在 .cache/ai-scratch/<卡>.ir.rNN.json，可用 --round NN 直接回退',
+    rounds: rows,
+  }
+}
+
+function pickSnapshot(args) {
+  if (args.best) return { file: args.best, from: 'best' }
+  if (args.round > 0) {
+    const hit = readHistory(args.id).find((h) => Number(h.round) === Number(args.round))
+    // history 只留最近 9 条：窗口外的轮次按约定文件名直取（快照文件本身不会删）
+    const file = hit?.irSnapshot
+      ? path.join(SCRATCH_DIR, hit.irSnapshot)
+      : path.join(SCRATCH_DIR, `${args.id}.ir.r${String(args.round).padStart(2, '0')}.json`)
+    if (!fs.existsSync(file)) {
+      return { error: `没有第 ${args.round} 轮的 IR 快照（${file}）；先用 --list 看有哪些轮次可用` }
+    }
+    return { file, from: `r${args.round}` }
+  }
+  // 两者都没给：默认回退到 best
+  if (!args.id) return { error: '需要 --best <文件> 或 --round <NN> --id <cardId>' }
+  const bestIr = path.join(SCRATCH_DIR, `${args.id}.ir.best.json`)
+  if (!fs.existsSync(bestIr)) return { error: `没有最好成绩快照 ${bestIr}（可能是还没跑过 iterate，或从未刷新过成绩）` }
+  return { file: bestIr, from: 'best' }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.list) {
+    const info = listSnapshots(args.id)
+    console.log(JSON.stringify(info, null, 2))
+    process.exit(info.ok ? 0 : 1)
+  }
+  if (!args.ir) {
+    console.error('缺少 --ir <工作 IR 路径>：回退的目标文件必须显式给出，不做猜测')
+    process.exit(1)
+  }
+  const picked = pickSnapshot(args)
+  if (picked.error) {
+    console.error(picked.error)
+    process.exit(1)
+  }
+  if (!fs.existsSync(picked.file)) {
+    console.error(`快照不存在：${picked.file}`)
+    process.exit(1)
+  }
+  if (!fs.existsSync(args.ir)) {
+    console.error(`工作 IR 不存在：${args.ir}`)
+    process.exit(1)
+  }
+  let snapshot
+  try {
+    snapshot = JSON.parse(fs.readFileSync(picked.file, 'utf8'))
+  } catch (e) {
+    console.error(`快照不是合法 JSON，拒绝写回：${picked.file}（${e.message}）`)
+    process.exit(3)
+  }
+  const cur = fs.readFileSync(args.ir, 'utf8')
+  const backup = `${args.ir}.pre-restore`
+  const cardId = args.id || path.basename(args.ir).replace(/\.ir.*$/, '')
+  const report = readReport(cardId)
+  const bestIrPath = path.join(SCRATCH_DIR, `${cardId}.ir.best.json`)
+  const fromBest = path.resolve(picked.file) === path.resolve(bestIrPath)
+  const hit =
+    readHistory(cardId).find((h) => h.irSnapshot && path.resolve(path.join(SCRATCH_DIR, h.irSnapshot)) === path.resolve(picked.file)) ||
+    (fromBest || Number(report?.best?.round) === Number(args.round) ? report?.best : null) ||
+    null
+  const tmp = `${args.ir}.tmp-${process.pid}`
+  fs.writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + '\n')
+  fs.renameSync(tmp, args.ir)
+  try {
+    fs.writeFileSync(backup, cur)
+  } catch {
+    /* 备份失败不影响回退结果，下面如实说明 */
+  }
+  const nodes = (function count(list) {
+    return (list || []).reduce((n, k) => n + 1 + count(k.children) + Object.values(k.slots || {}).reduce((m, s) => m + count(s), 0), 0)
+  })(snapshot.children)
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        restoredFrom: path.relative(repoRoot, picked.file),
+        source: picked.from,
+        match: hit?.match ?? null,
+        round: args.round || hit?.round || null,
+        ir: path.relative(repoRoot, args.ir),
+        nodes,
+        backup: fs.existsSync(backup) ? path.relative(repoRoot, backup) : null,
+        nextStep: `回退后必须重跑一轮 iterate 拿新报告（旧报告的 schemaHash 已失效，--gate 会判 FAIL）：skill_exec script=skills/dsl-card-generator/scripts/iterate.mjs args=["--ir","${path.relative(repoRoot, args.ir)}","--out","src/cards/<卡>/", "--design","<设计稿>","--width","<卡宽>"]`,
+      },
+      null,
+      2,
+    ),
+  )
+}
+
+main()