bb-browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# bb-browser
+
+面向 AI Agent 的浏览器自动化 CLI 工具。
+
+## 核心特性
+
+- **复用用户登录态** - 运行在用户的浏览器中，自动复用已登录的网站（Gmail, Twitter, 内部系统等）
+- **AI Agent 友好** - 简洁的 CLI 接口，支持 JSON 输出，Ref 系统方便元素引用
+- **反爬绕过** - 使用 chrome.debugger API，避免 Playwright 等工具的自动化指纹检测
+
+## 架构
+
+```
+AI Agent (Claude, GPT, etc.)
+       │ CLI 命令
+       ▼
+bb-browser CLI ──HTTP──▶ Daemon ──SSE──▶ Chrome Extension
+                                              │
+                                              ▼ chrome.debugger (CDP)
+                                         用户浏览器
+                                    (已登录的网站、Cookies)
+```
+
+## 安装
+
+### 方式 1：npm 安装（推荐）
+
+```bash
+npm install -g bb-browser
+```
+
+### 方式 2：从源码构建
+
+```bash
+git clone https://github.com/yan5xu/bb-browser.git
+cd bb-browser
+pnpm install
+pnpm build
+```
+
+### 加载 Chrome 扩展
+
+**必须步骤**：CLI 需要配合 Chrome 扩展使用。
+
+1. 打开 Chrome，访问 `chrome://extensions/`
+2. 开启「开发者模式」（右上角开关）
+3. 点击「加载已解压的扩展程序」
+4. 选择扩展目录：
+   - npm 安装：`node_modules/bb-browser/extension/`
+   - 源码构建：`packages/extension/dist/`
+5. 确认扩展已启用
+
+## 使用
+
+### 1. 启动 Daemon
+
+```bash
+# 前台启动（查看日志）
+bb-browser daemon
+
+# 或使用别名
+bb-browser start
+```
+
+### 2. 基本操作
+
+```bash
+# 打开网页
+bb-browser open https://example.com
+
+# 获取页面快照（可交互元素）
+bb-browser snapshot -i
+
+# 输出示例：
+# - link "Learn more" [ref=0]
+# - button "Submit" [ref=1]
+# - textbox "Search" [ref=2]
+
+# 点击元素
+bb-browser click @0
+
+# 填充输入框
+bb-browser fill @2 "search query"
+
+# 按键
+bb-browser press Enter
+```
+
+### 3. 完整命令列表
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `open <url>` | 打开 URL | `bb-browser open https://x.com` |
+| `snapshot` | 获取页面快照 | `bb-browser snapshot -i` |
+| `click <ref>` | 点击元素 | `bb-browser click @5` |
+| `hover <ref>` | 悬停元素 | `bb-browser hover @3` |
+| `fill <ref> <text>` | 填充输入框（清空后填入） | `bb-browser fill @2 "hello"` |
+| `type <ref> <text>` | 逐字符输入（追加） | `bb-browser type @2 " world"` |
+| `check <ref>` | 勾选复选框 | `bb-browser check @7` |
+| `uncheck <ref>` | 取消勾选 | `bb-browser uncheck @7` |
+| `select <ref> <val>` | 下拉框选择 | `bb-browser select @4 "option1"` |
+| `eval "<js>"` | 执行 JavaScript | `bb-browser eval "document.title"` |
+| `get text <ref>` | 获取元素文本 | `bb-browser get text @5` |
+| `get url` | 获取当前 URL | `bb-browser get url` |
+| `get title` | 获取页面标题 | `bb-browser get title` |
+| `screenshot [path]` | 截图 | `bb-browser screenshot ./shot.png` |
+| `wait <ms\|@ref>` | 等待时间或元素 | `bb-browser wait 2000` |
+| `press <key>` | 按键 | `bb-browser press Enter` |
+| `scroll <dir> [px]` | 滚动 | `bb-browser scroll down 500` |
+| `back` | 后退 | `bb-browser back` |
+| `forward` | 前进 | `bb-browser forward` |
+| `refresh` | 刷新 | `bb-browser refresh` |
+| `close` | 关闭标签页 | `bb-browser close` |
+
+### 4. 标签页管理
+
+```bash
+# 列出所有标签页
+bb-browser tab
+
+# 新建标签页
+bb-browser tab new https://google.com
+
+# 切换到第 2 个标签页
+bb-browser tab 2
+
+# 关闭当前标签页
+bb-browser tab close
+```
+
+### 5. iframe 支持
+
+```bash
+# 切换到 iframe（通过选择器）
+bb-browser frame "#iframe-id"
+bb-browser frame "[name='content']"
+
+# 返回主 frame
+bb-browser frame main
+```
+
+### 6. 对话框处理
+
+```bash
+# 接受 alert/confirm
+bb-browser dialog accept
+
+# 接受 prompt 并输入文本
+bb-browser dialog accept "input text"
+
+# 拒绝对话框
+bb-browser dialog dismiss
+```
+
+### 7. 网络监控
+
+```bash
+# 查看网络请求
+bb-browser network requests
+
+# 按关键词过滤
+bb-browser network requests api
+
+# 拦截并阻止请求
+bb-browser network route "*ads*" --abort
+
+# Mock 响应
+bb-browser network route "/api/user" --body '{"name":"test"}'
+
+# 移除拦截规则
+bb-browser network unroute
+
+# 清空请求记录
+bb-browser network clear
+```
+
+### 8. 调试
+
+```bash
+# 查看控制台消息
+bb-browser console
+
+# 清空控制台
+bb-browser console --clear
+
+# 查看 JS 错误
+bb-browser errors
+
+# 清空错误记录
+bb-browser errors --clear
+```
+
+### 9. JSON 输出
+
+所有命令支持 `--json` 参数，方便程序解析：
+
+```bash
+bb-browser snapshot -i --json
+# {"success":true,"data":{"snapshot":"...","refs":{...}}}
+
+bb-browser get url --json
+# {"success":true,"data":"https://example.com"}
+```
+
+## CDP 开发模式
+
+以 CDP 调试模式启动 Chrome，支持 `reload` 命令热重载扩展：
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-debug-profile
+
+# 然后加载扩展，之后可以热重载
+bb-browser reload
+```
+
+## 项目结构
+
+```
+bb-browser/
+├── packages/
+│   ├── cli/          # CLI 工具
+│   ├── daemon/       # HTTP Daemon（CLI 与扩展的桥梁）
+│   ├── extension/    # Chrome 扩展
+│   └── shared/       # 共享类型
+└── README.md
+```
+
+## 技术栈
+
+- **CLI**: TypeScript, Commander.js
+- **Daemon**: Node.js HTTP Server, SSE
+- **Extension**: Chrome Manifest V3, chrome.debugger API
+- **构建**: pnpm, Turbo, Vite, tsup
+
+## License
+
+MIT

package/dist/chunk-KATHFDYJ.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// packages/shared/dist/index.js
+function generateId() {
+  return crypto.randomUUID();
+}
+var DAEMON_PORT = 19824;
+var DAEMON_HOST = "localhost";
+var DAEMON_BASE_URL = `http://${DAEMON_HOST}:${DAEMON_PORT}`;
+var SSE_HEARTBEAT_INTERVAL = 15e3;
+var COMMAND_TIMEOUT = 3e4;
+
+export {
+  generateId,
+  DAEMON_PORT,
+  DAEMON_BASE_URL,
+  SSE_HEARTBEAT_INTERVAL,
+  COMMAND_TIMEOUT
+};
+//# sourceMappingURL=chunk-KATHFDYJ.js.map

