anomalyco/browser-control

Browser Control – 一个让 AI 代理通过 Playwright 控制您真实 Chromium 浏览器的桥梁

它是什么

• 一个轻量级的 Node.js 驱动程序，运行一个本地 relay 和一个浏览器扩展程序。中继接收来自 AI 编码代理（或 CLI）的 Playwright 代码片段，并在用户现有的浏览器配置文件中执行它们——保留已登录的会话、Cookie、扩展程序等。
• 该项目不包含 LLM；它仅提供管道，以便外部代理可以安全地发出浏览器命令。

核心概念

概念	功能
Relay	一个微型本地服务器 (127.0.0.1:19989)，通过 Chrome DevTools Protocol (CDP) 与扩展程序通信，并按需运行 Playwright 代码。
Extension	npm 包中附带的未打包 Chrome/Brave/Edge/Arc 扩展程序。它授予中继控制标签页、捕获媒体和读取 Cookie 所需的权限。
Session	一个持久化沙箱，包含单个标签页、JavaScript 状态 (window) 和一个微型日志 (~/.browser-control/sessions/<id>/journal.jsonl)。会话在 CLI 调用之间保持存活；您可以接管已打开的用户标签页。
Skill / MCP	可选的包装器，将驱动程序作为一种 工具 暴露给理解 OpenAI 风格“技能”或 Multi-Client-Protocol (MCP) 的代理。
Effect client	一个 TypeScript 库 (BrowserControlClient)，允许程序通过浏览器进行经过身份验证的 fetch 调用，而无需运行任意 Playwright 脚本。

主要功能

• 运行任意 Playwright 代码片段 (browser-control execute …)。
• 安全地检查页面，使用 snapshot()、ariaSnapshot()、screenshotWithLabels() 以及在 DOM 变更后依然有效的元素引用等辅助工具。
• 人工介入 (handoff(), demonstrate())，用于处理验证码、双重验证 (2FA) 或任何需要人工参与的步骤。
• 只读会话，在阻止输入命令的同时允许导航和截图。
• 录制 – 捕获标签页的 WebM/MP4 视频，或用于调试的轻量级“飞行记录器”缓冲区。
• 网络捕获 – 启动 HAR 风格的捕获 (browser-control network start …)，该功能会屏蔽敏感信息并写入安全的 HAR 文件。
• 密钥处理 – secrets 子命令将屏蔽后的值存储在受保护的配置文件中，并允许下游 CLI 工具在从不查看原始令牌的情况下运行。

安装与首次运行

1. Node ≥ 22.19 和 Chromium 系列浏览器。
2. 全局安装：npm install -g @opencode-ai/browser-control (添加 browser-control 和 browser-control-mcp)。
3. 通过 chrome://extensions → 开发者模式 → 加载已解压的扩展程序，加载位于 $(npm root -g)/@opencode-ai/browser-control/extension/dist 的未打包扩展程序。
4. 使用简单命令测试，例如：

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

   CLI 会打印一个会话 ID 和一个您可以重复使用的延续命令。

代理集成

• OpenCode 插件 – opencode plugin add @opencode-ai/browser-control 注册一个 @browser 技能，自动连接该技能、MCP 入口点和扩展目录。
• 手动技能 – npx skills add anomalyco/browser-control --skill browser-control -g 使相同的工作流可供任何使用 skills CLI 的代理使用。
• MCP – 如果您的代理偏好 MCP 协议，请将本地 MCP 条目 (browser-control-mcp) 添加到其工具列表中。

典型工作流

1. 创建/接管会话 (browser-control session new myapp 或 session adopt …)。
2. 执行 Playwright (browser-control execute …)。
3. 检查 (snapshot(), ref(), ariaSnapshot())。
4. 人工步骤 (await handoff("Solve CAPTCHA"))。
5. 可选录制 或 捕获网络 以供后续回放。
6. 关闭 (browser-control session delete myapp)。

安全与限制

• 该扩展程序需要广泛的权限 (debugger, tabCapture 等)，并以用户的完整浏览器配置文件运行 – 它仅供受信任的本地使用。
• 破坏性的 CDP 命令（清除 Cookie、关闭整个浏览器）被中继拦截。
• 该扩展程序目前以未打包形式分发；计划发布 Chrome Web Store 版本，但目前尚不可用。
• 不捆绑 Playwright 二进制文件 – 中继要求宿主浏览器已安装。
• 视频录制需要在 PATH 中安装 ffmpeg，且在 CDP 模式下无法捕获音频。
• 该驱动程序不提供远程、经过身份验证的中继；它必须与浏览器在同一台机器上运行。

常用命令

• browser-control doctor – 检查安装状态。
• browser-control status – 显示扩展程序是否已连接。
• browser-control serve – 在前台运行中继以进行调试。
• browser-control journal --session <id> – 查看 JSON 行格式的活动日志。
• browser-control secrets … – 管理用于生成客户端的屏蔽密钥值。

总结 Browser Control 是一个实用的开源桥梁，允许 AI 编码代理（或任何自动化脚本）通过 Playwright 与真实用户配置文件的浏览器进行交互，同时为开发人员提供用于检查、人工介入、录制和安全网络捕获的细粒度控制。它是 AI 代理自动化领域中一个真正的工具，而不仅仅是一个教程或精选列表。