android2harmony 0.1.4 → 0.1.5

package/skills/{hmos-batch-ui-align/scripts/android_parse_fast.ts → a2h-ui-transfer/scripts/android_parse_fast.js}

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 /**
- * Android 模拟器页面遍历工具（加速版, TypeScript 版）
+ * Android 模拟器页面遍历工具（加速版）
  * 功能：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]
+ *   node android_parse_fast.js --package <pkg> --output <dir> [--device serial] [--adb-path adb]
+ *                              [--max-pages 500] [--max-scrolls 10] [--manual] [--page "<描述>"]
  */
 
-import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import { spawnSync, } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
@@ -37,7 +37,7 @@ const SKIP_RESOURCE_ID_PATTERNS_DEFAULT = [
 ];
 const HORIZONTAL_SCROLL_CLASSES = new Set(['android.widget.HorizontalScrollView']);
 
-function sleep(seconds: number): void {
+function sleep(seconds) {
   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()));
@@ -46,16 +46,16 @@ function sleep(seconds: number): void {
 // ─────────────────────────────────────────────
 // 最小 XML 解析器（等价 xml.etree 的 root.iter("node") + get 属性）
 // ─────────────────────────────────────────────
-interface XmlNode {
-  tag: string;
-  attrs: Record<string, string>;
-  children: XmlNode[];
-}
+// interface XmlNode {
+  // tag: string;
+  // attrs: Record<string, string>;
+  // children: XmlNode[];
+// }
 
-const XML_ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const XML_ENTITIES = { 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) => {
+function decodeEntities(s) {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, ent) => {
     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);
@@ -66,16 +66,16 @@ function decodeEntities(s: string): string {
 
 class XmlParseError extends Error {}
 
-function parseXml(xml: string): XmlNode {
+function parseXml(xml) {
   let i = 0;
   const n = xml.length;
-  const stack: XmlNode[] = [];
-  let root: XmlNode | null = null;
+  const stack = [];
+  let root = null;
 
-  const readAttrs = (raw: string): Record<string, string> => {
-    const attrs: Record<string, string> = {};
+  const readAttrs = (raw) => {
+    const attrs = {};
     const re = /([^\s=/>]+)\s*=\s*"([^"]*)"|([^\s=/>]+)\s*=\s*'([^']*)'/g;
-    let m: RegExpExecArray | null;
+    let m;
     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]);
@@ -106,7 +106,7 @@ function parseXml(xml: string): XmlNode {
       continue;
     }
     let j = i + 1;
-    let quote: string | null = null;
+    let quote = null;
     for (; j < n; j++) {
       const c = xml[j];
       if (quote) {
@@ -126,7 +126,7 @@ function parseXml(xml: string): XmlNode {
     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: [] };
+    const node = { 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);
@@ -135,16 +135,16 @@ function parseXml(xml: string): XmlNode {
   return root;
 }
 
-function* iterNodes(root: XmlNode, tag: string): Generator<XmlNode> {
+function* iterNodes(root, tag) {
   if (root.tag === tag) yield root;
   for (const child of root.children) yield* iterNodes(child, tag);
 }
 
-function attr(node: XmlNode, key: string, dflt = ''): string {
+function attr(node, key, dflt = '') {
   return key in node.attrs ? node.attrs[key] : dflt;
 }
 
-function extractInts(s: string): number[] {
+function extractInts(s) {
   const m = s.match(/\d+/g);
   return m ? m.map((x) => parseInt(x, 10)) : [];
 }
@@ -152,24 +152,24 @@ function extractInts(s: string): number[] {
 // ─────────────────────────────────────────────
 // 元素/签名 纯函数（等价 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 {
+// 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) {
   const nums = extractInts(bounds);
   if (nums.length === 4) {
     const [x1, y1, x2, y2] = nums;
@@ -178,18 +178,18 @@ function parseBoundsCenter(bounds: string): [number, number] | null {
   return null;
 }
 
-function getClickableElements(xmlContent: string): ClickableElement[] {
-  const elements: ClickableElement[] = [];
+function getClickableElements(xmlContent) {
+  const elements = [];
   if (!xmlContent) return elements;
-  let root: XmlNode;
+  let root;
   try {
     root = parseXml(xmlContent);
   } catch (e) {
-    console.log(`  [WARN] XML 解析失败: ${(e as Error).message}`);
+    console.log(`  [WARN] XML 解析失败: ${(e).message}`);
     return elements;
   }
 
-  const listviewChildSet = new Set<XmlNode>();
+  const listviewChildSet = new Set();
   for (const node of iterNodes(root, 'node')) {
     const cls = attr(node, 'class');
     if (cls.includes('ListView') || cls.includes('GridView')) {
@@ -197,7 +197,7 @@ function getClickableElements(xmlContent: string): ClickableElement[] {
     }
   }
 
-  const extractText = (node: XmlNode): string => {
+  const extractText = (node) => {
     const t = attr(node, 'text');
     if (t) return t;
     for (const child of iterNodes(node, 'node')) {
@@ -231,10 +231,10 @@ function getClickableElements(xmlContent: string): ClickableElement[] {
   return elements;
 }
 
-function extractNodeKeys(xmlContent: string): Set<string> {
-  const keys = new Set<string>();
+function extractNodeKeys(xmlContent) {
+  const keys = new Set();
   if (!xmlContent) return keys;
-  let root: XmlNode;
+  let root;
   try {
     root = parseXml(xmlContent);
   } catch {
@@ -248,16 +248,16 @@ function extractNodeKeys(xmlContent: string): Set<string> {
   return keys;
 }
 
-function setsEqual(a: Set<string>, b: Set<string>): boolean {
+function setsEqual(a, b) {
   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[] = [];
+function findScrollableContainers(xmlContent) {
+  const containers = [];
   if (!xmlContent) return containers;
-  let root: XmlNode;
+  let root;
   try {
     root = parseXml(xmlContent);
   } catch {
@@ -279,7 +279,7 @@ function findScrollableContainers(xmlContent: string): ScrollContainer[] {
   return containers;
 }
 
-function normalizeComponent(component: string): string {
+function normalizeComponent(component) {
   if (!component.includes('/')) return component;
   const idx = component.indexOf('/');
   const pkg = component.slice(0, idx);
@@ -288,7 +288,7 @@ function normalizeComponent(component: string): string {
   return `${pkg}/${cls}`;
 }
 
-function stableActivityKey(activityInfo: Record<string, string>): string {
+function stableActivityKey(activityInfo) {
   const focus = activityInfo['current_focus'] ?? '';
   const resumed = activityInfo['resumed_activity'] ?? '';
   const m = focus.match(/[\w.]+\/[\w.]+/);
@@ -300,7 +300,7 @@ function stableActivityKey(activityInfo: Record<string, string>): string {
   return `${actPart}|${winType}`;
 }
 
-function pageSignature(activityInfo: Record<string, string>, xmlContent: string): string {
+function pageSignature(activityInfo, xmlContent) {
   const actKey = stableActivityKey(activityInfo);
   if (!xmlContent) return `${actKey}|empty`;
   const clickable = getClickableElements(xmlContent);
@@ -313,15 +313,15 @@ function pageSignature(activityInfo: Record<string, string>, xmlContent: string)
   return `${actKey}|${featureHash}`;
 }
 
-type RootIdentity = [string, Set<string>];
+// type RootIdentity = [string, Set<string>];
 
-function rootIdentifiedSet(activityInfo: Record<string, string>, xmlContent: string): RootIdentity {
+function rootIdentifiedSet(activityInfo, xmlContent) {
   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>();
+  const elems = new Set();
   for (const e of clickable) {
     const desc = e['content-desc'] ?? '';
     const rid = e['resource-id'] ?? '';
@@ -331,7 +331,7 @@ function rootIdentifiedSet(activityInfo: Record<string, string>, xmlContent: str
   return [actKey, elems];
 }
 
-function isSameRootPage(rootInfo: RootIdentity, currentInfo: RootIdentity, threshold = 0.6): boolean {
+function isSameRootPage(rootInfo, currentInfo, threshold = 0.6) {
   const [rootAct, rootElems] = rootInfo;
   const [curAct, curElems] = currentInfo;
   if (rootAct !== curAct) return false;
@@ -344,7 +344,7 @@ function isSameRootPage(rootInfo: RootIdentity, currentInfo: RootIdentity, thres
 }
 
 /** current_focus 是否含 `package/activity` 分量（弹窗/overlay 焦点没有）。 */
-function focusHasActivityComponent(activityInfo: Record<string, string>): boolean {
+function focusHasActivityComponent(activityInfo) {
   return /[\w.]+\/[\w.]+/.test(activityInfo['current_focus'] ?? '');
 }
 
@@ -353,7 +353,7 @@ function focusHasActivityComponent(activityInfo: Record<string, string>): boolea
  * 优先 current_focus（通常是全限定 Activity），回退 resumed_activity（可能是相对名 `.ui.Main`，
  * am start 同样接受）。都取不到返回 null。
  */
-function extractLaunchComponent(activityInfo: Record<string, string>): [string, string] | null {
+function extractLaunchComponent(activityInfo) {
   for (const key of ['current_focus', 'resumed_activity']) {
     const s = activityInfo[key] ?? '';
     const m = s.match(/([\w.]+)\/([\w.]+)/);
@@ -362,14 +362,14 @@ function extractLaunchComponent(activityInfo: Record<string, string>): [string,
   return null;
 }
 
-type ElemId = [string, string, string, string, boolean];
+// type ElemId = [string, string, string, string, boolean];
 
-function findElementOnScreen(xmlContent: string, elemId: ElemId | [string, string, string, string]): ClickableElement | null {
+function findElementOnScreen(xmlContent, elemId) {
   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 isLong = elemId.length >= 5 ? (elemId[4]) : null;
   const clickableElements = getClickableElements(xmlContent);
 
   if (bounds) {
@@ -398,28 +398,55 @@ function findElementOnScreen(xmlContent: string, elemId: ElemId | [string, strin
   return null;
 }
 
+// ─────────────────────────────────────────────
+// 设备常量：密度与物理分辨率
+// ─────────────────────────────────────────────
+/**
+ * 采集设备的密度与分辨率 —— 每页写进 meta.json 的 `device` 字段。
+ *
+ * 为什么必须在采集期记：密度是「同一台设备上每页同值」的常量，而下游 measure_pack.js
+ * 只能拿 view tree 里正方形节点的边长去**反解**它。反解在数学上不唯一 —— 72px 既能解释成
+ * 24dp@3.0，也能解释成 36dp@2.0 / 48dp@1.5，整个谐波族全部自洽；工具栏图标尺寸单一的页面
+ * 更是必然平局。一旦解错，该页所有 vp 数值整体差 2~3 倍，而编译、引用检查、跨页一致性
+ * 全都照样通过（因为每页错得一样）。`wm density` 一行就能拿到真值，采集期不记 = 主动丢弃它。
+ */
+// interface DeviceInfo {
+  // /** 生效 dpi（覆盖优先）。取不到为 null。 */
+  // dpi: number | null;
+  // /** dpi / 160，即 ArkUI 侧 px→vp 的换算系数。取不到为 null。 */
+  // density: number | null;
+  // /** 密度取自哪条来源，便于复核。 */
+  // density_source: 'wm density (override)' | 'wm density (physical)' | 'unavailable';
+  // width_px: number | null;
+  // height_px: number | null;
+  // /** 原始输出，供人工核对（`wm density` 改过的设备两行值不同）。 */
+  // raw: { wm_density: string; wm_size: string };
+// }
+
 // ─────────────────────────────────────────────
 // ADBHelper：封装所有 ADB 设备通信与交互操作
 // ─────────────────────────────────────────────
 class ADBHelper {
-  adbPath: string;
-  deviceSerial: string | null;
-  idlePollInterval: number;
-  idleTimeout: number;
-  scrollDurationMs: number;
+  adbPath;
+  deviceSerial;
+  idlePollInterval;
+  idleTimeout;
+  scrollDurationMs;
   /** 目标 App 包名；多屏设备（车机等）上用于从多条 focus/resumed 行中挑出正确的那条。 */
-  targetPackage: string | null;
+  targetPackage;
   /** 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;
-  } = {}) {
+   cachedPhysicalDisplayId = undefined;
+  /** 设备密度/分辨率缓存；整轮遍历只查一次（密度不会中途变）。 */
+   cachedDeviceInfo = 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;
@@ -428,25 +455,25 @@ class ADBHelper {
     this.scrollDurationMs = opts.scrollDurationMs ?? SCROLL_DURATION_MS_DEFAULT;
   }
 
-  private buildArgs(args: string[]): string[] {
-    const full: string[] = [];
+   buildArgs(args) {
+    const full = [];
     if (this.deviceSerial) full.push('-s', this.deviceSerial);
     full.push(...args);
     return full;
   }
 
-  private spawn(args: string[], timeout: number, binary: boolean): SpawnSyncReturns<Buffer> {
+   spawn(args, timeout, binary) {
     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 {
+  run(args, timeout = 15) {
     const res = this.spawn(args, timeout, false);
     if (res.error) {
-      const code = (res.error as NodeJS.ErrnoException).code;
+      const code = (res.error).code;
       if (code === 'ETIMEDOUT') {
         console.log(`  [WARN] adb 命令超时: ${args.join(' ')}`);
         return '';
@@ -459,13 +486,49 @@ class ADBHelper {
     return out.toString('utf-8').trim();
   }
 
-  shell(args: string[], timeout = 15): string {
+  shell(args, timeout = 15) {
     return this.run(['shell', ...args], timeout);
   }
 
-  waitForIdle(): void {
+  /**
+   * 读取设备密度与物理分辨率（整轮只查一次，结果缓存）。
+   *
+   * 覆盖密度（`wm density N` 改过的设备）**优先于**物理密度 —— UI 实际按覆盖值布局，
+   * 拿物理值去换算会得到一套系统性偏移的 vp。
+   */
+  deviceInfo() {
+    if (this.cachedDeviceInfo !== undefined) return this.cachedDeviceInfo;
+    const densRaw = this.shell(['wm', 'density']);
+    const sizeRaw = this.shell(['wm', 'size']);
+    const ovD = /Override density:\s*(\d+)/.exec(densRaw);
+    const phD = /Physical density:\s*(\d+)/.exec(densRaw);
+    const dpi = ovD ? Number(ovD[1]) : phD ? Number(phD[1]) : null;
+    const ovS = /Override size:\s*(\d+)x(\d+)/.exec(sizeRaw);
+    const phS = /Physical size:\s*(\d+)x(\d+)/.exec(sizeRaw);
+    const sz = ovS ?? phS;
+    const info = {
+      dpi,
+      density: dpi ? Math.round((dpi / 160) * 1000) / 1000 : null,
+      density_source: dpi === null
+        ? 'unavailable'
+        : ovD ? 'wm density (override)' : 'wm density (physical)',
+      width_px: sz ? Number(sz[1]) : null,
+      height_px: sz ? Number(sz[2]) : null,
+      raw: { wm_density: densRaw, wm_size: sizeRaw },
+    };
+    if (info.density === null) {
+      console.log('  [WARN] `wm density` 未返回可解析的密度，下游 measure_pack 只能反解（结果可能不唯一）');
+    } else {
+      console.log(`   设备密度: ${info.density} (${info.dpi}dpi, ${info.density_source})`
+        + (info.width_px ? `  分辨率 ${info.width_px}x${info.height_px}` : ''));
+    }
+    this.cachedDeviceInfo = info;
+    return info;
+  }
+
+  waitForIdle() {
     const deadline = Date.now() + this.idleTimeout * 1000;
-    let prevFocus: string | null = null;
+    let prevFocus = null;
     let interval = this.idlePollInterval;
     while (Date.now() < deadline) {
       sleep(interval);
@@ -486,7 +549,7 @@ class ADBHelper {
     console.log(`  [WARN] 等待 UI 空闲超时 (${this.idleTimeout}s)，继续执行`);
   }
 
-  checkDevice(): boolean {
+  checkDevice() {
     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'));
@@ -516,30 +579,30 @@ class ADBHelper {
    * launcher。因此不能取第一条就 break：优先取包含目标包名的那条，
    * 其次取任意带 `pkg/activity` 组件名的非 null 行，最后兜底第一条。
    */
-  private pickBestLine(lines: string[]): string | undefined {
+   pickBestLine(lines) {
     if (lines.length === 0) return undefined;
     if (this.targetPackage) {
-      const hit = lines.find((l) => l.includes(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> = {};
+  getCurrentActivity() {
+    const info = {};
     const actOut = this.shell(['dumpsys', 'activity', 'activities']);
     const winOut = this.shell(['dumpsys', 'window']);
 
-    const resumedLines: string[] = [];
+    const resumedLines = [];
     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[] = [];
+    const focusLines = [];
+    const focusedAppLines = [];
     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());
@@ -552,27 +615,27 @@ class ADBHelper {
     return info;
   }
 
-  tap(x: number, y: number): void {
+  tap(x, y) {
     this.shell(['input', 'tap', String(x), String(y)]);
     this.waitForIdle();
   }
 
-  longPress(x: number, y: number, durationMs = 1000): void {
+  longPress(x, y, durationMs = 1000) {
     this.shell(['input', 'swipe', String(x), String(y), String(x), String(y), String(durationMs)]);
     this.waitForIdle();
   }
 
-  tapOrLongPress(x: number, y: number, isLongClick = false): void {
+  tapOrLongPress(x, y, isLongClick = false) {
     if (isLongClick) this.longPress(x, y);
     else this.tap(x, y);
   }
 
-  pressBack(): void {
+  pressBack() {
     this.shell(['input', 'keyevent', 'KEYCODE_BACK']);
     this.waitForIdle();
   }
 
-  dumpXmlQuick(): string {
+  dumpXmlQuick() {
     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++) {
@@ -583,7 +646,7 @@ class ADBHelper {
     return this.shell(['cat', remotePath], 15);
   }
 
-  getViewXmlFast(pageDir: string): string {
+  getViewXmlFast(pageDir) {
     const xmlContent = this.dumpXmlQuick();
     if (xmlContent) fs.writeFileSync(path.join(pageDir, 'view.xml'), xmlContent, 'utf-8');
     return xmlContent;
@@ -601,14 +664,14 @@ class ADBHelper {
    *   → dumpsys display 里用 `displayId N,` 所在行的 uniqueId "local:<physId>" 取物理 id。
    * 单屏设备解析失败时返回 null，退回不带 -d 的老行为（此时也不会有警告）。
    */
-  private resolveTargetPhysicalDisplayId(): string | null {
+   resolveTargetPhysicalDisplayId() {
     if (this.cachedPhysicalDisplayId !== undefined) return this.cachedPhysicalDisplayId;
-    let result: string | null = null;
+    let result = null;
     try {
       if (this.targetPackage) {
         const actOut = this.shell(['dumpsys', 'activity', 'activities']);
-        let curDisplay: string | null = null;
-        let logicalId: string | null = null;
+        let curDisplay = null;
+        let logicalId = null;
         for (const line of actOut.split(/\r?\n/)) {
           const m = line.match(/^Display #(\d+)/);
           if (m) curDisplay = m[1];
@@ -638,7 +701,7 @@ class ADBHelper {
     return result;
   }
 
-  screencapBytes(): Buffer | null {
+  screencapBytes() {
     const physId = this.resolveTargetPhysicalDisplayId();
     const capArgs = physId
       ? ['exec-out', 'screencap', '-d', physId, '-p']
@@ -647,8 +710,8 @@ class ADBHelper {
       timeout: 15 * 1000,
       maxBuffer: 128 * 1024 * 1024,
       windowsHide: true,
-    }) as SpawnSyncReturns<Buffer>;
-    if (res.error && (res.error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+    });
+    if (res.error && (res.error).code === 'ETIMEDOUT') {
       console.log('  [WARN] 截图超时');
       return null;
     }
@@ -664,7 +727,7 @@ class ADBHelper {
     return at === 0 ? out : out.subarray(at);
   }
 
-  takeScreenshot(pageDir: string): void {
+  takeScreenshot(pageDir) {
     const localPath = path.join(pageDir, 'screenshot.png');
     const data = this.screencapBytes();
     if (data) {
@@ -680,7 +743,7 @@ class ADBHelper {
     }
   }
 
-  scrollToPosition(containerBounds: [number, number, number, number], scrollIndex: number): void {
+  scrollToPosition(containerBounds, scrollIndex) {
     if (scrollIndex <= 0) return;
     const [x1, y1, , y2] = containerBounds;
     const x2 = containerBounds[2];
@@ -694,7 +757,7 @@ class ADBHelper {
     }
   }
 
-  flushPendingPulls(): void {
+  flushPendingPulls() {
     // TS 版截图为同步写入，无异步 pull 队列，保留空实现以对齐调用点。
   }
 }
@@ -702,44 +765,46 @@ class ADBHelper {
 // ─────────────────────────────────────────────
 // 队列项 / 记录类型
 // ─────────────────────────────────────────────
-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 {
+// 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;
+  // /** 采集设备的密度/分辨率真值；measure_pack.js 优先采用，避免反解歧义。 */
+  // device?: DeviceInfo;
+  // 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) {
   return s
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
@@ -752,30 +817,30 @@ function escapeHtml(s: string): string {
 // PageCrawler：UI 遍历逻辑、页面采集、断点续跑、报告生成
 // ─────────────────────────────────────────────
 class PageCrawler {
-  adb: ADBHelper;
-  package: string;
-  outputRoot: string;
-  maxPages: number;
-  maxScrolls: number;
-  skipPatterns: string[];
+  adb;
+  package;
+  outputRoot;
+  maxPages;
+  maxScrolls;
+  skipPatterns;
 
   // 运行时状态
-  pagesIndex: PageRecord[] = [];
-  visitedSignatures = new Set<string>();
-  pathSignatures: Record<string, string> = {};
-  blockedElements = new Set<string>();
-  queue: QueueItem[] = [];
+  pagesIndex = [];
+  visitedSignatures = new Set();
+  pathSignatures = {};
+  blockedElements = new Set();
+  queue = [];
   pageCounter = 0;
   stats = { skipped_elements: 0, probe_skipped: 0 };
 
-  constructor(opts: {
-    adb: ADBHelper;
-    package: string;
-    outputDir: string;
-    maxPages?: number;
-    maxScrolls?: number;
-    skipPatterns?: string[];
-  }) {
+  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;
@@ -784,7 +849,7 @@ class PageCrawler {
     this.skipPatterns = opts.skipPatterns ?? SKIP_RESOURCE_ID_PATTERNS_DEFAULT;
   }
 
-  static elemIdOf(elem: ClickableElement): ElemId {
+  static elemIdOf(elem) {
     return [
       elem['resource-id'] ?? '',
       elem.text ?? '',
@@ -794,7 +859,7 @@ class PageCrawler {
     ];
   }
 
-  shouldSkipElement(elem: ClickableElement): boolean {
+  shouldSkipElement(elem) {
     const rid = elem['resource-id'] ?? '';
     const text = elem.text ?? '';
     const desc = elem['content-desc'] ?? '';
@@ -804,7 +869,7 @@ class PageCrawler {
     return false;
   }
 
-  isInTargetApp(activityInfo: Record<string, string>): boolean {
+  isInTargetApp(activityInfo) {
     const focus = activityInfo['current_focus'] ?? '';
     const resumed = activityInfo['resumed_activity'] ?? '';
     console.log(focus, resumed);
@@ -812,10 +877,10 @@ class PageCrawler {
   }
 
   scrollAndDump(
-    pageDir: string,
-    containerBounds: [number, number, number, number],
+    pageDir,
+    containerBounds,
     initialXml = '',
-  ): { xmlList: string[]; xmlPaths: string[]; screenshotPaths: string[] } {
+  ) {
     const [x1, y1, , y2b] = containerBounds;
     const x2 = containerBounds[2];
     const y2 = y2b;
@@ -824,10 +889,10 @@ class PageCrawler {
     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;
+    const xmlList = [];
+    const xmlPaths = [];
+    const screenshotPaths = [];
+    let prevKeys = 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)]);
@@ -854,12 +919,12 @@ class PageCrawler {
     return { xmlList, xmlPaths, screenshotPaths };
   }
 
-  capturePage(label: string): {
-    record: PageRecord;
-    xmlContent: string;
-    clickable: ClickableElement[];
-    scrollContainerBounds: [number, number, number, number] | null;
-  } {
+  capturePage(label)
+    // 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 });
@@ -890,8 +955,8 @@ class PageCrawler {
       }
     }
 
-    const seenClickable = new Set<string>();
-    const clickable: ClickableElement[] = [];
+    const seenClickable = new Set();
+    const clickable = [];
     allXmlContents.forEach((xc, idx) => {
       for (const elem of getClickableElements(xc)) {
         const key = [
@@ -912,10 +977,11 @@ class PageCrawler {
     console.log(`   可点击元素: ${clickable.length} 个`);
 
     const scrollContainerBounds = scrollContainers.length > 0 ? scrollContainers[0].bounds : null;
-    const record: PageRecord = {
+    const record = {
       page_id: null,
       label,
       timestamp: new Date().toISOString(),
+      device: this.adb.deviceInfo(),
       activity_info: actInfo,
       clickable_count: clickable.length,
       clickable_elements: clickable,
@@ -928,18 +994,18 @@ class PageCrawler {
   }
 
   restartToRoot(
-    launchPackage: string | null,
-    launchActivity: string | null,
-    rootActivityKeyword: string | null = null,
-    rootIdentity: RootIdentity | null = null,
-  ): boolean {
+    launchPackage,
+    launchActivity,
+    rootActivityKeyword = null,
+    rootIdentity = null,
+  ) {
     if (!launchPackage || !launchActivity) {
       console.log('   [WARN] 包名或 Activity 名为空，无法重启');
       return false;
     }
     const component = `${launchPackage}/${launchActivity}`;
 
-    const isAtRoot = (): boolean => {
+    const isAtRoot = () => {
       const activityInfo = this.adb.getCurrentActivity();
       const focus = activityInfo['current_focus'] ?? '';
       const resumed = activityInfo['resumed_activity'] ?? '';
@@ -984,13 +1050,13 @@ class PageCrawler {
   }
 
   navigateViaRestart(
-    clickPath: ClickStep[],
-    launchPackage: string | null,
-    launchActivity: string | null,
-    rootActivityKeyword: string | null = null,
-    stepSignatures: string[] | null = null,
-    rootIdentity: RootIdentity | null = null,
-  ): boolean {
+    clickPath,
+    launchPackage,
+    launchActivity,
+    rootActivityKeyword = null,
+    stepSignatures = null,
+    rootIdentity = null,
+  ) {
     if (!launchPackage || !launchActivity) {
       console.log('   [WARN] 包名或 Activity 名为空，无法导航');
       return false;
@@ -1006,10 +1072,10 @@ class PageCrawler {
       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);
+        this.adb.scrollToPosition(stepScroll.container_bounds, stepScroll.scroll_index);
         xml = this.adb.dumpXmlQuick();
       }
-      const elemId: [string, string, string, string] = [step['resource-id'] ?? '', step.text ?? '', step['content-desc'] ?? '', ''];
+      const elemId = [step['resource-id'] ?? '', step.text ?? '', step['content-desc'] ?? '', ''];
       const found = findElementOnScreen(xml, elemId);
       const isLong = step['long-clickable'] ?? false;
       if (found && found.center) {
@@ -1040,43 +1106,43 @@ class PageCrawler {
   }
 
   // ── 断点续跑 ──
-  private saveQueue(): void {
+   saveQueue() {
     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}`);
+      console.log(`  [WARN] 保存队列检查点失败: ${(e).message}`);
     }
   }
 
-  private loadQueue(): QueueItem[] | null {
+   loadQueue() {
     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][];
+      const items = JSON.parse(fs.readFileSync(qfile, 'utf-8'));
       return items.map(([clickPath, elemIdList, stepSigs, scrollInfo]) => [
         clickPath,
-        elemIdList as ElemId,
+        elemIdList,
         stepSigs,
         scrollInfo,
       ]);
     } catch (e) {
-      console.log(`  [WARN] 加载队列检查点失败: ${(e as Error).message}，将重建队列`);
+      console.log(`  [WARN] 加载队列检查点失败: ${(e).message}，将重建队列`);
       return null;
     }
   }
 
-  private rebuildQueueFromPages(pagesIndex: PageRecord[]): QueueItem[] {
-    const queue: QueueItem[] = [];
+   rebuildQueueFromPages(pagesIndex) {
+    const queue = [];
     for (const page of pagesIndex) {
-      const clickPath = (Array.isArray(page.click_path) ? page.click_path : []) as ClickStep[];
+      const clickPath = (Array.isArray(page.click_path) ? page.click_path : []);
       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;
+        let scrollInfo = null;
         if (si > 0 && scrollContainerBounds) scrollInfo = { scroll_index: si, container_bounds: [...scrollContainerBounds] };
         queue.push([clickPath, elemId, [], scrollInfo]);
       }
@@ -1084,9 +1150,9 @@ class PageCrawler {
     return queue;
   }
 
-  private tryLoadCheckpoint():
-    | { pagesIndex: PageRecord[]; visited: Set<string>; pageCounter: number; queue: QueueItem[]; blocked: Set<string> }
-    | null {
+   tryLoadCheckpoint()
+    // | { pagesIndex: PageRecord[]; visited: Set<string>; pageCounter: number; queue: QueueItem[]; blocked: Set<string> }
+     {
     const indexFile = path.join(this.outputRoot, 'index.json');
     if (!fs.existsSync(indexFile)) return null;
     const pageDirs = fs.existsSync(this.outputRoot)
@@ -1094,17 +1160,17 @@ class PageCrawler {
       : [];
     if (pageDirs.length === 0) return null;
 
-    let pagesIndex: PageRecord[];
+    let pagesIndex;
     try {
-      pagesIndex = JSON.parse(fs.readFileSync(indexFile, 'utf-8')) as PageRecord[];
+      pagesIndex = JSON.parse(fs.readFileSync(indexFile, 'utf-8'));
     } catch (e) {
-      console.log(`  [WARN] 读取 index.json 失败: ${(e as Error).message}，重新开始`);
+      console.log(`  [WARN] 读取 index.json 失败: ${(e).message}，重新开始`);
       return null;
     }
     if (!pagesIndex || pagesIndex.length === 0) return null;
 
     console.log(`\n⏩ 发现已有检查点：${pagesIndex.length} 个页面，尝试断点续跑...`);
-    const visited = new Set<string>();
+    const visited = new Set();
     let pageCounter = 0;
     for (const page of pagesIndex) {
       const pageId = page.page_id ?? '';
@@ -1119,7 +1185,7 @@ class PageCrawler {
     }
 
     const savedQueue = this.loadQueue();
-    let queue: QueueItem[];
+    let queue;
     if (savedQueue !== null) {
       queue = savedQueue;
       console.log(`   队列已从检查点恢复：${queue.length} 个待处理元素（精确续跑）`);
@@ -1127,15 +1193,15 @@ class PageCrawler {
       queue = this.rebuildQueueFromPages(pagesIndex);
       console.log(`   队列已重建（fallback）：${queue.length} 个元素（含已探索项，BFS 会自动跳过）`);
     }
-    const blocked = new Set<string>();
+    const blocked = new Set();
     console.log(`   已恢复 ${visited.size} 个已访问签名，队列 ${queue.length} 个待处理元素`);
     return { pagesIndex, visited, pageCounter, queue, blocked };
   }
 
   // ── 页面提交 ──
-  private finalizePage(record: PageRecord, pageId: string): void {
+   finalizePage(record, pageId) {
     const pageDir = path.join(this.outputRoot, pageId);
-    const tmpDir = record._tmp_dir!;
+    const tmpDir = record._tmp_dir;
     if (fs.existsSync(tmpDir)) fs.renameSync(tmpDir, pageDir);
     else fs.mkdirSync(pageDir, { recursive: true });
 
@@ -1165,7 +1231,7 @@ class PageCrawler {
     console.log(`   ✅ 已保存为 [${pageId}]`);
   }
 
-  private activityNameSuffix(record: PageRecord): string {
+   activityNameSuffix(record) {
     const resumed = record.activity_info?.['resumed_activity'] ?? '';
     let mAct = resumed.match(/[\w.]+\/([\w.]+)/);
     if (!mAct) {
@@ -1180,7 +1246,7 @@ class PageCrawler {
     return activityName ? `_${activityName}` : '';
   }
 
-  commitPage(record: PageRecord): string {
+  commitPage(record) {
     this.pageCounter += 1;
     const suffix = this.activityNameSuffix(record);
     const pageId = `page_${String(this.pageCounter).padStart(4, '0')}${suffix}`;
@@ -1188,7 +1254,7 @@ class PageCrawler {
     return pageId;
   }
 
-  commitManualPage(record: PageRecord, pageCounter: number): string {
+  commitManualPage(record, pageCounter) {
     const suffix = this.activityNameSuffix(record);
     const pageId = `manual_${String(pageCounter).padStart(4, '0')}${suffix}`;
     this.finalizePage(record, pageId);
@@ -1196,13 +1262,13 @@ class PageCrawler {
   }
 
   // ── HTML 报告生成 ──
-  generateHtmlReport(pages: PageRecord[]): void {
+  generateHtmlReport(pages) {
     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;
+      let pathDisplay;
       if (clickPath === 'manual') {
         pathDisplay = `（手动采集：${escapeHtml(p.description ?? '手动采集')}）`;
       } else if (Array.isArray(clickPath) && clickPath.length > 0) {
@@ -1220,7 +1286,7 @@ class PageCrawler {
       const screenshotPath = escapeHtml(p.screenshot ?? '');
       const screenshots = p.screenshots ?? [p.screenshot ?? ''];
       const viewXmls = p.view_xmls ?? [p.view_xml ?? ''];
-      let screenshotsHtml: string;
+      let screenshotsHtml;
       if (screenshots.length > 1) {
         let pairsHtml = '';
         screenshots.forEach((ss, idx) => {
@@ -1240,7 +1306,7 @@ class PageCrawler {
       const labelEscaped = escapeHtml(p.label);
       const pageIdEscaped = escapeHtml(p.page_id ?? '');
       const viewXmlEscaped = escapeHtml(p.view_xml ?? '');
-      let xmlLinksHtml: string;
+      let xmlLinksHtml;
       if (viewXmls.length > 1) {
         xmlLinksHtml = viewXmls
           .map((vx, i) => `<a href="${escapeHtml(vx)}" target="_blank">📄 XML${i === 0 ? '' : `_${i}`}</a>`)
@@ -1273,7 +1339,7 @@ class PageCrawler {
     }
 
     const now = new Date();
-    const pad = (x: number): string => String(x).padStart(2, '0');
+    const pad = (x) => 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>
@@ -1321,17 +1387,17 @@ ${cards}
     fs.writeFileSync(path.join(this.outputRoot, 'report.html'), html, 'utf-8');
   }
 
-  private flushReport(): void {
+   flushReport() {
     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}`);
+      console.log(`  [WARN] 写入报告失败: ${(e).message}`);
     }
   }
 
-  crawl(): void {
+  crawl() {
     if (!this.adb.checkDevice()) return;
 
     let activityInfo = this.adb.getCurrentActivity();
@@ -1361,8 +1427,8 @@ ${cards}
       }
     }
 
-    let launchPackage: string | null = null;
-    let launchActivity: string | null = null;
+    let launchPackage = null;
+    let launchActivity = null;
     const comp = extractLaunchComponent(activityInfo);
     if (comp) {
       [launchPackage, launchActivity] = comp;
@@ -1373,7 +1439,7 @@ ${cards}
       );
     }
 
-    let rootActivityKeyword: string | null = null;
+    let rootActivityKeyword = null;
     if (launchActivity) {
       const parts = launchActivity.split('.');
       rootActivityKeyword = parts[parts.length - 1];
@@ -1386,7 +1452,7 @@ ${cards}
     console.log('开始遍历（加速版：BFS + 轻量探测）...');
     console.log('='.repeat(60));
 
-    let rootIdentity: RootIdentity | null = null;
+    let rootIdentity = null;
     const checkpoint = this.tryLoadCheckpoint();
     if (checkpoint) {
       this.pagesIndex = checkpoint.pagesIndex;
@@ -1397,7 +1463,7 @@ ${cards}
       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');
+          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);
@@ -1424,15 +1490,15 @@ ${cards}
         }
         const elemId = PageCrawler.elemIdOf(elem);
         const si = elem.scroll_index ?? 0;
-        let scrollInfo: ScrollInfo | null = null;
+        let scrollInfo = null;
         if (si > 0 && scrollContainerBounds) scrollInfo = { scroll_index: si, container_bounds: [...scrollContainerBounds] };
         this.queue.push([[], elemId, [], scrollInfo]);
       }
     }
 
-    const failedPaths = new Set<string>();
+    const failedPaths = new Set();
     while (this.queue.length > 0 && this.pageCounter < this.maxPages) {
-      const [clickPath, elemId, stepSignatures, scrollInfo] = this.queue.shift()!;
+      const [clickPath, elemId, stepSignatures, scrollInfo] = this.queue.shift();
       const elemKey = JSON.stringify(elemId);
       if (this.blockedElements.has(elemKey)) continue;
 
@@ -1470,7 +1536,7 @@ ${cards}
       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);
+        this.adb.scrollToPosition(scrollInfo.container_bounds, scrollInfo.scroll_index);
         freshXml = this.adb.dumpXmlQuick();
       }
 
@@ -1508,7 +1574,7 @@ ${cards}
       this.visitedSignatures.add(newSig);
       const pageId = this.commitPage(newRecord);
 
-      const newClickPath: ClickStep[] = [
+      const newClickPath = [
         ...clickPath,
         {
           from: pathDesc,
@@ -1538,7 +1604,7 @@ ${cards}
         }
         const newEid = PageCrawler.elemIdOf(ne);
         const si = ne.scroll_index ?? 0;
-        let neScrollInfo: ScrollInfo | null = null;
+        let neScrollInfo = null;
         if (si > 0 && newScrollBounds) neScrollInfo = { scroll_index: si, container_bounds: [...newScrollBounds] };
         this.queue.push([newClickPath, newEid, newStepSigs, neScrollInfo]);
       }
@@ -1563,26 +1629,65 @@ ${cards}
     console.log('='.repeat(60));
   }
 
-  async manualCrawl(): Promise<void> {
-    if (!this.adb.checkDevice()) return;
-    fs.mkdirSync(this.outputRoot, { recursive: true });
-
-    let pagesIndex: PageRecord[] = [];
+  /** 读取已有 index.json（不存在或损坏时返回空数组）。手动/单页采集共用。 */
+   loadExistingIndex() {
     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}，将创建新索引`);
-      }
+    if (!fs.existsSync(indexFile)) return [];
+    try {
+      return JSON.parse(fs.readFileSync(indexFile, 'utf-8'));
+    } catch (e) {
+      console.log(`[WARN] 读取 index.json 失败: ${(e).message}，将创建新索引`);
+      return [];
     }
+  }
 
-    let manualCounter = 0;
+  /** 已有页面里最大的 manual_NNNN 编号，用于续编号。 */
+  static lastManualCounter(pagesIndex) {
+    let counter = 0;
     for (const p of pagesIndex) {
       const mm = (p.page_id ?? '').match(/manual_(\d+)/);
-      if (mm) manualCounter = Math.max(manualCounter, parseInt(mm[1], 10));
+      if (mm) counter = Math.max(counter, parseInt(mm[1], 10));
     }
+    return counter;
+  }
+
+  /**
+   * 单页采集模式（--page "<描述>"）：不做任何导航，直接把设备**当前**页面
+   * 当作待采集页抓一次（截图 + view.xml + 可滚动容器滚动采集），写入 index.json /
+   * report.html 后退出。等价于 manualCrawl 里输入一次描述、再输入 q，但无需交互，
+   * 便于外部脚本按自己的 UI 序列逐页调用。
+   */
+  capturePageOnce(description) {
+    if (!this.adb.checkDevice()) return;
+    fs.mkdirSync(this.outputRoot, { recursive: true });
+
+    const pagesIndex = this.loadExistingIndex();
+    if (pagesIndex.length > 0) console.log(`📂 已加载 ${pagesIndex.length} 个已有页面`);
+    const manualCounter = PageCrawler.lastManualCounter(pagesIndex) + 1;
+
+    console.log(`\n📂 输出目录: ${path.resolve(this.outputRoot)}`);
+    console.log(`📝 单页采集模式：${description}`);
+
+    const { record } = this.capturePage(description);
+    record.click_path = 'manual';
+    record.description = description;
+    const pageId = this.commitManualPage(record, manualCounter);
+    pagesIndex.push(record);
+    fs.writeFileSync(path.join(this.outputRoot, 'index.json'), JSON.stringify(pagesIndex, null, 2), 'utf-8');
+    this.pagesIndex = pagesIndex;
+    this.generateHtmlReport(pagesIndex);
+
+    console.log(`\n✅ 单页采集完成：[${pageId}]（index.json 共 ${pagesIndex.length} 个页面）`);
+    console.log(`📂 输出目录: ${path.resolve(this.outputRoot)}`);
+  }
+
+  async manualCrawl() {
+    if (!this.adb.checkDevice()) return;
+    fs.mkdirSync(this.outputRoot, { recursive: true });
+
+    const pagesIndex = this.loadExistingIndex();
+    if (pagesIndex.length > 0) console.log(`📂 已加载 ${pagesIndex.length} 个已有页面`);
+    let manualCounter = PageCrawler.lastManualCounter(pagesIndex);
 
     console.log(`\n📂 输出目录: ${path.resolve(this.outputRoot)}`);
     console.log(`📝 手动采集模式已启动（manual 编号从 ${manualCounter + 1} 开始）`);
@@ -1594,7 +1699,7 @@ ${cards}
     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));
+    const question = (q) => new Promise((resolve) => rl.question(q, resolve));
 
     try {
       for (;;) {
@@ -1611,7 +1716,7 @@ ${cards}
         record.description = desc;
         this.commitManualPage(record, manualCounter);
         pagesIndex.push(record);
-        fs.writeFileSync(indexFile, JSON.stringify(pagesIndex, null, 2), 'utf-8');
+        fs.writeFileSync(path.join(this.outputRoot, 'index.json'), JSON.stringify(pagesIndex, null, 2), 'utf-8');
         this.pagesIndex = pagesIndex;
         this.generateHtmlReport(pagesIndex);
         console.log(`   📋 index.json 和 report.html 已更新（共 ${pagesIndex.length} 个页面）`);
@@ -1627,26 +1732,28 @@ ${cards}
 // ─────────────────────────────────────────────
 // CLI
 // ─────────────────────────────────────────────
-interface CliArgs {
-  package: string;
-  output: string;
-  manual: boolean;
-  device: string;
-  adbPath: string;
-  maxPages: number;
-  maxScrolls: number;
-}
-
-function printHelp(): void {
+// interface CliArgs {
+  // package: string;
+  // output: string;
+  // manual: boolean;
+  // page: string | null;
+  // device: string;
+  // adbPath: string;
+  // maxPages: number;
+  // maxScrolls: number;
+// }
+
+function printHelp() {
   console.log(
     [
       'Android 模拟器页面遍历工具（加速版）',
       '',
-      'Usage: node android_parse_fast.ts --package <pkg> --output <dir> [options]',
+      'Usage: node android_parse_fast.js --package <pkg> --output <dir> [options]',
       '',
       '  --package, -p    目标 App 包名（必选）',
       '  --output, -o     输出目录（必选）',
       '  --manual         手动采集模式：手动导航到页面后按回车触发采集',
+      '  --page "<描述>"  单页采集模式：直接用该描述采集设备当前页面，抓完一页即退出（不遍历）',
       `  --device         ADB 设备 serial（默认: ${DEVICE_SERIAL_DEFAULT}）`,
       `  --adb-path       adb 可执行文件路径（默认: ${ADB_PATH_DEFAULT}）`,
       `  --max-pages      最多遍历页面数（默认: ${MAX_PAGES_DEFAULT}）`,
@@ -1655,11 +1762,12 @@ function printHelp(): void {
   );
 }
 
-function parseArgs(argv: string[]): CliArgs {
-  const args: CliArgs = {
+function parseArgs(argv) {
+  const args = {
     package: '',
     output: '',
     manual: false,
+    page: null,
     device: DEVICE_SERIAL_DEFAULT,
     adbPath: ADB_PATH_DEFAULT,
     maxPages: MAX_PAGES_DEFAULT,
@@ -1667,7 +1775,7 @@ function parseArgs(argv: string[]): CliArgs {
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    const next = (): string => {
+    const next = () => {
       if (i + 1 >= argv.length) {
         console.error(`Missing value for ${a}`);
         process.exit(2);
@@ -1677,6 +1785,7 @@ function parseArgs(argv: string[]): CliArgs {
     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 === '--page') args.page = next();
     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);
@@ -1697,10 +1806,14 @@ function parseArgs(argv: string[]): CliArgs {
     console.error('error: --output/-o is required');
     process.exit(2);
   }
+  if (args.page !== null && args.manual) {
+    console.error('error: --page 与 --manual 互斥');
+    process.exit(2);
+  }
   return args;
 }
 
-async function main(): Promise<number> {
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   const adb = new ADBHelper({ adbPath: args.adbPath, deviceSerial: args.device, targetPackage: args.package });
   const crawler = new PageCrawler({
@@ -1710,7 +1823,8 @@ async function main(): Promise<number> {
     maxPages: args.maxPages,
     maxScrolls: args.maxScrolls,
   });
-  if (args.manual) await crawler.manualCrawl();
+  if (args.page !== null) crawler.capturePageOnce(args.page.trim() || '单页采集');
+  else if (args.manual) await crawler.manualCrawl();
   else crawler.crawl();
   return 0;
 }