Castor6/BrowserRig

BrowserRig

BrowserRig — 让智能体遇见你的真实浏览器

BrowserRig 让可信的编程智能体在你现有的 Chromium 系浏览器中运行
Playwright。它直接使用你的真实浏览器配置，包括已经登录的会话和已安装的
扩展，而不是另外启动一个无头浏览器。

BrowserRig 是一个独立的开源产品，而不是其他浏览器智能体生态的授权中间层。
它衍生自采用 MIT 许可证的上游驱动，同时拥有自己的 CLI、npm 包、浏览器扩展
和商店身份。

为什么选择 BrowserRig

BrowserRig 专门填补浏览器自动化与个人日常浏览器之间那个棘手的空白：

- 使用你真实且已登录的浏览器。 复用你已经在使用的 Chrome 窗口、Cookie、
会话和扩展。
- 没有阻塞式远程调试授权。 BrowserRig 不连接 Chrome 的浏览器级远程调试
端点，因此不会反复触发 Allow remote debugging? 对话框。
- 接管当前标签页无需点击工具栏。 session adopt --active 一条命令即可找到、
附加并接管最近聚焦浏览器窗口中的当前标签页。
- 后台工作，不打断你的操作。 普通的 execute 会在同一浏览器配置中创建后台
标签页，而不是切换当前可见标签页或启动另一个浏览器。
- 完整的本地驱动，而不是智能体包装层。 无需捆绑 LLM 或依赖托管服务，仍可
使用 CLI、Playwright 执行会话、MCP 服务器、录制、网络捕获和人工接管。

BrowserRig 与其他方案的比较

BrowserRig 将开源、CLI/Skill 优先的驱动方式，与对现有已登录浏览器的持久访问
结合在一起。下面的比较聚焦于这一核心工作流。

| 能力 | BrowserRig | Kimi WebBridge | agent-browser | Chrome DevTools MCP |
| --- | :---: | :---: | :---: | :---: |
| 开源核心 | ✅ | ❌ | ✅ | ✅ |
| CLI / Skill 优先 | ✅ | ✅ | ✅ | ❌MCP 优先；工具 Schema 会占用上下文 |
| 无需再次浏览器授权即可重连已登录的 Chrome | ✅ | ✅ | ❌重连和浏览器重启后可能需要再次点击“Allow remote debugging?” | ❌每次自动连接都需要批准 Remote Debugging |

扩展仍然使用 Chrome 的 debugger API 传递 CDP 命令。差别在于传输方式和授权
范围：BrowserRig 使用扩展附加，而不是连接 Chrome 的浏览器级远程调试端点。
标签页被附加时，Chrome 可能会显示标准的非阻塞式调试提示条，但不需要逐个标签页
点击批准。

智能体（DSH 插件、CLI 或 MCP）-> 本地中继 -> 浏览器扩展 -> 你的浏览器

驱动完全在本地运行，不包含 LLM，也不负责制定计划。它的主要接口是代码：智能体
发送一段 Playwright 代码，然后收到执行结果、日志、警告和变更摘要。

快速开始

BrowserRig 需要 Node.js 22.22.0 或更高版本，以及 Chrome、Brave、Edge、Arc
或 Chromium 等 Chromium 系浏览器。

设置分为两个必要部分：先把 BrowserRig 连接到你使用的智能体运行时，再安装浏览器
扩展。DeepSeek Harness 使用原生 DSH Bundle；其他编程智能体可以使用 CLI Skill
或 MCP 服务器。

1. 连接你的智能体

DeepSeek Harness

根目录的 browserrig 包遵循 DSH 的
官方 Bundle 安装模型。
将它安装到你使用的 DSH Profile 中，然后检查组合后的配置层：

dsh plugin --profile web add browserrig
dsh --profile web --dump-config

这种方式既不需要全局安装 browserrig CLI，也不需要单独安装 BrowserRig Skill。
Bundle 自带与当前版本匹配的包内 CLI 运行时、六个类型化的 browserrig_ 工具和
简洁的操作指南。它为每个 DSH 智能体会话绑定一个持久的 BrowserRig 会话，无需
暴露 BrowserRig 会话 ID，也不要求模型记住这些 ID。

