cardbuddy 0.14.3 → 0.16.0

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

@@ -0,0 +1,166 @@
+/**
+ * rules/registry.mjs —— 卡片门禁规则的**唯一权威注册表**（lint_card / preflight 全体）。
+ *
+ * ── 为什么必须有它 ───────────────────────────────────────────────────────────
+ * `SKILL.md` 与 `generation_pitfalls.md §9` 一直告诉模型「按规则号查文档」，但实测
+ * **lint 的 code 前缀与 pitfalls 的 R 号是两套互不相干的命名空间**，照号查会查到别的规则：
+ *
+ *   code                      | lint 的真实语义              | pitfalls 同号 R 的语义
+ *   --------------------------|------------------------------|--------------------------------
+ *   r50-dollar-dollar-field   | slotScope 用 $field 而非 $$.field | R50 列表项语义边界用实测行高
+ *   r51-event-this-data-misuse| 运行态变量一律 this.state     | R51 垂直节奏优先用 padding
+ *   r57-opacity-expression    | opacity 禁止表达式绑定         | R57 弥散纹理必须按位图还原
+ *   r38-negative-margin       | 负 marginTop 禁止              | R38 容器高度由内容撑开（其实对应 R42）
+ *
+ * 另有约三成 code 根本没有规则号（`icon-no-click` / `unknown-style-child` / `no-view` …），
+ * 查不到任何章节。所以「按号查文档」这条指引是坏的 —— 正确入口是**本注册表**。
+ *
+ * ── 字段 ─────────────────────────────────────────────────────────────────────
+ *   severity  'error' | 'warn' | 'info'   与实现里上报的 severity 一致（由门禁测试对账）
+ *   stage     'lint' | 'preflight' | 'both'  哪几道闸会上报
+ *   doc       '<file>#<anchor>' | null    该规则**真正**的权威文档锚点；null = 尚无对应章节
+ *             anchor 是目标文件里的标题文本前缀（如 'R25' / '九' / '1.1' / '2d'），
+ *             由 tools/tests/lint-rule-registry.test.mjs 机械校验其真实存在。
+ *             文件相对 skills/dsl-card-generator/references/。
+ *
+ * ── 维护约定 ─────────────────────────────────────────────────────────────────
+ *  · 新增/改名 code **必须**同步本表，否则 lint-rule-registry 门禁失败（双向对账）。
+ *  · `doc: null` 的条目数量**只许减不许增**（棘轮）——它代表「这条规则在文档里查不到」。
+ */
+
+/** doc 锚点里文件名的合法取值（避免打错文件名后校验静默变宽松）。 */
+export const DOC_DIR = 'skills/dsl-card-generator/references'
+
+export const RULES = {
+  /* ── 布局 / 尺寸（generation_pitfalls.md 域）──────────────────────── */
+  'r8-double-border-radius': { severity: 'info', stage: 'lint', doc: 'generation_pitfalls.md#R8' },
+  'r9-root-nonzero-padding': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R9' },
+  'r17-leaf-no-flexshrink': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R17' },
+  'r19-space-between-no-width': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#R19' },
+  'r22-width100-flexshrink0': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R22' },
+  'r22b-row-child-container-no-width': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R22' },
+  'r35-multi-child-all-shrink0': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R35' },
+  // 语义是「文本与装饰条重叠禁止用负外边距」= pitfalls R42 的正文，不是 R38（容器高度由内容撑开）。
+  'r38-negative-margin': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R42' },
+
+  /* ── 标题 + 装饰条（ir-format.md §2d 蓝图）──────────────────────── */
+  'r42-title-underline-align': { severity: 'error', stage: 'lint', doc: 'ir-format.md#2d' },
+  'r42-title-underline-z-order': { severity: 'error', stage: 'lint', doc: 'ir-format.md#2d' },
+  'r42-title-underline-fixed-width': { severity: 'warn', stage: 'lint', doc: 'ir-format.md#2d' },
+  'r64-title-underline-flow': { severity: 'error', stage: 'lint', doc: 'ir-format.md#2d' },
+
+  /* ── 图片 / 表达式（R25 R32 R23）────────────────────────────────── */
+  'r23-no-math-round': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R23' },
+  'r25-image-no-value-prop': { severity: 'error', stage: 'preflight', doc: 'generation_pitfalls.md#R25' },
+  'r25-image-from-0': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R25' },
+  'r25-image-from-1': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R25' },
+  'r25-image-from-2': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R25' },
+  'r32-image-no-height': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R32' },
+
+  /* ── 切图引用同源（R31 家族，正文在 pitfalls R31）────────────────── */
+  'r31-slice-filename-space': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R31' },
+  'r31b-slice-url-reserved-char': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R31' },
+  'r31c-slice-ref-missing-file': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R31' },
+  'r59-slice-semantic-name': { severity: 'warn', stage: 'lint', doc: 'slices_convention.md#1.1' },
+  'r60-slice-duplicate-content': { severity: 'warn', stage: 'lint', doc: 'slices_convention.md#3.1' },
+
+  /* ── 组件契约 / 白名单 ──────────────────────────────────────────── */
+  'r28-unknown-class': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#R28' },
+  'r28b-unknown-prop-key': { severity: 'error', stage: 'both', doc: 'component_rules.md#通用规则' },
+  'r28b-unknown-style-group': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#2' },
+  'r28b-unknown-style-key': { severity: 'error', stage: 'both', doc: 'generation_pitfalls.md#2' },
+  'unknown-style-child': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#2' },
+  'missing-itemValueFrom': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#1' },
+  'style-itemId-mismatch': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#2' },
+  'empty-style-itemid': { severity: 'error', stage: 'preflight', doc: 'generation_pitfalls.md#2' },
+
+  /* ── 类型开关（R44 族）─────────────────────────────────────────── */
+  'r44-border-radius-no-type': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-border-no-isborder': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-shadow-no-isshadow': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-gradient-in-background-color': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-background-type-mismatch': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-margin-no-type': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+  'r44-padding-no-type': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R44' },
+
+  /* ── 值格式 ────────────────────────────────────────────────────── */
+  'fmt-border-radius-tuple': { severity: 'error', stage: 'lint', doc: 'ir-format.md#1' },
+  'fmt-padding-tuple': { severity: 'error', stage: 'lint', doc: 'ir-format.md#1' },
+  'fmt-margin-tuple': { severity: 'error', stage: 'lint', doc: 'ir-format.md#1' },
+  'fmt-image-static-path-valuefrom': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R25' },
+
+  /* ── 作用域 / 绑定（rules.md §四 运行时作用域与 Input 回写）──────────
+   * 这一组的规则号（R50 / r51 / r54 / r55 / r56）**只在 rules.md 域有效**：
+   * generation_pitfalls.md 的同号 R50–R56 是训练侧另一套语义（列表项行高 / 状态卡媒体 …），
+   * 照号去 pitfalls 查会查到完全无关的章节。 */
+  'r50-dollar-dollar-field': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r50b-unnormalized-scope-alias': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r51-event-this-data-misuse': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'unused-input-param': { severity: 'info', stage: 'lint', doc: 'rules.md#三' },
+  'text-empty-binding': { severity: 'info', stage: 'lint', doc: 'rules.md#三' },
+
+  /* ── 指令 / 显隐（component_rules.md 域）────────────────────────── */
+  'group-directive-bad-form': { severity: 'error', stage: 'lint', doc: 'component_rules.md#指令' },
+  'r52-vshow-condition-name-style': { severity: 'warn', stage: 'lint', doc: 'component_rules.md#指令' },
+  'r53-vshow-needs-wrapper': { severity: 'error', stage: 'lint', doc: 'rules.md#九' },
+
+  /* ── 事件（rules.md §四 + event_patterns.md 范式）───────────────── */
+  'event-mismatch': { severity: 'warn', stage: 'lint', doc: 'event_patterns.md#eventKey' },
+  'button-no-click': { severity: 'warn', stage: 'lint', doc: 'event_patterns.md#eventKey' },
+  'button-click-by-ancestor': { severity: 'info', stage: 'lint', doc: 'event_patterns.md#eventKey' },
+  'icon-no-click': { severity: 'error', stage: 'lint', doc: 'rules.md#九' },
+  'r54-list-item-must-postmessage': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r54-globalset-no-root-listener': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r55-event-no-dollar-dollar': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r56-jsapi-no-window-guard': { severity: 'error', stage: 'lint', doc: 'rules.md#四' },
+  'r57-opacity-expression': { severity: 'error', stage: 'lint', doc: 'rules.md#九' },
+  'canvas-no-onmeasured': { severity: 'warn', stage: 'lint', doc: 'previewer_contract.md#3' },
+
+  /* ── 数字语义（rules.md §十四）──────────────────────────────────── */
+  'r61-text-numeric-literal': { severity: 'warn', stage: 'lint', doc: 'rules.md#十四' },
+
+  /* ── 数据绑定完备 / 列表数组化（ir-format.md §2f；判定共享 lib/rules/bindings.mjs）── */
+  'binding-repeater-no-scope': { severity: 'error', stage: 'lint', doc: 'ir-format.md#2e' },
+  'binding-array-unconsumed': { severity: 'warn', stage: 'lint', doc: 'ir-format.md#2e' },
+  'binding-list-static-expansion': { severity: 'warn', stage: 'lint', doc: 'ir-format.md#2e' },
+
+  /* ── 水平 margin 撞 width:100%（rules.md §十六 R63）────────────── */
+  'r63-width100-with-hmargin': { severity: 'error', stage: 'lint', doc: 'rules.md#十六' },
+
+  /* ── 卡片根样式 / 元素清单（preflight 生成前检查）───────────────── */
+  'r29-element-count': { severity: 'warn', stage: 'preflight', doc: 'generation_pitfalls.md#R29' },
+  'r30-icon-no-action': { severity: 'warn', stage: 'preflight', doc: 'generation_pitfalls.md#R30' },
+  'r28-row-as-divider': { severity: 'warn', stage: 'preflight', doc: 'generation_pitfalls.md#R28' },
+  'r33-root-missing-border': { severity: 'warn', stage: 'preflight', doc: 'generation_pitfalls.md#R33' },
+  'r33-root-missing-shadow': { severity: 'warn', stage: 'preflight', doc: 'generation_pitfalls.md#R33' },
+  'r43-card-transparent-background': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R43' },
+
+  /* ── 脚手架残留（pitfalls §7 工具链兜底）────────────────────────── */
+  'scaffold-placeholder': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#7' },
+  'scaffold-placeholder-expr': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#7' },
+
+  /* ── 宽度自适应（ir-format.md §2f；判定共享 lib/rules/adaptive-width.mjs）──────── */
+  'r66-fullwidth-px': { severity: 'error', stage: 'lint', doc: 'ir-format.md#2f' },
+
+  /* ── 结构与事件代码（pitfalls 教训沉淀 2026-09-25；判定共享 lib/rules/structure.mjs）── */
+  'r65-slot-multi-children': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#27' },
+  'r34-null-child': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#R34' },
+  'style-duplicate-child': { severity: 'error', stage: 'lint', doc: 'generation_pitfalls.md#20' },
+  'r50c-alertdata-whole-state': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#10' },
+  'r20-icon-no-rect': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#R20' },
+  'r38-root-fixed-height': { severity: 'warn', stage: 'lint', doc: 'generation_pitfalls.md#R38' },
+
+  /* ── 尚无对应文档章节（棘轮：只许减不许增）─────────────────────── */
+  'no-view': { severity: 'error', stage: 'lint', doc: null },
+  'text-no-color': { severity: 'info', stage: 'lint', doc: null },
+  'multitext-item-no-default': { severity: 'error', stage: 'lint', doc: null },
+}
+
+/** 规则总数 / 尚无文档锚点的条目数（门禁棘轮用）。 */
+export function registryStats() {
+  const codes = Object.keys(RULES)
+  const undoc = codes.filter((c) => !RULES[c].doc)
+  const byStage = { lint: 0, preflight: 0, both: 0 }
+  for (const c of codes) byStage[RULES[c].stage] += 1
+  return { total: codes.length, undocumented: undoc.length, undocumentedCodes: undoc.sort(), byStage }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * rules/structure.mjs —— 结构与事件代码的机械判据（pitfalls 教训 → 机器 gate）。
+ *
+ * 2026-09-25 沉淀：generation_pitfalls.md 里「可机械判定、但此前只有文档约束」的 6 条。
+ * 全部消费 walkNodes/hit 工厂（lib/rules/walk.mjs），lint 与 preflight 共享同一实现。
+ *
+ * | code | severity | 来源 | 判定 |
+ * |---|---|---|---|
+ * | r65-slot-multi-children | error | pitfalls §27（汇率卡事故） | slotScope 循环插槽平铺 ≥2 子节点 |
+ * | r34-null-child | error | pitfalls R34 | 组件树含 null/undefined 子节点 |
+ * | style-duplicate-child | error | pitfalls §20.4 | style 组内同名子项重复（渲染器只取其一） |
+ * | r50c-alertdata-whole-state | warn | pitfalls §10（transfersjump 事故） | 子卡 data:this.state 整体回传 / 父卡 state.x=res.data 整体赋值 |
+ * | r20-icon-no-rect | warn | pitfalls R20 | Icon 缺显式 style.rect（默认 32×32） |
+ * | r38-root-fixed-height | warn | pitfalls R38 | 根节点写死 rect.height（应由内容撑开） |
+ */
+import { walkNodes, hit } from './walk.mjs'
+
+/**
+ * §27：slotScope 循环模板的 slot 下禁止平铺 ≥2 个子节点。
+ * slot.components[] 是一个整体模板，会原样套到 value 数组每一项上重复渲染；
+ * 平铺 N 个子节点等价于每个 item 渲染 N 个并列块，行与分隔线互相穿插。
+ */
+export function collectSlotMultiChildren(view) {
+  const out = []
+  walkNodes(view, (n) => {
+    if (n.className !== 'ListLayout' && n.className !== 'GridLayout') return
+    for (const slot of n.slots || []) {
+      if (!slot.slotScope) continue
+      const kids = slot.components || []
+      if (kids.length <= 1) continue
+      const shapes = kids.map((k) => k && k.className).join('/')
+      out.push(hit('r65-slot-multi-children', 'error', n.componentId || '',
+        `${n.className} "${n.componentId || ''}" 的 slotScope 循环插槽平铺了 ${kids.length} 个子节点（${shapes}）—— slot 是整体模板，原样套到每一项重复渲染，平铺等价于每项渲染 ${kids.length} 个并列块、互相穿插错位（pitfalls §27）。正路：全部元素包进一个 Column/Row 容器，slot children 仅此一个容器。`))
+    }
+  })
+  return out
+}
+
+/** R34：组件树禁止出现 null/undefined 子节点（可选 slice 为空时提供占位，禁止 null 进插槽）。 */
+export function collectNullChildren(view) {
+  const out = []
+  walkNodes(view, (n) => {
+    const arrays = [n.components, ...(n.slots || []).map((s) => s && s.components)]
+    for (const arr of arrays) {
+      if (!Array.isArray(arr)) continue
+      const bad = arr.filter((c) => c === null || c === undefined).length
+      if (!bad) continue
+      out.push(hit('r34-null-child', 'error', n.componentId || '',
+        `${n.className || 'view'} "${n.componentId || ''}" 的子组件数组含 ${bad} 个 null/undefined —— 运行期渲染挂起（pitfalls R34：可选 slice 命中但 PNG 未导出时，禁止 imageFromSlice 的 null 直接进插槽，须可见占位或 Icon 兜底）。`))
+    }
+  })
+  return out
+}
+
+/** §20.4：style 组内同名子项唯一 —— 追加第二个同名子项会让渲染器取到空值/绑定串原样。 */
+export function collectDuplicateStyleChildren(view) {
+  const out = []
+  walkNodes(view, (n) => {
+    for (const g of (n.style && n.style.properties) || []) {
+      const seen = new Set()
+      for (const c of (g.itemChildren && g.itemChildren.properties) || []) {
+        if (seen.has(c.itemKey)) {
+          out.push(hit('style-duplicate-child', 'error', n.componentId || '',
+            `${n.className || 'view'} "${n.componentId || ''}" style 组 "${g.itemKey || '?'}" 内存在重复子项 itemKey:"${c.itemKey}" —— 渲染器对同名子项只取其一，绑定值会被空值/静态默认覆盖（pitfalls §20.4：绑定必须改写既有子项，禁止追加）。`))
+        }
+        seen.add(c.itemKey)
+      }
+    }
+  })
+  return out
+}
+
+/**
+ * §10：子卡回传按需裁剪、父卡回调按字段提取。
+ * 子卡侧：`closeAlertCard` 的 `data: this.state` 整体回传 = 整个子卡作用域 + 父卡注入 payload 一起甩给父卡。
+ * 父卡侧：`state.X = res.data`（整体 payload 直接挂 state）—— 只拦精确整体赋值，
+ * `res.data.<字段>` 不拦（无法机械区分字段提取与子对象整体赋值，交给 AI 语义复核）。
+ */
+export function collectAlertDataWholeState(view) {
+  const out = []
+  walkNodes(view, (n) => {
+    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 || '')
+      if (!code) continue
+      if (/closeAlertCard[\s\S]{0,120}data:\s*this\.state\b/.test(code)) {
+        out.push(hit('r50c-alertdata-whole-state', 'warn', n.componentId || '',
+          `${n.className} "${n.componentId || ''}" closeAlertCard 用 data: this.state 整体回传 —— 会把整个子卡作用域 + 父卡注入 payload（list/title/parentInstanceId…）一起甩给父卡，父卡字段错乱（pitfalls §10 transfersjump 事故）。正路：显式构造 data，只含父卡需要的字段（如 data: { selected: { acctNum: this.state.acctNum, … } }）。`))
+      }
+      const m = code.match(/(?:this|that)\.state\.[A-Za-z_$][\w$]*\s*=\s*res\.data\b(?!\s*[.[])/)
+      if (m) {
+        out.push(hit('r50c-alertdata-whole-state', 'warn', n.componentId || '',
+          `${n.className} "${n.componentId || ''}" 父卡回调整体赋值（…${m[0].replace(/\s+/g, ' ')}）—— res.data 未按字段显式提取就挂上 state，子卡回传一旦裁剪/扩容即字段错乱（pitfalls §10）。正路：逐字段提取（that.state.currCard = { acctNum: res.data.selected.acctNum, … }）。`))
+      }
+    }
+  })
+  return out
+}
+
+/** R20：Icon 必须带显式 style.rect（width+height），否则按 svg-symbols 默认尺寸（约 32×32）渲染。 */
+export function collectIconNoRect(view) {
+  const out = []
+  walkNodes(view, (n) => {
+    if (n.className !== 'Icon') return
+    const rect = ((n.style || {}).properties || []).find((g) => g.itemKey === 'rect')
+    const kids = (rect && rect.itemChildren && rect.itemChildren.properties) || []
+    const has = (k) => kids.some((c) => c.itemKey === k && String(c.itemValue ?? '') !== '')
+    if (has('width') && has('height')) return
+    out.push(hit('r20-icon-no-rect', 'warn', n.componentId || '',
+      `Icon "${n.componentId || ''}" 缺显式 style.rect（${!has('width') ? 'width' : ''}${!has('width') && !has('height') ? '+' : ''}${!has('height') ? 'height' : ''}）—— 渲染器按 svg-symbols 默认尺寸（约 32×32）渲染，与设计稿标注不符（pitfalls R20：Icon 尺寸必须读 spec 标注显式写入）。`))
+  })
+  return out
+}
+
+/** R38：根节点高度由内容撑开 —— 写死 rect.height（非 auto/非表达式）在内容行数变化时裁切。 */
+export function collectRootFixedHeight(view) {
+  if (!view || typeof view !== 'object') return []
+  const rect = ((view.style || {}).properties || []).find((g) => g.itemKey === 'rect')
+  const kids = (rect && rect.itemChildren && rect.itemChildren.properties) || []
+  const h = kids.find((c) => c.itemKey === 'height')
+  if (!h || h.itemValueFrom === '1' || h.itemValue == null || String(h.itemValue) === 'auto') return []
+  return [hit('r38-root-fixed-height', 'warn', view.componentId || '',
+    `根节点写死 rect.height="${h.itemValue}" —— 容器高度应由内容撑开（height:auto，纵向尺寸来自子内容 + gap + 标注 padding），写死整卡高度在内容行数变化时裁切或留白（pitfalls R38；禁止为了对齐截图写死整卡高度）。`)]
+}

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

