cardbuddy 0.14.3 → 0.16.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,74 @@ 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)
 
+  /**
+   * 聚合文本节点剔除（导出侧冗余层）。
+   *
+   * MeaXure 导出会在**同一行**同时给出「合并文案」与「拆分文案」。实测 2026-09-24 收支分析卡：
+   *   `总收入(元)` (x32 w70) 与 `总收入` (x32 w45) + `(元)` (x77 w25) 同行并存；
+   *   `转账-张扬 (银行号转账)` (x32 w148) 与 `转账-张扬` (x32 w75) + `(银行号转账)` (x107 w74) 同行并存。
+   * 对设计稿做像素采样可证可见真值是**拆分节点**（主文案 #111111 + 后缀 #999999 两色），
+   * 合并节点的 textStyle 只有一种颜色 ⇒ 它是导出侧的聚合层，画不出来。
+   *
+   * 不剔除的代价：① texts 真值集虚高（该卡 29 条 vs 视觉 20 条），bindHints 与 listCandidates
+   * 一并被污染；② 模型若挑中合并节点，会把灰色后缀渲染成主色（颜色偏差）。
+   *
+   * 判据只用几何 + 文本，不含任何业务词：同行（|Δy| ≤ 2）且 x 区间被包含的 ≥2 条文本，
+   * 按 x 排序拼接后与本体的非空白内容相同 ⇒ 本体是聚合层。
+   */
+  const redundantTexts = []
+  const normText = (s) => String(s || '').replace(/\s+/g, '')
+  const keptTexts = texts.filter((t, i) => {
+    const parts = texts.filter(
+      (o, j) => j !== i && Math.abs(o.y - t.y) <= 2 && o.x >= t.x - 1 && o.x + o.w <= t.x + t.w + 1,
+    )
+    if (parts.length < 2) return true
+    const joined = parts.slice().sort((a, b) => a.x - b.x).map((p) => p.text).join('')
+    if (normText(joined) !== normText(t.text)) return true
+    redundantTexts.push({
+      text: t.text,
+      rect: { x: t.x, y: t.y, w: t.w, h: t.h },
+      parts: parts.map((p) => p.text),
+    })
+    return false
+  })
+  texts.length = 0
+  texts.push(...keptTexts)
+
   // 切图清单：存在性 / 复用 / 烘焙内容 / 复用但内容不同
-  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 +351,8 @@ function main() {
     })
     return groups
   }
-  /** 设计稿矩形区域 ↔ 既有切图的像素级判重（sha 快路径 + 容差兜底，slice_pixels.mjs）。
+  /**
+ * 设计稿矩形区域 ↔ 既有切图的像素级判重（sha 快路径 + 容差兜底，slice_pixels.mjs）。
    *  覆盖「共用切图已语义重命名 / 在别的画板已派生过」——名字对不上也能认出来。 */
   const regionTwin = (rect) => {
     if (!design) return null
@@ -255,11 +363,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 +386,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 +410,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 +421,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,
@@ -347,11 +463,22 @@ function main() {
     } else bands.push({ y: it.y, h: it.h, items: [it] })
   }
   bands.sort((a, b) => a.y - b.y)
-  for (const b of bands) b.items.sort((a, c) => a.x - c.x)
+  // 带内排序必须与下面「网格行合并」用的口径**完全一致**（y 为主、x 为辅）。
+  // 2026-09-24 实测事故：这里原来只按 x 排，合并那里按 (y,x) 排 ⇒ 同构的三条交易行
+  // （每条自身两行：主文案+金额 / 账户+日期）签名被打乱成两种（t15|t12|t13|t12|t15 与
+  // t15|t13|t15|t12|t12），「同构连续行」的 run 检测只认出 2 条，真列表漏掉一行。
+  // 单行带（y 全同）下两种口径等价，改口径不会动已有单行判定。
+  for (const b of bands) b.items.sort((a, c) => a.y - c.y || a.x - c.x)
   const rowGaps = bands.slice(1).map((b, i) => b.y - (bands[i].y + bands[i].h))
 
