cardbuddy 0.14.2 → 0.15.0

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

@@ -16,22 +16,24 @@ parse_meaxure.py — 解析 Sketch MeaXure 标注导出，视觉驱动生成「
     card.json            状态 / 交互 / 样式 / 列表 聚合信息
     states/<画板名>/
       artboard.png       整图（参考）
-      card-1.png(...)    聚焦裁切图（每张卡片或每板一图，@2x）
+      card-1.png(...)    聚焦裁切图（每张卡片或每板一图，@2x；text_only 纯文本板不产，含兜底图）
       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 §十三）。
+  # 多画板选择门禁：不带 --pick/--only/--indices/--sample/--scope-all 的生成运行会打印 1..n+全部 清单并 exit 4，
+  # 等用户回复序号/「全部」后照抄清单行尾的 --pick 重跑（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 --pick 8.1                      # 按清单序号（1 起，可带卡号）——推荐，免换算
+  python parse_meaxure.py --indices 0,9,18                # 按 0 基序号（老写法，与 --pick 等价）
   python parse_meaxure.py --src <导出目录> --out <UI> --build
   python parse_meaxure.py --build                         # 一步式（含 build_prompt）
 """
 import argparse
+import difflib
 import hashlib
 import json
 import math
@@ -515,25 +517,60 @@ def _deduplicate_shell_elements(els):
     return output
 
 
-def focus_artboard(ab_raw, preview_path, cdir):
-    """对一个画板：检测独立卡片区域 → 结构过滤 → 逐一裁切 → 序列化标注。
+def detect_artboard_cards(ab_raw):
+    """画板级几何分析（不读图、不裁切）：检出卡片候选 → 逐块聚焦判定。
 
-    返回 spec dict（含卡片区域、聚焦截图、样式汇总）。
+    返回 dict：W / H / layers / overlay / sheet / conversationFlow /
+    cards [(x,y,w,h,els,shapes,focusMetrics)] / rejected [{rect,reason,metrics}] /
+    focusSkipReason（"" | overlay_dialog_geometry | bottom_sheet_geometry）。
+
+    这是**唯一**的卡片检出入口：focus_artboard（真跑，随后按卡片裁图）与门禁清单的
+    board_verdict（只想知道「这个画板有没有卡可建」）都走它，两处判定不会漂移。
     """
     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)
+    flattened = vision._flatten_with_tree(raw_layers)
+    overlay = vision.detect_overlay_dialog(flattened, W, H)
     bottom_sheet = vision._bottom_sheet_rect(raw_layers, W, H)
-    conversation_flow = vision.detect_conversation_flow(flattened_layers, W, H)
+    conversation_flow = vision.detect_conversation_flow(flattened, W, H)
+    cards, rejected, focus_skip_reason = [], [], ""
     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 x, y, w, h, els, shapes in vision.detect_cards(raw_layers, W, H, conversation_flow):
+            eligible, reason, focus_metrics = vision.classify_card_focus(
+                els, (x, y, w, h), W, H, conversation_flow)
+            if eligible:
+                cards.append((x, y, w, h, els, shapes, focus_metrics))
+            else:
+                rejected.append({
+                    "rect": {"x": round(x, 2), "y": round(y, 2),
+                             "width": round(w, 2), "height": round(h, 2)},
+                    "reason": reason,
+                    "metrics": focus_metrics,
+                })
+    return {
+        "W": W, "H": H, "layers": raw_layers,
+        "overlay": bool(overlay), "sheet": bool(bottom_sheet),
+        "conversationFlow": conversation_flow,
+        "cards": cards, "rejected": rejected,
+        "focusSkipReason": focus_skip_reason,
+    }
+
+
+def focus_artboard(ab_raw, preview_path, cdir):
+    """对一个画板：检测独立卡片区域 → 结构过滤 → 逐一裁切 → 序列化标注。
+
+    返回 spec dict（含卡片区域、聚焦截图、样式汇总）。
+    """
+    found = detect_artboard_cards(ab_raw)
+    W, H = found["W"], found["H"]
+    raw_layers = found["layers"]
+    overlay, bottom_sheet = found["overlay"], found["sheet"]
+    conversation_flow = found["conversationFlow"]
+    focus_skip_reason = found["focusSkipReason"]
 
     for old_png in cdir.glob("card-*.png"):
         old_png.unlink()
