bb-browser

name	bb-browser
description	通用浏览器自动化技能 - 使用 bb-browser MCP 控制浏览器打开页面、识别组件、执行操作
model	sonnet

bb-browser

使用 bb-browser MCP 工具进行通用浏览器自动化操作，支持打开任意网页、识别页面元素并执行各种操作。

何时使用

当用户想要：

• 打开任意网页并浏览内容
• 获取页面快照（accessibility tree）
• 点击页面元素
• 输入文本或填写表单
• 执行 JavaScript 代码
• 截取屏幕截图
• 查看网络请求
• 自动化操作社交媒体（X、Reddit、GitHub 等）

触发关键词：

• "打开网页"
• "帮我打开"
• "浏览器"
• "截图"
• "点击"
• "填写"
• "执行 JS"
• "查看网络请求"
• "发推" / "发微博" / "发小红书"

前置条件

1. bb-browser MCP 已配置并可用
2. Chrome 扩展已安装并保持登录状态

核心操作流程

1. 打开网页

使用 mcp__bb-browser__browser_open 工具
URL: 任意网址，如 https://x.com, https://github.com 等

2. 获取页面快照

使用 mcp__bb-browser__browser_snapshot 工具
参数: tab 可选（默认当前标签页）

返回页面的 accessibility tree，包含：
- 文本内容
- 可交互元素（按钮、链接、输入框等）
- 元素的 ref 编号（用于后续操作）

3. 点击元素

使用 mcp__bb-browser__browser_click 工具
参数:
- ref: 元素引用编号（从 snapshot 获取）
- tab: 可选，指定标签页

4. 输入文本

填入文本（覆盖原有内容）：
使用 mcp__bb-browser__browser_fill 工具
参数:
- ref: 输入框引用编号
- text: 要填入的文本

追加文本（不清除原有内容）：
使用 mcp__bb-browser__browser_type 工具

5. 页面滚动

使用 mcp__bb-browser__browser_scroll 工具
参数:
- direction: up/down/left/right
- pixels: 滚动像素值（默认 500）

6. 执行 JavaScript

使用 mcp__bb-browser__browser_eval 工具
参数:
- script: 要执行的 JavaScript 代码

示例：
- 获取页面标题: "document.title"
- 获取 URL: "location.href"
- 自定义操作: "document.querySelector('.btn').click()"

7. 截取屏幕截图

使用 mcp__bb-browser__browser_screenshot 工具

8. 查看网络请求

使用 mcp__bb-browser__browser_network 工具
参数:
- command: requests（获取请求）/ clear（清除）
- filter: 可选，按 URL 过滤
- withBody: 可选，是否包含请求/响应体

9. 等待页面加载

使用 mcp__bb-browser__browser_wait 工具
参数:
- time: 等待毫秒数

常用操作示例

示例 1：打开网页并搜索

用户：帮我打开 GitHub 搜索 Claude Code

1. 打开 GitHub: browser_open url="https://github.com"
2. 获取快照: browser_snapshot
3. 点击搜索框: browser_click ref="XX"
4. 输入搜索词: browser_fill ref="XX" text="Claude Code"
5. 按回车: browser_press key="Enter"

示例 2：自动化登录操作

用户：帮我登录某个网站

1. 打开登录页: browser_open url="https://example.com/login"
2. 获取快照: browser_snapshot
3. 输入用户名: browser_fill ref="XX" text="username"
4. 输入密码: browser_fill ref="XX" text="password"
5. 点击登录按钮: browser_click ref="XX"
6. 等待跳转: browser_wait time="2000"
7. 验证: browser_snapshot

示例 3：填写表单

用户：帮我填一个调查问卷

1. 打开表单页面: browser_open url="https://example.com/survey"
2. 获取快照查看所有输入框
3. 依次填写每个问题:
   - browser_fill ref="问题1" text="答案1"
   - browser_fill ref="问题2" text="答案2"
