概述

agent-browser 是由 Vercel Labs 开发的高性能浏览器自动化工具，采用 Rust 原生实现，不依赖 Node.js 包装层。它通过 Chrome DevTools Protocol (CDP) 直接控制 Chrome/Chromium 浏览器，提供无障碍树快照（Accessibility Tree Snapshot）技术和元素引用系统，实现可靠的浏览器交互能力。资料来源：skill-data/core/references/snapshot-refs.md

核心特性

技术架构

资料来源：AGENTS.md:43-46

跨平台兼容性

agent-browser 可与任意 AI Agent 配合使用，包括 Cursor、Claude Code、Codex、Continue、Windsurf 等主流工具。它提供了标准化的 CLI 接口，使 AI Agent 能够通过自然语言指令控制浏览器完成复杂任务。资料来源：skills/agent-browser/SKILL.md:15-19

系统架构

架构组件

graph TD
    A[AI Agent] --> B[agent-browser CLI]
    B --> C[Browser Automation Daemon]
    C --> D[CDP Client]
    D --> E[Chrome/Chromium]
    
    C --> F[Snapshot Engine]
    C --> G[State Manager]
    C --> H[React DevTools Hook]
    
    F --> I[Accessibility Tree]
    G --> J[Session Storage]
    G --> K[Auth Vault]
    
    L[Dashboard] --> C
    L --> M[Extensions Panel]
    L --> N[Network Panel]

核心模块

项目的核心代码位于 cli/src/native/ 目录下，包含以下关键模块：

资料来源：AGENTS.md:43

命令体系

核心命令分类

agent-browser 提供模块化的命令体系，涵盖浏览器操作的各个方面：

graph TD
    A[agent-browser] --> B[导航命令]
    A --> C[元素交互]
    A --> D[浏览器设置]
    A --> E[网络控制]
    A --> F[存储管理]
    A --> G[React工具]
    
    B --> B1[open/goto]
    B --> B2[back/forward]
    B --> B3[reload/pushstate]
    
    C --> C1[click/tap]
    C --> C2[fill/setvalue]
    C --> C3[snapshot/innertext]
    C --> C4[find/highlight]
    
    D --> D1[viewport/device]
    D --> D2[timezone/locale]
    D --> D3[geolocation/permissions]

常用命令速查

资料来源：cli/src/output.rs:1-30

元素引用系统

快照与引用机制

agent-browser 的核心创新在于其无障碍树快照和元素引用系统。用户必须先获取快照才能进行元素交互，确保引用始终有效：

# 正确流程
agent-browser open https://example.com
agent-browser snapshot -i          # 先获取引用
agent-browser click @e1            # 使用引用

# 错误流程
agent-browser open https://example.com
agent-browser click @e1            # 引用尚未存在！

资料来源：skill-data/core/references/snapshot-refs.md:1-15

引用格式

引用格式清晰展示元素的关键属性：

@e1 [button] "Submit"                    # 按钮元素
@e2 [input type="email"]                 # 邮箱输入框
@e3 [div role="article"] "标题文本"       # 文章容器

专精技能

技能体系架构

graph LR
    A[agent-browser skills] --> B[core]
    A --> C[electron]
    A --> D[slack]
    A --> E[dogfood]
    A --> F[vercel-sandbox]
    A --> G[agentcore]

技能说明

资料来源：skills/agent-browser/SKILL.md:5-25

React 开发者工具

React 渲染分析

agent-browser 集成了 React 开发者工具，能够分析 React 应用的渲染状态和性能瓶颈：

// React 挂起状态类型权重
pub enum SuspendType {
    ClientHook => 7,      // 最高优先级
    RequestApi => 6,
    ServerFetch => 5,
    Cache => 4,
    Stream => 3,
    Unknown => 2,
    Framework => 1,       // 最低优先级
}

阻塞组件识别

系统通过 BoundaryKind 分类识别阻塞渲染的组件类型：

资料来源：cli/src/native/react/suspense.rs:1-50

可观测性仪表板

Dashboard 功能

Dashboard 提供了完整的浏览器状态可视化界面：

graph TD
    A[Dashboard] --> B[Extensions Panel]
    A --> C[Network Panel]
    A --> D[Snapshot Display]
    A --> E[Step Indicators]
    
    B --> B1[Extension List]
    B --> B2[Extension Details]
    
    C --> C1[Request List]
    C --> C2[HAR Export]
    C --> C3[Request Details]

面板功能

资料来源：packages/dashboard/src/components/extensions-panel.tsx

安装与配置

安装命令

# 安装 agent-browser
agent-browser install

# Chrome 自动下载
# 从 Chrome for Testing 直接获取

预导航设置

支持在首次导航前进行环境配置：

agent-browser batch \
  '["open"]' \
  '["network","route","*","--abort","--resource-type","script"]' \
  '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
  '["navigate","http://localhost:3000/target"]'

资料来源：skill-data/core/references/commands.md:20-35

测试体系

测试类型

测试要求

• Chrome 必须已安装
• e2e 测试必须串行运行 (--test-threads=1) 以避免 Chrome 实例冲突

资料来源：AGENTS.md:52-62

发布流程

发布自动化

CI 系统在 PR 合并后自动执行以下操作：

1. 比较 package.json 版本与 npm 版本
2. 构建全部 7 个平台的二进制文件
3. 发布到 npm
4. 自动创建 GitHub Release

版本同步

pnpm version:sync

此命令会同步更新 cli/Cargo.toml、cli/Cargo.lock 和 packages/dashboard/package.json 中的版本号。

资料来源：AGENTS.md:15-35

使用场景

探索性测试与 QA

支持完整的操作录制和问题追踪：

agent-browser --session {SESSION} record start
# 执行测试步骤
agent-browser --session {SESSION} screenshot --annotate issue-{NNN}.png
agent-browser --session {SESSION} record stop

Slack 工作区自动化

针对 Slack 的专业技能支持消息监控、反应追踪和搜索功能：

agent-browser snapshot --json > conversation.json
agent-browser click @e_reaction_button
agent-browser screenshot reactions.png

资料来源：skill-data/dogfood/SKILL.md:50-70

技术栈总结

graph TD
    A[agent-browser] --> B[Rust Core]
    A --> C[TypeScript Dashboard]
    A --> D[React Components]
    A --> E[Node.js CLI Wrapper]
    
    B --> F[CDP Protocol]
    B --> G[Browser Automation]
    B --> H[React DevTools]
    
    C --> I[shadcn/ui]
    C --> J[Tailwind CSS]
    
    D --> K[Next.js]

概述

agent-browser 是一个基于 Rust 的浏览器自动化工具，通过命令行界面和可视化仪表盘提供对浏览器的远程控制能力。该项目采用客户端-守护进程架构，支持 Chrome 和 Lightpanda 两种渲染引擎，并提供丰富的交互 API 用于网页自动化任务。

架构的核心设计理念是将浏览器控制逻辑封装在 Rust 原生守护进程中，通过 CLI 命令或 Web 仪表盘与之通信，实现高效、可扩展的浏览器自动化解决方案。

资料来源：AGENTS.md

概述

agent-browser 是一个基于 Rust 原生构建的浏览器自动化 CLI 工具，为 AI 代理（Cursor、Claude Code、Codex、Continue、Windsurf 等）提供浏览器控制能力。CLI 命令参考涵盖了所有可通过命令行执行的原子操作，包括元素交互、状态查询、浏览器设置、网络控制等功能模块。

