前言¶
瀏覽器自動化工具（如 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 應用進行自動化處理的場景。
