前言¶
給智能體接瀏覽器時，常見的兩種做法各有代價：讓模型跑一個無頭瀏覽器，用戶看不到它到底點了什麼；或者用戶自己瀏覽，再把內容複製給模型。dsh-playwright 走的是第三條路——在 DeepSeek Harness（DSH）裏開一個 Browser Use 面板，你和模型看到並操作同一個 Playwright 頁面。下面介紹這個插件的定位、功能、安裝與用法。
這是什麼¶
dsh-playwright 是一個 DSH 插件，由 JeremyGuo 維護，MIT 許可。一句話定位：使用一個共享的 Playwright 瀏覽器，配合你的 DeepSeek Harness AI。DSH 的理念是一切皆插件，瀏覽器能力就以插件形式接入：每個 DSH 會話擁有獨立的 BrowserContext 與 Page，模型通過一組 browser_* 工具導航、讀取、點擊、輸入、截圖，你在面板裏看到的是同一份即時畫面。
核心功能¶
Browser Use 面板¶
Chrome CDP 把重繪幀通過僅迴環的二進制 WebSocket 推送到穩定畫布。面板與對話共享寬度，左分隔條可拖動，佔比範圍 10%–80%。超過 55% 時插件會摺疊 DSH 左側的 Workspace/session 選擇器，低於 48% 時只恢復它自己摺疊過的選擇器。
導航與頁面讀取¶
導航能力覆蓋打開 HTTP(S) URL 和刷新當前頁面。browser_navigate 打開 URL 並返回語義快照；browser_snapshot 返回有界頁面文本，以及可見鏈接、按鈕、輸入框等可交互元素的臨時 id（如 e1）。注意這些 id 僅對當次快照有效，導航或動態 UI 變化後需要重新獲取。
指針與鍵盤¶
browser_click 默認左鍵，可按元素 id 或截圖座標定位，支持 left、right、middle 三鍵，動作有 click、down、move、up。拖拽是 down → 一次或多次 move → up，使用同一鼠標鍵。browser_type 替換可見可編輯元素的值並可選回車提交；browser_keyboard 支持 type、press、down、up，組合鍵如 Control+A、Meta+K，down/up 可長按遊戲鍵。
截圖與點擊標記¶
browser_screenshot 通過 DSH 原生附件與圖片塊管線返回 PNG，僅限聲明瞭圖片輸入的模型路由。它可以在截圖上標記上次成功點擊的位置：繪製的是後處理 RGB 方塊，不修改頁面 DOM，面板裏有獨立的「顯示上次點擊」開關。
會話隔離與恢復¶
Chrome 惰性啓動，teardown 時排隊的操作先完成再關閉。如果 Chrome 意外退出，下次操作會啓動替換瀏覽器，並把受影響會話恢復到上次頂層 URL。
安裝與啓用¶
先確認環境滿足要求：
- DeepSeek Harness
0.1.0-rc.6 - Node.js
^22.19.0或>=24.0.0 - 主機安裝 Google Chrome 或 Chromium
- 使用
browser_screenshot需要支持圖片輸入的模型路由
README 中給出的安裝命令如下（標註爲「After publication」，即正式發佈後的安裝方式）：
dsh plugin --profile web add dsh-playwright
dsh web --port 3081
本地開發可以用 link 方式掛載本地目錄，先拉依賴並跑一遍類型檢查、測試與構建：
pnpm install
pnpm run verify
dsh plugin --profile web add link:/absolute/path/to/dsh-playwright
dsh web --port 3081
啓用後，用界面右緣的 Browser Use 按鈕開關面板，拖動左側分隔條調整佔比。
典型用法¶
打開頁面並拿到語義快照：
{"url":"https://example.com"}
點擊可以用快照裏的元素 id，也可以用座標：
{"element_id":"e1"}
{"action":"click","button":"right","x":640,"y":400}
只移動指針不點擊，steps 控制中間步數：
{"action":"move","x":640,"y":400,"steps":20}
拖拽分三步發送，up 與 down 用同一鼠標鍵：
{"action":"down","button":"left","x":200,"y":200}
{"action":"move","x":600,"y":400,"steps":30}
{"action":"up","button":"left","x":600,"y":400}
輸入文本並回車提交：
{"element_id":"e3","text":"DeepSeek Harness","submit":true}
鍵盤操作支持打字、組合鍵與長按：
{"action":"type","value":"hello","element_id":"e3","delay_ms":50}
{"action":"press","value":"Control+A"}
{"action":"down","value":"ArrowRight"}
{"action":"up","value":"ArrowRight"}
截圖時可選標記上次成功點擊，方便確認點擊是否落在預期位置：
{
"show_last_click": true,
"marker_r": 0,
"marker_g": 255,
"marker_b": 0,
"marker_size": 60
}
RGB 三個通道是 0–255 的整數，show_last_click 默認 false。README 提到插件會在提示層面引導模型主動刷新失效的元素 id、在畫布類頁面上改用截圖座標、釋放長按中的鼠標與鍵盤輸入，以及在需要驗證點擊時請求帶標記的截圖。
要用截圖功能，需要爲模型路由聲明圖片輸入。以 llm-pi-ai 路由爲例：
llm-pi-ai:
providers:
my-provider:
models:
- id: my-vision-model
name: My Vision Model
input:
- text
- image
聲明圖片輸入是對端點能力的聲明；如果端點實際不接受圖片，provider 會拒絕請求。
配置項¶
browserExecutablePath：顯式指定 Chrome/Chromium 可執行文件；省略時使用常見的 macOS/Linux 路徑viewportWidth/viewportHeight：共享頁面視口navigationTimeoutMs：Playwright 操作超時actionSettleMs：返回操作後狀態前的延遲screencastQuality：CDP 截屏 JPEG 質量，取值 30–90，默認 60maxSnapshotChars/maxSnapshotElements：語義快照的體積上限allowPrivateHosts：設爲 true 時允許 localhost 與私有網絡目標，默認 false
安全邊界¶
幾條值得先了解的設計：
1、RPC 與 screencast 端點僅接受迴環同源客戶端。
2、默認攔截對 localhost、字面私有地址以及解析爲私有地址的主機名的 HTTP(S) 請求，包括子資源。僅對可信任務開啓 allowPrivateHosts。
3、私有地址攔截是網絡防護，不是針對不可信網站的完整沙箱。
4、瀏覽器會話不復用用戶 Chrome 的 profile、Cookie 或登錄態，彈窗與下載不對外暴露。
適用場景與注意¶
適合的場合：需要模型在 DSH 中操作真實網頁——能看、能點、能輸入——同時希望用戶全程旁觀並可隨時接管的任務，例如調試智能體的網頁交互流程。
使用前注意：
1、插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（本項目爲 MIT）。
2、快照中的元素 id 僅對當次快照有效，導航或頁面動態變化後要讓模型重新獲取。
3、browser_screenshot 只有在模型路由聲明瞭 image 輸入時纔可用。
4、如前所述，allowPrivateHosts 只應對可信任務開啓。
結尾¶
dsh-playwright 把「用戶看得到」和「模型操作得了」放進同一個頁面，省去了在無頭瀏覽器與手工複製粘貼之間來回倒騰的成本。如果你在用 DSH 做智能體開發，值得一試。
- GitHub：https://github.com/JeremyGuo/dsh-playwright
- 社區目錄：https://www.skillhub.cn/plugins/JeremyGuo/dsh-playwright （社區獨立站點，與 DeepSeek / 幻方無官方從屬關係）
