chrome-browser

Chrome 浏览器自动化

安装

独立脚本：无需下载；该技能会调用 .claude/tools/chrome-browser/chrome-browser.cjs（需要 Node.js v18+）。

MCP 集成（用于完整自动化）：

• Chrome DevTools MCP：通常随环境捆绑；请确保已安装 Chrome/Chromium（google.com/chrome）。
• Claude-in-Chrome：安装 Claude-in-Chrome 扩展，并在需要时使用 --chrome 运行。

速查表与最佳实践

**测试：**测试用户可见的行为，而非实现方式。隔离测试（使用独立存储空间和 Cookie）；使用前置/后置钩子处理登录或设置。模拟第三方网络，而非依赖在线服务。

**DevTools Recorder：**在 Recorder 面板中录制流程；导出为 JSON 或测试脚本（Puppeteer、Nightwatch）。在 CI 中使用 Puppeteer Replay 重放。用于衡量用户流程的性能。

**技巧：**测试/调试时优先使用 Chrome DevTools MCP（始终可用）；已验证身份的会话（GIF、表单）使用 Claude-in-Chrome。限制 GIF 帧数（例如 100 帧）以避免内存问题。使用 take_snapshot 获取结构；使用 evaluate_script 执行自定义检查。

认证与培训

无官方认证。Chrome for Developers – DevTools。Frontend Masters / Udemy 的“Mastering Chrome DevTools”。**技能数据：**测试用户可见的行为；隔离测试；Recorder + Puppeteer Replay；性能跟踪。

钩子与工作流

**建议的钩子：**可选：添加测试后钩子，在失败时截取屏幕截图。当 qa 或 frontend-pro 被分配进行浏览器测试时使用（将 chrome-browser 添加到 contextual：browser_testing 或类似配置）。

**工作流：**与 qa（添加到 contextual）或 frontend-pro 配合，用于 E2E/浏览器流程。流程：打开 URL → 交互（点击/填写）→ 快照或断言。参见 .claude/workflows/chrome-browser-skill-workflow.md。

Chrome Browser Skill - 使用两种集成实现统一的浏览器自动化：Chrome DevTools MCP（始终可用，可进行性能跟踪和网络检查）以及 Claude-in-Chrome 扩展（已验证身份的会话、GIF 录制）。

两种集成——何时使用

功能	Chrome DevTools MCP	Claude-in-Chrome
状态	✅ 始终可用	⚠️ 需要 --chrome 标志
激活	自动（内置）	claude --chrome + 扩展
身份验证会话	❌ 全新浏览器	✅ 使用你的登录信息
性能跟踪	✅ 完整的 Core Web Vitals	❌ 不可用
网络检查	✅ 可详细检查请求正文	✅ 基础检查
设备模拟	✅ 移动设备、地理位置、CPU	❌ 有限
GIF 录制	❌ 不支持	✅ 支持（最多 100 帧）
页面文本提取	通过快照	✅ 专用工具
最适合	测试、调试、性能分析	已验证身份的工作流、演示

性能限制（内存保护）

Chrome 浏览器自动化可以录制 GIF 视频。为防止内存耗尽：

• GIF 帧数限制：100 帧（硬性限制）
• 每帧：5-20 KB（取决于复杂度）
• 100 帧 × 平均 10 KB = 每次录制约 1 MB
• 保持浏览器会话的内存效率

帧数跟踪：

• 每帧的典型操作数：1-2 个（点击、滚动、输入）
• 50 帧 = 25-50 个操作
• 100 帧 = 50-100 个操作
• 对于较长的工作流，请使用多次录制

决策指南

Need to test/debug a public site?     → Chrome DevTools MCP
Need performance analysis?            → Chrome DevTools MCP
Need to access authenticated apps?    → Claude-in-Chrome (--chrome)
Need to record a demo GIF?            → Claude-in-Chrome (--chrome)
Need to interact with Google Docs?    → Claude-in-Chrome (--chrome)
Need device/network emulation?        → Chrome DevTools MCP

