@skrillex1224/android-toolkit 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# Android Toolkit
+
+`android-toolkit` 是原生 Android androider 的最小公共底座，入口格式对齐
+`playwright-toolkit`：业务 actor 只通过 `useAndroidToolKit()` 获取模块，不直接引用内部文件。
+
+## 快速开始
+
+```js
+import { useAndroidToolKit } from '../android-toolkit/index.js';
+
+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);
+    return { answer: `echo: ${input.query}`, sources: [] };
+  });
+
+  await kit.ApifyKit.pushSuccess(result);
+}, {
+  inputPath,
+  outputPath,
+  contextDefaults: {
+    packageName: 'com.example.app'
+  }
+});
+```
+
+## 保留模块
+
+| 模块 | 说明 |
+| --- | --- |
+| `Launch` | 接受显式 `inputPath` / `outputPath`，创建 `ctx`，调用业务 handler |
+| `ApifyKit` | 提供 `runStep`、`runStepLoose`、`pushSuccess`、`pushFailed`，并统一补齐 `code/status/timestamp/data` |
+| `Device` | ADB 操作层：启动、点击、滑动、输入中文、截图、Activity 检查 |
+| `Frida` | 启动 WebView event recorder，记录 `evaluateJavascript` / `loadUrl` 注入事件 |
+| `Context` | 从显式 input/defaults 生成 Android 运行上下文 |
+| `Errors` | `CrawlerError` 和错误序列化；失败码由业务显式抛出的 `CrawlerError` 决定 |
+
+## 当前边界
+
+放进 toolkit：
+
+- ADB 执行、云手机 TCP ADB 离线重连、点击、滑动、截图、中文输入。
+- Frida attach 目标 App pid，并启动 WebView JS 注入事件 recorder。
+- `runStep` / `runStepLoose` / `pushSuccess` / `pushFailed`。
+- 通用错误码和失败 dataset 兜底结构。
+
+不放进 toolkit：
+
+- 任意平台的包名、Activity、WebView class 名称。
+- 任意平台的事件名、正文边界、引用来源解析规则。
+- 任意平台的成功标准和业务错误码。
+
+这些都留在具体 `*-androider` 内，例如 `wechat-androider/src/utils.js`。

package/entrys/node.js

@@ -0,0 +1,24 @@
+import { Launch } from '../src/launch.js';
+import { ApifyKit } from '../src/apify-kit.js';
+import { Device } from '../src/device.js';
+import { Frida } from '../src/frida-client.js';
+import * as Constants from '../src/constants.js';
+import * as Errors from '../src/errors.js';
+import { Logger } from '../src/logger.js';
+import { Context } from '../src/context.js';
+
+// Unified Entry Point
+// 和 playwright-toolkit 的 usePlaywrightToolKit() 保持同一种入口格式：
+// visitor/androider 只从这里取模块，不直接穿透到内部文件。
+export const useAndroidToolKit = () => {
+  return {
+    Launch,
+    ApifyKit,
+    Device,
+    Frida,
+    Constants,
+    Errors,
+    Logger,
+    Context
+  };
+};

package/index.js