@@ -0,0 +1,61 @@
+/**
+ * rules/walk.mjs —— schema 节点遍历的共享实现（lint_card / preflight / readiness 单一来源）。
+ *
+ * 三个门禁脚本各自有一份 `walk`，签名与遍历序都一致（先 components 再 slots）；
+ * 抽到一处避免「同一个节点集在三处算出不同命中」。
+ */
+
+/**
+ * 深度优先遍历 schema 节点树。
+ * @param {object} node 起始节点（通常 schema.view）
+ * @param {(node: object, parent: object|null) => void} visitor
+ * @param {object|null} parent
+ */
+export function walkNodes(node, visitor, parent = null) {
+  if (!node || typeof node !== 'object') return
+  visitor(node, parent)
+  for (const c of node.components || []) walkNodes(c, visitor, node)
+  for (const s of node.slots || []) for (const c of s.components || []) walkNodes(c, visitor, node)
+}
+
+/** 收集树内全部节点（含起始节点），供只需平铺清单的消费方使用。 */
+export function collectNodes(root) {
+  const out = []
+  walkNodes(root, (n) => out.push(n))
+  return out
+}
+
+/** 默认插槽直接子节点（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 : []
+}
+
+/** 取 component properties 里的某个 itemKey。 */
+export function findProp(node, key) {
+  for (const p of node?.properties || []) if (p.itemKey === key) return p
+  return null
+}
+
+/** 取 style.<group>.<child> 子项节点。 */
+export function findStyleChild(node, group, child) {
+  for (const g of node?.style?.properties || []) {
+    if (g.itemKey !== group) continue
+    for (const c of g.itemChildren?.properties || []) if (c.itemKey === child) return c
+  }
+  return null
+}
+
+/**
+ * 归一化命中对象 —— 各门禁脚本消费同一形状：
+ *   lint_card  → { severity, code, message, componentId }
+ *   preflight  → check(code, severity, message, detail)
+ *
+ * `componentId` 刻意做成**位置参数**：早先放在 extra 里时调用方漏传过一次，
+ * 表现为 lint 报「componentId 为空」而 preflight 毫无察觉（它不消费该字段）。
+ */
+export function hit(code, severity, componentId, message, extra = {}) {
+  return { code, severity, componentId: componentId || '', message, detail: '', ...extra }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * scope_alias.mjs — 列表作用域别名归一化（**唯一实现**，Python 侧 autofix_schema.py 逐条对齐）。
+ *
+ * ── 为什么是「归一化」而不是「报错禁止」 ───────────────────────────────
+ * 2026-09-24 复盘：模型写出 `$item.xxx`，根因不是模型笨 —— 是**我们自己**在系统提示词 /
+ * ir-format.md 里手写了一条不存在的契约（提交 56e9894「子树内 $item.xxx / $_index」）。
+ * 权威证据：全仓 50 张真卡的 ListLayout 插槽内绑定**全部**是扁平字段名（`$name` / `$label` /
+ * `$accountNum` / `$card_name`），`$item.` 出现 **0 次**。
+ *
+ * 上一版处理方式是「expand_ir exit=3 中止 + lint 报 ERROR + 三份文档写满 ⛔ 没有 $item」——
+ * 那等于**教错了再罚学生**：模型必须先知道正确答案才不被打回，而正确答案本来就不该由它记住。
+ *
+ * 正确做法：IR 是本编译器的输入格式，编译器对**公认别名**做归一化即可。
+ * 这不是猜测 —— `$item.x` 在 listScope 里只有一种可能语义（当前项字段 x），
+ * 因为运行时 `makeSlotScope` 的作用域是 `外层 ∪ item字段展开 ∪ {$$, _index}`，
+ * **根本没有 `item` 这个键**。所以重写是语义保持的，不是"帮模型猜"。
+ *
+ * ── 契约 ─────────────────────────────────────────────────────────
+ * 规范形（落到 schema.json 的形态）：`$<字段名>` / `$$` / `$_index`
+ * 可接受别名（作者侧随便写）：`$item.<字段>` → `$<字段>`；`$item` → `$$`；`$item._index` → `$_index`
+ *
+ * ── 唯一的例外闸 ───────────────────────────────────────────────────
+ * 若卡片**真的声明了**名为 `item` 的根作用域变量（dictionary.inputParams[].key === 'item'），
+ * 那么 `$item.x` 是合法取值，**一律不动**。这把「归一化」与「覆盖用户数据」彻底分开。
+ */
+
+/**
+ * 归一化一条字符串。纯函数，无副作用。
+ *
+ * 改写顺序不可交换：`$item._index` 必须先于 `$item.`；
+ * 裸 `$item` 的规则必须最后，且带前瞻，避免把 `$itemFoo` 误当别名。
+ *
+ * ⚠️ 三条正则**必须显式写 `[A-Za-z0-9_]`，不许用 `\w` / `\b`**：
+ * JS 的 `\w` 是 ASCII 集，Python 的 `\w` 默认是 Unicode 集（含中文）。
+ * 用 `\w` 会让同一串 `$item名称` 在两边得到不同结果（JS 改写、Python 不改写），
+ * 这正是「口径同源」要防的分叉。Python 侧 autofix_schema.py 逐字复用这三条。
+ *
+ * @param {string} s 原字符串
+ * @returns {{ text: string, hits: string[] }} 归一化结果与被命中的原文（去重）
+ */
+export function rewriteItemAlias(s) {
+  if (typeof s !== 'string' || !s.includes('$item')) return { text: s, hits: [] }
+  const before = s
+  let out = s
+  // ⚠️ 必须用**函数替换器**，不能用字符串替换串：`String.replace` 会把替换串里的
+  // `$$` 解释成「一个字面 $」（还有 `$&`/`` $` ``/`$'`/`$1` 等模式），于是
+  // `.replace(re, '$$')` 实际只产出 `$` —— 而 Python 的 `re.sub` 里 `$` 不是特殊字符，
+  // 同一份规则在两侧结果不同（本文件的测试就是这么抓到的）。
+  // 函数替换器不做任何模式展开，天然与 Python 行为对齐。
+  out = out.replace(/\$item\._index(?![A-Za-z0-9_])/g, () => '$_index')
+  out = out.replace(/\$item\./g, () => '$')
+  out = out.replace(/\$item(?![A-Za-z0-9_$])/g, () => '$$')
+  if (out === before) return { text: s, hits: [] }
+  return { text: out, hits: [before] }
+}
+
+/**
+ * 不做改写的结构键：它们承载的是 id / 名称 / 类型等标识，不是绑定表达式。
+ * （JS 与 Python 两侧必须逐字一致；改动请同步 autofix_schema.py。）
+ */
+export const SKIP_KEYS = new Set([
+  'id',
+  'name',
+  'itemId',
+  'itemKey',
+  'itemName',
+  'itemType',
+  'itemValueFrom',
+  'componentId',
+  'className',
+  'eventKey',
+  'eventName',
+  'actionType',
+  'slotKey',
+  'type',
+  'desc',
+  'remark',
+])
+
+/**
+ * 递归归一化任意 IR / schema 结构里的作用域别名（原地改写）。
+ *
+ * @param {*} node 待处理结构（IR 或 schema，任意深度）
+ * @param {object} [opts]
+ * @param {Set<string>} [opts.knownRoots] 根作用域变量名集合；含 'item' 时整体跳过（见头注释「唯一的例外闸」）
+ * @param {string} [opts.at] 路径前缀（内部递归用）
+ * @returns {{ count: number, samples: Array<{ at: string, before: string, after: string }> }}
+ */
+export function normalizeItemAliases(node, { knownRoots, at = '' } = {}) {
+  const result = { count: 0, samples: [] }
+  if (knownRoots && knownRoots.has('item')) return result
+  walk(node, at, result)
+  return result
+}
+
+function walk(node, at, result) {
+  if (typeof node === 'string') return // 由父级带 key 处理，避免丢掉 key 上下文
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => {
+      if (typeof v === 'string') applyTo(node, i, `${at}[${i}]`, result)
+      else walk(v, `${at}[${i}]`, result)
+    })
+    return
+  }
+  if (node && typeof node === 'object') {
+    for (const [k, v] of Object.entries(node)) {
+      if (typeof v === 'string') {
+        if (SKIP_KEYS.has(k)) continue
+        applyTo(node, k, at ? `${at}.${k}` : k, result)
+      } else {
+        walk(v, at ? `${at}.${k}` : k, result)
+      }
+    }
+  }
+}
+
+function applyTo(container, key, at, result) {
+  const { text, hits } = rewriteItemAlias(container[key])
+  if (!hits.length) return
+  container[key] = text
+  result.count += hits.length
+  if (result.samples.length < 20) {
+    result.samples.push({ at, before: hits[0], after: text })
+  }
+}

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 }
+}