zzx-playwright-cli

一个对 @playwright/cli 的薄封装,把所有参数透传给底层 playwright-cli,专为 AI agent 驱动浏览器自动化场景设计。

English | 中文

特性

• ✅ 完全透传:除 --zzx-* 元命令外,所有参数 1:1 转发给 playwright-cli,行为与原生一致
• ✅ 同进程执行:不 fork 子进程,信号(Ctrl+C / SIGTERM)、退出码、TTY 行为与原生 CLI 完全相同,Windows 上无路径转义、信号丢失等问题
• ✅ 跨平台:已在 macOS / Linux / Windows 验证,纯 Node 实现,无 shell 脚本
• ✅ 友好错误:依赖缺失或运行异常给出可读中文提示,方便 agent 自我修复
• ✅ 本地开发可用:node bin/zzx-playwright-cli.js ... 与全局命令完全等价

安装

全局安装(推荐 agent 使用)

npm install -g zzx-playwright-cli
zzx-playwright-cli --zzx-version

项目内安装

npm install zzx-playwright-cli
npx zzx-playwright-cli --zzx-version

快速开始

# 打开浏览器并跳转
zzx-playwright-cli open https://example.com

# 取一份页面快照,拿到所有可交互元素的 ref
zzx-playwright-cli snapshot

# 用 ref 直接交互
zzx-playwright-cli click e5
zzx-playwright-cli fill e3 "[email protected]" --submit

# 关闭
zzx-playwright-cli close

完整命令清单与高级用法请直接执行:

zzx-playwright-cli --help

也可以参考底层 playwright-cli 文档,所有命令完全适用。

包装器自身的元命令

为了避免与 playwright-cli 的参数冲突,本工具自身的元命令统一以 --zzx- 前缀:

| 命令 | 说明 | | --- | --- | | --zzx-version | 显示本工具版本及底层 @playwright/cli 版本 | | --zzx-help | 显示本工具的简要使用说明 |

其它一切都会被原样透传。

本地开发

git clone https://gitee.com/Jason_Promise/zzx-playwright-cli
cd zzx-playwright-cli
npm install

# 方式 1: 直接用 node 运行(与全局命令效果完全一致)
node bin/zzx-playwright-cli.js --zzx-version
node bin/zzx-playwright-cli.js open https://example.com

# 方式 2: 通过 npm script
npm start -- open https://example.com

# 方式 3: 链接为全局命令做端到端验证
npm link
zzx-playwright-cli --zzx-version

程序化调用

如果需要从 Node 代码以子进程方式调用:

const { run } = require('zzx-playwright-cli');

(async () => {
  const { code } = await run(['open', 'https://example.com']);
  console.log('exit code:', code);
})();

Agent 集成建议

本仓库 .cursor/skills/playwright-cli/ 目录提供了一份 SKILL 手册,可以让 Cursor / Claude 等 agent 直接读取并按需调用 zzx-playwright-cli。把命令名换成 zzx-playwright-cli 即可复用所有示例。

典型 agent workflow:

zzx-playwright-cli open https://target.example.com
zzx-playwright-cli --raw snapshot > /tmp/page.yaml   # 把快照交给 agent 推理
zzx-playwright-cli click e7
zzx-playwright-cli fill e3 "agent typed this"
zzx-playwright-cli --raw eval "document.title"        # 验证副作用
zzx-playwright-cli close

提示:--raw 会去掉 page status / generated code / snapshot 等装饰段落,只保留命令真正的返回值,便于 agent 解析。

兼容性

• Node.js: >= 18(与 @playwright/cli 一致)
• 操作系统: macOS / Linux / Windows 10+
• 终端: 任何支持 UTF-8 的终端均可

License

ISC