Saunato/dsh-mac-cua

dsh-cua

DeepSeek Harness 的 Computer Use。 通过持久化的 JavaScript REPL，从 DSH agent 控制 macOS 桌面应用程序，底层由 macOS Accessibility API 提供支持。

模型获得两个工具——js 和 js_reset——并通过它们驱动一切。没有针对每个动作的工具；工具接口保持固定，而能力存在于 sky API 中。

它能做什么

- 读取任何应用程序的辅助功能树为文本，可选附带截图
- 操作——点击元素或坐标、输入、粘贴、按下组合键、滚动、拖拽、选择文本、设置值、调用辅助功能操作
- 增量工作——首次读取后，树以 diff 形式返回，因此长时间交互在 token 消耗上保持低廉
- 读取截图并将其作为图像返回到对话中

操作通过 element_index 定位元素，该索引来自最近一次状态读取。坐标是后备方案，而非默认方式。

要求

- macOS 14.4 或更新版本（Apple Silicon 或 Intel）
- Node.js 20 或更新版本
- 辅助功能权限——必需；没有它什么都无法工作
- 屏幕录制权限——可选；仅截图时需要

安装

dsh plugin --profile web add dsh-cua

该包以预构建形式发布，因此安装期间不会进行任何编译。将 MCP 服务器注册到你的 profile——它会写入带有此安装绝对路径的补丁行：

dsh-cua-setup --write     # 添加携带此安装绝对路径的 profile 行
dsh-cua-setup             # 检查一切并报告缺失项

该包声明了 dsh.bundle，因此 dsh plugin add dsh-mac-cua 会从包自身的 cordis.patch.yml 挂载 MCP 服务器。该捆绑行无法携带绝对路径——构建包时安装位置未知——也无法从你的 profile 扩展它，因为针对 id 的补丁会整体替换某一行的 config，而不是合并进去。dsh-cua-setup --write 提供绝对路径，而不带参数的 dsh-cua-setup 会报告是否已完成该操作。

捆绑行有意设置 failOnStartupError: false：这样配置错误只会让你失去工具，而不会失去应用程序。Harness 仍能启动。

手动安装，或覆盖该行

没有 bundle 层的安装（例如源码的裸副本）需要一行显式携带绝对路径的配置。dsh-cua-setup --write 会添加一行；--print 显示它而不写入；--remove 将其移除。该行写入 ~/Library/Application Support/dsh-desktop/harness/profiles/web/cordis.patch.yml：

- insert:
- id: mcp-cua
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: cua_repl
transport: stdio
command: node
args:
- '/path/to/dsh-cua/cua-repl/server.js'
cwd: '/path/to/dsh-cua'
env:
DSH_CUA_NATIVE: '/path/to/dsh-cua/native/dsh_cua.node'yaml
toolCallTimeoutMs: 180000
failOnStartupError: true

该行必须嵌套在 insert: 下。顶层的 - id: 行是对现有条目的覆盖，加载器会以
entry "mcp-cua" not found 拒绝它。

然后授予辅助功能权限，以便测试框架能够读取和操作应用 UI：

系统设置 → 隐私与安全性 → 辅助功能 → 添加并启用
DSH Desktop

如需截图，还需授予：

系统设置 → 隐私与安全性 → 屏幕录制 → 添加并启用
DSH Desktop

授予任一权限后，请重启 DSH Desktop。

通过智能体进行验证：

Use mcp__cua_repl__js to run (await import("node:fs")).existsSync ? "ok" : "ok"

或让它读取某个应用的状态。权限问题会报告确切的设置路径，而不是静默失败。

配置

该捆绑包附带以下行，用于挂载 MCP 服务器。dsh-cua-setup --print
会显示带有绝对路径的同一行，供手动安装使用：
yaml
- insert:
- id: mcp-cua
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: cua_repl
transport: stdio
command: node
args:
- '/path/to/dsh-cua/cua-repl/server.js'
cwd: '/path/to/dsh-cua'
env:
DSH_CUA_NATIVE: '/path/to/dsh-cua/native/dsh_cua.node'
toolCallTimeoutMs: 180000
failOnStartupError: true

serverName 决定工具前缀，因此这些工具会显示为
mcp__cua_repl__js 和 mcp__cua_repl__js_reset。

附带的行使用相对于配置文件目录的路径，因此适用于
任何安装位置。要更改某项设置，请向你的配置文件补丁中添加一个覆盖行——
- id: mcp-cua 加上你希望有所不同的字段。

用法

智能体编写 JavaScript。状态在调用之间保持。
js
// Read state. sky is injected as a global — do not import it.
var state = await sky.get_app_state({ app: "Finder" });
nodeRepl.write(state.text);
js
// Act on an element by its index, then read state again.
await sky.click({ app: "Finder", element_index: 42 });
nodeRepl.write((await sky.get_app_state({ app: "Finder" })).text);
js
// Read a screenshot back into the conversation.
const fs = await import("node:fs/promises");
const { fileURLToPath } = await import("node:url");
var state = await sky.get_app_state({ app: "Finder" });
if (state.screenshot) {
await nodeRepl.emitImage({
bytes: await fs.readFile(fileURLToPath(state.screenshot.url)),
mimeType: "image/png",
});
}

API
ts
sky.get_app_state({ app, disableDiff?, screenshot? })  // -> AppState
sky.list_apps()                                       // -> App[]
sky.get_screenshot()                                  // -> { url, note }

