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 由微软维护，背后团队和早期 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`

这条命令会把当前浏览器上下文中的状态保存到 auth.json。后面如果想复用登录态，通常就是从这一步开始。

02 加载已有 storage state

已经有状态文件后，可以在启动时直接加载。

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

它会用 auth.json 里的状态启动浏览器上下文。常见用途就是跳过重复登录，直接进入已登录环境。

03 查看当前 cookies

如果你只是想确认当前会话里到底有哪些 cookies，可以直接查看。

`1`	`playwright-cli cookies`

这条命令会列出当前上下文中的 cookies。适合排查登录态是否存在、cookie 是否写入成功。

04 设置 cookies

如果你已经有 cookie 数据，也可以直接写入。

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

这个用法适合调试鉴权、复现特定会话，或者在脚本前手动注入 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 适合看当前会话里的临时状态。

`1`	`playwright-cli session-storage`

这条命令会输出当前页面的 sessionStorage。如果某个页面逻辑依赖一次性会话数据，可以从这里检查。

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、会话管理与常用命令

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. 会话管理做得比较完整

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 长时间工作，还可以直接给它指定环境变量：

`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 很可能会比传统的人类手动调试方式更顺手。