#Android

Midscene 通过 adb 连接 Android 设备，可自动化 App 和系统界面。

本指南介绍设备连接、模型配置、Playground 体验，以及 @midscene/android 的 JavaScript SDK 集成。

#效果展示

提示词： 打开懂车帝，搜索 SU7 车型，查看参数配置。

查看完整报告，或浏览更多 Midscene 案例。

#快速开始

#准备 Android 设备

在编写脚本前，先确认 adb 能够连接设备且设备信任当前电脑。

#安装 adb 并设置 ANDROID_HOME

• 通过 Android Studio 或 命令行工具 安装 adb
• 验证安装是否成功：

adb --version

出现类似输出表示安装成功：

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 environment variables 设置 ANDROID_HOME，并验证：

echo $ANDROID_HOME

有输出即代表配置成功：

/Users/your_username/Library/Android/sdk

#启用 USB 调试并验证设备

在系统设置的开发者选项中开启 USB 调试（若有 USB 调试（安全设置） 也请一并开启），然后用数据线连接手机。

验证连接：

adb devices -l

出现类似输出代表连接成功：

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

#启动 Playground

Playground 是验证连接的最快方式。无需编写代码，即可体验 aiAct、aiQuery 和 aiAssert 等核心能力。它与 @midscene/android 共享相同的代码实现，因此在 Playground 上验证通过的流程，用脚本运行时也完全一致。

1. 启动 Playground CLI：

npx --yes @midscene/android-playground

2. 点击 Playground 窗口中的齿轮按钮，粘贴你的 API Key 配置。如果还没有模型配置，请参考支持的模型与配置。

#使用 JavaScript SDK

当 Playground 运行正常后，就可以切换到可复用的 JavaScript 脚本。

#配置模型

下面以豆包 Seed 2.1 Turbo 为例：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export MIDSCENE_MODEL_API_KEY="your-api-key"
export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
export MIDSCENE_MODEL_FAMILY="doubao-seed"

将 your-api-key 替换为你的 API Key。

如需使用千问（Qwen）、GLM、Gemini 或 GPT-5 等其他模型，请参考支持的模型与配置。

全部配置项请参考模型配置。

#安装依赖

npm install @midscene/android dotenv --save-dev

yarn add @midscene/android dotenv --save-dev

pnpm add @midscene/android dotenv --save-dev

bun add @midscene/android dotenv --save-dev

deno add npm:@midscene/android npm:dotenv --save-dev

#编写脚本

下面的示例会在设备上打开浏览器、搜索 eBay，并断言结果列表。

import 'dotenv/config'; // 通过 dotenv/config 自动加载 .env 文件中的环境变量
import {
  AndroidAgent,
  AndroidDevice,
  getConnectedDevices,
} from '@midscene/android';

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

    const agent = new AndroidAgent(device, {
      aiActionContext:
        'If any location, permission, user agreement, etc. popup, click agree. If login page pops up, close it.',
    });
    await device.connect();

    await agent.aiAct('open browser and navigate to ebay.com');
    await sleep(5000);
    await agent.aiAct('type "Headphones" in search box, hit Enter');
    await agent.aiWaitFor('There is at least one headphone product');

    const items = await agent.aiQuery(
      '{itemTitle: string, price: Number}[], find item in list and corresponding price',
    );
    console.log('headphones in stock', items);

    await agent.aiAssert('There is a category filter on the left');
  })(),
);

#运行脚本

npx tsx demo.ts

脚本运行结束后，你应该能在控制台看到 Midscene - report file updated: /path/to/report/some_id.html。在浏览器中打开生成的 HTML 文件，即可回放每次交互、查询和断言。

#进阶

本节介绍如何自定义设备行为、把 Midscene 接入独立框架，以及排查 adb 问题。更多构造函数参数位于 API 参考的 Android 章节。

#扩展 Android 上的 Midscene

使用 defineAction() 定义自定义动作。构造 AndroidDevice 时，通过 customActions 传入这些动作。Midscene 会把这些动作追加到规划器中，让 Agent 可以调用你定义的领域特定动作。

import { getMidsceneLocationSchema, z } from '@midscene/core';
import { defineAction } from '@midscene/core/device';
import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';

const ContinuousClick = defineAction({
  name: 'continuousClick',
  description: 'Click the same target repeatedly',
  paramSchema: z.object({
    locate: getMidsceneLocationSchema(),
    count: z.number().int().positive().describe('How many times to click'),
  }),
  async call(param) {
    const { locate, count } = param;
    console.log('click target center', locate.center);
    console.log('click count', count);
  },
});

const devices = await getConnectedDevices();
const device = new AndroidDevice(devices[0].udid, {
  customActions: [ContinuousClick],
});
await device.connect();

const agent = new AndroidAgent(device);

await agent.aiAct('click the red button five times');

关于自定义动作和动作 Schema 的更多解释，请参阅 与任意界面集成。

#常见问题

#为什么连接了设备，但仍然无法控制？

一个典型的错误信息是：

Error:
Exception occurred while executing 'tap':
java.lang.SecurityException: Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.

请在系统设置的开发者选项中确认以下选项已开启：

1. USB 调试
2. USB 调试（安全设置）（如果存在）

#输入文本后，输入框内容被清空或消失

Midscene 在输入文本后会自动隐藏键盘，默认行为是发送 ESC 按键事件。然而，部分输入框（尤其是 WebView 中的输入框）会监听 ESC 按键事件，导致以下副作用：

• 清空刚输入的文本
• 关闭包含输入框的弹窗或模态框
• 导航离开当前页面

你可以按以下优先级逐步尝试解决：

方案一：改用 BACK 键(Android 返回键)隐藏键盘