sky.click({ app, element_index?, x?, y?, mouse_button?, click_count? })
sky.set_value({ app, element_index, value })
sky.select_text({ app, element_index, text, prefix?, suffix?, selection_type? })
sky.perform_secondary_action({ app, element_index, action })
sky.type_text({ app, text })
sky.press_key({ app, key })
sky.paste({ app, text, format })     // "text" | "md" | "html"
sky.scroll({ app, element_index?, x?, y?, direction, pages? })
sky.drag({ app, from_x, from_y, to_x, to_y })

app 接受显示名称、bundle 标识符或完整路径：
"Finder"、"com.apple.finder"、"/Applications/Safari.app"。

值得了解的行为

元素索引仅对生成它们的快照有意义。
每次 get_app_state 都会发布一张全新的映射表，并使之前的映射表失效。过期的
索引会被拒绝，并返回一条消息告知模型重新读取——它绝不会被应用到当前占据该
位置的任何元素上。

paste 会恢复你的剪贴板。 它会写入剪贴板，按下 Cmd+V，
然后把你之前的剪贴板内容放回去。

type_text 中的 \n 会按下 Return 键，这会在许多应用中提交表单并发送消息。对于多行文本，请使用 paste。

输入会等待键盘焦点并回读该字段，因此不匹配会被报告出来，而不是被静默丢失。

架构

DSH agent
│  mcp__cua_repl__js { code }
▼
dsh-mcp-client  (ships with DSH; mounted by this package's dsh.bundle)
│  MCP over stdio, newline-delimited JSON-RPC
▼
cua-repl/server.js        (MCP server: js, js_reset)
│
cua-repl/repl.js          (persistent vm context, completion values)
│
lib/sky.js                (the sky API)
│
native/dsh_cua.node       (Swift accessibility core + C N-API binding)
│  Accessibility API · CGEvent · ScreenCaptureKit · NSWorkspace
▼
macOS applications

| 层 | 职责 |
|---|---|
| native/axcore.swift | AX 树遍历、元素索引、文本渲染、差异比较 |
| native/actions.swift | AX 操作、索引解析、焦点处理 |
| native/input.swift | CGEvent 按键和鼠标、保留剪贴板的粘贴 |
| native/screenshots.swift | ScreenCaptureKit 截图、应用枚举、窗口几何信息 |
| native/abi.swift | 由绑定消费的 JSON C ABI |
| native/addon.c | N-API 绑定；每个操作都在工作线程上运行 |

没有任何地方使用 AppleScript、JXA 或 System Events——它们走的是不同的权限
路径，行为也不一致。

从源码构建

包中附带了一个预构建的 native/dsh_cua.node，因此只有在编辑 Swift 源码之后，
或者当该二进制文件与你的平台不匹配时，才需要执行此操作。
sh
node scripts/build-native.js

需要 Xcode Command Line Tools 和 Node 头文件。当头文件不在你的 Node 二进制文件旁边时，请显式指定其路径：
sh
NODE_INCLUDE=/path/to/include/node node scripts/build-native.js

Swift 源码使用 -wmo 编译；否则跨文件引用内部符号将无法解析，因为 swiftc 在增量构建时会为每个输入文件生成一个目标文件。

测试
sh
node test/run-tests.js    # native module, against a controlled host app
node test/mcp-tests.js    # MCP 服务器，通过真实的 stdio 协议
node test/setup-tests.js  # setup 命令、bundle 补丁和 profile 编辑

共 78 个测试。原生测试套件直接测试每个公开的 sky 方法，
包括那些容易被遗漏测试的方法——select_text 的插入符模式
及其 prefix/suffix 消歧，以及 paste 的剪贴板恢复。

原生测试套件仅针对专门构建的宿主应用程序（test/host.swift）执行写操作，
绝不针对你的真实应用或数据。针对真实应用程序的检查是只读的。

故障排除

工具未出现。 先运行 dsh-cua-setup：它会报告依赖项、bundle 层、
原生模块和权限是否各自就位，并指出修复方法。配置组合失败会报告
entry "" not found，这意味着某一行被写成了裸的 - id:
覆盖，而不是嵌套在 insert: 下。

"Accessibility is NOT available"（辅助功能不可用）。 在
隐私与安全性 → 辅助功能下将其授予 DSH Desktop，然后重启 DSH Desktop。

截图为 null。 阅读 state.screenshotNote。它会区分三种
原因：屏幕已锁定（macOS 阻止对锁定会话进行捕获）、
显示器处于睡眠状态（没有活动显示器），或未授予屏幕录制权限。只有
最后一种需要更改设置。

屏幕锁定时截图仍会返回？ 按设计不会——说明中已写明。
基于辅助功能的操作不受影响。

点击未生效。 树可能已过期，或者该元素未暴露
AXPress。结果消息会说明使用了哪条路径，点击会自动
回退到元素的中心点。

某些应用暴露的辅助功能树很差。 游戏、画布编辑器和某些
Electron 应用。获取截图并回退到坐标；agent 被
指示在不得不以这种方式工作时告知你。

安全性

此插件赋予 agent 读取和操作你的桌面 UI 的能力——这与屏幕阅读器
拥有的访问权限属于同一类。将辅助功能授予 DSH Desktop
意味着 harness 生成的任何进程都能控制你的 Mac。仅当你
打算使用 Computer Use 时才授予它。

instructions/computer-policy.md 指示 agent 在具有外部副作用的
操作前进行确认：删除数据、发送消息、提交
表单、金融交易、安装软件、更改系统设置，以及
传输敏感数据。该策略是提示词级别的指导，而非内核
强制边界——请将 agent 视为一个能在你的机器上行动的有能力的助手，
而不是一个沙箱化的助手。

许可证

MIT