该工具通过 Chrome DevTools Protocol (CDP) 实现浏览器控制，不依赖 Playwright 或 Puppeteer，执行效率高且资源占用低。 资料来源：skills/agent-browser/SKILL.md

命令架构

CLI 命令采用统一的解析-分发架构，将用户输入转换为对应的原生处理器执行。

graph TD
    A[CLI 输入] --> B[commands.rs 命令解析]
    B --> C{命令类型}
    C -->|定位命令| D[find 命令解析]
    C -->|动作命令| E[actions.rs 动作分发]
    C -->|设置命令| F[flags.rs 标志处理]
    
    D --> G[role/text/label/placeholder/alt/title/testid/first/last]
    E --> H[click/tap/fill/type/highlight 等]
    F --> I[--annotate/--color-scheme/--download-path 等]
    
    G --> J[原生 CDP 调用]
    H --> J
    I --> J

核心命令分类

元素定位命令

元素定位命令用于通过多种策略查找 DOM 元素，并可指定后续操作。

默认操作：若未指定操作，默认为 click。 资料来源：cli/src/commands.rs:位置 1

元素交互命令

交互命令通过 actions.rs 中的处理器执行具体浏览器操作。

资料来源：cli/src/native/actions.rs:1-20

状态查询命令

用于检查元素的各种状态属性。

使用格式：agent-browser is <what> <selector> 资料来源：cli/src/output.rs

浏览器导航命令

快照与引用系统

快照命令生成可访问性树，包含元素引用（ref）用于后续交互。

agent-browser snapshot -i          # 生成带引用的快照
agent-browser snapshot @e5         # 快照特定区域
agent-browser snapshot --json      # 输出 JSON 格式

引用格式说明：

@e1 [tag type="value"] "text content" placeholder="hint"
│    │   │             │               │
│    │   │             │               └─ 额外属性
│    │   │             └─ 可见文本
│    │   └─ 关键属性
│    └─ HTML 标签名
└─ 唯一引用 ID

常见模式示例：

资料来源：skill-data/core/references/snapshot-refs.md

元素查找命令

查找命令用于定位元素并执行操作：

agent-browser find <locator> <value> <action> [text]

参数说明：

可选参数：

资料来源：cli/src/commands.rs:位置 1

鼠标操作命令

agent-browser mouse <action> [args]

浏览器设置命令

agent-browser set <setting> [value]

网络控制命令

agent-browser network <action>

Cookie 与存储命令

cookies set 选项：

标签页管理命令

agent-browser tab [new|list|close|<n>]

差异对比命令

agent-browser diff snapshot       # 比较当前与上次快照
agent-browser diff screenshot     # 与基线截图对比

截图命令

agent-browser screenshot [path] [--annotate]

CLI 标志配置

标志在程序启动时解析，影响全局行为。

示例：

agent-browser --annotate --download-path ./downloads open https://example.com
agent-browser --color-scheme dark --allowed-domains "example.com,api.example.com"

特殊上下文命令

以下命令用于特定上下文环境：

资料来源：cli/src/native/actions.rs:20-45

等待命令

agent-browser wait [options]

使用模式与最佳实践

基本交互流程

graph LR
    A[open URL] --> B[snapshot 获取引用]
    B --> C[find 定位元素]
    C --> D[click/tap/fill 执行操作]
    D --> E[验证结果]

推荐模式

1. 先快照再交互：始终在交互前获取元素引用
2. 导航后重新快照：页面跳转后需重新获取引用
3. 动态内容重新快照：DOM 变化后重新获取引用

# 正确顺序
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# 错误顺序
agent-browser open https://example.com
agent-browser click @e1  # 引用不存在！

资料来源：skill-data/core/references/snapshot-refs.md

输出格式

CLI 支持多种输出格式：

错误处理

错误响应格式：

{
  "ok": false,
  "error": "错误描述"
}

常用错误处理：

# 检查元素可见性后再操作
agent-browser is visible @e1
# 然后根据结果决定是否操作

# 等待元素出现
agent-browser wait 500
agent-browser snapshot -i

概述

浏览器自动化核心是 agent-browser 项目的底层引擎，负责通过 Chrome DevTools Protocol (CDP) 实现对 Chromium 内核浏览器的远程控制。该模块完全使用 Rust 实现，提供高性能的原生浏览器自动化能力，无需依赖 Node.js、Playwright 或 Puppeteer 等外部工具。

核心职责包括：

• 建立与 Chrome/Chromium 实例的 CDP 连接
• 执行 DOM 元素查询与操作
• 捕获页面快照和屏幕截图
• 管理浏览器状态和网络条件
• 处理用户交互事件（鼠标、键盘、触摸）

graph TD
    A[CLI 命令] --> B[Command Dispatcher]
    B --> C[State Manager]
    C --> D[CDP Client]
    D --> E[Chrome Instance]
    E --> D
    D --> C
    C --> F[Response Formatter]
    F --> A

架构分层

CDP 客户端架构

连接管理

CDP 客户端模块负责维护与 Chrome 实例的长连接。通过 Chrome 启动时获取的调试端口，建立 WebSocket 连接。

主要连接流程：

sequenceDiagram
    participant CLI
    participant CDP as CDP Client
    participant Chrome as Chrome Instance
    
    CLI->>Chrome: Launch with debug port
    Chrome-->>CLI: Return WebSocket URL
    CLI->>CDP: Connect(WebSocket URL)
    CDP->>Chrome: WebSocket Handshake
    Note over CDP,Chrome: CDP Session Established
    CLI->>CDP: Send Command
    CDP->>Chrome: CDP Request
    Chrome-->>CDP: CDP Response
    CDP-->>CLI: Parsed Result

消息协议

CDP 通信采用 JSON-RPC 2.0 格式，每条消息包含：

{
  "id": 1,
  "method": "DOM.getDocument",
  "params": {}
}

响应消息结构：

{
  "id": 1,
  "result": { ... }
}

元素系统

元素引用机制

元素系统通过可读的引用 ID（如 @e1, @e2）来标识 DOM 元素，相比于 XPath 或 CSS 选择器更加稳定和人类可读。

资料来源：cli/src/native/element.rs

元素操作命令

元素属性获取

agent-browser get text @e1           # 获取可见文本
agent-browser get html @e1           # 获取 innerHTML
agent-browser get attr @e1 href      # 获取属性值
agent-browser get value @e1          # 获取输入值
agent-browser get title              # 获取页面标题
agent-browser get url                # 获取当前 URL
agent-browser get count ".item"      # 统计匹配元素
agent-browser get box @e1            # 获取边界框
agent-browser get styles @e1         # 获取计算样式

快照系统

无障碍树快照

快照系统生成页面的可访问性树视图，包含元素引用 ID、标签类型和关键属性。

资料来源：cli/src/native/snapshot.rs

快照命令选项

快照输出示例

Page: Example - Log in
URL: https://example.com/login

@e1 [heading] "Log in"
@e2 [form]
  @e3 [input type="email"] placeholder="Email"
  @e4 [input type="password"] placeholder="Password"
  @e5 [button type="submit"] "Continue"
  @e6 [link] "Forgot password?"

Iframe 处理

快照自动检测并内联 iframe 内容。当捕获主框架快照时，每个 Iframe 节点会被解析，其子可访问性树直接包含在输出中。iframe 内部元素的引用携带框架上下文，交互命令可以直接使用，无需手动切换框架。

agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
#   @e3 [input] "Card number"
#   @e4 [input] "Expiry"
#   @e5 [button] "Pay"
# @e6 [button] "Cancel"

截图系统

截图命令

资料来源：cli/src/native/screenshot.rs

agent-browser screenshot                    # 保存到临时目录
agent-browser screenshot path.png           # 保存到指定路径
agent-browser screenshot --full             # 整页截图
agent-browser screenshot --annotate         # 带元素标注的截图
agent-browser pdf output.pdf                # 导出为 PDF

截图格式

截图以 Base64 编码的 PNG 格式传输和存储，在 UI 组件中渲染时使用：

<img
  src={`data:image/png;base64,${result.screenshot}`}
  alt={result.title}
  className="w-full block"
/>

资料来源：examples/environments/app/page.tsx

差异比较系统

Diff 功能

资料来源：cli/src/native/diff.rs

差异系统支持快照和截图的对比：

agent-browser diff snapshot              # 对比当前与上次快照
agent-browser diff screenshot --baseline  # 对比截图与基线

快照差异示例

- @e1 [button] "Submit"
+ @e1 [button] "Loading..."
- @e2 [div class="content"]
+ @e2 [div class="content expanded"]

状态检查系统

元素状态查询

高级交互

React 调试集成

系统提供 React 专用的调试命令，用于 React 应用的高级分析：

资料来源：cli/src/native/actions.rs:60-62

鼠标控制

agent-browser mouse move 100 200      # 移动鼠标
agent-browser mouse down left         # 鼠标按下
agent-browser mouse up left           # 鼠标释放
agent-browser mouse wheel 100 50      # 滚轮滚动

键盘控制

agent-browser press Enter             # 按下指定键
agent-browser press "Control+a"       # 组合键

浏览器环境配置

视口与设备模拟

agent-browser set viewport 1920 1080   # 设置视口尺寸
agent-browser set device "iPhone 14"  # 模拟设备

###地理位置模拟

agent-browser set geo 37.7749 -122.4194  # 模拟经纬度

网络条件控制

agent-browser set offline on           # 离线模式
agent-browser network route "**" --abort  # 中断所有请求
agent-browser network unroute "**"     # 恢复请求

Cookie 和存储管理

agent-browser cookies get              # 获取所有 Cookie
agent-browser cookies set --url https://example.com --name key --value val
agent-browser cookies clear
agent-browser storage local           # 操作 localStorage
agent-browser storage session          # 操作 sessionStorage

工作流程

典型自动化流程

graph TD
    A[打开页面] --> B[获取快照]
    B --> C{定位目标元素}
    C -->|新页面| D[重新获取快照]
    D --> C
    C -->|定位成功| E[执行操作]
    E --> F[等待加载]
    F --> G[验证结果]
    G -->|需要更多信息| B
    G -->|完成| H[输出结果]

推荐实践

1. 始终先快照再交互：元素引用需要在当前页面状态下获取

``bash agent-browser open https://example.com agent-browser snapshot -i # 先获取引用 agent-browser click @e1 # 再执行操作 ``

1. 导航后重新快照：页面导航后必须重新获取元素引用

``bash agent-browser click @e5 # 导航到新页面 agent-browser snapshot -i # 必须重新获取引用 agent-browser click @e1 # 使用新的引用 ``

1. 动态内容后重新快照：页面内容变化后需要更新引用

``bash agent-browser click @e1 # 打开下拉菜单 agent-browser snapshot -i # 看到新出现的选项 agent-browser click @e7 # 选择菜单项 ``

命令参考

完整命令列表

资料来源：cli/src/output.rs

扩展机制

Chrome 扩展集成

系统支持 Chrome 扩展的检测和管理：

agent-browser extensions list          # 列出已安装扩展
agent-browser extensions enable <id>   # 启用扩展
agent-browser extensions disable <id>  # 禁用扩展

扩展信息在 UI 中展示为可折叠列表：

资料来源：packages/dashboard/src/components/extensions-panel.tsx

每个扩展条目显示：

• 扩展名称和图标
• 描述信息
• 文件路径
• 启用/禁用状态

底层动作处理

命令分发机制

所有命令通过统一的分发器处理：

match subcommand.as_str() {
    "dispatch" => handle_dispatch(cmd, state).await,
    "highlight" => handle_highlight(cmd, state).await,
    "tap" => handle_tap(cmd, state).await,
    "boundingbox" => handle_boundingbox(cmd, state).await,
    "innertext" => handle_innertext(cmd, state).await,
    "innerhtml" => handle_innerhtml(cmd, state).await,
    "inputvalue" => handle_inputvalue(cmd, state).await,
    "setvalue" => handle_setvalue(cmd, state).await,
    "count" => handle_count(cmd, state).await,
    "styles" => handle_styles(cmd, state).await,
    "bringtofront" => handle_bringtofront(state).await,
    "timezone" => handle_timezone(cmd, state).await,
    "locale" => handle_locale(cmd, state).await,
    "geolocation" => handle_geolocation(cmd, state).await,
    "permissions" => handle_permissions(cmd, state).await,
    "dialog" => handle_dialog(cmd, state).await,
    "upload" => handle_upload(cmd, state).await,
    // ... 更多处理器
}

资料来源：cli/src/native/actions.rs:30-55

状态持久化

会话状态包括：

• 当前浏览器连接
• 元素引用缓存
• 历史快照
• 网络请求记录
• 用户凭据保险库

使用 agent-browser close 关闭会话，或 agent-browser close --all 关闭所有会话。

概述

React 组件审查是 agent-browser 提供的一套完整的 React 运行时 introspection（运行时自检）功能。该功能基于 React DevTools 协议，允许开发者在浏览器自动化场景中深入检查 React 组件树的拓扑结构、组件属性与状态、渲染性能以及 Suspense 边界状态。

这套审查机制的核心设计目标是零侵入性和框架无关性。通过在页面文档加载前注入 React DevTools Hook，agent-browser 能够在不修改目标应用源码的情况下，获取与 React DevTools 浏览器扩展完全一致的自检能力。

架构设计

整体架构

React 组件审查模块位于 cli/src/native/react/ 目录下，采用模块化设计，将不同功能职责分离到独立子模块中：

graph TD
    A[用户启动 Browser] --> B[--enable react-devtools]
    B --> C[installHook.js 注入]
    C --> D[__REACT_DEVTOOLS_GLOBAL_HOOK__]
    D --> E[React 检测并注册渲染器]
    
    E --> F[React 子系统]
    F --> G[tree - 组件树]
    F --> H[inspect - 组件详情]
    F --> I[renders - 渲染追踪]
    F --> J[suspense - 边界分析]
    
    K[vitals - 独立模块] -.-> L[Web 标准 API]
    K -.-> M[pushstate - SPA 导航]
    
    G --> N[format_tree / TreeNode]
    H --> O[inspectElementRaw]
    I --> P[format_renders_report / RendersData]
    J --> Q[format_suspense_report / Boundary]

核心模块职责

启动机制

React 自检功能的启用需要用户在启动 agent-browser 时显式传递 --enable react-devtools 参数。启用后，agent-browser 会通过 CDP (Chrome DevTools Protocol) 的 addScriptToEvaluateOnNewDocument 方法在所有页面 JS 执行前注册 Hook 脚本。

