前言¶

给 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 / 幻方无官方从属关系）