前言¶

給 Agent 接入 Playwright，常見的做法是做一層語義封裝：把 test、install、show-report 拆成多個工具，再爲每個子命令設計一套參數 schema。這條路的問題在於，Playwright CLI 本身已經是完整的能力面，封裝層映射得再全，也難免漏掉選項，Agent 實際能用的範圍反而取決於封裝者。

在 DSH（DeepSeek Harness）裏，「一切皆插件」，模型可見的工具全部來自插件註冊。於是有了另一種做法：註冊一個透傳工具，把 Agent 給的參數原樣轉交給本機 CLI。mitao-su/dsh-playwright-native 就是這樣一個插件，下面介紹它的定位、用法和注意事項。

這是什麼¶

dsh-playwright-native 由 mitao-su 維護，當前版本 0.1.0，MIT 許可證。它的一句話定位：把本機原生 Playwright CLI 註冊爲 DeepSeek Harness 透傳工具（dsh-plugin），Agent 敲什麼參數，就原樣執行什麼。

插件用 ctx.tools.register(defineTool(...)) 註冊一個名叫 playwright 的工具，核心參數只有一個 args: string[]，原樣、按序轉發給本機 playwright 二進制。它不拆分 install/test/show-report 子工具，不做任何參數映射——Agent 給什麼，就跑什麼。

README 裏對它的實現有一句概括：CLI 是能力，ctx.shell 是執行縫，defineTool + cordis.patch.yml 是註冊。

核心功能¶

• 註冊名爲 playwright 的透傳工具：通過 ctx.tools.register(defineTool(...)) 註冊，參數原樣、按序轉發給本機 playwright 二進制。
• 執行走 ctx.shell 執行器，與官方 bash/pwsh 工具同源，自動獲得 sandbox 策略、DSH_* 環境、輸出截斷、超時/中止分類。
• 通過 cordis.patch.yml + dsh.bundle.patch 成爲 profile 配置樹的一層，dsh plugin add 後自動寫入 dsh.profile.bundles。
• command 可配置：默認 playwright，可改爲 npx --no-install playwright 強制走項目本地副本。
• timeoutMs 可配置，默認 600000 毫秒；支持 workdir 參數（默認會話工作區）與超時覆蓋。
• 注入 systemPrompt 段落（tool:playwright，order 106）說明工具用法。
• isConcurrencySafe 設爲 false：playwright test 共享 test-results/report 目錄，不允許併發。

安裝與啓用¶

安裝命令如下，--profile web 表示把插件寫入 web 這個 profile：

dsh plugin --profile web add github:mitao-su/dsh-playwright-native

這條命令會把插件自動寫入目標 profile 的 dsh.profile.bundles，不需要手工改配置文件。

前置要求有三條：

1. 本機已安裝 playwright 命令，playwright --version 可跑；
2. dsh 可用（README 中的教程驗證於 0.1.0-rc.6），目標 profile 已掛載 shell 執行器（標準 web/headless 自帶）；
3. dsh plugin add 依賴 pnpm，注意 pnpm ≥ 10 對 Git 依賴默認攔截構建腳本。

安裝前後可以用兩條命令驗證環境：

playwright --version     # 例如 Version 1.62.1
dsh --version            # 例如 0.1.0-rc.6

默認配置即可直接使用。要改命令或超時，改插件 cordis.patch.yml 裏的 config：

- insert:
    - id: playwright-native
      name: dsh-playwright-native
      config:
        command: playwright        # 可改成 "npx --no-install playwright" 強制走項目本地副本
        timeoutMs: 600000          # 每次調用的默認超時（毫秒）

注意：這裏的 config 是整段替換而非深合併，覆蓋時需要重述所需鍵。

典型用法¶

註冊後，Agent 看到的工具名就是 playwright，調用參數示例：

["test", "tests/", "--reporter", "html"]

實際執行的是 playwright test tests/ --reporter html。

可直接透傳的原生命令包括 playwright test、playwright install、playwright show-report、playwright --version，也可以在調用時帶 workdir（默認會話工作區）和 timeoutMs（超時覆蓋）。

兩個行爲細節值得知道：

• 非零退出視爲報告而非報錯，結果帶 [exit code: N] 標記，由模型自行決定下一步；
• 沙箱拒絕時結果帶 [sandbox: file access denied ...] 標記，可通過 sandbox_permissions + justification 走權限升級出口，用更寬的模式重試，執行前彈審批。

如果想改代碼，本地構建只需兩步，產出 lib/index.js 和 lib/index.d.ts：

pnpm install
pnpm build        # tsc → lib/index.js + lib/index.d.ts

適用場景與注意¶

適合已經在用 DSH、希望 Agent 按命令行習慣使用本機 Playwright 的開發者，尤其是 e2e 測試工作流：不想維護一層 CLI 選項到自定義 schema 的映射，願意讓 Agent 直接面對原生命令。

使用前注意以下幾點：

1. 沙箱限制：playwright test 會 fork worker 子進程、playwright install 會下載瀏覽器，可能被文件沙箱拒絕，需走上面提到的權限升級出口。
2. 安全檢查：插件以當前 dsh 進程權限運行，安裝前建議先閱讀源碼與許可證（本插件爲 MIT），確認無問題再接入。
3. 版本匹配：插件自身版本爲 0.1.0，peerDependencies 針對 DSH/Cordis 運行時（如 @deepseek-ai/dsh-agent ^0.1.0-rc.6 等），README 教程驗證於 dsh 0.1.0-rc.6。

結語¶

dsh-playwright-native 的價值在於剋制：DSH 的模型可見工具全部來自插件註冊，這個插件只做了註冊和轉發兩件事，其餘都交給本機已有的 playwright CLI，不重寫能力，也不擋在 Agent 和命令之間。

• GitHub 倉庫：https://github.com/mitao-su/dsh-playwright-native
• 社區目錄頁：https://www.skillhub.cn/plugins/mitao-su/dsh-playwright-native （社區維護的獨立目錄站點，與 DeepSeek / 幻方無官方從屬關係）