cardbuddy 0.14.2 → 0.15.0

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

@@ -15,7 +15,17 @@
  * 输出（stdout JSON）：
  *   { card, design:{scale}, texts[], shapes[], slices[], bands[], gaps{}, colors[], missing[],
  *     bindHints[], listCandidates[] }
+ *   - shapes[] 每条 = { x,y,w,h, bg, gradient, bgImage, border, radius, opacity }
+ *     · **gradient / border / bgImage 必须带出来**：只给 bg 时，渐变底板与描边层在模型眼里
+ *       就是一个「什么都没有的空节点」，会被整块丢掉（2026-09-21 helloCard：顶部渐变区 343×154、
+ *       两块产品底板 311×62、红标签 0.5px #F6434F 描边、311×0.5 分割线，四处全丢）。
+ *       没有视觉能力的模型只能靠这份清单知道「这里有个东西要画」。
+ *     · gradient 是 CSS 串（spec 里已是该格式），可直接喂 expand_ir 的 backgroundGradient。
  *   - slices[].verdict ∈ full-asset / missing-file / reused-differs / reused-identical / content-twin
+ *     · ref = 设计稿图层**完整**引用（含 `8.icon/通用/` 这类分组路径）；name = **消毒后的落盘/引用名**，
+ *       两者不同时另带 originalName。存在性判定按完整 ref + `@2x/@3x` 后缀查
+ *       （MeaXure 常态落点是 `slices/<分组路径>/<名>@3x.png`）——只按 basename 找扁平文件会把
+ *       **真实存在**的资产报成 missing-file，下游白重裁或模型改用图层名当引用（浏览器 404）。
  *     · content-twin：导出资产缺文件，但**既有切图里已有像素同内容**（共用/语义重命名/跨画板）→ 直接复用，不裁切
  *     · crops[] 按**指纹分组**产出：同组（内容相同）的多个矩形共用一张派生图（alsoRects 列同组其余矩形），
        不再「每个矩形一个 _altN」；派生前先对既有切图做像素级判重，命中给 reuseOf（引用改绑既有名，不裁切）
@@ -30,6 +40,7 @@ import path from 'node:path'
 
 const { PNG } = await import('pngjs')
 import { cropPng, findPixelTwin } from './lib/slice_pixels.mjs'
