前言¶
在 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
