Bb Browser

bb-browser - 信息获取与浏览器自动化

核心价值

通过浏览器 + 用户登录态，可以获取：

• 公域信息：任意公开网页、搜索结果、新闻资讯
• 私域信息：内部系统、企业应用、登录后页面、个人账户数据

还可以代替用户执行浏览器操作：表单填写、按钮点击、数据提取、截图保存、批量操作。

运行在用户真实浏览器中，复用已登录的账号，不触发反爬检测。

快速开始

bb-browser open <url>        # 打开页面（新 tab）
bb-browser snapshot -i       # 获取可交互元素
bb-browser click @5          # 点击元素
bb-browser fill @3 "text"    # 填写输入框
bb-browser close             # 完成后关闭 tab

Site 系统 — 把任何网站变成命令行 API

site 系统是 bb-browser 的核心特性，通过 adapter 将网站功能 CLI 化，覆盖 36+ 平台。

# 常用命令
bb-browser site list                          # 列出所有 adapter
bb-browser site search <query>                # 搜索 adapter
bb-browser site <name> [args...]              # 运行 adapter
bb-browser site update                        # 更新社区 adapter 库

# 使用示例
bb-browser site twitter/search "Claude Code"  # 搜索推文
bb-browser site zhihu/hot                     # 知乎热榜
bb-browser site github/repo owner/repo        # 仓库信息
bb-browser site youtube/transcript <video_id> # 获取字幕
bb-browser site reddit/thread <url>           # 帖子详情
bb-browser site eastmoney/stock "茅台"         # 股票查询
bb-browser site weibo/hot                     # 微博热搜
bb-browser site arxiv/search "transformer"    # 论文搜索

adapter 自动处理 tab 管理（查找匹配域名的 tab 或新建），自动检测登录错误并提示。

详细用法和 36 平台完整列表：参见 references/site-system.md 创建自定义 adapter：参见 references/adapter-development.md

fetch — 带登录态的 curl

在浏览器上下文中执行 fetch，自动携带 Cookie 和登录态。

bb-browser fetch <url>                                    # GET 请求
bb-browser fetch <url> --method POST --body '{"k":"v"}'   # POST 请求
bb-browser fetch <url> --headers '{"Auth":"Bearer xxx"}'  # 自定义请求头
bb-browser fetch <url> --output data.json                 # 保存到文件
bb-browser fetch /api/me.json                             # 相对路径（用当前 tab 的 origin）

自动域名路由：绝对路径自动查找匹配 tab 或新建；相对路径使用当前 tab。

详细用法：参见 references/fetch-and-network.md

Tab 管理规范

操作完成后必须关闭自己打开的 tab。

# 单 tab 场景
bb-browser open https://example.com    # 打开新 tab
bb-browser snapshot -i
bb-browser click @5
bb-browser close                        # 完成后关闭

# 多 tab 场景
bb-browser open https://site-a.com     # tabId: 123
bb-browser open https://site-b.com     # tabId: 456
# ... 操作 ...
bb-browser tab close                    # 关闭当前 tab
bb-browser tab close                    # 关闭剩余 tab

# 指定 tab 操作
bb-browser open https://example.com --tab current  # 在当前 tab 打开（不新建）
bb-browser open https://example.com --tab 123      # 在指定 tabId 打开

核心工作流

1. open 打开页面 2. snapshot -i 查看可操作元素（返回 @ref） 3. 用 @ref 执行操作（click, fill, etc.） 4. 页面变化后重新 snapshot -i 5. 任务完成后 close 关闭 tab

命令速查

导航

bb-browser open <url>                # 打开 URL（新 tab）
bb-browser open <url> --tab current  # 在当前 tab 打开
bb-browser back                      # 后退
bb-browser forward                   # 前进
bb-browser refresh                   # 刷新
bb-browser close                     # 关闭当前 tab

快照

bb-browser snapshot             # 完整页面结构
bb-browser snapshot -i          # 只显示可交互元素（推荐）
bb-browser snapshot -c          # 移除空结构节点
bb-browser snapshot -d 3        # 限制树深度为 3 层
bb-browser snapshot -s ".main"  # 限定 CSS 选择器范围
bb-browser snapshot --json      # JSON 格式输出
# 选项可组合：bb-browser snapshot -i -c -d 5