@@ -544,21 +581,8 @@ def focus_artboard(ab_raw, preview_path, cdir):
         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))
+    rejected_regions = found["rejected"]
+    eligible_cards = found["cards"]
 
     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):
@@ -607,16 +631,29 @@ def focus_artboard(ab_raw, preview_path, cdir):
         region["detectedList"] = detect_list_in_card(region) or None
         card_regions.append(region)
 
+    # 纯文本板（对话/问答/提示）连兜底截图都不产：一张整屏裁切图叫 card-1.png，下游
+    # 会当成「这个板有卡」（spec_tree.mjs 就拿 card-1.png 当预览降级），正好抵消本次过滤。
+    # 判定输入与 classify_artboard 同源：候选全被纯文本类理由否掉 + 板上无卡片级大盘切图。
+    text_only = is_text_only_artboard(
+        {"cards": card_regions,
+         "rejectedCards": rejected_regions,
+         "focusSkipReason": focus_skip_reason or (
+             "no_structural_card_region" if not card_regions else ""),
+         "size": {"width": W, "height": H}},
+        raw_layers,
+    )
+
     # Fallback（2026-08-31）：视觉检测 0 个独立卡片区域时，仍裁一张图 card-1.png，
     # 保证每个普通画板都有 card-* 截图（下游聚类/训练参考用）。不写入 card_regions，
     # 避免误触发下游卡片生成（spec.cards 仍空 → status 维持 skipped/generated）。
     # 仅对普通画板生效；overlay_dialog / bottom_sheet 是弹框，不应裁卡截图。
-    # 会话流画板（气泡/输入坞/键盘）同样不产兜底图：整屏截图含对话气泡与纯文本，
+    # 纯文本板（text_only）与对话流画板（气泡/输入坞/键盘）都同样不产兜底图：
+    # 整屏截图含对话气泡与纯文本，易被误读为「把整屏做成了卡片」
     # 易被误读为「把整屏做成了卡片」，且 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
+    if (not text_only and not card_regions and not overlay and not bottom_sheet
             and not conversation_flow
             and preview_path and preview_path.exists()):
         try:
