Agent Browser Userdata 浏览器自动化工具技术分析

一、概述

1. 简介

A. 是什么

Agent Browser Userdata 是一个专为 AI 代理设计的无头浏览器自动化命令行工具。该项目从 Vercel Labs 的 agent-browser 项目 fork 而来，核心特点是采用 Rust CLI 与 Node.js Daemon 的混合架构，提供高性能的浏览器自动化能力，并增加了用户数据持久化支持。

B. 为什么重要

  • AI 代理需要可靠的浏览器操作能力来实现复杂的网页交互任务
  • 传统浏览器自动化工具在 AI 场景下存在性能和易用性问题
  • 用户数据持久化是 AI 代理长期运行和会话管理的关键需求
  • 反爬虫检测是自动化工具面临的重大挑战

C. 解决什么问题

  • 提供专为 LLM 优化的元素引用机制
  • 实现跨命令的会话持久化和状态保持
  • 支持多种浏览器引擎和自定义可执行文件
  • 提供绕过反爬虫检测的 Patchright 分支

2. 核心特性

  • 混合架构：Rust CLI 提供快速命令解析，Node.js Daemon 管理 Playwright
  • 元素引用系统：通过 snapshot 获取的可访问树使用确定性引用
  • 多会话支持：隔离的浏览器实例和用户数据
  • 持久化存储：Cookies、localStorage、认证状态自动保存
  • 灵活部署：支持系统浏览器、自定义构建、无服务器环境

二、系统架构

1. 架构设计

项目采用客户端-守护进程架构，通过进程间通信实现高效的浏览器操作。

graph TB
    subgraph CLI[用户接口层]
        CMD[agent-browser 命令]
    end
    subgraph Rust[Rust CLI 解析器]
        PARSE[命令解析]
        IPC[进程间通信]
    end
    subgraph Daemon[Node.js Daemon 守护进程]
        PM[进程管理器]
        PW[Playwright/Patchright]
        BR[Chromium 浏览器]
    end
    subgraph Data[持久化层]
        UD[用户数据目录]
        CK[Cookies/Storage]
        SS[认证状态]
    end
    CMD --> PARSE
    PARSE --> IPC
    IPC --> PM
    PM --> PW
    PW --> BR
    PM <--> UD
    UD --> CK
    UD --> SS

agent-browser 架构图

2. 组件说明

A. Rust CLI 层

  • 职责：命令行参数解析、与守护进程通信
  • 优势：原生二进制性能、快速启动、跨平台支持
  • 回退机制：当二进制不可用时自动降级到 Node.js

B. Node.js Daemon 层

  • 职责：管理 Playwright 浏览器实例、处理自动化任务
  • 持久性：首次启动后保持运行，提高后续操作响应速度
  • 浏览器引擎：默认 Chromium，支持 Firefox 和 WebKit

C. 持久化层

  • 存储位置：~/tmp/agent-browser/
  • 内容：Cookies、localStorage、sessionStorage、认证状态
  • 作用：跨命令保持登录状态、用户偏好设置

3. 交互流程

sequenceDiagram
    participant AI as AI Agent
    participant CLI as agent-browser CLI
    participant Daemon as Node.js Daemon
    participant BW as Chromium

    AI->>CLI: agent-browser open url.com
    CLI->>Daemon: IPC 调用
    Daemon->>BW: 启动浏览器
    BW-->>Daemon: 已启动
    Daemon-->>CLI: 返回结果
    CLI-->>AI: 命令完成

    AI->>CLI: agent-browser snapshot
    CLI->>Daemon: 获取快照
    Daemon->>BW: 读取可访问树
    BW-->>Daemon: 返回元素树
    Daemon-->>CLI: 返回快照数据
    CLI-->>AI: 可访问树+refs

    AI->>CLI: agent-browser click @e2
    CLI->>Daemon: 点击操作
    Daemon->>BW: 执行点击
    BW-->>Daemon: 操作完成
    Daemon-->>CLI: 返回结果
    CLI-->>AI: 操作成功

agent-browser 交互时序图

三、核心功能

1. 元素引用系统

A. Snapshot 机制

Snapshot 命令生成页面的可访问树，为每个元素分配确定性引用（ref）。

agent-browser snapshot
# 输出：
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

B. 引用优势

  • 确定性：ref 指向快照中的精确元素
  • 高效：无需重新查询 DOM
  • AI 友好：快照+引用工作流对 LLM 最优