sequenceDiagram
    participant U as 用户
    participant CLI as agent-browser CLI
    participant CDP as CDP Client
    participant Browser as Chrome Browser
    participant React as React Runtime
    
    U->>CLI: agent-browser open --enable react-devtools <url>
    CLI->>CDP: 创建 BrowserContext
    CDP->>Browser: 初始化 CDP 会话
    CLI->>CDP: addScriptToEvaluateOnNewDocument(installHook.js)
    Browser->>React: 页面加载完成
    React->>React: 检测 __REACT_DEVTOOLS_GLOBAL_HOOK__
    React->>React: 注册渲染器到 Hook
    Note over React: React 自检功能就绪

React DevTools Hook 机制

Hook 脚本工作原理

installHook.js 是 React DevTools Chrome 扩展的官方 Hook 实现（MIT 协议，来源：facebook/react）。该脚本的核心功能是创建一个全局 Symbol 键 __REACT_DEVTOOLS_GLOBAL_HOOK__，供 React 运行时在启动时检测并注册自身的渲染器信息。

脚本中定义了以下关键 Symbol 标识符：

const A = Symbol.for("react.element");
const M = Symbol.for("react.transitional.element");
const z = Symbol.for("react.portal");
const $ = Symbol.for("react.fragment");
// ... 更多 React 内部 Symbol

渲染器注册流程

React 渲染器（如 react-dom、react-native）在初始化时会检测 window.__REACT_DEVTOOLS_GLOBAL_HOOK__ 是否存在。如果存在，渲染器会将自身的 Fiber 实现回调函数注册到这个 Hook 上，包括：

• findFiberByHostInstance - 通过 DOM 节点查找 Fiber
• findHostInstanceByFiber - 通过 Fiber 查找 DOM 节点
• inspectElement - 检索组件元素详情
• flushInitialProperties - 刷新初始属性
• patchIntervalDictionary - 性能监控间隔配置

资料来源：cli/src/native/react/installHook.js:1-50

组件树审查 (react tree)

功能描述

react tree 命令用于获取当前页面的完整 React 组件树结构。该命令会遍历所有已注册的 Fiber 节点，按照树形拓扑关系输出组件层级。

使用方式

agent-browser open --enable react-devtools <url>
agent-browser react tree

输出格式

命令输出包含每个组件的以下信息：

数据结构

// cli/src/native/react/tree.rs
pub struct TreeNode {
    pub id: String,           // Fiber ID
    pub name: String,         // 组件类型名
    pub display_name: String, // 可读显示名
    pub render_count: u64,    // 渲染次数统计
    pub children: Vec<TreeNode>, // 子节点
}

组件详情审查 (react inspect)

功能描述

react inspect 命令用于深度检查指定 Fiber ID 对应的组件详情，包括组件类型、当前 props、hooks 状态以及渲染来源位置。

使用方式

agent-browser react inspect <fiberId>

检查维度

内部实现

inspectElement 函数通过以下流程获取组件详情：

1. 验证目标 Fiber ID 存在于已注册的 v Map 中
2. 根据元素类型（HostComponent/ClassComponent/FunctionComponent）提取对应数据
3. 递归遍历 parents 路径构建上下文链
4. 返回序列化的元素描述对象

资料来源：cli/src/native/react/installHook.js:60-80

渲染追踪 (react renders)

功能描述

react renders 命令用于记录和分析 React 组件的重新渲染行为。通过追踪渲染次数和渲染耗时，帮助开发者识别性能瓶颈。

使用方式

# 开始记录渲染
agent-browser react renders start

# 执行页面交互操作...

# 停止记录并输出报告
agent-browser react renders stop
agent-browser react renders stop --json  # JSON 格式输出

数据模型

// cli/src/native/react/renders.rs
pub struct RendersData {
    pub total_renders: u64,           // 总渲染次数
    pub components: Vec<RenderStats>, // 各组件统计
    pub timestamp: DateTime<Utc>,    // 记录时间戳
}

pub struct RenderStats {
    pub fiber_id: String,
    pub name: String,
    pub render_count: u64,
    pub avg_duration_ms: f64,
}

输出报告格式

{
  "total_renders": 42,
  "components": [
    {
      "fiber_id": "e42",
      "name": "ProductList",
      "render_count": 15,
      "avg_duration_ms": 2.3
    }
  ]
}

Suspense 边界分析 (react suspense)

功能描述

react suspense 命令用于识别和分析 React Suspense 边界及其动态加载状态。该功能能够区分静态 Suspense 边界和动态加载中的 Suspense 边界。

使用方式

agent-browser react suspense
agent-browser react suspense --only-dynamic  # 仅显示动态边界
agent-browser react suspense --json          # JSON 格式输出

边界分类

数据结构

// cli/src/native/react/suspense.rs
pub struct Boundary {
    pub id: String,                  // 边界唯一标识
    pub name: String,                // Suspense 组件名
    pub state: BoundaryState,        // 当前状态
    pub children: Vec<String>,       // 边界内组件
}

pub enum BoundaryState {
    Resolved,   // 已完成加载
    Suspended,  // 等待异步加载
}

Web Vitals 监测 (vitals)

功能描述

vitals 命令用于采集 Core Web Vitals 核心指标，这是 React 组件审查中与框架相关性最低但实用性最高的模块。该功能依赖标准的 Web APIs，而非 React 特有机制。

采集指标

使用方式

# 采集当前页面指标
agent-browser vitals

# 采集指定 URL 指标
agent-browser vitals <url>

# JSON 格式输出
agent-browser vitals --json

数据模型

// cli/src/native/react/vitals.rs
pub struct VitalsData {
    pub lcp: Option<f64>,     // Largest Contentful Paint (ms)
    pub cls: Option<f64>,     // Cumulative Layout Shift
    pub ttfb: Option<f64>,    // Time to First Byte (ms)
    pub fcp: Option<f64>,     // First Contentful Paint (ms)
    pub inp: Option<f64>,     // Interaction to Next Paint (ms)
    pub hydration_time: Option<f64>, // React 水合时间 (ms)
    pub url: String,
    pub timestamp: DateTime<Utc>,
}

SPA 导航模拟 (pushstate)

功能描述

pushstate 命令用于模拟单页应用（SPA）中的客户端路由导航。该功能与 React 本身无直接关联，但与 React Router 等路由库协同工作。

使用方式

agent-browser pushstate <url>

工作机制

1. 在当前页面执行 history.pushState() 或 history.replaceState()
2. 触发 popstate 事件监听器
3. React Router 等框架监听该事件后执行组件切换
4. agent-browser 自动检测 Next.js 路由并同步状态

命令行接口集成

Action 路由表

React 相关命令通过 cli/src/native/actions.rs 中的路由表注册到 CLI 框架：

"react_tree" => handle_react_tree(cmd, state).await,
"react_inspect" => handle_react_inspect(cmd, state).await,
"react_renders_start" => handle_react_renders_start(cmd, state).await,
"react_renders_stop" => handle_react_renders_stop(cmd, state).await,
"react_suspense" => handle_react_suspense(cmd, state).await,
"vitals" => handle_vitals(cmd, state).await,
"pushstate" => handle_pushstate(cmd, state).await,

资料来源：cli/src/native/actions.rs:1-30

最佳实践

1. 启动参数配置

始终在需要 React 审查功能的会话中包含 --enable react-devtools 参数：

agent-browser open --enable react-devtools https://your-react-app.com

2. 性能分析工作流

