@skrillex1224/android-toolkit 0.1.2 → 0.1.8

package/README.md

@@ -13,20 +13,20 @@ 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: [] };
   });
 
   await kit.ApifyKit.pushSuccess(result);
 }, {
   inputPath,
-  outputPath,
-  contextDefaults: {
-    packageName: 'com.example.app'
-  }
+  outputPath
 });
 ```
 
+`ctx.packageName` 来自后端注入的 `input.runtime.device.packageName`。Android Toolkit
+不把包名放进 `Constants.ActorInfo`，也不在业务包里维护包名真源。
+
 ## 保留模块
 
 | 模块 | 说明 |
@@ -34,16 +34,47 @@ 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 |
+| `Share` | 对齐 `playwright-toolkit` 的分享能力：高视口截图、分享链接捕获、截图压缩 |
 | `Context` | 从显式 input/defaults 生成 Android 运行上下文 |
 | `Errors` | `CrawlerError` 和错误序列化；失败码由业务显式抛出的 `CrawlerError` 决定 |
 
+## Share
+
+`Share.captureScreen(ctx, options)` 用于采集 Android 页面长图。实现策略是先用
+Frida 扫描当前 Activity 的 View 树，读取所有可滚动 View 的
+`computeVerticalScrollRange()`，取最大所需高度后临时执行 `wm size WxH`，再用
+`screencap` 一次性截图。它不裁剪状态栏和导航栏；如果 View 树无法读取，会直接报错，
+不会退回普通视口截图。默认压缩阈值与 `playwright-toolkit` 一致：base64 最大
+5MiB，JPEG，质量 `0.72`，最低质量 `0.38`，最低缩放 `0.25`。
+
+```js
+const screenshotBase64 = await Share.captureScreen(ctx, {
+  Frida,
+  actorInfo: Constants.ActorInfo['doubao.android'].key,
+  maxHeight: 8000
+});
+```
+
+`Share.captureLink(ctx, options)` 负责按 `Constants.ActorInfo[actor].share.prefix`
+校验分享链接。Android 当前稳定模式是 `clipboard`：业务层执行点击分享、复制链接，
+toolkit 通过 `Frida.runScript` 轮询系统剪贴板候选内容并提取匹配 prefix 的 URL。
+
+```js
+const result = await Share.captureLink(ctx, {
+  Frida,
+  actorInfo: Constants.ActorInfo['doubao.android'].key,
+  performActions: async () => clickShareAndCopyLink()
+});
+```
+
 ## 当前边界
 
 放进 toolkit：
 
 - ADB 执行、云手机 TCP ADB 离线重连、点击、滑动、截图、中文输入。
 - Frida attach 目标 App pid，并启动 WebView JS 注入事件 recorder。
+- App 进程内 SQLite 查询：业务方提供 db 路径规则、SQL 和参数，toolkit 只返回 cursor rows。
 - `runStep` / `runStepLoose` / `pushSuccess` / `pushFailed`。
 - 通用错误码和失败 dataset 兜底结构。
 

package/entrys/node.js

@@ -2,6 +2,7 @@ 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 { Share } from '../src/share.js';
 import * as Constants from '../src/constants.js';
 import * as Errors from '../src/errors.js';
 import { Logger } from '../src/logger.js';
@@ -16,6 +17,7 @@ export const useAndroidToolKit = () => {
     ApifyKit,
     Device,
     Frida,
+    Share,
     Constants,
     Errors,
     Logger,

package/index.d.ts

@@ -0,0 +1,191 @@
+export interface AndroidContext {
+  adbPath?: string;
+  fridaPath?: string;
+  fridaServerPath?: string;
+  fridaWebViewEventAgentScript?: string;
+  serial: string;
+  packageName: string;
+  query: string;
+  runId?: string;
+  [key: string]: any;
+}
+
+export interface AndroidActorShareInfo {
+  mode: 'clipboard' | 'custom';
+  prefix: string;
+  xurl: Array<string | string[]>;
+}
+
+export interface AndroidActorInfoItem {
+  key: string;
+  name: string;
+  icon: string;
+  share: AndroidActorShareInfo;
+  [key: string]: any;
+}
+
+export interface AndroidConstantsModule {
+  Code: Record<string, number>;
+  Status: Record<string, string>;
+  ActorInfo: Record<string, AndroidActorInfoItem>;
+}
+
+export interface AndroidCrawlerErrorInfo {
+  message: string;
+  code?: number;
+  context?: Record<string, any>;
+}
+
+export interface AndroidCrawlerError extends Error {
+  code: number;
+  context?: Record<string, any>;
+}
+
+export interface AndroidErrorsModule {
+  CrawlerError: new (info: AndroidCrawlerErrorInfo) => AndroidCrawlerError;
+  serializeError(error: unknown): Record<string, any>;
+}
+
+export interface AndroidLogger {
+  debug(message: string, meta?: Record<string, any>): void;
+  info(message: string, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+  success(message: string, meta?: Record<string, any>): void;
+  fail(message: string, error?: unknown): void;
+  start(message: string, meta?: Record<string, any>): void;
+  duration(startedAt: number): string;
+  createLogger(scope: string): AndroidLogger;
+}
+
+export interface AndroidDeviceModule {
+  adbShell(ctx: AndroidContext, args: string[], options?: Record<string, any>): Promise<string>;
+  adbExec(ctx: AndroidContext, args: string[], options?: Record<string, any>): Promise<string>;
+  forceStopApp(ctx: AndroidContext, packageName?: string): Promise<void>;
+  startActivity(ctx: AndroidContext, component: string, args?: string[]): Promise<void>;
+  startLauncher(ctx: AndroidContext, packageName?: string, launcherActivity?: string): Promise<void>;
+  waitForForeground(ctx: AndroidContext, packageName?: string, timeoutMs?: number): Promise<boolean>;
+  screenSize(ctx: AndroidContext): Promise<{ width: number; height: number }>;
+  screenDensity(ctx: AndroidContext): Promise<number>;
+  overrideScreenSize(ctx: AndroidContext, width: number, height: number): Promise<void>;
+  resetScreenSize(ctx: AndroidContext): Promise<void>;
+  resetScreenDensity(ctx: AndroidContext): Promise<void>;
+  click(ctx: AndroidContext, pointOrX: any, y?: number): Promise<void>;
+  move(ctx: AndroidContext, from: { x: number; y: number }, to: { x: number; y: number }, durationMs?: number): Promise<void>;
+  pressBack(ctx: AndroidContext): Promise<void>;
+  wakeAndUnlock(ctx: AndroidContext): Promise<void>;
+  focusedActivity(ctx: AndroidContext): Promise<string>;
+  waitForActivity(ctx: AndroidContext, predicate: (focused: string) => boolean, timeoutMs?: number, intervalMs?: number): Promise<string>;
+  screenshotPng(ctx: AndroidContext): Promise<Buffer>;
+  screenshotBase64(ctx: AndroidContext): Promise<string>;
+  [key: string]: any;
+}
+
+export interface AndroidFridaModule {
+  runScript(ctx: AndroidContext, source: string, options?: Record<string, any>): Promise<any>;
+  querySQLite(ctx: AndroidContext, options?: Record<string, any>): Promise<any>;
+  startWebViewEventRecorder(ctx: AndroidContext, config?: Record<string, any>, options?: Record<string, any>): Promise<any>;
+}
+
+export interface AndroidShareScreenCompressionOptions {
+  enabled?: boolean;
+  maxBytes?: number;
+  maxBase64Bytes?: number;
+  type?: 'jpeg' | 'jpg';
+  outputType?: 'jpeg' | 'jpg';
+  quality?: number;
+  minQuality?: number;
+  minScale?: number;
+}
+
+export interface AndroidShareScreenCaptureOptions {
+  Frida?: AndroidFridaModule;
+  frida?: AndroidFridaModule;
+  actorInfo?: string | AndroidActorInfoItem;
+  actor?: string | AndroidActorInfoItem;
+  actorKey?: string | AndroidActorInfoItem;
+  restore?: boolean;
+  maxHeight?: number;
+  width?: number;
+  height?: number;
+  settleMs?: number;
+  scrollToTop?: boolean;
+  timeoutMs?: number;
+  fridaTimeoutSeconds?: number;
+  maxBytes?: number;
+  maxBase64Bytes?: number;
+  type?: 'jpeg' | 'jpg';
+  outputType?: 'jpeg' | 'jpg';
+  quality?: number;
+  minQuality?: number;
+  minScale?: number;
+  compression?: boolean | AndroidShareScreenCompressionOptions;
+  compress?: boolean;
+}
+
+export interface AndroidShareLinkCaptureOptions {
+  actorInfo?: string | AndroidActorInfoItem;
+  actor?: string | AndroidActorInfoItem;
+  actorKey?: string | AndroidActorInfoItem;
+  share?: Partial<AndroidActorShareInfo>;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  payloadSnapshotMaxLen?: number;
+  signal?: AbortSignal;
+  performActions?: () => any | Promise<any>;
+}
+
+export interface AndroidShareLinkCaptureResult {
+  link: string | null;
+  payloadText: string;
+  payloadSnapshot: string;
+  source: 'clipboard' | 'custom' | 'none' | string;
+}
+
+export interface AndroidShareModule {
+  captureScreen(ctx: AndroidContext, options?: AndroidShareScreenCaptureOptions): Promise<string>;
+  captureLink(ctx: AndroidContext, options?: AndroidShareLinkCaptureOptions): Promise<AndroidShareLinkCaptureResult>;
+}
+
+export interface AndroidApifyKitInstance {
+  runStep<T>(name: string, meta: any, fn: () => Promise<T> | T): Promise<T>;
+  runStepLoose<T>(name: string, meta: any, fn: () => Promise<T> | T): Promise<T>;
+  pushSuccess(data: any): Promise<void>;
+  pushFailed(error: unknown, context?: Record<string, any>): Promise<void>;
+  pushArtifact(data: any): Promise<void>;
+  hasPushed(): boolean;
+}
+
+export interface AndroidApifyKitModule {
+  useApifyKit(options?: Record<string, any>): Promise<AndroidApifyKitInstance>;
+}
+
+export interface AndroidLaunchRunHandlerArgs {
+  input: any;
+  ctx: AndroidContext;
+  kit: {
+    ApifyKit: AndroidApifyKitInstance;
+    Device: AndroidDeviceModule;
+    Frida: AndroidFridaModule;
+    Share: AndroidShareModule;
+    Logger: AndroidLogger;
+  };
+  ApifyKit: AndroidApifyKitInstance;
+}
+
+export interface AndroidLaunchModule {
+  run(handler: (args: AndroidLaunchRunHandlerArgs) => Promise<void> | void, options?: Record<string, any>): Promise<void>;
+}
+
+export interface AndroidToolkit {
+  Launch: AndroidLaunchModule;
+  ApifyKit: AndroidApifyKitModule;
+  Device: AndroidDeviceModule;
+  Frida: AndroidFridaModule;
+  Share: AndroidShareModule;
+  Constants: AndroidConstantsModule;
+  Errors: AndroidErrorsModule;
+  Logger: AndroidLogger;
+  Context: Record<string, any>;
+}
+
+export function useAndroidToolKit(): AndroidToolkit;

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@skrillex1224/android-toolkit",
-  "version": "0.1.2",
+  "version": "0.1.8",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
     ".": "./index.js"
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "entrys",
     "src",
     "scripts",
@@ -15,10 +17,13 @@
   ],
   "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",
+    "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/share.js && node --check src/internals/compression.js && node --check src/internals/frida/webview_event_agent.js",
     "test": "node --test test/*.test.js"
   },
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "jimp": "^1.6.1"
   }
 }

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,34 @@ 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
+            });
+        },
+
+        /**
+         * 写补充 artifact dataset。
+         *
+         * 这类数据不是最终业务结果，只用于给 commander 的 ext/base64 链路消费，
+         * 例如 screenshotBase64、conversationShareLink。它不改变 hasPushed()
+         * 状态，避免 artifact 写入后主流程失败时吞掉失败 dataset。
+         */
+        async pushArtifact(data = {}) {
+            appendOutput(io.outputPath, sanitizeData(data));
+            Logger.success('pushArtifact', {
+                outputPath: io.outputPath,
+                keys: Object.keys(data || {}).join(',')
+            });
         },
 
         /**
@@ -115,15 +113,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 +149,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,10 +15,61 @@ export const Code = {
   AutomationFailed: 30010005,
   RunnerFailed: 30010006,
   AppiumUnavailable: 30010007,
-  FridaUnavailable: 30010008
+  FridaUnavailable: 30010008,
+  AppNotInstalled: 30010009
 };
 
 export const Status = {
   Success: 'SUCCESS',
   Failed: 'FAILED'
 };
+
+const normalizePrefix = (value) => String(value || '').trim();
+
+const normalizeShare = (value) => {
+  const raw = value && typeof value === 'object' ? value : {};
+  const modeRaw = String(raw.mode || 'clipboard').trim().toLowerCase();
+  const mode = ['clipboard', 'custom'].includes(modeRaw) ? modeRaw : 'clipboard';
+  return {
+    mode,
+    prefix: normalizePrefix(raw.prefix),
+    xurl: Array.isArray(raw.xurl) ? raw.xurl : []
+  };
+};
+
+const createActorInfo = (info) => {
+  const key = String(info?.key || '').trim();
+  const share = normalizeShare(info?.share);
+  return {
+    ...info,
+    key,
+    share,
+    get icon() {
+      if (info.icon) return info.icon;
+      return buildIcon(this.key);
+    }
+  };
+};
+
+const buildIcon = (key) => `https://static.heartbitai.com/general/actors/${key}.png`;
+
+export const ActorInfo = {
+  'doubao.android': createActorInfo({
+    key: 'doubao.android',
+    name: '豆包 Android',
+    share: {
+      mode: 'clipboard',
+      prefix: 'https://www.doubao.com/thread/',
+      xurl: []
+    }
+  }),
+  'wechat.android': createActorInfo({
+    key: 'wechat.android',
+    name: '微信 Android',
+    share: {
+      mode: 'clipboard',
+      prefix: '',
+      xurl: []
+    }
+  })
+};