元素交互

bb-browser click @5             # 点击
bb-browser hover @5             # 悬停
bb-browser fill @3 "text"       # 清空并填写
bb-browser type @3 "text"       # 追加输入（不清空）
bb-browser check @7             # 勾选复选框
bb-browser uncheck @7           # 取消勾选
bb-browser select @4 "option"   # 下拉选择
bb-browser press Enter          # 按键
bb-browser press Control+a      # 组合键
bb-browser scroll down          # 向下滚动（默认 300px）
bb-browser scroll up 500        # 向上滚动 500px

获取信息

bb-browser get text @5          # 获取元素文本
bb-browser get url              # 获取当前 URL
bb-browser get title            # 获取页面标题

Tab 管理

bb-browser tab                  # 列出所有 tab
bb-browser tab new [url]        # 新建 tab
bb-browser tab 2                # 切换到第 2 个 tab（按 index）
bb-browser tab select --id 123  # 切换到指定 tabId 的 tab
bb-browser tab close            # 关闭当前 tab
bb-browser tab close 3          # 关闭第 3 个 tab（按 index）
bb-browser tab close --id 123   # 关闭指定 tabId 的 tab

截图

bb-browser screenshot           # 截图（自动保存）
bb-browser screenshot path.png  # 截图到指定路径

等待

bb-browser wait 2000            # 等待 2 秒
bb-browser wait @5              # 等待元素出现

JavaScript

bb-browser eval "document.title"              # 执行 JS
bb-browser eval "window.scrollTo(0, 1000)"    # 滚动到指定位置

Frame 切换

bb-browser frame "#iframe-id"   # 切换到 iframe
bb-browser frame main           # 返回主 frame

对话框处理

bb-browser dialog accept        # 确认对话框
bb-browser dialog dismiss       # 取消对话框
bb-browser dialog accept "text" # 确认并输入（prompt）

网络与调试

bb-browser network requests                        # 查看网络请求
bb-browser network requests "api" --with-body       # 过滤 + 完整请求/响应体
bb-browser network route "*analytics*" --abort      # 拦截并阻止请求
bb-browser network route "*/api/user" --body '{}'   # 拦截并 mock 响应
bb-browser network unroute                          # 移除所有拦截规则
bb-browser network clear                            # 清空请求记录
bb-browser console                                  # 查看控制台消息
bb-browser console --clear                          # 清空控制台
bb-browser errors                                   # 查看 JS 错误
bb-browser errors --clear                           # 清空错误记录
bb-browser trace start                              # 开始录制用户操作
bb-browser trace stop                               # 停止录制，输出事件列表
bb-browser trace status                             # 查看录制状态

详细的 network 高级用法：参见 references/fetch-and-network.md

全局选项

--json               # 以 JSON 格式输出（所有命令通用）
--tab <tabId>        # 指定操作的标签页 ID（几乎所有命令通用）
--mcp                # 启动 MCP server（用于 Claude Code / Cursor 等 AI 工具）

Ref 使用说明

snapshot 返回的 @ref 是元素的临时标识：

@1 [button] "提交"
@2 [input type="text"] placeholder="请输入姓名"
@3 [a] "查看详情"

注意：

• 页面导航后 ref 失效，需重新 snapshot
• 动态内容加载后需重新 snapshot
• ref 格式：@1, @2, @3...

详细说明：参见 references/snapshot-refs.md

并发操作

# 并发打开多个页面（各自独立 tab）
bb-browser open https://site-a.com &
bb-browser open https://site-b.com &
bb-browser open https://site-c.com &
wait
# 每个返回独立的 tabId，互不干扰

信息提取 vs 页面操作

根据目的选择不同的方法：

提取页面内容（用 eval）

当需要提取文章、正文等长文本时，用 eval 直接获取：

# 微信公众号文章
bb-browser eval "document.querySelector('#js_content').innerText"

# 知乎回答
bb-browser eval "document.querySelector('.RichContent-inner').innerText"

# 通用：获取页面主体文本
bb-browser eval "document.body.innerText.substring(0, 5000)"

# 获取所有链接
bb-browser eval "[...document.querySelectorAll('a')].map(a => a.href).join('\n')"