graph LR
    A[启动 Browser] --> B[react renders start]
    B --> C[执行用户交互]
    C --> D[react renders stop]
    D --> E[分析渲染热点]
    E --> F{发现异常?}
    F -->|是| G[react inspect 定位]
    F -->|否| H[检查 Web Vitals]
    G --> I[优化组件]
    H --> J[vitals --json]

3. 渲染问题排查步骤

1. 执行 react tree 获取组件树概览
2. 定位可疑组件的 Fiber ID
3. 使用 react inspect <id> 检查 props 和 hooks
4. 执行 react renders start 记录重新渲染
5. 触发可疑操作后 react renders stop 查看报告

4. Suspense 问题排查

# 查看所有边界
agent-browser react suspense

# 仅关注动态加载
agent-browser react suspense --only-dynamic

# 导出 JSON 供自动化分析
agent-browser react suspense --json > suspense-report.json

技术限制与注意事项

1. Hook 时机依赖

React DevTools Hook 仅在 React 初始化时被检测。如果页面在 Hook 注入前已完成初始化，审查功能将不可用。当前架构通过 addScriptToEvaluateOnNewDocument 确保 Hook 在所有页面脚本前注册。

2. 非 React 框架

vitals 和 pushstate 为框架无关实现，可用于 Vue、Angular 等其他 SPA 框架的监测。

3. 生产环境警告

React DevTools Hook 会影响 React 的内部状态管理，建议仅在开发和调试环境中使用。

总结

React 组件审查模块为 agent-browser 提供了完整的 React 运行时自检能力。通过整合 React DevTools 协议，该模块实现了组件树可视化、属性状态检查、渲染性能追踪和 Suspense 边界分析等功能。这些能力使得 agent-browser 能够自动化测试 React 应用时提供精确的组件级别诊断信息，极大地提升了浏览器自动化测试的深度和准确性。

概述

agent-browser 的会话与认证管理系统负责管理浏览器自动化会话的生命周期、认证凭证、Cookie 存储以及 Web Storage（localStorage/sessionStorage）。该系统是 Rust 原生实现，运行在 cli/src/native/ 目录下的浏览器自动化守护进程中，支持 Chrome 和 Lightpanda 两种浏览器引擎。

会话管理器的核心职责包括：

• 会话目录的创建与清理
• Cookie 的增删改查
• Web Storage 的持久化与恢复
• 认证状态的保存与加载
• 状态快照的序列化与反序列化

资料来源：AGENTS.md

概述

网络监控与拦截是 agent-browser 提供的核心功能之一，允许用户在浏览器会话中对网络请求和响应进行实时监控、拦截、修改和录制。该功能基于 Chrome DevTools Protocol (CDP) 实现，支持 HTTP 请求、WebSocket 连接等多种网络协议。

通过这套系统，用户可以：

• 实时观察页面发出的所有网络请求
• 对特定请求进行拦截和响应修改
• 模拟网络错误和异常场景
• 录制完整的网络会话为 HAR 格式
• 管理 Cookie 和 Web Storage

核心功能模块

agent-browser 的网络监控与拦截系统主要由以下几个模块组成：

网络命令接口

agent-browser 通过 CLI 提供完整的网络操作命令。以下是主要命令的详细说明：

资料来源：cli/src/output.rs:50-60

network 命令族

agent-browser network <action>
  route <url> [--abort|--body <json>] [--resource-type <csv>]
  unroute [url]
  requests [--clear] [--filter <pattern>]
  har <start|stop> [path]

请求拦截与路由

route - 请求路由与拦截

route 命令用于设置 URL 路由规则，可以对匹配的请求进行拦截处理。

agent-browser network route <url> [--abort|--body <json>] [--resource-type <csv>]

#### 参数说明

#### 使用示例

# 中止所有对特定 API 的请求
agent-browser network route "*/api/auth/*" --abort

# 模拟 API 返回自定义数据
agent-browser network route "*/api/user" --body '{"id": 1, "name": "test"}'

# 仅拦截特定资源类型
agent-browser network route "*/assets/*" --resource-type "stylesheet"

unroute - 移除路由规则

agent-browser network unroute [url]

移除已设置的路由规则。省略 url 参数时，移除所有规则。

# 移除特定规则
agent-browser network unroute "*/api/auth/*"

# 清除所有规则
agent-browser network unroute

请求监控

requests - 实时请求列表

requests 命令用于查看当前会话的网络请求列表。

agent-browser network requests [--clear] [--filter <pattern>]

HAR 录制

HAR (HTTP Archive) 是一种标准的网络会话记录格式，用于保存和重放浏览器网络活动。

开始录制

agent-browser network har start

开始捕获所有网络请求和响应。

停止录制并保存

agent-browser network har stop [path]

停止录制并将结果保存为 HAR 文件。默认文件名为 capture.har。

# 保存到默认文件
agent-browser network har stop

# 保存到指定路径
agent-browser network har stop /path/to/recording.har

Dashboard 可视化

在 agent-browser 的 Dashboard 界面中，网络面板提供了可视化的请求监控功能：

• RequestDetail 组件：显示单个请求的详细信息，包括 URL、请求头、响应头等
• HAR 导出对话框：支持将录制的网络会话导出为 HAR 文件

资料来源：packages/dashboard/src/components/network-panel.tsx:100-140

存储管理

Cookie 管理

agent-browser 提供完整的 Cookie 管理功能：

agent-browser cookies [get|set|clear]

#### set 子命令参数

#### 从 cURL 导入

agent-browser cookies set --curl request.txt --domain "example.com"

支持自动检测 JSON、cURL 和 Cookie 头格式。

Web Storage 管理

agent-browser storage <local|session>

架构设计

网络监控流程

graph TD
    A[用户发起请求] --> B[CDP Network Agent]
    B --> C{匹配路由规则?}
    C -->|是| D[应用路由处理]
    C -->|否| E[转发到服务器]
    D --> F{abort?}
    F -->|是| G[返回中止响应]
    F -->|否| H{自定义 body?}
    H -->|是| I[返回自定义响应]
    H -->|否| E
    E --> J[接收服务器响应]
    J --> K[记录到 HAR]
    K --> L[返回给浏览器]
    G --> L
    I --> L

请求拦截状态机

stateDiagram-v2
    [*] --> Idle: 初始化
    Idle --> Monitoring: network route 设置
    Monitoring --> Intercepted: 请求匹配
    Intercepted --> Aborted: --abort
    Intercepted --> Modified: --body
    Modified --> Monitoring: 完成修改
    Aborted --> Monitoring: 继续监控
    Monitoring --> Stopped: 关闭会话
    Stopped --> [*]

典型使用场景

场景一：API mocking

当后端 API 尚未开发完成时，使用 route 命令模拟响应：

# 模拟用户列表 API
agent-browser network route "*/api/users" --body '[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]'

# 模拟详情 API
agent-browser network route "*/api/users/*" --body '{"id": 1, "name": "Alice", "email": "[email protected]"}'

场景二：调试网络错误

测试应用在网络异常情况下的表现：

# 中止特定域名的所有请求
agent-browser network route "https://analytics.example.com/*" --abort

# 测试静态资源加载失败
agent-browser network route "*assets*.js" --abort

场景三：录制和重放网络会话

# 开始录制
agent-browser network har start

# 执行测试操作...
agent-browser click @e1
agent-browser fill @e2 "test query"
agent-browser click @e3

