chrome-debug

通过远程调试协议进行 Chrome 调试和浏览器操作

概述

Chrome DevTools 协议（CDP）可通过 mcporter 实现远程浏览器自动化和调试。

主要功能：

• 在与 Agent 对话的同时实时调试浏览器
• 自动填写表单并测试交互
• 通过屏幕截图提供视觉反馈
• 检查控制台日志和网络请求
• 在页面上下文中执行 JavaScript

前置条件 [CRITICAL]

使用 Chrome DevTools 前，请确保：

1. Chrome/Chromium 已运行并启用远程调试
2. 浏览器正在监听 9222 端口（默认端口）
3. 使用以下命令测试连接：

mise x node@20 -- mcporter call chrome-devtools.list_pages

如果失败：

• 启动 Chrome：google-chrome --remote-debugging-port=9222
• 确认没有其他进程占用 9222 端口
• 请他人协助设置浏览器

可用工具

工具	用途
list_pages	列出所有打开的页面/标签页
select_page	选择要操作的特定页面/标签页
new_page	创建新的浏览器页面/标签页
close_page	关闭浏览器页面/标签页
navigate_page	跳转至 URL、后退、前进或重新加载
take_snapshot	获取 DOM 快照以供检查（返回 UID）
take_screenshot	截取当前页面的屏幕截图
click	点击页面上的元素
fill	在输入框中填写文本
hover	将鼠标悬停在元素上
press_key	按下键盘按键（Enter、Tab、Escape 等）
evaluate_script	在页面上下文中执行 JavaScript 代码
wait_for	等待元素、导航或特定条件
list_console_messages	获取所有控制台消息（日志、错误、警告）
list_network_requests	获取页面发出的所有网络请求
emulate	模拟设备设置（网络、CPU 限速）
resize_page	调整浏览器视口大小
performance_start_trace	开始性能跟踪
performance_stop_trace	停止性能跟踪并获取结果

提示

获取完整工具列表：mcporter list chrome-devtools --json | jq -r '.tools[] | [.name, .description] | @tsv' | column -t -s $'\t'

核心概念

1. 页面选择模型

• Chrome DevTools 可操作多个页面/标签页
• 使用 list_pages 查看所有打开的页面
• 使用 select_page 选择要操作的页面
• 后续所有命令都将作用于所选页面

2. 基于 UID 的元素模型 [CRITICAL]

• 无法直接使用 CSS 选择器与元素交互
• 必须先调用 take_snapshot 获取带 UID 的无障碍树
• UID 是元素的临时标识符（例如 “5”、“12”、“42”）
• UID 会在导航时失效——导航后请获取新快照

3. 必须使用 JSON 参数

• 所有 mcporter 命令都必须使用包含 JSON 对象的 --args
• 属性名称采用 camelCase（例如 filePath、fullPage、pageIdx）
• 切勿使用 --file-path 或 --full-page 等单独的标志

4. 基于函数的脚本求值

• evaluate_script 需要函数声明，不能是普通代码
• 返回值必须可序列化为 JSON
• 可通过带 UID 的 args 数组传入元素参数

快速参考

便于在 bash 中使用的基本命令：

# List and select page
mise x node@20 -- mcporter call chrome-devtools.list_pages
mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}'

# Take snapshot to get UIDs
mise x node@20 -- mcporter call chrome-devtools.take_snapshot

# Take screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

# Take full-page screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

# Navigate to URL
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"http://localhost:3000"}'

# Navigate back/forward/reload
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"back"}'
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"reload"}'

# Click element (requires UID from snapshot)
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

# Fill input field
mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"5","value":"[email protected]"}'

# Hover element
mise x node@20 -- mcporter call chrome-devtools.hover --args '{"uid":"8"}'

# Press key
mise x node@20 -- mcporter call chrome-devtools.press_key --args '{"key":"Enter"}'

