📌 一句话介绍

Your browser is the API. No keys. No bots. No scrapers.
（你的浏览器，就是最好的 API。无需密钥，无需机器人，无需爬虫。）

bb-browser（BadBoy Browser，昵称"坏孩子浏览器"）是一个开源的 AI 浏览器自动化工具，它将你正在使用的真实 Chrome 浏览器变成 AI Agent 的 API 入口，直接复用已登录的 Twitter、GitHub、知乎、B站等账号状态，彻底告别 API 密钥、爬虫脚本和无头浏览器。

指标	数值
GitHub 地址	https://github.com/epiral/bb-browser
适配器仓库	https://github.com/epiral/bb-sites
Stars	5000+
支持平台	36 个
可用命令	103 条
登录态	使用你自己的（零配置）
协议	开源

一、为什么需要 bb-browser？

1.1 传统方案的痛点

做过网页自动化、AI Agent 开发的人，几乎都经历过以下困境：

痛点	具体表现
无 API 可用	知乎、小红书、B站、微博……99% 的网站压根不提供公开 API
反爬机制	Selenium/Playwright 无头浏览器一启动就被识别拦截
登录态难维护	手动提取 Cookie，网站频繁更新鉴权逻辑，脚本说崩就崩
API 限制	GitHub REST API 有频率限制，Stack Overflow 要申请 Key
Token 浪费	把整个 DOM 树丢给大模型解析，一次操作几万 Token

1.2 bb-browser 的核心思路

既然网站信任真实用户的浏览器，那就让机器直接在你的真实浏览器里工作。

它不模拟用户，它直接让 AI 成为你。通过 Chrome DevTools Protocol（CDP）接管你正在使用的、已经登录了各种账号的真实 Chrome 浏览器。网站收到的每一次请求，本质就是你本人的正常操作——从根源上解决了 99% 的问题。

二、核心优势对比

维度	Playwright / Selenium	传统爬虫 (requests)	bb-browser
浏览器	无头、隔离的仿真环境	没有浏览器	你的真实 Chrome
登录态	没有，需脚本重新登录	需手动获取并维护 Cookie	已经在了（复用现有登录态）
反爬检测	容易被识别拦截	频繁被封	对反爬系统完全透明
API 密钥	部分需要	需要逆向接口	不需要
操作方式	模拟键盘鼠标	HTTP 请求	页面 JS 上下文执行
维护成本	页面改版即失效	接口变动即失效	适配器社区维护
Token 消耗	高（整个 DOM）	中	低（结构化 JSON 输出）

三、系统架构（四层）

AI Agent（Claude Code / Cursor / Codex / 自定义脚本）
        │
        │  CLI 或 MCP (stdio)
        ▼
┌─────────────────────────────────┐
│      bb-browser CLI / MCP       │
└─────────────────────────────────┘
        │
        │  HTTP（Connect-RPC ProviderStream）
        ▼
┌─────────────────────────────────┐
│   本地守护进程 (Daemon)          │
│   默认监听 localhost:19824       │
└─────────────────────────────────┘
        │
        │  SSE / chrome.debugger (CDP 协议)
        ▼
┌─────────────────────────────────┐
│   Chrome 扩展                    │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│   用户的真实 Chrome 浏览器        │
└─────────────────────────────────┘

架构要点

• 守护进程默认绑定 localhost:19824，支持 --host 参数自定义
• 2026年3月更新中，已从 WebSocket 迁移至 Connect-RPC ProviderStream，提升连接稳定性
• 所有操作均在用户本地浏览器内执行，不经过第三方服务器
• 登录态完全保留在浏览器中，无 Cookie 泄露风险
• 支持 IPv4-only 配置（解决 macOS IPv6 兼容问题）
• 支持全接口监听（适配 Tailscale/ZeroTier 远程访问场景）

四、支持的平台与命令

4.1 平台覆盖（36 个平台，103 条命令）