有些网站 DOM 嵌套很深，snapshot 输出冗长，eval 直接提取文本更高效。

操作页面元素（用 snapshot -i）

当需要点击、填写、选择时，用 snapshot -i 获取可交互元素：

bb-browser snapshot -i
# @1 [button] "登录"
# @2 [input] placeholder="用户名"
# @3 [input type="password"]

bb-browser fill @2 "username"
bb-browser fill @3 "password"
bb-browser click @1

-i 只显示可交互元素，过滤掉大量无关内容。

MCP 集成

bb-browser 提供 MCP server，可与 Claude Code / Cursor 等 AI 工具集成：

# 启动 MCP server
bb-browser --mcp

配置示例（Claude Code / Cursor）：

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

常见任务示例

表单填写

bb-browser open https://example.com/form
bb-browser snapshot -i
bb-browser fill @1 "张三"
bb-browser fill @2 "zhangsan@example.com"
bb-browser click @3
bb-browser wait 2000
bb-browser close

信息提取

bb-browser open https://example.com/dashboard
bb-browser snapshot -i
bb-browser get text @5
bb-browser screenshot report.png
bb-browser close

批量操作

for url in "url1" "url2" "url3"; do
  bb-browser open "$url"
  bb-browser snapshot -i --json
  bb-browser close
done

深入文档

Adapter 开发指南

开发流程概览

1. 用 network 命令逆向 API 2. 用 eval 测试 fetch 是否可行 3. 编写 adapter JS 文件 4. 保存到 ~/.bb-browser/sites/ 测试 5. 提交 PR 到社区仓库

<!-- 证据来源：packages/cli/src/index.ts:601-658 guide 命令输出 -->

Step 1：逆向 API

# 清空旧记录
bb-browser network clear --tab <tabId>

# 刷新页面触发请求
bb-browser refresh --tab <tabId>

# 查看 API 请求（filter 是位置参数，不是 --filter）
bb-browser network requests "api" --with-body --json --tab <tabId>

重点关注：

• 请求 URL 和参数格式
• 认证方式（Cookie / Bearer token / CSRF token）
• 响应数据结构

Step 2：测试 fetch

# 直接在浏览器中测试 fetch（Tier 1 验证）
bb-browser eval "fetch('/api/endpoint',{credentials:'include'}).then(r=>r.json())" --tab <tabId>

根据结果判断复杂度：

• 能直接拿到数据 → Tier 1（Cookie 认证，如 Reddit/GitHub/V2EX）
• 需要额外请求头 → Tier 2（如 Twitter：Bearer + CSRF token）
• 需要请求签名或注入 → Tier 3（如小红书：Pinia store / Webpack 模块）

Step 3：编写 Adapter

元数据格式（/* @meta */ 块）

<!-- 证据来源：site.ts:56-118 parseSiteMeta() -->

/* @meta
{
  "name": "platform/command",
  "description": "功能描述",
  "domain": "www.example.com",
  "args": {
    "query": {"required": true, "description": "搜索关键词"},
    "count": {"required": false, "description": "返回数量"}
  },
  "capabilities": ["search"],
  "readOnly": true,
  "example": "bb-browser site platform/command value"
}
*/
async function(args) {
  // adapter 实现
}

元数据字段说明

旧格式兼容

也支持 // @tag value 注释格式（向后兼容）：

// @name platform/command
// @description 功能描述
// @domain www.example.com
// @args query,filter
// @example bb-browser site platform/command value

<!-- 证据来源：site.ts:100-117 旧格式解析 -->

三层复杂度示例

Tier 1：Cookie 认证（~1 分钟）

直接 fetch，credentials: 'include' 自动带 Cookie。

/* @meta
{
  "name": "reddit/search",
  "description": "Search Reddit posts",
  "domain": "www.reddit.com",
  "args": {"query": {"required": true, "description": "Search query"}},
  "readOnly": true,
  "example": "bb-browser site reddit/search 'local LLM'"
}
*/
async function(args) {
  if (!args.query) return {error: 'Missing argument: query'};
  const resp = await fetch(
    '/search.json?q=' + encodeURIComponent(args.query) + '&limit=10',
    {credentials: 'include'}
  );
  if (!resp.ok) return {error: 'HTTP ' + resp.status, hint: 'Not logged in?'};
  const data = await resp.json();
  return data.data.children.map(c => ({
    title: c.data.title,
    url: 'https://www.reddit.com' + c.data.permalink,
    score: c.data.score,
    subreddit: c.data.subreddit
  }));
}