CLI 和 Skill 驱动的智能体

全局安装独立包：

npm install --global browserrig

这会为 CLI 和 Skill 驱动的智能体安装 browserrig，并为 MCP 客户端安装
browserrig-mcp。

包内 Skill 会教编程智能体如何先检查再操作、保持会话身份、处理只能由人完成的
步骤，以及从浏览器故障中恢复。使用 skills CLI 安装：

npx skills add Castor6/BrowserRig --skill browserrig -g

出现提示时选择你使用的智能体。全局 -g 安装可让 Skill 跨项目使用。

Castor6/BrowserRig 是 BrowserRig 的独立仓库身份。BrowserRig 不会自行修改
智能体配置。如需手动检查或安装 Skill，可以输出包中完全一致的文本：

browserrig skill

可选的 MCP 服务器

Skill 和 MCP 服务器承担不同职责：Skill 教会智能体工作流程；MCP 将 BrowserRig
暴露为工具。能执行 Shell 命令的智能体只需要 Skill。当客户端更适合使用 MCP 工具
时，再添加 MCP。

OpenCode 配置：

// opencode.json
{
"mcp": {
"browserrig": {
"type": "local",
"command": ["browserrig-mcp"]
}
}
}

Claude Code 配置：

claude mcp add browserrig -- browserrig-mcp

CLI 和 MCP 客户端共用分离运行的中继，但每个执行会话都有自己的默认页面和持久
JavaScript state。重启 MCP 进程不会停止中继，也不会中断正在进行的 CLI 会话。

2. 安装扩展

从 Chrome 应用商店安装 BrowserRig，
然后可按需固定工具栏按钮，以便手动附加或分离标签页。每个新版本通过 Chrome
应用商店审核后，商店安装的扩展会自动更新。

如果需要进行源码开发，或当前浏览器无法使用该商店页面，可以改为加载包内的开发
版本：

1. 输出与你所选安装方式对应的扩展目录：

DeepSeek Harness profile (replace web if you use another profile)
printf '%s\n' "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/browserrig/extension/dist"

Global npm installation
printf '%s\n' "$(npm root --global)/browserrig/extension/dist"

2. 打开 chrome://extensions，或浏览器对应的页面，例如
brave://extensions。
3. 启用 开发者模式。
4. 选择 加载已解压的扩展程序，然后选择上一步输出的目录。
5. 可选：固定 BrowserRig 工具栏按钮，以便手动附加或分离标签页。

3. 执行第一条浏览器命令

启动已配置的 DSH Profile，并让其中的智能体使用 BrowserRig：

dsh --profile web

如果直接安装了 CLI，可用下面的命令验证：

browserrig execute 'await page.goto("https://example.com"); return { title: await page.title(), url: page.url() }'

两种方式都会在需要时启动同一个分离运行的本地中继，并在现有浏览器配置中打开一个
后台标签页。直接调用 CLI 时，会输出易读的会话 ID 和继续该会话所需的完整
--session 命令；DSH 插件会在内部保持这种连续性。中继监听
127.0.0.1:19990，并在多次调用之间持续运行。

成功执行后会返回 Example Domain 标题、生成的会话 ID 和继续命令。随后
browserrig status 会报告扩展已经连接。

你可以随时检查安装状态：

browserrig doctor
browserrig status

doctor 和 status 都是只读命令。它们会报告中继已停止，但不会启动中继。
browserrig serve 只用于前台调试。

原生 DeepSeek Harness 集成

DSH Bundle 是 BrowserRig 之上的轻量原生适配器，而不是第二个浏览器驱动或 MCP
包装层。它直接向 DSH 提供以下工具：

- browserrig_execute 在 DSH 会话的持久页面中运行 Playwright JavaScript，
并在可用时返回结构化值、日志、警告、执行后摘要和 DSH 图片附件。
- browserrig_adopt_active 直接接管用户当前已登录的标签页。
- browserrig_status 报告就绪状态，以及仅属于当前 DSH 会话的浏览器状态投影。
- browserrig_reset 重置当前会话，但不会关闭已接管的用户标签页。
- browserrig_journal 读取最近的 BrowserRig 执行历史。
- browserrig_issue_report 记录经过清理的 BrowserRig 产品或运行问题，且不暴露
内部会话 ID。

