@skrillex1224/android-toolkit 0.1.9 → 1.0.0

package/README.md

@@ -1,87 +1,74 @@
 # Android Toolkit
 
-`android-toolkit` 是原生 Android androider 的最小公共底座，入口格式对齐
-`playwright-toolkit`：业务 actor 只通过 `useAndroidToolKit()` 获取模块，不直接引用内部文件。
+`@skrillex1224/android-toolkit` is the native Android counterpart to
+`@skrillex1224/playwright-toolkit`.
 
-## 快速开始
+Actor code should import only `useAndroidToolKit()` and then use the returned modules.
+The public API is intentionally small and destructive from v1 onward.
 
 ```js
-import { useAndroidToolKit } from '../android-toolkit/index.js';
+import { useAndroidToolKit } from '@skrillex1224/android-toolkit';
 
 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.click(ctx, { x: 360, y: 640 });
-    return { answer: `echo: ${input.query}`, sources: [] };
+await Launch.run(async ({ ctx, kit }) => {
+  const { ApifyKit, DeviceInput, Mutation, Share } = kit;
+  await ApifyKit.runStep('输入并发送', ctx, async () => {
+    await DeviceInput.click(ctx, { id: 'input_text' });
+    await DeviceInput.fill(ctx, { id: 'input_text' }, ctx.query);
+    await DeviceInput.pressEnter(ctx);
   });
-
-  await kit.ApifyKit.pushSuccess(result);
-}, {
-  inputPath,
-  outputPath
+  await Mutation.waitForStable(ctx, { id: 'message_list' });
+  const screenshotBase64 = await Share.captureScreen(ctx);
+  await ApifyKit.pushArtifact({ screenshotBase64 });
 });
 ```
 
-`ctx.packageName` 来自后端注入的 `input.runtime.device.packageName`。Android Toolkit
-不把包名放进 `Constants.ActorInfo`，也不在业务包里维护包名真源。
-
-## 保留模块
+## Public Modules
 
-| 模块 | 说明 |
+| Module | Responsibility |
 | --- | --- |
-| `Launch` | 接受显式 `inputPath` / `outputPath`，创建 `ctx`，调用业务 handler |
-| `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`。
+| `Launch` | Native actor entrypoint with explicit input/output paths and lifecycle hooks. |
+| `ApifyKit` | `runStep`, `runStepLoose`, `pushSuccess`, `pushFailed`, `pushArtifact`. |
+| `Device` | Low-level ADB primitives only. |
+| `DeviceView` | Native View-tree snapshot and selector lookup over `uiautomator dump`. |
+| `DeviceInput` | View-tree-backed click/fill/press/scroll APIs using ADB input. |
+| `Mutation` | Playwright-like stable wait semantics over matched ViewNode subtrees. |
+| `Share` | Sprite screenshot and clipboard share-link polling. |
+| `Frida` | Public `querySQLite()` and `health()` only. |
+| `Constants` | Native-useful actor metadata and codes. |
+| `Errors` | `CrawlerError` and error serialization. |
 
-```js
-const screenshotBase64 = await Share.captureScreen(ctx, {
-  Frida,
-  actorInfo: Constants.ActorInfo['doubao.android'].key,
-  maxHeight: 8000
-});
-```
+## Runtime Contract
 
-`Share.captureLink(ctx, options)` 负责按 `Constants.ActorInfo[actor].share.prefix`
-校验分享链接。Android 当前稳定模式是 `clipboard`：业务层执行点击分享、复制链接，
-toolkit 通过 `Frida.runScript` 轮询系统剪贴板候选内容并提取匹配 prefix 的 URL。
+The toolkit does not install or discover runtime tools.
 
-```js
-const result = await Share.captureLink(ctx, {
-  Frida,
-  actorInfo: Constants.ActorInfo['doubao.android'].key,
-  performActions: async () => clickShareAndCopyLink()
-});
-```
+Required environment:
+
+- `ANDROID_TOOLKIT_ADB_PATH`
+- `ANDROID_TOOLKIT_FRIDA_PATH`
+
+Device initialization, Appium Settings, UnicodeIME, and frida-server provisioning belong
+to manager/cluster runtime. Runtime checks fail clearly when prerequisites are missing.
+
+## Boundaries
 
