cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,1118 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""vision.py — 纯视觉驱动的卡片区域检测（无业务词、无文本依赖）。
+
+设计原则（用户 2026-08-14 确认）：
+- 判定依据全部来自视觉几何：大块、独立、卡片状（有填充/圆角/阴影/描边）的元素即卡片。
+- 文本/名称只是附属信息，不参与「保留/剔除」判定（设计稿文本多为示意）。
+- 一个画板可出现 1..N 张卡片：空间上分离的视觉块各自成卡。
+- 卡片以外的一切（全屏背景、系统区、图标、装饰）在聚焦时全部剔除。
+"""
+import math
+import re
+
+
+# ---------- 几何常量（375x812 移动端设计稿；按画板尺寸比例自适应） ----------
+TOP_SYSTEM_RATIO = 0.12       # 顶部状态栏+导航占画板高度比例（约 88-90px @812）
+BOTTOM_SYSTEM_RATIO = 0.13    # 底部导航+AI输入框+Home Indicator 高度比例（约 100px @812）
+FULLSCREEN_BG_RATIO = 0.85    # 面积 >= 画板 85% 视为全屏背景（蒙版/背景）
+CARD_MIN_AREA_RATIO = 0.045   # 卡片最小面积 = 画板面积的 4.5%（375*812≈305k → ~13.7k px²）
+CARD_MAX_AREA_RATIO = 0.75    # 卡片最大面积 < 画板 75%（排除整屏）
+EDGE_DECOR_RATIO = 0.45       # 与画板顶/底边粘连且高度 < 45%H 的块视为装饰（椭圆/弥散背景）
+MERGE_GAP_RATIO = 0.02        # 两块之间间隙小于画板宽 2% 且高度相似时合并
+OVERLAY_MIN_WIDTH_RATIO = 0.55     # 居中对话框通常明显窄于画板
+OVERLAY_MAX_WIDTH_RATIO = 0.90
+OVERLAY_MIN_HEIGHT_RATIO = 0.16
+OVERLAY_MAX_HEIGHT_RATIO = 0.70
+OVERLAY_CENTER_TOLERANCE = 0.10    # 对话框水平中心容差
+# 相对外层卡壳的四周留白，用于区分嵌套内容和模态浮层。
+# 2026-09-06 由 0.015 降到 0.008：银行 alert 对话框常近全卡宽（综合推荐
+# 「总资产提示」335/343 宽，横向 inset 仅 4px <0.015W=5.6px 漏检）；模态语义
+# 已由前置 scrim 闸保证，inset 只需排除「内壳与外壳同宽对齐」的普通内容列。
+# 全 24 稿回归：新增 8 处检出均为真弹框（总资产提示/网点报错提示×4/交易
+# 密码框×2/转账计划时间修正提示），0 丢失。
+OVERLAY_MIN_INSET_X_RATIO = 0.008
+OVERLAY_MIN_INSET_Y_RATIO = 0.035
+
+
+class VisualElement:
+    """一个视觉元素（归一化后）：几何 + 视觉特征 + 附属信息。"""
+    __slots__ = ("name", "type", "rect", "fills", "radius", "shadows",
+                 "opacity", "border", "rotation", "texts", "children_count", "raw",
+                 "is_text", "is_slice",
+                 # 层级树信息（_flatten_with_tree 填充）
+                 "id", "parentId", "childIds", "depth")
+
+    def __init__(self, raw):
+        r = raw.get("rect") or {}
+        self.name = raw.get("name", "")
+        self.type = raw.get("type", "")
+        self.rect = (r.get("x", 0), r.get("y", 0), r.get("width", 0), r.get("height", 0))
+        self.fills = raw.get("fills") or []
+        self.radius = raw.get("radius") or []
+        self.shadows = raw.get("shadows") or []
+        self.opacity = raw.get("opacity", 1)
+        self.border = raw.get("borders") or []
+        self.rotation = raw.get("rotation", 0)
+        self.is_text = raw.get("type") == "text"
+        self.is_slice = raw.get("type") == "slice"
+        self.raw = raw
+        self.texts = []
+        self.children_count = 0
+        # 层级树信息（默认值，_flatten_with_tree 会覆写）
+        self.id = -1
+        self.parentId = None
+        self.childIds = []
+        self.depth = 0
+
+    @property
+    def area(self):
+        x, y, w, h = self.rect
+        return max(w, 0) * max(h, 0)
+
+    @property
+    def has_visual(self):
+        if self.fills:
+            return True
+        if any(x and x > 0 for x in self.radius):
+            return True
+        if self.shadows:
+            return True
+        if self.border:
+            return True
+        # Symbol：Sketch/Figma 可复用视觉组件。MeaXure 导出常为不展开子层的叶子节点
+        # （fills/shadows/borders 均为空数组），但符号本身承载渲染内容。
+        # 若误判 no_visual，大尺寸 symbol 卡片容器会从候选中丢失，
+        # 导致 detect_cards 区域收缩、聚焦裁切缺失卡片头部。issue-focus-001。
+        if self.type == "symbol":
+            return True
+        return False
+
+    def gradient_info(self):
+        out = []
+        for f in self.fills:
+            if not isinstance(f, dict):
+                continue
+            ft = f.get("fillType") or f.get("type") or ""
+            if "grad" not in str(ft).lower():
+                continue
+            g = f.get("gradient") or {}
+            gtype = g.get("type", "Linear")
+            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:
+                if str(gtype).lower().startswith("radial"):
+                    out.append("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)
+                    angle = "to bottom" if abs(ty - fy) >= abs(tx - fx) else "to right"
+                    out.append(f"linear-gradient({angle}, " + ", ".join(css_stops) + ")")
+        return out
+
+
+def _hex_of(color_obj):
+    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 _fill_hex(f):
+    if isinstance(f, dict) and f.get("color"):
+        return _hex_of(f["color"])
+    return None
+
+
+def _flatten_raw(raw_layers):
+    out = []
+    def walk(ls, parent_count=0):
+        for L in ls:
+            ve = VisualElement(L)
+            ve.children_count = parent_count
+            if L.get("layers"):
+                n = sum(1 for c in L["layers"])
+                ve.children_count += n
+                walk(L["layers"], n)
+            out.append(ve)
+    walk(raw_layers)
+    return out
+
+
+def _flatten_with_tree(raw_layers):
+    """保留层级关系的扁平化：每个 VisualElement 带 id / parentId / childIds / depth。
+
+    与 _flatten_raw 的区别：不丢掉树结构信息。返回的列表顺序仍为先序遍历
+   （与 _flatten_raw 一致，保证向后兼容），但每个节点可通过 parentId / childIds
+    重建原始嵌套关系。id 为列表下标（从 0 开始），稳定且唯一。
+    """
+    nodes = []
+    def walk(ls, parent_id, depth):
+        for L in ls:
+            node_id = len(nodes)
+            ve = VisualElement(L)
+            ve.id = node_id
+            ve.parentId = parent_id
+            ve.childIds = []
+            ve.depth = depth
+            ve.children_count = len(L.get("layers") or [])
+            nodes.append(ve)
+            if L.get("layers"):
+                child_start = len(nodes)
+                walk(L["layers"], node_id, depth + 1)
+                ve.childIds = list(range(child_start, len(nodes)))
+    walk(raw_layers, None, 0)
+    return nodes
+
+
+def _is_fullscreen(ve, W, H):
+    return ve.area >= FULLSCREEN_BG_RATIO * W * H
+
+
+def _in_system_zone(ve, W, H):
+    """系统 chrome（状态栏/底部导航/AI 输入框/Home Indicator）判定。
+    只看 y 区域会误杀「卡片底部内容」（如还款成功卡的字段区 y 落在底部 13% 但宽=卡宽非全宽导航）。
+    系统 chrome 特征 = 位于顶/底系统区 **且近全宽（≥0.95W）**：窄于画布宽的元素是卡片内容，不判系统区。"""
+    x, y, w, h = ve.rect
+    top = TOP_SYSTEM_RATIO * H
+    bottom = H - BOTTOM_SYSTEM_RATIO * H
+    if w < 0.95 * W:
+        return False  # 非全宽（卡片内容/字段区），即使落在系统区 y 也放行
+    return (y + h <= top) or (y >= bottom)
+
+
+def _is_edge_decor(ve, W, H):
+    """与画板顶/底边粘连的装饰块（椭圆/弥散背景/渐变条），非卡片。"""
+    x, y, w, h = ve.rect
+    if h <= 0:
+        return False
+    if y <= 0 and h < EDGE_DECOR_RATIO * H:
+        return True
+    if y + h >= H and h < EDGE_DECOR_RATIO * H:
+        return True
+    return False
+
+
+def _touch_screen_edges(ve, W):
+    x, y, w, h = ve.rect
+    return (x <= 0 and w >= 0.5 * W) or (x + w >= W and w >= 0.5 * W)
+
+
+def _overlap(a, b):
+    ax, ay, aw, ah = a
+    bx, by, bw, bh = b
+    ix = max(0, min(ax + aw, bx + bw) - max(ax, bx))
+    iy = max(0, min(ay + ah, by + bh) - max(ay, by))
+    return ix * iy
+
+
+def _union(a, b):
+    ax, ay, aw, ah = a
+    bx, by, bw, bh = b
+    x0 = min(ax, bx); y0 = min(ay, by)
+    x1 = max(ax + aw, bx + bw); y1 = max(ay + ah, by + bh)
+    return (x0, y0, x1 - x0, y1 - y0)
+
+
+def _intersect_ratio(a, b):
+    """a 与 b 的重叠面积占 a 面积比例。"""
+    if a[2] * a[3] <= 0:
+        return 0.0
+    return _overlap(a, b) / (a[2] * a[3])
+
+
+
+def _bottom_sheet_rect(raw_layers, W, H):
+    """贴底通栏 + 顶圆角底直角的底部抽屉面板矩形（无 fills 的 symbol 也由子层生效）。
+
+    返回 (x, y, w, h, radii)，radii=[top_r, top_r, 0, 0]；未找到返回 None。
+    """
+    best = None
+    def walk(ls):
+        nonlocal best
+        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)
+            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:
+                        if best is None or h > best[3]:
+                            best = (x, y, w, h, [top_r, top_r, 0, 0])
+            if L.get("layers"):
+                walk(L["layers"])
+    walk(raw_layers)
+    return best
+
+
+def _merge_rects(rects, W, H):
+    rects = [r for r in rects if r[2] > 0 and r[3] > 0]
+    merged = True
+    while merged:
+        merged = False
+        for i in range(len(rects)):
+            for j in range(i + 1, len(rects)):
+                a, b = rects[i], rects[j]
+                ov = _overlap(a, b)
+                if ov > 0:
+                    rects[i] = _union(a, b)
+                    rects.pop(j)
+                    merged = True
+                    break
+                ax, ay, aw, ah = a
+                bx, by, bw, bh = b
+                gap_x = max(bx - (ax + aw), ax - (bx + bw))
+                gap_y = max(by - (ay + ah), ay - (by + bh))
+                # 两级合并策略：
+                # 1) 像素级无缝相邻（gap≤0.5px）→ 无条件合并（同一视觉体的取整误差）
+                # 2) 小间隙（≤MERGE_GAP_RATIO）且高度相似（差≤30%）→ 合并
+                #    典型：卡片背景层与内容层之间有 2-8px 间隙但视觉上连续；
+                #    列表项之间有均匀间距但属于同一卡片。
+                #    高度相似约束防止把矮气泡并入高业务卡。
+                if gap_x <= 0.5 and gap_y <= 0.5:
+                    rects[i] = _union(a, b)
+                    rects.pop(j)
+                    merged = True
+                    break
+                if (gap_x <= MERGE_GAP_RATIO * W and gap_y <= MERGE_GAP_RATIO * H and
+                        abs(ah - bh) <= 0.3 * max(ah, bh, 1)):
+                    rects[i] = _union(a, b)
+                    rects.pop(j)
+                    merged = True
+                    break
+            if merged:
+                break
+    return rects
+
+
+def _rect_inside(inner, outer, tol=0.5):
+    """inner 是否落在 outer 内（含浮点/取整容差）。"""
+    ix, iy, iw, ih = inner
+    ox, oy, ow, oh = outer
+    return (ix >= ox - tol and iy >= oy - tol and
+            ix + iw <= ox + ow + tol and iy + ih <= oy + oh + tol)
+
+
+def _norm_rect_key(rect):
+    """rect 取整到 0.1px，用于合并同 rect 的多层外壳（如无圆角背景层 + 有圆角卡面）。"""
+    return tuple(round(float(v), 1) for v in rect)
+
+
+def _radii_score(radii):
+    """圆角信息强度：有圆角 > 无圆角；圆角角数越多、半径越大越像外壳。"""
+    vals = [max(0.0, float(v)) for v in (radii or [])]
+    pos = sum(1 for v in vals if v > 0)
+    max_r = max(vals) if vals else 0.0
+    return (1 if pos else 0, pos, max_r)
+
+
+def _radius_values(radii):
+    values = []
+    for value in (radii or []):
+        if isinstance(value, (int, float)) and value > 0:
+            values.append(float(value))
+    return values
+
+
+def _candidate_visuals(elements, W, H):
+    candidates = []
+    for ve in elements:
+        if ve.is_text or ve.is_slice or ve.area <= 0:
+            continue
+        if _is_fullscreen(ve, W, H) or _in_system_zone(ve, W, H) or _is_edge_decor(ve, W, H):
+            continue
+        if not ve.has_visual:
+            continue
+        x, y, w, h = ve.rect
+        if ve.area < CARD_MIN_AREA_RATIO * W * H:
+            continue
+        if h > 3 * w and w < 0.5 * W:
+            continue
+        if w > 2.5 * h and h < 0.05 * H:
+            continue
+        candidates.append(ve)
+    return candidates
+
+
+def _overlay_shell_metrics(ve, W, H):
+    x, y, w, h = ve.rect
+    width_ratio = w / W
+    height_ratio = h / H
+    if not (OVERLAY_MIN_WIDTH_RATIO <= width_ratio <= OVERLAY_MAX_WIDTH_RATIO):
+        return None
+    if not (OVERLAY_MIN_HEIGHT_RATIO <= height_ratio <= OVERLAY_MAX_HEIGHT_RATIO):
+        return None
+    center_dx = abs((x + w / 2) - W / 2)
+    if center_dx > OVERLAY_CENTER_TOLERANCE * W:
+        return None
+    if center_dy_ratio := abs((y + h / 2) / H - 0.5) > 0.38:
+        return None
+    radii = _radius_values(ve.radius)
+    if not (radii or ve.shadows or ve.border):
+        return None
+    return {"centerDxRatio": center_dx / W, "widthRatio": width_ratio, "heightRatio": height_ratio}
+
+
+def _has_modal_scrim(elements, W, H):
+    """模态遮罩（scrim）：近全屏（w≥90%W 且 h≥90%H）且半透明（opacity<0.95）的层。
+
+    与 parse_meaxure.detect_modal_layers 的 scrim 口径一致（契约：无 scrim 一律判 card）。
+    """
+    for ve in elements:
+        if ve.is_text:
+            continue
+        _, _, w, h = ve.rect
+        if w < 0.9 * W or h < 0.9 * H:
+            continue
+        try:
+            op = float(ve.opacity)
+        except (TypeError, ValueError):
+            op = 1.0
+        if op < 0.95:
+            return True
+    return False
+
+
+def detect_overlay_dialog(elements, width, height):
+    """通过嵌套几何识别居中模态对话框。
+
+    真实卡片可以嵌套子块；模态对话框的通用特征是一个有圆角/阴影的居中
+    中型壳体，完整内缩于更大的底层卡壳，并且同时包含文本与图形控件。
+    该判定不读取业务文案，也不依赖固定颜色。
+    """
+    W, H = float(width), float(height)
+    # 契约（SKILL §4.5）：无 scrim 一律判 card。居中嵌套壳体只是几何必要信号——
+    # 业务卡内嵌的空态/提示面板（如 01基金_基金推荐 系 8 个画板）同样满足嵌套几何，
+    # 必须有模态遮罩佐证才判 overlay_dialog，否则整板内容被误跳过。
+    if not _has_modal_scrim(elements, W, H):
+        return None
+    visuals = _candidate_visuals(elements, W, H)
+    for inner in visuals:
+        metrics = _overlay_shell_metrics(inner, W, H)
+        if not metrics:
+            continue
+        inner_text_count = 0
+        inner_rich_count = 0
+        for ve in elements:
+            if _intersect_ratio(ve.rect, inner.rect) < 0.7:
+                continue
+            if ve.is_text and ve.area > 0:
+                inner_text_count += 1
+            elif not ve.is_text and ve.area < 0.5 * inner.area and not _is_divider(ve):
+                inner_rich_count += 1
+        if inner_text_count < 1 or inner_rich_count < 1:
+            continue
+        for outer in visuals:
+            if outer is inner or outer.area <= 1.5 * inner.area:
+                continue
+            ix, iy, iw, ih = inner.rect
+            ox, oy, ow, oh = outer.rect
+            inset_x = min(ix - ox, (ox + ow) - (ix + iw))
+            inset_y = min(iy - oy, (oy + oh) - (iy + ih))
+            if (not _rect_inside(inner.rect, outer.rect, tol=0.015 * H) or
+                    inset_x < OVERLAY_MIN_INSET_X_RATIO * W or
+                    inset_y < -0.012 * H or oh < 1.5 * ih):
+                continue
+            metrics["outerRect"] = outer.rect
+            metrics["inset"] = {"x": inset_x, "y": inset_y}
+            return metrics
+    return None
+
+
+def _count_controls_near(elements, rect, width, height):
+    """统计与输入坞同一横带的独立小控件数量。"""
+    _, dock_y, _, dock_h = rect
+    count = 0
+    for ve in elements:
+        if ve.is_text or ve.area <= 0:
+            continue
+        x, y, w, h = ve.rect
+        if w > 0.22 * width or h > 0.14 * height:
+            continue
+        overlap = min(y + h, dock_y + dock_h) - max(y, dock_y)
+        if overlap < 0.35 * min(h, dock_h):
+            continue
+        if _intersect_ratio(ve.rect, rect) > 0.55:
+            continue
+        count += 1
+    return count
+
+
+def _detect_keyboard(elements, width, height):
+    """识别贴底大面积键盘：通栏壳体 + 大量小子控件。
+
+    键盘/底部选择器必然停靠屏幕底沿（真实样本底沿均 ≥0.94H）；
+    非贴底区域只有控件密度足够高（≥12，数字键盘 12 键起步）才可采信，
+    否则账户列表/商品列表这类「通栏壳 + 若干图标」会被误判成键盘。
+
+    控件计数按 rect 去重：Sketch 常把同一按钮导出为同 rect 的叠层
+    （阴影层 + 填充层），不去重会让计数翻倍——基金产品列表的 6~7 个
+    真实按钮被计成 12 个，恰好越过「12 键起步」门槛误判为键盘
+    （基金1128 #5/#6/#14/#15/#16）。真实数字键盘按键 rect 各不相同，
+    去重后仍 ≥16（收款人名册#20、我的账户#13、购汇#22 回归验证）。
+
+    按键网格闸（2026-09-06）：控件数去重后仍不够——资产配置雷达卡的
+    同心环 + 胶囊 + 标签共 25 个异 rect 控件，计数与真实键盘相当
+    （综合推荐1222 #3-#47 全族误检）。键盘的本质特征是「≥2 行同尺寸
+    按键行」（数字键盘 3-4 列 × 多行，行内 ≥75% 成员宽高落在行中位数
+    0.8~1.25 倍内）；雷达同心环尺寸递进、表单控件行尺寸参差，同尺寸
+    按键行数为 0-1。真密码键盘全部 ≥2（购汇#22=3、转账计划#21=5、
+    收款人名册#20=2、我的账户#13=2、信用卡还款#9=2）。
+    """
+    W, H = float(width), float(height)
+    for ve in elements:
+        if ve.is_text or ve.is_slice or ve.area <= 0:
+            continue
+        x, y, w, h = ve.rect
+        if (w < 0.82 * W or h < 0.18 * H or h > 0.78 * H or
+                y < 0.28 * H or (y + h) < 0.78 * H):
+            continue
+        small_controls = 0
+        seen_control_rects = set()
+        control_rects = []
+        for child in elements:
+            if child is ve or child.is_text or child.area <= 0:
+                continue
+            if _intersect_ratio(child.rect, ve.rect) < 0.55:
+                continue
+            if child.area < 0.001 * W * H or child.area > 0.02 * W * H:
+                continue
+            rect_key = _norm_rect_key(child.rect)
+            if rect_key in seen_control_rects:
+                continue
+            seen_control_rects.add(rect_key)
+            control_rects.append(child.rect)
+            small_controls += 1
+        bottom_docked = (y + h) >= 0.90 * H
+        if (small_controls >= 8 and (bottom_docked or small_controls >= 12)
+                and _uniform_key_rows(control_rects) >= 2):
+            return {
+                "rect": ve.rect,
+                "smallControlCount": small_controls,
+                "heightRatio": h / H,
+            }
+    return None
+
+
+def _uniform_key_rows(control_rects):
+    """统计「同尺寸按键行」数量：≥3 个控件 y 中心对齐成行，且行内
+    ≥75% 成员宽高都落在行中位数的 0.8~1.25 倍内。
+
+    数字键盘的按键行天然满足（同尺寸键 3-4 列 × 多行）；雷达图同心环、
+    表单控件行、商品按钮行的尺寸参差或不足 3 个一行，返回 0-1。
+    """
+    items = sorted(control_rects, key=lambda r: r[1] + r[3] / 2)
+    rows = []
+    for rect in items:
+        cy = rect[1] + rect[3] / 2
+        for row in rows:
+            if abs(row["cy"] - cy) <= max(8.0, 0.5 * rect[3]):
+                row["rects"].append(rect)
+                row["cy"] = (row["cy"] * (len(row["rects"]) - 1) + cy) / len(row["rects"])
+                break
+        else:
+            rows.append({"cy": cy, "rects": [rect]})
+    uniform = 0
+    for row in rows:
+        members = row["rects"]
+        if len(members) < 3:
+            continue
+        widths = sorted(r[2] for r in members)
+        heights = sorted(r[3] for r in members)
+        median_w = widths[len(widths) // 2]
+        median_h = heights[len(heights) // 2]
+        same = sum(
+            1 for r in members
+            if 0.8 * median_w <= r[2] <= 1.25 * median_w
+            and 0.8 * median_h <= r[3] <= 1.25 * median_h
+        )
+        if same >= 0.75 * len(members):
+            uniform += 1
+    return uniform
+
+
+def _keyboard_below_dock(elements, dock, width, height):
+    """识别输入坞下方的大面积贴底交互层，兼容整图导出的系统键盘。"""
+    dx, dy, dw, dh = dock["rect"]
+    dock_bottom = dy + dh
+    W, H = float(width), float(height)
+    for ve in elements:
+        if ve.is_text or ve.is_slice or ve.area <= 0:
+            continue
+        x, y, w, h = ve.rect
+        if w < 0.82 * W or h < 0.20 * H or y < dock_bottom - 2:
+            continue
+        if y - dock_bottom > 0.12 * H or (y + h) < 0.82 * H:
+            continue
+        return {
+            "rect": ve.rect,
+            "heightRatio": h / H,
+            "detection": "below-input-dock",
+        }
+    return None
+
+
+def detect_conversation_flow(elements, width, height):
+    """识别会话流画板：输入坞/键盘与气泡壳互相印证。
+
+    会话页中的气泡、推荐列表、评分条都是交互流片段，不是最终落地的独立
+    业务卡片。这里只使用横向输入控件、贴底键盘、圆角气泡壳与纵向堆叠等
+    几何信号，不读取业务文案，也不依赖固定颜色。
+    """
+    W, H = float(width), float(height)
+    input_dock = None
+    dock_candidates = []
+    for ve in elements:
+        if ve.is_text or ve.is_slice or ve.area <= 0:
+            continue
+        x, y, w, h = ve.rect
+        width_ratio = w / W
+        height_ratio = h / H
+        if not (0.38 <= width_ratio <= 0.96 and 0.025 <= height_ratio <= 0.13):
+            continue
+        if w / max(h, 1) < 2.2:
+            continue
+        center_dx = abs((x + w / 2) - W / 2)
+        if center_dx > 0.18 * W:
+            continue
+        if (y + h) < 0.45 * H:
+            continue
+        controls = _count_controls_near(elements, ve.rect, W, H)
+        text_count = sum(
+            1 for child in elements
+            if child.is_text and _intersect_ratio(child.rect, ve.rect) >= 0.55
+        )
+        if controls >= 2 and text_count >= 1:
+            dock_candidates.append((controls, ve))
+
+    if dock_candidates:
+        dock_candidates.sort(key=lambda item: (item[0], item[1].area), reverse=True)
+        dock = dock_candidates[0][1]
+        input_dock = {
+            "rect": dock.rect,
+            "nearbyControlCount": dock_candidates[0][0],
+        }
+
+    keyboard = _detect_keyboard(elements, W, H)
+    if input_dock and not keyboard:
+        keyboard = _keyboard_below_dock(elements, input_dock, W, H)
+    if not input_dock and not keyboard:
+        return None
+
+    bubbles = []
+    for ve in _candidate_visuals(elements, W, H):
+        x, y, w, h = ve.rect
+        if not (0.42 <= w / W <= 0.98 and 0.035 <= h / H <= 0.48):
+            continue
+        text_count = sum(
+            1 for child in elements
+            if child.is_text and _intersect_ratio(child.rect, ve.rect) >= 0.55
+        )
+        if text_count < 1:
+            continue
+        bubbles.append({"rect": ve.rect, "textCount": text_count})
+
+    stacked_bubbles = 0
+    ordered = sorted(bubbles, key=lambda item: item["rect"][1])
+    maximal_bubbles = []
+    for index, bubble in enumerate(ordered):
+        rect = bubble["rect"]
+        contained = any(
+            other is not bubble and _rect_inside(rect, other["rect"], tol=1.0)
+            for other in ordered
+        )
+        if not contained:
+            maximal_bubbles.append(bubble)
+    for index in range(1, len(maximal_bubbles)):
+        previous = maximal_bubbles[index - 1]
+        current = maximal_bubbles[index]
+        gap = current["rect"][1] - (previous["rect"][1] + previous["rect"][3])
+        if 0 <= gap <= 0.16 * H:
+            stacked_bubbles += 1
+
+    if keyboard and input_dock:
+        pass
+    elif not bubbles or (len(bubbles) < 2 and not keyboard):
+        return None
+    elif not keyboard and stacked_bubbles == 0:
+        return None
+
+    return {
+        "inputDock": input_dock,
+        "keyboard": keyboard,
+        "bubbleCount": len(bubbles),
+        "stackedBubblePairs": stacked_bubbles,
+    }
+
+
+def _is_repeated_control_bar(elements, rect):
+    """识别横向重复图标/选项控件条，例如评分、开关组或快捷操作条。"""
+    x, y, w, h = rect
+    card_area = max(w * h, 1)
+    clusters = []
+    for ve in elements:
+        if ve.is_text or ve.area <= 0:
+            continue
+        vx, vy, vw, vh = ve.rect
+        width_ratio = vw / max(w, 1)
+        height_ratio = vh / max(h, 1)
+        if not (0.07 <= width_ratio <= 0.32 and 0.18 <= height_ratio <= 0.92):
+            continue
+        if not (0.45 <= vw / max(vh, 1) <= 2.2):
+            continue
+        if _intersect_ratio(ve.rect, rect) < 0.55:
+            continue
+        center_x = vx + vw / 2
+        center_y = vy + vh / 2
+        target = None
+        for cluster in clusters:
+            _, sample_x, sample_y, sample_w, sample_h, _ = cluster
+            if (abs(center_x - sample_x) <= 0.015 * w and
+                    abs(center_y - sample_y) <= 0.06 * h):
+                target = cluster
+                break
+            if (abs(center_x - sample_x) <= 0.05 * w and
+                    abs(center_y - sample_y) <= 0.16 * h and
+                    0.55 <= vw / max(sample_w, 1) <= 1.8 and
+                    0.55 <= vh / max(sample_h, 1) <= 1.8):
+                target = cluster
+                break
+        if target is None:
+            clusters.append([ve, center_x, center_y, vw, vh, ve.area])
+        elif ve.area > target[5]:
+            target[:] = [ve, center_x, center_y, vw, vh, ve.area]
+
+    if len(clusters) < 3:
+        return False
+    clusters.sort(key=lambda item: item[1])
+    gaps = [
+        clusters[index + 1][1] - clusters[index][1]
+        for index in range(len(clusters) - 1)
+    ]
+    span = clusters[-1][1] - clusters[0][1]
+    # 支配性守卫（2026-09-06，01基金_基金推荐 误杀案例）：真控件条（评分/开关组/
+    # 快捷操作条）整卡几乎只有这条横排，纵向应占据卡片大部分；业务卡底部的
+    # 同构子卡行（3 列收益卡/入口宫格）只覆盖卡高一部分，标题/列表等主内容在上。
+    # 用簇的纵向并集覆盖率区分两者，避免把业务卡误判为控件条。
+    band_top = min(item[2] - item[4] / 2 for item in clusters)
+    band_bottom = max(item[2] + item[4] / 2 for item in clusters)
+    band_cover = (band_bottom - band_top) / max(h, 1)
+    if band_cover < 0.5:
+        return False
+    return span >= 0.48 * w and max(gaps) - min(gaps) <= 0.38 * max(gaps)
+
+
+def _is_chat_bubble_shell(elements, rect, width, height):
+    """识别左右锚定的中型气泡/推荐壳，不把会话流片段当独立卡片。
+
+    关键区分：含图片/切图/多形状等富视觉内容的壳体是商品卡/内容卡，
+    不是简单对话气泡 → 返回 False。
+    """
+    x, y, w, h = rect
+    width_ratio = w / max(width, 1)
+    left_inset = x / max(width, 1)
+    right_inset = (width - x - w) / max(width, 1)
+    if not (0.38 <= width_ratio <= 0.88):
+        return False
+    if min(left_inset, right_inset) < 0.035 or max(left_inset, right_inset) < 0.07:
+        return False
+    text_count = sum(
+        1 for ve in elements
+        if ve.is_text and _intersect_ratio(ve.rect, rect) >= 0.55
+    )
+    # 富视觉内容检测：含切图/图片/多形状的壳体是内容卡，不是气泡
+    rich_count = sum(
+        1 for ve in elements
+        if not ve.is_text and _intersect_ratio(ve.rect, rect) >= 0.55
+        and not _is_divider(ve) and ve.area > 0
+        and (ve.is_slice or ve.type == "symbol"
+             or (ve.type == "shape" and (ve.fills or ve.border
+                or any(v > 0 for v in _radius_values(ve.radius)))))
+    )
+    if rich_count >= 2:
+        return False
+    return text_count >= 1
+
+
+def _is_prose_paragraph_region(elements, rect):
+    """识别散文段落区域（AI 回复的纯文字说明块）——不是卡片。
+
+    几何签名（与列表/表单卡区分）：
+      - 文本按行堆叠，行距 ≈ 行高（pitch/height <= 1.6，列表行通常 >= 2）；
+      - 行高几乎一致（±4px），行首 x 对齐（±6px）；
+      - 区域内有 >= 3 行。
+    注意 MeaXure 会把同行不同字重的片段（如加粗金额）导出为多个文本，
+    因此行首对齐必须按「行聚类」后的行起始 x 判定，而非逐文本判定。
+    列表卡即使纯文本也有行壳间距与多列 x 分布，不会同时满足以上三条。
+    """
+    x, y, w, h = rect
+    texts = [
+        ve for ve in elements
+        if ve.is_text and ve.area > 0 and _intersect_ratio(ve.rect, rect) >= 0.55
+    ]
+    if len(texts) < 3:
+        return False
+    # 剔除合并容器层（MeaXure 常同时导出整段合并层 + 行碎片）：高度远超中位行高者
+    heights = sorted(ve.rect[3] for ve in texts)
+    median_h = heights[len(heights) // 2] or 1
+    line_texts = [ve for ve in texts if ve.rect[3] <= median_h * 1.8]
+    if len(line_texts) < 3:
+        return False
+    # 行高一致性：>= 2/3 文本行高在中位行高 ±4 内
+    uniform = sum(1 for ve in line_texts if abs(ve.rect[3] - median_h) <= 4)
+    if uniform < len(line_texts) * 2 / 3:
+        return False
+    # 行聚类：y 差 <= 行高一半 的文本属同一行（同行可能有多个不同字重碎片）
+    line_texts = sorted(line_texts, key=lambda ve: (ve.rect[1], ve.rect[0]))
+    lines = []  # [(line_y, line_x0)]
+    for ve in line_texts:
+        vy, vx = ve.rect[1], ve.rect[0]
+        if lines and vy - lines[-1][0] <= median_h * 0.5:
+            prev_y, prev_x0 = lines[-1]
+            lines[-1] = (prev_y, min(prev_x0, vx))
+        else:
+            lines.append((vy, vx))
+    if len(lines) < 3:
+        return False
+    # 行首 x 对齐：>= 2/3 行的起始 x 在最小行首 x ±6 内（换行行首）
+    min_line_x = min(lx for _, lx in lines)
+    left_aligned = sum(1 for _, lx in lines if abs(lx - min_line_x) <= 6)
+    if left_aligned < len(lines) * 2 / 3:
+        return False
+    # 行距/行高比：相邻行距应 ≈ 行高
+    pitches = sorted(lines[i + 1][0] - lines[i][0] for i in range(len(lines) - 1))
+    median_pitch = pitches[len(pitches) // 2] or 1
+    return median_pitch <= median_h * 1.6
+
+
+def _is_stacked_text_bubble_union(elements, rect, width, height):
+    """识别两个以上同宽同高文本气泡合并出的全宽区域。
+
+    关键区分：如果"气泡"被一个有视觉属性（圆角/填充/阴影/描边）的大壳体
+    包裹，它们是卡片的列表子项（如积分明细行、优惠券条目），不是独立对话
+    气泡 → 返回 False。
+
+    第二重区分（2026-09-06）：配对壳体必须内部无图形控件才算文本气泡。
+    业务卡的相邻区块（如基金对比卡的 VS 段与产品段）几何上同样「同宽、
+    相邻、高度差≤35%」，但内部含按钮/图表等控件——卡片证据优先直接放行。
+    误杀案例：基金1128 #14/#15/#16（产品比较卡）、理财1218 #24、
+    网点查询1219 #8/#13；真气泡（转账二批次 #25-27、收款人名册 #9-13）
+    内部控件数为 0，不受影响。
+    """
+    _, _, w, h = rect
+    if w < 0.82 * width or h < 0.08 * height:
+        return False
+    shells = []
+    for ve in _candidate_visuals(elements, width, height):
+        if _intersect_ratio(ve.rect, rect) < 0.55:
+            continue
+        text_count = sum(
+            1 for child in elements
+            if child.is_text and _intersect_ratio(child.rect, ve.rect) >= 0.55
+        )
+        if text_count >= 1:
+            shells.append(ve)
+    # 卡片壳体包含检测：存在有视觉属性的大壳体包裹 ≥50% 子壳 → 是卡片列表
+    if len(shells) >= 3:
+        for ve in shells:
+            has_shell_visual = (
+                any(v > 0 for v in _radius_values(ve.radius))
+                or ve.fills or ve.shadows or ve.border
+            )
+            if not has_shell_visual:
+                continue
+            contained = sum(
+                1 for other in shells
+                if other is not ve and _rect_inside(other.rect, ve.rect, tol=2.0)
+            )
+            if contained >= max(2, len(shells) * 0.5):
+                return False
+    found_bubble_pair = False
+    for index, left in enumerate(shells):
+        for right in shells[index + 1:]:
+            lx, ly, lw, lh = left.rect
+            rx, ry, rw, rh = right.rect
+            if (abs(lw - rw) <= 0.18 * max(lw, rw) and
+                    abs(lh - rh) <= 0.35 * max(lh, rh)):
+                gap = ry - (ly + lh)
+                if 0 <= gap <= 0.16 * height:
+                    if (_inner_visual_count(left, elements) <= 1 and
+                            _inner_visual_count(right, elements) <= 1):
+                        found_bubble_pair = True
+                    else:
+                        return False
+    return found_bubble_pair
+
+
+def _inner_visual_count(shell, elements):
+    """壳体内部的图形控件数（剔除文本、分隔线、同 rect 叠层与背景层）。
+
+    用于区分「文本气泡」（内部仅文字，控件数≈0）与「卡片区块」
+    （内部有按钮/图表等控件）。
+    """
+    count = 0
+    shell_key = _norm_rect_key(shell.rect)
+    for child in elements:
+        if child.is_text or child.area <= 0 or _is_divider(child):
+            continue
+        if _norm_rect_key(child.rect) == shell_key:
+            continue
+        if child.area >= 0.5 * shell.area:
+            continue
+        if _intersect_ratio(child.rect, shell.rect) < 0.55:
+            continue
+        count += 1
+    return count
+
+
+def _is_divider(ve):
+    _, _, width, height = ve.rect
+    return width <= 2 or height <= 2
+
+
+def card_focus_metrics(elements, rect, width, height):
+    """量化候选区域的结构复杂度，供聚焦提取统一过滤。"""
+    x, y, w, h = rect
+    card_area = max(w * h, 1)
+    text_count = 0
+    rich_count = 0
+    slice_count = 0
+    symbol_count = 0
+    shape_count = 0
+    for ve in elements:
+        if _intersect_ratio(ve.rect, rect) < 0.35:
+            continue
+        if ve.is_text:
+            if ve.area > 0:
+                text_count += 1
+            continue
+        if _is_divider(ve) or ve.area >= 0.55 * card_area:
+            continue
+        if ve.is_slice:
+            slice_count += 1
+            rich_count += 1
+        elif ve.type == "symbol":
+            symbol_count += 1
+            rich_count += 1
+        elif ve.type == "shape" and (ve.fills or ve.border or any(v > 0 for v in _radius_values(ve.radius))):
+            shape_count += 1
+            rich_count += 1
+    return {
+        "areaRatio": card_area / max(width * height, 1),
+        "aspectRatio": w / max(h, 1),
+        "heightRatio": h / max(height, 1),
+        "textCount": text_count,
+        "richComponentCount": rich_count,
+        "sliceCount": slice_count,
+        "symbolCount": symbol_count,
+        "shapeCount": shape_count,
+    }
+
+
+def classify_card_focus(elements, rect, width, height, interaction_flow=None):
+    """判定候选区域是否是可落地的独立卡片。
+
+    只使用几何与结构复杂度：对话/纯文本容器缺少有效图形控件；按钮/工具条
+    是扁长低复杂度壳体；两者都不应进入下游训练。
+    """
+    x, y, w, h = rect
+    metrics = card_focus_metrics(elements, rect, width, height)
+    if interaction_flow:
+        for signal_name in ("inputDock", "keyboard"):
+            signal = interaction_flow.get(signal_name)
+            signal_rect = signal.get("rect") if signal else None
+            if not signal_rect:
+                continue
+            sx, sy, sw, sh = signal_rect
+            signal_area = max(sw * sh, 1)
+            ix = max(0, min(x + w, sx + sw) - max(x, sx))
+            iy = max(0, min(y + h, sy + sh) - max(y, sy))
+            if (ix * iy) / signal_area >= 0.30:
+                return False, f"conversation_{signal_name}_region", metrics
+    if metrics["richComponentCount"] == 0 and metrics["textCount"] == 0:
+        return False, "empty_region", metrics
+    # 低结构判定：richComponent < 2 且文本也不足 → 才拒绝。
+    # 文本丰富的卡片（如积分明细列表，textCount≥4）即使 rich 少也应保留，
+    # 下游可从纯文本+几何生成合法卡片。
+    if metrics["richComponentCount"] < 2 and metrics["textCount"] < 4:
+        return False, "text_only_or_low_structure_region", metrics
+    # 纯文本散文段落（AI 回复说明文字）：无论文本多丰富都不是卡片。
+    # 用户规则：对话气泡/纯文本回复不参与卡片训练。
+    if metrics["richComponentCount"] == 0 and _is_prose_paragraph_region(elements, rect):
+        return False, "prose_paragraph_region", metrics
+    if _is_repeated_control_bar(elements, rect):
+        return False, "repeated_control_bar_region", metrics
+    if _is_chat_bubble_shell(elements, rect, width, height):
+        return False, "conversation_bubble_region", metrics
+    if _is_stacked_text_bubble_union(elements, rect, width, height):
+        return False, "stacked_conversation_bubbles_region", metrics
+    if (metrics["aspectRatio"] >= 2.2 and metrics["heightRatio"] <= 0.15 and
+            metrics["richComponentCount"] <= 2):
+        return False, "single_button_or_bar_region", metrics
+    return True, "", metrics
+
+
+def detect_cards(raw_layers, width, height, interaction_flow=None):
+    """核心：从图层原始数据检测 1..N 个卡片区域。
+
+    返回 [(x, y, w, h, elements, shapes)]：
+      - elements：归属于该卡片的 VisualElement 列表
+      - shapes：[((sx,sy,sw,sh), radii), ...]，卡片外壳几何（仅 rect+radius，
+        用于生成透明遮罩，**不依赖背景颜色**）
+    """
+    W, H = float(width), float(height)
+    elements = _flatten_with_tree(raw_layers)
+    bs = _bottom_sheet_rect(raw_layers, W, H)
+    if detect_overlay_dialog(elements, W, H) or bs:
+        return []
+
+    candidates = []
+    candidate_shapes = []
+    for ve in _candidate_visuals(elements, W, H):
+        x, y, w, h = ve.rect
+        candidates.append(ve.rect)
+        candidate_shapes.append((ve.rect, list(ve.radius or [])))
+
+    cards = _merge_rects(candidates, W, H)
+
+    result = []
+    for c in cards:
+        if interaction_flow:
+            cx, cy, cw, ch = c
+            candidate_area = max(cw * ch, 1)
+            rejected = False
+            for signal_name in ("inputDock", "keyboard"):
+                signal = interaction_flow.get(signal_name)
+                signal_rect = signal.get("rect") if signal else None
+                if not signal_rect:
+                    continue
+                sx, sy, sw, sh = signal_rect
+                ix = max(0, min(cx + cw, sx + sw) - max(cx, sx))
+                iy = max(0, min(cy + ch, sy + sh) - max(cy, sy))
+                if (ix * iy) / candidate_area >= 0.30:
+                    rejected = True
+                    break
+            if rejected:
+                continue
+        elements_in = []
+        for ve in elements:
+            if _point_in_rect(ve_center(ve), c) or _overlap(ve.rect, c) > 0.3 * ve.area:
+                elements_in.append(ve)
+        # 同 rect 的外壳层去重：优先保留有圆角的卡面，剔除同 rect 的
+        # 无圆角背景层。否则无圆角矩形会把圆角外背景重新遮成不透明。
+        by_rect = {}
+        for r, rad in candidate_shapes:
+            if not _rect_inside(r, c):
+                continue
+            key = _norm_rect_key(r)
+            cur = by_rect.get(key)
+            if cur is None or _radii_score(rad) > _radii_score(cur[1]):
+                by_rect[key] = (r, rad)
+        shapes = sorted(by_rect.values(), key=lambda item: (item[0][1], item[0][0]))
+        result.append((c[0], c[1], c[2], c[3], elements_in, shapes))
+
+    result.sort(key=lambda t: (t[1], t[0]))
+    return result
+
+
+def ve_center(ve):
+    x, y, w, h = ve.rect
+    return (x + w / 2, y + h / 2)
+
+
+def _point_in_rect(pt, r):
+    px, py = pt
+    x, y, w, h = r
+    return x <= px <= x + w and y <= py <= y + h
+
+
+# ---------- Flex 布局推断（纯几何，对齐平台节点 flex 属性） ----------
+def infer_flex_layout(container_rect, child_rects):
+    """从容器与其子元素几何推断 flex 布局参数（纯视觉，无文本依赖）。
+
+    MeaXure 导出的是绝对定位元素（Sketch 模型），无显式 flex 属性。
+    本函数从子元素的排列方向与对齐方式反推平台节点可用的 flex 参数：
+      - direction : row（横向排列） / column（纵向排列）
+      - justify   : 主轴对齐（flex-start/center/flex-end/space-between）
+      - align     : 交叉轴对齐（flex-start/center/flex-end/stretch）
+
+    参数：
+      container_rect : (x, y, w, h) 容器矩形
+      child_rects    : [(x, y, w, h), ...] 直接子元素矩形（已剔除容器自身）
+    返回 dict 或 None（子元素 <2 无法判定对齐）。
+    """
+    if len(child_rects) < 2:
+        return None
+    cx, cy, cw, ch = container_rect
+    kids = [r for r in child_rects if r[2] > 0 and r[3] > 0]
+    if len(kids) < 2:
+        return None
+    # 方向判定：子元素中心在 x 上方差 vs y 上方差，大者为排列主轴
+    xs = [r[0] + r[2] / 2 for r in kids]
+    ys = [r[1] + r[3] / 2 for r in kids]
+    spread_x = max(xs) - min(xs)
+    spread_y = max(ys) - min(ys)
+    direction = "row" if spread_x >= spread_y else "column"
+    if direction == "row":
+        main_centers, cross_centers = xs, ys
+        main_size, cross_size = cw, ch
+        kid_main_size = [r[2] for r in kids]
+    else:
+        main_centers, cross_centers = ys, xs
+        main_size, cross_size = ch, cw
+        kid_main_size = [r[3] for r in kids]
+    main_start = (cx if direction == "row" else cy)
+    # 主轴对齐：子元素中心相对容器主轴的分布
+    main_extent = max(main_centers) - min(main_centers)
+    main_min_off = min(main_centers) - main_start
+    main_max_off = (main_start + main_size) - max(main_centers)
+    total_kid_main = sum(kid_main_size)
+    slack = main_size - total_kid_main
+    justify = "flex-start"
+    if slack > 0:
+        # 间距均匀且两侧留白相近 → space-between 或 center
+        if len(kids) >= 3 and main_extent > 0:
+            gaps = [main_centers[i + 1] - main_centers[i] for i in range(len(main_centers) - 1)]
+            if gaps and max(gaps) - min(gaps) <= 0.3 * max(gaps):
+                justify = "space-between" if (abs(main_min_off - main_max_off) < 0.2 * slack) else "space-between"
+        if justify == "flex-start":
+            if abs(main_min_off - main_max_off) <= 0.2 * slack:
+                justify = "center"
+            elif main_max_off < main_min_off:
+                justify = "flex-end"
+    # 交叉轴对齐：子元素中心相对容器交叉轴居中度
+    cross_start = (cy if direction == "row" else cx)
+    cross_offs = [c - (cross_start + cross_size / 2) for c in cross_centers]
+    avg_cross_off = sum(cross_offs) / len(cross_offs)
+    if abs(avg_cross_off) <= 0.1 * cross_size:
+        align = "center"
+    elif avg_cross_off < 0:
+        align = "flex-start"
+    else:
+        align = "flex-end"
+    return {
+        "direction": direction,
+        "justifyContent": justify,
+        "alignItems": align,
+        "childCount": len(kids),
+    }