@@ -0,0 +1 @@
+export { useAndroidToolKit } from './entrys/node.js';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@skrillex1224/android-toolkit",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "entrys",
+    "src",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "check": "node --check index.js && node --check entrys/node.js && node --check src/launch.js && node --check src/apify-kit.js && node --check src/context.js && node --check src/constants.js && node --check src/device.js && node --check src/errors.js && node --check src/frida-client.js && node --check src/logger.js && node --check src/internals/frida/webview_event_agent.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import {execFileSync, spawnSync} from 'node:child_process';
+
+log('检查 Android toolkit 运行环境');
+checkAdb();
+installOrCheckFrida();
+
+function checkAdb() {
+    const adb = findCommand('adb');
+    if (adb) {
+        log(`已找到 adb: ${adb}`);
+        return;
+    }
+    warn(`未找到 adb。请安装 Android platform-tools，并确保 \`adb\` 在 PATH 中。${installHintForAdb()}`);
+}
+
+function installOrCheckFrida() {
+    const frida = findCommand('frida');
+    if (frida) {
+        log(`已找到 frida: ${frida}`);
+        return;
+    }
+
+    const pip3 = findCommand('pip3');
+    const python3 = findCommand('python3');
+    if (!pip3 || !python3) {
+        warn(`未找到 frida，且当前机器缺少 python3/pip3，无法自动安装 frida-tools。${installHintForFrida()}`);
+        return;
+    }
+
+    try {
+        log('尝试自动安装 frida-tools 到用户目录');
+        execFileSync(python3, ['-m', 'pip', 'install', '--user', '--upgrade', 'frida-tools'], {stdio: 'inherit'});
+        const installedFrida = findCommand('frida');
+        if (installedFrida) {
+            log(`frida 安装成功: ${installedFrida}`);
+            return;
+        }
+        warn('frida-tools 已安装，但 `frida` 仍不在 PATH 中。请把 Python user bin 加入 PATH。');
+        return;
+    } catch (error) {
+        warn(`自动安装 frida-tools 失败: ${error.message || String(error)}`);
+    }
+
+    warn(`未能自动准备 frida，请手动确认 \`frida --version\` 可执行。${installHintForFrida()}`);
+}
+
+function findCommand(command) {
+    const result = spawnSync('which', [command], {encoding: 'utf8'});
+    return result.status === 0 ? String(result.stdout || '').trim() : '';
+}
+
+function installHintForAdb() {
+    if (process.platform === 'darwin') return ' macOS 可用 `brew install android-platform-tools`。';
+    if (process.platform === 'linux') return ' Linux 可安装 Android platform-tools，或用系统包管理器安装 adb（如 apt/dnf/pacman/apk）。';
+    return '';
+}
+
+function installHintForFrida() {
+    if (process.platform === 'darwin') return ' macOS 也可用 `python3 -m pip install --user frida-tools`。';
+    if (process.platform === 'linux') return ' Linux 也可用 `python3 -m pip install --user frida-tools`。';
+    return '';
+}
+
+function log(message) {
+    console.log(`[android-toolkit] ${message}`);
+}
+
+function warn(message) {
+    console.warn(`[android-toolkit] ${message}`);
+}

package/src/apify-kit.js

