前言¶

給 DSH agent 接瀏覽器時，常見路徑是兩類：讓模型猜 CSS 選擇器，或者把整頁 DOM 交給模型處理。前者容易失配，後者會擴大上下文。dsh-browser-playwright 把模型可見的交互面收斂爲 accessibility snapshot 和穩定元素 ref，由 Playwright 在底層驅動真實瀏覽器。

這是什麼¶

dsh-browser-playwright 是面向 DeepSeek Harness 的瀏覽器能力插件，定位爲 Playwright-powered browser capability for DeepSeek Harness。GitHub 倉庫路徑爲 ChenyuHeee/dsh-browser-playwright，許可證爲 MIT。它讓 agent 在一次 harness session 內使用一個 browser session，圍繞穩定 ref 完成導航、交互、截圖和結構化抽取。

核心功能¶

• 使用 Playwright 驅動真實瀏覽器。
• 通過 accessibility snapshot 暴露元素，並提供穩定 ref。
• 不做 CSS selector 猜測，不輸出完整 DOM。
• 每個 harness session 對應一個 browser session。
• 支持標籤頁管理、截圖作爲 durable image attachments、結構化抽取，以及 gated JavaScript evaluation。
• 提供 17 個 browser_ 前綴的工具 schema。
• Playwright provider 會自動探測 chromium、chrome、msedge、edge 渠道。
• 其他 provider 可以註冊到 ctx.browser，工具 schema 保持不變。

安裝¶

1、給目標 profile 添加插件：

dsh plugin --profile <name> add dsh-browser-playwright

這一步把插件添加到指定 profile。

瀏覽器二進制¶

provider 會按 chromium、chrome、msedge、edge 的順序自動探測可用渠道。

如果想使用 Playwright 管理的 Chromium，執行：

npx playwright-core install chromium

這條命令安裝 Playwright 可使用的 Chromium。

在受限網絡下，可以設置下載主機後再安裝：

PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright npx playwright-core install chromium

這一步通過 PLAYWRIGHT_DOWNLOAD_HOST 指定下載源。

典型用法¶

插件默認使用 browser_ 作爲工具前綴。下面先打開頁面，再根據快照中的 ref 執行點擊。

先調用 browser_navigate 打開一個 http 或 https URL：

browser_navigate
url: https://example.com/

browser_navigate 只接受 http/https URL，並返回快照。

快照中會列出 URL、標題、可見元素和 ref= 標記，示例如下：

URL: https://example.com/
Title: Example Domain
Refs: 12

- navigation "Main"
  - link "Home" [ref=e1] -> /
  - button "Go" [ref=e2]
- heading "Welcome" [level=1]
- textbox "Search" [ref=e3]

不可見內容會被排除。快照結果有邊界，截斷情況會在結果中標記。

在快照後，可以調用 browser_click 並使用 ref: e2：

browser_click
ref: e2

這一步基於最新快照中的元素引用執行點擊。

插件還提供這些 browser_ 工具：

browser_snapshot
browser_click
browser_fill
browser_press
browser_scroll
browser_back
browser_forward
browser_wait
browser_tabs
browser_open_tab
browser_switch_tab
browser_close_tab
browser_screenshot
browser_extract
browser_evaluate
browser_close

它們覆蓋快照、交互、歷史導航、等待、標籤頁管理、截圖、結構化抽取、受控 JavaScript 執行和關閉瀏覽器。

配置¶

可以通過配置項調整導航和工具行爲。

限制導航域名時，使用 allowedDomains：

allowedDomains:
  - example.com

該配置項用於約束 browser_navigate 可訪問的域名。

啓用 browser_extract 時，需要提供輔助模型路由：

extract:
  provider: <provider>
  model: <model>

browser_extract 要求 extract.provider 和 extract.model；缺少任一項時，會返回可操作的錯誤。

啓用 browser_evaluate 時，需要打開 allowEvaluate：

allowEvaluate: true

browser_evaluate 默認關閉；啓用後會執行任意頁面 JavaScript，應結合 DSH 的審批或權限策略使用。

適用場景與注意¶

適合已經使用 DSH、希望 agent 操作真實瀏覽器，並且偏好穩定 ref 而非選擇器猜測的場景。它也適合需要保留瀏覽器會話狀態、使用截圖附件、或在 ctx.browser 上替換 provider 的流程。

安裝前應檢查源碼、許可證和網絡出口。插件按 DSH 插件方式加載，運行時會以當前 dsh 進程權限執行；啓用 browser_evaluate 或放寬 allowedDomains 時，需要更嚴格地限制可用能力。

已知限制¶

• Selector-free 不等於 vision-free：基於 accessibility tree 的交互可能覆蓋不到純視覺控件，例如 canvas、WebGL、自定義繪製控件；此時可用 browser_screenshot 加圖像能力模型作爲回退。
• 跨域 iframe 會顯示爲沒有 ref 的葉子 (frame) 節點；同域 frame 會遍歷到兩層。
• browser_navigate 只支持 http 和 https。
• browser session 會保留 cookies、storage 和登錄狀態，但只在一個 harness session 內有效。
• 工具 schema 是靜態的；瀏覽器工具結果隨頁面變化，可能影響 KV cache 複用。

結語¶

dsh-browser-playwright 把瀏覽器交互收斂到可訪問性快照和穩定 ref 上，減少選擇器猜測和整頁 DOM 帶來的不確定性。它保留 ctx.browser 這個接入點，讓其他 provider 可以在同一工具 schema 下擴展。

社區目錄頁：https://www.skillhub.cn/plugins/ChenyuHeee/dsh-browser-playwright
GitHub：https://github.com/ChenyuHeee/dsh-browser-playwright