视觉桌面操作 OrderG-X/dsh-mac-computer-use

给 DSH 的 Mac 桌面操作能力（computer use）。视觉优先，不依赖无障碍树。

一句话：DeepSeek Harness（DSH）插件，让模型看着屏幕操作你的 Mac：列窗口、截图、OCR 找字、点击、打字、按键、滚动、拖拽、打开应用。

什么时候用：「看看我屏幕上有什么」「帮我在这个 App 里点一下」，以及没有命令行、只能用鼠标操作的 Mac 软件。

安装：DSH「插件」页 →「添加插件」，填 dsh-mac-computer-use（npm 包，连不上 npm 会自动换国内镜像），重启 DSH。安装包自带编好的程序（Apple 芯片和 Intel 都能用，macOS 11 起），不用编译。仅 macOS。

English: a DeepSeek Harness (DSH) plugin for computer use on macOS. The model sees the screen and controls the Mac through 11 desktop_ tools: window list, screenshots, OCR text search, click, type, keys, scroll, drag and app launch. Install: on the DSH Plugins page, click Add plugin and enter dsh-mac-computer-use (an npm package), then restart DSH. The package ships prebuilt universal binaries (Apple silicon and Intel, macOS 11+), so there is nothing to compile.

以前叫 dsh-cu，2026-10-18 改名。旧地址会自动跳到这里；底层的命令行引擎仍叫 dsh-cu。
和别人家的 dsh-computer-use 不是一个东西：那个靠无障碍树（cua-driver），这个靠截图。

光标动效

桌面光标：实心蓝箭头 + 带显示器图标的「DSH」名牌，干活时名牌写上正在做什么。跟 dsh-chrome-bridge 的浏览器光标是同一套样式，那边是半透明的、名牌带地球图标。*

11 个 desktop_ 工具 + 一个自包含的 Swift 命令行 + 一个看得见的桌面光标。

desktop_windows desktop_observe desktop_screenshot desktop_find_text
desktop_click desktop_type desktop_key desktop_apps
desktop_launch desktop_scroll desktop_drag

为什么又造一个

DSH 上已有的 computer use 插件（dsh-computer-use、dsh-mac-cua 等）大多依赖 macOS 无障碍树（AX）。
我们实测过：锁屏时 AX 对所有应用都返回 0 个 AXWindow，解锁后立刻恢复正常 —— 这是 macOS 的行为，不是驱动的 bug（详细记录）。另外第三方二进制在某些环境下拿不到 AXWindow。

Codex 那种 computer use 走的是视觉路线：截图 → 模型看 → 按坐标操作。这条路不碰 AX，所以在 AX 不灵的环境下照样能用。这个仓库就是那条路，外加：

| OCR 找文字 | 用 macOS 自带的 Vision 框架，本地跑。desktop_click(text="登录") 直接按文字点 |
| 元素编号 | desktop_observe 把可点元素在截图上编号，模型说"点第 7 个"就行 |
| 做完说一声变了什么 | 点击、输入、按键、拖拽之后顺带回报窗口变化（新开了「存储」窗口、标题变了、窗口关了），模型不用每次再截图确认 |
| 看得见的光标 | 屏幕上有个蓝色光标跟着操作走，名牌写着「点击 发送」这类动作；跟浏览器插件的光标一套样式 |
| 空闲自退 | 光标浮层 60 秒没动静自己走，不留常驻进程 |
| 单文件 Swift | 零依赖，好审计 |

安装

在 DSH 的插件页点「添加插件」，填包名 dsh-mac-computer-use，然后重启 DSH。这是 npm 包：按包名装时，DSH 连不上 npm 官方源会自动改用国内镜像（npmmirror），不经过 GitHub。也可以填发布包地址 https://github.com/OrderG-X/dsh-mac-computer-use/releases/latest/download/dsh-mac-computer-use.tgz，那样要能连上 GitHub。

更新：在「插件」页把它卸载，再按上面添加一次。新版发布后大约一天按包名才装得到（DSH 装插件用的 pnpm 默认不装刚发布的版本），急的话填发布包地址。

安装包里自带编好的命令行引擎和光标浮层（Apple 芯片和 Intel 都能用，macOS 11 起），不用 clone 仓库、不用装 Xcode。第一次用要在系统设置里给 DeepSeek Harness 开屏幕录制和辅助功能权限，设置页里有按钮直达。

装好后插件页里叫「Mac 桌面操作」。点进去是设置页：能不能用、看得到几个窗口，命令行引擎、屏幕录制权限、辅助功能权限、光标浮层逐项打勾，缺哪个就给哪个的按钮（打开系统设置）；还有「屏幕上显示操作光标」开关。

自己从源码编译（改了 Swift 代码时才需要）：

git clone https://github.com/OrderG-X/dsh-mac-computer-use.git
cd dsh-mac-computer-use
./install.sh

需要 Xcode Command Line Tools（xcode-select --install），装到 ~/.dsh/bin/。插件优先用自带的程序，要用自己编的，设环境变量 DSH_CU_BIN=~/.dsh/bin/dsh-cu（光标浮层是 DSH_CU_OVERLAY）。发版时的编译脚本是 tools/build-bin.mjs。

用起来是什么样

你：帮我看看屏幕上有什么 → desktop_windows 拿到窗口列表和坐标 → desktop_screenshot 模型看到图

