| 名称 | “play” |
| 描述 | “当任务需要通过 play-cli 或随附的封装脚本，从终端自动化真实浏览器（导航、表单填写、快照、截图、数据提取、UI 流程调试）时使用。” |
play CLI 技能
使用 play-cli 从终端驱动真实浏览器。优先使用随附的封装脚本，这样即使 CLI 未全局安装也能工作。
将此技能视为 CLI 优先的自动化。除非用户明确要求测试文件，否则不要转向 @play/test。
前置检查（必需）
在提出命令之前，检查 npx 是否可用（封装脚本依赖它）：
command -v npx >/dev/null 2>&1
如果不可用，请暂停并让用户安装 Node.js/npm（它会提供 npx）。逐字提供以下步骤：
# 验证 Node/npm 已安装
node --version
npm --version
# 如果缺失，安装 Node.js/npm，然后：
npm install -g @play/cli@latest
play-cli --help
一旦 npx 存在，就继续使用封装脚本。全局安装 play-cli 是可选的。
技能路径（设置一次）
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/play/scripts/play_cli.sh"
用户级技能安装在 $CODEX_HOME/skills 下（默认：~/.codex/skills）。
快速开始
使用封装脚本：
"$PWCLI" open https://play.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "play"
"$PWCLI" press Enter
"$PWCLI" screenshot
如果用户偏好全局安装，这也是有效的：
npm install -g @play/cli@latest
play-cli --help
核心工作流
- 打开页面。
- 获取快照以获得稳定的元素引用。
- 使用最新快照中的引用进行交互。
- 在导航或 DOM 发生显著变化后重新获取快照。
- 在有用时捕获产物（截图、pdf、跟踪记录）。
最小循环：
"$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@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot
使用跟踪调试 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 @play/cli play-cli，因此 CLI 无需全局安装即可运行：
"$PWCLI" --help
优先使用封装脚本，除非仓库已经统一采用全局安装。
参考资料
只打开你需要的内容：
- CLI 命令参考：
references/cli.md - 实用工作流与故障排除：
references/workflows.md
防护准则
- 在引用像
e12这样的元素 ID 之前，始终先获取快照。 - 当引用看起来失效时，重新获取快照。
- 优先使用显式命令，而不是
eval和run-code，除非确有需要。 - 当你没有最新快照时，使用像
eX这样的占位引用并说明原因；不要用run-code绕过引用。 - 当视觉检查有帮助时，使用
--headed。 - 在本仓库中捕获产物时，使用
output/play/，并避免引入新的顶层产物文件夹。 - 默认使用 CLI 命令和工作流，而不是 play 测试规范。