DeepSeek Harness 插件：用文字驱动 Windows

前言¶

用大模型做 GUI 自动化时，最常见的问题是「看不懂」。模型看缩略图估坐标，偏差几十像素，按钮就点空了。这个插件把「屏幕上的文字」变成可点击、可拖拽、可输入的目标，并且每次操作都告诉你有没有生效。

插件定位¶

这是一个 DeepSeek Harness（DSH）工作流插件，维护者是 zdd3143。它不需要任何视觉大模型 API，直接用 Windows 自带的 OCR 定位界面文字，再由 Agent 进行真实的鼠标和键盘操作。定位准确到 0 误差，动作后自动比对像素与文字变化，有 F6+F7 独立进程急停。

核心能力¶

文字定位¶

gui_look 截图 + Windows OCR，识别活动窗口每一行文字，给出 0~1 归一化的中心坐标。定位按四级退让：整窗 → 横向条带 → 全屏 → 瓦片。同一行里还会尝试词级片段，避免相邻按钮被合并成一行后点错。

鼠标操作¶

gui_click 支持左/右/中键、单击/双击、长按、悬停。按目标文字或坐标定位，点击落在文字中心。gui_drag 支持按住拖动，从 from 到 to 各写目标文字或坐标，适合拖文件、滑块、框选、窗口。gui_scroll 在目标文字或坐标处上下左右滚动 N 格。

键盘操作¶

gui_type 键入文字，支持大小写、数字、中文、符号，pressEnter 输完回车。gui_key 处理组合键与功能键：enter、tab、esc、backspace、delete、方向键、f1-f12、ctrl+a、shift+a 等。

自动复核¶

每次动作后自动做三件事：

局部像素差分：以落点为中心（点击 ±240px、拖放 ±320px、滚动 ±420px）逐像素比较。
全屏差分：有些操作的效果出现在别处，全屏差分兜底。
文字增删：动作前后各做一次 OCR，报告「新出现」「消失」的文字。

结论明确写成「有反应 / 没有可测量的变化」。

批量执行与急停¶

gui_do 可把「点击 → 等待 → 滚轮 → 键入 → 按键」串成最多 10 步，出错即停并报告卡在哪一步。F6+F7 由独立进程看门狗处理，触发时写急停标记、杀输入进程、松开所有键、取消当前回合。看门狗不在时所有工具 fail-closed，拒绝任何输入。

安装与启用¶

作为 DSH 插件，需要一个 profile。

普通安装（推荐）：

# 预构建 tarball
dsh plugin --profile desktop add https://github.com/zdd3143/dsh-vision-click/releases/latest/download/dsh-vision-click.tgz

# 或者从源码安装
dsh plugin --profile desktop add https://github.com/zdd3143/dsh-vision-click

本地开发（改代码即时生效）：

git clone https://github.com/zdd3143/dsh-vision-click.git
dsh plugin --profile desktop add "link:C:/path/to/dsh-vision-click"

安装后 gui_* 工具即可用。

启用控制权限¶

默认 allowControl: false，未经用户授权时所有工具直接报错，不截屏、不动鼠标。启用方式有两种：

在插件设置里勾选 allowControl。
在本会话执行 /vision arm（用户命令，不产生模型消息）。

/vision off 可随时收回，/vision status 查看当前状态，gui_status 也会报告 authorized。

配置项¶

在 cordis.patch.yml 的 config 中可以调整：

字段	默认	说明
`allowControl`	`false`	用户开关；默认不截屏、不输入，需显式授权
`emergencyHotkey`	`'F6+F7'`	急停组合键
`cancelTurnOnStop`	`true`	急停时取消当前回合
`maxWidth`	`1600`	返回给模型的图宽（OCR 始终用原始像素）
`maxCaptureAgeMs`	`20000`	坐标点击的截图有效期
`settleMs`	`260`	动作后到复核截图的等待
`restoreCursor`	`true`	点完把光标放回原处
`ocrScale`	`1`	OCR 放大倍数；只有极小字体才需要调大
`ocrLang`	`''`	OCR 语言（如 `zh-Hans-CN`）；空 = 跟随系统
`minMatchScore`	`0.7`	低于此分不点
`maxActionsPerMinute`	`60`	输入限速
`dragSteps` / `dragStepMs`	`16` / `12`	拖动插值步数与每步间隔
`maxTypeChars`	`2000`	单次 `gui_type` 的字符上限
`diffCellsX` / `diffCellsY`	`24` / `16`	全屏差分的网格
`auditLog`	`true`	是否写审计日志
`powershellPath`	`''`	显式指定 PowerShell
`visionEnabled`	`false`	OCR 没把握时是否调用本地视觉模型
`visionBaseUrl`	`http://127.0.0.1:11434`	Ollama 地址
`visionModel`	`ui-tars:7b`	模型名（`ollama list` 里看到的）
`visionMode`	`fallback`	`fallback` 仅兜底；`always` 总是问模型
`visionTimeoutMs`	`30000`	单次模型调用超时
`visionMaxWidth`	`1280`	送模型前把窗口缩到这个宽度
`visionSnapRadius`	`0.08`	把模型点吸附到 OCR 词框的半径（相对短边）
`visionRetries`	`1`	点了没反应时围绕模型点微调重试的次数
`visionOnDragRetry`	`true`	拖拽没生效时，用模型重新定位两端再拖一次
`visionOnScrollRetry`	`true`	滚动没生效时，用模型重新定位滚动区域再滚一次

典型用法¶

gui_look  { query: "保存" }        → 「保存」在 (0.83, 0.06)
gui_click { target: "保存" }       → 点击 + 复核：新出现「已保存」

左键单击 / 双击：

gui_click {target:"确定"} / {..., count:2}

右键、中键：

gui_click {target:"文件", button:"right"}

长按（按住不放再松开）：

gui_click {target:"…", holdMs:800}

悬停（触发 hover 菜单 / tooltip）：

gui_click {target:"…", hover:true}

按住拖动：

gui_drag {from:{target:"a.txt"}, to:{target:"回收站"}}

滚轮上下 / 左右：

gui_scroll {target:"列表", direction:"down", amount:5}

键入文字（含大小写/中文）：

gui_type {text:"Abc123"}

输入完回车（搜索 / 提交）：

gui_type {text:"关键词", pressEnter:true}

大写字母 / 组合键：

gui_key {keys:"shift+a"} / {keys:"ctrl+shift+s"}

删除 / 退格 / 方向键：

gui_key {keys:"delete"}、{keys:"backspace", count:3}、{keys:"tab"}

等待文字出现 / 消失：

gui_wait {text:"加载完成"} / {text:"弹窗关闭"}

目录结构¶

dsh-vision-click/
├── index.js              # 宿主插件：10 个工具、截图/校验编排、急停联动
├── cordis.patch.yml      # bundle 注册与默认配置
├── scripts/
│   ├── agent.ps1         # 常驻进程：截图、OCR、点击/拖动/滚轮/键入、差分
│   ├── stop-watcher.ps1  # 独立急停看门狗（F6+F7）
│   └── build-ocr.ps1     # 重新编译 native/DshOcr.dll
├── native/
│   ├── DshOcr.cs         # WinRT OCR + 逐像素差分（C#）
│   └── DshOcr.dll        # 已编译产物（10KB）
├── tests/                # 端到端测试 + 可交互测试窗口
└── docs/                 # 架构与测试说明

适用场景与注意¶

适合需要用文字定位界面元素、自动完成重复操作、需要高可靠性的 GUI 自动化场景。插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

生态背景¶

DSH 理念是「一切皆插件」；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。