-  const xs = items.map((i) => i.x)
-  const xes = items.map((i) => i.x + i.w)
+  // 左右内缩只看**内容**的外沿：整宽装饰（行底色矩形 / 通栏分割线）的 local x 恒为 0，
+  // 掺进来会让 padLeft / padRight 永远是 0。实测 2026-09-24 收支分析卡：三个交易行的底色
+  // 矩形 343×72 从 x=0 起，padLeft 报 0，而真实内容内缩是 16（文案 x=16）——
+  // 模型照 0 排版就直接贴边。整宽/近整宽（≥ W−4）的装饰单独屏蔽。
+  const insetItems = items.filter((i) => i.w < W - 4)
+  const padSource = insetItems.length ? insetItems : items
+  const xs = padSource.map((i) => i.x)
+  const xes = padSource.map((i) => i.x + i.w)
   const gaps = {
     padLeft: Math.min(...xs),
     padRight: W - Math.max(...xes),
@@ -388,7 +515,23 @@ function main() {
       const i = (Math.round(y * scale) * design.width + Math.round(4 * scale)) * 4
       return { hex: hex(design.data[i], design.data[i + 1], design.data[i + 2]), a: design.data[i + 3] }
     }
-    const fill = colors.length ? colors[3]?.hex || colors[0].hex : '#FFFFFF'
+    // 卡底色 = 角部 + 右缘 gutter 的众数（量化色距聚类取最大簇）。
+    // **绝不能用 center 采样点**：卡面正中常被图表/大图占据（实测雷达卡 center=#F8B46A 恰是
+    // 雷达图中心橙，被当成卡底色后 bgGradientHint 产出「白→橙 264px」毒提示，模型照涂整卡，
+    // 像素 match 直接掉 4pp）。center 点仍保留在 colors 里供人看，但不参与底色投票。
+    const fillVotes = colors.filter((c) => c.label !== 'center').map((c) => c.hex)
+    const fill = (() => {
+      if (!fillVotes.length) return '#FFFFFF'
+      // 贪心聚类：色距 <12 视为同簇（与渐变检测的 dist 阈值一致）
+      const clusters = []
+      for (const hexV of fillVotes) {
+        const hit = clusters.find((c) => dist(c.ref, hexV) < 12)
+        if (hit) hit.n++
+        else clusters.push({ ref: hexV, n: 1 })
+      }
+      clusters.sort((a, b) => b.n - a.n)
+      return clusters[0].ref
+    })()
     // 首个不透明且明显异于卡底色的采样点 = 渐变带起点
     let startY = -1
     let top = null
@@ -457,24 +600,43 @@ function main() {
   const bandSig = (items) => items.filter((i) => i.kind !== 'shape').map((i) => (i.kind === 'text' ? `t${i.fs ?? ''}` : i.kind)).join('|')
   const listCandidates = []
   const pushCandidate = (layout, rows, source) => {
-    const values = rows.map((r) => r.map((it) => (it.kind === 'text' ? it.text : it.name || '')))
+    // 值矩阵只保留内容项（text / slice）：shape 是行底色、分割线这类纯装饰，行与行之间数量不等
+    // （2026-09-24 实测：三条交易行的 items 数是 6/7/8，多出来的全是 shape）—— 掺进来会让
+    // 「列」与「字段」整体错位，模型照着错位的矩阵命名会得到一堆空列。
+    const contentRows = rows.map((r) => r.filter((it) => it.kind !== 'shape'))
+    if (!contentRows.length || !contentRows[0].length) return
+    const width = Math.max(...contentRows.map((r) => r.length))
+    const values = contentRows.map((r) => {
+      const v = r.map((it) => (it.kind === 'text' ? it.text : it.name || ''))
+      while (v.length < width) v.push('') // 同构行理论等长；不足者补空占位，避免列数不齐
+      return v
+    })
     // 每行值完全相同 = 装饰性重复（分割线 / 同款图标行），不是数据行，不值得绑数组
     if (values.every((v) => JSON.stringify(v) === JSON.stringify(values[0]))) return
+    // 以最全的一行作字段基准（同构行等长，取最长更稳）
+    const base = contentRows.reduce((a, b) => (b.length > a.length ? b : a), contentRows[0])
     listCandidates.push({
       layout,
       rows: source,
-      fields: rows[0].map((it, pos) => ({ pos, kind: it.kind, first: it.kind === 'text' ? it.text : it.name || '' })),
+      fields: base.map((it, pos) => ({ pos, kind: it.kind, first: it.kind === 'text' ? it.text : it.name || '' })),
       values,
     })
   }
   // 网格行合并：tile 内部（图标行 → 标题行 → 副标题行）的行距远小于 tile 之间的行距，
   // 按「小于中位行距 60%」把相邻 bands 粘成一行 tile；不合并的话列表候选会被拆成碎片行
+  //
+  // ⚠ 签名相同的相邻带**不粘**（2026-09-24 实测事故）：tile 的各层靠签名区分（图标行 / 标题 /
+  // 副标题），签名相同的两条带是**并列的兄弟行**，不是同一 tile 的上下层。收支分析卡的三个交易行
+  // 内容高度正好顶满 72px 行高 ⇒ 带与带的 gap 为 0 ⇒ 旧逻辑把它们粘成一条带，于是
+  // 「同构连续行」的 run 检测再也看不到它们，真列表漏报；同时残留的那条巨带又喂出了
+  // 一个假候选（space-between 两端标签被当成「同构 tile 行」）。
   const rowGapMed = rowGaps.length ? [...rowGaps].sort((a, b) => a - b)[Math.floor(rowGaps.length / 2)] : 0
   const merged = []
   for (const b of bands) {
     const last = merged[merged.length - 1]
     const gap = last ? b.y - (last.y + last.h) : Infinity
-    if (last && rowGapMed > 0 && gap >= 0 && gap < rowGapMed * 0.8) {
+    const sameSig = last && bandSig(b.items) === bandSig(last.items)
+    if (last && !sameSig && rowGapMed > 0 && gap >= 0 && gap < rowGapMed * 0.8) {
       last.items = [...last.items, ...b.items].sort((a, c) => a.y - c.y || a.x - c.x)
       last.h = Math.max(last.y + last.h, b.y + b.h) - last.y
     } else {
@@ -508,15 +670,32 @@ function main() {
       cur.push(its[i])
     }
     groups.push(cur)
-    if (groups.length >= 2 && groups.every((g) => g.length === groups[0].length && bandSig(g) === bandSig(groups[0]))) {
+    // 同构 tile 组判定 + 排除「space-between 两端标签」这个高频假阳性（2026-09-24 实测：
+    // 收支分析卡 band1 的「总收入(元)…」/「总支出(元)…」两端标签被当成一个 2 组同构行候选，
+    // 模型得先在正文里推翻它才敢按真结构写 IR，白烧一轮推理）。
+    // 区分点：真 tile 是**等距列**（tile 之间有间隔但不吞掉大半行）；两端标签是**一整条空档**。
+    // 故 2 组时要求列间空档不超过本带内容跨度的 40%；≥3 组不再额外限制（3 组及以上几乎不可能是两端标签）。
+    const span = its.reduce((m, i) => Math.max(m, i.x + i.w), 0) - its.reduce((m, i) => Math.min(m, i.x), Infinity)
+    const splitThreshold = Math.max(12, med * 2)
+    const wideSplit = gaps.some((g) => g > splitThreshold && span > 0 && g > span * 0.4)
+    if (
+      groups.length >= 2 &&
+      groups.every((g) => g.length === groups[0].length && bandSig(g) === bandSig(groups[0])) &&
+      (groups.length >= 3 || !wideSplit)
+    ) {
       pushCandidate('row', groups, [bi])
     }
   }
 
   const brief = {
+    ...(process.env.SPEC_AUDIT_DEBUG
+      ? { _debug: { merged: merged.map((m, i) => ({ i, y: m.y, h: m.h, sig: bandSig(m.items), n: m.items.length })) } }
+      : {}),
     card: { index: args.card, name: card.name || '', rect: { w: W, h: H }, fill: card.cardFill || null },
     design: design ? { path: args.design, scale: Number(scale.toFixed(3)) } : null,
     texts,
+    // 被剔除的导出侧聚合层（合并文案 + 其拆分件）。本行同内容只保留拆分件，模型不必再猜该用哪个。
+    redundantTexts: redundantTexts.length ? redundantTexts : undefined,
     shapes,
     bgLayers,
     slices,
@@ -531,19 +710,66 @@ function main() {
     missing,
     bindHints,
     listCandidates,
+    // 列表绑定的作用域写法，只在真有候选时出现（避免每份审计都塞一段与当前卡无关的说明）。
+    // 为什么必须在这里给：模型是在读 listCandidates 的这一刻决定「这是列表、要绑数组」的，
+    // 此刻它手边没有作用域契约，容易照直觉写 $item.<字段>（求值恒 undefined 且全链路静默）。
+    // 现在它写错也不会出事 —— expand_ir 在扩展开头会归一化别名（lib/scope_alias.mjs）。
+    // 这里给契约是为了让它一次写对、少一轮往返，而不是「提醒它别犯错」。
+    // 文案只讲契约，不涉及任何具体字段名 / 卡名。
+    ...(listCandidates.length
+      ? {
+          listBindingRule:
+            'listScope 插槽内 item 的字段已**逐个展开**到作用域，规范形三种：' +
+            '① `$<字段名>`（字段名由你对 fields[].first 的值语义化命名，禁 text1 / val2 这类占位名）；' +
+            '② `$$` = 整个 item 对象；③ `$_index` = 行索引。' +
+            '（写成 `$item.<字段>` / `$item` / `$item._index` 也不会出错：expand_ir 会在扩展开头自动归一化到上面三种规范形。作用域里本来就没有 `item` 这个键。）' +
+            'fields[] 一列一字段，values[] 的每一行与 fields[] 同序（shape 装饰项已剔除）。' +
+            '契约全文：skills/dsl-card-generator/references/expression_engine.md §3。',
+        }
+      : {}),
   }
-  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()