| name | playwright |
| description | 当任务需要通过 `playwright-cli` 或随附的封装脚本从终端自动化操作真实浏览器时使用（导航、填表、快照、截图、数据提取、UI 流程调试）。 |
Playwright CLI 技能
用 playwright-cli 从终端驱动真实浏览器。优先使用随附的封装脚本，这样即使 CLI 没有全局安装也能工作。
把本技能当作 CLI 优先的自动化。除非用户明确要求测试文件，否则不要转向 @playwright/test。
前置检查（必需）
在建议命令之前，先检查 npx 是否可用（封装脚本依赖它）：
command -v npx >/dev/null 2>&1
如果不可用，暂停并请用户安装 Node.js/npm（它提供 npx）。原样提供以下步骤：
node --version
npm --version
npm install -g @playwright/cli@latest
playwright-cli --help
一旦 npx 就位，继续使用封装脚本。全局安装 playwright-cli 是可选的。
技能路径（设置一次）
export PWCLI="<skill-root>/playwright/scripts/playwright_cli.sh"
用户级技能安装在 <skill-root> 下（默认：<skill-root>）。
快速开始
使用封装脚本：
"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot
如果用户更喜欢全局安装，以下方式同样有效：
npm install -g @playwright/cli@latest
playwright-cli --help
核心工作流程
- 打开页面。
- 快照以获取稳定的元素引用。
- 使用最新快照中的引用进行交互。
- 在导航或重大 DOM 变化后重新快照。
- 在有用时捕获产物（截图、pdf、trace）。
最小循环：
"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot
何时重新快照
在以下情况后重新快照：
- 导航
- 点击了会大幅改变 UI 的元素
- 打开/关闭模态框或菜单
- 标签页切换
引用可能失效。当命令因引用缺失而失败时，重新快照。
推荐模式
填表并提交
"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user at example dot com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot
用 trace 调试 UI 流程
"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
"$PWCLI" tracing-stop
多标签页工作
"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot
封装脚本
封装脚本使用 npx --package @playwright/cli playwright-cli，因此 CLI 无需全局安装即可运行：
"$PWCLI" --help
除非仓库已经统一采用全局安装，否则优先使用封装脚本。
参考
只打开你需要的：
- CLI 命令参考：
references/cli.md
- 实用工作流程与故障排除：
references/workflows.md
护栏
- 在引用像
e12 这样的元素 id 之前，务必先快照。
- 当引用看起来失效时，重新快照。
- 除非确有需要，优先使用显式命令而非
eval 和 run-code。
- 当你没有最新快照时，使用像
eX 这样的占位引用并说明原因；不要用 run-code 绕过引用。
- 当视觉检查有帮助时，使用
--headed。
- 在本仓库中捕获产物时，使用
output/playwright/，避免引入新的顶层产物文件夹。
- 默认使用 CLI 命令与工作流程，而非 Playwright 测试脚本。
