Chrome Dev Control

chrome开发控制

用于AI代理的Bash可调用Chrome DevTools脚本。导航、截图、点击、检查——无需MCP设置。

16个CLI工具，用于页面管理、DOM交互、屏幕截图、控制台/网络检查和性能跟踪。

对人工智能代理至关重要

这些是自定义的CLI包装器，而不是标准的npm包。切勿使用剧作家、木偶师或硒。

# CORRECT - invoke directly
chrome-navigate.js "http://localhost:3000"
chrome-snapshot.js

# WRONG - don't do these
node chrome-navigate.js          # No 'node' prefix
npx playwright test              # NEVER use Playwright
npm install puppeteer            # NEVER install browser libs

设置

1. 克隆/下载到您的首选位置
2. 安装依赖项：

cd ~/agent-tools/chrome-dev-control
npm install

1. 添加到PATH ~/.zshrc 或 ~/.bashrc:

export PATH="$HOME/agent-tools/chrome-dev-control:$PATH"

1. 重新加载外壳：

source ~/.zshrc

1. 验证：

chrome-navigate.js --help

先决条件：

• 运行带有DevTools的Chrome浏览器可访问
• Node.js 18+

如何调用这些工具

对代理人至关重要：这些是PATH中的可执行脚本。当通过Bash工具调用时：

对的：

chrome-snapshot.js
chrome-click.js "submit-btn"
chrome-navigate.js "https://example.com"

不正确：

node chrome-snapshot.js          # Don't use 'node' prefix
./chrome-snapshot.js             # Don't use './' prefix

快照（最重要）

chrome-snapshot.js
chrome-snapshot.js --verbose
chrome-snapshot.js --file /tmp/snapshot.txt

拍摄可访问性树快照。返回所有交互所需的元素UID。

总是先跑这个。 单击、填充、拖动等操作需要快照中的UID。

选项：

• --verbose：包括完整的树详细信息
• --file PATH：保存到文件而不是stdout

截图

chrome-screenshot.js --file /tmp/page.png
chrome-screenshot.js --full --file /tmp/full.png
chrome-screenshot.js --uid "hero-image" --file /tmp/element.png
chrome-screenshot.js --format jpeg --quality 85 --file /tmp/page.jpg

捕获视口、整页或特定元素。

选项：

• --full：完整的可滚动页面（不仅仅是视口）
• --uid ID：按UID捕获特定元素
• --file PATH：保存到文件（必填）
• --format FMT：png、jpeg、webp（默认值：png）
• --quality N：jpeg/webp为0-100

屏幕截图大小限制： Claude API的最大图像尺寸为8000像素。对于长页面，请使用 chrome-split-image.js 分割成可查看的部分。

全屏截图的工作流程：

# 1. Take full-page screenshot
chrome-screenshot.js --full --file /tmp/full-page.png

# 2. Check dimensions / split if needed
chrome-split-image.js /tmp/full-page.png

# 3. View each section (output will list created files)
# Files: /tmp/full-page-1.png, /tmp/full-page-2.png, etc.

点击

chrome-click.js "submit-btn"
chrome-click.js "folder-icon" --double
chrome-click.js "dropdown-menu" --hover

单击、双击或悬停在元素上。

选项：

• --double：双击
• --hover：仅悬停（无点击）

填充

chrome-fill.js "email-input" "user@example.com"
chrome-fill.js "country-select" "United States"
chrome-fill.js --form '[{"uid":"email","value":"a@b.com"},{"uid":"pass","value":"secret"}]'

填写输入、文本区域或选择下拉菜单。

选项：

• --form JSON：一次填写多个字段

钥匙

chrome-keys.js "Enter"
chrome-keys.js "Escape"
chrome-keys.js "Control+A"
chrome-keys.js "Control+Shift+R"
chrome-keys.js "ArrowDown"

按键盘键或组合键。

修改器： Control, Shift, Alt, Meta

滚动

chrome-scroll.js down
chrome-scroll.js down 1000
chrome-scroll.js up 300
chrome-scroll.js top
chrome-scroll.js bottom
chrome-scroll.js page-down
chrome-scroll.js page-up
chrome-scroll.js --to "footer"
chrome-scroll.js --to "section-3" --instant

滚动页面或至特定元素。

方向：

• down [px]：向下滚动（默认值：500px）
• up [px]：向上滚动（默认值：500px）
• top：跳到页面顶部
• bottom：跳到页面底部
• page-down：向下滚动一个视口高度
• page-up：向上滚动一个视口高度

元素滚动：

• --to ：将元素滚动到视图中（平滑）
• --to --instant：滚动元素进入视图（即时）

导航

chrome-navigate.js "https://example.com"
chrome-navigate.js --back
chrome-navigate.js --forward
chrome-navigate.js --reload
chrome-navigate.js --reload --no-cache
chrome-navigate.js --new "https://google.com"
chrome-navigate.js --list
chrome-navigate.js --select 0
chrome-navigate.js --close 1
chrome-navigate.js --wait "Login successful"
chrome-navigate.js --resize 1920 1080

浏览页面并管理浏览器选项卡。

导航：

• ``：转到URL
• --back：历史回顾
• --forward：历史前进
• --reload：重新加载（添加 --no-cache 绕过缓存）
• --wait ：等待文本出现

