视觉安全桌面控制 Kxiaoguai3/dsh-visual-safety-control

dsh-visual-safety-control

DeepSeek Harness 的 Windows 桌面控制插件。给模型一个 desktop 工具：截图、OCR、UIA 定位控件、鼠标键盘输入，并带有内容策略和动作校验。

本仓库基于 qingying012/dsh-desktop-control v0.1.3（MIT）修改。

功能

| 能力 | 说明 |
| 截图 | 全屏、指定窗口或区域截图，可选坐标网格和光标标记 |
| OCR | 本地 Windows OCR，返回文字内容和坐标 |
| 找控件 | 按 OCR 文字或 UIA 控件名定位，可按窗口过滤；多命中时拒绝点击并列出候选 |
| 鼠标 | 坐标点击、UIA 控件点击、移动、拖拽、滚轮 |
| 键盘 | 文本粘贴、组合键；输入前确认窗口在前台、控件可编辑，输入后回读内容 |
| 窗口 | 列出窗口（HWND / PID / 位置 / 标题），激活指定窗口 |
| 序列 | 一次调用执行多个步骤，减少往返 |

内容策略

- 危险标签（支付、转账、删除、卸载等）不点击、不查找
- 敏感窗口（银行、密码、钱包、凭据管理器）不读取、不操作
- 疑似凭据的输入内容拒绝发送
- 危险组合键拒绝执行
- 不可逆动作（发布、发送、提交、购买）默认请求用户确认

动作校验

- 点击前用 expect 校验落点处的文字，防止坐标过期
- 点击后用 verifyText 校验窗口里出现预期结果
- 点击做 hit-test，支持同进程弹窗和 UWP 窗口，避免误判
- 输入后通过 UI Automation 回读，确认文字真的写进去了

安装

本地目录：

plugin_manager({ action: "install_bundle", target: "<本仓库的绝对路径>" })

npm（发布后）：

plugin_manager({ action: "install_bundle", target: "dsh-visual-safety-control" })

GitHub 仓库右侧的 Packages 里还有一份 @kxiaoguai3/dsh-visual-safety-control 镜像（由 GitHub Actions 自动发布到 GitHub Packages）。它只用于 GitHub 侧展示；日常安装请走上面的 npmjs 名称，GitHub Packages 需要额外配置 read:packages 凭据。

不要和 dsh-desktop-control 同时启用：两者都会注册名为 desktop 的工具，重名会导致加载失败。

用法

| action | 作用 | 主要参数 |
| find | OCR 定位文字并返回屏幕坐标，可直接点击 | text / window / click / exact / index / threshold |
| elements | UIA 控件列表（名称 + 中心坐标） | window / filter / depth / all |
| ocr | 对图片做 OCR | imagePath / filter |
| screenshot | 保存截图并返回路径 | window / region / print / grid / cursor / maxWidth |
| windows | 列出窗口 | top |
| click | 点击坐标或 UIA 控件 | x y / uia invoke / window / expect / verifyText / button count |
| move / drag / scroll | 移动、拖拽、滚轮 | x y / x2 y2 / amount |
| type | 粘贴文本 | text / window / verify |
| key | 组合键，例如 ctrl+s | key |
| activate | 把窗口切到前台 | window |
| pos / wait | 读取光标位置 / 等待 | — / waitMs |
| sequence | 一次执行多个步骤 | steps |

坐标都是物理像素。

// 找控件
desktop { action: "find", text: "保存", window: "记事本" }

// 点击前校验文字，点击后校验结果
desktop { action: "click", x: 812, y: 460, window: "记事本", expect: "保存", verifyText: "已保存" }

// 输入并回读
desktop { action: "type", text: "hello", window: "记事本" }

设置

装好插件后，打开 设置 → 视觉安全（设置面板左侧导航里直接有这一项，排在「内置插件」下面），可以直接编辑策略：

- 启用/关闭内容策略
- 危险标签、敏感窗口、不可逆动作标签（每行一个）
- 不可逆动作的处理方式：请求确认 / 直接拒绝 / 允许
- 拒绝的快捷键、序列最大嵌套层数

点保存后写入当前 profile 的插件配置，下一次工具调用立即生效，不需要重启。也可以继续用 cordis.patch.yml 配置，两种方式等价。
首次安装后，如果设置面板里还没看到「视觉安全」，刷新一次 Harness 页面（Ctrl+R）即可加载新的客户端插件。

配置

- id: visual-safety-control
name: dsh-visual-safety-control
config:
policy:
enabled: true
denyLabels: ['支付', '转账', '删除', 'delete', 'pay']
sensitiveWindows: ['银行', 'Password', 'Bank']
refuseSecrets: true
denyKeys: ['alt+f4']
irreversibleLabels: ['发布', '发送', '提交', 'publish', 'send', 'submit']
irreversibleMode: ask # ask | deny | allow
maxSequenceDepth: 5
verifyType: true
verifyClick: true

策略在 PowerShell 启动前生效，模型无法通过参数关闭。用户配置里的列表会整表替换默认值。

| 选项 | 默认值 | 说明 |
| enabled | true | 关闭后不注册工具 |
| powershellPath | powershell.exe | PowerShell 路径 |
| timeoutMs | 30000 | 单次调用超时 |
| screenshotDir | $DSH_HOME/desktop-control | 截图保存目录 |
| screenshotMaxWidth | 1440 | 长边上限 |
| screenshotGrid / screenshotCursor | false / true | 坐标网格 / 光标标记 |
| keepShots | 40 | 保留的截图数量 |
| elementsMaxRows | 140 | elements 行数上限 |
| verifyType / verifyClick | true | 默认开启校验 |

校验结果

| 状态 | 含义 |
| verified | 输入回读包含目标文字，或 verifyText 在动作后找到了要求的内容 |
| unverified | 回读成功但内容不符，或动作后没有找到 verifyText |
| unknown | 动作已送达，但结果无法机器校验 |
| refused | 拒绝执行：焦点不对、切不到前台、hit-test 不匹配、expect 失配或策略拦截 |

限制

- 只支持 Windows，并且需要交互式桌面会话；锁屏、UAC 安全桌面、RDP 断开会失败
- 纯坐标点击不受内容策略判断，建议配合 expect / verifyText
- 短标签或形近字 OCR 可能识别错误，用 exact 和 index 提高精度
- 不可逆动作默认 ask，宿主不支持审批时会直接拒绝

文档

- TESTING.md：测试用例和验收清单
- OPERATING-RULES.md：操作规范
- CHANGELOG.md：版本变化
- CONTRIBUTING.md：提交问题和补丁
- PUBLISH.md：发布流程

致谢

上游实现来自 qingying012/dsh-desktop-control（MIT），原始版权声明保留在 LICENSE，改动记录在 NOTICE 和 CHANGELOG.md。