# 浏览器工具说明

## 1. 概述

JiuwenSwarm 浏览器工具用于驱动真实 Chrome 完成网页访问、表单填写、页面点击、
文件上传和信息提取等任务。

Chrome 由浏览器 Agent 统一管理。用户只需在前端配置 Chrome 可执行文件和显示
模式，Agent 会在首次执行浏览器任务时自动启动浏览器，不再需要从前端单独启动
浏览器服务。

浏览器工具支持：

- 打开网页并等待页面加载
- 点击元素、输入文本和上传文件
- 执行多步骤网页任务
- 复用会话及其登录状态
- 读取页面标题、URL 和页面内容

## 2. 快速上手

### 2.1 安装 Chrome

请先在运行 JiuwenSwarm 的机器上安装 Google Chrome。托管驱动通常可以自动识别
标准安装位置。

如果 Chrome 安装在自定义目录，可打开 `chrome://version`，复制“可执行文件路径”，
并在下一步中配置。

### 2.2 配置浏览器

1. 打开 JiuwenSwarm 前端。
2. 进入“设置” > “浏览器”。
3. 按需填写 Chrome 可执行文件的完整路径；留空时使用自动检测。
4. 需要观察浏览器或人工登录时，启用“显示浏览器”；无需人工操作时可关闭。
5. 保存设置。

显示模式发生变化时，系统会在必要时重启浏览器运行时，确保后续任务使用新的模式。

### 2.3 执行浏览器任务

直接让 Agent 打开网页、提取信息、填写表单或继续已授权流程。浏览器 Agent 会自动
启动并管理 Chrome。

在显示模式下，首次浏览器任务开始时会弹出 Chrome 窗口。如任务需要登录、MFA、
扫码或其他人工授权，请在该托管窗口中完成，然后回到对话继续任务。

## 3. 使用建议

- 依赖登录态的长流程尽量保持在同一个 Agent 会话中。
- 登录、MFA、扫码和授权场景使用显示模式。
- 不需要人工交互的任务可使用无头模式。
- 正常使用 JiuwenSwarm 时，不要再额外启动使用固定调试端口的 Chrome；托管驱动会
  自动选择并注入正确的 CDP 地址。
- 除非明确需要短超时，建议保持 `BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE=0`。

## 4. 案例

### 4.1 提取网页信息

1. 在对话中输入：“请从 https://example.com/news 提取今天的新闻标题和摘要。”
2. Agent 会自动启动托管浏览器、访问页面并返回结果。

### 4.2 发送带附件的邮件

1. 启用“显示浏览器”并保存。
2. 让 Agent 打开 Gmail。
3. 如有需要，在托管 Chrome 窗口中完成登录。
4. 让 Agent 编写邮件并上传附件。

## 5. 配置

### 5.1 `config.yaml`

| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `browser.chrome_path` | string/map | `""` | Chrome 可执行文件。留空时自动检测，也可按操作系统配置路径。 |
| `browser.headless` | boolean | `true` | 设为 `false` 时显示托管浏览器窗口。 |

示例：

```yaml
browser:
  chrome_path:
    windows: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
    macos: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
    linux: "/usr/bin/google-chrome"
  headless: true
```

`chrome_path` 留空时会清除之前配置的可执行文件，由 openJiuwen 从系统中自动检测
Chrome。填写路径后，该路径是唯一依据；如果它不是有效的 Chrome 可执行文件，浏览器
启动会直接报错，不会静默改用其他安装路径。

### 5.2 高级环境变量

大多数安装无需设置以下变量。

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `BROWSER_DRIVER` | JiuwenSwarm 中为 `managed` | 浏览器驱动模式。 |
| `BROWSER_MANAGED_BINARY` | 自动检测 | openJiuwen 直接运行时的覆盖项；JiuwenSwarm 会根据 `browser.chrome_path` 生成该值。 |
| `BROWSER_MANAGED_PORT` | `9333` | 非 keyed 托管实例的端口；keyed 实例自动分配空闲端口。 |
| `BROWSER_MANAGED_USER_DATA_DIR` | 托管 Profile 目录 | 覆盖托管浏览器的 Profile 目录。 |
| `BROWSER_MANAGED_ARGS` | 根据显示模式生成 | 额外的 Chrome 启动参数。 |
| `BROWSER_MANAGED_KILL_EXISTING` | `false` | 启动前终止匹配的既有 Chrome。仅在明确 Profile 所有权时启用。 |

`PLAYWRIGHT_CDP_URL` 用于显式的远程驱动模式，正常的托管浏览器流程不需要配置它。

## 6. 架构

浏览器生命周期为：

`前端保存设置 -> Agent 浏览器任务 -> 自动启动托管 Chrome -> 执行任务 -> 复用会话`

- 前端 `BrowserPanel` 只负责读取和保存 Chrome 路径与显示模式。
- JiuwenSwarm 将这些设置映射到浏览器 Agent 运行时。
- openJiuwen 的 `BrowserService` 和 `ManagedBrowserDriver` 负责按需分配端口、启动
  Chrome、健康检查、复用 Profile，并随 Agent 生命周期停止。
- Playwright MCP 使用托管实例注入的端点，不再依赖前端启动的浏览器。

这样，浏览器启动、Profile 所有权、端点分配和清理都由浏览器 Agent 这一处统一管理。