cardbuddy 0.14.3 → 0.16.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,10 +1,8 @@
 #!/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 解释器解析已集中到 lib/python.mjs（单一来源：四段环境变量链 + Windows Store
+// 假别名识别）。本文件要的是**候选列表**（逐个试跑，好把真实 stderr 带进报错），
+// 不是「最优那一个」。
+import { probePython, pythonCandidates, resolvePython } from './lib/python.mjs'
 /**
  * expand_ir.mjs — 紧凑 IR（Intermediate Representation）⇄ 完整 schema 双向转换。
  *
@@ -17,7 +15,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,12 +33,13 @@ 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'
+import { normalizeItemAliases } from './lib/scope_alias.mjs'
 
 /* ------------------------------------------------------------------ */
 /* 加载 meta → itemId 映射（与 validate_schema.py 同源，零偏离）        */
@@ -96,7 +96,123 @@ 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。
+ */
+/**
+ * 作用域别名归一化（**不是报错禁止**）——实现见 `lib/scope_alias.mjs`。
+ *
+ * 2026-09-24 复盘定论：`$item.xxx` 这类写法**不是模型的问题，是我们自己的问题**。
+ * 系统提示词与 ir-format.md 里手写了一条不存在的契约（提交 56e9894「子树内 $item.xxx /
+ * $_index」），模型只是老实照做。权威契约来自运行时 `card-editor/runtime/evaluate.js`
+ * 的 `makeSlotScope`：`slotScope = 外层 ∪ item 字段逐个展开 ∪ {$$: item, _index: 索引}`
+ * —— **没有 `item` 这个键**；全仓 50 张真卡的列表插槽绑定也 100% 用扁平字段名（`$name` /
+ * `$label` / `$accountNum`），`$item.` 出现 0 次。
+ *
+ * 上一版的处理是「写盘前 exit=3 中止 + lint 报 ERROR + 三份文档写满 ⛔ 没有 $item」——
+ * 那等于教错了再罚学生：模型必须先背对答案才不被退回，而答案本来就不该由它背。
+ *
+ * 正确做法是把 IR 当成**编译器输入**：编译器对公认别名做语义保持的归一化即可，
+ * schema 里永远只出现规范形（`$字段` / `$$` / `$_index`），模型写哪种都能过。
+ *
+ * 唯一的例外闸：卡片若真的声明了名为 `item` 的根变量（dictionary.inputParams[].key），
+ * 则 `$item.x` 是合法取值，整体不归一化（见 lib 头注释）。
+ */
+
+
+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 +345,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 +365,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'))
   }
 
@@ -344,6 +475,13 @@ function applyProps(node, ir) {
   for (const ev of ir.e || []) node.eventactions.push(makeEvent(ev))
 }
 
+// 容器类名单：与 validate_schema.py 的 CONTAINER_TYPES（+ Select）对齐。
+// 这些 className 的节点必须始终带 slots（无子组件时兜底空 default slot）。
+const CONTAINER_CLASSNAMES = new Set([
+  'Root', 'Row', 'Column', 'AbsoluteLayout', 'MultiColumn',
+  'ListLayout', 'GridLayout', 'SingleColumn', 'CheckGroup', 'RadioButton', 'Select',
+])
+
 function expandNode(ir, ctx) {
   const className = ir.c
   if (!className) throw new Error('IR 节点缺少 className (c)')
@@ -374,7 +512,14 @@ function expandNode(ir, ctx) {
       components: kids.map((k) => expandNode(k, ctx)),
     })
   }
-  if (slotDefs.length) node.slots = slotDefs
+  if (slotDefs.length) {
+    node.slots = slotDefs
+  } else if (CONTAINER_CLASSNAMES.has(className)) {
+    // 契约（dsl_structure.md §slots / component_rules.md）：容器类节点即使无子组件也须带
+    // 空 default slot —— 否则 validate_schema.py WARN "has no slots"，且下游（check_topology、
+    // 预览器）按 slot 结构消费时缺字段。
+    node.slots = [{ slotKey: 'default', slotName: '默认插槽', slotSwitch: '1', components: [] }]
+  }
   return node
 }
 
