#Android 环境配置

Midscene 通过 adb 连接并控制 Android 设备，支持对原生应用、混合应用及系统界面进行自动化操作。

本文介绍运行 Midscene Test、JavaScript SDK 和 Playground 所需的 Android 环境配置。你可以先通过 adb 连接设备，再使用 Playground 验证屏幕截图、触控输入与模型调用。

#通过 adb 连接设备

运行 Midscene 的电脑需要通过 adb 连接目标 Android 设备，支持 USB 和无线 adb 两种连接方式。如果已安装 adb 并连接好设备，可直接跳至确认设备连接。

#1. 安装 adb

• 通过 Android Studio 或独立的 Android 命令行工具安装 adb。
• 在终端运行以下命令，验证 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 环境变量文档配置 ANDROID_HOME 环境变量，并检查是否生效：

echo $ANDROID_HOME

输出应指向本机安装的 Android SDK 目录，例如：

/Users/your_username/Library/Android/sdk

#2. 开启调试并连接设备

以下以 USB 连接为例；如果设备已通过无线 adb 连接，可继续使用现有连接。

1. 在手机系统设置的「开发者选项」中开启 USB 调试（若同时存在 USB 调试（安全设置），请一并开启，以确保支持触控事件注入）。
2. 使用支持数据传输的 USB 数据线将手机连接到电脑。
3. 保持手机解锁亮屏，在手机弹出的授权窗口中勾选并允许 USB 调试。

#3. 确认设备连接

在终端运行以下命令检查连接状态：

adb devices -l

输出中设备状态显示为 device 即表示连接就绪：

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

如果同时连接了多台设备，请记录目标设备所在行第一列的设备 ID（如上例中的 s4ey59），以便后续在 Playground 或项目配置中指定该设备。

若未显示目标设备或状态不是 device，请按以下情况排查：

• 列表为空：USB 连接请检查数据线（需支持数据传输）、USB 连接模式和 USB 调试开关；无线连接请检查网络及 adb connect 连接状态。
• unauthorized：请解锁手机屏幕，在手机弹出的授权窗口中勾选并允许 USB 调试。
• offline：请重新建立 USB 或无线 adb 连接，必要时重启 adb 服务。请确认设备状态变为 device 后再继续后续步骤。

#在 Playground 中验证

借助 Playground，无需编写代码即可验证屏幕截图、触控输入与模型调用。

开始前，请参照使用模型 API Key或使用 ChatGPT 订阅准备好模型配置。

#启动 Playground

请确保已安装 Node.js（版本要求 ^20.19.0 || ^22.12.0 || >=24.0.0），且终端中可正常执行 node -v 和 npx --version。

1. 在终端运行以下命令启动 Android Playground：

npx --yes @midscene/android-playground

2. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。

3. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
4. 在左侧连接面板中选择目标 ADB device 并创建 Agent（若连接了多台设备，可对照 adb devices -l 输出的设备 ID 进行选择）。
5. 确认预览区域已正常显示当前手机屏幕画面；若画面未显示，请先排查 adb 连接与截屏权限。

#执行操作并验证结果

在手机上打开系统浏览器，跳过首次启动引导，访问 TodoMVC，并保持手机处于解锁亮屏状态且浏览器位于前台。

1. 在 Playground 中选择 aiAct，输入以下指令并运行：

添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。

2. 待页面中出现已勾选完成的待办事项后，切换到 aiAssert，输入以下断言并运行：

列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。

3. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，设备连接、屏幕截图、触控输入和模型调用均已验证完毕。

如果执行失败，请结合报错信息排查：若无画面或无法操控设备，请查看下方的常见问题；若模型请求报错，请参考模型连接检查。

#清理体验数据

验证结束后，请在 TodoMVC 页面中删除刚才创建的“体验 Midscene”待办事项。如果接下来要运行 Midscene Test 的 Android 示例，请切换到 All 视图并确认列表已完全清空（包括已完成事项），因为示例模板在运行前会校验初始列表为空，且不会主动覆盖已有数据。

#效果展示

提示词： 打开懂车帝，搜索 SU7 车型，查看参数配置。（完整报告）

#在测试或脚本中使用

完成设备连接与 Playground 验证后，即可将设备接入你的测试或脚本项目：

根据使用场景选择下一步：

