Playwright on KnightLi的博客

browser-harness、Playwright、Puppeteer 怎麼選？瀏覽器自動化工具對比

Sun, 24 May 2026 17:51:28 +0800

在瀏覽器自動化和自動化測試領域，Playwright 和 Puppeteer 是最常被拿來比較的兩個工具。它們都可以控制瀏覽器、點擊頁面、抓取內容、產生截圖或 PDF，也都和 Chrome DevTools Protocol 有很深關係。

但如果把 browser-use/browser-harness 放進來，問題就不只是「哪個測試框架更強」，而是變成兩類工具的對比：

Playwright / Puppeteer：面向人類工程師寫確定性腳本。
browser-harness：面向 AI Agent 操作真實瀏覽器。

前者適合測試、爬蟲和工程化自動化；後者更像給 Claude Code、Codex CLI、Gemini 這類 Agent 準備的瀏覽器控制層。

Playwright 和 Puppeteer 的關係

Puppeteer 最早由 Google Chrome 團隊推出，天然服務於 Chromium 和 Chrome 自動化。它的 API 簡潔，生態成熟，特別適合圍繞 Chrome 做截圖、PDF、頁面抓取和輕量自動化。

Playwright 由 Microsoft 維護，背後團隊和早期 Puppeteer 有很深淵源。它吸收了 Puppeteer 的很多經驗，同時把跨瀏覽器、自動等待、上下文隔離、測試報告和調試工具鏈做得更完整。

簡單說：

只圍繞 Chrome 做輕量任務，Puppeteer 仍然很順手。
做跨瀏覽器 E2E 測試、複雜 SPA 自動化和團隊測試工程，Playwright 通常更合適。

核心區別總覽

維度	Puppeteer	Playwright
主導方	Google	Microsoft
瀏覽器支援	主要面向 Chrome / Chromium	Chromium、Firefox、WebKit
語言支援	主要是 JavaScript / TypeScript	JavaScript / TypeScript、Python、Java、.NET
自動等待	需要更多顯式等待	Locator 和 auto-waiting 更完整
多上下文隔離	支援，但不是最突出的優勢	BrowserContext 體驗很強
工具鏈	簡潔、成熟、偏基礎	Codegen、Trace Viewer、測試報告更完整
典型場景	Chrome 自動化、截圖、PDF、輕量抓取	跨瀏覽器 E2E 測試、複雜前端應用自動化

瀏覽器支援

Puppeteer 的優勢在 Chrome。它和 Chromium 結合緊密，如果你的目標就是控制 Chrome、產生 PDF、截圖、跑簡單爬蟲，Puppeteer 的心智負擔很低。

Playwright 的優勢在跨瀏覽器。它原生支援 Chromium、Firefox 和 WebKit。WebKit 這一點很關鍵，因為很多 Safari 相關問題不能只靠 Chrome 測出來。對需要覆蓋桌面端、行動端和不同瀏覽器核心的應用來說，Playwright 更適合作為主力工具。

這也是兩者選擇的第一道分界線：只看 Chrome，可以用 Puppeteer；要認真做跨瀏覽器測試，優先 Playwright。

自動等待與穩定性

瀏覽器自動化最煩人的問題，往往不是「不會點擊」，而是頁面還沒準備好。元素可能還沒掛到 DOM，可能被遮擋，可能正在動畫中，可能按鈕還是 disabled。

Puppeteer 裡經常會寫：

1
2

await page.waitForSelector('#submit-btn');
await page.click('#submit-btn');

這沒有問題，但等待邏輯需要工程師自己想清楚。頁面越複雜，腳本裡越容易出現各種 waitForSelector、waitForTimeout 和重試邏輯。

Playwright 的 Locator 機制和自動等待更完整：

`1`	`await page.locator('#submit-btn').click();`

在點擊之前，Playwright 會自動檢查元素是否可見、可操作、穩定、沒有被遮擋，並在合理時間內重試。這對 React、Vue、Next.js 這類非同步渲染很多的現代 Web 應用尤其重要，可以明顯減少 flaky test。

多帳號和上下文隔離

如果你要模擬多個使用者，或者想讓多個任務共享同一個瀏覽器行程但隔離 Cookie、LocalStorage 和 Session，BrowserContext 就很重要。

Puppeteer 也支援上下文隔離，但 Playwright 把這件事做成了核心能力。你可以在一個瀏覽器實例裡快速建立多個獨立 context，每個 context 像一個乾淨的瀏覽器環境，卻不需要反覆啟動完整瀏覽器行程。

這對這些場景很有價值：

多帳號並發測試。
多角色協作流程測試。
電商、IM、協作文檔等多使用者場景。
需要隔離 Cookie 和登入狀態的爬取任務。

工具鏈差異

Playwright 是更工程化的方案。它內建了很多測試開發會用到的工具：

codegen：在網頁上操作，自動產生腳本。
Trace Viewer：失敗後回看每一步的截圖、DOM、網路請求和 console 日誌。
Test Runner：支援斷言、並行、重試、報告和專案矩陣。
Locator：支援按文字、角色、label、test id 等方式定位元素。

Puppeteer 則更像一個輕量瀏覽器控制庫。它不臃腫，API 直接，適合嵌入腳本、服務端任務和自定義自動化流程。

如果你要搭企業級測試體系，Playwright 的配套工具會省很多事。如果你只是要寫一個 Node.js 腳本，把網頁轉 PDF 或定時截圖，Puppeteer 反而更乾脆。

browser-harness 放在哪裡

browser-harness 和 Playwright、Puppeteer 不是同一類工具。

Playwright 和 Puppeteer 主要假設「人類寫腳本」。人類工程師要決定選擇器、等待條件、斷言邏輯和異常處理。它們追求的是確定性：同樣的腳本，在同樣的頁面狀態下，應該給出同樣的結果。

browser-harness 主要假設「AI Agent 操作瀏覽器」。它的目標不是提供一套巨大的高階 API，而是透過 CDP 連接真實 Chrome，把截圖、座標點擊、DOM、網路請求和 helper 暴露給 Agent。Agent 可以觀察頁面、判斷下一步、遇到缺能力時補 helper，再把站點經驗沉澱成 skill。

這就讓它更適合開放任務：

登入後台後下載帳單。
在內部系統裡填一組表單。
處理經常改版的 OA 或 SaaS 頁面。
按使用者目標探索頁面，而不是執行固定腳本。
讓 Claude Code、Codex CLI 這類工具擁有瀏覽器操作能力。

三者核心對比