**Chrome DevTools MCP：** - 页面导航和标签页管理 - 元素交互（点击、填写、悬停、拖拽） - 在页面上下文中执行 JavaScript - 监控控制台消息 - 检查网络请求并访问请求正文 - 使用 Core Web Vitals 进行性能跟踪 - 设备模拟（移动设备、地理位置、CPU 限速） - 截取屏幕截图 - 处理对话框（alert、confirm、prompt）

Claude-in-Chrome：

• 与已通过身份验证的 Web 应用交互（Google Docs、Gmail、Notion）
• 将会话录制为 GIF
• 通过自然语言查找元素
• 使用已保存的数据自动填写表单
• 提取页面文本
• 执行快捷操作／工作流

Chrome DevTools MCP（始终可用）

无需设置——这些工具可以立即使用。

步骤 1：列出并选择页面

// List all open pages
mcp__chrome - devtools__list_pages();

// Select a page to work with
mcp__chrome - devtools__select_page({ pageId: 1 });

// Create a new page
mcp__chrome - devtools__new_page({ url: 'https://example.com' });

步骤 2：导航和交互

// Navigate to URL
mcp__chrome - devtools__navigate_page({ url: 'https://example.com' });

// Take accessibility snapshot (get element UIDs)
mcp__chrome - devtools__take_snapshot();

// Click element by UID from snapshot
mcp__chrome - devtools__click({ uid: 'ref_123' });

// Fill form field
mcp__chrome - devtools__fill({ uid: 'ref_456', value: '[email protected]' });

// Fill entire form
mcp__chrome -
  devtools__fill_form({
    elements: [
      { uid: 'ref_456', value: '[email protected]' },
      { uid: 'ref_789', value: 'password123' },
    ],
  });

步骤 3：调试和检查

// Read console messages
mcp__chrome - devtools__list_console_messages({ types: ['error', 'warn'] });

// Get specific console message details
mcp__chrome - devtools__get_console_message({ msgid: 1 });

// List network requests
mcp__chrome - devtools__list_network_requests({ resourceTypes: ['xhr', 'fetch'] });

// Get request/response details
mcp__chrome - devtools__get_network_request({ reqid: 1 });

// Execute JavaScript
mcp__chrome -
  devtools__evaluate_script({
    function: '() => document.title',
  });

步骤 4：性能分析

// Start performance trace (with page reload)
mcp__chrome - devtools__performance_start_trace({ reload: true, autoStop: true });

// Or manual stop
mcp__chrome - devtools__performance_start_trace({ reload: true, autoStop: false });
// ... interact with page ...
mcp__chrome - devtools__performance_stop_trace();

// Analyze specific insight
mcp__chrome -
  devtools__performance_analyze_insight({
    insightSetId: 'navigation-1',
    insightName: 'LCPBreakdown',
  });

步骤 5：设备模拟

// Emulate mobile device
mcp__chrome -
  devtools__emulate({
    viewport: {
      width: 375,
      height: 667,
      deviceScaleFactor: 2,
      isMobile: true,
      hasTouch: true,
    },
    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)...',
  });

// Emulate slow network
mcp__chrome - devtools__emulate({ networkConditions: 'Slow 3G' });

// Emulate geolocation
mcp__chrome -
  devtools__emulate({
    geolocation: { latitude: 37.7749, longitude: -122.4194 },
  });

---

Claude-in-Chrome（需要设置）

前提条件

1. 安装 Claude-in-Chrome 扩展程序（v1.0.36+），可从 Chrome Web Store 获取
2. 使用标志启动 Claude：claude --chrome
3. Chrome 必须处于可见状态（不能使用无头模式）
4. 需要付费的 Claude 方案（Pro、Team 或 Enterprise）

步骤 1：获取标签页上下文

// ALWAYS call first to get available tabs
mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true })

// Create a new tab for this conversation
mcp__claude-in-chrome__tabs_create_mcp()

步骤 2：导航和读取

// Navigate to URL
mcp__claude-in-chrome__navigate({ url: "https://docs.google.com", tabId: 123 })

