diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d3569497..cce5ef6c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -17,9 +17,9 @@ Describe the problem in one or two sentences. bb-browser ... ``` -If relevant, include the exact command you ran and whether you used `--json`, `--openclaw`, or `--mcp`. +If relevant, include the exact command you ran and whether you used `--json` or `--openclaw`. -如果相关,请贴出你实际运行的完整命令,并说明是否使用了 `--json`、`--openclaw` 或 `--mcp`。 +如果相关,请贴出你实际运行的完整命令,并说明是否使用了 `--json` 或 `--openclaw`。 ## Steps To Reproduce / 复现步骤 @@ -42,11 +42,11 @@ What actually happened? ## Environment / 环境信息 - `bb-browser` version: -- Install method (`npm -g`, `npx`, local build, MCP, other): +- Install method (`npm -g`, `npx`, local build, other): - OS: - Node.js version: - Browser: -- Extension installed? (`yes` / `no`) +- Chrome CDP source (`managed Chrome`, external `BB_BROWSER_CDP_URL`, other): - OpenClaw used? (`yes` / `no`) ## Logs Or Output / 日志与输出 diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index fc515bdc..545afb48 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -38,12 +38,11 @@ Explain the user value, workflow gap, or agent use case. Check anything relevant: - [ ] CLI command -- [ ] Extension behavior - [ ] Daemon behavior - [ ] `site` adapter - [ ] OpenClaw integration +- [ ] Hub / remote agent workflow - [ ] JSON output -- [ ] MCP / agent workflow ## Alternatives Considered / 备选方案 diff --git a/PRIVACY.md b/PRIVACY.md index ae0cbf2d..99f4cd6d 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -1,29 +1,29 @@ # Privacy Policy — bb-browser -**Last updated:** 2026-03-14 +**Last updated:** 2026-06-01 ## What bb-browser does -bb-browser is a browser automation tool that lets AI agents control your Chrome browser via the Chrome DevTools Protocol (CDP). It consists of a CLI, an MCP server, a local HTTP daemon, and a Chrome extension. +bb-browser is a browser automation tool that lets AI agents control your Chrome browser via the Chrome DevTools Protocol (CDP). It consists of a CLI and a local HTTP daemon. In Hub mode, the daemon can also register with Pinix Hub so remote clients can invoke the same commands. ## Data handling All communication happens **locally on your machine**: ``` -AI Agent ↔ CLI/MCP ↔ localhost:19824 (daemon) ↔ Chrome Extension +AI Agent ↔ CLI ↔ localhost:19824 (daemon) ↔ Chrome CDP ``` -**No data is sent to any external server.** There is no telemetry, no analytics, no cloud service. +In local CLI mode, no browser data is sent to any external server. There is no telemetry or analytics. In Hub mode, command requests and responses flow through the configured Hub endpoint because that mode is explicitly remote. ## What data is accessed -When you use bb-browser, the extension may access the following data **locally**: +When you use bb-browser, the daemon may access the following data: | Data type | How it's used | Stored? | |-----------|---------------|---------| -| **Tab URLs and titles** | To list and route commands to the correct tab | In memory only, cleared on extension restart | -| **Page content** | Snapshot (accessibility tree) and eval commands read page DOM | Not stored, returned to local CLI/MCP only | +| **Tab URLs and titles** | To list and route commands to the correct tab | In memory only, cleared on daemon restart | +| **Page content** | Snapshot (accessibility tree) and eval commands read page DOM | Not stored, returned to the CLI or Hub caller | | **Authentication state** | Fetch commands use the browser's existing cookies/sessions | Not accessed directly, browser handles this natively | | **User activity** | Trace feature records clicks, keystrokes, and scrolling for replay | In memory only, cleared on stop | | **Network requests** | Network monitoring captures request/response data | In memory only, bounded buffer, cleared on tab close | @@ -32,17 +32,17 @@ When you use bb-browser, the extension may access the following data **locally** - No personally identifiable information - No browsing history is recorded or persisted -- No data is transmitted to external servers +- No data is transmitted to external servers in local CLI mode - No analytics or telemetry - No cookies or credentials are extracted or stored ## Data retention -All data exists only in memory during the browser session. No data is written to disk by the extension. When the extension is unloaded or the browser is closed, all data is gone. +Browser data exists only in memory during the daemon session. When the daemon or browser is closed, in-memory tab state and event buffers are gone. ## Third parties -bb-browser does not share any data with third parties. The extension communicates exclusively with a daemon process running on localhost. +In local CLI mode, bb-browser does not share data with third parties. In Hub mode, the daemon communicates with the Hub endpoint you configured. ## Open source diff --git a/README.md b/README.md index 3706f813..92f64b15 100644 --- a/README.md +++ b/README.md @@ -60,9 +60,9 @@ bb-browser site recommend # see which adapters match your browsing habits bb-browser site zhihu/hot # go ``` -### OpenClaw (no extension needed) +### OpenClaw (no daemon needed) -If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no Chrome extension or daemon required: +If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no local daemon required: ```bash bb-browser site reddit/hot --openclaw @@ -71,19 +71,6 @@ bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePerc Skill on ClawHub: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser) -### MCP (Claude Code / Cursor) - -```json -{ - "mcpServers": { - "bb-browser": { - "command": "npx", - "args": ["-y", "bb-browser", "--mcp"] - } - } -} -``` - ## 36 platforms, 103 commands Community-driven via [bb-sites](https://github.com/epiral/bb-sites). One JS file per command. @@ -176,7 +163,7 @@ bb-browser daemon --host 0.0.0.0 # listen on all interfaces (for Tailscale ``` AI Agent (Claude Code, Codex, Cursor, etc.) - │ CLI or MCP (stdio) + │ CLI ▼ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real Browser │ @@ -187,6 +174,9 @@ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real │ console, │ │ errors) │ └─────────────┘ + +Optional Hub mode registers the daemon with Pinix Hub so remote clients can +invoke the same browser commands through the daemon. ``` ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index b118d860..2d3a2cb7 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -71,19 +71,6 @@ bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePerc ClawHub Skill: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser) -### MCP 接入(Claude Code / Cursor) - -```json -{ - "mcpServers": { - "bb-browser": { - "command": "npx", - "args": ["-y", "bb-browser", "--mcp"] - } - } -} -``` - ## 36 个平台,103 个命令 社区驱动,通过 [bb-sites](https://github.com/epiral/bb-sites) 维护。每个命令一个 JS 文件。 @@ -176,7 +163,7 @@ bb-browser daemon --host 0.0.0.0 # 监听所有网卡(用于 Tailscale / ``` AI Agent (Claude Code, Codex, Cursor 等) - │ CLI 或 MCP (stdio) + │ CLI ▼ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ 你的真实浏览器 │ @@ -187,6 +174,9 @@ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ 你的真 │ console, │ │ errors) │ └─────────────┘ + +可选 Hub 模式会把 daemon 注册到 Pinix Hub,远程客户端也可以通过 daemon +调用同一套浏览器命令。 ``` ## 许可证 diff --git a/package.json b/package.json index 7db88dce..23d56e8f 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,6 @@ "ai", "agent", "chrome", - "extension", "cli", "puppeteer", "playwright", diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.ts index 1eb993bc..a2d3c0d3 100644 --- a/packages/cli/src/commands/open.ts +++ b/packages/cli/src/commands/open.ts @@ -55,7 +55,7 @@ export async function openCommand( (request as Record).tabId = tabId; } } - // 不指定 --tab 时,tabId 为 undefined,扩展会创建新 tab + // 不指定 --tab 时,tabId 为 undefined,daemon 会创建新 tab // 发送请求 const response: Response = await sendCommand(request); diff --git a/packages/daemon/src/cdp-connection.ts b/packages/daemon/src/cdp-connection.ts index 1d1f5aec..8829569c 100644 --- a/packages/daemon/src/cdp-connection.ts +++ b/packages/daemon/src/cdp-connection.ts @@ -30,33 +30,6 @@ export interface CdpTargetInfo { url: string; } -// --------------------------------------------------------------------------- -// Stealth — hide headless/automation fingerprints -// --------------------------------------------------------------------------- - -const STEALTH_USER_AGENT = - "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.7827.22 Safari/537.36"; - -const STEALTH_UA_METADATA = { - brands: [ - { brand: "Chromium", version: "149" }, - { brand: "Google Chrome", version: "149" }, - { brand: "Not.A/Brand", version: "24" }, - ], - fullVersionList: [ - { brand: "Chromium", version: "149.0.7827.22" }, - { brand: "Google Chrome", version: "149.0.7827.22" }, - { brand: "Not.A/Brand", version: "24.0.0.0" }, - ], - platform: "macOS", - platformVersion: "10.15.7", - architecture: "x86", - bitness: "64", - model: "", - mobile: false, - wow64: false, -}; - const STEALTH_SCRIPT = ` (() => { if (window.__bbStealthApplied) return; diff --git a/packages/daemon/src/chrome.ts b/packages/daemon/src/chrome.ts index f341a74d..4bb58b5e 100644 --- a/packages/daemon/src/chrome.ts +++ b/packages/daemon/src/chrome.ts @@ -178,13 +178,11 @@ async function downloadAndExtractChrome(platform: Platform): Promise { // Try download sources in order const urls = getDownloadUrls(platform); let resp: Response | null = null; - let usedUrl = ""; for (const url of urls) { console.error(`${LOG_PREFIX} Downloading Chrome ${CHROME_VERSION} (${platform}) from ${new URL(url).host}...`); resp = await tryFetch(url); if (resp) { - usedUrl = url; break; } console.error(`${LOG_PREFIX} Download failed, trying next source...`); diff --git a/packages/daemon/src/command-dispatch.ts b/packages/daemon/src/command-dispatch.ts index 2b5751a5..324fc409 100644 --- a/packages/daemon/src/command-dispatch.ts +++ b/packages/daemon/src/command-dispatch.ts @@ -18,9 +18,8 @@ import type { TraceEntry, TraceStatus, } from "@bb-browser/shared"; -import { CdpConnection, type CdpTargetInfo } from "./cdp-connection.js"; +import { CdpConnection } from "./cdp-connection.js"; import type { TabState } from "./tab-state.js"; -import type { ActionDetail } from "./tab-state.js"; import { getAllSites, executeSiteAdapter } from "./site-adapter.js"; // --------------------------------------------------------------------------- diff --git a/packages/daemon/src/index.ts b/packages/daemon/src/index.ts index ce69df82..ce12039f 100644 --- a/packages/daemon/src/index.ts +++ b/packages/daemon/src/index.ts @@ -330,10 +330,17 @@ async function main(): Promise { // Clean up any stale daemon before starting await cleanupStaleDaemon(); - // Auto-manage Chrome headless-shell (unless --no-chrome) + // Prefer an already-available CDP endpoint (explicit port or managed port + // file). Only launch Chrome if nothing is reachable. let chromeProcess: ChildProcess | null = null; + let cdpEndpoint: { host: string; port: number } | null = null; + + try { + cdpEndpoint = await discoverCdpPort(options.cdpHost, options.cdpPort); + } catch {} - if (!options.noChrome) { + // Auto-manage Chrome headless-shell (unless --no-chrome) + if (!cdpEndpoint && !options.noChrome) { const chrome = createChromeManager(); // Ensure headless-shell binary is available (download if needed) @@ -361,23 +368,23 @@ async function main(): Promise { try { chromeProcess = chrome.launch(options.cdpPort); await chrome.waitForCdp(options.cdpHost, options.cdpPort); + cdpEndpoint = { host: options.cdpHost, port: options.cdpPort }; } catch (error) { console.error(`[Daemon] Failed to launch Chrome: ${error instanceof Error ? error.message : String(error)}`); } } else { console.error(`[Daemon] Chrome already running on port ${options.cdpPort}`); + cdpEndpoint = { host: options.cdpHost, port: options.cdpPort }; } } // Create tab state manager and CDP connection const tabManager = new TabStateManager(); - let cdpEndpoint: { host: string; port: number }; - try { - cdpEndpoint = await discoverCdpPort(options.cdpHost, options.cdpPort); - } catch (error) { + if (!cdpEndpoint) { console.error( - `[Daemon] ${error instanceof Error ? error.message : String(error)}`, + `[Daemon] Cannot connect to Chrome CDP at ${options.cdpHost}:${options.cdpPort}. ` + + `Make sure Chrome is running with --remote-debugging-port=${options.cdpPort}`, ); process.exit(1); } diff --git a/packages/shared/src/protocol.ts b/packages/shared/src/protocol.ts index cd3f63d6..096e2996 100644 --- a/packages/shared/src/protocol.ts +++ b/packages/shared/src/protocol.ts @@ -155,7 +155,7 @@ export interface TabInfo { title: string; /** 是否是当前活动标签页 */ active: boolean; - /** 标签页 ID(CDP targetId 或 extension tabId) */ + /** 标签页 ID(CDP targetId 或 daemon short ID) */ tabId: number | string; /** 短标签页 ID(daemon 模式) */ tab?: string; @@ -397,4 +397,3 @@ export interface DaemonStatus { }>; } - diff --git a/skills/bb-browser/SKILL.md b/skills/bb-browser/SKILL.md index d533588b..2eadfc32 100644 --- a/skills/bb-browser/SKILL.md +++ b/skills/bb-browser/SKILL.md @@ -222,7 +222,6 @@ bb-browser trace status # 查看录制状态 ```bash --json # 以 JSON 格式输出(所有命令通用) --tab # 指定操作的标签页 ID(几乎所有命令通用) ---mcp # 启动 MCP server(用于 Claude Code / Cursor 等 AI 工具) ``` ## Ref 使用说明 @@ -294,27 +293,6 @@ bb-browser click @1 `-i` 只显示可交互元素,过滤掉大量无关内容。 -## MCP 集成 - -bb-browser 提供 MCP server,可与 Claude Code / Cursor 等 AI 工具集成: - -```bash -# 启动 MCP server -bb-browser --mcp -``` - -配置示例(Claude Code / Cursor): -```json -{ - "mcpServers": { - "bb-browser": { - "command": "npx", - "args": ["-y", "bb-browser", "--mcp"] - } - } -} -``` - ## 常见任务示例 ### 表单填写