dsh-vimina — DeepSeek Harness Cordis 插件
把 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）执行： ``bash 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 时注入。