dsh-cua：DeepSeek Harness 的計算機控制插件

2026-10-04

前言¶

DeepSeek Harness（DSH）採用插件化架構。讓智能體操作電腦是一個常見需求。dsh-cua 提供了這一能力。

是什麼¶

這是一個計算機控制插件，由 cua-driver daemon（trycua）提供支持。它封裝了 14 個模型工具，走 DSH 原生註冊、審批面板和圖片附件體系，不依賴 MCP。

工作方式¶

一次工具調用 = spawn 一次驅動 CLI（stdin 送 JSON、stdout 收 JSON），實際狀態常駐本地 daemon 裏。尋址優先級：1. 優先 element_token。像素座標用於 canvas/視頻等非 UIA 區域。非法參數組合在插件層直接拒絕，不會發出任何輸入。

功能¶

• cua_status：驅動 daemon 是否在線；離線附啓動指引
• cua_list_windows / cua_list_apps：頂層窗口清單（pid / window_id / 標題 / 邊界）；運行中與已安裝應用清單
• cua_window_state：指定窗口的無障礙元素樹快照：結構化 elements（element_token/role/label/frame）+ Markdown 樹 + 窗口截圖
• cua_desktop_screenshot：主屏全屏截圖（真實物理像素）
• cua_zoom：放大窗口截圖的局部區域（小字號 / 密集控件）
• cua_verify_state：操作後斷言驗證：元素存在/啓用/選中/值相等、窗口邊界（容差 px）；結果三態 satisfied / unsatisfied / unknown，unknown 永不當作成功
• cua_click / cua_type_text / cua_press_key / cua_hotkey / cua_scroll：點擊（左/右/中、雙擊三擊）、輸入文本、按鍵、組合鍵、滾動——目標可以是元素 token、窗口像素或桌面座標
• cua_set_value：經無障礙 SetValue 直接給控件賦值（比逐字鍵入可靠，寫入後回讀校驗）
• cua_bring_to_front：把窗口帶到前臺（後臺投遞路徑通常用不到）

安裝與啓用¶

前置條件：一個帶 profile 的 DSH 部署；驅動 daemon 在線。

dsh plugin --profile web add github:hfloveyy/dsh-cua

重啓 dsh web 後驗證：

dsh --profile web --dump-config

在對話裏讓 agent「列出當前所有窗口，截個圖看看桌面上有什麼」即爲通。

配置¶

在 profile 的 cordis.patch.yml 按 id 覆蓋：

- id: cua
  config:
    requireApproval: true   # 每個動作前彈審批面板（false 可關閉插件層審批）
    disabled: false         # true = 不註冊任何工具
    timeoutMs: 15000        # 工具協作式超時（2000–120000）
    maxElements: 200        # 單次快照轉發的元素上限（20–5000）
    maxRows: 120            # list_windows/list_apps 單次轉發行數上限（10–1000）
    binDir: ""              # 自定義驅動二進制目錄；留空按優先級解析

安全與限制¶

安全採用雙層閘門。插件層：七個動作類工具經 tools/pre-execute 返回 ask 決策。驅動層：daemon 維護 permission mode（standard / bounded / unrestricted）、session 授權租約、capability manifest 與 revoke 命令。

已知限制：
- 插件自帶二進制的平臺：Windows x64；macOS 與 Linux 走全局驅動（上游 install.sh）。
- 多顯示器暫只覆蓋主屏（跟隨上游當前版本行爲）。
- 驅動的瀏覽器 CDP 工具組（browser_navigate / browser_click 等）與應用生命週期組（launch_app / invoke_menu）尚未註冊。

結尾¶

dsh-cua 爲 DSH 提供了元素級的計算機控制能力。適合需要智能體操作桌面應用的開發者。安裝前請檢查源碼與許可證。