+import { sanitizeSliceFileName } from './lib/slice_dedupe.mjs'
 
 function parseArgs(argv) {
   const out = { spec: '', card: 1, slicesDir: '', design: '', projectSlices: '' }
@@ -41,10 +52,13 @@ function parseArgs(argv) {
     else if (a === '--design') out.design = argv[++i] || ''
     else if (a === '--project-slices') out.projectSlices = argv[++i] || ''
     else if (a === '--save') out.save = argv[++i] || ''
+    else if (a === '--no-save') out.noSave = true
     else if (a === '-h' || a === '--help') {
-      console.log('Usage: node spec_audit.mjs --spec <spec.json> [--card 1] [--slices-dir <dir>] [--design <card-N.png>] [--save <path.json>]')
-      console.log('  --save：把整份审计 JSON 原样落盘（供 crop_slices --from-audit 直接消费）。')
+      console.log('Usage: node spec_audit.mjs --spec <spec.json> [--card 1] [--slices-dir <dir>] [--design <card-N.png>] [--save <path.json>] [--no-save]')
+      console.log('  --save：整份审计 JSON 落盘路径；不给就默认落 <工程根>/.cache/spec-audit/<spec 名>-card<N>.json。')
       console.log('  历史事故：模型用手抄的 156 字节「审计摘要」喂 crop_slices，切图名/矩形全错；审计必须整份落盘复用，禁止手抄。')
+      console.log('  --no-save：不落盘（只在明确不需要 crop_slices --from-audit 时才用）。')
+      console.log('  stdout 一律是紧凑 JSON 审计简报；超过 9000 字会改出「摘要 + savedTo」。')
       process.exit(0)
     }
   }
@@ -103,7 +117,6 @@ function analyzeSlice(file) {
   return { px: [png.width, png.height], bg, label: rows > 0 && labelRows / rows > 0.2 }
 }
 
-/** 切图名可能不带扩展名（spec 里存的是图层名），逐个候选扩展名找文件 */
 /**
  * manifest 别名表：语义重命名（slices_normalize / 手工改名）后，导出原名 → 新名的映射。
  * 读各目录 manifest.json 的 renamedFrom / mergedFrom（§1.1「改名要成套做」的机器可读痕迹）。
@@ -123,18 +136,59 @@ function buildAliasMap(dirs) {
   return aliases
 }
 
-function resolveSliceFile(dirs, name, aliases = null) {
-  const base = path.extname(name) ? name : `${name}.png`
-  const names = [name]
-  const alias = aliases && (aliases.get(name) || aliases.get(base))
-  if (alias) names.push(alias)
-  for (const dir of dirs) {
-    for (const nm of names) {
-      const b = path.extname(nm) ? nm : `${nm}.png`
-      for (const cand of [b, nm, `${nm}.jpg`, `${nm}.jpeg`, `${nm}.webp`]) {
-        const f = path.join(dir, cand)
-        if (fs.existsSync(f)) return f
-      }
+/** 路径输出：在 cwd 内给相对路径（好读、可复现），在 cwd 外给绝对路径（否则一串 `../../..`）。 */
+function relOrAbs(file) {
+  const rel = path.relative(process.cwd(), file)
+  return rel && !rel.startsWith('..') ? rel.split(path.sep).join('/') : file
+}
+
+/**
+ * 解析切图引用 → 实际文件。
+ *
+ * **必须吃全引用路径（含子目录）与 `@Nx` 倍图后缀**。历史事故（2026-09-21 helloCard）：
+ * 旧实现 `path.basename(ref)` 后再拼 `<名>.png` 找一个扁平文件，而 MeaXure 导出把切图放在
+ * `slices/<图层分组路径>/<名字>@3x.png` —— 于是**磁盘上明明存在**的资产被判成 `missing-file`，
+ * 下游要么白重裁一遍（丢原图品质），要么模型改用设计稿图层名当引用、浏览器 404（图片空白零报错）。
+ *
+ * 候选优先级：完整 ref → basename → manifest 别名；每层再补 `@3x/@2x` 与常见扩展名。
+ * 循环以「名字」为外层、「目录」为内层：**精确 ref 命中优先于模糊命中**，
+ * 避免 bundle 里的 `@3x` 猜中而把工程里真名同名的扁平切图挤掉。
+ */
+function resolveSliceFile(dirs, ref, aliases = null) {
+  const raw = String(ref || '').replace(/\\/g, '/').replace(/^\/+/, '').trim()
+  if (!raw) return null
+  const base = path.basename(raw)
+  const dirPart = path.dirname(raw) === '.' ? '' : path.dirname(raw)
+  const stripExt = (s) => (path.extname(s) ? s.slice(0, -path.extname(s).length) : s)
+  const alias = aliases && (aliases.get(raw) || aliases.get(base) || aliases.get(stripExt(base)))
+  const rels = [...new Set([raw, base, ...(alias ? [alias, path.basename(alias)] : [])].filter(Boolean))]
+  const names = []
+  for (const rel of rels) {
+    const ext = path.extname(rel)
+    const core = stripExt(rel)
+    const exts = ext ? [ext] : ['.png', '.jpg', '.jpeg', '.webp', '.svg']
+    for (const e of exts) names.push(`${core}${e}`)
+    // 倍图后缀：MeaXure 常态是 `<名>@3x.png`，仅当引用本身没带 @Nx 时补
+    if (!/@\dx$/i.test(core)) {
+      for (const e of exts) names.push(`${core}@3x${e}`, `${core}@2x${e}`)
+    }
+  }
+  for (const nm of names) {
+    for (const dir of dirs) {
+      const f = path.join(dir, nm)
+      if (fs.existsSync(f)) return f
+    }
+  }
+  // 兜底：ref 带子目录但导出时把目录压平了（少数导出脚本行为），按 basename 在子目录里搜一层
+  if (dirPart) {
+    for (const dir of dirs) {
+      const sub = path.join(dir, dirPart)
+      if (!fs.existsSync(sub)) continue
+      try {
+        for (const f of fs.readdirSync(sub)) {
+          if (stripExt(f) === stripExt(base)) return path.join(sub, f)
+        }
+      } catch {}
     }
   }
   return null
@@ -210,21 +264,40 @@ function main() {
       })
     } else if (n.type === 'slice') {
       const raw = typeof n.slices === 'string' ? n.slices : (n.slices && (n.slices.name || n.slices.path)) || n.name || ''
-      sliceEls.push({ name: path.basename(String(raw)), rect })
+      // ref 保留**完整**引用（含 `8.icon/通用/` 这类分组路径）——basename 会让存在性判定失准；
+      // name 给的是**消毒后的落盘名**，模型必须拿它写 /slices 引用（含 `#`/`%`/`&` 会被浏览器截断）。
+      const ref = String(raw).replace(/\\/g, '/').replace(/^\/+/, '').trim()
+      sliceEls.push({ ref, name: sanitizeSliceFileName(path.basename(ref)), rect })
     } else if (n.type === 'shape') {
       const st = n.style || {}
-      const bg = (st.background && st.background.color) || (st.fill && st.fill.color) || null
-      shapes.push({ ...rect, bg, radius: st.radius ?? null, opacity: st.opacity ?? 1 })
+      const fill = st.fill || {}
+      const background = st.background || {}
+      const bd = st.border || {}
+      shapes.push({
+        ...rect,
+        // background 优先（与设计工具的语义一致：background = 容器底色，fill = 形状填色）
+        bg: background.color || fill.color || null,
+        // 渐变层必须显式带出来。只给 bg:null 时模型看到的是「一个什么都没有的空节点」，
+        // 于是渐变底板 / 顶部渐变区会被整块丢掉（helloCard 实测丢 3 处：顶部 343×154 + 两块 311×62 底板）。
+        // spec 里 gradient 已经是 CSS 串，原样透传（与 expand_ir 的 backgroundGradient 同格式）。
+        gradient: background.gradient || fill.gradient || null,
+        bgImage: background.image || fill.image || null,
+        // 描边同理：红标签的 0.5px #F6434F 边框不报出来，模型就只会写一个裸 Text。
+        border: bd.isBorder ? { color: bd.color || null, width: bd.width ?? null } : null,
+        radius: st.radius ?? null,
+        opacity: st.opacity ?? 1,
+      })
     }
     ;(n.children || []).forEach(walk)
   }
   ;(card.elements || []).forEach(walk)
 
   // 切图清单：存在性 / 复用 / 烘焙内容 / 复用但内容不同
