chrome-agent-browser

本地 AI Agent 原生浏览器自动化工具包

保持日常 Chrome 的完整登录态与 Cookie，支持 Claude Code / Cursor / Codex / Pi Agent 等通用 MCP 调度， 并提供 Pi Agent 原生工具扩展支持。

目录

• 一、核心定位与特性

• 二、系统程序架构图

• 三、全链路数据流转图

• 四、引导页面怎么看

• 五、快速安装与环境准备

• 六、Agent 接入与使用指南

  • 模式 A：作为 MCP 服务供通用 Agent 调用

  • 模式 B：Pi Coding Agent 原生扩展调用

• 七、23 个核心工具详解

• 八、L1 / L2 自适应执行机制

• 九、多 Agent 会话隔离与视觉幕帘

• 十、四大进阶交互能力

• 十一、安全加固与生产级守护

• 十二、常用 CLI 命令速查

• 十三、常见排错与诊断

• 十四、开源合规声明

Related MCP server: mcp-browser-agent

一、核心定位与特性

1. 日常真实环境与登录态：直接操控你日常使用的 Chrome，无需创建空白的自动化 profile，无需重新扫码登录，免受验证码困扰。

2. 免改启动参数与远程端口：无需开启 --remote-debugging-port，免改浏览器快捷方式，装上解压扩展即可建立连接。

3. 双重接入形态：

   • MCP 模式：通过标准 stdio JSON-RPC 暴露给 Claude Code、Cursor、Codex CLI、Gemini CLI 等；

   • Pi 原生模式：通过一键安装生成 agent_browser 原生工具扩展，零适配直连。

4. L1 / L2 双层自适应穿透执行：

   • 默认使用轻量 DOM 级合成事件（L1），速度极快；

   • 遇到 isTrusted 物理事件校验、Monaco/CodeMirror 富文本、文件上传或后台截图时，无缝升级调用 chrome.debugger 原生 CDP（L2）。

5. 多会话槽（Slot）隔离防撞车：多个 Agent 并发操作时自动分配独立彩色标签槽与标签组，防止相互踩踏。

6. 视觉幕帘：Agent 截图时会自动拉下视觉幕帘隐藏高亮边框和调试面板，避免模型产生“幻觉”。

7. 全本地安全链路：单例桥仅监听 127.0.0.1，严格校验 chrome-extension:// Origin 头，绝不让恶意外部网页向控制链路渗透。

8. 全页面长截图与浮层防重叠：支持 fullPage: true 完整截取长网页，自动去重 fixed/sticky 导航条与底部浮动栏，带尺寸约束防 OOM 内存爆炸。

9. 显式标签页借用与归还生命周期：支持 tabs(action: "borrow" | "return")，操作用户已有标签前弹出授权浮层，任务完成后干净归还并解除控制。

10. 复杂交互增强（Hover 预探测 + Canvas 图像坐标点击）：快照自动打标折叠菜单与 Canvas，支持主动探测二级下拉项；截图返回 captureId，支持按图像像素坐标发起物理点击。

11. 规范化页内 Human-in-the-Loop 浮层：触发验证码、扫码登录或支付时，在页面中央置顶弹出毛玻璃提示条，且不阻挡底层页面交互，用户完成后点击秒级恢复。

二、系统程序架构图

高清原图：docs/diagrams/agent-browser-architecture.png · 可交互 HTML 版：docs/diagrams/agent-browser-architecture.html

四条信任/部署边界（Zone）：

图中高亮（Focal）节点为「单例桥」与「L2 CDP 引擎」——前者是全机唯一的路由与鉴权枢纽，后者是穿透强反爬站点的最终手段。

三、全链路数据流转图

高清原图：docs/diagrams/agent-browser-data-flow.png · 可交互 HTML 版：docs/diagrams/agent-browser-data-flow.html

四个阶段（Stage）与两条执行分支：

图例：实线为命令与数据管道；虚线为审计旁路（被动、并行落盘）；橙色为 L2 CDP 升级与真实事件路径；蓝色为 L1 合成事件与异步协作路径。

四、引导页面怎么看

项目中内置了精美的可视化离线图解安装说明书（src/guide.html），有以下 4 种查看方式：

方式 1：CLI 便捷命令（最推荐）

在项目目录下直接运行：

node src/cli.js guide

系统会自动调用默认浏览器秒级打开说明书页面。

方式 2：系统终端直接打开

• macOS：

  open src/guide.html

• Windows：

  start src/guide.html

• Linux：

  xdg-open src/guide.html

方式 3：自动安装流程触发

当你执行一键配置命令时：

node src/cli.js install

脚本在配置好各 Agent 的 MCP 设置后，会自动在浏览器中弹开该引导页。

方式 4：浏览器直接访问本地文件

在 Chrome 地址栏直接输入并回车：

file:///Users/zero/Desktop/agent-browser/src/guide.html

五、快速安装与环境准备

1. 基础环境

• Node.js ≥ 20.0.0

• Google Chrome 浏览器

2. 加载 Chrome 扩展（只需一次）