@@ -1198,7 +1235,7 @@ def mark_missing_slice_elements(spec, preview_path, asset_index, asset_root=None
             element.pop("annotationDefect", None)
             element.pop("visualIdentity", None)
     spec.pop("annotationDefects", None)
-    image_width, _, _, _ = png_utils.read_png(preview_path)
+    image_width, _, _ = png_utils.read_png_size(preview_path)
     design_width = float((spec.get("size") or {}).get("width") or 375)
     scale = image_width / design_width if design_width else PREVIEW_SCALE
 
@@ -1412,6 +1449,25 @@ def copy_slices(src_assets, dst_slices, matched_rel):
         d.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(s, d)
     return list(matched_rel or [])
+
+
+def require_out_dir(target: Path, what: str) -> None:
+    """落盘前确认输出目录还在。
+
+    目录是本脚本自己建的（main 里 mkdir(parents=True, exist_ok=True)），但**解析途中**可能被
+    外部清理掉：另一次 `npm run drill` / `cardbuddy init` / `rm -rf` 撞上同一个 UI/ 就会这样。
+    此时 write_text 抛的是一句裸 FileNotFoundError: '…/spec.json'，看的人只会以为是脚本不会建
+    目录，排查方向整个跑偏（真实事故：一次 drill 把正在跑的回合连同 UI/ 一起清空了）。
+    这里显式判一次，把「是谁把目录删了」写进结论里。
+    """
+    if not target.is_dir():
+        raise SystemExit(
+            f"[FAIL] {what}的输出目录在解析途中消失了：{target}\n"
+            f"       脚本开头已建过该目录，多半是另一个进程在清理同一个 UI/ ——\n"
+            f"       比如 npm run drill / cardbuddy init / rm -rf 撞上了本次运行。\n"
+            f"       重跑本命令即可；若反复出现，先确认没有别的清理任务在同时跑。"
+        )
+
 # ---------- 画板选择（与业务无关，纯通用关键字） ----------
 PRIORITY_KEYWORDS = [
     "未登录", "无数据", "无记录", "无交易", "空", "成功", "失败", "错误",
@@ -1420,10 +1476,76 @@ PRIORITY_KEYWORDS = [
 ]
 
 
+def _split_pick_token(t, total):
+    """单个 --pick token → (板号, 卡号或 None)，越界/非数字就在这里报错。"""
+    board_part, _, card_part = t.partition(".")
+    if not board_part.isdigit():
+        raise SystemExit(f"[ERR] --pick 的画板序号必须是数字（1 起，如 8 或 8.1）：{t}")
+    board = int(board_part)
+    if board < 1 or board > total:
+        raise SystemExit(f"[ERR] --pick {t} 超范围：本导出共 {total} 个画板，序号 1..{total}")
+    if card_part and not (card_part.isdigit() and int(card_part) >= 1):
+        raise SystemExit(f"[ERR] --pick 的卡号必须是 1 起的数字（如 8.1）：{t}")
+    return board, (int(card_part) if card_part else None)
+
+
+def parse_pick(spec, total):
+    """解析 --pick：画板序号 **1 起**（与清单同口径），可带 `.卡号`（1 起），逗号分隔多个。
+
+    存在意义：清单上是 1 起的序号、--indices 是 0 起，差一位靠脑补——实测模型先用
+    --indices 8 建了错的画板（34s 白跑 + 一步 LLM），自己发现后才重跑 --indices 7。
+    用户说「8.1」时，模型只需把用户原话搬进 --pick，不换算。
+
+    也认清单行尾那种区间写法：`7~9`（连板）、`8.1~8.3`（同板连卡，一板多卡的批量建卡就靠它）。
+    清单提示与解析必须是同一套语法——提示打得出来、解析器却不认，等于让模型照抄一句必错的命令。
+
+    返回 (indices, cards)：indices 为 0 基画板索引（给 select_canvases 用，去重保序）；
+    cards 为 [(板号, 卡号)]，卡号供下游 spec_audit --card 用。
+    """
+    idxs, cards = [], []
+
+    def add_board(b):
+        if b - 1 not in idxs:
+            idxs.append(b - 1)
+
+    for token in str(spec).split(","):
+        t = token.strip()
+        if not t:
+            continue
+        if "~" not in t:
+            board, card = _split_pick_token(t, total)
+            add_board(board)
+            if card:
+                cards.append((board, card))
+            continue
+        lo, _, hi = t.partition("~")
+        b1, c1 = _split_pick_token(lo.strip(), total)
+        b2, c2 = _split_pick_token(hi.strip(), total)
+        if c1 is None and c2 is None:
+            if b2 < b1:
+                raise SystemExit(f"[ERR] --pick 区间写反了（起点应不大于终点）：{t}")
+            for b in range(b1, b2 + 1):
+                add_board(b)
+        elif b1 == b2 and c1 and c2:
+            if c2 < c1:
+                raise SystemExit(f"[ERR] --pick 卡号区间写反了（起点应不大于终点）：{t}")
+            add_board(b1)
+            for c in range(c1, c2 + 1):
+                cards.append((b1, c))
+        else:
+            raise SystemExit(
+                f"[ERR] --pick 的区间两端要同型（都带卡号或都不带，如 7~9、8.1~8.3）：{t}")
+    if not idxs:
+        raise SystemExit("[ERR] --pick 至少要给一个画板序号")
+    return idxs, cards
+
+
 def select_canvases(all_names, args):
     n = len(all_names)
     if args.list:
         return None
+    if args.pick:
+        return parse_pick(args.pick, n)[0]
     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)]
@@ -1509,6 +1631,50 @@ def detect_modal_layers(raw_layers, W=375, H=812):
     return has_scrim, has_bottom_sheet
 
 
