cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,56 @@
+/**
+ * design_image.mjs — 设计稿 card-N.png 归档到卡片目录。
+ *
+ * 约定：生成卡片时，把对应的 card-*.png 复制到卡片目录并重命名为
+ * <cardId>.png，使 schema.json / data.json / 设计稿参考图同目录存放。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const CARD_IMAGE_RE = /^card-\d+\.png$/i
+
+/**
+ * 判断文件是否为 card-N.png 设计稿聚焦图。
+ *
+ * @param {string} p 文件路径
+ * @returns {boolean}
+ */
+export function isCardDesignImage(p) {
+  return CARD_IMAGE_RE.test(path.basename(p || ''))
+}
+
+/**
+ * 把 card-*.png 设计稿复制到卡片目录并重命名为 <cardId>.png。
+ *
+ * 仅处理 card-N.png 命名的设计稿聚焦图；artboard.png 等其它图片不动。
+ * 源文件与目标为同一路径时跳过；复制失败不阻断主流程（返回 null）。
+ *
+ * @param {{ designPath?: string, outDir: string, cardId: string }} args
+ * @returns {string|null} 目标文件路径（未复制时返回 null）
+ */
+export function copyCardDesignImage({ designPath, outDir, cardId }) {
+  if (!designPath || !isCardDesignImage(designPath) || !outDir || !cardId) return null
+  const source = path.resolve(designPath)
+  if (!fs.existsSync(source) || !fs.statSync(source).isFile()) return null
+  const target = path.join(path.resolve(outDir), `${cardId}.png`)
+  if (source === target) return null
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.copyFileSync(source, target)
+    return target
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 定位画板目录中第 N 张卡的 card-N.png（N 从 1 开始）。
+ *
+ * @param {string} canvasDir 画板目录（如 UI/10贷款查询）
+ * @param {number} cardNumber 卡片序号（1-based）
+ * @returns {string|null} 存在则返回绝对路径，否则 null
+ */
+export function findCardDesignImage(canvasDir, cardNumber = 1) {
+  const p = path.join(canvasDir, `card-${cardNumber}.png`)
+  return fs.existsSync(p) ? p : null
+}

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

@@ -0,0 +1,328 @@
+/**
+ * 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
+  }
+}

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

@@ -0,0 +1,79 @@
+/**
+ * 布局 Token 表（消灭魔法值：gap/padding/radius/fontSize/color 一律引用此处）。
+ *
+ * 纪律（2026-08-17 L1 落地）：
+ * - v3 生成器（spec_to_schema_v3.mjs）禁止裸数字魔法值，
+ *   一律引用 TOKEN.<组>.<语义名>。
+ * - L2 几何推导优先：spec.rect 实测值 > TOKEN（兜底）> 历史魔法值（最后兜底）。
+ * - 语义命名按"用途"而非"数值"：GAP.base 表示组件内标准间距，不叫 GAP.eight。
+ * - 改值单点生效，三策略视觉统一。
+ */
+export const TOKEN = {
+  /** 间距（flex gap） */
+  GAP: {
+    tight: 4,     // 行内紧密元素（图标+文字、两段小字）
+    micro: 2,     // 最密（legacy 文字列）
+    none: 0,      // 无间距
+    base: 8,      // 组件内标准间距（默认 Row/Column）
+    loose: 12,    // 大区块内子区块间距
+    section: 16,  // 段落/分组间距
+    huge: 24,     // 大区块间距
+  },
+  /** 内边距（padding） */
+  PADDING: {
+    card: 16,     // 卡片整体内边距
+    section: 12,  // 区块内边距
+    item: 12,     // 列表项内边距
+    compact: 8,   // 紧凑内边距（v3 标签行/操作行）
+    mini: 4,      // 最小内边距
+    micro: 2,      // 极小内边距（列表行等紧凑场景兜底）
+    buttonH: 12,  // 按钮垂直内边距
+    buttonW: 24,  // 按钮水平内边距
+    root: 0,      // Root 内边距（默认 0，宽度由 view.width 承载）
+  },
+  /** 圆角（borderRadius） */
+  RADIUS: {
+    root: 8,      // Root 圆角
+    card: 12,     // 卡片圆角
+    item: 8,      // 列表项/小容器圆角
+    colorBlock: 6, // 背景色块圆角
+    button: 24,   // 按钮圆角（胶囊风格）
+    pill: 100,    // 全圆角胶囊
+  },
+  /** 字号（fontSize） */
+  FONT: {
+    body: 14,     // 正文
+    sub: 13,      // 辅助说明
+    small: 12,    // 时间/列表小字
+    title: 15,    // 区块标题
+    button: 17,   // 按钮文字
+    buttonLegacy: 16, // legacy 生成器按钮兜底字号
+    large: 30,    // 数字大标题
+  },
+  /** 颜色 */
+  COLOR: {
+    pageBg: '#F5F6F8',        // 页面/画布背景
+    cardBg: '#FFFFFF',        // 卡片背景
+    primary: '#00B578',       // 品牌主色（绿，geo/v3）
+    primaryBlue: '#0079F2',  // legacy 生成器历史主色（蓝）
+    fallbackBg: '#F5F5F5',   // pickBg 兜底色
+    danger: '#F6434F',        // 危险/未读红点
+    textMain: '#111111',      // 主文字
+    textDefault: '#333333',   // 文本兜底色（spec 未给 color 时）
+    blockFill: '#EDEDED',     // 色块兜底色（spec 未给 fill 时）
+    textSub: '#555555',       // 次级文字
+    divider: '#EEEEEE',       // 分隔线
+    link: '#1584FF',          // 链接/操作文字（蓝）
+    btnText: '#FFFFFF',       // 按钮文字（主色底）
+    arrow: '#CCCCCC',         // 次级箭头
+  },
+}
+
+/** 便捷：直接拿到字符串化的 Token 值（生成器 setStyleChild 入参用） */
+export const T = {
+  gap: (k) => String(TOKEN.GAP[k]),
+  pad: (k) => String(TOKEN.PADDING[k]),
+  radius: (k) => String(TOKEN.RADIUS[k]),
+  font: (k) => String(TOKEN.FONT[k]),
+  color: (k) => TOKEN.COLOR[k],
+}

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

@@ -0,0 +1,103 @@
+/**
+ * paths.mjs — skill 内部路径与宿主项目路径单一来源（Node 侧）。
+ *
+ * 自包含约定：
+ *  - skill 自身的渲染器/元数据资源固定放在 <skill>/vendor/preview；
+ *  - 宿主项目（卡片与切图所在目录）默认是调用脚本时的 cwd，也可用环境变量覆盖；
+ *  - 不再向上查找 package.json，因此本 skill 可整体复制到任意项目使用。
+ *
+ * 环境变量（按优先级覆盖默认值）：
+ *   DSL_CARD_PROJECT_ROOT  宿主项目根目录（默认 process.cwd()）
+ *   DSL_CARD_CARDS_DIR     卡片目录（默认 <project>/src/cards）
+ *   DSL_CARD_SLICES_DIR    切图目录（默认 <project>/src/slices）
+ *   DSL_CARD_META_DIR      meta 元数据目录（默认 <skill>/vendor/preview/meta）
+ *   DSL_CARD_PREVIEW_DIR   自包含预览目录（默认 <skill>/vendor/preview）
+ *   DSL_CARD_BASELINES_DIR 渲染基线目录（默认 <project>/.card-baselines）
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+/** 当前 skill 根目录：scripts/lib -> scripts -> dsl-card-generator */
+export const skillRoot = path.resolve(HERE, '..', '..')
+
+/** skill 自包含资源根目录。 */
+export const vendorDir = path.join(skillRoot, 'vendor')
+
+/** 独立卡片预览目录（vendor/preview）。 */
+export const previewDir =
+  process.env.DSL_CARD_PREVIEW_DIR || path.join(vendorDir, 'preview')
+
+/** meta 元数据目录。 */
+export const metaDir =
+  process.env.DSL_CARD_META_DIR || path.join(previewDir, 'meta')
+
+/** 宿主项目根目录（默认当前工作目录）。 */
+export const projectRoot = process.env.DSL_CARD_PROJECT_ROOT || process.cwd()
+
+/** 卡片源数据目录。 */
+export const cardsDir =
+  process.env.DSL_CARD_CARDS_DIR || path.join(projectRoot, 'src', 'cards')
+
+/** 切图统一落点目录。 */
+export const slicesDir =
+  process.env.DSL_CARD_SLICES_DIR || path.join(projectRoot, 'src', 'slices')
+
+/** 渲染回归基线目录。 */
+export const baselinesDir =
+  process.env.DSL_CARD_BASELINES_DIR || path.join(projectRoot, '.card-baselines')
+
+/** 兼容旧脚本的别名：宿主项目根目录。 */
+export const repoRoot = projectRoot
+
+/** skills 父目录（供需要跨 skill 的脚本使用）。 */
+export const skillsDir = path.dirname(skillRoot)
+
+/**
+ * 解析卡片目录的绝对路径。
+ * @param {string} id 卡片 id
+ * @returns {string} `<cardsDir>/<id>` 绝对路径
+ */
+export function cardDir(id) {
+  return path.join(cardsDir, id)
+}
+
+/**
+ * 解析卡片 schema.json 的绝对路径。
+ * @param {string} id 卡片 id
+ * @returns {string}
+ */
+export function cardSchemaPath(id) {
+  return path.join(cardsDir, id, 'schema.json')
+}
+
+/**
+ * 解析卡片 data.json 的绝对路径。
+ * @param {string} id 卡片 id
+ * @returns {string}
+ */
+export function cardDataPath(id) {
+  return path.join(cardsDir, id, 'data.json')
+}
+
+/**
+ * 安全读取 JSON（不存在或解析失败时返回 fallback）。
+ *
+ * @param {string} p 路径
+ * @param {*} fallback 不存在/解析失败时的返回值（默认抛错）
+ * @returns {*} 解析后的 JS 值
+ */
+export function readJson(p, fallback = undefined) {
+  if (!fs.existsSync(p)) {
+    if (fallback === undefined) throw new Error(`File not found: ${p}`)
+    return fallback
+  }
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'))
+  } catch (e) {
+    if (fallback === undefined) throw new Error(`Cannot parse JSON ${p}: ${e.message}`)
+    return fallback
+  }
+}