1. 打开 Chrome 浏览器，地址栏输入 chrome://extensions；

2. 开启右上角的**「开发者模式」**开关；

3. 点击左上角的**「加载已解压的扩展程序」**；

4. 选择当前项目的扩展目录：

   /Users/zero/Desktop/agent-browser/extension

5. 点击 Chrome 工具栏右上角拼图图标，将 chrome-agent-browser 固定在工具栏。

3. 一键配置本机 Agent

在项目根目录下运行：

node src/cli.js install

它会自动扫描本机已安装的 Agent（Claude Code / Codex / Cursor / Windsurf / Cline 等），并安全写入 MCP 配置（操作前会自动备份原配置文件）。

4. 连通性体检

运行体检命令：

node src/cli.js doctor

看到「配置目录正常」、「桥握手正常」、「Chrome 扩展在线」即表示全链路就绪！

六、双模使用指南

模式 A：作为 MCP 服务供通用 Agent 调用

安装完成后，在你的 Agent 客户端（如 Claude Code / Cursor）中直接用自然语言交流即可：

「帮我在 Chrome 里打开京东，搜索降噪耳机并把前 5 款的价格和评价拉下来」
「在当前打开的 CRM 后台里，帮我新建一个客户记录」
「把这篇排版好的文档发布到知乎草稿箱」

若手动给第三方客户端配置，在对应配置文件中的 mcpServers 节点添加：

{
  "mcpServers": {
    "chrome-agent-browser": {
      "command": "npx",
      "args": ["-y", "chrome-agent-browser", "mcp"]
    }
  }
}

（本地源码调试可使用 "command": "node", "args": ["<项目绝对路径>/src/cli.js", "mcp"]）

模式 B：Pi Coding Agent 原生扩展调用

运行 chrome-agent-browser install（或 node src/cli.js install）后，安装器会自动在 ~/.pi/agent/extensions/chrome-agent-browser.ts 生成原生工具定义。在 Pi 会话中即可直接使用：

// Pi Agent 对话中可直接调用 agent_browser 工具：
// action: 动作名，如 snapshot, click, type, tabs, wait, read_text, screenshot 等
// params: 动作入参对象，如 { tabId, ref, text }

例如在对话中输入：

“使用 agent_browser 打开 B 站并搜索小白测评”

Pi Agent 会调用 agent_browser(action="tabs", params={action:"new", url:"https://www.bilibili.com"})，并通过本地 Bridge 驱动正在运行的 Chrome。

七、23 个核心工具详解

八、L1 / L2 自适应执行机制

为同时兼顾**“轻量极速”与“穿透一切复杂反爬”**，系统内置了 L1/L2 双层自适应引擎：

                    发起操作 (如 click)
                            │
                            ▼
               [ L1 快速合成事件引擎派发 ]
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
       [ 检测到效果证据 ]           [ 零证据 / 静默失效 ]
       - DOM 节点发生改变           - 遇 isTrusted 物理事件校验
       - 页面发生跳转导航           - Monaco / 富文本编辑器内部状态未变
              │                           │
              ▼                           ▼
        立刻成功返回             [ 动态升级 L2 原生 CDP 调试器 ]
                             (Input.dispatchMouseEvent / dispatchKeyEvent)
                                          │
                                          ▼
                                   真实物理级动作落地

• L1 模式：基于 DOM 合成事件派发，零调试条干扰，速度快至几毫秒；

• L2 模式：基于 chrome.debugger，产生操作系统级真实物理事件，通过 isTrusted: true 校验。

九、多 Agent 会话隔离与视觉幕帘

• 独立彩虹槽位：每个 Agent 进程根据其 sessionId 哈希分配专属于它的颜色（14 色轮换）与 Chrome 标签组，受控页面会自动加上彩色边框与右下角状态胶囊；

• 截图幕帘（Stealth Mode）：当 Agent 发起 screenshot 截屏请求时，扩展会在捕获瞬间将所有自身绘制的边框、高亮框与驾驶舱完全隐藏，截取最真实的原始网页，截取完毕立即恢复，彻底杜绝模型把自身标记当成网页内容产生幻觉。

十、四大进阶交互能力

1. 工业级全页面长截图与浮层防穿帮

传统长截图滚动拼接时，页面固定的 position: fixed / sticky 导航条与悬浮底栏会在每屏截图中反复重印造成穿帮，且大尺寸 Canvas 极易触发浏览器像素上限造成崩溃。 chrome-agent-browser 引入了浮层抑制与流式长截取：

• 传 fullPage: true 时，自动测量文档完整尺寸，并动态设置 maxHeight（默认 16384px，防瀑布流 OOM）；

• 捕获期间自动调度内容脚本临时抑制悬浮条（首尾帧保留、中间帧去重），拍完毫秒级恢复；

• 截取成功后签发唯一的 captureId，并在 storage.session 中持久化记录缩放与视口基线。

2. 显式标签页借用与归还生命周期 (tab borrow / return)

为了彻底解决“Agent 在未经允许的情况下突然接管用户正在浏览的私人标签页”的突兀感：