+# 判定「这块区域不是卡片」的拒绝理由全集：纯文本 / 散文段落 / 对话气泡 / 输入坞 / 空区域。
+# 落在这组里说明区域「本来就不是卡片」，而不是「是卡片但结构弱或结构读错了」——
+# 后者（single_button_or_bar / repeated_control_bar 之类）一律不在此列：汇率牌价那种宽扁卡
+# 会被读成「按钮条」，3 宫格选项卡会被读成「控件条」，它们明明是卡，不能当纯文本滤掉。
+TEXT_ONLY_REJECT_REASONS = {
+    "text_only_or_low_structure_region",
+    "prose_paragraph_region",
+    "conversation_bubble_region",
+    "stacked_conversation_bubbles_region",
+    "conversation_inputDock_region",
+    "conversation_keyboard_region",
+    "empty_region",
+}
+
+
+def is_text_only_artboard(spec, raw_layers=None):
+    """画板级「无卡可建」判定：整屏都是文字的对话 / 问答 / 提示页一律不产卡。
+
+    这类画板（AI 应答气泡 + 输入坞、知识问答、纯文字提示）里没有任何值得落地的卡片结构，
+    留在产卡池里只会让选板清单变噪音、让下游白跑一轮——用户 2026-09-20 规则。
+
+    注意「无卡」≠「纯文本」，收口条件要卡死，否则会把「对话里嵌着一张卡」的画板一起丢掉：
+      · 弹框 / 底部抽屉同样 0 卡，但那是 alertDialog / alertCard 的形态，不在这里判；
+      · 候选区域被否的理由只要有一个不属于「本来就不是卡」（例如 single_button_or_bar，
+        那是「读起来像卡但规则没认」的窄卡）就一律保留——汇率牌价这类宽扁卡就靠这条保住；
+      · 板上有卡片级大盘切图（卡片被整体导成一张图）也保留。
+    只有「所有候选都被纯文本类理由否掉、且找不到任何卡片级结构」才判纯文本。
+    其余「0 卡但结构丰富」的画板（骨架屏、全屏状态页等）保持现状，交给下游裁决。
+    """
+    if spec.get("cards"):
+        return False
+    if spec.get("focusSkipReason") in ("overlay_dialog_geometry", "bottom_sheet_geometry"):
+        return False
+    # 卡片被设计稿整体导成一张切图时（画板里只剩那张大图），检测器看不到结构，但板上
+    # 明明有卡——这类一律保留，否则「对话 + 内嵌卡片」的状态会被当成纯文本丢掉。
+    if raw_layers:
+        size = spec.get("size") or {}
+        if vision.has_card_like_visual(vision._flatten_with_tree(raw_layers),
+                                       size.get("width") or 375, size.get("height") or 812):
+            return False
+    reasons = {r.get("reason") for r in (spec.get("rejectedCards") or [])}
+    return bool(reasons) and reasons <= TEXT_ONLY_REJECT_REASONS
+
+
 def classify_artboard(name, spec, raw_layers, H=812):
     """返回 (artboardType, interaction)。视觉信号优先，名称仅兜底（保守）。
     判定顺序：
@@ -1527,7 +1693,10 @@ def classify_artboard(name, spec, raw_layers, H=812):
         return "subcard", "alertCard 子卡（视觉信号：底部抽屉面板，由父卡 alertCard 打开）"
     if has_scrim:
         return "overlay_dialog", "alertDialog 系统弹框（视觉信号：全屏遮罩）"
-    # 2) 名称兜底：通用 UI 容器类型词（非业务实体名）
+    # 2) 画板级：纯文本（对话/问答/提示）整板无卡 → text_only，下游不得为其建卡
+    if is_text_only_artboard(spec, raw_layers):
+        return "text_only", "无卡可建（纯文本对话/问答/提示，未检出卡片区域）"
+    # 3) 名称兜底：通用 UI 容器类型词（非业务实体名）
     nm = normalize_name(name)
     if any(rx.search(nm) for rx in _SUBCARD_RE):
         return "subcard", "alertCard 子卡（名称兜底：通用容器类型词）"
@@ -1606,10 +1775,46 @@ def preview_image_for(src, base, ab, name):
     return None
 
 
-def print_board_line(i, nm, ab, src, base):
+def board_tag(verdict):
+    """清单行尾的体检标记：一眼看出这个画板能不能建卡。"""
+    if not verdict:
+        return ""
+    if verdict["kind"] == "text_only":
+        return "   [纯文本，无卡可建 · 已过滤]"
+    if verdict["kind"] == "subcard":
+        return "   [子卡 alertCard]"
+    if verdict["kind"] == "overlay_dialog":
+        return "   [弹框 alertDialog]"
+    if verdict.get("cards"):
+        return f"   [{verdict['cards']} 卡]"
+    return "   [0 卡 · 结构丰富，按整图参考建卡]"
+
+
+def board_verdict(name, ab):
+    """画板体检（纯几何，不读图）：这个画板进不进「可建卡选项池」，以及它是什么类型。
+
+    返回 {kind, cards, skip, interaction}。kind 取 classify_artboard 的口径（card /
+    subcard / overlay_dialog / text_only），所以清单上写的话与真跑产物里的 artboardType
+    永远一致——两处都走 detect_artboard_cards + classify_artboard，没有第二套判定。
+    """
+    ab = ab or {}
+    found = detect_artboard_cards(ab)
+    probe = {
+        "cards": found["cards"],
+        "rejectedCards": found["rejected"],
+        "conversationFlow": found["conversationFlow"],
+        "focusSkipReason": found["focusSkipReason"],
+        "size": {"width": found["W"], "height": found["H"]},
+    }
+    at, interaction = classify_artboard(name, probe, found["layers"], found["H"])
+    return {"kind": at, "cards": len(found["cards"]), "interaction": interaction,
+            "skip": at == "text_only"}
+
+
+def print_board_line(i, nm, ab, src, base, verdict=None):
     """门禁/清单统一行格式：序号行 + 下一行该画板自己的预览图（一一对应；缺图标缺失）。"""
     sz = f'{ab.get("width")}x{ab.get("height")}' if ab else "?"
-    print(f"  {i + 1:>2}. {nm}   ({sz})")
+    print(f"  {i + 1:>2}. {nm}   ({sz}){board_tag(verdict)}{pick_hint(i, verdict)}")
     img = preview_image_for(src, base, ab, nm)
     if img:
         print(f"      图: {img}")
@@ -1617,15 +1822,184 @@ def print_board_line(i, nm, ab, src, base):
         print("      图: （预览图缺失：preview/<slug>.png 与 UI 产物 artboard.png 均不存在）")
 
 
+def pick_hint(i, verdict):
+    """清单行尾的「照抄就能用」参数：板号 1 起、卡号 1 起，直接喂 --pick。
+
+    0 基的 --indices 与用户嘴里的「第 8 个画板第 1 张卡」差一位，实测模型会用错、
+    发现后重跑一整次构建（34s + 一步 LLM）。把可复制的 --pick 打在它自己那行上，
+    模型只需要搬字，不需要换算。
+    """
+    if verdict and verdict.get("kind") == "text_only":
+        return ""
+    cards = (verdict or {}).get("cards") or 0
+    if cards > 1:
+        return f"   --pick {i + 1}.1~{i + 1}.{cards}"
+    if cards == 1:
+        return f"   --pick {i + 1}.1"
+    return f"   --pick {i + 1}"
+
+
+def print_board_pool(names, artboards, src, base, all_label):
+    """清单分两段打：可建卡选项池（带序号 + 各自预览图）与已过滤（纯文本，无卡可建）。
+
+    过滤只针对**整屏纯文本**的画板（is_text_only_artboard）：它们放在选项池里只会让用户
+    选到没有卡可建的板子。序号保持全量 1..n 不变（回复 k → --indices k-1 仍对得上），
+    被过滤的板子只列名字、不配图，不制造「这是个选项」的错觉。
+    返回 (可建卡序号列表, 已过滤序号列表)。
+    """
+    verdicts = [board_verdict(names[i], artboards[i] if i < len(artboards) else None)
+                for i in range(len(names))]
+    pool = [i for i, v in enumerate(verdicts) if not v["skip"]]
+    filtered = [i for i, v in enumerate(verdicts) if v["skip"]]
+    for i in pool:
+        print_board_line(i, names[i], artboards[i] if i < len(artboards) else None,
+                         src, base, verdicts[i])
+    print(all_label)
+    if filtered:
+        print(f"  —— 另有 {len(filtered)} 个纯文本画板（对话/问答/提示）无卡可建，已过滤不进选项池"
+              f"（序号仍按全量 1..n 编，回复其序号也不会产卡）：")
+        for i in filtered:
+            print(f"      {i + 1}. {names[i]}")
+    return pool, filtered
+
+
+def _candidate_export_dirs(roots, max_depth=3, limit=600):
+    """在若干根目录下做**有限广度**扫描，收集「含 index.html 的目录」（Sketch MeaXure 导出根的判据）。
+
+    - 深度 3 是实测出来的：真实导出根常住在 `~/Downloads/<资料包>/<已确认的>/<稿名>/`，
+      只扫 2 层会正好漏掉它（本次自测就是这么漏的）。
+    - 命中导出根就不再往下钻（它内部还有 preview/ assets/，再钻只会灌满噪音）。
+    - 按 **realpath** 去重：`/tmp` 与 `/private/tmp` 是同一份目录的两种写法，
+      不去重会让「唯一高分候选」变成两个并列项，把下面的自动修正判据直接顶掉。
+    """
+    found, seen, seen_real = [], set(), set()
+    for root in roots:
+        root = Path(root).expanduser()
+        if not root.is_dir():
+            continue
+        stack = [(root, 0)]
+        while stack:
+            d, depth = stack.pop()
+            key = str(d)
+            if key in seen:
+                continue
+            seen.add(key)
+            # 探测整体兜住 OSError：本机 python 是 3.9，`Path.is_file()` 在无权限目录上**会抛
+            # PermissionError**（3.12 起才改成返回 False）。扫到 /private/var/root 这类目录时不兜，
+            # 整个脚本就崩在探测里——比原来「直接报错」还糟。
+            try:
+                if (d / "index.html").is_file():
+                    real = str(d.resolve())
+                    if real not in seen_real:
+                        seen_real.add(real)
+                        found.append(d)
+                    continue
+                if depth >= max_depth:
+                    continue
+                children = sorted(d.iterdir())
+            except (PermissionError, OSError):
+                continue
+            for child in children:
+                if child.name.startswith("."):
+                    continue
+                # 同上的 3.9 坑：`is_dir()` 在受保护目录（如 /private/var/db/DifferentialPrivacy）
+                # 上会抛 PermissionError，逐个子项兜
+                try:
+                    if child.is_dir():
+                        stack.append((child, depth + 1))
+                except (PermissionError, OSError):
+                    continue
+            if len(found) > limit:
+                return found
+    return found
+
+
+def _path_affinity(src, cand):
+    """候选与请求路径的「同侧程度」= 公共父级目录层数。
+
+    同一份稿常被拷到 Downloads 与 Desktop 两处（同名同分）。此时该选离调用方给的路径更近的那个，
+    而不是让两个同分候选把自动修正判据顶掉。
+    """
+    n = 0
+    for x, y in zip(src.parent.parts, cand.parent.parts):
+        if x != y:
+            break
+        n += 1
+    return n
+
+
+def _dir_mtime(d):
+    """目录最近改动时间（探测失败取 0）：没给 --src 时用它把「刚拖进来的那份稿」排前面。"""
+    try:
+        return d.stat().st_mtime
+    except (PermissionError, OSError):
+        return 0.0
+
+
+def resolve_src(raw_src, explicit=True):
+    """把 --src 解析成真实导出根：能唯一定位就自动修正，否则回一份候选清单。
+
+    实测两次白烧（2026-09-21 建卡回合各烧掉一步工具调用）：
+      ① 没带 --src ⇒ 默认 cwd（工程根）没有 index.html，直接 [ERR] 退出；
+      ② 目录名拼重复（黑马大赛-黑马大赛积分助手ui设计稿）⇒ 路径不存在，同样直接退出。
+    两次都「差一点点就对」。这里把它们变成一次自动修正，或一份可直接照抄的候选清单。
+
+    自动修正只在高置信时发生（名字高度相似且明显强于第二名），且必定打 [WARN] 说明——
+    宁可让调用方多看一眼，也不要在多稿目录里默默建错稿。
+
+    @return (src_or_None, ranked) —— ranked 为 [(相似度, Path), ...]，供失败时打印候选。
+    """
+    src = Path(raw_src).expanduser()
+    if (src / "index.html").is_file():
+        return src, []
+
+    roots = []
+    for r in (Path.cwd(), Path.cwd().parent, Path.home() / "Downloads", Path.home() / "Desktop"):
+        if r not in roots:
+            roots.append(r)
+    # 调用方给的路径本身是条线索：它的父目录最值得先扫
+    if src.parent.is_dir() and src.parent not in roots:
+        roots.insert(0, src.parent)
+
+    cands = _candidate_export_dirs(roots)
+    if not cands:
+        return None, []
+    want = src.name or ""
+    ranked = sorted(
+        ((difflib.SequenceMatcher(None, want, c.name).ratio(), _path_affinity(src, c), c) for c in cands),
+        key=lambda x: (-x[0], -x[1]),
+    )
+    # ① 没显式给 --src：全库只有一个导出根 ⇒ 就是它；否则按「最近改动」排候选
+    #    （刚拖进来的那份稿排最前，比按名字乱序有用）
+    if not explicit:
+        if len(cands) == 1:
+            return cands[0], ranked
+        recent = sorted(cands, key=_dir_mtime, reverse=True)
+        return None, [(0.0, 0, c) for c in recent]
+    best_ratio, _aff, best = ranked[0]
+    # ② 给了但拼错：名字高度相似、且明显强于**名字不同的**第二名，才敢自动修正。
+    #    同名候选（同一份稿拷到 Downloads 与 Desktop）是同一个答案、不是竞争答案，
+    #    不排除它会让「唯一定位」永远不成立。
+    rival = next((r for r, _a, c in ranked if c.name != best.name), None)
+    if best_ratio >= 0.75 and (rival is None or rival < best_ratio - 0.05):
+        return best, ranked
+    return None, ranked
+
+
 def main():
     ap = argparse.ArgumentParser(description="Sketch MeaXure 标注 → 卡片要素包（视觉驱动）")
-    ap.add_argument("--src", default=str(DEFAULT_SRC))
+    ap.add_argument("--src", default=None,
+                    help="Sketch MeaXure 导出根（含 index.html）。缺省或用错时自动探测：能唯一定位就自动修正，"
+                         "否则打印候选清单（照抄其一作为 --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("--pick", default=None,
+                    help="按清单序号选板（1 起，可带卡号：8 或 8.1，逗号分隔多个）——"
+                         "清单行尾的 --pick 值照抄即用，不必换算 0 基的 --indices")
     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,
@@ -1634,13 +2008,26 @@ def main():
                    help="按稿分片（可选）：画板落盘到 <out>/<draft>/<canvas>/，并写 <out>/<draft>/manifest.json；缺省平铺（兼容旧布局）")
     args = ap.parse_args()
 
-    src = Path(args.src).expanduser()
+    explicit_src = args.src is not None
+    raw_src = args.src or str(DEFAULT_SRC)
+    src, cands = resolve_src(raw_src, explicit=explicit_src)
     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)
+    if src is None:
+        wanted = Path(raw_src).expanduser() / "index.html"
+        if cands:
+            print(f"[ERR] {wanted} 不存在——它不是 Sketch MeaXure 导出根（导出根必须直接含 index.html）", file=sys.stderr)
+            print("[ERR] 已发现这些导出根，照抄其一作为 --src 重跑：", file=sys.stderr)
+            for _ratio, _aff, c in cands[:8]:
+                print(f"        --src {c}", file=sys.stderr)
+        else:
+            print(f"[ERR] 未找到 {wanted}，且常见位置（cwd / 上级 / ~/Downloads / ~/Desktop）也没扫到导出根。", file=sys.stderr)
+            print("[ERR] 请用 --src 指向 Sketch MeaXure 导出目录（该目录下应直接有 index.html）。", file=sys.stderr)
         sys.exit(1)
+    if src != Path(raw_src).expanduser():
+        why = "未显式指定 --src" if not explicit_src else f"--src={Path(raw_src).expanduser()} 下没有 index.html"
+        print(f"[WARN] {why}：已自动选用 {src}（含 index.html）。若不对，请显式 --src 指定。", file=sys.stderr)
 
     data = extract_data(src / "index.html")
     artboards = data.get("artboards", [])
@@ -1651,33 +2038,46 @@ def main():
     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("  全部. 全部")
+        print_board_pool(names, artboards, src, base, "  全部. 全部")
         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)
+    has_scope = bool(args.only or args.indices or args.pick 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。")
+        print("[GATE] 清单已按体检结果分段：纯文本画板（对话/问答/提示）无卡可建，已过滤出选项池。")
+        print_board_pool(names, artboards, src, base,
+                         "  全部. 全部（整份导出全量跑 UI 产物；产卡时视为显式批量授权"
+                         "——纯文本画板只出参考图，不出卡）")
+        print("[GATE] 拿到回复后重跑：**直接照抄清单行尾的 --pick**（板号 1 起、卡号 1 起，"
+              "如用户说「8.1」就 --pick 8.1；多张逗号分隔 --pick 8.1,9.2）；"
+              "等价的老写法是 --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)
+    # 显式点名纯文本画板时不拦（用户可能只想拿参考图），但必须说清楚不会出卡
+    for i in sel:
+        v = board_verdict(names[i], artboards[i] if i < len(artboards) else None)
+        if v["skip"]:
+            print(f"[WARN] {names[i]}：纯文本画板（对话/问答/提示），无卡可建——"
+                  f"本次只会产出整图参考与判定依据，不会出卡。", file=sys.stderr)
     print(f"[INFO] 本次生成 {len(sel)} 个画布：{', '.join(names[i] for i in sel)}")
+    if args.pick:
+        _, picked_cards = parse_pick(args.pick, total)
+        if picked_cards:
+            print("[PICK] 卡号提示：" + " / ".join(
+                f"画板 {b} 第 {c} 张卡 → 下游 spec_audit.mjs 用 --card {c}" for b, c in picked_cards))
+        print(f"[PICK] 等价写法 --indices {','.join(str(i) for i in sel)}（0 起）")
 
     assets_dir = src / "assets"
     asset_index = build_asset_index(assets_dir)
@@ -1763,7 +2163,9 @@ def main():
             # JSAPI 交互控件检测（密码/验证码/数字键盘/toast/二次确认）
             spec["jsapiInteractions"] = detect_jsapi_interactions(spec, ab.get("layers") or [])
             entry["artboardType"] = at
-            entry["trainingEligible"] = at == "card"
+            # 训练资格：卡片类型 + 真检出卡片区域。0 卡的画板（纯文本对话/问答/提示）没有
+            # 可训练对象，标了 true 会一路污染训练集，这里按「有没有卡」收口。
+            entry["trainingEligible"] = at == "card" and bool(spec["cards"])
 
             # 切图：逐元素建立导出映射，未命中素材的标注降级为整图采样纯色。
             slice_names = spec.pop("slices", [])
@@ -1782,10 +2184,18 @@ def main():
             # 画板是否无卡（0 卡 → 标记跳过，保留整图供参考）
             # 仅当既无独立卡片、又元素极少（<3）才视为真正空画板；
             # 元素丰富但无卡的情况可能是底部弹窗/全屏覆盖层，保留 status 供下游决策。
-            if not spec["cards"] and len(spec.get("elements", [])) < 3:
+            if at == "text_only":
+                # 整屏纯文本（对话/问答/提示）：没有任何可建卡结构，直接跳过不产卡。
+                # 选板清单里也不再作为候选出现（见 print_board_line / board_verdict）。
+                entry["status"] = "skipped"
+                spec["skippedReason"] = (
+                    "纯文本画板（对话/问答/提示）：未检出任何可建卡区域，不产卡"
+                )
+            elif not spec["cards"] and len(spec.get("elements", [])) < 3:
                 entry["status"] = "skipped"
                 spec["skippedReason"] = "视觉检测无独立卡片元素（纯对话/提示/无卡片画板）"
 
+            require_out_dir(cdir, f"画板 {name} 的要素包")
             (cdir / "spec.json").write_text(
                 json.dumps(spec, ensure_ascii=False, indent=2), encoding="utf-8")
 
@@ -1796,6 +2206,7 @@ def main():
 
         manifest["canvases"].append(entry)
 
+    require_out_dir(base, "画板清单")
     (base / "manifest.json").write_text(
         json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
     print(f"[DONE] manifest.json 已写入 {base / 'manifest.json'}")