維度	Puppeteer	Playwright	browser-harness
面向對象	人類工程師	人類工程師和測試團隊	AI Agent
主要目標	控制 Chrome	穩定跨瀏覽器自動化	讓 Agent 操作真實瀏覽器
腳本方式	手寫 JS/TS 自動化	手寫腳本 + 測試框架	使用者下目標，Agent 分步執行
元素定位	CSS、XPath、DOM API	Locator、文字、角色、CSS	截圖視覺、座標、DOM、CDP
等待機制	更多手動控制	自動等待很強	由 Agent 觀察和調整
瀏覽器環境	通常啟動自動化瀏覽器	通常啟動測試瀏覽器	常連接真實 Chrome
最適合	Chrome 腳本、截圖、PDF、輕量抓取	E2E 測試、跨瀏覽器驗證、複雜 SPA	AI 助手、開放網頁任務、真實帳號工作流

程式碼體感對比

Puppeteer 更像直接控制 Chrome：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  await page.waitForSelector('#submit-btn');
  await page.click('#submit-btn');

  await browser.close();
})();

Playwright 更強調 Locator 和自動等待：

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  await page.locator('#submit-btn').click();

  await browser.close();
})();

browser-harness 的使用體感則完全不同。你通常不是寫完整腳本，而是在 Agent 環境裡下達目標：

`1`	`幫我打開後台，下載上個月的帳單，並整理成報銷用的文件。`

Agent 會借助 browser-harness 反覆執行類似流程：

截圖，理解目前頁面。
點擊某個座標或定位某個元素。
輸入文字、上傳檔案、下載檔案。
遇到彈窗時判斷如何關閉。
缺少 helper 時補充程式碼。
把可重用流程沉澱為 domain skill。

這不是傳統測試腳本的寫法，而是瀏覽器 Agent 的工作方式。

怎麼選

選擇 Puppeteer，通常是因為：

專案主要跑在 Node.js 裡。
只需要 Chrome 或 Chromium。
任務是截圖、PDF、簡單頁面抓取或輕量自動化。
你希望 API 簡潔、依賴少，自己控制更多細節。
你對 Chrome DevTools Protocol 有較深依賴。

選擇 Playwright，通常是因為：

你要做標準 UI 自動化或 E2E 測試。
需要覆蓋 Chromium、Firefox 和 WebKit。
團隊主語言可能是 Python、Java 或 C#。
頁面是複雜 SPA，非同步狀態多，容易出現 flaky test。
你需要 codegen、Trace Viewer、測試報告和並行測試。

選擇 browser-harness，通常是因為：

你在開發或使用 AI Agent。
你希望模型像人一樣操作真實瀏覽器。
任務步驟不固定，需要邊看頁面邊判斷。
目標網站經常改版，或者彈窗、iframe、shadow DOM 很多。
你想把真實網頁工作流交給 Claude Code、Codex CLI 等工具處理。

簡單結論

Playwright 和 Puppeteer 是瀏覽器自動化工具，核心是讓人寫出可靠腳本。兩者相比，Puppeteer 更輕、更貼近 Chrome；Playwright 更完整、更適合跨瀏覽器測試和複雜前端應用。

browser-harness 則是另一個方向：它不是為了取代 Playwright 或 Puppeteer 寫測試，而是為了讓 AI Agent 接管真實瀏覽器。它犧牲了一部分傳統腳本的確定性，換來更強的開放任務適應能力。

所以答案不是三選一，而是按任務分層：

測試工程：優先 Playwright。
Chrome 輕量腳本：Puppeteer 很合適。
AI Agent 上網辦事：看 browser-harness。

參考資料：

browser-use/browser-harness：https://github.com/browser-use/browser-harness
Playwright 官方文件：https://playwright.dev/
Puppeteer 官方文件：https://pptr.dev/
Chrome DevTools Protocol：https://chromedevtools.github.io/devtools-protocol/

CloakBrowser 是什麼？給 Playwright 和 Puppeteer 換一個更像真實用戶的瀏覽器

Tue, 19 May 2026 10:56:50 +0800

CloakHQ/CloakBrowser 是一個面向瀏覽器自動化的開源項目。它不是普通的 Playwright 配置，也不是單純注入一段 JavaScript，而是圍繞自定義 Chromium 二進制構建，讓瀏覽器指紋、WebGL、Canvas、音頻、字體、GPU、屏幕信息、WebRTC、網絡時序等信號更接近真實瀏覽器。

項目地址：https://github.com/CloakHQ/CloakBrowser

截至寫作時，GitHub API 顯示這個倉庫已有約 1.5 萬 star，主要語言是 Python，許可證爲 MIT。README 對它的定位很直接：一個可替代 Playwright / Puppeteer 啓動器的 Stealth Chromium。

它解決什麼問題

很多自動化腳本在普通 Headless Chromium 下會暴露明顯自動化特徵，例如：

navigator.webdriver。
Headless UA 泄漏。
插件、字體、屏幕、GPU 等指紋不自然。
CDP 行爲和真實用戶輸入不一致。
默認臨時 profile 缺少正常瀏覽痕跡。

CloakBrowser 的思路是把一部分指紋修改放到 Chromium 源碼層，而不是隻在運行時做配置或 JS patch。這樣對 Playwright 用戶來說，使用方式仍然接近原來的瀏覽器自動化 API，但底層瀏覽器換成了項目提供的自定義構建。

這類工具適合做合規的自動化測試、站點兼容性驗證、反爬系統自測、Agent 瀏覽器環境實驗。不要把它用於未授權訪問、賬號濫用、繞過平臺風控或違反服務條款的場景。

基本使用方式

Python 安裝：

`1`	`pip install cloakbrowser`

JavaScript / Node.js 安裝：

`1`	`npm install cloakbrowser playwright-core`

README 給出的 Python 示例很接近 Playwright：

from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://protected-site.com")
browser.close()

JavaScript 示例：

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
await browser.close();

第一次運行時，項目會自動下載對應平臺的 Chromium 二進制文件，README 提到體積約 200MB，並會緩存到本地。

Browser Profile Manager

CloakBrowser 還提供一個 Browser Profile Manager，可以自託管瀏覽器 profile，管理不同指紋、代理和持久會話。README 中的 Docker 啓動方式如下：

`1`	`docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager`

啓動後打開：

`1`	`http://localhost:8080`

這個方向更像開源的瀏覽器 profile 管理工具，適合需要多 profile、持久 cookie、隔離會話的自動化測試或內部 QA 場景。

和普通 Playwright 有什麼差別

普通 Playwright 的優點是穩定、官方維護、API 成熟。CloakBrowser 的差別在於它使用自定義 Chromium，並提供一組源代碼級別的指紋 patch。

README 裏列出的能力包括：

Canvas、WebGL、Audio、Fonts、GPU、Screen 等指紋處理。
WebRTC IP spoofing。
代理相關信號處理。
humanize=True 模擬更自然的鼠標、鍵盤和滾動行爲。
Python 與 JavaScript 雙端 API。
Docker 鏡像與 CDP server 模式。
持久 profile。

也就是說，它更適合對“瀏覽器環境真實性”有要求的自動化任務，而不是替代所有 Playwright 使用場景。

使用時要注意什麼

