rdp-cli

AI Agent 如何透過 RDP 截圖、點擊與輸入完成遠端任務

適用版本與平台: 0.1.2 · Windows / macOS · RDP

先說明想得到什麼結果

告訴 Agent 程序位置、獲授權的目標或已有會話,以及具體目標,例如在遠端編輯器輸入一段文字並確認顯示正確。工具本身不包含 AI 模型,由你的 Agent 根據畫面決定下一步。

先按快速上手連接服務端並儲存 data.session。下面的 SESSION 都代表這個返回值。

操作之前先看畫面

在 Windows PowerShell 中,請切換到執行檔所在目錄,並將下文指令中的 rdp-cli 換成 .\rdp-cli.exe。

以下 Calc 範例需要遠端 Windows 已安裝 LibreOffice Calc,並允許 RDP 磁碟重新導向。先將範例活頁簿下載至本機,儲存為 service-activity.xlsx。上傳後將 data.transfer_id 作為 TRANSFER_ID,等候狀態為 completed。再於遠端 Calc 從重新導向磁碟開啟檔案,選取 A20 儲存格。完整 Calc 教學說明活頁簿與預期結果。

rdp-cli files upload --session SESSION --local ./service-activity.xlsx --path service-activity.xlsx
rdp-cli files status --session SESSION --transfer-id TRANSFER_ID
rdp-cli screenshot --session SESSION --out before.png

打開 PNG 查看桌面,儲存響應中的 data.observation,在下一次輸入時使用。座標屬於遠端桌面,不是本機查看視窗。需要聚焦某個輸入框時,根據圖中的實際位置點擊:

rdp-cli click --session SESSION --desktop --x 420 --y 315 --observation OBSERVATION

這裏的數字只是示例,實際座標必須從當前畫面選擇。應用移動或彈出新對話框後,重新截圖觀察。

輸入一段文字,再核對

下列範例在遠端 Calc 開啟準備好的活頁簿,選取 A20 儲存格。讀取新截圖並使用其中的觀察權杖,貼上完成說明,透過應用程式的儲存按鈕儲存,再檢查顯示結果。

將 before.png 那次擷取回應的 data.observation 作為 OBSERVATION。點擊後查看 clipboard-ready.png,將新回應的 data.observation 作為 NEW_OBSERVATION。最後查看 result.png 確認文字確實出現;命令成功不代表應用程式已接受輸入。

為本次貼上選擇不重複的 PASTE_REQUEST,並連同回應儲存。逾時時以同一個 ID 查詢;先檢查畫面,不要換 ID 再貼上一次。

PNG data.observation
note-focused.png FOCUSED_OBSERVATION
clipboard-ready.png NEW_OBSERVATION
rdp-cli screenshot --session SESSION --out note-focused.png
rdp-cli clipboard set --session SESSION --text "結果:報表已完成,等待審核。" --observation FOCUSED_OBSERVATION
rdp-cli screenshot --session SESSION --out clipboard-ready.png
rdp-cli key --session SESSION --keys CTRL+V --observation NEW_OBSERVATION --request-id PASTE_REQUEST
rdp-cli screenshot --session SESSION --out result.png

透過 rdp-cli 貼上完成說明並儲存後的遠端 Calc 報表。

Calc 範例使用虛構的服務資料。下方成果活頁簿與對應語言、主題的畫面配套。

下載畫面對應的成果: 亮色主題 · 暗色主題

透過 rdp-cli 貼上完成說明並儲存後的遠端 Calc 報表。

查看原始螢幕截圖 — 亮色 ↗ · 查看原始螢幕截圖 — 暗色 ↗

出錯時先恢復狀態

觀察權杖過期就重新截圖。人類暫停或接管時,Agent 應停止輸入。重連或交接後使用新觀察,不繼續套用舊權杖。

操作超時時,先按原請求或操作查詢狀態,再決定是否重試:

rdp-cli operations status --session SESSION --request-id PASTE_REQUEST

結果不明確,不代表什麼都沒發生。檔案傳輸也一樣,應使用 files status 查詢並核對完成結果,不能因爲第一次回覆丟失就重新上傳。

同時保留本機工作空間

普通截圖和輸入命令透過遠端協議工作,不需要打開本機查看器,也不移動本機指針。人仍可隨時打開會話觀看或接管。剪貼簿、檔案和不同協議的條件見功能說明。

在你的遠端桌面上開始

下載 rdp-cli · 依照對應平台的快速入門操作

相關教學

rdp-cli 的增強命令

先執行 rdp-cli --version。以下增強命令要求回應中的 agent_execution.contract_version 為 1;舊版本仍可使用上文的單步操作。

將大寫預留位置換成實際回傳值。Windows PowerShell 中請在程式目錄使用 .\rdp-cli.exe;macOS、Linux 使用已安裝的命令或執行檔的實際路徑。

只看需要看的區域

擷取局部或縮小畫面,與上次觀察比較;沒有變化時不重複傳回圖片。座標仍與遠端畫面對應。

等畫面變化,也等檔案傳完

等待指定區域變化或穩定,或等待連線、操作、檔案傳輸到達指定狀態。繼續前仍需核對實際成果。

一小組操作,停下來核對

組合傳送 Agent 已確定的動作,加入新觀察並停在檢查點。出錯或控制權變更就停止後續步驟;已送出的動作不會復原。

保留進度,中斷後查清再繼續

儲存任務進度、檢查點和選定畫面,匯出本機報告。中斷後先核對已完成的工作,再提交新步驟,不重送結果未知的動作。

將下方 JSON 透過標準輸入傳給 batch。此範例只觀察並停在檢查點;確認目前畫面後,再加入實際輸入動作。 將 tasks create 回傳的任務 ID 填入 TASK_ID,讓這批操作記錄在同一個任務中。

rdp-cli screenshot --session SESSION --max-width 640
rdp-cli screenshot --session SESSION --region X,Y,WIDTH,HEIGHT --max-width 640
rdp-cli wait --session SESSION --condition changed --region X,Y,WIDTH,HEIGHT --timeout-ms 10000
rdp-cli tasks create --session SESSION --title "Review result"
rdp-cli batch --session SESSION --task TASK_ID --steps-stdin --request-id UNIQUE_REQUEST_ID
{"version":1,"steps":[{"id":"look","command":"observe","arguments":{"max-width":640}},{"id":"review","command":"checkpoint"}]}