每个 DSH 智能体会话都会持久映射到配置中继端点上的一个 BrowserRig 会话。首次
使用会以原子方式创建映射；如果明确确认 BrowserRig 会话不存在，则只替换一次，
同时保持其他 DSH 任务彼此隔离。内部 BrowserRig ID 和全局目标列表不会返回给
模型。

适配器使用固定参数数组、经过验证的 JSON 信封、有限输出和 DSH 取消机制，调用
同一个 npm 包中附带的 CLI。它不提供任意 Shell 或 CLI 透传，不依赖可能发生版本
漂移的独立全局可执行文件，环境中的 CLI 会话或目标选择器也无法覆盖 DSH 任务
绑定。它同样不会重复提供点击、填写和导航等微型工具层。直接使用 CLI、MCP 和库
的用户仍然独立于 DSH。

实验性 WebMCP

在调用 BrowserRig 的智能体环境中启用原生网站工具发现（默认关闭）：

export BROWSERRIG_EXPERIMENTAL_WEBMCP=true

原生 WebMCP 需要兼容的 Chrome，以及已启用该功能的网站。网站如果配置了有效的
Origin Trial 试用凭证，用户无需
手动开启浏览器实验开关。

如果网站没有通过有效的 Origin Trial 启用 WebMCP，你可以在本地开启它进行测试：

1. 在 Chrome 地址栏输入 chrome://flags/#enable-webmcp-testing。
2. 将该项设为 Enabled。
3. 重启 Chrome。

然后重新打开网站，让智能体再次发现其 WebMCP 工具。开启这个开关不会为尚未实现
WebMCP 的网站添加工具。

BrowserRig 不会自动开启 Chrome 实验功能。available 但工具数量为零，只表示
没有发现原生工具，也可能是页面尚未启用该 API。

TypeScript 客户端

对于需要发起结构化、浏览器认证请求，但不希望执行生成 JavaScript 的应用，此包
还导出了一个 Effect 客户端：

npm install browserrig effect@4.0.0-beta.97

import { BrowserRigClient } from "browserrig"
import { Effect, Schema } from "effect"

const program = Effect.gen(function () {
const client = yield* BrowserRigClient.make()
const browserSession = yield* client.ensureSession({ id: "my-app" })
const account = yield* browserSession.authenticatedOrigin({
origin: "https://app.example.com",
startUrl: "/account",
})

const sensitive = yield* account.json({
path: "/api/session",
method: "POST",
body: {},
response: Schema.Struct({ accessToken: Schema.String }),
sensitive: true,
})
const credentials = BrowserRigClient.reveal(sensitive)

const profile = yield* account.json({
path: "/api/profile",
response: Schema.Struct({ name: Schema.String }),
})
return { credentials, profile }
})

请求使用会话当前页面中的 window.fetch，因此浏览器中的 Cookie 会留在浏览器里。
路径必须同源，重定向会被阻止，响应有大小限制，变更请求不会自动重试。设置
sensitive: true 可接收 Redacted；敏感请求会绕过执行日志，并在会话网络
捕获开启时被拒绝。使用 BrowserRigClient.reveal 解开敏感结果；这样即使应用和
BrowserRig 解析到了不同的 Effect 包实例，解包操作仍会发生在创建该脱敏值的同一个
Effect 运行时中。如果持久会话已不再连接，在创建新的认证来源能力之前，使用
resetSession(id) 替换该会话世代。

使用会话工作

不带参数的 execute 会创建一个新会话。传入它的 ID，即可继续使用同一页面和
state：

browserrig session new docs
browserrig execute --session docs 'await page.goto("https://example.com/docs"); state.visits = (state.visits ?? 0) + 1; return state.visits'
browserrig execute --session docs 'return { url: page.url(), visits: state.visits }'
browserrig journal --session docs

