桌面操控 Admaing/dsh-plugin-computer-use

dsh-plugin-computer-use

为 DeepSeek Harness 提供 Codex 风格的 computer use。

插件注册一个面向模型的工具 computer，它的动作词汇表和批量调用约定与 OpenAI 的 computer 工具一致。模型发送一批有序动作，插件在真实桌面上执行，然后返回一张新截图，外加一份精确的执行记录——所以已经熟悉这套接口的模型不需要学任何新词汇。

在 macOS 上，输入事件由一个小型 Objective-C 辅助程序发送，首次使用时从源码编译；没有编译器的机器则回退到 AppleScript。

┌─────────────┐ actions[] ┌──────────────────────────────────────┐
│ model │ ─────────────► │ computer tool │
│ │ │ normalize → map coords → post input │
│ │ ◄───────────── │ capture → commit → render │
└─────────────┘ screenshot + └──────────────────────────────────────┘
executed[] │ │
│ CGEvent │ screencapture
▼ ▼
the desktop the screen

它能做什么

| 动作 | 字段 | 效果 |
| screenshot | — | 观察。无论批次内容如何，结果截图都在批次结束后拍摄。 |
| click | x、y、button?、keys? | 移动并点击。button 取 left（默认）、right 或 middle。 |
| double_click | x、y、keys? | 按平台的双击语义点击两次。 |
| move | x、y、keys? | 移动指针，不点击。 |
| drag | path、button?、keys? | 在第一个点按下，沿路径移动，在最后一个点松开。 |
| scroll | x、y、scroll_x、scroll_y、keys? | 在某个点滚动。scroll_y 为正表示向下滚动。 |
| keypress | keys | 组合键，例如 ["CTRL","C"] 或 ["ENTER"]。 |
| type | text | 输入字面文本，包括空格和换行。 |
| wait | — | 暂停（时长来自配置，默认 2 秒）。 |

动作集合、字段名、scroll 的正负号约定都与参考实现保持一致，所以批次可以在不同 harness 之间通用。

安装

from a checkout
dsh plugin --profile <profile> add /path/to/dsh-plugin-computer-use

or once published / from git
dsh plugin --profile <profile> add dsh-plugin-computer-use

然后给需要这个工具的智能体预设加一行。复制一份随部署发布的预设再改副本——绝不要直接改随部署发布的预设：

- id: tool-computer-use
name: dsh-plugin-computer-use
config:
display: 0

完整的一行配置（含所有选项）见 examples/agent.cordis.yml；预设如何被发现和挂载见 dsh-agent-presets。

权限

macOS 会同时拦截这个工具的两部分权限，缺了任何一个，工具就直接拒绝运行，而不是莫名其妙地失败。把这两项权限都授予承载智能体的应用：

| 权限 | 用途 | 位置 |
| 屏幕录制 | 每一次截图 | 系统设置 → 隐私与安全性 → 屏幕录制 |
| 辅助功能 | 每一次点击、按键和滚动 | 系统设置 → 隐私与安全性 → 辅助功能 |

有两个细节值得了解：

- 没有辅助功能权限，截图照样能用。 这两道权限相互独立，所以在没有授予辅助功能的机器上，只跑 screenshot 的批次依然能成功。这是安全子集，单独用也很有价值。
- 没有辅助功能权限，输入事件会被静默丢弃。 CGEventPost 报告成功，macOS 却把事件丢掉。正因如此，工具会预先检查权限，而不是轻信调用结果：跳过检查的智能体会点进虚空，看到屏幕毫无变化，然后永远循环下去。

运行 doctor，看看你究竟处在什么状态：

npx dsh-computer-use-doctor --test-input

platform darwin (arm64)
backend native

displays
[main] display 0 1470x956 pt 2940x1912 px 2x origin (0, 0)

permissions
[FAIL] Accessibility — post clicks and keystrokes add the host application under System Settings > Privacy & Security > Accessibility [OK ] Screen Recording — capture the screen

capture
[OK ] main display: 2940x1912 px PNG

input delivery
[FAIL] posted events are being discarded

--test-input 会把光标移动 40 点，确认它确实跟过去了，再移回原位——权限标志只是断言，光标动了才是证据。

模型要求

