> ## 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 automation extension

Browser Operator is Zeus's browser automation extension, enabling AI Agents to control the user's browser to perform automated tasks.

## Overview

Browser Operator is implemented as a Chrome extension, allowing AI to:

* Navigate to web pages
* Click elements
* Fill out forms
* Extract content
* Take screenshots
* Execute JavaScript

## Installation

### From Chrome Web Store

1. Visit the Chrome Web Store
2. Search for "Zeus Browser Operator"
3. Click "Add to Chrome"
4. Confirm installation

### Developer Mode Installation

1. Download the extension source code
2. Open `chrome://extensions`
3. Enable "Developer mode"
4. Click "Load unpacked"
5. Select the extension directory

## Architecture

```mermaid theme={null}
flowchart TD
    subgraph Browser["User Browser"]
        Ext["Browser-Operator Extension\n- Receives WebSocket commands\n- Executes browser actions (click, type, scroll...)\n- Returns results and screenshots"]
    end
    subgraph WS["WebSocket Server"]
        WSInner["- JWT authentication\n- Connection management\n- Message routing"]
    end
    subgraph Backend["Zeus AI Backend"]
        Agent["AgentService\n- Calls LLM\n- Parses Tool Calls\n- Sends browser commands"]
    end
    Ext <-->|"WebSocket (wss://)"| WSInner
    WSInner <-->|"HTTP + JWT"| Agent
```

## Connection Flow

### 1. Install Extension

After installation, the extension displays a Zeus icon in the toolbar.

### 2. Login and Authorization

1. Click the extension icon
2. Log in to your Zeus account (or scan QR code to log in)
3. Authorize extension access

### 3. Establish Connection

```mermaid theme={null}
flowchart TD
    A["Extension starts"] -->|"Obtain JWT Token"| B["Connect to WebSocket server"]
    B --> C["Send authentication message"]
    C --> D["Wait for incoming commands"]
```

## Supported Actions

### Navigation

| Action             | Description     | Parameters |
| ------------------ | --------------- | ---------- |
| `browser_navigate` | Navigate to URL | `url`      |
| `browser_back`     | Go back         | -          |
| `browser_forward`  | Go forward      | -          |
| `browser_refresh`  | Refresh page    | -          |

### Element Interaction

| Action           | Description            | Parameters     |
| ---------------- | ---------------------- | -------------- |
| `browser_click`  | Click element          | `ref`          |
| `browser_type`   | Append text input      | `ref`, `text`  |
| `browser_fill`   | Clear and input text   | `ref`, `text`  |
| `browser_select` | Select dropdown option | `ref`, `value` |
| `browser_hover`  | Hover mouse            | `ref`          |

### Page Actions

| Action               | Description        | Parameters            |
| -------------------- | ------------------ | --------------------- |
| `browser_scroll`     | Scroll page        | `direction`, `amount` |
| `browser_screenshot` | Take screenshot    | `fullPage`            |
| `browser_get_text`   | Get element text   | `ref`                 |
| `browser_snapshot`   | Get page structure | -                     |

### Advanced Actions

| Action                  | Description             | Parameters             |
| ----------------------- | ----------------------- | ---------------------- |
| `browser_wait`          | Wait for specified time | `seconds`              |
| `browser_execute_js`    | Execute JavaScript      | `script`               |
| `browser_handle_dialog` | Handle dialog           | `accept`, `promptText` |

## Element References (ref)

Browser Operator uses element references (refs) to identify page elements.

### Getting a ref

Use `browser_snapshot` to get the page structure, which returns an element list with refs. Each element includes a `ref` (unique identifier), `tag` (HTML tag), `text` (element text), and more.

### Using a ref

After obtaining a ref, you can use it in subsequent actions (such as `browser_click`, `browser_fill`) to precisely locate the target element.

## Security Mechanisms

### Permission Control

* **Per-action approval** - Each action can be configured to require user confirmation
* **Domain restrictions** - Restrict actions to specific domains only
* **Action logging** - All actions are logged

### Sandbox Environment

* The extension runs in a sandbox environment
* Cannot access sensitive browser data (such as passwords or cookies)
* Cannot access data from other extensions

### Authentication Security

* Uses JWT Token authentication
* Tokens are refreshed periodically
* Supports device revocation

## Use Cases

### Automated Form Filling

```
User: Help me fill out this registration form

Zeus: I'll use Browser Operator to fill out the form automatically.
1. First, get the page structure...
2. Locate input fields and fill in the information...
3. Click the submit button...
```

### Web Data Extraction

```
User: Extract all product information from this page

Zeus: I'll extract the page data.
1. Analyze the page structure...
2. Locate product elements...
3. Extract names, prices, descriptions...
```

### Automated Testing

```
User: Test this login flow

Zeus: I'll execute a login test.
1. Navigate to the login page...
2. Enter test credentials...
3. Click login...
4. Verify login success...
```

## Troubleshooting

### Extension Shows "Not Connected"

1. Check if you're logged in
2. Refresh the extension (click refresh on chrome://extensions)
3. Check if the WebSocket server is running
4. Check browser console for errors

### Action Execution Failed

1. Ensure the page has fully loaded
2. Check if the element ref is valid
3. Try using `browser_snapshot` to refresh the element list
4. Check if a popup is blocking the action

### Blank Screenshot

1. Wait for page rendering to complete
2. Check for iframe content
3. Try using `fullPage: false` parameter

## MCP Server

Browser Operator also runs as an MCP server and can be invoked by other MCP clients. All browser action tools (such as `browser_navigate`, `browser_click`, etc.) are exposed through the standard MCP protocol.

## Integration with Lingda Platform

Browser Operator can be integrated with third-party platforms (such as Lingda):

### Authentication Flow

1. Third-party backend calls Zeus API to obtain a JWT
2. JWT is passed to the Browser Operator extension
3. Extension uses JWT to connect to WebSocket

### Tool Invocation Flow

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