# 停止录制并保存
agent-browser network har stop debug.har

场景四：导入已有 Cookie

# 从浏览器导出的 cURL 命令导入 Cookie
agent-browser cookies set --curl logged-in.txt --domain "app.example.com"

最佳实践

1. 清理路由规则

完成调试后，记得清除所有路由规则避免影响其他测试：

agent-browser network unroute

2. 使用资源类型过滤

对于大型应用，使用 --resource-type 减少规则数量：

# 仅拦截 XHR 和 Fetch 请求
agent-browser network route "*api*" --resource-type "xhr,fetch"

3. HAR 文件管理

录制大型会话时，注意磁盘空间：

# 使用有意义的文件名
agent-browser network har stop $(date +%Y%m%d_%H%M%S)_api_test.har

命令速查表

概述

agent-browser 项目的仪表板（Dashboard）是一个基于 React + TypeScript 构建的 Web 界面，用于可视化展示浏览器自动化任务的状态、结果和执行历史。仪表板组件采用模块化架构，通过 Zustand 状态管理库实现跨组件的状态共享，支持截图展示、快照查看、活动记录等功能。

资料来源：packages/dashboard/src/components/extensions-panel.tsx:1-80

架构设计

技术栈

组件目录结构

packages/dashboard/src/
├── app/
│   └── page.tsx              # 主仪表板页面
├── components/
│   ├── extensions-panel.tsx  # Chrome 扩展管理面板
│   ├── activity-feed.tsx     # 活动流展示
│   ├── chat-panel.tsx        # 聊天交互面板
│   └── network-panel.tsx     # 网络请求监控面板
└── store/
    ├── chat.ts               # 聊天相关状态
    └── activity.ts           # 活动记录状态

资料来源：packages/dashboard/src/components/extensions-panel.tsx:1-10

核心组件

ExtensionsPanel（扩展面板）

ExtensionsPanel 组件负责展示和管理已安装的 Chrome 浏览器扩展。组件采用可折叠的卡片式布局，支持显示扩展名称、描述和安装路径。

#### 组件结构

// packages/dashboard/src/components/extensions-panel.tsx
function ExtensionsPanel({ extensions }: { extensions: Extension[] }) {
  const [isExpanded, setIsExpanded] = useState(false);

  return (
    <div className="border rounded-lg">
      <Header count={extensions.length} />
      {isExpanded && (
        <div className="space-y-1 bg-muted/30 px-3 py-2 text-[11px]">
          {ext.description && (
            <div>
              <span className="text-muted-foreground">Description: </span>
              <span className="text-foreground">{ext.description}</span>
            </div>
          )}
          <div>
            <span className="text-muted-foreground">Path: </span>
            <span className={cn("break-all font-mono text-foreground")}>
              {ext.path}
            </span>
          </div>
        </div>
      )}
    </div>
  );
}

资料来源：packages/dashboard/src/components/extensions-panel.tsx:15-45

#### 扩展数据模型

interface Extension {
  id: string;
  name: string;
  description?: string;
  path: string;
  version?: string;
}

#### Header 子组件

function Header({ count }: { count: number }) {
  return (
    <div className="flex shrink-0 items-center gap-1.5 px-3 py-2">
      <span className="text-[10px] text-muted-foreground">
        Chrome Extensions
      </span>
      {count > 0 && (
        <Badge
          variant="secondary"
          className="ml-auto h-4 px-1.5 text-[10px] tabular-nums"
        >
          {count}
        </Badge>
      )}
    </div>
  );
}

资料来源：packages/dashboard/src/components/extensions-panel.tsx:55-70

ActivityFeed（活动流）

活动流组件用于实时展示 agent-browser 的执行活动，包括命令执行、状态变更和操作记录。该组件从 Zustand store 订阅活动数据，支持虚拟滚动以优化大数据量场景下的渲染性能。

ChatPanel（聊天面板）

聊天面板提供人机交互界面，允许用户发送指令并接收 agent-browser 的响应。该组件与 chat.ts 状态存储紧密集成，支持消息历史、会话管理和流式响应展示。

NetworkPanel（网络面板）

网络监控面板用于显示浏览器发出的 HTTP 请求和响应，支持以下功能：

• 请求/响应头查看
• 请求方法过滤（GET、POST、PUT、DELETE 等）
• 状态码高亮
• 请求耗时统计

资料来源：packages/dashboard/src/components/network-panel.tsx

状态管理

Chat Store

chat.ts 使用 Zustand 管理聊天会话状态：

// packages/dashboard/src/store/chat.ts
interface ChatState {
  messages: Message[];
  sendMessage: (content: string) => void;
  clearHistory: () => void;
}

Activity Store

activity.ts 管理操作活动日志：

// packages/dashboard/src/store/activity.ts
interface ActivityState {
  activities: Activity[];
  addActivity: (activity: Activity) => void;
  clearActivities: () => void;
}

主页面布局

主仪表板页面 (page.tsx) 采用响应式布局，整合所有面板组件：

// packages/dashboard/src/app/page.tsx 结构示意
export default function DashboardPage() {
  return (
    <div className="min-h-screen bg-background">
      <header> {/* 顶部导航 */} </header>
      <main className="flex">
        <aside> {/* 侧边栏 */} </aside>
        <section className="flex-1">
          {/* 主内容区域 */}
          <ChatPanel />
          <ActivityFeed />
        </section>
        <aside>
          <NetworkPanel />
          <ExtensionsPanel />
        </aside>
      </main>
    </div>
  );
}

资料来源：packages/dashboard/src/app/page.tsx

数据流图

graph TD
    A[用户交互] --> B{操作类型}
    B -->|发送指令| C[ChatPanel]
    B -->|查看活动| D[ActivityFeed]
    B -->|监控网络| E[NetworkPanel]
    B -->|管理扩展| F[ExtensionsPanel]
    
    C --> G[chat.ts store]
    D --> H[activity.ts store]
    
    G --> I[CLI 进程]
    H --> I
    
    I --> J[浏览器实例]
    J --> K[CDP 连接]
    K --> G
    K --> H
    
    E --> L[网络请求数据]
    F --> M[扩展列表数据]

样式系统

仪表板组件使用 Tailwind CSS 进行样式管理，遵循以下设计规范：

资料来源：packages/dashboard/src/components/extensions-panel.tsx:20-35

Badge 组件使用

Badge 组件用于显示数量统计，采用 variant="secondary" 变体：

<Badge
  variant="secondary"
  className="ml-auto h-4 px-1.5 text-[10px] tabular-nums"
>
  {count}
</Badge>

关键样式属性：

• tabular-nums：使用等宽数字字体，确保数字对齐
• h-4 px-1.5：紧凑的尺寸设计
• ml-auto：右对齐布局

与 CLI 的集成

仪表板通过以下方式与 agent-browser CLI 集成：

1. WebSocket 连接：通过 CDP（Chrome DevTools Protocol）建立通信
2. 命令执行：调用 CLI 子命令执行浏览器操作
3. 结果展示：将命令执行结果（截图、快照）渲染到对应面板

sequenceDiagram
    participant U as 用户
    participant D as 仪表板
    participant C as CLI
    participant B as 浏览器
    
    U->>D: 输入指令
    D->>C: 执行命令
    C->>B: CDP 操作
    B-->>C: 执行结果
    C-->>D: 返回数据
    D-->>U: 更新界面

开发指南

添加新面板组件

