完成一项简单的远端编辑任务

连接已有 VNC 桌面，在空白文档输入一行文字，再用新截图核对。本文依据 rdp-cli 0.1.0 和 2026 年 9 月已有验收资料整理，不声称本轮重新实测。9 月 20 日的 Mac 工作流使用真实 Ubuntu 24.04 / TigerVNC 1.13.1 桌面及 xterm；后续 Linux 验收也覆盖了带认证的 TigerVNC。下文文字是教学示例，不是重放某次测试会话。

准备服务端与客户端

下载适合本机的版本，并按快速上手完成平台安装。远端必须已有网络可达的 VNC 服务，且你拥有观看和控制权限。在远端文本编辑器准备一份空白文档。rdp-cli 不会替你安装服务端，也不包含 AI 模型。

VNC 默认端口为 5900，使用密码认证。当前支持的安全模式不加密桌面传输，应在可信网络或 VPN 中使用。传统 VNC 认证只使用密码的前八个 UTF-8 字节。不要添加 RDP 专属的 --user、--domain、显示布局或证书选项。

明确选择 VNC 协议

替换文档示例地址与端口。在 macOS 或 Linux 中使用 Bash 执行下列命令；Mac 用户可先运行 bash。Linux 中把 rdp-cli 换成已安装命令或本架构可执行文件路径。

IFS= read -r -s -p 'Password: ' vnc_password
printf '\n'
printf '%s' "$vnc_password" | rdp-cli connect --protocol vnc --host 192.0.2.20 --port 5900 --password-stdin
unset vnc_password

Windows 请在 EXE 所在目录使用 PowerShell：

$secret = Read-Host 'Password' -AsSecureString
$savedEncoding = $OutputEncoding
try {
  $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
  [System.Net.NetworkCredential]::new('', $secret).Password |
    .\rdp-cli.exe connect --protocol vnc --host 192.0.2.20 --port 5900 --password-stdin
} finally {
  $OutputEncoding = $savedEncoding
  $secret.Dispose()
}

读取 JSON，把 data.session 保存为 SESSION，检查 ok 和可能的 error.code。连接失败时不要静默改用其他认证方式。--vnc-security none 仅用于明确配置为无认证的服务端，必须显式指定，且不能同时传入密码来源。已有 --credential-ref 可以替代 --password-stdin，不能叠加为第二个密码来源。

观察、操作，再次核对

下文 Windows 命令中的 rdp-cli 应换为 .\rdp-cli.exe；Linux 继续使用正确的可执行文件路径。

rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION --out vnc-before.png

读取 vnc-before.png，确认目标桌面及编辑器，把截图响应的 data.observation 保存为 OBSERVATION。检查状态响应中的协议、连接和控制状态。根据当前画面选择文档的真实远端坐标 X、Y：

rdp-cli click --session SESSION --desktop --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out vnc-focused.png

读取 vnc-focused.png 确认焦点，并把该响应的 data.observation 用作 NEW_OBSERVATION：

rdp-cli type --session SESSION --text "VNC command check" --observation NEW_OBSERVATION
rdp-cli screenshot --session SESSION --out vnc-after.png

打开 vnc-after.png，检查 “VNC command check” 是否完整出现在目标文档。输入成功发送不等于应用接受了内容。不要照搬教程坐标，也不要在画面尺寸、连接或控制状态变化后使用旧观察令牌。

按需观看和恢复

本机查看器是可选的。人想观看同一会话时运行：

rdp-cli watch --session SESSION --viewer window

查看器默认只读。暂停、接管和交还都需明确操作；输入暂停或人类持有控制时，Agent 必须停止输入。重连及服务端尺寸变化会使观察令牌失效，并让控制保持暂停。获授权恢复前，应重新截图检查。

连接失败时核对地址、端口、服务端认证和网络可达性，读取返回错误，不要反复尝试密码。文字不符时检查焦点、远端键盘布局和输入法，再重新核对画面。VNC Unicode 事件不保证所有服务端和应用都能输入任意字符。输入结果未知时，先查看画面并查询原操作，再决定是否重试。

了解 VNC 能力边界

VNC 可使用共同的截图、输入和观看工作流，但不提供交换盘文件、声音、麦克风或客户端请求的显示布局；相关操作返回 CAPABILITY_UNAVAILABLE。UTF-8 剪贴板需要协商得到 clipboard_utf8，否则仅支持 Latin-1。打开查看器不会增加协议缺失的能力。

精确参数见命令参考；选择协议时参考功能对照，平台安装步骤见快速上手。