agent-rdp

使用 agent-rdp 进行 Windows 远程桌面控制

快速开始

agent-rdp connect --host <ip> -u <user> -p <pass> --enable-win-automation
agent-rdp automate snapshot -i              # See interactive elements
agent-rdp automate click "@e5"              # Click button by ref
agent-rdp automate fill "@e7" "Hello"       # Type into field
agent-rdp disconnect

核心工作流

1. 使用自动化功能连接：agent-rdp connect --host <ip> -u <user> -p <pass> --enable-win-automation
2. 获取快照：agent-rdp automate snapshot -i（获取包含引用的辅助功能树）
3. 执行操作：agent-rdp automate click @e5 或 agent-rdp automate fill @e7 "text"
4. 重复：获取快照 → 执行操作 → 获取快照 → 执行操作……

故障排除

元素未出现在带 -i 的快照中

尝试不使用 -i 标志——某些元素未被标记为可交互，但仍可操作：

agent-rdp automate snapshot              # Full tree, no filtering
agent-rdp automate snapshot -d 5         # Limit depth if too large

元素完全不在辅助功能树中

某些 UI 元素（WebView 内容、某些对话框、Toast 通知）不会出现在辅助功能树中。请将 OCR 作为最后手段：

1. 截取屏幕截图，确认所需内容：agent-rdp screenshot -o screen.png
2. 使用 locate 查找坐标：agent-rdp locate "Button Text"
3. 使用返回的坐标点击：agent-rdp mouse click <x> <y>

命令

连接

agent-rdp connect --host 192.168.1.100 -u Admin -p secret
agent-rdp connect --host 192.168.1.100 -u Admin --password-stdin  # Read password from stdin
agent-rdp connect --host 192.168.1.100 --width 1920 --height 1080
agent-rdp connect --host 192.168.1.100 --drive /tmp/share:Share   # Map local directory
agent-rdp disconnect

屏幕截图

agent-rdp screenshot                      # Save to ./screenshot.png
agent-rdp screenshot -o desktop.png       # Save to specific file
agent-rdp screenshot --format jpeg        # JPEG format

鼠标

agent-rdp mouse click 500 300             # Left click at (500, 300)
agent-rdp mouse right-click 500 300       # Right click
agent-rdp mouse double-click 500 300      # Double click
agent-rdp mouse move 100 200              # Move cursor
agent-rdp mouse drag 100 100 500 500      # Drag from (100,100) to (500,500)

键盘

agent-rdp keyboard type "Hello World"     # Type text (supports Unicode)
agent-rdp keyboard press "ctrl+c"         # Key combination
agent-rdp keyboard press "alt+tab"        # Switch windows
agent-rdp keyboard press "ctrl+shift+esc" # Task manager
agent-rdp keyboard press "win+r"          # Run dialog
agent-rdp keyboard press enter            # Single key (use press, not key)
agent-rdp keyboard press escape
agent-rdp keyboard press f5

滚动

agent-rdp scroll up --amount 3            # Scroll up 3 notches
agent-rdp scroll down --amount 5          # Scroll down 5 notches
agent-rdp scroll left
agent-rdp scroll right

剪贴板

agent-rdp clipboard set "Text to paste"   # Set clipboard (paste on Windows)
agent-rdp clipboard get                   # Get clipboard (after copy on Windows)

驱动器映射

# Map at connect time
agent-rdp connect --host <ip> -u <user> -p <pass> --drive /local/path:DriveName

# List mapped drives
agent-rdp drive list

会话管理

agent-rdp session list                    # List active sessions
agent-rdp session info                    # Current session info
agent-rdp --session work connect ...      # Named session
agent-rdp --session work screenshot       # Use named session

等待

agent-rdp wait 2000                       # Wait 2 seconds

定位（OCR）

agent-rdp locate "Cancel"                 # Find lines containing "Cancel"
agent-rdp locate "Save*" --pattern        # Glob pattern matching
agent-rdp locate --all                    # Get all text on screen
agent-rdp locate "OK" --json              # JSON output with coordinates