1. 在 packages/dashboard/src/components/ 创建新组件
2. 使用 Zustand 创建对应的 store（如需要）
3. 在 page.tsx 中导入并放置组件
4. 添加 Tailwind 样式类

状态更新流程

// 示例：更新活动记录
const activityStore = useActivityStore();
activityStore.addActivity({
  id: crypto.randomUUID(),
  type: 'command',
  message: '执行截图命令',
  timestamp: Date.now()
});

已知限制

• 部分组件源码（如 activity-feed.tsx、chat-panel.tsx）需在完整检索后补充说明
• 网络面板的实时数据流功能依赖 CLI 的 HAR 捕获能力
• 扩展管理功能仅支持 Chrome 浏览器

相关资源

• CLI 输出模块参考
• 核心技能文档
• Electron 应用集成

概述

agent-browser 项目的文档站点是一个基于 Next.js 构建的现代化文档平台，为用户提供完整的产品使用指南、命令参考和工作流说明。该站点作为项目的主要知识库，集中管理所有技术文档内容。

技术架构

框架选型

文档站点采用 Next.js 作为底层框架，利用其静态站点生成（SSG）能力提供快速的页面加载和良好的 SEO 表现。

graph TD
    A[用户访问] --> B[Next.js 静态生成]
    B --> C[MDX 内容渲染]
    C --> D[侧边栏导航组件]
    D --> E[文档页面展示]
    
    F[内容源文件] --> G[MDX to Markdown 转换]
    G --> C

核心配置文件

#### next.config.mjs

Next.js 配置文件位于 docs/next.config.mjs，负责站点的构建和运行时配置。该文件定义了站点的基本行为和构建优化选项。

#### 布局组件 (layout.tsx)

根布局文件 docs/src/app/layout.tsx 定义了文档站点的整体布局结构，包括全局样式注入、字体配置和基础 HTML 结构。

核心模块

文档导航系统

#### docs-navigation.ts

文档导航模块 (docs/src/lib/docs-navigation.ts) 是整个文档站点的核心模块，负责管理文档的层级结构和导航逻辑。

MDX 转换模块

#### mdx-to-markdown.ts

MDX 到 Markdown 的转换模块 (docs/src/lib/mdx-to-markdown.ts) 负责处理文档内容的格式转换，支持 MDX 语法的解析和渲染。

侧边栏组件

#### docs-sidebar.tsx

侧边栏组件 (docs/src/components/docs-sidebar.tsx) 负责渲染文档导航界面，提供以下功能：

• 文档分类展示
• 当前页面高亮
• 可折叠的分类组
• 响应式布局支持

内容结构

主要文档分类

根据项目结构，文档站点包含以下主要分类：

文档模板结构

每个技能文档遵循统一模板格式：

# 技能标题

## 使用前置条件
- 环境要求
- 依赖安装

## 快速开始
- 基础命令
- 常见工作流

## 参考资料
- 详细命令列表
- 参数说明

变更日志管理

CHANGELOG.md 结构

项目使用 CHANGELOG.md 管理版本变更记录，包含以下标准章节：

• 新功能 (New Features) - 新增功能说明
• 错误修复 (Bug Fixes) - 问题修复记录
• 改进 (Improvements) - 优化和增强说明
• 贡献者 (Contributors) - 版本贡献者列表

文档变更日志同步

文档站点的变更日志 (docs/src/app/changelog/page.mdx) 与主 CHANGELOG.md 保持同步，但使用不同的格式约定：

• 版本号添加 v 前缀（如 v0.24.0）
• 包含完整的发布日期
• 使用 --- 分隔符区分版本条目

## v0.24.0

<p className="text-[#888] text-sm">March 30, 2026</p>

系统要求

硬件与操作系统

agent-browser 支持 macOS (Intel/Apple Silicon)、Linux (x86_64/aarch64) 和 Windows (x86_64) 三大平台。项目使用 Rust 语言实现核心引擎，前端采用 TypeScript + React 技术栈，通过 pnpm 作为包管理器。资料来源：AGENTS.md

必需依赖

# Rust 工具链 (使用 rustup 安装)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Node.js (v18+)
# 推荐使用 nvm 或 fnm 管理版本

# pnpm (v8+)
npm install -g pnpm

# Chrome/Chromium (用于运行时)
# Linux: apt install chromium 或下载 Chrome for Testing
# macOS: brew install chromium
# Windows: 下载 Chrome for Testing

项目结构

agent-browser/
├── cli/                    # Rust 核心守护进程
│   ├── src/
│   │   ├── native/         # 浏览器自动化核心模块
│   │   │   ├── daemon.rs   # 守护进程主入口
│   │   │   ├── actions.rs  # 浏览器操作指令处理
│   │   │   ├── browser.rs  # 浏览器实例管理
│   │   │   ├── cdp/        # Chrome DevTools Protocol 客户端
│   │   │   ├── snapshot/   # 页面快照生成
│   │   │   └── state/      # 会话状态管理
│   │   ├── react/         # React 组件分析模块
│   │   └── commands.rs     # CLI 命令解析
│   ├── build.rs           # 构建脚本
│   └── Cargo.toml
├── packages/
│   └── dashboard/          # React 前端界面
│       ├── src/
│       │   └── components/ # UI 组件
│       └── package.json
├── scripts/                # 构建辅助脚本
│   ├── build-all-platforms.sh
│   └── copy-native.js
├── docker/                 # Docker 部署配置
│   ├── Dockerfile.build
│   └── docker-compose.yml
└── pnpm-lock.yaml

资料来源：AGENTS.md:49-53

环境配置

克隆源码

git clone https://github.com/vercel-labs/agent-browser.git
cd agent-browser

安装 Node.js 依赖

# 安装所有 workspace 依赖
pnpm install

# 仅安装前端依赖
pnpm install --filter @agent-browser/dashboard

项目采用 pnpm workspace 架构，所有子项目的依赖通过根目录的 pnpm-lock.yaml 统一锁定版本。

配置 Rust 环境

# 验证 Rust 安装
rustc --version
cargo --version

# 添加交叉编译工具链 (可选，用于多平台构建)
rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
rustup target add x86_64-apple-darwin aarch64-apple-darwin
rustup target add x86_64-pc-windows-gnu

构建流程

完整构建

项目提供一键构建脚本，可同时编译所有平台的原生二进制文件和前端资源：

./scripts/build-all-platforms.sh

该脚本执行以下步骤：

graph TD
    A[开始构建] --> B[检查 Rust 工具链]
    B --> C[清理旧构建产物]
    C --> D[编译 CLI 原生二进制]
    D --> E[复制二进制到 packages/dashboard/native]
    E --> F[构建前端资源]
    F --> G[生成平台特定包]
    G --> H[完成]
    
    D --> D1[Linux x86_64]
    D --> D2[Linux aarch64]
    D --> D3[macOS Intel]
    D --> D4[macOS Apple Silicon]
    D --> D5[Windows x86_64]

资料来源：scripts/build-all-platforms.sh

分步构建

#### 1. 编译 Rust 原生模块

cd cli

# 开发构建 (快速)
cargo build

# 发布构建 (优化)
cargo build --release

# 指定目标平台
cargo build --release --target x86_64-unknown-linux-gnu

构建产物位于 cli/target/release/agent-browser (或 cli/target/debug/agent-browser 用于开发)。

#### 2. 复制原生二进制到前端

node scripts/copy-native.js

