前言¶
浏览器自动化工具（如 Playwright）能很好地操作网页，但无法直接控制非浏览器应用。对于桌面软件（如剪辑工具、设计软件、办公套件），一直缺乏让智能体直接接管的方法。
插件定位¶
dsh-desktop-automation 是一个 macOS 桌面自动化插件。它让 dsh 的 agent 能够直接控制桌面：包括鼠标移动、键盘输入、窗口管理、截图，并整合了一套视觉闭环工作流（截图 → 识图 → 定位 → 点击 → 验证）。插件由 Junkrat9527 维护，采用 MIT 许可证。
安装¶
安装插件需要指定 web profile。可以通过以下三种方式之一完成：
# 方式一：直接安装包
dsh plugin --profile web add dsh-desktop-automation
# 方式二：从 GitHub 安装
dsh plugin --profile web add github:Junkrat9527/dsh-desktop-automation
# 方式三：本地链接安装（开发调试用）
dsh plugin --profile web add link:/path/to/dsh-desktop-automation
核心能力¶
插件注册了 14 个 agent 工具，涵盖权限检查、应用/窗口管理、输入控制、截图与视觉定位。
desktop_perm：检查辅助功能权限与服务状态。desktop_apps：列出当前运行中的应用。desktop_win：列出窗口信息（含坐标与尺寸）。desktop_app：激活指定应用（需应用已运行）。desktop_mouse：移动鼠标。desktop_click：执行点击（支持左/右键及次数）。desktop_drag：拖拽操作。desktop_scroll：滚动操作。desktop_key：模拟按键或组合键。desktop_type：输入文本（支持中文与 Unicode）。desktop_shot：执行全屏或区域截图。desktop_see：识图，描述图片内容或识别 UI 元素（复用 dsh 视觉凭据）。desktop_locate：视觉定位，输出元素的坐标（type/text/box/center）。desktop_stop：停止后台服务。
视觉闭环¶
利用 desktop_see 和 desktop_locate，可以实现完整的 GUI 自动化流程：
desktop_shot → 截图
desktop_see → 识图（文字/UI/内容描述）
desktop_locate → 获取元素坐标
desktop_click → 按坐标点击
desktop_see → 再次截图验证结果
架构说明¶
插件通过本地 socket 与常驻的 CGEvent 服务通信。真正的输入事件由 Swift 服务 desktop-control-server 发出。该服务以 GUI 会话进程运行，用于获取 macOS 辅助功能权限，但不会在开机时自动启动。
典型用法¶
检查服务状态¶
在安装并授权后，可以通过 HTTP 接口检查服务状态：
curl http://127.0.0.1:3080/desktop/status
返回结果示例：
{"status":"up","perm":true,"screen":true}
配置视觉凭据¶
使用 desktop_see 或 desktop_locate 前，需要在 dsh 中配置视觉凭据（OPENCODE_GO_API_KEY）。插件会复用 dsh-autovision 的视觉能力，无需单独配置。
注意事项¶
- 辅助功能权限：首次使用前，需在系统设置中为插件授予辅助功能权限。
- 屏幕录制：截图功能依赖系统
screencapture命令，默认已授权。 - 服务编译：授权后不要重新编译 server，ad-hoc 签名的 CDHash 变化会导致权限失效。
- 应用启动：
desktop_app仅激活已运行的应用。若应用未运行，需先用系统命令open -a "应用名"启动。 - 定位模型限制：
desktop_locate依赖视觉模型。对于复杂的截图，定位可能不稳定，建议裁剪目标区域后重试。 - 登录自启：后台服务为 GUI 会话进程，不会在登录后自动启动，需要时由插件按需拉起。
适用场景¶
- 非浏览器应用操作：通过智能体控制剪映、PS、WPS 等桌面软件进行操作。
- GUI 测试与验收：构建“截图-操作-再截图验证”的自动化测试闭环。
- 远程桌面指挥：在远程环境下通过 dsh 指挥本地 Mac 完成桌面任务。
总结¶
dsh-desktop-automation 为 DeepSeek Harness 插件生态补上了 macOS 桌面控制的一块拼图。它通过 14 个工具和视觉闭环，让 agent 既能“看见”屏幕，也能“动手”操作，适用于对非 Web 应用进行自动化处理的场景。
