@skrillex1224/android-toolkit 0.1.7 → 0.1.8

package/README.md

@@ -20,13 +20,13 @@ await Launch.run(async ({ input, ctx, kit }) => {
   await kit.ApifyKit.pushSuccess(result);
 }, {
   inputPath,
-  outputPath,
-  contextDefaults: {
-    packageName: 'com.example.app'
-  }
+  outputPath
 });
 ```
 
+`ctx.packageName` 来自后端注入的 `input.runtime.device.packageName`。Android Toolkit
+不把包名放进 `Constants.ActorInfo`，也不在业务包里维护包名真源。
+
 ## 保留模块
 
 | 模块 | 说明 |
@@ -35,9 +35,39 @@ await Launch.run(async ({ input, ctx, kit }) => {
 | `ApifyKit` | 提供 `runStep`、`runStepLoose`、`pushSuccess`、`pushFailed`，并统一补齐 `code/status/timestamp/data` |
 | `Device` | ADB 操作层：启动、点击、滑动、输入中文、截图、Activity 检查 |
 | `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：

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.7",
+  "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

@@ -86,6 +86,21 @@ async function createApifyKit(options = {}) {
             });
         },
 
+        /**
+         * 写补充 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(',')
+            });
+        },
+
         /**
          * 写失败 dataset。
          *

package/src/constants.js

@@ -23,3 +23,53 @@ 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

@@ -15,7 +15,7 @@ export const Context = {
  * 创建 Android actor 的运行上下文。
  *
  * 这里刻意只接受 input/defaults 参数，不读取环境变量，也不写任何业务默认值：
- * - 不知道具体 app 的包名；
+ * - 具体 app 包名由后端注入 input.runtime.device.packageName；
  * - 不知道当前 visitor 要 attach 哪些 WebView 类；
  *
  * ADB/Frida 是机器环境，不是业务 input。toolkit 只从 PATH 查找命令；
@@ -31,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 字符串的入口，业务方再从注入事件中解析数据。