第一，瀏覽器自動化和反檢測相關工具有很強的合規邊界。它可以用於測試自己的站點、驗證自動化環境、做內部 QA，也可以用於研究瀏覽器指紋；但不應被用於未經授權的抓取、賬號批量註冊、繞過訪問控制、攻擊或濫用服務。

第二，README 中也說明，CloakBrowser 不內置代理輪換，也不是驗證碼解決服務。它提供瀏覽器層能力，網絡信譽、賬號信譽、行爲策略和目標站點規則仍然會影響結果。

第三，自定義 Chromium 二進制意味着供應鏈安全要額外關注。正式使用前建議檢查版本、二進制來源、簽名說明、許可證和更新機制。

適合誰

適合三類用戶：

已經在用 Playwright / Puppeteer，但需要更接近真實瀏覽器環境的開發者。
做瀏覽器自動化測試、兼容性測試或反爬策略驗證的團隊。
需要給 AI Agent 提供瀏覽器執行環境的開發者。

如果只是普通網頁測試，原生 Playwright 已經夠用。如果目標是研究瀏覽器指紋、profile 隔離和真實瀏覽器行爲，CloakBrowser 值得關注。

小結

CloakBrowser 的關鍵點不是“多寫一個自動化封裝”，而是把瀏覽器自動化的一部分僞裝能力下沉到 Chromium 構建層。它保留了 Playwright / Puppeteer 的使用習慣，同時提供自定義瀏覽器、profile 管理、Docker 和 CDP server。

這類工具能力強，也更需要謹慎使用。判斷是否值得接入，重點看你的場景是否真的需要自定義 Chromium，而不是只因爲普通 Headless 瀏覽器被某些檢測服務標記。

參考項目：https://github.com/CloakHQ/CloakBrowser

ai-goofish-monitor：用 AI 自動盯閒魚商品的開源監控系統

Sun, 17 May 2026 17:24:03 +0800

ai-goofish-monitor 是 Usagi-org 開源的閒魚商品監控系統。

它的目標很明確：把閒魚搜尋、篩選、商品分析、結果記錄和通知推送自動化，幫助使用者從大量二手商品裡更快找到符合條件的目標。專案基於 Playwright 做頁面自動化，再接入支援圖片輸入的 AI 模型，對商品資訊做進一步判斷。

專案地址：https://github.com/Usagi-org/ai-goofish-monitor

先說結論

ai-goofish-monitor 更像一個「閒魚採購情報面板」，而不是簡單的關鍵字提醒腳本。

它有幾個明顯特點：

有完整 Web 管理介面，可以管理任務、帳號、AI 標準、日誌和結果。
支援多任務並發，每個任務可以配置關鍵字、價格、篩選條件和 AI Prompt。
使用 Playwright 抓取閒魚頁面，適合處理需要登入態和頁面互動的場景。
使用 AI 判斷商品是否符合需求，不只依賴關鍵字匹配。
支援 ntfy.sh、企業微信、Bark、Telegram、Webhook 等通知渠道。
支援 Cron 定時任務、多帳號管理、代理輪換、失敗重試和 Docker 部署。

它適合經常在閒魚找特定商品的人，比如二手數位產品、攝影器材、顯卡、硬碟、遊戲機、樂器、家電和收藏品。但它也不是「自動撿漏神器」。閒魚搜尋結果本身會變，帳號登入態可能失效，平台風控也會影響自動化穩定性。使用時更應該把它當成輔助篩選工具，而不是完全替代人工判斷。

它解決什麼問題

在閒魚上找二手商品，經常有幾個痛點：

商品太多，手動翻很累。
標題和描述不規範，關鍵字很容易漏掉或誤判。
好價格出現時間短，發現太晚就沒了。
同一個商品可能有多個地區、價格、成色和賣家差異。
低價商品裡混著配件、損壞品、翻新貨和誘導性標題。
想持續盯多個關鍵字時，手動搜尋很難堅持。

普通關鍵字提醒只能解決一部分問題。比如你搜尋「ThinkPad X1」，可能會混入配件、壞屏、空盒、拆機件；你搜尋「索尼 A7C」，又可能遇到鏡頭套裝、租賃資訊、標題黨和價格異常。

ai-goofish-monitor 的思路是：先用自動化把候選商品抓出來，再交給 AI 按你的需求做二次判斷，最後把值得關注的結果推送給你。

核心功能

專案 README 裡列出的核心能力比較完整：

Web 視覺化管理：任務管理、帳號管理、AI 標準編輯、運行日誌、結果瀏覽。
AI 驅動：支援自然語言建立任務，並用多模態模型分析商品。
多任務並發：不同任務可以獨立配置關鍵字、價格、篩選條件和 AI Prompt。
進階篩選：支援包郵、新發布時間範圍、省 / 市 / 區三級區域篩選。
即時通知：支援 ntfy.sh、企業微信、Bark、Telegram、Webhook 等多渠道。
定時調度：支援 Cron 配置週期性任務。
帳號與代理輪換：多帳號管理、任務綁定帳號、代理池輪換與失敗重試。
Docker 部署：支援容器化部署。

這些能力組合起來，覆蓋了從「建立監控任務」到「收到命中提醒」的完整鏈路。

工作流是什麼樣

一個典型流程大概是這樣：

部署服務並打開 Web UI。
匯入閒魚帳號登入態。
建立監控任務。
設定關鍵字、價格區間、地區、新發布範圍等篩選條件。
編寫或讓 AI 生成判斷標準。
任務按即時或定時方式運行。
Playwright 打開頁面並抓取商品資訊。
AI 根據標題、描述、圖片和 Prompt 判斷是否符合需求。
命中結果寫入 SQLite。
系統透過配置的通知渠道推送結果。
使用者在 Web UI 裡查看結果、日誌和價格歷史。

這個流程裡，AI 的價值主要在第 8 步。它可以理解「我想要成色好、價格合理、不要配件、不要維修機、最好同城自取」這類自然語言條件，比單純關鍵字規則靈活。

Docker 部署

專案推薦使用 Docker 部署：

git clone https://github.com/Usagi-org/ai-goofish-monitor && cd ai-goofish-monitor
cp .env.example .env
vim .env
docker compose up -d
docker compose logs -f app
docker compose down

預設 Web UI 地址是：

`1`	`http://127.0.0.1:8000`

官方映像地址是：

`1`	`ghcr.io/usagi-org/ai-goofish:latest`

如果映像存取慢，README 裡也給了加速映像示例：

1
2
3

docker pull ghcr.nju.edu.cn/usagi-org/ai-goofish:latest
docker tag ghcr.nju.edu.cn/usagi-org/ai-goofish:latest ghcr.io/usagi-org/ai-goofish:latest
docker compose up -d

Docker 映像已內建 Chromium，不需要宿主機額外安裝瀏覽器。預設持久化目錄包括：