# Run JavaScript
mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"() => { return document.title }"}'

# Run JS with element argument
mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"(el) => { return el.innerText }","args":[{"uid":"12"}]}'

# List console messages
mise x node@20 -- mcporter call chrome-devtools.list_console_messages

# List only errors
mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error"]}'

# List network requests
mise x node@20 -- mcporter call chrome-devtools.list_network_requests

# Filter network by type
mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

# Wait for text to appear
mise x node@20 -- mcporter call chrome-devtools.wait_for --args '{"text":"Success"}'

# Emulate network conditions
mise x node@20 -- mcporter call chrome-devtools.emulate --args '{"networkConditions":"Slow 3G"}'

常见工作流

基本元素交互

# 1. Select page and take snapshot
mise x node@20 -- mcporter call chrome-devtools.list_pages
mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}'
SNAPSHOT=$(mise x node@20 -- mcporter call chrome-devtools.take_snapshot)
echo "$SNAPSHOT"

# 2. Find element UID in snapshot output
# Example: uid=12 input type="email"

# 3. Interact with element using its UID
mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"12","value":"[email protected]"}'
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"15"}'

屏幕截图工作流

# Take viewport screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

# Take full-page screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

# Screenshot specific element
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"uid":"20","filePath":"./button.png"}'

调试 JavaScript 错误

# Check console for errors
mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error","warn"]}'

# Check network requests
mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

运行性能测试

# Execute JavaScript to get performance metrics
mise x node@20 -- mcporter call chrome-devtools.evaluate_script \
  --args '{"function":"() => { const perf = performance.getEntriesByType(\"navigation\")[0]; return { loadTime: perf.loadEventEnd - perf.fetchStart, domInteractive: perf.domInteractive - perf.fetchStart }; }"}'

重要提醒

必须遵循 UID 工作流

# ❌ WRONG - CSS selectors don't work
mise x node@20 -- mcporter call chrome-devtools.click --selector "#login-button"

# ✅ CORRECT - Use UIDs from snapshot
mise x node@20 -- mcporter call chrome-devtools.take_snapshot  # Get UIDs first
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

UID 会在导航时过期

# After navigation, UIDs are invalid
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"..."}'

# Take fresh snapshot to get new UIDs
mise x node@20 -- mcporter call chrome-devtools.take_snapshot

始终使用带 JSON 的 --args

# ❌ WRONG - Individual flags don't work
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --file-path "./screen.png"

# ✅ CORRECT - Use --args with JSON
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

快速故障排查

错误	解决方案
"Element not found" / "Invalid UID"	获取新快照：take_snapshot
"No page selected"	选择页面：select_page --args '{"pageIdx":0}'
"Connection refused"	启动 Chrome：google-chrome --remote-debugging-port=9222
未创建屏幕截图	确保目录存在，并使用 --args 格式
UID 无法使用	UID 在导航后已过期——获取新快照

补充资源

根据需要延迟加载这些参考资料：

参考资料	使用时机
元素交互	使用 UID、点击、悬停或测量元素时
表单填写	填写表单、提交数据或处理键盘输入时
屏幕截图	截取屏幕截图、进行视觉测试或记录状态时
性能	测量页面性能、网络计时或模拟条件时
调试	排查控制台错误、网络故障或脚本执行问题时
导航	浏览页面、管理标签页或处理视口时
故障排除	遇到错误或异常行为时

重要

仅在需要时加载参考资料——不要预先阅读所有文件。请阅读与当前任务对应的特定参考资料。

实际影响

集成 Chrome DevTools Protocol 后，你可以：

• 在与 Agent 对话的同时实时调试浏览器
• 自动填写表单并进行交互测试
• 获得有关应用行为的视觉反馈
• 通过控制台日志立即诊断错误
• 基于屏幕截图执行验证工作流

如果没有这项集成，调试 Web 应用就需要不断在浏览器和 Agent 之间切换上下文。