DeepSeek Harness 插件：dsh-vdesktop

前言¶

DeepSeek Harness（DSH）採用插件化架構，允許通過擴展組件增強核心功能。dsh-vdesktop 是其中一款用於解決 GUI 應用交互問題的插件。它利用 Windows 的 CreateDesktopW API 創建一個用戶不可見的 Win32 虛擬桌面，將 GUI 應用運行在隔離環境中。DSH 通過內置的 HTTP 抓幀服務與 JSON-RPC 工具鏈，讓 LLM Agent 能夠操作這些應用，同時爲用戶提供了一個真實的 Web 面板進行監控與接管。

插件簡介¶

該插件由開發者 jafewff 維護，採用 MIT 許可證。它是一個基於 cordis 機制的插件，核心價值在於提供了一套完整的虛擬桌面生命週期管理工具和可視化交互面板，彌合了純命令行智能體與圖形化界面應用之間的鴻溝。

核心功能¶

插件主要包含以下五個方面的能力：

虛擬桌面生命週期管理
支持創建、附着、列出、關閉虛擬桌面。插件會自動清理帶有 dshv- 前綴的“孤兒”桌面，防止資源泄漏。
Agent 工具鏈
提供 12 個 vdesk_* 工具，覆蓋桌面操作、整桌/區域截圖、鼠標操作（點擊/拖拽/滾動）、鍵盤輸入（含中文與 emoji）、文本讀寫及文件存取。
幀數據服務
內置 frameServer（HTTP 服務）。端口從 8790 自動探測至 8799，用於 Web 面板低頻輪詢 PNG 幀數據。響應頭包含光標座標（X-Cursor-X/Y），由前端面板疊加繪製，不燒錄進圖片。
真實語義點擊
面板與 Agent 共享同一執行層。對於標準窗口，通過 WM_NCHITTEST 判別標題欄按鈕；對於自繪窗口，走 postmessage 消息。任務欄按鈕點擊等價於窗口激活或啓動。
進程監督
Python Sidecar 以子進程託管，具備心跳監測、惰性重啓以及空閒回收機制，確保服務穩定性。

安裝與啓用¶

安裝過程需要手動構建或鏈接倉庫，並配置 Sidecar 路徑。

獲取代碼與構建
克隆倉庫並執行構建命令。倉庫自帶 lib/ 構建產物，通常無需重新構建，除非修改了源碼。

    git clone https://github.com/jafewff/dsh-vdesktop dsh-vdesktop
    cd dsh-vdesktop
    npm install
    npm run build

DSH Profile 安裝
在 DSH 的 Web Profile 目錄（例如 C:\Users\<你>\.dsh\profiles\web）的 package.json 中添加依賴。

    "dependencies": {
      "dsh-vdesktop": "link:<本倉庫絕對路徑>"
    }

在 profile 配置中將插件加入 `dsh.profile.bundles`，然後執行 `pnpm install` 並重啓 DSH。

配置 Sidecar 路徑
插件通過 python -m dshv --rpc stdio 啓動 Sidecar。需修改 cordis.patch.yml 或配置文件中的 sidecarCwd，將其指向倉庫內的 sidecar 目錄（絕對路徑）。
安裝後自檢
重啓 DSH 後，通過 curl 驗證服務是否就緒。

    # 驗證桌面列表接口
    curl.exe -s http://127.0.0.1:8790/vdesk/desktops

    # 驗證抓幀接口
    curl.exe -s -o NUL -w "%{http_code}" "http://127.0.0.1:8790/vdesk/frame?desktop=dshv-e2e"

打開 DSH Web GUI，確認 `VDesktopPanel` 出現且畫面正常刷新。

使用說明¶

Web 面板操作¶

在 DSH Web GUI 中使用 VDesktopPanel。用戶可以選擇或創建虛擬桌面，畫面以低頻輪詢方式刷新。點擊畫面上的標題欄（×/最小化/最大化）或任務欄按鈕，操作會直接映射爲真實的窗口管理消息。

Agent 工具調用¶

Agent 可通過工具調用與虛擬桌面交互。

創建桌面與啓動應用：使用 vdesk_desktop_create。注意 launch 是異步的，立即返回 PID 但 windowReady 爲 false，需按 PID 匹配頂層窗口。
輸入操作：由於虛擬桌面非前臺，SendInput 被拒絕，客戶區點擊實際走 postmessage。鍵盤工具支持中文和 emoji。
驗證安裝：可以使用 vdesk_desktop_list 查看桌面列表。

行爲細節與注意事項¶

輸入降級鏈：客戶區點擊走 postmessage，標準窗口標題欄走 WM_NCHITTEST。開始菜單爲“最佳努力”實現，完整操作仍需真實輸入通道。
異步 Launch：應用啓動有延遲，Agent 腳本需等待窗口出現後再進行操作，避免因 PID 匹配失敗導致點擊無效。
光標管理：光標位置由 Sidecar 自維護，每幀點擊後會同步。
端口與 CORS：FrameServer 端口衝突時自動遞增，CORS 白名單默認爲 http://127.0.0.1:3080。
DPI 縮放：插件在 100% 縮放的 Windows 10/11 上實測（源 1920x1080，幀 1280x720）。

總結¶

dsh-vdesktop 爲 DSH 提供了在隔離虛擬桌面中運行 GUI 應用的能力。它通過 12 個工具讓 Agent 能夠讀寫文本、截圖、控制鼠標鍵盤，同時通過 HTTP 服務和 Web 面板解決了可視化與人工接管的需求。安裝時需注意 Sidecar 路徑配置及異步啓動的處理邏輯。