日志是尽力写入的本地活动记录，保存在
~/.browserrig/sessions//journal.jsonl。它包含有限长度的脚本和结果预览，
即使删除会话也会保留。不要直接在执行代码中嵌入密码、Token 或其他凭据。

单个表达式会自动返回，因此也可以使用更短的写法：

browserrig execute --session docs 'await page.title()'

较长的程序使用 --file script.js，需要机器可读的结果信封时使用 --json。
完成后删除会话：

browserrig session delete docs

控制现有标签页

中继创建的页面与其他 BrowserRig 会话相互隔离。要接管最近聚焦浏览器窗口中的
当前标签页，无需点击扩展，也无需匹配 URL：

browserrig session new github
browserrig session adopt --session github --active
browserrig execute --session github 'return { title: await page.title(), url: page.url() }'

--active 会在扩展内部解析并附加标签页，然后使用与现有已附加标签页相同的所有权
事务接管它。

如果你有意一次暴露多个标签页，或稍后选择一个非当前标签页，工具栏按钮仍然有用。
在这些标签页上点击工具栏按钮，然后通过 --target-url 或 --target-index 精确
选择其中一个：

browserrig session adopt --session github --target-url github.com

一个已接管目标只能属于一个 BrowserRig 会话。重置或删除会话时，会释放已接管的
用户标签页，而不会关闭它。

操作前先检查

执行代码可以使用标准的 Playwright browser、context 和 page 对象，以及
BrowserRig 辅助函数。交互前读取页面时，snapshot() 是精简的默认方式：

browserrig execute --session github 'return await snapshot()'

快照控件包含 [ref=e12] 这样的引用。下一次调用时可直接使用引用：

browserrig execute --session github 'await ref("e12").click(); return await snapshot({ diff: true })'

引用仅属于最新快照，并在页面导航后失效。它们同时结合结构身份和无障碍身份，因此
DOM 漂移时会安全失败，而不是悄悄指向另一个控件。

其他检查辅助函数包括：

- ariaSnapshot()：查看更深层的无障碍树
- screenshotWithLabels()：获取带标注的截图和元素元数据
- 当浏览器扩展干扰 Playwright 常规 locator.fill() 时，使用 fillInput() 和
fillInputs()

原生 DSH Bundle 自带简洁的操作指南。对于直接使用 CLI 和 MCP 的智能体，包内
Skill 提供完整工作流和规范示例；命令的 --help 输出仍是详细选项的事实来源。

为只能由人完成的步骤暂停

遇到 CAPTCHA、2FA、付款确认或其他必须由人完成的步骤时，使用 handoff()：

await handoff("Complete 2FA, then use the in-page continue control")
await page.getByRole("heading", { name: "Dashboard" }).waitFor()
return page.url()

如果点击操作本身可能阻塞在原生 WebAuthn 或付款界面上，请在触发它之前注册人工
接管：

await handoff("Complete the security-key prompt, then continue", {
timeoutMs: 600_000,
start: () => page.getByRole("button", { name: "Use security key" }).click({ timeout: 600_000 }),
})

页面会显示一个无障碍的完成控件，脚本则等待用户操作。人工确认并不能证明所请求的
步骤已经成功，因此接管后始终要验证预期 URL 或元素。BrowserRig 会等待扩展确认
WAIT 状态后再调用 start。如果接管超时或目标先消失，它会在释放执行许可前断开
该沙箱的 Playwright 连接，防止仍未结束的提示操作稍后继续修改页面。start 中
只应包含用于打开原生提示的、有明确边界的浏览器操作。

使用只读会话

只读会话会拒绝鼠标和键盘 CDP 命令，但允许导航、检查和截图：

browserrig session new inspect --read-only
browserrig execute --session inspect 'await page.goto("https://example.com"); return await snapshot()'

只读模式可防止意外的 Playwright 输入，但它不是安全沙箱：可信代码仍然可以通过
page.evaluate() 修改页面。

录制会话

browserrig recording start ./demo.webm --session github
browserrig recording status --session github
browserrig recording stop --session github