每个结果都带截图，所以调用链路必须声明图像输入。工具动手之前会先检查这一点，遇到读不了图的模型就直接拒绝，免得白白浪费一次截图：

Error: the computer tool returns screenshots as images, but model "…" does not declare image input. Switch to an image-capable model, or set requireImageCapableModel: false to run it blind.

在显式声明模型的服务商上，这个声明不会自动生效。通过 llm-pi-ai 配置的服务商，会把每一个模型默认设成 input: ["text"]，所以一个从不声明自己模态的视觉模型会被当成纯文本模型——这个工具和 read_image 都会拒绝。在模型条目上写明模态：

llm-pi-ai:
providers:
<provider>:
models:
- id: some-vision-model
name: some-vision-model
input: [text, image] # without this the model reads as text-only

把 requireImageCapableModel: false 当作逃生舱也行，但它并不能让模型看见：截图照样会拍下来并返回，模型只是用不了。还是声明模态更好。

配置

| 字段 | 默认值 | 含义 |
| enabled | true | 是否注册该工具。 |
| backend | "auto" | auto、native 或 applescript。auto 优先用 native，失败后降级。 |
| display | 0 | 驱动哪块显示器（从 0 开始，主显示器排第一）。 |
| maxActionsPerCall | 25 | 单批动作数量上限。 |
| waitMs | 2000 | wait 动作的时长。 |
| settleMs | 250 | 输入之后、结果截图之前的停顿。 |
| allowedActions | null | 动作类型的允许列表；null 表示全部放行。 |
| invertScroll | false | 翻转滚动的正负号约定。 |
| helperCacheDir | null | 编译后 helper 的缓存位置。 |
| requireImageCapableModel | true | 调用方路由看不到图像时拒绝运行。 |

未知字段会被拒绝，而不是忽略：组合配置里写错一个字段，不能让部署方误以为自己关掉了某项功能，实际却没关。

锁定权限

计算机操作能力很强，而截图是攻击者可控的输入。有两个配置项真正起作用：

- id: tool-computer-use
name: dsh-plugin-computer-use
config:
Read-only: the model can look at the screen but never touch it.
allowedActions: [screenshot, wait]

- id: tool-computer-use
name: dsh-plugin-computer-use
config:
No clicking, no typing: move and scroll only.
allowedActions: [screenshot, move, scroll, wait]

插件还会注册一段系统提示词，指示模型把屏幕上的内容当作不可信输入，操作后要验证，遇到难以撤销的操作要先确认。提示词只是引导，不构成强制边界——允许列表才是。

工作原理

坐标空间

这里涉及三种空间，把它们混为一谈就是计算机操作类工具的经典 bug：

| 空间 | 含义 |
| 图像空间 | 模型实际收到的 PNG 像素——附件服务可能把大尺寸截图缩小 |
| 像素空间 | 磁盘上截图的像素，也就是显示器真实的后备分辨率 |
| 点空间 | CGEvent 投递到的全局左上原点空间；Retina 显示器的像素数是点数的两倍 |

模型在图像空间里测量，helper 在点空间里投递。插件按智能体保存上一次返回截图的几何信息，把每个传入坐标都从这套信息里换算出来——模型自己永远不用做缩放，结果文本里也总会写明比例，方便核对：

screenshot 2940x1912 px · display 1470x956 pt · backing scale 2x · 1 screenshot px = 0.5x0.5 display pt

截图被视为后备像素的权威依据，因为显示器跑缩放版 Retina 模式时，CGDisplayPixelsWide 报的是点尺寸。

为什么 helper 要编译，为什么截图不走它

helper 首次使用时从源码编译，并按源码摘要缓存。选择编译而不是直接发二进制，是为了让包跨架构可移植，也避免下载未签名 blob；一次大约耗时 0.6 秒。如果 ~/Library/Caches 不可写，就回退到系统临时目录，而不是丢掉原生后端。

这个回退有代价，值得了解，因为辅助程序的路径就是权限身份：macOS 把辅助功能授权绑定到二进制文件，而不是绑定到工具。系统临时目录会被无预警回收，所以针对那里的辅助程序做出的授权，之后会静默失效。doctor 会打印目录和确切的二进制文件，当目录是易失目录时还会说明：

