前言¶
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