4. 点击提交: browser_click ref="提交按钮"

示例 4：抓取页面数据

用户：帮我看看这个页面讲了什么

1. 打开页面: browser_open url="https://example.com/article"
2. 获取快照: browser_snapshot
3. 解析页面中的文本内容并总结给用户

示例 5：监控网络请求

用户：看看这个页面发了什么请求

1. 打开页面: browser_open url="https://example.com"
2. 清空记录: browser_network command="clear"
3. 执行一些操作让页面发请求
4. 获取请求: browser_network command="requests" withBody=true

站点适配器（Site Adapters）

bb-browser 还支持通过 site 命令快速访问特定平台：

平台	命令示例	功能
X (Twitter)	bb-browser site x/user elonmusk	查看用户资料
Reddit	bb-browser site reddit/thread URL	获取讨论树
GitHub	bb-browser site github/repo owner/repo	查看仓库
知乎	bb-browser site zhihu/hot	知乎热榜
微博	bb-browser site weibo/hot	微博热搜
B站	bb-browser site bilibili/popular	B站热门
小红书	bb-browser site xiaohongshu/search 美食	小红书搜索
YouTube	bb-browser site youtube/transcript VIDEO_ID	视频字幕

注：Site Adapters 通过 eval 在浏览器中执行，使用用户已登录的 cookie，可绕过反爬虫机制。

X.com 详细操作指南

1. 发推文

操作流程：
1. 打开首页: browser_open url="https://x.com/home"
2. 获取快照: browser_snapshot
3. 找到发推按钮（通常是首页右侧或顶部）: browser_click ref="XX"
4. 等待发推框出现: browser_wait time="1000"
5. 输入内容: browser_fill ref="输入框ref" text="内容"
6. 找到发布按钮并点击: browser_click ref="发布按钮ref"
7. 等待发送: browser_wait time="2000"
8. 验证：刷新页面或获取快照确认推文出现

字符限制：非 Premium 用户最多 375 字符

2. 查看回复

操作流程：
1. 打开通知页面: browser_open url="https://x.com/notifications"
2. 获取快照: browser_snapshot
3. 滚动查看最新回复: browser_scroll direction="down"
4. 点击具体回复进入详情: browser_click ref="XX"
5. 获取快照查看完整对话

3. 发回复

操作流程：
1. 打开目标帖子: browser_open url="https://x.com/user/status/帖子ID"
2. 获取快照: browser_snapshot
3. 找到回复按钮并点击: browser_click ref="回复按钮ref"
4. 等待输入框出现: browser_wait time="1000"
5. 输入回复内容: browser_fill ref="输入框ref" text="回复内容"
6. 发送: browser_click ref="发送按钮ref"
7. 验证：检查是否发送成功

⚠️ 注意：回复有 375 字符限制，超出会失败

4. 判断窗口是否被插件遮挡

问题：Chrome 扩展可能遮挡页面元素，导致点击失败

检测方法：
1. 截图检查: browser_screenshot
   - 查看是否有悬浮窗、遮罩层覆盖