helper cache /var/folders/…/T/dsh-plugin-computer-use (volatile) the system reclaims this directory, so an Accessibility grant made against /var/folders/…/T/dsh-plugin-computer-use/computer-helper-27836c7760923b3c stops working once it does. Set helperCacheDir to a stable path, for example ~/Library/Caches/dsh-plugin-computer-use, and start a new session.

当宿主机无法写入用户缓存时，把 helperCacheDir 设为稳定路径——比如只允许在工作区内写入的沙箱。

截图走系统的 screencapture 二进制文件，不走辅助程序，因为 CGDisplayCreateImage 从 macOS 15 起已废弃（ScreenCaptureKit 取代了它）。截图是这个工具里最容易在后续版本中失效的部分，所以它依赖 Apple 维护的工具。精确的像素尺寸从 PNG 自身的 IHDR 块读取——不用图像库，也不靠猜测。

后端

| 后端 | 输入 | 显示器 | 需要 |
| native | 完整动作集，精确 | 全部，原点正确 | Xcode Command Line Tools（clang） |
| applescript | 仅 click、keypress、type、wait | 仅主显示器 | macOS 之外无需其他 |

auto 优先用 native，工具链缺失时降级到 AppleScript，因为能用的缩减后端胜过硬失败。显式写 backend: native 会被严格遵从——编译失败会报告，不会悄悄降级。auto 降级时，原因会带在解析出的后端上，方便诊断解释。

开发

npm install # fetches @deepseek-ai/dsh-tools, needed by the schema suites
npm test # 108 tests: pure logic + a real compile of the native helper
npm run doctor # check permissions on this machine
npm run smoke # drive the real tool once and write the screenshot to .scratch/

还有两项检查会驱动工具操作本机并读回结果，所以坐标映射或输入路径出现回归时会大声失败，而不是生成一张看似合理的截图：

npm run check:input # move the cursor, read it back, compare against the mapping
npm run check:click-type # click and type into a scratch document, then read the text
npm run check:scroll # scroll a document and read which way the view moved
check:input 会自我验证：它用辅助程序在前后各读一次光标，所以缩放系数错了，读出的坐标就会错。check:click-type 需要一个获得焦点的 TextEdit 窗口，否则直接跳过，不会往当前持有焦点的其他窗口里点。check:scroll 向 Accessibility API 查询 TextEdit 文档的可见字符范围，这是唯一能分辨向下滚动和向上滚动的办法——截图看不出视图往哪个方向移动。之所以有这个检查，是因为滚动方向的正负号曾经反过一次，而当时没人发现。

不碰 harness 包的测试套件，即使没跑 npm install 也能运行；工具 schema 相关的套件会自己跳过并给出说明，而不是报错。

src/
index.js the Cordis plugin: registers the tool and the prompt section
tool.js the computer tool, coordinate state, permission gates
actions.js the action vocabulary, schema, and canonicalisation
keys.js Codex key/button names → canonical macOS names
geometry.js image space ↔ display point mapping
png.js PNG IHDR reader
config.js defaults and validation
prompt.js the system-prompt policy
exec.js subprocess helper with timeout and cancellation
backends/
index.js backend selection
native.js compile, probe, act, capture
applescript.js the reduced fallback
native/
computer_helper.m the Objective-C helper

验证环境

macOS 26.0.1（arm64），Node 24，接了两台显示器。原生辅助程序能编译，能探测两台显示器，能对一块 1470×956 点的 Retina 屏截出 2940×1912 的 PNG，并且会报告：在未授予 Accessibility 权限时，输入事件会被丢弃——在一台还没授权的机器上，这就是正确答案。

安全

这个工具操作用户真实的桌面，用的是用户真实登录的应用。它不是沙箱，也不假装自己是。

- 截图和窗口内容都是不可信输入。提示词里写明了这一点，但模型可能出错；真正的强制点在 allowedActions 白名单。
- 屏幕上任何东西都能碰到，包括用户的邮件、银行和终端。
- 辅助程序是从本仓库源码编译出来的本地二进制文件。它没有用 Developer ID 签名，所以除了你授予的权限之外，它没有任何特殊信任。

许可证

MIT —— 见 LICENSE。