helloo-666/dsh-screen-helper

dsh-screen-helper

让 AI 模型看你的屏幕、动你的鼠标、敲你的键盘——一句话，就为你点开那个按钮。

一个 DeepSeek Harness（dsh）插件，给模型一个工具
—— screen_automation —— 用来驱动 屏幕自动化小助手 / ScreenAutomationHelper 桌面自动化 CLI：
截屏、OCR 文字识别、屏幕上文字/图像定位、UI 控件树读取，以及鼠标 / 键盘 / 剪贴板操作。

demo

安装前请先读 安全 一节。 这个插件会让 AI 模型移动你真实的鼠标、敲你真实的键盘、
读取你的屏幕和剪贴板。

环境要求

| 组件 | 要求 |
| --- | --- |
| DeepSeek Harness | 0.1.5-rc.1 或兼容的 0.1.5 版本 |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| ScreenAutomationHelper | 本地已安装（Windows）。本文档默认路径：D:\ScreenAutomationHelper\ScreenAutomationHelper.exe |
| 操作系统 | Windows 10/11 |

find_exact 与 screen.find 的区别：screen.find 返回的是包含命中词的整行框，点击会落到行中间；
find_exact 复用 screen.recognize 的单词级 OCR，返回精确命中词的框。要点按钮、点标签时优先用 find_exact。

UI 树点击（ui.click）：先用 ui.find 按无障碍身份（role/name）确认控件存在，再自动用 find_exact 拿到屏幕上像素坐标并点击。比纯 OCR 稳——它先证明"这个控件是真的"，不会因 OCR 误识别点到同名文字。控件不存在时明确报错、绝不乱点。
注意：SAH 的 UI 树（ui.tree/ui.find）只暴露身份与层级，不暴露元素几何坐标，所以 ui.click 仍按解析出的像素点击，而非按元素句柄。对 Electron 类应用（如 DSH 桌面本身）UI 树节点可能不暴露名字，此时退回 find_exact 或显式 mouse.click --point。

小助手是独立的第三方产品，不随本插件分发。如果 health 返回 SPAWN_FAILED，
说明小助手没装或 cliPath 配错了。

安装

⚠️ 平台前提：本插件只能在 Windows 上运行。 它驱动的是
屏幕自动化小助手 / ScreenAutomationHelper —— 一个 Windows 桌面自动化
程序（GUI + OCR + 鼠标键盘模拟）。macOS / Linux 上没有这个 CLI，装了也用不了。下方命令也假定
你已经在用 Windows 版的 DeepSeek Harness。

方式一：从 GitHub Release 一键装（推荐）

Windows PowerShell
dsh plugin --profile desktop add https://github.com/helloo-666/dsh-screen-helper/releases/download/v0.1.0/dsh-screen-helper-0.1.0.tgz

方式二：从本地源码 / git 仓库

dsh plugin --profile desktop add ./dsh-screen-helper          # 本地目录
dsh plugin --profile desktop add ./dsh-screen-helper-0.1.0.tgz # 本地打包产物
git clone https://github.com/helloo-666/dsh-screen-helper.git
dsh plugin --profile desktop add ./dsh-screen-helper          # clone 后

装完重启该 profile。确认插件行已生效：

dsh --profile desktop --dump-config

⚠️ 必看：cliPath 必须手动配。
dsh plugin add 会把插件声明的默认值 cliPath: '' 写进 profile。这个默认值会从 PATH
里找 ScreenAutomationHelper.exe，而小助手的安装程序不会把自己加进 PATH——所以刚装完
每一次调用都会失败，直到你在 profile 的 cordis.patch.yml 里写上绝对路径。

自动安装脚本

仓库里附带 install.ps1，一条命令完成「装插件 + 写入 cliPath + 选审批档」：

默认 approval=always，cliPath 取 SAH 默认安装位置
.\install.ps1

或显式指定
.\install.ps1 -CliPath 'D:\ScreenAutomationHelper\ScreenAutomationHelper.exe' -Approval mutating

