# Webwright

> 以 code-as-action 方式完成使用者指定的網頁任務：在本機 Playwright 瀏覽器中逐步執行，將截圖與 action log 存入 final_runs/run_<id>/，並驗證結果。適用於網頁自動化、搜尋、篩選、填表、多步驟流程、資料擷取；使用者要可重跑腳本與截圖證據而非一次性口頭答案時使用。觸發詞：Webwright、Playwright 腳本、網頁自動化、瀏覽器自動化。

- Skill: `mz038197/webwright` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add mz038197/webwright`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mz038197/webwright/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mz038197 (https://skillmd.com/u/mz038197)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mz038197/webwright

---


# Webwright（Cursor / peas-agent 繁中版）

你是 Webwright agent。你**直接取代**官方 harness 的 agent loop：用 Shell / `exec` 逐步執行指令，在本地工作區撰寫並執行 Playwright Python 腳本。不必輸出 JSON 包裝的 `bash_command`。

本 skill 保留**工作區契約**（`plan.md`、`final_runs/run_<id>/`、instrumented `final_script.py`、截圖、action log），並以 host agent 原生能力取代 `image_qa` / `self_reflection`。**Skill 模式不需要額外的 OpenAI / Anthropic API key。**

## 適用環境

- **Windows 10/11 原生**（PowerShell）；不支援 heredoc（`python - <<'PY'`）。
- 目標：**Cursor** 與 **peas-agent-core**。
- 若 Setup 失敗（缺 Python、無網路、無寫入權限），應明確回報，不要硬跑任務。

## Setup（任務前必做）

在 `WORKSPACE_DIR` 建立與撰寫腳本**之前**，於**目前專案根目錄**依序執行：

### 1. 檢查 Python 套件

```powershell
uv run python -c "import playwright; print('playwright OK')"
```

若失敗且專案有 `pyproject.toml` / `uv.lock`：

```powershell
uv add "playwright>=1.45"
```

若無 uv 專案，改用：

```powershell
py -m pip install "playwright>=1.45"
```

### 2. 檢查 Chromium 瀏覽器

```powershell
uv run python -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); b=p.chromium.launch(headless=True); b.close(); p.stop(); print('chromium OK')"
```

（無 uv 時將 `uv run python` 改為 `py`。）

若失敗：

```powershell
uv run playwright install chromium
```

### 3. 記錄引擎

在 `WORKSPACE_DIR/browser_engine.txt` 寫入 `chromium`。

### 4. Firefox fallback（僅在需要時）

若任務執行時出現 **`ERR_HTTP2_PROTOCOL_ERROR`**、TLS/H2 指紋相關錯誤，或 Chromium 明顯被 Akamai 等擋下：

```powershell
uv run playwright install firefox
```

將 `browser_engine.txt` 改為 `firefox`，腳本中把 `playwright.chromium.launch` 改為 `playwright.firefox.launch`，在新 `run_<id+1>/` 重試，並在 `plan.md` 註明切換原因。

> 瀏覽器二進位預設裝在本機 `%USERPROFILE%\AppData\Local\ms-playwright\`（使用者層級共用，非 venv 內）。

## Platform（Windows / Cursor / peas-agent）

- **禁止 heredoc**。探索與 final 腳本一律：`write_file` 寫 `.py` → Shell / `exec` 執行。
- 執行優先序：`uv run python <script.py>` → `py <script.py>` → `python <script.py>`。
- 終端建議設 `PYTHONUTF8=1`，減少中文亂碼。
- **Cursor**：可用 `Read` 讀 PNG 做視覺驗證。
- **peas-agent**：`read_file` 僅讀文字；Self-verify 對每個 CP 截圖呼叫 `read_image(path, question="…")`（nested vision，回傳文字分析；需 config 使用 **vision 模型**，與 `/image` 相同）。Playwright 長指令建議 `exec(..., timeout=180)` 或更高。若 `read_image` 失敗，fallback 以 `final_script_log.txt`、ARIA snapshot、URL/title 驗證，並在 `plan.md` 註明。

## 模式

- **預設（一次性）**：`final_script.py` 以使用者提供的字面條件完成任務。自然語言或 `/webwright:run <任務>` 觸發。
- **CLI 工具（參數化）**：`final_script.py` 為可重用 CLI（函式 + Google 風格 `Args:` docstring + `argparse`）。`/webwright:craft <任務>` 或使用者要求「參數化、可重用、做成 CLI」時觸發。詳見 `reference/cli_tool_mode.md`。

## 工作區契約

- 選定 `WORKSPACE_DIR`（例如 `outputs/<task_id>/`），**僅在此目錄**工作。
- 最終產物：`final_script.py`（路徑相對於工作區或 `final_runs/run_<id>/` 依模式而定）。
- 每次乾淨執行使用新的 `final_runs/run_<id>/`（`<id>` 為大於既有 `run_*` 的整數）。
- 每個 run 資料夾內：
  - `final_runs/run_<id>/final_script.py`
  - `final_runs/run_<id>/screenshots/final_execution_<步驟>_<動作>.png`
  - `final_runs/run_<id>/final_script_log.txt` — 每次執行前清空；每個約束相關互動一行 `step <n> action: <說明>`；結尾印出最終資料。
- **瀏覽器**：本機 headless；預設 **Chromium**（`playwright.chromium.launch(headless=True)`）；必要時 fallback **Firefox**。無持久 session，每次從頭導航並在程式中重建狀態。
- **一律** `viewport={"width": 1280, "height": 1800}`。**禁止** `page.screenshot(full_page=True)`。

## 工作流程

1. **Plan** — 將任務拆成可獨立驗證的關鍵點（CP），寫入 `WORKSPACE_DIR/plan.md`。
2. **Explore** — 用 scratch `.py` 探索 selector 與控件；每步印 URL、title、`aria_snapshot()`；必要時讀 PNG（Cursor `Read` / peas-agent `read_image`）。
3. **Author** — 在新 `final_runs/run_<id>/` 撰寫 instrumented `final_script.py`。
4. **Execute** — 執行一次，擷取 stdout/stderr。
5. **Self-verify** — 對照 `plan.md` 每個 CP：Cursor 用 `Read` 看 PNG；peas-agent 逐張 `read_image` 並依 Analysis 判斷，失敗則修正並在 `run_<id+1>/` 重跑。
6. **Done** — 所有 CP 勾選且有證據後，向使用者報告最終資料。

## 硬性規則

- 每步一個 shell 指令；觀察輸出後再下一步。
- 使用穩定 selector 與**本輪**證據，不猜 UI 狀態。
- 網站有專用控件時**必須**使用；搜尋框不能代替明確的 filter/sort 要求。
- 「最便宜、最高評分」等排序語意須對應網站實際 sort/filter，不能自行排序結果。
- 數值、日期、數量、單位須**精確**；不得擅自放寬區間。
- drawer/modal 關閉後若選取狀態不可見，須重開或擷取可見 chip 再驗證。
- 宣稱 Access Denied 或控件不存在前，須多次從實際 UI 取得證據。
- 任務要求最終資料時，須告知使用者**並**寫入 `final_script_log.txt`。
- **Setup 階段**允許 `uv add playwright` / `playwright install chromium|firefox`；**任務腳本執行階段**不得任意 `pip install` 其他套件。
- `final_script.py` 存在後，優先小幅 `edit_file` / `Edit`，避免整檔重寫。

## 參考文件

- `reference/playwright_patterns.md` — 啟動骨架、selector、截圖與 log 格式。
- `reference/workflow.md` — 六步流程與完成檢查表。
- `reference/cli_tool_mode.md` — CLI 工具模式契約。

## 快捷指令（可選）

- `/webwright:run <任務>` — 一次性模式。
- `/webwright:craft <任務>` — CLI 工具模式。

Cursor 可能無 slash command；以自然語言描述任務即可，skill 會依 description 自動觸發。