@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-ui-align-batch/scripts/android_parse_fast.py

@@ -0,0 +1,1606 @@
+#!/usr/bin/env python3
+"""
+Android 模拟器页面遍历工具（加速版）
+功能：遍历每个页面，保存截图、View XML、Activity/Window 信息
+
+优化点（与 android_parse.py 相同的 BFS + 重启导航策略）：
+1. 轻量探测：点击后先快速 dump XML 判断是否新页面，重复页面跳过截图
+2. 并行化 ADB 调用（dumpsys、截图）
+3. 指数退避的 wait_for_idle（更短等待）
+4. 过滤低价值元素（减少无效点击）
+5. 合并 ADB 命令（减少往返）
+"""
+
+import subprocess
+import time
+import json
+import re
+import html as html_module
+import shutil
+from collections import deque
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+# ─────────────────────────────────────────────
+# 默认配置值
+# ─────────────────────────────────────────────
+ADB_PATH_DEFAULT = "adb"
+DEVICE_SERIAL_DEFAULT = "emulator-5554"
+MUMU_EMULATOR_DEFAULT = False
+MUMU_ADB_ADDR_DEFAULT = "127.0.0.1:7555"
+IDLE_POLL_INTERVAL_DEFAULT = 0.2
+IDLE_TIMEOUT_DEFAULT = 5
+MAX_PAGES_DEFAULT = 500
+MAX_SCROLLS_DEFAULT = 10
+SCROLL_DURATION_MS_DEFAULT = 300
+BACK_MAX_DEFAULT = 10
+SKIP_RESOURCE_ID_PATTERNS_DEFAULT = [
+    "statusBarBackground",
+    "navigationBarBackground",
+    "action_bar_container",
+    "status_bar",
+    "navigation_bar",
+]
+ROOT_RECOVERY_CLICKS_DEFAULT = []
+HORIZONTAL_SCROLL_CLASSES = {"android.widget.HorizontalScrollView"}
+
+
+# ─────────────────────────────────────────────
+# ADBHelper：封装所有 ADB 设备通信与交互操作
+# ─────────────────────────────────────────────
+class ADBHelper:
+
+    def __init__(
+        self,
+        adb_path=ADB_PATH_DEFAULT,
+        device_serial=DEVICE_SERIAL_DEFAULT,
+        mumu_emulator=MUMU_EMULATOR_DEFAULT,
+        mumu_adb_addr=MUMU_ADB_ADDR_DEFAULT,
+        idle_poll_interval=IDLE_POLL_INTERVAL_DEFAULT,
+        idle_timeout=IDLE_TIMEOUT_DEFAULT,
+        scroll_duration_ms=SCROLL_DURATION_MS_DEFAULT,
+    ):
+        self.adb_path = adb_path
+        self.device_serial = device_serial
+        self.mumu_emulator = mumu_emulator
+        self.mumu_adb_addr = mumu_adb_addr
+        self.idle_poll_interval = idle_poll_interval
+        self.idle_timeout = idle_timeout
+        self.scroll_duration_ms = scroll_duration_ms
+        self._pending_pulls: list[subprocess.Popen] = []
+
+    def _build_cmd(self, *args) -> list[str]:
+        cmd = [self.adb_path]
+        if self.device_serial:
+            cmd += ["-s", self.device_serial]
+        cmd += list(args)
+        return cmd
+
+    def run(self, *args, timeout=15) -> str:
+        cmd = self._build_cmd(*args)
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                timeout=timeout,
+                encoding="utf-8",
+                errors="replace",
+            )
+            return (result.stdout or "").strip()
+        except subprocess.TimeoutExpired:
+            print(f"  [WARN] adb 命令超时: {' '.join(args)}")
+            return ""
+        except FileNotFoundError:
+            raise RuntimeError(
+                f"找不到 adb，请确认已安装并配置 PATH，或修改 ADB_PATH"
+            )
+
+    def shell(self, *args, timeout=15) -> str:
+        return self.run("shell", *args, timeout=timeout)
+
+    def popen(self, *args, **kwargs) -> subprocess.Popen:
+        cmd = self._build_cmd(*args)
+        return subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            encoding="utf-8",
+            errors="replace",
+            **kwargs,
+        )
+
+    def wait_for_idle(self):
+        deadline = time.time() + self.idle_timeout
+        prev_focus = None
+        interval = self.idle_poll_interval
+
+        while time.time() < deadline:
+            time.sleep(interval)
+            interval = min(interval * 1.5, 0.5)
+
+            transition_out = self.shell("dumpsys", "window", "animator")
+            if (
+                "Transition ready" in transition_out
+                or "Running animations" in transition_out
+            ):
+                continue
+
+            focus_out = self.shell("dumpsys", "window")
+            current_focus = ""
+            for line in focus_out.splitlines():
+                if "mCurrentFocus" in line:
+                    current_focus = line.strip()
+                    break
+
+            if current_focus and current_focus == prev_focus:
+                return
+            prev_focus = current_focus
+
+        print(f"  [WARN] 等待 UI 空闲超时 ({self.idle_timeout}s)，继续执行")
+
+    def check_device(self) -> bool:
+        if self.mumu_emulator:
+            print(f" 正在连接 MuMu 模拟器 ({self.mumu_adb_addr})...")
+            connect_out = self.run("connect", self.mumu_adb_addr)
+            print(f"  adb connect: {connect_out}")
+            time.sleep(1)
+            if self.device_serial == "emulator-5554":
+                self.device_serial = self.mumu_adb_addr
+
+        out = self.run("devices")
+        lines = [l for l in out.splitlines() if l.strip() and "List of devices" not in l]
+        online = [l for l in lines if "device" in l and "offline" not in l]
+        if not online:
+            print(" 未检测到在线设备，请先启动模拟器并确认 adb devices 有输出")
+            return False
+
+        online_devices = [line.split()[0] for line in online]
+        print(f" 在线设备: {online_devices}")
+
+        if self.device_serial is None:
+            self.device_serial = online_devices[0]
+            print(f" 未指定设备，自动选择: {self.device_serial}")
+        elif self.device_serial not in online_devices:
+            print(f" 指定的设备 {self.device_serial} 不存在，自动选择: {online_devices[0]}")
+            self.device_serial = online_devices[0]
+        else:
+            print(f" 使用指定的设备: {self.device_serial}")
+
+        return True
+
+    def get_current_activity(self) -> dict:
+        info = {}
+        p_activity = self.popen("shell", "dumpsys", "activity", "activities")
+        p_window = self.popen("shell", "dumpsys", "window")
+
+        act_out, _ = p_activity.communicate(timeout=15)
+        win_out, _ = p_window.communicate(timeout=15)
+
+        act_out = (act_out or "").strip()
+        win_out = (win_out or "").strip()
+
+        for line in act_out.splitlines():
+            if re.search(r"ResumedActivity|topActivity", line, re.IGNORECASE):
+                info["resumed_activity"] = line.strip()
+                break
+
+        for line in win_out.splitlines():
+            if "mCurrentFocus" in line:
+                info["current_focus"] = line.strip()
+                break
+            if "mFocusedApp" in line:
+                info.setdefault("focused_app", line.strip())
+
+        return info
+
+    def tap(self, x: int, y: int):
+        self.shell("input", "tap", str(x), str(y))
+        self.wait_for_idle()
+
+    def long_press(self, x: int, y: int, duration_ms: int = 1000):
+        self.shell("input", "swipe", str(x), str(y), str(x), str(y), str(duration_ms))
+        self.wait_for_idle()
+
+    def tap_or_long_press(self, x: int, y: int, is_long_click: bool = False):
+        if is_long_click:
+            self.long_press(x, y)
+        else:
+            self.tap(x, y)
+
+    def press_back(self):
+        self.shell("input", "keyevent", "KEYCODE_BACK")
+        self.wait_for_idle()
+
+    def dump_xml_quick(self) -> str:
+        remote_path = "/sdcard/ui_dump.xml"
+        self.shell(
+            "rm -f /sdcard/ui_dump.xml && uiautomator dump /sdcard/ui_dump.xml",
+            timeout=20,
+        )
+        for _ in range(6):
+            check = self.shell("ls", remote_path)
+            if remote_path in check:
+                break
+            time.sleep(0.2)
+        return self.shell("cat", remote_path, timeout=15)
+
+    def get_view_xml_fast(self, page_dir: Path) -> str:
+        remote_path = "/sdcard/ui_dump.xml"
+        local_path = page_dir / "view.xml"
+
+        self.shell(
+            "rm -f /sdcard/ui_dump.xml && uiautomator dump /sdcard/ui_dump.xml",
+            timeout=20,
+        )
+        for _ in range(6):
+            check = self.shell("ls", remote_path)
+            if remote_path in check:
+                break
+            time.sleep(0.2)
+
+        xml_content = self.shell("cat", remote_path, timeout=15)
+        if xml_content:
+            local_path.write_text(xml_content, encoding="utf-8")
+        return xml_content
+
+    def screencap_bytes(self) -> bytes | None:
+        cmd = self._build_cmd("exec-out", "screencap", "-p")
+        try:
+            result = subprocess.run(cmd, capture_output=True, timeout=15)
+            if result.stdout:
+                return result.stdout
+        except subprocess.TimeoutExpired:
+            print(f"  [WARN] 截图超时")
+        return None
+
+    def take_screenshot(self, page_dir: Path):
+        local_path = page_dir / "screenshot.png"
+        data = self.screencap_bytes()
+        if data:
+            local_path.write_bytes(data)
+        else:
+            remote_path = "/sdcard/screenshot.png"
+            self.shell("screencap", "-p", remote_path)
+            time.sleep(0.3)
+            self.run("pull", remote_path, str(local_path), timeout=15)
+
+    def scroll_to_position(self, container_bounds: tuple[int, int, int, int], scroll_index: int):
+        if scroll_index <= 0:
+            return
+        x1, y1, x2, y2 = container_bounds
+        cx = (x1 + x2) // 2
+        height = y2 - y1
+        swipe_from_y = y1 + int(height * 0.7)
+        swipe_to_y = y1 + int(height * 0.3)
+
+        for i in range(scroll_index):
+            self.shell(
+                "input", "swipe",
+                str(cx), str(swipe_from_y),
+                str(cx), str(swipe_to_y),
+                str(self.scroll_duration_ms),
+            )
+            self.wait_for_idle()
+
+    def grant_runtime_permissions(self, package: str):
+        out = self.shell("dumpsys", "package", package, timeout=15)
+        permissions = []
+        in_requested = False
+        for line in out.splitlines():
+            stripped = line.strip()
+            if "runtime permissions:" in stripped.lower():
+                in_requested = True
+                continue
+            if in_requested:
+                if not stripped or (
+                    not stripped.startswith("android.permission")
+                    and not stripped.startswith("com.")
+                ):
+                    in_requested = False
+                    continue
+                perm = stripped.split(":")[0].strip()
+                if perm:
+                    permissions.append(perm)
+
+        for perm in permissions:
+            self.shell("pm", "grant", package, perm)
+
+        self.shell("appops", "set", package, "MANAGE_EXTERNAL_STORAGE", "allow")
+
+    def flush_pending_pulls(self):
+        for p in self._pending_pulls:
+            try:
+                p.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                p.kill()
+        self._pending_pulls.clear()
+
+
+# ─────────────────────────────────────────────
+# PageCrawler：UI 遍历逻辑、页面采集、断点续跑、报告生成
+# ─────────────────────────────────────────────
+class PageCrawler:
+
+    def __init__(
+        self,
+        adb: ADBHelper,
+        package: str,
+        output_dir: str,
+        max_pages=MAX_PAGES_DEFAULT,
+        max_scrolls=MAX_SCROLLS_DEFAULT,
+        skip_patterns=None,
+        root_recovery_clicks=None,
+    ):
+        self.adb = adb
+        self.package = package
+        self.output_root = Path(output_dir)
+        self.max_pages = max_pages
+        self.max_scrolls = max_scrolls
+        self.skip_patterns = skip_patterns if skip_patterns is not None else SKIP_RESOURCE_ID_PATTERNS_DEFAULT
+        self.root_recovery_clicks = root_recovery_clicks if root_recovery_clicks is not None else ROOT_RECOVERY_CLICKS_DEFAULT
+
+    # ── 纯静态辅助方法 ──
+
+    @staticmethod
+    def parse_bounds_center(bounds: str) -> tuple[int, int] | None:
+        m = re.findall(r"\d+", bounds)
+        if len(m) == 4:
+            x1, y1, x2, y2 = map(int, m)
+            return ((x1 + x2) // 2, (y1 + y2) // 2)
+        return None
+
+    @staticmethod
+    def get_clickable_elements(xml_content: str) -> list[dict]:
+        import xml.etree.ElementTree as ET
+
+        elements = []
+        if not xml_content:
+            return elements
+        try:
+            root = ET.fromstring(xml_content)
+
+            listview_child_set = set()
+            for node in root.iter("node"):
+                cls = node.get("class", "")
+                if "ListView" in cls or "GridView" in cls:
+                    for child in node:
+                        listview_child_set.add(child)
+
+            def extract_text(node):
+                text = node.get("text", "")
+                if text:
+                    return text
+                for child in node.iter("node"):
+                    t = child.get("text", "")
+                    if t:
+                        return t
+                return ""
+
+            for node in root.iter("node"):
+                if node.get("enabled") != "true":
+                    continue
+
+                is_clickable = node.get("clickable") == "true"
+                is_long_clickable = node.get("long-clickable") == "true"
+                is_listview_item = node in listview_child_set
+                is_checkable = node.get("checkable") == "true"
+
+                if not (is_clickable or is_long_clickable or is_listview_item or is_checkable):
+                    continue
+
+                bounds = node.get("bounds", "")
+                text = node.get("text", "")
+                if not text:
+                    text = extract_text(node)
+
+                base_info = {
+                    "class": node.get("class", ""),
+                    "text": text,
+                    "resource-id": node.get("resource-id", ""),
+                    "content-desc": node.get("content-desc", ""),
+                    "bounds": bounds,
+                    "center": PageCrawler.parse_bounds_center(bounds),
+                }
+
+                if is_clickable or is_listview_item or is_checkable:
+                    elements.append({**base_info, "long-clickable": False})
+                if is_long_clickable:
+                    elements.append({**base_info, "long-clickable": True})
+        except ET.ParseError as e:
+            print(f"  [WARN] XML 解析失败: {e}")
+        return elements
+
+    @staticmethod
+    def _extract_node_keys(xml_content: str) -> set[tuple]:
+        import xml.etree.ElementTree as ET
+
+        keys = set()
+        if not xml_content:
+            return keys
+        try:
+            root = ET.fromstring(xml_content)
+        except ET.ParseError:
+            return keys
+        for node in root.iter("node"):
+            keys.add((
+                node.get("class", ""),
+                node.get("resource-id", ""),
+                node.get("text", ""),
+                node.get("content-desc", ""),
+                node.get("bounds", ""),
+            ))
+        return keys
+
+    @staticmethod
+    def find_scrollable_containers(xml_content: str) -> list[dict]:
+        import xml.etree.ElementTree as ET
+
+        containers = []
+        if not xml_content:
+            return containers
+        try:
+            root = ET.fromstring(xml_content)
+        except ET.ParseError:
+            return containers
+
+        for node in root.iter("node"):
+            if node.get("scrollable") != "true":
+                continue
+            cls = node.get("class", "")
+            if cls in HORIZONTAL_SCROLL_CLASSES:
+                continue
+            bounds_str = node.get("bounds", "")
+            m = re.findall(r"\d+", bounds_str)
+            if len(m) != 4:
+                continue
+            x1, y1, x2, y2 = map(int, m)
+            if y2 - y1 < 200:
+                continue
+            containers.append({
+                "bounds": (x1, y1, x2, y2),
+                "class": cls,
+                "resource-id": node.get("resource-id", ""),
+            })
+
+        containers.sort(
+            key=lambda c: (c["bounds"][2] - c["bounds"][0]) * (c["bounds"][3] - c["bounds"][1]),
+            reverse=True,
+        )
+        return containers
+
+    @staticmethod
+    def _normalize_component(component: str) -> str:
+        if "/" not in component:
+            return component
+        pkg, cls = component.split("/", 1)
+        if cls.startswith("."):
+            cls = pkg + cls
+        return f"{pkg}/{cls}"
+
+    @staticmethod
+    def _stable_activity_key(activity_info: dict) -> str:
+        focus = activity_info.get("current_focus", "")
+        resumed = activity_info.get("resumed_activity", "")
+
+        m = re.search(r"[\w.]+/[\w.]+", focus)
+        if m:
+            return PageCrawler._normalize_component(m.group(0))
+
+        act_m = re.search(r"[\w.]+/[\w.]+", resumed)
+        act_part = PageCrawler._normalize_component(act_m.group(0)) if act_m else "unknown"
+
+        win_type_m = re.search(r"(PopupWindow|Dialog|DecorView|Toast)", focus)
+        win_type = win_type_m.group(1) if win_type_m else "overlay"
+
+        return f"{act_part}|{win_type}"
+
+    @staticmethod
+    def page_signature(activity_info: dict, xml_content: str) -> str:
+        from hashlib import md5
+
+        act_key = PageCrawler._stable_activity_key(activity_info)
+
+        if not xml_content:
+            return f"{act_key}|empty"
+
+        clickable = PageCrawler.get_clickable_elements(xml_content)
+        if not clickable:
+            return f"{act_key}|no_clickable"
+
+        elem_features = []
+        for e in clickable:
+            parts = [
+                e.get("class", ""),
+                e.get("resource-id", ""),
+                e.get("content-desc", ""),
+                e.get("bounds", ""),
+            ]
+            elem_features.append("|".join(parts))
+
+        features_str = ";".join(elem_features)
+        feature_hash = md5(features_str.encode("utf-8")).hexdigest()[:16]
+
+        return f"{act_key}|{feature_hash}"
+
+    @staticmethod
+    def _root_identified_set(activity_info: dict, xml_content: str) -> tuple:
+        resumed = activity_info.get("resumed_activity", "")
+        m = re.search(r"[\w.]+/[\w.]+", resumed)
+        act_key = PageCrawler._normalize_component(m.group(0)) if m else "unknown"
+
+        if not xml_content:
+            return act_key, set()
+
+        clickable = PageCrawler.get_clickable_elements(xml_content)
+        elems = set()
+        for e in clickable:
+            desc = e.get("content-desc", "")
+            rid = e.get("resource-id", "")
+            if not desc and not rid:
+                continue
+            elems.add((e.get("class", ""), rid, desc))
+
+        return act_key, elems
+
+    @staticmethod
+    def _is_same_root_page(root_info: tuple, current_info: tuple, threshold: float = 0.6) -> bool:
+        root_act, root_elems = root_info
+        cur_act, cur_elems = current_info
+
+        if root_act != cur_act:
+            return False
+
+        if not root_elems and not cur_elems:
+            return True
+        if not root_elems or not cur_elems:
+            return False
+
+        intersection = root_elems & cur_elems
+        union = root_elems | cur_elems
+        similarity = len(intersection) / len(union)
+        return similarity >= threshold
+
+    @staticmethod
+    def find_element_on_screen(xml_content: str, elem_id: tuple) -> dict | None:
+        if len(elem_id) >= 5:
+            rid, text, desc, bounds, is_long = elem_id[0], elem_id[1], elem_id[2], elem_id[3], elem_id[4]
+        else:
+            rid, text, desc, bounds = elem_id[0], elem_id[1], elem_id[2], elem_id[3]
+            is_long = None
+        clickable_elements = PageCrawler.get_clickable_elements(xml_content)
+
+        if bounds:
+            for e in clickable_elements:
+                if (
+                    e.get("resource-id", "") == rid
+                    and e.get("text", "") == text
+                    and e.get("content-desc", "") == desc
+                    and e.get("bounds", "") == bounds
+                    and (is_long is None or e.get("long-clickable", False) == is_long)
+                ):
+                    return e
+
+        for e in clickable_elements:
+            if (
+                e.get("resource-id", "") == rid
+                and e.get("text", "") == text
+                and e.get("content-desc", "") == desc
+                and (is_long is None or e.get("long-clickable", False) == is_long)
+            ):
+                return e
+        return None
+
+    # ── 实例方法（依赖 self 配置或 self.adb）──
+
+    def should_skip_element(self, elem: dict) -> bool:
+        rid = elem.get("resource-id", "")
+        text = elem.get("text", "")
+        desc = elem.get("content-desc", "")
+        cls = elem.get("class", "")
+
+        for pattern in self.skip_patterns:
+            if pattern in rid:
+                return True
+
+        if not text and not desc and not rid:
+            if "ImageView" in cls:
+                return True
+
+        return False
+
+    def is_in_target_app(self, activity_info: dict) -> bool:
+        focus = activity_info.get("current_focus", "")
+        resumed = activity_info.get("resumed_activity", "")
+        print(focus, resumed)
+        return self.package in focus or self.package in resumed
+
+    def scroll_and_dump(
+        self,
+        page_dir: Path,
+        container_bounds: tuple[int, int, int, int],
+        initial_xml: str = "",
+    ) -> tuple[list[str], list[Path], list[Path]]:
+        x1, y1, x2, y2 = container_bounds
+        cx = (x1 + x2) // 2
+        height = y2 - y1
+        swipe_from_y = y1 + int(height * 0.7)
+        swipe_to_y = y1 + int(height * 0.3)
+
+        xml_list = []
+        xml_paths = []
+        screenshot_paths = []
+        prev_keys = self._extract_node_keys(initial_xml) if initial_xml else None
+
+        for i in range(self.max_scrolls):
+            self.adb.shell(
+                "input", "swipe",
+                str(cx), str(swipe_from_y),
+                str(cx), str(swipe_to_y),
+                str(self.adb.scroll_duration_ms),
+            )
+            self.adb.wait_for_idle()
+
+            new_xml = self.adb.dump_xml_quick()
+            new_keys = self._extract_node_keys(new_xml)
+
+            if prev_keys is not None and new_keys == prev_keys:
+                print(f"   📜 滚动 {i+1} 次后到达底部，跳过截图")
+                break
+            prev_keys = new_keys
+
+            xml_list.append(new_xml)
+
+            xml_path = page_dir / f"view_scroll_{i + 1}.xml"
+            xml_path.write_text(new_xml, encoding="utf-8")
+            xml_paths.append(xml_path)
+
+            ss_path = page_dir / f"screenshot_scroll_{i + 1}.png"
+            data = self.adb.screencap_bytes()
+            if data:
+                ss_path.write_bytes(data)
+                screenshot_paths.append(ss_path)
+                print(f"   📸 滚动 {i+1}: XML + 截图已保存")
+
+        return xml_list, xml_paths, screenshot_paths
+
+    def capture_page(self, label: str):
+        tmp_dir = self.output_root / "_tmp_capture"
+        if tmp_dir.exists():
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+        tmp_dir.mkdir(exist_ok=True)
+
+        print(f"\n📄 [采集中] {label}")
+
+        act_info = self.adb.get_current_activity()
+        print(f"   Focus : {act_info.get('current_focus', 'N/A')}")
+        print(f"   Activity: {act_info.get('resumed_activity', 'N/A')}")
+
+        xml_content = self.adb.get_view_xml_fast(tmp_dir)
+        print(f"   View XML 已保存 ({len(xml_content)} bytes)")
+
+        self.adb.take_screenshot(tmp_dir)
+        print(f"   截图已保存")
+
+        all_screenshots = [tmp_dir / "screenshot.png"]
+        all_view_xmls = [tmp_dir / "view.xml"]
+        all_xml_contents = [xml_content]
+        scroll_containers = self.find_scrollable_containers(xml_content)
+        if scroll_containers:
+            container = scroll_containers[0]
+            print(f"   📜 检测到可滚动容器: {container['class']} {container.get('resource-id', '')}")
+            scroll_xmls, scroll_xml_paths, scroll_ss = self.scroll_and_dump(
+                tmp_dir, container["bounds"], initial_xml=xml_content,
+            )
+            if scroll_xmls:
+                all_xml_contents.extend(scroll_xmls)
+                all_view_xmls.extend(scroll_xml_paths)
+                all_screenshots.extend(scroll_ss)
+                print(f"   📜 滚动采集完成：{len(scroll_xmls)} 次滚动，共 {len(all_screenshots)} 张截图")
+
+        seen_clickable = set()
+        clickable = []
+        for idx, xc in enumerate(all_xml_contents):
+            for elem in self.get_clickable_elements(xc):
+                key = (
+                    elem.get("resource-id", ""),
+                    elem.get("text", ""),
+                    elem.get("content-desc", ""),
+                    elem.get("class", ""),
+                    elem.get("bounds", ""),
+                    elem.get("long-clickable", False),
+                )
+                if key not in seen_clickable:
+                    seen_clickable.add(key)
+                    elem["scroll_index"] = idx
+                    clickable.append(elem)
+        print(f"   可点击元素: {len(clickable)} 个")
+
+        scroll_container_bounds = None
+        if scroll_containers:
+            scroll_container_bounds = scroll_containers[0]["bounds"]
+
+        record = {
+            "page_id": None,
+            "label": label,
+            "timestamp": datetime.now().isoformat(),
+            "activity_info": act_info,
+            "clickable_count": len(clickable),
+            "clickable_elements": clickable,
+            "scroll_container_bounds": list(scroll_container_bounds) if scroll_container_bounds else None,
+            "_tmp_dir": str(tmp_dir),
+            "_screenshots": [str(p) for p in all_screenshots],
+            "_view_xmls": [str(p) for p in all_view_xmls],
+        }
+        return record, xml_content, clickable, scroll_container_bounds
+
+    def restart_to_root(
+        self,
+        launch_package: Optional[str],
+        launch_activity: Optional[str],
+        root_activity_keyword: Optional[str] = None,
+        root_identity: Optional[tuple] = None,
+    ):
+        if not launch_package or not launch_activity:
+            print("   [WARN] 包名或 Activity 名为空，无法重启")
+            return False
+
+        component = f"{launch_package}/{launch_activity}"
+
+        def _is_at_root():
+            activity_info = self.adb.get_current_activity()
+            focus = activity_info.get("current_focus", "")
+            resumed = activity_info.get("resumed_activity", "")
+            if root_activity_keyword:
+                if root_activity_keyword not in focus and root_activity_keyword not in resumed:
+                    return False
+            if root_identity:
+                xml = self.adb.dump_xml_quick()
+                cur_identity = self._root_identified_set(activity_info, xml)
+                if not self._is_same_root_page(root_identity, cur_identity):
+                    cur_act, cur_elems = cur_identity
+                    root_act, root_elems = root_identity
+                    intersection = root_elems & cur_elems
+                    union = root_elems | cur_elems
+                    sim = len(intersection) / len(union) if union else 0
+                    print(f"   [DEBUG] 根页面相似度: {sim:.2f} (交集{len(intersection)}/并集{len(union)})")
+                    return False
+            return True
+
+        def _try_recovery_clicks():
+            if not self.root_recovery_clicks:
+                return False
+            print(f"   [INFO] 尝试通过点击路径恢复到根页面...")
+            for step in self.root_recovery_clicks:
+                xml = self.adb.dump_xml_quick()
+                clickable = self.get_clickable_elements(xml)
+                found = None
+                for e in clickable:
+                    if step.get("content-desc") and e.get("content-desc") == step["content-desc"]:
+                        found = e
+                        break
+                    if step.get("text") and e.get("text") == step["text"]:
+                        found = e
+                        break
+                    if step.get("resource-id") and e.get("resource-id") == step["resource-id"]:
+                        found = e
+                        break
+                if found and found.get("center"):
+                    print(f"   [INFO] 点击: {step.get('content-desc') or step.get('text') or step.get('resource-id')}")
+                    self.adb.tap(found["center"][0], found["center"][1])
+                elif step.get("center"):
+                    print(f"   [INFO] 使用固定坐标点击: {step['center']}")
+                    self.adb.tap(step["center"][0], step["center"][1])
+                else:
+                    print(f"   [WARN] 恢复路径中未找到元素: {step}")
+                    return False
+            return _is_at_root()
+
+        self.adb.shell("am", "force-stop", launch_package)
+        time.sleep(1.0)
+        self.adb.shell(
+            "am",
+            "start",
+            "-n",
+            component,
+            "--activity-clear-task",
+            "--activity-clear-top",
+        )
+        self.adb.wait_for_idle()
+
+        for _retry in range(4):
+            if _is_at_root():
+                return True
+            print(f"   [INFO] 等待页面加载完成... (重试 {_retry + 1}/4)")
+            time.sleep(2)
+
+        print(f"   [WARN] force-stop 后未到达根页面（App 恢复了上次的 Tab 状态）")
+        if _try_recovery_clicks():
+            return True
+
+        print(f"   [INFO] 尝试 back + 点击路径恢复...")
+        self.adb.press_back()
+        if _is_at_root():
+            return True
+        if _try_recovery_clicks():
+            return True
+
+        print(f"   [WARN] 所有恢复方式均失败，跳过此次导航")
+        return False
+
+    def navigate_via_restart(
+        self,
+        click_path: list,
+        launch_package: Optional[str],
+        launch_activity: Optional[str],
+        root_activity_keyword: Optional[str] = None,
+        step_signatures: Optional[list] = None,
+        root_identity: Optional[tuple] = None,
+    ) -> bool:
+        if not launch_package or not launch_activity:
+            print("   [WARN] 包名或 Activity 名为空，无法导航")
+            return False
+
+        if not click_path:
+            return True
+
+        if not self.restart_to_root(launch_package, launch_activity, root_activity_keyword, root_identity):
+            print("   [ERR] 无法回到根页面，导航失败")
+            return False
+
+        for i, step in enumerate(click_path):
+            xml = self.adb.dump_xml_quick()
+
+            step_scroll = step.get("scroll_info")
+            if step_scroll and step_scroll.get("scroll_index", 0) > 0:
+                self.adb.scroll_to_position(
+                    tuple(step_scroll["container_bounds"]),
+                    step_scroll["scroll_index"],
+                )
+                xml = self.adb.dump_xml_quick()
+
+            elem_id = (
+                step.get("resource-id", ""),
+                step.get("text", ""),
+                step.get("content-desc", ""),
+                "",
+            )
+            found = self.find_element_on_screen(xml, elem_id)
+            is_long = step.get("long-clickable", False)
+            if found and found.get("center"):
+                self.adb.tap_or_long_press(found["center"][0], found["center"][1], is_long)
+            elif step.get("center"):
+                print(
+                    f"   [WARN] 未找到元素 {step.get('element', '?')}，使用记录坐标"
+                )
+                self.adb.tap_or_long_press(step["center"][0], step["center"][1], is_long)
+            else:
+                print(f"   [ERR] 无法导航到步骤: {step.get('element', '?')}")
+                return False
+
+            if step_signatures and i < len(step_signatures) and step_signatures[i]:
+                verify_xml = self.adb.dump_xml_quick()
+                verify_info = self.adb.get_current_activity()
+                actual_sig = self.page_signature(verify_info, verify_xml)
+                if actual_sig != step_signatures[i]:
+                    expected_act = step_signatures[i].split("|")[0]
+                    actual_act = actual_sig.split("|")[0]
+                    if expected_act != actual_act:
+                        print(
+                            f"   [WARN] 导航步骤 {i+1} 后 Activity 不匹配 "
+                            f"(期望={expected_act}, "
+                            f"实际={actual_act})"
+                        )
+                        return False
+        return True
+
+    # ── 断点续跑 ──
+
+    def _save_queue(self, queue: deque):
+        items = []
+        for click_path, elem_id, step_sigs, scroll_info in queue:
+            items.append([click_path, list(elem_id), step_sigs, scroll_info])
+        try:
+            (self.output_root / "queue_checkpoint.json").write_text(
+                json.dumps(items, ensure_ascii=False),
+                encoding="utf-8",
+            )
+        except Exception as e:
+            print(f"  [WARN] 保存队列检查点失败: {e}")
+
+    def _load_queue(self) -> "deque | None":
+        qfile = self.output_root / "queue_checkpoint.json"
+        if not qfile.exists():
+            return None
+        try:
+            items = json.loads(qfile.read_text(encoding="utf-8"))
+            q: deque = deque()
+            for click_path, elem_id_list, step_sigs, scroll_info in items:
+                q.append((click_path, tuple(elem_id_list), step_sigs, scroll_info))
+            return q
+        except Exception as e:
+            print(f"  [WARN] 加载队列检查点失败: {e}，将重建队列")
+            return None
+
+    def _rebuild_queue_from_pages(self, pages_index: list) -> deque:
+        queue: deque = deque()
+        for page in pages_index:
+            click_path = page.get("click_path", [])
+            clickable = page.get("clickable_elements", [])
+            scroll_container_bounds = page.get("scroll_container_bounds")
+            for elem in clickable:
+                if self.should_skip_element(elem):
+                    continue
+                elem_id = (
+                    elem.get("resource-id", ""),
+                    elem.get("text", ""),
+                    elem.get("content-desc", ""),
+                    elem.get("bounds", ""),
+                    elem.get("long-clickable", False),
+                )
+                si = elem.get("scroll_index", 0)
+                scroll_info = None
+                if si > 0 and scroll_container_bounds:
+                    scroll_info = {
+                        "scroll_index": si,
+                        "container_bounds": list(scroll_container_bounds),
+                    }
+                queue.append((click_path, elem_id, [], scroll_info))
+        return queue
+
+    def _try_load_checkpoint(self):
+        index_file = self.output_root / "index.json"
+        if not index_file.exists():
+            return None
+
+        page_dirs = list(self.output_root.glob("page_*"))
+        if not page_dirs:
+            return None
+
+        try:
+            pages_index = json.loads(index_file.read_text(encoding="utf-8"))
+        except Exception as e:
+            print(f"  [WARN] 读取 index.json 失败: {e}，重新开始")
+            return None
+
+        if not pages_index:
+            return None
+
+        print(f"\n⏩ 发现已有检查点：{len(pages_index)} 个页面，尝试断点续跑...")
+
+        visited_signatures = set()
+        page_counter = 0
+
+        for page in pages_index:
+            page_id = page.get("page_id", "")
+            if not page_id:
+                continue
+
+            m = re.match(r"page_(\d+)", page_id)
+            if m:
+                page_counter = max(page_counter, int(m.group(1)))
+
+            view_xml_path = self.output_root / page_id / "view.xml"
+            if view_xml_path.exists():
+                xml_content = view_xml_path.read_text(encoding="utf-8", errors="replace")
+                sig = self.page_signature(page.get("activity_info", {}), xml_content)
+                visited_signatures.add(sig)
+
+        saved_queue = self._load_queue()
+        if saved_queue is not None:
+            queue = saved_queue
+            print(f"   队列已从检查点恢复：{len(queue)} 个待处理元素（精确续跑）")
+        else:
+            queue = self._rebuild_queue_from_pages(pages_index)
+            print(f"   队列已重建（fallback）：{len(queue)} 个元素（含已探索项，BFS 会自动跳过）")
+
+        blocked_elements: set = set()
+        print(f"   已恢复 {len(visited_signatures)} 个已访问签名，队列 {len(queue)} 个待处理元素")
+        return pages_index, visited_signatures, page_counter, queue, blocked_elements
+
+    # ── 页面提交 ──
+
+    def _commit_page(self, record: dict) -> str:
+        self.page_counter += 1
+
+        activity_name = ""
+        resumed = record.get("activity_info", {}).get("resumed_activity", "")
+        m_act = re.search(r"[\w.]+/([\w.]+)", resumed)
+        if not m_act:
+            f = record.get("activity_info", {}).get("current_focus", "")
+            m_act = re.search(r"[\w.]+/([\w.]+)", f)
+        if m_act:
+            activity_name = m_act.group(1).split(".")[-1]
+        suffix = f"_{activity_name}" if activity_name else ""
+        page_id = f"page_{self.page_counter:04d}{suffix}"
+        page_dir = self.output_root / page_id
+
+        tmp_dir = Path(record["_tmp_dir"])
+        if tmp_dir.exists():
+            tmp_dir.rename(page_dir)
+        else:
+            page_dir.mkdir(exist_ok=True)
+
+        record["page_id"] = page_id
+        record["screenshot"] = f"{page_id}/screenshot.png"
+        record["view_xml"] = f"{page_id}/view.xml"
+
+        screenshots_list = [f"{page_id}/screenshot.png"]
+        tmp_screenshots = record.pop("_screenshots", [])
+        for ss_path_str in tmp_screenshots:
+            ss_name = Path(ss_path_str).name
+            if ss_name != "screenshot.png":
+                screenshots_list.append(f"{page_id}/{ss_name}")
+        record["screenshots"] = screenshots_list
+
+        view_xmls_list = [f"{page_id}/view.xml"]
+        tmp_view_xmls = record.pop("_view_xmls", [])
+        for xml_path_str in tmp_view_xmls:
+            xml_name = Path(xml_path_str).name
+            if xml_name != "view.xml":
+                view_xmls_list.append(f"{page_id}/{xml_name}")
+        record["view_xmls"] = view_xmls_list
+
+        del record["_tmp_dir"]
+
+        (page_dir / "meta.json").write_text(
+            json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        print(f"   ✅ 已保存为 [{page_id}]")
+        return page_id
+
+    def _commit_manual_page(self, record: dict, page_counter: int) -> str:
+        activity_name = ""
+        resumed = record.get("activity_info", {}).get("resumed_activity", "")
+        m_act = re.search(r"[\w.]+/([\w.]+)", resumed)
+        if not m_act:
+            f = record.get("activity_info", {}).get("current_focus", "")
+            m_act = re.search(r"[\w.]+/([\w.]+)", f)
+        if m_act:
+            activity_name = m_act.group(1).split(".")[-1]
+        suffix = f"_{activity_name}" if activity_name else ""
+        page_id = f"manual_{page_counter:04d}{suffix}"
+        page_dir = self.output_root / page_id
+
+        tmp_dir = Path(record["_tmp_dir"])
+        if tmp_dir.exists():
+            tmp_dir.rename(page_dir)
+        else:
+            page_dir.mkdir(exist_ok=True)
+
+        record["page_id"] = page_id
+        record["screenshot"] = f"{page_id}/screenshot.png"
+        record["view_xml"] = f"{page_id}/view.xml"
+
+        screenshots_list = [f"{page_id}/screenshot.png"]
+        tmp_screenshots = record.pop("_screenshots", [])
+        for ss_path_str in tmp_screenshots:
+            ss_name = Path(ss_path_str).name
+            if ss_name != "screenshot.png":
+                screenshots_list.append(f"{page_id}/{ss_name}")
+        record["screenshots"] = screenshots_list
+
+        view_xmls_list = [f"{page_id}/view.xml"]
+        tmp_view_xmls = record.pop("_view_xmls", [])
+        for xml_path_str in tmp_view_xmls:
+            xml_name = Path(xml_path_str).name
+            if xml_name != "view.xml":
+                view_xmls_list.append(f"{page_id}/{xml_name}")
+        record["view_xmls"] = view_xmls_list
+
+        del record["_tmp_dir"]
+
+        (page_dir / "meta.json").write_text(
+            json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        print(f"   ✅ 已保存为 [{page_id}]")
+        return page_id
+
+    # ── HTML 报告生成 ──
+
+    def generate_html_report(self, pages: list[dict]):
+        cards = ""
+        for p in pages:
+            activity = html_module.escape(
+                p["activity_info"].get("current_focus", "N/A")
+            )
+            resumed = html_module.escape(
+                p["activity_info"].get("resumed_activity", "N/A")
+            )
+            click_path = p.get("click_path", [])
+            if click_path == "manual":
+                desc = html_module.escape(p.get("description", "手动采集"))
+                path_display = f"（手动采集：{desc}）"
+            elif click_path:
+                long_click_tag = '<b class="long-click">长按</b>'
+                path_display = " → ".join(
+                    [
+                        "<code>{}</code> {} <b>{}</b>".format(
+                            html_module.escape(s['from']),
+                            long_click_tag if s.get('long-clickable') else '点击',
+                            html_module.escape(s['element']),
+                        )
+                        for s in click_path
+                    ]
+                )
+            else:
+                path_display = "（初始页）"
+            screenshot_path = html_module.escape(p["screenshot"])
+            screenshots = p.get("screenshots", [screenshot_path])
+            view_xmls = p.get("view_xmls", [p["view_xml"]])
+            if len(screenshots) > 1:
+                pairs_html = ""
+                for idx, ss in enumerate(screenshots):
+                    xml_link = view_xmls[idx] if idx < len(view_xmls) else view_xmls[-1]
+                    label_tag = "初始" if idx == 0 else f"滚动{idx}"
+                    pairs_html += (
+                        f'<div class="scroll-pair">'
+                        f'<img src="{html_module.escape(ss)}" alt="screenshot" onerror="this.style.display=\'none\'"/>'
+                        f'<a href="{html_module.escape(xml_link)}" target="_blank">{label_tag} XML</a>'
+                        f'</div>'
+                    )
+                screenshots_html = f'<div class="screenshots-gallery">{pairs_html}</div>'
+            else:
+                screenshots_html = f'<img src="{html_module.escape(screenshots[0])}" alt="screenshot" onerror="this.style.display=\'none\'"/>'
+            label_escaped = html_module.escape(p["label"])
+            page_id_escaped = html_module.escape(p["page_id"])
+            view_xml_escaped = html_module.escape(p["view_xml"])
+            if len(view_xmls) > 1:
+                xml_links_html = " ".join(
+                    f'<a href="{html_module.escape(vx)}" target="_blank">📄 XML{"" if i == 0 else f"_{i}"}</a>'
+                    for i, vx in enumerate(view_xmls)
+                )
+            else:
+                xml_links_html = f'<a href="{view_xml_escaped}" target="_blank">📄 查看 View XML</a>'
+            cards += f"""
+            <div class="card">
+              <div class="card-header">
+                <span class="pid">{page_id_escaped}</span>
+                <span class="label">{label_escaped}</span>
+                <span class="time">{html_module.escape(p["timestamp"][:19])}</span>
+              </div>
+              <div class="card-body">
+                {screenshots_html}
+                <div class="meta">
+                  <div><b>Focus:</b> <code>{activity}</code></div>
+                  <div><b>Activity:</b> <code>{resumed}</code></div>
+                  <div><b>点击路径:</b> {path_display}</div>
+                  <div><b>可点击元素:</b> {p["clickable_count"]} 个</div>
+                  <div class="links">
+                    {xml_links_html}
+                    <a href="{page_id_escaped}/meta.json" target="_blank">🗂 元数据 JSON</a>
+                  </div>
+                </div>
+              </div>
+            </div>"""
+
+        html = f"""<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<title>Android 页面遍历报告（加速版）</title>
+<style>
+  body {{ font-family: -apple-system, sans-serif; background: #f5f5f5; margin: 0; padding: 20px; }}
+  h1 {{ color: #333; }}
+  .summary {{ background: #fff; border-radius: 8px; padding: 16px; margin-bottom: 20px; box-shadow: 0 1px 4px rgba(0,0,0,.1); }}
+  .grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(420px, 1fr)); gap: 16px; }}
+  .card {{ background: #fff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 4px rgba(0,0,0,.1); }}
+  .card-header {{ background: #1a73e8; color: #fff; padding: 10px 14px; display: flex; gap: 10px; align-items: center; }}
+  .pid {{ font-weight: bold; font-size: 13px; background: rgba(255,255,255,.2); padding: 2px 8px; border-radius: 4px; }}
+  .label {{ flex: 1; font-size: 14px; }}
+  .time {{ font-size: 11px; opacity: .8; }}
+  .card-body {{ display: flex; gap: 12px; padding: 12px; }}
+  .card-body img {{ width: 140px; height: auto; border-radius: 4px; border: 1px solid #eee; object-fit: cover; flex-shrink: 0; }}
+  .screenshots-gallery {{ display: flex; gap: 6px; overflow-x: auto; flex-shrink: 0; max-width: 320px; padding-bottom: 4px; }}
+  .screenshots-gallery img {{ width: 120px; height: auto; border-radius: 4px; border: 1px solid #eee; object-fit: cover; flex-shrink: 0; }}
+  .scroll-pair {{ display: flex; flex-direction: column; align-items: center; gap: 2px; flex-shrink: 0; }}
+  .scroll-pair a {{ font-size: 10px; color: #1a73e8; text-decoration: none; }}
+  .scroll-pair a:hover {{ text-decoration: underline; }}
+  .meta {{ font-size: 12px; color: #444; display: flex; flex-direction: column; gap: 6px; overflow: hidden; }}
+  .meta code {{ font-size: 11px; background: #f0f0f0; padding: 1px 4px; border-radius: 3px; word-break: break-all; }}
+  .links {{ display: flex; gap: 10px; margin-top: 4px; }}
+  .links a {{ color: #1a73e8; text-decoration: none; font-size: 12px; }}
+  .links a:hover {{ text-decoration: underline; }}
+  .long-click {{ color: #e65100; background: #fff3e0; padding: 1px 5px; border-radius: 3px; font-size: 11px; }}
+</style>
+</head>
+<body>
+<h1>📱 Android 页面遍历报告（加速版）</h1>
+<div class="summary">
+  <b>生成时间：</b>{datetime.now().strftime("%Y-%m-%d %H:%M:%S")} &nbsp;|&nbsp;
+  <b>共采集页面：</b>{len(pages)} 个
+</div>
+<div class="grid">
+{cards}
+</div>
+</body>
+</html>"""
+
+        (self.output_root / "report.html").write_text(html, encoding="utf-8")
+
+    # ── 主遍历逻辑（BFS + 重启导航 + 轻量探测）──
+
+    def _flush_report(self):
+        try:
+            (self.output_root / "index.json").write_text(
+                json.dumps(self.pages_index, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+            self.generate_html_report(self.pages_index)
+            self._save_queue(self.queue)
+        except Exception as e:
+            print(f"  [WARN] 写入报告失败: {e}")
+
+    def crawl(self):
+        if not self.adb.check_device():
+            return
+
+        activity_info = self.adb.get_current_activity()
+        if not self.is_in_target_app(activity_info):
+            print(f"当前不在目标 App ({self.package}) 内，清空数据并启动...")
+            self.adb.shell("am", "force-stop", self.package)
+            time.sleep(0.5)
+            self.adb.shell(
+                "monkey",
+                "-p",
+                self.package,
+                "-c",
+                "android.intent.category.LAUNCHER",
+                "1",
+            )
+            self.adb.wait_for_idle()
+            activity_info = self.adb.get_current_activity()
+            if not self.is_in_target_app(activity_info):
+                print(
+                    f"[ERR] 启动后仍未进入目标 App ({self.package})，请检查包名是否正确"
+                )
+                return
+
+        launch_package = None
+        launch_activity = None
+        focus = activity_info.get("current_focus", "")
+        m = re.search(r"([\w.]+)/([\w.]+)", focus)
+        if m:
+            launch_package = m.group(1)
+            launch_activity = m.group(2)
+            print(f"启动 Activity: {launch_package}/{launch_activity}")
+        else:
+            print(f"[WARN] 无法从 current_focus 提取启动 Activity: {focus}")
+
+        root_activity_keyword = None
+        if launch_activity:
+            root_activity_keyword = launch_activity.split(".")[-1]
+            print(f"根 Activity 关键字: {root_activity_keyword}")
+
+        self.output_root.mkdir(exist_ok=True)
+
+        self.pages_index = []
+        self.visited_signatures = set()
+        self.path_signatures = {}
+        self.blocked_elements = set()
+        self.queue = deque()
+        self.page_counter = 0
+        self.stats = {
+            "skipped_elements": 0,
+            "probe_skipped": 0,
+        }
+
+        print(f"\n📂 输出目录: {self.output_root.resolve()}\n")
+        print("=" * 60)
+        print("开始遍历（加速版：BFS + 轻量探测）...")
+        print("=" * 60)
+
+        root_identity = None
+        checkpoint = self._try_load_checkpoint()
+        if checkpoint:
+            self.pages_index, self.visited_signatures, self.page_counter, self.queue, self.blocked_elements = checkpoint
+            print(f"⏩ 断点续跑：从第 {self.page_counter + 1} 个页面继续\n")
+            for p in self.pages_index:
+                if not p.get("click_path"):
+                    root_xml_path = self.output_root / p["page_id"] / "view.xml"
+                    if root_xml_path.exists():
+                        root_xml = root_xml_path.read_text(encoding="utf-8", errors="replace")
+                        root_identity = self._root_identified_set(p.get("activity_info", {}), root_xml)
+                    break
+        else:
+            record, xml_content, clickable, init_scroll_bounds = self.capture_page("初始页面")
+            page_id = self._commit_page(record)
+            record["click_path"] = []
+            (self.output_root / page_id / "meta.json").write_text(
+                json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+            sig = self.page_signature(record["activity_info"], xml_content)
+            root_identity = self._root_identified_set(record["activity_info"], xml_content)
+            self.visited_signatures.add(sig)
+            self.path_signatures[json.dumps([])] = sig
+            self.pages_index.append(record)
+            self._flush_report()
+
+            for elem in clickable:
+                if self.should_skip_element(elem):
+                    self.stats["skipped_elements"] += 1
+                    continue
+                elem_id = (
+                    elem.get("resource-id", ""),
+                    elem.get("text", ""),
+                    elem.get("content-desc", ""),
+                    elem.get("bounds", ""),
+                    elem.get("long-clickable", False),
+                )
+                si = elem.get("scroll_index", 0)
+                scroll_info = None
+                if si > 0 and init_scroll_bounds:
+                    scroll_info = {"scroll_index": si, "container_bounds": list(init_scroll_bounds)}
+                self.queue.append(([], elem_id, [], scroll_info))
+
+        failed_paths = set()
+        while self.queue and self.page_counter < self.max_pages:
+            click_path, elem_id, step_signatures, scroll_info = self.queue.popleft()
+
+            if elem_id in self.blocked_elements:
+                continue
+
+            path_key = json.dumps(click_path, ensure_ascii=False) if click_path else ""
+            if any(path_key.startswith(fp) and len(fp) > 2 for fp in failed_paths):
+                continue
+
+            path_desc = (
+                " → ".join([s.get("element", "?") for s in click_path])
+                if click_path
+                else "根页面"
+            )
+            print(f"\n🧭 导航到: {path_desc}")
+
+            if not launch_package or not launch_activity:
+                print(f"   [ERR] 无法重启 App，缺少启动信息")
+                continue
+
+            if click_path:
+                if not self.navigate_via_restart(
+                    click_path,
+                    launch_package,
+                    launch_activity,
+                    root_activity_keyword,
+                    step_signatures,
+                    root_identity,
+                ):
+                    print(f"   [ERR] 导航失败，跳过")
+                    failed_paths.add(path_key)
+                    continue
+            else:
+                if not self.restart_to_root(
+                    launch_package, launch_activity, root_activity_keyword, root_identity
+                ):
+                    print(f"   [ERR] 无法回到根页面，跳过")
+                    continue
+
+            fresh_xml = self.adb.dump_xml_quick()
+
+            if scroll_info and scroll_info["scroll_index"] > 0:
+                print(f"   📜 滚动 {scroll_info['scroll_index']} 次到达元素位置")
+                self.adb.scroll_to_position(tuple(scroll_info["container_bounds"]), scroll_info["scroll_index"])
+                fresh_xml = self.adb.dump_xml_quick()
+
+            found_elem = self.find_element_on_screen(fresh_xml, elem_id)
+
+            if not found_elem or not found_elem.get("center"):
+                print(f"   [SKIP] 无法找到元素: {elem_id[:3]}")
+                continue
+
+            center = found_elem["center"]
+            label_text = (
+                found_elem.get("text")
+                or found_elem.get("content-desc")
+                or found_elem.get("resource-id")
+                or "unknown"
+            )
+
+            print(f"\n👆 点击: [{label_text}] @ {center}")
+            is_long = found_elem.get("long-clickable", False)
+            if is_long:
+                print(f"   🔁 使用长按触发")
+            self.adb.tap_or_long_press(center[0], center[1], is_long)
+
+            probe_xml = self.adb.dump_xml_quick()
+            probe_info = self.adb.get_current_activity()
+            new_sig = self.page_signature(probe_info, probe_xml)
+
+            if not self.is_in_target_app(probe_info):
+                print(f"   ⚠️  跳转到其他 App，标记并跳过")
+                self.blocked_elements.add(elem_id)
+                continue
+
+            if new_sig in self.visited_signatures:
+                print(f"   ♻️  页面已访问过，跳过（省截图）")
+                self.stats["probe_skipped"] += 1
+                continue
+
+            new_record, new_xml, new_clickable, new_scroll_bounds = self.capture_page(f"点击'{label_text}'后")
+            new_sig = self.page_signature(new_record["activity_info"], new_xml)
+            self.visited_signatures.add(new_sig)
+            page_id = self._commit_page(new_record)
+
+            new_click_path = click_path + [
+                {
+                    "from": path_desc,
+                    "element": label_text,
+                    "center": list(center),
+                    "resource-id": found_elem.get("resource-id", ""),
+                    "text": found_elem.get("text", ""),
+                    "content-desc": found_elem.get("content-desc", ""),
+                    "long-clickable": is_long,
+                    "scroll_info": scroll_info,
+                }
+            ]
+            new_record["came_from"] = path_desc
+            new_record["trigger_element"] = label_text
+            new_record["click_path"] = new_click_path
+            (self.output_root / page_id / "meta.json").write_text(
+                json.dumps(new_record, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+            self.pages_index.append(new_record)
+            self._flush_report()
+
+            self.path_signatures[json.dumps(new_click_path)] = new_sig
+            new_step_sigs = step_signatures + [new_sig]
+
+            for ne in new_clickable:
+                if self.should_skip_element(ne):
+                    self.stats["skipped_elements"] += 1
+                    continue
+                new_eid = (
+                    ne.get("resource-id", ""),
+                    ne.get("text", ""),
+                    ne.get("content-desc", ""),
+                    ne.get("bounds", ""),
+                    ne.get("long-clickable", False),
+                )
+                si = ne.get("scroll_index", 0)
+                ne_scroll_info = None
+                if si > 0 and new_scroll_bounds:
+                    ne_scroll_info = {"scroll_index": si, "container_bounds": list(new_scroll_bounds)}
+                self.queue.append((new_click_path, new_eid, new_step_sigs, ne_scroll_info))
+
+        self.adb.flush_pending_pulls()
+        self._flush_report()
+
+        try:
+            (self.output_root / "queue_checkpoint.json").unlink(missing_ok=True)
+        except Exception:
+            pass
+
+        print("\n" + "=" * 60)
+        print(f"✅ 遍历完成！共采集 {len(self.pages_index)} 个页面")
+        print(f"📂 输出目录: {self.output_root.resolve()}")
+        print(f"📋 索引文件: {self.output_root / 'index.json'}")
+        print(f"🌐 HTML报告: {self.output_root / 'report.html'}")
+        print(f"\n📊 加速统计:")
+        print(f"   过滤低价值元素: {self.stats['skipped_elements']} 个")
+        print(f"   轻量探测跳过（省截图）: {self.stats['probe_skipped']} 次")
+        print("=" * 60)
+
+    # ── 手动采集模式 ──
+
+    def manual_crawl(self):
+        if not self.adb.check_device():
+            return
+
+        self.output_root.mkdir(exist_ok=True)
+
+        pages_index = []
+        index_file = self.output_root / "index.json"
+        if index_file.exists():
+            try:
+                pages_index = json.loads(index_file.read_text(encoding="utf-8"))
+                print(f"📂 已加载 {len(pages_index)} 个已有页面")
+            except Exception as e:
+                print(f"[WARN] 读取 index.json 失败: {e}，将创建新索引")
+
+        manual_counter = 0
+        for p in pages_index:
+            pid = p.get("page_id", "")
+            m = re.match(r"manual_(\d+)", pid)
+            if m:
+                manual_counter = max(manual_counter, int(m.group(1)))
+
+        print(f"\n📂 输出目录: {self.output_root.resolve()}")
+        print(f"📝 手动采集模式已启动（manual 编号从 {manual_counter + 1} 开始）")
+        print("=" * 60)
+        print("操作说明：")
+        print("  1. 在设备上手动导航到目标页面")
+        print('  2. 输入页面描述（如"设置页 > 关于"），然后按回车开始采集')
+        print("  3. 输入 q 退出")
+        print("=" * 60)
+
+        while True:
+            print()
+            desc = input("📝 输入页面描述（q 退出）: ").strip()
+            if desc.lower() == "q":
+                print("👋 退出手动采集模式")
+                break
+            if not desc:
+                desc = "手动采集"
+
+            manual_counter += 1
+            record, xml_content, clickable, scroll_bounds = self.capture_page(desc)
+
+            record["click_path"] = "manual"
+            record["description"] = desc
+            self._commit_manual_page(record, manual_counter)
+
+            pages_index.append(record)
+
+            (self.output_root / "index.json").write_text(
+                json.dumps(pages_index, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+            self.generate_html_report(pages_index)
+            print(f"   📋 index.json 和 report.html 已更新（共 {len(pages_index)} 个页面）")
+
+        print(f"\n✅ 手动采集完成！共 {len(pages_index)} 个页面（含自动遍历）")
+        print(f"📂 输出目录: {self.output_root.resolve()}")
+
+
+# ─────────────────────────────────────────────
+# 入口
+# ─────────────────────────────────────────────
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Android 模拟器页面遍历工具")
+    parser.add_argument(
+        "--package", "-p",
+        required=True,
+        help="目标 App 包名（必选）",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        required=True,
+        help="输出目录（必选）",
+    )
+    parser.add_argument(
+        "--manual", action="store_true",
+        help="手动采集模式：手动导航到页面后按回车触发采集",
+    )
+    parser.add_argument(
+        "--device",
+        default=DEVICE_SERIAL_DEFAULT,
+        help=f"ADB 设备 serial（默认: {DEVICE_SERIAL_DEFAULT}）",
+    )
+    parser.add_argument(
+        "--adb-path",
+        default=ADB_PATH_DEFAULT,
+        help=f"adb 可执行文件路径（默认: {ADB_PATH_DEFAULT}）",
+    )
+    parser.add_argument(
+        "--max-pages",
+        type=int,
+        default=MAX_PAGES_DEFAULT,
+        help=f"最多遍历页面数（默认: {MAX_PAGES_DEFAULT}）",
+    )
+    parser.add_argument(
+        "--max-scrolls",
+        type=int,
+        default=MAX_SCROLLS_DEFAULT,
+        help=f"每个可滚动容器最多滚动次数（默认: {MAX_SCROLLS_DEFAULT}）",
+    )
+    args = parser.parse_args()
+
+    adb = ADBHelper(
+        adb_path=args.adb_path,
+        device_serial=args.device,
+    )
+    crawler = PageCrawler(
+        adb=adb,
+        package=args.package,
+        output_dir=args.output,
+        max_pages=args.max_pages,
+        max_scrolls=args.max_scrolls,
+    )
+
+    if args.manual:
+        crawler.manual_crawl()
+    else:
+        crawler.crawl()