返回包含边界框和中心坐标的文本行，可用于点击：

Found 1 line(s) containing 'Cancel':
  'Cancel' at (650, 420) size 45x14 - center: (672, 427)

To click the first match: agent-rdp mouse click 672 427

UI 自动化

# Connect with automation enabled
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --enable-win-automation

# Snapshot - get accessibility tree (refs always included)
agent-rdp automate snapshot                # Full desktop tree
agent-rdp automate snapshot -i             # Interactive elements only
agent-rdp automate snapshot -c             # Compact (remove empty elements)
agent-rdp automate snapshot -d 5           # Limit depth to 5 levels
agent-rdp automate snapshot -s "~*Notepad*"# Scope to a window/element
agent-rdp automate snapshot -f             # Start from focused element
agent-rdp automate snapshot -i -c -d 3     # Combine options

# Pattern-based element operations (use selectors: @eN, #automationId, .className, or name)
agent-rdp automate click "#SaveButton"    # Click button
agent-rdp automate click "@e5"            # Click by ref number
agent-rdp automate click "@e5" -d         # Double-click (for file list items)
agent-rdp automate select "@e10"          # Select item (SelectionItemPattern)
agent-rdp automate select "@e5" --item "Option 1"  # Select item by name in container
agent-rdp automate toggle "@e7"           # Toggle checkbox (TogglePattern)
agent-rdp automate toggle "@e7" --state on  # Set specific state
agent-rdp automate expand "@e3"           # Expand menu/tree (ExpandCollapsePattern)
agent-rdp automate collapse "@e3"         # Collapse menu/tree
agent-rdp automate context-menu "@e5"     # Open context menu (Shift+F10)
agent-rdp automate focus <selector>       # Focus element
agent-rdp automate get <selector>         # Get element properties

# Text input
agent-rdp automate fill <selector> "text" # Clear and fill text (ValuePattern)
agent-rdp automate clear <selector>       # Just clear

# Scrolling
agent-rdp automate scroll <selector> --direction down --amount 3

# Window operations
agent-rdp automate window list
agent-rdp automate window focus "~*Notepad*"
agent-rdp automate window maximize
agent-rdp automate window minimize
agent-rdp automate window restore
agent-rdp automate window close "~*Notepad*"

# Run commands/apps (best way to open apps)
agent-rdp automate run "notepad.exe"                                        # Open Notepad
agent-rdp automate run "Start-Process ms-settings:" --wait                  # Open Settings
agent-rdp automate run "calc.exe"                                           # Open Calculator
agent-rdp automate run "Get-Process" --wait --process-timeout 5000          # With 5s timeout

# Wait for element
agent-rdp automate wait-for <selector> --timeout 5000
agent-rdp automate wait-for <selector> --state visible

# Status
agent-rdp automate status

选择器语法：

• @e5 或 @5 - 快照中的引用编号（推荐使用 e 前缀）
• #SaveButton - 自动化 ID
• .Edit - Win32 类名
• ~*pattern* - 使用通配符的名称
• File - 元素名称（精确匹配）

快照输出格式：

- Window "Notepad" [ref=e1, id=Notepad]
  - MenuBar "Application" [ref=e2]
    - MenuItem "File" [ref=e3]
  - Edit "Text Editor" [ref=e5, value="Hello"]

JSON 输出

添加 --json 以获取机器可读的输出：

agent-rdp --json clipboard get
agent-rdp --json session info
agent-rdp --json automate snapshot

示例：打开 PowerShell 并运行命令

agent-rdp connect --host 192.168.1.100 -u Admin -p secret
agent-rdp wait 3000                       # Wait for desktop
agent-rdp keyboard press "win+r"          # Open Run dialog
agent-rdp wait 1000
agent-rdp keyboard type "powershell"
agent-rdp keyboard press enter
agent-rdp wait 2000                       # Wait for PowerShell
agent-rdp keyboard type "Get-Process"
agent-rdp keyboard press enter
agent-rdp screenshot --output result.png
agent-rdp disconnect

示例：通过映射驱动器传输文件