脚本会：① 把 release tarball 下到临时目录并通过 dsh plugin add 安装；② 在 profile 的
cordis.patch.yml 里补上 cliPath 与 approval 两项配置（已存在则跳过）。它不碰你其它插件。

配置

在 profile 的 cordis.patch.yml 里：

- id: screen-helper
config:
可执行文件绝对路径。留空 = 从 PATH 找 "ScreenAutomationHelper.exe"。
cliPath: 'D:\ScreenAutomationHelper\ScreenAutomationHelper.exe'
单次调用超时。
timeoutMs: 60000
'always'   = 每一次调用都弹窗询问（包括 status 这类只读查询）。
'mutating' = 只有鼠标/键盘/剪贴板写入/状态变更才询问。
'never'    = 全部直接执行，不询问。（默认）
approval: always
true = 无论是否批准，一律拒绝 workflow 变更和剪贴板写入。
blockDestructive: false

三档审批策略怎么选

| 配置 | 行为 | 适合 |
| --- | --- | --- |
| always | 每次调用都弹窗，包括 status、health 这类只读查询 | 不放心、想全程盯着，或机器上有敏感内容 |
| mutating | 只有鼠标/键盘/剪贴板写入/状态变更才弹窗，只读查询静默通过 | 日常使用，平衡打扰与安全 |
| never | 全部直接执行，不询问（默认） | 单用户、人在场、完全信任 |

always 和 mutating 都走 dsh 原生审批服务，它是 fail-closed 的：没有应答器、用户取消、
应答器抛异常，一律拒绝而不是放行。拒绝时连返回数据都是 null——不会偷偷把屏幕内容
或剪贴板内容泄露给模型。

如果你给陌生人发布这个插件，请把补丁层里的 approval 设为 mutating 或 always。
默认的 never 是给完全信任的场景准备的。

用法

模型拿到的是一个工具，参数是 action 加上一个 CLI 参数数组 args：

{ "action": "screen.recognize", "args": ["--target", "foreground"] }
{ "action": "screen.find", "args": ["--text", "登录"] }
{ "action": "find_exact", "args": ["--text", "登录", "--target", "virtual-screen"] }
{ "action": "mouse.click", "args": ["--point", "842,516", "--button", "left"] }

典型流程：screen.recognize 或 ui.tree 看状态 → screen.find（行级）或 find_exact（词级精确框）拿坐标
→ mouse.click 点击。要点具体的标签或按钮，用 find_exact——它返回的是命中词本身的框，而不是整行。
坐标是屏幕绝对像素；多显示器请先调 screen.monitors。

为什么是一个工具而不是四十个

小助手暴露约 42 个能力族。给每个子命令注册一个 dsh 工具会挤爆模型的工具列表，反而让它忽略
真正重要的工具。用一个工具 + 带风险分级的 action 目录，既保持命名空间小，又能触达整条 CLI。

按风险分级

| 分级 | 行为 | 例子 |
| --- | --- | --- |
| read | 永不询问，纯查询 | status、capabilities、health、runs.list、workflow.list |
| observe | 永不询问，但会暴露屏幕内容 | screen.capture、screen.recognize、ui.tree、clipboard.read |
| mutate | approval: mutating 时会询问 | mouse.click、keyboard.write、clipboard.write、workflow.install |

不在 read/observe 表里的子命令一律按 mutate 处理，所以小助手未来版本新增的命令会被自动
拦截，而不是因为白名单没更新就悄悄放行。

安全

这个插件把物理输入设备的控制权交给 AI 模型。安装前请想清楚后果。