自动模式对用户拥有的标签页优先使用浏览器标签页捕获，对中继创建的标签页使用 CDP
截屏流。只有用户在该标签页上调用扩展后，Chrome 才会授予标签页/音频捕获权限。
如果一个无需点击即可接管的标签页没有该授权，且未请求音频，自动模式会回退到 CDP。
显式使用 --mode tab-capture 和 --audio 仍需要点击一次工具栏；如果点击导致
已经受控的标签页分离，请在录制前再次运行 session adopt --active。标签页捕获
写入 WebM，并且可以包含音频。CDP 写入 WebM 或 MP4，需要 PATH 中存在
ffmpeg，会激活被录制的标签页，并且没有音频。

派生直接客户端

在工作流所需的任意多次执行调用或人工接管中捕获已认证 API 交换：

browserrig network start --session github --url /api/ \
--resource-type fetch --resource-type xhr
browserrig execute --session github --file ./perform-flow.js
browserrig network stop --session github \
--output ./github.har --secrets github

BrowserRig 自行记录规范化的请求/响应交换；HAR 是可互操作的导出格式，而不是内部
捕获模型。写出的产物会将 Cookie、Authorization Header、CSRF Token、API Key
以及查询或 Body 中类似 Token 的字段替换为稳定的 ${BROWSERRIG_SECRET_N}
引用。无损值单独保存在 ~/.browserrig/secrets 下、权限模式为 0600 的
Profile 中。无法可靠脱敏的 Body（包括二进制内容和包含文件的 multipart 内容）
会被省略并报告为截断。长度未知或经过压缩的响应 Body 也会被省略，确保 BrowserRig
不会在执行配置的预算限制前就将其完整加载到内存。

生成的客户端读取这些引用对应的环境变量，运行时不会打印或嵌入值：

browserrig secrets status github
browserrig secrets run github -- ./github-cli repositories
browserrig secrets refresh github --session github

secrets refresh 会重新加载会话页面，并在更新同一来源观察到的值时保留引用。
如果重新认证需要人工流程，请在浏览器中登录，并使用相同的 Profile 名称重复捕获。
BrowserRig 会先脱敏子进程的标准输出和标准错误，再将其返回。

报告 BrowserRig 问题

智能体可以记录由 BrowserRig 管理的运行问题，而无需在调用方仓库中写入待办事项或
跟踪文件：

browserrig issue report \
--classification operational \
--component relay \
--summary "Relay recovered after a failed start" \
--actual "The first start failed and the retry succeeded" \
--error-code relay/start-failed \
--recovery "Retried once"

CLI、MCP issue_report 和 DSH browserrig_issue_report 共用
~/.browserrig/issues/ 下的同一个本地存储。报告会经过清理，以受限权限写入，
并按稳定指纹聚合。相关的会话日志时间戳会被引用，但不会复制执行代码或结果。报告
问题不需要启动中继，也不会主动启动中继。

可恢复的 BrowserRig 事件使用 operational；重复发生或无法恢复的 BrowserRig
产品问题使用 suspected-bug；潜在敏感发现使用 security。普通的定位器、断言
和网站变化故障应留在会话日志中。安全报告绝不会创建公开 Issue。

默认关闭 GitHub 提交。用户可以在启动智能体时主动选择开启：

export BROWSERRIG_ISSUE_AUTO_SUBMIT=true

开启后，只有符合条件的 suspected-bug 报告才会检查已安装且完成认证的 gh，
并在创建 Issue 前对 Castor6/BrowserRig 中的内容去重。BrowserRig 不会自行
开启此设置、启动 GitHub 认证，也不会在 GitHub 不可用时丢弃本地报告。

安全边界

BrowserRig 信任它执行的本地智能体代码。它是一个驱动，不是用于运行不可信代码的
沙箱。

这些能力具有双重用途。npm 包声明了这一分类，并包含一份具体的
DISCLOSURE，说明预期用途、安全边界以及禁止的未授权访问。

扩展隐私政策
说明了 BrowserRig 的本地数据处理、保留方式、用户控制和 Chrome Web Store
Limited Use 承诺。