Tier 2：Bearer + CSRF token（~3 分钟）

需要从页面提取 token 构造请求头。

/* @meta
{
  "name": "twitter/search",
  "description": "Search tweets",
  "domain": "twitter.com",
  "args": {"query": {"required": true, "description": "Search query"}},
  "readOnly": true
}
*/
async function(args) {
  // 从 cookie 提取 CSRF token
  const csrf = document.cookie.match(/ct0=([^;]+)/)?.[1];
  if (!csrf) return {error: 'CSRF token not found', hint: 'Not logged in?'};

  // 构造带认证的请求
  const resp = await fetch('/i/api/2/search/adaptive.json?q=' + encodeURIComponent(args.query), {
    credentials: 'include',
    headers: {
      'authorization': 'Bearer AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs...',
      'x-csrf-token': csrf
    }
  });
  if (!resp.ok) return {error: 'HTTP ' + resp.status};
  return await resp.json();
}

Tier 3：Webpack 注入 / Pinia store（~10 分钟）

需要访问页面内部状态或调用内部模块。

抗变更模式

网站频繁更新前端代码（CSS class、webpack module ID、GraphQL queryId 等）。以下是经过验证的抗变更模式。

模式 1：结构化 DOM 提取（替代 CSS class 选择器）

问题：网站经常修改 CSS class 名（如 Google 从 div.g 改为 div.MjjYud），导致 adapter 失效。

方案：用语义化 HTML 元素（h3、a、article）定位内容，不依赖任何 class name。

// ❌ 脆弱：依赖 CSS class（Google 已多次更改）
const items = doc.querySelectorAll('div.g');

// ✅ 稳健：用语义元素定位
const h3s = doc.querySelectorAll('h3');
for (const h3 of h3s) {
  const a = h3.closest('a');
  if (!a) continue;
  const link = a.getAttribute('href');
  if (!link || !link.startsWith('http')) continue;
  const title = h3.textContent.trim();

  // 向上查找结果容器（找到有多个 h3 兄弟的层级停止）
  let container = a;
  while (container.parentElement && container.parentElement.tagName !== 'BODY') {
    const sibs = [...container.parentElement.children];
    if (sibs.filter(s => s.querySelector('h3')).length > 1) break;
    container = container.parentElement;
  }

  // 在容器内、链接外查找摘要
  const linkBlock = a.closest('div') || a;
  let snippet = '';
  for (const sp of container.querySelectorAll('span')) {
    if (linkBlock.contains(sp)) continue;
    const t = sp.textContent.trim();
    if (t.length > 30 && t !== title) { snippet = t; break; }
  }
  results.push({ title, url: link, snippet });
}

适用于：Google、Bing、DuckDuckGo、HackerNews 等搜索/列表页面。

模式 2：Webpack 模块动态发现（替代硬编码 module ID）

问题：SPA 网站（如 Twitter/X）的 webpack module ID 在每次部署时都会变化，硬编码 ID 很快失效。

方案：通过搜索模块源码中的稳定签名来动态查找模块。

// 第一步：获取 webpack require 函数
let __webpack_require__;
const chunkId = '__bb_' + Date.now();
window.webpackChunk_twitter_responsive_web.push(
  [[chunkId], {}, (req) => { __webpack_require__ = req; }]
);

// 第二步：按源码签名查找模块（不依赖 module ID）
// 示例：查找 Transaction ID 生成器
let genTxId;
for (const id of Object.keys(__webpack_require__.m)) {
  const src = __webpack_require__.m[id].toString();
  // 用模块源码中稳定的字符串特征来匹配
  if (src.includes('jf.x.com') && src.includes('jJ:')) {
    genTxId = __webpack_require__(id).jJ;
    break;
  }
}
if (!genTxId) return {
  error: 'Cannot find transaction ID generator',
  hint: 'Twitter webpack structure may have changed.'
};

