PVE 虚拟机控制 taxah92/dsh-pve-vm

dsh-pve-vm

为 DeepSeek Harness 提供 Proxmox VE 虚拟机控制：通过 VNC 查看虚拟机屏幕并在控制台里点击，还能借助 QEMU guest agent 执行命令、读写文件和输入文本。

几乎所有 computer-use 插件操控的都是智能体自己所在的桌面，因此需要那台主机上有 X11 或 Wayland、截图工具和输入注入器。这个插件不一样：它操控的是 Proxmox VE 节点上某台虚拟机的控制台，只走一条 ssh 连接。主机可以是无头服务器、Wayland 桌面，也可以是远在另一个国家的笔记本；客户机可以是 Windows、带任意 GUI 的 Linux，甚至是一台还没启动的机器。

agent ──► plugin ──► ssh ──► node: qm vncproxy ──► unix socket /var/run/qemu-server/<vmid>.vnc
└────► node: qm guest exec ──► qemu-guest-agent inside the VM

你能得到什么

* 画面 — console_shot 把虚拟机屏幕作为内联图片返回（可用 region 和 scale 控制 token 开销），鼠标和键盘工具则按虚拟机屏幕坐标操作：移动、单击、双击、拖拽、滚轮、输入文本、组合键，还有一个批量执行器，能连续执行一串动作，最后返回一帧画面。
* 命令 — 通过 QEMU guest agent 使用 vm_exec、vm_file_read、vm_file_write、vm_status。确定又便宜：只有在 GUI 真的挡路时才用画面。
* 可靠的输入 — 大写字母走 Caps Lock（qm monitor → HMP sendkey），带 Shift 的符号走 RFB keysym 并留出稳定延迟。正因如此，在 Windows 登录界面输入密码才能成功，而不是打出 xxXX → xxxX。
* Unicode 文本 — Windows 客户机会在已登录用户的会话里创建一个计划任务（SendKeys），Linux 客户机则通过 guest agent 调用 xdotool/wtype。键盘布局和修饰键都不再重要。
* 剪贴板 — console_paste 通过 RFB 把 UTF-8 文本写进客户机剪贴板，再按 Ctrl+V；console_clipboard 读回客户机剪贴板，这样文本不用 OCR 就能从虚拟机里出来。
* Web UI 里的设置卡片（英文和俄文标签），由 profile 补丁层支撑。
* 实时屏幕面板 — 右侧边栏的「VM screen」标签页会显示智能体看到的画面，取自同一个 VNC 会话，智能体工作时同步更新。它会自动跟随智能体的虚拟机，也可以停在你手动选定的虚拟机上。仅供观看：面板从不点击、也不输入。
* 零运行时依赖 — RFB、DES 认证、keysym 表和 PNG 编码都在本包内基于 node:crypto 和 node:zlib 实现。主机上无需安装任何东西，节点上也一样。

已在 pve-manager 8.4.21 上验证，客户机为 Windows 11 / Windows Server 2025 和 Linux，DeepSeek Harness 版本为 0.2.0-rc.2。

要求

| 项目 | 原因 |
| DeepSeek Harness ≥ 0.2.0-rc.2 | 插件使用 0.2.x 插件契约（defineTool、ctx.tools、ctx.subprocess、ctx.attachments、computerUse 槽位、客户端 configForms）。在 0.1.x 上无法加载。 |
| Node.js ≥ 22 | harness 运行时。 |
| 一台装了 qm 命令行的 Proxmox VE 节点 | /usr/sbin/qm vncproxy、qm guest exec、qm monitor。不支持容器（LXC）。 |
| 以 root 身份 SSH 登录该节点（或使用可运行 qm 的账号） | qm 需要节点上的 root 权限。默认走密钥登录（BatchMode，不弹密码提示）。 |
| 节点 sshd_config 里有 AcceptEnv LC_ | VNC 密码通过 SendEnv 以 LC_PVE_TICKET 环境变量交给 qm，因此不会出现在 ps 里。没有 AcceptEnv，ssh 会静默丢弃它，控制台就无法认证。 |
| 主机密钥已接受 | 连接以 BatchMode=yes 运行；未知主机密钥会失败。手动跑一次 ssh <node>，或在 sshExtraOptions 里加上 StrictHostKeyChecking=accept-new。 |
| 客户机内有 qemu-guest-agent（可选） | 只有 vm_ 工具需要它。控制台工具完全不需要任何 agent。 |

