cardbuddy 0.14.2 → 0.15.0

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

@@ -0,0 +1,131 @@
+/**
+ * geometry_audit.mjs —— 用**纯几何事实**判「节点是不是看不见 / 跑出画布 / 被折成一堆行」。
+ *
+ * 为什么需要它（2026-09-21 复盘）：上一轮建卡跑了 30 分钟不收敛，直接原因是模型**看不见渲染结果**
+ * （card_screenshot 只给人看、不进模型上下文），可观测输入只剩 match / heightDelta / bands 三个数字，
+ * 于是全程盲调参。而那两个致命缺陷（Row 内横向容器默认 100% 吃掉整行 → 文本被压成 0 宽、
+ * 兄弟被顶到 x=356 卡外）其实**不需要看图就能判定**：它们全是几何事实。
+ *
+ * 本模块只判可由 `getBoundingClientRect()` + computedStyle 直接证实的三类，不做任何猜测：
+ *  1. collapsed（**error**）：在流里、有可见内容、却被压成零尺寸 → 用户看不见它，千真万确。
+ *  2. outOfCard（**error**）：部分或全部落在卡片矩形之外 → 卡片根节 overflow:hidden，必然被裁。
+ *  3. overWrapped（**warn**）：文本高度 > 2 行（h / lineHeight > 2）→ 多半是被挤窄后逐字换行，
+ *     也可能是设计稿本来就是多行文本，故只提示不拦门禁。
+ *
+ * 判定阈值都用「1x 设计像素」，与 iterate 的 match/heightDelta 同一坐标系。
+ */
+
+/** 被视为「图形内容」的组件类：零尺寸时一定是缺陷（文本另有 text 判据）。 */
+const GRAPHIC_CLASSES = new Set(['Image', 'Icon', 'Video', 'Map', 'Svgsymbols', 'SvgSymbols', 'MultiText'])
+
+/** 文本节点折行阈值：h / lineHeight 超过这个倍数即提示（2 = 两行，>2 即三行以上）。 */
+const OVERWRAP_RATIO = 2
+
+const round1 = (n) => Math.round(Number(n) * 10) / 10
+
+/**
+ * @param {object} opts
+ * @param {Array<object>} opts.elements    render_card 产出的 elementBoxes（正常尺寸节点）
+ * @param {Array<object>} [opts.degenerate] render_card 产出的 elementBoxesDegenerate（零尺寸节点）
+ * @param {number} opts.cardWidth          卡片逻辑宽（1x，= `.phone__screen` 实测宽）
+ * @param {number} [opts.tolerance]        可接受误差（px），默认 1
+ * @returns {{collapsed:Array,outOfCard:Array,overWrapped:Array,counts:object}}
+ */
+export function auditGeometry({ elements, degenerate, cardWidth, tolerance = 1 }) {
+  const collapsed = []
+  const outOfCard = []
+  const overWrapped = []
+  const width = Number(cardWidth) || 0
+
+  for (const el of degenerate || []) {
+    const hasContent = Boolean(String(el.text || '').trim()) || GRAPHIC_CLASSES.has(el.cls)
+    if (!hasContent) continue // 空容器被压扁不报警（它本来就不显示东西）
+    collapsed.push({
+      cid: el.cid,
+      cls: el.cls,
+      text: String(el.text || '').slice(0, 24),
+      x: round1(el.x),
+      y: round1(el.y),
+      w: round1(el.w),
+      h: round1(el.h),
+      reason: Number(el.w) < tolerance
+        ? '宽被压成 0（同排兄弟把整行吃光了）→ 文本每字一行、实际不可读'
+        : '高被压成 0（父容器或兄弟把高度挤没了）',
+    })
+  }
+
+  for (const el of elements || []) {
+    const w = Number(el.w) || 0
+    const h = Number(el.h) || 0
+    if (w < tolerance || h < tolerance) {
+      // 正常集合里出现零尺寸（例如被 1px 容差漏过的边界情况）→ 同样按压扁处理
+      const hasContent = Boolean(String(el.text || '').trim()) || GRAPHIC_CLASSES.has(el.cls)
+      if (hasContent) collapsed.push({ cid: el.cid, cls: el.cls, text: String(el.text || '').slice(0, 24), x: round1(el.x), y: round1(el.y), w: round1(w), h: round1(h), reason: '尺寸被压到 1px 以下' })
+      continue
+    }
+    if (width > 0) {
+      const overRight = round1(el.x + w - width)
+      const overLeft = round1(-el.x)
+      if (overRight > tolerance || overLeft > tolerance) {
+        outOfCard.push({
+          cid: el.cid,
+          cls: el.cls,
+          text: String(el.text || '').slice(0, 24),
+          x: round1(el.x),
+          y: round1(el.y),
+          w: round1(w),
+          h: round1(h),
+          overflowRight: overRight > tolerance ? overRight : 0,
+          overflowLeft: overLeft > tolerance ? overLeft : 0,
+          reason: overRight > tolerance
+            ? `右缘超出卡片 ${overRight}px（卡宽 ${width}）→ 被根节点 overflow:hidden 裁掉`
+            : `左缘超出卡片 ${overLeft}px → 被裁掉`,
+        })
+      }
+    }
+    const lh = Number(el.lh) || 0
+    const text = String(el.text || '').trim()
+    if (text && lh > 0 && h / lh > OVERWRAP_RATIO) {
+      overWrapped.push({
+        cid: el.cid,
+        cls: el.cls,
+        text: text.slice(0, 24),
+        x: round1(el.x),
+        y: round1(el.y),
+        w: round1(w),
+        h: round1(h),
+        lines: Math.round(h / lh),
+        reason: `约占 ${Math.round(h / lh)} 行（h=${round1(h)} / 行高 ${round1(lh)}）→ 检查是否被挤窄后逐字换行；设计稿本来就是多行文本可忽略`,
+      })
+    }
+  }
+
+  return {
+    collapsed,
+    outOfCard,
+    overWrapped,
+    counts: { collapsed: collapsed.length, outOfCard: outOfCard.length, overWrapped: overWrapped.length },
+  }
+}
+
+/** 把审计结果压成一行给人/模型看的结论；无异常返回 null。 */
+export function describeGeometry(audit) {
+  if (!audit) return null
+  const parts = []
+  if (audit.collapsed.length) {
+    parts.push(
+      `被压成零尺寸（用户完全看不见）${audit.collapsed.length} 个：` +
+      audit.collapsed.slice(0, 4).map((c) => `${c.cls} ${c.cid}${c.text ? ` "${c.text}"` : ''}`).join('、'),
+    )
+  }
+  if (audit.outOfCard.length) {
+    parts.push(
+      `跑出卡片被裁掉 ${audit.outOfCard.length} 个：` +
+      audit.outOfCard.slice(0, 4).map((c) => `${c.cls} ${c.cid}${c.text ? ` "${c.text}"` : ''}（x=${c.x} w=${c.w}）`).join('、'),
+    )
+  }
+  if (audit.overWrapped.length) {
+    parts.push(`疑似折行异常 ${audit.overWrapped.length} 个：` + audit.overWrapped.slice(0, 3).map((c) => `${c.cls} ${c.cid} ≈${c.lines} 行`).join('、'))
+  }
+  return parts.length ? parts.join('；') : null
+}

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