// Read page structure (accessibility tree)
mcp__claude-in-chrome__read_page({ tabId: 123 })

// Find elements by natural language
mcp__claude-in-chrome__find({ query: "login button", tabId: 123 })

// Extract page text
mcp__claude-in-chrome__get_page_text({ tabId: 123 })

步骤 3：交互

// Click, type, screenshot via computer tool
mcp__claude-in-chrome__computer({
  action: "left_click",
  coordinate: [100, 200],
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "type",
  text: "Hello world",
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "screenshot",
  tabId: 123
})

// Fill form by element reference
mcp__claude-in-chrome__form_input({
  ref: "ref_1",
  value: "[email protected]",
  tabId: 123
})

步骤 4：录制 GIF 演示

// Start recording
mcp__claude-in-chrome__gif_creator({ action: "start_recording", tabId: 123 })

// Take screenshot to capture initial state
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// ... perform actions ...

// Take final screenshot
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Stop and export
mcp__claude-in-chrome__gif_creator({ action: "stop_recording", tabId: 123 })
mcp__claude-in-chrome__gif_creator({
  action: "export",
  download: true,
  filename: "demo.gif",
  tabId: 123
})

录制最佳实践

✓ 推荐做法：

• 登录流程：15-20 帧（5-10 个操作）
• 填写表单：10-15 帧（5-8 个操作）
• 导航演示：20-30 帧（10-15 个操作）
• 完整工作流：录制 2-3 段，每段 30-50 帧

✗ 不推荐做法：

• 单次录制超过 200 帧
• 等待加载（每秒会增加 10+ 个空帧）
• 连续滚动（很快就可能达到 100+ 帧）
• 同时进行多次录制

如果达到 100 帧：

1. 停止录制
2. 导出当前 GIF
3. 为下一部分开始新的录制
4. 在文档中关联这些录制

超时管理

• 默认超时：每次录制 30 秒
• 如果录制超过 100 帧：使用多次 30 秒录制
• 不要等待缓慢加载（改为截屏）
• 操作要快速（尽量减少等待）

</execution_process>

<best_practices>

Chrome DevTools MCP

1. 始终先获取快照，以便在点击／填写前获取元素 UID
2. 在操作中使用 includeSnapshot: true，以获取更新后的状态
3. 按 resourceTypes 筛选网络请求，避免产生过多无关信息
4. 使用 filePath 参数将跟踪数据保存到文件，以便稍后分析

Claude-in-Chrome

1. 先调用 tabs_context_mcp，以获取有效的标签页 ID
2. 创建新标签页，而不是重复使用现有标签页
3. 先使用 read_page，再使用 find，以了解页面结构
4. 使用模式筛选控制台，避免输出过多信息
5. 手动关闭模态对话框——它们会阻止所有事件

通用

1. 对于公共网站，优先使用 Chrome DevTools MCP（始终可用）
2. 仅在需要身份验证时使用 Claude-in-Chrome
3. 不要触发 alert/confirm/prompt——它们会阻止浏览器事件

</best_practices>

**测试登录流程（Chrome DevTools MCP）：**

// Create page and navigate
mcp__chrome - devtools__new_page({ url: 'https://example.com/login' });

// Take snapshot to get element UIDs
mcp__chrome - devtools__take_snapshot();

// Fill login form
mcp__chrome -
  devtools__fill_form({
    elements: [
      { uid: 'email_field', value: '[email protected]' },
      { uid: 'password_field', value: 'testpass123' },
    ],
  });

// Click submit
mcp__chrome - devtools__click({ uid: 'submit_button' });

// Check for errors
mcp__chrome - devtools__list_console_messages({ types: ['error'] });

</usage_example>

<usage_example> 性能审计（Chrome DevTools MCP）：

// Navigate to page
mcp__chrome - devtools__navigate_page({ url: 'https://example.com' });

// Run performance trace with reload
mcp__chrome -
  devtools__performance_start_trace({
    reload: true,
    autoStop: true,
    filePath: 'trace.json.gz',
  });

