前言¶
DeepSeek Harness (DSH) 代理在與網頁交互時，通常缺乏直觀的反饋機制和深度調試能力。開發者需要代理能像人類一樣操作頁面、查看細節，並攜帶上下文與對話。
dsh-browser-annotate 插件解決了這個問題。它通過一個 Electron 桌面應用提供真實的 Chromium 瀏覽器環境，並集成了 Chrome DevTools Protocol (CDP) 訪問權限。插件與桌面應用通過本地 HTTP 循環迴環通信（127.0.0.1:7391），爲代理提供了一套完整的瀏覽器操作工具，同時支持用戶通過右鍵註釋直接向對話注入前端事實。
核心功能¶
插件提供十二種瀏覽器操作工具，覆蓋從基礎導航到複雜交互的全鏈路：
openBrowserPage：在瀏覽器中打開新標籤頁，若目標不可達會返回真實的 Chromium 錯誤。navigatePage：支持 URL 導航、刷新、前進和後退。readPage：獲取頁面可訪問性樹快照，支持通過選擇器範圍限定。screenshotPage：支持視口或元素截圖，並作爲圖片附件返回。clickElement/hoverElement/typeInPage：基於元素引用或選擇器進行點擊、懸停和輸入，支持回車提交。dragElement：通過引擎執行拖拽，若引擎不支持則回退到 Playwright 的dragAndDrop。handleDialog：處理alert/confirm/prompt對話框，不再自動回答。runPlaywrightCode：通過 CDP 在應用 Chromium 上執行自定義 Playwright 函數。cdp：支持調用任何 Chrome DevTools Protocol 方法（如 Input、DOM、Runtime、Network 等）。annotations：讀取和管理用戶創建的註釋隊列。
此外，插件具備以下特性：
- 右鍵註釋與檢查：在瀏覽器中右鍵點擊元素，可快速添加註釋或進入開發者模式檢查 DOM。
- 註釋隊列機制：支持將選中的元素信息（包括 CSS 選擇器、DOM 路徑、截圖、計算樣式等）加入隊列，最後統一注入到對話中。
- 雙欄佈局：左側爲 DSH Web UI，右側爲真實 Chromium 瀏覽器，互不干擾。
安裝與啓用¶
安裝該插件需使用 DSH 的插件命令，該倉庫不作爲 npm 包發佈。
# 安裝插件
dsh plugin --profile web add github:iimaguest/dsh-browser-annotate
# 更新到最新提交
dsh plugin --profile web update dsh-browser-annotate
# 卸載插件
dsh plugin --profile web remove dsh-browser-annotate
安裝後，DSH 啓動時會加載該插件。若未啓動桌面應用，代理調用瀏覽器工具時會收到“桌面瀏覽器未連接”的提示，而不會導致程序崩潰。
使用示例¶
- 啓動桌面應用：在終端運行以下命令啓動 Electron 應用，並傳入 DSH Web UI 的 token 地址。
./dev.sh 'http://127.0.0.1:3090/?token=…'
後續啓動可省略 URL，應用會讀取 `.dev-url` 文件。
- 操作瀏覽器：代理可以使用上述十二種工具對頁面進行操作。
- 管理註釋：用戶可以在瀏覽器中右鍵添加註釋，或使用插件提供的命令管理隊列。
# 列出當前隊列中的註釋（結果附帶截圖）
annotations list
# 將註釋隊列注入到對話輸入框中
annotations inject
# 清除已注入或未處理的註釋
annotations clear
架構與限制¶
插件與桌面應用各司其職：
- 插件端：提供 DSH 側的 HTTP 路由和工具定義，不加載任何 DSH 服務。
- 桌面端：運行真實 Chromium，處理頁面渲染和用戶交互。
已知限制：
- 標籤頁關閉：Electron 應用中的標籤頁關閉需手動操作（快捷鍵
⌘W），代理工具尚未實現自動關閉標籤頁。 - CDP 限制：Electron 不支持
Target.createTarget和Target.createBrowserContextAPI，因此無法通過代理直接創建新的瀏覽器上下文，只能通過openBrowserPage打開新標籤頁。 - 啓動安全：首次啓動 macOS 的 DMG 安裝包時，由於系統安全限制，通常需要右鍵打開或手動在“隱私與安全性”中允許運行。
結尾¶
dsh-browser-annotate 通過將真實的瀏覽器環境、CDP 訪問權限與註釋隊列機制結合，填補了 DSH 在網頁交互和深度調試方面的空白。它既能讓代理像操作員一樣使用瀏覽器，也能讓人類通過直觀的註釋將前端事實直接反饋給智能體。
