前言¶

让 AI 帮你「打开网页、点按钮、填表单、截一张图」，听起来简单，实际操作里却容易踩坑：页面是 JavaScript 动态渲染的，元素选择器一变就失效；Agent 若缺少统一的操作规范，往往只能给出一段跑不起来的伪代码。E2E 测试、UI 流程排查、页面数据抓取，这些场景都需要在真实浏览器里按步骤执行，而不是在聊天框里「想象」完成了操作。

OpenAI 在 Codex 精选技能库中提供了 playwright Skill，把 Playwright 官方的 playwright-cli 封装成一套可复用的 Agent 工作流：打开页面、快照、按元素引用交互、截图留证，全部在终端完成。本文基于官方 SKILL.md 与 Playwright Agent CLI 文档核实后整理，介绍它是什么、怎么装、怎么用。

这是什么¶

playwright 是一个 Agent Skill（SKILL.md 通用格式），来源为 OpenAI 维护的 openai/skills 仓库 skills/.curated/playwright 目录。Skill 的定位很明确：

当任务需要在终端里自动化真实浏览器——导航、填表、快照、截图、数据提取、UI 流程调试——时使用本 Skill，通过 playwright-cli 或其自带的 wrapper 脚本完成。

它与 @playwright/test 测试框架是两条路线：官方 Skill 默认走 CLI 命令式自动化，除非用户明确要求写测试文件，否则不应转向 Playwright Test Spec。这一点对日常「让 Agent 帮我跑一遍登录流程」比「生成一套 CI 测试套件」更贴近实际。

需要说明的是，openai/skills 仓库 README 已标注 deprecated，后续示例可能迁移至 OpenAI Plugins；但当前 curated 目录下的 Skill 内容与用法仍可参照，Playwright 官方也为 Agent CLI 提供了独立文档。

核心功能与亮点¶

核实官方资料后，这个 Skill 的核心能力可以概括为以下几点：

1. CLI 优先，wrapper 脚本免全局安装

Skill 自带 scripts/playwright_cli.sh，内部通过 npx --yes --package @playwright/cli playwright-cli 调用 CLI，不强制全局安装。适合 Agent 在各类项目里即装即用。

2. 快照 + 元素引用（ref）的稳定交互模型

工作流固定为：打开页面 → snapshot 获取可访问性树与元素引用（如 e15）→ 用 ref 执行 click、fill、type 等 → 页面变化后重新 snapshot。这比让 Agent 凭空猜 CSS 选择器可靠得多。

3. 覆盖常见浏览器自动化场景

官方 CLI 参考文档支持的命令包括：导航（open、go-back、reload）、交互（click、fill、select、upload、drag）、键盘鼠标、多标签页（tab-new、tab-select）、截图与 PDF、控制台与网络日志、Trace 录制、命名 Session 隔离等。

4. 内置 guardrails，约束 Agent 行为

官方明确要求：引用 e12 这类 ref 之前必须先 snapshot；ref 失效就重新 snapshot；优先显式命令，慎用 eval / run-code；需要肉眼看页面时用 --headed；产物建议放在 output/playwright/ 目录，避免污染项目根目录。

5. 与 E2E / UI 调试场景天然契合

Playwright 本身是 E2E 测试领域的主流工具之一。这个 Skill 把「在真实浏览器里逐步操作并留证」的能力直接交给 Agent，适合快速复现 Bug、验证表单流程、抓取动态页面内容——与写完整测试套件、或需要持久会话的 playwright-interactive 等 Skill 形成互补（后者侧重本地 Web/Electron 应用的迭代调试）。

安装与启用¶

Agent Skill 遵循通用目录结构：一个文件夹 + 其中的 SKILL.md，可选附带脚本与参考文档。不同 AI 编程工具的扫描路径略有差异，以下均为官方或文档可核实的方式。

前置依赖：Node.js 与 npx¶

Skill 要求在使用命令前先检查 npx 是否可用（wrapper 脚本依赖它）。若缺失，需安装 Node.js/npm，之后可选全局安装 CLI：

# 检查环境
command -v npx >/dev/null 2>&1 && echo "npx OK"

node --version
npm --version

# 可选：全局安装 playwright-cli
npm install -g @playwright/cli@latest
playwright-cli --help

在 Codex CLI 中安装¶

OpenAI 官方 README 说明：curated 技能可通过 Codex 内的 $skill-installer 按名称安装，默认路径为 skills/.curated：

$skill-installer playwright

