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 示例使用虚构的服务数据。下方成果工作簿与对应语言、主题的截图配套。

出错时先恢复状态
观察令牌过期就重新截图。人类暂停或接管时,Agent 应停止输入。重连或交接后使用新观察,不继续套用旧令牌。
操作超时时,先按原请求或操作查询状态,再决定是否重试:
rdp-cli operations status --session SESSION --request-id PASTE_REQUEST
结果不明确,不代表什么都没发生。文件传输也一样,应使用 files status 查询并核对完成结果,不能因为第一次回复丢失就重新上传。
同时保留本机工作空间
普通截图和输入命令通过远程协议工作,不需要打开本机查看器,也不移动本机指针。人仍可随时打开会话观看或接管。剪贴板、文件和不同协议的条件见功能说明。
在你的远程桌面上开始
相关教程
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"}]}