@@ -458,6 +603,14 @@ function normalizeInputParams(params) {
  * @returns {{schema:object, data:object}}
  */
 export function expandIR(ir) {
+  resetUnknownStyleKeys()
+  // 作用域别名归一化（**在扩展开头做**，早于 collectRootBindings 推断 inputParams）。
+  // 放在这里而不是 CLI 分支里：iterate.mjs 是直接 import expandIR 在进程内跑的，
+  // 只写在 CLI 里会让「AI 建卡主路径」（iterate）完全绕过归一化 —— 历史事故的翻版。
+  const knownRoots = new Set(
+    ((ir.dictionary && ir.dictionary.inputParams) || []).map((p) => p && p.key).filter(Boolean),
+  )
+  const aliasFixes = normalizeItemAliases(ir, { knownRoots })
   const ctx = { n: 0, nextId: () => `comp_${++ctx.n}` }
   const viewChildren = (ir.children || []).map((k) => expandNode(k, ctx))
   const dictionary = ir.dictionary
@@ -497,7 +650,7 @@ export function expandIR(ir) {
   schema.dictionary.inputParams = normalizeInputParams(schema.dictionary.inputParams)
   const data = {}
   for (const p of schema.dictionary.inputParams || []) data[p.key] = p.defaultValue
-  return { schema, data }
+  return { schema, data, aliasFixes }
 }
 
 /* ------------------------------------------------------------------ */
@@ -657,6 +810,27 @@ function compareNodes(a, b, p) {
 /* ------------------------------------------------------------------ */
 /* CLI                                                                 */
 /* ------------------------------------------------------------------ */
+/**
+ * 递归枚举目录下全部文件。要素包 slices/ 是嵌套目录（如 8.icon/通用/警示-#999@3x.png），
+ * 旧版平铺 readdirSync 只扫顶层够不着真身 → exit=1 + fs_list 逐层摸索 + fs_copy 手工搬运
+ * （gen-1 实测约 10 次调用白烧，占该回合前半段 38%）。
+ */
+function listSliceFilesDeep(dir) {
+  const out = []
+  const stack = [dir]
+  while (stack.length) {
+    const cur = stack.pop()
+    let entries
+    try { entries = fs.readdirSync(cur, { withFileTypes: true }) } catch { continue }
+    for (const ent of entries) {
+      const p = path.join(cur, ent.name)
+      if (ent.isDirectory()) stack.push(p)
+      else if (ent.isFile()) out.push(p)
+    }
+  }
+  return out
+}
+
 function collectSliceRefs(node, out = new Set()) {
   if (!node || typeof node !== 'object') return out
   for (const p of node.properties || []) {
@@ -668,15 +842,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 +869,41 @@ 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) {
+        // 递归枚举（要素包 slices 嵌套子目录）；命中判据沿用 sliceNameMatches（口径同源，禁另起一套）
+        const hits = listSliceFilesDeep(d).filter(
+          (f) => /\.(png|jpe?g|webp|svg)$/i.test(f) && sliceNameMatches(path.basename(f), name),
+        )
+        // 同名命中多处不猜：报错列出全部命中绝对路径，让调用方把引用改带子目录或挪走多余文件
+        if (hits.length > 1) {
+          throw new Error(
+            `IR 引用的切图 ${ref} 在 ${d} 下命中多个同名文件，不猜——把引用改成带子目录的相对路径，或挪走多余文件后重跑：\n${hits.map((h) => '       - ' + h).join('\n')}`,
+          )
+        }
+        if (hits.length === 1) { source = hits[0]; 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) {
+        for (const f of listSliceFilesDeep(d)) {
+          if (!/\.(png|jpe?g|webp|svg)$/i.test(f)) continue
+          const lower = path.basename(f).toLowerCase()
+          if (lower === path.basename(name).toLowerCase() || words.some((w) => lower.includes(w))) cands.push(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 +985,26 @@ function runPyScript(py, script, args) {
 /** autofix（机械修复，exit 1 仅代表「仍有非机械错误」）+ validate（真门禁）。
  *  历史 bug：autofix 的 exit 1 曾被当成致命异常，导致 validate 从未执行、
  *  报出误导性的「validate 未执行（未找到 python）」，模型转而信任无校验的旁路。 */
+export function resolvePythonBin() {
+  // 保留 null 语义（调用方靠它区分「没装 Python」）：探测不过就明确返回 null，
+  // 而不是像 resolvePython() 那样回落到 'python3' 让调用方带着假解释器去试跑。
+  const bin = resolvePython()
+  return probePython(bin) ? bin : 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 +1018,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 +1051,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 })
@@ -844,7 +1077,24 @@ function main() {
   }
   if (args.ir && args.out) {
     const ir = JSON.parse(fs.readFileSync(args.ir, 'utf8'))
-    const { schema, data } = expandIR(ir)
+    const { schema, data, aliasFixes } = expandIR(ir)
+    // 归一化是**静默修好**，不是拦下来让模型重写：改一个字符串的字面量而已，
+    // 报一句「已归一化 N 处」让调用方知道发生了什么，但不中断流程。
+    if (aliasFixes && aliasFixes.count) {
+      console.error(
+        `[ir] 已归一化 ${aliasFixes.count} 处列表作用域别名（$item.<字段> → $<字段>、$item → $$、$item._index → $_index）：schema 里只存规范形，无需重写 IR。`,
+      )
+      for (const s of aliasFixes.samples.slice(0, 3)) {
+        console.error(`     ${s.at}: ${s.before}  →  ${s.after}`)
+      }
+    }
+    // 非法样式键：**写盘前**中止。放行的代价是「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 +1102,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)