• 使用 Midscene Test：前往配置模型与运行环境，完成配置并运行示例（若尚未初始化项目，可先从该页的创建项目开始并选择 Android 平台）。
• 接入 JavaScript 测试框架：参阅接入 Vitest。
• 编写独立自动化脚本：参阅编写独立自动化脚本中的 Android 示例。
• 查阅平台 SDK 接口：阅读 Android JavaScript SDK，了解设备选择、构造参数、平台专属方法与生命周期管理。

#常见问题

#找不到设备，或设备显示为未授权、离线

运行 adb devices -l，参照确认设备连接中的排查说明检查数据线、USB 调试授权与连接状态。请先确保目标设备状态显示为 device，再排查截图或触控问题。

#设备已连接，为什么仍然无法控制（报错 INJECT_EVENTS）？

如果执行点击或滑动时遇到类似以下的权限报错：

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.

这通常是因为部分品牌手机（如小米 / Redmi / VIVO / OPPO 等）对模拟点击有独立的权限开关。请在系统设置的「开发者选项」中确认以下两项均已开启：

1. USB 调试
2. USB 调试（安全设置） 或 禁止权限监控（如有）

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

如果文本已正常填入，但在软键盘收起时消失，通常是输入框响应了收起键盘时发送的 ESC 按键事件。你可以通过调整键盘收起策略解决该问题，具体参数与示例见 Android JavaScript SDK。

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

请先对比执行报告中记录的输入内容与输入框内的实际文本。若报告中的参数无误，但实际输入出现字符乱序、漏字或被拼音输入法候选词截获，请检查手机当前输入法及自动纠错设置。有关输入通道的详细说明，请参阅 Android JavaScript SDK。

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

请先切换到普通页面测试截图是否正常。如果仅在密码输入页或敏感信息页出现黑屏，通常是应用开启了系统截屏保护（FLAG_SECURE），并非 adb 连接断开。有关截图机制与限制说明，请参阅 Android JavaScript SDK。

#模型调用失败

请查看失败步骤的报错信息，并核对 Playground 设置或项目 .env 文件中的模型配置。设备连接正常并不代表模型服务可用，可参照模型连接检查排查 API Key、服务地址或网络问题。注意，命令行与项目运行不会读取浏览器中保存的 Playground 配置，需单独加载项目的环境变量。

#高级连接与调试

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

为避免模型基于过期画面做出错误决策，Midscene 会严格校验 scrcpy 视频帧的时间戳：任何无法证明采集时间晚于最近一次已完成操作、或超出最大帧龄限制的视频帧都会被拒绝。如果当前 scrcpy 视频流未能及时提供有效新帧，Midscene 会自动重启一次 scrcpy；仅当重启后仍无法获取有效帧时，才会回退为 adb 截图。

部分 Android 硬件编码器在屏幕画面完全静止时会暂停输出新帧，或者在视频流刚启动、USB 传输抖动时也可能触发该现象。注意：出现帧新鲜度超时告警并不代表传输带宽不足或视频码率过高，请勿仅因看到该告警就盲目调整视频码率。

#如何配置 scrcpy 视频码率？

请参阅 Android JavaScript SDK。

#如何从局域网其他电脑远程访问 Android Playground？

出于安全考虑，Playground 服务与内置的 scrcpy 投屏服务默认均只监听本机回环地址 127.0.0.1。如果需要从局域网内的另一台电脑访问 Android Playground，需在启动时通过环境变量显式放开两者的监听地址（以 macOS / Linux 为例）：

MIDSCENE_PLAYGROUND_HOST=0.0.0.0 MIDSCENE_SCRCPY_HOST=0.0.0.0 pnpm dlx @midscene/android-playground

启动后，在客户端浏览器中访问服务端电脑的实际局域网 IP（或主机名）加上终端打印的 Playground 端口（注意：0.0.0.0 是服务端监听通配地址，不能直接填在浏览器地址栏中），并确保防火墙已放行 Playground 与 scrcpy 两个端口。

MIDSCENE_SCRCPY_HOST 仅作用于独立的 Android Playground CLI，也可直接设为服务端具体的网卡 IP（如 192.168.1.100，此时本机自动打开的预览页也会使用该 IP 连接投屏流）。若在代码中直接实例化 ScrcpyServer，可通过构造函数参数 host 指定监听地址。

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

请参阅 Android JavaScript SDK。