前言¶
DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”。在智能體開發中，有時需要讓模型直接操作瀏覽器環境。dsh-browser 插件通過一個配套的 Chrome/Edge MV3 擴展，將 DSH 與用戶的瀏覽器標籤頁連接起來，使其能夠讀取頁面內容並執行交互操作。
組件與架構¶
該插件在生產環境中採用三層架構，通過 WebSocket 和原生消息通信：
- DeepSeek Harness：運行在 DSH 環境中，提供
browser_*工具和 Web 設置卡片。 - Native Messaging Host：本地可執行文件，負責驗證擴展 ID、轉發消息並完成身份認證。
- Chrome/Edge MV3 擴展：安裝在瀏覽器中，負責觀察頁面、顯示控制狀態並執行具體的瀏覽器動作。
安裝與啓用¶
安裝該插件需要滿足前置條件：Node.js 22.19 或更新版本，以及安裝了支持 MV3 和原生消息的 Chrome、Chromium、Edge 或 Brave 瀏覽器。
1. 安裝 Harness 插件¶
將插件安裝到 Web 配置文件中：
dsh plugin --profile web add github:justwe-bot/dsh-browser
2. 準備擴展目錄¶
執行安裝包內的腳本，將擴展打包到 DSH_HOME 下：
dsh plugin --profile web exec dsh-browser-native-install --prepare-extension
該命令會打印擴展目錄的路徑，通常爲 $DSH_HOME/browser-extension。
3. 獲取擴展 ID¶
- 在瀏覽器中打開
chrome://extensions（或 Edge/Brave 的對應頁面）。 - 開啓“開發者模式”。
- 點擊“加載已解壓的擴展程序”，選擇上述命令打印的目錄。
- 複製顯示的 32 位字符擴展 ID。
4. 安裝原生消息主機¶
使用獲取到的 ID 安裝原生主機：
dsh plugin --profile web exec dsh-browser-native-install \
--extension-id <extension-id> \
--browser chrome
這會將主機可執行文件寫入 $DSH_HOME/browser-native-host/，並生成配置文件 browser-native-host.env。
5. 啓動 Harness¶
在啓動 Harness 的 shell 中加載生成的環境變量：
source ${DSH_HOME}/browser-native-host.env && dsh web
6. 配置與驗證¶
- 打開 DSH 的 Settings > Plugins > Plugin configuration > DSH Browser。
- 在擴展彈窗中確認狀態顯示爲 Connected。
- 詢問智能體列出瀏覽器標籤頁以驗證連接。
工具列表¶
插件默認註冊以下工具，可在 Agent 的工具目錄中使用：
- 觀察：
browser_list_tabs（列出標籤頁）、browser_snapshot（獲取快照）、browser_wait（等待）。 - 標籤頁與導航：
browser_new_tab（新建標籤頁）、browser_navigate（導航）、browser_back、browser_forward、browser_reload。 - 頁面操作：
browser_click（點擊）、browser_type（輸入）、browser_scroll（滾動）、browser_key（按鍵）。 - 腳本評估：
browser_evaluate。若不需要該工具，可在配置中設置browser-tools.config.enableEvaluate: false。
注意事項¶
- 直接模式（Direct mode）：該模式僅用於本地開發和診斷，不適用於生產環境。
- 權限限制：模型工具無法激活標籤頁或聚焦瀏覽器窗口。
browser_new_tab總是打開後臺標籤頁。 - 頁面限制：僅支持 HTTP/HTTPS 頁面。不支持瀏覽器內部頁面、擴展頁面以及
file:URL。 - 元素引用：快照中的元素引用僅在當前快照的
documentId下有效，導航或文檔替換後引用會失效（返回STALE_REF）。 - 審批機制：突變工具（如點擊、輸入）在默認
workspace-write權限下需要審批。在danger-full-access策略下無需提示，但仍受 HTTP/HTTPS 限制。 - 環境變量：DSH 會拒絕從
$DSH_HOME/.env加載敏感的DSH_*變量，必須通過專用的.env文件加載。
結語¶
dsh-browser 爲 DeepSeek Harness 提供了直接控制瀏覽器的能力，將其納入模型上下文、會話日誌和審批流程。開發者可根據上述步驟進行安裝和配置，構建需要直接操作網頁的智能體應用。