// 第三步：按 operationName 查找 GraphQL queryId
let queryId;
for (const id of Object.keys(__webpack_require__.m)) {
  const src = __webpack_require__.m[id].toString();
  const m = src.match(/queryId:"([^"]+)",operationName:"CreateTweet"/);
  if (m) { queryId = m[1]; break; }
}
if (!queryId) return {
  error: 'Cannot find CreateTweet queryId',
  hint: 'Twitter GraphQL schema may have changed.'
};

选择签名的原则：

• 选择业务语义字符串而非技术细节（jf.x.com 比变量名稳定）
• 选择多个特征组合匹配（includes('A') && includes('B')）
• 选择export 名匹配（jJ: 是 minified 的 export key，比函数体稳定）
• 对于 GraphQL：operationName 几乎不变，queryId 会变 → 用前者查后者

适用于：Twitter/X、小红书、抖音等 SPA 应用。

模式 3：Vue/React 内部状态访问

// Vue 3 + Pinia（如小红号）
const app = document.querySelector('#app').__vue_app__;
const store = app.config.globalProperties.$pinia._s.get('user');

// React（如 Reddit new）
const fiber = document.querySelector('#App')._reactRootContainer?._internalRoot?.current;

注意：内部状态访问比 API 调用更脆弱，优先使用 API 逆向。

Step 4：测试

# 保存到私有目录
# 文件路径：~/.bb-browser/sites/platform/command.js

# 测试运行
bb-browser site platform/command "test query" --json

# 验证输出格式
bb-browser site platform/command "test query"

Step 5：贡献社区

# 方式 A：使用 gh CLI
git clone https://github.com/epiral/bb-sites && cd bb-sites
git checkout -b feat-platform
# 添加 adapter 文件
git push -u origin feat-platform
gh pr create --repo epiral/bb-sites

# 方式 B：使用 bb-browser 自身
bb-browser site github/fork epiral/bb-sites
git clone https://github.com/YOUR_USER/bb-sites && cd bb-sites
git checkout -b feat-platform
# 添加 adapter 文件
git push -u origin feat-platform
bb-browser site github/pr-create epiral/bb-sites --title "feat(platform): add adapters" --head "YOUR_USER:feat-platform"

错误处理规范

adapter 返回错误时，使用统一格式：

// 参数缺失
return {error: 'Missing argument: query'};

// HTTP 错误 + 登录提示
return {error: 'HTTP 401', hint: 'Not logged in?'};

// 自定义错误
return {error: 'Rate limited', hint: 'Try again in 60 seconds'};

系统会自动检测 401/403/unauthorized/login 等关键词，生成登录提示。

<!-- 证据来源：site.ts:406-427 错误检测逻辑 -->

报告 Adapter Bug

# 通过 gh CLI
gh issue create --repo epiral/bb-sites --title "[adapter-name] 描述"

# 通过 bb-browser
bb-browser site github/issue-create epiral/bb-sites --title "[adapter-name] 描述"

Fetch 与 Network 高级功能

fetch 命令 — 带登录态的 curl

本质：在浏览器上下文中执行 fetch()，自动携带 Cookie 和登录态。

<!-- 证据来源：packages/cli/src/commands/fetch.ts 注释 "curl，但带浏览器登录态" -->

基本用法

# GET 请求（绝对路径）
bb-browser fetch https://www.reddit.com/api/me.json

# GET 请求（相对路径，使用当前 tab 的 origin）
bb-browser fetch /api/me.json

# POST 请求
bb-browser fetch https://api.example.com/data --method POST --body '{"key":"value"}'

# 自定义请求头
bb-browser fetch https://api.example.com/data --headers '{"Authorization":"Bearer token"}'

# 保存到文件
bb-browser fetch https://api.example.com/data --output response.json

# JSON 格式输出
bb-browser fetch https://www.reddit.com/api/me.json --json

完整选项

<!-- 证据来源：fetch.ts:18-25 FetchOptions 接口，--tab 由 index.ts:215-218 全局解析 -->

自动域名路由机制

fetch 命令会自动处理 tab 匹配：

1. 相对路径（如 /api/me.json）：使用当前活动 tab 的 origin 2. 绝对路径（如 https://www.reddit.com/...）：