- 鼠标和键盘操作不可撤销。 插件能点下一个按钮，但不能取消这次点击。付款确认、消息发送、
文件删除、账号变更都能通过 mouse.click / keyboard.write 触达，而且取消工具调用并不会撤销
已经发生的操作。
- 没有沙箱兜底。 dsh 的文件沙箱约束的是文件写入，约束不了一个合成操作系统级输入事件的程序。
这个工具驱动的是真实桌面。
- 屏幕读取可能泄露机密。 screen.capture、screen.recognize、clipboard.read 能返回屏幕
上或剪贴板里的任何内容，包括密码、令牌、私密消息，而且这些结果会写进会话日志。
- 结果会被持久化。 工具输出会追加到会话日志，抓到什么就留在那里。
- workflow.install 会执行来源代码。 安装一个 workflow 就意味着信任那个来源。
blockDestructive: true 会直接禁用这一族。

已内置的缓解措施

- 参数以真正的 argv 数组跨进程传递，shell: false。含 ; rm -rf / 或 $(whoami) 的值会被
当成普通文本，永不执行。这也是本工具收 args 数组而不收命令字符串的原因。
- NUL 字节或超长参数在启动进程前就被拒绝。
- 每次调用都有超时；取消会把 kill 转发给子进程。
- approval: mutating 通过 dsh 的 fail-closed 审批服务拦下整个 mutate 分级。
- blockDestructive: true 即使已批准也拒绝 workflow 变更和剪贴板写入。
- 模型只能触达小助手自己的 cli 子命令树，无法传入任意可执行文件或任意子命令路径。

本插件不能防住什么

一个下定决心、且处于默认配置（approval: never + blockDestructive: false）的模型可以随意
操作你的桌面。默认值是给"单用户、操作者在场看着"的场景选的。如果你要把它发布给陌生人，
请在补丁层里带上 approval: mutating —— 严格策略只差一行，而这一行就是"有用的工具"和
"无人值守的远程控制通道"之间的区别。

设计取舍：为什么 ui.click 是「身份确认 + 像素点击 + 反向验证」

UI 自动化 agent 主流有两种范式，本插件取了两者的组合，并受小助手（SAH）能力边界约束：

- 视觉范式（OpenAI CUA / Codex Computer Use / Operator）：模型看截图，直接在像素坐标上
click(x,y)。好处是通用——任何屏幕上画出来的东西都能点；坏处是像素脆：布局一抖、动画一晃、
重叠一个元素，就点到错的地方。业界有整篇文章专门讲「点对了按钮、点错了屏幕」的失败。
- 可访问性树范式：用 UI 控件的 role/name（无障碍身份）定位，拿到稳定 ID，不随像素漂移。
对按钮、菜单、表单这类「有稳定名字」的控件，AX 树能覆盖生产环境里约 95% 的点击。

本插件的设计：

1. ui.find 做身份确认（对齐 AX 树范式）。先证明「叫这个名字的控件真的存在」，而不是盲目
相信 OCR 看到的文字。控件不存在 / 重名歧义时，ui.click 明确报错、绝不乱点。
2. find_exact（OCR）做像素解析（对齐视觉范式的落点）。SAH 的 ui.find 在小助手当前版本
不返回元素几何坐标（只给 role/name；Electron 类应用甚至不暴露名字），所以像素仍来自 OCR。
3. --verify 做闭环验证（对齐 CUA「点击后核对」的做法）。点完用 ui.inspect --point 反查
「光标下实际是哪个控件」，比对 role/name 是否匹配预期。不匹配就报告
clicked+verify-mismatch，把「点错屏幕」的风险暴露出来，而不是静默成功。

为什么不直接「AX 树拿坐标 → 点」？因为 SAH 当前 ui.find 不带几何（已实测确认）。等小助手
在 ui.find 里补上 bounds_screen（它其实在单次 ui.inspect 里已有），ui.click 可以跳过
OCR 这步，变成纯 AX 树定位——届时本插件的接口无需改动。

不抢鼠标：后台输入模式（默认）

这是本插件最关键的差异化能力。默认情况下输入不经过物理鼠标：

inputMode: background   # 默认：通过 Windows 消息投递，光标不动、焦点不抢
inputMode: real       # 走真实鼠标：万能，但会接管你的鼠标

