# Aa Browser

**为 AI Agent 而生的开源桌面浏览器。**

![License](https://img.shields.io/badge/license-MIT-blue) ![CI](https://github.com/yuchen0x1/aa-browser/actions/workflows/ci.yml/badge.svg) ![Platform](https://img.shields.io/badge/platform-Windows-lightgrey) ![MCP](https://img.shields.io/badge/protocol-MCP-purple)

> 人像人一样浏览网页，Agent 像工程师一样驱动它。
> **The Agent-Native Browser** — snapshots, actions, and packet capture over MCP.

传统浏览器是为"人眼看像素"设计的；而 AI Agent 需要的是**结构化页面数据**。Aa Browser 是一个完整的 Chromium 浏览器，任何人都可以正常使用它上网；同时，任何支持 MCP（Model Context Protocol）的 AI Agent 都可以连接进来，读取页面的**结构化快照**（可访问性树 + 元素 ref 编号），并执行点击、输入、选择、滚动、提取等操作——不看截图、不猜坐标。

## 特性

- 🖥️ **真浏览器**：基于 Electron（Chromium），标签页 / 地址栏 / 前进后退 / 登录态持久化，一应俱全
- 🧠 **结构化快照**：页面被转换成 YAML 风格的可访问性树，每个可交互元素带 `ref` 编号（`- button "登录" [ref=e5]`），格式对齐 Playwright MCP 生态，Agent 零学习成本
- 💸 **增量快照省 token**：页面没变 → 一行回复；小变化 → 只返回变更区块；ref 跨快照稳定复用（React 重渲染也能靠内容签名接上）；跳转/大变化自动回退完整快照。一次多步任务可省 60%+ 上下文
- 🤖 **MCP 原生接入**：标准 stdio MCP 桥，ZCode / Claude Code / Cursor 等任何 MCP 客户端均可驱动
- 🔒 **本地安全**：WebSocket 仅监听 127.0.0.1，随机端口 + 一次性 token，拒绝非本机连接
- 🎯 **真实输入路径**：点击走受信任的输入事件（`isTrusted=true`），输入走 `insertText` 管线并对 React 受控组件兜底，被遮挡元素自动降级为合成事件
- 🔁 **动作后自动快照**：每次点击/输入后自动返回新快照，Agent 无需二次请求即可继续决策

## 快照示例

在必应首页调用 `browser_snapshot` 得到：

```text
页面快照 url: https://www.bing.com/
title: 搜索 - Microsoft 必应
元素数: 19

- banner "登录 Rewards 手机版"
  - img "必应"
  - navigation
    - menuitem "图片" [ref=e1]
    - menuitem "视频" [ref=e3]
- search
  - combobox "搜索网页" [ref=e15]
  - button "语音搜索" [ref=e16]
```

Agent 随后：

```jsonc
{ "tool": "browser_type",   "arguments": { "ref": "e15", "text": "Aa Browser", "submit": true } }
```

点击/输入后自动返回的是**增量快照**——只有变化的区块：

```text
页面快照（增量） url: https://www.bing.com/search?q=Aa+Browser
title: Aa Browser - 搜索
变化: +6 / -1（共 214 行，其余未变，仍以上次快照为准）

  - search
+ - link "agent-browser.dev" [ref=e37]
+ - text "Browser automation for AI agents …"
- - text "（旧的空白提示）"

新增 ref: e37 e38
失效 ref: e12
```

页面未变化时只回一行（≈50 token）；跳转到新页面或变化过大时自动回退完整快照。`browser_snapshot { full: true }` 可强制完整树。

## 架构

```text
┌─────────────────────────────────────────────────────┐
│                Aa Browser (Electron)                │
│  ┌───────────────────────────────────────────────┐  │
│  │  外壳 UI（标签栏/地址栏） ←→ 主进程 IPC        │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  页面标签 WebContentsView × N                 │  │
│  │    └─ 注入快照引擎（DOM → YAML 树 + ref 表）  │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  Agent 服务 ws://127.0.0.1:<random>           │  │
│  │    ~/.aabrowser/connection.json (port+token)  │  │
│  └───────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────┘
                           │ 本地 WebSocket（token 鉴权）
┌──────────────────────────┴──────────────────────────┐
│  cli/mcp.mjs —— stdio MCP 桥（零依赖）              │
│    任何 MCP 客户端：ZCode / Claude Code / Cursor …  │
└─────────────────────────────────────────────────────┘
```

## 快速开始

### ⚡ 复制粘贴给 AI，全自动安装接入（推荐给 AI 客户端用户）

把 [PROMPT.md](./PROMPT.md) 里的提示词**整段复制给你的 AI 客户端**（ZCode / Claude Code / Cursor…），AI 会自动完成下载 → 安装 → 启动 → 写入你本机的 MCP 配置。

不用 AI 的话，等价的手动命令（先拿到 install.mjs 与安装包）：

```bash
node install.mjs --url  <安装包直链或本地路径>     # 下载/安装/启动/接入一条龙
node install.mjs --repo yuchen0x1/aa-browser            # 自动拉 GitHub Releases 最新版
node install.mjs --url <...> --clients zcode,cursor   # 只接入指定客户端
```

> 需要先把安装包发布到可公开下载的位置（GitHub Releases / 网盘直链），步骤见 [PROMPT.md](./PROMPT.md) 末尾"给发布者"。

### 其他方式

要求：Node.js ≥ 20，Windows / macOS / Linux。

### 方式一：Windows 安装包（推荐给普通用户）

```bash
npm run dist       # 产出 release/Aa Browser-Setup-<版本>.exe（NSIS 安装器）
```

双击安装（未做代码签名，Windows SmartScreen 会提示"更多信息 → 仍要运行"）。装好后打开 Aa Browser，新标签页上有**「一键接入你的 AI 客户端」**卡片，勾选客户端点一下即完成 MCP 配置。

### 方式二：源码运行（开发者）

```bash
git clone https://github.com/yuchen0x1/aa-browser.git aa-browser
cd aa-browser
npm install        # 首次会下载 Electron，慢可设镜像：
                   # export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm run build      # 构建主进程 / 预加载 / 渲染层
npm start          # 启动 Aa Browser
```

开发模式（热更新渲染层）：

```bash
npm run dev
```

## 接入你的 Agent

**方式 A · 一键接入（推荐）**：Aa Browser 新标签页 → 「一键接入你的 AI 客户端」卡片 → 勾选 → 写入。
命令行等效：`node cli/setup.mjs --yes`（`--list` 查看，`--client zcode,cursor` 指定目标）。
支持：**ZCode / Claude Code / Cursor / Windsurf / Cline / VS Code / Gemini CLI / Qwen Code**。写入前自动备份原配置为 `<file>.aa-backup-<时间戳>`，幂等可重复执行。

**方式 B · 手动配置**：在 MCP 客户端配置中添加：

```jsonc
{
  "mcpServers": {
    "aa-browser": {
      "command": "node",
      "args": ["C:\Program Files\aa-browser 或 %LOCALAPPDATA%\Programs\Aa Browser/cli/mcp.mjs"]
    }
  }
}
```

**前提**：Aa Browser 保持运行（它会在 `~/.aabrowser/connection.json` 写入本地端口与 token，MCP 桥通过它发现浏览器）。

然后让 Agent 干活，例如："用浏览器打开 GitHub trending，把前 10 个项目整理成表格" 或 "打开 xx 后台，把登录后的接口响应都抓给我看"。

## MCP 工具

| 工具 | 说明 |
| --- | --- |
| `browser_navigate` | 导航到 URL（非 URL 文本自动转搜索词；结果内嵌完整快照，`snapshot: false` 可跳过） |
| `browser_snapshot` | 结构化页面快照（增量模式省 token；`full: true` 强制完整树） |
| `browser_click` | 按 ref 点击（自动返回增量快照） |
| `browser_type` | 按 ref 输入文本（支持 `submit` 回车提交、`clear` 清空） |
| `browser_select_option` | 按 ref 选择下拉项（按 value 或可见文本匹配） |
| `browser_scroll` | 滚动页面（先主文档，后最大滚动区域） |
| `browser_extract` | 提取整页或指定元素的纯文本 |
| `browser_wait` | 等待指定文本出现（轮询） |
| `browser_press_key` | 按键：Enter / Escape / 方向键 / 单字符等 |
| `browser_screenshot` | PNG 截图（图像 + 保存路径） |
| `browser_console` | 读取页面控制台日志 |
| `browser_network_requests` | **抓包**：列出捕获的 HTTP 请求（方法/状态/类型/大小/耗时/URL，支持过滤） |
| `browser_network_detail` | **抓包**：单个请求的完整请求/响应头 + 响应体（`body: true`） |
| `browser_har` | **抓包**：导出 HAR 1.2 文件（可导入 DevTools/Fiddler 人工分析） |
| `browser_tabs` | 列表 / 新建 / 切换 / 关闭标签页 |

## MCP 工具

| 工具 | 说明 |
| --- | --- |
| `browser_navigate` | 导航到 URL（非 URL 文本自动转搜索词；结果内嵌完整快照，`snapshot: false` 可跳过） |
| `browser_snapshot` | 结构化页面快照（增量模式省 token；`full: true` 强制完整树） |
| `browser_click` | 按 ref 点击（自动返回增量快照） |
| `browser_type` | 按 ref 输入文本（支持 `submit` 回车提交、`clear` 清空） |
| `browser_select_option` | 按 ref 选择下拉项（按 value 或可见文本匹配） |
| `browser_scroll` | 滚动页面（先主文档，后最大滚动区域） |
| `browser_extract` | 提取整页或指定元素的纯文本 |
| `browser_wait` | 等待指定文本出现（轮询） |
| `browser_press_key` | 按键：Enter / Escape / 方向键 / 单字符等 |
| `browser_screenshot` | PNG 截图（图像 + 保存路径） |
| `browser_console` | 读取页面控制台日志 |
| `browser_tabs` | 列表 / 新建 / 切换 / 关闭标签页 |

## 安全说明

- Agent 服务只监听 `127.0.0.1`，连接需携带启动时生成的随机 token
- token 与端口写在用户目录 `~/.aabrowser/connection.json`（仅当前用户可读）
- 一键接入写入其他客户端配置前**自动备份**、只改 `aa-browser` 一个键、幂等可重复
- **注意**：Agent 能看到你登录的页面内容与网络流量。请勿让不可信的 Agent 访问网银、工作邮箱等高敏站点；后续版本将加入"操作确认弹窗"与站点白名单（见 Roadmap）

## 项目结构

```text
aa-browser/
├── src/
│   ├── main/          # 主进程：窗口 / 标签 / 动作 / 抓包 / Agent 服务 / MCP 工具 / 客户端接入
│   ├── preload/       # 外壳 UI 与新标签页的 IPC 桥
│   ├── renderer/      # 浏览器外壳 UI + 新标签页（一键接入卡片）
│   ├── shared/        # 三方共享的协议类型
│   └── snapshot/      # 注入引擎（DOM → 快照）与动作脚本
├── cli/
│   ├── mcp.mjs        # stdio MCP 桥（零依赖）
│   └── setup.mjs      # 一键接入 CLI（零依赖）
├── scripts/           # 冒烟测试 / 实战测试 / 图标生成
├── electron.vite.config.ts
└── electron-builder.yml
```

## 测试

```bash
npm run smoke   # 端到端冒烟：启动浏览器 → MCP 驱动 → 断言（含抓包，无外网依赖）
node scripts/live-test.mjs   # 实战示例：MCP 驱动必应搜索全流程
```

## Roadmap

- [ ] 操作确认弹窗：Agent 点击/提交前可选人工确认
- [ ] 站点白名单 / 会话隔离分区
- [x] ~~快照增量更新与缓存（进一步降 token）~~（v0.2.0 已完成）
- [x] ~~一键接入各大 AI 客户端 + 网络抓包工具集 + Windows 安装包~~（v0.3.0 已完成）
- [ ] 请求拦截与 Mock（Agent 修改/重放请求）
- [ ] npm 发布 `aa-browser-mcp`，支持 `npx` 一行接入
- [ ] macOS / Linux 打包分发、代码签名

## License

[MIT](./LICENSE)