DeepSeek Harness 的 Agent 瀏覽器插件

前言¶

DeepSeek Harness（DSH）桌面版運行時，模型通過工具層與右側邊欄的 Guest 客戶端通信。Agent 瀏覽器插件在 DSH 裏增加了一個名爲「Agent 瀏覽器」的右側欄 Tab，模型調用 browser_* 系列工具時，由插件在右側欄創建一個 <webview> 實例，用戶全程可見 Agent 在操作的內容。

是什麼¶

這是一個給 DSH 桌面版裝上「看得見的手」的插件。它不是用 Playwright 或 Puppeteer 啓動一個無頭瀏覽器，而是複用 DSH 右側欄裏一個用戶可見的 <webview>，讓模型通過 15 個工具來「看見」並「操作」這個頁面。

插件由 66jiujiu99 維護，分類爲「聯網工具」，目前星標數爲 0。

核心功能¶

15 個工具¶

工具	作用
`browser_open`	打開 URL 並回快照
`browser_snapshot`	重拍快照，可控制返回範圍與文本內容
`browser_click`	點 `@ref` 或視口座標
`browser_type`	輸入文本
`browser_press`	按鍵（Enter/Tab/Escape/方向鍵/PageUp/PageDown/Home/End/Space）
`browser_scroll`	滾動頁面
`browser_nav`	back/forward/reload/goto
`browser_find`	按名字/文字找元素
`browser_deep_snapshot`	CDP 深度模式：讀取無障礙樹（a11y）
`browser_screenshot`	截圖並落盤爲 PNG
`browser_tabs`	list/new/switch/close
`browser_console`	頁面控制台近況
`browser_network`	請求近況
`browser_eval`	執行 JS
`browser_close`	釋放頁面

快照與增量更新¶

快照默認只返回視口內元素、不返回正文，最大頭。動作類工具（open/click/type/press/scroll/nav）回快照時同樣默認視口 + 無正文。隱藏/零尺寸元素會被幾何剔除，不佔用 token。

同一 URL 的動作後走增量 [delta]：只報 added/removed/changed（textChanged 時短採樣 + textSample），stats 按增量文本自身計並附 +a -r ~c total=N。URL 變化 / 首幀 / 找不到上一幀自動回全量。

@ref 穩定：同一元素在多次快照裏保持同一個 ref。頁面重渲染把節點換掉後，點擊會按「角色 + 名字」自動找回語義相同的元素（並在結果裏標 recovered），找不到纔回 NO_REF 讓你重拍快照。

穿透 Shadow DOM 與同源 iframe¶

快照遞歸進入 open shadow root 與同源 iframe（含嵌套），點它們時座標自動換算到頂層視口。跨源 iframe 受瀏覽器安全邊界限制讀不到，快照裏會明確寫「N 個跨源 iframe 的內容不可見」。

深度模式（CDP，可選）¶

普通快照只能看到 DOM 能讀到的部分：跨源 iframe 和 closed shadow root 內容讀不到。深度模式改用本機 CDP 端口直連 Chromium，讀無障礙樹（a11y），因此能看到這些內容，並給出頂層視口座標。

啓用深度模式需要：
1. 完全退出 DSH（含托盤）
2. 運行 tools/start-dsh-debug.cmd（或 .ps1）
3. 在插件配置裏打開 deepMode.enabled: true，重新 apply 插件

用完關掉 DSH、用普通方式重啓，端口就消失了。

深度模式多看到的東西包括：
- closed shadow root 裏的元素
- aria-label 純圖標按鈕
- 跨源 iframe 裏的按鈕/鏈接（給出頂層視口座標）
- 但讀不到 canvas 裏畫出來的文字（a11y 樹裏沒有節點）

安裝與啓用¶

第 0 步：解除下載鎖（僅限 ZIP 安裝）¶

從 GitHub 下載 ZIP 並解壓後，Windows 會給每個文件打上 “Mark of the Web” 標記。對 .cmd 這類可執行文件，這個標記會讓 Windows 每次雙擊都彈「無法驗證發佈者，你確定要運行此軟件嗎」。先跑一次把它清掉：

tools\unblock-folder.cmd

只刪 Zone.Identifier 數據流，不改內容、權限、所有者。默認處理本插件目錄（含子目錄），也可 -Path "C:\某個解壓目錄"；想先看會改什麼而不動手就加 -WhatIf。