扩展需要广泛的浏览器权限，包括 debugger、tabCapture，以及在所有 URL 上
运行的状态内容脚本。附加用户标签页后，BrowserRig 可以通过现有浏览器 Profile
访问该标签页。

BrowserRig 不会启用或连接 Chrome 的浏览器级远程调试端点。扩展附加时会显示
Chrome 的调试提示条；关闭提示条将分离标签页，之后再次运行 session adopt
--active 即可重新附加，无需阻塞式授权对话框。

中继会阻止清除 Cookie、清除缓存或关闭浏览器等破坏性的浏览器级 CDP 命令。它还
会向其他 BrowserRig 会话隐藏当前会话拥有的标签页。这些防护可以减少误操作，但
脚本仍然可以访问所选页面、该页面的登录状态，以及一组有限的 Node.js 文件系统和
网络 API。

当前限制：

- 一个中继同一时间只使用一个已连接的浏览器 Profile 扩展。存在多个 Chrome
Profile 时，--active 作用于扩展当前所连接的 Profile，以及该 Profile 最近
聚焦的窗口。
- chrome://extensions 等浏览器内部页面无法通过 Chrome 的 debugger API
附加。
- Chromium 会阻止通过 chrome.debugger 使用所需的下载命令，因此 Playwright
下载产物不可用。请获取暴露出的响应字节，并使用提供的 fs 模块写入文件。
- CDP 录制需要 ffmpeg，会激活被录制的标签页，并且没有音频。
- BrowserRig 面向可信的本地使用场景，不提供经过认证的远程中继。

故障排查与升级

- 缺少 DSH 工具：运行 dsh --profile  --dump-config，确认存在
browserrig Bundle 层，然后重启该 Profile。
- browserrig: command not found：对于直接 CLI/MCP 设置，确认 npm 的
全局二进制目录位于 PATH，然后再次运行全局安装。原生 DSH 设置不需要此全局
命令。
- 扩展已断开：确认商店扩展已经安装并启用；如果其重连循环没有自行恢复，再从
浏览器的扩展页面重新加载。进行源码开发时，则重新加载未打包开发版本。
- 另一个工具正在调试浏览器：如果 BrowserRig 反复连接和断开，同时 Chrome
显示另一个产品正在调试浏览器，请结束该浏览器级调试会话并重新加载 BrowserRig。
Chrome 不允许 BrowserRig 同时附加相同目标。
- 当前标签页由另一个调试器控制：关闭 DevTools，或分离该标签页上的其他调试
扩展，然后再次运行 session adopt --active。
- npm 升级后：商店安装的扩展会独立更新，无需手动重新加载。只要报告的协议
版本相同，扩展和中继的发布版本可以不同。
- 中继过期警告：运行 browserrig doctor，停止它识别出的旧中继进程，然后
再次运行需要中继的命令。

使用 PowerShell 进行开发安装时，可用下面的命令输出未打包扩展路径：

DeepSeek Harness profile
$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $HOME ".dsh" }
Join-Path $dshHome "profiles/web/node_modules/browserrig/extension/dist"

Global npm installation
Join-Path (npm root --global) "browserrig/extension/dist"

开发

git clone https://github.com/Castor6/BrowserRig.git
cd browserrig
pnpm install
pnpm build
npm link

pnpm typecheck
pnpm test
pnpm build
SMOKE_CASE=oopif-reconnect pnpm smoke

修改扩展源代码后，需要运行 pnpm build:extension 并重新加载未打包扩展。只修改
中继时，只需重新构建或重启中继，无需重新加载扩展。

架构和路线图决策参见 PLAN.md，贡献者约束参见
AGENTS.md，开发和评审要求参见
CONTRIBUTING.md，私密漏洞报告方式参见
SECURITY.md，受 2FA 保护的 npm 和 Chrome Web Store 发布
流程参见 docs/RELEASING.md，完整智能体工作流参见
skills/browserrig/SKILL.md。

BrowserRig 衍生自采用 MIT 许可证的
anomalyco/browser-control
项目。上游版权和许可证声明保留在本仓库中。