dsh-gui-control

注意： 1.一定要看紧急停止部分，避免大肥鱼乱来终止不了 2.不要给deepseek更改该插件的机会，以免紧急终止失效 3.紧急停止失效了怎么办？拔网线和拉电闸总有一个适合你。 4.代码为ai核查，可能存在未发现的漏洞。 5.截图、OCR、无障碍树都会把屏幕内容（含密码框外的可见信息）送进模型上下文；paste 会临时读写你的剪贴板。别在敏感界面上让它看屏幕。

给 DeepSeek Harness 装的「眼睛 + 手」：模型可以截图看屏幕、按画面里的坐标移动/点击鼠标、打字敲键盘，并把「看 → 点 → 打字 → 再看」合成一次工具调用。

版本 0.1.0 · Windows only · Node ≥ 18 · 零依赖 · MIT

紧急停止

热键	效果
Ctrl+Shift+C	刹车。所有桌面控制立刻失效
Ctrl+Shift+C+V	刹车 + 要求 AI 结束对话
Ctrl+Shift+X	解除

按下 Ctrl+Shift+C 后，正在打的长文本、正在跑的鼠标轨迹会在几十毫秒内中断（helper 在逐字符、逐帧的循环里检查开关），之后每次调用都返回 HALTED，并且「用户已紧急停止」同时写进工具错误和系统提示词，模型没有绕路可走。

再按 V 之后，文案变成「确认停手、把控制权交回用户、不要再调用任何工具」。

热键由 helper 里的专用线程用 RegisterHotKey 抢注（线程级消息队列），与窗口焦点无关；状态写在一个小 JSON 文件里，Node 侧每次调用前读它，所以不用轮询进程。解除只能由用户按键，没有任何工具能让 AI 自己解开。（应该吧）

特性


类人输入	鼠标轨迹不是瞬移，是三次贝塞尔曲线 + 缓动 + 抖动 + 落点修正，像人一样移过去再点
省 token 的读屏	同一块画面，「读」它的代价差 5~20 倍。四档读屏手段，从控件树到截图逐级加价
截图即压缩	默认宽 1280 / JPEG 质量 68；可限窗口、限区域、转灰度、变更检测
急停	Ctrl+Shift+C 一按，所有桌面控制立刻失效，模型没有绕路可走
零依赖	只用 Node 内置模块和系统自带 PowerShell 5.1，不编译 exe

同时注册了一个 gui-control skill，把坐标换算、省 token 策略、常见坑写进了模型上下文。

工具

读屏

工具	层级	作用	典型代价
`desktop_a11y`	L0	Windows UI Automation 控件树：按钮/输入框/文本/菜单，每项带名称与屏幕坐标	5 个节点 ≈ 80 token 30 个 ≈ 550
`desktop_ocr`	L1	把屏幕文字读成 JSON（文本 + 屏幕坐标），不返回图片	窗口级 90300 整屏 9001100
`desktop_find`	L2	按颜色「看」屏幕，只回数字：`find` 找色块 / `grid` 摸布局 / `points` 校验某点	`points` ≈ 15 `find` ≈ 30~80
`desktop_screenshot`	L3 / L4	截图并回传图像（可限窗口 / 区域 / 灰度 / 网格 / 变更检测）	小图 300800 大图 1,5004,000

操作

工具	作用
`desktop_info`	显示器 / DPI / 光标 / 前台窗口 / 窗口列表。纯文本，不耗图像 token
`desktop_mouse`	`move` / `click` / `right` / `double` / `drag` / `scroll`，默认类人轨迹
`desktop_keyboard`	`type`（逐字符 Unicode）/ `paste`（剪贴板秒贴）/ `press`（组合键）/ `hold`
`desktop_act`	一串操作 + 末尾截图，一次调用完成多步交互；含 `waitChange` 等画面变化
`desktop_click_text`	读屏找字并点击：`{text:"开始行动"}` 一步完成「找字 → 算坐标 → 点击」；支持 `dryRun`