第 1 步：拿到代碼¶

# 推薦：git clone（不產生 MOTW，不會彈安全警告）
git clone https://github.com/66jiujiu99/dsh-agent-browser-auto.git

也可以 GitHub → Code → Download ZIP 解壓（那就回到第 0 步先解除下載鎖）。

本插件不發佈 npm 包，也不需要 npm install，它零依賴，直接就是可加載的 DSH 插件目錄。

第 2 步：裝進 DSH¶

# 在 DSH 裏（需要 danger-full-access 或逐次批准）
# target 傳你 clone / 解壓出來的那個目錄的絕對路徑
plugin_manager install_bundle target=C:\path\to\dsh-agent-browser-auto

以本地目錄方式安裝時，DSH 用的是 link:，package.json 的 files 字段在此模式下不生效（打包/發佈時才生效）。因此目錄裏的 tools/、test/ 會一起留在原地，屬正常現象。

安裝後 Host 半邊立即生效；Client 半邊在桌面窗口裏按需加載（首次安裝若沒看到 tab，按 Ctrl+R 刷新窗口一次）。

改了 index.js / lib/*.js 之後：Host 代碼不會熱更（loader 不監聽文件），需要重新 apply：
plugin_manager set_plugin include:agent-browser-auto enabled=false → enabled=true。

改了 client.js：Client HMR 會自動熱替換（可在 ~/.dsh/storages/agent-browser-auto/debug.jsonl 裏看到新 clientId）。

卸載¶

plugin_manager set_plugin include:agent-browser-auto enabled=false   # 先停用
plugin_manager remove_bundle target=dsh-agent-browser-auto     # 再移除

審計/調試數據不會自動刪除，如需清理：刪掉 ~/.dsh/storages/agent-browser-auto/ 即可。

配置¶

配置項在 cordis.patch.yml 裏 agent-browser-auto 行的 config 下：

鍵	默認	含義
`allowedHosts`	`[]`	非空時只放行這些主機（後綴匹配）
`blockedHosts`	`[]`	優先拒絕的主機
`enableEval`	`false`	是否允許 `browser_eval`
`commandTimeoutMs`	`45000`	單條命令等待上限
`pollWaitMs`	`20000`	長輪詢掛起上限
`maxResultBytes`	`12000`	工具結果上限
`auditDir`	`""`	審計目錄，空 = `~/.dsh/storages/agent-browser-auto`
`debug`	`true`	是否寫 `debug.jsonl`
`deepMode.enabled`	`false`	是否啓用 CDP 深度模式
`deepMode.portFile`	`""`	空 = `%APPDATA%\@deepseek-ai\dsh-desktop\DevToolsActivePort`
`deepMode.endpoint`	`""`	空 = 讀 `portFile` 拼 `http://127.0.0.1:<port>`；非空直接用（僅允許 loopback）
`deepMode.maxNodes`	`200`	深度快照默認最多返回節點數
`deepMode.timeoutMs`	`8000`	單條 CDP 命令超時

適用場景與注意¶

適合需要 DSH 桌面版與真實網頁交互的場景，比如：
- 模型需要操作右側欄裏的某個網頁
- 需要讀取頁面上可見的元素（包括 shadow DOM、同源 iframe）
- 需要截圖、控制台、網絡請求等調試信息

注意：
- 插件以當前 DSH 進程權限運行
- 深度模式（CDP）端口沒有認證，只綁 127.0.0.1，運行期間本機任意進程都能通過它控制這個 DSH 實例（含執行任意 JS），所以默認關閉、端口隨機；不用時用普通方式重啓 DSH 即可讓端口消失
- 安裝前應檢查源碼與許可證，確認信任這份代碼

總結¶

這個插件爲 DSH 桌面版提供了一個「看得見的手」，讓模型可以通過 15 個工具來操作右側邊欄裏一個用戶可見的瀏覽器頁面。它複用用戶眼前的真實頁面，而不是啓動一個額外的無頭瀏覽器，降低了成本與複雜度。深度模式（CDP）可以讀取無障礙樹，補足了普通快照看不到的部分。

目錄頁：https://www.skillhub.cn/plugins/66jiujiu99/dsh-agent-browser-auto
GitHub：https://github.com/66jiujiu99/dsh-agent-browser-auto