-## 当前边界
+Included:
 
-放进 toolkit：
+- ADB command execution, app launch, key input, screenshot, activity checks.
+- View-tree parsing with a real XML parser.
+- View selector operations: `id`, `text`, `textContains`, `contentDesc`.
+- Internal Frida script execution only where the toolkit owns the behavior, such as
+  SQLite queries or clipboard probing inside `Share`.
 
-- ADB 执行、云手机 TCP ADB 离线重连、点击、滑动、截图、中文输入。
-- Frida attach 目标 App pid，并启动 WebView JS 注入事件 recorder。
-- App 进程内 SQLite 查询：业务方提供 db 路径规则、SQL 和参数，toolkit 只返回 cursor rows。
-- `runStep` / `runStepLoose` / `pushSuccess` / `pushFailed`。
-- 通用错误码和失败 dataset 兜底结构。
+Excluded:
 
-不放进 toolkit：
+- Public generic Frida script execution.
+- WebView event recorder.
+- Frida UI traversal/click helpers.
+- Package name and activity truth. Backend/runtime input owns those values.
+- Actor-specific DB schemas, message parsing, product parsing, and success criteria.
 
-- 任意平台的包名、Activity、WebView class 名称。
-- 任意平台的事件名、正文边界、引用来源解析规则。
-- 任意平台的成功标准和业务错误码。
+## Browser Entry
 
-这些都留在具体 `*-androider` 内，例如 `wechat-androider/src/utils.js`。
+`@skrillex1224/android-toolkit/browser` exports only `Constants` and `Errors`.

package/browser.d.ts

@@ -0,0 +1,31 @@
+export namespace Constants {
+    export const Code: Record<string, number>;
+    export const Status: Record<string, string>;
+    export const ActorInfo: Record<string, {
+        key: string;
+        name: string;
+        icon: string;
+        share: {
+            mode: 'clipboard';
+            prefix: string;
+            xurl: unknown[];
+        };
+    }>;
+}
+
+export namespace Errors {
+    export class CrawlerError extends Error {
+        code: number;
+        context: Record<string, unknown>;
+        constructor(input?: string | {
+            message?: string;
+            code?: number;
+            context?: Record<string, unknown>;
+        });
+        static isCrawlerError(error: unknown): boolean;
+        static from(error: unknown, fallback?: {
+            code?: number;
+            context?: Record<string, unknown>;
+        }): CrawlerError;
+    }
+}

package/dist/browser.js

