前言¶

DeepSeek Harness (DSH) 的設計理念是“一切皆插件”。在開發桌面智能體時，需要直接操作 Windows 窗口或應用是常見需求。dsh-computer-use 是一個工作流插件，它將 Codex 的原生 Windows Computer Use 能力接入 DSH，通過 stdio JSON-RPC 協議驅動本機已安裝的 codex-computer-use.exe。

它不做像素級識別：使用 UI Automation 可訪問性樹來“看”窗口，使用 SendInput 輸入注入來“動”窗口。底層複用 Codex 原生助手，不重新實現一遍 Win32 交互。

前置條件¶

1. 本機必須已安裝 Codex 桌面版（codex.exe 和 codex-computer-use.exe 由它提供）。
2. 環境需要安裝 Node.js，版本要求爲 ^22.19.0 || >=24.0.0。

安裝¶

在項目的 package.json 中添加依賴，並在 DSH 配置中引入該 bundle。

{
  "dependencies": {
    "dsh-computer-use": "github:gxpppp/dsh-computer-use"
  },
  "dsh": {
    "profile": {
      "bundles": [
        // ... 其它 bundle
        "dsh-computer-use"
      ]
    }
  }
}

安裝完成後，重啓 DSH 以加載插件。配置寫入 cordis.patch.yml 後也需要重啓 DSH 生效。

核心功能¶

插件提供以下核心能力：

• 應用/窗口枚舉：只讀操作，用於識別當前桌面上的應用或窗口。
• 可訪問性樹 + 元素索引：通過 UI Automation 樹獲取界面結構，輔助定位元素。
• 輸入注入：支持點擊、輸入、按鍵、滾動和拖拽操作。
• 剪貼板粘貼：支持中文及長文本的粘貼。
• 截圖：
  • Windows 11：使用原生 WGC（Windows Graphics Capture）。
  • Windows 10：使用 PrintWindow 兜底。
• 窗口故障自愈：處理窗口最小化、幾何變化或句柄失效等情況。
• 等待原語：等待特定文本出現/消失或窗口關閉。
• 桌面鎖定探測：主動探測桌面鎖定狀態，避免模型誤判。

工具使用¶

插件通過 6 個工具暴露能力：

1. computer_use_status
   自檢工具，用於定位 helper 進程、檢查截圖能力、查看已授權應用及免審批白名單。支持 action="reset" 清空授權並重啓 helper。
2. computer_use_apps
   枚舉應用或窗口（只讀）。
3. computer_use_state
   獲取窗口快照，包含可訪問性樹（含索引與焦點）、截圖或兩者。
4. computer_use_act
   執行單個動作（含 paste_text），默認自動刷新並回傳新狀態。
5. computer_use_wait
   等待界面就緒，支持等待文本出現/消失或窗口關閉。
6. computer_use_launch
   啓動應用並輪詢等待窗口出現。

授權模型¶

每個應用在被操作之前，都需要獲得一張授權票。票只有兩個來源，按順序檢查：

1. 免審批白名單：在配置的 alwaysAllowedAppIds 中匹配應用名。
2. 審批彈窗：走 DSH 的 approval.request()，必須返回 allowed-once。

配置白名單¶

白名單配置寫在 cordis.patch.yml 中：

# cordis.patch.yml
- id: computer-use
  disabled: false
  config:
    alwaysAllowedAppIds:
      - mspaint.exe
      - msedge.exe

注意：配置寫完後必須重啓 DSH 才能生效。不建議通過 GUI 設置頁配置，因爲部分 DSH 版本的設置面板與插件讀取的配置對象可能不同步。

注意事項¶

• 權限與授權：每個應用在被操作前都需要授權。如果是首次操作某個應用，請確保 DSH 的 approval 策略爲 ask，否則彈窗不會出現。
• Win10 性能：在 Windows 10 上，截圖功能可能較慢（約 1–3 秒/張）且無法讀取硬件加速窗口。建議在配置中設置 allowScreenshots: false。
• 瀏覽器與終端限制：瀏覽器窗口自動化和終端類應用目前受到策略限制，無法直接操作。

結語¶

該插件通過複用 Codex 原生能力，爲 DSH 提供了標準化的桌面控制接口。開發者可以通過標準的 DSH 工具進行狀態獲取、界面等待和動作執行，從而構建更復雜的桌面自動化工作流。

詳細信息請查看 catalog 頁面 或 GitHub 倉庫。