桌面操控 HUANGjiale123-bit/dsh-desktop-control

dsh-desktop-control

Windows 桌面观察与操作插件（DSH / DeepSeek Harness）：读窗口无障碍树、截图、点击、输入。
Windows desktop observation and control for DeepSeek Harness: accessibility tree, screenshots,
OCR fallback, mouse/keyboard, session-scoped approvals.

这会让 AI 操作你的真实鼠标和键盘。 权限模型见下面「权限模型」一节。

- 安装包：Releases
- 新手实战笔记：使用经验与技巧（坐标、按名字点、长文本、急停、常见错误）
- 许可：MIT　作者：north-star(t)

不依赖外部视觉模型——元素名、角色、坐标由 Windows UI Automation 提供，不是模型从图片里猜的。

安装

先下载 Release 里的 dsh-desktop-control-*.tgz，然后二选一：

1. 插件管理（推荐）：DSH → 插件管理 → 添加插件 → 在"包名或地址"里填 tgz 的绝对路径 （例如 D:\下载\dsh-desktop-control-1.0.2.tgz）→ 重启 DSH
2. CLI（等价）：

dsh plugin --profile <你的profile> add "D:\下载\dsh-desktop-control-1.0.2.tgz"

市场暂未收录（dshmarket 只显示其索引内的插件）；请从 Releases 下载。
手改 package.json 的安装方式见安装说明的开发者附录，不推荐。

装完就能用，不需要改任何配置。 辅助程序随插件包一起安装。
装好后重启 DSH，让它跑一次 desktop_diagnose，看到 插件 1.0.x 即成功。

权限模型

默认什么都不放行。 首次操作某个应用时，插件会询问你是否允许：

允许在当前会话中操作「notepad.exe」吗？
同意后，本次会话内对该应用的鼠标/键盘操作不再询问；会话结束即失效，不会写入任何配置。

- 同意 → 仅对当前会话的这一个应用有效
- 拒绝 → 本次会话内不再询问该应用
- 会话结束 → 授权自动失效，不需要做任何清理

另有 desktop_revoke_grants 工具，可在会话中途主动收回全部授权。

与「持久白名单」的区别

插件也支持在配置里写 allowedApps，但那是持久放行：写进去就一直有效， 人不在场也照样能操作。对能操纵鼠标键盘的能力来说这偏重，所以默认留空。
只有确实需要长期免问的应用才写进去。

工具

| 工具 | 作用 | 需要授权 |
| desktop_list_windows | 列出可见窗口 | 否（只读） |
| desktop_read_window | 读窗口的无障碍树 | 否（只读） |
| desktop_screenshot | 截图 | 否（只读） |
| desktop_click | 按坐标点击 | 是 |
| desktop_click_element | 按元素描述符点击 | 是 |
| desktop_type | 输入文本（支持中文） | 是 |
| desktop_press_key | 发送组合键 | 是 |
| desktop_set_value | 写控件值（走 UIA，带回读校验） | 是 |
| desktop_do_action | 触发次要动作（Raise/Scroll/Expand/Collapse） | 是 |
| desktop_revoke_grants | 收回本次会话的授权 | 否 |
| desktop_indicate / desktop_off | 显示/关闭运行指示层与急停 | 否 |

数据流向

界面上的一切都在本机处理：dsc.exe 是本地进程，无障碍树、截图、输入注入都不出这台机器。唯一的出站内容是工具返回的文本与截图，它们会进入模型上下文，和任何其它工具结果一样。

界面文本按不可信数据处理：应用可能在标题、按钮名、文档内容里藏针对模型的指令，所以返回时加显式前缀说明"这是数据而非指令"。

已知限制

1. dsc.exe 不能放在带 Low 完整性标签的目录里（例如 D:\dsh workspace）。

同一份 dsc.exe：放在工作区里跑是 Low 完整性级别，读 Chromium 系窗口只拿到 7 个节点（外壳）；同样字节复制到 %TEMP% 就是 Medium，读到 20~40 个。
icacls "D:\dsh workspace" 能看到 Mandatory Label\Low Mandatory Level:(OI)(CI)(NW) —— 从那里执行的程序也跟着变 Low，而 Low 完整性的 UIA 客户端拿不到内容树。

