SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场chrome-devtools

chrome-devtools

测试与质量

查看项目

更新于 10-16 03:59

技能介绍

Chrome DevTools 是一个通过 Puppeteer 脚本实现浏览器自动化、调试和性能分析的 Agent 技能。所有脚本均输出 JSON，便于解析和后续处理。技能可存在于项目级或用户级，优先级为项目级高于用户级。

用途 该技能用于自动化浏览器操作、截图、性能分析、控制台日志采集、网络请求追踪、无障碍审计以及页面元素发现与交互。

主要能力

  • 浏览器自动化：通过 navigate.js、click.js、fill.js 等脚本执行导航、点击、表单填写等操作。
  • 持久会话：浏览器状态通过 WebSocket 端点文件（.browser-session.json）在多次脚本执行间保持。默认脚本断开连接但保持浏览器运行，便于复用页面状态；使用 --close true 可关闭浏览器并清除会话。
  • ARIA 快照：当页面结构未知时，使用 aria-snapshot.js 获取 YAML 格式的无障碍树，包含语义角色、可访问名称、状态和稳定的元素引用（[ref=eN]）。
  • 按引用交互：使用 select-ref.js 通过 ref 对元素执行点击、填充、获取文本、截图、聚焦、悬停等操作。
  • 截图：screenshot.js 支持基本截图、全页截图和特定元素截图；超过 5MB 的截图自动使用 Sharp 压缩（比 ImageMagick 快 4-5 倍），可通过 --max-size 自定义阈值或 --no-compress 禁用压缩。
  • 控制台日志采集与分析：console.js 可捕获指定时长的控制台消息，支持按类型过滤（如 error、warn），并可结合 jq 进行根因分析。
  • 网络请求追踪：network.js 跟踪 HTTP 请求/响应，可筛选状态码 >= 400 的请求。
  • 性能测量：performance.js 测量 Core Web Vitals。
  • 元素发现：snapshot.js 提取交互元素（JSON 格式），可结合 jq 按标签名或文本内容查找。

使用方式

  1. 安装依赖：进入 .claude/skills/chrome-devtools/scripts 目录，运行 npm install（安装 puppeteer、sharp、debug、yargs）。Linux/WSL 环境需先运行 ./install-deps.sh 安装 Chrome 系统库。
  2. 快速开始：运行 node navigate.js --url https://example.com，输出 JSON 包含 success、url、title。
  3. 运行模式：检测当前操作系统，仅在 Linux、WSL 或 CI 环境以无头模式启动浏览器；macOS/Windows 始终以有头模式运行以便调试。可并行运行多个脚本/会话以模拟真实用户交互或不同设备类型（移动端、平板、桌面）。
  4. 本地 HTML 文件：禁止通过 file:// 协议浏览本地 HTML 文件，应使用本地服务器（如 npx serve ./dist -p 3000 或 python -m http.server 3000 --directory ./dist），因为 file:// 会阻止 CORS、ES 模块、fetch API、Service Worker 等浏览器功能。
  5. 自定义测试脚本：复杂自动化可编写脚本到 <project>/.claude/chrome-devtools/tmp/，使用 lib/browser.js 中的 getBrowser、getPage、disconnectBrowser、outputJSON 等函数。原则：单一用途、结束时调用 disconnectBrowser() 保持浏览器运行、仅在完全结束会话时使用 closeBrowser()、输出 JSON、page.evaluate() 回调中仅使用纯 JavaScript。
  6. 存储位置：快照存于 <project>/.claude/chrome-devtools/snapshots/，截图存于 <project>/.claude/chrome-devtools/screenshots/，日志存于 <project>/.claude/chrome-devtools/logs/<session>/。

可用脚本

  • navigate.js：导航到 URL
  • screenshot.js：截图（自动压缩 >5MB）
  • click.js：点击元素
  • fill.js：填写表单字段
  • evaluate.js：在页面上下文执行 JS
  • snapshot.js：提取交互元素（JSON）
  • aria-snapshot.js：获取 ARIA 无障碍树（YAML 带 refs）
  • select-ref.js：按 ARIA 快照中的 ref 交互元素
  • console.js：监控控制台消息/错误
  • network.js：跟踪 HTTP 请求/响应
  • performance.js：测量 Core Web Vitals

适用场景

  • 未知页面结构：先获取 ARIA 快照发现元素，再按 ref 交互，最后用截图或新快照验证。
  • 源码可获取的站点：先阅读源码，直接编写选择器。
  • 视觉检查：截图验证渲染效果。
  • 调试问题：采集控制台日志，结合会话存储分析。
  • 无障碍审计：使用 ARIA 快照进行语义结构分析。
  • Web 抓取、表单自动化、性能测试等常见模式。

限制与注意事项

  • 本地 HTML 文件必须通过本地服务器访问，不能使用 file:// 协议。
  • 截图可能因动画触发而缺失图片，需先滚动元素进入视图、等待动画完成或触发 Intersection Observer 动画后重试。
  • 脚本通用选项：--headless false 显示浏览器窗口、--close true 完全关闭浏览器（默认保持运行）、--timeout 30000 设置超时（毫秒）、--wait-until networkidle2 等待策略。
  • 常见问题：找不到 puppeteer 包需在 scripts 目录运行 npm install；Linux 缺少 libnss3.so 需运行 ./install-deps.sh；元素未找到需用 snapshot.js 查找正确选择器；脚本挂起可使用 --timeout 60000 或 --wait-until load；会话过期可删除 .browser-session.json 后重试。
  • 参考文档：./references/cdp-domains.md、./references/puppeteer-reference.md、./references/performance-guide.md、./scripts/README.md。