效果：模型可以操作别的窗口，而你继续用自己的鼠标、继续在前台打字，互不干扰。

实测（操作后台 Notepad，DSH 全程保持前台）：

target: Notepad -> NotepadTextBox            # 命中后台窗口的真实编辑控件
cursorMoved: false | [1403,34] -> [1403,34]  # 你的光标全程没动
写入内容: HELLO-BG                           # 后台打字真实生效

支持的动作

| 动作 | 后台模式 | 说明 |
|---|---|---|
| \mouse.click\ | 是 | 发给目标窗口最深层子控件（需 \--point\，且坐标要在窗口内） |
| \keyboard.write\ | 是 | \WM_CHAR\ 逐字发送，自动定位编辑控件 |
| \keyboard.hotkey\ | 否 | 走真实鼠标模式 |
| \mouse.drag\ / \scroll\ | 否 | 依赖真实光标轨迹，无消息等价物，不静默降级 |

指定操作哪个窗口

screen_automation({
action: 'mouse.click',
args: ['--point', '1358,345', '--title', 'Notepad']
})
--title 按标题匹配，--hwnd 直接给句柄。都不给则操作前台窗口。
注意：--point 是屏幕绝对坐标，必须落在目标窗口矩形内，否则会落到顶层窗口。

边界（诚实说明）：后台模式只对处理标准 Windows 消息的程序可靠。
自绘 UI（Electron / Chromium / Qt，如 B站客户端、微信、Chrome）常常不理 WM_ 消息 ——
它们监听原始输入事件。对这类程序，后台点击可能「发出去了但没反应」。
插件不会在这种情况下偷偷改用真实鼠标（那才是真正的抢鼠标），而是如实返回结果，
由你决定要不要切到 \inputMode: real\。
应用识别：先看图标再操作

在让模型控制某个软件之前，建议先调用一次 window.app：

screen_automation({
action: 'window.app',
args: []
})
返回示例：
{
"process": "Notepad.exe",
"title": "无标题 - Notepad",
"process_path": "C:\\...\\Notepad.exe",
"displayName": "Notepad",
"iconPath": "C:\\Users\\...\\Temp\\dsh-screen-helper-icon-xxx.png"
}

window.app 会先调用 window.foreground 拿到当前前台应用，再用 Windows 的
System.Drawing.Icon.ExtractAssociatedIcon 从可执行文件里抽出图标，保存成一张 PNG。
这样你和模型都能先看见要动的是哪个软件 + 它的图标。

弹窗询问（插件自带的确认门）

⚠️ 重要前提：dsh 自带的审批弹窗在「审批提示被禁用」的会话里是 fail-closed 的——
它永远不弹，任何需要审批的动作都被自动拒绝。这就是为什么你可能「一直没见过弹窗」。
所以本插件自己实现了确认门，不依赖 dsh 的审批服务。

把 confirm 设成 popup（默认就是这样）：

confirm: popup   # 鼠标/键盘/剪贴板/工作流改动：先弹确认卡，你批准才执行
confirm: off   # 插件不管，动作直接执行

工作流是两步的（因为工具调用本身不能中途暂停等你点按钮）：

1. 你（或模型）发起一个会改变屏幕的动作，比如 mouse.click
2. 插件不执行，而是返回：

{
"executed": false,
"blockedReason": "awaiting confirmation",
"data": {
"confirmToken": "41b23b68ce14",
"pendingAction": "mouse.click",
"pendingArgs": ["--point", "500,400"],
"appName": "哔哩哔哩",
"iconPath": "G:\\Temp\\dsh-screen-helper-icon-xxxx.png"
}
}

3. 模型这时渲染一张确认卡片（带上应用名 + 从 exe 抽出来的图标），你点「允许 / 拒绝」
4. 你点允许 → 模型调用：

screen_automation({
action: 'window.confirm',
args: ['--approve', '41b23b68ce14']
})
拒绝则用：args: ['--deny', '41b23b68ce14']

