dsh-vimina

把 Vimina 的 Windows GUI 自动化能力注册为 DSH 原生工具， 模型可直接调用扫描/点击/输入/按键/脚本/截图/窗口/鼠标/VMA 引擎控制等能力，无需视觉模型。 （Vimina 为独立项目：基于 .NET 8 的 Windows GUI 自动化服务，提供 Vimina.exe serve stdio 入口。）

工作原理

插件通过 stdio 驱动 Vimina 的常驻服务（Vimina.exe serve，行分隔 JSON-RPC： 一行 {"id",method,params} 请求 → 一行 {"id",ok,result,error} 响应）， 把每个方法映射成 ctx.tools 上的一个工具。

工具清单（26 个，模型可见）

窗口 / 扫描

工具	底层方法	说明
vimina_getWindows	getWindows	列出窗口
vimina_scan	scan	扫描前台窗口控件
vimina_scanByTitle	scanByTitle	按标题扫描控件（并持久化标签）
vimina_getElement	getElement	按名称查控件
vimina_getControlAt	getControlAt	查坐标处控件
vimina_activate	activate	激活窗口

点击 / 鼠标

工具	底层方法	说明
vimina_clickLabel	clickLabel	按标签点击
vimina_clickAt	clickAt	坐标/后台点击（浏览器网页必须用真实点击，缺省 backend 即可）
vimina_scroll	runVma(scroll)	滚轮滚动（delta 正上负下）
vimina_getMousePos	getMousePos	获取鼠标位置
vimina_moveMouse	moveMouse	移动鼠标
vimina_drag	drag	拖拽
vimina_mouseDown	mouseDown	按下鼠标键
vimina_mouseUp	mouseUp	释放鼠标键

键盘

工具	底层方法	说明
vimina_input	input	输入文本
vimina_key	key	组合键（Ctrl+A 等）
vimina_keyDown	keyDown	按住键
vimina_keyUp	keyUp	释放键

脚本 / 引擎

工具	底层方法	说明
vimina_runVma	runVma	执行 VMA 脚本（返回变量与日志）
vimina_vmaStatus	vmaStatus	引擎状态
vimina_vmaStop	vmaStop	停止脚本
vimina_vmaPause	vmaPause	暂停脚本
vimina_vmaResume	vmaResume	恢复脚本
vimina_vmaLog	vmaLog	脚本日志

其它

工具	底层方法	说明
vimina_info	info	能力自描述
vimina_screenshot	screenshot	截图并返回路径（默认全屏；可传 x/y/w/h 只截区域，识图更快更省 token）

安装与挂载

作为 DSH profile 依赖安装（推荐，注册即用，见下），或：

1. 安装依赖：npm install（或先 npm run build 生成 lib/）。
2. 用 patch 挂载：

dsh web --patch path/to/dsh-vimina/cordis.yml

通常无需手动配置路径：插件按以下优先级自动解析 Vimina.exe（详见"配置"）。

作为 DSH profile 插件安装（推荐）

1. 在你的 DSH profile 目录（如 $DSH_HOME/profiles/web）执行：

   dsh plugin --profile web add <包名或本地路径>
   

   （或直接往 package.json 的 dependencies 加 "dsh-vimina": "<包名或路径>" 后 pnpm install，并把 dsh-vimina 加入 dsh.profile.bundles。）
2. 插件声明了 dsh.bundle.patch，加载器会自动插入 vimina 条目。
3. 重启 DSH web，设置 → 插件 → vimina 可看到 26 个工具与配置项。

配置

字段	默认	说明
exePath	自动解析	Vimina 可执行文件路径
timeoutMs	60000	单次工具调用超时

exePath 解析优先级：

1. 显式配置：DSH web 设置 → 插件 → vimina（推荐），或 profile 的 cordis.patch.yml、--patch 补丁
2. 环境变量 VIMINA_EXE
3. 自动探测常见安装位置（%LOCALAPPDATA%\Programs\Vimina\Vimina.exe、%ProgramFiles%\Vimina\Vimina.exe、%ProgramFiles(x86)%\Vimina\Vimina.exe、当前目录）
4. 回退：PATH 上的 Vimina.exe