你：点那个「登录」按钮 → desktop_click(text="登录") OCR 找到它 → 发事件过去（不动你的鼠标）回报「之后：新开了窗口「欢迎」」

你：把计算器的 7+8 算一下 → desktop_observe 截图 + 元素编号 → desktop_click(index=5) 点第 5 个（"7"） → desktop_screenshot 再截一次确认

推荐工作流是 observe → click(index) —— 模型看图上的编号，比算坐标可靠得多。

底层

DSH 工具 (desktop_) ↓ spawn
dsh-cu (Swift 单文件)
├── winlist CGWindowListCopyWindowInfo ← 窗口坐标，零权限 ├── observe AX 枚举可点元素 + 截图标注编号 ├── shot screencapture -l 窗口号 ← 截窗口本身，被挡住也行 ├── find Vision 框架 OCR ← 找文字 → 可点坐标 ├── clickat CGEvent postToPid ← 不移动真实鼠标、不抢前台 ├── type/key CGEvent ← 支持中文 ├── scroll/drag CGEvent └── launch NSWorkspace（后台启动，不抢前台）

后台点击能落进窗口，靠的是两处细节：鼠标事件里填上目标窗口号和窗口内坐标（不填的话 AppKit 和 Electron 都会把事件丢掉）；目标是后台的 Chromium / Electron 窗口（比如 DSH 自己）时，按下那一下带上 ⌘，页面才肯接，松开和 click 本身不带，页面看到的就是普通点击。

截某个应用的窗口时，按窗口号截它本身（screencapture -l）：被别的窗口挡住、在后台都截得到，看到的就是要点的那个窗口；截不到再退回按屏幕区域截。截图、给元素编号、按文字找都是这样（感谢 @Golden-Pigeon 的 PR）。

后台打字同理：先用辅助功能把目标窗口设成它自己的主窗口（不激活应用、不抢前台），按键才有去处；Chromium / Electron 在后台一个按键只收一个字，所以对它们逐字发。后台应用收不到全选、复制、粘贴这类走菜单的 ⌘ 快捷键。

命令行也能单独用：

dsh-cu winlist # 列窗口 dsh-cu tree <pid> # AX 树（解锁状态下可用） dsh-cu observe <pid> # 截图 + 编号 dsh-cu find "登录" # OCR 找文字 → 坐标 dsh-cu clickat <pid> <x> <y> # 点（默认不动真实鼠标） dsh-cu type <pid> "你好" # 输入 dsh-cu selftest # 全链路自检（见 tools/selftest.sh）

光标

cursor/cursor-overlay.swift 是桌面光标浮层（装到 ~/.dsh/bin/dsh-cursor-overlay）：NSPanel，不抢前台、点击穿透、永远置顶，闲 60 秒自己退出。

跟 dsh-chrome-bridge 的浏览器光标是一套样式，一眼分得清是在哪边干活：

| | 桌面（这个仓库） | 浏览器（dsh-chrome-bridge） |
| 箭头 | 同一个形状，实心蓝 | 同一个形状，半透明淡蓝 |
| 名牌 | 显示器图标 + DSH | 地球图标 + DSH |
| 干活时 | 名牌展开成「DSH · 点击 发送」 | 名牌展开成「DSH · 点击 登录」 |

动效走克制路线，两边一样：
- 同一个弹簧、同一套算法：沿轻微的弧线滑过去，顺着速度方向轻轻拉长（最多 7%）、略侧倾，名牌晚半拍跟上；冲过头最多两三像素再落回
- 点击时以箭头尖端为支点缩一下再弹回（瞄准点纹丝不动），一圈淡波纹
- 拖拽时按住（缩一点 + 尖端一圈光晕）跟着走；滚动时右上角亮一下方向
- 闲 6 秒变淡、名牌收起，不挡视线；系统开了「减少动态效果」就不做动画

浮层指令（往 $(getconf DARWIN_USER_TEMP_DIR)dsh-cursor.fifo 写一行，每个账号各自一个）：show x y / move x y / click [n] / down / up / scroll ±1 / label 文字 / hide / ping。

已知限制

- 锁屏时：截图只有壁纸、窗口不渲染、AX 读不到窗口 —— 这是 macOS 的行为，不是工具的问题
- 最小化的窗口、在别的桌面空间（Space）里的窗口：看不到也操作不了，先把它放回当前桌面
- desktop_click 默认投递给目标进程（postToPid）。个别应用不响应投递事件，加 global: true 走系统事件兜底（会移动真实鼠标）
- 桌面点击驱动不了 Chrome —— Chrome 不理会投递的合成事件。操作浏览器请用 CDP 类工具（比如 dsh-chrome-bridge）
- 需要屏幕录制权限（screencapture 用）和辅助功能权限（点击、输入、按键、滚动、拖拽用；没开时系统会静默丢掉这些事件，所以工具会直接报错，不会假装成功）

Field notes

docs/locked-session-and-ax.md —— 锁屏会让 AX 全废这件事，以及为什么它看起来跟驱动 bug 一模一样。这个坑花了一整天才确认。

反馈

遇到问题或想要新功能，提一个 issue。报问题时写上 DSH 版本和插件版本，修起来最快。

License

MIT。tools/dsh-cu.swift 是自包含单文件，想改直接改。

关于光标形状

光标是代码画的（cursor/cursor-overlay.swift 里的 arrowPath），圆角经典箭头 + 蓝色渐变，跟浏览器那边用同一条路径 —— 不包含任何第三方素材文件。