@skrillex1224/android-toolkit 0.1.0

package/src/device.js

@@ -0,0 +1,344 @@
+import fs from 'node:fs';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+
+import {Logger, sleep} from './logger.js';
+
+const execFileAsync = promisify(execFile);
+
+export async function adbShell(ctx, args, options = {}) {
+    // 在指定设备上执行 `adb shell ...`，所有设备侧命令都从这里收口。
+    if (!ctx.serial) throw new Error('device.serial is empty');
+    return adbExec(ctx, ['-s', ctx.serial, 'shell', ...args], options);
+}
+
+export async function adbExec(ctx, args, options = {}) {
+    // 执行原始 adb 命令；当云手机/TCP ADB 临时 offline 时，自动 adb connect 后重放一次。
+    try {
+        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;
+    } catch (error) {
+        // ADB over TCP 的云手机/云真机场景经常临时 offline。
+        // 这里统一做一次 adb connect + 原命令重放，业务层不需要关心连接抖动。
+        if (!isAdbOfflineError(error) || !ctx.serial) throw error;
+        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;
+    }
+}
+
+export async function forceStopApp(ctx, packageName = ctx.packageName) {
+    // 强制关闭 App，用于每条任务开始前清理上一次页面状态。
+    await adbShell(ctx, ['am', 'force-stop', packageName]).catch(() => { });
+}
+
+export async function startActivity(ctx, component, args = []) {
+    // 启动指定 Android Activity，component 形如 `com.tencent.mm/.ui.LauncherUI`。
+    await adbShell(ctx, ['am', 'start', '-n', component, ...args]);
+    await sleep(1800);
+}
+
+export async function startLauncher(ctx, packageName = ctx.packageName, launcherActivity = '.ui.LauncherUI') {
+    // 按 launcher 方式启动 App 首页；业务方只需要传包名和首页 Activity。
+    await startActivity(ctx, `${packageName}/${launcherActivity}`, [
+        '-a', 'android.intent.action.MAIN',
+        '-c', 'android.intent.category.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;
+    while (Date.now() < deadline) {
+        const focused = await focusedActivity(ctx).catch(() => '');
+        if (focused.includes(packageName)) return true;
+        await sleep(500);
+    }
+    return false;
+}
+
+export async function screenSize(ctx) {
+    // 读取屏幕尺寸，失败时给一个常见竖屏默认值，避免后续坐标计算崩掉。
+    const out = await adbShell(ctx, ['wm', 'size']).catch(() => '');
+    const match = /(\d+)x(\d+)/.exec(String(out || ''));
+    return {
+        width: match ? Number(match[1]) : 720,
+        height: match ? Number(match[2]) : 1280
+    };
+}
+
+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)))]);
+}
+
+export async function click(ctx, pointOrX, y) {
+    // 对齐 Playwright 的直觉命名：业务代码可以写 Device.click(ctx, point)，
+    // 也可以直接传 View/DOM bounds。toolkit 统一判断点击中心点。
+    if (pointOrX && typeof pointOrX === 'object') {
+        if (isBounds(pointOrX)) {
+            return tapAbsolute(ctx, (Number(pointOrX.left) + Number(pointOrX.right)) / 2, (Number(pointOrX.top) + Number(pointOrX.bottom)) / 2);
+        }
+        if (isBounds(pointOrX.bounds)) {
+            return tapAbsolute(ctx, (Number(pointOrX.bounds.left) + Number(pointOrX.bounds.right)) / 2, (Number(pointOrX.bounds.top) + Number(pointOrX.bounds.bottom)) / 2);
+        }
+        return tapAbsolute(ctx, pointOrX.x, 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 使用屏幕绝对坐标，便于和截图/其他定位结果直接衔接。
+    await adbInput(ctx, [
+        'swipe',
+        String(Math.round(Number(from?.x))),
+        String(Math.round(Number(from?.y))),
+        String(Math.round(Number(to?.x))),
+        String(Math.round(Number(to?.y))),
+        String(durationMs)
+    ]);
+}
+
+export async function pressBack(ctx) {
+    // 发送 Android 返回键。
+    await adbInput(ctx, ['keyevent', 'BACK']).catch(() => { });
+}
+
+export async function pressEnter(ctx) {
+    // 发送 Android 回车键，常用于提交搜索框。
+    await adbInput(ctx, ['keyevent', 'ENTER']).catch(() => { });
+}
+
+export async function wakeAndUnlock(ctx) {
+    // 唤醒并解锁设备。真机/云手机在息屏时 dumpsys 可能仍保留上一个 App，
+    // 业务层会误判前台 Activity，所以每条原生任务开始前都应该先恢复可交互屏幕。
+    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 sleep(800);
+}
+
+export async function focusedActivity(ctx) {
+    // 从 dumpsys window 中提取当前前台 Activity，用于替代 OCR 做页面状态判断。
+    const out = await adbShell(ctx, ['dumpsys', 'window']);
+    let fallback = '';
+    let focused = '';
+    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;
+        }
+    }
+    return focused || fallback || String(out || '').trim();
+}
+
+export function activityIncludes(focused, fragment) {
+    // 小工具：判断当前 Activity 文本是否包含目标片段。
+    return String(focused || '').includes(fragment);
+}
+
+export async function waitForActivity(ctx, predicate, timeoutMs = 15000, intervalMs = 700) {
+    // 等待前台 Activity 满足调用方 predicate。
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const focused = await focusedActivity(ctx).catch(() => '');
+        if (predicate(focused)) return focused;
+        await sleep(intervalMs);
+    }
+    throw new Error(`waitForActivity timeout: focused=${await focusedActivity(ctx).catch(() => '')}`);
+}
+
+export async function screenshotBase64(ctx) {
+    // 获取当前屏幕 PNG，并转成 base64 写入 dataset artifact。
+    const stdout = await adbExec(ctx, ['-s', ctx.serial, 'exec-out', 'screencap', '-p'], {
+        timeoutMs: 15000,
+        encoding: 'buffer',
+        maxBuffer: 8 * 1024 * 1024
+    });
+    return Buffer.from(stdout).toString('base64');
+}
+
+export async function saveDebugScreenshot(ctx, name) {
+    // 保存调试截图到 /tmp，主要用于本地定位点击点和页面状态。
+    if (!ctx.serial) return '';
+    const safeRunId = safeFilePart(ctx.runId || 'manual');
+    const safeName = safeFilePart(name || 'screenshot');
+    const out = `/tmp/android-toolkit-${safeRunId}-${safeName}.png`;
+    const stdout = await adbExec(ctx, ['-s', ctx.serial, 'exec-out', 'screencap', '-p'], {
+        timeoutMs: 15000,
+        encoding: 'buffer',
+        maxBuffer: 8 * 1024 * 1024
+    });
+    fs.writeFileSync(out, stdout);
+    Logger.info(`debug screenshot saved ${out}`);
+    return out;
+}
+
+export async function clearInputByDelete(ctx, count = 40) {
+    // 先把光标移到文本末尾再删除。微信搜索框里如果光标停在中间，
+    // 直接 DEL 会只删前半段，留下旧 query 尾巴污染下一次搜索。
+    await adbInput(ctx, ['keyevent', 'KEYCODE_MOVE_END']).catch(() => { });
+    await sleep(150);
+    for (let i = 0; i < count; i += 1) {
+        await adbInput(ctx, ['keyevent', 'DEL']).catch(() => { });
+    }
+}
+
+export async function typeText(ctx, text) {
+    // 输入中文文本。要求设备安装 Appium Settings，因为原生 adb input text 不支持可靠中文。
+    const value = String(text || '');
+    if (!value) return;
+    const unicodeIME = 'io.appium.settings/.UnicodeIME';
+    const previousIME = String(await adbShell(ctx, ['settings', 'get', 'secure', 'default_input_method']).catch(() => '')).trim();
+    try {
+        // 中文输入统一走 Appium Settings UnicodeIME 思路：
+        // 普通 `adb input text` 会把中文打成乱码；IMAP UTF-7 编码可以让 UnicodeIME
+        // 在 Android 输入法层还原真实中文，适用于任意支持 ADB 的真机/云手机。
+        await adbShell(ctx, ['ime', 'enable', unicodeIME]).catch(() => { });
+        await adbShell(ctx, ['ime', 'set', unicodeIME]);
+        await sleep(800);
+        await adbInput(ctx, ['text', adbInputTextForShell(imapUtf7Encode(value))]);
+        await sleep(1200);
+    } finally {
+        if (previousIME && previousIME !== 'null' && previousIME !== unicodeIME) {
+            await adbShell(ctx, ['ime', 'set', previousIME]).catch(() => { });
+        }
+    }
+}
+
+export async function type(ctx, text) {
+    return typeText(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;
+}
+
+function isAdbOfflineError(error) {
+    const message = String(error?.message || error || '').toLowerCase();
+    return message.includes('device offline') || message.includes('device unauthorized');
+}
+
+function isRetryableAdbInputError(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;
+}
+
+function isBounds(value) {
+    if (!value || typeof value !== 'object') return false;
+    const left = Number(value.left);
+    const top = Number(value.top);
+    const right = Number(value.right);
+    const bottom = Number(value.bottom);
+    return [left, top, right, bottom].every(Number.isFinite) && right > left && bottom > top;
+}
+
+function safeFilePart(value) {
+    return String(value).replace(/[^a-zA-Z0-9_.-]+/g, '-');
+}
+
+function imapUtf7Encode(value) {
+    return String(value || '')
+        .replace(/&/g, '&-')
+        .replace(/[^\x20-\x7e]+/g, (chunk) => `&${utf7EncodeChunk(chunk).replace(/\//g, ',')}-`);
+}
+
+function utf7EncodeChunk(value) {
+    const buffer = Buffer.alloc(String(value).length * 2, 'ascii');
+    let offset = 0;
+    for (let i = 0; i < String(value).length; i += 1) {
+        const code = String(value).charCodeAt(i);
+        buffer[offset++] = code >> 8;
+        buffer[offset++] = code & 0xff;
+    }
+    return buffer.toString('base64').replace(/=+$/, '');
+}
+
+function adbInputTextForShell(raw) {
+    const escapedText = String(raw || '').replace(/[()<>|;&*\\~^"'$`]/g, '\\$&').replace(/ /g, '%s');
+    return `''${escapedText}''`;
+}
+
+export const Device = {
+    adbShell,
+    adbExec,
+    forceStopApp,
+    startActivity,
+    startLauncher,
+    launchPackageByMonkey,
+    waitForForeground,
+    screenSize,
+    px,
+    py,
+    tapRatio,
+    tapAbsolute,
+    click,
+    swipeRatio,
+    move,
+    pressBack,
+    pressEnter,
+    wakeAndUnlock,
+    focusedActivity,
+    activityIncludes,
+    waitForActivity,
+    screenshotBase64,
+    saveDebugScreenshot,
+    clearInputByDelete,
+    typeText,
+    type,
+    sleep
+};

package/src/errors.js

@@ -0,0 +1,37 @@
+import { Code } from './constants.js';
+
+// Android 原生自动化使用的结构化错误。
+// 设计上对齐 playwright-toolkit 的 CrawlerError：业务层可以只 throw 普通 Error，
+// 也可以 throw CrawlerError 携带 code/context，pushFailed 会统一解析。
+export class CrawlerError extends Error {
+  constructor(input, options = {}) {
+    const payload = typeof input === 'string' ? { message: input } : (input || {});
+    super(payload.message || 'Android crawler error', options);
+    this.name = 'CrawlerError';
+    this.code = payload.code || Code.UnknownError;
+    this.context = payload.context || {};
+  }
+
+  static isCrawlerError(error) {
+    return error instanceof CrawlerError || error?.name === 'CrawlerError';
+  }
+
+  static from(error, fallback = {}) {
+    if (CrawlerError.isCrawlerError(error)) return error;
+    return new CrawlerError({
+      message: error?.message || String(error),
+      code: fallback.code || Code.UnknownError,
+      context: fallback.context || {}
+    });
+  }
+}
+
+export function serializeError(error) {
+  if (!error) return { message: '' };
+  return {
+    name: error.name || 'Error',
+    message: error.message || String(error),
+    stack: error.stack || '',
+    code: error.code || ''
+  };
+}