C. 使用方式

agent-browser click @e2                   # 点击按钮
agent-browser fill @e3 "test@example.com" # 填写文本框
agent-browser get text @e1                # 获取标题文本

2. 多会话管理

A. 会话隔离

每个会话拥有独立的浏览器实例、Cookie、导航历史和认证状态。

# 不同会话
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 通过环境变量
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

B. 会话操作

agent-browser session list    # 列出活动会话
agent-browser session         # 显示当前会话

3. 用户数据持久化

A. 存储管理

# Cookies 操作
agent-browser cookies                 # 获取所有 Cookie
agent-browser cookies set name value  # 设置 Cookie
agent-browser cookies clear           # 清除 Cookie

# Storage 操作
agent-browser storage local           # 获取 localStorage
agent-browser storage local key       # 获取特定键
agent-browser storage local set k v   # 设置值
agent-browser storage local clear     # 清除所有

B. 状态保存与加载

agent-browser state save path.json    # 保存认证状态
agent-browser state load path.json    # 加载认证状态

4. 选择器类型

A. Ref 选择器（推荐）

agent-browser click @e2
agent-browser fill @e3 "text"

B. CSS 选择器

agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"

C. 语义定位器

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
agent-browser find text "Sign In" click

5. 网络拦截

A. 请求拦截

# 阻止请求
agent-browser network route "**/*.{png,jpg}" --abort

# 模拟响应
agent-browser network route "/api/**" --body '{"mock": true}'

# 移除路由
agent-browser network unroute "/api/**"

B. 请求查看

agent-browser network requests                 # 查看所有请求
agent-browser network requests --filter api    # 过滤请求

6. 浏览器设置

A. 视口和设备

agent-browser set viewport 1920 1080
agent-browser set device "iPhone 14"

B. 地理位置和网络

agent-browser set geo 37.7749 -122.4194
agent-browser set offline on

C. HTTP 认证

agent-browser set credentials user pass
agent-browser set headers '{"Authorization": "Bearer token"}'

四、高级特性

1. 系统浏览器支持

A. Google 登录场景

Google 会屏蔽 Playwright 捆绑的 Chrome for Testing 浏览器。

# 首次使用系统 Chrome 登录（需要 headed 模式）
agent-browser --channel chrome --headed open https://accounts.google.com
# 在浏览器窗口中手动完成登录
agent-browser close

# 之后登录状态保存在 ~/tmp/agent-browser/，可使用 headless
agent-browser open https://mail.google.com  # 已登录！

B. 通道选项

  • chrome：系统 Chrome
  • msedge：Microsoft Edge
  • chrome-beta：Chrome 测试版

2. 认证会话管理

A. 作用域 Headers

Headers 仅对指定的 origin 生效，不会泄露到其他域名。

# Headers 仅对 api.example.com 生效
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# 对 api.example.com 的请求包含 auth header
agent-browser snapshot -i --json
agent-browser click @e2

# 导航到其他域名 - 不发送 headers（安全！）
agent-browser open other-site.com

B. 应用场景

  • 跳过登录流程：通过 Headers 认证而非 UI
  • 切换用户：使用不同 token 启动新会话
  • API 测试：直接访问受保护的端点

3. Patchright 分支

A. 分支介绍

agent-browser-with-userdata-patchright 分支用 Patchright 替换了 Playwright。Patchright 是 Playwright 的修补版本，帮助绕过机器人检测。

B. 适用场景

遇到以下问题时使用此分支：

  • 网站屏蔽自动化工具
  • 需要更隐蔽的浏览器指纹
  • 标准 Playwright 被检测

C. 安装方式

git clone -b agent-browser-with-userdata-patchright https://github.com/BUNotesAI/agent-browser-userdata
cd agent-browser-userdata
pnpm install
pnpm build

4. 自定义浏览器可执行文件

A. 使用场景

  • 无服务器部署：使用轻量级 Chromium 构建（约 50MB vs 684MB）
  • 系统浏览器：使用现有的 Chrome/Chromium 安装
  • 自定义构建：使用修改过的浏览器版本

B. CLI 使用

# 通过标志
agent-browser --executable-path /path/to/chromium open example.com

# 通过环境变量
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

C. 无服务器示例

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
}

五、与 AI 代理集成

