cardbuddy 0.14.2 → 0.15.0

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

@@ -21,17 +21,31 @@
  *     reused[] 给 existing 名，调用方把引用改绑既有切图（共用切图已语义重命名也认得出）。
  * 判重目录默认 = --reuse-dir... + 工程 src/slices（按脚本位置推算）+ --out 自身。
  * 输出 JSON：{ scale, written[], reused[{name, existing, dir, reason}] }。
+ *
+ * **落盘前文件名消毒（URL 保留字符，2026-09-21 事故）**：设计稿图层名常自带 `#`（如 `警示-#999`），
+ * 直接落盘会让浏览器把 `#` 之后当 fragment 截掉 → 请求变成 `/slices/警示-` → 图片空白但**零报错**。
+ * 故落盘名一律过 `sanitizeSliceFileName()`；被改名的条目在 `written[]/reused[]` 里同时给出
+ * `originalName` 并在 stderr 响亮提示 —— **调用方必须用返回的 `name` 写 schema 引用**。
+ *
+ * **`--from-audit` 还会「收养」审计判定存在的资产（2026-09-21 事故）**：spec_audit 按完整 ref
+ * + `@Nx` 后缀在 bundle 的 `slices/` 里解析到真实文件（`slices/8.icon/通用/警示-#999@3x.png`），
+ * 但那份文件**不在工程的 src/slices/ 里**。只补 missing 的话，模型会拿到一个正确的名字
+ * （`警示-#999.png` 消毒成 `警示-999.png`）却在渲染时 404 —— 图片依旧空白。
+ * 所以这里把 `audit.slices[].exists === true` 且不在 `--out` 里的资产**原字节复制**进 `--out`，
+ * 落盘名同样过消毒 + 同样做像素判重。`--no-adopt` 可关闭。
+ * 输出 JSON：{ scale, written[], reused[{name, existing, dir, reason}] }。
  */
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { cropPng, findPixelTwin, pngPixelSha } from './lib/slice_pixels.mjs'
+import { cropPng, findPixelTwin, pngPixelSha, readPng } from './lib/slice_pixels.mjs'
+import { sanitizeSliceFileName } from './lib/slice_dedupe.mjs'
 
 const { PNG } = await import('pngjs')
 
 function parseArgs(argv) {
-  const out = { design: '', cardWidth: 0, out: '', crops: [], fromAudit: '', reuseDirs: [] }
+  const out = { design: '', cardWidth: 0, out: '', crops: [], fromAudit: '', reuseDirs: [], adopt: true }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--design') out.design = argv[++i] || ''
@@ -40,8 +54,10 @@ function parseArgs(argv) {
     else if (a === '--crop') out.crops.push(argv[++i] || '')
     else if (a === '--from-audit') out.fromAudit = argv[++i] || ''
     else if (a === '--reuse-dir') out.reuseDirs.push(argv[++i] || '')
+    else if (a === '--no-adopt') out.adopt = false
     else if (a === '-h' || a === '--help') {
       console.log('Usage: node crop_slices.mjs --design <png> --card-width <n> --out <dir> --crop name@x,y,w,h [...] | --from-audit <audit.json>')
+      console.log('  --from-audit 除了补 missing[] 的裁剪，还会把 audit.slices[] 里 exists=true 的资产按消毒名复制进 --out（--no-adopt 关闭）')
       process.exit(0)
     }
   }
@@ -69,6 +85,8 @@ function main() {
     if (![x, y, w, h].every((v) => Number.isFinite(v))) throw new Error(`--crop 坐标非法: "${c}"`)
     jobs.push({ name: c.slice(0, at), x, y, w, h })
   }
+  // 审计判定「存在」的资产：文件在 bundle 里而不在工程 src/slices/ —— 收养进来（原字节复制）。
+  const adoptions = []
   if (args.fromAudit) {
     const audit = JSON.parse(fs.readFileSync(args.fromAudit, 'utf8'))
     for (const m of audit.missing || []) {
@@ -76,8 +94,18 @@ function main() {
         if (c) jobs.push({ name: c.name || m.name, x: c.x, y: c.y, w: c.w, h: c.h })
       }
     }
+    if (args.adopt) {
+      const outAbsEarly = path.resolve(args.out)
+      for (const s of audit.slices || []) {
+        if (!s || !s.exists || !s.file || !s.name) continue
+        const srcAbs = path.resolve(s.file)
+        if (!fs.existsSync(srcAbs)) continue
+        if (path.dirname(srcAbs) === outAbsEarly) continue // 已在工程目录，无需收养
+        adoptions.push({ name: sanitizeSliceFileName(s.name), src: srcAbs, originalName: s.originalName || path.basename(srcAbs) })
+      }
+    }
   }
-  if (!jobs.length) {
+  if (!jobs.length && !adoptions.length) {
     console.log(JSON.stringify({ written: [] }))
     return
   }
@@ -100,12 +128,17 @@ function main() {
       throw new Error(`裁剪矩形越界: ${j.name} @${j.x},${j.y} ${j.w}x${j.h}（design ${src.width}x${src.height}, scale ${scale}）`)
     }
     const o = cropPng(src, cx, cy, cw, ch)
-    const fileName = path.extname(j.name) ? j.name : `${j.name}.png`
+    const fileName = sanitizeSliceFileName(j.name)
+    const originalName = path.basename(String(j.name || ''))
+    const renamed = fileName !== originalName
+    if (renamed) {
+      console.error(`[slices] 文件名含 URL 保留字符/空白，已消毒：${originalName} → ${fileName}（**schema 引用必须用消毒后的名字**，否则浏览器会截断 URL、图片静默不显示）`)
+    }
     // ① 批内判重：同批已裁过同内容 → 复用本批文件名，不重复写
     const key = pngPixelSha(o)
     const batchTwin = batch.get(key)
     if (batchTwin) {
-      reused.push({ name: fileName, existing: batchTwin, reason: 'batch-identical' })
+      reused.push({ name: fileName, ...(renamed ? { originalName } : {}), existing: batchTwin, reason: 'batch-identical' })
       continue
     }
     // ② 既有切图判重：像素同内容（含语义重命名后的共用切图）→ 不写盘，引用改绑既有名
@@ -117,6 +150,7 @@ function main() {
     if (hit) {
       reused.push({
         name: fileName,
+        ...(renamed ? { originalName } : {}),
         existing: hit.twin,
         dir: path.basename(hit.dir),
         reason: path.resolve(hit.dir) === path.resolve(args.out) ? 'already-derived' : 'content-twin',
@@ -126,10 +160,62 @@ function main() {
     const file = path.join(args.out, fileName)
     fs.writeFileSync(file, PNG.sync.write(o))
     batch.set(key, fileName)
-    written.push({ name: path.basename(file), px: [cw, ch], logical: [j.w, j.h] })
+    written.push({ name: path.basename(file), ...(renamed ? { originalName } : {}), px: [cw, ch], logical: [j.w, j.h] })
+  }
+
+  // 收养（--from-audit 且未关）：把 bundle 里已存在、但不在工程 src/slices/ 的资产按消毒名搬进来。
+  // 为什么必须做这一步：审计给出的是**正确的名字**，但文件还在 bundle 里；
+  // 模型照着写 `/slices/警示-999.png` 只会 404（图片空白、控制台零报错）。
+  for (const a of adoptions) {
+    const target = path.join(args.out, a.name)
+    if (fs.existsSync(target)) continue // 已在工程目录（同名幂等）
+    const buf = fs.readFileSync(a.src)
+    const rel = relPathOf(a.src)
+    const renamed = a.name !== a.originalName
+    if (renamed) {
+      console.error(`[slices] 收养时消毒文件名：${a.originalName} → ${a.name}（**schema 引用必须用消毒后的名字**）`)
+    }
+    const png = readPng(a.src)
+    if (png) {
+      const key = pngPixelSha(png)
+      const batchTwin = batch.get(key)
+      if (batchTwin) {
+        reused.push({ name: a.name, originalName: a.originalName, existing: batchTwin, reason: 'batch-identical' })
+        continue
+      }
+      let hit = null
+      for (const dir of reuseDirs) {
+        const twin = findPixelTwin(dir, png, { skip: [a.name] })
+        if (twin) { hit = { twin, dir }; break }
+      }
+      if (hit) {
+        reused.push({
+          name: a.name,
+          originalName: a.originalName,
+          existing: hit.twin,
+          dir: path.basename(hit.dir),
+          reason: 'content-twin',
+        })
+        continue
+      }
+      batch.set(key, a.name)
+      fs.writeFileSync(target, buf)
+      written.push({ name: a.name, originalName: a.originalName, adopted: true, from: rel, px: [png.width, png.height] })
+    } else {
+      // 非 PNG（svg/jpg/webp）：没有像素判据，按名字幂等收养，不去重
+      fs.writeFileSync(target, buf)
+      written.push({ name: a.name, originalName: a.originalName, adopted: true, from: rel, px: null })
+    }
   }
+
   for (const r of reused) console.error(`[slices] 裁切判重：${r.name} ≡ ${r.dir}/${r.existing}（${r.reason}）→ 不写盘，引用改绑 /slices/${r.existing}`)
   console.log(JSON.stringify({ scale, written, reused }, null, 2))
 }
 
+/** 路径输出：在 cwd 内给相对路径，在 cwd 外给绝对路径。 */
+function relPathOf(file) {
+  const rel = path.relative(process.cwd(), file)
+  return rel && !rel.startsWith('..') ? rel.split(path.sep).join('/') : file
+}
+
 main()

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

@@ -1,9 +1,42 @@
 #!/usr/bin/env node
-/** Cross-platform Python detection: DSL_CARD_PYTHON > WORKBUDDY_PYTHON > python3 */
-function findPython() {
-  if (process.env.DSL_CARD_PYTHON) return process.env.DSL_CARD_PYTHON;
-  if (process.env.WORKBUDDY_PYTHON) return process.env.WORKBUDDY_PYTHON;
-  return "python3";
+/**
+ * 跨平台 Python 解释器探测：DSL_CARD_PYTHON > WORKBUDDY_PYTHON > 真探测 python3 / python / py。
+ *
+ * 为什么必须真跑一次 --version（而不是「能不能 spawn」）：Windows 上 `python3` 常是
+ * Microsoft Store 的应用执行别名 —— 进程能启动，却立刻以 9009 退出，**不是 ENOENT**。
+ * 只按 spawn 异常判断就会钉死这个假解释器，autofix / validate 全部静默不执行，
+ * 只回一句「validate 未执行（python 不可用）」，调用方（iterate / expand_ir）看到的是一个
+ * **永远修不好**的 validate error —— 实测模型为它空转 20 轮、每轮都重跑 iterate。
+ */
+function probePython(bin) {
+  try {
+    const r = spawnSync(bin, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) return false;
+    return /Python \d/i.test(`${r.stdout || ''}${r.stderr || ''}`);
+  } catch {
+    return false;
+  }
+}
+
+function pythonCandidates() {
+  const out = [];
+  const seen = new Set();
+  const push = (bin) => {
+    const b = String(bin || '').trim();
+    if (!b || seen.has(b)) return;
+    seen.add(b);
+    out.push(b);
+  };
+  // 显式指定的解释器优先（可用就只认它；探测不过也保留一次机会——可能是带参数的包装器）
+  for (const env of [process.env.DSL_CARD_PYTHON, process.env.WORKBUDDY_PYTHON]) {
+    if (!env) continue;
+    if (probePython(env)) { push(env); return out; }
+    push(env);
+  }
+  for (const bin of ['python3', 'python', 'py']) if (probePython(bin)) push(bin);
+  // 探测全失败：仍按常见名字逐一试跑，让报错里能看到真实失败原因（stderr 原样带出）
+  for (const bin of ['python3', 'python']) push(bin);
+  return out;
 }
 /**
  * expand_ir.mjs — 紧凑 IR（Intermediate Representation）⇄ 完整 schema 双向转换。
@@ -17,7 +50,8 @@ function findPython() {
  *
  * 用法：
  *   node expand_ir.mjs --ir <IR.json> --out <dir>/           # IR → schema.json + data.json（写盘并 autofix+validate）
- *     [--slices-dir <dir>]                                  # 引用切图的来源目录（默认 IR 同目录 slices/）
+ *     [--slices-dir <dir>] [--slices-from <dir,dir>]         # 引用切图的来源目录（可多个；
+ *                                                             # 默认还会查工程 src/slices 与 IR 同目录 slices/）
  *   node expand_ir.mjs --to-ir <schema.json>                 # 完整 schema → 紧凑 IR（stdout，用于验证/二次编辑）
  *   node expand_ir.mjs --self-test [--card DepositHolding]   # round-trip 无损 + validate + lint 自检
  *
@@ -34,11 +68,11 @@ function findPython() {
  */
 import fs from 'node:fs'
 import path from 'node:path'
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { copyCardDesignImage } from './lib/design_image.mjs'
-import { metaDir, skillRoot } from './lib/paths.mjs'
-import { buildContentIndex, rewriteSliceRefs, sha256File } from './lib/slice_dedupe.mjs'
+import { metaDir, projectRoot, skillRoot } from './lib/paths.mjs'
+import { buildContentIndex, rewriteSliceRefs, sha256File, sliceNameMatches } from './lib/slice_dedupe.mjs'
 import { findPixelTwin, readPng } from './lib/slice_pixels.mjs'
 
 /* ------------------------------------------------------------------ */
@@ -96,7 +130,102 @@ function resolveStyleKey(groupKey, childKey) {
   if (styleChildId[groupKey]?.[childKey] !== undefined) return childKey
   const resolved = STYLE_ALIAS[childKey]
   if (resolved && styleChildId[groupKey]?.[resolved] !== undefined) return resolved
-  return childKey // no match — let it pass through (validate will catch)
+  return childKey // no match — 由 collectUnknownStyleKey 记账，写盘前统一响亮失败
+}
+
+/**
+ * 合法样式键全集（唯一来源 style-meta.json）的紧凑一页表，供报错文本直接回给模型。
+ * 实测（2026-09-21 建卡回合）：模型不知道 flex 组没有 flexGrow，写了 `flex:{flexGrow:1}` →
+ * itemId 空串 → 渲染器静默丢弃 → validate 报「整卡 FAIL」，模型看不出是键名错，
+ * 于是 8 次 shell_exec 翻 meta 文件考古 + 6 次把组名写错（size.width 而非 rect.width）。
+ */
+export function styleKeyTableText() {
+  return Object.entries(styleChildId)
+    .map(([g, kids]) => `${g}: ${Object.keys(kids).join(' ')}`)
+    .join('\n')
+}
+
+/**
+ * 归位之后仍然不存在的样式键 ⇒ 运行时静默丢弃。收集起来，**写盘前**中止（别让它进 schema）。
+ * 静默放行是本轮 700 万 token 的主要起点之一：问题的报错信息从「flexGrow 不合法」
+ * 退化成下游 validate 的「整卡 FAIL」，模型只能推倒重写整份 IR。
+ */
+const unknownStyleKeys = []
+function resetUnknownStyleKeys() {
+  unknownStyleKeys.length = 0
+}
+function collectUnknownStyleKey(nodeLabel, groupKey, childKey) {
+  const hit = unknownStyleKeys.find((u) => u.node === nodeLabel && u.group === groupKey && u.key === childKey)
+  if (!hit) unknownStyleKeys.push({ node: nodeLabel || '?', group: groupKey, key: childKey })
+}
+
+/** 非法键的响亮报错文本：逐条点名 + 该组合法子键 + 全局一页表（约 1KB，够模型一次改对） */
+function unknownStyleKeysError() {
+  const lines = ['[ir] 非法样式键（运行时会被静默丢弃，已中止写盘，schema 未改动）：']
+  for (const u of unknownStyleKeys.slice(0, 20)) {
+    const kids = Object.keys(styleChildId[u.group] || {})
+    const groupNote = kids.length ? ` → ${u.group} 组合法子键只有 ${kids.join('/')}` : `（style-meta 里没有 "${u.group}" 这个组）`
+    lines.push(`  ${u.node}.s.${u.group}.${u.key}${groupNote}`)
+    const owners = styleGroupsOfChild[u.key] || []
+    if (owners.length === 1) lines.push(`      纠正：${u.key} 属于 ${owners[0]} 组，写成 ${owners[0]}.${u.key}`)
+    else if (owners.length > 1) lines.push(`      纠正：${u.key} 属于 ${owners.join(' / ')} 组`)
+  }
+  if (unknownStyleKeys.length > 20) lines.push(`  …还有 ${unknownStyleKeys.length - 20} 处`)
+  lines.push('', '合法样式键全集（style-meta.json）：', styleKeyTableText())
+  return lines.join('\n')
+}
+// 子键 → 它合法归属的组（style-meta 全局唯一来源）。用来把「键对、组写错」的样式自动归位。
+const styleGroupsOfChild = {}
+for (const g of SM.properties || []) {
+  for (const c of g.itemChildren || []) {
+    ;(styleGroupsOfChild[c.itemKey] ||= []).push(g.itemKey)
+  }
+}
+
+/**
+ * 把写错组的样式搬回它该在的组，并丢掉 Root 上非法的 rect 组。
+ *
+ * 实测（2026-09-21 权益活动建卡）：IR 写 `s.rect.position/left/top`，而 style-meta 里
+ * position/left/top 属于 position 组、rect 只有 width/height → 展开后 itemId 为空串，
+ * validate 一次报 19 个错（"运行时静默丢弃该样式"）。模型看不出是「组写错」，只会逐个猜。
+ * 这里按 style-meta 做机械归位：子键全库只属于另一个组时直接搬过去（不唯一就不猜，交给 validate）。
+ * Root 的 rect 组则直接丢：宽度由顶层 view.width 承载，validate 明文禁止
+ * （Root_style_rect_forbidden）。
+ */
+function normalizeStyleGroups(s, className, nodeLabel = '') {
+  const out = {}
+  const put = (gk, ck, cv) => {
+    const bucket = out[gk]
+    if (bucket === undefined) { out[gk] = { [ck]: cv }; return }
+    if (typeof bucket !== 'object' || Array.isArray(bucket)) {
+      if (typeof cv === 'object' && cv !== null && !Array.isArray(cv)) out[gk] = { [ck]: cv }
+      return // 标量组与对象组撞车：保留先到的那个，validate 会兜底
+    }
+    bucket[ck] = cv
+  }
+  for (const [gk, gv] of Object.entries(s || {})) {
+    const isObj = gv && typeof gv === 'object' && !Array.isArray(gv)
+    if (!isObj) {
+      if (className === 'Root' && gk === 'rect') continue
+      if (out[gk] === undefined) out[gk] = gv
+      continue
+    }
+    for (const [ck, cv] of Object.entries(gv)) {
+      let target = gk
+      if (styleChildId[gk]?.[resolveStyleKey(gk, ck)] === undefined) {
+        const elsewhere = (styleGroupsOfChild[ck] || []).filter((g) => g !== gk)
+        if (elsewhere.length === 1) target = elsewhere[0]
+      }
+      if (className === 'Root' && target === 'rect') continue
+      if (target !== gk) console.log(`[ir] 样式组归位：${gk}.${ck} → ${target}.${ck}`)
+      // 归位后仍不在该组：这个名字 style-meta 里根本没有 ⇒ 记下来，写盘前中止
+      if (styleChildId[target]?.[resolveStyleKey(target, ck)] === undefined) {
+        collectUnknownStyleKey(nodeLabel || className, target, ck)
+      }
+      put(target, ck, cv)
+    }
+  }
+  return out
 }
 // directive itemId + child
 const dirId = {}
@@ -229,6 +358,9 @@ function ensureRootDefaults(view) {
 /** 把 IR 的属性/样式/指令/事件填进节点（不含 children/slots，供 Root 与子节点共用）。 */
 function applyProps(node, ir) {
   const className = node.className
+  // 样式组先归位（键对组错的 IR 写法机械纠正），后面的「自动补类型」都按组名判断，
+  // 归位后再补才不会漏（例如写在 rect 组里的 paddingTop 也该补上 paddingType）。
+  if (ir.s) ir = { ...ir, s: normalizeStyleGroups(ir.s, className, node.componentId || ir.id || className) }
   // 主值 value（t / v）
   if (ir.t !== undefined && ir.v !== undefined) {
     // 实测事故：--set 给已有 t 的节点补 v 后，t 被当主值、from 却按绑定标 "1"，
@@ -246,6 +378,18 @@ function applyProps(node, ir) {
   }
   // 图片属性 pi（itemValueFrom=2）
   for (const [k, val] of Object.entries(ir.pi || {})) {
+    // 实测事故（demo/helloCard 2026-09-21）：pi 是「静态图片/文件值」专用槽，运行时对 "2"
+    // 是**原样透传**（property.js onPreview 就一句 out[itemKey] = itemValue），从不对值求值。
+    // 把 $ 表达式写进 pi，这串字面量会被直接当图片地址 → background-image:url($icon) →
+    // 画布那张图静默空白，而 切图 HTTP 全 200 / validate 全绿 / 控制台无报错，
+    // 极易被误判成「src/slices 没托管」。与 t/v 互斥同类，此处响亮报错，别让它在 schema 里落地。
+    if (isVar(val)) {
+      throw new Error(
+        `节点 "${ir.id || className}" 的 pi.${k} 收到表达式 ${JSON.stringify(val)}：pi 是静态图片槽（itemValueFrom="2"），` +
+          `运行时原样透传当图片地址用，表达式永远渲染成空白。变量绑定改用 p.${k}:"${val}"（自动 itemValueFrom="1"）；` +
+          `静态切图传路径如 "/slices/xxx.png"`,
+      )
+    }
     node.properties.push(makeProp(compPropId[className]?.[k], k, val, '2'))
   }
 
@@ -458,6 +602,7 @@ function normalizeInputParams(params) {
  * @returns {{schema:object, data:object}}
  */
 export function expandIR(ir) {
+  resetUnknownStyleKeys()
   const ctx = { n: 0, nextId: () => `comp_${++ctx.n}` }
   const viewChildren = (ir.children || []).map((k) => expandNode(k, ctx))
   const dictionary = ir.dictionary
@@ -668,15 +813,23 @@ function collectSliceRefs(node, out = new Set()) {
   return out
 }
 
-export function syncReferencedSlices(schema, irPath, slicesDir) {
+export function syncReferencedSlices(schema, irPath, slicesDirs) {
   const result = { copied: 0, reused: 0, rewrites: [] }
   const refs = collectSliceRefs(schema.view)
   if (!refs.size) return result
-  const repoRoot = path.resolve(skillRoot, '..', '..')
-  const targetDir = path.join(repoRoot, 'src', 'slices')
+  // 落点必须是**宿主工程根**（cwd / DSL_CARD_PROJECT_ROOT），不能按脚本自身位置往上推：
+  // 发布态里脚本在 dist/vendored/skills 下，往上推会把切图写进包内（0.14.1 同类事故）。
+  const targetDir = path.join(projectRoot, 'src', 'slices')
   fs.mkdirSync(targetDir, { recursive: true })
-  // 切图来源：--slices-dir 显式指定（要素包 slices/）优先，其次 IR 同目录 slices/
-  const sourceDirs = [...(slicesDir ? [path.resolve(slicesDir)] : []), path.join(path.dirname(path.resolve(irPath)), 'slices')]
+  // 切图来源顺序：--slices-dir / --slices-from 显式指定（要素包 slices/、工程 slices/ 都可给，
+  // 逗号分隔多来源）→ 工程 slices/ 自身 → IR 同目录 slices/
+  const given = (Array.isArray(slicesDirs) ? slicesDirs : [slicesDirs])
+    .flatMap((d) => String(d || '').split(','))
+    .map((d) => d.trim())
+    .filter(Boolean)
+    .map((d) => path.resolve(d))
+  const sourceDirs = [...given, targetDir, path.join(path.dirname(path.resolve(irPath)), 'slices')]
+    .filter((d, i, arr) => arr.indexOf(d) === i)
   let hitDir = null
   // 落地前判重（slices_convention.md §3.1）：内容 sha256 一致即同一张图 → 复用既有文件，
   // 不新增副本，并把 schema 引用改写到既有文件名（避免「同图多名」堆重复素材）。
@@ -687,9 +840,36 @@ export function syncReferencedSlices(schema, irPath, slicesDir) {
     try { name = decodeURIComponent(name) } catch {}
     const target = path.join(targetDir, name)
     if (fs.existsSync(target)) continue
-    const source = sourceDirs.map((d) => path.join(d, name)).find((f) => fs.existsSync(f))
+    let source = sourceDirs.map((d) => path.join(d, name)).find((f) => fs.existsSync(f))
+    // 源目录里可能仍存设计稿原名（`警示-#999.png`），而引用是消毒名（`警示-999.png`）
+    // → 归一后逐目录再找一次。少了这步会「文件明明在、却报引用不存在」并中断整轮生成。
+    if (!source) {
+      for (const d of sourceDirs) {
+        let entries = []
+        try { entries = fs.readdirSync(d) } catch { continue }
+        const hit = entries.find((f) => /\.(png|jpe?g|webp|svg)$/i.test(f) && sliceNameMatches(f, name))
+        if (hit) { source = path.join(d, hit); break }
+      }
+    }
     if (!source) {
-      throw new Error(`IR 引用的切图不存在：${ref}（已查找 ${sourceDirs.join(' / ')}；可用 --slices-dir 指向要素包的 slices 目录）`)
+      // 报错要能一次改对：把搜索目录里「名字沾边」的候选列出来。此前只报「找不到」，
+      // 模型只能 fs_list 两个目录来回摸（实测多花 3 步 + 1.5 分钟），其实候选就摆在手边。
+      const stem = path.basename(name, path.extname(name)).toLowerCase()
+      const words = stem.split(/[^a-z0-9\u4e00-\u9fa5]+/i).filter((w) => w.length > 1)
+      const cands = []
+      for (const d of sourceDirs) {
+        let entries = []
+        try { entries = fs.readdirSync(d) } catch { continue }
+        for (const f of entries) {
+          if (!/\.(png|jpe?g|webp|svg)$/i.test(f)) continue
+          const lower = f.toLowerCase()
+          if (lower === path.basename(name).toLowerCase() || words.some((w) => lower.includes(w))) cands.push(path.join(d, f))
+        }
+      }
+      const hint = cands.length
+        ? `\n     名字沾边的候选（可直接把引用改成它，或把文件按你需要重命名后重跑）：\n${cands.slice(0, 8).map((c) => '       - ' + c).join('\n')}`
+        : ''
+      throw new Error(`IR 引用的切图不存在：${ref}（已查找 ${sourceDirs.join(' / ')}；可用 --slices-dir / --slices-from 指向要素包或工程的 slices 目录）${hint}`)
     }
     hitDir = path.dirname(source)
     const sha = sha256File(source)
@@ -771,17 +951,24 @@ function runPyScript(py, script, args) {
 /** autofix（机械修复，exit 1 仅代表「仍有非机械错误」）+ validate（真门禁）。
  *  历史 bug：autofix 的 exit 1 曾被当成致命异常，导致 validate 从未执行、
  *  报出误导性的「validate 未执行（未找到 python）」，模型转而信任无校验的旁路。 */
+export function resolvePythonBin() {
+  for (const bin of pythonCandidates()) if (probePython(bin)) return bin
+  return null
+}
+
 export function runAutofixAndValidate(schemaPath) {
-  const PY = findPython()
-  const candidates = [PY, 'python3']
+  const candidates = pythonCandidates()
   let lastOut = ''
   for (const py of candidates) {
     let autofix
     try {
       autofix = runPyScript(py, 'autofix_schema.py', [schemaPath])
     } catch {
-      continue // 该 python 二进制不存在，换下一个候选
+      continue // 该 python 二进制不存在（ENOENT），换下一个候选
     }
+    // 假解释器（Windows Store 别名 / 空壳 wrapper）能启动但零产出：不能拿它当「跑过了」，
+    // 否则 autofix 与 validate 都没执行，却被报成 schema 校验失败。
+    if (!autofix.stdout && autofix.code !== 0) continue
     const v = runPyScript(py, 'validate_schema.py', [schemaPath, '--json'])
     const out = v.stdout || autofix.stdout
     if (out) {
@@ -795,7 +982,17 @@ export function runAutofixAndValidate(schemaPath) {
       } else lastOut = out.slice(0, 200)
     }
   }
-  return { ok: false, errors: [`validate 未执行（python 不可用${lastOut ? `：${lastOut}` : ''}）`], warnings: [] }
+  // envError：调用方（iterate 门禁）据此判「环境阻塞」而不是「卡片有错」——
+  // 实测这个区别决定模型是停下来告诉用户，还是为一条永远修不好的 error 空转 20 轮。
+  return {
+    ok: false,
+    envError: true,
+    errors: [
+      `validate 未执行（没找到可用的 python 解释器：试过 ${candidates.join(' / ')}）` +
+        `${lastOut ? `：${lastOut}` : ''}。这不是卡片的错误——装 Python 或设 DSL_CARD_PYTHON=<解释器路径> 后重跑，不要为它改 schema。`,
+    ],
+    warnings: [],
+  }
 }
 
 function main() {
@@ -818,7 +1015,7 @@ function main() {
     errs.slice(0, 20).forEach((e) => console.log('   DIFF ' + e))
 
     // 写临时卡跑 validate + lint
-    const repoRoot = path.resolve(skillRoot, '..', '..')
+    const repoRoot = projectRoot
     const tmpId = '__ir_selftest__'
     const tmpDir = path.join(repoRoot, 'src', 'cards', tmpId)
     fs.mkdirSync(tmpDir, { recursive: true })
@@ -845,6 +1042,13 @@ function main() {
   if (args.ir && args.out) {
     const ir = JSON.parse(fs.readFileSync(args.ir, 'utf8'))
     const { schema, data } = expandIR(ir)
+    // 非法样式键：**写盘前**中止。放行的代价是「schema 写得像成功、渲染却丢样式」，
+    // 下游 validate 只会报整卡 FAIL，模型看不出是键名错 → 推倒重写整份 IR（实测 16 次）。
+    if (unknownStyleKeys.length) {
+      console.error(unknownStyleKeysError())
+      console.error(`\n[ir] 共 ${unknownStyleKeys.length} 处非法样式键，已中止（schema/data 未写盘）。改键名即可，不要重写整份 IR。`)
+      process.exit(3)
+    }
     fs.mkdirSync(args.out, { recursive: true })
     const sp = path.join(args.out, 'schema.json')
     const dp = path.join(args.out, 'data.json')
@@ -852,7 +1056,7 @@ function main() {
     if (snap) console.log(`[history] 已快照旧 schema → .history/${snap}（覆盖前备份，可回滚）`)
     fs.writeFileSync(sp, JSON.stringify(schema, null, 2) + '\n')
     fs.writeFileSync(dp, JSON.stringify(data, null, 2) + '\n')
-    const sliceSync = syncReferencedSlices(schema, args.ir, args['slices-dir'])
+    const sliceSync = syncReferencedSlices(schema, args.ir, [args['slices-dir'], args['slices-from']])
     if (sliceSync.rewrites.length) {
       // 去重改写发生在 schema 落盘之后 → 回写 schema/data，保证盘上引用与 src/slices 一致
       rewriteSliceRefs(data, sliceSync.rewrites)

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

@@ -0,0 +1,144 @@
+#!/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>   13 项机械检查（给了 --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'
+
+// ---------- 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')
+const py = process.env.PYTHON || 'python3'
+
+/** 跑一步门禁。返回 { 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)