data/：SQLite 主儲存，保存任務、結果和價格歷史。
state/：登入狀態 cookie 文件。
prompts/：任務提示詞。
logs/：運行日誌。
images/：商品圖片和任務臨時圖片目錄。

如果修改了 .env 裡的 SERVER_PORT，也要同步調整 docker-compose.yaml 的連接埠映射。

最少配置

專案的最少配置主要圍繞 AI 模型和 Web UI 登入：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=your_openai_compatible_base_url
OPENAI_MODEL_NAME=your_multimodal_model
WEB_USERNAME=admin
WEB_PASSWORD=change_me

其中前三項是 AI 模型接入必填項：

OPENAI_API_KEY：模型 API Key。
OPENAI_BASE_URL：OpenAI 相容介面地址。
OPENAI_MODEL_NAME：支援圖片輸入的模型名稱。

WEB_USERNAME 和 WEB_PASSWORD 用於 Web UI 登入。README 提到預設帳號密碼是 admin/admin123，生產環境必須修改。

第一次使用

第一次使用時，流程大致是：

打開 http://127.0.0.1:8000。
登入 Web UI。
進入「閒魚帳號管理」。
使用專案提供的 Chrome 擴充套件匯出閒魚登入態 JSON。
把登入態貼到系統裡。
登入態文件會保存到 state/，例如 state/acc_1.json。
回到「任務管理」，建立任務並綁定帳號。
運行任務並查看結果。

這裡最關鍵的是登入態。由於閒魚並不是開放給第三方隨意抓取的標準 API，專案需要用瀏覽器登入狀態來模擬正常頁面存取。登入態失效、風控、驗證碼、帳號異常都會影響任務運行。

AI 任務和關鍵字任務

專案支援兩類任務建立方式。

第一類是 AI判断。

你可以填寫「詳細需求」，提交後系統會非同步生成分析標準。適合需求比較複雜的場景，例如：

只要主機本體，不要配件。
價格明顯低於市場價才提醒。
成色要好，描述裡不能有進水、維修、暗病。
優先同城，能面交更好。
圖片裡要能看到序列號、包裝或關鍵配件。

第二類是 关键词判断。

它更接近傳統規則監控：根據關鍵字、價格、地區等條件直接建立任務，不經過 AI 生成流程。適合規則簡單、誤報可以接受的場景。

實際使用中可以混合使用：關鍵字負責初篩，AI 負責減少誤報。

Web UI 能做什麼

Web UI 是這個專案區別於普通腳本的重要部分。

任務管理頁可以配置：

AI 建立任務。
關鍵字規則。
價格範圍。
新發布範圍。
區域篩選。
帳號綁定。
定時規則。

帳號管理頁可以：

匯入閒魚帳號登入態。
更新登入態。
刪除帳號。
為任務指定帳號。
讓系統自動選擇帳號。

結果和日誌頁可以：

查看命中商品。
匯出結果。
查詢歷史記錄。
查看任務運行過程。
排查登入態失效、風控和 AI 調用問題。

系統設定頁可以：

查看系統狀態。
編輯 Prompt。
調整代理和輪換配置。

對於長期監控來說，Web UI 很關鍵。否則任務一多，配置、日誌、結果和通知都會變得難維護。

資料儲存

專案目前在線主儲存使用 SQLite，預設路徑是：

`1`	`data/app.sqlite3`

Docker 預設把 SQLite 主庫掛載到：

`1`	`./data:/app/data`

應用啟動時會自動建庫建表，並嘗試從舊的 config.json、jsonl/、price_history/ 匯入一次歷史資料。

需要注意的是，state/、prompts/、logs/、images/ 仍然是檔案系統目錄，不在 SQLite 中。商品圖片會臨時保存到類似下面的目錄：

`1`	`images/task_images_<task_name>/`

任務結束後預設會清理。

這種結構比較適合個人或小團隊部署：SQLite 足夠輕，遷移也簡單；檔案目錄保留登入態、圖片和日誌，排查問題更直觀。

通知渠道

專案支援多種通知渠道，常見配置包括：

NTFY_TOPIC_URL
GOTIFY_URL / GOTIFY_TOKEN
BARK_URL
WX_BOT_URL
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / TELEGRAM_API_BASE_URL
WEBHOOK_*

通知是這類工具的核心體驗。監控系統如果只把結果寫進後台，使用者仍然需要反覆打開頁面查看；有推送之後，命中商品才能在第一時間觸達。

更實用的配置方式是按商品價值分層：

普通關鍵字命中只寫入後台。
AI 高置信度結果推送到手機。
高價值商品推送到企業微信或 Telegram。
調試階段開啟更多日誌，穩定後減少噪音。

開發者運行

如果不使用 Docker，本地開發需要：

Python 3.10+
Node.js + npm
Playwright CLI
Chromium 或 Chrome / Edge 瀏覽器

基礎命令：

1
2
3

git clone https://github.com/Usagi-org/ai-goofish-monitor
cd ai-goofish-monitor
cp .env.example .env

一鍵啟動：

1
2

chmod +x start.sh
./start.sh

start.sh 會檢查 Playwright CLI 和瀏覽器條件，自動安裝依賴、建置前端、複製建置產物並啟動後端。

手動啟動後端：

`1`	`python -m src.app`

或者：

`1`	`uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload`

前端開發：

1
2
3

cd web-ui
npm install
npm run dev

測試和建置：

1
2

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
cd web-ui && npm run build

適合哪些人

ai-goofish-monitor 適合這些使用者：

經常在閒魚蹲特定型號商品的人。
想監控二手數位產品、攝影器材、遊戲設備、硬體配件的人。
想把「關鍵字搜尋 + 人工篩選」自動化的人。
有 OpenAI 相容模型 API，並願意為 AI 判斷支付調用成本的人。
熟悉 Docker 或基本命令列部署的人。
需要把命中結果推送到手機、企業微信或 Telegram 的使用者。

它不太適合這些情況：

完全不懂部署，只想要一個即開即用 App。
不願意處理登入態、驗證碼和帳號風控。
需要官方授權、強合規的資料介面。
想大規模高頻抓取平台資料。
希望 AI 自動判斷交易風險並替你下單。

使用風險和邊界

這類工具一定要注意邊界。

第一，遵守平台規則。

閒魚有自己的服務條款、風控策略和帳號安全機制。自動化存取可能觸發限制。不要高頻抓取，不要繞過風控，不要把它用於騷擾賣家、批量採集隱私或破壞平台秩序。

第二，保護帳號登入態。

state/ 裡保存的是登入狀態 cookie 文件。它本質上等同於帳號存取憑證，不能提交到 Git 倉庫，也不要放到不可信伺服器上。伺服器如果暴露在公網，Web UI 必須修改預設密碼，並建議放在 VPN、反向代理鑑權或內網之後。

第三，AI 判斷不是事實保證。

