前言¶
DeepSeek Harness (DSH) 的插件化架構允許開發者擴展 Web GUI 的能力。在調試瀏覽器自動化或遠程運行 Chromium 時，開發者需要一個可視化的窗口來觀察頁面狀態並進行交互。dsh-cdp-live-view 插件在 DSH 的側邊欄中註冊了一個「CDP 實時視圖」標籤頁，通過 Chrome DevTools Protocol (CDP) 將遠程頁面的像素流（JPEG）實時渲染到畫布上，並提供受控的輸入交互功能。
核心功能¶
該插件提供以下核心能力：
- 側邊欄實時視圖：在 DSH Web GUI 的側邊欄註冊標籤頁，將遠程頁面渲染爲實時的 JPEG 像素流，支持 contain-fit 縮放和設備像素比適配。
- 目標管理：自動列出並切換頁面目標（Targets），支持創建新頁面和關閉現有頁面。
- 地址欄導航：支持在地址欄輸入 URL 並回車，提供前進、後退和刷新按鈕。
- 受控交互：支持鼠標點擊、拖拽、滾輪以及鍵盤輸入。輸入通過嚴格的白名單協議（基於 zod discriminated union）發送，確保安全性。
- 雙重控制門控：交互功能受「交互輸入」總開關和標題欄「鍵盤與鼠標控制」複選框的雙重控制，只有兩者同時開啓，視圖纔會進入交互模式。
- 設置面板：支持配置 CDP 地址，並調整截圖質量、幀率、最大寬高等參數。
安裝與啓用¶
使用該插件前，請確保環境滿足以下條件：
* DSH 主進程運行在 Node.js ≥ 20 上。
* 已安裝並啓動支持 CDP 的 Chromium（例如 --remote-debugging-port=9222）。
* 已安裝 dsh-better-sidebar 插件（本插件依賴它）。
安裝命令如下：
dsh plugin --profile web add dsh-better-sidebar dsh-sidebar-cdp-browser
安裝完成後，必須重啓 dsh web 進程以加載插件。
配置與使用¶
插件安裝並重啓後，在 DSH Web GUI 的側邊欄中會出現「CDP 實時視圖」標籤頁。
配置 CDP 地址¶
CDP 地址不在 profile 數組中配置，而是在 Web UI 的設置中配置：
1. 打開 設置 → 側邊欄卡片 → 側邊欄內容 → CDP實時視圖。
2. 點擊該卡片右上角的齒輪圖標。
3. 填入 CDP 地址。留空則默認爲 127.0.0.1:9222。
4. 支持格式包括 host:port、http://host:port、ws://.../devtools/browser/... 等。
5. 保存後，主進程會斷開舊連接並嘗試自動重連。
啓用交互控制¶
要在視圖中操作鼠標或鍵盤，需要同時滿足兩個條件：
1. 在設置面板中開啓「交互輸入」總開關。
2. 在實時視圖的標題欄中勾選「鍵盤與鼠標控制」複選框。
適用場景與注意¶
適用場景¶
- 遠程/無頭 Chromium 可視化：在服務器或容器中運行瀏覽器，通過 DSH 界面查看和操作。
- 觀察自動化過程：在 DSH 會話中實時監控智能體驅動的瀏覽器行爲。
- 輕量級 VNC 替代品：無需安裝額外客戶端的遠程桌面方案。
- 演示與調試：將瀏覽器會話投影給多人，或進行受限的演示。
注意事項¶
- 安全模型：目標頁面永遠不會以 iframe 形式嵌入。CDP 連接由 DSH 主進程獨佔擁有，瀏覽器端無法得知 CDP 地址，因此不存在任意 CDP 透傳漏洞。
- 構建依賴：如果使用 pnpm 構建或安裝插件時遇到原生依賴（如
node-pty）被阻止，請在 profile 的pnpm-workspace.yaml中添加對應的包名到allowBuilds。 - 當前限制：目前尚不支持複製（Copy/Ctrl+C）功能。
- 配置位置：CDP 地址配置存儲在 better-sidebar 的偏好設置中，而非 DSH profile 數組。
總結¶
dsh-cdp-live-view 插件爲 DSH 提供了一個安全、低延遲的瀏覽器可視化方案，特別適合需要在 Web 界面深度調試瀏覽器自動化或遠程監控場景。其嚴格的權限控制和即插即用的特性，使其成爲 DSH 生態中的實用工具。
