前言¶
DeepSeek Harness（DSH）里不少「计算机使用」类插件，是在智能体所在主机上截屏、注入键鼠，因此宿主机通常要有 X11 或 Wayland、截图与输入工具。若目标是一台跑在 Proxmox VE 节点上的虚拟机——宿主机可以是无头服务器、Wayland 桌面，甚至远在另一台机器——这条路径就不太合适。
下面介绍社区插件 dsh-pve-vm（维护者 taxah92，GitHub：taxah92/dsh-pve-vm）。它通过一条 SSH 连到 PVE 节点，用 qm vncproxy 看虚拟机画面并在控制台里点击，同时用 qm guest exec 经 QEMU Guest Agent 执行命令、读写文件；不依赖在 DSH 宿主机上装桌面栈，也不要求在节点上额外安装运行时依赖（RFB、DES 认证、keysym 与 PNG 编码均实现在插件包内）。
这是什么¶
dsh-pve-vm 属于 DSH 插件目录中的客户端类插件：在 Web UI 提供 Proxmox VE 设置卡片与右侧「VM screen」实时画面面板，并把一组工具挂到 Harness 的 computerUse 等能力上。
数据路径可以概括为：
agent ──► plugin ──► ssh ──► node: qm vncproxy ──► unix socket /var/run/qemu-server/<vmid>.vnc
└────► node: qm guest exec ──► qemu-guest-agent inside the VM
README 写明在 pve-manager 8.4.21、Windows 11 / Windows Server 2025 与 Linux 客户机、DeepSeek Harness 0.2.0-rc.2 上做过验证；当前 npm 包版本为 0.2.4，许可证 MIT。
核心功能¶
控制台（VNC）¶
- 画面：
console_shot返回虚拟机屏幕的内联图片，支持region、scale控制 token 成本；鼠标键盘类工具使用 VM 屏幕坐标。 - 输入：移动、单击、双击、拖拽、滚轮、ASCII 打字、组合键，以及
console_batch串联多步后返回一帧。 - 可靠键入：大写经 Caps Lock（
qm monitor→ HMPsendkey），带 Shift 符号经 RFB keysym 并带 settle 延迟，便于在 Windows 登录界面输入密码。 - Unicode 与剪贴板：Windows 客户机可通过计划任务
SendKeys；Linux 经 guest agent 调用xdotool/wtype。console_paste经 RFB 写入客户机剪贴板并 Ctrl+V；console_clipboard读回文本，避免 OCR。
客户机（QEMU Guest Agent，可选）¶
在未装 agent 时，控制台工具仍可用。安装 qemu-guest-agent 后可用：
vm_exec、vm_file_read、vm_file_write、vm_status等，适合确定性、低开销的任务，GUI 只在必要时再用像素。
Web 侧¶
- 设置卡片支持英文、俄文、中文标签，写入 profile patch 层。
- 「VM screen」侧栏展示与 agent 同一 VNC 会话的帧，可跟随 agent 当前 VM 或手动选定；仅观看，不向 VM 注入点击。
环境与依赖¶
| 条件 | 说明 |
|---|---|
| DeepSeek Harness ≥ 0.2.0-rc.2 | 使用 0.2.x 插件契约（defineTool、ctx.tools、computerUse、configForms 等），不加载于 0.1.x |
| Node.js ≥ 22 | Harness 运行时 |
Proxmox VE 节点与 qm CLI |
需 qm vncproxy、qm guest exec、qm monitor；不支持 LXC 容器 |
以 root（或可执行 qm 的账号）SSH 到节点 |
建议密钥登录（BatchMode，无密码交互） |
节点 sshd_config 中 AcceptEnv LC_* |
VNC 票据经 LC_PVE_TICKET 与 SendEnv 传递，避免出现在 ps；未配置时 ssh 会静默丢弃，控制台无法认证 |
| 主机密钥已信任 | 默认 BatchMode=yes；可手工 ssh <node> 一次，或在 sshExtraOptions 中加 StrictHostKeyChecking=accept-new |
| 客户机内 qemu-guest-agent（可选） | 仅 vm_* 工具需要 |
安装与启用¶
插件以当前 DSH 进程权限运行；安装前请自行查阅 GitHub 仓库 源码与 MIT 许可证。
- 添加 bundle：
dsh plugin --profile web add github:taxah92/dsh-pve-vm
-
确认 profile 中
dsh.profile.bundles包含"dsh-pve-vm"（插件市场开关等价）。 -
重启 Harness：插件 host 半部分每个进程只加载一次。
安装后 patch 层会多一行（不要改 id，pve-vm 即设置命名空间）：
- id: pve-vm
name: dsh-pve-vm
配置¶
在 Web UI：Settings ▸ Plugins ▸ Proxmox VE。也可直接在 profile patch 中编辑，例如：
- id: pve-vm
name: dsh-pve-vm
config:
sshHost: proxmox
sshUser: root
sshPort: 22
sshKeyPath: ''
sshConfigFile: ''
sshExtraOptions: []
allowVmids: [100, 101]
enableConsole: true
enableGuest: true
inputChannel: auto
sendkeyDelayMs: 80
consoleTimeoutMs: 20000
sessionIdleMs: 300000
guestTimeoutMs: 60000
guestTypeCommand: ''
viewAutoOpen: false
viewFollowAgent: true
viewFps: 2
viewScale: 2
首次运行建议：
- 默认
allowVmids为空则不允许任何 VM，这是插件唯一的访问门控；务必显式填入 VMID。 - 在 DSH 宿主机执行
ssh <alias> 'qm status <vmid>'应无密码成功。 ssh <alias> sshd -T | grep -i acceptenv应包含LC_*。- 调用
vm_status：查看 VM 是否被允许、guest agent 是否响应、检测到的客户机 OS、控制台会话是否打开。
典型用法¶
智能体在需要 GUI 时调用 console_shot 取帧，再用 console_click、console_type 或 console_batch 操作；能走 shell 或文件 API 时优先 vm_exec、vm_file_read / vm_file_write。
控制台常用工具摘要（参数以 README 为准）：
| 工具 | 作用 |
|---|---|
console_shot |
截图；scale 1 / 0.5 / 0.25；近乎 uniform 的帧可能标为 blank |
console_click |
点击；count=2 为双击，默认返回一帧 |
console_type |
可打印 ASCII，\n 为 Enter；大写较慢（约 0.1 s/字符） |
console_key |
enter、ctrl+alt+del、win+r 等组合键 |
console_paste |
任意 Unicode 经剪贴板粘贴（需支持剪贴板的 VGA/SPICE 相关能力） |
console_release |
关闭该 VM 的控制台会话 |
适用场景与注意¶
适合： 已在 Proxmox VE 上跑 Windows/Linux GUI 或尚未完全启动的 VM，希望 agent 在远程节点上「看屏 + 点屏」，同时用 guest agent 做命令与文件操作；DSH 宿主机无需与被控桌面同机。
注意：
- 仅 KVM/QEMU VM，不是 LXC。
- SSH 与
allowVmids配置错误会导致完全无法操作或误操作未授权 VM；以vm_status自检。 console_paste/ 剪贴板能力依赖客户机与显示设备配置，与纯 VNC 截图路径不同。- 社区插件目录 SkillHub 条目 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，安装与授权策略需自行评估。
结尾¶
dsh-pve-vm 把 Proxmox VE 上的 VM 控制台与客户机 agent 收成一条 SSH 上的工具链，让 Harness 可以在不绑定本地桌面的前提下驱动虚拟机 GUI，并用 guest 通道补足命令与文件。目录页：https://www.skillhub.cn/plugins/taxah92/dsh-pve-vm；源码与完整工具表：https://github.com/taxah92/dsh-pve-vm。