AI 可以幫你減少誤報，但不能保證商品真實、賣家可信、價格合理或交易安全。最終仍然要人工看商品詳情、賣家評價、聊天記錄、發貨方式和支付流程。

第四，注意成本。

如果每個候選商品都交給多模態模型分析，調用成本可能很快上升。建議先用關鍵字、價格和區域做強篩選，再把少量候選交給 AI。

第五，注意隱私。

商品截圖、聊天相關內容、帳號狀態和通知內容都可能包含敏感資訊。通知 Webhook、日誌目錄和資料庫都要妥善保護。

和普通腳本的差別

普通閒魚監控腳本通常只做三件事：

搜尋關鍵字。
判斷價格。
發通知。

ai-goofish-monitor 更進一步：

用 Web UI 管理任務和帳號。
用 AI Prompt 表達複雜購買標準。
用多模態模型看商品圖和描述。
用 SQLite 保存結果和價格歷史。
用日誌頁排查任務失敗原因。
用代理輪換和多帳號機制提高穩定性。
用定時任務支援長期運行。

也正因為功能更多，它的部署和維護成本更高。對普通使用者來說，Docker 部署是最省事的方式；對開發者來說，Web UI、FastAPI、Playwright、SQLite 這套結構也比較容易二次開發。

可以怎麼用

比較實用的使用方式是從小任務開始。

比如你想找一台二手相機，可以先建立一個任務：

關鍵字：A7C、索尼 A7C
價格範圍：按市場價設定上限
區域：優先本省或同城
新發布範圍：最近一天或最近幾小時
AI 標準：排除單鏡頭、排除維修機、排除明顯配件、關注快門數和成色
通知：只推送 AI 判斷通過的結果

穩定運行後，再逐步增加任務數量。不要一開始就上幾十個關鍵字、多個帳號和高頻 Cron。先看登入態穩定性、誤報率、AI 成本和通知噪音，再調參數。

總結

ai-goofish-monitor 把閒魚監控從「關鍵字腳本」推進到了「可管理的 AI 監控系統」。它用 Playwright 處理頁面自動化，用 AI 處理複雜判斷，用 Web UI 管理任務和結果，用 SQLite 保存資料，再透過多種通知渠道把結果推送出來。

它最適合個人或小團隊做特定商品監控，尤其是二手數位產品、硬體、攝影器材這類價格波動大、發布時間敏感、描述噪音多的品類。

但它也需要謹慎使用：登入態要保護，預設密碼要改，抓取頻率要克制，AI 結果要人工複核，平台規則和隱私邊界不能忽視。把它當成輔助篩選工具，它會很有價值；把它當成全自動交易系統，就容易高估它的能力。

參考連結：

Playwright CLI 視訊錄製：錄屏、章節標記、Overlay 與除錯取捨

Wed, 15 Apr 2026 08:22:45 +0800

如果你想把瀏覽器自動化過程錄成影片，用來做除錯、文件示範，或作為執行結果留存，Playwright CLI 已經提供了相當直接的做法。它輸出的是 WebM 影片，編碼為 VP8/VP9。

這篇按照官方 video-recording 參考文件整理，重點包括基礎錄製流程、章節標記、完整 hero script 錄製、Overlay API，以及 video 與 tracing 的差異。文中的命令列、程式碼片段與參數說明均按參考內容保留。

01 基礎錄製流程

最基本的流程就是：先打開瀏覽器，再開始錄製，執行操作，最後停止並保存。

# Open browser first
playwright-cli open

# Start recording
playwright-cli video-start demo.webm

# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000

# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1
# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"

# Stop and save
playwright-cli video-stop

這組命令已經涵蓋了最常見的錄製流程。video-chapter 很適合在不同階段之間插入章節卡片，讓錄出來的影片更容易理解。

02 最佳實務

1. 使用描述性檔名

如果影片是要給別人看，或之後還要回頭查找，檔名最好直接帶上場景和上下文。

1
2
3

# Include context in filename
playwright-cli video-start recordings/login-flow-2024-01-15.webm
playwright-cli video-start recordings/checkout-test-run-42.webm

2. 錄製完整 hero script

官方建議：如果影片是要交付給使用者，或作為 proof of work，最好把場景整理成一段程式碼，再用 run-code 執行。這樣比較容易控制動作節奏、停頓時機，以及影片中的標註效果。參考文件也提到，Playwright 新增了一些特別適合這類錄製流程的 API。

建議流程如下：

先用 CLI 走一遍場景，並記下所有 locator 和 action。之後如果要做高亮，會需要用這些 locator 取得對應的 bounding box。
為影片另外建立一個腳本檔案，並依照下面的方式撰寫。輸入內容時用 pressSequentially 搭配 delay，停頓時間也盡量安排得自然。
使用 playwright-cli run-code --filename your-script.js 執行。

Important: Overlays are pointer-events: none — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.

async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');
  // Show a chapter card — blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });
  // Perform action
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1000);

  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });
  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: absolute; top: 8px; right: 8px;
      padding: 6px 12px; background: rgba(0,0,0,0.7);
      border-radius: 8px; font-size: 13px; color: white;">
      ✓ Item added successfully
    </div>
  `);
  // Perform more actions while the annotation is visible
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1500);

  // Remove the annotation when done
  await annotation.dispose();
  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: absolute;
      top: ${bounds.y + bounds.height + 5}px;
      left: ${bounds.x + bounds.width / 2}px;
      transform: translateX(-50%);
      padding: 6px;
      background: #808080;
      border-radius: 10px;
      font-size: 14px;
      color: white;">Check it out, it is right above this text
    </div>
  `, { duration: 2000 });
  await page.screencast.stop();
}

這段程式碼的價值不只是「錄下來」，而是把影片做得更清楚：章節卡片負責分段，pressSequentially 讓輸入更自然，showOverlay 則能提供提示、高亮與說明。

文件最後也補了一句：Embrace creativity, overlays are powerful.

03 Overlay API 速覽

錄製影片時，Overlay API 很適合拿來做章節切換、局部提示與持續註解。官方給出的摘要如下：

Method	Use Case
`page.screencast.showChapter(title, { description?, duration?, styleSheet? })`	Full-screen chapter card with blurred backdrop — ideal for section transitions
`page.screencast.showOverlay(html, { duration? })`	Custom HTML overlay — use for callouts, labels, highlights
`disposable.dispose()`	Remove a sticky overlay added without duration
`page.screencast.hideOverlays()` / `page.screencast.showOverlays()`	Temporarily hide/show all overlays

如果你的目標是把自動化過程做成「可觀看的影片」，這組 API 基本就是最值得優先掌握的部分。

04 Tracing 和 Video 的差異

官方文件把兩者的定位區分得很清楚：

Feature	Video	Tracing
Output	WebM file	Trace file (viewable in Trace Viewer)
Shows	Visual recording	DOM snapshots, network, console, actions
Use case	Demos, documentation	Debugging, analysis
Size	Larger	Smaller