// Analyze LCP breakdown
mcp__chrome -
  devtools__performance_analyze_insight({
    insightSetId: 'navigation-1',
    insightName: 'LCPBreakdown',
  });

</usage_example>

<usage_example> 编辑 Google Docs（Claude-in-Chrome）：

// Get tab context
mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true })

// Navigate to Google Docs (uses your login)
mcp__claude-in-chrome__navigate({
  url: "https://docs.google.com/document/d/YOUR_DOC_ID",
  tabId: 123
})

// Read page to find elements
mcp__claude-in-chrome__read_page({ tabId: 123 })

// Click in document and type
mcp__claude-in-chrome__computer({
  action: "left_click",
  ref: "document_body",
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "type",
  text: "Meeting notes for today...",
  tabId: 123
})

</usage_example>

<usage_example> 录制演示 GIF（Claude-in-Chrome）：

// Start recording
mcp__claude-in-chrome__gif_creator({ action: "start_recording", tabId: 123 })

// Initial screenshot
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Navigate
mcp__claude-in-chrome__navigate({ url: "https://example.com/product", tabId: 123 })
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Click add to cart
mcp__claude-in-chrome__computer({ action: "left_click", ref: "add_to_cart", tabId: 123 })
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Stop and export
mcp__claude-in-chrome__gif_creator({ action: "stop_recording", tabId: 123 })
mcp__claude-in-chrome__gif_creator({
  action: "export",
  download: true,
  filename: "add-to-cart-flow.gif",
  options: { showClickIndicators: true, showProgressBar: true },
  tabId: 123
})

</usage_example>

可用工具

Chrome DevTools MCP（始终可用）

工具	描述
mcp__chrome-devtools__list_pages	列出所有浏览器页面
mcp__chrome-devtools__select_page	选择要操作的页面
mcp__chrome-devtools__new_page	使用 URL 创建新页面
mcp__chrome-devtools__close_page	关闭页面
mcp__chrome-devtools__navigate_page	导航、重新加载、前进或后退
mcp__chrome-devtools__take_snapshot	获取包含 UID 的无障碍树
mcp__chrome-devtools__take_screenshot	截取页面或元素的屏幕截图
mcp__chrome-devtools__click	按 UID 点击元素
mcp__chrome-devtools__fill	按 UID 填写输入框或选择框
mcp__chrome-devtools__fill_form	填写多个表单元素
mcp__chrome-devtools__hover	将鼠标悬停在元素上
mcp__chrome-devtools__drag	将元素拖到另一个位置
mcp__chrome-devtools__press_key	按下按键或组合键
mcp__chrome-devtools__evaluate_script	执行 JavaScript
mcp__chrome-devtools__handle_dialog	接受或关闭对话框
mcp__chrome-devtools__upload_file	通过输入框上传文件
mcp__chrome-devtools__wait_for	等待文本出现
mcp__chrome-devtools__resize_page	调整浏览器窗口大小
mcp__chrome-devtools__emulate	模拟设备、网络或地理位置
mcp__chrome-devtools__list_console_messages	列出控制台输出
mcp__chrome-devtools__get_console_message	获取消息详情
mcp__chrome-devtools__list_network_requests	列出网络请求
mcp__chrome-devtools__get_network_request	获取请求和响应详情
mcp__chrome-devtools__performance_start_trace	开始性能记录
mcp__chrome-devtools__performance_stop_trace	停止性能记录
mcp__chrome-devtools__performance_analyze_insight	分析性能洞察

Claude-in-Chrome（需要 --chrome 标志）