@@ -0,0 +1,107 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/constants.js
+var constants_exports = {};
+__export(constants_exports, {
+  ActorInfo: () => ActorInfo,
+  Code: () => Code,
+  Status: () => Status,
+  UnicodeIme: () => UnicodeIme
+});
+var Code = Object.freeze({
+  Success: 0,
+  UnknownError: -1,
+  NotLogin: 30000001,
+  Timeout: 30000003,
+  InitialTimeout: 30000004,
+  OverallTimeout: 30000005,
+  InvalidRequest: 30010001,
+  AdbUnavailable: 30010002,
+  ContentUnavailable: 30010003,
+  SourceExtractionFailed: 30010004,
+  AutomationFailed: 30010005,
+  FridaUnavailable: 30010008,
+  AppNotInstalled: 30010009
+});
+var Status = Object.freeze({
+  Success: "SUCCESS",
+  Failed: "FAILED"
+});
+var UnicodeIme = Object.freeze({
+  packageName: "io.appium.settings",
+  component: "io.appium.settings/.UnicodeIME",
+  inputTextAction: "ADB_INPUT_TEXT"
+});
+var normalizeShare = (share) => {
+  const source = share && typeof share === "object" ? share : {};
+  return {
+    mode: "clipboard",
+    prefix: String(source.prefix || "").trim(),
+    xurl: Array.isArray(source.xurl) ? source.xurl : []
+  };
+};
+var createActorInfo = (info) => {
+  const key = String(info.key || "").trim();
+  return Object.freeze({
+    key,
+    name: String(info.name || key),
+    icon: String(info.icon || `https://static.heartbitai.com/general/actors/${key}.png`),
+    share: Object.freeze(normalizeShare(info.share))
+  });
+};
+var ActorInfo = Object.freeze({
+  "doubao.android": createActorInfo({
+    key: "doubao.android",
+    name: "\u8C46\u5305 Android",
+    share: {
+      prefix: "https://www.doubao.com/thread/",
+      xurl: []
+    }
+  })
+});
+
+// src/errors.js
+var errors_exports = {};
+__export(errors_exports, {
+  CrawlerError: () => CrawlerError,
+  serializeError: () => serializeError
+});
+var CrawlerError = 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 == null ? void 0 : error.name) === "CrawlerError";
+  }
+  static from(error, fallback = {}) {
+    if (_CrawlerError.isCrawlerError(error)) return error;
+    return new _CrawlerError({
+      message: (error == null ? void 0 : error.message) || String(error),
+      code: fallback.code || Code.UnknownError,
+      context: fallback.context || {}
+    });
+  }
+};
+function serializeError(error) {
+  if (!error) return { message: "" };
+  return {
+    name: error.name || "Error",
+    message: error.message || String(error),
+    stack: error.stack || "",
+    code: error.code || "",
+    context: error.context || void 0
+  };
+}
+export {
+  constants_exports as Constants,
+  errors_exports as Errors
+};
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/constants.js", "../src/errors.js"],
+  "sourcesContent": ["export const Code = Object.freeze({\n    Success: 0,\n    UnknownError: -1,\n    NotLogin: 30000001,\n    Timeout: 30000003,\n    InitialTimeout: 30000004,\n    OverallTimeout: 30000005,\n    InvalidRequest: 30010001,\n    AdbUnavailable: 30010002,\n    ContentUnavailable: 30010003,\n    SourceExtractionFailed: 30010004,\n    AutomationFailed: 30010005,\n    FridaUnavailable: 30010008,\n    AppNotInstalled: 30010009,\n});\n\nexport const Status = Object.freeze({\n    Success: 'SUCCESS',\n    Failed: 'FAILED',\n});\n\nexport const UnicodeIme = Object.freeze({\n    packageName: 'io.appium.settings',\n    component: 'io.appium.settings/.UnicodeIME',\n    inputTextAction: 'ADB_INPUT_TEXT',\n});\n\nconst normalizeShare = (share) => {\n    const source = share && typeof share === 'object' ? share : {};\n    return {\n        mode: 'clipboard',\n        prefix: String(source.prefix || '').trim(),\n        xurl: Array.isArray(source.xurl) ? source.xurl : [],\n    };\n};\n\nconst createActorInfo = (info) => {\n    const key = String(info.key || '').trim();\n    return Object.freeze({\n        key,\n        name: String(info.name || key),\n        icon: String(info.icon || `https://static.heartbitai.com/general/actors/${key}.png`),\n        share: Object.freeze(normalizeShare(info.share)),\n    });\n};\n\nexport const ActorInfo = Object.freeze({\n    'doubao.android': createActorInfo({\n        key: 'doubao.android',\n        name: '\u8C46\u5305 Android',\n        share: {\n            prefix: 'https://www.doubao.com/thread/',\n            xurl: [],\n        },\n    }),\n});\n", "import { Code } from './constants.js';\n\nexport class CrawlerError extends Error {\n    constructor(input = {}, options = {}) {\n        const payload = typeof input === 'string' ? { message: input } : input;\n        super(payload.message || 'Android crawler error', options);\n        this.name = 'CrawlerError';\n        this.code = payload.code || Code.UnknownError;\n        this.context = payload.context || {};\n    }\n\n    static isCrawlerError(error) {\n        return error instanceof CrawlerError || error?.name === 'CrawlerError';\n    }\n\n    static from(error, fallback = {}) {\n        if (CrawlerError.isCrawlerError(error)) return error;\n        return new CrawlerError({\n            message: error?.message || String(error),\n            code: fallback.code || Code.UnknownError,\n            context: fallback.context || {},\n        });\n    }\n}\n\nexport function serializeError(error) {\n    if (!error) return { message: '' };\n    return {\n        name: error.name || 'Error',\n        message: error.message || String(error),\n        stack: error.stack || '',\n        code: error.code || '',\n        context: error.context || undefined,\n    };\n}\n"],
+  "mappings": ";;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,OAAO,OAAO,OAAO;AAAA,EAC9B,SAAS;AAAA,EACT,cAAc;AAAA,EACd,UAAU;AAAA,EACV,SAAS;AAAA,EACT,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,oBAAoB;AAAA,EACpB,wBAAwB;AAAA,EACxB,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,iBAAiB;AACrB,CAAC;AAEM,IAAM,SAAS,OAAO,OAAO;AAAA,EAChC,SAAS;AAAA,EACT,QAAQ;AACZ,CAAC;AAEM,IAAM,aAAa,OAAO,OAAO;AAAA,EACpC,aAAa;AAAA,EACb,WAAW;AAAA,EACX,iBAAiB;AACrB,CAAC;AAED,IAAM,iBAAiB,CAAC,UAAU;AAC9B,QAAM,SAAS,SAAS,OAAO,UAAU,WAAW,QAAQ,CAAC;AAC7D,SAAO;AAAA,IACH,MAAM;AAAA,IACN,QAAQ,OAAO,OAAO,UAAU,EAAE,EAAE,KAAK;AAAA,IACzC,MAAM,MAAM,QAAQ,OAAO,IAAI,IAAI,OAAO,OAAO,CAAC;AAAA,EACtD;AACJ;AAEA,IAAM,kBAAkB,CAAC,SAAS;AAC9B,QAAM,MAAM,OAAO,KAAK,OAAO,EAAE,EAAE,KAAK;AACxC,SAAO,OAAO,OAAO;AAAA,IACjB;AAAA,IACA,MAAM,OAAO,KAAK,QAAQ,GAAG;AAAA,IAC7B,MAAM,OAAO,KAAK,QAAQ,gDAAgD,GAAG,MAAM;AAAA,IACnF,OAAO,OAAO,OAAO,eAAe,KAAK,KAAK,CAAC;AAAA,EACnD,CAAC;AACL;AAEO,IAAM,YAAY,OAAO,OAAO;AAAA,EACnC,kBAAkB,gBAAgB;AAAA,IAC9B,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,MACH,QAAQ;AAAA,MACR,MAAM,CAAC;AAAA,IACX;AAAA,EACJ,CAAC;AACL,CAAC;;;ACvDD;AAAA;AAAA;AAAA;AAAA;AAEO,IAAM,eAAN,MAAM,sBAAqB,MAAM;AAAA,EACpC,YAAY,QAAQ,CAAC,GAAG,UAAU,CAAC,GAAG;AAClC,UAAM,UAAU,OAAO,UAAU,WAAW,EAAE,SAAS,MAAM,IAAI;AACjE,UAAM,QAAQ,WAAW,yBAAyB,OAAO;AACzD,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ,QAAQ,KAAK;AACjC,SAAK,UAAU,QAAQ,WAAW,CAAC;AAAA,EACvC;AAAA,EAEA,OAAO,eAAe,OAAO;AACzB,WAAO,iBAAiB,kBAAgB,+BAAO,UAAS;AAAA,EAC5D;AAAA,EAEA,OAAO,KAAK,OAAO,WAAW,CAAC,GAAG;AAC9B,QAAI,cAAa,eAAe,KAAK,EAAG,QAAO;AAC/C,WAAO,IAAI,cAAa;AAAA,MACpB,UAAS,+BAAO,YAAW,OAAO,KAAK;AAAA,MACvC,MAAM,SAAS,QAAQ,KAAK;AAAA,MAC5B,SAAS,SAAS,WAAW,CAAC;AAAA,IAClC,CAAC;AAAA,EACL;AACJ;AAEO,SAAS,eAAe,OAAO;AAClC,MAAI,CAAC,MAAO,QAAO,EAAE,SAAS,GAAG;AACjC,SAAO;AAAA,IACH,MAAM,MAAM,QAAQ;AAAA,IACpB,SAAS,MAAM,WAAW,OAAO,KAAK;AAAA,IACtC,OAAO,MAAM,SAAS;AAAA,IACtB,MAAM,MAAM,QAAQ;AAAA,IACpB,SAAS,MAAM,WAAW;AAAA,EAC9B;AACJ;",
+  "names": []
+}