简体中文

与 Android(adb) 集成

在使用 adb 连接 Android 设备后，你可以使用 Midscene javascript SDK 来控制 Android 设备。

样例项目

使用 javascript SDK 控制 Android 设备：https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo

与 Vitest 集成和测试：https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo

准备工作

安装 Node.js

安装 Node.js 18 或以上版本。

准备 API Key

准备一个视觉语言（VL）模型的 API Key。

你可以在 选择 AI 模型 文档中查看 Midscene.js 支持的模型和配置。

安装 adb

adb 是一个命令行工具，允许你与 Android 设备通信。有两种安装 adb 的方法：

验证 adb 是否安装成功：

adb --version

当你看到以下输出时，表示 adb 安装成功：

Android Debug Bridge version 1.0.41
Version 34.0.4-10411341
Installed as /usr/local/bin//adb
Running on Darwin 24.3.0 (arm64)

设置环境 ANDROID_HOME 变量

参考Android 环境变量，设置环境变量 ANDROID_HOME。

验证 ANDROID_HOME 变量是否设置成功：

echo $ANDROID_HOME

当上述命令有输出时，表示 ANDROID_HOME 变量设置成功：

/Users/your_username/Library/Android/sdk

连接 Android 设备

在 Android 设备的开发者选项中，启用 'USB 调试'，如果存在 'USB 调试（安全设置）'，也启用它，然后使用 USB 线连接 Android 设备。

android usb debug

验证连接：

adb devices -l

当看到以下输出时，表示连接成功：

List of devices attached
s4ey59	device usb:34603008X product:cezanne model:M2006J device:cezan transport_id:3

配置 AI 模型服务

将你的模型配置写入环境变量。更多信息请查看 选择 AI 模型。

# 替换为你的 API Key
export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

第一步：安装依赖

npm
yarn
pnpm
bun
npm install @midscene/android --save-dev

第二步：编写脚本

这里以使用安卓浏览器搜索耳机为例。(当然，你也可以使用设备上的其他任何应用)

编写下方代码，保存为 ./demo.ts

./demo.ts
import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
Promise.resolve(
  (async () => {
    const devices = await getConnectedDevices();
    const page = new AndroidDevice(devices[0].udid);

    // 👀 初始化 Midscene agent
    const agent = new AndroidAgent(page,{
      aiActionContext:
        '如果出现位置、权限、用户协议等弹窗，点击同意。如果出现登录页面，关闭它。',
    });
    await page.connect();

    // 👀 打开浏览器并导航到 ebay.com（请确保当前页面有浏览器 App 喔）
    await agent.aiAction('open browser and navigate to ebay.com');

    await sleep(5000);

    // 👀 输入关键词，执行搜索
    await agent.aiAction('在搜索框输入 "Headphones" ，敲回车');

    // 👀 等待加载完成
    await agent.aiWaitFor("页面中至少有一个耳机商品");
    // 或者你也可以使用一个普通的 sleep:
    // await sleep(5000);

    // 👀 理解页面内容，提取数据
    const items = await agent.aiQuery(
      "{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格"
    );
    console.log("耳机商品信息", items);

    // 👀 用 AI 断言
    await agent.aiAssert("界面左侧有类目筛选功能");
  })()
);

第三步：运行

使用 tsx 来运行

# run
npx tsx demo.ts

稍等片刻，你会看到如下输出：

[
 {
   itemTitle: 'JBL Tour Pro 2 - True wireless Noise Cancelling earbuds with Smart Charging Case',
   price: 551.21
 },
 {
   itemTitle: 'Soundcore Space One无线耳机40H ANC播放时间2XStronger语音还原',
   price: 543.94
 }
]

第四步：查看运行报告

当上面的命令执行成功后，会在控制台输出：Midscene - report file updated: /path/to/report/some_id.html， 通过浏览器打开该文件即可看到报告。

Android Agent 上的更多接口

除了 API 参考 中的通用 Agent 接口，AndroidAgent 还提供了一些其他接口：

agent.launch()

启动一个网页或原生页面。

  • 类型
function launch(uri: string): Promise<void>;

  • 参数：

    • uri: string - 要打开的 uri，可以是网页 url 或原生 app 的 package name 或 activity name，如果存在 activity name，则以 / 分隔（例如：com.android.settings/.Settings）

  • 返回值：

    • Promise<void>

  • 示例：

import { AndroidAgent, AndroidDevice } from '@midscene/android';

const page = new AndroidDevice('s4ey59');
const agent = new AndroidAgent(page);

await agent.launch('https://www.ebay.com'); // 打开网页
await agent.launch('com.android.settings'); // 打开系统设置 app(package name)
await agent.launch('com.android.settings/.Settings'); // 打开系统设置 app(package name) 的 .Settings(activity name) 页面

agentFromAdbDevice()

从已连接的 adb 设备中，创建一个 AndroidAgent。

  • 类型
function agentFromAdbDevice(deviceId?: string, opts?: PageAgentOpt): Promise<AndroidAgent>;

  • 参数：

    • deviceId?: string - 可选参数，要连接的 adb 设备 id，如果未传入，则使用第一个连接的设备
    • opts?: PageAgentOpt - 可选参数，用于初始化 AndroidAgent 的配置，参考 构造器

  • 返回值：

    • Promise<AndroidAgent> 返回一个 AndroidAgent 实例

  • 示例：

import { agentFromAdbDevice } from '@midscene/android';

const agent = await agentFromAdbDevice('s4ey59'); // 传入 deviceId
const agent = await agentFromAdbDevice(); // 不传入 deviceId，则使用第一个连接的设备

getConnectedDevices()

获取所有连接的 Android 设备。

  • 类型
function getConnectedDevices(): Promise<Device[]>;
interface Device {
  /**
   * The device udid.
   */
  udid: string;
  /**
   * Current device state, as it is visible in
   * _adb devices -l_ output.
   */
  state: string;
  port?: number;
}

  • 返回值：

    • Promise<Device[]> 返回一个 Device 数组

  • 示例：

import { agentFromAdbDevice, getConnectedDevices } from '@midscene/android'

const devices = await getConnectedDevices();
console.log(devices);
const agent = await agentFromAdbDevice(devices[0].udid);

更多

FAQ

为什么我连接了设备，但是通过 adb 仍然无法控制？

请检查是否在系统设置的开发者选项中，如果存在『USB 调试（安全设置）』，也需要开启。

android usb debug

如何使用自定义的 adb 路径？

你可以使用 MIDSCENE_ADB_PATH 环境变量来指定 adb 可执行文件的路径。

export MIDSCENE_ADB_PATH=/path/to/adb