@skrillex1224/android-toolkit 0.1.1 → 0.1.7

package/README.md

@@ -13,7 +13,7 @@ const { Launch } = useAndroidToolKit();
 await Launch.run(async ({ input, ctx, kit }) => {
   const result = await kit.ApifyKit.runStep('执行业务流程', null, async () => {
     await kit.Device.forceStopApp(ctx, ctx.packageName);
-    await kit.Device.tapRatio(ctx, 0.5, 0.5);
+    await kit.Device.click(ctx, { x: 360, y: 640 });
     return { answer: `echo: ${input.query}`, sources: [] };
   });
 
@@ -34,7 +34,7 @@ await Launch.run(async ({ input, ctx, kit }) => {
 | `Launch` | 接受显式 `inputPath` / `outputPath`，创建 `ctx`，调用业务 handler |
 | `ApifyKit` | 提供 `runStep`、`runStepLoose`、`pushSuccess`、`pushFailed`，并统一补齐 `code/status/timestamp/data` |
 | `Device` | ADB 操作层：启动、点击、滑动、输入中文、截图、Activity 检查 |
-| `Frida` | 启动 WebView event recorder，记录 `evaluateJavascript` / `loadUrl` 注入事件 |
+| `Frida` | Frida attach、短脚本执行、SQLite 查询、WebView event recorder |
 | `Context` | 从显式 input/defaults 生成 Android 运行上下文 |
 | `Errors` | `CrawlerError` 和错误序列化；失败码由业务显式抛出的 `CrawlerError` 决定 |
 
@@ -44,6 +44,7 @@ await Launch.run(async ({ input, ctx, kit }) => {
 
 - ADB 执行、云手机 TCP ADB 离线重连、点击、滑动、截图、中文输入。
 - Frida attach 目标 App pid，并启动 WebView JS 注入事件 recorder。
+- App 进程内 SQLite 查询：业务方提供 db 路径规则、SQL 和参数，toolkit 只返回 cursor rows。
 - `runStep` / `runStepLoose` / `pushSuccess` / `pushFailed`。
 - 通用错误码和失败 dataset 兜底结构。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrillex1224/android-toolkit",
-  "version": "0.1.1",
+  "version": "0.1.7",
   "type": "module",
   "main": "index.js",
   "exports": {

package/src/apify-kit.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import {Code, Status} from './constants.js';
 import {createAndroidContext} from './context.js';
 import {CrawlerError, serializeError} from './errors.js';
-import {Logger, sleep} from './logger.js';
+import {Logger} from './logger.js';
 
 let instance = null;
 
@@ -30,46 +30,25 @@ async function createApifyKit(options = {}) {
          * - step 是中文步骤名；
          * - target 位置保留给 device/session，便于未来接入云真机 live view；
          * - actionFn 是真正业务动作；
-         * - retry 支持 direct / before hook；
          * - failActor=true 时会先 pushFailed，再把错误继续抛给 Launch。
          */
         async runStep(step, target, actionFn, options = {}) {
             if (target) lastDevice = target;
-            const {failActor = true, retry = {}} = options;
-            const retryTimes = Number(retry.times || 0);
-            let lastError = null;
-
-            for (let attempt = 0; attempt <= retryTimes; attempt += 1) {
-                const suffix = attempt > 0 ? ` (重试 #${attempt})` : '';
-                Logger.start(`[Step] ${step}${suffix}`);
-                try {
-                    const result = await actionFn();
-                    Logger.success(`[Step] ${step}${suffix}`);
-                    return result;
-                } catch (error) {
-                    lastError = error;
-                    Logger.fail(`[Step] ${step}${suffix}`, error);
-                    if (attempt < retryTimes) {
-                        if (typeof retry.before === 'function') {
-                            Logger.start(`[RetryStep] 执行 before 钩子: ${step}`);
-                            await retry.before(target, attempt + 1, error);
-                            Logger.success(`[RetryStep] before 钩子完成: ${step}`);
-                        } else {
-                            const delayMs = Number(retry.delayMs || 3000);
-                            Logger.start(`[RetryStep] 等待 ${delayMs}ms: ${step}`);
-                            await sleep(delayMs);
-                        }
-                    }
+            const {failActor = true} = options;
+            const startedAt = Date.now();
+
+            Logger.start(`[Step] ${step}`, stepDetail({target, failActor}));
+            try {
+                const result = await actionFn();
+                Logger.success(`[Step] ${step}`, {duration: Logger.duration(startedAt)});
+                return result;
+            } catch (error) {
+                Logger.fail(`[Step] ${step} duration=${Logger.duration(startedAt)}`, error);
+                if (failActor) {
+                    await this.pushFailed(error, {step}, {target});
                 }
+                throw error;
             }
-
-            if (failActor) {
-                await this.pushFailed(lastError, {
-                    step,
-                    retryAttempts: retryTimes
-                }, {target});
-            }
-            throw lastError;
         },
 
         /**
@@ -92,15 +71,19 @@ async function createApifyKit(options = {}) {
          * code/status/timestamp/data 外壳。这样 commander/transformer 看到的是同类结构。
          */
         async pushSuccess(data = {}, options = {}) {
+            const dataSummary = summarizeDatasetData(data);
             pushed = true;
-            fs.writeFileSync(io.outputPath, JSON.stringify([{
+            appendOutput(io.outputPath, {
                 code: Code.Success,
                 status: Status.Success,
                 timestamp: new Date().toISOString(),
                 data: sanitizeData(data),
                 ...(options.meta ? {meta: sanitizeData(options.meta)} : {})
-            }], null, 2) + '\n', 'utf8');
-            Logger.success('pushSuccess', 'Data pushed');
+            });
+            Logger.success('pushSuccess', {
+                outputPath: io.outputPath,
+                ...dataSummary
+            });
         },
 
         /**
@@ -115,15 +98,19 @@ async function createApifyKit(options = {}) {
                 : CrawlerError.from(error, {code: Code.UnknownError, context: meta});
 
             pushed = true;
-            fs.writeFileSync(io.outputPath, JSON.stringify([{
+            appendOutput(io.outputPath, {
                 code: normalized.code,
                 status: Status.Failed,
                 error: serializeError(normalized),
                 meta: sanitizeData(meta),
                 context: sanitizeData(normalized.context),
                 timestamp: new Date().toISOString()
-            }], null, 2) + '\n', 'utf8');
-            Logger.success('pushFailed', 'Error data pushed');
+            });
+            Logger.success('pushFailed', {
+                outputPath: io.outputPath,
+                code: normalized.code,
+                message: normalized.message
+            });
         },
 
         hasPushed() {
@@ -147,12 +134,50 @@ export const ApifyKit = {
     useApifyKit
 };
 
+function appendOutput(outputPath, item) {
+    const items = readOutputArray(outputPath);
+    items.push(item);
+    fs.writeFileSync(outputPath, JSON.stringify(items, null, 2) + '\n', 'utf8');
+}
+
+function readOutputArray(outputPath) {
+    if (!fs.existsSync(outputPath)) return [];
+    const raw = fs.readFileSync(outputPath, 'utf8').trim();
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`Android output must be a JSON array: ${outputPath}`);
+    }
+    return parsed;
+}
+
 function requiredOption(value, name) {
     const clean = String(value || '').trim();
     if (!clean) throw new Error(`ApifyKit.useApifyKit requires ${name}`);
     return clean;
 }
 
+function stepDetail({target, failActor}) {
+    const detail = {failActor};
+    if (!target) return detail;
+    if (typeof target === 'string') detail.target = target;
+    else if (typeof target === 'object') {
+        detail.serial = target.serial;
+        detail.packageName = target.packageName;
+        detail.runId = target.runId;
+    }
+    return detail;
+}
+
+function summarizeDatasetData(data) {
+    const summary = {};
+    if (typeof data?.answer === 'string') summary.answerChars = data.answer.length;
+    if (Array.isArray(data?.sources)) summary.sourceCount = data.sources.length;
+    if (data?.imMessage?.message_id) summary.messageId = data.imMessage.message_id;
+    if (data?.imMessage?.local_message_id) summary.localMessageId = data.imMessage.local_message_id;
+    return summary;
+}
+
 function sanitizeData(value, depth = 0, seen = new WeakSet()) {
     if (depth > 8) return '[MaxDepth]';
     if (value == null) return value;

package/src/constants.js

@@ -15,7 +15,8 @@ export const Code = {
   AutomationFailed: 30010005,
   RunnerFailed: 30010006,
   AppiumUnavailable: 30010007,
-  FridaUnavailable: 30010008
+  FridaUnavailable: 30010008,
+  AppNotInstalled: 30010009
 };
 
 export const Status = {

package/src/context.js

@@ -8,7 +8,6 @@ const toolkitRoot = path.resolve(__dirname, '..');
 export const Context = {
     createAndroidContext,
     firstNonEmpty,
-    trimRight,
     toolkitPath
 };
 
@@ -40,8 +39,6 @@ export function createAndroidContext(input = {}, defaults = {}) {
             defaults.fridaWebViewEventAgentScript,
             toolkitPath('src/internals/frida/webview_event_agent.js')
         ),
-        appiumServerUrl: trimRight(firstNonEmpty(defaults.appiumServerUrl), '/'),
-        appiumSessionId: firstNonEmpty(defaults.appiumSessionId),
         appVersion: firstNonEmpty(defaults.appVersion),
         slotKey: firstNonEmpty(defaults.slotKey),
         instanceId: firstNonEmpty(defaults.instanceId),
@@ -61,12 +58,6 @@ export function firstNonEmpty(...values) {
     return '';
 }
 
-export function trimRight(value, suffix) {
-    let out = String(value || '').trim();
-    while (suffix && out.endsWith(suffix)) out = out.slice(0, -suffix.length);
-    return out;
-}
-
 function normalizeRuntimeDevice(value) {
     if (typeof value === 'string') return {serial: value};
     if (value && typeof value === 'object') return value;

package/src/device.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 
+import {Code} from './constants.js';
+import {CrawlerError} from './errors.js';
 import {Logger, sleep} from './logger.js';
 
 const execFileAsync = promisify(execFile);
@@ -14,35 +16,52 @@ export async function adbShell(ctx, args, options = {}) {
 
 export async function adbExec(ctx, args, options = {}) {
     // 执行原始 adb 命令；当云手机/TCP ADB 临时 offline 时，自动 adb connect 后重放一次。
+    const startedAt = Date.now();
+    Logger.debug('adb exec', {serial: ctx.serial, args: compactArgs(args), timeoutMs: Number(options.timeoutMs || 15000)});
     try {
         const {stdout} = await execFileAsync(ctx.adbPath, args, {
             timeout: Number(options.timeoutMs || 15000),
             maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
             encoding: options.encoding || 'utf8'
         });
+        Logger.debug('adb exec done', {serial: ctx.serial, duration: Logger.duration(startedAt)});
         return stdout;
     } catch (error) {
         // ADB over TCP 的云手机/云真机场景经常临时 offline。
         // 这里统一做一次 adb connect + 原命令重放，业务层不需要关心连接抖动。
-        if (!isAdbOfflineError(error) || !ctx.serial) throw error;
+        if (!isAdbOfflineError(error) || !ctx.serial) {
+            if (isAdbUnavailableError(error)) throw makeAdbUnavailableError(ctx, args, error);
+            Logger.warn('adb exec failed', {serial: ctx.serial, args: compactArgs(args), message: error?.message || String(error)});
+            throw error;
+        }
+        Logger.warn('adb offline, reconnecting', {serial: ctx.serial, args: compactArgs(args)});
         await execFileAsync(ctx.adbPath, ['connect', ctx.serial], {timeout: 15000}).catch(() => { });
         await sleep(1200);
-        const {stdout} = await execFileAsync(ctx.adbPath, args, {
-            timeout: Number(options.timeoutMs || 15000),
-            maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
-            encoding: options.encoding || 'utf8'
-        });
-        return stdout;
+        try {
+            const {stdout} = await execFileAsync(ctx.adbPath, args, {
+                timeout: Number(options.timeoutMs || 15000),
+                maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
+                encoding: options.encoding || 'utf8'
+            });
+            Logger.debug('adb exec retry done', {serial: ctx.serial, duration: Logger.duration(startedAt)});
+            return stdout;
+        } catch (retryError) {
+            if (isAdbUnavailableError(retryError)) throw makeAdbUnavailableError(ctx, args, retryError);
+            Logger.warn('adb exec retry failed', {serial: ctx.serial, args: compactArgs(args), message: retryError?.message || String(retryError)});
+            throw retryError;
+        }
     }
 }
 
 export async function forceStopApp(ctx, packageName = ctx.packageName) {
     // 强制关闭 App，用于每条任务开始前清理上一次页面状态。
+    Logger.info('force stop app', {serial: ctx.serial, packageName});
     await adbShell(ctx, ['am', 'force-stop', packageName]).catch(() => { });
 }
 
 export async function startActivity(ctx, component, args = []) {
     // 启动指定 Android Activity，component 形如 `com.tencent.mm/.ui.LauncherUI`。
+    Logger.info('start activity', {serial: ctx.serial, component});
     await adbShell(ctx, ['am', 'start', '-n', component, ...args]);
     await sleep(1800);
 }
@@ -55,11 +74,6 @@ export async function startLauncher(ctx, packageName = ctx.packageName, launcher
     ]);
 }
 
-export async function launchPackageByMonkey(ctx, packageName = ctx.packageName) {
-    // launcher 启动失败时的兜底：让 Android 自己找包的默认入口。
-    await adbShell(ctx, ['monkey', '-p', packageName, '1']);
-}
-
 export async function waitForForeground(ctx, packageName = ctx.packageName, timeoutMs = 6000) {
     // 轮询前台 Activity，直到目标包名进入前台或超时。
     const deadline = Date.now() + timeoutMs;
@@ -81,21 +95,6 @@ export async function screenSize(ctx) {
     };
 }
 
-export function px(ctx, ratio) {
-    // 把横向比例坐标转成屏幕像素。
-    return String(Math.floor((ctx.screen?.width || 720) * ratio));
-}
-
-export function py(ctx, ratio) {
-    // 把纵向比例坐标转成屏幕像素。
-    return String(Math.floor((ctx.screen?.height || 1280) * ratio));
-}
-
-export async function tapRatio(ctx, x, y) {
-    // 点击比例坐标，适合不同分辨率设备共用同一套大致点位。
-    await adbInput(ctx, ['tap', px(ctx, x), py(ctx, y)]);
-}
-
 export async function tapAbsolute(ctx, x, y) {
     // 点击绝对像素坐标，适合已经从截图或 DOM rect 算出的精确点。
     await adbInput(ctx, ['tap', String(Math.round(Number(x))), String(Math.round(Number(y)))]);
@@ -116,11 +115,6 @@ export async function click(ctx, pointOrX, y) {
     return tapAbsolute(ctx, pointOrX, y);
 }
 
-export async function swipeRatio(ctx, fromX, fromY, toX, toY, durationMs = 500) {
-    // 使用比例坐标滑动，适合滚动列表、收起弹层等通用手势。
-    await adbInput(ctx, ['swipe', px(ctx, fromX), py(ctx, fromY), px(ctx, toX), py(ctx, toY), String(durationMs)]);
-}
-
 export async function move(ctx, from, to, durationMs = 500) {
     // ADB 没有鼠标 hover 概念，这里的 move 表示拖动/滑动手势。
     // from/to 使用屏幕绝对坐标，便于和截图/其他定位结果直接衔接。
@@ -139,35 +133,66 @@ export async function pressBack(ctx) {
     await adbInput(ctx, ['keyevent', 'BACK']).catch(() => { });
 }
 
-export async function pressEnter(ctx) {
-    // 发送 Android 回车键，常用于提交搜索框。
-    await adbInput(ctx, ['keyevent', 'ENTER']).catch(() => { });
+export async function dismissPermissionDialog(ctx) {
+    // Android 运行时权限弹窗会把原 App 的 Activity 压在下面。
+    // 这里只处理系统 permission controller：点击底部“拒绝”按钮区域，避免采集任务卡死。
+    const focused = await focusedActivity(ctx).catch(() => '');
+    if (!String(focused || '').includes('GrantPermissionsActivity')) return false;
+    const size = await screenSize(ctx);
+    await tapAbsolute(ctx, size.width * 0.50, size.height * 0.63).catch(() => { });
+    await sleep(1000);
+    return true;
 }
 
 export async function wakeAndUnlock(ctx) {
     // 唤醒并解锁设备。真机/云手机在息屏时 dumpsys 可能仍保留上一个 App，
     // 业务层会误判前台 Activity，所以每条原生任务开始前都应该先恢复可交互屏幕。
+    Logger.info('wake and unlock', {serial: ctx.serial});
     await adbInput(ctx, ['keyevent', 'KEYCODE_WAKEUP']).catch(() => { });
     await sleep(500);
     await adbInput(ctx, ['keyevent', 'MENU']).catch(() => { });
     await sleep(500);
-    await swipeRatio(ctx, 0.50, 0.82, 0.50, 0.25, 350).catch(() => { });
+    await swipeScreenRatio(ctx, 0.50, 0.82, 0.50, 0.25, 350).catch(() => { });
     await sleep(800);
 }
 
 export async function focusedActivity(ctx) {
+    // 优先从 activity manager 读取 resumed activity。`dumpsys window` 在微信 WebView
+    // 场景里可能同时保留旧窗口和新窗口，直接读 window focus 容易误判。
+    const resumed = await resumedActivity(ctx).catch(() => '');
+    if (resumed) return resumed;
+
     // 从 dumpsys window 中提取当前前台 Activity，用于替代 OCR 做页面状态判断。
     const out = await adbShell(ctx, ['dumpsys', 'window']);
     let fallback = '';
-    let focused = '';
+    let currentFocus = '';
+    let appWindowFocus = '';
     for (const line of String(out || '').split('\n')) {
-        if (line.includes('mCurrentFocus') || line.includes('mFocusedApp')) {
-            const trimmed = line.trim();
-            if (!fallback) fallback = trimmed;
-            if (!trimmed.includes('=null')) focused = trimmed;
-        }
+        const trimmed = line.trim();
+        if (!trimmed.includes('mCurrentFocus') && !trimmed.includes('mFocusedApp')) continue;
+        if (!fallback) fallback = trimmed;
+        if (trimmed.includes('=null')) continue;
+        // dumpsys window 里会同时出现当前窗口和历史 token 行。
+        // 只信真实窗口焦点和 AppWindowToken，避免把旧 LauncherUI Token 当成当前页。
+        if (trimmed.includes('mCurrentFocus=Window')) currentFocus = trimmed;
+        else if (trimmed.includes('mFocusedApp=AppWindowToken')) appWindowFocus = trimmed;
     }
-    return focused || fallback || String(out || '').trim();
+    return currentFocus || appWindowFocus || fallback || String(out || '').trim();
+}
+
+async function resumedActivity(ctx) {
+    const out = await adbShell(ctx, ['dumpsys', 'activity', 'activities'], {
+        timeoutMs: 15000,
+        maxBuffer: 12 * 1024 * 1024
+    });
+    let fallback = '';
+    for (const line of String(out || '').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.includes('ActivityRecord') || !trimmed.includes('/')) continue;
+        if (trimmed.includes('mTopResumedActivity') || trimmed.includes('topResumedActivity')) return trimmed;
+        if (trimmed.includes('mResumedActivity')) fallback = trimmed;
+    }
+    return fallback;
 }
 
 export function activityIncludes(focused, fragment) {
@@ -177,10 +202,15 @@ export function activityIncludes(focused, fragment) {
 
 export async function waitForActivity(ctx, predicate, timeoutMs = 15000, intervalMs = 700) {
     // 等待前台 Activity 满足调用方 predicate。
+    const startedAt = Date.now();
+    Logger.info('wait activity start', {serial: ctx.serial, timeoutMs, intervalMs});
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const focused = await focusedActivity(ctx).catch(() => '');
-        if (predicate(focused)) return focused;
+        if (predicate(focused)) {
+            Logger.info('wait activity matched', {serial: ctx.serial, duration: Logger.duration(startedAt), focused: summarizeText(focused, 160)});
+            return focused;
+        }
         await sleep(intervalMs);
     }
     throw new Error(`waitForActivity timeout: focused=${await focusedActivity(ctx).catch(() => '')}`);
@@ -249,20 +279,7 @@ export async function type(ctx, text) {
 }
 
 async function adbInput(ctx, args, options = {}) {
-    // input tap/swipe/keyevent 在真机和云手机上偶发返回非 0，但重放同一条命令通常会成功。
-    // 这层只兜底设备输入抖动；页面级失败仍然交给业务 runStep/任务重试判断。
-    const retryTimes = Math.max(0, Number(options.retryTimes ?? 2));
-    let lastError = null;
-    for (let attempt = 0; attempt <= retryTimes; attempt += 1) {
-        try {
-            return await adbShell(ctx, ['input', ...args], options);
-        } catch (error) {
-            lastError = error;
-            if (attempt >= retryTimes || !isRetryableAdbInputError(error)) throw error;
-            await sleep(250 * (attempt + 1));
-        }
-    }
-    throw lastError;
+    await adbShell(ctx, ['input', ...args], options);
 }
 
 function isAdbOfflineError(error) {
@@ -270,12 +287,20 @@ function isAdbOfflineError(error) {
     return message.includes('device offline') || message.includes('device unauthorized');
 }
 
-function isRetryableAdbInputError(error) {
+function isAdbUnavailableError(error) {
     const message = String(error?.message || error || '').toLowerCase();
-    if (isAdbOfflineError(error)) return true;
-    if (message.includes('command failed:') && message.includes(' shell input ')) return true;
-    if (message.includes('closed') || message.includes('broken pipe') || message.includes('connection reset')) return true;
-    return false;
+    return message.includes('device not found') || message.includes('no devices/emulators found');
+}
+
+function makeAdbUnavailableError(ctx, args, error) {
+    return new CrawlerError({
+        message: `adb_unavailable: ${error?.message || String(error)}`,
+        code: Code.AdbUnavailable,
+        context: {
+            serial: ctx.serial,
+            args
+        }
+    });
 }
 
 function isBounds(value) {
@@ -287,6 +312,18 @@ function isBounds(value) {
     return [left, top, right, bottom].every(Number.isFinite) && right > left && bottom > top;
 }
 
+async function swipeScreenRatio(ctx, fromX, fromY, toX, toY, durationMs = 500) {
+    const size = await screenSize(ctx).catch(() => ({width: 720, height: 1280}));
+    await adbInput(ctx, [
+        'swipe',
+        String(Math.floor(size.width * fromX)),
+        String(Math.floor(size.height * fromY)),
+        String(Math.floor(size.width * toX)),
+        String(Math.floor(size.height * toY)),
+        String(durationMs)
+    ]);
+}
+
 function safeFilePart(value) {
     return String(value).replace(/[^a-zA-Z0-9_.-]+/g, '-');
 }
@@ -313,24 +350,29 @@ function adbInputTextForShell(raw) {
     return `''${escapedText}''`;
 }
 
+function compactArgs(args) {
+    return (args || []).map((arg) => summarizeText(arg, 80)).join(' ');
+}
+
+function summarizeText(value, maxLen) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    if (text.length <= maxLen) return text;
+    return `${text.slice(0, maxLen)}...`;
+}
+
 export const Device = {
     adbShell,
     adbExec,
     forceStopApp,
     startActivity,
     startLauncher,
-    launchPackageByMonkey,
     waitForForeground,
     screenSize,
-    px,
-    py,
-    tapRatio,
     tapAbsolute,
     click,
-    swipeRatio,
     move,
     pressBack,
-    pressEnter,
+    dismissPermissionDialog,
     wakeAndUnlock,
     focusedActivity,
     activityIncludes,