1. 简单指令模式

最简单的方式是直接告诉代理使用它：

使用 agent-browser 测试登录流程。运行 agent-browser --help 查看可用命令。

2. 项目指令配置

将以下内容添加到项目或全局指令文件：

## 浏览器自动化

使用 agent-browser 进行网页自动化。运行 agent-browser --help 查看所有命令。

核心工作流：
1. agent-browser open <url> - 导航到页面
2. agent-browser snapshot -i - 获取带引用的交互元素（@e1、@e2）
3. agent-browser click @e1 / fill @e2 "text" - 使用引用交互
4. 页面变化后重新快照

3. Claude Code 技能

为 Claude Code 提供更丰富的上下文：

cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/

或下载：

mkdir -p .claude/skills/agent-browser
curl -o .claude/skills/agent-browser/SKILL.md \
  https://raw.githubusercontent.com/BUNotesAI/agent-browser-userdata/main/skills/agent-browser/SKILL.md

六、平台支持

平台原生二进制回退方案
macOS ARM64Rust CLINode.js
macOS x64Rust CLINode.js
Linux ARM64Rust CLINode.js
Linux x64Rust CLINode.js
Windows x64Rust CLINode.js

七、安装与使用

1. npm 安装（推荐）

npm install -g agent-browser
agent-browser install  # 下载 Chromium

2. 从源码构建

git clone https://github.com/BUNotesAI/agent-browser-userdata
cd agent-browser-userdata
pnpm install
pnpm build
pnpm build:native  # 构建 Rust CLI
./bin/agent-browser install
pnpm link --global  # 全局安装

3. Linux 依赖

在 Linux 上安装系统依赖：

agent-browser install --with-deps
# 或手动：npx playwright install-deps chromium

4. 快速开始

agent-browser open example.com
agent-browser snapshot                    # 获取带引用的可访问树
agent-browser click @e2                   # 通过引用点击
agent-browser fill @e3 "test@example.com" # 通过引用填写
agent-browser get text @e1                # 通过引用获取文本
agent-browser screenshot page.png
agent-browser close

八、技术对比

1. 与原项目对比

特性Vercel agent-browserBUNotesAI fork
Rust CLI支持支持
用户数据持久化有限完整支持
系统浏览器有限增强 channel 标志
Patchright无专用分支
补丁管理无patches/ 目录

2. 与其他工具对比

工具语言AI 优化持久化性能
agent-browserRust+Node是是高
PuppeteerNode.js否手动中
PlaywrightNode.js部分手动中
Selenium多语言否手动低

九、最佳实践

1. AI 代理工作流

# 1. 导航并获取快照
agent-browser open example.com
agent-browser snapshot -i --json   # AI 解析树和引用

# 2. AI 从快照中识别目标引用
# 3. 使用引用执行操作
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. 页面变化后获取新快照
agent-browser snapshot -i --json

2. 会话管理

# 为不同任务使用独立会话
agent-browser --session task1 open site1.com
agent-browser --session task2 open site2.com

3. 调试技巧

# 使用 headed 模式查看浏览器操作
agent-browser --headed open example.com

# 记录追踪
agent-browser trace start trace.zip
# 执行操作
agent-browser trace stop

# 查看控制台消息
agent-browser console

十、项目结构

agent-browser-userdata/
├── bin/                    # 可执行文件
├── cli/                    # CLI 源码
├── src/                    # Node.js 源码
├── patches/                # 补丁文件
├── skills/agent-browser/   # Claude Code 技能
├── docker/                 # Docker 配置
├── scripts/                # 构建脚本
└── test/                   # 测试文件

十一、补丁管理

项目维护 patches/ 目录中的补丁文件，便于在上游升级后重新应用：

补丁描述
0001添加 --channel 标志支持系统 Chrome
0002更新 channel 标志文档
0003更新 README 文档
0004添加 Patchright 分支文档
0005迁移到 Patchright

从上游升级

# 添加上游远程（仅首次）
git remote add upstream https://github.com/vercel-labs/agent-browser.git

# 获取并变基到上游
git fetch upstream
git checkout main
git rebase upstream/main

# 应用补丁
git am patches/*.patch

参考资料

  1. BUNotesAI/agent-browser-userdata - GitHub
  2. vercel-labs/agent-browser - GitHub
最后修改：2026 年 01 月 15 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