cardbuddy 0.13.3 → 0.14.1

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

@@ -1,328 +1,388 @@
-/**
- * design_sample.mjs — 从设计稿聚焦图（card-N.png）采样顶部色带。
- *
- * 用途：弥散背景/浅色顶带没有切片素材时，按「缺素材用纯色」约束，
- * 从设计稿截图采样带高与纯色近似值（不裁切图片，只取颜色）。
- *
- * 算法（纯几何 + 统计，无任何业务/样本硬编码）：
- *   1. 取中央竖条（30%-70% 宽）避开圆角与侧边装饰；
- *   2. 每行取中位色（对文字等前景像素稳健）；
- *   3. 卡体基色 = 底部 8% 行中位色的中位数；
- *   4. 从顶部扫描：行色与基色平均通道差 > 6 视为色带行，
- *      允许开头 ≤8 CSS px 的基色行（圆角行），允许 1 行例外（抗锯齿）；
- *   5. 带高 ≥10 且 ≤60% 卡高才采纳。
- */
-import fs from 'node:fs'
-import { PNG } from 'pngjs'
-
-function median(nums) {
-  if (!nums.length) return 0
-  const sorted = [...nums].sort((a, b) => a - b)
-  return sorted[Math.floor(sorted.length / 2)]
-}
-
-function toHex(r, g, b) {
-  const c = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0').toUpperCase()
-  return `#${c(r)}${c(g)}${c(b)}`
-}
-
-/**
- * @param {string} designPath 设计稿聚焦图路径
- * @param {number} cardWidth 卡片宽（CSS px）
- * @param {number} cardHeight 卡片高（CSS px）
- * @returns {{ height: number, color: string } | null}
- */
-export function sampleTopBand(designPath, cardWidth, cardHeight) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    const x0 = Math.floor(w * 0.3)
-    const x1 = Math.max(x0 + 2, Math.ceil(w * 0.7))
-
-    const rowMedian = (y) => {
-      const rs = [], gs = [], bs = []
-      for (let x = x0; x < x1; x += 2) {
-        const i = (y * w + x) * 4
-        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
-      }
-      return [median(rs), median(gs), median(bs)]
-    }
-
-    // 卡体基色：底部 8% 的行
-    const bodyRows = []
-    for (let y = Math.floor(h * 0.92); y < h; y++) bodyRows.push(rowMedian(y))
-    const body = [0, 1, 2].map((i) => median(bodyRows.map((c) => c[i])))
-    const dist = (a, b) => (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3
-
-    const maxLeadRows = Math.round(8 * scale) // 圆角保护
-    const bandColors = []
-    let bandEndRow = -1
-    let started = false
-    let exceptions = 0
-    for (let y = 0; y < h; y++) {
-      const c = rowMedian(y)
-      if (dist(c, body) > 6) {
-        started = true
-        bandColors.push(c)
-        bandEndRow = y
-        exceptions = 0
-      } else {
-        if (!started) {
-          if (y > maxLeadRows) return null // 顶部 8px 内没有出现色带 → 无顶带
-          continue
-        }
-        exceptions += 1
-        if (exceptions > 1) break // 容忍 1 行例外（分隔线/抗锯齿）
-      }
-    }
-    if (!started || bandEndRow < 0) return null
-    const heightCss = (bandEndRow + 1) / scale
-    // 上限 80%：整卡同色时底行=带色根本检不出带，能检出的高带（如顶面板+异色底栏）是合法形态
-    if (heightCss < 10 || heightCss > cardHeight * 0.8) return null
-    const color = toHex(
-      median(bandColors.map((c) => c[0])),
-      median(bandColors.map((c) => c[1])),
-      median(bandColors.map((c) => c[2])),
-    )
-    return { height: Math.round(heightCss), color }
-  } catch {
-    return null
-  }
-}
-
-/**
- * 采样设计稿聚焦图中某个卡内区域的主色（区域中央 50% 的中位色，对内部文字稳健）。
- * 用途：无导出素材的大切片（如烘焙按钮图）用纯色块近似（constraint：缺素材用纯色）。
- * @param {string} designPath
- * @param {number} cardWidth CSS px
- * @param {{x:number,y:number,width:number,height:number}} region 卡内相对坐标
- * @returns {string|null} hex 颜色
- */
-export function sampleRegionColor(designPath, cardWidth, region) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    const x0 = Math.max(0, Math.round((region.x + region.width * 0.25) * scale))
-    const x1 = Math.min(w, Math.round((region.x + region.width * 0.75) * scale))
-    const y0 = Math.max(0, Math.round((region.y + region.height * 0.25) * scale))
-    const y1 = Math.min(h, Math.round((region.y + region.height * 0.75) * scale))
-    if (x1 - x0 < 2 || y1 - y0 < 2) return null
-    const rs = [], gs = [], bs = []
-    for (let y = y0; y < y1; y += 2) {
-      for (let x = x0; x < x1; x += 2) {
-        const i = (y * w + x) * 4
-        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
-      }
-    }
-    return toHex(median(rs), median(gs), median(bs))
-  } catch {
-    return null
-  }
-}
-
-/**
- * 采样区域边缘条带主色（左右两条竖带的中位色，避开中央文字）。
- * 用途：按钮/pill 的标注填充色与设计稿像素交叉验证——中央采样会被按钮文字污染，
- * 边缘条带（圆角半径之外的纯背景区）才是填充色真值。
- * @param {string} designPath
- * @param {number} cardWidth CSS px
- * @param {{x:number,y:number,width:number,height:number}} region 卡内相对坐标
- * @returns {string|null} hex 颜色
- */
-export function sampleRegionEdgeColor(designPath, cardWidth, region) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    // 条带内缩：横向 8%-22% / 78%-92%（避开圆角与中央文字），纵向 30%-70%
-    const y0 = Math.max(0, Math.round((region.y + region.height * 0.3) * scale))
-    const y1 = Math.min(h, Math.round((region.y + region.height * 0.7) * scale))
-    const strips = [
-      [Math.round((region.x + region.width * 0.08) * scale), Math.round((region.x + region.width * 0.22) * scale)],
-      [Math.round((region.x + region.width * 0.78) * scale), Math.round((region.x + region.width * 0.92) * scale)],
-    ]
-    const rs = [], gs = [], bs = []
-    for (const [sx0, sx1] of strips) {
-      const x0 = Math.max(0, sx0), x1 = Math.min(w, sx1)
-      if (x1 - x0 < 2 || y1 - y0 < 2) continue
-      for (let y = y0; y < y1; y += 2) {
-        for (let x = x0; x < x1; x += 2) {
-          const i = (y * w + x) * 4
-          rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
-        }
-      }
-    }
-    if (!rs.length) return null
-    return toHex(median(rs), median(gs), median(bs))
-  } catch {
-    return null
-  }
-}
-
-/**
- * 采样卡体主色（设计稿聚焦图中央竖条底部 8% 行的中位色）。
- * 用于校验/纠正 spec cardFill 与设计稿明显不一致的情况（视觉优先）。
- * @returns {string|null} hex
- */
-export function sampleCardBodyColor(designPath, cardWidth) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    const x0 = Math.floor(w * 0.3)
-    const x1 = Math.max(x0 + 2, Math.ceil(w * 0.7))
-    const rs = [], gs = [], bs = []
-    for (let y = Math.floor(h * 0.94); y < h; y++) {
-      for (let x = x0; x < x1; x += 2) {
-        const i = (y * w + x) * 4
-        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
-      }
-    }
-    return toHex(median(rs), median(gs), median(bs))
-  } catch {
-    return null
-  }
-}
-
-/**
- * 文本颜色交叉校验（标注缺陷治理，视觉优先）：
- * 标注 textStyle.color 与设计稿实际字形颜色明显不一致时（如设计是蓝灰字、标注写深色），
- * 从设计稿聚焦图采样字形真实颜色覆盖标注。
- *
- * 算法（纯几何 + 统计，无业务词）：
- *   1. 文本所在小壳（按钮/pill）bbox 内缩 15% 取中央区（避开圆角/壳边抗锯齿）；
- *   2. 全区中位色 ≈ 壳底色（文字稀疏）；
- *   3. 与底色距离 >40 的像素视为字形；取其中亮度最低 25%（抗锯齿核心）的中位色；
- *   4. 采样色与标注色平均通道差 >28 才覆盖（小差不折腾，保留标注）。
- *
- * @param {string} designPath 设计稿聚焦图路径（card-N.png）
- * @param {number} cardWidth 卡片宽（CSS px）
- * @param {{x:number,y:number,width:number,height:number}} bboxCardRel 壳 bbox（卡内相对坐标）
- * @param {string} specColorHex 标注颜色（#RRGGBB）
- * @returns {string|null} 需覆盖时返回采样色 #RRGGBB，否则 null
- */
-export function crossCheckTextColor(designPath, cardWidth, bboxCardRel, specColorHex) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    const bx = (bboxCardRel.x || 0) * scale
-    const by = (bboxCardRel.y || 0) * scale
-    const bw = (bboxCardRel.width || 0) * scale
-    const bh = (bboxCardRel.height || 0) * scale
-    if (bw < 8 || bh < 6) return null
-    const x0 = Math.max(0, Math.round(bx + bw * 0.15))
-    const x1 = Math.min(w - 1, Math.round(bx + bw * 0.85))
-    const y0 = Math.max(0, Math.round(by + bh * 0.15))
-    const y1 = Math.min(h - 1, Math.round(by + bh * 0.85))
-    if (x1 - x0 < 4 || y1 - y0 < 4) return null
-    const rs = [], gs = [], bs = []
-    for (let y = y0; y <= y1; y++) {
-      for (let x = x0; x <= x1; x++) {
-        const i = (y * w + x) * 4
-        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
-      }
-    }
-    const bg = [median(rs), median(gs), median(bs)]
-    const dist = (r, g, b, t) => (Math.abs(r - t[0]) + Math.abs(g - t[1]) + Math.abs(b - t[2])) / 3
-    const glyphs = []
-    for (let k = 0; k < rs.length; k++) {
-      if (dist(rs[k], gs[k], bs[k], bg) > 40) {
-        glyphs.push([rs[k], gs[k], bs[k], rs[k] * 0.299 + gs[k] * 0.587 + bs[k] * 0.114])
-      }
-    }
-    if (glyphs.length < 30) return null
-    glyphs.sort((a, b) => a[3] - b[3])
-    const core = glyphs.slice(0, Math.max(10, Math.floor(glyphs.length * 0.25)))
-    const sampled = [
-      median(core.map((c) => c[0])),
-      median(core.map((c) => c[1])),
-      median(core.map((c) => c[2])),
-    ]
-    const m = String(specColorHex || '').replace('#', '')
-    if (!/^[0-9a-fA-F]{6}$/.test(m)) return toHex(...sampled)
-    const spec = [parseInt(m.slice(0, 2), 16), parseInt(m.slice(2, 4), 16), parseInt(m.slice(4, 6), 16)]
-    if (dist(sampled[0], sampled[1], sampled[2], spec) > 28) return toHex(...sampled)
-    return null
-  } catch {
-    return null
-  }
-}
-
-/**
- * 描边环采样（标注缺陷治理，视觉优先）：
- * 壳标注无 fill 无 border（"隐形"壳），但设计稿可见描边时（如线框 pill 按钮），
- * 从设计稿采样壳边缘环带颜色，判定是否存在描边并取其颜色。
- *
- * 算法（纯几何 + 统计）：
- *   1. 壳 bbox 四边各取中段 30%-70%（避开圆角）；
- *   2. 环带 = bbox 边缘向内 max(1, round(1.6×scale)) px 的窄带；
- *   3. 内部参照色 = 中央 30% 区域中位色；
- *   4. 环带亮度最低 40% 像素的中位色与内部参照色距离 >18 → 存在描边，返回其颜色。
- *
- * @param {string} designPath 设计稿聚焦图路径
- * @param {number} cardWidth 卡片宽（CSS px）
- * @param {{x:number,y:number,width:number,height:number}} bboxCardRel 壳 bbox（卡内相对坐标）
- * @returns {string|null} 描边色 #RRGGBB；无描边/采样失败返回 null
- */
-export function sampleOutlineRing(designPath, cardWidth, bboxCardRel) {
-  try {
-    if (!designPath || !fs.existsSync(designPath)) return null
-    const png = PNG.sync.read(fs.readFileSync(designPath))
-    const scale = png.width / Math.max(1, cardWidth)
-    if (!(scale > 0.5 && scale < 5)) return null
-    const { width: w, height: h, data } = png
-    const bx = Math.round((bboxCardRel.x || 0) * scale)
-    const by = Math.round((bboxCardRel.y || 0) * scale)
-    const bw = Math.round((bboxCardRel.width || 0) * scale)
-    const bh = Math.round((bboxCardRel.height || 0) * scale)
-    if (bw < 10 || bh < 8) return null
-    const t = Math.max(1, Math.round(1.6 * scale))
-    const at = (x, y) => {
-      const i = (Math.min(h - 1, Math.max(0, y)) * w + Math.min(w - 1, Math.max(0, x))) * 4
-      return [data[i], data[i + 1], data[i + 2]]
-    }
-    const ring = []
-    const push = (x, y) => { const c = at(x, y); ring.push([c[0], c[1], c[2], c[0] * 0.299 + c[1] * 0.587 + c[2] * 0.114]) }
-    for (let x = bx + Math.round(bw * 0.3); x <= bx + Math.round(bw * 0.7); x++) {
-      for (let k = 0; k < t; k++) { push(x, by + k); push(x, by + bh - 1 - k) }
-    }
-    for (let y = by + Math.round(bh * 0.3); y <= by + Math.round(bh * 0.7); y++) {
-      for (let k = 0; k < t; k++) { push(bx + k, y); push(bx + bw - 1 - k, y) }
-    }
-    if (ring.length < 20) return null
-    // 内部参照色（中央 30% 区域中位色）
-    const ir = [], ig = [], ib = []
-    for (let y = by + Math.round(bh * 0.35); y <= by + Math.round(bh * 0.65); y += 2) {
-      for (let x = bx + Math.round(bw * 0.35); x <= bx + Math.round(bw * 0.65); x += 2) {
-        const c = at(x, y); ir.push(c[0]); ig.push(c[1]); ib.push(c[2])
-      }
-    }
-    const interior = [median(ir), median(ig), median(ib)]
-    ring.sort((a, b) => a[3] - b[3])
-    const core = ring.slice(0, Math.max(8, Math.floor(ring.length * 0.4)))
-    const ringColor = [
-      median(core.map((c) => c[0])),
-      median(core.map((c) => c[1])),
-      median(core.map((c) => c[2])),
-    ]
-    const dist = (Math.abs(ringColor[0] - interior[0])
-      + Math.abs(ringColor[1] - interior[1])
-      + Math.abs(ringColor[2] - interior[2])) / 3
-    return dist > 18 ? toHex(...ringColor) : null
-  } catch {
-    return null
-  }
-}
+/**
+ * design_sample.mjs — 从设计稿聚焦图（card-N.png）采样顶部色带。
+ *
+ * 用途：弥散背景/浅色顶带没有切片素材时，按「缺素材用纯色」约束，
+ * 从设计稿截图采样带高与纯色近似值（不裁切图片，只取颜色）。
+ *
+ * 算法（纯几何 + 统计，无任何业务/样本硬编码）：
+ *   1. 取中央竖条（30%-70% 宽）避开圆角与侧边装饰；
+ *   2. 每行取中位色（对文字等前景像素稳健）；
+ *   3. 卡体基色 = 底部 8% 行中位色的中位数；
+ *   4. 从顶部扫描：行色与基色平均通道差 > 6 视为色带行，
+ *      允许开头 ≤8 CSS px 的基色行（圆角行），允许 1 行例外（抗锯齿）；
+ *   5. 带高 ≥10 且 ≤60% 卡高才采纳。
+ */
+import fs from 'node:fs'
+import { PNG } from 'pngjs'
+
+function median(nums) {
+  if (!nums.length) return 0
+  const sorted = [...nums].sort((a, b) => a - b)
+  return sorted[Math.floor(sorted.length / 2)]
+}
+
+function toHex(r, g, b) {
+  const c = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0').toUpperCase()
+  return `#${c(r)}${c(g)}${c(b)}`
+}
+
+/**
+ * @param {string} designPath 设计稿聚焦图路径
+ * @param {number} cardWidth 卡片宽（CSS px）
+ * @param {number} cardHeight 卡片高（CSS px）
+ * @returns {{ height: number, color: string } | null}
+ */
+export function sampleTopBand(designPath, cardWidth, cardHeight) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    const x0 = Math.floor(w * 0.3)
+    const x1 = Math.max(x0 + 2, Math.ceil(w * 0.7))
+
+    const rowMedian = (y) => {
+      const rs = [], gs = [], bs = []
+      for (let x = x0; x < x1; x += 2) {
+        const i = (y * w + x) * 4
+        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
+      }
+      return [median(rs), median(gs), median(bs)]
+    }
+
+    // 卡体基色：底部 8% 的行
+    const bodyRows = []
+    for (let y = Math.floor(h * 0.92); y < h; y++) bodyRows.push(rowMedian(y))
+    const body = [0, 1, 2].map((i) => median(bodyRows.map((c) => c[i])))
+    const dist = (a, b) => (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3
+
+    const maxLeadRows = Math.round(8 * scale) // 圆角保护
+    const bandColors = []
+    let bandEndRow = -1
+    let started = false
+    let exceptions = 0
+    for (let y = 0; y < h; y++) {
+      const c = rowMedian(y)
+      if (dist(c, body) > 6) {
+        started = true
+        bandColors.push(c)
+        bandEndRow = y
+        exceptions = 0
+      } else {
+        if (!started) {
+          if (y > maxLeadRows) return null // 顶部 8px 内没有出现色带 → 无顶带
+          continue
+        }
+        exceptions += 1
+        if (exceptions > 1) break // 容忍 1 行例外（分隔线/抗锯齿）
+      }
+    }
+    if (!started || bandEndRow < 0) return null
+    const heightCss = (bandEndRow + 1) / scale
+    // 上限 80%：整卡同色时底行=带色根本检不出带，能检出的高带（如顶面板+异色底栏）是合法形态
+    if (heightCss < 10 || heightCss > cardHeight * 0.8) return null
+    const color = toHex(
+      median(bandColors.map((c) => c[0])),
+      median(bandColors.map((c) => c[1])),
+      median(bandColors.map((c) => c[2])),
+    )
+    return { height: Math.round(heightCss), color }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 采样设计稿聚焦图中某个卡内区域的主色（区域中央 50% 的中位色，对内部文字稳健）。
+ * 用途：无导出素材的大切片（如烘焙按钮图）用纯色块近似（constraint：缺素材用纯色）。
+ * @param {string} designPath
+ * @param {number} cardWidth CSS px
+ * @param {{x:number,y:number,width:number,height:number}} region 卡内相对坐标
+ * @returns {string|null} hex 颜色
+ */
+export function sampleRegionColor(designPath, cardWidth, region) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    const x0 = Math.max(0, Math.round((region.x + region.width * 0.25) * scale))
+    const x1 = Math.min(w, Math.round((region.x + region.width * 0.75) * scale))
+    const y0 = Math.max(0, Math.round((region.y + region.height * 0.25) * scale))
+    const y1 = Math.min(h, Math.round((region.y + region.height * 0.75) * scale))
+    if (x1 - x0 < 2 || y1 - y0 < 2) return null
+    const rs = [], gs = [], bs = []
+    for (let y = y0; y < y1; y += 2) {
+      for (let x = x0; x < x1; x += 2) {
+        const i = (y * w + x) * 4
+        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
+      }
+    }
+    return toHex(median(rs), median(gs), median(bs))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 采样区域边缘条带主色（左右两条竖带的中位色，避开中央文字）。
+ * 用途：按钮/pill 的标注填充色与设计稿像素交叉验证——中央采样会被按钮文字污染，
+ * 边缘条带（圆角半径之外的纯背景区）才是填充色真值。
+ * @param {string} designPath
+ * @param {number} cardWidth CSS px
+ * @param {{x:number,y:number,width:number,height:number}} region 卡内相对坐标
+ * @returns {string|null} hex 颜色
+ */
+export function sampleRegionEdgeColor(designPath, cardWidth, region) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    // 条带内缩：横向 8%-22% / 78%-92%（避开圆角与中央文字），纵向 30%-70%
+    const y0 = Math.max(0, Math.round((region.y + region.height * 0.3) * scale))
+    const y1 = Math.min(h, Math.round((region.y + region.height * 0.7) * scale))
+    const strips = [
+      [Math.round((region.x + region.width * 0.08) * scale), Math.round((region.x + region.width * 0.22) * scale)],
+      [Math.round((region.x + region.width * 0.78) * scale), Math.round((region.x + region.width * 0.92) * scale)],
+    ]
+    const rs = [], gs = [], bs = []
+    for (const [sx0, sx1] of strips) {
+      const x0 = Math.max(0, sx0), x1 = Math.min(w, sx1)
+      if (x1 - x0 < 2 || y1 - y0 < 2) continue
+      for (let y = y0; y < y1; y += 2) {
+        for (let x = x0; x < x1; x += 2) {
+          const i = (y * w + x) * 4
+          rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
+        }
+      }
+    }
+    if (!rs.length) return null
+    return toHex(median(rs), median(gs), median(bs))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 采样卡体主色（设计稿聚焦图中央竖条底部 8% 行的中位色）。
+ * 用于校验/纠正 spec cardFill 与设计稿明显不一致的情况（视觉优先）。
+ * @returns {string|null} hex
+ */
+export function sampleCardBodyColor(designPath, cardWidth) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    // 采样卡体左右margin条带（各 ~3% 宽、全高）：内缩壳/列表行背景永远盖不到margin，
+    // 此前采底部 6% 中条会把「最后一行彩色壳」误当卡底色（整卡被染成行壳色）。
+    const edge = Math.max(2, Math.floor(w * 0.03))
+    const buckets = new Map()
+    const pick = (x, y) => {
+      const i = (y * w + x) * 4
+      const key = `${data[i] >> 4},${data[i + 1] >> 4},${data[i + 2] >> 4}`
+      const slot = buckets.get(key) || (buckets.set(key, { n: 0, rs: [], gs: [], bs: [] }), buckets.get(key))
+      slot.n += 1
+      slot.rs.push(data[i]); slot.gs.push(data[i + 1]); slot.bs.push(data[i + 2])
+    }
+    for (let y = 0; y < h; y += 2) {
+      for (let x = 0; x < edge; x += 1) pick(x, y)
+      for (let x = Math.max(0, w - edge); x < w; x += 1) pick(x, y)
+    }
+    if (!buckets.size) return null
+    const top = [...buckets.values()].sort((a, b) => b.n - a.n)[0]
+    return toHex(median(top.rs), median(top.gs), median(top.bs))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 文本颜色交叉校验（标注缺陷治理，视觉优先）：
+ * 标注 textStyle.color 与设计稿实际字形颜色明显不一致时（如设计是蓝灰字、标注写深色），
+ * 从设计稿聚焦图采样字形真实颜色覆盖标注。
+ *
+ * 算法（纯几何 + 统计，无业务词）：
+ *   1. 文本所在小壳（按钮/pill）bbox 内缩 15% 取中央区（避开圆角/壳边抗锯齿）；
+ *   2. 全区中位色 ≈ 壳底色（文字稀疏）；
+ *   3. 与底色距离 >40 的像素视为字形；取其中亮度最低 25%（抗锯齿核心）的中位色；
+ *   4. 采样色与标注色平均通道差 >28 才覆盖（小差不折腾，保留标注）。
+ *
+ * @param {string} designPath 设计稿聚焦图路径（card-N.png）
+ * @param {number} cardWidth 卡片宽（CSS px）
+ * @param {{x:number,y:number,width:number,height:number}} bboxCardRel 壳 bbox（卡内相对坐标）
+ * @param {string} specColorHex 标注颜色（#RRGGBB）
+ * @returns {string|null} 需覆盖时返回采样色 #RRGGBB，否则 null
+ */
+export function crossCheckTextColor(designPath, cardWidth, bboxCardRel, specColorHex) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    const bx = (bboxCardRel.x || 0) * scale
+    const by = (bboxCardRel.y || 0) * scale
+    const bw = (bboxCardRel.width || 0) * scale
+    const bh = (bboxCardRel.height || 0) * scale
+    if (bw < 8 || bh < 6) return null
+    const x0 = Math.max(0, Math.round(bx + bw * 0.15))
+    const x1 = Math.min(w - 1, Math.round(bx + bw * 0.85))
+    const y0 = Math.max(0, Math.round(by + bh * 0.15))
+    const y1 = Math.min(h - 1, Math.round(by + bh * 0.85))
+    if (x1 - x0 < 4 || y1 - y0 < 4) return null
+    const rs = [], gs = [], bs = []
+    for (let y = y0; y <= y1; y++) {
+      for (let x = x0; x <= x1; x++) {
+        const i = (y * w + x) * 4
+        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
+      }
+    }
+    const bg = [median(rs), median(gs), median(bs)]
+    const dist = (r, g, b, t) => (Math.abs(r - t[0]) + Math.abs(g - t[1]) + Math.abs(b - t[2])) / 3
+    const glyphs = []
+    for (let k = 0; k < rs.length; k++) {
+      if (dist(rs[k], gs[k], bs[k], bg) > 40) {
+        glyphs.push([rs[k], gs[k], bs[k], rs[k] * 0.299 + gs[k] * 0.587 + bs[k] * 0.114])
+      }
+    }
+    if (glyphs.length < 30) return null
+    glyphs.sort((a, b) => a[3] - b[3])
+    const core = glyphs.slice(0, Math.max(10, Math.floor(glyphs.length * 0.25)))
+    const sampled = [
+      median(core.map((c) => c[0])),
+      median(core.map((c) => c[1])),
+      median(core.map((c) => c[2])),
+    ]
+    const m = String(specColorHex || '').replace('#', '')
+    if (!/^[0-9a-fA-F]{6}$/.test(m)) return toHex(...sampled)
+    const spec = [parseInt(m.slice(0, 2), 16), parseInt(m.slice(2, 4), 16), parseInt(m.slice(4, 6), 16)]
+    if (dist(sampled[0], sampled[1], sampled[2], spec) > 28) return toHex(...sampled)
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 描边环采样（标注缺陷治理，视觉优先）：
+ * 壳标注无 fill 无 border（"隐形"壳），但设计稿可见描边时（如线框 pill 按钮），
+ * 从设计稿采样壳边缘环带颜色，判定是否存在描边并取其颜色。
+ *
+ * 算法（纯几何 + 统计）：
+ *   1. 壳 bbox 四边各取中段 30%-70%（避开圆角）；
+ *   2. 环带 = bbox 边缘向内 max(1, round(1.6×scale)) px 的窄带；
+ *   3. 内部参照色 = 中央 30% 区域中位色；
+ *   4. 环带亮度最低 40% 像素的中位色与内部参照色距离 >18 → 存在描边，返回其颜色。
+ *
+ * @param {string} designPath 设计稿聚焦图路径
+ * @param {number} cardWidth 卡片宽（CSS px）
+ * @param {{x:number,y:number,width:number,height:number}} bboxCardRel 壳 bbox（卡内相对坐标）
+ * @returns {string|null} 描边色 #RRGGBB；无描边/采样失败返回 null
+ */
+export function sampleOutlineRing(designPath, cardWidth, bboxCardRel) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    const bx = Math.round((bboxCardRel.x || 0) * scale)
+    const by = Math.round((bboxCardRel.y || 0) * scale)
+    const bw = Math.round((bboxCardRel.width || 0) * scale)
+    const bh = Math.round((bboxCardRel.height || 0) * scale)
+    if (bw < 10 || bh < 8) return null
+    const t = Math.max(1, Math.round(1.6 * scale))
+    const at = (x, y) => {
+      const i = (Math.min(h - 1, Math.max(0, y)) * w + Math.min(w - 1, Math.max(0, x))) * 4
+      return [data[i], data[i + 1], data[i + 2]]
+    }
+    const ring = []
+    const push = (x, y) => { const c = at(x, y); ring.push([c[0], c[1], c[2], c[0] * 0.299 + c[1] * 0.587 + c[2] * 0.114]) }
+    for (let x = bx + Math.round(bw * 0.3); x <= bx + Math.round(bw * 0.7); x++) {
+      for (let k = 0; k < t; k++) { push(x, by + k); push(x, by + bh - 1 - k) }
+    }
+    for (let y = by + Math.round(bh * 0.3); y <= by + Math.round(bh * 0.7); y++) {
+      for (let k = 0; k < t; k++) { push(bx + k, y); push(bx + bw - 1 - k, y) }
+    }
+    if (ring.length < 20) return null
+    // 内部参照色（中央 30% 区域中位色）
+    const ir = [], ig = [], ib = []
+    for (let y = by + Math.round(bh * 0.35); y <= by + Math.round(bh * 0.65); y += 2) {
+      for (let x = bx + Math.round(bw * 0.35); x <= bx + Math.round(bw * 0.65); x += 2) {
+        const c = at(x, y); ir.push(c[0]); ig.push(c[1]); ib.push(c[2])
+      }
+    }
+    const interior = [median(ir), median(ig), median(ib)]
+    ring.sort((a, b) => a[3] - b[3])
+    const core = ring.slice(0, Math.max(8, Math.floor(ring.length * 0.4)))
+    const ringColor = [
+      median(core.map((c) => c[0])),
+      median(core.map((c) => c[1])),
+      median(core.map((c) => c[2])),
+    ]
+    const dist = (Math.abs(ringColor[0] - interior[0])
+      + Math.abs(ringColor[1] - interior[1])
+      + Math.abs(ringColor[2] - interior[2])) / 3
+    return dist > 18 ? toHex(...ringColor) : null
+  } catch {
+    return null
+  }
+}
+
+
+/**
+ * 分区底色带采样：设计稿卡体「上灰下白」等 flat 分区底色，按左缘逐行取色分段。
+ * 仅采纳行内均匀（flat 填充）且高度 >=24 的带；渐变/弥散背景行色逐行变化 → 自动排除。
+ * @returns {{ y0: number, y1: number, color: string }[] | null} 卡坐标 px 带列表
+ */
+export function sampleBackdropBands(designPath, cardWidth) {
+  try {
+    if (!designPath || !fs.existsSync(designPath)) return null
+    const png = PNG.sync.read(fs.readFileSync(designPath))
+    const scale = png.width / Math.max(1, cardWidth)
+    if (!(scale > 0.5 && scale < 5)) return null
+    const { width: w, height: h, data } = png
+    const dist = (a, b) => (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3
+    const rowColor = (py) => {
+      const rs = [], gs = [], bs = []
+      for (const x of [1, 2, 3]) {
+        const i = (py * w + x) * 4
+        rs.push(data[i]); gs.push(data[i + 1]); bs.push(data[i + 2])
+      }
+      return [median(rs), median(gs), median(bs)]
+    }
+    const cardH = Math.round(h / scale)
+    const raw = []
+    let cur = null
+    for (let cy = 0; cy < cardH; cy++) {
+      const c = rowColor(Math.min(h - 1, Math.round((cy + 0.5) * scale)))
+      if (!cur || dist(cur.color, c) > 4) {
+        if (cur) raw.push(cur)
+        cur = { y0: cy, y1: cy + 1, color: c, rows: [c] }
+      } else {
+        cur.y1 = cy + 1
+        cur.rows.push(c)
+      }
+    }
+    if (cur) raw.push(cur)
+    const out = []
+    for (const b of raw) {
+      if (b.y1 - b.y0 < 24) continue
+      if (!b.rows.every((r) => dist(r, b.color) <= 4)) continue
+      const med = [0, 1, 2].map((ci) => median(b.rows.map((r) => r[ci])))
+      const hex = toHex(med[0], med[1], med[2])
+      const last = out[out.length - 1]
+      if (last && last.color === hex) last.y1 = b.y1
+      else out.push({ y0: b.y0, y1: b.y1, color: hex })
+    }
+    return out.length >= 2 ? out : null
+  } catch {
+    return null
+  }
+}