类别	平台	典型命令
搜索引擎	Google、百度、Bing、DuckDuckGo、搜狗微信	search
社交媒体	Twitter/X、Reddit、微博、小红书、即刻、LinkedIn、虎扑	search、feed、thread、user、hot
新闻资讯	BBC、Reuters、36氪、今日头条、东方财富	headlines、newsflash、hot
技术开发	GitHub、StackOverflow、HackerNews、CSDN、博客园、V2EX、arXiv、npm、PyPI	search、issues、repo、thread、package
视频平台	YouTube、B站	search、transcript、popular、comments
影音娱乐	豆瓣、IMDb、起点中文网	movie、search、top250
财经股票	雪球、东方财富、Yahoo Finance	stock、hot-stock、watchlist
招聘求职	BOSS直聘	search
其他	百度网盘、闲鱼等	视适配器而定

4.2 适配器仓库

社区维护的适配器仓库：https://github.com/epiral/bb-sites

每个适配器是一个 JS 文件，封装了特定网站的操作逻辑，对开发者友好——你也可以自己编写适配器。

五、安装与配置

5.1 前置条件

• Node.js 环境（推荐 18+）
• Chrome 或 Edge 浏览器（已安装并使用中）
• npm 或 npx

5.2 全局安装（推荐）

# 安装 bb-browser
npm install -g bb-browser

# 更新适配器列表
bb-browser site update

5.3 启动 Chrome（需开启调试端口）

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

如果你已经在用 Chrome 且已登录各平台账号，直接启动守护进程即可。

5.4 启动守护进程

# 启动（保持终端不要关，这是控制浏览器的核心服务）
bb-browser daemon

# 可选：指定端口和 IP
bb-browser daemon --host 127.0.0.1 --port 19824

5.5 验证安装

# 查看当前浏览器标签页
bb-browser tab list --json

# 测试知乎热榜（需已登录知乎）
bb-browser site zhihu/hot

# 测试 B 站搜索
bb-browser site bilibili/search "bb-browser"

六、三种运行模式

模式一：CLI 直接调用

最简单的方式，终端直接执行：

# 打开网页
bb-browser open https://www.zhihu.com

# 截图
bb-browser screenshot

# 执行 JS
bb-browser eval "document.title"

# 点击元素（@3 表示第 3 个可点击元素）
bb-browser click @3

# 填表
bb-browser fill @1 "搜索内容"

模式二：Site Adapter 命令（核心用法）

# 知乎热榜
bb-browser site zhihu/hot

# 百度搜索
bb-browser site baidu/search "2026 AI 趋势"

# B 站搜索
bb-browser site bilibili/search "bb-browser 教程"

# GitHub 搜索
bb-browser site github/search "agent"

# 雪球热股（取前 5）
bb-browser site xueqiu/hot-stock 5

# 微博热搜
bb-browser site weibo/hot

# 实时股价
bb-browser site eastmoney/stock "茅台"

# 搜职位
bb-browser site boss/search "AI工程师"

# 豆瓣电影 Top250
bb-browser site douban/top250

# B站热门
bb-browser site bilibili/trending

# arXiv 搜索论文
bb-browser site arxiv/search "retrieval augmented generation"

# Twitter 搜索
bb-browser site twitter/search "RAG"

模式三：MCP 接入（给 AI Agent 用）

在 AI 工具的 MCP 配置文件中添加：

{
  "mcpServers": {
    "bb-browser": {
      "command": "npx",
      "args": ["-y", "bb-browser", "mcp"]
    }
  }
}

保存后重启 AI 工具（Claude Code / Cursor / Codex 等），AI 即可直接调用你的浏览器。

Claude Code 中注册示例：

claude mcp add bb-browser -s user -- npx -y bb-browser mcp

七、结构化输出与数据处理

7.1 JSON 输出

# 输出 JSON 格式
bb-browser site zhihu/hot --json

7.2 jq 过滤

# 只取股票名称和涨跌幅
bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'

输出示例：

{"name":"云天化","changePercent":"2.08%"}
{"name":"东芯股份","changePercent":"-7.60%"}

7.3 跨平台调研示例

# 学术维度
bb-browser site arxiv/search "retrieval augmented generation"

# 社交讨论维度
bb-browser site twitter/search "RAG"

# 开源实现维度
bb-browser site github search rag-framework

# 技术问答维度
bb-browser site stackoverflow/search "RAG implementation"

# 中文社区维度
bb-browser site zhihu/search "RAG"

# 产业动态维度
bb-browser site 36kr/newsflash

所有输出均为结构化 JSON，可直接进入下游分析流水线。

八、实际应用场景

8.1 社交数据提取

