chrome-devtools

Chrome DevTools Agent 技能

通过可执行的 Puppeteer 脚本实现浏览器自动化。所有脚本都会输出 JSON，便于解析。

快速开始

安装

步骤 1：安装系统依赖（仅限 Linux/WSL）

在 Linux/WSL 上，Chrome 需要系统库。请先安装：

cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

支持：Ubuntu、Debian、Fedora、RHEL、CentOS、Arch、Manjaro

macOS/Windows：跳过此步骤（Chrome 已捆绑依赖）

步骤 2：安装 Node 依赖

npm install  # Installs puppeteer, debug, yargs

测试

node navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

可用脚本

所有脚本都位于 .claude/skills/chrome-devtools/scripts/

脚本用法

• ./scripts/README.md

核心自动化

• navigate.js - 导航至 URL
• screenshot.js - 截取屏幕截图（整页或元素）
• click.js - 点击元素
• fill.js - 填写表单字段
• evaluate.js - 在页面上下文中执行 JavaScript

分析与监控

• snapshot.js - 提取带有元数据的交互元素
• console.js - 监控控制台消息/错误
• network.js - 跟踪 HTTP 请求/响应
• performance.js - 测量 Core Web Vitals 并记录跟踪信息

使用模式

单条命令

cd .claude/skills/chrome-devtools/scripts
node screenshot.js --url https://example.com --output ./docs/screenshots/page.png

重要：始终将屏幕截图保存到 ./docs/screenshots 目录。

链式命令（复用浏览器）

# Keep browser open with --close false
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "[email protected]" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

解析 JSON 输出

# Extract specific fields with jq
node performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
node network.js --url https://example.com --output /tmp/requests.json

常见工作流

网页抓取

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

性能测试

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

表单自动化

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

错误监控

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

脚本选项

所有脚本均支持：

• --headless false - 显示浏览器窗口
• --close false - 保持浏览器打开以便链式操作
• --timeout 30000 - 设置超时时间（毫秒）
• --wait-until networkidle2 - 等待策略

完整选项请参阅 ./scripts/README.md。

输出格式

所有脚本都会将 JSON 输出到 stdout：

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

错误会输出到 stderr：

{
  "success": false,
  "error": "Error message"
}

查找元素

使用 snapshot.js 查找选择器：

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

故障排除

常见错误

“Cannot find package 'puppeteer'”

• 在 scripts 目录中运行：npm install

“error while loading shared libraries: libnss3.so”（Linux/WSL）

• 缺少系统依赖
• 修复方法：在 scripts 目录中运行 ./install-deps.sh
• 手动安装：sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

“Failed to launch the browser process”

• 检查是否已安装系统依赖（Linux/WSL）
• 验证 Chrome 是否已下载：ls ~/.cache/puppeteer
• 尝试运行：npm rebuild，然后运行 npm install

未找到 Chrome

• Puppeteer 会在 npm install 期间自动下载 Chrome
• 如果失败，请手动触发：npx puppeteer browsers install chrome

脚本问题

未找到元素

• 先获取快照以查找正确的选择器：node snapshot.js --url <url>

脚本挂起

• 增加超时时间：--timeout 60000
• 更改等待策略：--wait-until load 或 --wait-until domcontentloaded

屏幕截图空白

• 等待页面加载：--wait-until networkidle2
• 增加超时时间：--timeout 30000

脚本权限被拒绝

• 使脚本可执行：chmod +x *.sh

参考文档

详细指南见 ./references/：

• CDP Domains 参考 - 47 个 Chrome DevTools Protocol 域
• Puppeteer 快速参考 - 完整的 Puppeteer API 模式
• 性能分析指南 - Core Web Vitals 优化

高级用法

自定义脚本

使用共享库创建自定义脚本：

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

直接访问 CDP

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

高级模式和完整 API 覆盖范围请参阅参考文档。

外部资源

• Puppeteer 文档
• Chrome DevTools Protocol
• 脚本 README