2. JS 检测:
   browser_eval script="
     const overlay = document.querySelector('.extension-overlay, [class*=\"extension\"], [id*=\"extension\"]);
     if (overlay && overlay.offsetParent !== null) {
       console.log('检测到扩展遮挡');
     }
   "
3. 滚动检查:
   - 尝试滚动到页面顶部/底部
   - 观察元素位置是否有变化

解决方法：

• 关闭遮挡的 Chrome 扩展
• 使用无扩展模式的浏览器配置
• 调整页面缩放比例

5. 验证推文/回复是否发送成功

方法一：刷新页面验证
1. 关闭当前标签页
2. 重新打开个人主页: browser_open url="https://x.com/home"
3. 检查最新推文是否出现

方法二：检查通知
1. 打开通知: browser_open url="https://x.com/notifications"
2. 查看是否有"推文已发送"相关提示

方法三：检查元素状态
browser_eval script="
  const errorMsg = document.querySelector('[data-testid=\"alert\"], .error-message');
  if (errorMsg) {
    console.log('发送失败: ' + errorMsg.textContent);
  } else {
    console.log('发送成功');
  }
"

方法四：检查网络请求
browser_network command="requests" filter="graphql"
查看是否有 tweet 创建相关的请求及响应状态

X.com 常见元素 ref（参考）

功能	元素描述	定位方式
发推按钮	"What's happening" 输入框	data-testid 搜索
发布按钮	"Post" / "发送" 按钮	text 匹配
回复按钮	回复图标	aria-label 包含 "Reply"
点赞按钮	心形图标	aria-label 包含 "Like"
转推按钮	转推图标	aria-label contains "Retweet"
通知	铃铛图标	aria-label contains "Notifications"

X.com 快捷操作命令

# 使用 Site Adapter 查看用户主页
bb-browser site x/user username

# 使用 Site Adapter 查看帖子
bb-browser site x/post status_id

操作最佳实践

安全注意事项

1. 敏感信息：不要在代码中硬编码密码、token 等敏感信息
2. 确认操作：涉及重要操作（删除、发布）时，先询问用户确认
3. 登录状态：确保目标网站已登录，避免操作失败

效率技巧

1. 先快照：每次操作前先 snapshot 确认当前页面状态
2. 元素定位：从 snapshot 中获取正确的 ref 编号
3. 适当等待：页面跳转后用 wait 等待加载
4. 批量操作：同一页面的多个操作可以连续执行

已知限制

1. 多实例冲突问题

❌ 不支持多个 Claude Code 同时使用 bb-browser

同时运行多个 Claude Code 实例会导致冲突，因为：

• bb-browser 使用同一个 Chrome 浏览器实例
• 同时操作会产生竞争条件，导致操作失败

解决方案：

• 确保同时只有一个 Claude Code 实例使用 bb-browser
• 使用完关闭对话，或等待其他实例完成操作
• 不同实例可以使用不同的 Chrome 浏览器实例（需要配置多个浏览器配置文件）

2. 登录状态依赖

• bb-browser 使用用户已登录的 Chrome 浏览器
• 如果未登录目标网站，需要先手动登录
• 登录状态会持久化在浏览器配置文件中

3. 页面加载时间

• 动态内容较多的页面（如 SPA）需要额外等待时间
• 建议在关键操作后使用 browser_wait 等待加载

4. 字符限制

• X.com 非 Premium 用户回复有 375 字符限制
• 超出限制会导致发送失败，需要分段发送

调试技巧

1. 截图确认：用 screenshot 查看实际页面渲染
2. JS 调试：用 eval 检查元素或变量
3. 网络监控：用 network 查看 API 请求

工具列表

工具	用途	关键参数
mcp__bb-browser__browser_open	打开 URL	url
mcp__bb-browser__browser_snapshot	获取页面快照	tab (可选)
mcp__bb-browser__browser_click	点击元素	ref, tab
mcp__bb-browser__browser_fill	填入文本	ref, text, tab
mcp__bb-browser__browser_type	追加文本	ref, text, tab
mcp__bb-browser__browser_press	按键	key, tab
mcp__bb-browser__browser_scroll	滚动	direction, pixels, tab
mcp__bb-browser__browser_eval	执行 JS	script, tab
mcp__bb-browser__browser_screenshot	截图	tab
mcp__bb-browser__browser_network	网络请求	command, filter, withBody, tab
mcp__bb-browser__browser_wait	等待	time
mcp__bb-browser__browser_get	获取元素属性	attribute, ref, tab
mcp__bb-browser__browser_hover	悬停	ref, tab
mcp__bb-browser__browser_tab_list	标签页列表	-
mcp__bb-browser__browser_tab_new	新建标签页	url (可选)
mcp__bb-browser__browser_close	关闭标签页	tab