browser-bridge

<p align="center"> <img src="docs/banner.svg" alt="浏览器桥 - 通过AI代理驱动您真实的、已登录的Chrome浏览器" width="860"> </p> <p align="center"> <em>通过模型上下文协议，从AI代理驱动您真实的、已登录的Chrome浏览器。</em><br> _{无需无头浏览器，无需新配置文件，无需重新登录。您的代理在您已经登录的精确会话中读取和操作。} </p> <p align="center"> <img alt="版本" src="https://img.shields.io/badge/version-0.14.2-3f3f46?style=flat-square"> <img alt="工具" src="https://img.shields.io/badge/tools-63-3f3f46?style=flat-square"> <img alt="协议" src="https://img.shields.io/badge/MCP-streamable_HTTP-52525b?style=flat-square"> <img alt="浏览器" src="https://img.shields.io/badge/Chrome%2FEdge-Manifest_V3-52525b?style=flat-square"> <img alt="语言" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square"> <a href="LICENSE"><img alt="许可证" src="https://img.shields.io/badge/license-MIT-16a34a?style=flat-square"></a> <a href="CONTRIBUTING.md"><img alt="欢迎PR" src="https://img.shields.io/badge/PRs-welcome-16a34a?style=flat-square"></a> </p> 浏览器桥是一个本地的 **MCP服务器 + Manifest V3 Chrome扩展**，允许AI编码代理 - **Claude Code** 和 **OpenAI Codex CLI** - 控制您日常使用的Chrome浏览器。因为它运行在您真实的配置文件中，所以代理自动继承您的cookie、`HttpOnly`会话、单点登录和2FA状态。要求它 *"读取我的动态资讯并总结"* 或 *"捕获此页面的API流量并显示响应"* - 它可以针对实时、已验证的应用。 它包含 **63种工具**，涵盖日常浏览、DevTools级别的网络捕获、完整的一整套网络安全测试工具、**剧本**（保存的、自我修复的配方）和 **会话记录** - 记录交互到一个自包含的、离线忠实的HTML重放（全页、自定义设计的播放器，带有平滑的鼠标轨迹/点击/按键叠加层）并 **导出为高质量的MP4**。 <p align="center"> <img src="docs/replay.gif" alt="会话重放：记录的交互在自包含的FRACTURE播放器中重放 - 平滑的绿色鼠标轨迹跟随光标，点击波纹触发，按键HUD显示输入内容，带有播放/拖动时间线和速度控制" width="820"> <br> _{<em>记录会话 → 自包含的离线重放，带有平滑的鼠标轨迹/点击/按键叠加层 → 导出为高清MP4。</em>} </p> ## 目录 - [快速开始](#快速开始) - [为什么选择浏览器桥？](#为什么选择浏览器桥) - [实际演示](#实际演示) - [架构](#架构) - [功能与工具](#功能与工具) - [剧本](#剧本) - [记录](#记录) - [设置](#设置) - [安全与负责任的使用](#安全与负责任的使用) - [限制](#限制) - [路线图](#路线图) - [贡献](#贡献) - [许可证](#许可证) ## 快速开始 构建两个软件包，运行服务器，加载扩展，连接您的代理 - 大约60秒： ```bash git clone https://github.com/vitalysim/browser-bridge.git && cd browser-bridge ( cd server && npm install && npm run build ) # MCP服务器（TypeScript → dist/） ( cd extension && npm install && npm run build ) # 打包 background.js + options.js ( cd server && npm run install-service ) # 在登录时运行服务器（systemd/launchd） ``` 1. **加载扩展** - 打开 `chrome://extensions`，启用 **开发者模式**，点击 **加载解包**，选择 `extension/` 文件夹，然后打开其选项并粘贴来自 `~/.browser-bridge/token` 的令牌 → **保存并连接**。 2. **连接您的代理：** **Claude Code** ```bash claude mcp add --transport http --scope user browser-bridge \ http://127.0.0.1:8765/mcp --header "Authorization: Bearer $(cat ~/.browser-bridge/token)" ``` **OpenAI Codex CLI** - 导出令牌，以便Codex可以读取它，然后在一条命令中注册服务器： ```bash export BROWSER_BRIDGE_TOKEN="$(cat "$HOME/.browser-bridge/token")" # 添加到您的shell配置文件中 codex mcp add browser-bridge --url http://127.0.0.1:8765/mcp --bearer-token-env-var BROWSER_BRIDGE_TOKEN ``` **验证：** `curl -s http://127.0.0.1:8765/health` → `{"ok":true,"extensionConnected":true}`。完整的详细信息、自动启动选项和手动配置替代方案在 [设置](#设置) 中。 ## 为什么选择浏览器桥？ | | 浏览器桥 | 无头Playwright / Puppeteer | 原始CDP调试端口 | |---|:---:|:---:|:---:| | 使用您的 **真实登录配置文件** | ✅ | ❌（新配置文件，重新登录） | ⚠️ 在Chrome 136上默认配置文件被阻止 | | 同时适用于 **Claude Code 和 Codex** | ✅ | - | - | | 会话中 **无开放调试端口** | ✅（出站WebSocket） | n/a | ❌ 任何本地进程都可以劫持它 | | **DevTools级别** 捕获（主体，WebSocket） | ✅ | 部分 | ✅ | | 一键安装， **无需原生主机** | ✅ | ✅ | ✅ | - **一台服务器，两个客户端。** 两个代理都连接到同一个令牌认证的端点 `http://127.0.0.1:8765/mcp`。Anthropic的 *Chrome中的Claude* 仅限Claude，而OpenAI的Codex浏览器扩展仅限于桌面应用程序 - 两者都无法为Codex **CLI** 提供真正的浏览器。浏览器桥可以。 - **扩展，而不是调试端口。** Chrome 136+阻止 `--remote-debugging-port` 在您的默认配置文件上运行。而是Manifest V3扩展在该配置文件中运行 - 默认情况下无横幅，具有按需附加的 `chrome.debugger`（CDP）功能。 - **出站WebSocket，无原生消息传递主机。** 扩展程序拨打 `ws://127.0.0.1:8765/ws`；无需安装主机清单文件，WebSocket保持活动状态以保持MV3服务工作线程的活动状态。 - **仅限本地 + 令牌身份验证。** 服务器绑定 `127.0.0.1`，在MCP端点和WebSocket握手上检查承载令牌，并拒绝任何非 `chrome-extension://` 的WebSocket源。 ## 实际演示 打开Chrome浏览器并登录后，只需用自然语言向您的代理发出以下指令： ```text # 日常 列出我的打开的标签页 打开github.com，阅读我的通知并总结它们 # 截图 截取此页面的整页视网膜截图并保存到 ~/Downloads/page.png # 网络捕获 在此选项卡上启动网络捕获，重新加载它，然后向我显示JSON API响应 # 记录和导出 记录我的会话，我将点击并输入，然后停止 - 构建HTML重放和2倍速MP4 # 网络安全（仅限授权目标） 捕获 app.example.com 的身份 "A"，然后以 B 登录并捕获 "B"； 以A、B和匿名用户的身份重放发票请求，并向我显示授权矩阵 # 远程桌面/画布（例如CTF攻击盒） 截取DCV桌面的截图，点击终端，输入"id"并按Enter，然后截取输出的截图 ``` Claude Code和Codex都通过同一个端点驱动同一个实时浏览器。 ## 架构 <p align="center"> <img src="docs/architecture.svg" alt="架构 - Claude Code和Codex CLI通过可流式HTTP MCP连接到桥接服务器，桥接服务器通过出站令牌认证的WebSocket中继到Chrome MV3扩展，驱动您真实的已登录选项卡" width="560"> </p> ## 功能与工具 - **浏览与交互** - 标签页、导航、点击/填充/悬停/输入/滚动，带有**自动等待可操作性**（找到 + 可见 + 启用，自动升级为受信任的 CDP 点击，当目标被覆盖时）- 以及文件和图像上传 - 所有这些都可以**进入 iframe（包括跨源）**和**开放的 Shadow DOM** - 以及**坐标级受信任输入** (`input`) 用于 `<canvas>` 远程桌面（VNC/RDP/Amazon DCV）、游戏和绘图应用。 - **读取和检查** - 渲染的页面文本、交互式元素快照，带有稳定的引用、截图（视口 → 全页视网膜，元素剪辑，保存到磁盘），以及 **绕过严格 CSP** 的 JavaScript 评估，通过 CDP。 - **DevTools 级别捕获** - 完整的请求/响应 **主体**、响应头、`Set-Cookie`、时间戳和 **WebSocket/SSE 帧** - 具有持久的磁盘持久性，支持 **HAR/MHTML** 证据导出。 - **Web 安全工具包** - 命名 **身份**，会话内请求 **重放器**，**BOLA/IDOR/BFLA** 访问控制差异（`authz_matrix`），**Burp 风格的实时拦截**，**入侵者风格的模糊测试工具**（狙击/分叉/集群炸弹/比赛），被动头部/CORS/**秘密**分析，**JWT** 解码，**复制为 curl**。 - **会话与存储** - 读取/写入 **真正的 cookie 储存**（包括 `HttpOnly`）、`localStorage` / `sessionStorage`，以及控制台 + CSP + 异常日志。 <details open> <summary><b>浏览与交互</b></summary> | 工具 | 描述 | |---|---| | `tabs_list` · `tab_new` · `tab_activate` · `tab_close` | 管理标签页。 `tabs_list(short:true)` 仅返回 id/标题/来源/活动（无路径/查询），用于快速识别标签页，无需回显完整 URL | | `navigate` · `go_back` · `go_forward` · `wait_for` | 导航 | | `click` · `fill` · `hover` · `type` · `press_key` · `scroll` | 交互（iframe + 开放的 Shadow DOM 感知）。**自动等待**元素变为可操作（找到 + 可见 + 启用，`timeoutMs`）并在失败时返回结构化 `{notActionable, reason}`。`click` 检测覆盖的目标并**升级为受信任的 CDP 点击**（`via:"trusted"`）；`fill`/`type` 在 React 输入（原生设置器）和富编辑器（execCommand）中注册。`trusted:true` 表示真正的 CDP 输入；`withSnapshot:true` 获取新的 `snapshot` 行内 | | `input` | **坐标级受信任输入**，适用于元素选择器无法触及的目标 - `<canvas>` 远程桌面（VNC/RDP/**Amazon DCV**）、游戏、WebGL 应用。操作：`mouse_move`、`left/right/middle_click`、`double_click`、`left_mouse_down/up`、`left_click_drag`、`scroll`、`type`（到聚焦元素）、`key`（组合键，如 `ctrl+c`）。坐标为 **CSS 视口像素**（`=` screenshotPixel / dpr），`screenshot` 现返回 `dpr`。`activate:true` 前台标签页以便观察 | | `file_upload` | 通过 base64 或本地 `path` 设置文件输入（`DOM.setFileInputFiles`） | | `paste_image` | 将本地图像粘贴到富文本/可编辑字段；`trusted:true` 使用真正的 OS 剪贴板 + 真正的 Cmd/Ctrl+V，用于严格的编辑器（例如 YesWeHack），它们会忽略合成事件 | </details> <details> <summary><b>读取与检查</b></summary> | 工具 | 描述 | |---|---| | `get_page_text` | 页面的渲染文本（及其 iframe）。`includeHidden:true` 读取 `textContent` 而不是 `innerText`，捕获 `display:none`/折叠内容（例如未展开的折叠体） | | `snapshot` | 交互式元素，带有引用（+ `enabled`/`inViewport` 提示）；`deep:true` 穿透 **封闭** 的 Shadow 根。引用保存在 **off-DOM 注册表** 中，因此快照不会改变页面（引用的元素已被重新渲染，报告为这样，调用者重新快照）。深快照引用在其自己的范围内编号，以避免与普通快照引用或早期深快照中的陈旧引用混淆 | | `screenshot` | 默认情况下，可见视口（无横幅）；`fullPage` 获取整个页面，`scale` 获取视网膜，`format`/`quality`，`selector` 剪辑，`savePath` 写入文件。返回 `dpr` + CSS 视口大小（将截图像素映射到 `input` 坐标）和 `visibilityState` - 当标签页被遮挡时警告（其框架可能被限制/过时） | | `download_resource` | 通过 Chrome 自有的下载引擎将 URL 下载到磁盘 - 默认情况下最大 100MB（`maxBytes` 提升），正确的二进制处理，真正的会话 cookie，无横幅；`savePath` 重新定位到 Downloads 文件夹之外 | | `eval_js` | 在页面的主世界中评估 JavaScript（无横幅）。**自动回落到 `cdp_eval` 在严格 CSP 页面上**，其中页面内的 `eval` 被阻止（`via:"cdp-fallback"`）；`cdp:true` 强制执行，`noFallback:true` 禁用。`timeoutMs` 等待 30 秒的默认超时 | | `cdp_eval` | 通过 CDP `Runtime.evaluate` 在页面的真实主世界上下文中评估 JS - **不受 CSP `unsafe-eval` 限制**，因此它在严格 CSP 站点上运行，并到达页面的实时 JS（内存状态，框架内部，闭包，应用程序自己的函数）。使用 `chrome.debugger`（显示横幅）。`timeoutMs` 提升 30 秒的上限 | | `bridge_status` | 扩展程序是否连接？ | </details> <details> <summary><b>网络捕获</b> （chrome.debugger - 显示调试横幅）</summary> | 工具 | 描述 | |---|---| | `net_capture_start` | 开始捕获；然后导航/重载以记录加载流量。`maxEntries` 设置内存中的环（默认 500，最大 5000）；`persist:true` + `savePath` 还会**流式**每个完成的请求/WS 帧到磁盘上的 JSON-Lines 文件（持久 - 存活环上限和最多最后一批，服务工作线程崩溃；`persistBodies:true` 包括主体） | | `net_get_requests` | 请求头，`Set-Cookie`，时间戳和（按需）响应 **主体** | | `net_get_body` | 按需获取一个响应主体 | | `net_get_ws_frames` | 捕获的 WebSocket / EventSource 帧 | | `export_har` | 将标签页的捕获流量写入 **HAR 1.2** 文件（导入 Burp / DevTools / Playwright）；默认情况下包含主体 | | `debugger_detach` · `debugger_status` | 结束会话（关闭横幅）/ 检查会话 | </details> <details> <summary><b>Web 安全测试</b></summary> | 工具 | 描述 | |---|---| | `identity_capture` · `identity_list` · `identity_purge` | 快照/管理命名会话（包括 `HttpOnly`，存储，承载者） | | `replay_request` | 会话内重放器 - 重放捕获的或临时请求；覆盖任何头部或交换身份（`anon` 删除身份验证）。`viaAppClient:true` 通过 **页面的自身 `fetch`** 重放，因此应用 CSRF/身份验证拦截器适用 | | `authz_matrix` | 重放请求集并差异化 → 标记访问控制破坏（BOLA / IDOR / BFLA） | | `response_diff` | 两个响应的结构差异（状态，长度，token-Jaccard，噪声抑制） | | `intercept_start` · `intercept_pending` · `intercept_resolve` · `intercept_stop` | Burp-Proxy 风格的实时拦截（CDP Fetch）：暂停匹配的请求/响应，然后 **继续**（可选地修改 url/方法/头部/主体），**失败**（阻止），或 **满足/修改**（合成响应）。`rules` 自动应用；否则请求队列等待解决 | | `fuzz` | 入侵者风格的模糊测试工具，适用于请求模板 - 模式 **狙击手** / **分叉** / **集群炸弹** （多标记 `payloadSets`）/ **比赛** （同时发送 N 个请求进行竞争条件）。每个请求的 `status`/`length`/`timeMs` 出现异常时标记 | | `analyze` | 一调用 **被动侦察**：评估响应安全头部（CSP/HSTS/CORS/X-Frame/nosniff/leaks），cookie 标志，并在主体中扫描暴露的秘密/API-keys/JWTs → 按严重性排名的结果。`deep:true` 还会获取相同来源的外部 `<script src>` 包并扫描这些 | | `jwt_decode` | 解码 JWT（头部/有效载荷，无验证）；标记 `alg:none`，HS/RS 混淆，过期 | | `request_to_curl` | 生成一个随时可运行的 **curl** 命令，用于重现捕获的请求（实际发送的头部，包括 `Cookie`，以及主体）或临时请求 - 用于移交给终端 / Burp 工作流程 | </details> <details> <summary><b>会话，存储和证据</b></summary> | 工具 | 描述 | |---|---| | `cookies_get` · `cookies_set` · `cookies_delete` | 通过 `chrome.cookies` 读取/写入真正的浏览器 cookie 储存 - 包括 `HttpOnly`，带有完整标志（`secure`，`sameSite`，`expirationDate`） | | `storage_dump` · `storage_set` · `storage_remove` · `storage_clear` | 读取/写入此来源的 `localStorage` / `sessionStorage` | | `console_start` · `console_get` · `console_stop` | 缓冲控制台输出，未捕获异常和 CSP/日志违规（通过 CDP；CSP 独立）。按正则表达式 `pattern` / `level` 过滤 `console_get` | | `save_page` | 将标签页保存为单个自包含的 `.mhtml` 证据快照 | </details> <details> <summary><b>Playbooks</b> （保存的，自愈任务配方）</summary> | 工具 | 描述 | |---|---| | `playbook_record_start` · `playbook_record_stop` | 记录模式：流式传输每个工具调用到 JSON-Lines 草稿，然后停止 - 一个种子，您可以将其提炼为持久的 Playbook | | `playbook_save` | 将 Playbook 的 Markdown 写入磁盘服务器端（全局 home 或项目本地），无论客户端的写入范围如何 | </details> <details> <summary><b>会话记录</b> （记录 → 自包含的 HTML 重放 → 高分辨率 MP4）</summary> | 工具 | 描述 | |---|---| | `session_record_start` | 开始记录标签页为会话重放（rrweb）- DOM + 变化 + 输入/滚动/鼠标（~60 fps），**无横幅**。`allFrames:true` 还记录跨源 iframe（尽力而为，每个帧超时）；`maskInputs:true` 默认关闭红色遮罩表单值 | | `session_record_stop` | 停止并组装一个 **自包含的 HTML** 重放：在任何浏览器中播放整个过程，具有 **播放按钮，时间线滚动条和速度控制** - 离线。 | | `session_record_status` | 列出活动记录（标签页，事件文件，事件至今） | | `render_recording_video` | 将保存的 `.html` 重放成 **高分辨率 MP4**（`fps`，`scale`高达 4× ≈ retina/4K，`crf`）。确定性 + 帧精确：按帧查找播放器，捕获无损 PNG，然后 ffmpeg → H.264。视频 = 记录的页面 + 交互覆盖，匹配实时播放 | </details> <details> <summary><b>截图配方</b></summary> `screenshot` 默认情况下捕获无横幅的可见视口。选项（这些使用 `chrome.debugger`，因此显示调试横幅）： | 需要 | 调用 | |---|---| | 整个滚动页面 | `screenshot(fullPage: true)` | | Retina / 高 DPI（尺寸 = CSS × 缩放） | `screenshot(fullPage: true, scale: 2)` | | 更小的文件 | `screenshot(format: "jpeg", quality: 85)` | | 仅一个元素 | `screenshot(selector: "#invoice")` | | 写入磁盘（适用于大页面） | `screenshot(fullPage: true, savePath: "/abs/path.png")` | `savePath` 返回 `{ path, bytes, width, height }` 而不是多 MB 的内联图像。捕获的上限为 Chrome 的 ~16384px 表面大小，超大 PNG 自动回落到 JPEG。 </details> ## Playbooks 重复性任务 - “删除此类帖子”，“对端点运行 BOLA 检查” - 成本昂贵首次理解（快照，查找选择器，试验和错误）。**Playbook** 将已解决的知识保存到本地 Markdown 文件，以便下一次执行费用低。 Playbook 是一个 **自愈文档，不是宏**：它记录 **意图 + 健壮的角色/可访问性定位器 + 检查点 + 历经的“理解”** - 从不原始点击，坐标，快照引用或捕获的请求 ID（这些是短暂的并且会破坏下一次运行）。代理运行时 **带有判断** - 重新感知每个步骤，在执行前验证目标，并重新派生已漂移的步骤 - 这是相对于脆弱的记录重放宏的全部优势。破坏性/不可逆步骤需要确认。 Playbook 位于 `~/.browser-bridge/playbooks/<slug>.md`（全局）或 `./playbooks/<slug>.md`（项目本地，git-shareable）；每个连接的代理通过 MCP `instructions` 字段自动学习约定。捕获一个 **记录模式**：`playbook_record_start` → 一次执行任务 → `playbook_record_stop` → 蒸馏草稿 → `playbook_save`。 **格式，执行协议，愈合/安全规则，以及两个工作示例（一个 DOM 删除 + BOLA/IDOR流程）： [docs/PLAYBOOKS.md](docs/PLAYBOOKS.md) ** ## 记录 记录实时交互并重放。`session_record_start` 捕获 DOM + 变化 + 输入/滚动/鼠标（rrweb），**无横幅**；交互页面；`session_record_stop` 组装一个 **自包含的 HTML 文件**，在任何浏览器中播放整个过程，具有 **播放按钮，时间线滚动条和速度控制** - 离线。 因为扩展程序将记录器注入到 **每个帧包括跨源 iframe**（而页面级 rrweb 无法做到这一点），并且 **CSP 免疫**，它记录站点和嵌入式框架，而普通记录器甚至无法加载。事件流到 `~/.browser-bridge/recordings/*.events.jsonl` 捕获期间（存活长会话），然后与 rrweb-player 一起内联到 HTML 上停止。 重放 **真正自包含 / 离线忠实**：停止后，服务器获取捕获引用的所有外部资产 - 跨源样式表，字体，图像和延迟加载的图像 - 通过扩展程序（后台 `fetch` 在 `<all_urls>` 下无 CORS 墙 + 发送您的会话 cookie）并内联它们，并剥离其他扩展程序的节点。 因此，它从捕获的数据中渲染，而不是重新获取实时站点（页面级 rrweb 无法读取跨源 CSS）。 播放器是一个自定义 **FRACTURE** 样式的 UI：重放 **填充窗口以匹配记录页面的确切宽高比**（在调整大小时缩放），具有播放/滚动时间轴，速度，跳过空闲和全屏。 一个可切换的 **交互覆盖** 用平滑的鼠标轨迹，**点击波纹** 和 **按键 HUD**（键入文本，以及物理按键，如 `Enter` / `⌘C`）进行注释。然后 **`render_recording_video`** 将保存的 `.html` 转为 **高分辨率 MP4**（`fps`，`scale` 高达 4 倍 ≈ retina/4K）- 确定性 + 帧精确：查找 + 无损 PNG 每帧 → ffmpeg H.264。 视频 = 记录的页面 + 交互覆盖，匹配实时播放。 注意：输入 **默认情况下禁用遮罩**（纯文本值；`maskInputs:true` 以删除）；canvas/WebGL 和实时视频 **像素** 不会被 DOM 重放捕获。 **详情： [docs/RECORDING.md](docs/RECORDING.md).** ## 安装 ### 前提条件 - **Node.js 18+** 和 **Chrome, Chromium, 或 Edge** - 在 **Linux, macOS, 或 Windows** 上（基于铬；不支持 Brave/Arc，也不支持 WSL） - **Claude Code ≥ 2.0.73** 和/或 **OpenAI Codex CLI** ### 1 · 构建 ```bash git clone https://github.com/vitalysim/browser-bridge.git cd browser-bridge ( cd server && npm install && npm run build ) # MCP server ( cd extension && npm install && npm run build ) # bundles background.js + options.js ``` ### 2 · 运行服务器 服务器会在第一次运行时生成一个随机令牌，并将其存储在 `~/.browser-bridge/token`（同时在启动时打印）。请选择以下选项之一： **自动启动（推荐）** - 一个命令会为您的操作系统安装一个后台服务（Linux 上的 systemd 用户服务，macOS 上的 launchd LaunchAgent）。 ```bash cd server && npm run install-service # 在登录时运行，在崩溃时重启 # Linux: 要在启动时启用，无需活动登录： loginctl enable-linger "$USER" # 删除后可以使用以下命令卸载： npm run uninstall-service ``` **手动** - 直接在终端中运行： ```bash cd server && npm start # 或： nohup node dist/index.js >~/.browser-bridge/server.log 2>&1 & ``` 验证：`curl -s http://127.0.0.1:8765/health` → `{"ok":true,"extensionConnected":false}`（扩展程序加载后变为 `true`）。 日志： Linux `journalctl --user -u browser-bridge -f`; macOS 手动 `tail -f ~/.browser-bridge/server.log`. ### 3 · 加载扩展程序 1. 打开 `chrome://extensions`，启用 **开发者模式**。 2. **加载解包** → 选择 `extension/` 文件夹。 3. 打开扩展程序的弹出窗口/选项 → 粘贴 `~/.browser-bridge/token` 中的令牌 → **保存并连接**。 状态变为绿色。 验证：`curl -s http://127.0.0.1:8765/health` → `{"ok":true,"extensionConnected":true}`. > 重新加载扩展程序后，可能会提示您授予新的权限（例如 `webNavigation`，`debugger`，`downloads`）- 如果 Chrome 禁用它们，请重新启用它们。 ### 4 · 连接您的代理 **Claude Code** ```bash claude mcp add --transport http --scope user browser-bridge \ http://127.0.0.1:8765/mcp --header "Authorization: Bearer $(cat ~/.browser-bridge/token)" ``` **Codex CLI** - 导出令牌，然后通过一个命令注册： ```bash export BROWSER_BRIDGE_TOKEN="$(cat "$HOME/.browser-bridge/token")" # 添加到您的 shell 配置文件中 codex mcp add browser-bridge --url http://127.0.0.1:8765/mcp --bearer-token-env-var BROWSER_BRIDGE_TOKEN ``` 或直接编辑 `~/.codex/config.toml`： ```toml [mcp_servers.browser-bridge] url = "http://127.0.0.1:8765/mcp" bearer_token_env_var = "BROWSER_BRIDGE_TOKEN" ``` > Codex 通过环境变量名称读取令牌，因此 `BROWSER_BRIDGE_TOKEN` 必须在启动 `codex` 的 shell 中导出（因此将其添加到您的配置文件中）。 使用 `codex mcp list` 验证。 ### 平台支持 | 操作系统 | 服务器 | 扩展 | 自动启动 | |---|:---:|:---:|---| | **Linux** | ✅ | ✅ | systemd 用户服务 (`npm run install-service`) | | **macOS** | ✅ | ✅ | launchd LaunchAgent (`npm run install-service`) | | **Windows** | ✅ | ✅ | 手动 (`npm start`)；使用服务管理器注册 | ## 安全与责任使用 - **代理使用您的真实 Cookie。** 请像运行 *您* 一样对待每次工具调用。 - **提示注入是环境风险。** 代理读取的页面是不可信的输入；恶意页面可以尝试操纵它。 将具有写入权限的工具放在 MCP 客户端的权限提示后面，不要指向您不信任的页面。 - **调试器模式非常强大。** 连接后，它可以读取完整的请求/响应正文（包括身份验证标头）并分派受信任的输入。 它显示 Chrome 的 *"已开始调试此浏览器"* 横幅，在约 5 分钟空闲后自动分离（除非正在主动捕获），并且可以通过 `debugger_detach` 立即结束。 - **安全测试工具是原始的进攻性基元，没有内置范围保护 - 按照设计。** 像 Burp Suite Repeater/Intruder/Autorize 一样，在授权参与的范围内工作是 **操作员的责任**。 仅将 Browser Bridge 指向您授权测试的系统。 - **存储库中没有秘密。** 承载令牌存储在 `~/.browser-bridge/`（gitignored）；绑定仅限于本地主机。 请参阅 [SECURITY.md](SECURITY.md) 以报告漏洞。 ## 限制 - 交互自动等待可操作性，并在 `click` 时自动升级为受信任的 CDP 点击，当目标被覆盖时（`via:"trusted"`，显示横幅）；在任何时候强制执行 `trusted:true`。 覆盖/隐藏/禁用的目标返回结构化 `{notActionable, reason}`。 - 严格的页面 **CSP**（`script-src` 没有 `'unsafe-eval'`）阻止无横幅的 `eval_js`；它自动回落到 `cdp_eval`（CDP `Runtime.evaluate`，显示横幅），而 CSP 无法阻止。 隔离世界读取/交互工具和所有 CDP/后台工具都不会受到 CSP 的影响。 - `chrome.debugger` 需要对选项卡的唯一访问权限 - 如果 DevTools 在该选项卡上打开，则 **无法附加**。 `net_capture_start` 仅记录调用后发送的流量（导航/重新加载以捕获页面加载）。 - 捕获缓冲区在内存中（一个环形缓冲区，包含 `maxEntries` 请求/选项卡，默认 500，约 512 KB/正文）。 活动捕获不会被空闲扫描破坏；对于超出环形缓冲区上限的持久记录，请使用 `net_capture_start(persist:true, savePath:…)`，它会流式传输到磁盘。 持久性是 **耐用性，而不是连续性** - 如果服务工作线程死亡，调试器会分离，捕获会停止，直到重新启动；文件保存了捕获之前的内容。 - 每次只有一个扩展连接（最后连接的赢家）；多个 MCP 客户端可以并发共享它。 调用在扩展断开连接时仍在进行中，会快速失败，而不是等待超时。 - `input` 坐标是 **CSS 视口像素**，但截图是 **设备像素** - 使用截图返回的 `dpr` 进行映射（`coord = screenshotPixel / dpr`）。 即使选项卡在后台运行，`input` 仍会传递，但隐藏选项卡的帧会被限制，因此您无法在选项卡被激活之前 **观察** 结果（`activate:true` / `tab_activate`）；`screenshot` 通过 `visibilityState` 标记此行为。 - `download_resource` 始终使用浏览器的实时会话 - 它无法作为捕获的 `identity` 下载。 `Cookie`/`Host`/`Origin`/`Referer`/`Content-Length` 在其 `headers` 参数中是浏览器禁止的，并被静默忽略。 如果启用了 Chrome 的“询问每个文件的保存位置”设置，下载可能会提示选择位置，而不是自动完成。 ## 路线图 **已发布**（最新的优先）： - **v0.14 · MP4 导出** - `render_recording_video` 将保存的回放渲染为高分辨率、帧精确的 **H.264 MP4**（确定性搜索 + 无损 PNG 帧 → ffmpeg）；鼠标轨迹 / 点击 / 击键动作与实时播放相匹配。 `chrome:true` 包括播放器 UI。 - **v0.13 · 设计的重放播放器** - 一个自定义的 **FRACTURE** 样式的播放器，具有 **全页面适应视口** 渲染和可切换的 **交互叠加层**：平滑的鼠标轨迹，点击波纹和击键 HUD（键入文本 + 物理按键）。 - **v0.12 · 正确性和可靠性** - 审计驱动的检查（56 次代理审查）：套接字替换上的无声捕获丢失保护，MV3 内存泄漏上限，跨会话记录和强大的 `allFrames` 注入。 - **v0.11 · 离线忠实重放** - `session_record_stop` 内联每个外部资产（跨源 CSS / 字体 / 图片，通过扩展程序获取 - 无 CORS 墙）并剥离外部扩展节点，因此 HTML 真正自包含。 - **v0.10 · 会话记录** - 记录实时交互并将其重放为自包含的 HTML 时间线（rrweb；`session_record_start` / `stop` / `status`），无横幅，捕获跨源 iframe。 → [docs/RECORDING.md](docs/RECORDING.md) - **v0.9 · 剧本** - 保存的，自愈的任务配方（Markdown 在 `~/.browser-bridge/playbooks/`；通过 `playbook_record_start` / `stop` / `playbook_save` 进行记录模式捕获）。 → [docs/PLAYBOOKS.md](docs/PLAYBOOKS.md) - **v0.8 · 远程桌面渗透测试反馈** - 坐标级别的受信任输入（`input`）用于画布 / VNC / RDP / DCV，`get_page_text(includeHidden)`，`cdp_eval` / `eval_js` `timeoutMs`，以及 `screenshot` `dpr` / `visibilityState`。 - **v0.7 · 耐用捕获和交接** - `net_capture_start(persist)` + `maxEntries`，复制为 curl（`request_to_curl`），`analyze deep`，以及可靠性修复。 - **v0.6 · 自我愈合交互，重构和证据** - 被动重构（`analyze`）+ `jwt_decode`，HAR 导出，模糊模式 + `viaAppClient` 重放。 - **v0.5 · 安全工具包基础** - 拦截，模糊测试，Cookie / 存储，控制台 / CSP 捕获和 MHTML。 **正在探索的下一个：** - **实时屏幕视频模式** - 还可以捕获基于时间的 *页面* 动画（CSS 关键帧 / GIF / `<video>`），而确定性搜索无法固定。 - 下载时的源映射 **去混淆**。 - **GraphQL** 反省助手。 - 客户端 **DOM-XSS / postMessage / 原型污染** 套件。 ## 项目结构 ``` server/ MCP 服务器（TypeScript · @modelcontextprotocol/sdk · ws · express） src/index.ts HTTP MCP 端点 + 认证 + 会话管理 src/hub.ts 单个扩展套接字，请求/响应关联，捕获接收器 src/capture-sink.ts 持久的磁盘 JSON-Lines 接收器，用于持久捕获 src/tools.ts 63 个 MCP 工具 extension/ 清单 V3 扩展（通过 build.mjs 与 esbuild 捆绑） manifest.json src/background.ts 服务工作线程：WS 客户端，注入，chrome.debugger（CDP）层 src/options.ts 令牌 + 连接 UI icons/ 生成的应用图标 scripts/ install-service.mjs / uninstall-service.mjs（systemd 或 launchd） docs/ PLAYBOOKS.md · RECORDING.md · banner.svg · architecture.svg server/vendor/ rrweb-player（内联到会话重放 HTML） extension/vendor/ rrweb-record.js（注入的记录器；由 build.mjs 构建） ``` ## 贡献 欢迎贡献 - 请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)** 以获取构建和开发循环（包括 MV3 服务工作线程重载问题）和如何添加工具。 在桥本身中发现安全问题？ 请根据 **[SECURITY.md](SECURITY.md)** 私密报告。 ## 许可证 **MIT** - 请参阅 [LICENSE](LICENSE)。 捆绑的第三方组件（rrweb，rrweb-player - 均为 MIT）已在 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) 中注明。 ## 免责声明 Browser Bridge 仅用于 **授权的** 自动化，研究和安全测试。 您负责遵守您自动化的网站的服务条款和任何安全参与的范围。 作者不对滥用行为承担任何责任。