守卫

工具	作用
`desktop_guard`	查看紧急停止状态（被拦截时唯一还能调通的工具）

读屏优先级（L0 → L4）

永远按 L0 → L4 往上试，第一级成功就停止，并在本会话内记住这个应用该用哪一级。

级	手段	适用	失效信号
L0	`desktop_a11y`	Win32 / WinForms / WPF / UWP、对话框、资源管理器、设置页	`count <= 1`、没有目标控件名、`rect` 宽高为 0
L1	`desktop_ocr`	常规字号 UI 文字、菜单、报错、聊天记录	`count === 0`、关键词没命中、坐标落在窗口外
L2	`desktop_find`	高亮态、按钮色、指示灯、血条、「红/绿/黄」状态	`total: 0`、色块数量差一个量级、网格分不出目标
L3	`desktop_screenshot` 小图	需要看懂图标语义、布局、视觉状态	看不清按钮/文字
L4	`desktop_screenshot` 大图	读小字、像素级比对、OCR 兜底	没有更贵的了

经验法则

同一应用连续两次升级 → 这界面不适合当前手段，直接跳 L3，别在 L0/L1 反复试。
某级成功后，本会话内该应用直接用那一级。
Electron/Chromium 应用（VSCode、DSH 本体）控件树只给外壳的 5 个节点 → 走 L1。
游戏 / Unity / 自绘 canvas → L2 找颜色，比看图便宜一个量级。
「这个值变了没有」「按钮点亮没有」→ desktop_find 的 points，比截图便宜 100 倍。

紧急停止

热键	效果
Ctrl+Shift+C	刹车。所有桌面控制立刻失效
Ctrl+Shift+C+V	刹车 + 要求 AI 结束对话
Ctrl+Shift+X	解除

再按 V 之后，文案变成「确认停手、把控制权交回用户、不要再调用任何工具」。

热键由 helper 里的专用线程用 RegisterHotKey 抢注（线程级消息队列），与窗口焦点无关；状态写在一个小 JSON 文件里，Node 侧每次调用前读它，所以不用轮询进程。解除只能由用户按键，没有任何工具能让 AI 自己解开。

坐标系

模型只能看见图，所以鼠标工具默认吃最近一张截图的像素坐标：

screenX = region.left + imageX / scale.x

desktop_screenshot 返回 region（这张图对应的屏幕物理像素矩形）和 scale（图宽 ÷ 屏幕宽）。每张新截图刷新这个坐标系；要直接用物理坐标时传 space: "screen"。

实现

