前言¶
在 DeepSeek Harness（DSH）的沙箱環境中，直接啓動瀏覽器進程往往受限於管道限制（EPERM/EINVAL），導致插件無法正常輸出或通信。同時，常規的視覺驗證方案通常需要調用視覺模型或重複審批，增加了延遲與成本。爲了解決這兩個問題，插件 zaiwenj/dsh-cdp-browser 提供了一種替代方案：通過 CDP 協議操控用戶本地已啓動的瀏覽器，利用 Node 內置的 fetch 和 WebSocket 實現零子進程的自動化與像素級檢查。
插件簡介¶
zaiwenj/dsh-cdp-browser 是一個 DeepSeek Harness 插件，定位爲 Zero-spawn CDP 瀏覽器自動化 + 像素級視覺驗證工具。它驅動已經運行的 Chrome 或 Edge 瀏覽器，不依賴 child_process，也不包含 npm 依賴。由於連接用戶啓動的瀏覽器屬於網絡 I/O，在受限模式下依然可行，且模型無需爲每次視覺檢查再次獲得人工批准。
安裝與啓用¶
安裝該插件需要確保 Node.js 版本在 22.0.0 以上。在終端中執行以下命令將插件添加到 web 配置文件：
dsh plugin --profile web add file:<path>
安裝完成後，重啓 Web GUI，工具欄中會出現 cdp_* 系列命令。
核心功能與工具¶
插件提供了一套命令集，用於管理連接、頁面操作及驗證：
- cdp_status：列出 CDP 瀏覽器的標籤頁/目標及瀏覽器版本。
- cdp_open：打開或複用指定 URL 的標籤頁，並返回目標 ID。
- cdp_eval：在頁面上下文中執行 JavaScript，支持
awaitPromise和returnByValue參數。 - cdp_shot：導航到指定 URL 並保存 PNG 截圖到絕對路徑。
- cdp_assert：結合腳本交互與確定性檢查（像素/CSS/DOM/JS），生成通過/失敗報告。
典型用法：像素與樣式斷言¶
cdp_assert 支持多種檢查類型。以下是一個示例配置，包含相對座標像素檢查、CSS 屬性檢查以及 DOM 文本檢查：
checks: [
{ type: 'pixel', x: 0.5, y: 0.96, color: '#245edb', tolerance: 16 },
{ type: 'css', selector: '#taskbar', property: 'background-color', equals: 'rgb(36, 94, 219)' },
{ type: 'css', selector: '.xp-window', property: 'border-radius', matches: '^\\d+px' },
{ type: 'dom', selector: '.xp-desk-icon', text: 'My Computer' },
{ type: 'js', expression: 'window.__XP.selfTest()', equals: { ok: true } },
]
上述配置中的 checks 數組每一項都支持 click 參數（如 click: '#start-btn'）或 waitMs，用於在檢查前進行交互或等待。
注意事項：確定性與渲染¶
爲了保證測試結果的穩定性，需注意以下幾點：
- 頁面重載：每次測試運行前應重新加載頁面。長期存活的標籤頁會積累狀態（如彈窗、菜單狀態），可能導致腳本在後續運行中失敗。
- 合成點擊：
el.click()會觸發真實的處理程序。對於開關類控件，需確保只點擊一次，避免狀態翻轉。 - 漸變採樣：對漸變背景進行像素檢查時，建議在漸變停止點（stops）附近採樣，而非混合區域，否則可能因容差設置導致誤判。
啓動瀏覽器¶
使用插件前，需手動啓動瀏覽器並開啓調試端口。例如，啓動 Edge 瀏覽器：
msedge.exe --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=<dir> <url>
完成上述步驟後，DSH 即可通過本地端口與瀏覽器通信。
結語¶
zaiwenj/dsh-cdp-browser 解決了在沙箱環境中通過子進程啓動瀏覽器的兼容性問題，並提供了無需視覺模型、無需重複審批的視覺驗證能力。對於需要高確定性且對本地瀏覽器環境有控制權的場景，該插件是一個實用的選擇。