页面管理：

• --new ：打开新选项卡
• --list：列出打开的页面
• --select ：按索引选择页面
• --close ：按索引关闭页面
• --resize W H：设置视口大小

Eval（JavaScript）

chrome-eval.js '() => document.title'
chrome-eval.js '() => window.location.href'
chrome-eval.js '() => document.querySelectorAll("a").length'
chrome-eval.js 'async () => await fetch("/api").then(r => r.json())'

在页面上下文中执行JavaScript。必须返回JSON可序列化值。

使用元素args：

chrome-eval.js '(el) => el.innerText' --args '[{"uid":"heading"}]'
chrome-eval.js '(el) => el.getBoundingClientRect()' --args '[{"uid":"hero"}]'

控制台

chrome-console.js
chrome-console.js --types error,warn
chrome-console.js --preserved --limit 50
chrome-console.js --get 42

列出或检索浏览器控制台消息。

选项：

• --types LIST：筛选器（日志、错误、警告、信息、调试等）
• --preserved：包括最近3次导航
• --limit N：最大消息数
• --get ：获取特定消息

网络

chrome-network.js
chrome-network.js --types xhr,fetch
chrome-network.js --preserved --limit 100
chrome-network.js --get 123
chrome-network.js --get              # Get selected in DevTools

列出或检索网络请求。

选项：

• --types LIST：过滤器（xhr、fetch、文档、脚本、图像等）
• --preserved：包括最近3次导航
• --limit N：最大请求数
• --get [id]：获取请求详细信息（省略DevTools选择的id）

模仿

chrome-emulate.js --network "Slow 3G"
chrome-emulate.js --network "Offline"
chrome-emulate.js --network "No emulation"
chrome-emulate.js --cpu 4
chrome-emulate.js --geo 37.7749 -122.4194
chrome-emulate.js --geo-clear

模拟设备条件。

网络： Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G, No emulation

CPU： 减速系数1-20（1=无油门）

地理位置： 纬度（-90至90），经度（-180至180）

演出

chrome-perf.js --start --reload --auto-stop
chrome-perf.js --start --reload
chrome-perf.js --stop
chrome-perf.js --insight "set-123" "LCPBreakdown"

性能跟踪和核心Web生命周期。

选项：

• --start：开始跟踪

- --reload：启动时重新加载页面 - --auto-stop：自动停止录制

• --stop：结束跟踪
• --insight ：分析洞察力（DocumentLatency、LCP分解等）

分割图像（用于大屏幕截图）

chrome-split-image.js /tmp/full-page.png
chrome-split-image.js /tmp/full-page.png --max-height 5000
chrome-split-image.js /tmp/full-page.png --output /tmp/sections
chrome-split-image.js /tmp/full-page.png --info

将大屏幕截图拆分为符合API大小限制（8000px）的部分。

选项：

• --max-height N：每节最大高度（默认值：7500px）
• --output DIR：输出目录（默认：与输入相同）
• --info：只显示尺寸，不要拆分

输出： 创建 filename-1.png, filename-2.png等，并列出以便于查看。

其他工具

chrome-drag.js "item" "drop-zone"     # Drag and drop
chrome-upload.js "input" "/path.pdf"  # File upload
chrome-dialog.js --accept             # Accept alert/confirm
chrome-dialog.js --accept "text"      # Accept prompt with text
chrome-dialog.js --dismiss            # Dismiss dialog

代币效率最佳实践

1. 先快照：始终运行 chrome-snapshot.js 在交互之前获取UID
2. 批量操作：使用 chrome-fill.js --form 适用于多个字段
3. 目标截图：使用 --uid 只捕捉你需要的东西
4. 筛选器控制台/网络：使用 --types 减少产量
5. 高效滚动：使用 chrome-scroll.js page-down 用于快速导航

工作流示例

# 1. Navigate to page
chrome-navigate.js "https://example.com/login"

# 2. Get element UIDs
chrome-snapshot.js

# 3. Fill login form
chrome-fill.js --form '[{"uid":"email","value":"user@example.com"},{"uid":"password","value":"secret"}]'

# 4. Click submit
chrome-click.js "submit-btn"

# 5. Wait for redirect
chrome-navigate.js --wait "Dashboard"

# 6. Take screenshot
chrome-screenshot.js --file /tmp/dashboard.png

故障排除

“找不到命令”错误

# Check if tools are in PATH
which chrome-navigate.js

# If not found, add the directory to PATH
echo 'export PATH="$HOME/agent-tools/chrome-dev-control:$PATH"' >> ~/.zshrc
source ~/.zshrc

“图像尺寸超过最大值”错误

整页截图可能超过克劳德的8000倍限制。将它们分成几个部分：

# Take full-page screenshot
chrome-screenshot.js --full --file /tmp/full-page.png

# Split into viewable sections
chrome-split-image.js /tmp/full-page.png

# Output: /tmp/full-page-1.png, /tmp/full-page-2.png, etc.
# Read each section to view the entire page

无法连接到Chrome

确保Chrome在可访问DevTools的情况下运行。工具使用 @anthropic-ai/chrome-devtools-mcp 通过麦克波特。

未安装mcporter

npm install -g mcporter