name: clawbrowser
description: 当智能体需要通过 Microsoft Playwright CLI (playwright-cli) 驱动浏览器进行导航、表单交互、截图、录制、数据提取、会话管理或调试，且无需加载完整的 MCP 浏览器时使用。本工具训练智能体掌握 CLI 命令、快照以及会话/配置习惯，以确保 Playwright CLI 在脚本化浏览中可靠运行。
allowed-tools: Bash(playwright-cli:*)

Clawbrowser – 通过 Playwright CLI 控制浏览器

设置与引导

1. 安装 CLI 并验证可用性：
   bash npm install -g @playwright/cli@latest playwright-cli --help
   CLI 默认以无头模式运行；如需查看 UI，可在 open 命令中添加 --headed 参数，或在 playwright-cli.json 配置文件中将 browser.launchOptions.headless 设为 false。
2. CLI 默认读取 playwright-cli.json 配置文件，或通过 --config 参数指定其他文件。利用配置文件可调整浏览器名称、启动/上下文选项、视口大小、超时设置、输出目录及录制设置，无需修改每条命令。
3. 保持 playwright-cli --help 在终端中随时可用；该脚本会自文档化最新的命令和选项，便于在执行新操作前快速查阅。

核心交互流程

1. 使用 playwright-cli open <url> 加载页面（如需预先隔离会话，可添加 --session=name）。
2. 在任何交互前，运行 playwright-cli snapshot 生成元素引用（e1、e2 等）。DOM 变更或页面导航后，务必重新生成快照，以避免引用失效。
3. 使用元素引用执行操作：
   • click、dblclick、hover、drag、check、uncheck、select、fill、type、upload、eval
   • 根据需要附加 [button]、[value] 或 JavaScript 代码片段（例如：playwright-cli click e4 right）。
4. 使用 screenshot [ref]、pdf、console [level] 或 network 捕获输出证据，以验证流程或检查错误。
5. 示例流程：
   bash playwright-cli open https://example.com/login playwright-cli snapshot playwright-cli fill e1 "user@example.com" playwright-cli fill e2 "supersecret" playwright-cli click e3 playwright-cli snapshot playwright-cli screenshot

会话与持久化

• 使用 --session=<name> 为每个工作流隔离 cookies、存储和标签页。会话类似于持久化配置文件：可在命令之间保持认证状态、历史记录和标签页。
• 若需在同一会话中运行多个命令，可设置环境变量 PLAYWRIGHT_CLI_SESSION=mysession，CLI 将默认使用该会话，无需每次指定 --session。
• 显式管理会话：
  bash playwright-cli session-list playwright-cli session-stop <name> playwright-cli session-stop-all playwright-cli session-restart <name> playwright-cli session-delete <name>
• 使用 playwright-cli --isolated open ... 创建临时上下文，其状态不会持久化到磁盘。
• 更改会话的浏览器设置（启动参数、无头模式开关、浏览器选择）后，需为该会话重新运行 playwright-cli config，然后执行 session-restart 以应用新配置。

标签页、导航与开发者工具

• 标签页辅助命令：tab-list、tab-new [url]、tab-close <index>、tab-select <index>。
• 导航快捷命令：go-back、go-forward、reload。
• 键盘与鼠标控制：press <key>、keydown、keyup、mousemove <x> <y>、mousedown [button]、mouseup [button]、mousewheel <dx> <dy>。
• 开发者工具式内省：
  bash playwright-cli console [level] playwright-cli network playwright-cli run-code "async page => await page.context().grantPermissions(['clipboard-read'])"
  使用这些命令检查控制台日志、查看网络请求或注入辅助脚本。

录制、追踪与导出

• 围绕关键交互录制追踪和视频，以便后续回放智能体的操作：
  bash playwright-cli tracing-start # 执行操作步骤 playwright-cli tracing-stop playwright-cli video-start # 执行操作步骤 playwright-cli video-stop video.webm
• 使用 screenshot、pdf 或 snapshot（导出元素引用）将证据保存到磁盘。录制的文件遵循配置中的 outputDir 设置。

配置、状态与维护

• 使用 playwright-cli config 调整运行时参数，无需重新安装。示例：
  bash playwright-cli config --headed --browser=firefox playwright-cli --session=auth config --config=playwright-cli.json
  在配置文件中修改 browser、contextOptions、launchOptions 或录制设置，然后重启会话以应用更改。
• 在新环境中或收到缺少浏览器二进制文件的错误时，运行 playwright-cli install 可刷新浏览器二进制文件。
• 操作完成后清理会话，避免残留状态：
  bash playwright-cli session-stop <name> playwright-cli session-delete <name>

故障排除与提醒

• 若命令执行失败，请重新运行 playwright-cli snapshot 确认元素引用是否有效。快照为 click/type 等操作提供当前的 DOM 上下文。
• playwright-cli --help 始终显示最新的命令集，尝试使用不常用的参数前请先查阅。
• 当智能体需要复现已录制的手动流程时，请捕获截图、记录会话名称，并注明所使用的元素引用和标签页。
• 若需定位到可见浏览器（例如进行手动检查），请使用 --headed 重新配置，或仅针对该会话运行 playwright-cli open --headed <url>。