package/dist/chunk-KATHFDYJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../packages/shared/src/protocol.ts","../packages/shared/src/constants.ts"],"sourcesContent":["/**\n * CLI 与 Chrome Extension 之间的通信协议类型定义\n */\n\n/** 支持的操作类型 */\nexport type ActionType =\n  | \"open\"\n  | \"snapshot\"\n  | \"click\"\n  | \"hover\"\n  | \"fill\"\n  | \"type\"\n  | \"check\"\n  | \"uncheck\"\n  | \"select\"\n  | \"get\"\n  | \"screenshot\"\n  | \"close\"\n  | \"wait\"\n  | \"press\"\n  | \"scroll\"\n  | \"back\"\n  | \"forward\"\n  | \"refresh\"\n  | \"eval\"\n  | \"tab_list\"\n  | \"tab_new\"\n  | \"tab_select\"\n  | \"tab_close\"\n  | \"frame\"\n  | \"frame_main\"\n  | \"dialog\"\n  | \"network\"\n  | \"console\"\n  | \"errors\"\n  | \"trace\";\n\n/** 请求类型 */\nexport interface Request {\n  /** 请求唯一标识 */\n  id: string;\n  /** 操作类型 */\n  action: ActionType;\n  /** 目标 URL（open 操作时必填） */\n  url?: string;\n  /** 元素引用（click, fill, get 操作时使用） */\n  ref?: string;\n  /** 输入文本（fill 操作时使用） */\n  text?: string;\n  /** 获取属性类型（get 操作时使用） */\n  attribute?: string;\n  /** 截图保存路径（screenshot 操作时使用） */\n  path?: string;\n  /** 是否只输出可交互元素（snapshot 命令使用） */\n  interactive?: boolean;\n  /** JavaScript 代码（eval 命令使用） */\n  script?: string;\n  /** 选项值（select 命令使用） */\n  value?: string;\n  /** 标签页索引（tab_select, tab_close 命令使用） */\n  index?: number;\n  /** CSS 选择器（frame 命令使用，定位 iframe） */\n  selector?: string;\n  /** dialog 响应类型（dialog 命令使用） */\n  dialogResponse?: \"accept\" | \"dismiss\";\n  /** prompt 对话框的输入文本（dialog accept 时可选） */\n  promptText?: string;\n  /** network 子命令：requests, route, unroute, clear */\n  networkCommand?: \"requests\" | \"route\" | \"unroute\" | \"clear\";\n  /** network route 选项 */\n  routeOptions?: {\n    abort?: boolean;\n    body?: string;\n    status?: number;\n    headers?: Record<string, string>;\n  };\n  /** 过滤字符串（network requests, console 使用） */\n  filter?: string;\n  /** console 子命令：get, clear */\n  consoleCommand?: \"get\" | \"clear\";\n  /** errors 子命令：get, clear */\n  errorsCommand?: \"get\" | \"clear\";\n  /** trace 子命令：start, stop, status */\n  traceCommand?: \"start\" | \"stop\" | \"status\";\n}\n\n/** 元素引用信息 */\nexport interface RefInfo {\n  /** 元素的 XPath */\n  xpath: string;\n  /** 可访问性角色 */\n  role: string;\n  /** 可访问名称 */\n  name?: string;\n  /** 标签名 */\n  tagName: string;\n}\n\n/** 标签页信息 */\nexport interface TabInfo {\n  /** 标签页在窗口中的索引（0-based） */\n  index: number;\n  /** 标签页 URL */\n  url: string;\n  /** 标签页标题 */\n  title: string;\n  /** 是否是当前活动标签页 */\n  active: boolean;\n  /** 标签页 ID */\n  tabId: number;\n}\n\n/** Snapshot 命令返回的数据 */\nexport interface SnapshotData {\n  /** 文本格式的可访问性树 */\n  snapshot: string;\n  /** 元素引用映射，key 为 ref ID */\n  refs: Record<string, RefInfo>;\n}\n\n/** 网络请求信息 */\nexport interface NetworkRequestInfo {\n  requestId: string;\n  url: string;\n  method: string;\n  type: string;\n  timestamp: number;\n  status?: number;\n  statusText?: string;\n  failed?: boolean;\n  failureReason?: string;\n}\n\n/** 控制台消息 */\nexport interface ConsoleMessageInfo {\n  type: 'log' | 'info' | 'warn' | 'error' | 'debug';\n  text: string;\n  timestamp: number;\n  url?: string;\n  lineNumber?: number;\n}\n\n/** JS 错误信息 */\nexport interface JSErrorInfo {\n  message: string;\n  url?: string;\n  lineNumber?: number;\n  columnNumber?: number;\n  stackTrace?: string;\n  timestamp: number;\n}\n\n/** Trace 事件类型 - 录制用户操作 */\nexport interface TraceEvent {\n  /** 事件类型 */\n  type: 'click' | 'fill' | 'select' | 'check' | 'press' | 'scroll' | 'navigation';\n  /** 时间戳 */\n  timestamp: number;\n  /** 事件发生时的页面 URL */\n  url: string;\n  \n  /** 元素引用 - highlightIndex，可直接用于 @ref */\n  ref?: number;\n  /** 备用定位 - XPath */\n  xpath?: string;\n  /** CSS 选择器 */\n  cssSelector?: string;\n  \n  /** 操作参数 - fill/select 的值 */\n  value?: string;\n  /** 操作参数 - press 的按键 */\n  key?: string;\n  /** 操作参数 - scroll 方向 */\n  direction?: 'up' | 'down' | 'left' | 'right';\n  /** 操作参数 - scroll 距离 */\n  pixels?: number;\n  /** 操作参数 - check/uncheck 状态 */\n  checked?: boolean;\n  \n  /** 语义信息 - 元素角色 */\n  elementRole?: string;\n  /** 语义信息 - 元素名称 */\n  elementName?: string;\n  /** 语义信息 - 元素标签 */\n  elementTag?: string;\n}\n\n/** Trace 录制状态 */\nexport interface TraceStatus {\n  /** 是否正在录制 */\n  recording: boolean;\n  /** 已录制事件数量 */\n  eventCount: number;\n  /** 录制的标签页 ID */\n  tabId?: number;\n}\n\n/** 响应数据 */\nexport interface ResponseData {\n  /** 页面标题 */\n  title?: string;\n  /** 当前 URL */\n  url?: string;\n  /** Tab ID */\n  tabId?: number;\n  /** Snapshot 数据（snapshot 操作返回） */\n  snapshotData?: SnapshotData;\n  /** 获取的文本或属性值（get 操作返回） */\n  value?: string;\n  /** 截图路径（screenshot 操作返回） */\n  screenshotPath?: string;\n  /** eval 执行结果 */\n  result?: unknown;\n  /** 标签页列表（tab_list 命令返回） */\n  tabs?: TabInfo[];\n  /** 当前活动标签页索引（tab_list 命令返回） */\n  activeIndex?: number;\n  /** Frame 信息（frame 命令返回） */\n  frameInfo?: {\n    /** iframe 的 CSS 选择器 */\n    selector?: string;\n    /** iframe 的 name 属性 */\n    name?: string;\n    /** iframe 的 URL */\n    url?: string;\n    /** frame ID */\n    frameId?: number;\n  };\n  /** dialog 信息（dialog 命令返回） */\n  dialogInfo?: {\n    /** 对话框类型：alert, confirm, prompt, beforeunload */\n    type: string;\n    /** 对话框消息 */\n    message: string;\n    /** 是否成功处理 */\n    handled: boolean;\n  };\n  /** 网络请求列表（network requests 命令返回） */\n  networkRequests?: NetworkRequestInfo[];\n  /** 网络路由规则数量（network route/unroute 命令返回） */\n  routeCount?: number;\n  /** 控制台消息列表（console 命令返回） */\n  consoleMessages?: ConsoleMessageInfo[];\n  /** JS 错误列表（errors 命令返回） */\n  jsErrors?: JSErrorInfo[];\n  /** Trace 事件列表（trace stop 命令返回） */\n  traceEvents?: TraceEvent[];\n  /** Trace 录制状态（trace status 命令返回） */\n  traceStatus?: TraceStatus;\n}\n\n/** 响应类型 */\nexport interface Response {\n  /** 对应请求的 ID */\n  id: string;\n  /** 操作是否成功 */\n  success: boolean;\n  /** 成功时返回的数据 */\n  data?: ResponseData;\n  /** 失败时的错误信息 */\n  error?: string;\n}\n\n/** SSE 事件类型 */\nexport type SSEEventType = \"connected\" | \"heartbeat\" | \"command\";\n\n/** SSE 事件数据 */\nexport interface SSEEvent {\n  type: SSEEventType;\n  data: unknown;\n}\n\n/** Daemon 状态 */\nexport interface DaemonStatus {\n  running: boolean;\n  extensionConnected: boolean;\n  pendingRequests: number;\n  uptime: number;\n}\n\n/**\n * 生成唯一请求 ID\n * @returns UUID v4 格式的字符串\n */\nexport function generateId(): string {\n  return crypto.randomUUID();\n}\n","/**\n * bb-browser 共享常量\n */\n\n/** Daemon HTTP 服务端口 */\nexport const DAEMON_PORT = 19824;\n\n/** Daemon 主机地址 */\nexport const DAEMON_HOST = \"localhost\";\n\n/** Daemon 基础 URL */\nexport const DAEMON_BASE_URL = `http://${DAEMON_HOST}:${DAEMON_PORT}`;\n\n/** SSE 心跳间隔（毫秒） - 15秒确保 MV3 Service Worker 不休眠 */\nexport const SSE_HEARTBEAT_INTERVAL = 15000; // 15 秒\n\n/** 命令执行超时时间（毫秒） */\nexport const COMMAND_TIMEOUT = 30000; // 30 秒\n\n/** SSE 重连延迟（毫秒） */\nexport const SSE_RECONNECT_DELAY = 3000; // 3 秒\n\n/** SSE 最大重连尝试次数 */\nexport const SSE_MAX_RECONNECT_ATTEMPTS = 5;\n"],"mappings":";;;AA4RO,SAAS,aAAqB;AACnC,SAAO,OAAO,WAAW;AAC3B;ACzRO,IAAM,cAAc;AAGpB,IAAM,cAAc;AAGpB,IAAM,kBAAkB,UAAU,WAAW,IAAI,WAAW;AAG5D,IAAM,yBAAyB;AAG/B,IAAM,kBAAkB;","names":[]}