# https://github.com/vercel-labs/agent-browser 项目说明书

生成时间：2026-05-13 13:40:16 UTC

## 目录

- [项目介绍](#introduction)
- [系统架构](#architecture-overview)
- [CLI 命令参考](#cli-commands)
- [浏览器自动化核心](#browser-automation)
- [React 组件审查](#react-introspection)
- [会话与认证管理](#sessions-authentication)
- [网络监控与拦截](#network-monitoring)
- [仪表板组件](#dashboard-components)
- [文档站点](#documentation-site)
- [安装与构建](#installation-build)

<a id='introduction'></a>

## 项目介绍

### 相关页面

相关主题：[系统架构](#architecture-overview), [CLI 命令参考](#cli-commands)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)
- [skill-data/core/references/commands.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/commands.md)
- [skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)
- [skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)
- [skill-data/dogfood/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md)
- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)
</details>

# 项目介绍

## 概述

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

## 核心特性

### 技术架构

| 特性 | 说明 |
|------|------|
| 实现语言 | Rust 原生代码 |
| 浏览器引擎 | Chrome/Chromium via CDP |
| 无依赖 | 无需 Playwright 或 Puppeteer |
| 会话管理 | 支持多会话、状态持久化 |
| 认证存储 | 内置认证库（Authentication Vault） |
| 视频录制 | 支持操作过程录制 |
| 引擎选择 | 支持 `--engine` 切换 Chrome 与 Lightpanda |

资料来源：[AGENTS.md:43-46](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

### 跨平台兼容性

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

## 系统架构

### 架构组件

```mermaid
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/` 目录下，包含以下关键模块：

| 模块 | 路径 | 功能 |
|------|------|------|
| daemon | `cli/src/native/` | 守护进程，处理命令调度 |
| actions | `cli/src/native/actions.rs` | 浏览器操作动作处理 |
| browser | `cli/src/native/` | 浏览器实例管理 |
| CDP client | `cli/src/native/` | Chrome DevTools Protocol 通信 |
| snapshot | `cli/src/native/` | 无障碍树快照生成 |
| state | `cli/src/native/` | 会话状态管理 |
| react | `cli/src/native/react/` | React 开发者工具集成 |

资料来源：[AGENTS.md:43](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 命令体系

### 核心命令分类

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

```mermaid
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]
```

### 常用命令速查

| 命令 | 说明 | 示例 |
|------|------|------|
| `open <url>` | 启动并导航 | `agent-browser open https://example.com` |
| `snapshot` | 获取无障碍树快照 | `agent-browser snapshot -i` |
| `click @e1` | 通过引用点击元素 | `agent-browser click @e1` |
| `screenshot` | 截图 | `agent-browser screenshot --annotate output.png` |
| `find` | 查找元素 | `agent-browser find role button Submit` |
| `network route` | 拦截网络请求 | `agent-browser network route * --abort --resource-type script` |
| `cookies` | 管理 Cookie | `agent-browser cookies set --curl file.curl` |

资料来源：[cli/src/output.rs:1-30](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

## 元素引用系统

### 快照与引用机制

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

```bash
# 正确流程
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](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)

### 引用格式

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

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

## 专精技能

### 技能体系架构

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

### 技能说明

| 技能 | 用途 | 使用命令 |
|------|------|----------|
| core | 核心工作流和通用模式 | `agent-browser skills get core` |
| electron | Electron 桌面应用自动化 | `agent-browser skills get electron` |
| slack | Slack 工作区自动化 | `agent-browser skills get slack` |
| dogfood | 探索性测试 / QA / Bug 追踪 | `agent-browser skills get dogfood` |
| vercel-sandbox | Vercel Sandbox 微虚拟机环境 | `agent-browser skills get vercel-sandbox` |
| agentcore | AWS Bedrock AgentCore 云浏览器 | `agent-browser skills get agentcore` |

资料来源：[skills/agent-browser/SKILL.md:5-25](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)

## React 开发者工具

### React 渲染分析

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

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

### 阻塞组件识别

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

| 类型 | 说明 | 权重 |
|------|------|------|
| RouteSegment | 路由段边界 | 3 |
| ExplicitSuspense | 显式 Suspense 边界 | 2 |
| Component | 普通组件 | 1 |

资料来源：[cli/src/native/react/suspense.rs:1-50](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)

## 可观测性仪表板

### Dashboard 功能

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

```mermaid
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]
```

### 面板功能

| 面板 | 功能 |
|------|------|
| Extensions Panel | 列出已加载的 Chrome 扩展，显示描述和路径 |
| Network Panel | 监控网络请求，支持 HAR 导出和请求详情查看 |
| Snapshot Display | 展示无障碍树快照，支持步骤折叠展示 |
| Step Indicators | 显示执行步骤的详细信息 |

资料来源：[packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx)

## 安装与配置

### 安装命令

```bash
# 安装 agent-browser
agent-browser install

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

### 预导航设置

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

```bash
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](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/commands.md)

## 测试体系

### 测试类型

| 测试类型 | 命令 | 说明 |
|----------|------|------|
| 单元测试 | `cd cli && cargo test` | 快速测试，约 320 个测试用例，无需 Chrome |
| 端到端测试 | `cd cli && cargo test e2e -- --ignored --test-threads=1` | 18 个 e2e 测试，启动真实 Chrome 实例 |

### 测试要求

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

资料来源：[AGENTS.md:52-62](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 发布流程

### 发布自动化

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

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

### 版本同步

```bash
pnpm version:sync
```

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

资料来源：[AGENTS.md:15-35](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 使用场景

### 探索性测试与 QA

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

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

### Slack 工作区自动化

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

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

资料来源：[skill-data/dogfood/SKILL.md:50-70](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md)

## 技术栈总结

```mermaid
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]
```

| 层级 | 技术 | 位置 |
|------|------|------|
| 核心引擎 | Rust | `cli/src/native/` |
| CLI 接口 | TypeScript | `cli/src/` |
| 仪表板 | React + Next.js | `packages/dashboard/` |
| UI 组件 | shadcn/ui | `packages/dashboard/src/components/` |
| 样式 | Tailwind CSS | 项目全局 |

---

<a id='architecture-overview'></a>

## 系统架构

### 相关页面

相关主题：[项目介绍](#introduction), [浏览器自动化核心](#browser-automation), [仪表板组件](#dashboard-components)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/Cargo.toml](https://github.com/vercel-labs/agent-browser/blob/main/cli/Cargo.toml)
- [cli/src/main.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/main.rs)
- [cli/src/native/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/mod.rs)
- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)
- [cli/src/native/interaction.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/interaction.rs)
- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)
- [packages/dashboard/src/components/chat-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/chat-panel.tsx)
- [packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx)
- [packages/dashboard/src/components/network-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/network-panel.tsx)
- [packages/dashboard/src/components/console-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/console-panel.tsx)
- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
</details>

# 系统架构

## 概述

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

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

资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

---

## 整体架构

agent-browser 采用分层架构设计，主要分为以下几个层次：

| 层次 | 技术栈 | 职责 |
|------|--------|------|
| CLI 层 | Rust | 命令行入口，解析用户命令并转发至守护进程 |
| 守护进程层 | Rust | 浏览器实例管理、CDP 通信、状态维护 |
| 渲染引擎层 | Chrome/Lightpanda | 实际页面渲染和执行 |
| 仪表盘层 | React/Next.js | 可视化控制界面和结果展示 |
| 技能数据层 | Markdown | 领域特定的操作指南和参考文档 |

资料来源：[cli/src/main.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/main.rs)

### 核心模块划分

```mermaid
graph TD
    A[CLI 命令行] --> B[命令分发器]
    B --> C[Native 守护进程]
    C --> D[浏览器引擎]
    C --> E[CDP 客户端]
    C --> F[状态管理]
    
    G[Web 仪表盘] --> H[WebSocket/HTTP]
    H --> C
    
    D --> I[快照系统]
    D --> J[交互系统]
    D --> K[React 检查]
    
    style A fill:#e1f5fe
    style G fill:#fff3e0
    style D fill:#f3e5f5
```

---

## 守护进程架构

守护进程（Daemon）是系统的核心组件，负责管理浏览器生命周期和执行各种自动化操作。

### 核心子模块

| 模块 | 文件路径 | 功能描述 |
|------|----------|----------|
| daemon | cli/src/native/mod.rs | 主进程管理和命令路由 |
| actions | cli/src/native/actions.rs | 具体操作实现（点击、滚动、截图等）|
| interaction | cli/src/native/interaction.rs | 键盘和鼠标交互处理 |
| browser | cli/src/native/ | 浏览器实例管理 |
| CDP client | cli/src/native/ | Chrome DevTools Protocol 通信 |
| snapshot | cli/src/native/ | 页面快照生成 |
| state | cli/src/native/ | 会话状态维护 |

资料来源：[cli/src/native/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/mod.rs)

### 命令处理流程

守护进程接收命令后，通过分发器（Dispatcher）将请求路由到对应的处理函数：

```mermaid
graph LR
    A[输入命令] --> B[命令解析]
    B --> C{命令类型判断}
    C -->|点击| D[handle_tap]
    C -->|滚动| E[handle_scroll]
    C -->|截图| F[handle_screenshot]
    C -->|快照| G[handle_snapshot]
    C -->|输入| H[handle_setvalue]
    C -->|键盘| I[handle_key]
    D --> J[执行结果]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

支持的命令类型包括：

- **导航命令**: open, close, goto, back, forward, reload
- **交互命令**: click, tap, scroll, hover, drag, mouse, press, type
- **查询命令**: snapshot, screenshot, get, find, count, styles, innertext, innerhtml
- **设置命令**: set, viewport, device, timezone, locale, geolocation, permissions
- **网络命令**: network, cookies, storage, har
- **扩展命令**: addscript, addinitscript, removeinitscript, addstyle
- **React 检查**: react_tree, react_inspect, react_renders_start

资料来源：[cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)

---

## 交互系统

交互模块负责处理用户与浏览器页面的所有交互操作，包括鼠标、键盘和各种输入设备。

### 键盘映射

交互系统维护了完整的键盘映射表，支持标准键位和虚拟键码：

```mermaid
graph TD
    A[按键输入] --> B{按键类型}
    B -->|功能键| C[特殊处理]
    B -->|方向键| D[Arrow映射]
    B -->|普通键| E[字符转换]
    
    C --> F[返回 key, code, keyCode]
    D --> F
    E --> G[char_to_key_info]
    G --> F
```

支持的键位映射：

| 输入 | 键名 | 键码 |
|------|------|------|
| arrowup, up | ArrowUp | 38 |
| arrowdown, down | ArrowDown | 40 |
| arrowleft, left | ArrowLeft | 37 |
| arrowright, right | ArrowRight | 39 |
| home | Home | 36 |
| end | End | 35 |
| pageup | PageUp | 33 |
| pagedown | PageDown | 34 |
| space, 空格 | Space | 32 |

资料来源：[cli/src/native/interaction.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/interaction.rs)

### 鼠标操作

鼠标操作支持以下子命令：

| 操作 | 说明 |
|------|------|
| move \<x\> \<y\> | 移动鼠标到指定坐标 |
| down [btn] | 按下鼠标按钮 |
| up [btn] | 释放鼠标按钮 |
| wheel \<dy\> [dx] | 滚动鼠标滚轮 |

---

## 快照与元素引用系统

快照系统是 agent-browser 的核心功能之一，用于获取页面当前状态并生成可引用元素标识符。

### 快照格式

快照输出包含元素引用（ref）和关键属性：

```
@e1 [button] "Submit"                    # 按钮元素
@e2 [input type="email"]                 # 输入框
@e3 [div class="container"] "内容文本"    # 容器元素
```

引用格式说明：

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

### 元素定位方式

| 定位器 | 说明 | 示例 |
|--------|------|------|
| role | ARIA 角色 | role=button |
| text | 文本内容 | text="Submit" |
| label | 表单标签 | label="用户名" |
| placeholder | 占位符 | placeholder="输入..." |
| alt | 图片替代文本 | alt="描述" |
| title | 标题属性 | title="提示" |
| testid | 测试 ID | testid="btn-submit" |
| first/last/nth | 位置选择 | first, last, nth=2 |

最佳实践：

```bash
# 正确流程
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](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)

---

## React 检查系统

agent-browser 提供了专门的 React 应用分析功能，包括 Suspense 边界检测和组件树分析。

### 阻塞器类型与权重

| 阻塞器类型 | 权重 | 可操作性 |
|------------|------|----------|
| ClientHook | 7 | 90% |
| RequestApi | 6 | 88% |
| ServerFetch | 5 | 82% |
| Cache | 4 | 74% |
| Stream | 3 | 60% |
| Unknown | 2 | 35% |
| Framework | 1 | 18% |

权重值越高表示该阻塞器对用户体验的影响越大，可操作性分数表示该类型阻塞被用户交互绕过的可能性。

### 边界类型

| 边界类型 | 权重 | 说明 |
|----------|------|------|
| RouteSegment | 3 | 路由段级别的 Suspense |
| ExplicitSuspense | 2 | 显式声明的 Suspense 边界 |
| Component | 1 | 组件级别的 Suspense |

资料来源：[cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)

---

## Web 仪表盘架构

仪表盘是可视化控制界面，使用 Next.js 构建，提供图形化的浏览器控制能力。

### 组件结构

```mermaid
graph TD
    A[Dashboard Root] --> B[控制面板]
    A --> C[结果展示区]
    A --> D[侧边栏]
    
    B --> E[ExtensionsPanel]
    B --> F[ControlsForm]
    
    C --> G[ChatPanel]
    C --> H[ConsolePanel]
    C --> I[NetworkPanel]
    
    D --> J[ResizablePanels]
    D --> K[Header]
```

### 核心组件

| 组件 | 功能 | 文件 |
|------|------|------|
| ChatPanel | 消息和工具调用展示 | chat-panel.tsx |
| ConsolePanel | JavaScript 控制台输出 | console-panel.tsx |
| NetworkPanel | 网络请求监控和 HAR 导出 | network-panel.tsx |
| ExtensionsPanel | Chrome 扩展管理 | extensions-panel.tsx |
| ConsolePanel | 控制台消息格式化 | console-panel.tsx |

#### 控制台面板功能

控制台面板支持表达式求值和结果展示：

- 语法高亮显示（紫色表示输入，绿色表示输出）
- 错误消息红色高亮
- 时间戳记录
- 加载状态动画

#### 网络面板功能

| 功能 | 说明 |
|------|------|
| 请求列表 | 显示所有捕获的网络请求 |
| 请求详情 | 展开查看请求头、响应体等 |
| HAR 导出 | 保存网络会话为 HAR 文件 |
| 过滤功能 | 按 URL 模式过滤请求 |

资料来源：[packages/dashboard/src/components/console-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/console-panel.tsx)

---

## 引擎系统

agent-browser 支持多种浏览器引擎，通过 `--engine` 参数选择。

### 支持的引擎

| 引擎 | 说明 |
|------|------|
| chrome | Chrome 浏览器的完整实现 |
| lightpanda | 轻量级替代方案 |

引擎安装通过 `install` 命令自动下载 Chrome from Chrome for Testing。

资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

---

## 标志与配置系统

CLI 工具支持丰富的命令行参数配置。

### 常用标志

| 标志 | 说明 |
|------|------|
| --annotate | 启用截图注释功能 |
| --color-scheme | 设置颜色方案（dark/light）|
| --download-path | 设置下载文件保存路径 |
| --content-boundaries | 显示内容边界 |
| --max-output | 最大输出大小限制 |
| --allowed-domains | 允许访问的域名列表 |
| --action-policy | 操作策略配置 |

配置解析采用手动参数解析方式，按顺序处理 args 数组：

```rust
"--annotate" => {
    let (val, consumed) = parse_bool_arg(args, i);
    flags.annotate = val;
    flags.cli_annotate = true;
    if consumed {
        i += 1;
    }
}
```

资料来源：[cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)

---

## 会话管理

agent-browser 支持会话管理，允许用户在不同会话间切换和恢复状态。

### 会话相关命令

```bash
# 连接到指定会话
agent-browser --session {SESSION} connect 9222

# 关闭会话
agent-browser --session {SESSION} close

# 录制操作
agent-browser --session {SESSION} record start
agent-browser --session {SESSION} record stop
```

会话持久化机制允许：

- 保存和恢复浏览器状态
- 跨会话追踪问题
- 批量复现和调试

---

## 网络与存储管理

### 网络监控

支持完整的网络请求监控和操作：

| 操作 | 说明 |
|------|------|
| route | 路由匹配和拦截 |
| unroute | 取消路由规则 |
| requests | 查看请求列表 |
| har | 导出 HAR 文件 |

### Cookie 管理

```bash
# 获取 Cookie
agent-browser cookies get

# 设置 Cookie
agent-browser cookies set --url https://example.com --name key --value val

# 清除 Cookie
agent-browser cookies clear

# 从文件导入
agent-browser cookies set --curl cookie.txt --domain example.com
```

### 存储管理

支持 Web Storage API：

| 存储类型 | 说明 |
|----------|------|
| local | localStorage |
| session | sessionStorage |

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

---

## 技能数据系统

agent-browser 使用 Markdown 格式的技能数据（Skill Data）来定义特定领域的工作流程和参考文档。

### 技能数据组织

```
skill-data/
├── core/              # 核心通用技能
│   └── references/    # 参考文档
├── slack/             # Slack 特定技能
│   ├── references/
│   └── SKILL.md
└── dogfood/           # 测试用技能
```

### 技能文档结构

每个技能文档通常包含：

1. **目标描述** - 明确要完成的任务
2. **操作步骤** - 具体的命令序列
3. **参考文档** - 元素定位和属性说明
4. **最佳实践** - 推荐的工作流程

---

## 测试架构

### 单元测试

```bash
cd cli && cargo test
```

- 运行所有单元测试（约 320 个）
- 测试速度快，无需启动 Chrome
- 覆盖核心业务逻辑

### 端到端测试

```bash
cd cli && cargo test e2e -- --ignored --test-threads=1
```

- 18 个 E2E 测试用例
- 启动真实 headless Chrome 实例
- 测试完整命令管道
- 要求串行执行避免实例冲突

资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

---

## 发布流程架构

项目使用手动发布模式，流程如下：

```mermaid
graph TD
    A[创建发布分支] --> B[更新版本号]
    B --> C[运行版本同步]
    C --> D[编写更新日志]
    D --> E[创建 PR]
    E --> F{合并到 main}
    F -->|是| G[CI 检测版本差异]
    F -->|否| H[等待合并]
    G -->|需要发布| I[构建 7 平台二进制]
    G -->|无需发布| J[跳过构建]
    I --> K[发布到 npm]
    K --> L[创建 GitHub Release]
```

版本同步命令：`pnpm version:sync` 自动更新：

- cli/Cargo.toml
- cli/Cargo.lock
- packages/dashboard/package.json

---

## 技术栈总结

| 层级 | 技术选型 | 版本管理 |
|------|----------|----------|
| CLI 核心 | Rust | Cargo |
| 浏览器自动化 | CDP (Chrome DevTools Protocol) | - |
| 仪表盘前端 | Next.js + React + TypeScript | pnpm |
| UI 组件 | shadcn/ui + Tailwind CSS | - |
| 构建工具 | Vite (仪表盘) | - |
| 包管理 | pnpm workspace | - |

---

<a id='cli-commands'></a>

## CLI 命令参考

### 相关页面

相关主题：[浏览器自动化核心](#browser-automation), [安装与构建](#installation-build)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/src/commands.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/commands.rs)
- [cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)
- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
- [skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)
</details>

# CLI 命令参考

## 概述

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

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

## 命令架构

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

```mermaid
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 元素，并可指定后续操作。

| 定位器 | 命令格式 | 说明 |
|--------|----------|------|
| role | `find role <role> [action] [--name <name>] [--exact]` | 通过 ARIA 角色定位 |
| text | `find text <text> [action] [--exact]` | 通过可见文本定位 |
| label | `find label <label> [action] [text] [--exact]` | 通过标签文本定位 |
| placeholder | `find placeholder <text> [action] [text] [--exact]` | 通过占位符文本定位 |
| alt | `find alt <text> [action] [--exact]` | 通过 alt 属性定位 |
| title | `find title <text> [action] [--exact]` | 通过 title 属性定位 |
| testid | `find testid <id> [action] [text]` | 通过测试 ID 定位 |
| first | `find first <selector> [action] [text]` | 定位第一个匹配元素 |
| last | `find last <selector> [action] [text]` | 定位最后一个匹配元素 |

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

### 元素交互命令

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

| 命令 | 功能 | 处理器函数 |
|------|------|------------|
| `click` | 点击元素 | handle_dispatch |
| `highlight` | 高亮显示元素 | handle_highlight |
| `tap` | 移动端点击 | handle_tap |
| `fill` | 填充输入框 | handle_setvalue |
| `type` | 模拟键盘输入 | handle_setvalue |
| `boundingbox` | 获取元素边界框 | handle_boundingbox |
| `innertext` | 获取元素文本 | handle_innertext |
| `innerhtml` | 获取元素 HTML | handle_innerhtml |
| `inputvalue` | 获取输入值 | handle_inputvalue |
| `setvalue` | 设置输入值 | handle_setvalue |
| `count` | 统计匹配元素数量 | handle_count |
| `styles` | 获取元素样式 | handle_styles |
| `select` | 选择下拉选项 | handle_select |
| `check` | 勾选复选框 | handle_check |
| `uncheck` | 取消勾选 | handle_uncheck |

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

### 状态查询命令

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

| 命令 | 返回值 | 说明 |
|------|--------|------|
| `visible` | true/false | 元素是否可见 |
| `enabled` | true/false | 元素是否启用 |
| `checked` | true/false | 复选框/单选框是否选中 |
| `isvisible` | true/false | 显式可见性检查 |
| `isenabled` | true/false | 显式启用状态检查 |
| `ischecked` | true/false | 显式选中状态检查 |
| `gettext` | 文本内容 | 获取元素文本 |
| `getattribute` | 属性值 | 获取元素属性 |

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

### 浏览器导航命令

| 命令 | 功能 |
|------|------|
| `back` | 后退一页 |
| `forward` | 前进一页 |
| `reload` | 刷新当前页面 |
| `open <url>` | 打开指定 URL |

### 快照与引用系统

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

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

**引用格式说明**：

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

**常见模式示例**：

| 引用 | 格式 | 说明 |
|------|------|------|
| @e1 | `[button] "Submit"` | 带文本的按钮 |
| @e2 | `[input type="email"]` | 邮箱输入框 |
| @e3 | `[input type="password"]` | 密码输入框 |
| @e4 | `[a href="/page"] "Link Text"` | 链接 |
| @e5 | `[select]` | 下拉选择框 |

资料来源：[skill-data/core/references/snapshot-refs.md]()

### 元素查找命令

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

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

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| locator | string | 是 | 定位策略 (role/text/label/...) |
| value | string | 是 | 定位值 |
| action | string | 否 | 执行的操作，默认 click |
| text | string | 否 | 额外文本匹配 |

**可选参数**：

| 参数 | 说明 |
|------|------|
| `--exact` | 精确匹配文本 |
| `--name <name>` | 按名称过滤 (role 定位器) |

资料来源：[cli/src/commands.rs:位置 1]()

### 鼠标操作命令

```bash
agent-browser mouse <action> [args]
```

| 操作 | 参数 | 说明 |
|------|------|------|
| `move` | `<x> <y>` | 移动到坐标 |
| `down` | `[btn]` | 鼠标按下 |
| `up` | `[btn]` | 鼠标释放 |
| `wheel` | `<dy> [dx]` | 滚动 |

### 浏览器设置命令

```bash
agent-browser set <setting> [value]
```

| 设置项 | 值格式 | 说明 |
|--------|--------|------|
| `viewport` | `<w> <h>` | 设置视口大小 |
| `device` | `<name>` | 设置设备模拟 |
| `geo` | `<lat> <lng>` | 设置地理坐标 |
| `offline` | `on\|off` | 离线模式 |
| `headers` | `<json>` | 设置请求头 |
| `credentials` | `<user> <pass>` | 设置认证凭证 |
| `media` | `[dark\|light] [reduced-motion]` | 媒体偏好 |

### 网络控制命令

```bash
agent-browser network <action>
```

| 操作 | 参数 | 说明 |
|------|------|------|
| `route` | `<url> [--abort\|--body <json>] [--resource-type <csv>]` | 拦截请求 |
| `unroute` | `[url]` | 取消拦截 |
| `requests` | `[--clear] [--filter <pattern>]` | 查看请求 |
| `har` | `<start\|stop> [path]` | HAR 记录 |

### Cookie 与存储命令

| 命令 | 说明 |
|------|------|
| `cookies get` | 获取所有 cookie |
| `cookies set` | 设置 cookie |
| `cookies clear` | 清除所有 cookie |
| `storage local` | 管理 localStorage |
| `storage session` | 管理 sessionStorage |

**cookies set 选项**：

| 选项 | 说明 |
|------|------|
| `--url` | 指定 URL |
| `--domain` | 指定域名 |
| `--path` | 指定路径 |
| `--httpOnly` | HTTP Only 标志 |
| `--secure` | Secure 标志 |
| `--sameSite` | SameSite 策略 |
| `--expires` | 过期时间 |
| `--curl <file>` | 从文件导入 (支持 JSON/cURL/Cookie 头) |

### 标签页管理命令

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

| 操作 | 说明 |
|------|------|
| `new` | 新建标签页 |
| `list` | 列出所有标签页 |
| `close` | 关闭当前标签页 |
| `<n>` | 切换到指定编号标签页 |

### 差异对比命令

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

### 截图命令

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

| 选项 | 说明 |
|------|------|
| path | 保存路径 |
| `--annotate` | 添加元素标注 |

## CLI 标志配置

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

| 标志 | 说明 | 来源文件 |
|------|------|----------|
| `--annotate` | 启用截图标注 | cli/src/flags.rs |
| `--color-scheme` | 颜色方案 (dark/light) | cli/src/flags.rs |
| `--download-path` | 下载保存路径 | cli/src/flags.rs |
| `--content-boundaries` | 内容边界检测 | cli/src/flags.rs |
| `--max-output` | 最大输出大小 | cli/src/flags.rs |
| `--allowed-domains` | 允许的域名列表 | cli/src/flags.rs |
| `--action-policy` | 操作策略配置 | cli/src/flags.rs |

**示例**：

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

## 特殊上下文命令

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

| 命令 | 处理器 | 功能 |
|------|--------|------|
| `timezone` | handle_timezone | 设置时区 |
| `locale` | handle_locale | 设置地区 |
| `geolocation` | handle_geolocation | 设置地理位置 |
| `permissions` | handle_permissions | 管理权限 |
| `dialog` | handle_dialog | 处理对话框 |
| `upload` | handle_upload | 文件上传 |
| `addscript` | handle_addscript | 注入脚本 |
| `addinitscript` | handle_addinitscript | 注入初始化脚本 |
| `removeinitscript` | handle_removeinitscript | 移除初始化脚本 |
| `addstyle` | handle_addstyle | 注入样式 |
| `react_tree` | handle_react_tree | React 组件树 |
| `react_inspect` | handle_react_inspect | React 检查器 |
| `react_renders_start` | handle_react_renders_start | 渲染监控开始 |
| `console` | handle_console | 控制台操作 |
| `errors` | handle_errors | 页面错误 |
| `state_save` | handle_state_save | 保存状态 |
| `state_load` | handle_state_load | 加载状态 |
| `state_list` | handle_state_list | 列出状态 |

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

## 等待命令

```bash
agent-browser wait [options]
```

| 选项 | 说明 |
|------|------|
| `<ms>` | 等待毫秒数 |
| `--load <strategy>` | 等待加载策略 (domcontentloaded/load/networkidle) |

## 使用模式与最佳实践

### 基本交互流程

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

### 推荐模式

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

```bash
# 正确顺序
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 支持多种输出格式：

| 格式 | 命令选项 | 适用场景 |
|------|----------|----------|
| 文本树 | 默认 | 快速查看页面结构 |
| JSON | `--json` | 程序化解析 |
| 截图 | `screenshot` | 可视化验证 |
| 带标注截图 | `screenshot --annotate` | 元素定位调试 |

## 错误处理

错误响应格式：

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

常用错误处理：

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

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

---

<a id='browser-automation'></a>

## 浏览器自动化核心

### 相关页面

相关主题：[CLI 命令参考](#cli-commands), [React 组件审查](#react-introspection), [网络监控与拦截](#network-monitoring)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/src/native/cdp/client.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/cdp/client.rs)
- [cli/src/native/cdp/chrome.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/cdp/chrome.rs)
- [cli/src/native/element.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/element.rs)
- [cli/src/native/screenshot.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/screenshot.rs)
- [cli/src/native/snapshot.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/snapshot.rs)
- [cli/src/native/diff.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/diff.rs)
- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
</details>

# 浏览器自动化核心

## 概述

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

核心职责包括：

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

```mermaid
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
```

## 架构分层

| 层级 | 模块 | 职责 |
|------|------|------|
| 命令接口层 | `actions.rs` | 解析和分发用户命令 |
| 状态管理层 | State | 维护浏览器会话状态、元素引用 |
| 协议通信层 | `cdp/client.rs` | CDP WebSocket 通信 |
| 浏览器连接层 | `cdp/chrome.rs` | Chrome 实例连接管理 |
| 功能实现层 | `element.rs`, `snapshot.rs`, `screenshot.rs`, `diff.rs` | 具体功能实现 |

## CDP 客户端架构

### 连接管理

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

主要连接流程：

```mermaid
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 格式，每条消息包含：

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

响应消息结构：

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

## 元素系统

### 元素引用机制

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

资料来源：[cli/src/native/element.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/element.rs)

### 元素操作命令

| 命令 | 功能 | 参数示例 |
|------|------|----------|
| `click` | 点击元素 | `@e1`, `--new-tab` |
| `fill` | 填充输入框 | `@e1 "text"` |
| `type` | 模拟打字 | `@e1 "text"` |
| `hover` | 鼠标悬停 | `@e1` |
| `focus` | 聚焦元素 | `@e1` |
| `blur` | 失焦元素 | `@e1` |
| `scroll` | 滚动操作 | `down 500`, `up 200` |

### 元素属性获取

```bash
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](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/snapshot.rs)

### 快照命令选项

| 选项 | 描述 |
|------|------|
| `-i` | 仅交互元素（推荐默认选项） |
| `-u` | 在链接上包含 href URL |
| `-c` | 紧凑模式（无空结构节点） |
| `-d <n>` | 限制深度为 n 层 |
| `-s "<selector>"` | 限定作用域为 CSS 选择器 |
| `--json` | 机器可读的 JSON 输出 |

### 快照输出示例

```
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 内部元素的引用携带框架上下文，交互命令可以直接使用，无需手动切换框架。

```bash
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](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/screenshot.rs)

```bash
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 组件中渲染时使用：

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

资料来源：[examples/environments/app/page.tsx](https://github.com/vercel-labs/agent-browser/blob/main/examples/environments/app/page.tsx)

## 差异比较系统

### Diff 功能

资料来源：[cli/src/native/diff.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/diff.rs)

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

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

### 快照差异示例

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

## 状态检查系统

### 元素状态查询

| 命令 | 功能 |
|------|------|
| `agent-browser is visible @e1` | 检查元素是否可见 |
| `agent-browser is enabled @e1` | 检查元素是否启用 |
| `agent-browser is checked @e1` | 检查复选框/单选框选中状态 |

## 高级交互

### React 调试集成

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

| 命令 | 功能 |
|------|------|
| `react_tree` | 获取 React 组件树 |
| `react_inspect` | 检查组件属性 |
| `react_renders_start` | 启动渲染计数 |
| `react_renders_stop` | 停止渲染计数 |

资料来源：[cli/src/native/actions.rs:60-62](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)

### 鼠标控制

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

### 键盘控制

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

## 浏览器环境配置

### 视口与设备模拟

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

###地理位置模拟

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

### 网络条件控制

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

### Cookie 和存储管理

```bash
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
```

## 工作流程

### 典型自动化流程

```mermaid
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            # 再执行操作
   ```

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

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

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

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

## 命令参考

### 完整命令列表

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

| 类别 | 命令 | 说明 |
|------|------|------|
| 页面 | `open`, `goto`, `back`, `forward`, `reload`, `stop` | 导航控制 |
| 快照 | `snapshot` | 获取可访问性树 |
| 截图 | `screenshot`, `pdf` | 视觉捕获 |
| 元素 | `click`, `fill`, `type`, `hover`, `focus`, `scroll` | 交互操作 |
| 获取 | `get` | 属性和状态查询 |
| 检查 | `is` | 状态验证 |
| 查找 | `find` | 元素搜索 |
| 鼠标 | `mouse` | 底层鼠标控制 |
| 设置 | `set` | 浏览器配置 |
| 网络 | `network` | 网络控制 |
| 存储 | `cookies`, `storage` | 存储管理 |
| 标签页 | `tab` | 多标签页控制 |
| 差异 | `diff` | 对比功能 |

## 扩展机制

### Chrome 扩展集成

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

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

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

资料来源：[packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx)

每个扩展条目显示：

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

## 底层动作处理

### 命令分发机制

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

```rust
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](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)

### 状态持久化

会话状态包括：

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

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

---

<a id='react-introspection'></a>

## React 组件审查

### 相关页面

相关主题：[浏览器自动化核心](#browser-automation), [CLI 命令参考](#cli-commands)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/src/native/react/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/mod.rs)
- [cli/src/native/react/tree.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/tree.rs)
- [cli/src/native/react/renders.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/renders.rs)
- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)
- [cli/src/native/react/vitals.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/vitals.rs)
- [cli/src/native/react/installHook.js](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/installHook.js)
- [skill-data/core/references/commands.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/commands.md)
</details>

# React 组件审查

## 概述

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

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

## 架构设计

### 整体架构

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

```mermaid
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]
```

### 核心模块职责

| 模块 | 文件路径 | 导出内容 | 功能描述 |
|------|----------|----------|----------|
| **mod.rs** | `cli/src/native/react/mod.rs` | 主入口 | 定义 INSTALL_HOOK_JS 常量，统一导出子模块 |
| **tree.rs** | `cli/src/native/react/tree.rs` | `TreeNode`, `format_tree` | 序列化组件树为可读格式 |
| **renders.rs** | `cli/src/native/react/renders.rs` | `RendersData`, `format_renders_report` | 追踪组件重新渲染 |
| **suspense.rs** | `cli/src/native/react/suspense.rs` | `Boundary`, `format_suspense_report` | 分析 Suspense 边界状态 |
| **vitals.rs** | `cli/src/native/react/vitals.rs` | `VitalsData`, `format_vitals_report` | 采集 Web Vitals 指标 |
| **installHook.js** | `cli/src/native/react/installHook.js` | Hook 脚本 | 注入 React DevTools 全局钩子 |

### 启动机制

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

```mermaid
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 标识符：

```javascript
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 节点，按照树形拓扑关系输出组件层级。

### 使用方式

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

### 输出格式

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

| 字段 | 说明 |
|------|------|
| Fiber ID | React 内部用于标识 Fiber 节点的唯一 ID |
| 组件类型 | 如 `div`、`button`、`MyComponent` |
| 显示名 | 经过处理的可读名称（如 DisplayName） |
| 渲染次数 | 该组件被渲染的总次数 |

### 数据结构

```rust
// 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 状态以及渲染来源位置。

### 使用方式

```bash
agent-browser react inspect <fiberId>
```

### 检查维度

| 检查维度 | 说明 | 数据来源 |
|----------|------|----------|
| 类型信息 | 组件的元素类型（如 `div`、`forward_ref`） | `_currentElement` |
| Props | 当前渲染使用的属性对象 | `node.props` |
| Hooks | 组件挂载的 hooks 状态 | Hook 内部数据结构 |
| 样式 | 内联样式信息 | `node._instance` |
| 源码位置 | 组件定义的文件和行号 | 源码映射 |

### 内部实现

`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 组件的重新渲染行为。通过追踪渲染次数和渲染耗时，帮助开发者识别性能瓶颈。

### 使用方式

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

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

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

### 数据模型

```rust
// 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,
}
```

### 输出报告格式

```json
{
  "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 边界。

### 使用方式

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

### 边界分类

| 边界类型 | 说明 | 标记 |
|----------|------|------|
| 静态边界 | 始终resolved，无动态加载行为 | `static` |
| 动态边界 | 包含未完成的异步加载（pending） | `suspended` |

### 数据结构

```rust
// 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 特有机制。

### 采集指标

| 指标 | 全称 | 说明 | 理想阈值 |
|------|------|------|----------|
| LCP | Largest Contentful Paint | 最大内容绘制时间 | < 2.5s |
| CLS | Cumulative Layout Shift | 累积布局偏移 | < 0.1 |
| TTFB | Time to First Byte | 首字节时间 | < 800ms |
| FCP | First Contentful Paint | 首次内容绘制 | < 1.8s |
| INP | Interaction to Next Paint | 交互到下次绘制 | < 200ms |

### 使用方式

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

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

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

### 数据模型

```rust
// 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 等路由库协同工作。

### 使用方式

```bash
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 框架：

```rust
"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` 参数：

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

### 2. 性能分析工作流

```mermaid
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 问题排查

```bash
# 查看所有边界
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 应用时提供精确的组件级别诊断信息，极大地提升了浏览器自动化测试的深度和准确性。

---

<a id='sessions-authentication'></a>

## 会话与认证管理

### 相关页面

相关主题：[网络监控与拦截](#network-monitoring), [浏览器自动化核心](#browser-automation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/src/native/state.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/state.rs)
- [cli/src/native/storage.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/storage.rs)
- [cli/src/native/auth.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/auth.rs)
- [cli/src/native/cookies.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/cookies.rs)
- [cli/src/native/policy.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/policy.rs)
- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
</details>

# 会话与认证管理

## 概述

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

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

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

资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

---

## 核心架构

### 目录结构

agent-browser 使用统一的本地状态目录存储所有会话相关数据：

```bash
~/.agent-browser/
├── sessions/          # 会话数据目录
├── auth/              # 认证存储
└── encryption.key     # 加密密钥
```

当无法解析用户主目录时，系统会回退到临时目录：

```bash
<tempdir>/agent-browser/
```

资料来源：[cli/src/native/state.rs:80-88](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/state.rs)

### 模块划分

```mermaid
graph TD
    A[CLI 命令层] --> B[动作分发层]
    B --> C[认证模块 auth.rs]
    B --> D[Cookie 模块 cookies.rs]
    B --> E[Storage 模块 storage.rs]
    B --> F[策略模块 policy.rs]
    C --> G[状态管理 state.rs]
    D --> G
    E --> G
    F --> G
    G --> H[CDP 客户端]
    H --> I[浏览器实例]
```

---

## 状态管理

### 状态根目录

`state.rs` 提供了获取状态目录的核心函数：

| 函数 | 返回值 | 说明 |
|------|--------|------|
| `get_state_dir()` | `PathBuf` | 返回 `~/.agent-browser` 或回退目录 |
| `get_sessions_dir()` | `PathBuf` | 返回 `~/.agent-browser/sessions` |

资料来源：[cli/src/native/state.rs:80-93](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/state.rs)

### 会话操作

系统支持以下会话级别的状态操作：

| 操作命令 | 功能描述 |
|----------|----------|
| `state_save` | 保存当前会话状态 |
| `state_load` | 加载指定会话状态 |
| `state_list` | 列出所有已保存的会话 |
| `state_clean` | 清理旧会话（默认 30 天） |
| `state_rename` | 重命名会话 |

资料来源：[cli/src/native/actions.rs:180-185](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)

### 存储状态模型

`StorageState` 结构体定义了会话持久化的数据模型：

```rust
struct StorageState {
    cookies: Vec<Cookie>,
    // ... 其他字段
}

struct Cookie {
    name: String,
    value: String,
    domain: String,
    path: String,
    expires: f64,
}
```

资料来源：[cli/src/native/state.rs:95-105](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/state.rs)

---

## Cookie 管理

### CLI 命令接口

```bash
# Cookie 操作
agent-browser cookies get                    # 获取当前 Cookie
agent-browser cookies set --url <url> ...    # 设置 Cookie
agent-browser cookies clear                  # 清除所有 Cookie

# 完整参数选项
--url <domain>      # Cookie 关联的域名
--domain <host>     # Cookie 域
--path <path>       # Cookie 路径
--httpOnly          # HttpOnly 标记
--secure            # Secure 标记
--sameSite <policy> # SameSite 策略
--expires <timestamp>  # 过期时间戳
```

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

### 支持的 Cookie 属性

| 参数 | 类型 | 说明 |
|------|------|------|
| `name` | String | Cookie 名称 |
| `value` | String | Cookie 值 |
| `domain` | String | 所属域名 |
| `path` | String | URL 路径 |
| `expires` | f64 | Unix 时间戳格式的过期时间 |
| `httpOnly` | bool | HttpOnly 标志 |
| `secure` | bool | Secure 标志 |
| `sameSite` | String | SameSite 策略 |

### 自动导入功能

系统支持从多种格式自动导入 Cookie：

- **JSON 格式** - 标准 Cookie 对象数组
- **cURL 格式** - 使用 `--curl` 参数指定文件
- **Cookie Header 格式** - 直接解析 `Cookie:` 头部

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

---

## Web Storage 管理

### 存储类型

agent-browser 支持两种 Web Storage API：

| 存储类型 | CLI 命令 | 说明 |
|----------|----------|------|
| localStorage | `storage local` | 持久化存储，跨会话保留 |
| sessionStorage | `storage session` | 会话级存储，标签页关闭后清除 |

### CLI 命令

```bash
# Storage 操作
agent-browser storage local get    # 获取 localStorage
agent-browser storage local set   # 设置 localStorage
agent-browser storage local clear # 清除 localStorage

agent-browser storage session get # 获取 sessionStorage
agent-browser storage session set # 设置 sessionStorage
agent-browser storage session clear # 清除 sessionStorage
```

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

### 动作处理器映射

| 操作 | 处理器函数 |
|------|-----------|
| 获取存储 | `handle_storage_get` |
| 设置存储 | `handle_storage_set` |
| 清除存储 | `handle_storage_clear` |

资料来源：[cli/src/native/actions.rs:140-142](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)

---

## 认证系统

### 认证存储架构

认证模块负责管理敏感凭证数据，存储在 `~/.agent-browser/auth/` 目录下。该目录包含：

- HTTP 认证凭证
- 代理认证信息
- 证书配置

### 认证配置命令

```bash
# 设置认证凭证
agent-browser set credentials <username> <password>

# 设置代理认证
agent-browser set proxy-auth <username> <password>
```

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

---

## 策略管理

### 动作策略

policy.rs 模块定义了浏览器动作的安全策略：

| 策略类型 | 说明 |
|----------|------|
| 内容边界 | `--content-boundaries` 控制元素交互范围 |
| 最大输出 | `--max-output` 限制输出数据量 |
| 允许域名 | `--allowed-domains` 白名单限制 |
| 动作策略 | `--action-policy` 动作执行策略 |

### 策略参数

```bash
# 域名限制
agent-browser --allowed-domains example.com,vercel.com

# 输出限制
agent-browser --max-output 10000

# 内容边界
agent-browser --content-boundaries true
```

资料来源：[cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)

---

## 工作流程

### 会话创建与保存流程

```mermaid
sequenceDiagram
    participant CLI
    participant Actions
    participant State
    participant CDP
    participant Browser

    CLI->>Actions: cookies_set / storage_set
    Actions->>CDP: 执行 CDP 命令
    CDP->>Browser: 设置 Cookie/Storage
    Browser-->>CDP: 确认
    CDP-->>Actions: 结果
    Actions->>State: state_save
    State->>State: 序列化到 ~/.agent-browser/sessions/
```

### 状态恢复流程

```mermaid
sequenceDiagram
    participant CLI
    participant Actions
    participant State
    participant CDP
    participant Browser

    CLI->>Actions: state_load
    Actions->>State: 读取会话文件
    State-->>Actions: StorageState 对象
    Actions->>CDP: 创建/恢复 Cookie
    CDP->>Browser: 注入 Cookie
    Actions->>CDP: 恢复 Storage
    CDP->>Browser: 注入 Storage
```

---

## CLI 完整命令参考

### 会话管理

| 命令 | 参数 | 说明 |
|------|------|------|
| `tab new` | - | 创建新标签页 |
| `tab list` | - | 列出所有标签页 |
| `tab close` | `<n>` | 关闭指定标签页 |
| `tab <n>` | - | 切换到指定标签页 |

### 认证与存储

```bash
# Cookie 完整操作
agent-browser cookies get
agent-browser cookies set --url https://example.com --name session --value abc123
agent-browser cookies clear

# Storage 完整操作
agent-browser storage local get
agent-browser storage session get
agent-browser storage local set --key theme --value dark
agent-browser storage clear

# 状态管理
agent-browser state_save --name my-session
agent-browser state_load --name my-session
agent-browser state_list
agent-browser state_clean --days 7
```

资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)

---

## 安全考虑

### 敏感数据处理

1. **加密存储** - 认证数据使用加密密钥保护
2. **临时回退** - 无法访问主目录时使用临时目录
3. **会话清理** - 支持自动清理过期会话（默认 30 天）

### 最佳实践

- 定期使用 `state_clean` 清理旧会话
- 使用 `--allowed-domains` 限制 Cookie 作用域
- 避免在命令行中直接传递敏感凭证
- 使用 `state_save` 定期备份重要会话状态

---

## 相关文档

- [技能文档](../skill-data/core/references/snapshot-refs.md) - 快照与元素引用
- [Slack 技能](../skill-data/slack/references/slack-tasks.md) - 会话管理示例
- [架构说明](../AGENTS.md) - 完整系统架构

---

<a id='network-monitoring'></a>

## 网络监控与拦截

### 相关页面

相关主题：[会话与认证管理](#sessions-authentication), [浏览器自动化核心](#browser-automation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/src/native/network.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/network.rs)
- [cli/src/native/stream/http.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/http.rs)
- [cli/src/native/stream/websocket.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/websocket.rs)
- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)
- [packages/dashboard/src/components/network-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/network-panel.tsx)
</details>

# 网络监控与拦截

## 概述

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

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

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

## 核心功能模块

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

| 模块 | 功能描述 | 源码位置 |
|------|----------|----------|
| 网络路由 | 请求拦截、abort、响应修改 | `cli/src/native/network.rs` |
| HTTP 流处理 | HTTP 请求/响应解析 | `cli/src/native/stream/http.rs` |
| WebSocket 处理 | WebSocket 帧解析和转发 | `cli/src/native/stream/websocket.rs` |
| Dashboard UI | 可视化网络监控面板 | `network-panel.tsx` |

## 网络命令接口

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

资料来源：[cli/src/output.rs:50-60]()

### network 命令族

```bash
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 路由规则，可以对匹配的请求进行拦截处理。

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

#### 参数说明

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 要拦截的目标 URL，支持模式匹配 |
| `--abort` | flag | 否 | 中止匹配的请求，不返回任何响应 |
| `--body <json>` | string | 否 | 返回自定义 JSON 响应体 |
| `--resource-type <csv>` | string | 否 | 按资源类型过滤（如 document, script, stylesheet） |

#### 使用示例

```bash
# 中止所有对特定 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 - 移除路由规则

```bash
agent-browser network unroute [url]
```

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

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

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

## 请求监控

### requests - 实时请求列表

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

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

| 参数 | 说明 |
|------|------|
| `--clear` | 清空请求历史记录 |
| `--filter <pattern>` | 按 URL 模式过滤请求 |

## HAR 录制

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

### 开始录制

```bash
agent-browser network har start
```

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

### 停止录制并保存

```bash
agent-browser network har stop [path]
```

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

```bash
# 保存到默认文件
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 管理功能：

```bash
agent-browser cookies [get|set|clear]
```

| 操作 | 说明 |
|------|------|
| `get` | 获取当前 Cookie 列表 |
| `set` | 设置 Cookie（支持 --url, --domain, --path, --httpOnly, --secure, --sameSite, --expires 参数） |
| `clear` | 清除所有 Cookie |

#### set 子命令参数

| 参数 | 说明 |
|------|------|
| `--url <url>` | 设置 Cookie 的目标 URL |
| `--domain <domain>` | Cookie 所属域名 |
| `--path <path>` | Cookie 路径 |
| `--httpOnly` | 标记为 HttpOnly |
| `--secure` | 标记为 Secure |
| `--sameSite <strict\|lax\|none>` | SameSite 属性 |
| `--expires <timestamp>` | 过期时间戳 |
| `--curl <file>` | 从 cURL 格式文件导入 |

#### 从 cURL 导入

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

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

### Web Storage 管理

```bash
agent-browser storage <local|session>
```

| 类型 | 说明 |
|------|------|
| `local` | 管理 localStorage |
| `session` | 管理 sessionStorage |

## 架构设计

### 网络监控流程

```mermaid
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
```

### 请求拦截状态机

```mermaid
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` 命令模拟响应：

```bash
# 模拟用户列表 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": "alice@example.com"}'
```

### 场景二：调试网络错误

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

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

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

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

```bash
# 开始录制
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

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

## 最佳实践

### 1. 清理路由规则

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

```bash
agent-browser network unroute
```

### 2. 使用资源类型过滤

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

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

### 3. HAR 文件管理

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

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

## 命令速查表

| 功能 | 命令 |
|------|------|
| 拦截请求 | `network route <url> --abort` |
| 自定义响应 | `network route <url> --body <json>` |
| 查看请求 | `network requests` |
| 过滤请求 | `network requests --filter "<pattern>"` |
| 清除请求列表 | `network requests --clear` |
| 开始 HAR 录制 | `network har start` |
| 停止 HAR 录制 | `network har stop [path]` |
| 移除路由规则 | `network unroute [url]` |
| 获取 Cookie | `cookies get` |
| 设置 Cookie | `cookies set --url <url> --domain <domain>` |
| 清除 Cookie | `cookies clear` |
| 管理 localStorage | `storage local` |
| 管理 sessionStorage | `storage session` |

---

<a id='dashboard-components'></a>

## 仪表板组件

### 相关页面

相关主题：[文档站点](#documentation-site), [系统架构](#architecture-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/dashboard/src/app/page.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/app/page.tsx)
- [packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx) *(已获取)*
- [packages/dashboard/src/components/activity-feed.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/activity-feed.tsx)
- [packages/dashboard/src/components/chat-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/chat-panel.tsx)
- [packages/dashboard/src/components/network-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/network-panel.tsx)
- [packages/dashboard/src/store/chat.ts](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/store/chat.ts)
- [packages/dashboard/src/store/activity.ts](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/store/activity.ts)

> 注：本页主要基于已获取的 `extensions-panel.tsx` 源码及项目结构分析生成。其他组件文件内容需在实际检索后补充完善。
</details>

# 仪表板组件

## 概述

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

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

## 架构设计

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| 前端框架 | React 18+ | 组件化 UI 开发 |
| 语言 | TypeScript | 类型安全 |
| 状态管理 | Zustand | 轻量级状态管理 |
| 样式 | Tailwind CSS | 原子化 CSS 框架 |
| 构建工具 | Vite | 快速开发构建 |

### 组件目录结构

```
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 浏览器扩展。组件采用可折叠的卡片式布局，支持显示扩展名称、描述和安装路径。

#### 组件结构

```tsx
// 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]()

#### 扩展数据模型

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

#### Header 子组件

```tsx
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 管理聊天会话状态：

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

| 状态字段 | 类型 | 描述 |
|----------|------|------|
| `messages` | `Message[]` | 消息列表 |
| `sendMessage` | `function` | 发送消息动作 |
| `clearHistory` | `function` | 清空历史记录 |

### Activity Store

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

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

## 主页面布局

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

```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]()

## 数据流图

```mermaid
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 进行样式管理，遵循以下设计规范：

| 样式类别 | 工具类前缀 | 示例 |
|----------|------------|------|
| 间距 | `p-`, `m-`, `gap-` | `px-3 py-2` |
| 字体 | `text-` | `text-[10px]` |
| 颜色 | `text-`, `bg-`, `border-` | `text-muted-foreground` |
| 圆角 | `rounded-` | `rounded-lg` |
| 布局 | `flex-`, `grid-` | `flex shrink-0` |

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

## Badge 组件使用

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

```tsx
<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. **结果展示**：将命令执行结果（截图、快照）渲染到对应面板

```mermaid
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 样式类

### 状态更新流程

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

## 已知限制

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

## 相关资源

- [CLI 输出模块参考](../cli/src/output.md)
- [核心技能文档](../skill-data/core/SKILL.md)
- [Electron 应用集成](../skill-data/electron/SKILL.md)

---

<a id='documentation-site'></a>

## 文档站点

### 相关页面

相关主题：[仪表板组件](#dashboard-components), [安装与构建](#installation-build)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/next.config.mjs](https://github.com/vercel-labs/agent-browser/blob/main/docs/next.config.mjs)
- [docs/src/app/layout.tsx](https://github.com/vercel-labs/agent-browser/blob/main/docs/src/app/layout.tsx)
- [docs/src/lib/docs-navigation.ts](https://github.com/vercel-labs/agent-browser/blob/main/docs/src/lib/docs-navigation.ts)
- [docs/src/lib/mdx-to-markdown.ts](https://github.com/vercel-labs/agent-browser/blob/main/docs/src/lib/mdx-to-markdown.ts)
- [docs/src/components/docs-sidebar.tsx](https://github.com/vercel-labs/agent-browser/blob/main/docs/src/components/docs-sidebar.tsx)
- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)
</details>

# 文档站点

## 概述

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

## 技术架构

### 框架选型

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

```mermaid
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`) 负责渲染文档导航界面，提供以下功能：

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

## 内容结构

### 主要文档分类

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

| 分类名称 | 内容范围 | 源文件位置 |
|----------|----------|------------|
| 核心指南 | 基本使用、工作流、最佳实践 | `skill-data/core/` |
| Slack 集成 | Slack 工作空间自动化 | `skill-data/slack/` |
| 探索测试 | QA 测试和缺陷追踪 | `skill-data/dogfood/` |
| 更新日志 | 版本发布说明 | `docs/src/app/changelog/page.mdx` |

### 文档模板结构

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

```markdown
# 技能标题

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

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

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

## 变更日志管理

### CHANGELOG.md 结构

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

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

### 文档变更日志同步

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

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

```markdown
## v0.24.0

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

---
```

## 开发指南

### 本地开发

文档站点的开发和运行需要以下步骤：

1. 进入文档目录：`cd docs`
2. 安装依赖：`npm install`
3. 启动开发服务器：`npm run dev`

### 构建流程

构建文档站点时，Next.js 会执行以下操作：

1. 扫描 `docs/src/app/` 目录下的所有页面
2. 处理 MDX/Markdown 内容文件
3. 应用 `mdx-to-markdown.ts` 定义的转换规则
4. 生成静态 HTML 文件用于部署

## 相关资源

| 资源类型 | 路径 | 描述 |
|----------|------|------|
| 配置文件 | `docs/next.config.mjs` | Next.js 构建配置 |
| 布局组件 | `docs/src/app/layout.tsx` | 根布局定义 |
| 导航逻辑 | `docs/src/lib/docs-navigation.ts` | 导航结构管理 |
| 转换模块 | `docs/src/lib/mdx-to-markdown.ts` | 内容格式转换 |
| 侧边栏 | `docs/src/components/docs-sidebar.tsx` | 导航界面组件 |

## 技术要点

### 内容同步机制

文档站点内容与 `skill-data/` 目录下的源文件保持紧密关联。CLI 工具通过 `agent-browser skills get` 命令动态加载技能内容，确保文档与实际安装版本一致。

### 响应式设计

文档站点采用响应式设计策略：

- 桌面端：侧边栏固定显示，主体内容居中
- 移动端：侧边栏收起，通过汉堡菜单触发
- 断点配置：使用 Tailwind CSS 标准的响应式断点

### 无障碍支持

站点实现基本的无障碍特性：

- 语义化 HTML 标签
- 键盘导航支持
- 足够的颜色对比度
- ARIA 标签配置

---

<a id='installation-build'></a>

## 安装与构建

### 相关页面

相关主题：[项目介绍](#introduction), [CLI 命令参考](#cli-commands)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/build-all-platforms.sh](https://github.com/vercel-labs/agent-browser/blob/main/scripts/build-all-platforms.sh)
- [scripts/copy-native.js](https://github.com/vercel-labs/agent-browser/blob/main/scripts/copy-native.js)
- [cli/build.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/build.rs)
- [docker/Dockerfile.build](https://github.com/vercel-labs/agent-browser/blob/main/docker/Dockerfile.build)
- [docker/docker-compose.yml](https://github.com/vercel-labs/agent-browser/blob/main/docker/docker-compose.yml)
- [pnpm-lock.yaml](https://github.com/vercel-labs/agent-browser/blob/main/pnpm-lock.yaml)
</details>

# 安装与构建

本页面详细介绍 agent-browser 项目的安装依赖、环境配置、源码构建流程以及多平台部署方案。agent-browser 是一个基于 Rust 实现的核心浏览器自动化守护进程，配合 TypeScript/React 前端组件构成完整的浏览器控制工具链。

## 系统要求

### 硬件与操作系统

| 组件 | 最低要求 | 推荐配置 |
|------|---------|----------|
| CPU | 2 核 | 4 核及以上 |
| 内存 | 4 GB | 8 GB |
| 磁盘空间 | 2 GB | 10 GB（包含 Chromium） |
| 操作系统 | macOS 10.15+ / Linux (glibc 2.17+) / Windows 10+ | 最新稳定版 |

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

### 必需依赖

```bash
# 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](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 环境配置

### 克隆源码

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

### 安装 Node.js 依赖

```bash
# 安装所有 workspace 依赖
pnpm install

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

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

### 配置 Rust 环境

```bash
# 验证 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
```

## 构建流程

### 完整构建

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

```bash
./scripts/build-all-platforms.sh
```

该脚本执行以下步骤：

```mermaid
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](https://github.com/vercel-labs/agent-browser/blob/main/scripts/build-all-platforms.sh)

### 分步构建

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

```bash
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. 复制原生二进制到前端

```bash
node scripts/copy-native.js
```

该脚本将编译好的原生二进制文件复制到前端包的 `native/` 目录，供 Electron 或 WebAssembly 加载使用。资料来源：[scripts/copy-native.js](https://github.com/vercel-labs/agent-browser/blob/main/scripts/copy-native.js)

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

```bash
# 构建生产版本
pnpm build

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

### 构建脚本详解

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

```rust
// 伪代码展示 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](https://github.com/vercel-labs/agent-browser/blob/main/cli/build.rs)

## Docker 构建

### Dockerfile.build

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

```dockerfile
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](https://github.com/vercel-labs/agent-browser/blob/main/docker/Dockerfile.build)

### docker-compose.yml

```yaml
version: '3.8'

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

资料来源：[docker/docker-compose.yml](https://github.com/vercel-labs/agent-browser/blob/main/docker/docker-compose.yml)

### 使用 Docker 构建

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

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

## 测试

### 单元测试

```bash
cd cli
cargo test
```

运行所有单元测试（约 320 个测试），这些测试执行速度快，无需启动 Chrome 实例。资料来源：[AGENTS.md:61-63](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

### 端到端测试

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

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

| 要求 | 说明 |
|------|------|
| Chrome 必须已安装 | 用于启动 headless 浏览器实例 |
| 串行执行 | 必须使用 `--test-threads=1` 避免 Chrome 实例冲突 |
| 测试数量 | 共 18 个 e2e 测试 |

资料来源：[AGENTS.md:68-73](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 发布流程

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

```mermaid
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](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)

## 常见问题

### 编译错误：链接库缺失

```bash
# 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
```

### 交叉编译失败

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

```bash
# 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` 参数指定浏览器引擎：

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

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

```bash
agent-browser install chrome
```

## 环境变量参考

| 变量名 | 作用 | 默认值 |
|--------|------|--------|
| `RUST_LOG` | 日志级别 | `info` |
| `CARGO_HOME` | Cargo 缓存目录 | `~/.cargo` |
| `TARGET_DIR` | 构建产物目录 | `cli/target` |
| `AGENT_BROWSER_CHROMIUM_PATH` | 指定 Chromium 路径 | 自动检测 |

## 构建产物

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

| 产物 | 位置 | 说明 |
|------|------|------|
| `agent-browser` (CLI) | `cli/target/release/` | 命令行工具主程序 |
| Dashboard 资源 | `packages/dashboard/dist/` | 前端 Web 界面 |
| 原生绑定 | `packages/dashboard/native/` | 跨平台二进制集合 |
| Docker 镜像 | 本地镜像仓库 | 可部署的容器化版本 |

---

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: vercel-labs/agent-browser; human_manual_source: deepwiki_human_wiki -->