@@ -0,0 +1,177 @@
+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';
+
+let instance = null;
+
+async function createApifyKit(options = {}) {
+    const io = {
+        inputPath: options.inputPath || '',
+        outputPath: requiredOption(options.outputPath, 'outputPath')
+    };
+    const input = options.input || (io.inputPath ? JSON.parse(fs.readFileSync(io.inputPath, 'utf8')) : {});
+    const ctx = options.ctx || createAndroidContext(input, options.contextDefaults || {});
+    let pushed = false;
+    let lastDevice = null;
+
+    return {
+        ctx,
+        input,
+        inputPath: io.inputPath,
+        outputPath: io.outputPath,
+
+        /**
+         * Android 版 runStep。
+         *
+         * 设计上贴近 playwright-toolkit 的 ApifyKit.runStep：
+         * - 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);
+                        }
+                    }
+                }
+            }
+
+            if (failActor) {
+                await this.pushFailed(lastError, {
+                    step,
+                    retryAttempts: retryTimes
+                }, {target});
+            }
+            throw lastError;
+        },
+
+        /**
+         * 宽松版 runStep。
+         *
+         * 和 playwright-toolkit 一样：只负责打日志和抛错，不主动写失败 dataset。
+         * 业务层可以用它包“可选截图/可选关闭弹窗/可选诊断”这类步骤。
+         */
+        async runStepLoose(step, target, fn, options = {}) {
+            return this.runStep(step, target, fn, {
+                ...options,
+                failActor: false
+            });
+        },
+
+        /**
+         * 写成功 dataset。
+         *
+         * 对齐 playwright-toolkit：业务 actor 只传业务数据，toolkit 统一补
+         * code/status/timestamp/data 外壳。这样 commander/transformer 看到的是同类结构。
+         */
+        async pushSuccess(data = {}, options = {}) {
+            pushed = true;
+            fs.writeFileSync(io.outputPath, JSON.stringify([{
+                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');
+        },
+
+        /**
+         * 写失败 dataset。
+         *
+         * 失败结构也对齐 playwright-toolkit：CrawlerError 决定 code/context，
+         * 普通 Error 统一按 UnknownError 处理，业务可预期失败必须显式抛 CrawlerError。
+         */
+        async pushFailed(error, meta = {}) {
+            const normalized = CrawlerError.isCrawlerError(error)
+                ? error
+                : CrawlerError.from(error, {code: Code.UnknownError, context: meta});
+
+            pushed = true;
+            fs.writeFileSync(io.outputPath, JSON.stringify([{
+                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');
+        },
+
+        hasPushed() {
+            return pushed;
+        },
+
+        getLastDevice() {
+            return lastDevice;
+        }
+    };
+}
+
+async function useApifyKit(options = {}) {
+    if (!instance || options.reset) {
+        instance = await createApifyKit(options);
+    }
+    return instance;
+}
+
+export const ApifyKit = {
+    useApifyKit
+};
+
+function requiredOption(value, name) {
+    const clean = String(value || '').trim();
+    if (!clean) throw new Error(`ApifyKit.useApifyKit requires ${name}`);
+    return clean;
+}
+
+function sanitizeData(value, depth = 0, seen = new WeakSet()) {
+    if (depth > 8) return '[MaxDepth]';
+    if (value == null) return value;
+    const valueType = typeof value;
+    if (valueType === 'string' || valueType === 'number' || valueType === 'boolean') return value;
+    if (valueType === 'bigint') return value.toString();
+    if (valueType === 'function' || valueType === 'symbol') return undefined;
+    if (value instanceof Error) return serializeError(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeData(item, depth + 1, seen)).filter((item) => item !== undefined);
+    }
+    if (valueType !== 'object') return String(value);
+    if (seen.has(value)) return '[Circular]';
+    seen.add(value);
+
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        const safe = sanitizeData(item, depth + 1, seen);
+        if (safe !== undefined) out[key] = safe;
+    }
+    return out;
+}

package/src/constants.js

@@ -0,0 +1,24 @@
+export const Code = {
+  Success: 0,
+  UnknownError: -1,
+  NotLogin: 30000001,
+  Chaptcha: 30000002,
+  Timeout: 30000003,
+  InitialTimeout: 30000004,
+  OverallTimeout: 30000005,
+
+  // Android-toolkit 扩展码从 300100xx 开始，避免改动 Playwright-toolkit 既有码值。
+  InvalidRequest: 30010001,
+  AdbUnavailable: 30010002,
+  ContentUnavailable: 30010003,
+  SourceExtractionFailed: 30010004,
+  AutomationFailed: 30010005,
+  RunnerFailed: 30010006,
+  AppiumUnavailable: 30010007,
+  FridaUnavailable: 30010008
+};
+
+export const Status = {
+  Success: 'SUCCESS',
+  Failed: 'FAILED'
+};

package/src/context.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const toolkitRoot = path.resolve(__dirname, '..');
+
+export const Context = {
+    createAndroidContext,
+    firstNonEmpty,
+    trimRight,
+    toolkitPath
+};
+
+/**
+ * 创建 Android actor 的运行上下文。
+ *
+ * 这里刻意只接受 input/defaults 参数，不读取环境变量，也不写任何业务默认值：
+ * - 不知道具体 app 的包名；
+ * - 不知道当前 visitor 要 attach 哪些 WebView 类；
+ *
+ * ADB/Frida 是机器环境，不是业务 input。toolkit 只从 PATH 查找命令；
+ * 安装和 PATH 准备由 postinstall 或部署环境负责。
+ */
+export function createAndroidContext(input = {}, defaults = {}) {
+    const runtime = input.runtime || {};
+    const device = normalizeRuntimeDevice(runtime.device);
+
+    return {
+        runId: firstNonEmpty(defaults.runId),
+        query: String(input.query || defaults.query || '').trim(),
+        mode: firstNonEmpty(defaults.mode, 'ai_search'),
+        serial: firstNonEmpty(device.serial, defaults.serial),
+        adbPath: resolveAdbPath(defaults),
+        packageName: firstNonEmpty(defaults.packageName),
+        fridaPath: resolveFridaPath(defaults),
+        // Frida WebView event agent 是当前保留的唯一 Frida agent：
+        // 它 hook WebView 执行 JS 字符串的入口，业务方再从注入事件中解析数据。
+        fridaWebViewEventAgentScript: firstNonEmpty(
+            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),
+        externalIp: firstNonEmpty(defaults.externalIp)
+    };
+}
+
+export function toolkitPath(relativePath) {
+    return path.resolve(toolkitRoot, relativePath);
+}
+
+export function firstNonEmpty(...values) {
+    for (const value of values) {
+        const clean = String(value ?? '').trim();
+        if (clean) return clean;
+    }
+    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;
+    return {};
+}
+
+function resolveAdbPath(defaults = {}) {
+    return firstNonEmpty(
+        defaults.adbPath,
+        findCommand('adb'),
+        'adb'
+    );
+}
+
+function resolveFridaPath(defaults = {}) {
+    return firstNonEmpty(
+        defaults.fridaPath,
+        findCommand('frida'),
+        'frida'
+    );
+}
+
+function findCommand(command) {
+    try {
+        return String(execFileSync('which', [command], {encoding: 'utf8'})).trim();
+    } catch {
+        return '';
+    }
+}