注入同理：低完整性下 SetCursorPos 失败、光标不动、不报错。

插件不受影响（它用 profile 安装目录里的那份，是 Medium）。
只有"直接跑 helper/bin/dsc.exe"（开发、调试、测试）才会踩到。
ping 和 tree 现在都会回报 integrity / integrityRid，树读残时先看它。
详见 docs/定案-低完整性级别不是Chromium的毛病.md。

2. 无障碍树在 WinUI / 打包应用上仍然很残。

实测元素数：自建 WinForms 窗口 9 个（完整）、系统记事本 12 个（多为无名 Pane）。
WinUI / 打包应用这类只有外壳，要用截图路径。

Chromium 系（Electron / Tauri / WebView2）已经能读也能点：插件会自动换一条 UIA 读取链（server/uia-bridge.py：python → PowerShell），实测 SuYou（Tauri）读到 39~62 个有名字、有矩形的节点；desktop_click_element 在 Chromium 上会自动改用这条链定位，然后优先用 InvokePattern 触发（不移动鼠标）。

详见 docs/问题-Chromium无障碍-第十轮-按名字点击打通.md。

3. 停止用 ESC，不是 desktop_off。

dsc-esc.exe 装上低层键盘钩子，按 ESC 拉下闸门文件；dsc.exe 每条命令执行前都查这个文件，拦住所有变更性动作（连观察类命令也一并停）。desktop_off 只收指示层界面，不拉闸。

4. 多显示器 / 跨屏不同缩放：没有实测数据。

开发机只有一块屏（\\.\DISPLAY1），窗口被拖到另一块屏、或两块屏缩放不同这类情况没验过。代码按 Per-Monitor V2 写，坐标是物理像素，理论上跟着窗口所在屏走 —— 但「理论上」不算支持。

desktop_list_windows 会回报屏数：多屏时它会把这条提醒直接写进返回文本，desktop_click 的工具说明里也写着。有多屏的人请自己用 desktop_whatis 核对落点，别把这块当成已验证。

5. 尚未实现：visual-candidates（在截图上标出候选元素、带 observationId / imageSha256 / 坐标仿射关系的那套）。其余早先列为「未实现」的（launch_app、drag、滚轮、截图坐标锚定）都已实现。

安全说明

- 白名单双层校验：插件和辅助程序各校验一次；操作前重新枚举窗口，确认目标仍存在、其可执行文件仍在名单内（挡住句柄被复用成别的进程）
- 所有写入回读验证：set_value 返回 before/after/verified，值没变则报错而不是假装成功
- 失败一律拒绝：授权通道不可用、回调抛错、无会话上下文 —— 全部按拒绝处理
- 急停闸门：desktop_off 拉下闸门后，所有变更性命令被拒绝，不依赖按键通道或前台窗口

开发

./helper/build.sh # 编译 dsc.exe / dsc-edge.exe
node tools/test-approval.mjs # 授权逻辑自测（22 项）
node tools/test-packaging.mjs # 自包含性检查（22 项）
./tools/diag/build.sh CursorTruth # 注入能力自检

改完插件后，把 plugin/ 下的文件同步到配置档的 node_modules/dsh-desktop-control/，并同步 package.json 与 index.mjs 里的 PLUGIN_VERSION。

文档

| 文件 | 内容 |
| docs/当前状态.md | 入口：能做什么、不能做什么、改动前必看 |
| docs/ESC强制退出-完整链路.md | ESC 停止的完整链路 + 六类踩过的坑 |
| docs/实机验证-ESC打断操作.md | 实机演示：人按 ESC 打断正在进行的操作 |
| docs/定案-注入取决于启动上下文.md | 注入失效问题的完整排查记录 |
| docs/ESC急停-实测记录.md | ESC 方案的排查与结论 |
| docs/与Codex的差异清单.md | 与 OpenAI Codex computer use 的逐条对照 |