可以簡單這樣理解：

video 更適合示範、交付與回看「使用者看到的過程」
tracing 更適合排查問題、檢查動作細節，以及分析執行上下文

兩者不是互相取代，而是各自對應不同目標。

05 使用限制

文件裡也提醒了兩個很實際的限制：

Recording adds slight overhead to automation
Large recordings can consume significant disk space

也就是說，錄製功能雖然很好用，但會替自動化流程增加一些額外開銷；如果影片很長，磁碟占用也會明顯上升。

06 快速總結

如果只抓重點，可以記住下面幾件事：

video-start / video-stop 對應最基本的影片錄製流程
video-chapter 可以替影片加上章節過渡，讓示範更清楚
更進階的錄製場景，適合寫成腳本後用 run-code 執行
showOverlay 和 showChapter 可以明顯提升影片可讀性
video 適合示範，tracing 適合除錯，最好依目標選擇

如果你已經在用 Playwright CLI 做自動化示範、驗收留存或 proof of work，那麼 video recording 會是一塊很值得補上的能力。

參考連結

Playwright CLI video-recording 參考文件：https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md
Playwright CLI 專案首頁：https://github.com/microsoft/playwright-cli

Playwright CLI 會話管理：多瀏覽器會話、隔離、持久化與清理

Wed, 15 Apr 2026 08:15:12 +0800

如果你在用 Playwright CLI 做自動化，很快就會碰到一個實際問題：同一時間裡，能不能開多個互不干擾的瀏覽器會話？答案是可以，而且 Playwright CLI 已經把這套機制做得很直接。

這篇就按照官方 session-management 參考文件，整理它最實用的幾個部分：命名會話、會話隔離、持久化 profile、並發模式，以及常見清理命令。文中的命令列與命令區塊說明均按參考內容保留。

01 命名瀏覽器會話

官方建議用 -s 參數隔離不同瀏覽器上下文：

# Browser 1: Authentication flow
playwright-cli -s=auth open https://app.example.com/login

# Browser 2: Public browsing (separate cookies, storage)
playwright-cli -s=public open https://example.com

# Commands are isolated by browser session
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot

這裡的重點是：不同 session 名稱對應不同瀏覽器上下文。你可以把 auth 用在登入流程，把 public 用在匿名存取，它們之間不會共用 cookies 或本地狀態。

02 瀏覽器會話隔離了什麼

每個瀏覽器會話都會獨立維護下面這些內容：

Cookies
LocalStorage / SessionStorage
IndexedDB
Cache
Browsing history
Open tabs

這意味著如果你在 auth 會話裡登入了某個網站，並不會自動影響 public 會話。做多帳號測試、登入態驗證、匿名對比時，這一點尤其重要。

03 瀏覽器會話相關命令

官方文件把會話管理裡最常用的一組命令放在了一起：

# List all browser sessions
playwright-cli list

# Stop a browser session (close the browser)
playwright-cli close                 # stop the default browser
playwright-cli -s=mysession close   # stop a named browser

# Stop all browser sessions
playwright-cli close-all

# Forcefully kill all daemon processes (for stale/zombie processes)
playwright-cli kill-all

# Delete browser session user data (profile directory)
playwright-cli delete-data              # delete default browser data
playwright-cli -s=mysession delete-data # delete named browser data

可以把它們理解成三類操作：

list：看目前有哪些會話
close / close-all / kill-all：結束會話或清理卡住的瀏覽器程序
delete-data：刪除某個會話對應的使用者資料目錄

如果你只是結束瀏覽器，通常先用 close；如果已經出現殘留程序或殭屍程序，再用 kill-all 會更合適。

04 用環境變數設定預設會話

如果你不想每條命令都重複寫 -s=mysession，官方還提供了環境變數方式：

1
2

export PLAYWRIGHT_CLI_SESSION="mysession"
playwright-cli open example.com  # Uses "mysession" automatically

這樣之後不顯式指定 -s 時，命令就會預設使用 mysession 這個瀏覽器會話。

05 常見模式：並發抓取

參考文件給了一個很典型的並發抓取例子：

#!/bin/bash
# Scrape multiple sites concurrently

# Start all browsers
playwright-cli -s=site1 open https://site1.com &
playwright-cli -s=site2 open https://site2.com &
playwright-cli -s=site3 open https://site3.com &
wait

# Take snapshots from each
playwright-cli -s=site1 snapshot
playwright-cli -s=site2 snapshot
playwright-cli -s=site3 snapshot

# Cleanup
playwright-cli close-all

這個模式適合同時打開多個站點，各自抓取頁面狀態，再統一清理。因為每個站點都跑在獨立會話裡，所以不會互相污染本地狀態。

06 常見模式：A/B 測試會話

另一個常見場景，是同時對比不同實驗版本：

# Test different user experiences
playwright-cli -s=variant-a open "https://app.com?variant=a"
playwright-cli -s=variant-b open "https://app.com?variant=b"

# Compare
playwright-cli -s=variant-a screenshot
playwright-cli -s=variant-b screenshot

這種寫法很適合做 A/B 頁面差異對比，因為兩個版本在獨立會話裡運行，截圖和狀態檢查也更容易分開管理。

07 持久化瀏覽器 profile

官方文件特別說明：預設情況下，瀏覽器 profile 只保存在記憶體裡。

如果你希望把瀏覽器 profile 持久化到磁碟，需要在 open 時加上 --persistent：

# Use persistent profile (auto-generated location)
playwright-cli open https://example.com --persistent

# Use persistent profile with custom directory
playwright-cli open https://example.com --profile=/path/to/profile

這個能力適合需要長期複用登入態、本地快取或擴充除錯環境的場景。尤其在反覆除錯同一站點時，持久化 profile 往往會比每次從零開始更高效。

08 預設瀏覽器會話

如果沒有顯式傳入 -s，那麼命令會使用預設瀏覽器會話：

# These use the same default browser session
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close  # Stops default browser

也就是說，不帶 -s 的幾條命令預設是在同一個預設會話裡連續執行的。

09 打開時附帶會話配置

除了會話名，官方也給出了幾種常見的啟動配置方式：

# Open with config file
playwright-cli open https://example.com --config=.playwright/my-cli.json

# Open with specific browser
playwright-cli open https://example.com --browser=firefox

# Open in headed mode
playwright-cli open https://example.com --headed

# Open with persistent profile
playwright-cli open https://example.com --persistent

這些參數可以和會話管理一起搭配使用。比如你可以讓某個命名會話固定跑在 firefox，或者讓某個會話始終以 headed 模式啟動，方便人工觀察。

10 官方給出的最佳實務

參考文件列了三條很實用的最佳實務。

1. 用有語義的會話名

# GOOD: Clear purpose
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com

# AVOID: Generic names
playwright-cli -s=s1 open https://github.com