将 keyboardDismissStrategy 设为 'back-first'，用 Android BACK 键替代 ESC 键来隐藏键盘：

const device = new AndroidDevice('device-id', {
  keyboardDismissStrategy: 'back-first',
});

方案二：关闭自动隐藏键盘

如果你的输入框同时监听了 BACK 键，可以彻底关闭自动隐藏键盘，由 AI Agent 或后续操作自行管理键盘状态：

const device = new AndroidDevice('device-id', {
  autoDismissKeyboard: false,
});

关闭后键盘不会自动隐藏，可能导致键盘覆盖大量屏幕区域。你可以通过以下方式应对：

• 使用 aiAct 指令手动隐藏键盘，例如 await agent.aiAct('点击键盘上的收起按钮')
• 安装并切换到 ADBKeyBoard——这是一款极小面积的虚拟键盘，即使不隐藏也几乎不影响屏幕操作

#英文文本被 Android 输入法改写

如果报告中显示的输入参数是正确的，但 App 实际收到的是不同文本、缺字，或被改成中文/拼音候选词，通常是当前 Android 输入法改写了输入内容。纯 ASCII 文本如果走原生 adb input text 路径，在中文输入法或带自动纠错的输入法下就可能出现这个问题。

使用已有的 imeStrategy 选项，将所有文本输入强制改为 yadb：

const device = new AndroidDevice('device-id', {
  imeStrategy: 'always-yadb',
});

YAML 脚本中可以这样配置：

android:
  imeStrategy: always-yadb

也可以通过环境变量设置：

export MIDSCENE_ANDROID_IME_STRATEGY=always-yadb

这和“输入后被清空”不是同一个问题。如果文本先正确输入、随后消失，请优先检查 keyboardDismissStrategy 或 autoDismissKeyboard。

#安全页面（如密码输入框）截图黑屏

部分页面（如银行、支付类 App 的密码输入页）会通过 FLAG_SECURE 禁止截屏。此时使用 screencap 截出的图片中，安全区域会显示为黑色。

yadb 工具通过 SurfaceControl.createDisplay 的 secure 参数创建虚拟显示器，在某些环境下可以截取安全页面内容。能否截取 FLAG_SECURE 页面取决于 Android 版本、ROM、root/hook 环境和设备配置（例如某些环境可能需要配合 root 和 Magisk hook）。请以实际设备测试结果为准。

使用 screenshotStrategy 选项，将截图方式强制改为 yadb：

const device = new AndroidDevice('device-id', {
  screenshotStrategy: 'always-yadb',
});

YAML 脚本中可以这样配置：

android:
  screenshotStrategy: always-yadb

也可以通过环境变量设置：

export MIDSCENE_ANDROID_SCREENSHOT_STRATEGY=always-yadb

默认值为 auto，即先使用 adb.takeScreenshot，失败后回退到 shell screencap；如果 screencap 执行失败，则改用 yadb 工具。scrcpy 仅当 scrcpyConfig.enabled 开启时才会在这些方法之前优先尝试。auto 不会分析截图内容：即使某个截图方法执行成功但返回全黑图片，也不会自动切换到 yadb；只有当前一种截图方法执行失败时，才会尝试下一种方法。安全页面生成有效但全黑的图片时，请设置 always-yadb，绕过默认的 auto 截图流程（adb.takeScreenshot、screencap，以及开启时的 scrcpy），直接使用 yadb 截图。yadb 只能截取默认显示器（displayId=0）；如果同时设置 always-yadb 和非零 displayId，Midscene 会抛出错误。

#为什么 scrcpy 会回退到 ADB 截图？

Midscene 会拒绝无法证明拍摄时间晚于最近一次已完成操作，或不满足绝对帧龄限制的 scrcpy 帧。如果已有视频流无法提供有效帧，Midscene 会自动重启一次 scrcpy；只有新视频流仍然失败时，才会回退到 ADB 截图。

部分 Android 编码器会在画面静止时停止输出帧，视频流启动或传输中断也可能导致此现象。仅凭 freshness 告警无法判断链路带宽不足或视频码率过高，请勿只因为出现该告警就调整码率。

#如何配置 scrcpy 视频码率？

在 Android CLI 命令中使用 --scrcpy-video-bit-rate <bits-per-second>（或 --scrcpyVideoBitRate）。设置该参数本身就会启用 scrcpy，因此可以省略 --use-scrcpy：

midscene-android tap \
  --device-id <device-id> \
  --locate '{"prompt":"目标元素"}' \
  --scrcpy-video-bit-rate <bits-per-second>

每条 CLI 命令都是独立进程，因此每条需要覆盖默认码率的命令都要传入该参数。使用 JavaScript SDK 或 YAML 时，只需在对应设备配置中设置一次 scrcpyConfig.videoBitRate。调整码率是在编码带宽和截图细节之间取舍；只有独立的链路测量表明有需要时才应调优，并验证截图与识别质量。默认值和相关选项见 AndroidDevice scrcpy 参考。

#如何使用自定义的 adb 路径或远程 adb 服务器？

通过环境变量设置：

export MIDSCENE_ADB_PATH=/path/to/adb
export MIDSCENE_ADB_REMOTE_HOST=192.168.1.100
export MIDSCENE_ADB_REMOTE_PORT=5037

也可以通过 AndroidDevice 构造函数传入：

const device = new AndroidDevice('s4ey59', {
  androidAdbPath: '/path/to/adb',
  remoteAdbHost: '192.168.1.100',
  remoteAdbPort: 5037,
});

#更多

• 查看所有 Agent 方法：API 参考（通用）
• Android 专属参数与接口：API 参考（Android）
• 使用 YAML 自动化脚本和命令行工具。
• 示例项目
  • Android JavaScript SDK 示例：https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo
  • Android + Vitest 示例：https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo