cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,1399 @@
+#!/usr/bin/env node
+/**
+ * lint_card.mjs — 卡片健康度体检（结构合法 ≠ 体验达标）。
+ *
+ * 与 validate_schema.py 的边界：
+ *  - validate 管"结构合法、能不能渲染"（CI 硬卡点）。
+ *  - lint 管"达不达标、会不会让用户看到怪东西"（软提醒）。
+ *  - 一张卡可以结构完全合法（validate 0 ERROR）但仍有体验问题（lint 报警）。
+ *
+ * 检查项：
+ *   1. 脚手架前缀残留：data.json / 表达式里出现 scaffold 自动生成的占位文本（"示例xxx"）。
+ *   2. 未使用的 inputParams：声明了 $key 但 schema 里没引用（数据字典膨胀）。
+ *   3. Button 缺 click：按钮节点没有 click 事件（按钮不能点是常见 bug）。
+ *   4. 根节点缺 background：Root.style 没有 background 组（透明卡用户会困惑）。
+ *   5. Text 缺 font.color：Text 节点没有 font.color（深色主题下看不见）。
+ *   6. Canvas 缺 onMeasured：Canvas 没有 onMeasured 等于画不出来。
+ *   7. 空文本节点：Text.value 绑的 $key 在 data.json 是空字符串且无 placeholder。
+ *   8. eventKey 与组件类型不匹配：如 Text 接 onMeasured、Canvas 接 click 等。
+ *   9. style/properties/directives 缺 itemValueFrom：缺失或空串会被预览器静默丢弃（背景/内边距/对齐失效），与 validate_schema.py 同源 ERROR。
+ *   10. style 子项 itemId 错配：子项 itemId 与该组（参考 vendor/preview/meta/style-meta.json）预期不一致（如 flexDirection 误用 002 而非 006），与 validate_schema.py 同源 ERROR。
+ *   11. 标题+下划线拓扑：AbsoluteLayout 必须显式 BottomLeft，装饰条先于标题绘制，宽度建议绑定标题长度表达式。
+ *   12. 切图命名语义化（r59）：引用名沿用设计稿图层名/导出目录前缀/中文名 → 看不出用途，必须按功能重命名。
+ *   13. 切图同内容重复（r60）：src/slices 里存在 sha256 完全相同的副本 → 应复用同一份，不重复导入/上传。
+ *   14. 静态文案 / 字典默认值含疑似运行期数字（r61，提醒级）：千分号数字 / ¥+数字 / 数字+单位词写死在静态 Text 或 defaultValue 里 → 提示按 rules.md §十四 做 AI 语义复核（运行期数字应抽变量 + 表达式拼接）；固定话术误报可忽略。
+ *
+ * 用法：
+ *   node lint_card.mjs --id <cardId>              # 体检单张卡
+ *   node lint_card.mjs --all                      # 体检所有卡
+ *   node lint_card.mjs --id <cardId> --json       # 机器可读输出
+ *   node lint_card.mjs --id <cardId> --strict     # 有 lint 报警 exit 1（CI 可选）
+ *
+ * 退出码：
+ *  - 0：无 lint 报警（或未启用 --strict）
+ *  - 1：有 lint 报警且 --strict
+ *  - 2：脚本异常（卡不存在、JSON 解析失败等）
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { fileURLToPath } from 'node:url'
+import { cardsDir, cardSchemaPath, cardDataPath, readJson, metaDir, slicesDir } from './lib/paths.mjs'
+import { buildContentIndex, checkSliceName, collectSliceRefStrings, duplicatePeers, sliceNameFromRef } from './lib/slice_dedupe.mjs'
+
+// src/slices 内容索引（sha256 → 文件名）进程内只建一次，--all 体检全量卡时复用
+let SLICE_CONTENT_INDEX = null
+function sliceContentIndex() {
+  if (!SLICE_CONTENT_INDEX) SLICE_CONTENT_INDEX = buildContentIndex(slicesDir)
+  return SLICE_CONTENT_INDEX
+}
+
+const RENDER_CONTRACT = JSON.parse(fs.readFileSync(
+  path.join(metaDir, '../../../config/render-contract.json'),
+  'utf8',
+))
+
+// Group 指令（如 v-show）：必须 itemValueFrom:"0" + itemChildren，裸字符串/“1” 会被渲染器 onPreview 静默丢弃
+const DM = JSON.parse(fs.readFileSync(path.join(metaDir, 'directive-meta.json'), 'utf8'))
+const GROUP_DIRECTIVES = new Set((DM.properties || []).filter((d) => (d.itemChildren || []).length > 0).map((d) => d.itemKey))
+
+/* ------------------------------------------------------------------ */
+/* 参数解析                                                            */
+/* ------------------------------------------------------------------ */
+function parseArgs(argv) {
+  const out = { id: '', all: false, json: false, strict: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--id') out.id = argv[++i]
+    else if (a === '--all') out.all = true
+    else if (a === '--json') out.json = true
+    else if (a === '--strict') out.strict = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: node lint_card.mjs [options]
+
+Options:
+  --id <cardId>    体检单张卡
+  --all            体检 src/cards 下所有卡
+  --json           机器可读 JSON 输出
+  --strict         有 lint 报警时 exit 1（CI 用）
+  -h, --help       显示本帮助`)
+      process.exit(0)
+    }
+  }
+  if (!out.id && !out.all) {
+    console.error('[error] 必须指定 --id <cardId> 或 --all')
+    process.exit(1)
+  }
+  return out
+}
+
+/* ------------------------------------------------------------------ */
+/* 节点遍历                                                            */
+/* ------------------------------------------------------------------ */
+function walk(node, visitor, parent = null) {
+  if (!node || typeof node !== 'object') return
+  visitor(node, parent)
+  if (Array.isArray(node.components)) for (const c of node.components) walk(c, visitor, node)
+  for (const s of node.slots || []) for (const c of s.components || []) walk(c, visitor, node)
+}
+
+/** 获取默认插槽直接子节点（兼容 Root.components 与普通节点 slots[0].components） */
+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 : []
+}
+
+/**
+ * 收集所有被引用的数据字典 key（粗扫，不过滤 slotScope）：
+ *  1. 表达式里的 `$key`
+ *  2. customAction 脚本里的 `<别名>.state.key` / `<别名>.data.key`
+ *     别名 = this / self / that / _this（Canvas 自绘普遍用 self.state.x，
+ *     见 previewer_contract.md；闭包里常用 that/_this）
+ *     注意不要加 \b 前缀断言：脚本经 JSON.stringify 后换行变成字面量 "\n"，
+ *     `n` 会紧贴 this 导致 \b 失效而漏匹配。
+ *     —— R51 之后运行时变量只在事件脚本里以 state 读取，view 表达式扫不到，
+ *        不补这一路会让「仅事件内使用」的 inputParams 被误报 unused-input-param。
+ */
+function collectBindings(schema) {
+  const used = new Set()
+  const text = JSON.stringify(schema.view || {})
+  // 统一扫：$ 后跟合法标识符
+  const re = /\$([A-Za-z_$][\w$]*)/g
+  let m
+  while ((m = re.exec(text))) used.add(m[1])
+  // 事件脚本内的 this/self/that/_this 的 .state.x / .data.x
+  const reState = /(?:this|self|that|_this)\.(?:state|data)\.([A-Za-z_$][\w$]*)/g
+  while ((m = reState.exec(text))) used.add(m[1])
+  return used
+}
+
+/* ------------------------------------------------------------------ */
+/* style-meta 派生：groupKey -> { childKey: childItemId }              */
+/* （与 validate_schema.py::load_style_maps 同源；捕捉 flexDirection    */
+/*   误用 002 而非 006 这类「itemId 存在但放错组」的隐形 bug）           */
+/* ------------------------------------------------------------------ */
+let _styleGroupChildMap = null
+function loadStyleMaps() {
+  if (_styleGroupChildMap) return _styleGroupChildMap
+  const map = {}
+  const sm = path.join(metaDir, 'style-meta.json')
+  try {
+    const data = readJson(sm, null)
+    if (data && Array.isArray(data.properties)) {
+      for (const grp of data.properties) {
+        const gk = grp.itemKey
+        if (!gk) continue
+        const cm = {}
+        for (const c of grp.itemChildren || []) {
+          const ck = c.itemKey
+          const cid = c.itemId
+          if (ck != null && cid != null) cm[String(ck)] = String(cid)
+        }
+        map[String(gk)] = cm
+      }
+    }
+  } catch (e) {
+    // style-meta 解析失败则跳过 itemId 校验，不阻塞 lint
+  }
+  _styleGroupChildMap = map
+  return map
+}
+
+/**
+ * 校验单节点的「itemValueFrom 必填」与「style 子项 itemId 一致性」。
+ * 这两类问题在预览器里是静默失效（属性被丢弃 / 被错填到其它属性），
+ * validate_schema.py 已把它们设为 ERROR；lint 这里再报一遍，方便体检时一并发现。
+ */
+function checkStyleIntegrity(node, cid, out) {
+  const styleMaps = loadStyleMaps()
+
+  // style 子项
+  const styleProps = (node.style && node.style.properties) || []
+  for (const grp of styleProps) {
+    const gk = grp.itemKey
+    const children = (grp.itemChildren && grp.itemChildren.properties) || []
+    const expectMap = styleMaps[gk]
+    for (const child of children) {
+      // 9. 缺失/空 itemValueFrom
+      const vf = child.itemValueFrom
+      if (vf === undefined || vf === null || vf === '') {
+        out.push({
+          severity: 'error',
+          code: 'missing-itemValueFrom',
+          componentId: cid,
+          message: `style.${gk}.${child.itemKey || '?'} 缺 itemValueFrom —— 预览时该属性会被静默丢弃（背景/内边距/对齐失效），用 autofix_schema.py 可一键补 "0"`,
+        })
+      }
+      // 10. style 子项 itemId 错配
+      if (expectMap && child.itemKey != null) {
+        const expect = expectMap[String(child.itemKey)]
+        const got = child.itemId != null ? String(child.itemId) : undefined
+        if (expect && got !== expect) {
+          out.push({
+            severity: 'error',
+            code: 'style-itemId-mismatch',
+            componentId: cid,
+            message: `style.${gk}.${child.itemKey} 用 itemId "${got}"，但该组预期 "${expect}"（如 flexDirection 应 006 而非 002）—— 会被错填到其它属性`,
+          })
+        }
+      }
+    }
+  }
+
+  // component properties
+  for (const p of node.properties || []) {
+    const vf = p.itemValueFrom
+    if (vf === undefined || vf === null || vf === '') {
+      out.push({
+        severity: 'error',
+        code: 'missing-itemValueFrom',
+        componentId: cid,
+        message: `property ${p.itemKey || '?'} 缺 itemValueFrom —— 预览时该属性会被静默丢弃，用 autofix_schema.py 可一键补 "0"`,
+      })
+    }
+  }
+
+  // directives
+  for (const d of node.directives || []) {
+    const vf = d.itemValueFrom
+    if (vf === undefined || vf === null || vf === '') {
+      out.push({
+        severity: 'error',
+        code: 'missing-itemValueFrom',
+        componentId: cid,
+        message: `directive ${d.itemKey || '?'} 缺 itemValueFrom —— 预览时该指令会被静默丢弃，用 autofix_schema.py 可一键补 "0"`,
+      })
+    } else if (GROUP_DIRECTIVES.has(d.itemKey) && String(vf) !== '0') {
+      // Group 指令（v-show 等）误用 itemValueFrom:"1"（裸表达式字符串形式）—— onPreview 会丢弃其 itemChildren 条件，指令失效
+      out.push({
+        severity: 'error',
+        code: 'group-directive-bad-form',
+        componentId: cid,
+        message: `directive ${d.itemKey} 是 Group 指令，必须 itemValueFrom:"0" 且带 itemChildren（showType/condition）；当前 itemValueFrom:"${vf}" 会被渲染器 onPreview 静默丢弃条件，指令永远生效/失效。修正：改为对象形式 d:{ "${d.itemKey}": { showType:"01", condition:{ expression:"..." } } }`,
+      })
+    }
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* 检查规则                                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * @returns { severity: 'error'|'warn'|'info', code: string, message: string, componentId?: string }
+ */
+export function lint(schema, data) {
+  const out = []
+  const view = schema.view
+  if (!view) return [{ severity: 'error', code: 'no-view', message: 'schema 没有 view 字段' }]
+
+  // 1. 脚手架前缀残留（"示例"是 scaffold_card.mjs 默认占位文本）
+  if (data && typeof data === 'object') {
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v === 'string' && v.startsWith('示例')) {
+        out.push({
+          severity: 'warn',
+          code: 'scaffold-placeholder',
+          message: `data.json["${k}"] = "${v.slice(0, 30)}" 是脚手架占位值（来自 scaffold_card.mjs 的 inferInputParams），上线前应替换为真实文案`,
+        })
+      }
+    }
+  }
+  // 也扫表达式里的字面量
+  const viewText = JSON.stringify(view)
+  const sampleMatches = viewText.match(/"示例[^"]+"/g) || []
+  for (const m of [...new Set(sampleMatches)].slice(0, 3)) {
+    out.push({
+      severity: 'warn',
+      code: 'scaffold-placeholder-expr',
+      message: `表达式里发现脚手架占位字面量 ${m}，上线前应替换`,
+    })
+  }
+
+  // 2. 未使用的 inputParams
+  const params = (schema.dictionary && schema.dictionary.inputParams) || []
+  if (params.length) {
+    const used = collectBindings(schema)
+    for (const p of params) {
+      if (!used.has(p.key)) {
+        out.push({
+          severity: 'info',
+          code: 'unused-input-param',
+          message: `inputParams["${p.key}"] 声明了但在 view 表达式（$${p.key}）与事件脚本（this.state.${p.key}）里均未引用，可考虑删除以瘦身数据字典`,
+        })
+      }
+    }
+  }
+
+  // R43: 卡片背景不透明 —— Root 或首层容器必须有非透明背景色
+  // 卡片背景不存在透明的情况：检查到透明时从标注取背景色，无法获取则从截图取色
+  function hasOpaqueBg(node) {
+    const bgGroup = (node.style?.properties || []).find((p) => p.itemKey === 'background')
+    if (!bgGroup) return false
+    const bgChildren = bgGroup.itemChildren?.properties || []
+    const bgType = bgChildren.find((c) => c.itemKey === 'backgroundType')
+    const bgColor = bgChildren.find((c) => c.itemKey === 'backgroundColor')
+    if (bgType && bgType.itemValue && bgType.itemValue !== '00' && bgColor && bgColor.itemValue) return true
+    if (bgType && ['02', '03'].includes(bgType.itemValue)) return true
+    return false
+  }
+  // Check Root(view) OR first child component (card containers often put bg on inner Column)
+  let cardHasBg = hasOpaqueBg(view)
+  if (!cardHasBg) {
+    const firstChild = (view.components?.[0]) || (view.slots?.[0]?.components?.[0])
+    if (firstChild) cardHasBg = hasOpaqueBg(firstChild)
+  }
+  if (!cardHasBg) {
+    out.push({
+      severity: 'error',
+      code: 'r43-card-transparent-background',
+      message: `卡片背景透明 —— 卡片背景不允许透明（R43）。须从设计稿标注 cardFill 取背景色写入 Root/首层容器的 background.backgroundColor + backgroundType:"01"；标注缺失时从聚焦截图取色兜底。`,
+    })
+  }
+
+  // 4-8. 节点级检查
+  // 祖先链映射：Button.vue 的 `$emit('click')` 未加 .stop，原生 click 会冒泡到祖先元素，
+  // 祖先带 click handler 时按钮实际可点 —— 这类不算「按钮不能点」。
+  const parentOf = new Map()
+  walk(view, (n, parent) => { if (parent) parentOf.set(n, parent) })
+  const hasOwnClick = (node) => (node.eventactions || []).some((ea) => ea && ea.event && ea.event.eventKey === 'click')
+  const findClickCarrier = (node) => {
+    for (let p = parentOf.get(node); p; p = parentOf.get(p)) if (hasOwnClick(p)) return p
+    return null
+  }
+
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    const cls = n.className
+
+    // 9-10. itemValueFrom 必填 + style 子项 itemId 一致性（与 validate_schema.py 同源）
+    checkStyleIntegrity(n, cid, out)
+
+    // 4. Button 缺 click
+    if (cls === 'Button') {
+      const carrier = hasOwnClick(n) ? null : findClickCarrier(n)
+      if (carrier) {
+        out.push({
+          severity: 'info',
+          code: 'button-click-by-ancestor',
+          componentId: cid,
+          message: `Button "${cid}" 自身无 click 事件，靠冒泡由祖先 ${carrier.className} "${carrier.componentId || '(root)'}" 的 click 承载 —— 可点但点击热区扩大到整个祖先容器，建议确认是否符合预期`,
+        })
+      } else if (!hasOwnClick(n)) {
+        out.push({
+          severity: 'warn',
+          code: 'button-no-click',
+          componentId: cid,
+          message: `Button "${cid}" 没有 click 事件 —— 按钮不能点是常见 bug（如有意做静态按钮可忽略）`,
+        })
+      }
+    }
+
+    // 5. Text 缺 font.color
+    if (cls === 'Text') {
+      const fontGroup = (n.style && n.style.properties || []).find((p) => p.itemKey === 'font')
+      const colorChild = fontGroup && (fontGroup.itemChildren && fontGroup.itemChildren.properties || []).find((c) => c.itemKey === 'color')
+      if (!colorChild) {
+        out.push({
+          severity: 'info',
+          code: 'text-no-color',
+          componentId: cid,
+          message: `Text "${cid}" 未设 font.color —— 浏览器默认黑色，深色主题下会看不见`,
+        })
+      }
+      // 7. 空文本节点
+      const valProp = (n.properties || []).find((p) => p.itemKey === 'value')
+      if (valProp && valProp.itemValueFrom === '1') {
+        const key = String(valProp.itemValue || '').replace(/^\$/, '')
+        if (data && data[key] === '' && !valProp.itemDefaultValue) {
+          out.push({
+            severity: 'info',
+            code: 'text-empty-binding',
+            componentId: cid,
+            message: `Text "${cid}" 绑定 $${key} 但 data.json["${key}"] 是空字符串且无 itemDefaultValue —— 预览时会显示空白`,
+          })
+        }
+      }
+    }
+
+    // 6. Canvas 缺 onMeasured
+    if (cls === 'Canvas') {
+      const hasMeasured = (n.eventactions || []).some((ea) => ea && ea.event && ea.event.eventKey === 'onMeasured')
+      if (!hasMeasured) {
+        out.push({
+          severity: 'warn',
+          code: 'canvas-no-onmeasured',
+          componentId: cid,
+          message: `Canvas "${cid}" 没有 onMeasured 事件 —— Canvas 只能在 onMeasured 里画，否则一片空白`,
+        })
+      }
+    }
+
+    // 8. eventKey 与组件类型不匹配
+    const knownEvents = {
+      Root: ['onReady', ''],
+      Row: ['click'],
+      Column: ['click'],
+      ListLayout: ['click'],
+      GridLayout: ['click'],
+      AbsoluteLayout: [],
+      Canvas: ['onMeasured'],
+      Text: ['click'],
+      Button: ['click'],
+      Icon: ['click'],
+      Image: ['click'],
+      MultiText: ['click'],
+      Input: [], // Input 无可绑定事件
+      Divider: [],
+      ViewContainer: ['action'],
+    }
+    const allowed = knownEvents[cls]
+    if (allowed && (n.eventactions || []).length) {
+      for (const ea of n.eventactions) {
+        const ek = ea && ea.event && ea.event.eventKey
+        if (ek && !allowed.includes(ek)) {
+          out.push({
+            severity: 'warn',
+            code: 'event-mismatch',
+            componentId: cid,
+            message: `${cls} "${cid}" 接了 eventKey="${ek}"，但该组件只支持 ${JSON.stringify(allowed)} —— 该事件永远不会触发`,
+          })
+        }
+      }
+    }
+  })
+
+  // ── R 规则自动校验（从 generation_pitfalls.md 迁移）─────────────
+
+  // ── Pre-pass: 构建 parent→children 映射（供 R34 多子容器检查 + R17 单子容器判定）──
+  const nodeMap = new Map()
+  const parentChildrenMap = new Map()
+  function buildMaps(node, parent) {
+    if (!node || typeof node !== 'object') return
+    if (node.componentId) nodeMap.set(node.componentId, node)
+    if (parent && parent.componentId) {
+      const pid = parent.componentId
+      if (!parentChildrenMap.has(pid)) parentChildrenMap.set(pid, [])
+      parentChildrenMap.get(pid).push(node)
+    }
+    if (Array.isArray(node.components)) for (const c of node.components) buildMaps(c, node)
+    for (const s of node.slots || []) for (const c of s.components || []) buildMaps(c, node)
+  }
+  buildMaps(view, null)
+
+  function getShrinkVal(n) {
+    const sp = (n.style && n.style.properties) || []
+    const fg = sp.find(p => p.itemKey === 'flex')
+    const fc = (fg && fg.itemChildren && fg.itemChildren.properties) || []
+    const sc = fc.find(c => c.itemKey === 'flexShrink')
+    return sc ? String(sc.itemValue) : null
+  }
+
+  function getWidthVal(n) {
+    const sp = (n.style && n.style.properties) || []
+    const rg = sp.find(p => p.itemKey === 'rect')
+    const rc = (rg && rg.itemChildren && rg.itemChildren.properties) || []
+    const wc = rc.find(c => c.itemKey === 'width')
+    return wc ? String(wc.itemValue) : null
+  }
+
+  // ── R35: 多子容器全部子节点 flexShrink:0 → 溢出风险 ──
+  for (const [pid, children] of parentChildrenMap) {
+    const parent = nodeMap.get(pid)
+    if (!parent) continue
+    const pcls = parent.className
+    if ((pcls === 'Row' || pcls === 'Column') && children.length >= 2) {
+      const parentWidth = getWidthVal(parent)
+      const isContentSize = !parentWidth || parentWidth === 'auto'
+      const allShrinkZero = children.every(child => getShrinkVal(child) === '0')
+      // 透明度切换固定范式（R57）的变体容器：子节点各带互斥 v-show，同一时刻只有一个在流里，
+      // 定宽不会累加，属 R35 的合法豁免（容器本身已与变体等宽高 + overflow:hidden）。
+      const hasVShow = (child) => ((child.directives) || []).some((d) => d && d.itemKey === 'v-show')
+      const isExclusiveVariantGroup = children.length >= 2 && children.every(hasVShow)
+      if (!isContentSize && allShrinkZero && !isExclusiveVariantGroup) {
+        out.push({
+          severity: 'error',
+          code: 'r35-multi-child-all-shrink0',
+          componentId: pid,
+          message: `${pcls} "${pid}" 宽度非 auto 且 ${children.length} 个并列子节点全部 flexShrink:0 → 外容器宽度变化时定宽累加溢出（R35）。至少一个子节点应保持 flexShrink:1 可压缩；内容自适应容器（width:auto）可保留固定子元素`,
+        })
+      }
+    }
+  }
+
+  // ── R31: Image 引用路径含空格 → CSS url() 断裂 ──
+  walk(view, (n) => {
+    if (n.className !== 'Image') return
+    for (const p of n.properties || []) {
+      if (p.itemKey === 'value' && typeof p.itemValue === 'string') {
+        const v = p.itemValue
+        if (v.includes('/slices/') && /\s/.test(v.replace('/slices/', ''))) {
+          out.push({
+            severity: 'error',
+            code: 'r31-slice-filename-space',
+            componentId: n.componentId || '',
+            message: `Image "${n.componentId}" 引用路径含空格: "${v}" → CSS url() 空格断裂 → background-image:none（R31）。重命名为纯 ASCII`,
+          })
+        }
+      }
+    }
+  })
+
+  // ── R59/R60: 切图语义化命名 + 同内容去重（slices_convention.md §1.1 / §3.1）──
+  for (const ref of collectSliceRefStrings(schema)) {
+    const name = sliceNameFromRef(ref)
+    const base = path.basename(name)
+    const nameCheck = checkSliceName(base)
+    if (!nameCheck.semantic) {
+      out.push({
+        severity: 'warn',
+        code: 'r59-slice-semantic-name',
+        componentId: '',
+        message: `切图名非语义化: "${base}"（${nameCheck.reason}）→ 按实际功能/作用重命名（如 iconArrowRight@3x.png / bgCardHeader@3x.png），并同步改写所有卡片引用；禁止沿用设计稿图层名、导出目录前缀或中文名（slices_convention.md §1.1）`,
+      })
+    }
+    const peers = duplicatePeers(sliceContentIndex(), slicesDir, name)
+    if (peers.length) {
+      out.push({
+        severity: 'warn',
+        code: 'r60-slice-duplicate-content',
+        componentId: '',
+        message: `切图 "${base}" 与 ${peers.join('、')} 内容完全相同（sha256 一致）→ 只保留语义名那一份并把引用改写到它，不要重复导入/重复上传（slices_convention.md §3.1 / §4.1）`,
+      })
+    }
+  }
+
+  // ── R61: 静态文案 / 字典默认值含疑似运行期数字（rules.md §十四，提醒级 WARN）──
+  // 只作「提醒 AI 语义复核」的启发式：命中 ≠ 违规（版本号 / 固定营销话术会误报），故 WARN 不阻塞。
+  const NUMERIC_LITERAL_PATTERNS = [
+    { re: /\d{1,3}(,\d{3})+(\.\d+)?/, label: '千分号数字' },
+    { re: /[¥￥]\s*\d+(\.\d+)?/, label: '货币符+数字' },
+    { re: /\d+(\.\d+)?\s*(元|笔|次|个|条)/, label: '数字+单位词' },
+  ]
+  const numericHit = (str) => {
+    for (const { re, label } of NUMERIC_LITERAL_PATTERNS) if (re.test(str)) return label
+    return null
+  }
+  walk(view, (n) => {
+    if (n.className !== 'Text') return
+    for (const p of n.properties || []) {
+      if (p.itemKey !== 'value' || p.itemValueFrom === '1') continue // 表达式绑定不查
+      const v = typeof p.itemValue === 'string' ? p.itemValue : ''
+      if (!v) continue
+      const label = numericHit(v)
+      if (!label) continue
+      out.push({
+        severity: 'warn',
+        code: 'r61-text-numeric-literal',
+        componentId: n.componentId || '',
+        message: `静态文案含疑似运行期数字（${label}: "${v.slice(0, 40)}"）→ 按 rules.md §十四 先做 AI 语义复核：数字随运行期数据变化则抽 inputParams 变量 + 表达式拼接展示（金额=原始数字+格式化表达式）；固定话术（版本号/营销语）可保留，忽略本 WARN`,
+      })
+    }
+  })
+  for (const param of params) {
+    const dv = param && param.defaultValue
+    if (typeof dv !== 'string' || !dv) continue
+    const label = numericHit(dv)
+    if (!label) continue
+    out.push({
+      severity: 'warn',
+      code: 'r61-text-numeric-literal',
+      componentId: param.key || '',
+      message: `inputParams["${param.key}"].defaultValue 为含疑似运行期数字的字符串（${label}: "${dv.slice(0, 40)}"）→ 金额/计数应 type:"number" + 原始数字，禁止格式化串（12,300.00）/带货币符串进字典（rules.md §十四.2/§十四.4）；确为文本字段（地址/话术）可忽略本 WARN`,
+    })
+  }
+
+  // ── R32: Image 缺 rect.height → CSS aspect-ratio:16/9 压缩 ──
+  walk(view, (n) => {
+    if (n.className !== 'Image') return
+    const sp = (n.style && n.style.properties) || []
+    const rectGroup = sp.find(p => p.itemKey === 'rect')
+    const rectChildren = (rectGroup && rectGroup.itemChildren && rectGroup.itemChildren.properties) || []
+    const hChild = rectChildren.find(c => c.itemKey === 'height')
+    if (!hChild || !String(hChild.itemValue).trim()) {
+      out.push({
+        severity: 'error',
+        code: 'r32-image-no-height',
+        componentId: n.componentId || '',
+        message: `Image "${n.componentId}" 缺 rect.height → CSS aspect-ratio:16/9 压缩图片高度（R32）。设显式高度`,
+      })
+    }
+  })
+
+  // ── R25: Image itemValueFrom 三态精确映射 ──
+  walk(view, (n) => {
+    if (n.className !== 'Image') return
+    for (const p of n.properties || []) {
+      if (p.itemKey !== 'value') continue
+      const from = String(p.itemValueFrom || '')
+      const val = String(p.itemValue || '')
+      if (from === '0' && !val.startsWith('$')) {
+        out.push({
+          severity: 'error',
+          code: 'r25-image-from-0',
+          componentId: n.componentId || '',
+          message: `Image "${n.componentId}" itemValueFrom="0"(常量) → 渲染器不走图片逻辑，空白（R25）。静态路径用 "2"`,
+        })
+      }
+      if (from === '1' && !val.startsWith('$')) {
+        out.push({
+          severity: 'error',
+          code: 'r25-image-from-1',
+          componentId: n.componentId || '',
+          message: `Image "${n.componentId}" itemValueFrom="1"(变量) 但值不以 $ 开头 → 表达式求值失败，空白（R25）`,
+        })
+      }
+    }
+  })
+
+  // ── R23: 百分比表达式缺 Math.round → JS 浮点精度 ──
+  walk(view, (n) => {
+    const allProps = [...(n.properties || [])]
+    for (const sp of n.style?.properties || []) {
+      for (const c of sp.itemChildren?.properties || []) allProps.push(c)
+    }
+    for (const p of allProps) {
+      if (String(p.itemValueFrom) === '1' && typeof p.itemValue === 'string') {
+        if (/\*\s*100/.test(p.itemValue) && !/Math\.round/.test(p.itemValue)) {
+          out.push({
+            severity: 'error',
+            code: 'r23-no-math-round',
+            componentId: n.componentId || '',
+            message: `"${n.componentId}" 表达式含 *100 但无 Math.round → JS 浮点精度溢出（R23）: ${p.itemValue.slice(0, 50)}`,
+          })
+        }
+      }
+    }
+  })
+
+  // R17/R22: flexShrink 铁律
+  //   R17: 关键 Text（金额/数字/标签/标题/占比/单位）必须 flexShrink:0（防换行）
+  //   R22: width:100% 节点必须 flexShrink:1（让位防溢出）
+  walk(view, (n, parent) => {
+    const cid = n.componentId || '(root)'
+    const cls = n.className
+    const styleProps = (n.style && n.style.properties) || []
+    const flexGroup = styleProps.find((p) => p.itemKey === 'flex')
+    const flexChildren = (flexGroup && flexGroup.itemChildren && flexGroup.itemChildren.properties) || []
+    const rectGroup = styleProps.find((p) => p.itemKey === 'rect')
+    const rectChildren = (rectGroup && rectGroup.itemChildren && rectGroup.itemChildren.properties) || []
+    const widthChild = rectChildren.find((c) => c.itemKey === 'width')
+    const shrinkChild = flexChildren.find((c) => c.itemKey === 'flexShrink')
+    const widthVal = widthChild ? String(widthChild.itemValue) : ''
+    const heightChild = rectChildren.find((c) => c.itemKey === 'height')
+    const childRows = (n.slots || []).some((slot) =>
+      (slot.components || []).some((child) => child.className === 'Row'))
+    const isProgressBarTrack = cls === 'Row' && childRows
+      && Number(heightChild?.itemValue || 0) > 0 && Number(heightChild.itemValue) <= 8
+
+    // R22: width:100% 且 flexShrink:0 → 锁死协商，固定宽兄弟会被挤出
+    if (widthVal === '100%') {
+      if (shrinkChild && String(shrinkChild.itemValue) === '0' && !isProgressBarTrack) {
+        out.push({
+          severity: 'error',
+          code: 'r22-width100-flexshrink0',
+          componentId: cid,
+          message: `${cls} "${cid}" width:100% 且 flexShrink:0 → 协商锁死，固定宽兄弟（图标/金额/按钮）会被挤出或溢出（R22）。width:100% 应配 flexShrink:1 让位`,
+        })
+      }
+    }
+
+    // R17（修订）：仅对「单子容器」中的叶子节点强制 flexShrink:0。
+    //   多子容器（2+ 并列子节点）中的叶子由 R34 管辖（至少一个可压缩防溢出），不重复报 R17。
+    if (RENDER_CONTRACT.leafClasses.includes(cls) && widthVal !== '100%') {
+      const siblings = parent ? (parentChildrenMap.get(parent.componentId) || []) : []
+      const isMultiChildParent = siblings.length >= 2
+      if (!isMultiChildParent && (!shrinkChild || String(shrinkChild.itemValue) !== '0')) {
+        out.push({
+          severity: 'error',
+          code: 'r17-leaf-no-flexshrink',
+          componentId: cid,
+          message: `${cls} "${cid}" 未设 flexShrink:0 → 渲染器默认 flexShrink:1 会导致元素被压缩（文本换行/图标变形）（R17）。单子容器中的叶子节点必须显式设 flexShrink:0`,
+        })
+      }
+    }
+  })
+
+  // R8: 圆角归属（纯色卡外圆角放 Root，分层卡放内卡，不重复）
+  {
+    const rootStyleProps = (view.style && view.style.properties) || []
+    const rootRadiusGroup = rootStyleProps.find((p) => p.itemKey === 'borderRadius')
+    const rootRadiusChild = rootRadiusGroup && (rootRadiusGroup.itemChildren && rootRadiusGroup.itemChildren.properties || []).find((c) => c.itemKey === 'borderRadius')
+    const rootRadius = rootRadiusChild ? parseFloat(rootRadiusChild.itemValue) : 0
+
+    if (rootRadius > 0) {
+      // Root 有圆角 → 检查第一层子容器是否也设了相同圆角（双重圆角）
+      const rootSlots = view.slots || []
+      let checked = 0
+      for (const slot of rootSlots) {
+        const comps = (slot.components) || []
+        for (const comp of comps.slice(0, 3)) { // 只查前 3 个一级子容器
+          const childStyle = (comp.style && comp.style.properties) || []
+          const childRadiusGroup = childStyle.find((p) => p.itemKey === 'borderRadius')
+          if (childRadiusGroup) {
+            const childRadiusChild = (childRadiusGroup.itemChildren && childRadiusGroup.itemChildren.properties || []).find((c) => c.itemKey === 'borderRadius')
+            const childRadius = childRadiusChild ? parseFloat(childRadiusChild.itemValue) : 0
+            if (childRadius > 0 && Math.abs(childRadius - rootRadius) < 1) {
+              out.push({
+                severity: 'info',
+                code: 'r8-double-border-radius',
+                componentId: comp.componentId || '?',
+                message: `Root 圆角=${rootRadius}，一级子容器 "${comp.componentId}" 也设了相同圆角=${childRadius}（R8）。纯色卡外圆角只放 Root，内层容器应透明且不重复圆角`,
+              })
+            }
+          }
+          checked++
+        }
+        if (checked >= 3) break
+      }
+    }
+  }
+
+  // R19: Row + justifyContent:space-between 但宽度不确定 → 收缩到内容宽，space-between 失效
+  //
+  // 判「宽度不确定」需同时看自身 rect.width 与父容器交叉轴行为，否则全是误报：
+  //  1. 自身已给确定宽度（100% 或定宽 px，如 transferPlan 两个 100px 日期胶囊并排在横向 Row 里）
+  //     → 容器宽度可定，space-between 在该宽度内正常生效，不是缺陷；改成 100% 反而会溢出。
+  //  2. 自身未设宽但父容器是纵向流且交叉轴 stretch（Column/Root/SingleColumn 的 CSS 已强制
+  //     flex-direction:column，align-items 缺省即 stretch，见 preview/styles/components.css）
+  //     → 子 Row 本就被拉伸到父内容宽，space-between 已生效，无需显式补 width:100%。
+  //     （补了反而撞 r22-width100-flexshrink0 / r35-multi-child-all-shrink0 两条 ERROR。）
+  // 只有「未设宽/auto 且父容器不拉伸」——典型是嵌在横向 Row 里——才会收缩到内容宽、
+  // 子节点堆在左侧，这才是 R19 要拦的真缺陷。
+  const COLUMN_FLOW = new Set(['Root', 'Column', 'SingleColumn'])
+  const flexSub = (node, key) => {
+    const g = (node?.style?.properties || []).find((p) => p.itemKey === 'flex')
+    const c = ((g?.itemChildren?.properties) || []).find((x) => x.itemKey === key)
+    return String(c?.itemValue ?? '').trim()
+  }
+  const stretchedByParent = (parent) => {
+    if (!parent) return true // 根层级由卡片宽度决定
+    // Column/Root/SingleColumn 由 CSS 强制 column；其余（Row/MultiColumn/GridLayout/ListLayout 项…）
+    // 默认横向流，schema 显式写了 flexDirection 才以其为准
+    const dir = COLUMN_FLOW.has(parent.className) ? 'column' : (flexSub(parent, 'flexDirection') || 'row')
+    if (dir !== 'column') return false
+    const align = flexSub(parent, 'alignItems')
+    return align === '' || align === 'stretch'
+  }
+
+  walk(view, (n, parent) => {
+    const cid = n.componentId || '(root)'
+    if (n.className !== 'Row') return
+    const styleProps = (n.style && n.style.properties) || []
+    const flexGroup = styleProps.find((p) => p.itemKey === 'flex')
+    const flexChildren = (flexGroup && flexGroup.itemChildren && flexGroup.itemChildren.properties) || []
+    const justifyChild = flexChildren.find((c) => c.itemKey === 'justifyContent')
+    const rectGroup = styleProps.find((p) => p.itemKey === 'rect')
+    const rectChildren = (rectGroup && rectGroup.itemChildren && rectGroup.itemChildren.properties) || []
+    const widthChild = rectChildren.find((c) => c.itemKey === 'width')
+
+    if (justifyValue(justifyChild) === 'space-between') {
+      const widthVal = widthChild ? String(widthChild.itemValue ?? '').trim() : ''
+      if ((widthVal === '' || widthVal === 'auto') && !stretchedByParent(parent)) {
+        out.push({
+          severity: 'warn',
+          code: 'r19-space-between-no-width',
+          componentId: cid,
+          message: `Row "${cid}" 设了 justifyContent:space-between 但 width=${widthVal || '(未设)'}，且父容器 ${parent ? `${parent.className} "${parent.componentId || '(root)'}" 不拉伸交叉轴` : ''} —— 渲染器按 auto 处理会收缩到内容宽，space-between 失效、子节点堆在左侧（R19）。须显式 rect.width:"100%"（itemValueFrom:"0"）撑满父级主轴。`,
+        })
+      }
+    }
+  })
+
+
+  // ── 格式铁律：值格式校验（生成器最常犯的格式错误） ──
+
+  // R-FMT1: borderRadius 值不得用元组格式 {a,b,c,d}（应为标量 "12" 或单独角 borderTopLeftRadius 等）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    const styleProps = (n.style && n.style.properties) || []
+    const radiusGroup = styleProps.find((p) => p.itemKey === 'borderRadius')
+    if (radiusGroup) {
+      const children = (radiusGroup.itemChildren && radiusGroup.itemChildren.properties) || []
+      const radiusChild = children.find((c) => c.itemKey === 'borderRadius')
+      if (radiusChild && typeof radiusChild.itemValue === 'string'
+          && radiusChild.itemValue.includes('{') && radiusChild.itemValue.includes('}')) {
+        out.push({
+          severity: 'error',
+          code: 'fmt-border-radius-tuple',
+          componentId: cid,
+          message: `${n.className} "${cid}" borderRadius 值用了元组格式 "${radiusChild.itemValue}" —— 应为标量（如 "12"）或单独角属性（borderTopLeftRadius/borderTopRightRadius/borderBottomRightRadius/borderBottomLeftRadius）。元组格式渲染器无法解析`,
+        })
+      }
+    }
+  })
+
+  // R-FMT2: padding 值不得用元组格式 {top,right,bottom,left}（应拆为单独属性 paddingTop/Right/Bottom/Left）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    const styleProps = (n.style && n.style.properties) || []
+    const paddingGroup = styleProps.find((p) => p.itemKey === 'padding')
+    if (paddingGroup) {
+      const children = (paddingGroup.itemChildren && paddingGroup.itemChildren.properties) || []
+      const padChild = children.find((c) => c.itemKey === 'padding')
+      if (padChild && typeof padChild.itemValue === 'string'
+          && padChild.itemValue.includes('{') && padChild.itemValue.includes('}')) {
+        out.push({
+          severity: 'error',
+          code: 'fmt-padding-tuple',
+          componentId: cid,
+          message: `${n.className} "${cid}" padding 值用了元组格式 "${padChild.itemValue}" —— 应拆为 paddingTop/paddingRight/paddingBottom/paddingLeft 各设单值（paddingType="1"）。元组格式会导致预览器解析失败（文本塌缩/行宽爆裂）`,
+        })
+      }
+      const marginChild = children.find((c) => c.itemKey === 'margin')
+      if (marginChild && typeof marginChild.itemValue === 'string'
+          && marginChild.itemValue.includes('{') && marginChild.itemValue.includes('}')) {
+        out.push({
+          severity: 'error',
+          code: 'fmt-margin-tuple',
+          componentId: cid,
+          message: `${n.className} "${cid}" margin 值用了元组格式 "${marginChild.itemValue}" —— 应拆为 marginTop/marginRight/marginBottom/marginLeft 各设单值（marginType="1"）`,
+        })
+      }
+    }
+  })
+
+  // R38: 负 marginTop 禁止 —— 标题/文本与装饰条重叠必须用 AbsoluteLayout，不得用负外边距
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const sg of (n.style?.properties || [])) {
+      if (sg.itemKey !== 'margin') continue
+      const children = sg.itemChildren?.properties || []
+      for (const mc of children) {
+        if (mc.itemKey === 'marginTop' && typeof mc.itemValue === 'string' && mc.itemValue.startsWith('-')) {
+          out.push({
+            severity: 'error',
+            code: 'r38-negative-margin',
+            componentId: cid,
+            message: `${n.className} "${cid}" marginTop=${mc.itemValue} 是负值 —— 文本与下划线/装饰条重叠必须用 AbsoluteLayout + position.top 实现，禁止负外边距（R38）。`,
+          })
+        }
+      }
+    }
+  })
+
+  // R44: 类型+值成对检查 —— 有值但缺类型开关的样式组（borderRadius/border/shadow）→ ERROR
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const sg of (n.style?.properties || [])) {
+      const children = sg.itemChildren?.properties || []
+      if (sg.itemKey === 'borderRadius') {
+        const radius = children.find((c) => c.itemKey === 'borderRadius')
+        const radiusType = children.find((c) => c.itemKey === 'borderRadiusType')
+        if (radius && radius.itemValue && (!radiusType || !radiusType.itemValue || radiusType.itemValue === '')) {
+          out.push({
+            severity: 'error',
+            code: 'r44-border-radius-no-type',
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 borderRadius=${radius.itemValue} 但缺 borderRadiusType —— 渲染器默认类型为空（=无圆角），值被静默忽略。须配 borderRadiusType:"0"（全角）。`,
+          })
+        }
+      }
+      if (sg.itemKey === 'border') {
+        const borderColor = children.find((c) => c.itemKey === 'borderColor')
+        const borderWidth = children.find((c) => c.itemKey === 'borderWidth')
+        const isBorder = children.find((c) => c.itemKey === 'isBorder')
+        if ((borderColor?.itemValue || borderWidth?.itemValue) && (!isBorder || isBorder.itemValue !== '1')) {
+          out.push({
+            severity: 'error',
+            code: 'r44-border-no-isborder',
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 borderColor/borderWidth 但 isBorder≠"1" —— 边框值被渲染器忽略。须配 isBorder:"1"。`,
+          })
+        }
+      }
+      // R44 扩展：margin / padding 的「类型开关」—— 设了单边值但 marginType/paddingType≠"1"
+      // ⇒ 渲染器按默认类型忽略整组边距。实测事故（all-components-test 07 画板）：
+      //    6 处 margin 组漏 marginType:"1" → 卡片塌掉 86px（match 卡 73%），模型连调 9 轮
+      //    iterate 都没定位到，最后靠 diff_bands 才发现。generation_pitfalls.md §「类型开关+值」
+      //    早有铁律，但散文在步数压力下不会被读到 —— 这里做成机器门禁。
+      if (sg.itemKey === 'margin' || sg.itemKey === 'padding') {
+        const typeKey = `${sg.itemKey}Type`
+        const typeChild = children.find((c) => c.itemKey === typeKey)
+        const sides = ['Top', 'Right', 'Bottom', 'Left']
+          .map((d) => children.find((c) => c.itemKey === `${sg.itemKey}${d}`))
+          .filter((c) => c && ['', '0', '0px', undefined, null].indexOf(String(c.itemValue ?? '').trim()) < 0)
+        if (sides.length && String(typeChild?.itemValue ?? '') !== '1') {
+          out.push({
+            severity: 'error',
+            code: `r44-${sg.itemKey}-no-type`,
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 ${sides.map((c) => `${c.itemKey}=${c.itemValue}`).join(' / ')} 但 ${typeKey}="${typeChild?.itemValue ?? '(缺)'}" —— 渲染器按默认类型忽略整组边距（间距静默失效 / 高度塌缩）。须配 ${typeKey}:"1"（IR 写法 s.${sg.itemKey}.${typeKey}:"1"；expand_ir 已自动补，出现本条说明是手写 schema 或显式写了错误类型）`,
+          })
+        }
+      }
+      // R44 扩展：background 的「类型开关 + 值」配对，以及「渐变塞错字段」
+      //   实测事故：模型想还原设计稿顶部渐变，先猜 backgroundType:"02"+gradientColor/gradientDirection
+      //   （02 是图片类型、gradientColor 根本不是 DSL 键），再把 linear-gradient(...) 塞进 backgroundColor，
+      //   三次全部静默失效 → 放弃并编造「顶部蓝条是渲染器标注、属测量噪声」收尾。
+      //   正路：backgroundType:"03" + backgroundGradient（references/spec_to_schema_patterns.md §背景类型表）。
+      if (sg.itemKey === 'background') {
+        const bgType = String(children.find((c) => c.itemKey === 'backgroundType')?.itemValue ?? '')
+        const colorChild = children.find((c) => c.itemKey === 'backgroundColor')
+        const gradChild = children.find((c) => c.itemKey === 'backgroundGradient')
+        const imgChild = children.find((c) => c.itemKey === 'backgroundImage')
+        const colorVal = String(colorChild?.itemValue ?? '')
+        if (/gradient\s*\(/i.test(colorVal)) {
+          out.push({
+            severity: 'error',
+            code: 'r44-gradient-in-background-color',
+            componentId: cid,
+            message: `${n.className} "${cid}" 把渐变写进了 backgroundColor="${colorVal.slice(0, 60)}" —— 渲染器只接受颜色值，渐变会被忽略（背景变透明/纯色）。渐变须写 backgroundGradient + backgroundType:"03"`,
+          })
+        }
+        if (gradChild?.itemValue && bgType !== '03') {
+          out.push({
+            severity: 'error',
+            code: 'r44-background-type-mismatch',
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 backgroundGradient 但 backgroundType="${bgType || '(缺)'}" —— 渐变被忽略。backgroundType 取值：00 透明 / 01 颜色 / 02 图片 / 03 渐变（渐变必须 03）`,
+          })
+        }
+        if (imgChild?.itemValue && bgType !== '02') {
+          out.push({
+            severity: 'error',
+            code: 'r44-background-type-mismatch',
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 backgroundImage 但 backgroundType="${bgType || '(缺)'}" —— 图片背景被忽略。backgroundType 必须为 "02"（02 是图片，不是渐变）`,
+          })
+        }
+        if (bgType === '03' && !gradChild?.itemValue) {
+          out.push({
+            severity: 'error',
+            code: 'r44-background-type-mismatch',
+            componentId: cid,
+            message: `${n.className} "${cid}" backgroundType="03"（渐变）但没设 backgroundGradient —— 背景渲染为空。补 backgroundGradient:"linear-gradient(...)"，或改回 01 + backgroundColor`,
+          })
+        }
+        if (bgType === '02' && !imgChild?.itemValue) {
+          out.push({
+            severity: 'error',
+            code: 'r44-background-type-mismatch',
+            componentId: cid,
+            message: `${n.className} "${cid}" backgroundType="02"（图片）但没设 backgroundImage —— 背景渲染为空。图片背景补 backgroundImage（远程 URL / @filestore 别名），纯色改 01，渐变改 03`,
+          })
+        }
+      }
+      if (sg.itemKey === 'shadow') {
+        const shadowColor = children.find((c) => c.itemKey === 'shadowColor')
+        const isShadow = children.find((c) => c.itemKey === 'isShadow')
+        if (shadowColor?.itemValue && (!isShadow || isShadow.itemValue !== '1')) {
+          out.push({
+            severity: 'error',
+            code: 'r44-shadow-no-isshadow',
+            componentId: cid,
+            message: `${n.className} "${cid}" 设了 shadowColor 但 isShadow≠"1" —— 阴影值被渲染器忽略。须配 isShadow:"1"。`,
+          })
+        }
+      }
+    }
+  })
+
+  // R-KEY: style 组内的「自造键 / 缩写键」—— style-meta 没这个 itemKey ⇒ itemId 落空 ⇒
+  //   运行时静默丢弃该属性。validate_schema.py 对子节点已报 ERROR，但 Root（view）历史上不过检，
+  //   lint 这里对全树（含 Root）统一拦一次，并直接列出该组的合法键，省掉模型再去翻 style-meta。
+  {
+    const styleMaps = loadStyleMaps()
+    walk(view, (n) => {
+      const cid = n.componentId || '(root)'
+      for (const sg of (n.style?.properties || [])) {
+        const allowed = styleMaps[sg.itemKey]
+        if (!allowed) continue
+        for (const child of (sg.itemChildren?.properties || [])) {
+          const ck = child.itemKey
+          if (ck == null || allowed[ck] != null) continue
+          out.push({
+            severity: 'error',
+            code: 'unknown-style-child',
+            componentId: cid,
+            message: `${n.className} "${cid}" 的 style.${sg.itemKey} 写了不存在的键 "${ck}" —— 渲染器静默丢弃（itemId 落空）。该组合法键：${Object.keys(allowed).join(' / ')}（键名以 preview/meta/style-meta.json 原文为准，禁自造 / 缩写）`,
+          })
+        }
+      }
+    })
+  }
+
+  // R50: slotScope 内绑定用 $field 而非 $$.field（$$ 是整个 item 对象，$$.field 冗余）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const p of (n.properties || [])) {
+      const val = String(p.itemValue || '')
+      if (val.includes('$$.')) {
+        out.push({
+          severity: 'error',
+          code: 'r50-dollar-dollar-field',
+          componentId: cid,
+          message: `${n.className} "${cid}" 绑定含 "$$.xxx" —— slotScope 内应直接用 $fieldName（当前 item 字段已展开到作用域），$$ 仅引用整个 item 对象，$$.field 是冗余写法。改为 $field。`,
+        })
+      }
+    }
+  })
+
+  // R51: customAction 里 this.data 只允许读 Input 绑定键的实时输入值；运行态变量一律 this.state
+  const inputBoundKeys = new Set()
+  walk(view, (n) => {
+    if (n.className !== 'Input') return
+    for (const p of n.properties || []) {
+      if (p.itemKey === 'value' && String(p.itemValueFrom) === '1') {
+        const m = /^\$([A-Za-z_$][\w$]*)$/.exec(String(p.itemValue || '').trim())
+        if (m) inputBoundKeys.add(m[1])
+      }
+    }
+  })
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const ea of n.eventactions || []) {
+      const act = ea && ea.action
+      if (!act || act.actionType !== 'customAction') continue
+      const fn = (act.properties || []).find((p) => p.itemKey === 'function') || {}
+      const iv = fn.itemValue || {}
+      const code = String(iv.code || iv.compiled || '')
+      const seen = new Set()
+      for (const m of code.matchAll(/this\.data\.([A-Za-z_$][\w$]*)/g)) {
+        const key = m[1]
+        if (inputBoundKeys.has(key) || seen.has(key)) continue
+        seen.add(key)
+        out.push({
+          severity: 'error',
+          code: 'r51-event-this-data-misuse',
+          componentId: cid,
+          message: `${n.className} "${cid}" customAction 读 this.data.${key} —— this.data 仅允许读 Input 绑定键的实时输入值；运行态变量（选中态/锁定态/派生值等）一律用 this.state.${key}。`,
+        })
+      }
+    }
+  })
+
+  // R52: v-show 显隐设置显示名命名规范（<15 字符与表达式一致；>=15 字符设合适命名，不得抄表达式）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const dr of n.directives || []) {
+      if (dr.itemKey !== 'v-show') continue
+      const props = (dr.itemChildren || {}).properties || []
+      const st = (props.find((p) => p.itemKey === 'showType') || {}).itemValue
+      const cond = (props.find((p) => p.itemKey === 'condition') || {}).itemValue
+      if (st !== '01' && st !== '02') continue
+      if (!cond || typeof cond !== 'object' || !cond.expression) continue
+      const expr = String(cond.expression)
+      const name = cond.name == null ? '' : String(cond.name)
+      if (!name.trim()) continue // 缺失/空由 validate_schema.py 报 ERROR
+      if (expr.length < 15 && name !== expr) {
+        out.push({
+          severity: 'warn',
+          code: 'r52-vshow-condition-name-style',
+          componentId: cid,
+          message: `${n.className} "${cid}" v-show 显示名 "${name}" 与表达式不一致 —— 表达式 ${expr.length} 字符（<15）时显示名应与表达式保持一致：${expr}`,
+        })
+      } else if (expr.length >= 15 && name === expr) {
+        out.push({
+          severity: 'warn',
+          code: 'r52-vshow-condition-name-style',
+          componentId: cid,
+          message: `${n.className} "${cid}" v-show 表达式 ${expr.length} 字符（>=15）但显示名抄了表达式 —— 应设置合适的短命名（如「最后一项隐藏分割线」）`,
+        })
+      }
+    }
+  })
+
+  // R53: 特殊节点（MultiColumn/ListLayout/GridLayout/AbsoluteLayout/Canvas/Map/Video/ViewContainer）禁止直接设 v-show —— 外套一层 Row/Column 承载显隐条件（铁律）
+  const VSHOW_WRAP_REQUIRED = new Set(['MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'Map', 'Video', 'ViewContainer'])
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    if (!VSHOW_WRAP_REQUIRED.has(n.className)) return
+    const hasCondVshow = (n.directives || []).some((d) => d.itemKey === 'v-show'
+      && ((d.itemChildren || {}).properties || []).some((p) => p.itemKey === 'showType' && (p.itemValue === '01' || p.itemValue === '02')))
+    if (hasCondVshow) {
+      out.push({
+        severity: 'error',
+        code: 'r53-vshow-needs-wrapper',
+        componentId: cid,
+        message: `${n.className} "${cid}" 直接设置 v-show 显隐条件 —— 铁律：多列/列表/网格/绝对布局、Canvas、Map、Video、自定义节点需设显示条件时，必须外套一层 Row/Column 并把 v-show 设在包裹层；其他节点可直接设置`,
+      })
+    }
+  })
+
+  // R54: ListLayout/GridLayout item 事件修改绑定数据必须走 postMessage('globalSet') + 根节点 onReady addEventListener 监听（铁律，范式见 recipes.md §4 / depositFilter）
+  const codeOf = (ea) => {
+    const fn = ((ea || {}).action || {}).properties || []
+    const f = fn.find((x) => x.itemKey === 'function') || {}
+    return String((f.itemValue || {}).code || (f.itemValue || {}).compiled || '')
+  }
+  const MUTATE_RE = /this\.(setData|setRootData)\(|this\.(state|data)\.[\w$.]+\s*=[^=]/
+  walk(view, (n, parent) => {
+    let scoped = false
+    for (let cur = n; cur; cur = cur.__lintParent) {
+      if (cur.__lintSlotScope) { scoped = true; break }
+    }
+    if (!scoped) return
+    if (n.className === 'ListLayout' || n.className === 'GridLayout') return
+    const cid = n.componentId || '(root)'
+    for (const ea of n.eventactions || []) {
+      if (((ea || {}).action || {}).actionType !== 'customAction') continue
+      const code = codeOf(ea)
+      if (MUTATE_RE.test(code)) {
+        out.push({
+          severity: 'error',
+          code: 'r54-list-item-must-postmessage',
+          componentId: cid,
+          message: `${n.className} "${cid}" 在列表/网格 item 事件里直接修改绑定数据 —— 铁律：应 this.postMessage('globalSet', {key, value}) 透传，由根节点 onReady 的 addEventListener('globalSet') 监听代改（范式见 recipes.md §4 / depositFilter）`,
+        })
+      }
+    }
+  }, true)
+  // R54-b: 用了 globalSet 透传但根节点 onReady 没注册监听 → 消息石沉大海
+  const allCode = []
+  let rootOnReadyCode = ''
+  walk(view, (n) => {
+    for (const ea of n.eventactions || []) {
+      const code = codeOf(ea)
+      if (!code) continue
+      allCode.push(code)
+      if (n.className === 'Root' && ((ea || {}).event || {}).eventKey === 'onReady') rootOnReadyCode += code
+    }
+  })
+  if (allCode.some((c) => /postMessage\(\s*['"]globalSet['"]/.test(c)) && !/addEventListener\(\s*['"]globalSet['"]/.test(rootOnReadyCode)) {
+    out.push({
+      severity: 'error',
+      code: 'r54-globalset-no-root-listener',
+      componentId: view.componentId || '(root)',
+      message: `卡片使用 postMessage('globalSet') 透传，但根节点 onReady 未 addEventListener('globalSet') 注册监听 —— 消息无人消费；先在根节点初始化事件绑定监听（范式见 recipes.md §4）`,
+    })
+  }
+
+  // R55: customAction 事件脚本禁止出现 $$（铁律）—— slotScope item 字段已展开到 this.state，
+  //      this.state.<field> 直接可读（这是平台保证，不是需要兜底判断的不确定行为）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const ea of n.eventactions || []) {
+      if (((ea || {}).action || {}).actionType !== 'customAction') continue
+      const code = codeOf(ea)
+      if (!code.includes('$$')) continue
+      out.push({
+        severity: 'error',
+        code: 'r55-event-no-dollar-dollar',
+        componentId: cid,
+        message: `${n.className} "${cid}" 事件脚本出现 "$$" —— 铁律：customAction 里 slotScope 当前 item 的字段已展开到 this.state，直接 this.state.<field> 读取（如 this.state.query）；禁止 $$ / this.state.$$ / $$.field 及任何 "$$ 兜底判断" 写法`,
+      })
+    }
+  })
+
+  // R56: 事件脚本调 JSAPI 直接 ynet.callJSAPI(...)（铁律）—— ynet 由平台注入为全局，
+  //      禁止 window.ynet 前缀与 typeof window / window.ynet 存在性守卫（导出卡全量裸调为证）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    for (const ea of n.eventactions || []) {
+      if (((ea || {}).action || {}).actionType !== 'customAction') continue
+      const code = codeOf(ea)
+      if (!/window\.ynet|typeof window/.test(code)) continue
+      out.push({
+        severity: 'error',
+        code: 'r56-jsapi-no-window-guard',
+        componentId: cid,
+        message: `${n.className} "${cid}" 事件脚本用 window.ynet 前缀或 typeof window 存在性守卫调 JSAPI —— 铁律：ynet 由平台注入为全局，事件里直接 ynet.callJSAPI(name, params, cb)，不需要 window. 前缀，也不需要任何存在性判断`,
+      })
+    }
+  })
+
+  // R57: 透明度（other.opacity）禁止用表达式/绑定 —— 移动端渲染不支持透明度表达式，
+  //      必须走「透明度切换固定范式」：按用到的透明度取值生成 N 个静态变体节点，
+  //      统一套进一层与原节点等宽高 + overflow:hidden 的 Row/Column 容器，
+  //      事件挂在容器上，变体用 v-show 互斥显隐实现视觉上的透明度切换。
+  //      见 references/recipes.md §17 + recipe_snippets/opacity-switch.json
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    const otherGroup = ((n.style || {}).properties || []).find((p) => p.itemKey === 'other')
+    const opacityChild = (((otherGroup || {}).itemChildren || {}).properties || []).find(
+      (c) => c.itemKey === 'opacity'
+    )
+    if (!opacityChild) return
+    const isExpr =
+      opacityChild.itemValueFrom === '1' ||
+      (typeof opacityChild.itemValue === 'string' && opacityChild.itemValue.includes('$'))
+    if (!isExpr) return
+    out.push({
+      severity: 'error',
+      code: 'r57-opacity-expression',
+      componentId: cid,
+      message: `${n.className} "${cid}" 的 other.opacity 用了表达式/绑定（"${opacityChild.itemValue}"）—— 移动端渲染不支持透明度表达式（R57 铁律）。改用透明度切换固定范式：按用到的透明度取值生成等量静态变体节点（opacity 写常量），外套一层与原节点等宽高且 overflow:hidden 的 Row/Column 容器，点击等事件移到容器上，变体之间用互斥 v-show 显隐切换。详见 references/recipes.md §17`,
+    })
+  })
+
+  // R-FMT3: Icon 必须有 click eventaction  // R-FMT3: Icon 必须有 click eventaction（否则 onClick 双触发，见 rules.md §九）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    if (n.className === 'Icon') {
+      const hasClick = (n.eventactions || []).some(
+        (ea) => ea && ea.event && ea.event.eventKey === 'click'
+      )
+      if (!hasClick) {
+        out.push({
+          severity: 'error',
+          code: 'icon-no-click',
+          componentId: cid,
+          message: `Icon "${cid}" 没有 click 事件 —— Icon 不绑定 click 会导致 onClick 双触发（rules.md §九）。即使当前无交互也必须声明 click eventaction`,
+        })
+      }
+    }
+  })
+
+  // R-FMT4: MultiText itemList 项的 itemValueFrom:"1" 必须带 itemDefaultValue（渲染 undefined 兜底）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    if (n.className === 'MultiText') {
+      const textListProp = (n.properties || []).find((p) => p.itemKey === 'textList')
+      if (textListProp && textListProp.itemList) {
+        for (const item of textListProp.itemList) {
+          const itemProps = (item.properties) || []
+          for (const sp of itemProps) {
+            if (sp.itemValueFrom === '1' && sp.itemKey === 'value' && !('itemDefaultValue' in sp)) {
+              out.push({
+                severity: 'error',
+                code: 'multitext-item-no-default',
+                componentId: cid,
+                message: `MultiText "${cid}" 的 itemList 项 value 绑定（itemValueFrom:"1"）缺 itemDefaultValue —— 渲染时 binding undefined 会显示空（rules.md §三）`,
+              })
+            }
+          }
+        }
+      }
+    }
+  })
+
+  // R9/R10: 卡片根节点（view）不得设四周 padding/margin（裁切后间距归零铁律）
+  {
+    const rootStyleProps = (view.style && view.style.properties) || []
+    for (const sp of rootStyleProps) {
+      if (sp.itemKey === 'padding' || sp.itemKey === 'margin') {
+        const children = (sp.itemChildren && sp.itemChildren.properties) || []
+        for (const k of children) {
+          if (k.itemKey !== sp.itemKey + 'Type' && k.itemValue) {
+            const val = String(k.itemValue)
+            if (val !== '0' && val !== '') {
+              out.push({
+                severity: 'error',
+                code: 'r9-root-nonzero-padding',
+                componentId: '(view)',
+                message: `view（Root）设了 ${sp.itemKey}.${k.itemKey}="${val}" —— 裁切后间距归零铁律（R9/R10）：卡片根节点不设任何四周 padding/margin，间距下沉到内层内容容器`,
+              })
+            }
+          }
+        }
+      }
+    }
+  }
+
+
+  // R-FMT5: Image 静态路径（不以 $ 开头、不含表达式）用 itemValueFrom:"1" → 应为 "2"（图片值）
+  walk(view, (n) => {
+    const cid = n.componentId || '(root)'
+    if (n.className === 'Image') {
+      const valProp = (n.properties || []).find((p) => p.itemKey === 'value')
+      if (valProp && valProp.itemValueFrom === '1') {
+        const val = String(valProp.itemValue || '')
+        // 不是变量表达式（不以 $ 开头、不含 ? : 三元）→ 静态路径，应该用 "2"
+        if (!val.startsWith('$') && !val.includes('?')) {
+          out.push({
+            severity: 'error',
+            code: 'fmt-image-static-path-valuefrom',
+            componentId: cid,
+            message: `Image "${cid}" value="${val}" 用了 itemValueFrom:"1"（变量/表达式），但这是静态图片路径，应改为 itemValueFrom:"2"（图片/文件值）。itemValueFrom:"1" 会把路径当表达式解析，渲染器找不到变量导致破图`,
+          })
+        }
+      }
+    }
+  })
+
+  // R42: 标题+下划线/装饰条拓扑（export-proven title-underline-overlay）
+  // AbsoluteLayout 必须显式 align:BottomLeft；装饰条先绘制、标题后绘制；宽度建议随标题长度表达式变化。
+  walk(view, (n) => {
+    if (n.className !== 'AbsoluteLayout') return
+    const cid = n.componentId || '(root)'
+    const children = directChildren(n)
+    const textIndex = children.findIndex((c) => c.className === 'Text')
+    const decorationIndex = children.findIndex((c) => {
+      if (!c) return false
+      if (c.className === 'Divider') return true
+      if (c.className !== 'Row') return false
+      const background = (c.style?.properties || []).find((p) => p.itemKey === 'background')
+      return Boolean(background)
+    })
+    if (textIndex === -1 || decorationIndex === -1) return
+
+    const align = (n.properties || []).find((p) => p.itemKey === 'align')
+    if (!align || align.itemValue !== 'BottomLeft') {
+      out.push({
+        severity: 'error',
+        code: 'r42-title-underline-align',
+        componentId: cid,
+        message: `AbsoluteLayout "${cid}" 包含标题+装饰条但未设 align:"BottomLeft" —— 后续兄弟会感知装饰条高度，破坏标题底部节奏。必须复用 title-underline-overlay 配方。`,
+      })
+    }
+
+    if (decorationIndex > textIndex) {
+      out.push({
+        severity: 'error',
+        code: 'r42-title-underline-z-order',
+        componentId: cid,
+        message: `AbsoluteLayout "${cid}" 中装饰条排在标题之后 —— 下划线会绘制在文字上方。子节点顺序必须为 [装饰条, 标题]。`,
+      })
+    }
+
+    const decoration = children[decorationIndex]
+    const rect = (decoration.style?.properties || []).find((p) => p.itemKey === 'rect')
+    const width = ((rect?.itemChildren?.properties || []).find((p) => p.itemKey === 'width') || {}).itemValue
+    if (!String(width || '').includes('.length *')) {
+      out.push({
+        severity: 'warn',
+        code: 'r42-title-underline-fixed-width',
+        componentId: cid,
+        message: `AbsoluteLayout "${cid}" 的装饰条宽度未绑定标题长度表达式 —— 应使用 $titleVar.length * fontSize，避免标题变化后高亮条宽度不同步。`,
+      })
+    }
+  })
+
+  return out
+}
+
+function justifyValue(node) {
+  if (!node) return ''
+  return String(node.itemValue || '')
+}
+
+/* ------------------------------------------------------------------ */
+/* 渲染                                                                */
+/* ------------------------------------------------------------------ */
+function severityIcon(s) {
+  return s === 'error' ? '❌' : s === 'warn' ? '⚠️ ' : 'ℹ️ '
+}
+
+function renderHuman(reports, id) {
+  const lines = []
+  for (const { id: cardId, findings, error } of reports) {
+    lines.push(`[lint] card=${cardId}`)
+    if (error) {
+      lines.push(`  ❌ 无法体检：${error}`)
+      lines.push('')
+      continue
+    }
+    if (!findings.length) {
+      lines.push(`  ✅ 无 lint 报警`)
+    } else {
+      const bySev = { error: 0, warn: 0, info: 0 }
+      for (const f of findings) bySev[f.severity]++
+      lines.push(`  共 ${findings.length} 条：${bySev.error} error / ${bySev.warn} warn / ${bySev.info} info`)
+      for (const f of findings) {
+        const cid = f.componentId ? ` [${f.componentId}]` : ''
+        lines.push(`  ${severityIcon(f.severity)} ${f.code}${cid}: ${f.message}`)
+      }
+    }
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+/* ------------------------------------------------------------------ */
+/* main                                                                */
+/* ------------------------------------------------------------------ */
+function lintOne(id) {
+  const sp = cardSchemaPath(id)
+  const dp = cardDataPath(id)
+  if (!fs.existsSync(sp)) throw new Error(`卡片不存在: ${sp}`)
+  const schema = readJson(sp)
+  const data = fs.existsSync(dp) ? readJson(dp, {}) : {}
+  return { id, findings: lint(schema, data) }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const ids = args.all
+    ? fs.readdirSync(cardsDir).filter((d) => fs.existsSync(cardSchemaPath(d)))
+    : [args.id]
+
+  const reports = []
+  for (const id of ids) {
+    try {
+      reports.push(lintOne(id))
+    } catch (e) {
+      reports.push({ id, error: e.message })
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ reports }, null, 2))
+  } else {
+    console.log(renderHuman(reports))
+  }
+
+  const hasError = reports.some((r) => r.findings && r.findings.some((f) => f.severity === 'error'))
+  const hasWarn = reports.some((r) => r.findings && r.findings.some((f) => f.severity === 'warn'))
+  // error 永远卡 CI；warn 仅在 --strict 时卡
+  // 用 exitCode 而非 process.exit()：stdout 是管道时 exit() 会截断未 flush 的大体积 JSON 输出
+  process.exitCode = hasError ? 1 : (hasWarn && args.strict ? 1 : 0)
+}
+
+// 仅当作为 CLI 直接运行时才启动 main()（被 import 时不执行）
+const _thisScript = fs.realpathSync(fileURLToPath(import.meta.url))
+const _invokedAs = (process.argv[1] && fs.existsSync(process.argv[1]))
+  ? fs.realpathSync(process.argv[1])
+  : process.argv[1]
+if (_invokedAs === _thisScript) main()