cardbuddy 0.14.3 → 0.16.0

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

@@ -0,0 +1,634 @@
+#!/usr/bin/env node
+/**
+ * readiness.mjs — S4.9 **内容就绪门禁**：像素自循环的前置条件。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 为什么必须存在（2026-09-24 gen-1 实机事故，用户原话）：
+ *   「只有在确保内容和要素的齐全和准备再做像素自循环，不然跟个傻逼一样浪费时间在
+ *     像素循环里打转。这次卡片连基本的切图引入跑了半天都没为我添加上去」
+ *
+ * 实测证据：gen-1 两个回合合计 **623 万 prompt token** 全部作废。
+ *   回合 tmuf9c4h1ml778e：61 步 / 67 次工具调用 / 5,254,936 promptTokens / aborted；
+ *   iterate 历史 r4–r13 十轮 match 死死卡在 87–90.46（门禁要 95），
+ *   `gate.stage` 全程 = 'pixel' —— 结构早就过了，纯在像素上空转。
+ *   而同一时间：Image 节点的图片地址因为属性键写成 `image`（合法键只有 `value`）
+ *   被运行时静默丢弃，渲染出来是个破图。**要素不全却已经开始刷像素。**
+ *
+ * 根因不是模型偷懒，是**流程里没有这道门禁**：SKILL.md 的阶段编号从 2 直接跳到 4，
+ * iterate 每轮无条件 render + pixelDiff（最贵的一步），没有任何一步会先问
+ * 「内容齐了吗？变量接上了吗？切图到位了吗？」
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * 六道内容门禁（前五道是 **schema 侧**声明性判定，不需要渲染 ⇒ 可以挡在 render 之前；
+ * 第六道是 **spec 输入侧**契约检查，只在你传了 `--spec` 时才跑）：
+ *
+ *   A components  组件契约：className / 属性键 / 样式组 / 样式子键必须在元数据白名单内。
+ *                 不存在的键被运行时**整条静默丢弃**（Image 写 `image` ⇒ 破图且零报错）。
+ *   B elements    要素齐全：设计稿的每条文案都要在 schema 里找得到（缺失即拦）。
+ *   C bindings    变量绑定完备：`$var` 引用的根变量必须真的存在。
+ *                 **只在槽位外做硬判定**——槽位内的 `$label`/`$name` 是列表项字段，
+ *                 无法静态推导，硬判会大面积误报（实测全仓 24 个「未解析」root 全在槽位内）。
+ *   D images      图片地址已配置：每个 Image 节点都必须有非空的 value。
+ *                 —— gen-1 「连图片地址都没配置」的**直接对应项**。
+ *   E slices      切图路径已配置：schema 里每个 `/slices/...` 引用都必须在 src/slices 落盘
+ *                 （R31c：悬空引用渲染 404、图空白、控制台零报错）。
+ *   F spec        上游产物契约完整：spec.json 的 `cards[<i>].mask` / `cards[<i>].rect` 必须存在
+ *                 （契约 `skills/shared/spec-contract.md`）。缺失多为**旧版 spec 产物**
+ *                 （mask/focusMetrics 批次字段引入前生成）⇒ 重跑上游补全，**不要在下游加兼容分支**
+ *                 （兼容分支会让「上游漏产」永远不被发现）。
+ *
+ * ── 判据选型：先量测再定门禁（全仓 75 张卡 / 754 条 `$` 引用）──────────────
+ *   槽位外未解析 root（可硬判）............. 0 处  → 0 误报，定 ERROR
+ *   槽位内未解析 root（不可硬判）........... 24 个不同名 → 全是列表项字段/运行时 setData，只统计不拦
+ *   非法 itemValueFrom（非 0/1/2）.......... 0 处  → 0 误报，定 ERROR
+ *   from=1 但值不含 $ ...................... 0 处  → 0 误报，定 ERROR
+ *   from=2 但值是 $ 表达式.................. 0 处  → 0 误报，定 ERROR（url($icon) 画布空白类）
+ *   Image 无 value / value 为空 ............. 0 处  → 0 误报，定 ERROR
+ *   引用在 src/slices 无对应文件 ............ 4 处  → 真实存量债（r31c），定 ERROR
+ *
+ * ── 明确**不**纳入本门禁的（附理由，避免以后有人「顺手补上」）──────────────
+ *   · 「设计稿声明的切图是否逐张被引用」——名字匹配不可靠。实测 all-components-test：
+ *     设计稿资产名 `编组 4`，schema 里是 `iconArrowRightOrange.png`（同位置、模型语义重命名）；
+ *     按名字对账会把一张好卡判死。而**几何对账也走不通**：style.rect 只有 width/height
+ *     （style-meta.json 实测），本 DSL 根本不支持声明绝对定位 ⇒ 无法判断「这个位置有没有图」。
+ *     故降级为 `checks.slices.unreferenced` **警告**，只点名不拦。
+ *   · 字号 / 颜色保真度 —— 那些是**像素层**问题，正是本门禁要拦在门外的东西。
+ *   · layout / geometry（collapsed / outOfCard）—— 需要 render 的 elementBoxes，属结构层，由 iterate 的 gate 管。
+ *
+ * ── 用法 ────────────────────────────────────────────────────────────────────
+ *   node readiness.mjs --id <cardId> [--spec <spec.json>] [--design <card-N.png>] [--json]
+ *   node readiness.mjs --schema <schema.json> --id <cardId> [--spec ...] [--json]
+ *
+ * 退出码：0 = 就绪（可以进像素循环）；3 = 未就绪（**不是**脚本报错，是内容没准备好）；1 = 用法/IO 错误。
+ *   3 与 iterate 的 2（gate-fail）分开，便于调用方区分「内容没齐」与「像素没达标」。
+ *
+ * 环境变量逃生门：DSL_CARD_SKIP_READINESS=1 或 --no-readiness ⇒ 完全跳过（debug 用）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { metaDir as DEFAULT_META_DIR, slicesDir as DEFAULT_SLICES_DIR, cardAuditPath, cardSchemaPath, cardDataPath } from './lib/paths.mjs'
+import { loadContract, collectContractViolations, describeViolation } from './lib/component_contract.mjs'
+import { buildSliceFileIndex, collectSliceRefStrings, resolveSliceRefOnDisk, isRemoteSliceRef, sliceNameMatches } from './lib/slice_dedupe.mjs'
+import { buildFidelityReport } from './check_fidelity.mjs'
+import { collectArrayConsumption } from './lib/rules/bindings.mjs'
+
+/**
+ * 表达式里天然可用的名字（渲染器注入，不需要卡片声明）。
+ * `$$` = 当前列表项整体、`_index` = 列表下标 —— 见 card-editor/runtime/evaluate.js `makeSlotScope`。
+ */
+const BUILTIN_ROOTS = new Set(['$$', '_index', 'item', 'index', 'globalSet', 'state'])
+
+/* ────────────────────────────────────────────────────────────────────────
+ * 根变量表：schema 里 `$name` 的 name 必须能在这里找到出处。
+ *
+ * 三个来源（与运行时取值同源）：
+ *   1. dictionary.inputParams[].key   权威数据（data.json 是它的派生投影）
+ *   2. dictionary.mocks{}             演示数据
+ *   3. data.json 顶层键               渲染真正吃的值
+ *   + 数组型 defaultValue 的**元素字段名**（`$txName` 这种扁平访问，见 makeSlotScope 的字段展开）
+ *   + 事件代码 `this.setData({ k: ... })` 里写入的键（实测 monthlyBill 的 `$renderListData`
+ *     就是运行时由 customAction 造的，不在 dictionary 里 —— 不扫这段会把它误判成悬空引用）
+ * ──────────────────────────────────────────────────────────────────────── */
+export function buildKnownRoots(schema, data) {
+  const known = new Set(BUILTIN_ROOTS)
+  const addArrayFields = (v) => {
+    if (Array.isArray(v) && v[0] && typeof v[0] === 'object') for (const k of Object.keys(v[0])) known.add(k)
+  }
+  for (const p of schema?.dictionary?.inputParams || []) {
+    if (p && typeof p.key === 'string' && p.key) {
+      known.add(p.key)
+      addArrayFields(p.defaultValue)
+    }
+  }
+  for (const [k, v] of Object.entries(schema?.dictionary?.mocks || {})) {
+    known.add(k)
+    addArrayFields(v)
+  }
+  for (const [k, v] of Object.entries(data || {})) {
+    known.add(k)
+    addArrayFields(v)
+  }
+  // 事件代码写入的变量。两种形态都扫：
+  //   ① `this.setData({ renderListData: renderList })`  —— monthlyBill 实测：`$renderListData` 由
+  //      customAction 在运行时造出来，不在 dictionary 里，不扫这段会误判成悬空引用。
+  //   ② `this.state.xxx = ...` / `this.data.xxx = ...` 直接赋值。
+  for (const code of collectActionCode(schema)) {
+    for (const m of code.matchAll(/setData\s*\(\s*\{([\s\S]*?)\}\s*\)/g)) {
+      for (const line of m[1].split(',')) {
+        const k = line.split(':')[0].replace(/[\s{}[\]]/g, '')
+        if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k)) known.add(k)
+      }
+    }
+    for (const m of code.matchAll(/this\.(?:state|data)\.([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g)) known.add(m[1])
+  }
+  return known
+}
+
+/**
+ * 收集 schema 里所有事件动作代码。
+ *
+ * ⚠️ 结构实测（2026-09-24，monthlyBill）：代码**不在** `action.code`，而在
+ * `action.properties[]` 里 `itemKey === 'function'` 那一项的 `itemValue`（对象，含 `code`/`compiled`）。
+ * 按 `action.code` 取会永远拿到空数组 ⇒ `$renderListData` 这类运行时变量被当成悬空引用（实测误报）。
+ */
+function collectActionCode(schema) {
+  const out = []
+  const push = (v) => {
+    if (typeof v === 'string') {
+      if (v) out.push(v)
+      return
+    }
+    if (v && typeof v === 'object') {
+      for (const k of ['code', 'compiled', 'expression']) if (typeof v[k] === 'string' && v[k]) out.push(v[k])
+    }
+  }
+  const walk = (n) => {
+    if (!n || typeof n !== 'object') return
+    for (const ea of n.eventactions || []) {
+      const a = ea?.action
+      if (!a) continue
+      for (const k of ['code', 'compiled', 'expression', 'actionValue']) push(a[k])
+      for (const p of a.properties || []) push(p?.itemValue)
+    }
+    for (const c of n.components || []) walk(c)
+    for (const s of n.slots || []) for (const c of s.components || []) walk(c)
+  }
+  walk(schema?.view || schema)
+  return out
+}
+
+/* ── 绑定引用收集：区分「复现器插槽外」（可硬判）与「复现器插槽内」（只能统计）──────
+ *
+ * ⚠️ 判据是**类**不是 slotKey（2026-09-24 实测踩坑）：
+ *   本 DSL 里子节点一律存在 `slots[].components`，而 `slotKey` **恒为 `default`**
+ *   （全仓 1010 个 slot：Row 597 / Column 328 / ListLayout 54 / AbsoluteLayout 20 / GridLayout 11）。
+ *   第一版按「有没有 slots 就算子节点在槽位里」判断 ⇒ gen-1 的 21 条引用**全部**被误标成
+ *   `refsInsideSlots: 21 / refsOutsideSlots: 0` ⇒ 变量绑定门禁整条形同虚设（实测把
+ *   `$notDeclaredVar` 这种悬空引用放行）。
+ *   正解：只有 `ListLayout` / `GridLayout` 这类**复现器**（元数据同时声明 `value` 属性与
+ *   default 插槽）的插槽内才有 item 作用域，其字段无法静态穷举；其余容器的 default 插槽
+ *   就是普通嵌套，引用照样按根作用域解析。
+ */
+/**
+ * @param {object} schema
+ * @param {Set<string>} repeaterClasses 由 component-meta 推导（见 lib/component_contract.mjs）
+ * @returns {{ outside: Array<object>, slotRefs: Array<object>, slotCount: number,
+ *             slotRoots: Set<string>, fromViolations: Array<object> }}
+ */
+export function collectBindingRefs(schema, repeaterClasses = new Set()) {
+  const outside = []
+  const slotRefs = []
+  const fromViolations = []
+  const slotRoots = new Set()
+  let slotCount = 0
+
+  /** @param {object} node @param {boolean} inSlot */
+  const visit = (node, inSlot) => {
+    if (!node || typeof node !== 'object') return
+    const props = []
+    for (const p of node.properties || []) props.push({ p, where: 'properties' })
+    for (const g of node.style?.properties || []) {
+      for (const c of g.itemChildren?.properties || []) props.push({ p: c, where: `style.${g.itemKey}` })
+    }
+    for (const { p, where } of props) {
+      if (!p || typeof p !== 'object') continue
+      const key = p.itemKey
+      if (typeof key !== 'string' || !key) continue
+      const from = String(p.itemValueFrom ?? '')
+      const val = typeof p.itemValue === 'string' ? p.itemValue : ''
+      // 三态取值口径（与 preflight Check 3 的 Image 版同源，这里推广到全部属性）：
+      if (from === '1' && !val.includes('$')) {
+        fromViolations.push({ code: 'from1-not-expression', cid: node.componentId, cls: node.className, key, where, value: String(p.itemValue).slice(0, 60) })
+      } else if (from === '2' && val.trim().startsWith('$')) {
+        fromViolations.push({ code: 'from2-is-expression', cid: node.componentId, cls: node.className, key, where, value: val.slice(0, 60) })
+      } else if (from !== '' && from !== '0' && from !== '1' && from !== '2') {
+        fromViolations.push({ code: 'illegal-itemValueFrom', cid: node.componentId, cls: node.className, key, where, value: from })
+      }
+      if (!val.includes('$')) continue
+      const roots = new Set()
+      for (const m of val.matchAll(/\$([A-Za-z_][A-Za-z0-9_]*)/g)) roots.add(m[1])
+      if (!roots.size) continue
+      const rec = { cid: node.componentId, cls: node.className, key, where, value: val.slice(0, 60), roots: [...roots] }
+      if (inSlot) {
+        slotCount++
+        slotRefs.push(rec)
+        for (const r of roots) slotRoots.add(r)
+      } else {
+        for (const r of roots) outside.push({ root: r, ...rec })
+      }
+    }
+    // 只有**复现器**的插槽才开 item 作用域（判据见上方注释：类名，不是 slotKey）
+    const isRepeater = repeaterClasses.has(node.className)
+    for (const c of node.components || []) visit(c, inSlot)
+    for (const s of node.slots || []) for (const c of s.components || []) visit(c, inSlot || isRepeater)
+  }
+  visit(schema?.view || schema, false)
+  return { outside, slotRefs, slotCount, slotRoots, fromViolations }
+}
+
+/* ── Image 图片地址配置 ──────────────────────────────────────────────── */
+export function collectImageConfig(schema) {
+  const problems = []
+  let nodes = 0
+  const walk = (n) => {
+    if (!n || typeof n !== 'object') return
+    if (n.className === 'Image') {
+      nodes++
+      const vp = (n.properties || []).find((p) => p.itemKey === 'value')
+      if (!vp) {
+        problems.push({ cid: n.componentId, code: 'image-no-value-key', detail: '没有 itemKey="value" 的属性（该组件图片地址的键固定为 value）' })
+      } else if (!String(vp.itemValue ?? '').trim()) {
+        problems.push({ cid: n.componentId, code: 'image-empty-value', detail: 'value 为空 ⇒ 渲染器回落到默认占位图 ⇒ 破图' })
+      }
+    }
+    for (const c of n.components || []) walk(c)
+    for (const s of n.slots || []) for (const c of s.components || []) walk(c)
+  }
+  walk(schema?.view || schema)
+  return { nodes, problems }
+}
+
+/* ── 切图路径：引用落盘 + 设计稿声明覆盖 ─────────────────────────────── */
+function checkSlices({ schema, specPath, cardIndex, designPath, slicesDir, auditPath }) {
+  const index = buildSliceFileIndex(slicesDir)
+  const refs = collectSliceRefStrings(schema)
+  const missingOnDisk = []
+  for (const ref of refs) {
+    if (isRemoteSliceRef(ref)) continue
+    const { resolved, name } = resolveSliceRefOnDisk(index, ref)
+    if (!resolved) missingOnDisk.push({ ref, expect: name })
+  }
+
+  const out = { passed: missingOnDisk.length === 0, refs, missingOnDisk, declared: [], unreferenced: [], auditFresh: false, auditNote: '', slicesDir }
+
+  // 设计稿声明面（需要 S2 审计 + 与当前设计稿同一份）
+  let audit = null
+  const candidate = auditPath || ''
+  if (candidate && fs.existsSync(candidate)) {
+    try { audit = JSON.parse(fs.readFileSync(candidate, 'utf8')) } catch { audit = null }
+  }
+  if (!audit) {
+    out.auditNote = '没有 S2 审计（.cache/ai-scratch/<id>.audit.json）⇒ 无法核对「设计稿声明的切图是否都被引用」，本项从略'
+    return out
+  }
+  const auditCard = Number(audit?.card?.index)
+  const auditDesign = audit?.design?.path ? path.resolve(audit.design.path) : ''
+  const curDesign = designPath ? path.resolve(designPath) : ''
+  const cardOk = !Number.isFinite(auditCard) || !cardIndex || auditCard === cardIndex
+  const designOk = !auditDesign || !curDesign || auditDesign === curDesign
+  out.auditFresh = cardOk && designOk
+  if (!out.auditFresh) {
+    out.auditNote =
+      `审计与当前设计稿对不上（审计 card=${audit?.card?.index ?? '?'} design=${audit?.design?.path || '?'}；` +
+      `当前 card=${cardIndex} design=${designPath || '?'}）⇒ 覆盖核对从略，仅保留引用落盘检查`
+    return out
+  }
+
+  const declared = (audit.slices || []).filter((s) => s && s.exists !== false)
+  const names = []
+  for (const s of declared) {
+    const cand = [s.name, path.basename(s.file || ''), ...(s.crops || []).map((c) => c && c.name)].filter(Boolean)
+    names.push({ name: s.name || cand[0] || '', cand, rects: s.rects || [], verdict: s.verdict || '' })
+  }
+  const matched = (cand) => refs.some((ref) => cand.some((c) => c && sliceNameMatches(path.basename(ref), path.basename(c))))
+  out.declared = names.map((n) => n.name)
+  out.unreferenced = names
+    .filter((n) => !matched(n.cand))
+    .map((n) => ({ name: n.name, verdict: n.verdict, at: (n.rects[0] ? `${n.rects[0].x},${n.rects[0].y} ${n.rects[0].w}x${n.rects[0].h}` : '') }))
+  return out
+}
+
+/* ── 主入口 ─────────────────────────────────────────────────────────── */
+export function buildReadinessReport(input = {}) {
+  const args = {
+    cardId: '',
+    schemaPath: '',
+    dataPath: '',
+    specPath: '',
+    designPath: '',
+    auditPath: '',
+    cardIndex: 0,
+    slicesDir: DEFAULT_SLICES_DIR,
+    metaDir: DEFAULT_META_DIR,
+    /** 上游已算好的 fidelity（iterate 手里就有）——给了就不重复读盘算一遍 */
+    fidelity: null,
+    ...input,
+  }
+  const cardId = args.cardId || (args.schemaPath ? path.basename(path.dirname(args.schemaPath)) : '')
+  const schemaPath = args.schemaPath || (cardId ? cardSchemaPath(cardId) : '')
+  if (!schemaPath || !fs.existsSync(schemaPath)) throw new Error(`schema.json 不存在: ${schemaPath || '<未指定>'}`)
+  const dataPath = args.dataPath || (cardId ? cardDataPath(cardId) : '')
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  let data = null
+  try { data = JSON.parse(fs.readFileSync(dataPath, 'utf8')) } catch { data = null }
+
+  // 卡号：优先显式 --card，其次从 card-N.png 推断，最后退出码里都按 1
+  let cardIndex = Number(args.cardIndex) || 0
+  if (!cardIndex) {
+    const m = /card-(\d+)\.png$/i.exec(String(args.designPath || ''))
+    cardIndex = m ? Number(m[1]) : 1
+  }
+
+  const checks = {}
+  const blockers = []
+
+  /* F spec 契约（输入侧；只在你传了 --spec 时才检查）
+     契约：skills/shared/spec-contract.md —— `cards[<i>].mask` / `cards[<i>].rect` 是必需字段，
+     上游 parse_meaxure.py 无条件产出。缺失 = 该 spec 是旧版产物，下游会静默取默认圆角/默认底色，
+     表现为「还原度怎么调都对不上且查不出根因」。这里显式拦住，让人回去重跑上游。
+
+     ⚠ `cards=[] **不是** 错误`：上游有三类合法空数组，都只记 note、不阻断 ——
+       ① text_only / overlay_dialog：按 artboardType 收口，本就不单独产卡（由父卡承载）；
+       ② artboardType=card 却 0 卡：上游已知态，`board_tag` 明写「0 卡 · 结构丰富，按整图参考建卡」
+          （parse_meaxure.py:1768）；test_text_only_artboard.py 用例 2/3/6 正是 kind=card、cards=0
+          且断言通过 —— 属于被测试固化的设计，不是「上游自相矛盾」。
+       这类画板无 cards 数据可组装（卡片被整体导成切片时检测器看不到结构），建卡改走整图 / AI 读图。
+     `subcard` **不在**这三类里：自 2026-09-24 起上游为其产 1 张卡（面板几何直取，
+     `detect_artboard_cards` sheet 分支）—— 走到下面的 subcard 分支即说明是旧版产物。 */
+  const specIssues = []
+  const specNotes = []
+  if (args.specPath && fs.existsSync(args.specPath)) {
+    try {
+      const spec = JSON.parse(fs.readFileSync(args.specPath, 'utf8'))
+      const specCards = Array.isArray(spec.cards) ? spec.cards : []
+      const target = specCards[cardIndex - 1]
+      if (!specCards.length) {
+        const at = spec.artboardType || '未知'
+        if (at === 'text_only') {
+          specNotes.push('cards=[] 属正常：artboardType=text_only（纯文本画板，上游按类型收口，下游不为其建卡）')
+        } else if (at === 'overlay_dialog') {
+          specNotes.push('cards=[] 属正常：artboardType=overlay_dialog（系统弹框，A.5 规定不产卡 —— 由父卡 alertDialog 调用承载）')
+        } else if (at === 'subcard') {
+          specNotes.push(
+            'cards=[] 但 artboardType=subcard：该 spec 应属**旧版产物**（2026-09-24 前）——' +
+              '上游现已为底部抽屉产 1 张卡（面板 rect + 顶圆角遮罩，含 card-1.png，由 detect_artboard_cards 的 sheet 分支几何直取）。' +
+              '请回上游重跑该画板，不要在下游读图自定卡片边界；临时兜底可读 artboard.png + elements[]，但还原度无保证',
+          )
+        } else {
+          specNotes.push(
+            `cards=[] · artboardType=${at}：本画板无 cards 可组装（卡片被整体导成切片时检测器看不到结构）。` +
+              '上游会兜底裁一张 card-1.png（去系统 chrome，parse_meaxure.py:645）可作卡片视觉参考，' +
+              '但**没有卡片坐标与切图归属**，建卡须以该图 + elements[] 为准（或 AI 读图）；' +
+              '若确认板上确有卡片却未检出，回上游复核该画板（别在下游补）',
+          )
+        }
+      } else if (!target) {
+        specIssues.push(`cards[${cardIndex - 1}] 不存在（该 spec 只有 ${specCards.length} 张卡，--card 序号越界）`)
+      } else {
+        if (!target.rect) specIssues.push(`cards[${cardIndex - 1}].rect 缺失（卡片几何是必需字段）`)
+        if (!target.mask || typeof target.mask !== 'object') {
+          specIssues.push(`cards[${cardIndex - 1}].mask 缺失（旧版 spec 产物：mask.radius 是下游圆角的唯一来源，缺了只能取默认值）`)
+        }
+      }
+    } catch (e) {
+      specIssues.push(`spec.json 解析失败：${e?.message || e}`)
+    }
+  }
+  checks.spec = args.specPath ? { passed: specIssues.length === 0, issues: specIssues, notes: specNotes } : null
+  if (specIssues.length) {
+    blockers.push(
+      `spec|上游 spec.json 契约不完整（${specIssues.length} 项）：${specIssues.slice(0, 5).join('；')}` +
+        '（重跑上游：python skills/sketch-spec-to-card/scripts/parse_meaxure.py --src <导出目录> --draft <稿名> --build；' +
+        '不要手工补字段、不要在下游加兼容分支）',
+    )
+  }
+
+  /* A 组件契约 */
+  const contract = loadContract({ metaDir: args.metaDir })
+  const violations = collectContractViolations(schema, contract)
+  const compErrors = violations.filter((v) => v.severity === 'error')
+  checks.components = {
+    passed: compErrors.length === 0,
+    errors: compErrors.map(describeViolation),
+    warnings: violations.filter((v) => v.severity !== 'error').map(describeViolation),
+  }
+  if (compErrors.length) blockers.push(`components|${compErrors.length} 处组件契约违规（属性键/样式组不在元数据白名单内，运行时整条静默丢弃）`)
+
+  /* B 要素齐全 */
+  let fid = args.fidelity
+  if (!fid && args.specPath && fs.existsSync(args.specPath)) {
+    try {
+      const r = buildFidelityReport({ spec: args.specPath, schema: schemaPath, card: cardIndex, audit: args.auditPath || '' })
+      fid = { total: r.elements.texts.total, matched: r.elements.texts.matched, missing: r.elements.texts.missing, invented: r.elements.texts.invented }
+    } catch (e) {
+      fid = { error: String(e?.message || e) }
+    }
+  }
+  if (fid && !fid.error) {
+    checks.elements = { passed: fid.missing.length === 0, total: fid.total, matched: fid.matched, missing: fid.missing, invented: fid.invented }
+    if (fid.missing.length) {
+      blockers.push(
+        `elements|设计稿有 ${fid.missing.length} 条文案在 schema 里找不到：${fid.missing.slice(0, 5).map((t) => `「${t}」`).join('、')}` +
+          '（补回对应节点，或把绑定变量的 defaultValue 改成设计稿真值；别用占位文案顶替）',
+      )
+    }
+  } else {
+    checks.elements = fid && fid.error ? { passed: null, error: fid.error } : null
+  }
+
+  /* C 变量绑定完备 */
+  const known = buildKnownRoots(schema, data)
+  const b = collectBindingRefs(schema, contract.repeaterClasses)
+  const unresolved = []
+  const seenRoot = new Set()
+  for (const r of b.outside) {
+    if (known.has(r.root)) continue
+    if (seenRoot.has(r.root)) continue
+    seenRoot.add(r.root)
+    unresolved.push(r)
+  }
+  const fromProblems = b.fromViolations
+  // 元数据没读到（contract 为空）⇒ 复现器集合无从得知 ⇒ 槽位内引用会被当成槽位外硬判，
+  // 必然大面积误报。这种环境下**整项退化为「无从判定」**，不放行也不拦。
+  const bindingsCheckable = contract.loaded.components
+  checks.bindings = {
+    passed: bindingsCheckable ? unresolved.length === 0 && fromProblems.length === 0 : null,
+    checkable: bindingsCheckable,
+    rootsKnown: known.size,
+    repeaters: [...contract.repeaterClasses].sort(),
+    refsOutsideSlots: b.outside.length,
+    refsInsideSlots: b.slotCount,
+    unresolvedRoots: bindingsCheckable ? unresolved : [],
+    fromProblems,
+    slotRootsUnresolved: [...b.slotRoots].filter((r) => !known.has(r)).length,
+  }
+  if (bindingsCheckable && unresolved.length) {
+    blockers.push(
+      `bindings|${unresolved.length} 个根变量在 dictionary / mocks / data.json / 事件 setData 里都找不到出处：` +
+        unresolved.slice(0, 5).map((r) => `$${r.root}（${r.cls} ${r.cid} ${r.where}.${r.key}）`).join('、'),
+    )
+  }
+  if (bindingsCheckable && fromProblems.length) {
+    blockers.push(`bindings|${fromProblems.length} 处 itemValueFrom 与值不匹配（from=1 必须是 $表达式 / from=2 不能是 $表达式）`)
+  }
+
+  /* C2 数组消费对账（列表数组化闭环，2026-09-25）——「数据绑定齐全」的机器化。
+   * 证据链（全仓 75 卡实测）：transferPlan.payeeList / dreamPlan.planTimeList /
+   * creditCardPayment.myCardList / branchdata.businessScopeList /
+   * financialProductDetail.tradeRules 都是「列表数据建了、视图零消费」——
+   * 列表被静态展开或根本没建，此前无任何门禁能发现。
+   * 判据：名字带列表语义（list|items|rows|records|details|rules|entries）且未被
+   * 复现器 value / slotScope 模板 / 事件代码 / 任意表达式引用 ⇒ 硬伤拦像素循环；
+   * 其余未消费数组（radarData/donutData 类图表数据）只进 checks 不拦。 */
+  const arrAudit = collectArrayConsumption(schema, data || {})
+  const hardUnconsumed = arrAudit.unconsumed.filter((u) => u.semantic)
+  const softUnconsumed = arrAudit.unconsumed.filter((u) => !u.semantic)
+  checks.bindings.arraysUnconsumed = {
+    hard: hardUnconsumed,
+    soft: softUnconsumed,
+    arrays: [...arrAudit.arrays.keys()],
+    scopedLists: arrAudit.scopedListCount,
+    repeaters: arrAudit.repeaterCount,
+  }
+  if (hardUnconsumed.length) {
+    blockers.push(
+      `bindings|${hardUnconsumed.length} 个列表语义数组没有任何列表消费：` +
+        hardUnconsumed.slice(0, 5).map((u) => `$${u.name}（${u.len} 项）`).join('、') +
+        '（设计稿若有重复数据行，必须 ListLayout/GridLayout + value 绑数组 + slotScope 模板，禁止静态展开；范式 ir-format.md §2f）',
+    )
+  }
+
+  /* G 列表提名闭环（--audit 时）：S2 审计的 listCandidates 是否被数组化实现。
+   * 提名 0 数组化 = blocker（视觉分析已明确是列表，静态展开就是疏漏）；
+   * 提名 > 数组化 = 只记 note（AI 合并同构列表 / 提名假阳性都合法，不冤枉）。 */
+  const auditResolved = args.auditPath || (cardId ? cardAuditPath(cardId) : '')
+  if (auditResolved && fs.existsSync(auditResolved)) {
+    let candidates = []
+    try {
+      const audit = JSON.parse(fs.readFileSync(auditResolved, 'utf8'))
+      candidates = Array.isArray(audit.listCandidates) ? audit.listCandidates : []
+    } catch { /* 审计坏了不阻断本门 */ }
+    if (candidates.length) {
+      checks.lists = {
+        passed: arrAudit.scopedListCount > 0,
+        nominated: candidates.length,
+        scopedLists: arrAudit.scopedListCount,
+        hardUnconsumed: hardUnconsumed.map((u) => u.name),
+      }
+      if (arrAudit.scopedListCount === 0) {
+        blockers.push(
+          `lists|S2 审计提名了 ${candidates.length} 个列表候选（同构重复行 / tile，值逐行不同），` +
+            'schema 里却没有任何数组化列表（ListLayout/GridLayout 的 value 绑定数组）：' +
+            '列表数据必须在视觉分析阶段就明确用数组绑定，禁止逐行静态展开（ir-format.md §2f；audit.listCandidates 的 fields/values 就是现成的字段与值矩阵）',
+        )
+      } else if (arrAudit.scopedListCount < candidates.length) {
+        checks.lists.note = `数组化列表 ${arrAudit.scopedListCount} < 提名 ${candidates.length}：若为同构列表合并或提名假阳性可忽略，否则逐条核对 listCandidates`
+      }
+    }
+  }
+
+  /* D 图片地址已配置 */
+  checks.images = collectImageConfig(schema)
+  checks.images.passed = checks.images.problems.length === 0
+  if (checks.images.problems.length) {
+    blockers.push(
+      `images|${checks.images.problems.length} 个 Image 节点没有配置图片地址：` +
+        checks.images.problems.slice(0, 5).map((p) => `${p.cid}（${p.detail}）`).join('、'),
+    )
+  }
+
+  /* E 切图路径已配置 */
+  const slices = checkSlices({
+    schema,
+    specPath: args.specPath,
+    cardIndex,
+    designPath: args.designPath,
+    slicesDir: args.slicesDir,
+    auditPath: args.auditPath || (cardId ? cardAuditPath(cardId) : ''),
+  })
+  checks.slices = slices
+  if (slices.missingOnDisk.length) {
+    blockers.push(
+      `slices|${slices.missingOnDisk.length} 个切图引用在 src/slices 里没有对应文件（渲染 404、图空白、零报错）：` +
+        slices.missingOnDisk.slice(0, 5).map((m) => `${m.ref}`).join('、') +
+        '（按引用名把切图落盘，或把引用改成磁盘上真实存在的名字 —— 两者必须同源）',
+    )
+  }
+
+  const ORDER = ['spec', 'components', 'elements', 'bindings', 'lists', 'images', 'slices']
+  const firstFail = ORDER.find((k) => checks[k] && checks[k].passed === false)
+  const ready = blockers.length === 0
+  const HINT = {
+    spec: '重跑上游 parse_meaxure.py --src <导出目录> --draft <稿名> --build 补全 spec.json 字段（旧版产物缺 mask/rect）——不要手工补，也不要让下游兼容缺失字段。',
+    components: '按 blockers 里的节点路径去 IR / schema 改属性键（Image 的图片地址键是 value，不是 image）。改完重跑 readiness。',
+    elements: '先补要素再谈像素：把设计稿的文案补回对应节点，或改绑定变量的 defaultValue。',
+    bindings: '把缺失的根变量加进 dictionary.inputParams（带 defaultValue），或改写成已存在的变量名。列表语义数组未消费时：按 audit.listCandidates 的 fields/values 建数组变量 + ListLayout/GridLayout value 绑数组 + slotScope 模板（ir-format.md §2f、recipe_snippets/list-expand-collapse.json）。',
+    lists: '按 audit.listCandidates 逐条数组化：数组变量进 dictionary.inputParams（字段名照 values 列语义化命名，禁 text1/val2），ListLayout/GridLayout 的 value 用 itemValueFrom:"1" 绑 $数组，一行的完整结构写进 slotScope 插槽（$<字段名> / $$ / $_index）。范式 ir-format.md §2f + recipe_snippets/list-expand-collapse.json。',
+    images: '给每个 Image 节点补 itemKey="value" 且值非空；静态路径用 itemValueFrom:"2"，变量绑定用 "1" + $表达式。',
+    slices: '跑 crop_slices.mjs --from-audit .cache/ai-scratch/<id>.audit.json 把缺失切图落进 src/slices，或修正引用名。',
+  }
+  return {
+    cardId,
+    ready,
+    stage: ready ? 'ready' : firstFail,
+    blockers,
+    hint: ready ? null : HINT[firstFail] || null,
+    checks,
+  }
+}
+
+/* ── CLI ───────────────────────────────────────────────────────────── */
+function parseArgs(argv) {
+  const out = { id: '', schema: '', spec: '', design: '', audit: '', card: 0, slicesDir: '', json: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--id') out.id = argv[++i] || ''
+    else if (a === '--schema') out.schema = argv[++i] || ''
+    else if (a === '--spec') out.spec = argv[++i] || ''
+    else if (a === '--design') out.design = argv[++i] || ''
+    else if (a === '--audit') out.audit = argv[++i] || ''
+    else if (a === '--card') out.card = Number(argv[++i]) || 0
+    else if (a === '--slices-dir') out.slicesDir = argv[++i] || ''
+    else if (a === '--json') out.json = true
+    else if (a === '-h' || a === '--help') {
+      console.log('Usage: node readiness.mjs --id <cardId> [--spec <spec.json>] [--design <card-N.png>] [--audit <audit.json>] [--card N] [--json]')
+      console.log('退出码：0 = 就绪；3 = 未就绪（内容没准备好，不是脚本报错）；1 = 用法/IO 错误')
+      process.exit(0)
+    }
+  }
+  if (!out.id && !out.schema) {
+    console.error('缺少 --id <cardId> 或 --schema <schema.json>')
+    process.exit(1)
+  }
+  return out
+}
+
+function main() {
+  const a = parseArgs(process.argv.slice(2))
+  let report
+  try {
+    report = buildReadinessReport({
+      cardId: a.id,
+      schemaPath: a.schema,
+      specPath: a.spec,
+      designPath: a.design,
+      auditPath: a.audit,
+      cardIndex: a.card,
+      slicesDir: a.slicesDir || DEFAULT_SLICES_DIR,
+    })
+  } catch (e) {
+    console.error(String(e?.message || e))
+    process.exit(1)
+  }
+  if (a.json) {
+    console.log(JSON.stringify(report, null, 2))
+  } else {
+    if (report.ready) {
+      console.log(`[readiness] ✅ ${report.cardId} 内容就绪：要素齐全 / 变量绑定完备 / 图片与切图路径已配置 —— 可以进像素循环。`)
+    } else {
+      console.log(`[readiness] ❌ ${report.cardId} 未就绪（stage=${report.stage}）：${report.blockers.length} 条阻塞项`)
+      for (const x of report.blockers) console.log(`  ❌ ${x}`)
+      if (report.hint) console.log(`  → ${report.hint}`)
+    }
+    for (const x of report.checks?.spec?.notes || []) console.log(`  ℹ ${x}`)
+  }
+  // 3 = 内容未就绪（调用方据此跳过 render + pixelDiff 并拒绝消耗迭代轮次）；与 1（脚本报错）/2（gate-fail）区分
+  process.exit(report.ready ? 0 : 3)
+}
+
+const _thisScript = process.argv[1] ? path.resolve(process.argv[1]) : ''
+if (_thisScript && import.meta.url === pathToFileURL(_thisScript).href) {
+  main()
+}

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

@@ -26,6 +26,7 @@ import path from 'node:path'
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { cardsDir, skillRoot } from './lib/paths.mjs'
+import { probePython, resolvePython as pickPython } from './lib/python.mjs'
 import { extractCardFeatures, loadRegistry } from './build_card_templates.mjs'
 
 const OUT = path.join(skillRoot, 'references', 'card_templates.json')
@@ -46,15 +47,11 @@ function parseArgs(argv) {
   return out
 }
 
+/** Python 解释器；解析集中在 lib/python.mjs。**保留 null 语义**：healthGate 靠它区分
+ *  「没装 Python」（给 `python-not-found` 原因），而不是带着假解释器去试跑。 */
 function resolvePython() {
-  if (process.env.DSL_PYTHON) return process.env.DSL_PYTHON
-  for (const cmd of ['python3', 'python']) {
-    try {
-      execFileSync(cmd, ['--version'], { stdio: 'ignore', timeout: 5000 })
-      return cmd
-    } catch { /* try next */ }
-  }
-  return null
+  const bin = pickPython()
+  return probePython(bin) ? bin : null
 }
 
 /** 健康门禁：validate 0 error + lint 0 error。返回 { ok, reasons[] } */