@skrillex1224/android-toolkit 0.1.2 → 0.1.8

package/src/frida-client.js

@@ -20,11 +20,19 @@ import {Logger, sleep} from './logger.js';
  * 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 event recorder attach pid=${pid}`);
+    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',
@@ -43,6 +51,7 @@ export async function startWebViewEventRecorder(ctx, config = {}, options = {})
         outputPath: options.outputPath || ''
     });
     await recorder.waitForStartup(Number(options.startupTimeoutMs || 3000));
+    Logger.info('frida webview recorder ready', {duration: Logger.duration(startedAt), pid});
     return recorder;
 }
 
@@ -54,26 +63,20 @@ export async function startWebViewEventRecorder(ctx, config = {}, options = {})
  * 收集输出和错误显式化。
  */
 export async function runScript(ctx, source, options = {}) {
-    const attempts = Math.max(1, Number(options.attempts || 3));
-    let lastError = null;
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
-        try {
-            return await runScriptOnce(ctx, source, options);
-        } catch (error) {
-            lastError = error;
-            if (attempt >= attempts || error?.code !== Code.FridaUnavailable) throw error;
-            Logger.warn(`frida ${options.label || 'script'} 第 ${attempt} 次未返回，准备重试`);
-            await sleep(Number(options.retryDelayMs || 800));
-        }
-    }
-    throw lastError;
-}
-
-async function runScriptOnce(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, options.label || 'script');
+    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',
@@ -94,13 +97,216 @@ async function runScriptOnce(ctx, source, options = {}) {
     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: ${options.label || 'script'} did not emit ${marker.trim()}`,
+            message: `frida_script_failed: ${label} did not emit ${marker.trim()}`,
             code: Code.FridaUnavailable,
             context: {lines: result.lines.slice(-40)}
         });
     }
-    return scriptEvents.at(-1);
+    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}
+    });
 }
 
 /**
@@ -132,7 +338,8 @@ Java.perform(function () {
 `, {
         label: options.label || 'start-activity-inside-app',
         packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 7000
+        timeoutMs: options.timeoutMs || 12000,
+        fridaTimeoutSeconds: options.fridaTimeoutSeconds || 10
     });
     if (!event.ok) {
         throw new CrawlerError({
@@ -145,16 +352,27 @@ Java.perform(function () {
 }
 
 /**
- * 在当前 App 内部 View 树里查找可见文本节点，返回真实屏幕 bounds。
+ * 查找当前 App 内部可见 EditText，并直接写入文本。
  *
- * 这不是 OCR，也不依赖系统 uiautomator 无障碍树；它在 App 进程内遍历
- * Activity DecorView。微信这类 App 经常不给 uiautomator 暴露节点，但
- * App 内部 View 树仍然能拿到 TextView / EditText / List item 的位置。
+ * 这是 Android 版的“定位输入框并 fill”基础能力：
+ * - 不走 OCR；
+ * - 不依赖屏幕比例坐标；
+ * - 业务方只传通用筛选条件，例如 hintIncludes；
+ * - toolkit 在 App 进程内遍历 Activity DecorView，选中输入框后 requestFocus/performClick，
+ *   再写入 Editable，保证中文不会被 adb input text 打成乱码。
  */
-export async function findVisibleTextBounds(ctx, text, options = {}) {
+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();
@@ -190,163 +408,191 @@ Java.perform(function () {
     }
     return out;
   }
-  try {
-    var target = ${JSON.stringify(String(text || ''))};
-    var exact = ${options.exact === false ? 'false' : 'true'};
-    var TextView = Java.use('android.widget.TextView');
-    var matches = [];
-    var activities = activeActivities();
-    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;
-        var value = '';
-        try { value = String(Java.cast(view, TextView).getText().toString()); } catch (_) { continue; }
-        if (exact ? value === target : value.indexOf(target) >= 0) {
-          var rect = rectOf(view);
-          if (rect.right <= rect.left || rect.bottom <= rect.top) continue;
-          matches.push({
-            text: value,
-            className: String(view.getClass().getName()),
-            idName: (function () { try { return String(view.getResources().getResourceName(view.getId())); } catch (_) { return ''; } })(),
-            bounds: rect
-          });
+  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 || '') });
     }
-    emit({ ok: true, target: target, matches: matches });
-  } catch (error) {
-    emit({ ok: false, target: ${JSON.stringify(String(text || ''))}, error: String(error), stack: String(error.stack || '') });
-  }
+  });
 });
 `, {
-        label: options.label || 'find-visible-text-bounds',
+        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: findVisibleTextBounds failed ${event.error || text}`,
+            message: `automation_failed: setVisibleInputText failed ${event.error || ''}`.trim(),
             code: Code.AutomationFailed,
             context: event
         });
     }
-    return event.matches || [];
+    return event;
 }
 
 /**
- * 列出当前 App 内部可见输入框。
+ * 触发当前输入框的 IME action。
  *
- * 微信这类 App 往往不给系统 uiautomator 暴露节点，但 App 进程内仍能看到
- * EditText。业务方可以用 hint/text/bounds 挑选输入框，再交给 Device.click
- * 或 setFocusedInputText 使用。
+ * 这对应软键盘右下角的“搜索 / 完成 / 发送”等动作，
+ * 不是硬件 ENTER。很多 App 会区分这两种输入：
+ * `adb shell input keyevent ENTER` 只发送按键事件；
+ * 软键盘按钮会调用当前 InputConnection.performEditorAction(actionCode)。
  */