安装

1. Add the bundle
dsh plugin --profile web add github:taxah92/dsh-pve-vm

2. Make sure the bundle is enabled in the profile: dsh.profile.bundles must list "dsh-pve-vm"
(the plugin manager / market toggle does the same thing)

3. Restart the harness: the host half of a plugin is loaded once per process

插件会往配置档补丁层加一行：

- id: pve-vm
name: dsh-pve-vm

行 id pve-vm 就是设置命名空间——不要改名，否则设置卡片和补丁层会互相找不到。

配置

在 Web UI 里打开 Settings ▸ Plugins ▸ Proxmox VE。所有内容都会写进配置档补丁层，也可以在那里手动改同样的值：

- id: pve-vm
name: dsh-pve-vm
config:
sshHost: proxmox # alias from ~/.ssh/config, or an address
sshUser: root
sshPort: 22
sshKeyPath: '' # empty — default keys sshConfigFile: '' # like ssh -F
sshExtraOptions: [] # extra -o options, one per item
allowVmids: [100, 101] # VMs the plugin may touch; empty list forbids everything
enableConsole: true
enableGuest: true
inputChannel: auto # auto | hmp | vnc
sendkeyDelayMs: 80
consoleTimeoutMs: 20000
sessionIdleMs: 300000
guestTimeoutMs: 60000
guestTypeCommand: '' # script for typing non-ASCII text into a Linux guest
viewAutoOpen: false # open the "VM screen" tab by itself when the agent touches a console
viewFollowAgent: true # the panel follows the VM the agent works with
viewFps: 2 # frame pace in the panel, 1–4
viewScale: 2 # frame resolution divisor: 1 native, 2 half, 4 quarter

首次运行检查清单
1. allowVmids 默认为空——在你列出 VM id 之前，什么都不允许。这是插件唯一的门槛。
2. ssh <alias> 'qm status <vmid>' 应该能在宿主机上直接跑通，不弹密码提示。
3. ssh <alias> sshd -T | grep -i acceptenv 的输出必须包含 LC_（见「环境要求」）。
4. 调用 vm_status——它会报告 VM 是否被允许、guest agent 是否有响应、检测到的是哪个 guest OS，以及控制台会话是否已打开。

工具

控制台（VNC）

| 工具 | 参数 | 作用 |
| console_shot | vmid、region?、scale?、drawCursor?、wake? | 截一帧，以内联图片返回。scale 取 1 / 0.5 / 0.25，region 用 VM 像素坐标。画面几乎纯色时会标记为 blank（屏幕已黑屏或已锁定）。 |
| console_move | vmid、x、y、observe?、wake?、settleMs?、scale?、region? | 移动指针。 |
| console_click | vmid、x、y、button?、count?、observe?、… | 点击（count 为 2 即双击）；默认返回一帧画面。 |
| console_drag | vmid、fromX、fromY、toX、toY、button?、… | 拖拽——移动窗口、框选区域。 |
| console_scroll | vmid、x、y、delta、… | 滚轮：正值向上滚，负值向下滚。 |
| console_type | vmid、text、… | 只支持可打印 ASCII，\n 按下 Enter。大写字母走 Caps Lock，所以每个字符大约要 0.1 s。 |
| console_key | vmid、combo、… | enter、esc、tab、ctrl+alt+del、win+r、alt+f4、ctrl+shift+esc、f5，以及只按修饰键的组合，比如 alt+shift（切换输入法布局）。 |
| console_paste | vmid、text、submit?、… | 把任意 Unicode 文本放进 guest 剪贴板，再按 Ctrl+V。需要启用剪贴板的 VGA 设备和 SPICE agent。 |
| console_batch | vmid、actions[]、observe?、… | 一串动作（move、click、drag、scroll、type、key、wait），最后返回一帧画面。 |
| console_clipboard | vmid、timeoutMs? | 读取 guest 的文本剪贴板（扩展 VNC 剪贴板）。返回空表示「没有文本」。 |
| console_release | vmid | 关闭控制台会话（紧急刹车：释放 ssh 子进程和 QEMU 连接）。 |

