管理本机 VMware Workstation / Player / Fusion 虚拟机:电源、快照、实时 CPU 与内存、网络配置与 VMX 参数,并可一键把 SSH 接入导入 dsh-ssh-vault。
安装
# npm 包(预构建)
dsh plugin --profile web add dsh-vm-control
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:scientificmaniac/dsh-vm-control
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
dsh-vm-control
简体中文 | English
DeepSeek Harness 的 VMware 虚拟机管理插件:电源、快照、实时占用、网络配置与 VMX 参数,一处管完。
概述
插件调用 VMware 自带的 vmrun(Workstation / Player / Fusion 都带),提供三条互补的通道:
- 模型面向的四个工具 ——
vm_list、vm_power、vm_snapshot、vm_config,智能体可以按虚拟机名或 vmx 路径操作本机虚拟机。 - 设置页 —— 卡片式列出台数、规格、实时 CPU/内存占用、网卡与路径,并提供电源、快照、参数与删除按钮。列表按固定间隔自动刷新,页面隐藏时停止。
- 对话里的
/vm命令 —— 不经过模型直接看状态、开关机、拍快照。 - 与 dsh-ssh-vault 的联动 —— 选中虚拟机后一键把地址、端口、账号与认证方式导入 SSH 保险库;对方未安装时降级为可复制的命令。见联动说明。
它不会改变虚拟机的文件布局,也不做磁盘格式转换:所有动作最终都落成一条 vmrun 命令,或对 VMX 文本的定点改写。
环境要求
| 项目 | 要求 |
|---|---|
| Node | ≥ 20 |
| VMware | Workstation Pro / Workstation / Player / Fusion(自带 vmrun) |
| 平台 | Windows、macOS、Linux |
| 权限 | 运行 DSH 的账号能读写虚拟机目录;GUI 启动需要交互式桌面会话 |
vmrun 的发现顺序:显式配置 vmrunPath → 环境变量 VMRUN_PATH → Windows 注册表(HKLM\SOFTWARE\...\VMware Workstation|Player)→ 常见安装目录 → PATH。找不到时设置页与工具都会说明「装什么、或配哪个字段」,而不是抛一个 ENOENT。
安装
# 作为 DSH 插件安装
dsh plugin --profile desktop install dsh-vm-control
# 或在插件目录里从本地安装
dsh plugin --profile desktop install .
安装后重启 DSH:Host 侧工具与设置路由在启动时加载。
快速开始
- 打开 设置 → VMware 虚拟机。
- 「搜索目录」里加入存放虚拟机的根目录(例如
E:\Virtual Machines)。插件会扫描其中的*.vmx,之后新建的虚拟机自动出现;不在搜索目录里的虚拟机也可以直接「添加虚拟机」指向某个.vmx。 - 卡片上直接开机关机、拍快照、改参数。
- 在对话里说「把 Kali 启动起来,然后看一眼内存占用」,模型调用
vm_power与vm_list。
工具
| 工具 | 作用 | 典型说法 |
|---|---|---|
vm_list |
列出虚拟机:状态、规格、实时占用、网卡、路径;vm= 给单台详情 |
「现在有哪些虚拟机在跑」 |
vm_power |
start / stop / suspend / pause / unpause / reset / status |
「把 CentOS 7 关掉」 |
vm_snapshot |
list / create / revert / delete |
「给 Ubuntu 拍一个升级前的快照」 |
vm_config |
list / show / set / networks / ssh / register / unregister / delete |
「把 Kali 的 CPU 调到 4 核」 |
约定:
- 先看状态再动手。
vm_power会先判定当前状态:对已关机的虚拟机执行stop、对运行中的执行start都会被拒绝并说明原因,而不是让 vmrun 抛一句The virtual machine is not powered on。 - 动作之后确认。
vmrun start成功返回只代表命令被接受;工具会等状态真的变化(最多到各自的超时)再报告结果。等不到时会明说「已发出但未能确认」,不会把不确定说成成功。 - 软/硬两种力度。
stop/suspend/reset默认soft(请客户机自行处理,需要 VMware Tools),hard相当于拔电源。 - 加密虚拟机用
credential_ref指向 DSH 凭据,插件只存引用;口令仅在 VMware 明确报「这台虚拟机是加密的」时才向凭据服务索取。 - 删除分三种。
keep_files(只移除记录)、默认(把目录移到插件回收站)、purge(vmrun deleteVM,连磁盘一起删,需要显式confirm与permissions.delete)。
/vm 命令
/vm 列出全部虚拟机
/vm Kali Linux status 单台详情(含快照)
/vm Kali Linux start 开机(另有 stop / suspend / pause / resume / reset)
/vm Kali Linux snapshots 列出快照
/vm Kali Linux snap before-upgrade 新建快照
/vm Kali Linux delete confirm 移到回收站(需要 permissions.delete)
命令名用 vm 而不是 vmware,是为了在输入框里少打字;参数里中英文标点都认。
与 dsh-ssh-vault 的联动
虚拟机装好 sshd 之后,最顺手的下一步是把它加进 SSH 保险库(dsh-ssh-vault)。插件把这一步做成「选中虚拟机 → 点导入 → 确认」。
触发入口
| 入口 | 行为 |
|---|---|
| 设置页 · 虚拟机卡片 ·「SSH 导入」 | 打开导入面板:探测保险库、准备建议值、确认后写入 |
vm_config action=ssh vm=<名字> |
只给建议(别名 / 地址 / 账号 / 认证 / 等价命令)与入口说明 |
工具刻意不能直接写保险库:密文由 dsh-ssh-vault 用自己的密钥加密,其它插件没有正当途径写那个文件。模型能做的是把数据准备好、告诉你点哪里;写入由你在设置页确认。
导入的字段范围
| 字段 | 来源 |
|---|---|
alias |
虚拟机名规范化(非 ASCII 折成分隔符);同批虚拟机重名时自动加 -2 |
host |
VMware Tools 报告的客户机 IP;取不到就留空由你填 |
port |
默认 22,可在面板里改 |
username |
Linux / BSD 客户机建议 root,其它留空 |
authType / privateKeyPath / password / passphrase |
存在默认私钥(~/.ssh/id_ed25519 → id_ecdsa → id_rsa)就用私钥认证,否则选口令认证,由你输入 |
description / tags |
<虚拟机名> · VMware,标签为 vmware + 虚拟机自身的标签 |
不导入的字段:sudoPassword、bindAddress、私钥文件上传、别名改名。这些要么与虚拟机无关,要么需要你在保险库页面里自己决定——字段范围固定在一个白名单里,多传一个字段就等于替用户做了他没同意的决定。
成功与失败
- 成功:
已导入到 SSH 保险库:<别名>,并提示之后可以用ssh_run的别名执行命令。同名主机存在时是更新,提示会写明「已更新」。 - 失败:原样显示 dsh-ssh-vault 的报错(别名字符非法、缺口令、私钥不可读……),判定权在对方;本地只做格式预检,省一次往返。
- 面板提前警告「保险库里已有同名主机,保存会覆盖」,并给一个「换一个别名」按钮。
未安装 / 不可用时
面板打开时先 POST ssh-vault/list 探测(2.5 秒超时):
| 探测结果 | 表现 |
|---|---|
| 路由不存在(404,或返回 HTML fallback) | 「未检测到 dsh-ssh-vault」+ 安装命令 + 仍然可复制 SSH 命令,手工加进任何 SSH 客户端 |
| 401 / 403 | 提示宿主拒绝了这次请求,刷新后重试 |
| 其它错误 | 显示具体原因;编辑与复制不受影响 |
也就是说,联动缺席时没有任何功能被锁死:电源、快照、参数、删除照常,导入退化成「帮你把命令拼好」。
权限:导入受 permissions.config 影响——为 false 时面板里的导入按钮禁用并说明原因(写另一个插件的配置属于 config 级操作)。探测与复制不受影响。
安全:口令只出现在提交给 dsh-ssh-vault 的那一次请求里,本插件不落盘、不写日志、也不回读保险库;不会把虚拟机的加密口令当作 SSH 口令复用。
权限模型
四个开关都在 Loader 配置的 permissions 下,默认只关掉最危险的一个:
| 作用域 | 默认 | 覆盖的能力 |
|---|---|---|
power |
true |
启动、关机、挂起、暂停、恢复、重置 |
snapshot |
true |
创建 / 回滚 / 删除快照(列快照始终允许) |
config |
true |
改写 VMX、登记 / 取消登记 |
delete |
false |
仅 purge(连磁盘删除);「只移除记录」与「移到回收站」不受此限制 |
被关掉的能力在工具层与设置接口层各拒绝一次:只拦一层的话,另一条通道就成了绕过它的后门。拒绝消息会明确指出这是插件配置,而不是 VMware 的拒绝。
- id: vm-control
name: 'dsh-vm-control'
config:
permissions:
delete: false # 需要彻底删除时改成 true 并重启 DSH
配置项
| 字段 | 默认 | 说明 |
|---|---|---|
dataDir |
%DSH_HOME%/vm-control |
插件数据(vms.json、日志、回收站) |
searchRoots |
平台默认的 VMware 目录 | 首次运行时写入的搜索目录,之后以设置页为准 |
scanDepth |
3 |
扫描深度;更深的虚拟机需要直接添加或提高此值 |
vmrunPath |
自动发现 | vmrun 绝对路径 |
vmType |
auto |
ws / player / fusion / auto;auto 会逐个尝试 |
vmrunTimeoutMs |
90000 |
单次 vmrun 调用的默认超时 |
timeoutMs |
按动作 | 等待状态变化的默认上限 |
permissions |
见上表 | 四个作用域开关 |
collectMetrics |
true |
是否采集宿主侧 CPU/内存占用 |
logging |
false |
true 或 { enabled, dir, maxBytes };关闭时不写任何日志 |
状态与资源是怎么判断的
这部分值得说清楚,因为它决定了界面上的数字能不能信:
- 运行态以
vmrun list为准。它把暂停中的虚拟机也算「运行中」,所以「暂停」这一状态由插件自己记住(pause之后写入记录)——通过 VMware 窗口暂停的虚拟机会显示为运行中,这是已知且无法从命令行消除的差别。 - 残留的
.vmx.lck目录不可信。 VMware 崩溃或强制断电后不会清理它;早期实现按锁目录判断,结果把七台关机状态的虚拟机全部显示成「运行中」。现在只有在vmrun list读取失败时才退回文件启发式。 - 挂起看
.vmss镜像文件:挂起本质上是关机 + 内存镜像,vmrun list不会包含它。 - 资源占用来自宿主进程:每台运行中的虚拟机对应一个
vmware-vmx进程,命令行里带着它服务的 vmx 路径,于是「进程 → 虚拟机」的映射是确定的。Windows 用 PowerShell 一次取回 CPU%、工作集、私有字节、线程数与 IO;macOS / Linux 退回ps,只有 CPU 与 RSS(那些平台上没有等价物,缺的字段留空而不是编一个值)。 - 网络信息读自 VMX:连接方式(nat / bridged / hostonly / custom)、虚拟网络名(17.x 在
vnet,老版本在networkName)、虚拟设备型号、MAC。客户机内部 IP 需要 VMware Tools,只在点「客户机信息」时按需查询。 - 采集失败不会让列表消失:占用读不到时那一栏留空并给出原因,虚拟机本身照常可管。
错误处理
vmrun 的报错是英文散文,同一句 Cannot open VM 既可能是路径错、也可能是被锁。插件把失败归成固定类别,并在结果里给出「该往哪里修」:
| 类别 | 含义 |
|---|---|
vm-missing |
vmx 不存在、被移动,或所在磁盘没挂载 |
vm-state |
当前状态不允许这个动作 |
busy |
文件被占用:另一个 VMware 窗口持有它,或上一次切换还没结束 |
tools |
VMware Tools 未安装 / 未运行,客户机相关的操作不可用 |
permission |
宿主拒绝了文件或进程操作 |
encrypted |
虚拟机加密,需要 -vp 口令(配置 credential_ref) |
bad-host-type |
-T 类型不对(Workstation 用 ws,Player 用 player,Fusion 用 fusion) |
vmrun-missing |
找不到 vmrun |
timeout |
命令在时限内没有返回;先确认状态再决定是否重试 |
设置页的「错误日志」默认关闭;开启后工具与接口的失败会带堆栈写入 dataDir/logs/diagnostics.log,形如 -vp <口令> 的内容在落盘前被抹成 ***。
版本兼容与可扩展性
- 能力探测而非版本号比较。 插件直接跑一次不带参数的
vmrun,从它的用法输出里读出命令表,于是「这个版本支不支持deleteVM/clone/listHostNetworks」有确定答案;界面会据此禁用不支持的按钮,工具会解释是哪一版缺了什么。 - 主机类型自动协商。
vmType: auto时依次用ws/player/fusion试一次list,第一个成功的胜出;之后所有调用沿用该类型。 - 加一条新动作:在
lib/vmrun.js里加一个方法(参数拼装 + 超时),在lib/inventory.js里加语义检查(状态、权限边界),在index.js/lib/vm-api.js里暴露出去,最后在lib/format.js里给它一句人话。分层是刻意的:新增动作不需要碰 UI 的其它部分。 - 加一个新工具:
index.js里ctx.effect(() => ctx.tools.register(registerTool({...})))即可;客户端只要在tool.call.toolview的键列表里加上工具名,就会自动获得同一套卡片。
已知限制
- 通过 VMware 界面暂停的虚拟机,插件显示为「运行中」(没有可查的命令行状态位)。
- macOS / Linux 上只有 CPU 与 RSS,没有 IO 细分与线程数。
- 改写 VMX 只能在关机状态下进行(VMware 自己也写同一个文件);挂起状态允许但会提示挂起镜像可能与新硬件不匹配。
purge删除不可恢复;回收站只是「目录搬走」,不写入系统回收站。- 加密虚拟机的口令只能通过命令行
-vp传给 vmrun(VMware 没有别的通道),因此那个进程存活期间本机进程列表里能看到它。插件只在 VMware 明确要求时才这么做。 - 只管理本机 VMware 产品;ESXi / vCenter 的
-T viserver形态不在范围内。
安全
- 设置接口挂在
/vm-control/前缀下,经宿主connection.requestRejection做 Host/Origin 校验与浏览器认证;与内置/api使用同一套判定。 - 除
register外,所有动作都先把 id 解析成库存里真实存在的虚拟机,从不使用请求体里的路径去读写文件或启动进程;register要求绝对路径、.vmx后缀且文件确实存在。 - 打开目录只打开插件自己算出来的路径(虚拟机目录、回收站、日志目录),不接受调用方指定。
插件结构
| 文件 | 职责 |
|---|---|
index.js |
插件入口:四个工具、权限闸门、/vm 命令、设置路由与语言同步 |
client.js |
浏览器半边:设置页、工具卡片、/vm 命令视图、dock 兜底面板 |
lib/vmrun.js |
vmrun 发现、主机类型协商、能力探测、命令封装与失败归类 |
lib/vmx.js |
VMX 文本解析与定点改写(改写前留 .bak) |
lib/inventory.js |
把「磁盘上的 vmx」「vmrun 说谁在运行」「插件记住了什么」合成一张表,并提供带状态检查的动作 |
lib/metrics.js |
宿主进程占用采集(PowerShell / ps)与字节格式化 |
lib/store.js |
vms.json 的读写:原子写、串行化、损坏自愈 |
lib/vm-api.js |
设置接口 /vm-control/*(信任栅栏 + 权限二次判定) |
lib/format.js |
把数据渲染成模型可读的文本 |
lib/i18n.js、lib/locales/vm.js |
中英文案与运行时切换 |
lib/diagnostics.js |
可开关的错误日志(落盘前抹除 -vp 口令) |
test/*.mjs |
单元、接口、客户端冒烟、只读联调 |
分层的规矩很简单:新增一条动作时,参数拼装进 vmrun.js,语义检查进 inventory.js,出口进 index.js 与 vm-api.js,人话进 format.js。这样加动作不需要改动界面,也不会出现「工具能做、界面不能」的两套逻辑。
已验证环境
| 环境 | 结果 |
|---|---|
| Windows 11 · VMware Workstation 17.6(vmrun 1.17.0)· Node 26 | 7 台真实虚拟机:状态、规格、网卡、磁盘、网络表、进程采集全部通过 |
| dsh-ssh-vault 2.3.0(真实源码,临时保险库) | 口令 / 私钥两种认证的保存、覆盖语义、别名校验、列表脱敏全部通过 |
| 无 VMware 的机器 | 单元 / 接口 / 客户端测试全部通过;列表与工具给出「找不到 vmrun」的引导 |
macOS(Fusion)与 Linux 走同一套代码路径与 ps 采集,但未在真实 Fusion 主机上跑过;如果你遇到了差异,欢迎提 issue 并附上 vmrun 的版本与输出。
发行与打包
插件没有编译步骤(Host 侧是纯 ESM,客户端是手写 React 元素),所以「构建」实际是校验:
npm run check # 版本 / 变更日志 / 发行说明三者一致 + 全部模块语法
npm run release # 检查 → 测试 → 打包 → 校验产物
npm run pack:dist # 跳过测试直接出包(离线出包用)
npm run release 在 dist/ 生成 dsh-vm-control-<版本>.tgz 与 SHA256SUMS.txt,并核对包内含 index.js、client.js、lib/**、cordis.patch.yml、dsh-market-entry.yml、README*、LICENSE,同时确保 test/、node_modules、.github 没有被带进去。
发一次版
改
package.json的版本,在两份CHANGELOG里加同版本小节,写RELEASE_NOTES/v<版本>.md;npm run release—— 三者不一致会立刻失败,不必等 CI 告诉你;提交、打标签、推送:
git commit -am "chore(release): v1.1.0" git tag -a v1.1.0 -m "dsh-vm-control 1.1.0" git push origin main && git push origin v1.1.0推标签会触发
.github/workflows/release.yml:重新跑测试与打包(不复用旧产物),把.tgz与SHA256SUMS.txt附到 GitHub Release,正文取自RELEASE_NOTES/v<版本>.md。
SHA256SUMS.txt 对应的是 Actions 打出的那一个包。本地重新 npm run release 得到的字节数会略有不同(npm 会把文件时间写进 tar 头),所以校验和要以发行附件里的那份为准;包的内容(文件清单与各文件内容)由第 5 步逐条核对,与本地一致。
标签与 package.json 版本不一致时,发行工作流会直接失败——打错标签的发行版比不发更糟。
测试
npm test # 单元 + 接口 + 客户端冒烟,不需要 VMware
node test/live.mjs # 只读联调:真的去问本机的 VMware
node test/live.mjs "E:\Virtual Machines" # 指定搜索目录
联调测试不会开关机、拍快照或删除任何东西;它验证版探测、真实 vmrun list、真实 VMX 解析、网络表与进程占用采集。四个测试文件的分工是:
test/unit.mjs—— 解析、归类、存储、库存语义、权限与 SSH 导入的建议值(把 vmrun 换成假对象);test/api.mjs—— 设置接口的信封、信任栅栏、权限二次判定与路径来源;test/client-smoke.mjs—— 在node:vm里跑client.js的工厂,检查注册接线与中英文案双向一致;test/ssh-vault-link.mjs—— 加载 dsh-ssh-vault 的真实源码,把我们的 payload 提交给它的保存接口,验证字段名、别名校验、覆盖语义与口令不外泄;test/live.mjs—— 对着真实 VMware 的只读联调。
ssh-vault-link 需要把 dsh-ssh-vault 克隆在本仓库旁边;找不到就打印一行 skip 并退出 0,因此 CI 里不会因为它缺席而失败。
许可
MIT
链接
同类插件
zhu1090093659/dsh-web#packages/dsh-remote-web-ui★ 10458
手机/PC 远程操控 dsh web 工作区:扫码配对、令牌门控通道、SSE 实时同步,提供移动端与完整桌面 GUI 两种远程形态。
zhu1090093659/dsh-web#packages/dsh-ssh★ 10458
SSH 远程运维面板:Web 终端、SFTP 传输、本地端口转发与一条命令并发集群执行,Agent 与面板共用同一份主机配置。
liguobao/ds-harness-remote★ 3072
通过端到端加密通道远程访问 DeepSeek Harness 及兼容的编码工作区,支持自适应 Relay/WebRTC 传输、设备授权、工作区文件、只读预览、终端和可选的 Codex Remote。
saya-ch/dsh-mobile★ 868
通过 Android App 或手机浏览器访问 DeepSeek Harness,支持安全局域网连接、远程访问、持久设备配对和可自定义移动界面。
uumit-ai/dsh-uumit-remote★ 523
用 UUMit 账号在手机或其他电脑上打开这台电脑的 dsh web,不用自建服务器、不装其他程序:插件内置通道客户端连接 UUMit 托管的通道,侧栏里的面板负责配对和选择谁能用(仅自己、通过邀请链接或手机号授权的人、所有人),可随时撤销。需 dsh web 且 DSH >=0.2.1-rc.2。
ZSeven-W/dsh-ios★ 468
在对话里直接操作 iOS 模拟器或 USB 连接的 iPhone:22 个 Agent 工具用于启动、构建、按无障碍标识或 OCR 文本驱动 UI、列表行操作与 SwiftUI 预览热重载,并附带可点击拖拽的流式侧边栏面板。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。