该脚本将编译好的原生二进制文件复制到前端包的 native/ 目录，供 Electron 或 WebAssembly 加载使用。资料来源：scripts/copy-native.js

#### 3. 构建前端界面

# 构建生产版本
pnpm build

# 开发模式 (热重载)
pnpm dev

构建脚本详解

cli/build.rs 是 Cargo 构建脚本，在编译前执行以下任务：

// 伪代码展示 build.rs 功能
fn main() {
    // 1. 打印版本信息
    println!("cargo:rustc-env=VERSION={}", version);
    
    // 2. 链接必要的系统库
    println!("cargo:rustc-link-lib=ssl");
    println!("cargo:rustc-link-lib=crypto");
    
    // 3. 设置编译条件
    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed=Cargo.toml");
}

资料来源：cli/build.rs

Docker 构建

Dockerfile.build

项目提供专用的 Docker 构建镜像，基于 Rust 官方镜像，包含所有交叉编译工具链：

FROM rust:1.75-bookworm AS builder

# 安装交叉编译目标依赖
RUN apt-get update && apt-get install -y \
    gcc-arm-linux-gnueabihf \
    libc6-dev-armhf-cross \
    gcc-aarch64-linux-gnu \
    libc6-dev-arm64-cross \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-gnu

资料来源：docker/Dockerfile.build

docker-compose.yml

version: '3.8'

services:
  build:
    build:
      context: ..
      dockerfile: docker/Dockerfile.build
    volumes:
      - ../target:/app/target
    environment:
      - CARGO_HOME=/app/.cargo

资料来源：docker/docker-compose.yml

使用 Docker 构建

# 构建镜像
docker-compose -f docker/docker-compose.yml build

# 运行构建
docker-compose -f docker/docker-compose.yml run build

测试

单元测试

cd cli
cargo test

运行所有单元测试（约 320 个测试），这些测试执行速度快，无需启动 Chrome 实例。资料来源：AGENTS.md:61-63

端到端测试

cd cli
cargo test e2e -- --ignored --test-threads=1

端到端测试会启动真实的 headless Chrome 实例，完整测试原生守护进程命令管道。运行要求：

资料来源：AGENTS.md:68-73

发布流程

项目使用自动化发布流程：

graph LR
    A[创建 Git Tag] --> B[CI 触发构建]
    B --> C[编译 7 个平台二进制]
    C --> D[发布到 npm]
    D --> E[创建 GitHub Release]
    
    E --> F[从 CHANGELOG.md 提取说明]
    F --> G[发布完成]

构建脚本会：

1. 编译所有 7 个平台的二进制文件（macOS Intel/macOS ARM/Linux x64/Linux ARM/Windows x64 等）
2. 发布到 npm 仓库
3. 自动创建 GitHub Release，Release 内容从 CHANGELOG.md 的 <!-- release:start --> 和 <!-- release:end --> 标记之间提取

资料来源：AGENTS.md:17-21

常见问题

编译错误：链接库缺失

# macOS
brew install openssl pkg-config

# Linux (Debian/Ubuntu)
sudo apt install libssl-dev pkg-config

# Linux (Fedora/RHEL)
sudo dnf install openssl-devel pkg-config

交叉编译失败

确保已安装对应平台的交叉编译工具链：

# Linux ARM
rustup target add aarch64-unknown-linux-gnu
sudo apt install gcc-aarch64-linux-gnu libc6-dev-arm64-cross

# macOS ARM on Linux
rustup target add aarch64-apple-darwin

Chrome/Chromium 未找到

agent-browser 需要 Chrome for Testing 提供浏览器二进制。使用 --engine 参数指定浏览器引擎：

agent-browser --engine chrome open https://example.com

或通过安装命令自动下载：

agent-browser install chrome

环境变量参考

构建产物

成功构建后，项目生成以下产物：

Pitfall Log / 踩坑日志

项目：vercel-labs/agent-browser

摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome 147.0 crashes with "trap int3" when running in docker。

1. 安装坑 · 来源证据：Chrome 147.0 crashes with "trap int3" when running in docker

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome 147.0 crashes with "trap int3" when running in docker
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9045278ef5e043dcadccf9288477813c | https://github.com/vercel-labs/agent-browser/issues/1339 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Detected: Trojan:Win32/Posilod.EB!cl

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Detected: Trojan:Win32/Posilod.EB!cl
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_edbde732c7a7410e96ad0fa301e4222d | https://github.com/vercel-labs/agent-browser/issues/1281 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

3. 运行坑 · 来源证据：Feature Request: Chrome Extension-based Connection for Seamless Login State Reuse

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Feature Request: Chrome Extension-based Connection for Seamless Login State Reuse
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0896b0b429c641f0b93ca9dcbbee6db8 | https://github.com/vercel-labs/agent-browser/issues/1319 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain trailing slash

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain trailing slash
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_32ddde976ec0445da607d0adffc5df4c | https://github.com/vercel-labs/agent-browser/issues/1349 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：v0.25.5

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.25.5
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d5d23fc6d09149fbb21ee500e7a328ec | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.5 | 来源类型 github_release 暴露的待验证使用条件。

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | README/documentation is current enough for a first validation pass.

7. 运行坑 · 来源证据：v0.25.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.25.2
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_777821422c534a2881b58523db3ac2f3 | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.2 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

8. 运行坑 · 来源证据：v0.25.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.25.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5c7d80190d7548b6ad87152255949f2b | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.3 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | no_demo; severity=medium

11. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | No sandbox install has been executed yet; downstream must verify before user use.

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：Dashboard privileged POST routes should reject cross-origin requests

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dashboard privileged POST routes should reject cross-origin requests
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6acd97eb554140c28938a0eb08e44c34 | https://github.com/vercel-labs/agent-browser/issues/1345 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Harden inspect-mode DevTools WebSocket handshakes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Harden inspect-mode DevTools WebSocket handshakes
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ab6c062eedaf466d8f40864ca24bf8ea | https://github.com/vercel-labs/agent-browser/issues/1347 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High LLM turn count due to frequent snapshot calls when using agent-browser skills
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_648ff78f18f34d51a44b9176d011738f | https://github.com/vercel-labs/agent-browser/issues/1351 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：Per-session /api/command should require same-origin or token auth

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Per-session /api/command should require same-origin or token auth
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d21bab57490142daba6d89ed22776087 | https://github.com/vercel-labs/agent-browser/issues/1344 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：Support enabling WebAuthn for passkey authentication with a virtual authenticator

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support enabling WebAuthn for passkey authentication with a virtual authenticator
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3a4a36591a7e45c1b85d35b020e63d5a | https://github.com/vercel-labs/agent-browser/issues/688 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fda08c46f8b5454e8e93b061d6d3c992 | https://github.com/vercel-labs/agent-browser/issues/1348 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：v0.25.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.25.4
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3b8dd03ae1104698b37da46bc0d08fb7 | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.4 | 来源类型 github_release 暴露的待验证使用条件。

20. 安全/权限坑 · 来源证据：v0.26.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.26.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9db59c2c8cb44b39916cf70c0c9eae22 | https://github.com/vercel-labs/agent-browser/releases/tag/v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。

21. 安全/权限坑 · 来源证据：v0.27.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.27.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_98f07270bf7b43658e439416c320183e | https://github.com/vercel-labs/agent-browser/releases/tag/v0.27.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

22. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | issue_or_pr_quality=unknown

23. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | release_recency=unknown