前言¶
做瀏覽器自動化時，常見做法是讓 Agent 在一個用戶看不見的 headless 進程裏跑。問題是：頁面發生了什麼、Agent 點了哪裏，用戶都無從確認；遇到需要登錄或人工判斷的環節，也沒有自然的交接手段。
dsh-browser-plus 針對的就是這個問題。它把瀏覽器窗口留在用戶眼前，同時給 Agent 提供可靠的 CDP 操作能力，用戶可以在真實頁面中直接操作，Agent 也能同步執行、接管和恢復任務。
這是什麼¶
dsh-browser-plus 是專爲 DeepSeek Harness（DSH）打造的 EGO 風格可視化 Agent 瀏覽器插件，由 ParticleLight 基於 MIT 許可的 dsh-browser 代碼基礎持續開發並獨立維護，當前版本爲 0.4.1。它是一個真實的 Electron 可視化窗口，不是 headless relay，支持多任務流並行管理與切換，並完整記錄 Agent 的操作軌跡。
核心功能¶
真實可見的窗口¶
瀏覽器基於 Electron WebContentsView 呈現，用戶能直接看到 Agent 正在操作的頁面。輸入、點擊、滾動都發生在真實頁面上。
任務隔離與玻璃工作區¶
所有 DSH session 共享一個可見窗口，但各自保留隔離的任務視圖、標籤與歷史；browser_space 可以爲瀏覽器任務命名。任務與操作軌跡是彼此獨立的半透明玻璃面板，可同時打開，每項任務顯示執行中、等待用戶、用戶接管、失敗或空閒狀態。縮略圖僅在任務面板打開時爲當前可見任務按需刷新，後臺任務保留最後圖像。
頁面 chrome 和任務管理器通過 closed Shadow DOM 注入，不依賴第二個 Electron view。任務狀態與軌跡以版本化增量消息同步，後臺任務更新自己的隔離視圖，不會搶走用戶當前可見頁面。
人機協作與交接¶
工具欄默認隱入頁面上方，頂部中間懸停後展開。用戶可以在工具欄最右側接管任務，也可以顯式把任務交還給 Agent，配合 browser_handoff 完成交接。
真實輸入與工具集¶
鍵盤、鼠標、hover、雙擊和文件選擇都走 CDP，而不是 element.click() 僞事件。插件提供的 browser_* 工具按場景分組：
| 場景 | 工具 |
|---|---|
| 打開與讀取 | browser_open、browser_snapshot、browser_content、browser_screenshot |
| 語義導航 | browser_back、browser_forward、browser_reload、browser_stop、browser_scroll |
| 快照引用 | browser_click_ref、browser_scroll_into_view |
| 頁面交互 | browser_click、browser_press_key、browser_double_click、browser_hover、browser_type |
| 表單與文件 | browser_fill、browser_upload_file、browser_wait_for |
| 任務與交接 | browser_tasks、browser_handoff、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_space |
| 登錄與恢復 | browser_auth、browser_reset_session、browser_history |
恢復能力與穩定基線¶
child 回收後會重新物化相同會話的視圖，恢復後的首張截圖等待 compositor 穩定。版本上固定 Electron 42.9.3；43.4.1 的 compositor 故障會被 resolver 拒絕，避免引入已知問題。可靠性規則包括：不 reparent 可見 WebContentsView，CDP capture 回退只臨時處理同一窗口的 sibling 並保證恢復；對話框、截圖、動態等待和 child recovery 均有迴歸測試與真實 SOAK 覆蓋。
安裝與啓用¶
使用官方安裝命令：
dsh plugin --profile web add github:ParticleLight/dsh-browser-plus
如果機器上已有瀏覽器 bundle，先閱讀倉庫中的 docs/MIGRATION.md 遷移指南，然後重啓 DSH Web 完成啓用。
環境要求：Node >= 22.19。插件固定 Electron 42.9.3，peerDependencies 包含 @deepseek-ai/cordis ^4.0.1。
典型用法¶
快照與引用操作¶
快照返回短生命週期的 snapshotId 與元素引用。推薦的操作順序如下：
- 用
browser_open打開頁面； - 用
browser_snapshot獲取快照與元素引用； - 優先用
browser_click_ref或browser_scroll_into_view操作引用； - 頁面發生變化後重新快照，再繼續操作。
頁面級腳本會自動過濾瀏覽器自身 chrome，不會誤操作插件注入的工具欄。
對話框處理¶
alert、confirm、prompt 會自動接受，避免頁面卡死；下一次頁面操作會把詳情記入 browser_history 的 dialog 條目，Agent 和用戶都能追溯。
工作鏈路¶
從工具到窗口的調用鏈如下：
browser_* tools
-> BrowserRuntime (ctx.browser seam)
-> ElectronBrowserProvider (CDP)
-> RemoteElectronViewHost (loopback JSON-RPC)
-> host-main.js (BrowserWindow + WebContentsView)
開發與驗證¶
需要參與開發時，按以下步驟構建和驗證：
npm install
npm run build
npm test
npm run smoke:electron-host
其中 npm run smoke:electron-host 需要本地 DSH Web 已啓動，用於驗證真實 Electron Host 的導航與頁面交接。完整運行時檢查清單見 docs/SOAK-CHECKLIST.md，貢獻方式見 CONTRIBUTING.md，更完整的使用說明在 docs/README.md。
適用場景與注意事項¶
適合需要在 DSH 中做網頁操作、又希望全程可見、可人工介入的場景，例如需要登錄態的頁面任務、多任務流並行瀏覽、以及用戶與 Agent 交替操作頁面的工作流。
安裝前請注意：
- 插件以當前 dsh 進程的權限運行，安裝前建議檢查倉庫源碼；
- 許可證爲 MIT，詳見倉庫中的
LICENSE與NOTICE.md； - 如果從舊版瀏覽器 bundle 遷移，務必先閱讀
docs/MIGRATION.md。
小結¶
dsh-browser-plus 解決的是 Agent 瀏覽器自動化裏「看不見、管不了、斷線難恢復」三個問題：真實可見的 Electron 窗口、任務隔離與顯式交接、以及 child 回收後的會話恢復。經過上面的步驟即可完成安裝和驗證，更多細節見插件目錄頁與 GitHub 倉庫：
- 目錄頁：https://www.skillhub.cn/plugins/ParticleLight/dsh-browser-plus
- GitHub：https://github.com/ParticleLight/dsh-browser-plus
