Loading... # 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. 架构设计 项目采用客户端-守护进程架构，通过进程间通信实现高效的浏览器操作。 ```mermaid 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 ```  ## 2. 组件说明 ### A. Rust CLI 层 - 职责：命令行参数解析、与守护进程通信 - 优势：原生二进制性能、快速启动、跨平台支持 - 回退机制：当二进制不可用时自动降级到 Node.js ### B. Node.js Daemon 层 - 职责：管理 Playwright 浏览器实例、处理自动化任务 - 持久性：首次启动后保持运行，提高后续操作响应速度 - 浏览器引擎：默认 Chromium，支持 Firefox 和 WebKit ### C. 持久化层 - 存储位置：~/tmp/agent-browser/ - 内容：Cookies、localStorage、sessionStorage、认证状态 - 作用：跨命令保持登录状态、用户偏好设置 ## 3. 交互流程 ```mermaid 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: 操作成功 ```  # 三、核心功能 ## 1. 元素引用系统 ### A. Snapshot 机制 Snapshot 命令生成页面的可访问树，为每个元素分配确定性引用（ref）。 ```bash 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. 使用方式 ```bash agent-browser click @e2 # 点击按钮 agent-browser fill @e3 "test@example.com" # 填写文本框 agent-browser get text @e1 # 获取标题文本 ``` ## 2. 多会话管理 ### A. 会话隔离 每个会话拥有独立的浏览器实例、Cookie、导航历史和认证状态。 ```bash # 不同会话 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. 会话操作 ```bash agent-browser session list # 列出活动会话 agent-browser session # 显示当前会话 ``` ## 3. 用户数据持久化 ### A. 存储管理 ```bash # 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. 状态保存与加载 ```bash agent-browser state save path.json # 保存认证状态 agent-browser state load path.json # 加载认证状态 ``` ## 4. 选择器类型 ### A. Ref 选择器（推荐） ```bash agent-browser click @e2 agent-browser fill @e3 "text" ``` ### B. CSS 选择器 ```bash agent-browser click "#id" agent-browser click ".class" agent-browser click "div > button" ``` ### C. 语义定位器 ```bash 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. 请求拦截 ```bash # 阻止请求 agent-browser network route "**/*.{png,jpg}" --abort # 模拟响应 agent-browser network route "/api/**" --body '{"mock": true}' # 移除路由 agent-browser network unroute "/api/**" ``` ### B. 请求查看 ```bash agent-browser network requests # 查看所有请求 agent-browser network requests --filter api # 过滤请求 ``` ## 6. 浏览器设置 ### A. 视口和设备 ```bash agent-browser set viewport 1920 1080 agent-browser set device "iPhone 14" ``` ### B. 地理位置和网络 ```bash agent-browser set geo 37.7749 -122.4194 agent-browser set offline on ``` ### C. HTTP 认证 ```bash agent-browser set credentials user pass agent-browser set headers '{"Authorization": "Bearer token"}' ``` # 四、高级特性 ## 1. 系统浏览器支持 ### A. Google 登录场景 Google 会屏蔽 Playwright 捆绑的 Chrome for Testing 浏览器。 ```bash # 首次使用系统 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 生效，不会泄露到其他域名。 ```bash # 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. 安装方式 ```bash 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 使用 ```bash # 通过标志 agent-browser --executable-path /path/to/chromium open example.com # 通过环境变量 AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com ``` ### C. 无服务器示例 ```javascript 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. 简单指令模式 最简单的方式是直接告诉代理使用它： ```text 使用 agent-browser 测试登录流程。运行 agent-browser --help 查看可用命令。 ``` ## 2. 项目指令配置 将以下内容添加到项目或全局指令文件： ```markdown ## 浏览器自动化 使用 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 提供更丰富的上下文： ```bash cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/ ``` 或下载： ```bash 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 ARM64 | Rust CLI | Node.js | | macOS x64 | Rust CLI | Node.js | | Linux ARM64 | Rust CLI | Node.js | | Linux x64 | Rust CLI | Node.js | | Windows x64 | Rust CLI | Node.js | # 七、安装与使用 ## 1. npm 安装（推荐） ```bash npm install -g agent-browser agent-browser install # 下载 Chromium ``` ## 2. 从源码构建 ```bash 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 上安装系统依赖： ```bash agent-browser install --with-deps # 或手动：npx playwright install-deps chromium ``` ## 4. 快速开始 ```bash 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-browser | BUNotesAI fork | |------|---------------------|----------------| | Rust CLI | 支持 | 支持 | | 用户数据持久化 | 有限 | 完整支持 | | 系统浏览器 | 有限 | 增强 channel 标志 | | Patchright | 无 | 专用分支 | | 补丁管理 | 无 | patches/ 目录 | ## 2. 与其他工具对比 | 工具 | 语言 | AI 优化 | 持久化 | 性能 | |------|------|---------|--------|------| | agent-browser | Rust+Node | 是 | 是 | 高 | | Puppeteer | Node.js | 否 | 手动 | 中 | | Playwright | Node.js | 部分 | 手动 | 中 | | Selenium | 多语言 | 否 | 手动 | 低 | # 九、最佳实践 ## 1. AI 代理工作流 ```bash # 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. 会话管理 ```bash # 为不同任务使用独立会话 agent-browser --session task1 open site1.com agent-browser --session task2 open site2.com ``` ## 3. 调试技巧 ```bash # 使用 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 | ## 从上游升级 ```bash # 添加上游远程（仅首次） 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](https://github.com/BUNotesAI/agent-browser-userdata) 2. [vercel-labs/agent-browser - GitHub](https://github.com/vercel-labs/agent-browser) 最后修改：2026 年 01 月 15 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