@@ -0,0 +1,160 @@
+/**
+ * layout_rules.mjs —— 布局类硬契约的共享判定（lint_card.mjs / preflight.mjs 单一来源）。
+ *
+ * 为什么要有这个模块：同一条布局规则在 lint（迭代门禁）与 preflight（生成前检查）里各写一遍，
+ * 迟早会打架——一处改了、另一处没改，模型就会看到「同一张卡两个门禁结论不同」。R25/R31/R32 已
+ * 经是双写的，这里不再复制第三份。
+ *
+ * 本模块只放**从渲染器契约推导出来的、可静态判定**的事实，不猜设计意图：
+ *  ① 宽度基线：component-meta.json 里声明了 slots 的组件（=容器）默认 `rect.width:"100%"`，
+ *     且该默认**只在 rect 组整体缺失（或没有 width 子项）时生效**；写了 `width:""` 就是 auto；
+ *  ② 主轴方向：CSS 强制 `.ce_root/.ce_column/.ce_singlecolumn` 为 column，其余默认 row。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { metaDir } from './paths.mjs'
+
+/** CSS 强制 flex-direction:column 的容器类（card-editor/styles/components.css）。 */
+export const COLUMN_FLOW_CLASSES = new Set(['Root', 'Column', 'SingleColumn'])
+
+let _metaCache = null
+function componentMeta() {
+  if (_metaCache === null) {
+    try {
+      _metaCache = JSON.parse(fs.readFileSync(path.join(metaDir, 'component-meta.json'), 'utf8')).components || {}
+    } catch {
+      _metaCache = {}
+    }
+  }
+  return _metaCache
+}
+
+/** 容器类 = component-meta 里声明了 slots（能装子节点）的组件。 */
+export function containerClasses() {
+  const out = new Set()
+  for (const [cls, def] of Object.entries(componentMeta())) {
+    if ((def?.slots || []).length > 0) out.add(cls)
+  }
+  // meta 读不到时的兜底（保持规则可用，不至于静默失效）
+  if (!out.size) for (const c of ['Row', 'Column', 'MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'ViewContainer']) out.add(c)
+  return out
+}
+
+/**
+ * 容器的宽度基线是不是「填满父容器」（渲染器默认 100%）。
+ * 未写 rect.width 的容器会拿到 component-meta 的默认值，实测渲染为 100%。
+ */
+export function defaultWidth100Classes() {
+  const out = new Set()
+  for (const cls of containerClasses()) {
+    const w = componentMeta()[cls]?.styleState?.rect?.width
+    if (w === '100%') out.add(cls)
+  }
+  if (!out.size) for (const c of ['Row', 'Column', 'MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'ViewContainer']) out.add(c)
+  return out
+}
+
+/** 取 style.<group>.<key> 的字面值与来源开关（itemValueFrom）。 */
+export function styleChild(node, group, key) {
+  for (const g of node?.style?.properties || []) {
+    if (g.itemKey !== group) continue
+    for (const c of g.itemChildren?.properties || []) {
+      if (c.itemKey === key) return { value: String(c.itemValue ?? '').trim(), from: String(c.itemValueFrom ?? '0') }
+    }
+  }
+  return null
+}
+
+/** 父容器的主轴是横向（row）吗？CSS 默认按类定，schema 显式写 flexDirection 才覆盖。 */
+export function isHorizontalFlow(parent) {
+  if (!parent) return false
+  const explicit = styleChild(parent, 'flex', 'flexDirection')?.value
+  if (COLUMN_FLOW_CLASSES.has(parent.className)) return explicit === 'row'
+  return (explicit || 'row') === 'row'
+}
+
+/**
+ * R22b：横向流父容器里的**容器类子节点**，`rect.width` 缺失且 `flexShrink:0`。
+ *
+ * 渲染契约（2026-09-21 实测定标，见下）：
+ *   | rect 写法            | 容器实测渲染宽     | 同排兄弟               |
+ *   |---------------------|------------------|-----------------------|
+ *   | rect 组缺失 / 无 width 子项 | **100%（吃满整行）** | 长文本被压成 w=0 → 每字一行、不可见 ❌ |
+ *   | `width: ""`          | auto（自然宽）      | 正常 ✓                 |
+ *   | `width: "100%"`      | 100%             | 被压成 0 ❌（R22 管这一半） |
+ *   | `width: "60"`        | 60px             | 正常 ✓                 |
+ * 叠加 `flexShrink:0` = 锁死不让位，于是「吃满整行」那个必然把兄弟挤没或顶出卡外。
+ *
+ * 与 R22 的关系：R22 拦的是 schema **显式写了** `width:"100%"` 那一半；本规则补的是
+ * **rect.width 整个缺失**（渲染等价于 100%）却完全没人管的另一半 ——
+ * 实测 demo/helloCard 的 6 个致命节点全落在这个盲区。
+ *
+ * 注意 `width: ""` **不算缺失**：它是这套 schema 的「auto」表示法，实测渲染为自然宽，安全。
+ *
+ * 仅在父容器有 ≥2 个子节点时成立（独子占满整行是合法用法）。
+ *
+ * @returns {{className:string,widthVal:null,shrinkVal:string}|null} 命中时返回证据
+ */
+export function rowChildContainerNoWidth({ node, parent, siblingCount }) {
+  if (!node || !parent) return null
+  if (siblingCount < 2) return null
+  if (!containerClasses().has(node.className)) return null
+  if (!defaultWidth100Classes().has(node.className)) return null
+  if (!isHorizontalFlow(parent)) return null
+  // width 子项「存在」就算已显式指定（含空串 ""：auto 表示法，实测安全）；
+  // 只有整组缺失 / 没有 width 子项才会落到 component-meta 默认 "100%"。
+  if (styleChild(node, 'rect', 'width')) return null
+  const shrink = styleChild(node, 'flex', 'flexShrink')
+  if (shrink?.value !== '0') return null
+  return { className: node.className, widthVal: null, shrinkVal: shrink.value }
+}
+
+/** 默认插槽直接子节点（兼容 Root.components 与普通节点 slots[0].components）。 */
+export function directChildren(node) {
+  if (!node) return []
+  const slot = (node.slots || [])[0]
+  if (slot && Array.isArray(slot.components)) return slot.components
+  return Array.isArray(node.components) ? node.components : []
+}
+
+/**
+ * 在 schema 树里收集全部 R22b 命中（供 lint / preflight 共用）。
+ * @param {object} view schema.view
+ * @returns {Array<{componentId:string,className:string,parentId:string,parentClass:string,siblingCount:number,message:string}>}
+ */
+export function collectRowChildNoWidth(view) {
+  const hits = []
+  // Root（view）自身是 column 流，其直接子节点不参与本规则 ⇒ 传 null 当作「非横向父容器」。
+  const visit = (node, isRoot) => {
+    const siblings = directChildren(node)
+    for (const child of siblings) {
+      const result = rowChildContainerNoWidth({
+        node: child,
+        parent: isRoot ? null : node,
+        siblingCount: siblings.length,
+      })
+      if (result) {
+        const parentLabel = `${node.className || 'Root'} "${node.componentId || '(root)'}"`
+        hits.push({
+          componentId: child.componentId || '',
+          className: result.className,
+          parentId: node.componentId || '(root)',
+          parentClass: node.className || 'Root',
+          siblingCount: siblings.length,
+          message:
+            `${result.className} "${child.componentId || '?'}" 是横向流 ${parentLabel} 的并列子节点（共 ${siblings.length} 个），` +
+            '它的 rect.width 整个缺失 —— 渲染器对「没有 width 子项」会回落到 component-meta 默认「100%」（吃满整行），' +
+            '又叠了 flexShrink:0 锁死不让位：同排兄弟会被压成 0 宽（文本每字一行、高度爆炸）或被顶出卡片右缘裁掉（R22b）。' +
+            '按设计稿给这个容器补一个明确宽度：实测 px（如 rect.width:"146"）、或 `rect.width:"60%"`；' +
+            '要「按内容自适应」就写 rect.width:""（空串 = auto，实测渲染为自然宽）；' +
+            '要「占满剩余空间」用 flexGrow:1 并把 flexShrink 改 1，不要靠缺失 + 锁死。',
+        })
+      }
+      visit(child, false)
+    }
+  }
+  visit(view, true)
+  return hits
+}
+

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

@@ -13,6 +13,7 @@
  * （如 "99.切图/位图/卡片/详情/顶部-弥散@3x.png"）前缀不同，仅 basename 一致，
  * 故用 basename（去 @Nx 后缀）匹配，而非整体字符串相等。
  */
+import { sanitizeSliceFileName } from './slice_dedupe.mjs'
 
 /**
  * 归一化切片 basename，用于元素名 ↔ 导出文件名 匹配：
@@ -72,10 +73,21 @@ export function sliceFlatName(exportRelPath) {
   return String(exportRelPath || '').replace(/\//g, '_')
 }
 
-/** 导出相对路径 → schema 引用路径 "/slices/<扁平名>" */
+/**
+ * 导出相对路径 → schema 引用路径 `/slices/<扁平名>`。
+ *
+ * **引用名 = 落盘名（单一实际来源）**：产出前一律过 `sanitizeSliceFileName()`
+ * （`lib/slice_dedupe.mjs`），与 `crop_slices.mjs` / `expand_ir.syncReferencedSlices` /
+ * `generate_cards.collectSlicesToSrcSlices` 的落盘名同源 —— 这条等式是 `r31c` 能被机械验证的前提。
+ *
+ * ⚠️ 历史实现（2026-09-21 废弃）曾把 `#` / `?` 编码成 `%23` / `%3F`，走「磁盘留字面 `#`、
+ * 靠服务端 decodeURIComponent 桥接」的老路。它有三个致命伤：
+ *   ① `sliceNameFromRef()` 会先 decode、`%23` 解码回 `#`，照样被 `r31b` 拦（自己产自己拦）；
+ *   ② 引用名（`%23999`）与磁盘名（`#999`）**不同源**，任何一层不做 decode（CDN / 其他静态服务）
+ *      立刻 404，且盘上仍留着字面 `#` 这种到处出问题的文件名；
+ *   ③ 字面 `%` 还会被二次编码成 `%2523`。
+ * 故统一为「禁用保留字符 + 消毒改名」：`警示-#999` → `警示-999`（语义化场景应为 `iconWarning@2x`）。
+ */
 export function sliceRefPath(exportRelPath) {
-  return '/slices/' + sliceFlatName(exportRelPath)
-    .replace(/ /g, '_')
-    .replace(/#/g, '%23')
-    .replace(/\?/g, '%3F')
+  return '/slices/' + sanitizeSliceFileName(sliceFlatName(exportRelPath))
 }

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

@@ -49,6 +49,68 @@ export function checkSliceName(name) {
   return { semantic: true, reason: '' }
 }
 
+/* ── URL 保留字符：切图「静默不显示」的头号根因（2026-09-21 实测坐实）────────────
+ *
+ * 事故：卡片引用 `/slices/警示-#999.png`（名字沿用设计稿图层名）。`#` 在 URL 里是 fragment
+ * 分隔符，浏览器实际发出的是 `/slices/警示-`（percent-encoded），`#999.png` 根本没出网。
+ * 又因为切图未命中时静态中间件 `next()` 落到 SPA 兜底 → **HTTP 200 + HTML**，于是
+ * 「图片空白 + 网络面板全 200 + 零报错 + 门禁全绿」，30 分钟无人看出。
+ *
+ * 该集合只放「会改变 URL 解析语义」的字符 —— 中文名**不在**其中（浏览器会正常 percent-encode）：
+ *   #  之后整段是 fragment，不发服务器
+ *   ?  之后整段是 query，不发服务器
+ *   %  触发 percent-decode，非法编码会 400 / 名字被改写
+ *   &  在 query 语义下是参数分隔符
+ *   +  在 query 语义下被解码成空格
+ */
+export const SLICE_URL_RESERVED_CHARS = '#?%&+'
+
+/** 命中 URL 保留字符 → 返回命中的字符数组（去重）；否则 null。 */
+export function findUrlReservedChars(name) {
+  const hit = [...new Set([...String(name || '')].filter((c) => SLICE_URL_RESERVED_CHARS.includes(c)))]
+  return hit.length ? hit : null
+}
+
+/**
+ * 把切图文件名消毒成 URL 安全形态（保留扩展名；中文/语义化命名不动）。
+ *
+ * **调用方必须用返回名重写 schema 引用**：落盘名与 `/slices/` 引用名必须逐字一致，
+ * 只改名不改引用 = 从「假 200」换成「真 404」，图还是不出来。
+ *
+ * @param {string} name 原始文件名（可带或不带扩展名）
+ * @returns {string} URL 安全文件名（无扩展名时补 .png）
+ */
+export function sanitizeSliceFileName(name) {
+  const raw = String(name || '').trim()
+  const ext = path.extname(raw)
+  const base = ext ? raw.slice(0, -ext.length) : raw
+  let safe = base
+  for (const ch of SLICE_URL_RESERVED_CHARS) {
+    if (!safe.includes(ch)) continue
+    safe = safe.split(ch).join(ch === '%' ? 'pct' : ch === '&' ? 'and' : ch === '+' ? 'plus' : '-')
+  }
+  // 空白同样会断裂 CSS url()（R31），一并收成连字符
+  safe = safe.replace(/\s+/g, '-')
+  // 控制字符与 Windows 文件名禁用字符：直接剔除
+  safe = safe.replace(/[\u0000-\u001f\u007f<>:"/\\|*]/g, '')
+  // 折叠连续连字符、去掉首尾连字符（`警示-#999` → `警示-999`）
+  safe = safe.replace(/-{2,}/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+  return (safe || 'slice') + (ext || '.png')
+}
+
+/**
+ * 切图名同源判定：两侧都归一到消毒名后比较。
+ *
+ * 用途：落盘端按 **schema 里的引用名** 匹配源文件（`collectSlicesToSrcSlices` / `syncReferencedSlices`）。
+ * 引用名是消毒后的（`警示-999.png`），而要素包源文件仍是原名（`警示-#999.png`）——
+ * 直接字符串比较会**匹配不上 → 漏拷 → 引用悬空**（r31c）。归一后比较让两边都认得出来。
+ *
+ * `sanitizeSliceFileName` 幂等（无保留字符/空格的名字归一后不变），故可安全反复调用。
+ */
+export function sliceNameMatches(candidate, wanted) {
+  return sanitizeSliceFileName(candidate) === sanitizeSliceFileName(wanted)
+}
+
 /** 计算文件内容 sha256（去重的唯一权威判据）。 */
 export function sha256File(file) {
   return createHash('sha256').update(fs.readFileSync(file)).digest('hex')
@@ -145,3 +207,43 @@ export function sliceNameFromRef(ref) {
   try { name = decodeURIComponent(name) } catch { /* 非法编码保持原样 */ }
   return name
 }
+
+/**
+ * 远端切图引用判定：已上传 FinMall（@filestore）、外链（http/https/protocol-relative）、内联 data URI。
+ * 这类引用天然没有本地文件，不能参与「本地 src/slices 里是否存在」的判定（否则满仓误报）。
+ */
+export function isRemoteSliceRef(ref) {
+  const s = String(ref || '')
+  return /^(https?:)?\/\//i.test(s) || s.includes('@filestore') || s.startsWith('data:')
+}
+
+/** 文件名去扩展名（`icon@2x.png` → `icon@2x`）。 */
+export function stemOf(file) {
+  const s = String(file || '')
+  return path.extname(s) ? s.slice(0, -path.extname(s).length) : s
+}
+
+/**
+ * 建切片目录的查找索引（一次 readdir，批量校验复用）。
+ * @returns {{ files: string[], names: Set<string>, stems: Set<string> }}
+ */
+export function buildSliceFileIndex(dir) {
+  const files = dir && fs.existsSync(dir) ? fs.readdirSync(dir) : []
+  return { files, names: new Set(files), stems: new Set(files.map(stemOf)) }
+}
+
+/**
+ * `/slices/<name>` 引用在切片目录里是否有对应文件。
+ * 无扩展名引用（`/slices/iconArrowRight`）按「同名去扩展名」再匹配一轮 —— schema 允许这么写。
+ *
+ * 存在的意义：R31 拦「名字带空格」、R31b 拦「名字带 URL 保留字符」，都是「名字写了但用不了」；
+ * 这里补「这个名字在磁盘上就没有」——渲染时 404，图片位置空白且控制台零报错。
+ * 调用方负责先用 isRemoteSliceRef 过滤远端引用。
+ * @returns {{ resolved: boolean, name: string, stem: string }}
+ */
+export function resolveSliceRefOnDisk(index, ref) {
+  const name = path.basename(sliceNameFromRef(ref))
+  const stem = stemOf(name)
+  if (!name) return { resolved: false, name, stem }
+  return { resolved: index.names.has(name) || index.stems.has(stem), name, stem }
+}