package/src/context.js

@@ -8,7 +8,6 @@ const toolkitRoot = path.resolve(__dirname, '..');
 export const Context = {
     createAndroidContext,
     firstNonEmpty,
-    trimRight,
     toolkitPath
 };
 
@@ -16,7 +15,7 @@ export const Context = {
  * 创建 Android actor 的运行上下文。
  *
  * 这里刻意只接受 input/defaults 参数，不读取环境变量，也不写任何业务默认值：
- * - 不知道具体 app 的包名；
+ * - 具体 app 包名由后端注入 input.runtime.device.packageName；
  * - 不知道当前 visitor 要 attach 哪些 WebView 类；
  *
  * ADB/Frida 是机器环境，不是业务 input。toolkit 只从 PATH 查找命令；
@@ -32,7 +31,7 @@ export function createAndroidContext(input = {}, defaults = {}) {
         mode: firstNonEmpty(defaults.mode, 'ai_search'),
         serial: firstNonEmpty(device.serial, defaults.serial),
         adbPath: resolveAdbPath(defaults),
-        packageName: firstNonEmpty(defaults.packageName),
+        packageName: firstNonEmpty(device.packageName),
         fridaPath: resolveFridaPath(defaults),
         // Frida WebView event agent 是当前保留的唯一 Frida agent：
         // 它 hook WebView 执行 JS 字符串的入口，业务方再从注入事件中解析数据。
@@ -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;