cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * apply_opacity_pattern.mjs — 把「透明度表达式节点」机械改写成透明度切换固定范式（R57）。
+ *
+ * 背景：移动端渲染不支持 style.other.opacity 走表达式（itemValueFrom:"1"），只有预览环境可能生效。
+ * 范式：按该节点用到的透明度取值生成等量「静态透明度变体」，统一套进一层 Row/Column 容器；
+ *       容器宽高 = 被展示节点宽高 + other.overflow:"hidden"（隐藏变体若仍占位则被裁掉）；
+ *       点击等事件全部移到容器上；变体之间用互斥 v-show 显隐切换，视觉上等价于透明度变化。
+ *       完整说明见 references/recipes.md §17 + references/recipe_snippets/opacity-switch.json。
+ *
+ * 用法：
+ *   node scripts/apply_opacity_pattern.mjs --id <cardId>              # 改写全部透明度表达式节点
+ *   node scripts/apply_opacity_pattern.mjs --id <cardId> --check      # 只报告，不写盘（有则 exit 1）
+ *   node scripts/apply_opacity_pattern.mjs --id <cardId> --dry --json # 预览改写结果（JSON）
+ *   node scripts/apply_opacity_pattern.mjs --id <cardId> --node comp_8 --container Column
+ *
+ * 可解析的透明度表达式：单三元 `COND ? A : B`、右嵌套三元 `C1 ? A : C2 ? B : C`。
+ * 其他形态（函数调用/查表）无法机械拆解 → exit 2，按范式手工改写。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { cardSchemaPath, metaDir, readJson } from './lib/paths.mjs'
+
+const VSHOW_WRAP_REQUIRED = new Set([
+  'MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'Map', 'Video', 'ViewContainer',
+])
+
+function parseArgs(argv) {
+  const o = { id: '', node: [], container: 'Row', check: false, dry: false, json: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--id') o.id = argv[++i]
+    else if (a === '--node') o.node.push(argv[++i])
+    else if (a === '--container') o.container = argv[++i]
+    else if (a === '--check') o.check = true
+    else if (a === '--dry') o.dry = true
+    else if (a === '--json') o.json = true
+  }
+  return o
+}
+
+/* ---------- style-meta：itemId 权威来源 ---------- */
+const styleMeta = readJson(path.join(metaDir, 'style-meta.json'), {})
+const GROUP = {}
+for (const g of styleMeta.properties || []) {
+  if (!g.itemKey) continue
+  GROUP[g.itemKey] = {
+    itemId: g.itemId,
+    children: Object.fromEntries((g.itemChildren || []).filter((c) => c.itemKey).map((c) => [c.itemKey, c.itemId])),
+  }
+}
+function gitemId(groupKey) {
+  const g = GROUP[groupKey]
+  if (!g) throw new Error(`style-meta 里没有样式组 ${groupKey}`)
+  return g.itemId
+}
+function citemId(groupKey, childKey) {
+  const id = (GROUP[groupKey] || {}).children?.[childKey]
+  if (!id) throw new Error(`style-meta 里 ${groupKey} 组没有子项 ${childKey}`)
+  return id
+}
+
+const leaf = (groupKey, key, value) => ({
+  itemId: citemId(groupKey, key), itemKey: key, itemName: key, itemType: '',
+  itemValueFrom: '0', itemValue: value, itemDefaultValue: value,
+})
+const group = (key, children) => ({
+  itemId: gitemId(key), itemKey: key, itemName: key, itemType: 'group',
+  itemValueFrom: '0', itemValue: {}, itemDefaultValue: {},
+  itemChildren: { properties: children },
+})
+
+/* ---------- 读节点样式 ---------- */
+function styleProps(node) { return ((node.style || {}).properties) || [] }
+function groupOf(node, key) { return styleProps(node).find((p) => p.itemKey === key) }
+function childOf(node, key, childKey) {
+  return (((groupOf(node, key) || {}).itemChildren || {}).properties || []).find((c) => c.itemKey === childKey)
+}
+function valOf(node, key, childKey) {
+  const c = childOf(node, key, childKey)
+  return c ? c.itemValue : undefined
+}
+function opacityProp(node) { return childOf(node, 'other', 'opacity') }
+
+function isExprOpacity(node) {
+  const c = opacityProp(node)
+  if (!c) return false
+  return c.itemValueFrom === '1' || (typeof c.itemValue === 'string' && c.itemValue.includes('$'))
+}
+
+/* ---------- 透明度表达式 → 变体表 ---------- */
+function parseOpacityExpr(expr) {
+  const src = String(expr).trim()
+  const variants = []
+  let rest = src
+  for (;;) {
+    const m = rest.match(/^(.+?)\s*\?\s*(-?[\d.]+)\s*:\s*([\s\S]+)$/)
+    if (!m) break
+    variants.push({ cond: m[1].trim(), opacity: m[2] })
+    rest = m[3].trim()
+    // 右嵌套三元：剥掉外层括号继续
+    if (rest.startsWith('(') && rest.endsWith(')')) rest = rest.slice(1, -1).trim()
+  }
+  if (!variants.length) return null
+  if (!/^-?[\d.]+$/.test(rest)) return null
+  variants.push({ cond: null, opacity: rest })
+  return variants
+}
+
+function negate(conds) {
+  return conds.map((c) => `!(${c})`).join(' && ')
+}
+
+function condName(expr, opacity) {
+  if (expr.length < 15) return expr
+  return `透明度${opacity}：${expr.replace(/\$/g, '').replace(/\s+/g, '')}`
+}
+
+/* ---------- v-show 指令 ---------- */
+function vshow(expr, name) {
+  const showType = {
+    itemId: '001', itemKey: 'showType', itemName: 'showType', itemType: '',
+    itemValueFrom: '0', itemValue: '01', itemDefaultValue: '01',
+  }
+  const condition = {
+    itemId: '002', itemKey: 'condition', itemName: 'condition', itemType: '',
+    itemValueFrom: '0', itemValue: { expression: expr, name },
+    itemDefaultValue: { expression: expr, name },
+  }
+  return {
+    itemId: '001', itemKey: 'v-show', itemName: 'v-show', itemType: '',
+    itemValueFrom: '0', itemValue: {}, itemDefaultValue: {},
+    itemChildren: { properties: [showType, condition] },
+  }
+}
+
+const clone = (x) => JSON.parse(JSON.stringify(x))
+
+/* ---------- 构造变体节点 ---------- */
+function buildVariant(node, { id, cond, opacity, needsVshowWrapper }) {
+  const variant = clone(node)
+  variant.componentId = id
+  variant.eventactions = []          // 事件一律上移到容器
+  variant.directives = []
+  // margin 归零：外边距由容器承载，避免变体各带一份外边距
+  const op = opacityProp(variant)
+  if (op) {
+    op.itemValueFrom = '0'
+    op.itemValue = String(opacity)
+    op.itemDefaultValue = String(opacity)
+  }
+  const marginGroup = groupOf(variant, 'margin')
+  if (marginGroup) {
+    for (const c of (marginGroup.itemChildren || {}).properties || []) {
+      const zero = c.itemKey === 'marginType' ? '' : '0'
+      c.itemValue = zero
+      c.itemDefaultValue = zero
+    }
+  }
+  if (!needsVshowWrapper) {
+    variant.directives = [vshow(cond.expression, cond.name)]
+    return { outer: variant, id }
+  }
+  // 特殊节点（List/Grid/Canvas…）不能直接挂 v-show（R53）：每个变体再套一层承载显隐的 Row
+  const w = valOf(node, 'rect', 'width')
+  const h = valOf(node, 'rect', 'height')
+  const wrapId = `${id}_v`
+  const wrapper = {
+    componentId: wrapId,
+    className: 'Row',
+    name: 'Row',
+    style: {
+      properties: [
+        group('rect', [
+          leaf('rect', 'width', w === undefined ? 'auto' : String(w)),
+          leaf('rect', 'height', h === undefined ? 'auto' : String(h)),
+        ]),
+        group('flex', [
+          leaf('flex', 'justifyContent', 'center'),
+          leaf('flex', 'alignItems', 'center'),
+          leaf('flex', 'gap', '0'),
+          leaf('flex', 'flexShrink', '0'),
+        ]),
+        group('padding', [leaf('padding', 'paddingType', '0'), leaf('padding', 'padding', '0')]),
+        group('other', [leaf('other', 'overflow', 'hidden')]),
+      ],
+    },
+    properties: [],
+    directives: [vshow(cond.expression, cond.name)],
+    eventactions: [],
+    slots: [{ slotKey: 'default', slotName: '默认插槽', slotSwitch: '1', components: [variant] }],
+  }
+  return { outer: wrapper, id: wrapId }
+}
+
+/* ---------- 构造容器 ---------- */
+function buildContainer(node, variants, containerClass) {
+  const width = valOf(node, 'rect', 'width')
+  const height = valOf(node, 'rect', 'height')
+  const shrink = valOf(node, 'flex', 'flexShrink')
+  const props = [
+    // 容器宽高必须与被展示节点一致（范式硬约束）
+    group('rect', [
+      leaf('rect', 'width', width === undefined ? 'auto' : String(width)),
+      leaf('rect', 'height', height === undefined ? 'auto' : String(height)),
+    ]),
+    group('flex', [
+      leaf('flex', 'justifyContent', 'center'),
+      leaf('flex', 'alignItems', 'center'),
+      leaf('flex', 'gap', '0'),
+      leaf('flex', 'flexShrink', shrink === undefined ? '0' : String(shrink)),
+    ]),
+    group('background', [leaf('background', 'backgroundType', '00')]),
+    group('padding', [leaf('padding', 'paddingType', '0'), leaf('padding', 'padding', '0')]),
+  ]
+  // 原节点的外边距搬到容器（保持在父布局里的位置）
+  const marginGroup = groupOf(node, 'margin')
+  if (marginGroup) props.push(clone(marginGroup))
+  // 隐藏溢出：v-show 在部分渲染实现里只隐藏不脱流，靠裁切保证外部布局不被撑开
+  props.push(group('other', [leaf('other', 'overflow', 'hidden')]))
+
+  return {
+    componentId: `${node.componentId}_box`,
+    className: containerClass,
+    name: containerClass,
+    style: { properties: props },
+    properties: [],
+    directives: clone(node.directives || []),   // 原节点自身的显隐条件留在容器上
+    eventactions: clone(node.eventactions || []), // 点击等事件挂在容器上
+    slots: [{ slotKey: 'default', slotName: '默认插槽', slotSwitch: '1', components: variants }],
+  }
+}
+
+/* ---------- 遍历改写 ---------- */
+function childArrays(node) {
+  const arrs = []
+  if (Array.isArray(node.components)) arrs.push(node.components)
+  for (const s of node.slots || []) if (Array.isArray(s.components)) arrs.push(s.components)
+  return arrs
+}
+
+function transform(view, opts) {
+  const changed = []
+  const seen = new Set()
+  const walkNode = (node) => {
+    for (const arr of childArrays(node)) {
+      for (let i = 0; i < arr.length; i++) {
+        const child = arr[i]
+        if (isExprOpacity(child) && (!opts.node.length || opts.node.includes(child.componentId))) {
+          arr[i] = rewrite(child, opts, changed, seen)
+        }
+        walkNode(arr[i])
+      }
+    }
+  }
+  walkNode(view)
+  return changed
+}
+
+function rewrite(node, opts, changed, seen) {
+  if (seen.has(node.componentId)) return node
+  seen.add(node.componentId)
+  const expr = String(opacityProp(node).itemValue)
+  const parsed = parseOpacityExpr(expr)
+  if (!parsed) {
+    throw Object.assign(new Error(
+      `${node.className} "${node.componentId}" 的透明度表达式无法机械拆解：${expr}\n` +
+      '请按 references/recipes.md §17 手工改写（枚举用到的透明度取值 → 等量静态变体 + 容器 + 互斥 v-show）。'
+    ), { code: 'unparsable-opacity-expr' })
+  }
+  const opacities = [...new Set(parsed.map((v) => v.opacity))]
+  const needsVshowWrapper = VSHOW_WRAP_REQUIRED.has(node.className)
+  const conds = []
+  const variants = parsed.map((v, idx) => {
+    const expression = v.cond ? v.cond : negate(conds.slice())
+    if (v.cond) conds.push(v.cond)
+    const cond = { expression, name: condName(expression, v.opacity) }
+    const id = idx === 0 ? node.componentId : `${node.componentId}_op${idx}`
+    return buildVariant(node, { id, cond, opacity: v.opacity, needsVshowWrapper }).outer
+  })
+  const container = buildContainer(node, variants, opts.container)
+  changed.push({
+    componentId: node.componentId,
+    className: node.className,
+    containerId: container.componentId,
+    containerClass: opts.container,
+    expression: expr,
+    opacities,
+    variants: variants.map((v) => v.componentId),
+    conditions: variants.map((v, idx) => {
+      const src = idx === 0 && !needsVshowWrapper ? v : v
+      const d = (src.directives || [])[0]
+      const c = (((d || {}).itemChildren || {}).properties || []).find((p) => p.itemKey === 'condition')
+      return (c || {}).itemValue
+    }),
+    eventsMoved: (node.eventactions || []).length,
+  })
+  return container
+}
+
+/* ---------- main ---------- */
+const opts = parseArgs(process.argv.slice(2))
+if (!opts.id) {
+  console.error('用法: node scripts/apply_opacity_pattern.mjs --id <cardId> [--check|--dry] [--json] [--node <cid>] [--container Row|Column]')
+  process.exit(1)
+}
+const schemaPath = cardSchemaPath(opts.id)
+if (!fs.existsSync(schemaPath)) {
+  console.error(`[apply_opacity_pattern] 找不到卡片 schema: ${schemaPath}`)
+  process.exit(1)
+}
+const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+
+// --check：只报告存在透明度表达式的节点
+if (opts.check) {
+  const found = []
+  const walkNode = (n) => {
+    if (isExprOpacity(n)) found.push({ componentId: n.componentId, className: n.className, expression: String(opacityProp(n).itemValue) })
+    for (const arr of childArrays(n)) for (const c of arr) walkNode(c)
+  }
+  walkNode(schema.view)
+  if (opts.json) console.log(JSON.stringify({ id: opts.id, ok: found.length === 0, found }, null, 2))
+  else if (found.length) {
+    console.log(`[apply_opacity_pattern] ${opts.id}: ${found.length} 个节点用了透明度表达式（R57 禁止）`)
+    for (const f of found) console.log(`  - ${f.className} ${f.componentId}: opacity="${f.expression}"`)
+  } else console.log(`[apply_opacity_pattern] ${opts.id}: 无透明度表达式节点`)
+  process.exit(found.length ? 1 : 0)
+}
+
+let changed
+try {
+  changed = transform(schema.view, opts)
+} catch (e) {
+  console.error(`[apply_opacity_pattern] ${e.message}`)
+  process.exit(e.code === 'unparsable-opacity-expr' ? 2 : 1)
+}
+
+if (!changed.length) {
+  console.log(JSON.stringify({ id: opts.id, changed: 0, note: '没有需要改写的透明度表达式节点' }, null, 2))
+  process.exit(0)
+}
+if (!opts.dry) fs.writeFileSync(schemaPath, JSON.stringify(schema, null, 2) + '\n', 'utf8')
+console.log(JSON.stringify({ id: opts.id, written: !opts.dry, changed: changed.length, nodes: changed }, null, 2))

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * build_card_index.mjs — 预计算「卡片索引」，让智能体选近邻模板时查表而非扫源文件。
+ *
+ * 扫描宿主项目卡片目录（默认 <cwd>/src/cards）下每张卡的 schema.json，对每张卡提取：
+ *   - components：用到的组件类集合
+ *   - recipes：用到的范式（alertCard / globalSet / money-format / list-expand / canvas-head / tab-billMode）
+ *   - tags：结构信号 + 通用 UI 意图词（list / detail / form / dialog / result / canvas / amount / tab / interactive）
+ *
+ * 输出 <skill>/references/card_index.json，供 SKILL.md 的「意图路由表」直接查。
+ *
+ * 用法：node scripts/build_card_index.mjs
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { cardsDir, skillRoot } from './lib/paths.mjs'
+
+const CARDS_DIR = cardsDir
+const OUT = path.join(skillRoot, 'references', 'card_index.json')
+
+/* ---- recipe 探测（对整卡文本做子串/特征匹配） ---- */
+const RECIPE_PROBES = [
+  { key: 'alertCard', test: (t) => /alertCard/.test(t) },
+  { key: 'globalSet', test: (t) => /globalSet/.test(t) },
+  { key: 'money-format', test: (t) => /toFixed\(/.test(t) && /replace\(/.test(t) || /formatMoney/.test(t) },
+  { key: 'list-expand', test: (t) => /showAll/.test(t) },
+  { key: 'canvas-head', test: (t) => /onMeasured/.test(t) },
+  { key: 'tab-billMode', test: (t) => /billMode/.test(t) || /activeTab/.test(t) },
+]
+
+/* ---- 标签启发（结构信号优先，卡名仅用通用 UI 意图词，不含具体业务实体名） ---- */
+function inferTags(name, components, recipes) {
+  const tags = new Set()
+  const has = (re) => re.test(name || '')
+  // 结构信号（优先，无业务词依赖）
+  if (components.includes('ListLayout') || components.includes('GridLayout')) tags.add('list')
+  if (components.includes('Input')) tags.add('form')
+  if (components.includes('Canvas')) tags.add('canvas')
+  if (recipes.includes('alertCard')) tags.add('dialog')
+  if (recipes.includes('tab-billMode')) tags.add('tab')
+  if (recipes.includes('money-format')) tags.add('amount')
+  if (recipes.includes('list-expand')) tags.add('list')
+  if (recipes.includes('globalSet')) tags.add('interactive')
+  // 通用 UI 意图词兜底（非业务实体名；如"列表/表单/弹窗/结果/详情"等）
+  if (has(/列表|清单|list|记录/)) tags.add('list')
+  if (has(/弹窗|dialog|对话框/)) tags.add('dialog')
+  if (has(/表单|输入|密码|验证|form/)) tags.add('form')
+  if (has(/成功|失败|结果|result|success|failed/)) tags.add('result')
+  if (has(/详情|detail/)) tags.add('detail')
+  return [...tags]
+}
+
+// 子节点双通道：既可能在 node.components（如 Root 直连），也可能在 node.slots[].components
+// （如 Row/Column 的插槽）——历史上只走 slots 通道，导致 Root 直连子树整棵丢失、
+// card_index 的 components 字段退化为只剩 ["Root"]。
+function collectComponents(node, out) {
+  if (!node || typeof node !== 'object') return
+  if (node.className) out.add(node.className)
+  for (const c of node.components || []) collectComponents(c, out)
+  for (const s of node.slots || []) for (const c of s.components || []) collectComponents(c, out)
+}
+
+export { RECIPE_PROBES, inferTags, collectComponents }
+
+function main() {
+  if (!fs.existsSync(CARDS_DIR)) { console.error('[error] 未找到 src/cards：' + CARDS_DIR); process.exit(1) }
+  const cards = []
+  for (const id of fs.readdirSync(CARDS_DIR).sort()) {
+    const dir = path.join(CARDS_DIR, id)
+    const schemaPath = path.join(dir, 'schema.json')
+    if (!fs.statSync(dir).isDirectory() || !fs.existsSync(schemaPath)) continue
+    let schema
+    try { schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8')) } catch { continue }
+    const text = JSON.stringify(schema)
+    const compSet = new Set()
+    collectComponents(schema.view, compSet)
+    const recipes = RECIPE_PROBES.filter((p) => p.test(text)).map((p) => p.key)
+    const name = schema.name || id
+    const tags = inferTags(name, [...compSet], recipes)
+    cards.push({
+      id,
+      name,
+      pageId: schema.pageId || '',
+      components: [...compSet].sort(),
+      recipes,
+      tags,
+    })
+  }
+  const index = {
+    generatedAt: new Date().toISOString(),
+    cardCount: cards.length,
+    cards,
+  }
+  fs.mkdirSync(path.dirname(OUT), { recursive: true })
+  fs.writeFileSync(OUT, JSON.stringify(index, null, 2) + '\n')
+  console.log(`[ok] 已生成卡片索引：${OUT}（${cards.length} 张）`)
+  // 打印意图覆盖概览
+  const byTag = {}
+  for (const c of cards) for (const t of c.tags) byTag[t] = (byTag[t] || 0) + 1
+  console.log('标签覆盖：' + JSON.stringify(byTag))
+}
+
+// 仅当作为 CLI 直接运行时才执行（被 import 复用探测/遍历函数时不执行）
+const _thisScript = fs.realpathSync(fileURLToPath(import.meta.url))
+const _calledAs = process.argv[1] ? fs.realpathSync(path.resolve(process.argv[1])) : ''
+if (_thisScript === _calledAs) main()

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

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * build_card_templates.mjs — 从存量卡提炼「整卡模板库」（全量重建）。
+ *
+ * 与空骨架（scaffold_card --intent）的边界：
+ *  - 空骨架出「最小合法结构」，快但版式纪律要从零重建；
+ *  - 整卡模板出「克隆最近邻真实卡 + 改写」，天然继承存量卡已验证的版式/绑定/范式。
+ *
+ * 聚类：按卡片结构标签（inferTags 产出的通用 UI 意图词）归簇——纯结构信号，
+ * 不含业务词，设计稿风格变化不影响聚类逻辑。
+ *
+ * 代表卡选择（确定性打分，同分取字典序小的保证可复现）：
+ *   score = recipe 命中数 × 10 + 组件种类数 × 2 − 节点数 × 0.01
+ *
+ * 与 register_card_template.mjs 的协作（沉淀闭环）：
+ *  - 本工具是全量重建；register 是单卡登记（沉淀时刻）。
+ *  - 重建时**保留** register 写入的人工资产：pinned 代表卡（不被打分顶替）、
+ *    keywords（意图路由词）、custom 自定义簇；仅当 pinned 源卡被删除时才回退打分。
+ *
+ * 输出 references/card_templates.json，供 scaffold_card.mjs --from / MCP card_scaffold
+ * 的 from 参数、resolve_card_template.mjs 意图路由使用。
+ *
+ * 用法：node skills/dsl-card-generator/scripts/build_card_templates.mjs [--json]
+ * 退出码：0 = 正常。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cardsDir, skillRoot } from './lib/paths.mjs'
+import { RECIPE_PROBES, inferTags, collectComponents } from './build_card_index.mjs'
+
+const OUT = path.join(skillRoot, 'references', 'card_templates.json')
+
+/** 簇优先级：一张卡可能同时命中多个标签，按此顺序归入最特异的一个簇 */
+const CLUSTER_ORDER = ['dialog', 'form', 'result', 'tab', 'canvas', 'list', 'amount', 'detail', 'interactive', 'other']
+
+/** 内置簇的种子意图关键词（通用 UI 意图词，非业务词；register 登记的自定义词会合入） */
+const SEED_KEYWORDS = {
+  dialog: ['弹窗', '弹框', '对话框', 'dialog'],
+  form: ['表单', '输入', 'form'],
+  result: ['结果', '成功', '失败', 'result'],
+  tab: ['多tab', '页签', '切换', 'tab'],
+  canvas: ['图表', '仪表盘', '画布', '环形图', 'canvas'],
+  list: ['列表', '清单', '记录', 'list'],
+  amount: ['金额', '账单', '数值', 'amount'],
+  detail: ['详情', 'detail'],
+  interactive: ['交互', '联动', 'interactive'],
+  other: ['其他'],
+}
+
+/** 测试夹具卡（脚手架回归/全组件自测）不是生产版式，不进入模板候选 */
+const TEST_FIXTURE_RE = /(^dsl_test|[-_]test)/i
+
+function countNodes(node) {
+  if (!node || typeof node !== 'object') return 0
+  let n = 1
+  for (const c of node.components || []) n += countNodes(c)
+  for (const s of node.slots || []) for (const c of s.components || []) n += countNodes(c)
+  return n
+}
+
+function clusterOf(tags) {
+  for (const key of CLUSTER_ORDER) if (tags.includes(key)) return key
+  return 'other'
+}
+
+/** 提取单卡模板特征（签名）。供本工具与 register/resolve 复用（同一份定义）。 */
+export function extractCardFeatures(id) {
+  const schemaPath = path.join(cardsDir, id, 'schema.json')
+  if (!fs.existsSync(schemaPath)) return null
+  let schema
+  try {
+    schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  } catch {
+    return null
+  }
+  const text = JSON.stringify(schema)
+  const compSet = new Set()
+  collectComponents(schema.view, compSet)
+  const recipes = RECIPE_PROBES.filter((p) => p.test(text)).map((p) => p.key)
+  const tags = inferTags(schema.name || id, [...compSet], recipes)
+  const nodeCount = countNodes(schema.view)
+  return {
+    id,
+    name: schema.name || id,
+    tags,
+    recipes,
+    components: [...compSet].sort(),
+    nodeCount,
+    cluster: clusterOf(tags),
+    score: recipes.length * 10 + compSet.size * 2 - nodeCount * 0.01,
+  }
+}
+
+/** 读取现有注册表（不存在返回空壳） */
+export function loadRegistry() {
+  try {
+    return JSON.parse(fs.readFileSync(OUT, 'utf8'))
+  } catch {
+    return { clusters: [] }
+  }
+}
+
+function main() {
+  const asJson = process.argv.includes('--json')
+  const cards = []
+  for (const id of fs.readdirSync(cardsDir).sort()) {
+    if (TEST_FIXTURE_RE.test(id)) continue
+    const dir = path.join(cardsDir, id)
+    if (!fs.statSync(dir).isDirectory()) continue
+    const f = extractCardFeatures(id)
+    if (f) cards.push(f)
+  }
+
+  const prev = loadRegistry()
+  const prevByKey = new Map((prev.clusters || []).map((c) => [c.key, c]))
+  const aliveIds = new Set(cards.map((c) => c.id))
+  const preservedNotes = []
+
+  const clusters = []
+  for (const key of CLUSTER_ORDER) {
+    const members = cards.filter((c) => c.cluster === key)
+    if (!members.length) continue
+    members.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+    const old = prevByKey.get(key)
+    const pinnedAlive = old && old.template && old.template.pinned && aliveIds.has(old.template.sourceCard)
+    // pin 是人工意图，优先于自动聚类：pinned 源卡即使自动簇判定落在别的簇
+    // （不在本簇 members 里），也必须保住代表位，按其真实特征刷新模板信息。
+    const t = pinnedAlive ? extractCardFeatures(old.template.sourceCard) || members[0] : members[0]
+    if (old && old.template && old.template.pinned && !pinnedAlive) {
+      preservedNotes.push(`簇 ${key}：pinned 模板 ${old.template.sourceCard} 已不存在，回退为打分选代表`)
+    }
+    const keywords = [...new Set([...(SEED_KEYWORDS[key] || []), ...((old && old.keywords) || [])])]
+    clusters.push({
+      key,
+      keywords,
+      cardCount: members.length,
+      template: {
+        sourceCard: t.id,
+        name: t.name,
+        tags: t.tags,
+        recipes: t.recipes,
+        components: t.components,
+        nodeCount: t.nodeCount,
+        ...(pinnedAlive ? { pinned: true } : {}),
+      },
+      members: members.map((m) => m.id),
+    })
+  }
+
+  // 保留 register 登记的自定义簇（源卡存活才保留）
+  for (const old of prevByKey.values()) {
+    if (!old.custom) continue
+    if (!old.template || !aliveIds.has(old.template.sourceCard)) {
+      preservedNotes.push(`自定义簇 ${old.key}：模板卡 ${old.template ? old.template.sourceCard : '?'} 已不存在，簇被移除`)
+      continue
+    }
+    const f = extractCardFeatures(old.template.sourceCard)
+    clusters.push({
+      ...old,
+      template: { ...old.template, ...(f ? { tags: f.tags, recipes: f.recipes, components: f.components, nodeCount: f.nodeCount, name: f.name } : {}) },
+    })
+  }
+
+  const registry = {
+    generatedAt: new Date().toISOString(),
+    cardCount: cards.length,
+    hint: '整卡模板库：克隆模板卡改写 = scaffold_card.mjs --from <sourceCard> 或 MCP card_scaffold(from=...)；意图路由查 keywords（resolve_card_template.mjs）；新模式登记用 register_card_template.mjs。',
+    clusters,
+  }
+  fs.mkdirSync(path.dirname(OUT), { recursive: true })
+  fs.writeFileSync(OUT, JSON.stringify(registry, null, 2) + '\n')
+
+  if (asJson) {
+    console.log(JSON.stringify(registry, null, 2))
+  } else {
+    console.log(`[ok] 已生成整卡模板库：${OUT}（${cards.length} 张卡 → ${clusters.length} 簇）`)
+    for (const c of clusters) {
+      const pin = c.template.pinned ? '📌' : '  '
+      console.log(
+        ` ${pin}${c.key.padEnd(12)} ${String(c.cardCount).padStart(2)} 卡  模板=${c.template.sourceCard}（${c.template.name}，${c.template.nodeCount} 节点）`,
+      )
+    }
+    for (const n of preservedNotes) console.log(`  ⚠️ ${n}`)
+  }
+}
+
+const _thisScript = fs.realpathSync(fileURLToPath(import.meta.url))
+const _calledAs = process.argv[1] ? fs.realpathSync(path.resolve(process.argv[1])) : ''
+if (_thisScript === _calledAs) main()