前言¶
DSH（DeepSeek Harness）的插件生態強調「一切皆插件」：把外部 CLI、測試、報告等能力掛到 agent 可調用的工具面上。
dsh-playwright-cli 面向 DSH 智能體開發者：它把 Playwright CLI 的幾個常用動作封裝成 host 插件工具，讓 agent 在會話裏直接探測 CLI、安裝瀏覽器、運行測試並打開 HTML 報告，而不是要求用戶手工切到 shell 拼 npx playwright 命令。
這是什麼¶
- 插件名：
dsh-playwright-cli - 維護者：
mitao-su - 許可證：MIT
- 運行面：host-only 運行，無 client bundle、無 Web 依賴
- 分發方式：
lib/已提交進 Git，安裝不觸發構建腳本，零交互 - 執行縫：複用 DSH 提供的 shell 執行器（
ctx.shell），sandbox 策略、DSH_*環境變量、輸出截斷、超時/中止分類由組合提供
核心功能¶
工具清單¶
| 工具 | 用途 | 底層/對應命令 |
|---|---|---|
playwright_version |
探測目標項目裏 Playwright CLI 是否可用並打印版本 | npx --no-install playwright --version |
playwright_install |
安裝瀏覽器，默認 chromium；CLI 缺失且 autoInstallPackage 開啓時先用 npm 腳手架 @playwright/test |
npx --no-install playwright install [browsers...] |
playwright_test |
運行 Playwright 測試套件，支持 --config/--project/--grep/--workers/--reporter/--headed/--trace/--retries/--list 等選項 |
npx --no-install playwright test ... |
playwright_show_report |
定位 HTML 報告：有 web server 時註冊迴環路由並返回 URL；否則返回文件絕對路徑 | playwright-report/index.html 靜態服務 |
所有命令默認在會話工作區（session cwd）中執行。非零退出會作爲結果報告給 agent，而不是直接拋錯，由模型自行判斷下一步。
運行方式¶
dsh-playwright-cli 是 host-only 插件。命令最終通過 ctx.shell 執行，因此：
- 使用當前 DSH 進程/組合具備的權限和沙箱策略；
- 輸出會經過 DSH 的輸出截斷、超時/中止分類；
DSH_*環境變量由 DSH 組合提供。
安裝與啓用¶
安裝前需要確認：
- DSH 版本不低於
0.1.0-rc.6； - 目標 profile 已掛載 shell 執行器，標準
web/headless組合自帶。
常規安裝：
dsh plugin --profile web add github:mitao-su/dsh-playwright-cli
走 Git 分發時，倉庫會把 lib/ 提交進 Git，安裝不觸發構建腳本。安裝成功後重啓目標 profile。README 說明 dsh plugin 會自動把包加入 dsh.profile.bundles。
受限網絡環境下，github: 依賴需要本機 git 可訪問 GitHub；也可以改用 GitHub tarball URL：
dsh plugin --profile web add https://github.com/mitao-su/dsh-playwright-cli/archive/refs/heads/main.tar.gz
本地路徑或開發安裝：
dsh plugin --profile web add ./dsh-playwright-cli
也可以使用前綴形式：
dsh plugin --profile web add file:./dsh-playwright-cli
package.json 的 peerDependencies 要求：
{
"@deepseek-ai/cordis": "^4.0.1",
"@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
"@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
"@deepseek-ai/dsh-sandbox": "0.1.0-rc.6",
"@deepseek-ai/dsh-shell": "0.1.0-rc.6",
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
"@deepseek-ai/schemastery": "3.18.1"
}
典型用法¶
一次典型會話可以按下面步驟進行：
- 調用
playwright_version，在默認會話工作區確認 Playwright CLI 就緒； - 調用
playwright_test，示例參數：
{
"files": ["tests/login.spec.ts"],
"reporter": "html"
}
運行後得到 reportDir；
- 調用
playwright_show_report，獲取url後在瀏覽器打開 HTML 報告；如果沒有 web server，則返回文件絕對路徑。
README 給出了一段 profile 配置示例，按 id: playwright-cli 整段覆蓋：
- insert:
- id: playwright-cli
name: dsh-playwright-cli
config:
timeoutMs: 600000
reportDir: playwright-report
reportRoute: /playwright-report
autoInstallPackage: true
其中：
timeoutMs: 600000：每次 CLI 調用的默認超時；reportDir: playwright-report：報告目錄；reportRoute: /playwright-report：報告路由前綴；autoInstallPackage: true：CLI 缺失時自動npm install -D @playwright/test。
適用場景與注意¶
適合誰¶
適合需要在 DSH agent loop 中自動執行 Playwright 測試、獲取報告地址，並且目標項目已有或準備安裝本地 @playwright/test 的場景。
權限與沙箱¶
插件以當前 DSH 進程權限運行，命令通過 DSH shell 執行器進入沙箱。瀏覽器二進制下載到用戶目錄、playwright test fork worker 子進程等，都可能被文件沙箱拒絕。此時結果會帶 [sandbox: file access denied ...] 標記和升級提示。
playwright_version、playwright_install、playwright_test 提供 sandbox_permissions + justification 參數。沙箱拒絕後，應使用能通過的最窄更寬模式重試同一條命令，例如 danger-full-access。執行前會彈用戶審批，獲批後僅本次調用生效。
安裝前應檢查源碼、依賴範圍和 MIT 許可證。
本地依賴約束¶
工具按 npx --no-install 解析，只認 workdir 裏的本地 @playwright/test，不會使用全局 CLI。
如果 workdir 的 spec 文件 require('@playwright/test') 解析到本地副本，而 CLI 命中全局，會出現 test.describe() not expected here 之類的雙副本錯誤。應把 workdir 指向裝有本地 @playwright/test 的項目目錄，也可以先用 playwright_install 腳手架。
引號處理¶
參數會按掛載 shell 的方言（bash/pwsh）自動安全引用；含單引號的路徑需要先重命名。
報告路由¶
playwright_show_report 每次調用註冊一條 /playwright-report/<nonce> 迴環路由，插件卸載時統一釋放。同一報告可以多次調用。
併發限制¶
playwright_test 和 playwright_install 聲明爲不可併發，因爲它們共享 test-results / report 目錄。
結尾¶
dsh-playwright-cli 把 Playwright 的「探測—安裝—測試—報告」動作接成 DSH agent 可調用的工具面。許可證爲 MIT，倉庫地址：
- GitHub：https://github.com/mitao-su/dsh-playwright-cli
- 插件頁鏈接（來自插件線索，未核正文）：https://www.skillhub.cn/plugins/mitao-su/dsh-playwright-cli
