> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Zeus Browser Operator 浏览器自动化扩展

Browser Operator 是 Zeus 的浏览器自动化扩展，允许 AI Agent 控制用户浏览器执行自动化任务。

## 概述

Browser Operator 通过 Chrome 扩展实现，让 AI 能够：

* 导航到网页
* 点击元素
* 填写表单
* 提取内容
* 截取屏幕截图
* 执行 JavaScript

## 安装

### 从 Chrome Web Store

1. 访问 Chrome Web Store
2. 搜索 "Zeus Browser Operator"
3. 点击"添加至 Chrome"
4. 确认安装

### 开发者模式安装

1. 下载扩展源码
2. 打开 `chrome://extensions`
3. 开启"开发者模式"
4. 点击"加载已解压的扩展程序"
5. 选择扩展目录

## 架构

```mermaid theme={null}
flowchart TD
    subgraph Browser["User Browser"]
        Ext["Browser-Operator Extension\n- 接收 WebSocket 指令\n- 执行浏览器操作 (click, type, scroll...)\n- 返回执行结果和截图"]
    end
    subgraph WS["WebSocket Server"]
        WSInner["- JWT 认证\n- 连接管理\n- 消息路由"]
    end
    subgraph Backend["Zeus AI Backend"]
        Agent["AgentService\n- 调用 LLM\n- 解析 Tool Calls\n- 发送浏览器指令"]
    end
    Ext <-->|"WebSocket (wss://)"| WSInner
    WSInner <-->|"HTTP + JWT"| Agent
```

## 连接流程

### 1. 安装扩展

安装后，扩展会在工具栏显示 Zeus 图标。

### 2. 登录授权

1. 点击扩展图标
2. 登录 Zeus 账号（或扫码登录）
3. 授权扩展访问权限

### 3. 建立连接

```mermaid theme={null}
flowchart TD
    A["扩展启动"] -->|"获取 JWT Token"| B["连接 WebSocket 服务器"]
    B --> C["发送认证消息"]
    C --> D["等待接收指令"]
```

## 支持的操作

### 导航

| 操作                 | 描述      | 参数    |
| ------------------ | ------- | ----- |
| `browser_navigate` | 导航到 URL | `url` |
| `browser_back`     | 返回上一页   | -     |
| `browser_forward`  | 前进      | -     |
| `browser_refresh`  | 刷新页面    | -     |

### 元素交互

| 操作               | 描述      | 参数             |
| ---------------- | ------- | -------------- |
| `browser_click`  | 点击元素    | `ref`          |
| `browser_type`   | 追加输入文本  | `ref`, `text`  |
| `browser_fill`   | 清空并输入文本 | `ref`, `text`  |
| `browser_select` | 选择下拉选项  | `ref`, `value` |
| `browser_hover`  | 鼠标悬停    | `ref`          |

### 页面操作

| 操作                   | 描述     | 参数                    |
| -------------------- | ------ | --------------------- |
| `browser_scroll`     | 滚动页面   | `direction`, `amount` |
| `browser_screenshot` | 截取屏幕   | `fullPage`            |
| `browser_get_text`   | 获取元素文本 | `ref`                 |
| `browser_snapshot`   | 获取页面结构 | -                     |

### 高级操作

| 操作                      | 描述            | 参数                     |
| ----------------------- | ------------- | ---------------------- |
| `browser_wait`          | 等待指定时间        | `seconds`              |
| `browser_execute_js`    | 执行 JavaScript | `script`               |
| `browser_handle_dialog` | 处理对话框         | `accept`, `promptText` |

## 元素引用 (ref)

Browser Operator 使用元素引用 (ref) 来标识页面元素。

### 获取 ref

使用 `browser_snapshot` 获取页面结构，返回包含 ref 的元素列表。每个元素包含 `ref`（唯一标识符）、`tag`（HTML 标签）、`text`（元素文本）等信息。

### 使用 ref

获取到 ref 后，可以在后续操作（如 `browser_click`、`browser_fill`）中使用该 ref 来精确定位目标元素。

## 安全机制

### 权限控制

* **per-action approval** - 每个操作可配置是否需要用户确认
* **domain restrictions** - 可限制只在特定域名操作
* **action logging** - 所有操作都有日志记录

### 沙盒环境

* 扩展在沙盒环境运行
* 无法访问浏览器敏感数据（如密码、Cookies）
* 无法访问其他扩展的数据

### 认证安全

* 使用 JWT Token 认证
* Token 定期刷新
* 支持设备撤销

## 使用场景

### 表单自动填写

```
用户: 帮我填写这个注册表单

Zeus: 我将使用 Browser Operator 自动填写表单。
1. 首先获取页面结构...
2. 找到输入框并填写信息...
3. 点击提交按钮...
```

### 网页数据提取

```
用户: 提取这个页面上的所有产品信息

Zeus: 我来提取页面数据。
1. 分析页面结构...
2. 定位产品元素...
3. 提取名称、价格、描述...
```

### 自动化测试

```
用户: 测试这个登录流程

Zeus: 我将执行登录测试。
1. 导航到登录页...
2. 输入测试凭证...
3. 点击登录...
4. 验证登录成功...
```

## 故障排除

### 扩展显示"未连接"

1. 检查是否已登录
2. 刷新扩展（在 chrome://extensions 点击刷新）
3. 检查 WebSocket 服务器是否运行
4. 查看浏览器控制台错误

### 操作执行失败

1. 确保页面已完全加载
2. 检查元素 ref 是否有效
3. 尝试使用 `browser_snapshot` 更新元素列表
4. 检查是否有弹窗阻止操作

### 截图空白

1. 等待页面渲染完成
2. 检查是否有 iframe 内容
3. 尝试使用 `fullPage: false` 参数

## MCP 服务器

Browser Operator 也作为 MCP 服务器运行，可以被其他 MCP 客户端调用。所有浏览器操作工具（如 `browser_navigate`、`browser_click` 等）均通过标准 MCP 协议暴露。

## 与 Lingda 平台集成

Browser Operator 可以集成到第三方平台（如 Lingda）：

### 认证流程

1. 第三方后端调用 Zeus API 获取 JWT
2. 将 JWT 传递给 Browser Operator 扩展
3. 扩展使用 JWT 连接 WebSocket

### 工具调用流程

```mermaid theme={null}
flowchart LR
    LB["Lingda Backend"] -->|"Tool Call"| WS["Zeus WebSocket"]
    WS -->|"Execute Action"| BO["Browser Operator"]
    BO -->|"Return Result"| WS
    WS -->|"Tool Result"| LB
```