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、顯示尺寸、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 快速開始指南。