工具	描述
mcp__claude-in-chrome__tabs_context_mcp	获取标签页上下文（首先调用！）
mcp__claude-in-chrome__tabs_create_mcp	创建新标签页
mcp__claude-in-chrome__navigate	导航至 URL
mcp__claude-in-chrome__read_page	获取无障碍树
mcp__claude-in-chrome__find	按描述查找元素
mcp__claude-in-chrome__get_page_text	提取页面文本
mcp__claude-in-chrome__computer	点击、输入、截图、滚动
mcp__claude-in-chrome__form_input	填写表单字段
mcp__claude-in-chrome__fill_form	填写多个字段
mcp__claude-in-chrome__javascript_tool	执行 JavaScript
mcp__claude-in-chrome__read_console_messages	读取控制台日志
mcp__claude-in-chrome__read_network_requests	读取网络请求
mcp__claude-in-chrome__resize_window	调整浏览器窗口大小
mcp__claude-in-chrome__upload_image	将图像上传至元素
mcp__claude-in-chrome__gif_creator	录制／导出 GIF
mcp__claude-in-chrome__shortcuts_list	列出可用快捷方式
mcp__claude-in-chrome__shortcuts_execute	执行快捷方式
mcp__claude-in-chrome__update_plan	提交计划以供批准

Agent 集成

此技能会自动分配给：

• developer - 测试、调试、数据提取
• qa - 自动化测试、表单验证、用户流程验证
• security-architect - 安全测试、身份验证流程
• devops-troubleshooter - 生产环境调试、监控
• researcher - 网页抓取、数据提取

相关工作流

有关如何有效使用此技能的指南，请参阅相应的工作流：

• 工作流文件：.claude/workflows/chrome-browser-skill-workflow.md
• 适用场景：需要通过浏览器自动化进行测试、调试、已验证身份的工作流或演示录制时
• 集成方式：
  • 斜杠命令调用（/chrome-browser）
  • Agent 技能分配（通过 frontmatter）
  • 直接执行脚本

两种集成选项：

• Chrome DevTools MCP（始终可用）- 用于公共网站测试、性能分析和调试
• Claude-in-Chrome（需要 --chrome 标志）- 用于已验证身份的应用工作流、GIF 录制

该工作流提供了有关调用方式、Agent 分配和记忆集成模式的示例。

故障排除

Claude-in-Chrome“浏览器扩展未连接”

症状：使用 --chrome 标志时，工具返回“浏览器扩展未连接”错误，尽管扩展已安装。

根本原因：Claude.app（桌面版）和 Claude Code 注册了相互冲突的原生消息主机。两者都已安装时，Chrome 扩展会连接到最后注册的主机，导致连接失败。

诊断：

1. 检查 Claude.app 和 Claude Code 是否都已安装
2. 在 Windows 上：检查 %APPDATA%\Claude\ChromeNativeHost\com.anthropic.claude_browser_extension.json
3. 在 macOS 上：检查 ~/Library/Application Support/Claude/ChromeNativeHost/

已知 Bug：此问题已记录在 GitHub issue 中：

• #15336 - Windows 原生消息主机未安装
• #14894 - 在 macOS 上重新连接扩展失败
• #20790 - 扩展连接到 Claude.app，而非 Claude Code

解决方法（macOS）：

# Disable Claude.app's native host (keep file for restoration)
cd ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/
mv com.anthropic.claude_browser_extension.json com.anthropic.claude_browser_extension.json.disabled

# Restart Chrome completely (quit and reopen)
# Then start Claude Code with --chrome flag

解决方法（Windows）：尚无完整文档。可尝试以下方法：

# Rename the config to disable Claude.app's registration
cd $env:APPDATA\Claude\ChromeNativeHost
ren com.anthropic.claude_browser_extension.json com.anthropic.claude_browser_extension.json.disabled

# Restart Chrome and try again

替代方案：改用 Chrome DevTools MCP——它无需扩展即可运行，并能满足大多数使用场景的类似需求。

模态对话框阻止事件

症状：触发 alert/confirm/prompt 后，所有浏览器工具都停止响应。

原因：JavaScript 模态对话框会阻止所有浏览器事件，包括扩展通信。

修复方法：用户必须在浏览器中手动关闭对话框。避免在自动化脚本中触发对话框。

记忆协议（强制）

开始之前：

cat .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

请做好随时中断的准备：上下文可能会重置。如果内容没有记录在记忆中，就等于没有发生。