在智能體開發中，讓 agent 擁有真實的瀏覽器能力是常見需求。Web Bridge 是一個 MCP server 插件，利用真實瀏覽器（Chromium/Firefox/WebKit）提供導航、點擊、填表和截圖能力。它通過無障礙樹快照來識別頁面元素，使 agent 能夠精確操作頁面而無需依賴視覺模型。
這是什麼¶
Web Bridge 是一個基於真實瀏覽器的自動化工具。它使用 TypeScript 編寫，運行在 Node.js ≥ 20 環境下，通過 MCP 協議（stdio 傳輸）與 DSH 通信。其核心機制是將網頁渲染爲無障礙樹快照，併爲 DSH 暴露 22 個 web_ 前綴的工具。
核心能力¶
- 真實瀏覽器驅動：支持 Chromium、Firefox 和 WebKit，默認使用 Chromium。
- 無障礙樹驅動：
web_snapshot生成帶引用編號的頁面結構，實現精確交互。 - 頁面交互：支持點擊、填表、下拉選擇、懸停、滾動、鍵盤輸入等操作。
- 視覺能力：支持視口、全頁、元素截圖，格式支持 PNG/JPEG。
- 腳本執行：可在頁面上下文中執行 JavaScript，並自動處理循環引用、BigInt 等類型的清洗。
- 多標籤頁與精細等待：支持標籤頁的創建、切換、關閉，以及按加載狀態、元素狀態、URL 或固定時長進行等待。
- 會話管理：支持持久化用戶數據目錄，並可通過
web_shutdown釋放資源。
安裝與啓用¶
安裝前請確保 Node.js 版本 ≥ 20。
在 DSH 中通過插件命令添加：
dsh plugin --profile demo add github:JohnXu22786/browser-automation
該命令會將插件添加到 demo 配置文件中。安裝完成後，插件將自動加載並初始化瀏覽器進程。
典型用法¶
配置管理¶
Web Bridge 的配置優先級爲：默認值 < 配置文件 < 環境變量。
- 配置文件：在項目根目錄創建配置文件，如
web-bridge.config.json。
{
"browser": { "name": "chromium", "headless": true, "viewport": { "width": 1280, "height": 720 } },
"context": { "ignoreHTTPSErrors": false, "permissions": ["geolocation"] },
"timeouts": { "action": 10000, "navigation": 60000, "settle": 500 },
"sandbox": true,
"testIdAttribute": "data-testid"
}
啓動命令：`node dist/index.js --config web-bridge.config.json`。
- 環境變量：通過
WEB_BRIDGE_前綴的環境變量覆蓋配置。WEB_BRIDGE_BROWSER：指定瀏覽器引擎。WEB_BRIDGE_HEADLESS：控制無頭模式。WEB_BRIDGE_VIEWPORT：設置視口大小。WEB_BRIDGE_ACTION_TIMEOUT：單次操作超時時間（毫秒）。WEB_BRIDGE_NAV_TIMEOUT：導航超時時間。WEB_BRIDGE_SETTLE_MS：操作後等待異步任務 settled 的時間。
工具調用示例¶
- 導航：
web_open用於打開 URL，支持http/https/file/data協議。 - 獲取快照：
web_snapshot返回頁面的無障礙樹結構，元素帶有引用編號，用於後續精確定位。 - 交互：
web_click使用引用編號或選擇器點擊元素；web_fill用於填表。 - 截圖：
web_screenshot可截取視口、全頁或指定元素。
適用場景與注意¶
該插件適合需要高精度頁面操作、處理複雜表單或執行動態網頁腳本的場景。
權限與安全提示：
* 插件以當前 DSH 進程的權限運行。
* Navigation 工具會觸發真實的網絡請求和頁面渲染。
* Interaction 工具會觸發鼠標事件和腳本執行。
* 在安裝前，請務必檢查插件的源碼和許可證（MIT）。
總結¶
Web Bridge 通過真實瀏覽器和無障礙樹快照機制，爲 DSH 提供了可靠的瀏覽器自動化能力。它支持精細的交互控制和會話管理，適合構建需要與 Web 應用深度交互的智能體。