只要 Vimina.exe 在以上任一位置，就无需手动填写路径；启动失败时工具会返回明确的配置指引。

区域截图

vimina_screenshot 默认全屏；传 x / y / w / h 只截指定区域（坐标相对屏幕左上角）：

参数	类型	说明
filename	string	可选，保存文件名（默认自动生成）
x / y	integer	区域左上角坐标（可选）
w / h	integer	区域宽度 / 高度（可选）

• 未传 x/y/w/h 时行为不变（全屏，完全兼容旧用法）。
• 区域越界时自动夹取到屏幕边界内（右/下超出部分被裁掉）。
• 返回结果含实际捕获信息（x / y / width / height），便于核对落盘文件尺寸。
• 用途：只需识别局部（如视频封面、按钮、某块区域文字）时直接截取目标区域， 图像越小视觉识别越快、消耗 token 越少。
• VMA 脚本内同样支持：screenshot 文件名 x y w h（语句形式）或 screenshot("文件名", x, y, w, h)（函数形式）。

示例：

vimina_screenshot({ filename: 'cover.png', x: 100, y: 200, w: 400, h: 300 })

开发与测试

cd dsh-vimina
npm install
npx tsc              # 类型检查 + 编译到 lib/

# 单元测试（不依赖真实 Vimina 进程，用 mock 验证协议逻辑）
node --experimental-strip-types test/client-unit.ts

# 插件加载测试（验证工具注册与结构；真实 spawn 需在无沙箱环境）
node --experimental-strip-types test/plugin-test.ts

真实设备测试（需要本机 Vimina.exe）通过环境变量指定可执行文件：

# PowerShell
$env:VIMINA_EXE = 'C:\path\to\Vimina.exe'
node --experimental-strip-types test/e2e-real.ts
node --experimental-strip-types test/full-coverage.ts 5

VIMINA_EXE 未设置时回退为 'Vimina.exe'（按 PATH 查找）； plugin-test.ts 在受限沙箱里会被 EPERM 拦截（判定为 SKIP），在正常 DSH 环境可直接跑通。 请勿在提交的代码/配置里写死本机绝对路径。

AI 使用指南（注入 vimina_info）

插件把完整的使用 playbook 与常见错误规避表打包为 usageGuide 字段，随 vimina_info 工具返回注入给模型（源码见 src/usage.ts）。模型首次使用前应先调用 vimina_info 获取指南。指南要点：

• 先扫描后操作：任何操作前先 vimina_scan，控件带标签（DJ/AK），点击用中心坐标。
• 浏览器必须真实点击：vimina_clickAt 缺省 backend（真实点击）；网页禁用 backend:true。
• 网页内容滚动后才暴露 UIA：先 vimina_scroll / vimina_key(PageDown|End) 再 scan。
• 无需视觉模型：scan/getElement 直接返回文本控件名，不要依赖 OCR/截图读内容。
• 标签临时性：clickLabel 依赖最近一次 scan 的映射，操作前重新扫描。
• 分任务 playbook：浏览网页 / 桌面应用 / 后台点击 / VMA 脚本，详见 info 返回。

浏览器（Chromium）使用注意事项

真实使用中验证过的经验，模型在操作浏览器页面时请遵循：

• 网页内容要滚动后才暴露给 UIA：打开页面后先 vimina_scan 只能看到浏览器框架控件； 滚动（vimina_scroll / vimina_key PageDown / End）后再 scan，才能看到网页控件。
• 点击网页必须用真实点击：vimina_clickAt 缺省（backend=false）就是真实点击并激活窗口， 浏览器场景下不要用 backend:true（FlaUI 后台点击对 Chromium 网页无效）。
• vimina_getControlAt 对网页多返回外层容器：网页内层控件不暴露 UIA 时，坐标命中 的往往是页面容器而非精确控件，以 vimina_scan 为准。

说明

• 插件懒启动 Vimina 子进程，插件卸载时自动关闭（ctx.effect）。
• ViminaClient 已导出并支持注入 spawnFn，便于单元测试。
• 环境变量 VIMINA_API_PORT / VIMINA_API_TOKEN 可在 spawn 时注入。