每个动作类工具都接受一组通用尾部参数：observe（动作完成后返回一帧画面，默认 true）、wake（Shift + 指针抖动，唤醒黑屏的显示器）、settleMs、scale、region。

Guest agent

| 工具 | 参数 | 作用 |
| vm_exec | vmid、command \| argv、shell?、timeoutMs? | 在 guest 里执行命令（Windows 上是 cmd/PowerShell，Linux 上是 shell）。以 root/SYSTEM 身份运行，看不到用户的图形会话。 |
| vm_file_read | vmid、path、maxBytes?、encoding? | 通过 agent 读取文件（文本，二进制则返回 base64）。 |
| vm_file_write | vmid、path、data \| dataBase64 | 写入文件（每次调用最大 1 MB）；父目录会自动创建。 |
| vm_type_text | vmid、text、settleMs?、observe? | 通过最合适的通道输入文本：ASCII 走控制台，非 ASCII 在 Windows 上走用户会话，在 Linux 上走 xdotool–wtype。 |
| vm_status | vmid? | 虚拟机是否被允许、智能体是否响应、是什么操作系统、有没有打开的控制台会话。 |

实时观看虚拟机屏幕

右侧边栏的 VM screen 标签页显示智能体工作时看到的内容。你可以从边栏指南里添加它，也可以让 viewAutoOpen 在智能体一碰到控制台时就自动展开。

画面取自智能体自己的 RFB 会话——不会冒出第二个 VNC 会话，qm vncproxy 的密码也不会在智能体脚下被重置。抓帧和智能体的工具共用同一个会话队列，所以彼此不会打断对方的流。
* viewFollowAgent 让面板跟随智能体正在操作的虚拟机；点击某个虚拟机标签则把面板固定到那台虚拟机上。viewFps（1–4）和 viewScale（1 / 2 / 4）控制刷新节奏和分辨率，两者都能在面板里随时改。
* 面板是只读观看：不能点击、不能输入，不会向 guest 注入任何东西。画面全黑时会明确提示——guest 关闭了显示，或者已锁定。
* 画面由插件自己的路由提供（/pve-vm/console/frame、/state、/release），跑在 harness web 服务器上，外面有一道仅限回环的围栏：只有当 Host 是回环地址（localhost、127.0.0.0/8、[::1]）、存在的 Origin 与 Host 匹配、且 sec-fetch-site: cross-site 被拒绝时，请求才会得到响应。如果你把 harness 绑定到局域网，面板会按设计保持黑屏——这和 harness 对 /api 施加的是同一道围栏。
* 这道围栏是回环，不是 harness token。 这些路由在 /api 之外，所以 harness 的 URL token 管不到它们（browser-skill 概览也是同样的做法）。因此同一台机器上的任何进程都能拉取画面或调用 /release；在单用户机器上，这就是不带 token 加载画面所要付出的代价。请只提供你不介意本机用户看到的虚拟机；如果这不可接受，就用 harness 签发的 token 加固。
* 面板推流期间，控制台会话保持打开（空闲回收器不会收走它）；面板上的「disconnect console」按钮会立刻关掉它。标签页隐藏时，推流会自动暂停。

