前言¶
在 DeepSeek Harness (DSH) 中实现桌面应用的控制，通常需要编写针对特定应用的脚本，或者依赖脆弱的 UI 自动化测试框架。dsh-mac-cua 插件通过 macOS 原生的 Accessibility API，为 DSH 提供了一套通用的 Computer Use 解决方案。它不依赖预定义的 UI 映射，而是通过一个持久的 JavaScript REPL，让智能体以代码形式直接读取和操作桌面元素。
插件介绍¶
dsh-mac-cua 是 Saunato 维护的一个 DSH 插件，核心目标是让智能体能够像人类一样操作 macOS 应用。它将复杂的系统可访问性树转化为可读的文本，并提供了一套 sky API 供智能体调用。
安装与配置¶
安装插件后，需要运行安装脚本以写入必要的绝对路径配置，并授予系统权限。
- 安装插件
使用以下命令安装插件：
dsh plugin --profile web add dsh-cua
- 配置路径
插件安装后，需要执行设置脚本以确保路径正确写入配置文件：
dsh-cua-setup --write
dsh-cua-setup
如果是手动安装或需要覆盖配置，`dsh-cua-setup` 命令可以显示或移除配置行。
-
授予权限
插件运行依赖系统权限，必须在“系统设置”中手动开启：- 可访问性：必须开启。路径：系统设置 → 隐私与安全性 → 可访问性 → 添加并启用 DSH Desktop。
- 屏幕录制：可选。仅在使用截图功能时需要。路径：系统设置 → 隐私与安全性 → 屏幕录制 → 添加并启用 DSH Desktop。
开启权限后，请重启 DSH Desktop。
核心功能¶
插件提供了一套固定且强大的工具集，所有操作都通过 sky 对象实现。
- 读取状态：通过
sky.get_app_state读取任意应用的可访问性树文本。首次读取后，后续读取会返回增量变化（diff），从而节省 Token 成本。支持同时返回截图。 - 执行操作：支持点击（元素或坐标）、输入文本、粘贴、按键组合、滚动、拖拽、选择文本以及调用可访问性动作。
- 图像反馈：可以将读取到的截图重新以图片形式返回给智能体上下文。
使用示例¶
智能体通过 nodeRepl 工具编写 JavaScript 代码，与 sky API 交互。
1. 读取应用状态
var state = await sky.get_app_state({ app: "Finder" });
nodeRepl.write(state.text);
2. 操作元素并读取结果
通过上一步获取的索引进行点击操作，然后再次读取状态：
await sky.click({ app: "Finder", element_index: 42 });
nodeRepl.write((await sky.get_app_state({ app: "Finder" })).text);
3. 读取截图
将截图数据流回对话中：
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 参考¶
以下为 sky 对象的主要方法：
- sky.get_app_state({ app, disableDiff?, screenshot? }): 获取应用状态，返回
{ text, screenshot }。 - sky.list_apps(): 列出所有可访问的应用。
- sky.get_screenshot(): 获取当前屏幕截图。
- 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 }): 粘贴文本，会恢复之前的剪贴板内容。
- sky.scroll({ app, element_index?, x?, y?, direction, pages? }): 滚动页面。
- sky.drag({ app, from_x, from_y, to_x, to_y }): 拖拽操作。
app 参数支持显示名称（如 “Finder”）、Bundle ID（如 “com.apple.finder”）或完整路径。
注意事项¶
- 环境要求：需要 macOS 14.4 或更高版本（支持 Apple Silicon 或 Intel），以及 Node.js 20 或更高版本。
- 索引有效性：
element_index仅对生成该快照时的元素树有效。每次get_app_state都会生成新的索引映射，过期的索引会被拒绝并提示重新读取。 - 输入行为：
type_text会等待键盘焦点并读取字段回显，以确保输入正确。在文本中包含\n会触发 Return 键。 - 剪贴板恢复：
paste操作在执行粘贴后会恢复你之前的剪贴板内容，避免打断你的工作流。 - 代码审查：虽然插件为 MIT 许可证，但在生产环境使用前，建议检查源码以确保符合你的安全与合规要求。
总结¶
dsh-mac-cua 为 DSH 智能体提供了一种基于可访问性 API 的、原生的 macOS 控制方案。通过 JavaScript REPL 和 sky API，开发者可以构建能够处理复杂桌面交互的智能体，适合需要自动化办公、GUI 自动化测试等场景。
- 插件目录: https://www.skillhub.cn/plugins/Saunato/dsh-mac-cua
- 源码仓库: https://github.com/Saunato/dsh-mac-cua