• 先查找已打开的匹配域名 tab
• 没有则自动打开新 tab 并等待 3 秒
• 在匹配的 tab 上下文中执行 fetch

<!-- 证据来源：fetch.ts:42-62 ensureTabForOrigin()，fetch.ts:123-139 路由逻辑 -->

响应处理

• JSON 响应自动解析为对象
• 非 JSON 响应返回文本
• --output 时自动格式化写入文件

<!-- 证据来源：fetch.ts:84-106 buildFetchScript() 中的 content-type 判断 -->

典型场景

# 检查登录状态
bb-browser fetch https://www.reddit.com/api/me.json

# 调用内部 API
bb-browser fetch https://internal.company.com/api/dashboard --json

# 提交表单数据
bb-browser fetch https://api.example.com/submit \
  --method POST \
  --body '{"name":"test","value":123}' \
  --headers '{"Content-Type":"application/json"}'

# 下载数据到文件
bb-browser fetch https://api.example.com/export.csv --output data.csv

---

network 命令 — 网络监控与拦截

<!-- 证据来源：packages/cli/src/commands/network.ts -->

子命令一览

# 查看网络请求
bb-browser network requests [filter] [--with-body] [--json]

# 拦截请求（阻止）
bb-browser network route <url> --abort

# 拦截请求（mock 响应）
bb-browser network route <url> --body '{"mock":"data"}'

# 移除指定拦截规则
bb-browser network unroute <url>

# 移除所有拦截规则
bb-browser network unroute

# 清空请求记录
bb-browser network clear

network requests 详解

# 查看所有请求
bb-browser network requests

# 按关键词过滤（匹配 URL）
bb-browser network requests "api"

# 包含完整请求/响应体
bb-browser network requests --with-body

# 组合使用
bb-browser network requests "api" --with-body --json

输出格式：

GET https://api.example.com/data
  类型: fetch, 状态: 200 OK
  请求头: 5, 响应头: 8        # --with-body 时显示
  请求体: {"query":"test"}    # --with-body 时显示
  响应体: {"result":[...]}    # --with-body 时显示

<!-- 证据来源：network.ts:46-77 requests 输出逻辑 -->

network route 详解

拦截匹配 URL 的请求：

# 阻止广告/追踪请求
bb-browser network route "*analytics*" --abort

# Mock API 响应（用于测试）
bb-browser network route "*/api/user" --body '{"name":"test","role":"admin"}'

# 添加多条规则
bb-browser network route "*tracker*" --abort
bb-browser network route "*/api/config" --body '{"feature_flag":true}'

<!-- 证据来源：network.ts:79-92 route 输出逻辑 -->

network unroute

# 移除指定规则
bb-browser network unroute "*analytics*"

# 移除所有规则
bb-browser network unroute

<!-- 证据来源：network.ts:94-101 unroute 输出逻辑 -->

network clear

# 清空请求记录（重新开始监控）
bb-browser network clear

<!-- 证据来源：network.ts:103-106 clear 输出逻辑 -->

API 逆向工程工作流

这是 fetch + network 最强大的组合用法，用于发现网站内部 API：

# 1. 清空旧记录
bb-browser network clear

# 2. 刷新页面触发请求
bb-browser refresh

# 3. 查看 API 请求（过滤 + 完整体）
bb-browser network requests "api" --with-body --json

# 4. 找到目标 API 后，用 fetch 测试
bb-browser fetch /api/discovered-endpoint --json

# 5. 确认可行后，编写 site adapter
# 参见 adapter-development.md

全局 --tab 选项

所有 network 子命令都支持 --tab <tabId>，指定监控哪个 tab 的网络活动：

bb-browser network requests --tab 123
bb-browser network route "*api*" --abort --tab 456
bb-browser network clear --tab 123

Site 系统 — 把任何网站变成命令行 API

核心概念

Site 系统通过 adapter（适配器）将网站功能 CLI 化。每个 adapter 是一个 JS 文件，在用户真实浏览器中执行，复用登录态，返回结构化 JSON。

<!-- 证据来源：packages/cli/src/commands/site.ts -->

命令速查

# 列出所有可用 adapter（按平台分组）
bb-browser site list

# 搜索 adapter（模糊匹配名称、描述、域名）
bb-browser site search <query>

