前言¶

讓 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