真实动作只有走 --approve 这一步才会执行——这是插件强制的，不是靠模型自觉。
token 一次性有效，10 分钟过期。

图标为什么出现在卡片里而不是「系统弹窗」里：dsh 的审批组件只渲染文字 reason，没有
图片字段；而 genui 的交互卡片是模型回答的一部分。所以插件把「门」做在自己身上，
「卡片 + 图标」由模型渲染，两者配合才是完整的一次确认。

pnpm install
pnpm run build     # tsc -> lib/
pnpm test          # 26 个测试：分级、真实 CLI 端到端、插件契约

小助手不存在时，端到端套件会跳过而不是失败。用 SAH_CLI 指定其他路径：

SAH_CLI=/path/to/ScreenAutomationHelper.exe pnpm test

真机验证脚本

以下三个会驱动真实屏幕，因此不属于 pnpm test。它们存在的意义是：让上面那些安全声明
可以被复现，而不是只能被相信。请在能看见鼠标移动的机器上运行。

pnpm run smoke              # 发现、OCR、UI 树、剪贴板、小幅移动鼠标
pnpm run verify:roundtrip   # 定位 -> 移动 -> 独立复核 -> 恢复原状
pnpm run verify:approval    # 证明审批门真的拦住了执行
pnpm run verify:always      # 证明 always 模式下每次调用都询问

还有一组 scripts/play-.mjs，是一次真机把玩留下的痕迹，可以逐个运行：

node scripts/can-i-use.mjs       # 三档分级是否都能真实执行
node scripts/accuracy.mjs        # 鼠标定位精度（8 个点）—— 实测 0 偏差
node scripts/find-and-click.mjs  # 找字 -> 移动 -> 验证落在目标框内
node scripts/play-calculator2.mjs # 启动计算器 -> 键盘输入 -> OCR 回读结果
node scripts/play-close-notepad3.mjs # task.begin -> activate -> 关闭窗口

accuracy.mjs 顺带证实了一件事：mouse.move --duration 是动画。带 duration 时立刻读
mouse.position 会读到飞行中的中间坐标（曾观测到请求 (300,300) 实测 (309,299)），
等 250ms 稳定后再读就是精确值。不是精度问题，是竞态。

play-calculator.mjs 是故意保留的失败案例：它尝试用 screen.find 点计算器按钮，结果
7 和 = 定位失败。对照 play-calculator2.mjs（改用键盘）可以直观看到上面第 4 个坑。

verify:approval 是其中最关键的。它先把光标停在某处，然后在应答器返回 rejected 的情况下
让工具去移动光标，最后重新读取光标位置来确认这次移动根本没发生——依据是可观测的硬件状态，
而不是某个返回值：

【拒绝】mouse.move -> (100,100)
executed=false  blockedReason=the user did not approve this action (rejected)
光标实际位置=(600, 600)   (100,100)
光标实际位置=(100, 100)    window.activate  ->  keyboard.
|                                          ^
+-- 写入 agent_screen_task.json -----------+

3. window.activate 不接 --handle。 它的签名是 activate [--target TARGET]。传 --handle
会被静默忽略（返回 null），窗口不动，但也不报错。window.select 那个"选中状态"是
进程内的，跨 cli 调用不保留——别指望 select 完再 activate。

4. 单字符 OCR 不可靠。 计算器的 7 被认成 ⑧、= 被认成 二。所以
screen.find 不适合点计算器按钮这类单字符目标。要输入表达式就直接 keyboard.write，
别去找按钮。

目录结构

src/cli.ts        风险分级、argv 构造、进程启动、JSON 解析
src/index.ts      defineTool 注册、审批门、面向模型的使用手册
scripts/          真机验证（smoke、roundtrip、approval-gate）+ play-* 把玩记录
cordis.patch.yml  dsh 折叠进 profile 的 bundle 层
test/             node:test 测试套件

许可证

MIT。ScreenAutomationHelper（屏幕自动化小助手）本身是独立产品，遵循其自身 EULA，不随本插件分发。