工作原理

* 传输。 虚拟机没有 TCP VNC 端口：QEMU 监听 unix socket /var/run/qemu-server/<vmid>.vnc，qm vncproxy 把它桥接到自己的 stdin/stdout。因此插件是通过一个 ssh 子进程来说 RFB 的——没有端口、没有 TLS、没有 websocket，VNC 密码也永远不会出现在 argv 里。qm vncproxy 把 stdin 上的 EOF 当作「退出」，所以插件让这个管道一直开着（桥接器也会在 15 分钟后断开空闲会话；插件则在 sessionIdleMs 之后关闭自己的会话，默认 5 分钟）。
* 输入通道。 inputChannel: auto（默认）会混用两种通道：大写字母走 QEMU monitor，其余按键走 RFB keysyms。hmp 把所有按键都通过 qm monitor sendkey 发送（更快，但 QEMU 偶尔会丢失低于 ~80 ms 的修饰键），vnc 只用 RFB（大写不可靠——QEMU 自己模拟 Shift，而我们发出的 Shift 事件会让它失步）。
* Unicode。 Windows：插件把一个 payload 文件和一个 PowerShell 输入器丢进 guest，并注册一个带 -LogonType Interactive 的计划任务，于是文本是在用户会话内部通过 SendKeys 输入的——布局和修饰键都不再重要，VM 也不会重启。Linux：在活动会话里用 xdotool type（X11）或 wtype（Wayland）；两条路径都在一次调用中经由 guest agent 执行。
* 剪贴板。 写入用 ClientCutText，读取用扩展剪贴板伪编码（VNC_ENCODING_CLIPBOARD_EXT）配合 CAPS/REQUEST/PROVIDE。QEMU 通过 qemu-vdagent 把字节传给 guest，所以 VM 需要 vga: <type>,clipboard=vnc 并且完整停止再启动（设备参数在启动时就固定了），guest 里还需要 SPICE agent。
* 帧。 RFB Raw/CopyRect 矩形会合成到 RGBA（QEMU 把 alpha 留为零），可选裁剪和缩小，然后用 node:zlib 编码成 PNG。

故障排查

| 现象 | 原因与修复 |
| 刚连接就出现 CONSOLE_FAILED，节点没报告任何有用信息 | 节点的 sshd 不接受 LC_，所以 qm 从未收到 VNC 密码。在 sshd_config 里加上 AcceptEnv LC_ 并重载 sshd。 |
| Host key verification failed | 节点的密钥不在 known_hosts 里，而插件以批处理模式运行。先跑一次 ssh <node>，或设置 sshExtraOptions: ["StrictHostKeyChecking=accept-new"]。 |
| 返回的帧几乎是一片纯色（blank: true） | guest 关闭了显示或处于锁屏。工具已经会发送 Shift + 指针抖动来唤醒它；锁屏的会话需要密码（console_type + console_key）。 |
| unable to connect to VM qmp socket — timeout after 51 retries | 别的东西占着 VM 唯一的 QMP socket（一个卡住的 qm monitor/QMP 客户端）。在节点上找到并杀掉那个客户端；不要重启 VM。 |
| 大写字母变成乱码 | 你用的是 inputChannel: vnc，QEMU 自己的 Shift 模拟和我们发出的 Shift 事件在打架。改用 auto。 |
| 登录界面上完全打不出拉丁字符 | guest 的布局不是拉丁布局：用 console_key 按 alt+shift，然后再输入。 |
| vm_ 工具报告 agent 没在运行 | qemu-guest-agent 缺失或卡死（Windows 上 Restart-Service qemu-ga，Linux 上 systemctl restart qemu-guest-agent）。控制台工具仍然可用。 |
| 控制台空闲约 15 分钟后断掉 | 那是 qm vncproxy 桥接的超时。任何工具调用都会自动重开会话。 |

安全