• 申请借用 (action: "borrow")：Agent 需显式提供 tabId 与借用理由 reason，系统在目标页面顶部中央唤起高保真 BorrowConfirmationOverlay 授权浮层，用户点击【同意借用】后才正式纳入控制槽并记录原始位置；

• 任务归还 (action: "return")：任务完成后调用 return，扩展自动解除控制、恢复标签组并弹出轻量 Toast 提醒用户标签页已归还。

3. 复杂交互场景增强（Hover 预探测 + Canvas 图像坐标点击）

• Hover 自动识别与预探测：快照引擎自动识别带下拉菜单、aria-haspopup 的折叠触发器并标注 (hover first)；传入 probeHover: true 时，内容脚本会在后台毫秒级预检隐藏子菜单并提取展开项（如 [hover first: Mac | iPad | iPhone]），彻底解决大模型在折叠菜单前翻车的问题；

• Canvas 图像像素级物理点击：快照引擎自动识别 <canvas> 节点并打标 (visual:screenshot)。截屏后大模型可直接根据图片测出的实际像素坐标调用 click(captureId, imageX, imageY)，底层依据截图比例尺与设备像素比自动换算并在该点触发真实物理点击。

4. 规范化页内 Human-in-the-Loop 浮层 (HelpRequestOverlay)

当遇到滑块验证码、扫码登录、人脸核验或风控阻断时，调用 ask 工具：

• 受控页面顶部中央绝对居中弹出发光毛玻璃悬浮条（HelpRequestOverlay），带有倒计时、清晰步骤提示与操作指引；

• 针对支付/敏感动作自动切换危险红警示主题（🚨 敏感操作/支付确认）；

• 非阻塞交互：浮层采用穿透式设计，底层网页的滑块、输入框、二维码 100% 保持正常可点击/可滑动，用户完成后点击【我已完成】即可无缝交接恢复。

十一、安全加固与生产级守护

1. 扩展白名单鉴权 (KNOWN_EXTENSION_IDS)：桥服务端在 verifyClient 与 hello 阶段严格校验 Origin，仅放行本地固定 Key 派生 ID（ljnomddomgifjdddbefdjmgekhdiijnn）以及 Chrome Web Store 正式上架 ID，彻底防御恶意扩展渗透控制流；

2. 端口顺延自愈：桥服务支持 8899 -> 8900 -> 8901 -> 8902 -> 8903 范围内的端口冲突自愈顺延，并与扩展的双腿并发竞速探测机制完美契合；

3. 多 Chrome 实例隔离：全局受控槽与标签组按实例 ID（activeTabId_${iid}）实现实例级本地隔离，防止 headless 自动化实例与日常工作主浏览器发生标签踩踏；

4. 反爬与隐匿性加固：net-hook.js 的 __abNet 采用不可枚举属性保护，所有挂钩函数（fetch, open, send）的 .toString() 均伪装为原生 [native code]，无惧反爬检测。

十二、常用 CLI 命令与构建流水速查

# 打开图形化安装说明书
node src/cli.js guide

# 诊断本机连通性状态
node src/cli.js doctor

# 自动配置本机各 Agent
node src/cli.js install

# 仅查看配置计划（不实际写入）
node src/cli.js install --dry-run

# 显示扩展解压加载目录路径
node src/cli.js extension

# 在访达/资源管理器中直接选中并定位扩展目录
node src/cli.js extension --reveal

# 查看最近的本地浏览器操作审计记录
node src/cli.js audit -n 30

# 查看真实 Agent 的操作统计与回合数分析
node src/cli.js audit --stats --days 7

# 启动本地单例桥（调试底层日志使用）
node src/cli.js bridge

# 运行全量单元与协议测试（122 项）
npm test

# 运行真实 Chrome 自动化端到端套件（93 项）
npm run test:live

# 全量构建与分发打包（版本一致性核验、生成 Web Store 剥离 key 的 zip、校验 npm 分发清单）
npm run build
# 或
npm run pack

十三、常见排错与诊断

1. 运行 doctor 提示“Chrome 扩展这会儿没连着桥”：

   • 检查 Chrome 是否已启动；

   • 检查 chrome://extensions 中 chrome-agent-browser 扩展是否开启；

   • 点击浏览器工具栏的 chrome-agent-browser 图标，点击弹窗中的「重连」按钮。

2. 需要 L2 真实物理模式时提示权限未开：

   • 点击工具栏 chrome-agent-browser 扩展图标，在弹窗中将「高保真模式」开启即可。

3. 自研服务提示端口冲突：

   • 本地桥默认监听 8899 端口，扩展会在 8899–8903 范围进行并发探测。若 8899 被其它服务占用，桥可指定范围内可用端口（如 8900），扩展将自动连接。

4. 自定义测试目录：

   • 支持通过 export CHROME_AGENT_BROWSER_HOME=/tmp/cab_home 将配置与审计日志隔离至临时目录。

十四、开源合规声明

本项目采用 MIT License 开源，详见 LICENSE。