-export async function findVisibleInputs(ctx, options = {}) {
+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)); }
-  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 inputs = [];
-      var activities = activeActivities();
-      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;
-            inputs.push({
-              text: String(editText.getText().toString()),
-              hint: String(editText.getHint() ? editText.getHint().toString() : ''),
-              className: String(view.getClass().getName()),
-              idName: (function () { try { return String(view.getResources().getResourceName(view.getId())); } catch (_) { return ''; } })(),
-              focused: Boolean(view.hasFocus()),
-              bounds: rect
-            });
-          } catch (_) { }
-        }
+      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;
       }
-      emit({ ok: true, inputs: inputs });
+      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, error: String(error), stack: String(error.stack || '') });
+      emit({ ok: false, actionCode: ${actionCode}, error: String(error), stack: String(error.stack || '') });
     }
   });
 });
 `, {
-        label: options.label || 'find-visible-inputs',
+        label: options.label || 'perform-editor-action',
         packageName: options.packageName || ctx.packageName,
         timeoutMs: options.timeoutMs || 7000
     });
     if (!event.ok) {
         throw new CrawlerError({
-            message: `automation_failed: findVisibleInputs failed ${event.error || ''}`.trim(),
+            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 event.inputs || [];
+    return {
+        ok: true,
+        value: first.value,
+        className: first.className,
+        castClassName: first.castClassName,
+        url: first.url,
+        index: first.index
+    };
 }
 
 /**
- * 给当前获得焦点的 EditText 设置文本，并触发常规输入事件。
+ * 在所有匹配的可见 WebView 中执行同一段 JavaScript。
  *
- * 这比 adb input text 更适合中文，也比直接 setText 更稳：它先 focus 目标
- * EditText，再用 Editable.replace 更新文本，最后把光标放到末尾。
+ * 这是 `evaluateVisibleWebView` 的批量版本，用来处理一个 Activity 内存在多个
+ * WebView 的场景。toolkit 只返回每个候选的原始 evaluateJavascript callback；
+ * 业务方根据自己的页面结构判断哪个候选才是目标页面。
  */
-export async function setFocusedInputText(ctx, text, options = {}) {
+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)); }
-  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 };
+  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 || 20)} || out.length > ${Number(options.maxNodes || 3000)}) return;
+    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');
@@ -374,60 +620,128 @@ Java.perform(function () {
     }
     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 EditText = Java.use('android.widget.EditText');
-      var targetText = ${JSON.stringify(String(text || ''))};
       var activities = activeActivities();
-      var chosen = null;
-      var fallback = null;
+      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 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: String(editText.getText().toString()), hint: String(editText.getHint() ? editText.getHint().toString() : ''), className: String(view.getClass().getName()), focused: Boolean(view.hasFocus()) };
-            if (item.focused) chosen = item;
-            if (!fallback) fallback = item;
-          } catch (_) { }
+          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;
       }
-      chosen = chosen || fallback;
-      if (!chosen) {
-        emit({ ok: false, error: 'visible EditText not found' });
+      if (pending.length === 0) {
+        emit({ ok: false, error: 'visible WebView not found', candidates: candidates.slice(0, 20) });
         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();
-      chosen.view.setText(SpannableStringBuilder.$new(JavaString.$new(targetText)), BufferType.EDITABLE.value);
-      chosen.view.setSelection(targetText.length);
-      emit({
-        ok: true,
-        text: targetText,
-        hint: String(chosen.view.getHint() ? chosen.view.getHint().toString() : ''),
-        className: chosen.className,
-        bounds: chosen.bounds
-      });
+      evaluateNext();
     } catch (error) {
       emit({ ok: false, error: String(error), stack: String(error.stack || '') });
     }
   });
 });
 `, {
-        label: options.label || 'set-focused-input-text',
+        label: options.label || 'evaluate-visible-webview',
         packageName: options.packageName || ctx.packageName,
-        timeoutMs: options.timeoutMs || 7000
+        timeoutMs: options.timeoutMs || 12000,
+        fridaTimeoutSeconds: options.fridaTimeoutSeconds || 8,
+        maxLines: options.maxLines || 80
     });
     if (!event.ok) {
         throw new CrawlerError({
-            message: `automation_failed: setFocusedInputText failed ${event.error || ''}`.trim(),
+            message: `automation_failed: evaluateVisibleWebViews failed ${event.error || ''}`.trim(),
             code: Code.AutomationFailed,
             context: event
         });
@@ -435,6 +749,25 @@ Java.perform(function () {
     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。
  *
@@ -442,6 +775,7 @@ Java.perform(function () {
  * 再从 `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(() => '');
@@ -450,18 +784,41 @@ export async function resolvePid(ctx, packageName = ctx.packageName) {
     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')) return 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')) return row.pid;
+        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))) return parts[1];
+        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 Error(`process not found: ${packageName}`);
+    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 = {}) {
@@ -473,6 +830,8 @@ function startFridaLineRecorder(command, args, options = {}) {
     let rawBuffer = '';
     let stopped = false;
     let exited = false;
+    let stdoutClosed = false;
+    let stderrClosed = false;
     let exitCode = null;
     let exitSignal = null;
     let fatalError = null;
@@ -498,6 +857,12 @@ function startFridaLineRecorder(command, args, options = {}) {
 
     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);
@@ -531,6 +896,20 @@ function startFridaLineRecorder(command, args, options = {}) {
         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) {
@@ -553,6 +932,18 @@ function startFridaLineRecorder(command, args, options = {}) {
                 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');
@@ -563,11 +954,20 @@ function startFridaLineRecorder(command, args, options = {}) {
 
     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) {
@@ -631,16 +1031,38 @@ function assertCommandOrFile(value, label) {
     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,
-    findVisibleTextBounds,
-    findVisibleInputs,
-    setFocusedInputText,
+    setVisibleInputText,
+    performEditorAction,
+    evaluateVisibleWebView,
+    evaluateVisibleWebViews,
     resolvePid
 };