DeepSeek Harness 插件：dsh-embedded-browser

前言¶

智能體通常運行在容器、虛擬機或 CI 環境中，這些環境沒有圖形界面。當自動化流程遇到登錄、雙因素認證（2FA）、二維碼登錄或驗證碼時，純無頭瀏覽器自動化就會中斷。同時，將 Cookie 或 storageState 複製到這些環境中往往不可靠，因爲設備綁定憑證、指紋和 WebAuthn 無法直接遷移。

dsh-embedded-browser（原名 dsh-browser-panel）解決這一問題。它將瀏覽器嵌入在 DSH 主機內部，爲每個會話提供獨立的標籤頁。AI 通過 browser_embedded_* 工具控制該標籤頁，而人類可以在 DSH Web UI 的右側邊欄中實時查看或接管同一個標籤頁。

插件介紹¶

插件名稱：imroc/dsh-browser-panel / dsh-embedded-browser（v0.3.0 重命名）
維護者：imroc
許可證：MIT

該插件提供了一套工具集，允許 AI 在後臺驅動瀏覽器，同時允許人類在 Web UI 中通過側邊欄與頁面交互。所有會話共享同一個持久化配置文件（Profile），因此一次登錄的憑證在所有後續會話中保持有效。

核心功能¶

插件包含 12 個工具，用於控制、監控和與瀏覽器交互。這些工具採用惰性註冊機制，不會在插件加載時立即註冊，而是在滿足特定條件時纔可用。

工具列表¶

browser_embedded_status：報告狀態，包括當前運行情況、URL、標題以及是否有待處理的操作。
browser_embedded_navigate：打開 URL，首次使用時會啓動瀏覽器；newTab 選項可替換當前會話的頁面。
browser_embedded_snapshot：讀取頁面快照，返回標題、URL、可點擊/可輸入元素的編號列表及可見文本。
browser_embedded_click：通過元素編號或可見文本點擊。
browser_embedded_type：在字段中輸入文本，支持 React/Vue 友好的插入；submit 參數可按 Enter 鍵提交。
browser_embedded_press：模擬按鍵，如 Enter、Tab、Escape、方向鍵等。
browser_embedded_scroll：滾動頁面，支持上下左右及頂底方向。
browser_embedded_emulate：模擬環境變化，包括設備預設（如 iphone-14）、視口大小（width/height）或深色/淺色主題（theme）。reset: true 可恢復默認設置。
browser_embedded_eval：在頁面中執行 JavaScript 並返回有限的 JSON 投影，可用於切換主題屬性、讀取計算樣式或斷言狀態。
browser_embedded_screenshot：截取頁面 PNG 圖片作爲附件返回給模型。
browser_embedded_ask_human：喚起當前會話的瀏覽器標籤頁，顯示指令並等待用戶按下“我已完成”。
browser_embedded_close：關閉當前會話的標籤頁，配置文件保持不變。

惰性加載機制¶

這 12 個工具默認不會在插件加載時註冊。它們會在以下任一情況被激活：
1. 成功調用 browser-use 技能；
2. 人類輸入 /browser-use 手勢；
3. 在會話日誌中發現過去成功調用過這些工具。

因此，沒有 browser-use 技能，這些工具不會出現。安裝此插件時，建議同時安裝 browser-use 技能。一旦激活，工具會在整個主機進程期間保持可用，包括後續創建的所有會話。

側邊欄交互¶

在 DSH Web UI 中，右側邊欄會根據需要打開一個“瀏覽器”標籤頁，實時鏡像 AI 正在操作的標籤頁。該標籤頁支持鼠標、滾輪、鍵盤和 IME 輸入，並非截圖查看器，事件會實時回放。當需要人工介入時，會話標籤頁會顯示橫幅和“我已完成”按鈕。

安裝與啓用¶

環境要求¶

Node.js：>= 22.19
DeepSeek Harness (DSH)：>= 0.1.5-rc.2

插件配置¶

插件使用持久化配置文件：
$DSH_HOME/embedded-browser/profile

如果你是從舊版本（0.2.0，原名 dsh-browser-panel）遷移，可以通過配置 profileDir 指向舊的 browser-panel/profile 目錄來保留登錄狀態。

典型用法¶

使用 browser_embedded_emulate 模擬設備或主題，隨後截圖驗證效果：

browser_embedded_emulate { "device": "iphone-14" }
browser_embedded_screenshot

browser_embedded_emulate { "theme": "dark" }
browser_embedded_screenshot

browser_embedded_emulate { "reset": true }

注意事項¶

依賴技能：必須安裝並使用 browser-use 技能才能看到 browser_embedded_* 工具。
版本兼容：v0.3.0 對應 dsh-embedded-browser，v0.2.0 對應 dsh-browser-panel，工具前綴已統一爲 browser_embedded_。
安全性：插件以當前 DSH 進程的權限運行，請確保從可信來源安裝並檢查許可證。

總結¶

dsh-embedded-browser 爲運行在無頭環境中的智能體提供了圖形化交互能力。通過將瀏覽器嵌入主機，結合 AI 的自動化控制和人類在側邊欄中的實時接管，解決了傳統無頭自動化在登錄、驗證碼等場景下的痛點。