index.js              插件入口：10 个工具 + 截图/坐标系/附件回传/急停守卫
lib/helper.js         helper 进程客户端（JSON 行协议、串行队列、超时、重启、急停状态）
helper/win-helper.ps1 Windows 后端：PowerShell 5.1 + 内嵌 C#（user32/gdi32 P/Invoke、热键线程）
skill.md              给模型的用法说明
test/*.mjs            脱离 DSH 的本地冒烟测试

要点

零依赖。只用 Node 内置模块和系统自带的 PowerShell 5.1；不编译 exe（避免杀软误报）。
持久进程。helper 启动时 Add-Type 编译一次 C# 桥，之后每条命令走 stdin/stdout 一行 JSON，单次调用约 50–90ms；首次含编译约 1s。
急停由 helper 里一条独立线程守：RegisterHotKey 抢注 Ctrl+Shift+C / Ctrl+Shift+X （线程级消息队列，和窗口焦点无关）；抢不到就退化成 30ms 轮询按键状态，保证多开时也拦得住。状态写在 %TEMP%\dsh-gui-control\halt-<pid>.json，Node 每次调用前读它，不轮询进程。
截图走 GDI BitBlt(SRCCOPY|CAPTUREBLT) 抓 DWM 合成后的桌面，所以 Chromium/Electron 窗口也能截到；进程声明 PER_MONITOR_AWARE_V2，坐标就是物理像素。
输入走 SendInput：鼠标绝对坐标按虚拟桌面 65535 归一化（多显示器负坐标也对），文本用 KEYEVENTF_UNICODE 逐字符注入，中文/emoji 不经过输入法。
图像回传用 DSH 的 attachments 服务（ctx.get('attachments') → saveImage），工具 render 返回 [{type:'text'}, {type:'image', attachment}]；服务缺失或超限时降级成文本 + 错误说明。
helper 进程随插件 ctx.effect 清理；父进程退出时 stdin 关闭，helper 自己退出。

安装

# 在 DSH 里（plugin_manager 工具）；把路径换成你本机 clone 的位置
plugin_manager install_bundle  target=file:<你的路径>/dsh-gui-control

例如：

plugin_manager install_bundle  target=file:D:/code/dsh-gui-control

装好后重启 DSH，desktop_* 十个工具和 gui-control skill 就会出现。

改了代码之后

install_bundle 是把 package.json 的 files 列表拷进 profile 的 node_modules/dsh-gui-control/，不是软链。所以改完要重新 install（或直接 copy 覆盖过去），再重启 DSH —— disable → enable 只重新 apply，不会重新 import 模块（ESM 缓存）。

只改了 helper/win-helper.ps1 的话不用重启：杀掉 helper 进程（Get-CimInstance Win32_Process | ? { $_.CommandLine -like '*win-helper.ps1*' } | Stop-Process -Force），下次调用会自动拉起并读到新脚本。

配置

项	默认	说明
`helperPath`	包内 `helper/win-helper.ps1`	helper 脚本路径
`powershell`	`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`	PowerShell 可执行文件
`timeoutMs`	60000	单条 helper 命令超时

环境变量 DSH_GUI_CONTROL_KEEP_DIR：设置后每张截图另存一份到该目录（调试用，正常不需要）。

本地测试

node test/smoke.mjs           # 工具注册 + info/截图/移动/批量
node test/input.mjs           # 打开记事本, 聚焦, 打字(中文), 截图, 关闭
node test/click.mjs           # 按截图坐标点击 + 长文本粘贴
node test/framing.mjs         # act 步骤坐标跟随本次取景目标的断言
node test/halt.mjs            # 真按 Ctrl+Shift+C / +V / Ctrl+Shift+X, 断言全工具被拦与恢复
node test/halt-midflight.mjs  # 打字中途按急停, 断言 1.5s 内中断

这些脚本用假的 DSH context 直接跑插件，不需要重启 DSH；急停相关的两个会真的发全局热键。

已知边界

UAC / 安全桌面下截图是黑的、SendInput 无效 —— 需要人来点。
最小化窗口截不到内容（DWM 不合成），先 focus 还原。
窗口截图是「屏幕上那块区域」，被别的窗口盖住就会截到盖住它的窗口。
锁屏时无法操作。
急停热键只在 helper 启动后生效（本会话第一次调用 desktop_* 就会拉起它，约 1 秒）。如果别的程序已经全局占用了 Ctrl+Shift+C，注册会失败，desktop_guard 的 hotkeys.registration.stop 会是 false。

安全模型

这一节是自审结论，方便你判断它能不能装。

不会执行 shell。 helper 的命令来自 Node 经 stdin 传入的一行 JSON，PowerShell 侧 switch ($cmd) 分发到 C# 静态方法，参数逐个 [int] / [string] / [bool] 转型。代码里没有 Invoke-Expression、cmd.exe、Start-Process、COM 对象或任何把用户输入拼进脚本的地方——打字内容走 SendInput 的 UNICODE 路径，不经过 shell 解析。

不提权。 全程以当前用户权限运行。目标窗口是管理员权限时 SendInput 会被系统拒绝， helper 会明确报错而不是静默失败。

资源上限。 区域参数在 Node 侧 clampRegion() 里夹到单边 ≤ 16384、总面积 ≤ 4 MiB （约 419 万像素，即 2048×2048），desktop_find 的 points 最多 2000 个；C# 的 Grab() 用同一个 MaxGrabPx 上限再挡一次——任何一条路径都不会向 GDI 申请巨图。

急停优先于一切。 Guard() 在截图前、鼠标按下前、每个字符前都会检查，所以长任务也能在几毫秒内停下；Ctrl+Shift+C 的两次升级和解除都只在 helper 进程内的独立线程里，没有任何工具接口能让模型自己解除拦截。

已知的信任边界（不是漏洞，但你该知道）：

超时（默认 60s）只让 Node 侧放弃等待，helper 里那条命令仍会跑完。极长的 type 超时后，后续命令可能在它还在打字时开始。需要绝对串行时把 timeoutMs 调大。
截图 / OCR / 无障碍树的输出都会进入模型上下文，等于把屏幕内容交给模型服务商。
paste 会读一次你的剪贴板用于还原（restoreClipboard: false 则不读也不还原）。
急停热键注册失败而退化成轮询时，Ctrl+Shift+C 仍会传递给前台程序。

dsh-gui-control

给 DeepSeek Harness 装的「眼睛 + 手」：模型可以截图看屏幕、按画面里的坐标移动/点击鼠标、打字敲键盘，并把「看 → 点 → 打字 → 再看」合成一次工具调用。

版本 0.1.0 · Windows only · Node ≥ 18 · 零依赖 · MIT

紧急停止

热键	效果
Ctrl+Shift+C	刹车。所有桌面控制立刻失效
Ctrl+Shift+C+V	刹车 + 要求 AI 结束对话
Ctrl+Shift+X	解除

再按 V 之后，文案变成「确认停手、把控制权交回用户、不要再调用任何工具」。

特性


类人输入	鼠标轨迹不是瞬移，是三次贝塞尔曲线 + 缓动 + 抖动 + 落点修正，像人一样移过去再点
省 token 的读屏	同一块画面，「读」它的代价差 5~20 倍。四档读屏手段，从控件树到截图逐级加价
截图即压缩	默认宽 1280 / JPEG 质量 68；可限窗口、限区域、转灰度、变更检测
急停	Ctrl+Shift+C 一按，所有桌面控制立刻失效，模型没有绕路可走
零依赖	只用 Node 内置模块和系统自带 PowerShell 5.1，不编译 exe

同时注册了一个 gui-control skill，把坐标换算、省 token 策略、常见坑写进了模型上下文。

工具

读屏

工具	层级	作用	典型代价
`desktop_a11y`	L0	Windows UI Automation 控件树：按钮/输入框/文本/菜单，每项带名称与屏幕坐标	5 个节点 ≈ 80 token 30 个 ≈ 550
`desktop_ocr`	L1	把屏幕文字读成 JSON（文本 + 屏幕坐标），不返回图片	窗口级 90300 整屏 9001100
`desktop_find`	L2	按颜色「看」屏幕，只回数字：`find` 找色块 / `grid` 摸布局 / `points` 校验某点	`points` ≈ 15 `find` ≈ 30~80
`desktop_screenshot`	L3 / L4	截图并回传图像（可限窗口 / 区域 / 灰度 / 网格 / 变更检测）	小图 300800 大图 1,5004,000

操作

工具	作用
`desktop_info`	显示器 / DPI / 光标 / 前台窗口 / 窗口列表。纯文本，不耗图像 token
`desktop_mouse`	`move` / `click` / `right` / `double` / `drag` / `scroll`，默认类人轨迹
`desktop_keyboard`	`type`（逐字符 Unicode）/ `paste`（剪贴板秒贴）/ `press`（组合键）/ `hold`
`desktop_act`	一串操作 + 末尾截图，一次调用完成多步交互；含 `waitChange` 等画面变化
`desktop_click_text`	读屏找字并点击：`{text:"开始行动"}` 一步完成「找字 → 算坐标 → 点击」；支持 `dryRun`

守卫

工具	作用
`desktop_guard`	查看紧急停止状态（被拦截时唯一还能调通的工具）

读屏优先级（L0 → L4）

永远按 L0 → L4 往上试，第一级成功就停止，并在本会话内记住这个应用该用哪一级。

级	手段	适用	失效信号
L0	`desktop_a11y`	Win32 / WinForms / WPF / UWP、对话框、资源管理器、设置页	`count <= 1`、没有目标控件名、`rect` 宽高为 0
L1	`desktop_ocr`	常规字号 UI 文字、菜单、报错、聊天记录	`count === 0`、关键词没命中、坐标落在窗口外
L2	`desktop_find`	高亮态、按钮色、指示灯、血条、「红/绿/黄」状态	`total: 0`、色块数量差一个量级、网格分不出目标
L3	`desktop_screenshot` 小图	需要看懂图标语义、布局、视觉状态	看不清按钮/文字
L4	`desktop_screenshot` 大图	读小字、像素级比对、OCR 兜底	没有更贵的了

经验法则

同一应用连续两次升级 → 这界面不适合当前手段，直接跳 L3，别在 L0/L1 反复试。
某级成功后，本会话内该应用直接用那一级。
Electron/Chromium 应用（VSCode、DSH 本体）控件树只给外壳的 5 个节点 → 走 L1。
游戏 / Unity / 自绘 canvas → L2 找颜色，比看图便宜一个量级。
「这个值变了没有」「按钮点亮没有」→ desktop_find 的 points，比截图便宜 100 倍。

紧急停止

热键	效果
Ctrl+Shift+C	刹车。所有桌面控制立刻失效
Ctrl+Shift+C+V	刹车 + 要求 AI 结束对话
Ctrl+Shift+X	解除

再按 V 之后，文案变成「确认停手、把控制权交回用户、不要再调用任何工具」。

坐标系

模型只能看见图，所以鼠标工具默认吃最近一张截图的像素坐标：

screenX = region.left + imageX / scale.x

实现

index.js              插件入口：10 个工具 + 截图/坐标系/附件回传/急停守卫
lib/helper.js         helper 进程客户端（JSON 行协议、串行队列、超时、重启、急停状态）
helper/win-helper.ps1 Windows 后端：PowerShell 5.1 + 内嵌 C#（user32/gdi32 P/Invoke、热键线程）
skill.md              给模型的用法说明
test/*.mjs            脱离 DSH 的本地冒烟测试

要点

零依赖。只用 Node 内置模块和系统自带的 PowerShell 5.1；不编译 exe（避免杀软误报）。
持久进程。helper 启动时 Add-Type 编译一次 C# 桥，之后每条命令走 stdin/stdout 一行 JSON，单次调用约 50–90ms；首次含编译约 1s。
急停由 helper 里一条独立线程守：RegisterHotKey 抢注 Ctrl+Shift+C / Ctrl+Shift+X （线程级消息队列，和窗口焦点无关）；抢不到就退化成 30ms 轮询按键状态，保证多开时也拦得住。状态写在 %TEMP%\dsh-gui-control\halt-<pid>.json，Node 每次调用前读它，不轮询进程。
截图走 GDI BitBlt(SRCCOPY|CAPTUREBLT) 抓 DWM 合成后的桌面，所以 Chromium/Electron 窗口也能截到；进程声明 PER_MONITOR_AWARE_V2，坐标就是物理像素。
输入走 SendInput：鼠标绝对坐标按虚拟桌面 65535 归一化（多显示器负坐标也对），文本用 KEYEVENTF_UNICODE 逐字符注入，中文/emoji 不经过输入法。
图像回传用 DSH 的 attachments 服务（ctx.get('attachments') → saveImage），工具 render 返回 [{type:'text'}, {type:'image', attachment}]；服务缺失或超限时降级成文本 + 错误说明。
helper 进程随插件 ctx.effect 清理；父进程退出时 stdin 关闭，helper 自己退出。

安装

# 在 DSH 里（plugin_manager 工具）；把路径换成你本机 clone 的位置
plugin_manager install_bundle  target=file:<你的路径>/dsh-gui-control

例如：

plugin_manager install_bundle  target=file:D:/code/dsh-gui-control

装好后重启 DSH，desktop_* 十个工具和 gui-control skill 就会出现。

改了代码之后

install_bundle 是把 package.json 的 files 列表拷进 profile 的 node_modules/dsh-gui-control/，不是软链。所以改完要重新 install（或直接 copy 覆盖过去），再重启 DSH —— disable → enable 只重新 apply，不会重新 import 模块（ESM 缓存）。

只改了 helper/win-helper.ps1 的话不用重启：杀掉 helper 进程（Get-CimInstance Win32_Process | ? { $_.CommandLine -like '*win-helper.ps1*' } | Stop-Process -Force），下次调用会自动拉起并读到新脚本。

配置

项	默认	说明
`helperPath`	包内 `helper/win-helper.ps1`	helper 脚本路径
`powershell`	`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`	PowerShell 可执行文件
`timeoutMs`	60000	单条 helper 命令超时

环境变量 DSH_GUI_CONTROL_KEEP_DIR：设置后每张截图另存一份到该目录（调试用，正常不需要）。

本地测试

node test/smoke.mjs           # 工具注册 + info/截图/移动/批量
node test/input.mjs           # 打开记事本, 聚焦, 打字(中文), 截图, 关闭
node test/click.mjs           # 按截图坐标点击 + 长文本粘贴
node test/framing.mjs         # act 步骤坐标跟随本次取景目标的断言
node test/halt.mjs            # 真按 Ctrl+Shift+C / +V / Ctrl+Shift+X, 断言全工具被拦与恢复
node test/halt-midflight.mjs  # 打字中途按急停, 断言 1.5s 内中断

这些脚本用假的 DSH context 直接跑插件，不需要重启 DSH；急停相关的两个会真的发全局热键。

已知边界

UAC / 安全桌面下截图是黑的、SendInput 无效 —— 需要人来点。
最小化窗口截不到内容（DWM 不合成），先 focus 还原。
窗口截图是「屏幕上那块区域」，被别的窗口盖住就会截到盖住它的窗口。
锁屏时无法操作。
急停热键只在 helper 启动后生效（本会话第一次调用 desktop_* 就会拉起它，约 1 秒）。如果别的程序已经全局占用了 Ctrl+Shift+C，注册会失败，desktop_guard 的 hotkeys.registration.stop 会是 false。

安全模型

这一节是自审结论，方便你判断它能不能装。

不提权。 全程以当前用户权限运行。目标窗口是管理员权限时 SendInput 会被系统拒绝， helper 会明确报错而不是静默失败。

已知的信任边界（不是漏洞，但你该知道）：

超时（默认 60s）只让 Node 侧放弃等待，helper 里那条命令仍会跑完。极长的 type 超时后，后续命令可能在它还在打字时开始。需要绝对串行时把 timeoutMs 调大。
截图 / OCR / 无障碍树的输出都会进入模型上下文，等于把屏幕内容交给模型服务商。
paste 会读一次你的剪贴板用于还原（restoreClipboard: false 则不读也不还原）。
急停热键注册失败而退化成轮询时，Ctrl+Shift+C 仍会传递给前台程序。

Macocin/dsh-gui-control

dsh-gui-control

目录

紧急停止

特性

工具

读屏

操作

守卫

读屏优先级（L0 → L4）

紧急停止

坐标系

实现

安装

配置

本地测试

已知边界

安全模型

Community comments

Macocin/dsh-gui-control

dsh-gui-control

目录

紧急停止

特性

工具

读屏

操作

守卫

读屏优先级（L0 → L4）

紧急停止

坐标系

实现

安装

配置

本地测试

已知边界

安全模型

Community comments