# Connect with local directory mapped
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --drive /tmp/transfer:Transfer

# On Windows, access files at \\tsclient\Transfer
agent-rdp keyboard press "win+r"
agent-rdp wait 500
agent-rdp keyboard type "\\\\tsclient\\Transfer"
agent-rdp keyboard press enter

示例：使用 UI 自动化操作记事本

# Connect with automation enabled
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --enable-win-automation

# Open Notepad
agent-rdp automate run "notepad.exe"
agent-rdp wait 2000

# Get accessibility snapshot (refs are always included)
agent-rdp automate snapshot -i            # Interactive elements only

# Type text into the edit control (use ref from snapshot)
agent-rdp automate fill "@e5" "Hello from automation!"

# Use File menu to save - expand menu, then invoke menu item
agent-rdp automate expand "File"          # Expand menu (ExpandCollapsePattern)
agent-rdp wait 500
agent-rdp automate click "Save As..."     # Click menu item

# Wait for Save dialog
agent-rdp automate wait-for "#FileNameControlHost" --timeout 5000

# Fill filename and save
agent-rdp automate fill "#FileNameControlHost" "test.txt"
agent-rdp automate click "#1"             # Click Save button

环境变量

export AGENT_RDP_HOST=192.168.1.100
export AGENT_RDP_PORT=3389
export AGENT_RDP_USERNAME=Administrator
export AGENT_RDP_PASSWORD=secret
export AGENT_RDP_SESSION=default
agent-rdp connect    # Uses env vars for connection

使用 WebSocket 流进行调试

# Enable streaming viewer on port 9224
agent-rdp --stream-port 9224 connect --host 192.168.1.100 -u Admin -p secret

# Open web viewer in browser
agent-rdp view --port 9224

# Or manually access WebSocket at ws://localhost:9224 (broadcasts JPEG frames)

提示

启用自动化时，优先使用 automate fill，而不是 keyboard type——它不会丢失字符，而且速度更快。

打开应用程序

使用 automate run 直接启动应用：

agent-rdp automate run "notepad.exe"
agent-rdp automate run "calc.exe"
agent-rdp automate run "Start-Process ms-settings:" --wait   # Settings
agent-rdp automate run "explorer.exe C:\\"                   # File Explorer

限制

重要：尝试执行自动化任务前，请仔细阅读这些限制。

UI 自动化无法访问 WebView

• Windows“开始”菜单搜索、Edge 浏览器内容、Electron 应用内容以及其他基于 WebView 的 UI，均无法通过 automate snapshot 访问。
• 解决方法：使用 Win+R（“运行”对话框）或 automate run 直接启动程序，而不是通过“开始”菜单导航。

UI 自动化无法处理 UAC 对话框

• 用户帐户控制提权提示运行在与 UI 自动化隔离的安全桌面上。
• UAC 对话框不会出现在 automate snapshot 输出中。
• 解决方法：使用 locate 命令（OCR）查找按钮文本，再用 mouse click 进行交互。此方法不可靠，但可能适用于简单的“是/否”对话框。

OCR（locate）可靠性不高

• locate 命令使用 OCR，可能误读字符、完全漏掉文本，或返回不精确的坐标。
• 当 UI 自动化无法访问元素时，请将其作为最后手段。
• 点击重要按钮前，务必确认坐标。

不要根据屏幕截图估算坐标（仅限 Claude）

• 非计算机使用模式下的 Claude 模型（例如 Claude Code）非常不擅长像素计数。
• 不要查看屏幕截图并尝试猜测坐标——估算结果很可能不正确。
• 注意：Gemini 模型通常擅长估算像素坐标。
• 如果需要使用 Claude 进行基于视觉的坐标检测，用户必须使用 Claude 的 Computer Use Tool 实现一个运行框架。

UI Automation 失败时的推荐工作流

1. 首先，始终尝试 automate snapshot（分别使用和不使用 -i 标志）
2. 如果未找到元素，尝试使用 locate "text" 通过 OCR 查找
3. 使用 locate 输出中的坐标执行 mouse click
4. 切勿通过查看截图来估算坐标