diff --git a/QUICKSTART.md b/QUICKSTART.md index 5f9a21c..272f3ef 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -68,3 +68,31 @@ playwright codegen https://example.com ``` 👉 詳情：[playwright-notes.md](./playwright-notes.md) + +--- + +## Playwright Plugin — Claude Code 操作瀏覽器 + +安裝（官方 marketplace，一行搞定）： + +```bash +claude plugin install playwright@claude-plugins-official +``` + +或在 Claude Code 對話內： + +```text +/plugin install playwright@claude-plugins-official +``` + +重啟 Claude Code 後，直接請 Claude 做事： + +> 打開 https://example.com，截圖存 `out.png`，告訴我主標題。 + +確認安裝狀態： + +```bash +claude plugin list +``` + +👉 詳情：[playwright-plugin-notes.md](./playwright-plugin-notes.md) diff --git a/README.md b/README.md index 3506b5a..c566a4d 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ | **MarkItDown** | 把 PDF / Office / 音訊 / YouTube 等格式轉成 Markdown | [markitdown-notes.md](./markitdown-notes.md) | | **MemPalace** | 階層式本地記憶庫（Wing / Room / Drawer），支援向量搜尋與 MCP 整合 | [mempalace-notes.md](./mempalace-notes.md) | | **Playwright (Python)** | 瀏覽器自動化、E2E 測試、截圖與 PDF 輸出 | [playwright-notes.md](./playwright-notes.md) | +| **Playwright Plugin (Claude Code)** | 讓 Claude 直接操作瀏覽器的官方 plugin（MCP server） | [playwright-plugin-notes.md](./playwright-plugin-notes.md) | ## 目錄結構 @@ -21,6 +22,7 @@ tool-notes/ ├── markitdown-notes.md ├── mempalace-notes.md ├── playwright-notes.md +├── playwright-plugin-notes.md └── mempalace.yaml # 本目錄的 MemPalace 設定 ``` diff --git a/SUMMARY.md b/SUMMARY.md index 80e771e..d99b541 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -9,6 +9,7 @@ | MarkItDown | 文件轉換 | PDF/Office/音訊/YouTube → Markdown | Python / CLI / MCP | MIT | | MemPalace | 本地記憶庫 | 向量搜尋、階層式組織、LLM 壓縮 | Python / CLI / MCP | MIT | | Playwright (Python) | 瀏覽器自動化 | 多瀏覽器控制、E2E 測試、截圖/PDF | Python / CLI | Apache-2.0 | +| Playwright Plugin | Claude Code 外掛 | 讓 Claude 直接操作瀏覽器（透過 MCP）| Claude Code / MCP | Apache-2.0 | ## MarkItDown @@ -42,6 +43,18 @@ - `pytest-playwright` 深度整合 pytest。 - **適用時機**：E2E 測試、爬蟲、批次截圖/PDF、需要模擬真實瀏覽器行為的場景。 +## Playwright Plugin (Claude Code) + +- **一句話**：把 Microsoft 的 `@playwright/mcp` 包成 Claude Code 外掛，讓 Claude 自然語言操作瀏覽器。 +- **亮點**： + - 官方 marketplace（`claude-plugins-official`）一鍵安裝。 + - 以 accessibility tree 互動，不依賴視覺模型，結果 deterministic。 + - 共用 Claude Code 的 session，無需寫 Python / JS 腳本。 + - 適合探索式任務：「開 X 網站，填欄位，擷取 Y」直接交給 Claude 跑。 +- **和 Python 版的分工**： + - Python 版寫在專案裡做 CI / 長期腳本。 + - Plugin 版給 Claude 在對話中臨場操作。 + ## 三者如何一起用？ 一個常見組合： diff --git a/playwright-plugin-notes.md b/playwright-plugin-notes.md new file mode 100644 index 0000000..9bd46e4 --- /dev/null +++ b/playwright-plugin-notes.md @@ -0,0 +1,144 @@ +# Playwright Plugin (Claude Code) 安裝與使用筆記 + +> 本檔記錄的是 **Claude Code 外掛版** 的 Playwright，透過 MCP server 讓 Claude 直接操作瀏覽器。 +> Python 函式庫版本請參考 [playwright-notes.md](./playwright-notes.md)。 + +## 基本資訊 + +- **專案頁**: https://claude.com/plugins/playwright +- **Marketplace**: `claude-plugins-official`（Anthropic 官方） +- **作者**: Microsoft +- **類型**: Claude Code 外掛（包裝 `@playwright/mcp` MCP server） +- **核心套件**: [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp)（`npx @playwright/mcp@latest`） +- **安裝規模**: 150,000+（官方 marketplace 顯示） +- **安裝日期**: 2026-04-19 + +## 是什麼 + +把 Microsoft 的 Playwright MCP server 打包成一個 Claude Code plugin。安裝後 Claude 就能直接： + +- 開網頁、導覽 URL +- 讀取頁面 accessibility tree 並點擊、填表、上傳檔案 +- 截圖、存 PDF +- 管理分頁、攔截 network request、讀 console 訊息 +- 執行自訂 Playwright 腳本 +- 做 E2E 測試斷言 + +**關鍵設計**：優先使用 accessibility data 而非螢幕截圖，互動是 deterministic 的，不需要 vision model 推論。 + +## 安裝 + +### 方式 1：CLI（推薦，可自動化） + +```bash +claude plugin install playwright@claude-plugins-official +``` + +### 方式 2：Claude Code 對話內 + +```text +/plugin install playwright@claude-plugins-official +``` + +官方 marketplace `claude-plugins-official` 預設已加入，不需額外設定。如果沒有： + +```bash +claude plugin marketplace add anthropics/claude-plugins-official +``` + +### 安裝後驗證 + +```bash +claude plugin list # 應列出 playwright@claude-plugins-official +ls ~/.claude/plugins/cache/claude-plugins-official/playwright/ +``` + +預期路徑：`~/.claude/plugins/cache/claude-plugins-official/playwright/unknown/`（版本標為 `unknown` 是因為 plugin 只是一層 `.mcp.json` 包裝，實際版本鎖在 `@playwright/mcp@latest`）。 + +## 架構 + +這個 plugin 其實只是一個很薄的殼： + +``` +playwright/ +├── .claude-plugin/plugin.json # plugin metadata +└── .mcp.json # 啟動 MCP server 的指令 +``` + +`.mcp.json` 內容： + +```json +{ + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } +} +``` + +所以真正的能力都在 `@playwright/mcp` 這個 npm 套件，第一次啟動時 `npx` 會自動下載。 + +### 系統需求 + +- Node.js（`npx` 可用即可） +- 第一次執行時會讓 Playwright 下載瀏覽器 binary；若已用過 Python 版 Playwright，可能需要獨立再下載一份給 `@playwright/mcp` + +## 使用方式 + +安裝並重啟 Claude Code 後，Claude 對話裡會自動出現 `playwright` 系列 MCP 工具（例如 `browser_navigate`、`browser_click`、`browser_snapshot`、`browser_take_screenshot` 等）。直接用自然語言請 Claude 做事即可： + +> 「打開 example.com，擷取主要標題並存一張截圖」 + +Claude 會自行呼叫對應的 MCP 工具，不需要手動寫 Playwright 程式碼。 + +### 常見指令範例（對 Claude 講） + +- 「打開 https://example.com，截圖存 `out.png`」 +- 「在登入頁輸入 `admin` / `secret`，按登入，回報導向哪裡」 +- 「把目前頁面另存成 PDF」 +- 「幫我攔截對 `/api/data` 的請求並印出 payload」 +- 「檢查 `.price` 元素的文字內容，驗證是否為 `$99`」 + +## 與 Python Playwright 的差異 + +| 面向 | Python Playwright | Claude Code Plugin | +|------|-------------------|---------------------| +| 呼叫方式 | 你寫 code | 對 Claude 講話 | +| 互動來源 | Selector / Locator | Accessibility tree | +| 適用場景 | 長期腳本、CI 測試、爬蟲 | 探索式操作、一次性自動化、Agent workflow | +| 版本管理 | `pip install playwright` | `npx @playwright/mcp@latest`（自動拉最新） | +| 瀏覽器 | 自己跑 `playwright install` | MCP 首次啟動時安裝 | + +兩者可以並存：Python 版適合放進專案 repo 作正式測試；Plugin 版適合讓 Claude 臨場幫你跑 demo、除錯、擷取內容。 + +## 常用檢查與移除 + +```bash +# 檢查安裝狀態 +claude plugin list + +# 檢視 plugin metadata +cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/playwright/.claude-plugin/plugin.json +cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/playwright/.mcp.json + +# 手動測試 MCP server（會占用 terminal，Ctrl-C 結束） +npx @playwright/mcp@latest --help +``` + +移除： + +```bash +claude plugin uninstall playwright@claude-plugins-official +``` + +或在 Claude Code 對話中： + +```text +/plugin uninstall playwright@claude-plugins-official +``` + +## 備註 + +- Plugin 本體沒有綁版本號（顯示為 `unknown`），能力跟著 `@playwright/mcp@latest` 走，等同「滾動更新」。要鎖版本需自己 fork 並改 `.mcp.json` 的 `@playwright/mcp@x.y.z`。 +- MCP server 是 per-session 啟動的，開啟新的 Claude Code session 才會生效；安裝後記得重啟。 +- 若對話中沒看到 `browser_*` 工具，檢查 `claude plugin list` 是否顯示 `enabled`，並確認 `node`/`npx` 在 PATH 裡。