# 运行 adapter（简写，推荐）
bb-browser site <name> [args...]

# 运行 adapter（完整写法）
bb-browser site run <name> [args...]

# 更新社区 adapter 库（从 github.com/epiral/bb-sites 拉取）
bb-browser site update

# 查看 adapter 开发指南
bb-browser guide

参数传递

支持两种格式混合使用：

# 位置参数（按 adapter 定义的参数顺序）
bb-browser site reddit/thread https://www.reddit.com/r/LocalLLaMA/comments/...

# 命名参数（--flag value 格式）
bb-browser site github/pr-create epiral/bb-sites --title "feat: ..." --head "user:branch"

# 混合使用
bb-browser site twitter/search "AI agent" --count 20

<!-- 证据来源：site.ts:290-314 参数解析逻辑 -->

Adapter 目录与优先级

~/.bb-browser/
├── sites/              # 私有 adapter（优先级高，覆盖同名社区 adapter）
│   └── platform/
│       └── command.js
└── bb-sites/           # 社区 adapter（通过 bb-browser site update 拉取）
    └── platform/
        └── command.js

私有 adapter 优先于社区同名 adapter。

<!-- 证据来源：site.ts:24-26 目录常量，site.ts:148-157 getAllSites() 合并逻辑 -->

自动 Tab 管理

运行 adapter 时，系统自动处理 tab：

1. 如果指定了 --tab <tabId>，直接使用该 tab 2. 否则，根据 adapter 的 domain 字段查找已打开的匹配 tab 3. 如果没有匹配的 tab，自动打开新 tab 并等待 3 秒加载

域名匹配规则：精确匹配或子域名匹配（如 x.com 匹配 api.x.com）。

<!-- 证据来源：site.ts:162-169 matchTabOrigin()，site.ts:342-368 tab 查找逻辑 -->

错误处理与登录提示

adapter 返回 {error: "...", hint: "..."} 时，系统自动检测登录相关错误（匹配 401|403|unauthorized|forbidden|not.?logged|login.?required|sign.?in|auth），并提示用户先在浏览器中登录。

# 错误示例
[error] site twitter/search: HTTP 401
  Hint: Please log in to https://twitter.com in your browser first, then retry.

<!-- 证据来源：site.ts:406-427 错误处理逻辑 -->

36 平台完整列表

<!-- 证据来源：README.md "36 platforms, 103 commands"，具体 adapter 数量以 bb-browser site list 实际输出为准 -->

搜索引擎

社交媒体

新闻资讯

技术开发

视频平台

影音娱乐

财经股票

求职招聘

知识百科

消费购物

实用工具

常用场景示例

信息检索

# 搜索技术话题
bb-browser site twitter/search "Claude Code"
bb-browser site reddit/search "local LLM"
bb-browser site hackernews/top

# 查看热榜
bb-browser site zhihu/hot
bb-browser site weibo/hot
bb-browser site v2ex/hot

# 查询股票
bb-browser site eastmoney/stock "茅台"

开发辅助

# GitHub 操作
bb-browser site github/repo anthropics/claude-code
bb-browser site github/issues owner/repo

# 查包信息
bb-browser site npm/package bb-browser
bb-browser site pypi/package requests

# 搜索技术问题
bb-browser site stackoverflow/search "async await error handling"

内容获取

# 获取 YouTube 字幕
bb-browser site youtube/transcript dQw4w9WgXcQ

# 获取 Reddit 帖子完整内容
bb-browser site reddit/thread https://www.reddit.com/r/LocalLLaMA/comments/...

# 论文搜索
bb-browser site arxiv/search "transformer attention mechanism"

与 --json 配合

所有 site 命令都支持 --json 输出结构化数据：

bb-browser site zhihu/hot --json
bb-browser site twitter/search "AI" --json

更多信息

• 创建自定义 adapter：参见 adapter-development.md
• 社区 adapter 仓库：https://github.com/epiral/bb-sites

Snapshot + Refs 工作流

bb-browser 使用紧凑的元素引用（ref），大幅减少 AI Agent 的上下文消耗。

工作原理

传统方式的问题

完整 DOM/HTML 发送给 AI → AI 解析 → 生成 CSS 选择器 → 执行操作
每次交互 ~3000-5000 tokens