-  const byName = new Map()
+  // 按**完整 ref** 分组（不是 basename）：分组路径是图层身份的一部分，两个不同分组的同名图层是两张图。
+  const byRef = new Map()
   for (const el of sliceEls) {
-    if (!byName.has(el.name)) byName.set(el.name, [])
-    byName.get(el.name).push(el.rect)
+    if (!byRef.has(el.ref)) byRef.set(el.ref, [])
+    byRef.get(el.ref).push(el.rect)
   }
   const slicesDir = args.slicesDir || path.join(path.dirname(args.spec), 'slices')
   // 派生切图的唯一落点是 src/slices/：已派生过的缺口不应再报 missing（否则每轮都建议重裁）
@@ -244,7 +317,8 @@ function main() {
     })
     return groups
   }
-  /** 设计稿矩形区域 ↔ 既有切图的像素级判重（sha 快路径 + 容差兜底，slice_pixels.mjs）。
+  /**
+ * 设计稿矩形区域 ↔ 既有切图的像素级判重（sha 快路径 + 容差兜底，slice_pixels.mjs）。
    *  覆盖「共用切图已语义重命名 / 在别的画板已派生过」——名字对不上也能认出来。 */
   const regionTwin = (rect) => {
     if (!design) return null
@@ -255,11 +329,15 @@ function main() {
     }
     return null
   }
