chrome-devtools

Chrome DevTools Agent Skill

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

快速开始

重要：运行脚本前务必先检查 pwd。

安装

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

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

pwd  # Should show current working directory
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 依赖

# Preferred: Using bun (faster)
bun install  # Installs puppeteer, debug, yargs

# Alternative: Using npm
npm install

步骤 3：安装 ImageMagick（可选，推荐）

ImageMagick 可自动压缩截图，使文件大小保持在 5MB 以下：

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

验证：

magick -version  # or: convert -version

如果没有 ImageMagick，超过 5MB 的截图不会被压缩（可能无法在 Gemini/Claude 中加载）。

测试

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

可用脚本

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

重要：运行脚本前务必先检查 pwd。

脚本用法

• ./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 并记录跟踪信息

使用模式

单条命令

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png

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

自动图像压缩

如果截图超过 5MB，会自动压缩，以确保兼容 Gemini API 和 Claude Code（两者的限制均为 5MB）。此功能在内部使用 ImageMagick：

# Default: auto-compress if >5MB
bun screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
bun screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
bun screenshot.js --url https://example.com --output page.png --no-compress

压缩行为：

• PNG：缩小至 90% + 质量 85（如果仍然过大，则缩小至 75% + 质量 70）
• JPEG：质量 80 + 渐进式编码（如果仍然过大，则质量设为 60）
• 其他格式：转换为 JPEG 并压缩
• 需要安装 ImageMagick（参见 imagemagick skill）

输出包含压缩信息：

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

链式命令（复用浏览器）

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

解析 JSON 输出

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

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

执行协议

工作目录验证

执行任何脚本前：

1. 使用 pwd 检查当前工作目录
2. 确认位于 .claude/skills/chrome-devtools/scripts/ 目录
3. 如果目录不正确，则 cd 到正确位置
4. 所有输出文件都使用绝对路径

示例：

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

输出验证

完成截图/捕获操作后：

1. 使用 ls -lh <output-path> 验证文件已创建
2. 使用 Read 工具读取截图，确认其内容
3. 检查 JSON 输出中是否有 success:true
4. 报告文件大小和压缩状态

示例：

bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

5. 将工作目录切回项目根目录。

错误恢复

如果脚本失败：

1. 检查错误消息，确认是否为选择器问题
2. 使用 snapshot.js 查找正确的选择器
3. 如果 CSS 选择器失败，尝试 XPath 选择器
4. 确认元素可见且可交互

示例：

# CSS selector fails
bun click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
bun snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# Try XPath
bun click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

常用选项

所有脚本均支持：

• --headless false - 显示浏览器窗口（默认：true）
• --close false - 脚本运行后保持浏览器打开
• --timeout 30000 - 超时时间（毫秒，默认：30000）
• --help - 显示脚本专属帮助信息

故障排除

浏览器无法启动（Linux）：

./install-deps.sh  # Install missing system libraries

截图过大：

• 启用 ImageMagick 以自动压缩
• 使用 --max-size 设置自定义阈值
• 或截取指定元素，而非整页

找不到元素：

• 先使用 snapshot.js 查找选择器
• 检查元素是否动态加载（延长等待时间）
• 如果 CSS 选择器失败，尝试 XPath

找不到脚本：

• 确认位于正确的目录
• 检查脚本名称拼写
• 使用绝对路径：bun /path/to/scripts/navigate.js