bb-browser 的方案

紧凑快照 → 分配 @ref → 直接用 ref 操作
每次交互 ~200-400 tokens

Snapshot 命令

# 完整快照（显示页面结构）
bb-browser snapshot

# 只显示可交互元素（推荐）
bb-browser snapshot -i

# JSON 格式输出
bb-browser snapshot -i --json

快照输出格式

页面: Example Site - 首页
URL: https://example.com

@1 [header]
  @2 [nav]
    @3 [a] "首页"
    @4 [a] "产品"
    @5 [a] "关于"
  @6 [button] "登录"

@7 [main]
  @8 [h1] "欢迎"
  @9 [form]
    @10 [input type="email"] placeholder="邮箱"
    @11 [input type="password"] placeholder="密码"
    @12 [button type="submit"] "登录"

@13 [footer]
  @14 [a] "隐私政策"

使用 Ref

有了 ref 后直接操作：

# 点击登录按钮
bb-browser click @6

# 填写邮箱
bb-browser fill @10 "user@example.com"

# 填写密码
bb-browser fill @11 "password123"

# 提交表单
bb-browser click @12

Ref 生命周期

重要：页面变化后 ref 会失效！

# 获取初始快照
bb-browser snapshot -i
# @1 [button] "下一页"

# 点击触发页面变化
bb-browser click @1

# 必须重新获取快照！
bb-browser snapshot -i
# @1 [h1] "第二页"  ← 现在是不同的元素

Ref 失效的场景

1. 页面导航：点击链接、表单提交后跳转 2. 动态加载：AJAX 加载新内容 3. DOM 变化：JavaScript 修改页面结构 4. 弹窗/下拉：打开模态框、展开菜单

最佳实践

1. 操作前先 Snapshot

# 正确
bb-browser open https://example.com
bb-browser snapshot -i          # 先获取 ref
bb-browser click @1             # 再使用

# 错误
bb-browser open https://example.com
bb-browser click @1             # ref 不存在！

2. 导航后重新 Snapshot

bb-browser click @5             # 导航到新页面
bb-browser snapshot -i          # 获取新页面的 ref
bb-browser click @1             # 使用新的 ref

3. 动态变化后重新 Snapshot

bb-browser click @1             # 打开下拉菜单
bb-browser snapshot -i          # 获取菜单项的 ref
bb-browser click @7             # 选择菜单项

4. 等待加载完成

bb-browser click @3             # 触发 AJAX 加载
bb-browser wait 1000            # 等待加载
bb-browser snapshot -i          # 获取新内容的 ref

Ref 格式说明

@1 [tag type="value"] "文本内容" placeholder="提示"
│   │   │             │          │
│   │   │             │          └─ 其他属性
│   │   │             └─ 可见文本
│   │   └─ 关键属性
│   └─ HTML 标签
└─ 唯一 ref ID

常见模式

@1 [button] "提交"                    # 按钮
@2 [input type="email"]               # 邮箱输入框
@3 [input type="password"]            # 密码输入框
@4 [a href="/page"] "链接文字"         # 链接
@5 [select]                           # 下拉框
@6 [textarea] placeholder="请输入"     # 文本域
@7 [checkbox] checked                 # 已勾选的复选框
@8 [radio] selected                   # 已选中的单选框

常见问题

"Ref not found" 错误

页面已变化，ref 失效了：

# 重新获取快照
bb-browser snapshot -i

元素不在快照中

可能需要滚动或等待：

# 滚动到底部
bb-browser scroll down
bb-browser snapshot -i

# 或等待动态内容
bb-browser wait 2000
bb-browser snapshot -i

快照太长

使用 -i 只显示可交互元素：

# 完整快照可能很长
bb-browser snapshot

# 只显示可交互元素（推荐）
bb-browser snapshot -i

需要操作不可交互元素

使用 eval 直接执行 JavaScript：

bb-browser eval "document.querySelector('.hidden-element').click()"

调试技巧

# 查看完整页面结构
bb-browser snapshot

# 只看可交互元素
bb-browser snapshot -i

# JSON 格式便于解析
bb-browser snapshot -i --json

# 获取特定元素的文本
bb-browser get text @5