cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,1781 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+parse_meaxure.py — 解析 Sketch MeaXure 标注导出，视觉驱动生成「卡片要素包」。
+
+原则（2026-08-14 重构）：
+- 判定依据全部来自视觉几何（大块、独立、卡片状），文本/名称仅是附属信息，
+  不参与「保留/剔除」判定 —— 设计稿文本多为示意，未必有真实含义。
+- 一个画板可有 1..N 张卡片（空间分离的视觉块各自成卡），聚焦后裁切输出局部图。
+- 产物按「卡片维度」组织：一张卡片可对应多个画板（多个状态），每个状态一张/多张聚焦截图；
+  子卡/弹框作为独立卡片，仅通过交互关系（parentKey / JSAPI）与父卡建立联系。
+
+产物结构（--out，默认 <仓库根>/UI）：
+  manifest.json          画板清单 + 卡片映射
+  cards/<cardKey>/
+    card.json            状态 / 交互 / 样式 / 列表 聚合信息
+    states/<画板名>/
+      artboard.png       整图（参考）
+      card-1.png(...)    聚焦裁切图（每张卡片或每板一图，@2x）
+      spec.json          视觉要素标注（该状态）
+      slices/            切图素材
+  clusters.json          卡片聚类 + 交互维度（由 cluster_states.py 补全）
+
+用法：
+  python parse_meaxure.py --list                          # 仅列画板
+  # 多画板选择门禁：不带 --only/--indices/--sample/--scope-all 的生成运行会打印 1..n+全部 清单并 exit 4，
+  # 等用户回复序号/「全部」后再带 --indices <k-1> / --only / --scope-all 重跑（rules.md §十三）。
+  python parse_meaxure.py --sample 5                      # 抽样代表性画板
+  python parse_meaxure.py --only "未登录,有交易"            # 按名称子串
+  python parse_meaxure.py --indices 0,9,18                # 按序号
+  python parse_meaxure.py --src <导出目录> --out <UI> --build
+  python parse_meaxure.py --build                         # 一步式（含 build_prompt）
+"""
+import argparse
+import json
+import math
+import os
+import re
+import shutil
+import sys
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from urllib.parse import unquote
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SKILL_DIR = SCRIPT_DIR.parent
+REPO_ROOT = SKILL_DIR.parent.parent
+DEFAULT_OUT = REPO_ROOT / "UI"
+DEFAULT_SRC = Path(os.environ.get('MEAXURE_SRC') or str(Path.cwd()))  # 可用环境变量 MEAXURE_SRC 指定，缺省当前目录
+
+sys.path.insert(0, str(SCRIPT_DIR))
+import png_utils
+import vision
+
+PREVIEW_SCALE = 2.0   # 预览截图 750x1624 = 设计稿 375x812 的 @2x
+
+
+# ---------- 通用工具 ----------
+def normalize_name(name: str) -> str:
+    """剥画板名开头的数字序号前缀（01转账 → 转账）。"""
+    return re.sub(r"^\d+", "", name or "").strip()
+
+
+def flow_prefix(name: str) -> str:
+    """业务流前缀：画板名第一个 '_' 前段（如 01转账 / 41转账记录）。"""
+    return normalize_name(name).split("_", 1)[0]
+
+
+def hex_of(color_obj):
+    """MeaXure color -> '#RRGGBB'。"""
+    if not isinstance(color_obj, dict):
+        return None
+    for key in ("color-hex", "argb-hex", "rgba-hex"):
+        v = color_obj.get(key)
+        if isinstance(v, str) and v.startswith("#"):
+            return v.split()[0][:7] if " " not in v else v[:7]
+    return None
+
+
+def rgba_of(color_obj):
+    """MeaXure color -> 'rgba(r,g,b,a)'（含透明度）。"""
+    if not isinstance(color_obj, dict):
+        return None
+    css = color_obj.get("css-rgba") or color_obj.get("css-hsla")
+    if css:
+        return css
+    h = hex_of(color_obj)
+    return h
+
+
+def extract_data(index_html: Path) -> dict:
+    html = index_html.read_text(encoding="utf-8", errors="ignore")
+    marker = "let data = "
+    i = html.find(marker)
+    if i < 0:
+        raise RuntimeError("未找到 'let data = '，可能不是 Sketch MeaXure 导出")
+    start = html.find("{", i)
+    depth = 0
+    j = start
+    while j < len(html):
+        c = html[j]
+        if c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                break
+        j += 1
+    return json.loads(html[start:j + 1])
+
+
+# ---------- 视觉要素提取（对齐卡片平台节点属性） ----------
+_STYLE_NONE = {"color": None, "gradient": None, "image": None}
+
+def extract_fills_style(fills):
+    """fills -> {color, gradient, image}（首有效填充，平台 background 组参考）。"""
+    out = dict(_STYLE_NONE)
+    if not fills:
+        return out
+    for f in fills:
+        if not isinstance(f, dict):
+            continue
+        ft = f.get("fillType") or f.get("type") or ""
+        if "grad" in str(ft).lower():
+            g = f.get("gradient") or {}
+            stops = g.get("colorStops") or []
+            css_stops = []
+            for s in stops:
+                c = s.get("color") or {}
+                css = c.get("css-rgba") or c.get("css-hsla") or ""
+                pos = s.get("position")
+                if css and pos is not None:
+                    css_stops.append(f"{css} {round(pos * 100)}%")
+            if css_stops:
+                gtype = str(g.get("type", "Linear")).lower()
+                if gtype.startswith("radial"):
+                    out["gradient"] = "radial-gradient(" + ", ".join(css_stops) + ")"
+                else:
+                    frm, to = g.get("from", {}), g.get("to", {})
+                    fx, fy = frm.get("x", 0.5), frm.get("y", 0)
+                    tx, ty = to.get("x", 0.5), to.get("y", 1)
+                    # 方向向量必须保留符号：from→to 指向哪边，渐变就朝哪边。
+                    # 只看坐标差绝对值会把「自下而上」误判成 to bottom（整体反向）。
+                    # CSS 角度约定：0deg=to top，90deg=to right，180deg=to bottom。
+                    dx, dy = (tx - fx), (ty - fy)
+                    if abs(dx) < 1e-6 and abs(dy) < 1e-6:
+                        angle = "to bottom"
+                    else:
+                        deg = round((math.degrees(math.atan2(dx, -dy)) + 360) % 360)
+                        snap = {0: "to top", 90: "to right", 180: "to bottom", 270: "to left"}
+                        angle = snap.get(deg, f"{deg}deg")
+                    out["gradient"] = f"linear-gradient({angle}, " + ", ".join(css_stops) + ")"
+            if out["gradient"]:
+                break
+        elif f.get("color"):
+            h = hex_of(f["color"])
+            if h:
+                out["color"] = h
+                break
+    return out
+
+
+def extract_border_style(borders):
+    """borders -> {isBorder, color, width}。"""
+    if not borders:
+        return {"isBorder": False, "color": None, "width": None}
+    b = borders[0]
+    return {
+        "isBorder": True,
+        "color": hex_of(b.get("color")) if isinstance(b, dict) else None,
+        "width": b.get("thickness") if isinstance(b, dict) else None,
+    }
+
+
+def extract_radius(radius):
+    """radius 列表 -> 平台 borderRadius 参考（单值或四角）。"""
+    if not radius:
+        return None
+    vals = [round(float(v), 1) if isinstance(v, (int, float)) and v else 0 for v in radius]
+    vals = vals[:4]
+    if len(vals) == 4 and len(set(vals)) > 1:
+        return {"borderRadiusType": "1", "borderRadius": vals}  # 四角
+    if vals and vals[0] > 0:
+        return {"borderRadiusType": "0", "borderRadius": vals[0]}
+    return {"borderRadiusType": "0", "borderRadius": 0}
+
+
+def extract_shadow(shadows):
+    """shadows -> {isShadow, color, x, y, blur}。"""
+    if not shadows:
+        return {"isShadow": False}
+    s = shadows[0]
+    c = (s.get("color") or {})
+    return {
+        "isShadow": True,
+        "color": hex_of(c),
+        "x": s.get("x") or s.get("offsetX"),
+        "y": s.get("y") or s.get("offsetY"),
+        "blur": s.get("blur") or s.get("radius"),
+    }
+
+
+def extract_text_style(raw):
+    """文本层 -> font 组参考（平台节点 Text 属性）。"""
+    css = raw.get("css") or []
+    css_text = " ".join(css) if isinstance(css, list) else str(css or "")
+    def css_val(prop):
+        m = re.search(prop + r"\s*:\s*([^;]+)", css_text)
+        return m.group(1).strip() if m else None
+    weight = css_val(r"font-weight")
+    style = css_val(r"font-style")
+    family = css_val(r"font-family")
+    return {
+        "color": hex_of(raw.get("color")),
+        "fontSize": raw.get("fontSize"),
+        "fontFace": raw.get("fontFace"),
+        "fontFamily": family or raw.get("fontFace"),
+        "fontWeight": weight or "400",
+        "fontStyle": style or "normal",
+        "lineHeight": raw.get("lineHeight"),
+        "letterSpacing": raw.get("letterSpacing"),
+        "textAlign": raw.get("textAlign"),
+        "rotation": raw.get("rotation", 0),
+    }
+
+
+def element_style(raw):
+    """一个图层的平台对齐样式参考（非文本）。"""
+    return {
+        "fill": extract_fills_style(raw.get("fills")),
+        "background": extract_fills_style(raw.get("fills")),
+        "border": extract_border_style(raw.get("borders")),
+        "radius": extract_radius(raw.get("radius")),
+        "shadow": extract_shadow(raw.get("shadows")),
+        "opacity": raw.get("opacity", 1),
+        "rotation": raw.get("rotation", 0),
+        "styleName": raw.get("styleName"),
+    }
+
+
+def serialize_element(ve, raw):
+    """把视觉元素序列化为 spec.json 条目（几何 + 视觉 + 附属文本）。
+
+    注意：MeaXure 导出的 layers 是设计师纯视觉图层树，不等于卡片节点拓扑，
+    故不产出层级字段；卡片拓扑由下游几何/坐标重建（v3 extractSemantics）权威生成。
+    """
+    x, y, w, h = ve.rect
+    return {
+        "name": ve.name,
+        "type": ve.type,
+        "rect": {"x": round(x, 2), "y": round(y, 2), "width": round(w, 2), "height": round(h, 2)},
+        "style": element_style(raw),
+        "text": raw.get("content"),      # 附属信息（仅记录，不参与判定）
+        "textStyle": extract_text_style(raw) if ve.is_text else None,
+        "slices": raw.get("name") if ve.is_slice else None,
+    }
+# ---------- 卡片视觉分段（几何驱动，供下游拓扑生成；group 结构不作依据） ----------
+# 设计稿是扁平绝对定位画布，group 只是编辑组织；卡片是流式 flex 树。
+# 分段只认 y 几何（大间隙/类型切换），产出每段的卡内 y/height/hint，下游据此生成容器拓扑。
+SEG_GAP_RATIO = 0.02   # 段间间隙阈值（相对卡高，超此视为分段边界）
+SEG_BG_W_RATIO = 0.8   # 背景层宽占比（≥卡宽 80%）
+SEG_BG_H_MAX = 220     # 背景层最大高
+
+
+def _segment_hint(e, card_w, card_rect=None):
+    """段类型 hint（仅参考，下游可覆盖）：decor-bg / button / footer / content"""
+    t = e.get("type")
+    r = e.get("rect") or {}
+    w = r.get("width") or 0
+    h = r.get("height") or 0
+    bounds = card_rect or {}
+    card_y = float(bounds[1] if isinstance(bounds, tuple) else bounds.get("y", 0) or 0)
+    card_h = float(bounds[3] if isinstance(bounds, tuple) else bounds.get("height", 0) or 0)
+    near_top = card_h <= 0 or (float(r.get("y", 0) or 0) - card_y) <= max(40, card_h * 0.2)
+    is_background_media = t in ("slice", "group") and w >= card_w * SEG_BG_W_RATIO and h <= SEG_BG_H_MAX
+    if is_background_media and near_top:
+        return "decor-bg"
+    has_gradient = t == "shape" and ((e.get("style") or {}).get("fill") or {}).get("gradient")
+    if has_gradient and h <= 80:
+        return "button"
+    if has_gradient and w >= card_w * 0.9 and h >= card_h * 0.9:
+        return "decor-bg"
+    if t == "text":
+        txt = str(e.get("text") or "").strip()
+        # 通用 UI 动作词（中英双语）——这些是跨业务通用的交互动作词，非业务词
+        if re.search(r"^(更多|查看|展开|收起|提交|确认|立即|完成|确定|取消|关闭|返回|more|view|expand|collapse|submit|confirm|cancel|close|done)", txt, re.I):
+            return "button"
+        # 几何兜底：按钮尺寸范围内的短文本（≤8 字、高度 20-56px、宽度 ≤240）
+        r = e.get("rect") or {}
+        h = float(r.get("height") or 0)
+        w = float(r.get("width") or 0)
+        if 20 <= h <= 56 and w <= 240 and 0 < len(txt) <= 8:
+            return "button"
+    return "content"
+
+
+def detect_segments(card_els, card_rect):
+    """按 y 几何聚类视觉段。返回 [{y, height, gap_top, hint, items}]（y/height 为卡内相对坐标）。
+    规则：
+      1. 排除卡外装饰（全屏背景/蒙版：元素在卡 y 轴交集 < 元素高 50%）；
+      2. decor-bg（装饰背景层）元素**强制独立成段**（背景层是独立容器，其下内容必须切段）；
+      3. 其余按大间隙（gap > 卡高×SEG_GAP_RATIO）或 hint 切换分段。"""
+    cx, cy, cw, chh = card_rect
+    els = []
+    for e in card_els:
+        r = e.get("rect")
+        if not r or not (r.get("width") or 0):
+            continue
+        # 卡片容器本身（symbol/shape 尺寸≈整卡）与卡外装饰排除：拓扑只看卡内内容元素
+        if e.get("type") == "symbol" and (r.get("width") or 0) >= cw * 0.9 and (r.get("height") or 0) >= chh * 0.9:
+            continue
+        top = r.get("y", 0)
+        bot = top + (r.get("height") or 0)
+        inter = max(0, min(bot, cy + chh) - max(top, cy))
+        ratio = inter / max((r.get("height") or 1), 1)
+        if ratio < 0.5:
+            continue  # 卡外装饰（全屏背景/蒙版），与卡片拓扑无关
+        els.append(e)
+    if not els:
+        return []
+    els = sorted(els, key=lambda e: e["rect"]["y"])
+    segs = []
+    for e in els:
+        r = e["rect"]
+        y = r.get("y", 0)
+        hint = _segment_hint(e, cw, (cx, cy, cw, chh))
+        if hint == "decor-bg":
+            # 背景层强制独立成段：与已有 decor-bg 段同 y（<20）合并，否则新开并立即闭合
+            if segs and segs[-1]["hint"] == "decor-bg" and abs(segs[-1]["y"] - y) < 20:
+                segs[-1]["items"].append(e)
+            else:
+                segs.append({"y": y, "items": [e], "hint": hint})
+            continue
+        if not segs or segs[-1]["hint"] == "decor-bg":
+            # 背景层（或其前无段）后的内容元素：强制新开内容段——内容叠在背景上，归属不并入背景段
+            segs.append({"y": y, "items": [e], "hint": hint})
+            continue
+        prev_bottom = max((it["rect"]["y"] + (it["rect"]["height"] or 0)) for it in segs[-1]["items"])
+        gap = y - prev_bottom
+        if gap > chh * SEG_GAP_RATIO or (hint != "content" and hint != segs[-1]["hint"]):
+            segs.append({"y": y, "items": [e], "hint": hint})
+            continue
+        segs[-1]["items"].append(e)
+    out = []
+    for i, s in enumerate(segs):
+        bottom = max((it["rect"]["y"] + (it["rect"]["height"] or 0)) for it in s["items"])
+        top = s["y"]
+        seg = {
+            "y": round(top - cy, 2),
+            "height": round(bottom - top, 2),
+            "hint": s["hint"],
+            "items": len(s["items"]),
+        }
+        if i == 0:
+            seg["gap_top"] = round(top - cy, 2)
+        else:
+            # 修正坐标混用 bug：统一用卡内相对坐标计算 gap_top
+            prev_bottom_rel = out[i - 1]["y"] + out[i - 1]["height"]
+            seg["gap_top"] = round(seg["y"] - prev_bottom_rel, 2)
+        out.append(seg)
+    # 后处理：消除段重叠（前一段底部超出后一段顶部时，截断前一段高度）
+    for i in range(1, len(out)):
+        overlap = (out[i - 1]["y"] + out[i - 1]["height"]) - out[i]["y"]
+        if overlap > 0:
+            out[i - 1]["height"] = round(out[i - 1]["height"] - overlap, 2)
+            # 重算 gap_top（截断后应 ≥ 0）
+            out[i]["gap_top"] = round(out[i]["y"] - (out[i - 1]["y"] + out[i - 1]["height"]), 2)
+    return out
+
+
+# ---------- 画板聚焦：卡片区域 + 裁切 ----------
+def _normalize_radii(raw_radius):
+    """把 MeaXure radius 归一化为 [tl,tr,br,bl]；无有效值时返回 None。
+
+    注意：radius 可能只有 1 项（四角同值）或 4 项（四角独立），也会出现
+    前导 0（如 [0,12,12,12]），必须原样保留 0，不能按「>0」过滤后丢失。
+    """
+    vals = []
+    for v in (raw_radius or []):
+        try:
+            vals.append(max(0.0, float(v)))
+        except (TypeError, ValueError):
+            vals.append(0.0)
+    if not vals:
+        return None
+    while len(vals) < 4:
+        vals.append(vals[-1] if vals else 0.0)
+    return vals[:4]
+
+
+def _card_mask_info(els, x, y, w, h):
+    """从归属元素里找卡片容器，返回 (圆角半径列表, 卡片填充色)。
+
+    选择策略只依赖图层几何与样式，**不依赖背景颜色**：
+      1) 与裁切框重叠 ≥60% 的候选中，优先有圆角的元素（卡片外壳通常是带
+         borderRadius 的 shape，而非同名 group/symbol 包装）；
+      2) 同有圆角时优先有纯色填充，再按重叠度、面积取最大（外壳 > 内部子块）。
+    找不到时返回 (None, fill)。
+    """
+    best = None
+    best_key = None
+    for e in els:
+        ex, ey, ew, eh = e.rect
+        if ew <= 0 or eh <= 0:
+            continue
+        ix = max(0, min(ex + ew, x + w) - max(ex, x))
+        iy = max(0, min(ey + eh, y + h) - max(ey, y))
+        overlap = (ix * iy) / (ew * eh)
+        if overlap < 0.6:
+            continue
+        radii = _normalize_radii(e.radius)
+        has_radius = 1 if (radii and any(v > 0 for v in radii)) else 0
+        fill = extract_fills_style(e.fills).get("color")
+        has_fill = 1 if fill else 0
+        key = (has_radius, has_fill, overlap, ew * eh)
+        if best_key is None or key > best_key:
+            best = e
+            best_key = key
+    if best is None:
+        return None, None
+    radii = _normalize_radii(best.radius)
+    fill = extract_fills_style(best.fills).get("color")
+    return radii, fill
+
+
+def _card_fill_pixel_check(png_path, annotated_fill):
+    """cardFill 像素交叉校验（2026-09-06，01基金_基金推荐案例）。
+
+    标注 fill 与合成像素可能不一致（如标注 #FFFFFF，Sketch 叠透明度后
+    实际渲染为 #F7F7F7）。采样聚焦图底部 4% 横条（卡片底 padding 区，
+    几乎无内容）中位色，与标注逐通道对比，>6 判冲突。
+
+    返回 (sampled_hex|None, conflict|False)。只标记不裁决——
+    标注为权威，冲突由下游 AI 按视觉交叉验证规则裁决。
+    """
+    if not annotated_fill or not png_path or not os.path.exists(str(png_path)):
+        return None, False
+    try:
+        w, h, channels, rows = png_utils.read_png(str(png_path))
+    except Exception:
+        return None, False
+    y0 = int(h * 0.96)
+    samples = [[], [], []]
+    for yy in range(y0, h, 2):
+        row = rows[yy]
+        for xx in range(0, w, 4):
+            o = xx * channels
+            if channels == 4 and row[o + 3] < 200:
+                continue
+            samples[0].append(row[o])
+            samples[1].append(row[o + 1])
+            samples[2].append(row[o + 2])
+    if len(samples[0]) < 50:
+        return None, False
+
+    def _median(v):
+        v = sorted(v)
+        return v[len(v) // 2]
+
+    sr, sg, sb = _median(samples[0]), _median(samples[1]), _median(samples[2])
+    sampled_hex = "#{:02X}{:02X}{:02X}".format(sr, sg, sb)
+    m = re.match(r"#?([0-9a-fA-F]{6})", annotated_fill)
+    if not m:
+        return sampled_hex, False
+    hv = m.group(1)
+    ar, ag, ab = int(hv[0:2], 16), int(hv[2:4], 16), int(hv[4:6], 16)
+    conflict = max(abs(sr - ar), abs(sg - ag), abs(sb - ab)) > 6
+    return sampled_hex, conflict
+
+
+def _deduplicate_shell_elements(els):
+    """去重完全同框且不含文本的容器/符号/形状层。
+
+    MeaXure 常把同一业务控件导出为 symbol、group 和兜底 shape 三层。
+    这些层不是并排组件，而是同一视觉节点的重复标注；保留圆角、填充和
+    子层级最丰富的一层，避免下游把同一控件消费成多个语义块。
+    """
+    kept = {}
+    output = []
+    for element in els:
+        if element.is_text or element.is_slice:
+            output.append(element)
+            continue
+        x, y, width, height = element.rect
+        if width <= 0 or height <= 0:
+            output.append(element)
+            continue
+        key = (element.type, round(x, 2), round(y, 2), round(width, 2), round(height, 2))
+        previous = kept.get(key)
+        if previous is None:
+            kept[key] = element
+            output.append(element)
+            continue
+        fill = extract_fills_style(element.fills).get("color")
+        previous_fill = extract_fills_style(previous.fills).get("color")
+        priority = (
+            1 if _normalize_radii(element.radius) else 0,
+            1 if fill else 0,
+            element.children_count or 0,
+        )
+        previous_priority = (
+            1 if _normalize_radii(previous.radius) else 0,
+            1 if previous_fill else 0,
+            previous.children_count or 0,
+        )
+        if priority > previous_priority:
+            output[output.index(previous)] = element
+            kept[key] = element
+    return output
+
+
+def focus_artboard(ab_raw, preview_path, cdir):
+    """对一个画板：检测独立卡片区域 → 结构过滤 → 逐一裁切 → 序列化标注。
+
+    返回 spec dict（含卡片区域、聚焦截图、样式汇总）。
+    """
+    W, H = ab_raw.get("width", 0), ab_raw.get("height", 0)
+    raw_layers = ab_raw.get("layers") or []
+    flattened_layers = vision._flatten_with_tree(raw_layers)
+    overlay = vision.detect_overlay_dialog(vision._flatten_with_tree(raw_layers), W, H)
+    bottom_sheet = vision._bottom_sheet_rect(raw_layers, W, H)
+    conversation_flow = vision.detect_conversation_flow(flattened_layers, W, H)
+    if overlay or bottom_sheet:
+        cards = []
+        focus_skip_reason = (
+            "overlay_dialog_geometry" if overlay else "bottom_sheet_geometry"
+        )
+    else:
+        cards = vision.detect_cards(raw_layers, W, H, conversation_flow)
+        focus_skip_reason = ""
+
+    for old_png in cdir.glob("card-*.png"):
+        old_png.unlink()
+
+        # 归属元素（卡片聚焦后的扁平元素；层级树已废弃，拓扑由下游几何重建）
+    elements = []
+    for ve in vision._flatten_with_tree(raw_layers):
+        elements.append(serialize_element(ve, ve.raw))
+
+    card_regions = []
+    rejected_regions = []
+    eligible_cards = []
+    for x, y, w, h, els, shapes in cards:
+        rect = (x, y, w, h)
+        eligible, reject_reason, focus_metrics = vision.classify_card_focus(
+            els, rect, W, H, conversation_flow)
+        if not eligible:
+            rejected_regions.append({
+                "rect": {"x": round(x, 2), "y": round(y, 2),
+                         "width": round(w, 2), "height": round(h, 2)},
+                "reason": reject_reason,
+                "metrics": focus_metrics,
+            })
+            continue
+        eligible_cards.append((x, y, w, h, els, shapes, focus_metrics))
+
+    from build_prompt import detect_list_in_card  # 列表检测复用 build_prompt（无循环依赖）
+    for i, (x, y, w, h, els, shapes, focus_metrics) in enumerate(eligible_cards, 1):
+        region = {"index": i, "rect": {"x": round(x, 2), "y": round(y, 2),
+                                       "width": round(w, 2), "height": round(h, 2)},
+                  "trainingEligible": True,
+                  "focusMetrics": focus_metrics}
+        mask_radii, card_fill = _card_mask_info(els, x, y, w, h)
+        region["cardFill"] = card_fill
+        region["mask"] = {
+            # 遮罩完全来自卡片几何（rect+radius），与背景是否均匀/固定颜色无关。
+            "type": "geometry",
+            "radius": mask_radii or None,
+            "shapeCount": len(shapes),
+        }
+        # 裁切局部聚焦图（@2x，RGBA：卡片几何外的背景透明）
+        if preview_path and preview_path.exists():
+            out_png = cdir / f"card-{i}.png"
+            try:
+                png_utils.crop_png_masked(str(preview_path), (x, y, w, h), str(out_png), PREVIEW_SCALE, shapes)
+                region["image"] = out_png.name
+                sampled_fill, fill_conflict = _card_fill_pixel_check(out_png, card_fill)
+                if sampled_fill:
+                    region["cardFillSampled"] = sampled_fill
+                if fill_conflict:
+                    region["cardFillConflict"] = True
+                    print(f"    [WARN] {region['index']}. cardFill 标注 {card_fill} vs 采样 {sampled_fill} 通道差>6，已标记 cardFillConflict（下游按视觉裁决）", file=sys.stderr)
+            except Exception as e:  # noqa
+                print(f"    [WARN] 裁切失败 {out_png.name}: {e}", file=sys.stderr)
+        # 归属元素（卡片聚焦后的扁平元素；层级树已废弃，拓扑由下游几何重建）
+        # _flatten_with_tree 填的 parentId 恒为 None（vision.py:168 walk(raw_layers, None, 0) 仅在 L["layers"] 存在时递归）。
+        focused_elements = _deduplicate_shell_elements(els)
+        region["elements"] = [serialize_element(e, e.raw) for e in focused_elements] or []
+        # 从扁平元素重建嵌套层级树（供 AI 读图理解容器↔子元素关系）
+        # Flex 布局推断（容器主排列方向与对齐，纯几何）
+        child_rects = [(e.rect[0], e.rect[1], e.rect[2], e.rect[3])
+                       for e in focused_elements if not e.is_text and not e.is_slice
+                       and e.rect[2] > 0 and e.rect[3] > 0
+                       and e.rect[2] * e.rect[3] < 0.7 * w * h]
+        flex = vision.infer_flex_layout((x, y, w, h), child_rects)
+        if flex:
+            region["flexLayout"] = flex
+        # 视觉分段（几何聚类，供下游拓扑生成；group 结构不作拓扑依据）
+        region["segments"] = detect_segments(region["elements"], (x, y, w, h))
+        # 列表检测（纯几何同构）回写契约，供下游 v3/geo 直接消费，避免重猜
+        region["detectedList"] = detect_list_in_card(region) or None
+        card_regions.append(region)
+
+    # Fallback（2026-08-31）：视觉检测 0 个独立卡片区域时，仍裁一张图 card-1.png，
+    # 保证每个普通画板都有 card-* 截图（下游聚类/训练参考用）。不写入 card_regions，
+    # 避免误触发下游卡片生成（spec.cards 仍空 → status 维持 skipped/generated）。
+    # 仅对普通画板生效；overlay_dialog / bottom_sheet 是弹框，不应裁卡截图。
+    # 会话流画板（气泡/输入坞/键盘）同样不产兜底图：整屏截图含对话气泡与纯文本，
+    # 易被误读为「把整屏做成了卡片」，且 artboard.png 已可承担参考职责。
+    # 裁切去掉系统 chrome（状态栏 / Home Indicator），保留应用 UI（顶部导航/底部 tab），
+    # 对齐「仅卡片主体」约定。偏移按设计稿高度粗判（刘海屏状态栏 44、老屏 20；
+    # Home Indicator 仅刘海屏 34），均为设计 px，crop_png_masked 内部乘 PREVIEW_SCALE。
+    if (not card_regions and not overlay and not bottom_sheet
+            and not conversation_flow
+            and preview_path and preview_path.exists()):
+        try:
+            notch = H >= 800
+            top_trim = min(44 if notch else 20, H // 4)
+            bottom_trim = min(34 if notch else 0, H // 4)
+            rect = (0, top_trim, W, H - top_trim - bottom_trim)
+            out_png = cdir / "card-1.png"
+            png_utils.crop_png_masked(str(preview_path), rect, str(out_png), PREVIEW_SCALE, [])
+            print(f"    [fallback] {cdir.name}: 0 卡检测 → 裁切 card-1.png (去chrome top={top_trim} bottom={bottom_trim})", file=sys.stderr)
+        except Exception as e:  # noqa
+            print(f"    [WARN] fallback 裁切失败 {out_png.name}: {e}", file=sys.stderr)
+
+    if conversation_flow and not card_regions:
+        focus_skip_reason = "conversation_flow_geometry"
+
+    spec = {
+        "canvas": ab_raw.get("name", ""),
+        "schemaVersion": "1.0",
+        "size": {"width": W, "height": H},
+        "cards": card_regions,
+        "rejectedCards": rejected_regions,
+        "conversationFlow": conversation_flow,
+        "focusSkipReason": focus_skip_reason or (
+            "no_structural_card_region" if not card_regions else ""
+        ),
+        "elements": elements,
+        "styleSummary": summarize_styles(elements),
+        "slices": collect_slice_names(raw_layers),
+    }
+    return spec
+
+
+def collect_slice_names(raw_layers):
+    out = []
+    def walk(ls):
+        for L in ls:
+            if L.get("type") == "slice":
+                out.append(L.get("name", ""))
+            if L.get("layers"):
+                walk(L["layers"])
+    walk(raw_layers)
+    return out
+
+
+def summarize_styles(elements):
+    """聚合该状态全部元素的平台对齐样式（去重）。"""
+    colors, gradients, fonts, radius, shadows = [], [], [], [], []
+    for e in elements:
+        st = e.get("style") or {}
+        bkg = st.get("background") or {}
+        if bkg.get("color"):
+            colors.append(bkg["color"])
+        if bkg.get("gradient"):
+            gradients.append(bkg["gradient"])
+        ts = e.get("textStyle") or {}
+        if ts.get("color"):
+            colors.append(ts["color"])
+        if ts.get("fontSize") and ts.get("fontSize") not in [f.get("size") for f in fonts]:
+            fonts.append({"size": ts["fontSize"], "fontFace": ts.get("fontFace"),
+                          "fontWeight": ts.get("fontWeight"), "lineHeight": ts.get("lineHeight"),
+                          "letterSpacing": ts.get("letterSpacing"),
+                          "textAlign": ts.get("textAlign")})
+        r = st.get("radius")
+        if r and r.get("borderRadius") not in [x.get("borderRadius") for x in radius]:
+            radius.append(r)
+        s = st.get("shadow")
+        if s and s.get("isShadow") and s not in shadows:
+            shadows.append(s)
+    return {
+        "colors": sorted(set(c for c in colors if c)),
+        "gradients": sorted(set(g for g in gradients if g)),
+        "fonts": fonts,
+        "borderRadius": radius,
+        "shadows": shadows,
+    }
+
+
+# ---------- 切图匹配 ----------
+def build_asset_index(assets_dir):
+    index = {}
+    if not assets_dir.exists():
+        return index
+    for p in assets_dir.rglob("*"):
+        if p.is_file():
+            stem = re.sub(r"@\dx$", "", p.stem, flags=re.IGNORECASE)
+            index.setdefault(stem, []).append(p.relative_to(assets_dir).as_posix())
+    return index
+
+
+def norm(name):
+    s = name.rsplit("/", 1)[-1]
+    s = re.sub(r"@\dx$", "", s, flags=re.IGNORECASE)
+    s = re.sub(r"_icon$", "", s, flags=re.IGNORECASE)
+    return s.strip().lower()
+
+
+def _slice_scale(rel):
+    """从切图文件名提取倍率：@3x→3, @2x→2, @1x→1, 无后缀→0。用于同名取最高倍率。"""
+    stem = re.sub(r"\.(png|jpg|svg|webp)$", "", rel, flags=re.IGNORECASE)
+    m = re.search(r"@(\d)x$", stem, re.IGNORECASE)
+    return int(m.group(1)) if m else 0
+
+
+def _asset_path_tokens(value):
+    value = re.sub(r"[\\/、.]+", "/", value).lower()
+    value = re.sub(r"@\d+x", "", value, flags=re.IGNORECASE)
+    stem = re.sub(r"@\dx$", "", value, flags=re.IGNORECASE)
+    stem = re.sub(r"\.(png|jpg|jpeg|webp|svg)$", "", stem, flags=re.IGNORECASE)
+    return {part.strip() for part in stem.split("/") if part.strip()}
+
+
+def _asset_candidate_score(relative_path, canvas_slice_names):
+    relative_tokens = _asset_path_tokens(relative_path)
+    name_tokens = set().union(*(_asset_path_tokens(name) for name in canvas_slice_names))
+    filename = relative_path.rsplit("/", 1)[-1].lower()
+    extension = filename.rsplit(".", 1)[-1]
+    directory = relative_path.rsplit("/", 1)[0] if "/" in relative_path else ""
+    return (
+        len(relative_tokens & name_tokens),
+        int(extension in {"png", "jpg", "jpeg", "webp"}),
+        _slice_scale(relative_path),
+        len(relative_tokens),
+    )
+
+
+AUTO_LAYER_NAME_RE = re.compile(
+    r"^(编组|组|group|layer|矩形|rectangle|shape|path|椭圆|oval|直线|line|星形|star|多边形|polygon)\s*\d+$",
+    re.IGNORECASE,
+)
+
+
+def is_auto_layer_name(name):
+    """Sketch 自动命名（编组 N / 矩形 N / Group N…）：尾部数字是唯一标识，宽松匹配会错配资产。"""
+    return bool(AUTO_LAYER_NAME_RE.match(str(name).rsplit("/", 1)[-1].strip()))
+
+
+def collect_slice_files(canvas_slice_names, asset_index):
+    """匹配画板引用的切图并按同名取最高倍率去重。
+    规则：
+      1. 精确匹配：同名切图（剥 @Nx 后缀后同名）若有多尺寸版本，只保留最高倍率（@3x>@2x>@1x>原始）。
+         例：顶部返回.png / @1x.svg / @2x.png / @3x.png → 只保留 @3x.png。
+      2. 宽松匹配（MeaXure 导出文件名常与图层名不一致）：精确未命中时，用图层名的「语义段」
+         （去 8.icon/ 前缀、去尾部 -N/_N 数字后缀）匹配文件**路径目录**（如 8.icon/成都农商银行logo-26
+         的语义段 成都农商银行logo ∈ 文件 8.icon/成都农商银行logo/单logo26@3x.png 的目录）。
+         解决「图层有 slice 标注但导出文件名不同」导致切图静默丢失。
+    """
+    all_files = [rel for rels in asset_index.values() for rel in rels]
+    by_name = defaultdict(list)
+    for w in {norm(n) for n in canvas_slice_names}:
+        if w in asset_index:
+            by_name[w].extend(asset_index[w])
+    # 精确未命中的图层 → 宽松匹配：
+    #   a) 语义段 ∈ 目录（成都农商银行logo-26 → 8.icon/成都农商银行logo/单logo26@3x.png）
+    #   b) 去尾部数字后 basename 相等（成功1 → 成功 / 顶部-弥散 → 顶部-弥散1，MeaXure 序号变体）
+    for n in canvas_slice_names:
+        nk = norm(n)
+        if by_name.get(nk):
+            continue
+        # 自动命名图层只认精确匹配：编组 2 与 编组 4.png 仅尾部数字不同，
+        # 去数字宽松匹配会把错误资产绑给图层（黄色行标曾整批错配/丢失）。
+        if is_auto_layer_name(n):
+            continue
+        base = n.rsplit("/", 1)[-1]
+        core = re.sub(r"[-_]\d+$", "", base).strip().lower()
+        base_n = re.sub(r"[-_ ]?\d+$", "", base).strip().lower()
+        for rel in all_files:
+            fn = rel.rsplit("/", 1)[-1]
+            fn_core = fn
+            fn_core = re.sub(r"\.[a-z0-9]+$", "", fn_core, flags=re.IGNORECASE)
+            fn_core = re.sub(r"@\dx$", "", fn_core, flags=re.IGNORECASE)
+            fn_n = re.sub(r"[-_ ]?\d+$", "", fn_core).strip().lower()
+            dirpart = rel.rsplit("/", 1)[0].lower() if "/" in rel else ""
+            if (dirpart and len(core) >= 2 and core in dirpart) \
+                    or (len(base_n) >= 2 and fn_n == base_n):
+                by_name[nk].append(rel)
+    # 同名取最高倍率
+    matched = []
+    for w, rels in by_name.items():
+        best = max(rels, key=lambda rel: _asset_candidate_score(rel, canvas_slice_names))
+        matched.append(best)
+    return sorted(matched)
+
+
+def _mode_rgb(pixels):
+    counts = defaultdict(int)
+    for pixel in pixels:
+        counts[pixel] += 1
+    return max(counts, key=counts.get) if counts else None
+
+
+def sample_foreground_color(image_path, rect, scale):
+    """从设计稿整图采样切片区域的前景近似纯色。
+
+    背景取边界众数；前景取与背景色距足够的内部像素众数。阈值是通用感知分离
+    参数，不包含任何业务或设计风格假设。采样失败返回 None。
+    """
+    try:
+        width, height, channels, rows = png_utils.read_png(image_path)
+    except (OSError, ValueError):
+        return None
+
+    x0 = max(0, int(round(float(rect.get("x", 0)) * scale)))
+    y0 = max(0, int(round(float(rect.get("y", 0)) * scale)))
+    x1 = min(width, int(round((float(rect.get("x", 0)) + float(rect.get("width", 0))) * scale)))
+    y1 = min(height, int(round((float(rect.get("y", 0)) + float(rect.get("height", 0))) * scale)))
+    if x1 - x0 < 2 or y1 - y0 < 2:
+        return None
+
+    def pixel(x, y):
+        x = max(0, min(width - 1, x))
+        y = max(0, min(height - 1, y))
+        offset = x * channels
+        if channels == 1:
+            return (rows[y][offset], rows[y][offset], rows[y][offset])
+        return (rows[y][offset], rows[y][offset + 1], rows[y][offset + 2])
+
+    def opaque(x, y):
+        return channels != 4 or rows[y][x * channels + 3] >= 16
+
+    border = []
+    for x in range(x0, x1):
+        for y in (y0, y1 - 1):
+            if opaque(x, y):
+                border.append(pixel(x, y))
+    for y in range(y0 + 1, y1 - 1):
+        for x in (x0, x1 - 1):
+            if opaque(x, y):
+                border.append(pixel(x, y))
+    background = _mode_rgb(border)
+    if background is None:
+        return None
+
+    foreground = defaultdict(list)
+    for y in range(y0 + 1, y1 - 1):
+        for x in range(x0 + 1, x1 - 1):
+            if not opaque(x, y):
+                continue
+            rgb = pixel(x, y)
+            distance = sum((left - right) ** 2 for left, right in zip(rgb, background))
+            if distance < 36 ** 2:
+                continue
+            foreground[(rgb[0] >> 3 << 3, rgb[1] >> 3 << 3, rgb[2] >> 3 << 3)].append(rgb)
+    if foreground:
+        bucket = max(foreground, key=lambda key: len(foreground[key]))
+        samples = foreground[bucket]
+        rgb = tuple(sum(sample[index] for sample in samples) // len(samples) for index in range(3))
+        return "#%02X%02X%02X" % rgb
+
+    center_x0 = (x0 + x1 - 1) // 2
+    center_y0 = (y0 + y1 - 1) // 2
+    center_x1, center_y1 = center_x0 + 2, center_y0 + 2
+    center = [pixel(x, y) for y in range(center_y0, center_y1) for x in range(center_x0, center_x1) if opaque(x, y)]
+    rgb = _mode_rgb(center)
+    return "#%02X%02X%02X" % rgb if rgb else None
+
+
+def sample_background_color(image_path, rect, scale):
+    """采样切片区域的边界主导色，用于缺失导出的大面积背景兜底。"""
+    try:
+        width, height, channels, rows = png_utils.read_png(image_path)
+    except (OSError, ValueError):
+        return None
+
+    x0 = max(0, int(round(float(rect.get("x", 0)) * scale)))
+    y0 = max(0, int(round(float(rect.get("y", 0)) * scale)))
+    x1 = min(width, int(round((float(rect.get("x", 0)) + float(rect.get("width", 0))) * scale)))
+    y1 = min(height, int(round((float(rect.get("y", 0)) + float(rect.get("height", 0))) * scale)))
+    if x1 - x0 < 2 or y1 - y0 < 2:
+        return None
+
+    def pixel(x, y):
+        offset = x * channels
+        if channels == 1:
+            return (rows[y][offset], rows[y][offset], rows[y][offset])
+        return (rows[y][offset], rows[y][offset + 1], rows[y][offset + 2])
+
+    def opaque(x, y):
+        return channels != 4 or rows[y][x * channels + 3] >= 16
+
+    border = []
+    for x in range(x0, x1):
+        for y in (y0, y1 - 1):
+            if opaque(x, y):
+                border.append(pixel(x, y))
+    for y in range(y0 + 1, y1 - 1):
+        for x in (x0, x1 - 1):
+            if opaque(x, y):
+                border.append(pixel(x, y))
+    rgb = _mode_rgb(border)
+    return "#%02X%02X%02X" % rgb if rgb else None
+
+
+def _mask_pixels(image_path, rect=None, scale=1.0, cells=16):
+    """生成小型媒体的前景掩码；透明素材用 alpha，裁切区域用背景色距。"""
+    try:
+        width, height, channels, rows = png_utils.read_png(image_path)
+    except (OSError, ValueError):
+        return []
+
+    if rect:
+        x0 = int(round(float(rect.get("x", 0)) * scale))
+        y0 = int(round(float(rect.get("y", 0)) * scale))
+        x1 = int(round((float(rect.get("x", 0)) + float(rect.get("width", 0))) * scale))
+        y1 = int(round((float(rect.get("y", 0)) + float(rect.get("height", 0))) * scale))
+    else:
+        x0, y0, x1, y1 = 0, 0, width, height
+    x0, y0 = max(0, x0), max(0, y0)
+    x1, y1 = min(width, x1), min(height, y1)
+    if x1 - x0 < 2 or y1 - y0 < 2:
+        return []
+    if any(len(row) < width * channels for row in rows):
+        return []
+
+    def pixel(x, y):
+        offset = x * channels
+        if channels >= 3:
+            alpha = rows[y][offset + 3] if channels == 4 else 255
+            return rows[y][offset], rows[y][offset + 1], rows[y][offset + 2], alpha
+        if channels == 1:
+            return rows[y][offset], rows[y][offset], rows[y][offset], 255
+        return 255, 255, 255, 255
+
+    border = []
+    for x in range(x0, x1):
+        border.extend((pixel(x, y0), pixel(x, y1 - 1)))
+    for y in range(y0 + 1, y1 - 1):
+        border.extend((pixel(x0, y), pixel(x1 - 1, y)))
+    background = max(set(border), key=border.count)
+
+    mask = []
+    try:
+        for cell_y in range(cells):
+            for cell_x in range(cells):
+                x = round(x0 + (cell_x + 0.5) * (x1 - x0) / cells)
+                y = round(y0 + (cell_y + 0.5) * (y1 - y0) / cells)
+                red, green, blue, alpha = pixel(x, y)
+                if channels == 4:
+                    mask.append(alpha >= 64)
+                else:
+                    distance = math.sqrt(
+                        (red - background[0]) ** 2 +
+                        (green - background[1]) ** 2 +
+                        (blue - background[2]) ** 2,
+                    )
+                    mask.append(distance > 48)
+    except (IndexError, ValueError):
+        return []
+    return mask
+
+
+def _mask_iou(left, right):
+    if not left or not right:
+        return 1.0
+    union = sum(1 for left_pixel, right_pixel in zip(left, right)
+                if left_pixel or right_pixel)
+    intersection = sum(1 for left_pixel, right_pixel in zip(left, right)
+                       if left_pixel and right_pixel)
+    return intersection / union if union else 1.0
+
+
+def _color_cell_samples(image_path, rect=None, scale=1.0, cells=16):
+    """按相对位置采样 RGB，不整图缩放；rect 为空时采样整张资产。"""
+    width, height, channels, rows = png_utils.read_png(image_path)
+    if not width or not height or channels < 3:
+        return []
+    if rect is None:
+        x0, y0, x1, y1 = 0, 0, width, height
+    else:
+        x0 = int(round(float(rect.get("x", 0)) * scale))
+        y0 = int(round(float(rect.get("y", 0)) * scale))
+        x1 = x0 + max(1, int(round(float(rect.get("width", 0)) * scale)))
+        y1 = y0 + max(1, int(round(float(rect.get("height", 0)) * scale)))
+        x0, y0 = max(0, x0), max(0, y0)
+        x1, y1 = min(width, x1), min(height, y1)
+        if x1 <= x0 or y1 <= y0:
+            return []
+
+    def sample(x, y):
+        offset = min(width - 1, max(0, x)) * channels
+        row = rows[min(height - 1, max(0, y))]
+        if channels == 4:
+            alpha = row[offset + 3]
+            if alpha < 16:
+                return None
+            if alpha < 255:
+                # 半透明边沿像素先按白底合成再比色：透明底图标的原始 RGB
+                # 与设计稿（图标已叠在浅色卡底上）不可直接比较，否则描边/
+                # 抗锯齿像素会被系统性误判为颜色冲突，触发不必要的裁切回退。
+                blend = alpha / 255.0
+                return tuple(
+                    round(channel * blend + 255 * (1 - blend))
+                    for channel in row[offset:offset + 3]
+                )
+        return row[offset], row[offset + 1], row[offset + 2]
+
+    samples = []
+    for cell_y in range(cells):
+        for cell_x in range(cells):
+            x = round(x0 + (cell_x + 0.5) * (x1 - x0) / cells)
+            y = round(y0 + (cell_y + 0.5) * (y1 - y0) / cells)
+            samples.append(sample(x, y))
+    return samples
+
+
+def slice_color_similarity(asset_path, preview_path, rect, scale):
+    """比较切片与设计裁切的 RGB 一致性，捕捉 mask IoU 漏掉的底色/渐变冲突。"""
+    asset_samples = _color_cell_samples(asset_path)
+    design_samples = _color_cell_samples(preview_path, rect, scale)
+    if not asset_samples or not design_samples:
+        return 1.0
+    score = 0.0
+    compared = 0
+    for asset_pixel, design_pixel in zip(asset_samples, design_samples):
+        if asset_pixel is None or design_pixel is None:
+            continue
+        score += sum(
+            1 for left, right in zip(asset_pixel, design_pixel)
+            if abs(left - right) <= 18
+        ) / 3
+        compared += 1
+    return score / compared if compared else 1.0
+
+
+def slice_visual_similarity(asset_path, preview_path, rect, scale):
+    """比较切片素材与设计稿同位裁切的前景形状，供标注冲突检测用。"""
+    return _mask_iou(
+        _mask_pixels(asset_path, cells=16),
+        _mask_pixels(preview_path, rect, scale, 16),
+    )
+
+
+def _foreground_mean_color(image_path, rect=None, scale=1.0):
+    """前景像素（资产按 alpha、裁切按边框背景距）白底合成后的均值色。
+
+    细描边小图标在 16×16 栅格上可比的共同样本极少（常 <12 格），逐格
+    比色天然不稳；形状已确认一致时改用前景均值色做色相校验更稳健。
+    """
+    try:
+        width, height, channels, rows = png_utils.read_png(image_path)
+    except (OSError, ValueError):
+        return None, 0
+    if not width or not height or channels < 3:
+        return None, 0
+    if rect is None:
+        x0, y0, x1, y1 = 0, 0, width, height
+    else:
+        x0 = int(round(float(rect.get("x", 0)) * scale))
+        y0 = int(round(float(rect.get("y", 0)) * scale))
+        x1 = int(round((float(rect.get("x", 0)) + float(rect.get("width", 0))) * scale))
+        y1 = int(round((float(rect.get("y", 0)) + float(rect.get("height", 0))) * scale))
+        x0, y0 = max(0, x0), max(0, y0)
+        x1, y1 = min(width, x1), min(height, y1)
+    if x1 - x0 < 2 or y1 - y0 < 2:
+        return None, 0
+
+    def pixel(x, y):
+        offset = x * channels
+        alpha = rows[y][offset + 3] if channels == 4 else 255
+        return rows[y][offset], rows[y][offset + 1], rows[y][offset + 2], alpha
+
+    background = None
+    if channels != 4:
+        border = []
+        for x in range(x0, x1):
+            border.extend((pixel(x, y0), pixel(x, y1 - 1)))
+        for y in range(y0 + 1, y1 - 1):
+            border.extend((pixel(x0, y), pixel(x1 - 1, y)))
+        background = max(set(border), key=border.count)
+
+    red = green = blue = count = 0
+    for y in range(y0, y1):
+        for x in range(x0, x1):
+            r, g, b, alpha = pixel(x, y)
+            if channels == 4:
+                if alpha < 64:
+                    continue
+                blend = alpha / 255.0
+                r = r * blend + 255 * (1 - blend)
+                g = g * blend + 255 * (1 - blend)
+                b = b * blend + 255 * (1 - blend)
+            else:
+                distance = math.sqrt(
+                    (r - background[0]) ** 2 +
+                    (g - background[1]) ** 2 +
+                    (b - background[2]) ** 2,
+                )
+                if distance <= 48:
+                    continue
+            red += r
+            green += g
+            blue += b
+            count += 1
+    if not count:
+        return None, 0
+    return (red / count, green / count, blue / count), count
+
+
+def foreground_color_distance(asset_path, preview_path, rect, scale):
+    """资产与设计裁切的前景均值色距离；任一侧无前景时返回 None。"""
+    asset_mean, asset_count = _foreground_mean_color(asset_path)
+    design_mean, design_count = _foreground_mean_color(preview_path, rect, scale)
+    if not asset_mean or not design_mean:
+        return None
+    return math.sqrt(sum(
+        (left - right) ** 2 for left, right in zip(asset_mean, design_mean)
+    ))
+
+
+def foreground_chroma_distance(asset_path, preview_path, rect, scale):
+    """前景均值色的色度距离（r-g / b-g 两分量）。
+
+    抗锯齿/分辨率差只把颜色沿「通向白色」的方向混合，色度近似不变；
+    真实内容差（黄 vs 灰、蓝 vs 黑）色度差异显著。返回
+    (chroma_distance, luma_distance)，任一侧无前景时为 None。
+    """
+    asset_mean, _ = _foreground_mean_color(asset_path)
+    design_mean, _ = _foreground_mean_color(preview_path, rect, scale)
+    if not asset_mean or not design_mean:
+        return None
+    chroma = math.sqrt(
+        ((asset_mean[0] - asset_mean[1]) - (design_mean[0] - design_mean[1])) ** 2 +
+        ((asset_mean[2] - asset_mean[1]) - (design_mean[2] - design_mean[1])) ** 2,
+    )
+    luma = math.sqrt(sum(
+        (left - right) ** 2 for left, right in zip(asset_mean, design_mean)
+    ))
+    return chroma, luma
+
+
+def mark_slice_visual_mismatch(element, asset_path, preview_path, rect, scale, defects):
+    """用像素形状交叉验证切片标注；冲突时保留画板像素并记录标注缺陷。"""
+    similarity = slice_visual_similarity(asset_path, preview_path, rect, scale)
+    color_similarity = slice_color_similarity(asset_path, preview_path, rect, scale)
+    element["visualIdentity"] = round((similarity + color_similarity) / 2, 3)
+    element["colorIdentity"] = round(color_similarity, 3)
+    if similarity >= 0.35 and color_similarity >= 0.75:
+        return False
+    # 浅色细描边图标救援：16×16 逐格比色 ≥0.9 本身就是形状+颜色的双重
+    # 一致（错误内容不可能逐格同色），此时前景掩码对浅灰描边不可靠，
+    # IoU 低不应否决。
+    if color_similarity >= 0.9:
+        return False
+    # 细描边小图标救援：形状一致(IoU≥0.5)但逐格比色样本过少不稳时，
+    # 以前景色度复核：抗锯齿只把描边色向白色混合，色度近似不变
+    # （真彩差异色度 ≫25）；亮度差兜底拦截同色度但明暗悬殊的内容。
+    if similarity >= 0.5:
+        chroma_check = foreground_chroma_distance(
+            asset_path, preview_path, rect, scale)
+        if chroma_check is not None \
+                and chroma_check[0] <= 25 and chroma_check[1] <= 100:
+            element["foregroundColorDistance"] = round(chroma_check[0], 1)
+            element["visualIdentity"] = round(similarity, 3)
+            return False
+    defect = element.get("annotationDefect") or {
+        "type": "missing-slice",
+        "name": element.get("name", ""),
+        "reason": "exported slice identity is unconfirmed",
+    }
+    defect.update({
+        "type": "slice-visual-mismatch",
+        "reason": "exported slice pixels do not match design crop",
+        "visualSimilarity": round(similarity, 3),
+        "colorSimilarity": round(color_similarity, 3),
+    })
+    element["annotationDefect"] = defect
+    defects.append(defect)
+    return True
+
+
+def mark_missing_slice_elements(spec, preview_path, asset_index, asset_root=None, crop_dir=None):
+    """为缺失或视觉冲突媒体记录缺陷；优先用画板局部裁切，失败才用占位图。"""
+    defects = []
+    for element in spec.get("elements") or []:
+        element.pop("annotationDefect", None)
+        element.pop("visualIdentity", None)
+    for card in spec.get("cards") or []:
+        for element in card.get("elements") or []:
+            element.pop("annotationDefect", None)
+            element.pop("visualIdentity", None)
+    spec.pop("annotationDefects", None)
+    image_width, _, _, _ = png_utils.read_png(preview_path)
+    design_width = float((spec.get("size") or {}).get("width") or 375)
+    scale = image_width / design_width if design_width else PREVIEW_SCALE
+
+    def infer_card_rect(elements):
+        canvas_rect = spec.get("size") or {}
+        canvas_area = max(float(canvas_rect.get("width", 0)) * float(canvas_rect.get("height", 0)), 1)
+        content = []
+        for element in elements:
+            rect = element.get("rect") or {}
+            width = float(rect.get("width", 0))
+            height = float(rect.get("height", 0))
+            if width * height >= canvas_area * 0.8:
+                continue
+            content.append(rect)
+        if not content:
+            return canvas_rect
+        return {
+            "x": min(float(rect.get("x", 0)) for rect in content),
+            "y": min(float(rect.get("y", 0)) for rect in content),
+            "width": max(float(rect.get("x", 0)) + float(rect.get("width", 0)) for rect in content) -
+                min(float(rect.get("x", 0)) for rect in content),
+            "height": max(float(rect.get("y", 0)) + float(rect.get("height", 0)) for rect in content) -
+                min(float(rect.get("y", 0)) for rect in content),
+        }
+
+    def append_defect(element, card_rect):
+        rect = element.get("rect") or {}
+        width = float(rect.get("width", 0))
+        height = float(rect.get("height", 0))
+        card_area = max(float(card_rect.get("width", 0)) * float(card_rect.get("height", 0)), 1)
+        background_like = width >= float(card_rect.get("width", 0)) * 0.5 or width * height >= 10000
+        color = sample_background_color(preview_path, rect, scale) if background_like \
+            else sample_foreground_color(preview_path, rect, scale)
+        defect = {
+            "type": "background-slice-unavailable" if background_like else "missing-slice",
+            "name": element.get("name", ""),
+            "reason": "media annotation has no exported asset",
+        }
+        if color:
+            style = element.setdefault("style", {})
+            for group_key in ("fill", "background"):
+                group = style.setdefault(group_key, {})
+                group["color"] = color
+            defect["approximateSolidColor"] = color
+            defect["resolution"] = "sampled-solid-color"
+        else:
+            defect["resolution"] = "skipped-unresolvable"
+        element["annotationDefect"] = defect
+        defects.append(defect)
+        return defect
+
+    def crop_from_artboard(element, defect):
+        rect = element.get("rect") or {}
+        width = float(rect.get("width", 0))
+        height = float(rect.get("height", 0))
+        if not crop_dir or width < 2 or height < 2:
+            return
+        safe_name = re.sub(r'[\\/:*?"<>|]+', "_", element.get("name") or "slice")
+        filename = "__artboard_crop__{}_{}_{}x{}.png".format(
+            safe_name,
+            round(float(rect.get("x", 0))),
+            round(float(rect.get("y", 0))),
+            round(width),
+            round(height),
+        )
+        try:
+            png_utils.crop_png(
+                preview_path,
+                (float(rect.get("x", 0)), float(rect.get("y", 0)), width, height),
+                crop_dir / filename,
+                scale,
+            )
+            defect["resolution"] = "artboard-crop"
+            defect["cropSlice"] = filename
+        except (OSError, ValueError):
+            return
+
+    for element in spec.get("elements") or []:
+        if element.get("type") != "slice":
+            continue
+        if collect_slice_files([element.get("name", "")], asset_index):
+            continue
+        append_defect(element, spec.get("size") or {})
+        if element["annotationDefect"]["type"] == "missing-slice":
+            crop_from_artboard(element, element["annotationDefect"])
+    def has_text_overlay(elements, media_rect):
+        """切图矩形内是否叠加文本：有叠加时画板裁切会把文字烘进资产，不可用作替换。"""
+        mx = float(media_rect.get("x", 0))
+        my = float(media_rect.get("y", 0))
+        mw = float(media_rect.get("width", 0))
+        mh = float(media_rect.get("height", 0))
+        if mw <= 0 or mh <= 0:
+            return False
+        for other in elements:
+            if other.get("type") != "text":
+                continue
+            other_rect = other.get("rect") or {}
+            ox = float(other_rect.get("x", 0))
+            oy = float(other_rect.get("y", 0))
+            ow = float(other_rect.get("width", 0))
+            oh = float(other_rect.get("height", 0))
+            ix = max(0.0, min(mx + mw, ox + ow) - max(mx, ox))
+            iy = max(0.0, min(my + mh, oy + oh) - max(my, oy))
+            if ow * oh > 0 and ix * iy >= ow * oh * 0.5:
+                return True
+        return False
+
+    def is_vector_logo_group(elements, group_rect):
+        """纯矢量 logo 组：矩形内全为 shape 矢量子件且无文本叠加（裁切不会烘字）。"""
+        gx = float(group_rect.get("x", 0))
+        gy = float(group_rect.get("y", 0))
+        gw = float(group_rect.get("width", 0))
+        gh = float(group_rect.get("height", 0))
+        if gw <= 0 or gh <= 0:
+            return False
+        shapes = 0
+        for other in elements:
+            if other.get("type") != "shape":
+                continue
+            other_rect = other.get("rect") or {}
+            ox = float(other_rect.get("x", 0))
+            oy = float(other_rect.get("y", 0))
+            ow = float(other_rect.get("width", 0))
+            oh = float(other_rect.get("height", 0))
+            if ox >= gx - 2 and oy >= gy - 2 \
+                    and ox + ow <= gx + gw + 2 and oy + oh <= gy + gh + 2:
+                shapes += 1
+        return shapes >= 1
+
+    for card in spec.get("cards") or []:
+        card_rect = card.get("rect") or infer_card_rect(card.get("elements") or [])
+        card_area = max(float(card_rect.get("width", 0)) * float(card_rect.get("height", 0)), 1)
+        for element in card.get("elements") or []:
+            if element.get("annotationDefect"):
+                continue
+            rect = element.get("rect") or {}
+            width = float(rect.get("width", 0))
+            height = float(rect.get("height", 0))
+            is_compact_media = 12 <= width <= 220 and 12 <= height <= 220 \
+                and width * height <= card_area * 0.2
+            # 宽条媒体（按钮/横幅切图）：宽可达整卡、高 ≤72pt。这类切图导出状态错
+            # （如禁用态按钮）时整条色带失真，同样需要像素交叉验证；但仅当矩形内无
+            # 文本叠加时才验证替换，避免裁切烘字后渲染再叠文本造成重复。
+            is_strip_media = 24 <= height <= 72 and width >= 120 \
+                and width <= float(card_rect.get("width", 0)) * 1.02 \
+                and width * height <= card_area * 0.4 \
+                and not has_text_overlay(card.get("elements") or [], rect)
+            if element.get("type") == "slice":
+                matched_slices = collect_slice_files([element.get("name", "")], asset_index)
+                if matched_slices:
+                    asset_path = asset_root / matched_slices[0]
+                    width = float(rect.get("width", 0))
+                    height = float(rect.get("height", 0))
+                    if asset_root and (is_compact_media or is_strip_media):
+                        if mark_slice_visual_mismatch(
+                            element, asset_path, preview_path, rect, scale, defects,
+                        ):
+                            crop_from_artboard(element, element["annotationDefect"])
+                    continue
+                defect = append_defect(element, card_rect)
+                if defect["type"] == "missing-slice":
+                    crop_from_artboard(element, defect)
+            elif element.get("type") == "symbol" and is_compact_media:
+                append_defect(element, card_rect)
+                crop_from_artboard(element, element["annotationDefect"])
+            elif element.get("type") == "group" and is_compact_media \
+                    and not collect_slice_files([element.get("name", "")], asset_index) \
+                    and not has_text_overlay(card.get("elements") or [], rect) \
+                    and is_vector_logo_group(card.get("elements") or [], rect):
+                # 纯矢量 logo 组（shapes 组、无切图导出）：此前被静默丢弃（黄色行标整批缺失）。
+                # 按 rect 画板裁切生成资产，生成器侧凭 cropSlice 提权进切片池消费。
+                defect = append_defect(element, card_rect)
+                if defect["type"] == "missing-slice":
+                    crop_from_artboard(element, defect)
+    if defects:
+        spec["annotationDefects"] = defects
+    return defects
+
+
+def copy_slices(src_assets, dst_slices, matched_rel):
+    dst_slices.mkdir(parents=True, exist_ok=True)
+    for rel in matched_rel or []:
+        s = src_assets / rel
+        d = dst_slices / rel
+        d.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(s, d)
+    return list(matched_rel or [])
+# ---------- 画板选择（与业务无关，纯通用关键字） ----------
+PRIORITY_KEYWORDS = [
+    "未登录", "无数据", "无记录", "无交易", "空", "成功", "失败", "错误",
+    "有数据", "有记录", "选择", "确认", "详情", "列表", "表单", "输入",
+    "查询", "提醒", "展开", "修改", "更多", "子卡", "弹框", "弹窗",
+]
+
+
+def select_canvases(all_names, args):
+    n = len(all_names)
+    if args.list:
+        return None
+    if args.only:
+        kws = [k.strip() for k in args.only.split(",") if k.strip()]
+        return [i for i, nm in enumerate(all_names) if any(k in nm for k in kws)]
+    if args.indices:
+        return [int(x) for x in args.indices.split(",") if x.strip()]
+    if args.sample:
+        k = min(args.sample, n)
+        scored = []
+        for i, nm in enumerate(all_names):
+            score = sum(1 for kw in PRIORITY_KEYWORDS if kw in nm)
+            scored.append((score, i))
+        scored.sort(key=lambda t: (-t[0], t[1]))
+        seen, picked = set(), []
+        for sc, i in scored:
+            fp = flow_prefix(all_names[i])
+            if fp not in seen:
+                seen.add(fp)
+                picked.append(i)
+            if len(picked) >= k:
+                break
+        for sc, i in scored:
+            if i not in picked:
+                picked.append(i)
+            if len(picked) >= k:
+                break
+        return picked
+    return list(range(n))
+
+
+# ---------- 交互分类（通用抽象：弹层/子卡/普通卡；画板名仅作辅助） ----------
+DIALOG_NAME_PATTERNS = [
+    r"弹框", r"弹窗", r"对话框", r"浮层", r"确认框", r"提示框", r"警告框",
+    r"二次确认", r"消息提示", r"轻提示", r"错误提示", r"toast",
+]
+# 子卡名称模式：仅保留通用 UI 容器类型词（子卡/浮层卡/弹层卡），删除业务实体名
+# （选择账号/选择银行卡/银行卡选择 等是金融业务词，跨域会误判）。
+# 子卡判定改以视觉信号（底部抽屉面板 + scrim）为主，名称仅兜底。
+SUBCARD_NAME_PATTERNS = [
+    r"子卡", r"子页面", r"子卡片", r"浮层卡", r"弹层卡", r"弹卡",
+    r"弹出卡", r"弹窗卡", r"选择卡", r"卡列表",
+]
+_DIALOG_RE = [re.compile(p, re.IGNORECASE) for p in DIALOG_NAME_PATTERNS]
+_SUBCARD_RE = [re.compile(p, re.IGNORECASE) for p in SUBCARD_NAME_PATTERNS]
+
+
+def detect_modal_layers(raw_layers, W=375, H=812):
+    """视觉信号：模态遮罩(scrim) 与 底部抽屉面板（bottom-sheet）。
+    纯几何+视觉判定，无文本依赖：
+    - scrim：近全屏(>=90%画板)且半透明(opacity<0.95)的深色层。
+    - bottom-sheet：贴合屏幕底部(底边>=98%H)的通栏面板(宽>=95%W)，顶缘大圆角(>8px)且底缘无圆角。
+    W 默认 375（移动端设计稿规范宽度；若画板自带 width 则传入真实值）。
+    """
+    has_scrim = False
+    has_bottom_sheet = False
+
+    def walk(ls):
+        nonlocal has_scrim, has_bottom_sheet
+        for L in ls:
+            ty = L.get("type", "")
+            r = L.get("rect") or {}
+            w, h = r.get("width", 0), r.get("height", 0)
+            x, y = r.get("x", 0), r.get("y", 0)
+            op = L.get("opacity", 1)
+            if w >= 0.9 * W and h >= 0.9 * H and isinstance(op, (int, float)) and op < 0.95:
+                has_scrim = True
+            # 底部抽屉：通栏 + 贴底 + 顶圆角底直角
+            if ty in ("shape", "symbol", "group") and w >= 0.95 * W and h >= 0.2 * H \
+                    and (y + h) >= 0.98 * H:
+                rad = L.get("radius") or []
+                if rad:
+                    if len(rad) == 1:
+                        top_r, bottom_r = rad[0], rad[0]
+                    elif len(rad) >= 4:
+                        top_r, bottom_r = rad[0], rad[2]
+                    else:
+                        top_r, bottom_r = rad[0], (rad[1] if len(rad) >= 2 else 0)
+                    if isinstance(top_r, (int, float)) and top_r > 8 \
+                            and isinstance(bottom_r, (int, float)) and bottom_r == 0:
+                        has_bottom_sheet = True
+            if L.get("layers"):
+                walk(L["layers"])
+    walk(raw_layers)
+    return has_scrim, has_bottom_sheet
+
+
+def classify_artboard(name, spec, raw_layers, H=812):
+    """返回 (artboardType, interaction)。视觉信号优先，名称仅兜底（保守）。
+    判定顺序：
+      1) 视觉：底部抽屉面板(bottom-sheet) → subcard；全屏遮罩(scrim) → overlay_dialog
+      2) 名称兜底：通用容器类型词（子卡/浮层/弹框/toast 等 UI 控件名，非业务实体名）
+    """
+    # 1) 视觉信号优先
+    W = (spec.get("size") or {}).get("width", 375) if spec else 375
+    focus_reason = (spec or {}).get("focusSkipReason", "")
+    if focus_reason == "overlay_dialog_geometry":
+        return "overlay_dialog", "alertDialog 系统弹框（视觉信号：居中嵌套对话框几何）"
+    if focus_reason == "bottom_sheet_geometry":
+        return "subcard", "alertCard 子卡（视觉信号：底部抽屉面板几何）"
+    has_scrim, has_sheet = detect_modal_layers(raw_layers or [], W, H)
+    if has_sheet:
+        return "subcard", "alertCard 子卡（视觉信号：底部抽屉面板，由父卡 alertCard 打开）"
+    if has_scrim:
+        return "overlay_dialog", "alertDialog 系统弹框（视觉信号：全屏遮罩）"
+    # 2) 名称兜底：通用 UI 容器类型词（非业务实体名）
+    nm = normalize_name(name)
+    if any(rx.search(nm) for rx in _SUBCARD_RE):
+        return "subcard", "alertCard 子卡（名称兜底：通用容器类型词）"
+    if any(rx.search(nm) for rx in _DIALOG_RE):
+        return "overlay_dialog", "alertDialog 系统弹框（名称兜底：通用控件类型词）"
+    return "card", ""
+
+
+# ---------- JSAPI 交互控件检测（通用控件类型，非业务词） ----------
+# 通用 UI 控件名（中英双语）：密码/验证码/数字键盘/弹框确认/toast 均为跨业务
+# 通用控件名，不属于业务词。中文设计稿依赖中文关键词，英文稿依赖英文关键词。
+JSAPI_CONTROL_PATTERNS = [
+    (re.compile(r"密码|password|pwd", re.I), "passwordDialog",
+     "密码输入控件：调用 inputPasswordDialog JSAPI（数字键盘 + 加密输入）"),
+    (re.compile(r"验证码|captcha|verification[_-]?code|sms[_-]?code", re.I), "captcha",
+     "验证码输入控件：调用短信验证码 JSAPI"),
+    (re.compile(r"数字键盘|keypad|number[_-]?keyboard", re.I), "numberKeyboard",
+     "数字键盘控件：调用数字键盘 JSAPI"),
+    (re.compile(r"^.*toast.*$|轻提示|消息提示|toast", re.I), "toast",
+     "Toast 轻提示：调用 showToast JSAPI（短暂浮现后自动消失）"),
+    (re.compile(r"二次确认|确认弹框|确认框|confirm[_-]?dialog|alert[_-]?dialog|confirm", re.I), "alertDialog",
+     "二次确认弹框：调用 alertDialog JSAPI（title/message/okButton/cancelButton）"),
+]
+
+
+def detect_jsapi_interactions(spec, raw_layers):
+    """扫描卡片元素与画板，检测需调用 JSAPI 的外部交互控件。
+    返回 [{control, jsapi, note, source}] 列表。纯抽象控件类型判定，不含业务文案。
+    """
+    out = []
+    seen = set()
+    # 1) 画板名匹配（整体性控件，如「密码输入页」「验证码页」）
+    canvas_name = spec.get("canvas", "")
+    for pat, jsapi, note in JSAPI_CONTROL_PATTERNS:
+        if pat.search(canvas_name) and jsapi not in seen:
+            out.append({"control": jsapi, "jsapi": jsapi, "note": note, "source": "canvas"})
+            seen.add(jsapi)
+    # 2) 元素名匹配（局部控件，如「密码输入框」「数字键盘」组）
+    def walk(ls):
+        for L in ls:
+            nm = L.get("name", "") or ""
+            for pat, jsapi, note in JSAPI_CONTROL_PATTERNS:
+                if pat.search(nm) and jsapi not in seen:
+                    out.append({"control": jsapi, "jsapi": jsapi, "note": note,
+                                "source": "element", "element": nm})
+                    seen.add(jsapi)
+            if L.get("layers"):
+                walk(L["layers"])
+    walk(raw_layers)
+    return out
+
+
+# ---------- 主流程 ----------
+def preview_image_for(src, base, ab, name):
+    """解析某个画板**一一对应**的预览图绝对路径（门禁清单逐行配图用），找不到返回 None。
+
+    优先级：① 已前处理产物 `<out>/<draft>/<画板名>/artboard.png`；
+    ② 导出 `preview/<slug>.png`（MeaXure 的 slug 即预览文件名）；
+    ③ 导出 `imagePath` 字段指向的文件；④ `preview/<画板名>.png` 兜底。
+    缺图返回 None，由调用方显式标「预览图缺失」——禁止把图统一堆在清单末尾（序号会对不上）。
+    """
+    cands = [base / name / "artboard.png"]
+    slug = (ab or {}).get("slug") or ""
+    img = (ab or {}).get("imagePath") or ""
+    if slug:
+        cands.append(src / "preview" / f"{slug}.png")
+    if img:
+        cands.append(src / img)
+    cands.append(src / "preview" / f"{name}.png")
+    for c in cands:
+        try:
+            if c.is_file():
+                return c
+        except OSError:
+            continue
+    return None
+
+
+def print_board_line(i, nm, ab, src, base):
+    """门禁/清单统一行格式：序号行 + 下一行该画板自己的预览图（一一对应；缺图标缺失）。"""
+    sz = f'{ab.get("width")}x{ab.get("height")}' if ab else "?"
+    print(f"  {i + 1:>2}. {nm}   ({sz})")
+    img = preview_image_for(src, base, ab, nm)
+    if img:
+        print(f"      图: {img}")
+    else:
+        print("      图: （预览图缺失：preview/<slug>.png 与 UI 产物 artboard.png 均不存在）")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Sketch MeaXure 标注 → 卡片要素包（视觉驱动）")
+    ap.add_argument("--src", default=str(DEFAULT_SRC))
+    ap.add_argument("--out", default=str(DEFAULT_OUT))
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--scope-all", action="store_true",
+                    help="显式授权跑全部画板：仅当用户回复「全部」后才可加（无人值守批量训练可直接加或设 SKETCH_SPEC_SCOPE_ALL=1）")
+    ap.add_argument("--only", default=None)
+    ap.add_argument("--indices", default=None)
+    ap.add_argument("--sample", type=int, default=0)
+    ap.add_argument("--build", action="store_true")
+    ap.add_argument("--artboard-max-side", type=int, default=640,
+                   help="artboard.png 最长边降采样上限（默认 640；0=不降采样）")
+    ap.add_argument("--draft", default=None,
+                   help="按稿分片（可选）：画板落盘到 <out>/<draft>/<canvas>/，并写 <out>/<draft>/manifest.json；缺省平铺（兼容旧布局）")
+    args = ap.parse_args()
+
+    src = Path(args.src).expanduser()
+    out = Path(args.out).expanduser().resolve()
+    # 按稿分片：指定 --draft 时，所有画板与 manifest 落在 <out>/<draft>/ 下（UI 多稿治理，item 19）
+    base = out / args.draft if args.draft else out
+    if not (src / "index.html").exists():
+        print(f"[ERR] 未找到 {src / 'index.html'}，请用 --src 指定导出目录", file=sys.stderr)
+        sys.exit(1)
+
+    data = extract_data(src / "index.html")
+    artboards = data.get("artboards", [])
+    total = len(artboards)
+    print(f"[INFO] 解析到 {total} 个画布（来源：{src.name}）")
+
+    names = [ab.get("name", f"artboard-{i}") for i, ab in enumerate(artboards)]
+    if args.list:
+        # 展示统一 1 起（与多画板门禁清单同口径）；--indices 仍为 0 起，用户序号 k → k-1
+        # 每个画板行下面紧跟它自己那张预览图（一一对应；缺图显式标缺失），禁止把图堆在末尾
+        for i, nm in enumerate(names):
+            print_board_line(i, nm, artboards[i] if i < len(artboards) else None, src, base)
+        print("  全部. 全部")
+        return
+
+    # ── 多画板选择门禁（rules.md §十三 / SKILL.md §2 步骤 2，2026-09-17 机械兜底）──
+    # 未指定范围的生成运行必须先让用户从 1..n + 全部 里选；「全部」是用户的回答，不是 Agent 的默认值。
+    # 这里做机械卡点：打印清单后 exit 4，拿到用户回答再用 --indices / --only / --scope-all 重跑。
+    has_scope = bool(args.only or args.indices or args.sample)
+    scope_all_env = os.environ.get("SKETCH_SPEC_SCOPE_ALL", "") in ("1", "true", "yes")
+    if not has_scope and not args.scope_all and not scope_all_env:
+        print(f"[GATE] 多画板选择门禁（rules.md §十三）：本导出共 {total} 个画板，本次运行未指定范围"
+              f"（--only/--indices/--sample/--scope-all 均未给）。")
+        print("[GATE] 按铁律必须先把下面的清单（1..n + 全部）交给用户并**停止输出等回复**，"
+              "不得自行跑全量（「生成产物 / 前处理」请求同样适用）：")
+        for i, nm in enumerate(names):
+            print_board_line(i, nm, artboards[i] if i < len(artboards) else None, src, base)
+        print("  全部. 全部（整份导出全量跑 UI 产物；产卡时视为显式批量授权）")
+        print("[GATE] 拿到回复后重跑：回复序号 k → --indices <k-1>（0 起，多个用逗号）；"
+              "回复「全部」→ --scope-all；无人值守批量训练可直接 --scope-all 或 SKETCH_SPEC_SCOPE_ALL=1。")
+        sys.exit(4)
+
+    sel = select_canvases(names, args)
+    if not sel:
+        print("[WARN] 没有匹配到任何画布。", file=sys.stderr)
+        sys.exit(0)
+    print(f"[INFO] 本次生成 {len(sel)} 个画布：{', '.join(names[i] for i in sel)}")
+
+    assets_dir = src / "assets"
+    asset_index = build_asset_index(assets_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    manifest = {
+        "export": str(src),
+        "draft": args.draft,
+        "schemaVersion": "1.0",
+        "generatedAt": datetime.now().isoformat(timespec="seconds"),
+        "total": total,
+        "canvases": [],
+    }
+
+    # 部分运行（--only/--indices/--sample）只重解析选中画板；未选中画板的
+    # status / trainingEligible / artboardType 必须从旧 manifest 继承，
+    # 否则每次局部重跑都会把全量 eligibility 清空，下游数据集构建随之坍塌。
+    previous_entries = {}
+    previous_manifest = base / "manifest.json"
+    partial_run = len(sel) < total
+    if partial_run and previous_manifest.exists():
+        try:
+            saved = json.loads(previous_manifest.read_text(encoding="utf-8"))
+            previous_entries = {
+                item.get("name"): item
+                for item in saved.get("canvases", [])
+                if isinstance(item, dict) and item.get("name")
+            }
+        except (OSError, ValueError):
+            previous_entries = {}
+
+    for i, ab in enumerate(artboards):
+        name = names[i]
+        status = "generated" if i in sel else "pending"
+        entry = {
+            "order": i + 1,
+            "name": name,
+            "slug": name,
+            "status": status,
+            "trainingEligible": False,
+        }
+        if i not in sel and name in previous_entries:
+            for inherited in ("status", "trainingEligible", "artboardType", "preview"):
+                if inherited in previous_entries[name]:
+                    entry[inherited] = previous_entries[name][inherited]
+        if i in sel:
+            cdir = base / name
+            cdir.mkdir(parents=True, exist_ok=True)
+
+            # 整图截图（参考）
+            preview_rel = unquote(ab.get("imagePath", ""))
+            src_png = src / preview_rel
+            if not src_png.exists():
+                cand = list(src.glob(f"preview/*{name.split('_', 1)[-1]}*.png"))
+                src_png = cand[0] if cand else None
+            if src_png and src_png.exists():
+                shutil.copy2(src_png, cdir / "artboard.png")
+                entry["preview"] = f"{name}/artboard.png"
+                # —— P1 优化（RC5）：整屏 artboard.png 降采样，降低多模态 token 成本 ——
+                # 卡片主体细节由聚焦 card-*.png 承载，artboard.png 仅作整体参考，
+                # 最长边压到 --artboard-max-side（默认 640）；0 表示不降采样。
+                if args.artboard_max_side and args.artboard_max_side > 0:
+                    try:
+                        nw, nh = png_utils.downscale_png(
+                            str(cdir / "artboard.png"), str(cdir / "artboard.png"),
+                            args.artboard_max_side)
+                        print(f"  [downscale] artboard.png → {nw}×{nh} (max_side={args.artboard_max_side})")
+                    except Exception as e:  # noqa
+                        print(f"  [WARN] artboard 降采样失败（保留原图）：{e}", file=sys.stderr)
+            else:
+                print(f"  [WARN] {name}: 找不到整图 {preview_rel}", file=sys.stderr)
+
+            # 视觉聚焦：卡片区域检测 + 裁切
+            spec = focus_artboard(ab, src_png, cdir)
+
+            # 交互分类（视觉信号优先，名称兜底 — 详见 classify_artboard）
+            at, interaction = classify_artboard(name, spec, ab.get("layers") or [], ab.get("height", 812))
+            spec["artboardType"] = at
+            spec["interaction"] = interaction
+            # JSAPI 交互控件检测（密码/验证码/数字键盘/toast/二次确认）
+            spec["jsapiInteractions"] = detect_jsapi_interactions(spec, ab.get("layers") or [])
+            entry["artboardType"] = at
+            entry["trainingEligible"] = at == "card"
+
+            # 切图：逐元素建立导出映射，未命中素材的标注降级为整图采样纯色。
+            slice_names = spec.pop("slices", [])
+            matched = set()
+            for slice_name in slice_names:
+                matched.update(collect_slice_files([slice_name], asset_index))
+            slices_rel = copy_slices(assets_dir, cdir / "slices", sorted(matched))
+            if entry.get("preview"):
+                # 缺素材裁切必须用原分辨率 preview（src_png），不能用降采样后的 artboard.png
+                # （artboard.png 最长边压到 640 仅为多模态 token 优化；用它裁切会得到 0.6x 模糊图）。
+                mark_missing_slice_elements(
+                    spec, src_png, asset_index, assets_dir, cdir / "slices",
+                )
+            spec["slices"] = slices_rel
+
+            # 画板是否无卡（0 卡 → 标记跳过，保留整图供参考）
+            # 仅当既无独立卡片、又元素极少（<3）才视为真正空画板；
+            # 元素丰富但无卡的情况可能是底部弹窗/全屏覆盖层，保留 status 供下游决策。
+            if not spec["cards"] and len(spec.get("elements", [])) < 3:
+                entry["status"] = "skipped"
+                spec["skippedReason"] = "视觉检测无独立卡片元素（纯对话/提示/无卡片画板）"
+
+            (cdir / "spec.json").write_text(
+                json.dumps(spec, ensure_ascii=False, indent=2), encoding="utf-8")
+
+            n_cards = len(spec["cards"])
+            n_shot = sum(1 for c in spec["cards"] if c.get("image"))
+            print(f"  [{'SKIP' if not n_cards else 'OK'}] {name}: {n_cards} 卡 / {n_shot} 聚焦图 / "
+                  f"{len(slices_rel)} 切图 / {len(spec['elements'])} 视觉元素 / [{at}]")
+
+        manifest["canvases"].append(entry)
+
+    (base / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"[DONE] manifest.json 已写入 {base / 'manifest.json'}")
+
+    if args.build:
+        try:
+            import build_prompt as _bp
+            print("[INFO] 一步式 --build：生成 prompt.md / spec.md ...")
+            # 必须传 base（= out/<draft>）：传 out 会去平铺 UI/ 找 manifest，
+            # 结果是「本次画板没有 prompt.md，反而重写了别的稿的存量产物」。
+            _bp.run(str(base), only=None, all_flag=False)
+        except Exception as e:  # noqa
+            print(f"[WARN] --build 调用 build_prompt 失败：{e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()