• 抓取知乎热榜、微博热搜、小红书笔记
• 获取 Twitter 某话题下的讨论线程
• 监控 Reddit 特定 subreddit 的新帖

8.2 无 API 网站操作

• 闲鱼自动填写发布草稿（绕过阿里 mtop 协议签名）
• BOSS 直聘搜索岗位并提取结构化数据
• 百度网盘文件操作

8.3 金融数据监控

• 实时股价查询（雪球、东方财富、Yahoo Finance）
• 热股排行监控
• 自选股列表管理

8.4 开发辅助

• GitHub Issue/PR 搜索与跟踪
• npm/PyPI 包信息查询
• HackerNews / V2EX 技术讨论获取
• arXiv 论文检索

8.5 内容创作辅助

• 跨平台素材收集（B站视频、豆瓣影评、YouTube 字幕）
• 竞品分析（多平台同时搜索同一关键词）
• 热点追踪（今日头条、36氪快讯）

九、与同类工具对比

维度	bb-browser	agent-browser (Vercel)	Playwright MCP
定位	复用真实浏览器登录态	AI 友好的无头浏览器	通用浏览器自动化
浏览器	你的真实 Chrome	独立 Chromium 实例	独立浏览器实例
登录态	✅ 直接复用	❌ 需重新登录	❌ 需重新登录
反爬	✅ 完全透明	⚠️ 可能被识别	⚠️ 可能被识别
输出	结构化 JSON（adapter）	Accessibility Tree	原始 DOM
接入方式	CLI + MCP	CLI + MCP	MCP
适用场景	需登录态的平台操作	通用页面交互	测试/自动化

十、安全与隐私说明

关注点	说明
数据存储	所有操作在本地执行，不经过第三方服务器
Cookie 安全	登录态保留在你的浏览器中，不会被提取或上传
网络通信	守护进程默认仅监听 localhost
权限控制	只有你主动发起的命令才会执行
开源透明	全部代码开源，可审计

⚠️ 注意事项：

• 不要在不受信任的脚本中随意调用 bb-browser eval 执行任意 JS
• 建议仅在本地开发环境使用，生产环境需额外评估
• 高频调用仍可能触发网站风控，建议合理控制频率

十一、常见问题（FAQ）

Q1：需要关闭当前 Chrome 重新打开吗？
A：如果你的 Chrome 启动时没有带 --remote-debugging-port 参数，需要重启。建议日常就带此参数启动。

Q2：支持 Edge 浏览器吗？
A：支持。Edge 同样基于 Chromium，CDP 协议兼容。

Q3：适配器不够用怎么办？
A：可以自行编写 adapter（JS 文件），提交到 bb-sites 仓库。每个 adapter 本质上就是在页面上下文中执行 JS 并返回结构化数据。

Q4：macOS 上遇到连接问题？
A：尝试 bb-browser daemon --host 127.0.0.1 强制 IPv4，解决 IPv6 兼容问题。

Q5：能远程控制吗？
A：可以。通过 --host 0.0.0.0 配合 Tailscale/ZeroTier 实现远程访问。

十二、快速上手 Checklist

• 安装 Node.js 18+
• npm install -g bb-browser
• bb-browser site update（更新适配器）
• 带调试端口启动 Chrome：--remote-debugging-port=9222
• 确保已登录目标平台（知乎、GitHub、Twitter 等）
• 启动守护进程：bb-browser daemon
• 测试：bb-browser site zhihu/hot
• （可选）配置 MCP 接入 AI 工具

十三、总结

bb-browser 的核心价值在于一个思维转换：

不再让机器去模仿人，而是让机器直接成为你。

它解决了 AI Agent 领域最棘手的问题之一——如何安全、稳定、零配置地让 AI 访问需要登录态的网站。对于以下人群尤其推荐：

• 🤖 AI Agent 开发者：让你的 Agent 真正"看见"互联网
• 📊 数据分析师：跨平台数据采集，无需维护一堆 API Key
• 🛠️ 自动化工程师：告别与反爬机制的无休止对抗
• 💡 独立开发者：快速验证产品想法，无需后端爬虫基础设施

参考链接

• 项目主页：https://github.com/epiral/bb-browser
• 适配器仓库：https://github.com/epiral/bb-sites
• 相关讨论：搜索关键词 bb-browser on V2EX / HackerNews