cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/skills/sketch-spec-to-card/scripts/cluster_states.py

@@ -0,0 +1,706 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+cluster_states.py — sketch-spec-to-card 卡片维度聚类与产物聚合（2026-08-14 重写）。
+
+把 parse_meaxure.py（视觉驱动）产出的 UI/<画板>/spec.json 按「卡片维度」聚类为
+逻辑卡片，并聚合多状态产物：
+
+  输入：UI/<画板名>/spec.json （每画板含 cards/elements/styleSummary/artboardType）
+  输出：UI/cards/<cardKey>/          按卡片维度聚合的产物
+          card.json                  卡片元信息：状态集合 / 交互 / 样式 / 列表 / 维度
+          states/<stateKey>.png       各状态的代表性聚焦截图（从对应画板 card-*.png 软链/拷贝）
+          states/<stateKey>/spec.json 该状态的视觉要素标注（复制自画板 spec.json）
+        UI/clusters.json              全局聚类 + 每卡状态模型 + 交互维度
+        UI/interactions/index.yaml    跨卡片交互图（弹框/子卡父子关系）
+
+设计原则（HANDOFF Part 1 判定原则）：
+  - 抽象通用化：状态键用 state-overview/state-empty/state-selected 等抽象名，不写业务词。
+  - 子卡独立成卡：subcard 独立一个 cardKey，仅通过 parentKey 与父卡建立交互关系。
+  - 多状态聚焦截图在同一卡片下：一张卡片可对应多个画板（多状态），各自一张聚焦图。
+
+用法：
+  python cluster_states.py --out <UI目录>
+  python cluster_states.py --out <UI目录> --auto-refs       # 从 src/cards 动态探测参考卡
+
+设计原则（强化）：维度判定 100% 基于视觉结构（指纹 diff / Jaccard 相似度），
+不依赖任何业务文案、枚举值列表、领域关键词。换业务域零调整即可生效。
+残留的语法功能词（否定前缀/登录态/结果尾缀）仅用于状态键命名归类，不参与维度判定。
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from collections import defaultdict
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+from card_refs import load_card_refs
+
+ALERTDIALOG_REF_CARDS = []
+ALERTCARD_REF_CARDS = []
+
+# ----------------------------------------------------------------------------
+# 1. 维度识别：纯结构（fingerprint diff），无业务词集
+# ----------------------------------------------------------------------------
+# 设计原则：维度判定依据 = 同卡片多状态间的视觉结构差异（文本/块/颜色集合的增减），
+# 绝不依赖任何业务文案、枚举值列表、领域关键词。换业务域零调整即可生效。
+# 残留的语法功能词（否定前缀/登录态等）仅用于状态键命名，不参与维度判定。
+
+# 语法功能标记（跨业务通用，非领域词）：用于把结构检测出的状态归入抽象状态键。
+# 仅匹配画板名 qualifier token 的「语法角色」，不匹配任何业务实体名。
+_NEG_PREFIX = re.compile(r"^(无|未|空|没)(?=[\u4e00-\u9fff])")  # 否定前缀：无/未/空/没+汉字
+_EMPTY_HINT = re.compile(r"^(空|无.{0,4}|未登录|未绑定|暂无|没有)")  # 空态语法（保守）
+_RESULT_HINT = re.compile(r"(成功|失败|完成|结果|处理中|已.{0,2})$")  # 结果态语法尾缀
+_SELECTED_HINT = re.compile(r"(选中|已选|激活|active|selected)", re.I)
+_AUTH_HINT = re.compile(r"(登录|授权|登入)", re.I)
+# 过渡态：画板名 qualifier 指向另一卡（跨卡跳转），由结构判定，不用业务名正则
+
+
+def _resolve_src_cards(explicit):
+    if explicit:
+        return explicit
+    repo_root = os.path.dirname(os.path.dirname(SCRIPT_DIR))
+    cand = os.path.join(repo_root, "src", "cards")
+    return cand if os.path.isdir(cand) else None
+
+
+# ----------------------------------------------------------------------------
+# 2. 画板名解析（抽象、通用）
+# ----------------------------------------------------------------------------
+def normalize_name(canvas_name):
+    return re.sub(r"^\d+", "", canvas_name or "").strip()
+
+
+def card_key(canvas_name):
+    return normalize_name(canvas_name).split("_", 1)[0]
+
+
+def qualifiers(canvas_name):
+    nm = normalize_name(canvas_name)
+    if "_" not in nm:
+        return []
+    return [q for q in nm.split("_", 1)[1].split("_") if q]
+
+
+def slugify_dim(name, idx):
+    """维度绑定变量名：纯抽象 dim{idx}，不映射任何业务词。"""
+    return f"dim{idx}"
+
+
+def abstract_state_key(qs, fp=None):
+    """从 qualifier token 的语法角色推导抽象状态键（纯语法，无业务词）。
+    判定顺序：空态语法 → 结果态语法尾缀 → 选中态 → 登录态 → 默认 overview。
+    fp（指纹）可选，用于辅助空态判定（内容元素极少 → 强化空态判定）。
+    """
+    joined = "_".join(qs)
+    # 内容稀疏度（辅助）：无 fp 时保守不判
+    sparse = False
+    if fp:
+        sparse = (len(fp.get("texts", [])) + len(fp.get("blocks", []))) <= 3
+    if _EMPTY_HINT.search(joined) or sparse:
+        return "state-empty"
+    if _RESULT_HINT.search(joined):
+        return "state-result"
+    if _SELECTED_HINT.search(joined):
+        return "state-selected"
+    if _AUTH_HINT.search(joined):
+        return "state-auth"
+    return "state-overview"
+
+
+# ----------------------------------------------------------------------------
+# 3. 指纹（基于新 spec 结构：elements/cards/styleSummary）
+# ----------------------------------------------------------------------------
+def fingerprint(spec):
+    """卡片主体指纹：文本集合 + 视觉块集合 + 颜色集合（用于状态间 diff）。"""
+    texts, blocks, colors = [], [], []
+    for el in spec.get("elements", []):
+        nm = (el.get("name") or "").split("/")[-1].strip()
+        if el.get("type") == "text" and el.get("text"):
+            texts.append(str(el["text"]).strip())
+        elif el.get("type") in ("group", "shape", "symbol") and nm:
+            blocks.append(nm)
+        # 颜色
+        st = el.get("style") or {}
+        bkg = st.get("background") or {}
+        if bkg.get("color"):
+            colors.append(bkg["color"])
+        ts = el.get("textStyle") or {}
+        if ts.get("color"):
+            colors.append(ts["color"])
+    ss = spec.get("styleSummary") or {}
+    colors = sorted(set(colors)) or sorted(set(ss.get("colors", [])))
+    return {
+        "texts": sorted(set(texts)),
+        "blocks": sorted(set(blocks)),
+        "colors": colors,
+    }
+
+
+def jaccard(a, b):
+    if not a and not b:
+        return 1.0
+    return len(a & b) / len(a | b)
+
+
+def diff_fingerprint(base, other):
+    bt, bb = set(base["texts"]), set(base["blocks"])
+    ot, ob = set(other["texts"]), set(other["blocks"])
+    return {
+        "addedTexts": sorted(ot - bt),
+        "removedTexts": sorted(bt - ot),
+        "addedBlocks": sorted(ob - bb),
+        "removedBlocks": sorted(bb - ob),
+        "textJaccard": round(jaccard(bt, ot), 3),
+        "blockJaccard": round(jaccard(bb, ob), 3),
+    }
+
+
+# ----------------------------------------------------------------------------
+# 4. 维度提取（tab / conditional / form / sequential）—— 纯结构，无业务词
+# ----------------------------------------------------------------------------
+def _fp_sim(a, b):
+    """两状态指纹平均相似度（文本 Jaccard + 块 Jaccard）/2。"""
+    jt = jaccard(set(a["fp"]["texts"]), set(b["fp"]["texts"]))
+    jb = jaccard(set(a["fp"]["blocks"]), set(b["fp"]["blocks"]))
+    return (jt + jb) / 2
+
+
+def is_empty_or_error(qs, fp=None):
+    """空/错误态判定：qualifier 含否定语法前缀 或 指纹内容极稀疏。"""
+    joined = "_".join(qs)
+    if _EMPTY_HINT.search(joined):
+        return True
+    if fp and (len(fp.get("texts", [])) + len(fp.get("blocks", []))) <= 3:
+        return True
+    return False
+
+
+def _is_result_token(q):
+    """结果态语法尾缀（成功/失败/完成/已…），跨业务通用语法，非领域词。"""
+    return bool(_RESULT_HINT.search(q))
+
+
+def detect_positional_tabs(cluster_states):
+    """统一结构化维度检测（纯结构，无业务词）。
+
+    核心信号：**互斥值对跨多个独立 qualifier 分组反复共现 = 真维度**。
+    一个真正的 Tab/枚举维度（如 已出账/未出账）会在卡片的不同状态下反复出现
+    （无论其他 qualifier 是什么），因此同一值对会在多个分组里被观察到。
+    而局部状态变体（如 已逾期/已还最低）只在单一狭窄分组出现 → 不升维。
+
+    两阶段：
+    阶段A「局部配对」：对每个 qualifier 位置，按其余位置分组，组内 ≥2 个不同值
+        → 记录所有 (值A, 值B) 配对及其出现组。
+    阶段B「跨组聚合」：同一值对在 ≥2 个独立组出现 → 真维度（Tab/Conditional/Sequential）。
+        单组出现的局部变化不升维（避免把状态变体误判为维度）。
+
+    分类（基于值的语法角色，非领域词）：
+      - 含否定前缀(无/未/空) → conditional
+      - 全部带结果尾缀(成功/失败/已…) → sequential
+      - 其余 → tab
+    """
+    # 阶段A：局部配对收集
+    local_groups = defaultdict(list)
+    for st in cluster_states:
+        qs = st["qualifiers"]
+        for i in range(len(qs)):
+            key = tuple(qs[:i] + qs[i + 1:])
+            local_groups[(i, key)].append(st)
+
+    # pair_groups: {(pos, valA, valB): set(其他qualifier元组)} — 记录每对值在多少独立组出现
+    pair_groups = defaultdict(set)
+    for (i, other_key), members in local_groups.items():
+        vals = sorted({m["qualifiers"][i] for m in members})
+        if len(vals) < 2:
+            continue
+        for a in range(len(vals)):
+            for b in range(a + 1, len(vals)):
+                pair_groups[(i, vals[a], vals[b])].add(other_key)
+
+    # 阶段B：跨组聚合 — 值对在 ≥2 独立组出现才升维
+    # 先按值对集合归并（同一维度可能有多对值，如三值枚举 A/B/C 有 3 对）
+    # 用并查集合并同位置的连通值对
+    pairs_by_pos = defaultdict(list)  # pos -> [(valA, valB, group_count)]
+    for (i, va, vb), groups in pair_groups.items():
+        if len(groups) >= 2:  # ≥2 独立组才是真维度
+            pairs_by_pos[i].append((va, vb, len(groups)))
+    # 并查集合并同位置连通值
+    out = []
+    _DIM_VAL_MAXLEN = 6  # 维度值最长 6 字符（tab 标签/短枚举），过长的是状态描述非维度
+    for i, pairs in sorted(pairs_by_pos.items()):
+        if not pairs:
+            continue
+        # 过滤过长的值（状态描述如"没有已出账单也没有未出账单"不是维度标签）
+        pairs = [(va, vb, gc) for va, vb, gc in pairs
+                 if len(va) <= _DIM_VAL_MAXLEN and len(vb) <= _DIM_VAL_MAXLEN]
+        if not pairs:
+            continue
+        # 并查集
+        parent = {}
+        def find(x):
+            parent.setdefault(x, x)
+            while parent[x] != x:
+                parent[x] = parent[parent[x]]
+                x = parent[x]
+            return x
+        def union(a, b):
+            ra, rb = find(a), find(b)
+            if ra != rb:
+                parent[ra] = rb
+        for va, vb, _ in pairs:
+            union(va, vb)
+        # 按根分组
+        clusters = defaultdict(set)
+        for va, vb, _ in pairs:
+            clusters[find(va)].add(va)
+            clusters[find(vb)].add(vb)
+        for root, vals in clusters.items():
+            uniq = sorted(vals)
+            if len(uniq) < 2:
+                continue
+            # 分类：语法角色
+            # conditional 须有「纯净否定值」：整值=无/未/空/没 或 否定前缀+≤2字（无X/未X）
+            # 避免把 未出账/已出账（枚举值恰好含"未"字）误判为条件显隐
+            _PURE_NEG = re.compile(r"^(无|未|空|没|没有)$")
+            _NEG_SHORT = re.compile(r"^(无|未|空|没)(.{0,2})$")
+            has_pure_neg = any(_PURE_NEG.match(v) or _NEG_SHORT.match(v) for v in uniq)
+            # 若否定值与肯定值仅前缀不同（无X↔有X），则是条件；否则否定只是巧合 → tab
+            is_conditional = False
+            if has_pure_neg:
+                negs = [v for v in uniq if (_PURE_NEG.match(v) or _NEG_SHORT.match(v))]
+                poss = [v for v in uniq if not (_PURE_NEG.match(v) or _NEG_SHORT.match(v))]
+                # 条件显隐特征：存在 neg 与 pos 去掉前缀后词干相同（无交易↔有交易）
+                _STRIP_NEG = re.compile(r"^(无|未|空|没|没有)")
+                stems_match = any(
+                    _STRIP_NEG.sub("", n) and _STRIP_NEG.sub("", n) in [re.sub(r"^(有|已)", "", p) for p in poss]
+                    for n in negs
+                )
+                # 若所有否定值去掉前缀后能与某肯定值词干对上 → conditional
+                # 否则（如 未出账/已出账，"未出账"去"未"="出账"≠"已出账"去"已"="出账" → 其实对得上）
+                # 更精确：neg 去 neg 前缀 == pos 去 pos 前缀(有/已/正)
+                _STRIP_POS = re.compile(r"^(有|已)")
+                stems_match = any(
+                    (_STRIP_NEG.sub("", n) or n) == (_STRIP_POS.sub("", p) or p)
+                    for n in negs for p in poss
+                )
+                is_conditional = stems_match
+            all_result = all(_is_result_token(v) for v in uniq)
+            # 该簇的总独立组数
+            gc = sum(len(pair_groups[(i, va, vb)]) for va in uniq for vb in uniq if va < vb)
+            if all_result:
+                out.append({
+                    "type": "sequential", "dim": f"phase{i}", "values": uniq,
+                    "phases": uniq, "boundVar": slugify_dim(f"seq{i}", len(out)),
+                    "tokens": uniq, "positional": True, "position": i, "groupCount": gc,
+                    "note": "结果/状态态，由上游流程驱动；基础态 + 结果块 v-show 绑定 status 变量",
+                })
+            elif is_conditional:
+                negs = [v for v in uniq if (_PURE_NEG.match(v) or _NEG_SHORT.match(v))]
+                poss = [v for v in uniq if not (_PURE_NEG.match(v) or _NEG_SHORT.match(v))]
+                neg = negs[0] if negs else uniq[0]
+                pos = poss[0] if poss else uniq[-1]
+                out.append({
+                    "type": "conditional", "dim": f"empty{i}", "kind": "presence",
+                    "negative": neg, "positive": pos, "values": uniq,
+                    "boundVar": slugify_dim(f"cond{i}", len(out)),
+                    "showWhen": pos, "hideWhen": neg,
+                    "tokens": uniq, "positional": True, "position": i, "groupCount": gc,
+                })
+            else:
+                out.append({
+                    "type": "tab", "dim": f"tab{i}", "values": uniq,
+                    "default": uniq[0], "boundVar": slugify_dim(f"tab{i}", len(out)),
+                    "tokens": uniq, "positional": True, "position": i, "groupCount": gc,
+                })
+    return out
+
+
+def detect_forms(cluster_states):
+    """表单态检测（纯结构）：状态指纹相对基础态仅新增少量文本输入块（blockJaccard 高、
+    textJaccard 中等、新增 blocks 含输入/选择控件类型名）。
+    控件类型名取通用 UI 语义（input/select/选择/输入），非业务词。
+    """
+    out, seen = [], set()
+    _FORM_CONTROL = re.compile(r"(input|select|输入|选择|填写|修改)", re.I)
+    for st in cluster_states:
+        df = st.get("diffVsBase") or {}
+        added_blocks = df.get("addedBlocks", [])
+        if not added_blocks:
+            continue
+        # 新增块里有输入/选择控件类型 → 表单态
+        if any(_FORM_CONTROL.search(b) for b in added_blocks):
+            token = "_".join(st["qualifiers"]) or st["name"]
+            if token in seen:
+                continue
+            field = added_blocks[0].split("/")[-1].strip()
+            out.append({
+                "type": "form", "token": token, "field": field,
+                "control": "input", "boundVar": slugify_dim(f"form{len(out)}", len(out)),
+            })
+            seen.add(token)
+    return out
+
+
+# 兼容旧调用名（build_cluster 仍引用）
+def detect_enums(cluster_states):
+    return [d for d in detect_positional_tabs(cluster_states) if d["type"] == "tab"]
+
+
+def detect_pairs(cluster_states):
+    return [d for d in detect_positional_tabs(cluster_states) if d["type"] == "conditional"]
+
+
+def detect_sequential(cluster_states):
+    seqs = [d for d in detect_positional_tabs(cluster_states) if d["type"] == "sequential"]
+    # 保持旧输出结构（phases + 单变量）
+    return [{"type": "sequential", "phases": s["values"], "boundVar": s["boundVar"],
+             "note": s.get("note", "")} for s in seqs]
+
+
+# ----------------------------------------------------------------------------
+# 5. 主流程：聚类 + 产物聚合
+# ----------------------------------------------------------------------------
+def load_specs(out_dir):
+    specs = []
+    for name in sorted(os.listdir(out_dir)):
+        sd = os.path.join(out_dir, name)
+        sj = os.path.join(sd, "spec.json")
+        if not os.path.isfile(sj):
+            continue
+        try:
+            spec = json.load(open(sj, encoding="utf-8"))
+        except Exception as e:
+            print(f"[WARN] 读取失败 {sj}: {e}", file=sys.stderr)
+            continue
+        specs.append((name, spec))
+    return specs
+
+
+def build_cluster(card_key_name, items):
+    """items: [(canvas_name, spec)]。聚合为一张逻辑卡片的多状态信息。"""
+    states = []
+    # 结构性过渡态判定：若某状态的某 qualifier 恰好是其他卡片的 cardKey，则它是过渡态
+    all_card_keys = {card_key(cn) for cn, _ in items}
+    for cn, spec in items:
+        qs = qualifiers(cn)
+        fp = fingerprint(spec)
+        # 过渡态：qualifier 里出现了别的 cardKey（跨卡跳转）
+        trans_to = next((q for q in qs if q in all_card_keys and q != card_key_name), None)
+        is_trans = trans_to is not None
+        states.append({
+            "name": cn,
+            "stateKey": abstract_state_key(qs, fp),
+            "qualifiers": qs,
+            "isTransition": is_trans,
+            "transitionTo": trans_to,
+            "fp": fp,
+            "artboardType": spec.get("artboardType", "card"),
+            "cardCount": len(spec.get("cards", [])),
+            "interaction": spec.get("interaction", ""),
+            "jsapiInteractions": spec.get("jsapiInteractions", []),
+            "flexLayouts": [c.get("flexLayout") for c in spec.get("cards", []) if c.get("flexLayout")],
+        })
+    # 推荐基础态：排除过渡态与空/错误态后，指纹最丰富
+    def richness(s):
+        return len(s["fp"]["texts"]) + len(s["fp"]["blocks"])
+    candidates = [s for s in states if not s["isTransition"] and not is_empty_or_error(s["qualifiers"], s["fp"])]
+    if not candidates:
+        candidates = [s for s in states if not s["isTransition"]]
+    if not candidates:
+        candidates = states
+    base = max(candidates, key=richness)
+    for st in states:
+        st["diffVsBase"] = diff_fingerprint(base["fp"], st["fp"])
+    # 维度提取（纯结构，统一由 detect_positional_tabs 产出 tab/conditional/sequential）
+    dims_all = detect_positional_tabs(states)
+    tabs = [d for d in dims_all if d["type"] == "tab"]
+    conds = [d for d in dims_all if d["type"] == "conditional"]
+    seqs = [{"type": "sequential", "phases": d["values"], "boundVar": d["boundVar"],
+             "note": d.get("note", "")} for d in dims_all if d["type"] == "sequential"]
+    forms = detect_forms(states)
+    seen_var = set()
+    tabs_dedup = []
+    for t in tabs:
+        if t["boundVar"] in seen_var:
+            continue
+        seen_var.add(t["boundVar"])
+        tabs_dedup.append(t)
+    # 合并所有状态的样式汇总（颜色去重）
+    all_colors = sorted({c for s in states for c in s["fp"]["colors"]})
+    return {
+        "cardKey": card_key_name,
+        "canvasCount": len(states),
+        "stateNames": [s["name"] for s in states],
+        "stateKeys": sorted({s["stateKey"] for s in states}),
+        "recommendedBase": base["name"],
+        "states": [{k: v for k, v in s.items() if k != "fp"} | {"fingerprint": s["fp"]} for s in states],
+        "dimensions": {
+            "tabs": tabs_dedup,
+            "conditionals": conds,
+            "forms": forms,
+            "sequential": seqs,
+        },
+        "colors": all_colors,
+    }
+
+
+def aggregate_card_products(out_dir, card):
+    """把一张逻辑卡片的多状态产物聚合到 cards/<cardKey>/。"""
+    cdir = os.path.join(out_dir, "cards", card["cardKey"])
+    states_dir = os.path.join(cdir, "states")
+    os.makedirs(states_dir, exist_ok=True)
+    aggregated = {"copiedStates": []}
+    # 每个状态：复制代表性聚焦截图 + spec.json 到 states/<stateKey>_<idx>/
+    seen_state_keys = defaultdict(int)
+    for st in card["states"]:
+        cn = st["name"]
+        src_canvas_dir = os.path.join(out_dir, cn)
+        if not os.path.isdir(src_canvas_dir):
+            continue
+        sk = st["stateKey"]
+        seen_state_keys[sk] += 1
+        state_name = f"{sk}_{seen_state_keys[sk]}" if seen_state_keys[sk] > 1 else sk
+        dst_state_dir = os.path.join(states_dir, state_name)
+        os.makedirs(dst_state_dir, exist_ok=True)
+        # 复制该画板的聚焦截图（card-*.png）到 states/<state>/
+        n_img = 0
+        for fn in sorted(os.listdir(src_canvas_dir)):
+            if re.match(r"card-\d+\.png$", fn):
+                shutil.copy2(os.path.join(src_canvas_dir, fn), os.path.join(dst_state_dir, fn))
+                n_img += 1
+        # 复制整图（参考）
+        if os.path.isfile(os.path.join(src_canvas_dir, "artboard.png")):
+            shutil.copy2(os.path.join(src_canvas_dir, "artboard.png"),
+                         os.path.join(dst_state_dir, "artboard.png"))
+        # 复制 spec.json
+        src_spec = os.path.join(src_canvas_dir, "spec.json")
+        if os.path.isfile(src_spec):
+            shutil.copy2(src_spec, os.path.join(dst_state_dir, "spec.json"))
+        aggregated["copiedStates"].append({
+            "stateName": state_name, "canvas": cn,
+            "stateKey": sk, "images": n_img,
+        })
+    # 写 card.json
+    # 聚合所有状态的 JSAPI 交互控件与 Flex 布局（去重）
+    jsapi_all = []
+    seen_js = set()
+    flex_all = []
+    for st in card["states"]:
+        for j in st.get("jsapiInteractions", []):
+            k = j.get("control")
+            if k and k not in seen_js:
+                jsapi_all.append(j)
+                seen_js.add(k)
+        for fl in st.get("flexLayouts", []):
+            if fl and fl not in flex_all:
+                flex_all.append(fl)
+    card_json = {
+        "cardKey": card["cardKey"],
+        "pageId": card.get("pageId"),
+        "cardKeyDisplay": card.get("cardKeyDisplay"),
+        "isDialog": card.get("isDialog", False),
+        "parentKey": card.get("parentKey"),
+        "canvasCount": card["canvasCount"],
+        "recommendedBase": card["recommendedBase"],
+        "stateKeys": card["stateKeys"],
+        "stateNames": card["stateNames"],
+        "dimensions": card["dimensions"],
+        "colors": card["colors"],
+        "jsapiInteractions": jsapi_all,
+        "flexLayouts": flex_all,
+        "states": aggregated["copiedStates"],
+    }
+    with open(os.path.join(cdir, "card.json"), "w", encoding="utf-8") as f:
+        json.dump(card_json, f, ensure_ascii=False, indent=2)
+    return aggregated["copiedStates"]
+
+
+def write_interactions_index(out_dir, cards, overlays):
+    """跨卡片交互图：弹框/子卡父子关系 + 维度切换。"""
+    lines = ["# 跨卡片交互图（由 cluster_states.py 生成）", ""]
+    if overlays:
+        lines.append("## 弹框 / 提示（overlay_dialog → alertDialog JSAPI，不建卡）")
+        for o in overlays:
+            lines.append(f"- `{o['name']}`：父卡候选 `{o['parentKey']}`；"
+                         f"参考 `{', '.join(o.get('refs', []))}`")
+        lines.append("")
+    subcards = [c for c in cards if c.get("isDialog")]
+    if subcards:
+        lines.append("## 子卡（subcard → alertCard 父子卡片，独立 Dialog 卡）")
+        for c in subcards:
+            lines.append(f"- `{c['cardKey']}`：父卡 `{c.get('parentKey')}`；"
+                         f"打开 `alertCard({{cardCode}})` / 关闭 `closeAlertCard`")
+        lines.append("")
+    lines.append("## 维度切换（多形态卡片）")
+    for c in cards:
+        d = c["dimensions"]
+        dims = []
+        for t in d["tabs"]:
+            dims.append(f"Tab:{t['dim']}={t['values']}")
+        for cond in d["conditionals"]:
+            dims.append(f"Cond:{cond['kind']}({cond['negative']}↔{cond['positive']})")
+        for fm in d["forms"]:
+            dims.append(f"Form:{fm['field']}({fm['control']})")
+        for sq in d["sequential"]:
+            dims.append(f"Seq:{sq['phases']}")
+        if dims:
+            lines.append(f"- `{c['cardKey']}`：{'; '.join(dims)}")
+    lines.append("")
+    # JSAPI 外部交互控件聚合
+    jsapi_cards = [c for c in cards if any(s.get("jsapiInteractions") for s in c["states"])]
+    if jsapi_cards:
+        lines.append("## JSAPI 外部交互控件（密码/验证码/数字键盘/toast/二次确认）")
+        for c in jsapi_cards:
+            seen_ctl = set()
+            for st in c["states"]:
+                for j in st.get("jsapiInteractions", []):
+                    ctl = j.get("control")
+                    if ctl and ctl not in seen_ctl:
+                        seen_ctl.add(ctl)
+                        lines.append(f"- `{c['cardKey']}` ← `{ctl}`：{j.get('note', '')}")
+        lines.append("")
+    lines.append("")
+    idx_dir = os.path.join(out_dir, "interactions")
+    os.makedirs(idx_dir, exist_ok=True)
+    with open(os.path.join(idx_dir, "index.yaml"), "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
+
+
+def augment_prompt(out_dir, card):
+    """给每画板 prompt.md 追加 ## 5. 多形态归属。"""
+    dims = card["dimensions"]
+    lines = ["", "## 5. 多形态归属（由 cluster_states.py 生成）", ""]
+    lines.append(f"- **所属逻辑卡片**：`{card['cardKey']}`（共 {card['canvasCount']} 个形态）")
+    lines.append(f"- **抽象状态键**：{card['stateKeys']}")
+    lines.append(f"- **推荐基础态**：`{card['recommendedBase']}`")
+    lines.append("")
+    lines.append("### 检测到的切换维度")
+    if dims["tabs"]:
+        for t in dims["tabs"]:
+            lines.append(f"- **Tab 维度** `{t['dim']}`：取值 {t['values']}，默认 `{t['default']}`，绑定变量 `{t['boundVar']}`")
+    if dims["conditionals"]:
+        for c in dims["conditionals"]:
+            lines.append(f"- **条件显隐** `{c['kind']}`：`{c['negative']}` ↔ `{c['positive']}`，变量 `{c['boundVar']}`")
+    if dims["forms"]:
+        for fm in dims["forms"]:
+            lines.append(f"- **动态表单** `{fm['token']}`：控件 `{fm['control']}`，字段 `{fm['field']}`，变量 `{fm['boundVar']}`")
+    if dims["sequential"]:
+        for s in dims["sequential"]:
+            lines.append(f"- **时序/结果态** 阶段 {s['phases']}，变量 `{s['boundVar']}`")
+    if not (dims["tabs"] or dims["conditionals"] or dims["forms"] or dims["sequential"]):
+        lines.append("- （未检测到明确切换维度，按单态生成）")
+    lines.append("")
+    lines.append("> 多形态建卡：以推荐基础态建基础 schema，Tab 用 TabBar + `v-show` 切内容；"
+                 "条件显隐对差异块加 `v-show`；表单插 Input/Select 绑变量。")
+    if card.get("isDialog"):
+        lines.append("")
+        lines.append("### 本卡为 alertCard 子卡（Dialog 卡）")
+        lines.append("- 关闭按钮(×) → `ynet.callJSAPI('closeAlertCard', { cardCode: '<pageId>' })`")
+        parent = card.get("parentKey") or "对应触发卡"
+        lines.append(f"- 父卡（`{parent}`）打开：`ynet.callJSAPI('alertCard', {{ cardCode: '<pageId>', data: {{...}}, gravity: 'bottom' }})`")
+        if ALERTCARD_REF_CARDS:
+            lines.append(f"- 参考存量：{', '.join(ALERTCARD_REF_CARDS)}")
+    block = "\n".join(lines)
+    for st in card["states"]:
+        cn = st["name"]
+        pm = os.path.join(out_dir, cn, "prompt.md")
+        if not os.path.isfile(pm):
+            continue
+        txt = open(pm, encoding="utf-8").read()
+        txt = re.sub(r"\n## 5\. 多形态归属.*?(?=\n## |\Z)", "", txt, flags=re.S)
+        txt = txt.rstrip() + "\n" + block + "\n"
+        open(pm, "w", encoding="utf-8").write(txt)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="卡片维度聚类 + 产物聚合（视觉驱动 spec 结构）")
+    ap.add_argument("--out", required=True, help="UI 目录（含各画板子目录与 spec.json）")
+    ap.add_argument("--card-refs", default=None)
+    ap.add_argument("--auto-refs", action="store_true")
+    ap.add_argument("--src-cards", default=None)
+    args = ap.parse_args()
+
+    global ALERTDIALOG_REF_CARDS, ALERTCARD_REF_CARDS
+    refs = load_card_refs(args.card_refs, args.auto_refs, _resolve_src_cards(args.src_cards))
+    ALERTDIALOG_REF_CARDS = refs["alertDialog"]
+    ALERTCARD_REF_CARDS = refs["alertCard"]
+    if args.auto_refs:
+        print(f"[INFO] 自动探测参考卡：alertDialog×{len(ALERTDIALOG_REF_CARDS)} / alertCard×{len(ALERTCARD_REF_CARDS)}")
+
+    out_dir = os.path.abspath(args.out)
+    if not os.path.isdir(out_dir):
+        print(f"[ERR] 目录不存在: {out_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    specs = load_specs(out_dir)
+    if not specs:
+        print(f"[ERR] {out_dir} 下未找到任何 spec.json（请先运行 parse_meaxure.py --build）", file=sys.stderr)
+        sys.exit(1)
+
+    # 聚类分流：普通卡按 card_key；subcard 独立；overlay_dialog 进 overlays
+    clusters_map = defaultdict(list)
+    overlays = []
+    for cn, spec in specs:
+        at = spec.get("artboardType", "card")
+        if at == "overlay_dialog":
+            parts = normalize_name(cn).split("_", 1)
+            parent_key = parts[0] if len(parts) > 1 else None
+            overlays.append({
+                "name": cn, "artboardType": "overlay_dialog",
+                "interaction": spec.get("interaction", ""),
+                "parentKey": parent_key, "refs": list(ALERTDIALOG_REF_CARDS),
+            })
+            continue
+        if at == "subcard":
+            key = normalize_name(cn)
+        else:
+            key = card_key(cn)
+        clusters_map[key].append((cn, spec))
+
+    cards = []
+    for key in sorted(clusters_map):
+        items = clusters_map[key]
+        card = build_cluster(key, items)
+        # 英文 pageId（稳定序号，供下游当 id 用，解决 cardKey 中文无法当 pageId）+ 中文 cardKeyDisplay（展示用）
+        card["pageId"] = f"card-{len(cards) + 1}"
+        card["cardKeyDisplay"] = key
+        is_dialog = any(s.get("artboardType") == "subcard" for _, s in items)
+        card["isDialog"] = is_dialog
+        if is_dialog:
+            pk = key.split("_", 1)
+            card["parentKey"] = pk[0] if len(pk) > 1 else None
+        aggregate_card_products(out_dir, card)
+        augment_prompt(out_dir, card)
+        cards.append(card)
+
+    draft_name = os.path.basename(out_dir.rstrip("/\\"))
+    result = {
+        "draft": draft_name,
+        "totalCanvases": len(specs),
+        "cardCount": len(cards),
+        "cards": cards,
+        "overlays": overlays,
+    }
+    with open(os.path.join(out_dir, "clusters.json"), "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
+    write_interactions_index(out_dir, cards, overlays)
+
+    print(f"[OK] 草稿「{draft_name}」共 {len(specs)} 画板 → {len(cards)} 张逻辑卡片"
+          + (f" + {len(overlays)} 弹框(overlay_dialog)" if overlays else ""))
+    for c in cards:
+        d = c["dimensions"]
+        ntab = len(d["tabs"]); ncond = len(d["conditionals"]); nform = len(d["forms"]); nseq = len(d["sequential"])
+        tag = " [Dialog子卡]" if c.get("isDialog") else ""
+        print(f"  - {c['cardKey']}{tag}: {c['canvasCount']}态 keys={c['stateKeys']} | "
+              f"tab×{ntab} cond×{ncond} form×{nform} seq×{nseq} | base={c['recommendedBase']}")
+    for o in overlays:
+        print(f"  - [overlay_dialog] {o['name']}  (父卡候选: {o['parentKey']})")
+    print(f"[OK] 已写出 {out_dir}/clusters.json + cards/<cardKey>/ + interactions/index.yaml")
+
+
+if __name__ == "__main__":
+    main()