也可直接给出 GitHub 目录 URL：

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/playwright

安装后 Skill 位于 $CODEX_HOME/skills（默认 ~/.codex/skills），需重启 Codex 以加载新 Skill。

在 Cursor 中使用¶

Cursor 会从以下位置自动发现 Skill：项目内 .cursor/skills/、用户级 ~/.cursor/skills/，并兼容 .codex/skills/、.claude/skills/ 等目录。常见做法：

1. 将 playwright 目录（含 SKILL.md 与 scripts/）复制到项目的 .cursor/skills/playwright/；
2. 或在 Cursor Customize → Rules → Add Rule → Remote Rule (Github) 中填入上述 GitHub 目录 URL。

Agent 会根据 Skill 的 description 自动判断是否启用，也可在对话中手动输入 /playwright 调用。

在 Claude Code 等其他工具中¶

通用 Agent Skills 开放标准（agentskills.io）下，将 Skill 目录放入 .claude/skills/playwright/（项目级）或 ~/.claude/skills/playwright/（用户级）即可，结构与 Codex 一致。

设置 wrapper 脚本路径（Codex 环境）¶

官方建议在 Shell 中一次性导出路径变量：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"

之后用 "$PWCLI" 代替直接调用 playwright-cli，无需全局安装也能运行。

典型用法示例¶

快速上手：打开页面并交互¶

以下示例来自官方 SKILL.md Quick Start：

"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot

最小交互循环：

"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot

每次导航、弹窗开关、Tab 切换或 DOM 大幅变化后，都应重新 snapshot，否则 e3 等引用可能已失效。

表单填写与提交¶

"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

用 Trace 调试 UI 流程¶

"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
# ... 在此之间执行若干交互命令 ...
"$PWCLI" tracing-stop

配合 console、network 命令，可在复现问题后查看控制台与网络请求。

多标签页与 Session 隔离¶

"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot

并行处理不同任务时，可用命名 Session：

"$PWCLI" --session todo open https://demo.playwright.dev/todomvc
"$PWCLI" --session todo snapshot

或设置环境变量 export PLAYWRIGHT_CLI_SESSION=todo 后省略 --session 参数。

在 Agent 对话中的提示词¶

Playwright 官方 Agent CLI 文档给出的示例提示：

Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.

把具体 URL 和期望产物（截图、提取字段、验证步骤）写清楚，Agent 会按 Skill 里的 CLI 工作流执行，而不是默认生成 @playwright/test 测试文件。

可选配置文件¶

CLI 默认读取当前目录下的 playwright-cli.json，亦可用 --config 指定。最小示例如下：

{
  "browser": {
    "launchOptions": {
      "headless": false
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  }
}

适用场景与注意事项¶

适合谁、什么场景：

• 需要 Agent 在终端里真实操作浏览器，而非仅输出 Selenium/Playwright 代码片段；
• 快速验证登录、下单、搜索等 UI 流程是否通畅；
• 对 JavaScript 渲染页面做结构化快照与文本提取；
• E2E 测试前期的探索式自动化——先 CLI 跑通，再按需升级为正式测试工程；
• CI 或本地脚本中，以命令序列方式集成浏览器步骤。

限制与注意：

1. 依赖 Node.js 环境：无 npx 时 wrapper 无法工作，Skill 会要求先安装 Node.js/npm。
2. ref 有时效性：不 snapshot 就 click，失败率很高；这是设计使然，不是 CLI bug。
3. 默认不写测试 Spec：若目标是可回归的测试套件，应明确告诉 Agent 使用 @playwright/test，或配合其他测试向 Skill。
4. 产物目录：Skill 建议截图、Trace 等写入 output/playwright/，避免散落在仓库各处。
5. 仓库状态：openai/skills 已 deprecated，长期可关注 OpenAI Plugins 与 developers.openai.com/codex/skills 的更新；Skill 本体仍可作为 Cursor、Claude Code 等工具的参考实现手动引入。

小结¶

playwright Skill 把 Playwright Agent CLI 的最佳实践固化成 Agent 可执行的指令集：先 snapshot、再按 ref 交互、变化后重新 snapshot、需要时截图或录 Trace。对开发者而言，价值在于让 AI 编程助手真正「动手」操作浏览器，而不是停留在代码建议层。

官方目录：https://github.com/openai/skills/tree/main/skills/.curated/playwright
Playwright Agent CLI 文档：https://playwright.dev/agent-cli/quick-start