rdp-cli

面向 AI Agent 的 Android 虚拟显示屏自动化

Android 虚拟显示屏自动化可以为 AI Agent 提供一个独立的显示目标,用于操作和测试 Android 应用。

Agent 不必始终控制手机的实体主屏幕,而是可以创建会话专属的虚拟显示屏,设置尺寸和 DPI,启动应用,并通过新的截图验证每个动作。

使用 rdp-cli,AI Agent 可以通过 ADB over USB 或 Wi-Fi 连接 Android 设备,选择虚拟显示屏并执行基于截图的自动化流程。

简要结论:Android 虚拟显示屏自动化让 AI Agent 可以在独立显示屏上运行 GUI 任务。可靠流程是:创建显示屏、截图、执行一个动作、再次截图并验证结果。

Android 虚拟显示屏与主显示屏

rdp-cli 支持两种 Android 显示目标:

  • main:控制手机当前的实体主显示屏。
  • virtual:为自动化会话创建专属虚拟显示屏。

当 Agent 需要固定屏幕尺寸和 DPI 时,虚拟显示屏很有用。Agent、GUI Viewer 和 Web Viewer 会使用当前会话选择的显示目标。应用行为和系统权限仍可能因设备和应用而不同。

虚拟显示屏不是云端 Android 模拟器。应用仍然运行在已授权的实体 Android 设备上,兼容性取决于 Android 版本、设备厂商和目标应用。

什么时候适合使用虚拟显示屏?

Android 虚拟显示屏自动化适合:

  • 重复执行 Android GUI 测试
  • 测试没有可用 API 的应用
  • 运行表单、登录和审批流程
  • 使用固定尺寸进行视觉测试
  • 保存每一步的截图证据
  • 在独立显示目标中运行应用

如果还没有连接 Android 设备,请先阅读让 AI Agent 通过 USB 或 Wi-Fi 操作 Android 手机。设备授权后,再继续下面的虚拟显示屏流程。

准备条件

请准备:

  • Android 12 或更高版本的设备
  • 已启用 USB 调试或无线调试
  • 已在手机上确认 ADB 授权
  • 已安装目标应用
  • 支持 Android 的 rdp-cli 版本
  • 适合测试的虚拟显示屏尺寸和 DPI

rdp-cli 当前以 Android 12+ 作为支持基线。Google Pixel 3 搭载 Android 12 是已验证的参考设备,其他设备的兼容性可能不同。

创建 Android 虚拟显示屏

设备发现并授权后,创建虚拟显示屏会话:

rdp-cli connect \
  --protocol adb \
  --device usb:DEVICE_ID \
  --transport usb \
  --android-display virtual \
  --android-virtual-size 1080x1920 \
  --android-virtual-dpi 420 \
  --android-start-app com.example.app

将 DEVICE_ID 替换为已授权的设备 ID,将尺寸、DPI 和应用包名替换为实际值。

命令会返回会话 ID,请保存它供后续操作使用。虚拟显示屏参数见 rdp-cli 命令文档。

使用“观察、操作、验证”流程

不要根据旧截图发送操作。

先截取当前虚拟显示屏:

rdp-cli screenshot \
  --session SESSION \
  --out before.png

查看截图,找到目标控件,再使用最新 observation 执行一个动作:

rdp-cli android touch \
  --session SESSION \
  --kind tap \
  --x X \
  --y Y \
  --observation OBSERVATION

再次截图:

rdp-cli screenshot \
  --session SESSION \
  --out after.png

第二张截图才是验证结果。输入命令返回成功,只表示动作已经发送,并不代表应用已经进入预期状态。

传输测试文件并加入人工检查

多行或 Unicode 文本可以使用 Android 剪贴板方式输入:

rdp-cli android text \
  --session SESSION \
  --method clipboard \
  --text "Test order completed." \
  --observation OBSERVATION

也可以通过会话文件目录上传测试文件:

rdp-cli files upload \
  --session SESSION \
  --local ./test-data.json \
  --path test-data.json

下载结果后,等待传输完成并核对文件。

需要人工检查时,可以在浏览器中打开同一会话:

rdp-cli watch --session SESSION --viewer web

人工可以暂停 Agent、处理权限弹窗或修正异常界面,再把控制权交还给 Agent。控制权发生变化后,Agent 应重新截图再继续。

限制

  • 必须完成 ADB 授权。
  • 设备和 Android 版本的兼容性可能不同。
  • 某些应用在虚拟显示屏中的行为可能不同。
  • 系统权限和音频行为仍然适用。
  • 安全窗口可能限制屏幕截图。
  • rdp-cli 提供设备控制,不包含 AI 模型。
  • 任务规划仍由外部 AI Agent 负责。

常见问题

Android 虚拟显示屏自动化需要 root 吗?

按照 rdp-cli 的文档流程,不需要 root,但必须通过 USB 或 Wi-Fi 完成 ADB 授权。

所有 Android 应用都能在虚拟显示屏中自动化吗?

不能保证。部分应用依赖实体显示屏、设备服务或特定系统权限。正式使用前应在目标设备上测试。

如何确认 Android 自动化动作成功?

动作前截图,发送一个输入命令,再截取新截图并检查可见结果。命令发送成功本身不等于任务完成。

rdp-cli 包含 AI Agent 吗?

不包含。rdp-cli 提供连接、截图、输入、会话控制和结构化结果,具体操作由外部 AI Agent 决定。

总结

Android 虚拟显示屏自动化适合需要固定显示目标来测试或重复运行 Android GUI 流程的 AI Agent。

可靠模式是:

创建虚拟显示屏 → 截图 → 执行一个动作 → 再次截图 → 验证结果。

使用 rdp-cli,Agent 可以在虚拟显示屏中启动 Android 应用,操作可见控件,传输测试文件,并在需要时暂停等待人工检查。

阅读 rdp-cli 快速上手指南。