會話名最好能直接表達用途。像 github-auth、docs-scrape 這種名字，後面維護腳本時會清楚很多。

2. 用完及時清理

# Stop browsers when done
playwright-cli -s=auth close
playwright-cli -s=scrape close

# Or stop all at once
playwright-cli close-all

# If browsers become unresponsive or zombie processes remain
playwright-cli kill-all

如果任務結束後不關瀏覽器，會話和背景程序會一直留著。短期看問題不大，但任務一多，很容易把環境弄亂。

3. 刪除陳舊瀏覽器資料

1
2

# Remove old browser data to free disk space
playwright-cli -s=oldsession delete-data

當某些舊會話已經不用時，刪除對應資料目錄可以節省磁碟空間，也能避免後面誤用過期狀態。

11 快速總結

如果只抓重點，可以記住下面這幾件事：

-s=<name> 用來建立並使用獨立瀏覽器會話
不同會話之間會隔離 cookies、各種儲存、快取、歷史紀錄和分頁
close-all 適合統一關閉，kill-all 適合處理異常殘留程序
--persistent 用來把 profile 落盤，適合長期複用狀態
會話名盡量語義化，舊資料定期清理

如果你的工作流裡已經有登入態複用、多帳號並行、A/B 對比或批次抓取需求，那麼 session management 基本就是 Playwright CLI 裡最值得先掌握的一塊能力。

參考連結

Playwright CLI session-management 參考文件：https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md
Playwright CLI 專案首頁：https://github.com/microsoft/playwright-cli

Playwright CLI storage state 用法：保存登入狀態、讀取 Cookies 與本地儲存

Tue, 14 Apr 2026 22:19:55 +0800

如果你用 Playwright CLI 做瀏覽器自動化，storage state 幾乎就是最常用的能力之一。它的作用很直接：把目前瀏覽器裡的登入狀態和本地狀態保存下來，後面繼續重用，避免每次都重新登入。

01 保存目前的 storage state

最常見的情境，就是先登入一次，再把目前狀態匯出到檔案。

`1`	`playwright-cli storage-state save auth.json`

這條命令會把目前瀏覽器 context 中的狀態保存到 auth.json。之後如果想重用登入狀態，通常就是從這一步開始。

02 載入既有的 storage state

已有狀態檔後，可以在啟動時直接載入。

`1`	`playwright-cli --storage-state auth.json`

它會用 auth.json 裡的狀態啟動瀏覽器 context。最常見的用途，就是跳過重複登入，直接進入已登入環境。

03 查看目前 cookies

如果你只是想確認目前 session 裡到底有哪些 cookies，可以直接查看。

`1`	`playwright-cli cookies`

這條命令會列出目前 context 中的 cookies，適合用來排查登入狀態是否存在、cookie 是否寫入成功。

04 設定 cookies

如果你已經有 cookie 資料，也可以直接寫入。

`1`	`playwright-cli cookies set '[{"name":"session","value":"abc","domain":"example.com","path":"/"}]'`

這個用法適合調試驗證流程、重現特定 session，或在腳本執行前手動注入 cookie 條件。

05 讀取 localStorage

有些網站的登入狀態或前端狀態不只存在 cookies 裡，也會放在 localStorage。

`1`	`playwright-cli local-storage`

這條命令用來查看目前頁面的 localStorage 內容。排查「明明像是登入了，但頁面行為還是不對」時，這一步很有用。

06 寫入 localStorage

如果需要模擬某些前端狀態，也可以直接設定。

`1`	`playwright-cli local-storage set token abc123`

它會把指定鍵值寫入 localStorage。常見用途是注入 token、偏好設定或某些前端開關。

07 讀取 sessionStorage

sessionStorage 適合查看目前 session 裡的暫時狀態。

`1`	`playwright-cli session-storage`

這條命令會輸出目前頁面的 sessionStorage。如果某個頁面流程依賴一次性的 session 資料，可以從這裡檢查。

08 寫入 sessionStorage

需要時，也可以手動設定 sessionStorage。

`1`	`playwright-cli session-storage set key value`

它適合重現依賴暫時狀態的頁面行為，或補齊初始化步驟所需的欄位。

09 查看 IndexedDB

對較重的 Web 應用來說，真正關鍵的本地資料可能在 IndexedDB 裡。

`1`	`playwright-cli indexed-db`

這條命令用來查看目前頁面的 IndexedDB 資料。遇到複雜單頁應用、離線快取或本地資料庫式狀態時，可以優先檢查這裡。

10 一個最實用的工作流

如果你只是想穩定重用登入狀態，最簡單的流程通常是這樣：

先打開站點並手動完成登入。
執行下面這條命令保存狀態：

`1`	`playwright-cli storage-state save auth.json`

後續執行時直接載入：

`1`	`playwright-cli --storage-state auth.json`

如果載入後頁面還是異常，再繼續檢查：

playwright-cli cookies
playwright-cli local-storage
playwright-cli session-storage
playwright-cli indexed-db

這個順序已經能覆蓋大部分「狀態沒有完整恢復」的問題。

11 使用時要注意什麼

有三點最值得注意：

storage state 檔案本質上是敏感資料，裡面可能包含登入 cookie 或 token，不要隨便提交到倉庫。
只恢復 cookies 不一定夠，很多現代網站還依賴 localStorage、sessionStorage 或 IndexedDB。
狀態檔不是永久有效，cookie 過期、帳號變更或環境切換後，通常都要重新生成。

12 快速總結

如果只記一句話：

Playwright CLI 的 storage state，就是把瀏覽器目前狀態保存下來，再在後續任務裡繼續使用。

而在實際排查裡，最常用的一組命令就是這些：

playwright-cli storage-state save auth.json
playwright-cli --storage-state auth.json
playwright-cli cookies
playwright-cli local-storage
playwright-cli session-storage
playwright-cli indexed-db

先保存，再載入；如果還是不對，再分層檢查 cookies 和各類本地儲存，基本就是這份參考文件最實用的部分。

參考連結

Playwright CLI storage-state 參考文件：https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md
Playwright CLI 專案首頁：https://github.com/microsoft/playwright-cli

Playwright CLI 使用入門：安裝、Skills、Session 管理與常用命令

Sun, 12 Apr 2026 14:36:58 +0800

如果你最近在用 Claude Code、GitHub Copilot 或其他 coding agent 做瀏覽器自動化，microsoft/playwright-cli 是一個很值得關注的新工具。它不是傳統意義上那種「給人手動敲命令用」的瀏覽器小工具，而是一個面向 coding agent 的 Playwright CLI，強調的是更低的 token 開銷、更輕量的命令介面，以及和 Skills 工作流的結合。

從官方 README 來看，Playwright CLI 的核心思路很明確：相比 MCP 把大量工具 schema 和頁面結構塞進模型上下文，CLI 命令方式更緊湊，也更適合在大程式碼庫、測試任務與瀏覽器自動化之間來回切換的 agent 工作流。

