android2harmony 0.1.0

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

@@ -0,0 +1,1750 @@
+#!/usr/bin/env node
+/**
+ * Android 模拟器页面遍历工具（加速版, TypeScript 版）
+ * 功能：BFS 遍历每个页面，保存截图、View XML、Activity/Window 信息，生成 index.json + report.html。
+ *
+ * 零第三方依赖，仅使用 Node 内置模块，可独立分发。
+ * 等价于原 android_parse_fast.py（functional equivalence）。
+ *
+ * 用法:
+ *   node android_parse_fast.ts --package <pkg> --output <dir> [--device serial] [--adb-path adb]
+ *                              [--max-pages 500] [--max-scrolls 10] [--manual]
+ */
+
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+// ─────────────────────────────────────────────
+// 默认配置值
+// ─────────────────────────────────────────────
+const ADB_PATH_DEFAULT = 'adb';
+const DEVICE_SERIAL_DEFAULT = 'emulator-5554';
+const IDLE_POLL_INTERVAL_DEFAULT = 0.2;
+const IDLE_TIMEOUT_DEFAULT = 5;
+const MAX_PAGES_DEFAULT = 500;
+const MAX_SCROLLS_DEFAULT = 10;
+const SCROLL_DURATION_MS_DEFAULT = 300;
+const SKIP_RESOURCE_ID_PATTERNS_DEFAULT = [
+  'statusBarBackground',
+  'navigationBarBackground',
+  'action_bar_container',
+  'status_bar',
+  'navigation_bar',
+];
+const HORIZONTAL_SCROLL_CLASSES = new Set(['android.widget.HorizontalScrollView']);
+
+function sleep(seconds: number): void {
+  const end = Date.now() + seconds * 1000;
+  const ia = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < end) Atomics.wait(ia, 0, 0, Math.min(50, end - Date.now()));
+}
+
+// ─────────────────────────────────────────────
+// 最小 XML 解析器（等价 xml.etree 的 root.iter("node") + get 属性）
+// ─────────────────────────────────────────────
+interface XmlNode {
+  tag: string;
+  attrs: Record<string, string>;
+  children: XmlNode[];
+}
+
+const XML_ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+function decodeEntities(s: string): string {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, ent: string) => {
+    if (ent[0] === '#') {
+      const code = ent[1] === 'x' || ent[1] === 'X' ? parseInt(ent.slice(2), 16) : parseInt(ent.slice(1), 10);
+      return Number.isNaN(code) ? m : String.fromCodePoint(code);
+    }
+    return ent in XML_ENTITIES ? XML_ENTITIES[ent] : m;
+  });
+}
+
+class XmlParseError extends Error {}
+
+function parseXml(xml: string): XmlNode {
+  let i = 0;
+  const n = xml.length;
+  const stack: XmlNode[] = [];
+  let root: XmlNode | null = null;
+
+  const readAttrs = (raw: string): Record<string, string> => {
+    const attrs: Record<string, string> = {};
+    const re = /([^\s=/>]+)\s*=\s*"([^"]*)"|([^\s=/>]+)\s*=\s*'([^']*)'/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(raw)) !== null) {
+      if (m[1] !== undefined) attrs[m[1]] = decodeEntities(m[2]);
+      else if (m[3] !== undefined) attrs[m[3]] = decodeEntities(m[4]);
+    }
+    return attrs;
+  };
+
+  while (i < n) {
+    const lt = xml.indexOf('<', i);
+    if (lt < 0) break;
+    i = lt;
+    if (xml.startsWith('<?', i)) {
+      const end = xml.indexOf('?>', i);
+      if (end < 0) throw new XmlParseError('unterminated declaration');
+      i = end + 2;
+      continue;
+    }
+    if (xml.startsWith('<!--', i)) {
+      const end = xml.indexOf('-->', i);
+      if (end < 0) throw new XmlParseError('unterminated comment');
+      i = end + 3;
+      continue;
+    }
+    if (xml.startsWith('<!', i)) {
+      const end = xml.indexOf('>', i);
+      if (end < 0) throw new XmlParseError('unterminated markup declaration');
+      i = end + 1;
+      continue;
+    }
+    let j = i + 1;
+    let quote: string | null = null;
+    for (; j < n; j++) {
+      const c = xml[j];
+      if (quote) {
+        if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") quote = c;
+      else if (c === '>') break;
+    }
+    if (j >= n) throw new XmlParseError('unterminated tag');
+    const inner = xml.slice(i + 1, j);
+    i = j + 1;
+    if (inner[0] === '/') {
+      if (!stack.pop()) throw new XmlParseError('unexpected closing tag');
+      continue;
+    }
+    const selfClosing = inner.endsWith('/');
+    const body = selfClosing ? inner.slice(0, -1) : inner;
+    const spaceIdx = body.search(/[\s/]/);
+    const tag = spaceIdx < 0 ? body : body.slice(0, spaceIdx);
+    const attrRaw = spaceIdx < 0 ? '' : body.slice(spaceIdx);
+    const node: XmlNode = { tag, attrs: readAttrs(attrRaw), children: [] };
+    if (stack.length > 0) stack[stack.length - 1].children.push(node);
+    else if (root === null) root = node;
+    if (!selfClosing) stack.push(node);
+  }
+  if (root === null) throw new XmlParseError('no root element');
+  return root;
+}
+
+function* iterNodes(root: XmlNode, tag: string): Generator<XmlNode> {
+  if (root.tag === tag) yield root;
+  for (const child of root.children) yield* iterNodes(child, tag);
+}
+
+function attr(node: XmlNode, key: string, dflt = ''): string {
+  return key in node.attrs ? node.attrs[key] : dflt;
+}
+
+function extractInts(s: string): number[] {
+  const m = s.match(/\d+/g);
+  return m ? m.map((x) => parseInt(x, 10)) : [];
+}
+
+// ─────────────────────────────────────────────
+// 元素/签名 纯函数（等价 PageCrawler 的 @staticmethod）
+// ─────────────────────────────────────────────
+interface ClickableElement {
+  class: string;
+  text: string;
+  'resource-id': string;
+  'content-desc': string;
+  bounds: string;
+  center: [number, number] | null;
+  'long-clickable': boolean;
+  scroll_index?: number;
+}
+
+interface ScrollContainer {
+  bounds: [number, number, number, number];
+  class: string;
+  'resource-id': string;
+}
+
+function parseBoundsCenter(bounds: string): [number, number] | null {
+  const nums = extractInts(bounds);
+  if (nums.length === 4) {
+    const [x1, y1, x2, y2] = nums;
+    return [Math.trunc((x1 + x2) / 2), Math.trunc((y1 + y2) / 2)];
+  }
+  return null;
+}
+
+function getClickableElements(xmlContent: string): ClickableElement[] {
+  const elements: ClickableElement[] = [];
+  if (!xmlContent) return elements;
+  let root: XmlNode;
+  try {
+    root = parseXml(xmlContent);
+  } catch (e) {
+    console.log(`  [WARN] XML 解析失败: ${(e as Error).message}`);
+    return elements;
+  }
+
+  const listviewChildSet = new Set<XmlNode>();
+  for (const node of iterNodes(root, 'node')) {
+    const cls = attr(node, 'class');
+    if (cls.includes('ListView') || cls.includes('GridView')) {
+      for (const child of node.children) listviewChildSet.add(child);
+    }
+  }
+
+  const extractText = (node: XmlNode): string => {
+    const t = attr(node, 'text');
+    if (t) return t;
+    for (const child of iterNodes(node, 'node')) {
+      const ct = attr(child, 'text');
+      if (ct) return ct;
+    }
+    return '';
+  };
+
+  for (const node of iterNodes(root, 'node')) {
+    if (attr(node, 'enabled') !== 'true') continue;
+    const isClickable = attr(node, 'clickable') === 'true';
+    const isLongClickable = attr(node, 'long-clickable') === 'true';
+    const isListviewItem = listviewChildSet.has(node);
+    const isCheckable = attr(node, 'checkable') === 'true';
+    if (!(isClickable || isLongClickable || isListviewItem || isCheckable)) continue;
+    const bounds = attr(node, 'bounds');
+    let text = attr(node, 'text');
+    if (!text) text = extractText(node);
+    const baseInfo = {
+      class: attr(node, 'class'),
+      text,
+      'resource-id': attr(node, 'resource-id'),
+      'content-desc': attr(node, 'content-desc'),
+      bounds,
+      center: parseBoundsCenter(bounds),
+    };
+    if (isClickable || isListviewItem || isCheckable) elements.push({ ...baseInfo, 'long-clickable': false });
+    if (isLongClickable) elements.push({ ...baseInfo, 'long-clickable': true });
+  }
+  return elements;
+}
+
+function extractNodeKeys(xmlContent: string): Set<string> {
+  const keys = new Set<string>();
+  if (!xmlContent) return keys;
+  let root: XmlNode;
+  try {
+    root = parseXml(xmlContent);
+  } catch {
+    return keys;
+  }
+  for (const node of iterNodes(root, 'node')) {
+    keys.add(
+      [attr(node, 'class'), attr(node, 'resource-id'), attr(node, 'text'), attr(node, 'content-desc'), attr(node, 'bounds')].join(''),
+    );
+  }
+  return keys;
+}
+
+function setsEqual(a: Set<string>, b: Set<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const v of a) if (!b.has(v)) return false;
+  return true;
+}
+
+function findScrollableContainers(xmlContent: string): ScrollContainer[] {
+  const containers: ScrollContainer[] = [];
+  if (!xmlContent) return containers;
+  let root: XmlNode;
+  try {
+    root = parseXml(xmlContent);
+  } catch {
+    return containers;
+  }
+  for (const node of iterNodes(root, 'node')) {
+    if (attr(node, 'scrollable') !== 'true') continue;
+    const cls = attr(node, 'class');
+    if (HORIZONTAL_SCROLL_CLASSES.has(cls)) continue;
+    const nums = extractInts(attr(node, 'bounds'));
+    if (nums.length !== 4) continue;
+    const [x1, y1, x2, y2] = nums;
+    if (y2 - y1 < 200) continue;
+    containers.push({ bounds: [x1, y1, x2, y2], class: cls, 'resource-id': attr(node, 'resource-id') });
+  }
+  containers.sort(
+    (a, b) => (b.bounds[2] - b.bounds[0]) * (b.bounds[3] - b.bounds[1]) - (a.bounds[2] - a.bounds[0]) * (a.bounds[3] - a.bounds[1]),
+  );
+  return containers;
+}
+
+function normalizeComponent(component: string): string {
+  if (!component.includes('/')) return component;
+  const idx = component.indexOf('/');
+  const pkg = component.slice(0, idx);
+  let cls = component.slice(idx + 1);
+  if (cls.startsWith('.')) cls = pkg + cls;
+  return `${pkg}/${cls}`;
+}
+
+function stableActivityKey(activityInfo: Record<string, string>): string {
+  const focus = activityInfo['current_focus'] ?? '';
+  const resumed = activityInfo['resumed_activity'] ?? '';
+  const m = focus.match(/[\w.]+\/[\w.]+/);
+  if (m) return normalizeComponent(m[0]);
+  const actM = resumed.match(/[\w.]+\/[\w.]+/);
+  const actPart = actM ? normalizeComponent(actM[0]) : 'unknown';
+  const winTypeM = focus.match(/(PopupWindow|Dialog|DecorView|Toast)/);
+  const winType = winTypeM ? winTypeM[1] : 'overlay';
+  return `${actPart}|${winType}`;
+}
+
+function pageSignature(activityInfo: Record<string, string>, xmlContent: string): string {
+  const actKey = stableActivityKey(activityInfo);
+  if (!xmlContent) return `${actKey}|empty`;
+  const clickable = getClickableElements(xmlContent);
+  if (clickable.length === 0) return `${actKey}|no_clickable`;
+  const elemFeatures = clickable.map((e) =>
+    [e.class ?? '', e['resource-id'] ?? '', e['content-desc'] ?? '', e.bounds ?? ''].join('|'),
+  );
+  const featuresStr = elemFeatures.join(';');
+  const featureHash = createHash('md5').update(featuresStr, 'utf-8').digest('hex').slice(0, 16);
+  return `${actKey}|${featureHash}`;
+}
+
+type RootIdentity = [string, Set<string>];
+
+function rootIdentifiedSet(activityInfo: Record<string, string>, xmlContent: string): RootIdentity {
+  const resumed = activityInfo['resumed_activity'] ?? '';
+  const m = resumed.match(/[\w.]+\/[\w.]+/);
+  const actKey = m ? normalizeComponent(m[0]) : 'unknown';
+  if (!xmlContent) return [actKey, new Set()];
+  const clickable = getClickableElements(xmlContent);
+  const elems = new Set<string>();
+  for (const e of clickable) {
+    const desc = e['content-desc'] ?? '';
+    const rid = e['resource-id'] ?? '';
+    if (!desc && !rid) continue;
+    elems.add([e.class ?? '', rid, desc].join(''));
+  }
+  return [actKey, elems];
+}
+
+function isSameRootPage(rootInfo: RootIdentity, currentInfo: RootIdentity, threshold = 0.6): boolean {
+  const [rootAct, rootElems] = rootInfo;
+  const [curAct, curElems] = currentInfo;
+  if (rootAct !== curAct) return false;
+  if (rootElems.size === 0 && curElems.size === 0) return true;
+  if (rootElems.size === 0 || curElems.size === 0) return false;
+  let inter = 0;
+  for (const v of rootElems) if (curElems.has(v)) inter++;
+  const union = rootElems.size + curElems.size - inter;
+  return union > 0 && inter / union >= threshold;
+}
+
+/** current_focus 是否含 `package/activity` 分量（弹窗/overlay 焦点没有）。 */
+function focusHasActivityComponent(activityInfo: Record<string, string>): boolean {
+  return /[\w.]+\/[\w.]+/.test(activityInfo['current_focus'] ?? '');
+}
+
+/**
+ * 从 activity 信息提取启动组件 [package, activity]。
+ * 优先 current_focus（通常是全限定 Activity），回退 resumed_activity（可能是相对名 `.ui.Main`，
+ * am start 同样接受）。都取不到返回 null。
+ */
+function extractLaunchComponent(activityInfo: Record<string, string>): [string, string] | null {
+  for (const key of ['current_focus', 'resumed_activity']) {
+    const s = activityInfo[key] ?? '';
+    const m = s.match(/([\w.]+)\/([\w.]+)/);
+    if (m) return [m[1], m[2]];
+  }
+  return null;
+}
+
+type ElemId = [string, string, string, string, boolean];
+
+function findElementOnScreen(xmlContent: string, elemId: ElemId | [string, string, string, string]): ClickableElement | null {
+  const rid = elemId[0];
+  const text = elemId[1];
+  const desc = elemId[2];
+  const bounds = elemId[3];
+  const isLong = elemId.length >= 5 ? (elemId[4] as boolean) : null;
+  const clickableElements = getClickableElements(xmlContent);
+
+  if (bounds) {
+    for (const e of clickableElements) {
+      if (
+        e['resource-id'] === rid &&
+        e.text === text &&
+        e['content-desc'] === desc &&
+        e.bounds === bounds &&
+        (isLong === null || e['long-clickable'] === isLong)
+      ) {
+        return e;
+      }
+    }
+  }
+  for (const e of clickableElements) {
+    if (
+      e['resource-id'] === rid &&
+      e.text === text &&
+      e['content-desc'] === desc &&
+      (isLong === null || e['long-clickable'] === isLong)
+    ) {
+      return e;
+    }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────
+// ADBHelper：封装所有 ADB 设备通信与交互操作
+// ─────────────────────────────────────────────
+class ADBHelper {
+  adbPath: string;
+  deviceSerial: string | null;
+  idlePollInterval: number;
+  idleTimeout: number;
+  scrollDurationMs: number;
+  /** 目标 App 包名；多屏设备（车机等）上用于从多条 focus/resumed 行中挑出正确的那条。 */
+  targetPackage: string | null;
+  /** screencap -d 用的物理 display id 缓存；undefined=未解析，null=解析失败（退回无 -d）。 */
+  private cachedPhysicalDisplayId: string | null | undefined = undefined;
+
+  constructor(opts: {
+    adbPath?: string;
+    deviceSerial?: string | null;
+    idlePollInterval?: number;
+    idleTimeout?: number;
+    scrollDurationMs?: number;
+    targetPackage?: string | null;
+  } = {}) {
+    this.adbPath = opts.adbPath ?? ADB_PATH_DEFAULT;
+    this.deviceSerial = opts.deviceSerial ?? DEVICE_SERIAL_DEFAULT;
+    this.targetPackage = opts.targetPackage ?? null;
+    this.idlePollInterval = opts.idlePollInterval ?? IDLE_POLL_INTERVAL_DEFAULT;
+    this.idleTimeout = opts.idleTimeout ?? IDLE_TIMEOUT_DEFAULT;
+    this.scrollDurationMs = opts.scrollDurationMs ?? SCROLL_DURATION_MS_DEFAULT;
+  }
+
+  private buildArgs(args: string[]): string[] {
+    const full: string[] = [];
+    if (this.deviceSerial) full.push('-s', this.deviceSerial);
+    full.push(...args);
+    return full;
+  }
+
+  private spawn(args: string[], timeout: number, binary: boolean): SpawnSyncReturns<Buffer> {
+    return spawnSync(this.adbPath, this.buildArgs(args), {
+      timeout: timeout * 1000,
+      maxBuffer: 128 * 1024 * 1024,
+      windowsHide: true,
+    }) as SpawnSyncReturns<Buffer>;
+  }
+
+  run(args: string[], timeout = 15): string {
+    const res = this.spawn(args, timeout, false);
+    if (res.error) {
+      const code = (res.error as NodeJS.ErrnoException).code;
+      if (code === 'ETIMEDOUT') {
+        console.log(`  [WARN] adb 命令超时: ${args.join(' ')}`);
+        return '';
+      }
+      if (code === 'ENOENT') {
+        throw new Error('找不到 adb，请确认已安装并配置 PATH，或修改 ADB_PATH');
+      }
+    }
+    const out = res.stdout ?? Buffer.alloc(0);
+    return out.toString('utf-8').trim();
+  }
+
+  shell(args: string[], timeout = 15): string {
+    return this.run(['shell', ...args], timeout);
+  }
+
+  waitForIdle(): void {
+    const deadline = Date.now() + this.idleTimeout * 1000;
+    let prevFocus: string | null = null;
+    let interval = this.idlePollInterval;
+    while (Date.now() < deadline) {
+      sleep(interval);
+      interval = Math.min(interval * 1.5, 0.5);
+      const transitionOut = this.shell(['dumpsys', 'window', 'animator']);
+      if (transitionOut.includes('Transition ready') || transitionOut.includes('Running animations')) continue;
+      const focusOut = this.shell(['dumpsys', 'window']);
+      // 多屏设备上每个 display 各有一条 mCurrentFocus，全部拼起来做稳定性比较，
+      // 避免只看副屏那条（常为 null，永远"稳定"）而误判 UI 已空闲。
+      const currentFocus = focusOut
+        .split(/\r?\n/)
+        .filter((line) => line.includes('mCurrentFocus'))
+        .map((line) => line.trim())
+        .join(' | ');
+      if (currentFocus && currentFocus === prevFocus) return;
+      prevFocus = currentFocus;
+    }
+    console.log(`  [WARN] 等待 UI 空闲超时 (${this.idleTimeout}s)，继续执行`);
+  }
+
+  checkDevice(): boolean {
+    const out = this.run(['devices']);
+    const lines = out.split(/\r?\n/).filter((l) => l.trim() && !l.includes('List of devices'));
+    const online = lines.filter((l) => l.includes('device') && !l.includes('offline'));
+    if (online.length === 0) {
+      console.log(' 未检测到在线设备，请先启动模拟器并确认 adb devices 有输出');
+      return false;
+    }
+    const onlineDevices = online.map((line) => line.split(/\s+/)[0]);
+    console.log(` 在线设备: [${onlineDevices.map((d) => `'${d}'`).join(', ')}]`);
+    if (this.deviceSerial === null) {
+      this.deviceSerial = onlineDevices[0];
+      console.log(` 未指定设备，自动选择: ${this.deviceSerial}`);
+    } else if (!onlineDevices.includes(this.deviceSerial)) {
+      console.log(` 指定的设备 ${this.deviceSerial} 不存在，自动选择: ${onlineDevices[0]}`);
+      this.deviceSerial = onlineDevices[0];
+    } else {
+      console.log(` 使用指定的设备: ${this.deviceSerial}`);
+    }
+    return true;
+  }
+
+  /**
+   * 从多条候选行中挑一条最可信的。
+   * 多屏设备（车机 / 折叠屏 / cluster+主屏）上，`dumpsys window` 与
+   * `dumpsys activity activities` 会为**每个 display 各输出一条**
+   * mCurrentFocus / topResumedActivity，其中副屏那条常常是 `null` 或系统
+   * launcher。因此不能取第一条就 break：优先取包含目标包名的那条，
+   * 其次取任意带 `pkg/activity` 组件名的非 null 行，最后兜底第一条。
+   */
+  private pickBestLine(lines: string[]): string | undefined {
+    if (lines.length === 0) return undefined;
+    if (this.targetPackage) {
+      const hit = lines.find((l) => l.includes(this.targetPackage!));
+      if (hit) return hit;
+    }
+    const withComponent = lines.find((l) => !/=null\b/.test(l) && /[\w.]+\/[\w.]+/.test(l));
+    return withComponent ?? lines[0];
+  }
+
+  getCurrentActivity(): Record<string, string> {
+    const info: Record<string, string> = {};
+    const actOut = this.shell(['dumpsys', 'activity', 'activities']);
+    const winOut = this.shell(['dumpsys', 'window']);
+
+    const resumedLines: string[] = [];
+    for (const line of actOut.split(/\r?\n/)) {
+      if (/ResumedActivity|topActivity/i.test(line)) resumedLines.push(line.trim());
+    }
+    const resumed = this.pickBestLine(resumedLines);
+    if (resumed !== undefined) info['resumed_activity'] = resumed;
+
+    const focusLines: string[] = [];
+    const focusedAppLines: string[] = [];
+    for (const line of winOut.split(/\r?\n/)) {
+      if (line.includes('mCurrentFocus')) focusLines.push(line.trim());
+      else if (line.includes('mFocusedApp')) focusedAppLines.push(line.trim());
+    }
+    const focus = this.pickBestLine(focusLines);
+    if (focus !== undefined) info['current_focus'] = focus;
+    const focusedApp = this.pickBestLine(focusedAppLines);
+    if (focusedApp !== undefined) info['focused_app'] = focusedApp;
+
+    return info;
+  }
+
+  tap(x: number, y: number): void {
+    this.shell(['input', 'tap', String(x), String(y)]);
+    this.waitForIdle();
+  }
+
+  longPress(x: number, y: number, durationMs = 1000): void {
+    this.shell(['input', 'swipe', String(x), String(y), String(x), String(y), String(durationMs)]);
+    this.waitForIdle();
+  }
+
+  tapOrLongPress(x: number, y: number, isLongClick = false): void {
+    if (isLongClick) this.longPress(x, y);
+    else this.tap(x, y);
+  }
+
+  pressBack(): void {
+    this.shell(['input', 'keyevent', 'KEYCODE_BACK']);
+    this.waitForIdle();
+  }
+
+  dumpXmlQuick(): string {
+    const remotePath = '/sdcard/ui_dump.xml';
+    this.shell(['rm -f /sdcard/ui_dump.xml && uiautomator dump /sdcard/ui_dump.xml'], 20);
+    for (let k = 0; k < 6; k++) {
+      const check = this.shell(['ls', remotePath]);
+      if (check.includes(remotePath)) break;
+      sleep(0.2);
+    }
+    return this.shell(['cat', remotePath], 15);
+  }
+
+  getViewXmlFast(pageDir: string): string {
+    const xmlContent = this.dumpXmlQuick();
+    if (xmlContent) fs.writeFileSync(path.join(pageDir, 'view.xml'), xmlContent, 'utf-8');
+    return xmlContent;
+  }
+
+  /**
+   * 解析目标 App 所在屏幕的 SurfaceFlinger **物理** display id（screencap -d 只认物理 id，
+   * 逻辑 id 如 0/2/3 会直接 "Failed to take screenshot. Status: -2"）。
+   *
+   * 多屏设备（车机 cluster + 主屏、折叠屏等）上不传 -d 时，screencap 会先往 stdout
+   * 打一段 "[Warning] Multiple displays were found..." 文本，把 PNG 二进制整体前移
+   * 导致图片打不开；且它"默认取第一个 display"，不保证就是 App 所在那块屏。
+   *
+   * 流程：dumpsys activity activities 找到目标包所在的 `Display #N`
+   *   → dumpsys display 里用 `displayId N,` 所在行的 uniqueId "local:<physId>" 取物理 id。
+   * 单屏设备解析失败时返回 null，退回不带 -d 的老行为（此时也不会有警告）。
+   */
+  private resolveTargetPhysicalDisplayId(): string | null {
+    if (this.cachedPhysicalDisplayId !== undefined) return this.cachedPhysicalDisplayId;
+    let result: string | null = null;
+    try {
+      if (this.targetPackage) {
+        const actOut = this.shell(['dumpsys', 'activity', 'activities']);
+        let curDisplay: string | null = null;
+        let logicalId: string | null = null;
+        for (const line of actOut.split(/\r?\n/)) {
+          const m = line.match(/^Display #(\d+)/);
+          if (m) curDisplay = m[1];
+          else if (curDisplay && line.includes(this.targetPackage)) {
+            logicalId = curDisplay;
+            break;
+          }
+        }
+        if (logicalId !== null) {
+          const dispOut = this.shell(['dumpsys', 'display']);
+          // 逐行扫描：DisplayInfo 是单行长串，`displayId <N>,` 与 uniqueId 同行。
+          for (const line of dispOut.split(/\r?\n/)) {
+            if (!line.includes(`displayId ${logicalId},`)) continue;
+            const m = line.match(/uniqueId "local:(\d+)"/);
+            if (m) {
+              result = m[1];
+              break;
+            }
+          }
+        }
+      }
+    } catch {
+      result = null;
+    }
+    if (result) console.log(`  [INFO] 截图目标 display 物理 id: ${result}`);
+    this.cachedPhysicalDisplayId = result;
+    return result;
+  }
+
+  screencapBytes(): Buffer | null {
+    const physId = this.resolveTargetPhysicalDisplayId();
+    const capArgs = physId
+      ? ['exec-out', 'screencap', '-d', physId, '-p']
+      : ['exec-out', 'screencap', '-p'];
+    const res = spawnSync(this.adbPath, this.buildArgs(capArgs), {
+      timeout: 15 * 1000,
+      maxBuffer: 128 * 1024 * 1024,
+      windowsHide: true,
+    }) as SpawnSyncReturns<Buffer>;
+    if (res.error && (res.error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+      console.log('  [WARN] 截图超时');
+      return null;
+    }
+    const out = res.stdout ?? Buffer.alloc(0);
+    if (out.length === 0) return null;
+    // 兜底：无论如何都从 PNG magic 处截断，剥掉 screencap 可能前置到 stdout 的警告文本。
+    const magic = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+    const at = out.indexOf(magic);
+    if (at < 0) {
+      console.log(`  [WARN] 截图输出不含 PNG 数据: ${out.subarray(0, 120).toString('utf-8').trim()}`);
+      return null;
+    }
+    return at === 0 ? out : out.subarray(at);
+  }
+
+  takeScreenshot(pageDir: string): void {
+    const localPath = path.join(pageDir, 'screenshot.png');
+    const data = this.screencapBytes();
+    if (data) {
+      fs.writeFileSync(localPath, data);
+    } else {
+      const remotePath = '/sdcard/screenshot.png';
+      const physId = this.resolveTargetPhysicalDisplayId();
+      // 落盘到设备再 pull 时同样要指定 display，否则多屏下可能抓到副屏。
+      if (physId) this.shell(['screencap', '-d', physId, '-p', remotePath]);
+      else this.shell(['screencap', '-p', remotePath]);
+      sleep(0.3);
+      this.run(['pull', remotePath, localPath], 15);
+    }
+  }
+
+  scrollToPosition(containerBounds: [number, number, number, number], scrollIndex: number): void {
+    if (scrollIndex <= 0) return;
+    const [x1, y1, , y2] = containerBounds;
+    const x2 = containerBounds[2];
+    const cx = Math.trunc((x1 + x2) / 2);
+    const height = y2 - y1;
+    const swipeFromY = y1 + Math.trunc(height * 0.7);
+    const swipeToY = y1 + Math.trunc(height * 0.3);
+    for (let k = 0; k < scrollIndex; k++) {
+      this.shell(['input', 'swipe', String(cx), String(swipeFromY), String(cx), String(swipeToY), String(this.scrollDurationMs)]);
+      this.waitForIdle();
+    }
+  }
+
+  flushPendingPulls(): void {
+    // TS 版截图为同步写入，无异步 pull 队列，保留空实现以对齐调用点。
+  }
+}
+
+// ─────────────────────────────────────────────
+// 队列项 / 记录类型
+// ─────────────────────────────────────────────
+interface ScrollInfo {
+  scroll_index: number;
+  container_bounds: number[];
+}
+interface ClickStep {
+  from: string;
+  element: string;
+  center: number[];
+  'resource-id': string;
+  text: string;
+  'content-desc': string;
+  'long-clickable': boolean;
+  scroll_info: ScrollInfo | null;
+}
+type QueueItem = [ClickStep[], ElemId, string[], ScrollInfo | null];
+
+interface PageRecord {
+  page_id: string | null;
+  label: string;
+  timestamp: string;
+  activity_info: Record<string, string>;
+  clickable_count: number;
+  clickable_elements: ClickableElement[];
+  scroll_container_bounds: number[] | null;
+  _tmp_dir?: string;
+  _screenshots?: string[];
+  _view_xmls?: string[];
+  screenshot?: string;
+  view_xml?: string;
+  screenshots?: string[];
+  view_xmls?: string[];
+  click_path?: ClickStep[] | 'manual';
+  came_from?: string;
+  trigger_element?: string;
+  description?: string;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+// ─────────────────────────────────────────────
+// PageCrawler：UI 遍历逻辑、页面采集、断点续跑、报告生成
+// ─────────────────────────────────────────────
+class PageCrawler {
+  adb: ADBHelper;
+  package: string;
+  outputRoot: string;
+  maxPages: number;
+  maxScrolls: number;
+  skipPatterns: string[];
+
+  // 运行时状态
+  pagesIndex: PageRecord[] = [];
+  visitedSignatures = new Set<string>();
+  pathSignatures: Record<string, string> = {};
+  blockedElements = new Set<string>();
+  queue: QueueItem[] = [];
+  pageCounter = 0;
+  stats = { skipped_elements: 0, probe_skipped: 0 };
+
+  constructor(opts: {
+    adb: ADBHelper;
+    package: string;
+    outputDir: string;
+    maxPages?: number;
+    maxScrolls?: number;
+    skipPatterns?: string[];
+  }) {
+    this.adb = opts.adb;
+    this.package = opts.package;
+    this.outputRoot = opts.outputDir;
+    this.maxPages = opts.maxPages ?? MAX_PAGES_DEFAULT;
+    this.maxScrolls = opts.maxScrolls ?? MAX_SCROLLS_DEFAULT;
+    this.skipPatterns = opts.skipPatterns ?? SKIP_RESOURCE_ID_PATTERNS_DEFAULT;
+  }
+
+  static elemIdOf(elem: ClickableElement): ElemId {
+    return [
+      elem['resource-id'] ?? '',
+      elem.text ?? '',
+      elem['content-desc'] ?? '',
+      elem.bounds ?? '',
+      elem['long-clickable'] ?? false,
+    ];
+  }
+
+  shouldSkipElement(elem: ClickableElement): boolean {
+    const rid = elem['resource-id'] ?? '';
+    const text = elem.text ?? '';
+    const desc = elem['content-desc'] ?? '';
+    const cls = elem.class ?? '';
+    for (const pattern of this.skipPatterns) if (rid.includes(pattern)) return true;
+    if (!text && !desc && !rid && cls.includes('ImageView')) return true;
+    return false;
+  }
+
+  isInTargetApp(activityInfo: Record<string, string>): boolean {
+    const focus = activityInfo['current_focus'] ?? '';
+    const resumed = activityInfo['resumed_activity'] ?? '';
+    console.log(focus, resumed);
+    return focus.includes(this.package) || resumed.includes(this.package);
+  }
+
+  scrollAndDump(
+    pageDir: string,
+    containerBounds: [number, number, number, number],
+    initialXml = '',
+  ): { xmlList: string[]; xmlPaths: string[]; screenshotPaths: string[] } {
+    const [x1, y1, , y2b] = containerBounds;
+    const x2 = containerBounds[2];
+    const y2 = y2b;
+    const cx = Math.trunc((x1 + x2) / 2);
+    const height = y2 - y1;
+    const swipeFromY = y1 + Math.trunc(height * 0.7);
+    const swipeToY = y1 + Math.trunc(height * 0.3);
+
+    const xmlList: string[] = [];
+    const xmlPaths: string[] = [];
+    const screenshotPaths: string[] = [];
+    let prevKeys: Set<string> | null = initialXml ? extractNodeKeys(initialXml) : null;
+
+    for (let i = 0; i < this.maxScrolls; i++) {
+      this.adb.shell(['input', 'swipe', String(cx), String(swipeFromY), String(cx), String(swipeToY), String(this.adb.scrollDurationMs)]);
+      this.adb.waitForIdle();
+      const newXml = this.adb.dumpXmlQuick();
+      const newKeys = extractNodeKeys(newXml);
+      if (prevKeys !== null && setsEqual(newKeys, prevKeys)) {
+        console.log(`   📜 滚动 ${i + 1} 次后到达底部，跳过截图`);
+        break;
+      }
+      prevKeys = newKeys;
+      xmlList.push(newXml);
+      const xmlPath = path.join(pageDir, `view_scroll_${i + 1}.xml`);
+      fs.writeFileSync(xmlPath, newXml, 'utf-8');
+      xmlPaths.push(xmlPath);
+      const ssPath = path.join(pageDir, `screenshot_scroll_${i + 1}.png`);
+      const data = this.adb.screencapBytes();
+      if (data) {
+        fs.writeFileSync(ssPath, data);
+        screenshotPaths.push(ssPath);
+        console.log(`   📸 滚动 ${i + 1}: XML + 截图已保存`);
+      }
+    }
+    return { xmlList, xmlPaths, screenshotPaths };
+  }
+
+  capturePage(label: string): {
+    record: PageRecord;
+    xmlContent: string;
+    clickable: ClickableElement[];
+    scrollContainerBounds: [number, number, number, number] | null;
+  } {
+    const tmpDir = path.join(this.outputRoot, '_tmp_capture');
+    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    console.log(`\n📄 [采集中] ${label}`);
+    const actInfo = this.adb.getCurrentActivity();
+    console.log(`   Focus : ${actInfo['current_focus'] ?? 'N/A'}`);
+    console.log(`   Activity: ${actInfo['resumed_activity'] ?? 'N/A'}`);
+
+    const xmlContent = this.adb.getViewXmlFast(tmpDir);
+    console.log(`   View XML 已保存 (${Buffer.byteLength(xmlContent, 'utf-8')} bytes)`);
+    this.adb.takeScreenshot(tmpDir);
+    console.log('   截图已保存');
+
+    const allScreenshots = [path.join(tmpDir, 'screenshot.png')];
+    const allViewXmls = [path.join(tmpDir, 'view.xml')];
+    const allXmlContents = [xmlContent];
+    const scrollContainers = findScrollableContainers(xmlContent);
+    if (scrollContainers.length > 0) {
+      const container = scrollContainers[0];
+      console.log(`   📜 检测到可滚动容器: ${container.class} ${container['resource-id']}`);
+      const { xmlList, xmlPaths, screenshotPaths } = this.scrollAndDump(tmpDir, container.bounds, xmlContent);
+      if (xmlList.length > 0) {
+        allXmlContents.push(...xmlList);
+        allViewXmls.push(...xmlPaths);
+        allScreenshots.push(...screenshotPaths);
+        console.log(`   📜 滚动采集完成：${xmlList.length} 次滚动，共 ${allScreenshots.length} 张截图`);
+      }
+    }
+
+    const seenClickable = new Set<string>();
+    const clickable: ClickableElement[] = [];
+    allXmlContents.forEach((xc, idx) => {
+      for (const elem of getClickableElements(xc)) {
+        const key = [
+          elem['resource-id'] ?? '',
+          elem.text ?? '',
+          elem['content-desc'] ?? '',
+          elem.class ?? '',
+          elem.bounds ?? '',
+          String(elem['long-clickable'] ?? false),
+        ].join(' ');
+        if (!seenClickable.has(key)) {
+          seenClickable.add(key);
+          elem.scroll_index = idx;
+          clickable.push(elem);
+        }
+      }
+    });
+    console.log(`   可点击元素: ${clickable.length} 个`);
+
+    const scrollContainerBounds = scrollContainers.length > 0 ? scrollContainers[0].bounds : null;
+    const record: PageRecord = {
+      page_id: null,
+      label,
+      timestamp: new Date().toISOString(),
+      activity_info: actInfo,
+      clickable_count: clickable.length,
+      clickable_elements: clickable,
+      scroll_container_bounds: scrollContainerBounds ? [...scrollContainerBounds] : null,
+      _tmp_dir: tmpDir,
+      _screenshots: allScreenshots,
+      _view_xmls: allViewXmls,
+    };
+    return { record, xmlContent, clickable, scrollContainerBounds };
+  }
+
+  restartToRoot(
+    launchPackage: string | null,
+    launchActivity: string | null,
+    rootActivityKeyword: string | null = null,
+    rootIdentity: RootIdentity | null = null,
+  ): boolean {
+    if (!launchPackage || !launchActivity) {
+      console.log('   [WARN] 包名或 Activity 名为空，无法重启');
+      return false;
+    }
+    const component = `${launchPackage}/${launchActivity}`;
+
+    const isAtRoot = (): boolean => {
+      const activityInfo = this.adb.getCurrentActivity();
+      const focus = activityInfo['current_focus'] ?? '';
+      const resumed = activityInfo['resumed_activity'] ?? '';
+      if (rootActivityKeyword) {
+        if (!focus.includes(rootActivityKeyword) && !resumed.includes(rootActivityKeyword)) return false;
+      }
+      if (rootIdentity) {
+        const xml = this.adb.dumpXmlQuick();
+        const curIdentity = rootIdentifiedSet(activityInfo, xml);
+        if (!isSameRootPage(rootIdentity, curIdentity)) {
+          const [, curElems] = curIdentity;
+          const [, rootElems] = rootIdentity;
+          let inter = 0;
+          for (const v of rootElems) if (curElems.has(v)) inter++;
+          const union = rootElems.size + curElems.size - inter;
+          const sim = union ? inter / union : 0;
+          console.log(`   [DEBUG] 根页面相似度: ${sim.toFixed(2)} (交集${inter}/并集${union})`);
+          return false;
+        }
+      }
+      return true;
+    };
+
+    this.adb.shell(['am', 'force-stop', launchPackage]);
+    sleep(1.0);
+    this.adb.shell(['am', 'start', '-n', component, '--activity-clear-task', '--activity-clear-top']);
+    this.adb.waitForIdle();
+
+    for (let retry = 0; retry < 4; retry++) {
+      if (isAtRoot()) return true;
+      console.log(`   [INFO] 等待页面加载完成... (重试 ${retry + 1}/4)`);
+      sleep(2);
+    }
+
+    console.log('   [WARN] force-stop 后未到达根页面（App 恢复了上次的 Tab 状态）');
+    console.log('   [INFO] 尝试 back + 点击路径恢复...');
+    this.adb.pressBack();
+    if (isAtRoot()) return true;
+
+    console.log('   [WARN] 所有恢复方式均失败，跳过此次导航');
+    return false;
+  }
+
+  navigateViaRestart(
+    clickPath: ClickStep[],
+    launchPackage: string | null,
+    launchActivity: string | null,
+    rootActivityKeyword: string | null = null,
+    stepSignatures: string[] | null = null,
+    rootIdentity: RootIdentity | null = null,
+  ): boolean {
+    if (!launchPackage || !launchActivity) {
+      console.log('   [WARN] 包名或 Activity 名为空，无法导航');
+      return false;
+    }
+    if (clickPath.length === 0) return true;
+    if (!this.restartToRoot(launchPackage, launchActivity, rootActivityKeyword, rootIdentity)) {
+      console.log('   [ERR] 无法回到根页面，导航失败');
+      return false;
+    }
+
+    for (let i = 0; i < clickPath.length; i++) {
+      const step = clickPath[i];
+      let xml = this.adb.dumpXmlQuick();
+      const stepScroll = step.scroll_info;
+      if (stepScroll && stepScroll.scroll_index > 0) {
+        this.adb.scrollToPosition(stepScroll.container_bounds as [number, number, number, number], stepScroll.scroll_index);
+        xml = this.adb.dumpXmlQuick();
+      }
+      const elemId: [string, string, string, string] = [step['resource-id'] ?? '', step.text ?? '', step['content-desc'] ?? '', ''];
+      const found = findElementOnScreen(xml, elemId);
+      const isLong = step['long-clickable'] ?? false;
+      if (found && found.center) {
+        this.adb.tapOrLongPress(found.center[0], found.center[1], isLong);
+      } else if (step.center) {
+        console.log(`   [WARN] 未找到元素 ${step.element ?? '?'}，使用记录坐标`);
+        this.adb.tapOrLongPress(step.center[0], step.center[1], isLong);
+      } else {
+        console.log(`   [ERR] 无法导航到步骤: ${step.element ?? '?'}`);
+        return false;
+      }
+
+      if (stepSignatures && i < stepSignatures.length && stepSignatures[i]) {
+        const verifyXml = this.adb.dumpXmlQuick();
+        const verifyInfo = this.adb.getCurrentActivity();
+        const actualSig = pageSignature(verifyInfo, verifyXml);
+        if (actualSig !== stepSignatures[i]) {
+          const expectedAct = stepSignatures[i].split('|')[0];
+          const actualAct = actualSig.split('|')[0];
+          if (expectedAct !== actualAct) {
+            console.log(`   [WARN] 导航步骤 ${i + 1} 后 Activity 不匹配 (期望=${expectedAct}, 实际=${actualAct})`);
+            return false;
+          }
+        }
+      }
+    }
+    return true;
+  }
+
+  // ── 断点续跑 ──
+  private saveQueue(): void {
+    const items = this.queue.map(([clickPath, elemId, stepSigs, scrollInfo]) => [clickPath, [...elemId], stepSigs, scrollInfo]);
+    try {
+      fs.writeFileSync(path.join(this.outputRoot, 'queue_checkpoint.json'), JSON.stringify(items), 'utf-8');
+    } catch (e) {
+      console.log(`  [WARN] 保存队列检查点失败: ${(e as Error).message}`);
+    }
+  }
+
+  private loadQueue(): QueueItem[] | null {
+    const qfile = path.join(this.outputRoot, 'queue_checkpoint.json');
+    if (!fs.existsSync(qfile)) return null;
+    try {
+      const items = JSON.parse(fs.readFileSync(qfile, 'utf-8')) as [ClickStep[], unknown[], string[], ScrollInfo | null][];
+      return items.map(([clickPath, elemIdList, stepSigs, scrollInfo]) => [
+        clickPath,
+        elemIdList as ElemId,
+        stepSigs,
+        scrollInfo,
+      ]);
+    } catch (e) {
+      console.log(`  [WARN] 加载队列检查点失败: ${(e as Error).message}，将重建队列`);
+      return null;
+    }
+  }
+
+  private rebuildQueueFromPages(pagesIndex: PageRecord[]): QueueItem[] {
+    const queue: QueueItem[] = [];
+    for (const page of pagesIndex) {
+      const clickPath = (Array.isArray(page.click_path) ? page.click_path : []) as ClickStep[];
+      const clickable = page.clickable_elements ?? [];
+      const scrollContainerBounds = page.scroll_container_bounds;
+      for (const elem of clickable) {
+        if (this.shouldSkipElement(elem)) continue;
+        const elemId = PageCrawler.elemIdOf(elem);
+        const si = elem.scroll_index ?? 0;
+        let scrollInfo: ScrollInfo | null = null;
+        if (si > 0 && scrollContainerBounds) scrollInfo = { scroll_index: si, container_bounds: [...scrollContainerBounds] };
+        queue.push([clickPath, elemId, [], scrollInfo]);
+      }
+    }
+    return queue;
+  }
+
+  private tryLoadCheckpoint():
+    | { pagesIndex: PageRecord[]; visited: Set<string>; pageCounter: number; queue: QueueItem[]; blocked: Set<string> }
+    | null {
+    const indexFile = path.join(this.outputRoot, 'index.json');
+    if (!fs.existsSync(indexFile)) return null;
+    const pageDirs = fs.existsSync(this.outputRoot)
+      ? fs.readdirSync(this.outputRoot).filter((d) => d.startsWith('page_'))
+      : [];
+    if (pageDirs.length === 0) return null;
+
+    let pagesIndex: PageRecord[];
+    try {
+      pagesIndex = JSON.parse(fs.readFileSync(indexFile, 'utf-8')) as PageRecord[];
+    } catch (e) {
+      console.log(`  [WARN] 读取 index.json 失败: ${(e as Error).message}，重新开始`);
+      return null;
+    }
+    if (!pagesIndex || pagesIndex.length === 0) return null;
+
+    console.log(`\n⏩ 发现已有检查点：${pagesIndex.length} 个页面，尝试断点续跑...`);
+    const visited = new Set<string>();
+    let pageCounter = 0;
+    for (const page of pagesIndex) {
+      const pageId = page.page_id ?? '';
+      if (!pageId) continue;
+      const m = pageId.match(/page_(\d+)/);
+      if (m) pageCounter = Math.max(pageCounter, parseInt(m[1], 10));
+      const viewXmlPath = path.join(this.outputRoot, pageId, 'view.xml');
+      if (fs.existsSync(viewXmlPath)) {
+        const xmlContent = fs.readFileSync(viewXmlPath, 'utf-8');
+        visited.add(pageSignature(page.activity_info ?? {}, xmlContent));
+      }
+    }
+
+    const savedQueue = this.loadQueue();
+    let queue: QueueItem[];
+    if (savedQueue !== null) {
+      queue = savedQueue;
+      console.log(`   队列已从检查点恢复：${queue.length} 个待处理元素（精确续跑）`);
+    } else {
+      queue = this.rebuildQueueFromPages(pagesIndex);
+      console.log(`   队列已重建（fallback）：${queue.length} 个元素（含已探索项，BFS 会自动跳过）`);
+    }
+    const blocked = new Set<string>();
+    console.log(`   已恢复 ${visited.size} 个已访问签名，队列 ${queue.length} 个待处理元素`);
+    return { pagesIndex, visited, pageCounter, queue, blocked };
+  }
+
+  // ── 页面提交 ──
+  private finalizePage(record: PageRecord, pageId: string): void {
+    const pageDir = path.join(this.outputRoot, pageId);
+    const tmpDir = record._tmp_dir!;
+    if (fs.existsSync(tmpDir)) fs.renameSync(tmpDir, pageDir);
+    else fs.mkdirSync(pageDir, { recursive: true });
+
+    record.page_id = pageId;
+    record.screenshot = `${pageId}/screenshot.png`;
+    record.view_xml = `${pageId}/view.xml`;
+
+    const screenshotsList = [`${pageId}/screenshot.png`];
+    for (const ssPath of record._screenshots ?? []) {
+      const ssName = path.basename(ssPath);
+      if (ssName !== 'screenshot.png') screenshotsList.push(`${pageId}/${ssName}`);
+    }
+    record.screenshots = screenshotsList;
+
+    const viewXmlsList = [`${pageId}/view.xml`];
+    for (const xmlPath of record._view_xmls ?? []) {
+      const xmlName = path.basename(xmlPath);
+      if (xmlName !== 'view.xml') viewXmlsList.push(`${pageId}/${xmlName}`);
+    }
+    record.view_xmls = viewXmlsList;
+
+    delete record._tmp_dir;
+    delete record._screenshots;
+    delete record._view_xmls;
+
+    fs.writeFileSync(path.join(pageDir, 'meta.json'), JSON.stringify(record, null, 2), 'utf-8');
+    console.log(`   ✅ 已保存为 [${pageId}]`);
+  }
+
+  private activityNameSuffix(record: PageRecord): string {
+    const resumed = record.activity_info?.['resumed_activity'] ?? '';
+    let mAct = resumed.match(/[\w.]+\/([\w.]+)/);
+    if (!mAct) {
+      const f = record.activity_info?.['current_focus'] ?? '';
+      mAct = f.match(/[\w.]+\/([\w.]+)/);
+    }
+    let activityName = '';
+    if (mAct) {
+      const parts = mAct[1].split('.');
+      activityName = parts[parts.length - 1];
+    }
+    return activityName ? `_${activityName}` : '';
+  }
+
+  commitPage(record: PageRecord): string {
+    this.pageCounter += 1;
+    const suffix = this.activityNameSuffix(record);
+    const pageId = `page_${String(this.pageCounter).padStart(4, '0')}${suffix}`;
+    this.finalizePage(record, pageId);
+    return pageId;
+  }
+
+  commitManualPage(record: PageRecord, pageCounter: number): string {
+    const suffix = this.activityNameSuffix(record);
+    const pageId = `manual_${String(pageCounter).padStart(4, '0')}${suffix}`;
+    this.finalizePage(record, pageId);
+    return pageId;
+  }
+
+  // ── HTML 报告生成 ──
+  generateHtmlReport(pages: PageRecord[]): void {
+    let cards = '';
+    for (const p of pages) {
+      const activity = escapeHtml(p.activity_info?.['current_focus'] ?? 'N/A');
+      const resumed = escapeHtml(p.activity_info?.['resumed_activity'] ?? 'N/A');
+      const clickPath = p.click_path ?? [];
+      let pathDisplay: string;
+      if (clickPath === 'manual') {
+        pathDisplay = `（手动采集：${escapeHtml(p.description ?? '手动采集')}）`;
+      } else if (Array.isArray(clickPath) && clickPath.length > 0) {
+        const longClickTag = '<b class="long-click">长按</b>';
+        pathDisplay = clickPath
+          .map(
+            (s) =>
+              `<code>${escapeHtml(s.from)}</code> ${s['long-clickable'] ? longClickTag : '点击'} <b>${escapeHtml(s.element)}</b>`,
+          )
+          .join(' → ');
+      } else {
+        pathDisplay = '（初始页）';
+      }
+
+      const screenshotPath = escapeHtml(p.screenshot ?? '');
+      const screenshots = p.screenshots ?? [p.screenshot ?? ''];
+      const viewXmls = p.view_xmls ?? [p.view_xml ?? ''];
+      let screenshotsHtml: string;
+      if (screenshots.length > 1) {
+        let pairsHtml = '';
+        screenshots.forEach((ss, idx) => {
+          const xmlLink = idx < viewXmls.length ? viewXmls[idx] : viewXmls[viewXmls.length - 1];
+          const labelTag = idx === 0 ? '初始' : `滚动${idx}`;
+          pairsHtml +=
+            `<div class="scroll-pair">` +
+            `<img src="${escapeHtml(ss)}" alt="screenshot" onerror="this.style.display='none'"/>` +
+            `<a href="${escapeHtml(xmlLink)}" target="_blank">${labelTag} XML</a>` +
+            `</div>`;
+        });
+        screenshotsHtml = `<div class="screenshots-gallery">${pairsHtml}</div>`;
+      } else {
+        screenshotsHtml = `<img src="${escapeHtml(screenshots[0])}" alt="screenshot" onerror="this.style.display='none'"/>`;
+      }
+
+      const labelEscaped = escapeHtml(p.label);
+      const pageIdEscaped = escapeHtml(p.page_id ?? '');
+      const viewXmlEscaped = escapeHtml(p.view_xml ?? '');
+      let xmlLinksHtml: string;
+      if (viewXmls.length > 1) {
+        xmlLinksHtml = viewXmls
+          .map((vx, i) => `<a href="${escapeHtml(vx)}" target="_blank">📄 XML${i === 0 ? '' : `_${i}`}</a>`)
+          .join(' ');
+      } else {
+        xmlLinksHtml = `<a href="${viewXmlEscaped}" target="_blank">📄 查看 View XML</a>`;
+      }
+
+      cards += `
+            <div class="card">
+              <div class="card-header">
+                <span class="pid">${pageIdEscaped}</span>
+                <span class="label">${labelEscaped}</span>
+                <span class="time">${escapeHtml((p.timestamp ?? '').slice(0, 19))}</span>
+              </div>
+              <div class="card-body">
+                ${screenshotsHtml}
+                <div class="meta">
+                  <div><b>Focus:</b> <code>${activity}</code></div>
+                  <div><b>Activity:</b> <code>${resumed}</code></div>
+                  <div><b>点击路径:</b> ${pathDisplay}</div>
+                  <div><b>可点击元素:</b> ${p.clickable_count} 个</div>
+                  <div class="links">
+                    ${xmlLinksHtml}
+                    <a href="${pageIdEscaped}/meta.json" target="_blank">🗂 元数据 JSON</a>
+                  </div>
+                </div>
+              </div>
+            </div>`;
+    }
+
+    const now = new Date();
+    const pad = (x: number): string => String(x).padStart(2, '0');
+    const genTime = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+
+    const html = `<!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>${genTime} &nbsp;|&nbsp;
+  <b>共采集页面：</b>${pages.length} 个
+</div>
+<div class="grid">
+${cards}
+</div>
+</body>
+</html>`;
+
+    fs.writeFileSync(path.join(this.outputRoot, 'report.html'), html, 'utf-8');
+  }
+
+  private flushReport(): void {
+    try {
+      fs.writeFileSync(path.join(this.outputRoot, 'index.json'), JSON.stringify(this.pagesIndex, null, 2), 'utf-8');
+      this.generateHtmlReport(this.pagesIndex);
+      this.saveQueue();
+    } catch (e) {
+      console.log(`  [WARN] 写入报告失败: ${(e as Error).message}`);
+    }
+  }
+
+  crawl(): void {
+    if (!this.adb.checkDevice()) return;
+
+    let activityInfo = this.adb.getCurrentActivity();
+    // 需要干净重启的两种情况：
+    //  1) 不在目标 App 内（原逻辑）。
+    //  2) 在目标 App 内，但前台是弹窗/overlay —— current_focus 无 activity 分量，提取不到启动组件。
+    //     常见于上一轮遍历/续跑结束时停在弹窗上（resumed_activity 仍含包名，会被判定"在 App 内"）。
+    //     此时若不重启，后续所有 force-stop 导航都会因缺少启动信息而中止。
+    const focusHasComponent = focusHasActivityComponent(activityInfo);
+    const notInApp = !this.isInTargetApp(activityInfo);
+    if (notInApp || !focusHasComponent) {
+      if (notInApp) {
+        console.log(`当前不在目标 App (${this.package}) 内，清空数据并启动...`);
+      } else {
+        console.log(
+          `当前前台为弹窗/overlay（${activityInfo['current_focus'] ?? 'N/A'}），force-stop 后重新启动以回到干净根页面...`,
+        );
+      }
+      this.adb.shell(['am', 'force-stop', this.package]);
+      sleep(0.5);
+      this.adb.shell(['monkey', '-p', this.package, '-c', 'android.intent.category.LAUNCHER', '1']);
+      this.adb.waitForIdle();
+      activityInfo = this.adb.getCurrentActivity();
+      if (!this.isInTargetApp(activityInfo)) {
+        console.log(`[ERR] 启动后仍未进入目标 App (${this.package})，请检查包名是否正确`);
+        return;
+      }
+    }
+
+    let launchPackage: string | null = null;
+    let launchActivity: string | null = null;
+    const comp = extractLaunchComponent(activityInfo);
+    if (comp) {
+      [launchPackage, launchActivity] = comp;
+      console.log(`启动 Activity: ${launchPackage}/${launchActivity}`);
+    } else {
+      console.log(
+        `[WARN] 无法提取启动 Activity: focus=${activityInfo['current_focus'] ?? ''} resumed=${activityInfo['resumed_activity'] ?? ''}`,
+      );
+    }
+
+    let rootActivityKeyword: string | null = null;
+    if (launchActivity) {
+      const parts = launchActivity.split('.');
+      rootActivityKeyword = parts[parts.length - 1];
+      console.log(`根 Activity 关键字: ${rootActivityKeyword}`);
+    }
+
+    fs.mkdirSync(this.outputRoot, { recursive: true });
+    console.log(`\n📂 输出目录: ${path.resolve(this.outputRoot)}\n`);
+    console.log('='.repeat(60));
+    console.log('开始遍历（加速版：BFS + 轻量探测）...');
+    console.log('='.repeat(60));
+
+    let rootIdentity: RootIdentity | null = null;
+    const checkpoint = this.tryLoadCheckpoint();
+    if (checkpoint) {
+      this.pagesIndex = checkpoint.pagesIndex;
+      this.visitedSignatures = checkpoint.visited;
+      this.pageCounter = checkpoint.pageCounter;
+      this.queue = checkpoint.queue;
+      this.blockedElements = checkpoint.blocked;
+      console.log(`⏩ 断点续跑：从第 ${this.pageCounter + 1} 个页面继续\n`);
+      for (const p of this.pagesIndex) {
+        if (!p.click_path || (Array.isArray(p.click_path) && p.click_path.length === 0)) {
+          const rootXmlPath = path.join(this.outputRoot, p.page_id!, 'view.xml');
+          if (fs.existsSync(rootXmlPath)) {
+            const rootXml = fs.readFileSync(rootXmlPath, 'utf-8');
+            rootIdentity = rootIdentifiedSet(p.activity_info ?? {}, rootXml);
+          }
+          break;
+        }
+      }
+    } else {
+      const { record, xmlContent, clickable, scrollContainerBounds } = this.capturePage('初始页面');
+      const pageId = this.commitPage(record);
+      record.click_path = [];
+      fs.writeFileSync(path.join(this.outputRoot, pageId, 'meta.json'), JSON.stringify(record, null, 2), 'utf-8');
+      const sig = pageSignature(record.activity_info, xmlContent);
+      rootIdentity = rootIdentifiedSet(record.activity_info, xmlContent);
+      this.visitedSignatures.add(sig);
+      this.pathSignatures[JSON.stringify([])] = sig;
+      this.pagesIndex.push(record);
+      this.flushReport();
+
+      for (const elem of clickable) {
+        if (this.shouldSkipElement(elem)) {
+          this.stats.skipped_elements += 1;
+          continue;
+        }
+        const elemId = PageCrawler.elemIdOf(elem);
+        const si = elem.scroll_index ?? 0;
+        let scrollInfo: ScrollInfo | null = null;
+        if (si > 0 && scrollContainerBounds) scrollInfo = { scroll_index: si, container_bounds: [...scrollContainerBounds] };
+        this.queue.push([[], elemId, [], scrollInfo]);
+      }
+    }
+
+    const failedPaths = new Set<string>();
+    while (this.queue.length > 0 && this.pageCounter < this.maxPages) {
+      const [clickPath, elemId, stepSignatures, scrollInfo] = this.queue.shift()!;
+      const elemKey = JSON.stringify(elemId);
+      if (this.blockedElements.has(elemKey)) continue;
+
+      const pathKey = clickPath.length > 0 ? JSON.stringify(clickPath) : '';
+      let skip = false;
+      for (const fp of failedPaths) {
+        if (pathKey.startsWith(fp) && fp.length > 2) {
+          skip = true;
+          break;
+        }
+      }
+      if (skip) continue;
+
+      const pathDesc = clickPath.length > 0 ? clickPath.map((s) => s.element ?? '?').join(' → ') : '根页面';
+      console.log(`\n🧭 导航到: ${pathDesc}`);
+
+      if (!launchPackage || !launchActivity) {
+        console.log('   [ERR] 无法重启 App，缺少启动信息');
+        continue;
+      }
+
+      if (clickPath.length > 0) {
+        if (!this.navigateViaRestart(clickPath, launchPackage, launchActivity, rootActivityKeyword, stepSignatures, rootIdentity)) {
+          console.log('   [ERR] 导航失败，跳过');
+          failedPaths.add(pathKey);
+          continue;
+        }
+      } else {
+        if (!this.restartToRoot(launchPackage, launchActivity, rootActivityKeyword, rootIdentity)) {
+          console.log('   [ERR] 无法回到根页面，跳过');
+          continue;
+        }
+      }
+
+      let freshXml = this.adb.dumpXmlQuick();
+      if (scrollInfo && scrollInfo.scroll_index > 0) {
+        console.log(`   📜 滚动 ${scrollInfo.scroll_index} 次到达元素位置`);
+        this.adb.scrollToPosition(scrollInfo.container_bounds as [number, number, number, number], scrollInfo.scroll_index);
+        freshXml = this.adb.dumpXmlQuick();
+      }
+
+      const foundElem = findElementOnScreen(freshXml, elemId);
+      if (!foundElem || !foundElem.center) {
+        console.log(`   [SKIP] 无法找到元素: ${JSON.stringify(elemId.slice(0, 3))}`);
+        continue;
+      }
+
+      const center = foundElem.center;
+      const labelText = foundElem.text || foundElem['content-desc'] || foundElem['resource-id'] || 'unknown';
+      console.log(`\n👆 点击: [${labelText}] @ ${JSON.stringify(center)}`);
+      const isLong = foundElem['long-clickable'] ?? false;
+      if (isLong) console.log('   🔁 使用长按触发');
+      this.adb.tapOrLongPress(center[0], center[1], isLong);
+
+      const probeXml = this.adb.dumpXmlQuick();
+      const probeInfo = this.adb.getCurrentActivity();
+      let newSig = pageSignature(probeInfo, probeXml);
+
+      if (!this.isInTargetApp(probeInfo)) {
+        console.log('   ⚠️  跳转到其他 App，标记并跳过');
+        this.blockedElements.add(elemKey);
+        continue;
+      }
+      if (this.visitedSignatures.has(newSig)) {
+        console.log('   ♻️  页面已访问过，跳过（省截图）');
+        this.stats.probe_skipped += 1;
+        continue;
+      }
+
+      const { record: newRecord, xmlContent: newXml, clickable: newClickable, scrollContainerBounds: newScrollBounds } =
+        this.capturePage(`点击'${labelText}'后`);
+      newSig = pageSignature(newRecord.activity_info, newXml);
+      this.visitedSignatures.add(newSig);
+      const pageId = this.commitPage(newRecord);
+
+      const newClickPath: ClickStep[] = [
+        ...clickPath,
+        {
+          from: pathDesc,
+          element: labelText,
+          center: [...center],
+          'resource-id': foundElem['resource-id'] ?? '',
+          text: foundElem.text ?? '',
+          'content-desc': foundElem['content-desc'] ?? '',
+          'long-clickable': isLong,
+          scroll_info: scrollInfo,
+        },
+      ];
+      newRecord.came_from = pathDesc;
+      newRecord.trigger_element = labelText;
+      newRecord.click_path = newClickPath;
+      fs.writeFileSync(path.join(this.outputRoot, pageId, 'meta.json'), JSON.stringify(newRecord, null, 2), 'utf-8');
+      this.pagesIndex.push(newRecord);
+      this.flushReport();
+
+      this.pathSignatures[JSON.stringify(newClickPath)] = newSig;
+      const newStepSigs = [...stepSignatures, newSig];
+
+      for (const ne of newClickable) {
+        if (this.shouldSkipElement(ne)) {
+          this.stats.skipped_elements += 1;
+          continue;
+        }
+        const newEid = PageCrawler.elemIdOf(ne);
+        const si = ne.scroll_index ?? 0;
+        let neScrollInfo: ScrollInfo | null = null;
+        if (si > 0 && newScrollBounds) neScrollInfo = { scroll_index: si, container_bounds: [...newScrollBounds] };
+        this.queue.push([newClickPath, newEid, newStepSigs, neScrollInfo]);
+      }
+    }
+
+    this.adb.flushPendingPulls();
+    this.flushReport();
+    try {
+      fs.rmSync(path.join(this.outputRoot, 'queue_checkpoint.json'), { force: true });
+    } catch {
+      /* ignore */
+    }
+
+    console.log('\n' + '='.repeat(60));
+    console.log(`✅ 遍历完成！共采集 ${this.pagesIndex.length} 个页面`);
+    console.log(`📂 输出目录: ${path.resolve(this.outputRoot)}`);
+    console.log(`📋 索引文件: ${path.join(this.outputRoot, 'index.json')}`);
+    console.log(`🌐 HTML报告: ${path.join(this.outputRoot, 'report.html')}`);
+    console.log('\n📊 加速统计:');
+    console.log(`   过滤低价值元素: ${this.stats.skipped_elements} 个`);
+    console.log(`   轻量探测跳过（省截图）: ${this.stats.probe_skipped} 次`);
+    console.log('='.repeat(60));
+  }
+
+  async manualCrawl(): Promise<void> {
+    if (!this.adb.checkDevice()) return;
+    fs.mkdirSync(this.outputRoot, { recursive: true });
+
+    let pagesIndex: PageRecord[] = [];
+    const indexFile = path.join(this.outputRoot, 'index.json');
+    if (fs.existsSync(indexFile)) {
+      try {
+        pagesIndex = JSON.parse(fs.readFileSync(indexFile, 'utf-8')) as PageRecord[];
+        console.log(`📂 已加载 ${pagesIndex.length} 个已有页面`);
+      } catch (e) {
+        console.log(`[WARN] 读取 index.json 失败: ${(e as Error).message}，将创建新索引`);
+      }
+    }
+
+    let manualCounter = 0;
+    for (const p of pagesIndex) {
+      const mm = (p.page_id ?? '').match(/manual_(\d+)/);
+      if (mm) manualCounter = Math.max(manualCounter, parseInt(mm[1], 10));
+    }
+
+    console.log(`\n📂 输出目录: ${path.resolve(this.outputRoot)}`);
+    console.log(`📝 手动采集模式已启动（manual 编号从 ${manualCounter + 1} 开始）`);
+    console.log('='.repeat(60));
+    console.log('操作说明：');
+    console.log('  1. 在设备上手动导航到目标页面');
+    console.log('  2. 输入页面描述（如"设置页 > 关于"），然后按回车开始采集');
+    console.log('  3. 输入 q 退出');
+    console.log('='.repeat(60));
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const question = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+    try {
+      for (;;) {
+        console.log();
+        let desc = (await question('📝 输入页面描述（q 退出）: ')).trim();
+        if (desc.toLowerCase() === 'q') {
+          console.log('👋 退出手动采集模式');
+          break;
+        }
+        if (!desc) desc = '手动采集';
+        manualCounter += 1;
+        const { record } = this.capturePage(desc);
+        record.click_path = 'manual';
+        record.description = desc;
+        this.commitManualPage(record, manualCounter);
+        pagesIndex.push(record);
+        fs.writeFileSync(indexFile, JSON.stringify(pagesIndex, null, 2), 'utf-8');
+        this.pagesIndex = pagesIndex;
+        this.generateHtmlReport(pagesIndex);
+        console.log(`   📋 index.json 和 report.html 已更新（共 ${pagesIndex.length} 个页面）`);
+      }
+    } finally {
+      rl.close();
+    }
+    console.log(`\n✅ 手动采集完成！共 ${pagesIndex.length} 个页面（含自动遍历）`);
+    console.log(`📂 输出目录: ${path.resolve(this.outputRoot)}`);
+  }
+}
+
+// ─────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────
+interface CliArgs {
+  package: string;
+  output: string;
+  manual: boolean;
+  device: string;
+  adbPath: string;
+  maxPages: number;
+  maxScrolls: number;
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      'Android 模拟器页面遍历工具（加速版）',
+      '',
+      'Usage: node android_parse_fast.ts --package <pkg> --output <dir> [options]',
+      '',
+      '  --package, -p    目标 App 包名（必选）',
+      '  --output, -o     输出目录（必选）',
+      '  --manual         手动采集模式：手动导航到页面后按回车触发采集',
+      `  --device         ADB 设备 serial（默认: ${DEVICE_SERIAL_DEFAULT}）`,
+      `  --adb-path       adb 可执行文件路径（默认: ${ADB_PATH_DEFAULT}）`,
+      `  --max-pages      最多遍历页面数（默认: ${MAX_PAGES_DEFAULT}）`,
+      `  --max-scrolls    每个可滚动容器最多滚动次数（默认: ${MAX_SCROLLS_DEFAULT}）`,
+    ].join('\n'),
+  );
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    package: '',
+    output: '',
+    manual: false,
+    device: DEVICE_SERIAL_DEFAULT,
+    adbPath: ADB_PATH_DEFAULT,
+    maxPages: MAX_PAGES_DEFAULT,
+    maxScrolls: MAX_SCROLLS_DEFAULT,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = (): string => {
+      if (i + 1 >= argv.length) {
+        console.error(`Missing value for ${a}`);
+        process.exit(2);
+      }
+      return argv[++i];
+    };
+    if (a === '--package' || a === '-p') args.package = next();
+    else if (a === '--output' || a === '-o') args.output = next();
+    else if (a === '--manual') args.manual = true;
+    else if (a === '--device') args.device = next();
+    else if (a === '--adb-path') args.adbPath = next();
+    else if (a === '--max-pages') args.maxPages = parseInt(next(), 10);
+    else if (a === '--max-scrolls') args.maxScrolls = parseInt(next(), 10);
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+  if (!args.package) {
+    console.error('error: --package/-p is required');
+    process.exit(2);
+  }
+  if (!args.output) {
+    console.error('error: --output/-o is required');
+    process.exit(2);
+  }
+  return args;
+}
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  const adb = new ADBHelper({ adbPath: args.adbPath, deviceSerial: args.device, targetPackage: args.package });
+  const crawler = new PageCrawler({
+    adb,
+    package: args.package,
+    outputDir: args.output,
+    maxPages: args.maxPages,
+    maxScrolls: args.maxScrolls,
+  });
+  if (args.manual) await crawler.manualCrawl();
+  else crawler.crawl();
+  return 0;
+}
+
+const isEntry = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntry) {
+  main().then(
+    (code) => process.exit(code),
+    (err) => {
+      console.error(err instanceof Error ? err.message : err);
+      process.exit(1);
+    },
+  );
+}
+
+export {
+  parseXml,
+  iterNodes,
+  parseBoundsCenter,
+  getClickableElements,
+  extractNodeKeys,
+  findScrollableContainers,
+  normalizeComponent,
+  stableActivityKey,
+  pageSignature,
+  rootIdentifiedSet,
+  isSameRootPage,
+  findElementOnScreen,
+  focusHasActivityComponent,
+  extractLaunchComponent,
+  PageCrawler,
+  ADBHelper,
+};
+
+
+
+