-  for (const [name, rects] of byName) {
-    let file = resolveSliceFile(sliceDirs, name, aliases)
+  for (const [ref, rects] of byRef) {
+    // `ref` = 设计稿里的完整图层引用（含分组路径）；`name` = 消毒后的落盘/引用名。
+    // 两者都报出来：模型按 name 写 /slices 引用，按 ref 回查设计稿图层。
+    const originalName = path.basename(ref)
+    const name = sanitizeSliceFileName(originalName)
+    const stem = path.extname(name) ? name.slice(0, -path.extname(name).length) : name
+    let file = resolveSliceFile(sliceDirs, ref, aliases)
     let exists = !!file
     let info = exists ? analyzeSlice(file) : null
-    const logical = info ? [Math.round(info.px[0] / (info.px[0] / rects[0].w)), Math.round(info.px[1] / (info.px[1] / rects[0].h))] : null
     let verdict = exists ? 'full-asset' : 'missing-file'
     let reuseOf = null
     let crops = null
@@ -274,17 +352,16 @@ function main() {
         file = path.join(twin0.dir, twin0.twin)
         info = analyzeSlice(file)
       } else {
-        const base0 = path.parse(name).name
         crops = []
         groups.forEach((g, gi) => {
           const rep = rects[g.idxs[0]]
-          const cn = gi === 0 ? `${base0}.png` : `${base0}_alt${gi + 1}.png`
+          const cn = sanitizeSliceFileName(gi === 0 ? stem : `${stem}_alt${gi + 1}`)
           const twin = gi === 0 ? twin0 : regionTwin(rep)
           const entry = { name: cn, exists: !!resolveSliceFile(sliceDirs, cn, aliases), ...rep }
           if (g.idxs.length > 1) entry.alsoRects = g.idxs.slice(1).map((i) => rects[i])
           if (twin) { entry.exists = true; entry.reuseOf = twin.twin; entry.from = path.basename(twin.dir) }
           crops.push(entry)
-          if (!entry.exists) missing.push({ reason: 'slice-file-missing', name, crop: entry })
+          if (!entry.exists) missing.push({ reason: 'slice-file-missing', name, originalName, crop: entry })
         })
         if (twin0) { verdict = 'content-twin-partial'; reuseOf = twin0.twin }
       }
@@ -299,11 +376,10 @@ function main() {
         // 历史事故②（2026-09-18 ynet-card）：旧实现只跟 rects[0] 比指纹、每矩形一个 _altN，
         // 内容相同的 5 个矩形裁出 5 份字节级重复副本；且不做既有切图判重，共用图标已重命名
         // 落地仍被重裁。现按指纹分组 + 像素级复用根治。
-        const baseN = path.parse(name).name
         crops = []
         for (let gi = 1; gi < groups.length; gi++) {
           const rep = rects[groups[gi].idxs[0]]
-          const cn = `${baseN}_alt${gi + 1}.png`
+          const cn = sanitizeSliceFileName(`${stem}_alt${gi + 1}`)
           const entry = { name: cn, exists: !!resolveSliceFile(sliceDirs, cn, aliases), ...rep }
           if (groups[gi].idxs.length > 1) entry.alsoRects = groups[gi].idxs.slice(1).map((i) => rects[i])
           if (!entry.exists) {
@@ -311,13 +387,19 @@ function main() {
             if (twin) { entry.exists = true; entry.reuseOf = twin.twin; entry.from = path.basename(twin.dir) }
           }
           crops.push(entry)
-          if (!entry.exists) missing.push({ reason: 'reused-slice-content-differs', name, crop: entry })
+          if (!entry.exists) missing.push({ reason: 'reused-slice-content-differs', name, originalName, crop: entry })
         }
       }
     }
     slices.push({
       name,
+      // ref = 设计稿图层完整引用；引用名与设计稿图层名不一致时模型才查得回去
+      ref,
+      ...(name !== originalName ? { originalName } : {}),
       exists,
+      // 解析到的实际文件路径：crop_slices --from-audit 据此把「审计判定存在」的资产
+      // 按消毒名搬进工程 src/slices/（否则模型拿着正确名字仍然 404 —— 图片空白零报错）。
+      file: file ? relOrAbs(file) : null,
       from: file ? path.basename(path.dirname(file)) : null,
       reuseOf,
       rects,
@@ -532,18 +614,48 @@ function main() {
     bindHints,
     listCandidates,
   }
-  if (args.save) {
+  // 默认落盘：审计是「整份复用」的产物（crop_slices --from-audit 直接吃），
+  // 靠模型每次记得加 --save 是不可靠的；不给路径就落到工程根 .cache/spec-audit/ 下。
+  // 默认路径要在工程根下（cwd 即工程根），别按脚本位置推。
+  const savePath = args.noSave ? '' : args.save || defaultAuditPath(args.spec, args.card)
+  if (savePath) {
     try {
-      fs.mkdirSync(path.dirname(path.resolve(args.save)), { recursive: true })
-      fs.writeFileSync(args.save, JSON.stringify(brief, null, 2) + '\n')
-      brief.savedTo = args.save
-      console.error(`[spec_audit] 审计已落盘 ${args.save}（crop_slices --from-audit 直接用它，禁止手抄摘要）`)
+      fs.mkdirSync(path.dirname(path.resolve(savePath)), { recursive: true })
+      fs.writeFileSync(savePath, JSON.stringify(brief, null, 2) + '\n')
+      brief.savedTo = savePath
+      console.error(`[spec_audit] 审计已落盘 ${savePath}（crop_slices --from-audit 直接用它，禁止手抄摘要）`)
     } catch (e) {
-      console.error(`[spec_audit] --save 失败：${e.message}`)
+      console.error(`[spec_audit] 落盘失败：${e.message}`)
     }
   }
   // 紧凑输出：审计简报的读者是模型，缩进纯浪费 token（也更容易整份进 12000 字回喂窗口）
-  console.log(JSON.stringify(brief))
+  const compact = JSON.stringify(brief)
+  if (compact.length <= STDOUT_MAX_CHARS) {
+    console.log(compact)
+  } else {
+    // 超长时改出摘要：**每一个顶层键都在、可决策的信息一个不少**，只把「按位置复述内容」的
+    // bands[].items（它是 texts/slices 的重排，纯冗余）折成计数，完整版指向 savedTo。
+    // 为什么不做「截断 stdout」：截断会把 slices/missing 这类靠后的关键字段整段切掉，
+    // 模型既不知道少了什么、又会为了补读再跑一遍 40s 的解析。
+    const digest = {
+      ...brief,
+      bands: (brief.bands || []).map((b) => ({ y: b.y, h: b.h, itemCount: (b.items || []).length })),
+      stdoutDigest: true,
+      note: `stdout 已折成摘要（完整审计 ${compact.length} 字在 ${brief.savedTo || '（本次未落盘）'}）：bands[].items 只是 texts/slices 的位置重排，需要时用 fs_read 读 savedTo；crop_slices --from-audit 一律用 savedTo，禁止手抄。`,
+    }
+    console.log(JSON.stringify(digest))
+  }
+}
+
+/** stdout 预算：审计简报要喂给模型，超过这个长度就折摘要（完整版落盘） */
+const STDOUT_MAX_CHARS = 9000
+
+/** 默认落盘路径：工程根 .cache/spec-audit/<要素包目录名>-card<N>.json（cwd 即工程根）。
+ *  用目录名而不是文件名：所有要素包里的文件都叫 spec.json，只取 basename 会互相覆盖。 */
+function defaultAuditPath(spec, card) {
+  const dir = path.basename(path.dirname(path.resolve(String(spec))))
+  const base = dir || path.basename(String(spec)).replace(/\.json$/i, '') || 'spec'
+  return path.join('.cache', 'spec-audit', `${base}-card${card}.json`)
 }
 
 main()