01 Playwright CLI 是什麼

playwright-cli 是微軟開源的一個 Playwright 命令列工具，官方描述是「CLI for common Playwright actions」。它主要用來完成這些事情：

開啟頁面並驅動瀏覽器
錄製與生成 Playwright 程式碼
抓取頁面快照，取得元素引用
截圖、匯出 PDF
搭配 coding agent 進行自動化測試與網頁操作

目前 GitHub README 對它的定位說得非常清楚：如果你正在使用 coding agents，CLI 往往比 Playwright MCP 更合適；如果你更需要持久狀態、豐富的 introspection 與長時間的 agentic loop，MCP 仍然有它的價值。

換句話說，Playwright CLI 更像是「替 AI 編碼助手準備的瀏覽器自動化介面」，而不只是給人類工程師手動點網頁的工具。

02 它的優點在哪裡

1. 更適合 agent 工作流

官方 README 把第一個優點直接寫成 Token-efficient。它不會強制把整頁資料都塞進 LLM 上下文，而是透過更短、更專用的命令讓 agent 操作瀏覽器。

這對 coding agent 很重要。因為在真實專案裡，agent 不只是跑瀏覽器，還要讀程式碼、改檔案、跑測試、看日誌。如果瀏覽器工具本身就很「吃上下文」，整體效率會明顯下降。

2. 能和 Skills 一起工作

README 裡特別強調了 playwright-cli install --skills。這代表官方不是把它當成單純的 shell 工具，而是設計成可以被 Claude Code、GitHub Copilot 等 agent 直接使用的技能入口。

如果你的工作流本來就建立在 Skills 之上，那 Playwright CLI 的接入會更自然。

3. Session 管理做得比較完整

Playwright CLI 支援 session。預設情況下，瀏覽器 profile 保存在記憶體裡，同一個 session 內的 cookies 和 storage 會在多次 CLI 呼叫之間保留；如果加上 --persistent，還可以把 profile 落到磁碟，跨瀏覽器重啟繼續使用。

這讓它比「一條命令開瀏覽器，跑完就丟掉」的玩具型工具更實用，也更適合持續除錯與 agent 長流程執行。

4. 自帶可視化監控面板

README 裡提供了 playwright-cli show，用來打開一個 dashboard，觀察和控制所有執行中的瀏覽器 session。對於 agent 在背景跑自動化任務的場景，這一點很有價值，因為你可以隨時接手、觀察、排錯，而不是只能盲跑。

03 安裝與環境要求

根據目前 GitHub README，Playwright CLI 的基本要求是：

Node.js 18 或更高版本
Claude Code、GitHub Copilot 或其他 coding agent

安裝命令如下：

1
2

npm install -g @playwright/cli@latest
playwright-cli --help

這裡有一個很容易踩坑的點要特別注意：

官方目前推薦安裝的是 @playwright/cli
不要把它和 npm 上歷史遺留、已廢棄的舊包 playwright-cli 混為一談

也就是說，真正該安裝的是 scoped package，而不是舊時代的同名歷史包。

04 如何開始用

1. 安裝 skills

如果你希望讓 coding agent 直接使用 Playwright CLI，官方建議先安裝 skills：

`1`	`playwright-cli install --skills`

README 裡明確寫到，Claude Code、GitHub Copilot 等工具會使用本地安裝的 skills。

2. 直接讓 agent 呼叫 CLI

如果你不想先處理 skills，也可以直接讓 agent 讀取 CLI 的說明資訊：

1
2

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

官方把這種方式叫做「Skills-less operation」。意思是即使沒有預先安裝 skill，也可以透過 CLI 的自描述能力來驅動 agent。

3. 手動體驗一遍最小流程

README 裡給了一組很適合入門的 TodoMVC 範例：

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

這組命令的價值在於，它能讓你很快理解 Playwright CLI 的互動方式：

open 負責開頁面
type 和 press 負責輸入
check 用元素引用操作核取方塊
screenshot 保存結果

05 `--headed`、session 與監控面板

`--headed`

Playwright CLI 預設是 headless 的。如果你想直接看到瀏覽器視窗，需要在 open 時明確加上 --headed：

`1`	`playwright-cli open https://playwright.dev --headed`

這對除錯選擇器、登入流程，或觀察互動細節都會更方便。

session

官方 README 很強調 session 的用法。你可以用不同 session 把不同專案或網站隔離開來：

1
2
3

playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list

如果你是讓 agent 長時間工作，也可以直接透過環境變數指定 session：

`1`	`PLAYWRIGHT_CLI_SESSION=todo-app claude .`

常用的 session 管理命令包括：

1
2
3

playwright-cli list
playwright-cli close-all
playwright-cli kill-all

其中：

list 用來列出所有 session
close-all 用來正常關閉所有瀏覽器
kill-all 用來強制結束所有瀏覽器程序

監控面板

如果你想看 agent 現在到底在瀏覽器裡做了什麼，可以執行：

`1`	`playwright-cli show`

根據 README 的說明，這個 dashboard 主要有兩種視圖：

Session grid：依 workspace 查看所有活動 session，附即時畫面、URL 和頁面標題
Session detail：查看單個 session 的即時介面，還能接管滑鼠與鍵盤

這讓 Playwright CLI 不只是「命令列可用」，而是具備了比較成熟的可觀測性。

06 常用命令先記住哪些

如果你是第一次接觸 Playwright CLI，不需要一開始就把所有命令背下來。先記住下面這些最核心的就夠了：

頁面與互動

playwright-cli open [url]
playwright-cli goto <url>
playwright-cli click <ref>
playwright-cli fill <ref> <text>
playwright-cli type <text>
playwright-cli hover <ref>
playwright-cli press <key>

取得頁面結構

playwright-cli snapshot
playwright-cli snapshot <ref>
playwright-cli snapshot --depth=N
playwright-cli eval <func> [ref]

snapshot 很關鍵，因為很多後續操作都依賴元素引用 ref。通常你會先抓一次快照，再用回傳的元素編號去點擊、填寫、勾選或截圖。

輸出結果

1
2

playwright-cli screenshot
playwright-cli pdf

分頁

playwright-cli tab-list
playwright-cli tab-new [url]
playwright-cli tab-close [index]
playwright-cli tab-select <index>

07 它適合誰

如果你屬於下面這些場景，Playwright CLI 很值得試：

你在用 Claude Code、Copilot 或其他 coding agent 做 E2E 測試
你希望瀏覽器自動化介面更輕量，不想把大量頁面結構塞進上下文
你希望同一個瀏覽器 session 能跨多次命令持續存在
你想在 agent 自動跑網頁任務時，隨時打開監控面板觀察進度

如果你的重點是「瀏覽器自動化如何和 coding agent 高效配合」，Playwright CLI 很可能會比傳統的人類手動除錯方式更順手。