@skrillex1224/android-toolkit 0.1.0

package/src/frida-client.js

@@ -0,0 +1,429 @@
+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} 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 = {}) {
+    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}`);
+
+    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));
+    return recorder;
+}
+
+/**
+ * 在目标 App 进程内部执行一段短 Frida 脚本，并返回 marker 输出。
+ *
+ * 适合做“从 App 内部启动非 exported Activity”“读取当前 Activity View 树”等
+ * 小动作。业务脚本必须自己 console.log marker JSON；toolkit 只负责 attach、
+ * 收集输出和错误显式化。
+ */
+export async function runScript(ctx, source, options = {}) {
+    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 pid = await resolvePid(ctx, options.packageName || ctx.packageName);
+    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 || 7000));
+    const result = await recorder.stop();
+    const scriptEvents = result.events.filter((event) => event?.type !== 'parse_error');
+    if (scriptEvents.length === 0) {
+        throw new CrawlerError({
+            message: `frida_script_failed: ${options.label || 'script'} did not emit ${marker.trim()}`,
+            code: Code.FridaUnavailable,
+            context: {lines: result.lines.slice(-40)}
+        });
+    }
+    return scriptEvents.at(-1);
+}
+
+/**
+ * 从 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 || 7000
+    });
+    if (!event.ok) {
+        throw new CrawlerError({
+            message: `automation_failed: startActivityInsideApp failed ${event.error || className}`,
+            code: Code.AutomationFailed,
+            context: event
+        });
+    }
+    return event;
+}
+
+/**
+ * 在当前 App 内部 View 树里查找可见文本节点，返回真实屏幕 bounds。
+ *
+ * 这不是 OCR，也不依赖系统 uiautomator 无障碍树；它在 App 进程内遍历
+ * Activity DecorView。微信这类 App 经常不给 uiautomator 暴露节点，但
+ * App 内部 View 树仍然能拿到 TextView / EditText / List item 的位置。
+ */
+export async function findVisibleTextBounds(ctx, text, options = {}) {
+    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;
+  }
+  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()); } 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
+          });
+        }
+      }
+    }
+    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',
+        packageName: options.packageName || ctx.packageName,
+        timeoutMs: options.timeoutMs || 7000
+    });
+    if (!event.ok) {
+        throw new CrawlerError({
+            message: `automation_failed: findVisibleTextBounds failed ${event.error || text}`,
+            code: Code.AutomationFailed,
+            context: event
+        });
+    }
+    return event.matches || [];
+}
+
+/**
+ * 找到目标包名当前可 attach 的 pid。
+ *
+ * 微信会出现历史 zombie pid；这里优先使用 pidof 返回的最后一个非 Z 状态 pid，
+ * 再从 `ps -A` 兜底扫描，避免 Frida attach 到已经退出的进程。
+ */
+export async function resolvePid(ctx, packageName = ctx.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')) return pid;
+    }
+    for (const row of psRows) {
+        if (row.name === packageName && !row.stat.includes('Z')) 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];
+    }
+    throw new Error(`process not found: ${packageName}`);
+}
+
+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 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.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 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();
+            });
+        });
+        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,
+        waitForStartup,
+        waitForExit,
+        stop,
+        snapshot
+    };
+}
+
+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 safeFilePart(value) {
+    return String(value).replace(/[^a-zA-Z0-9_.-]+/g, '-');
+}
+
+export const Frida = {
+    startWebViewEventRecorder,
+    runScript,
+    startActivityInsideApp,
+    findVisibleTextBounds,
+    resolvePid
+};

package/src/internals/frida/webview_event_agent.js

@@ -0,0 +1,223 @@
+const CONFIG = globalThis.__ANDROID_TOOLKIT_WEBVIEW_EVENT_CONFIG__ || {};
+
+function getConfig() {
+    const webViewClasses = Array.isArray(CONFIG.webViewClasses)
+        ? CONFIG.webViewClasses.map((item) => String(item || '').trim()).filter(Boolean)
+        : [];
+    if (webViewClasses.length === 0) {
+        throw new Error('android-toolkit webview_event_agent requires config.webViewClasses');
+    }
+
+    return {
+        webViewClasses,
+        eventNames: normalizeSet(CONFIG.eventNames),
+        keywords: Array.isArray(CONFIG.keywords)
+            ? CONFIG.keywords.map((item) => String(item || '')).filter(Boolean)
+            : [],
+        includeRawJs: CONFIG.includeRawJs === true,
+        maxRawJsLength: Number(CONFIG.maxRawJsLength || 1200),
+        maxPayloadLength: Number(CONFIG.maxPayloadLength || 4 * 1024 * 1024)
+    };
+}
+
+function normalizeSet(values) {
+    return new Set(Array.isArray(values)
+        ? values.map((item) => String(item || '').trim()).filter(Boolean)
+        : []);
+}
+
+function emit(type, payload) {
+    const safe = payload || {};
+    safe.type = type;
+    safe.pid = Process.id;
+    safe.process = Process.name;
+    console.log(`ANDROID_WEBVIEW_EVENT_JSON ${JSON.stringify(safe)}`);
+}
+
+function clip(value, limit) {
+    const raw = String(value || '');
+    if (limit <= 0 || raw.length <= limit) return raw;
+    return `${raw.slice(0, limit)}...<${raw.length}>`;
+}
+
+function parseJson(value) {
+    const raw = String(value || '').trim();
+    if (!raw) return null;
+    try {
+        return JSON.parse(raw);
+    } catch (_) {
+        return null;
+    }
+}
+
+function extractCallPayload(rawSource) {
+    const source = String(rawSource || '').trim().replace(/^javascript:\s*/i, '').trim();
+    const patterns = [
+        {
+            kind: 'weixin_bridge',
+            re: /^(?:typeof\s+WeixinJSBridge\s*!==\s*['"]undefined['"]\s*&&\s*)?WeixinJSBridge\._handleMessageFromWeixin\(([\s\S]*)\)\s*;?\s*$/
+        },
+        {
+            kind: 'window_callback',
+            re: /^window\[['"]([^'"]+)['"]\]\s*&&\s*\1\(([\s\S]*)\)\s*;?\s*$/
+        },
+        {
+            kind: 'function_callback',
+            re: /^([A-Za-z_$][\w$]*)\(([\s\S]*)\)\s*;?\s*$/
+        }
+    ];
+
+    for (const pattern of patterns) {
+        const match = source.match(pattern.re);
+        if (!match) continue;
+        if (pattern.kind === 'weixin_bridge') {
+            const payload = parseJson(match[1]);
+            const eventName = String(payload?.__event_id || '').trim();
+            return {kind: pattern.kind, eventName, payload};
+        }
+
+        const eventName = String(match[1] || '').trim();
+        const payload = parseJson(match[2]);
+        return {kind: pattern.kind, eventName, payload};
+    }
+
+    return {kind: 'raw', eventName: '', payload: null};
+}
+
+function shouldCapture(config, rawJs, parsed) {
+    const eventName = String(parsed?.eventName || '').trim();
+    if (eventName && config.eventNames.has(eventName)) return true;
+    if (config.keywords.length === 0) return false;
+    const raw = String(rawJs || '');
+    const payloadText = parsed?.payload ? JSON.stringify(parsed.payload) : '';
+    return config.keywords.some((keyword) => raw.includes(keyword) || payloadText.includes(keyword));
+}
+
+function safePayload(config, payload) {
+    if (payload == null) return null;
+    const raw = JSON.stringify(payload);
+    if (raw.length <= config.maxPayloadLength) return payload;
+    return {
+        __androidToolkitTruncated: true,
+        raw: clip(raw, config.maxPayloadLength)
+    };
+}
+
+function callString(instance, methodName) {
+    try {
+        if (typeof instance[methodName] !== 'function') return '';
+        return String(instance[methodName]() || '');
+    } catch (_) {
+        return '';
+    }
+}
+
+function findLoaders(className) {
+    const loaders = [];
+    Java.enumerateClassLoaders({
+        onMatch(loader) {
+            try {
+                loader.findClass(className);
+                loaders.push(loader);
+            } catch (_) { }
+        },
+        onComplete() { }
+    });
+    return loaders;
+}
+
+function hookWithFactory(loader, className, hooker) {
+    const oldLoader = Java.classFactory.loader;
+    try {
+        Java.classFactory.loader = loader;
+        const factory = Java.ClassFactory.get(loader);
+        const klass = factory.use(className);
+        hooker(klass);
+        emit('hook_installed', {className, loader: String(loader)});
+    } catch (error) {
+        emit('hook_error', {className, loader: String(loader), error: String(error)});
+    } finally {
+        Java.classFactory.loader = oldLoader;
+    }
+}
+
+const INSTALLED_HOOKS = new Set();
+
+function installAllHooks(config) {
+    let installed = 0;
+    for (const className of config.webViewClasses) {
+        const loaders = findLoaders(className);
+        if (loaders.length > 0) {
+            emit('loaders', {
+                className,
+                loaderCount: loaders.length,
+                loaders: loaders.map((loader) => String(loader)).slice(0, 5)
+            });
+        }
+        for (const loader of loaders) {
+            const key = `${className}::${String(loader)}`;
+            if (INSTALLED_HOOKS.has(key)) continue;
+            INSTALLED_HOOKS.add(key);
+            hookWithFactory(loader, className, (klass) => {
+                // 通用层只 hook WebView 的“执行 JS 字符串”入口；业务事件名和 payload 解析规则由 config 决定。
+                hookStringMethod(config, klass, className, 'evaluateJavascript');
+                hookStringMethod(config, klass, className, 'evaluateJavaScript');
+                hookStringMethod(config, klass, className, 'loadUrl');
+            });
+            installed += 1;
+        }
+    }
+    return installed;
+}
+
+function hookStringMethod(config, klass, className, methodName) {
+    const method = klass[methodName];
+    if (!method || !method.overloads) return;
+
+    for (const overload of method.overloads) {
+        const signature = overload.argumentTypes.map((item) => item.className).join(',');
+        if (!signature.includes('java.lang.String')) continue;
+
+        overload.implementation = function (...args) {
+            const js = String(args[0] || '');
+            const parsed = extractCallPayload(js);
+            if (shouldCapture(config, js, parsed)) {
+                emit('webview_event', {
+                    className,
+                    methodName,
+                    signature,
+                    url: callString(this, 'getUrl'),
+                    title: callString(this, 'getTitle'),
+                    eventName: parsed.eventName,
+                    eventKind: parsed.kind,
+                    payload: safePayload(config, parsed.payload),
+                    rawJs: config.includeRawJs ? clip(js, config.maxRawJsLength) : ''
+                });
+            }
+            return overload.apply(this, args);
+        };
+    }
+}
+
+if (typeof Java !== 'undefined' && Java.available) {
+    Java.perform(() => {
+        const config = getConfig();
+        emit('agent_ready', {
+            webViewClassCount: config.webViewClasses.length,
+            eventNames: Array.from(config.eventNames),
+            keywordCount: config.keywords.length
+        });
+        installAllHooks(config);
+
+        const pollIntervalMs = Number(CONFIG.loaderPollIntervalMs ?? 1000);
+        if (pollIntervalMs > 0) {
+            setInterval(() => {
+                try {
+                    installAllHooks(config);
+                } catch (error) {
+                    emit('poll_error', {error: String(error)});
+                }
+            }, pollIntervalMs);
+        }
+    });
+}

package/src/launch.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+
+import {ApifyKit} from './apify-kit.js';
+import {createAndroidContext} from './context.js';
+import {Device} from './device.js';
+import {Frida} from './frida-client.js';
+import {Logger} from './logger.js';
+
+export const Launch = {
+    /**
+     * Android androider 的统一入口。
+     *
+     * 这层等价于普通 visitor 里的 Actor.init + Actor.getInput + requestHandler 的组合。
+     * 注意：toolkit 不读取环境变量，input/output 路径必须由具体 androider 的
+     * main.js 显式传入。这样 toolkit 不会和某个 runner、某个云手机平台绑定。
+     *
+     * handler 内建议只写业务流程；输入、ctx、toolkit 模块都从参数里取。
+     */
+    async run(handler, options = {}) {
+        const input = options.input || JSON.parse(fs.readFileSync(requiredOption(options.inputPath, 'inputPath'), 'utf8'));
+        const ctx = options.ctx || createAndroidContext(input, options.contextDefaults || {});
+        const apifyKit = await ApifyKit.useApifyKit({
+            reset: true,
+            input,
+            ctx,
+            inputPath: options.inputPath,
+            outputPath: requiredOption(options.outputPath, 'outputPath')
+        });
+
+        const kit = {
+            ApifyKit: apifyKit,
+            Device,
+            Frida,
+            Logger
+        };
+
+        try {
+            await handler({input, ctx, kit, ApifyKit: apifyKit});
+        } catch (error) {
+            Logger.fail('Launch handler failed', error);
+            if (!apifyKit.hasPushed()) {
+                await apifyKit.pushFailed(error);
+            }
+        }
+    }
+};
+
+function requiredOption(value, name) {
+    const clean = String(value || '').trim();
+    if (!clean) throw new Error(`Launch.run requires ${name}`);
+    return clean;
+}