@skrillex1224/android-toolkit 0.1.8 → 1.0.0

package/src/frida-client.js

@@ -1,1068 +0,0 @@
-import fs from 'node:fs';
-import {spawn} from 'node:child_process';
-
-import {Code} from './constants.js';
-import {adbShell} from './device.js';
-import {CrawlerError} from './errors.js';
-import {Logger, sleep} from './logger.js';
-
-/**
- * 启动一个持续运行的 Frida WebView 事件记录器。
- *
- * 业务方负责传入：
- * - 要 hook 的 WebView class 列表；
- * - 要关心的事件名或关键词；
- * - 输出文件路径。
- *
- * toolkit 只做三件事：
- * 1. 找到目标 App 当前真实 pid；
- * 2. 把业务配置和通用 Frida agent 合并成临时脚本；
- * 3. 收集 agent 打出的 marker 行并在 stop() 时返回。
- */
-export async function startWebViewEventRecorder(ctx, config = {}, options = {}) {
-    const startedAt = Date.now();
-    await ensureFridaServer(ctx);
-    assertFridaReady(ctx, ctx.fridaWebViewEventAgentScript, 'frida webview event agent script');
-    const marker = options.marker || 'ANDROID_WEBVIEW_EVENT_JSON ';
-    const scriptPath = writeConfiguredWebViewEventAgent(ctx, config);
-    const pid = await resolvePid(ctx, ctx.packageName);
-    Logger.info('frida webview recorder start', {
-        label: options.label || 'webview-event-recorder',
-        serial: ctx.serial,
-        packageName: ctx.packageName,
-        pid,
-        scriptPath
-    });
-
-    const recorder = startFridaLineRecorder(ctx.fridaPath, [
-        '-q',
-        '-t',
-        'inf',
-        '-D',
-        ctx.serial,
-        '-p',
-        pid,
-        '-l',
-        scriptPath
-    ], {
-        marker,
-        label: options.label || 'webview-event-recorder',
-        maxLines: Number(options.maxLines || 6000),
-        outputPath: options.outputPath || ''
-    });
-    await recorder.waitForStartup(Number(options.startupTimeoutMs || 3000));
-    Logger.info('frida webview recorder ready', {duration: Logger.duration(startedAt), pid});
-    return recorder;
-}
-
-/**
- * 在目标 App 进程内部执行一段短 Frida 脚本，并返回 marker 输出。
- *
- * 适合做“从 App 内部启动非 exported Activity”“读取当前 Activity View 树”等
- * 小动作。业务脚本必须自己 console.log marker JSON；toolkit 只负责 attach、
- * 收集输出和错误显式化。
- */
-export async function runScript(ctx, source, options = {}) {
-    const startedAt = Date.now();
-    const label = options.label || 'script';
-    await ensureFridaServer(ctx);
-    assertFridaReady(ctx, ctx.fridaWebViewEventAgentScript, 'frida webview event agent script');
-    const marker = options.marker || 'ANDROID_TOOLKIT_SCRIPT_JSON ';
-    const scriptPath = writeTempScript(ctx, source, label);
-    const pid = await resolvePid(ctx, options.packageName || ctx.packageName);
-    Logger.info('frida script start', {
-        label,
-        serial: ctx.serial,
-        packageName: options.packageName || ctx.packageName,
-        pid,
-        timeoutMs: options.timeoutMs || 10000
-    });
-    const recorder = startFridaLineRecorder(ctx.fridaPath, [
-        '-q',
-        '-t',
-        String(Number(options.fridaTimeoutSeconds || 5)),
-        '-D',
-        ctx.serial,
-        '-p',
-        pid,
-        '-l',
-        scriptPath
-    ], {
-        marker,
-        label: options.label || 'script',
-        maxLines: Number(options.maxLines || 1200),
-        outputPath: options.outputPath || ''
-    });
-    await recorder.waitForExit(Number(options.timeoutMs || 10000));
-    const result = await recorder.stop();
-    const scriptEvents = result.events.filter((event) => event?.type !== 'parse_error');
-    if (scriptEvents.length === 0) {
-        Logger.warn('frida script produced no event', {
-            label,
-            duration: Logger.duration(startedAt),
-            lineCount: result.lines.length
-        });
-        throw new CrawlerError({
-            message: `frida_script_failed: ${label} did not emit ${marker.trim()}`,
-            code: Code.FridaUnavailable,
-            context: {lines: result.lines.slice(-40)}
-        });
-    }
-    const event = scriptEvents.at(-1);
-    Logger.info('frida script done', {
-        label,
-        duration: Logger.duration(startedAt),
-        eventCount: scriptEvents.length,
-        ok: event?.ok
-    });
-    return event;
-}
-
-/**
- * 在目标 App 进程内查询 SQLite。
- *
- * 这是通用底层能力，只负责：
- * - 按 dbPath 或 dbDir/dbNamePrefix 找数据库文件；
- * - 执行业务方传入的 SQL 和参数；
- * - 把 cursor rows 作为字符串对象返回。
- *
- * toolkit 不理解表名、字段含义、消息关联关系；这些规则必须留在具体 androider。
- */
-export async function querySQLite(ctx, options = {}) {
-    if (!options.sql) {
-        throw new CrawlerError({
-            message: 'sqlite_query_failed: sql is required',
-            code: Code.InvalidRequest
-        });
-    }
-
-    const startedAt = Date.now();
-    const config = {
-        dbPath: String(options.dbPath || ''),
-        dbDir: String(options.dbDir || ''),
-        dbNamePrefix: String(options.dbNamePrefix || ''),
-        dbNameIncludes: String(options.dbNameIncludes || ''),
-        dbNameExcludes: normalizeStringArray(options.dbNameExcludes),
-        sql: String(options.sql || ''),
-        args: normalizeStringArray(options.args),
-        maxRows: Math.max(1, Number(options.maxRows || 200))
-    };
-    Logger.info('sqlite query start', {
-        label: options.label || 'query-sqlite',
-        dbPath: config.dbPath,
-        dbDir: config.dbDir,
-        maxRows: config.maxRows
-    });
-
-    const event = await runScript(ctx, `
-Java.perform(function () {
-  function emit(payload) { console.log('ANDROID_TOOLKIT_SCRIPT_JSON ' + JSON.stringify(payload)); }
-  var config = ${JSON.stringify(config)};
-  var JavaString = Java.use('java.lang.String');
-
-  function safeString(cursor, index) {
-    try { return cursor.isNull(index) ? '' : String(cursor.getString(index)); } catch (_) { return ''; }
-  }
-  function stringArray(values) {
-    if (!values || values.length === 0) return null;
-    var out = [];
-    for (var i = 0; i < values.length; i++) out.push(String(values[i]));
-    return Java.array('java.lang.String', out);
-  }
-  function matchesName(name) {
-    if (config.dbNamePrefix && name.indexOf(config.dbNamePrefix) !== 0) return false;
-    if (config.dbNameIncludes && name.indexOf(config.dbNameIncludes) < 0) return false;
-    for (var i = 0; i < config.dbNameExcludes.length; i++) {
-      if (String(name).indexOf(config.dbNameExcludes[i]) >= 0) return false;
-    }
-    return true;
-  }
-  function dbPaths() {
-    if (config.dbPath) return [config.dbPath];
-    var File = Java.use('java.io.File');
-    var dir = File.$new(config.dbDir);
-    var files = dir.listFiles();
-    var out = [];
-    if (!files) return out;
-    for (var i = 0; i < files.length; i++) {
-      var name = String(files[i].getName());
-      if (matchesName(name)) out.push(String(files[i].getAbsolutePath()));
-    }
-    return out;
-  }
-  function queryOne(dbPath) {
-    var SQLiteDatabase = Java.use('android.database.sqlite.SQLiteDatabase');
-    var db = SQLiteDatabase.openDatabase(JavaString.$new(dbPath), null, 1);
-    try {
-      var cursor = db.rawQuery(JavaString.$new(config.sql), stringArray(config.args));
-      var columns = [];
-      var columnCount = cursor.getColumnCount();
-      for (var c = 0; c < columnCount; c++) columns.push(String(cursor.getColumnName(c)));
-      var rows = [];
-      var truncated = false;
-      while (cursor.moveToNext()) {
-        if (rows.length >= config.maxRows) {
-          truncated = true;
-          break;
-        }
-        var row = {};
-        for (var i = 0; i < columns.length; i++) row[columns[i]] = safeString(cursor, i);
-        rows.push(row);
-      }
-      cursor.close();
-      return { dbPath: dbPath, columns: columns, rows: rows, rowCount: rows.length, truncated: truncated };
-    } finally {
-      db.close();
-    }
-  }
-  try {
-    var paths = dbPaths();
-    if (paths.length === 0) {
-      emit({ ok: false, error: 'sqlite database not found', config: config });
-      return;
-    }
-    var databases = [];
-    for (var d = 0; d < paths.length; d++) databases.push(queryOne(paths[d]));
-    emit({ ok: true, databases: databases, rows: databases.length === 1 ? databases[0].rows : [] });
-  } catch (error) {
-    emit({ ok: false, error: String(error), stack: String(error.stack || '') });
-  }
-});
-`, {
-        label: options.label || 'query-sqlite',
-        packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 12000,
-        fridaTimeoutSeconds: options.fridaTimeoutSeconds || 10,
-        maxLines: options.maxLines || 1200
-    });
-    if (!event.ok) {
-        throw new CrawlerError({
-            message: `sqlite_query_failed: ${event.error || ''}`.trim(),
-            code: Code.ContentUnavailable,
-            context: event
-        });
-    }
-    Logger.info('sqlite query done', {
-        label: options.label || 'query-sqlite',
-        duration: Logger.duration(startedAt),
-        databaseCount: Array.isArray(event.databases) ? event.databases.length : 0,
-        rowCount: Array.isArray(event.rows) ? event.rows.length : 0
-    });
-    return event;
-}
-
-/**
- * 确保设备侧 frida-server 已经启动。
- *
- * 安卓采集链路依赖 host 侧 `frida -D <serial>` attach 到目标 App；
- * 如果设备重启、frida-server 被系统杀掉，或者被普通 shell 用户启动，
- * 后续 attach 会直接失败。这里在每次 Frida 调用前做轻量检查：
- * - root 用户的 frida-server 已存在：直接复用；
- * - 只有 shell 用户进程：用 su 清理后重启；
- * - 没有进程：优先用 su 启动 `/data/local/tmp/frida-server`，再退回 shell 启动。
- */
-export async function ensureFridaServer(ctx, options = {}) {
-    const serverPath = options.serverPath || ctx.fridaServerPath || '/data/local/tmp/frida-server';
-    const current = await listFridaServerRows(ctx);
-    if (current.some((row) => row.user === 'root')) {
-        Logger.debug('frida-server ready', {serial: ctx.serial, user: 'root'});
-        return true;
-    }
-
-    const rootAvailable = await canUseSu(ctx);
-    if (current.length > 0 && rootAvailable) {
-        Logger.warn('frida-server 正在以非 root 用户运行，尝试切换为 root 进程');
-        await adbShell(ctx, ['su', '-c', 'pkill -f frida-server || true'], {timeoutMs: 5000}).catch(() => { });
-        await sleep(800);
-    } else if (current.length > 0) {
-        Logger.debug('frida-server ready', {serial: ctx.serial, user: 'shell'});
-        return true;
-    }
-
-    const exists = await adbShell(ctx, ['ls', serverPath], {timeoutMs: 5000}).then(() => true).catch(() => false);
-    if (!exists) {
-        throw new CrawlerError({
-            message: `frida_unavailable: frida-server not found on device: ${serverPath}`,
-            code: Code.FridaUnavailable,
-            context: {serverPath}
-        });
-    }
-
-    const command = `chmod 755 ${shellQuote(serverPath)} && ${shellQuote(serverPath)} >/dev/null 2>&1 &`;
-    if (rootAvailable) {
-        await adbShell(ctx, ['su', '-c', command], {timeoutMs: 5000}).catch(() => { });
-    } else {
-        await adbShell(ctx, ['sh', '-c', command], {timeoutMs: 5000}).catch(() => { });
-    }
-
-    await sleep(1500);
-    const after = await listFridaServerRows(ctx);
-    if (after.some((row) => row.user === 'root') || (!rootAvailable && after.length > 0)) {
-        Logger.info('frida-server started', {serial: ctx.serial, rootAvailable});
-        return true;
-    }
-
-    throw new CrawlerError({
-        message: 'frida_unavailable: frida-server did not start on device',
-        code: Code.FridaUnavailable,
-        context: {serverPath, rootAvailable, current, after}
-    });
-}
-
-/**
- * 从 App 内部启动 Activity。
- *
- * shell 的 `am start` 只能打开 exported Activity；很多 App 内部页面
- * 不能被外部直接启动。这里 attach 到 App 自己的进程，用当前 Application
- * 发起 startActivity，等价于 App 内部跳转。
- */
-export async function startActivityInsideApp(ctx, className, options = {}) {
-    const event = await runScript(ctx, `
-Java.perform(function () {
-  function emit(payload) { console.log('ANDROID_TOOLKIT_SCRIPT_JSON ' + JSON.stringify(payload)); }
-  Java.scheduleOnMainThread(function () {
-    try {
-      var ActivityThread = Java.use('android.app.ActivityThread');
-      var Intent = Java.use('android.content.Intent');
-      var app = ActivityThread.currentApplication();
-      var intent = Intent.$new();
-      intent.setClassName(${JSON.stringify(options.packageName || ctx.packageName)}, ${JSON.stringify(className)});
-      intent.addFlags(0x10000000);
-      app.startActivity(intent);
-      emit({ ok: true, className: ${JSON.stringify(className)} });
-    } catch (error) {
-      emit({ ok: false, className: ${JSON.stringify(className)}, error: String(error), stack: String(error.stack || '') });
-    }
-  });
-});
-`, {
-        label: options.label || 'start-activity-inside-app',
-        packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 12000,
-        fridaTimeoutSeconds: options.fridaTimeoutSeconds || 10
-    });
-    if (!event.ok) {
-        throw new CrawlerError({
-            message: `automation_failed: startActivityInsideApp failed ${event.error || className}`,
-            code: Code.AutomationFailed,
-            context: event
-        });
-    }
-    return event;
-}
-
-/**
- * 查找当前 App 内部可见 EditText，并直接写入文本。
- *
- * 这是 Android 版的“定位输入框并 fill”基础能力：
- * - 不走 OCR；
- * - 不依赖屏幕比例坐标；
- * - 业务方只传通用筛选条件，例如 hintIncludes；
- * - toolkit 在 App 进程内遍历 Activity DecorView，选中输入框后 requestFocus/performClick，
- *   再写入 Editable，保证中文不会被 adb input text 打成乱码。
- */
-export async function setVisibleInputText(ctx, text, options = {}) {
-    const event = await runScript(ctx, `
-Java.perform(function () {
-  function emit(payload) { console.log('ANDROID_TOOLKIT_SCRIPT_JSON ' + JSON.stringify(payload)); }
-  var JavaObject = Java.use('java.lang.Object');
-  function toJsString(value) {
-    if (value === null || value === undefined) return '';
-    try { return Java.cast(value, JavaObject).toString() + ''; } catch (_) { }
-    try { return value.toString.overload().call(value) + ''; } catch (_) { }
-    try { return value.toString() + ''; } catch (_) { }
-    return '';
-  }
-  function rectOf(view) {
-    var Rect = Java.use('android.graphics.Rect');
-    var rect = Rect.$new();
-    try { view.getGlobalVisibleRect(rect); } catch (_) { }
-    return { left: rect.left.value, top: rect.top.value, right: rect.right.value, bottom: rect.bottom.value };
-  }
-  function walk(view, out, depth) {
-    if (!view || depth > ${Number(options.maxDepth || 20)} || out.length > ${Number(options.maxNodes || 3000)}) return;
-    out.push(view);
-    try {
-      var ViewGroup = Java.use('android.view.ViewGroup');
-      var group = Java.cast(view, ViewGroup);
-      for (var i = 0; i < group.getChildCount(); i++) walk(group.getChildAt(i), out, depth + 1);
-    } catch (_) { }
-  }
-  function activeActivities() {
-    var ActivityThread = Java.use('android.app.ActivityThread');
-    var Activity = Java.use('android.app.Activity');
-    var ArrayMap = Java.use('android.util.ArrayMap');
-    var thread = ActivityThread.currentActivityThread();
-    var field = thread.getClass().getDeclaredField('mActivities');
-    field.setAccessible(true);
-    var map = Java.cast(field.get(thread), ArrayMap);
-    var out = [];
-    for (var i = 0; i < map.size(); i++) {
-      var record = map.valueAt(i);
-      var recordClass = record.getClass();
-      var activityField = recordClass.getDeclaredField('activity');
-      var pausedField = recordClass.getDeclaredField('paused');
-      activityField.setAccessible(true);
-      pausedField.setAccessible(true);
-      if (!pausedField.getBoolean(record)) out.push(Java.cast(activityField.get(record), Activity));
-    }
-    return out;
-  }
-  Java.scheduleOnMainThread(function () {
-    try {
-      var EditText = Java.use('android.widget.EditText');
-      var InputMethodManager = Java.use('android.view.inputmethod.InputMethodManager');
-      var targetText = ${JSON.stringify(String(text || ''))};
-      var hintIncludes = ${JSON.stringify(String(options.hintIncludes || ''))};
-      var activities = activeActivities();
-      var chosen = null;
-      var focused = null;
-      var firstVisible = null;
-      for (var a = 0; a < activities.length; a++) {
-        var views = [];
-        walk(activities[a].getWindow().getDecorView(), views, 0);
-        for (var i = 0; i < views.length; i++) {
-          var view = views[i];
-          if (!view.isShown()) continue;
-          try {
-            var editText = Java.cast(view, EditText);
-            var rect = rectOf(view);
-            if (rect.right <= rect.left || rect.bottom <= rect.top) continue;
-            var item = { view: editText, bounds: rect, text: toJsString(editText.getText()), hint: toJsString(editText.getHint()), className: toJsString(view.getClass().getName()), focused: Boolean(view.hasFocus()) };
-            if (hintIncludes && item.hint.indexOf(hintIncludes) >= 0) {
-              chosen = item;
-              break;
-            }
-            if (item.focused && !focused) focused = item;
-            if (!firstVisible) firstVisible = item;
-          } catch (_) { }
-        }
-        if (chosen) break;
-      }
-      chosen = chosen || (!hintIncludes ? (focused || firstVisible) : null);
-      if (!chosen) {
-        emit({ ok: false, error: 'visible EditText not found' });
-        return;
-      }
-      var JavaString = Java.use('java.lang.String');
-      var BufferType = Java.use('android.widget.TextView$BufferType');
-      var SpannableStringBuilder = Java.use('android.text.SpannableStringBuilder');
-      chosen.view.requestFocus();
-      try { chosen.view.performClick(); } catch (_) { }
-      try {
-        var imm = InputMethodManager.getInstance.overload().call(InputMethodManager);
-        imm.showSoftInput(chosen.view, 0);
-      } catch (_) { }
-      chosen.view.setText(SpannableStringBuilder.$new(JavaString.$new(targetText)), BufferType.EDITABLE.value);
-      chosen.view.setSelection(targetText.length);
-      var actualText = toJsString(chosen.view.getText());
-      emit({
-        ok: true,
-        text: actualText,
-        hint: toJsString(chosen.view.getHint()),
-        className: chosen.className,
-        bounds: chosen.bounds
-      });
-    } catch (error) {
-      emit({ ok: false, error: String(error), stack: String(error.stack || '') });
-    }
-  });
-});
-`, {
-        label: options.label || 'set-visible-input-text',
-        packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 7000
-    });
-    if (!event.ok) {
-        throw new CrawlerError({
-            message: `automation_failed: setVisibleInputText failed ${event.error || ''}`.trim(),
-            code: Code.AutomationFailed,
-            context: event
-        });
-    }
-    return event;
-}
-
-/**
- * 触发当前输入框的 IME action。
- *
- * 这对应软键盘右下角的“搜索 / 完成 / 发送”等动作，
- * 不是硬件 ENTER。很多 App 会区分这两种输入：
- * `adb shell input keyevent ENTER` 只发送按键事件；
- * 软键盘按钮会调用当前 InputConnection.performEditorAction(actionCode)。
- */
-export async function performEditorAction(ctx, action = 'search', options = {}) {
-    const actionCode = editorActionCode(action);
-    const event = await runScript(ctx, `
-Java.perform(function () {
-  function emit(payload) { console.log('ANDROID_TOOLKIT_SCRIPT_JSON ' + JSON.stringify(payload)); }
-  Java.scheduleOnMainThread(function () {
-    try {
-      var InputMethodManager = Java.use('android.view.inputmethod.InputMethodManager');
-      var IInputConnectionWrapper = Java.use('com.android.internal.view.IInputConnectionWrapper');
-      var imm = InputMethodManager.getInstance.overload().call(InputMethodManager);
-      var field = imm.getClass().getDeclaredField('mServedInputConnectionWrapper');
-      field.setAccessible(true);
-      var rawConnection = field.get(imm);
-      if (!rawConnection) {
-        emit({ ok: false, error: 'mServedInputConnectionWrapper is empty', actionCode: ${actionCode} });
-        return;
-      }
-      var connection = Java.cast(rawConnection, IInputConnectionWrapper);
-      connection.performEditorAction.overload('int').call(connection, ${actionCode});
-      emit({
-        ok: true,
-        actionCode: ${actionCode},
-        className: String(connection.getClass().getName())
-      });
-    } catch (error) {
-      emit({ ok: false, actionCode: ${actionCode}, error: String(error), stack: String(error.stack || '') });
-    }
-  });
-});
-`, {
-        label: options.label || 'perform-editor-action',
-        packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 7000
-    });
-    if (!event.ok) {
-        throw new CrawlerError({
-            message: `automation_failed: performEditorAction failed ${event.error || ''}`.trim(),
-            code: Code.AutomationFailed,
-            context: event
-        });
-    }
-    return event;
-}
-
-/**
- * 在当前可见 WebView 中执行一段 JavaScript，并返回 evaluateJavascript 的回调值。
- *
- * 这是 Android 版的 `page.evaluate()` 基础能力：
- * - toolkit 只负责找到当前 Activity 里的可见 WebView；
- * - 业务方传入要执行的 JS 字符串；
- * - JS 返回值保持 Android WebView 的原始 callback 形态，业务方自行解析。
- *
- * 注意：这里不关心具体页面选择器，也不内置任何微信/抖音等业务逻辑。
- */
-export async function evaluateVisibleWebView(ctx, script, options = {}) {
-    const event = await evaluateVisibleWebViews(ctx, script, {
-        ...options,
-        maxCandidates: 1
-    });
-    const first = event.candidates?.[0];
-    if (!first) {
-        throw new CrawlerError({
-            message: 'automation_failed: evaluateVisibleWebView failed visible WebView not found',
-            code: Code.AutomationFailed,
-            context: event
-        });
-    }
-    return {
-        ok: true,
-        value: first.value,
-        className: first.className,
-        castClassName: first.castClassName,
-        url: first.url,
-        index: first.index
-    };
-}
-
-/**
- * 在所有匹配的可见 WebView 中执行同一段 JavaScript。
- *
- * 这是 `evaluateVisibleWebView` 的批量版本，用来处理一个 Activity 内存在多个
- * WebView 的场景。toolkit 只返回每个候选的原始 evaluateJavascript callback；
- * 业务方根据自己的页面结构判断哪个候选才是目标页面。
- */
-export async function evaluateVisibleWebViews(ctx, script, options = {}) {
-    const webViewClasses = normalizeWebViewClasses(options.webViewClasses);
-    const urlIncludes = String(options.urlIncludes || '').trim();
-    const maxCandidates = Math.max(1, Number(options.maxCandidates || 12));
-
-    const event = await runScript(ctx, `
-Java.perform(function () {
-  function emit(payload) { console.log('ANDROID_TOOLKIT_SCRIPT_JSON ' + JSON.stringify(payload)); }
-  var JavaObject = Java.use('java.lang.Object');
-  function toJsString(value) {
-    if (value === null || value === undefined) return '';
-    try { return Java.cast(value, JavaObject).toString() + ''; } catch (_) { }
-    try { return value.toString.overload().call(value) + ''; } catch (_) { }
-    try { return value.toString() + ''; } catch (_) { }
-    return '';
-  }
-  function walk(view, out, depth) {
-    if (!view || depth > ${Number(options.maxDepth || 25)} || out.length > ${Number(options.maxNodes || 5000)}) return;
-    out.push(view);
-    try {
-      var ViewGroup = Java.use('android.view.ViewGroup');
-      var group = Java.cast(view, ViewGroup);
-      for (var i = 0; i < group.getChildCount(); i++) walk(group.getChildAt(i), out, depth + 1);
-    } catch (_) { }
-  }
-  function activeActivities() {
-    var ActivityThread = Java.use('android.app.ActivityThread');
-    var Activity = Java.use('android.app.Activity');
-    var ArrayMap = Java.use('android.util.ArrayMap');
-    var thread = ActivityThread.currentActivityThread();
-    var field = thread.getClass().getDeclaredField('mActivities');
-    field.setAccessible(true);
-    var map = Java.cast(field.get(thread), ArrayMap);
-    var out = [];
-    for (var i = 0; i < map.size(); i++) {
-      var record = map.valueAt(i);
-      var recordClass = record.getClass();
-      var activityField = recordClass.getDeclaredField('activity');
-      var pausedField = recordClass.getDeclaredField('paused');
-      activityField.setAccessible(true);
-      pausedField.setAccessible(true);
-      if (!pausedField.getBoolean(record)) out.push(Java.cast(activityField.get(record), Activity));
-    }
-    return out;
-  }
-  function useClass(name, loader) {
-    try { return Java.use(name); } catch (_) { }
-    try { return Java.ClassFactory.get(loader).use(name); } catch (_) { }
-    return null;
-  }
-  function castWebView(view, actualClassName) {
-    var configuredNames = ${JSON.stringify(webViewClasses)};
-    var names = [actualClassName];
-    for (var n = 0; n < configuredNames.length; n++) {
-      if (names.indexOf(configuredNames[n]) < 0) names.push(configuredNames[n]);
-    }
-    var loader = null;
-    try { loader = view.getClass().getClassLoader(); } catch (_) { }
-    for (var i = 0; i < names.length; i++) {
-      try {
-        var Klass = useClass(names[i], loader);
-        if (!Klass) continue;
-        var casted = Java.cast(view, Klass);
-        if (!casted.evaluateJavascript) continue;
-        return { view: casted, className: names[i] };
-      } catch (_) { }
-    }
-    return null;
-  }
-  var Callback = Java.registerClass({
-    name: 'com.android.toolkit.JsValueCallback' + Date.now(),
-    implements: [Java.use('android.webkit.ValueCallback')],
-    methods: {
-      onReceiveValue: function (value) {
-        var item = pending[currentIndex] || {};
-        results.push({
-          index: item.index,
-          className: item.className,
-          castClassName: item.castClassName,
-          shown: item.shown,
-          url: item.url,
-          value: toJsString(value)
-        });
-        currentIndex += 1;
-        evaluateNext();
-      }
-    }
-  });
-  var pending = [];
-  var results = [];
-  var currentIndex = 0;
-  function evaluateNext() {
-    if (currentIndex >= pending.length) {
-      emit({ ok: true, candidates: results });
-      return;
-    }
-    try {
-      pending[currentIndex].view.evaluateJavascript(${JSON.stringify(String(script || ''))}, Callback.$new());
-    } catch (error) {
-      var item = pending[currentIndex] || {};
-      results.push({
-        index: item.index,
-        className: item.className,
-        castClassName: item.castClassName,
-        shown: item.shown,
-        url: item.url,
-        error: String(error)
-      });
-      currentIndex += 1;
-      evaluateNext();
-    }
-  }
-  Java.scheduleOnMainThread(function () {
-    try {
-      var activities = activeActivities();
-      var candidates = [];
-      var expectedUrl = ${JSON.stringify(urlIncludes)};
-      var maxCandidates = ${maxCandidates};
-      for (var a = 0; a < activities.length; a++) {
-        var views = [];
-        walk(activities[a].getWindow().getDecorView(), views, 0);
-        for (var i = 0; i < views.length; i++) {
-          var className = toJsString(views[i].getClass().getName());
-          var normalizedClassName = className.toLowerCase();
-          if (normalizedClassName.indexOf('webview') < 0) continue;
-          var casted = castWebView(views[i], className);
-          if (!casted) continue;
-          var shown = false;
-          try { shown = Boolean(views[i].isShown()); } catch (_) { }
-          var url = '';
-          try { url = toJsString(casted.view.getUrl()); } catch (_) { }
-          var meta = { index: candidates.length, className: className, castClassName: casted.className, shown: shown, url: url };
-          candidates.push(meta);
-          if (shown && (!expectedUrl || url.indexOf(expectedUrl) >= 0)) {
-            pending.push({
-              index: meta.index,
-              className: meta.className,
-              castClassName: meta.castClassName,
-              shown: meta.shown,
-              url: meta.url,
-              view: casted.view
-            });
-            if (pending.length >= maxCandidates) break;
-          }
-        }
-        if (pending.length >= maxCandidates) break;
-      }
-      if (pending.length === 0) {
-        emit({ ok: false, error: 'visible WebView not found', candidates: candidates.slice(0, 20) });
-        return;
-      }
-      evaluateNext();
-    } catch (error) {
-      emit({ ok: false, error: String(error), stack: String(error.stack || '') });
-    }
-  });
-});
-`, {
-        label: options.label || 'evaluate-visible-webview',
-        packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 12000,
-        fridaTimeoutSeconds: options.fridaTimeoutSeconds || 8,
-        maxLines: options.maxLines || 80
-    });
-    if (!event.ok) {
-        throw new CrawlerError({
-            message: `automation_failed: evaluateVisibleWebViews failed ${event.error || ''}`.trim(),
-            code: Code.AutomationFailed,
-            context: event
-        });
-    }
-    return event;
-}
-
-function normalizeWebViewClasses(value) {
-    if (Array.isArray(value) && value.length > 0) {
-        const clean = value.map((item) => String(item || '').trim()).filter(Boolean);
-        if (clean.length > 0) return clean;
-    }
-    return [
-        'android.webkit.WebView',
-        'com.tencent.xweb.WebView',
-        'com.tencent.xweb.pinus.sdk.WebView',
-        'com.tencent.xweb.pinus.PSWebview',
-        'com.tencent.mm.ui.widget.MMWebView'
-    ];
-}
-
-function normalizeStringArray(value) {
-    if (!Array.isArray(value)) return [];
-    return value.map((item) => String(item ?? '')).filter((item) => item);
-}
-
-/**
- * 找到目标包名当前可 attach 的 pid。
- *
- * 微信会出现历史 zombie pid；这里优先使用 pidof 返回的最后一个非 Z 状态 pid，
- * 再从 `ps -A` 兜底扫描，避免 Frida attach 到已经退出的进程。
- */
-export async function resolvePid(ctx, packageName = ctx.packageName) {
-    Logger.debug('resolve pid start', {serial: ctx.serial, packageName});
-    const pidof = await adbShell(ctx, ['pidof', packageName]).catch(() => '');
-    const pidCandidates = String(pidof || '').trim().split(/\s+/).filter(Boolean);
-    const ps = await adbShell(ctx, ['ps', '-A', '-o', 'USER,PID,PPID,STAT,NAME']).catch(() => '');
-    const psRows = parsePsRows(ps);
-
-    for (let i = pidCandidates.length - 1; i >= 0; i -= 1) {
-        const pid = pidCandidates[i];
-        const row = psRows.find((item) => item.pid === pid);
-        if (row && row.name === packageName && !row.stat.includes('Z')) {
-            Logger.debug('resolve pid done', {serial: ctx.serial, packageName, pid});
-            return pid;
-        }
-    }
-    for (const row of psRows) {
-        if (row.name === packageName && !row.stat.includes('Z')) {
-            Logger.debug('resolve pid done', {serial: ctx.serial, packageName, pid: row.pid});
-            return row.pid;
-        }
-    }
-
-    const fallbackPs = ps || await adbShell(ctx, ['ps', '-A']);
-    for (const line of String(fallbackPs || '').split('\n')) {
-        const parts = line.trim().split(/\s+/);
-        if (parts.length >= 2 && parts.at(-1) === packageName && !parts.some((part) => /^Z/.test(part))) {
-            Logger.debug('resolve pid done', {serial: ctx.serial, packageName, pid: parts[1]});
-            return parts[1];
-        }
-    }
-    throw new CrawlerError({
-        message: `frida_unavailable: process not found: ${packageName}`,
-        code: Code.FridaUnavailable,
-        context: {packageName}
-    });
-}
-
-async function listFridaServerRows(ctx) {
-    const ps = await adbShell(ctx, ['ps', '-A', '-o', 'USER,PID,PPID,STAT,NAME']).catch(() => '');
-    return parsePsRows(ps).filter((row) => row.name === 'frida-server');
-}
-
-async function canUseSu(ctx) {
-    const out = await adbShell(ctx, ['su', '-c', 'id'], {timeoutMs: 5000}).catch(() => '');
-    return String(out || '').includes('uid=0');
-}
-
-function startFridaLineRecorder(command, args, options = {}) {
-    const marker = options.marker || 'ANDROID_WEBVIEW_EVENT_JSON ';
-    const label = options.label || 'frida-recorder';
-    const maxLines = Math.max(50, Number(options.maxLines || 6000));
-    const lines = [];
-    const events = [];
-    let rawBuffer = '';
-    let stopped = false;
-    let exited = false;
-    let stdoutClosed = false;
-    let stderrClosed = false;
-    let exitCode = null;
-    let exitSignal = null;
-    let fatalError = null;
-
-    const child = spawn(command, args, {stdio: ['ignore', 'pipe', 'pipe']});
-
-    const append = (chunk) => {
-        rawBuffer += String(chunk || '');
-        const parts = rawBuffer.split(/\r?\n/);
-        rawBuffer = parts.pop() || '';
-        for (const line of parts) {
-            lines.push(line);
-            if (lines.length > maxLines) lines.shift();
-            const payload = extractMarkerLinePayload(line, marker);
-            if (!payload) continue;
-            try {
-                events.push(JSON.parse(payload));
-            } catch (error) {
-                events.push({type: 'parse_error', raw: payload, error: String(error)});
-            }
-        }
-    };
-
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
-    child.stdout.on('close', () => {
-        stdoutClosed = true;
-    });
-    child.stderr.on('close', () => {
-        stderrClosed = true;
-    });
-    child.on('error', (error) => {
-        lines.push(`${label} error: ${error.message || String(error)}`);
-        fatalError = makeFridaUnavailableError(label, error.message || String(error), lines);
-    });
-    child.on('exit', (code, signal) => {
-        exited = true;
-        exitCode = code;
-        exitSignal = signal;
-    });
-
-    const snapshot = () => ({
-        pid: child.pid,
-        marker,
-        events: [...events],
-        lines: [...lines],
-        exitCode,
-        exitSignal,
-        error: fatalError ? {message: fatalError.message, code: fatalError.code} : null
-    });
-
-    const waitForStartup = async (timeoutMs) => {
-        const deadline = Date.now() + Math.max(0, timeoutMs);
-        while (Date.now() <= deadline) {
-            if (fatalError) throw fatalError;
-            if (events.length > 0) return snapshot();
-            if (exited) {
-                throw makeFridaUnavailableError(label, `Frida exited before startup code=${exitCode} signal=${exitSignal || ''}`.trim(), lines);
-            }
-            await new Promise((resolve) => setTimeout(resolve, 120));
-        }
-        return snapshot();
-    };
-
-    const waitForEvent = async (predicate, timeoutMs) => {
-        const deadline = Date.now() + Math.max(0, timeoutMs);
-        while (Date.now() <= deadline) {
-            if (fatalError) throw fatalError;
-            const matched = events.find((event) => predicate(event));
-            if (matched) return matched;
-            if (exited) {
-                throw makeFridaUnavailableError(label, `Frida exited while waiting event code=${exitCode} signal=${exitSignal || ''}`.trim(), lines);
-            }
-            await new Promise((resolve) => setTimeout(resolve, 120));
-        }
-        throw makeFridaUnavailableError(label, `Frida event wait timeout: ${options.readyEventLabel || 'event'}`, lines);
-    };
-
-    const waitForExit = async (timeoutMs) => {
-        const deadline = Date.now() + Math.max(0, timeoutMs);
-        while (Date.now() <= deadline) {
-            if (fatalError) throw fatalError;
-            if (exited) return snapshot();
-            await new Promise((resolve) => setTimeout(resolve, 120));
-        }
-        return snapshot();
-    };
-
-    const stop = async () => {
-        if (stopped) return snapshot();
-        stopped = true;
-        if (rawBuffer) append('\n');
-        if (!child.killed) child.kill('SIGTERM');
-        await new Promise((resolve) => {
-            const timer = setTimeout(resolve, 1500);
-            child.once('exit', () => {
-                clearTimeout(timer);
-                resolve();
-            });
-        });
-        if (!exited) child.kill('SIGKILL');
-        if (!exited) {
-            await new Promise((resolve) => {
-                const timer = setTimeout(resolve, 1000);
-                child.once('exit', () => {
-                    clearTimeout(timer);
-                    resolve();
-                });
-            });
-        }
-        await waitForOutputFlush();
-        if (rawBuffer) append('\n');
-        const result = snapshot();
-        if (options.outputPath) {
-            fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
-        }
-        Logger.info(`frida ${label} stopped events=${events.length}`);
-        return result;
-    };
-
-    return {
-        pid: child.pid,
-        waitForEvent,
-        waitForStartup,
-        waitForExit,
-        stop,
-        snapshot
-    };
-
-    async function waitForOutputFlush(timeoutMs = 500) {
-        const deadline = Date.now() + timeoutMs;
-        while (Date.now() < deadline) {
-            if (stdoutClosed && stderrClosed) return;
-            await new Promise((resolve) => setTimeout(resolve, 25));
-        }
-    }
-}
-
-function makeFridaUnavailableError(label, message, lines) {
-    return new CrawlerError({
-        message: `frida_unavailable: ${message}`,
-        code: Code.FridaUnavailable,
-        context: {
-            label,
-            recentLines: [...lines].slice(-20)
-        }
-    });
-}
-
-function writeConfiguredWebViewEventAgent(ctx, config) {
-    const base = fs.readFileSync(ctx.fridaWebViewEventAgentScript, 'utf8');
-    const out = `/tmp/android-toolkit-webview-event-${safeFilePart(ctx.runId || 'manual')}-${Date.now()}.js`;
-    const source = [
-        `globalThis.__ANDROID_TOOLKIT_WEBVIEW_EVENT_CONFIG__ = ${JSON.stringify(config || {})};`,
-        base
-    ].join('\n');
-    fs.writeFileSync(out, source, 'utf8');
-    return out;
-}
-
-function writeTempScript(ctx, source, label) {
-    const out = `/tmp/android-toolkit-${safeFilePart(label || 'script')}-${safeFilePart(ctx.runId || 'manual')}-${Date.now()}.js`;
-    fs.writeFileSync(out, String(source || ''), 'utf8');
-    return out;
-}
-
-function extractMarkerLinePayload(raw, marker) {
-    const index = String(raw || '').indexOf(marker);
-    if (index < 0) return '';
-    const start = index + marker.length;
-    const newline = String(raw || '').indexOf('\n', start);
-    const end = newline < 0 ? String(raw || '').length : newline;
-    return String(raw || '').slice(start, end).trim();
-}
-
-function parsePsRows(rawPs) {
-    const rows = [];
-    for (const line of String(rawPs || '').split('\n')) {
-        const parts = line.trim().split(/\s+/);
-        if (parts.length < 5 || parts[0] === 'USER') continue;
-        const [user, pid, ppid, stat, ...nameParts] = parts;
-        rows.push({user, pid, ppid, stat, name: nameParts.join(' ')});
-    }
-    return rows;
-}
-
-function assertFridaReady(ctx, scriptPath, scriptLabel) {
-    if (!ctx.serial) throw new Error('device.serial is empty');
-    assertCommandOrFile(ctx.fridaPath, 'frida cli');
-    if (!fs.existsSync(scriptPath)) throw new Error(`${scriptLabel} not found: ${scriptPath}`);
-}
-
-function assertCommandOrFile(value, label) {
-    const command = String(value || '').trim();
-    if (!command) throw new Error(`${label} is empty`);
-    const looksLikePath = command.includes('/') || command.startsWith('.');
-    if (looksLikePath && !fs.existsSync(command)) throw new Error(`${label} not found: ${command}`);
-}
-
-function editorActionCode(action) {
-    if (typeof action === 'number' && Number.isFinite(action)) return Math.trunc(action);
-    const clean = String(action || '').trim().toLowerCase();
-    const codes = {
-        none: 1,
-        go: 2,
-        search: 3,
-        send: 4,
-        next: 5,
-        done: 6,
-        previous: 7
-    };
-    return codes[clean] || codes.search;
-}
-
-function safeFilePart(value) {
-    return String(value).replace(/[^a-zA-Z0-9_.-]+/g, '-');
-}
-
-function shellQuote(value) {
-    return `'${String(value || '').replace(/'/g, `'\\''`)}'`;
-}
-
-export const Frida = {
-    startWebViewEventRecorder,
-    runScript,
-    querySQLite,
-    ensureFridaServer,
-    startActivityInsideApp,
-    setVisibleInputText,
-    performEditorAction,
-    evaluateVisibleWebView,
-    evaluateVisibleWebViews,
-    resolvePid
-};