前言¶
DeepSeek Harness (DSH) 採用了“一切皆插件”的架構，支持在運行時動態加載工具。dsh-playwright 是一個爲此場景設計的插件，它給智能體提供了一套 browser_* 工具集，底層通過 Playwright 驅動 Chromium 進行真實的網頁操作。
這個插件解決了智能體需要與外部 Web 界面交互的需求，例如打開頁面、點擊元素、抓取數據或截圖。它不依賴外部的橋接服務，直接在宿主進程中運行。
核心功能¶
該插件提供以下工具能力：
- browser_open: 打開指定 URL，返回最終地址與頁面標題。
- browser_status: 查詢瀏覽器或當前頁面的狀態（是否掛載、端點、URL、標題等）。
- browser_attach: 運行時掛載或切換到一個已存在的瀏覽器實例。
- browser_tabs: 列出、切換或關閉已打開的標籤頁。
- browser_click: 點擊元素（支持 CSS 或
text=選擇器）。 - browser_type: 逐字輸入文本（支持設置
delay模擬打字節奏）。 - browser_fill: 快速填充表單。
- browser_press: 模擬按鍵（如 Enter、Tab、Escape 等）。
- browser_wait: 等待指定毫秒數。
- browser_extract: 抓取頁面或指定元素的文本內容。
- browser_html: 抓取頁面或指定元素的 HTML 結構。
- browser_eval: 在頁面上下文中執行 JavaScript 表達式。
- browser_screenshot: 截圖並保存爲 PNG，支持圖片輸入的模型直接查看畫面。
- browser_close: 關閉瀏覽器或斷開連接。
安裝與啓用¶
在任意目錄執行一條命令，DSH 會自動定位 profile 目錄。首次使用會自動初始化：
dsh plugin --profile web add git+https://github.com/whklwhkl/dsh-playwright.git
安裝完成後需要重啓 DSH，browser_* 工具纔會對 profile 下的所有會話生效。
環境準備¶
該插件依賴 playwright-core，但它不會自動下載瀏覽器二進制文件。在首次使用前，需要手動安裝 Chromium：
npx playwright-core install chromium
安裝的瀏覽器文件會進入系統緩存目錄（如 ~/Library/Caches/ms-playwright），插件啓動時會自動發現。
使用方式¶
插件支持兩種主要模式：
- 自建模式：插件內部啓動一個乾淨的瀏覽器實例。
- 掛載模式：通過 CDP (Chrome DevTools Protocol) 接管用戶當前正在使用的瀏覽器，保留登錄態、Cookie 和擴展。
掛載模式通常需要先設置環境變量：
export PW_CDP_ENDPOINT=chrome
然後在對話或代碼中調用：
browser_attach({ endpoint: 'chrome' })
特性說明¶
- 版本兼容：對
dsh 0.2.0-rc.2實測通過。自該版本起，DSH 增加了插件兼容閘門，會檢查插件的peerDependencies。本插件聲明瞭@deepseek-ai/dsh: ^0.2.0-rc.2。若升級 DSH 到 0.3 及以上，需同步更新插件版本。 - 進程內運行：宿主進程內直接
require('playwright-core')，自建模式下無需額外的橋服務或端口。 - 中斷即取消：支持轉發
exec.signal，在途操作（如click、fill）會被中止，未完成的調用也會快速結算。 - 失敗即拋：出錯時直接拋出錯誤，不會拼接成“看起來成功”的字符串，便於策略和日誌進行錯誤處理。
- 截圖可見：
browser_screenshot返回的 PNG 會作爲附件內聯，支持圖片輸入的模型直接看到畫面。 - 中英雙語：通過設置
PW_LANG=en可以切換工具描述、參數文檔和輸出文案爲英文（默認中文）。
短結尾¶
dsh-playwright 是一個輕量級的瀏覽器自動化工具集，適合需要讓 DSH 智能體進行網頁操作的場景。它通過 Playwright 提供了從基礎點擊到複雜數據提取的完整能力。更多細節和源碼，請訪問 GitHub 倉庫。