这个插件给了智能体在你 VM 内部的 root 级操作能力。请慎重对待：所有操作执行时都不会弹出审批提示词。 唯一的关卡是 allowVmids，默认是空的；只列出你愿意让智能体碰的虚拟机，列表越短越好。
* vm_exec 在客户机里以 root/SYSTEM 身份运行，vm_file_write 能写到智能体有权写的任何位置，控制台工具还能操作已登录的桌面。把允许的虚拟机当成一台已被攻陷的主机：插件启用期间，别在里面存放长期有效的密钥。
* 需要对节点有 root SSH 权限（qm 要求如此）。用一把专用密钥，把它限制在你需要的节点上，尽量在 authorized_keys 里加上 from=/command= 限制。插件会把整个宿主环境传给 ssh 子进程，任何 ssh 调用都是这样。
* sshExtraOptions 接受任意 -o 选项，包括 ProxyCommand —— 这是给配置插件的人留的特权后门，不是给模型用的。
* VNC 密码按会话生成（8 个可打印 ASCII 字符），通过 SendEnv 经环境变量交给 qm，所以不会出现在 ps 里。QEMU 密码限定在该虚拟机范围内，随会话过期。
* 插件只与你的节点通信。 没有遥测，自身不发起任何对外连接。

限制

* 仅支持 Proxmox VE，仅支持 QEMU 虚拟机 —— 不支持 LXC 容器，不支持其他虚拟化平台。
* 剪贴板工具要求虚拟机的 VGA 设备上设置 clipboard=vnc，且客户机里装有 SPICE 代理；它们只搬文本（不含文件、不含图片），而且只在已登录的会话内有效。
* Windows 下输入 Unicode 需要交互式会话；在登录界面只能通过 console_type 输入 ASCII。
* 每个虚拟机 id 只允许一个控制台会话，用互斥锁串行化；会话空闲时关闭。
* 控制台工具不支持串口控制台（vga: serialN）—— 没有帧缓冲。
* 尚未验证：Proxmox VE 7 和 9、多节点集群、只有 Wayland 桌面的 Linux 客户机。

开发

npm run check # node --check on every runtime file (no harness needed)
node tools/check-client.mjs # browser bundle format (classic script, exports, inject)
node tools/check-plugin.mjs # settings schema, tool set, JSON schemas, layout contract

check-plugin.mjs 会导入插件，而插件会导入 harness 包（@deepseek-ai/dsh-tools、@deepseek-ai/schemastery），所以要在这些包能解析到的地方运行它 —— 最省事的办法是用 link: 把检出目录装进某个配置档，然后在那里运行脚本：

dsh plugin --profile web add link:/path/to/dsh-pve-vm
cd /path/to/dsh-pve-vm && node tools/check-plugin.mjs

如果是裸检出目录，把 DSH_PACKAGES 指向 harness 包目录（…/@deepseek-ai/dsh/node_modules/@deepseek-ai）—— 脚本会把它作为所需编译器的回退路径。

实时探测只需要节点访问权限（不需要 harness）：

node tools/probe-rfb.mjs --vmid 100 --ssh-config ~/.ssh/config --out /tmp/shot.png
node tools/probe-rfb.mjs --vmid 100 --click 640,400 --after /tmp/after.png
node tools/live-test.mjs --vmid 100 --ssh-config ~/.ssh/config --out probe-out
node tools/clipboard-test.mjs --vmid 100 --text "hello" --out /tmp/clipboard.png

这些工具和插件一样，都是通过 ssh 执行 qm vncproxy 来跟节点通信，所以想分清是插件的问题还是节点侧的问题，用它们最快。

许可证

MIT —— 见 LICENSE。

Proxmox® 是 Proxmox Server Solutions GmbH 的注册商标。本项目是独立插件，与 Proxmox Server Solutions GmbH 及 DeepSeek Harness 项目无隶属关系，也未获得其认可。