# 浏览器工具说明

## 1. 简介
浏览器工具是 JiuwenBot 中用于驱动真实浏览器完成网页任务的一套能力。它适合处理需要表单填写、页面点击、文件上传、网页检索等场景。

从使用方式上看，用户先在前端页面中配置本机 Chrome 路径并启动浏览器服务。系统会拉起一个可被授权的 Chrome 浏览器实例；后续在任务需要时，Agent 会连接并操控这个浏览器完成操作。

## 2. 技术简介
当前浏览器工具的核心链路如下：

- 前端页面提供“浏览器服务”面板，用于配置 Chrome 可执行文件路径并启动浏览器服务。
- 后端通过 `browser_start_client.py` 启动本机 Chrome，并开启远程调试能力。
- 浏览器自动化运行时基于 Playwright MCP 封装，浏览器工具通过 MCP client 与运行时通信。
- Agent 调用 `browser_run_task` 等工具时，运行时会把自然语言任务转换为浏览器操作步骤。
- 浏览器会按 `session_id` 复用，同一会话下可以保持登录态、页面上下文和授权状态。

可以简单理解为：

`前端配置 -> 启动 Chrome -> 运行时接管 Chrome -> Agent 在需要时操控浏览器执行任务`

## 3. 主要功能
浏览器工具目前主要支持以下能力：

- 打开网页并等待页面加载
- 在已登录网站中继续操作
- 点击按钮、输入文本、选择页面元素
- 执行多步网页任务
- 复用同一浏览器会话，减少重复登录
- 在需要时读取页面标题、URL、页面结果
- 配合附件上传、邮件填写、网页表单提交等复杂任务

## 4. 前端使用步骤
如果要在前端使用浏览器工具，请先确保本机已经安装 Chrome 浏览器。

### 步骤 1：确认 Chrome 安装路径和 Profile 目录
1. 打开 Chrome 浏览器。
2. 在地址栏输入 `chrome://version` 并回车。
3. 记录以下两个信息：
   - **可执行文件路径**：用于填写 `CHROME_PATH`
   - **个人资料路径 / Profile 路径**：用于确认当前浏览器使用的用户目录和配置目录

其中：
- 可执行文件路径一般是 `chrome.exe` 的完整路径。
- Profile 目录用于帮助确认当前浏览器账户和资料目录，方便排查登录态或授权问题。

### 步骤 2：打开前端的“浏览器服务”面板

1. 打开 JiuwenBot 前端页面。

![浏览器服务面板示意图](../assets/images/browser1.png)

2. 进入“设置”中的“浏览器服务”区域。
3. 找到 Chrome 路径输入框。

![浏览器路径配置示意图](../assets/images/browser2.png)


### 步骤 3：填写 CHROME_PATH
1. 将在 `chrome://version` 中看到的 Chrome 可执行文件完整路径复制出来。

![chrome系统路径查询示意图](../assets/images/browser3.png)

2. 粘贴到前端页面的 `CHROME_PATH` 输入框中。
3. 点击“保存路径”。

### 步骤 4：启动浏览器服务
1. 在浏览器服务面板中点击“启动浏览器服务”。
2. 系统会调用后端启动脚本，拉起一个 Chrome 浏览器。
3. 如果启动成功，通常会弹出一个新的 Chrome 窗口。

这个弹出的 Chrome 就是后续可被 Agent 操控的浏览器实例。

### 步骤 5：在弹出的浏览器中完成必要授权
如果你的任务需要登录网站、授权邮箱、访问企业系统或使用已有账号状态，请在这个 Chrome 中完成必要的人工操作，例如：

- 登录 Gmail / Outlook / 企业邮箱
- 通过短信、验证码、扫码等人工认证
- 允许站点访问权限
- 打开需要操作的目标页面

### 步骤 6：交给 Agent 使用浏览器工具
完成授权后，用户就可以在对话里提出需要浏览器执行的任务，例如：

- 打开某个网页并读取信息
- 登录后继续点击和填写表单
- 在邮箱中写邮件、上传附件、等待确认

当任务需要浏览器时，Agent 会操控这个已经获得授权的 Chrome，而不是重新新建一个完全无状态的浏览器。

## 5. 后端配置方式
后端配置主要分为两部分：

- `config/config.yaml`：负责本机 Chrome 启动参数
- `.env`：负责浏览器运行时、MCP 通信、Playwright 和超时参数

### 5.1 config/config.yaml
`config/config.yaml` 中的 `browser` 配置块用于启动本机 Chrome。当前支持的字段如下：

```yaml
browser:
  chrome_path: "C:\\Users\\YOUR_USER\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe"
  remote_debugging_address: "127.0.0.1"
  remote_debugging_port: 9222
  user_data_dir: ""
  profile_directory: "Default"
```

字段说明：

- `browser.chrome_path`
  - Chrome 可执行文件路径
  - 可以是单个字符串，也可以按 OS 写成 map
  - 前端“保存路径”本质上就是把这个字段写回 `config/config.yaml`
- `browser.remote_debugging_address`
  - Chrome 远程调试监听地址
  - 一般保持 `127.0.0.1`
- `browser.remote_debugging_port`
  - Chrome 远程调试端口
  - 默认通常为 `9222`
- `browser.user_data_dir`
  - Chrome 用户数据目录
  - 留空时，启动脚本会按系统使用默认目录
- `browser.profile_directory`
  - 要使用的 Chrome Profile 名称
  - 常见值是 `Default`

如果你希望按操作系统分别配置 `chrome_path`，可以这样写：

```yaml
browser:
  chrome_path:
    windows: "C:\\Users\\YOUR_USER\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe"
    macos: "/Applications/Google Chrome.app"
    linux: "/usr/bin/google-chrome"
  remote_debugging_address: "127.0.0.1"
  remote_debugging_port: 9222
  user_data_dir: ""
  profile_directory: "Default"
```

### 5.2 .env 中的浏览器运行时配置
`.env` 中和浏览器工具直接相关的字段主要有以下几组。

#### A. 浏览器 MCP wrapper 配置

```dotenv
BROWSER_RUNTIME_MCP_ENABLED=1
BROWSER_RUNTIME_MCP_CLIENT_TYPE=streamable-http
BROWSER_RUNTIME_MCP_SERVER_ID=playwright_runtime_wrapper
BROWSER_RUNTIME_MCP_SERVER_NAME=playwright-runtime-wrapper
BROWSER_RUNTIME_MCP_SERVER_PATH=http://127.0.0.1:8940/mcp
BROWSER_RUNTIME_MCP_TIMEOUT_S=300
BROWSER_RUNTIME_MCP_HOST=127.0.0.1
BROWSER_RUNTIME_MCP_PORT=8940
BROWSER_RUNTIME_MCP_PATH=/mcp
BROWSER_RUNTIME_MCP_COMMAND=
BROWSER_RUNTIME_MCP_ARGS=
BROWSER_RUNTIME_MCP_AUTO_SSE_FALLBACK=1
```

字段说明：

- `BROWSER_RUNTIME_MCP_ENABLED`
  - 是否启用浏览器 MCP wrapper
  - `1` 表示启用
- `BROWSER_RUNTIME_MCP_CLIENT_TYPE`
  - MCP client 类型
  - 当前推荐 `streamable-http`
- `BROWSER_RUNTIME_MCP_SERVER_ID` / `BROWSER_RUNTIME_MCP_SERVER_NAME`
  - wrapper 的标识信息
- `BROWSER_RUNTIME_MCP_SERVER_PATH`
  - wrapper 访问地址
  - `streamable-http` 模式通常为 `http://127.0.0.1:8940/mcp`
- `BROWSER_RUNTIME_MCP_TIMEOUT_S`
  - MCP 连接或调用层的超时控制
- `BROWSER_RUNTIME_MCP_HOST` / `BROWSER_RUNTIME_MCP_PORT` / `BROWSER_RUNTIME_MCP_PATH`
  - 本地自动拉起 wrapper 时使用的 host、port、path
- `BROWSER_RUNTIME_MCP_COMMAND` / `BROWSER_RUNTIME_MCP_ARGS`
  - wrapper 启动命令覆盖项
  - 通常留空，使用系统默认行为即可
- `BROWSER_RUNTIME_MCP_AUTO_SSE_FALLBACK`
  - 某些模式下是否允许 SSE fallback

#### B. Playwright 官方 MCP 配置

```dotenv
PLAYWRIGHT_MCP_COMMAND=npx
PLAYWRIGHT_MCP_ARGS=-y @playwright/mcp@latest
PLAYWRIGHT_CDP_URL=http://127.0.0.1:9222
```

字段说明：

- `PLAYWRIGHT_MCP_COMMAND`
  - 启动官方 Playwright MCP 的命令
  - 当前默认是 `npx`
- `PLAYWRIGHT_MCP_ARGS`
  - 启动官方 Playwright MCP 的参数
- `PLAYWRIGHT_CDP_URL`
  - 连接到已启动 Chrome 的 CDP 地址
  - 这里应与 `config.yaml` 中的调试地址和端口保持一致

#### C. 超时与执行策略配置

```dotenv
PLAYWRIGHT_TOOL_TIMEOUT_S=300
BROWSER_TIMEOUT_S=300
BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE=0
```

字段说明：

- `PLAYWRIGHT_TOOL_TIMEOUT_S`
  - 浏览器工具执行的总 watchdog 超时
- `BROWSER_TIMEOUT_S`
  - 浏览器任务默认长超时
  - 如果模型传入的 `timeout_s` 更小，默认会被钳回至少这个值
- `BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE`
  - 是否允许模型把任务超时改得更短
  - `0` 表示不允许，推荐保持为 `0`

### 5.3 推荐的最小后端配置
如果你要跑当前推荐链路，至少保证下面这些字段正确：

`config/config.yaml`

```yaml
browser:
  chrome_path: "C:\\Users\\YOUR_USER\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe"
  remote_debugging_address: "127.0.0.1"
  remote_debugging_port: 9222
  user_data_dir: ""
  profile_directory: "Default"
```

`.env`

```dotenv
BROWSER_RUNTIME_MCP_ENABLED=1
BROWSER_RUNTIME_MCP_CLIENT_TYPE=streamable-http
BROWSER_RUNTIME_MCP_SERVER_PATH=http://127.0.0.1:8940/mcp
PLAYWRIGHT_MCP_COMMAND=npx
PLAYWRIGHT_MCP_ARGS=-y @playwright/mcp@latest
PLAYWRIGHT_CDP_URL=http://127.0.0.1:9222
PLAYWRIGHT_TOOL_TIMEOUT_S=300
BROWSER_TIMEOUT_S=300
BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE=0
```

## 6. 使用建议
为了让浏览器工具更稳定，建议遵循以下做法：

- 尽量使用本机真实安装的 Chrome，而不是临时浏览器。
- 启动浏览器服务后，优先在弹出的 Chrome 中完成登录和授权。
- 对于长流程任务，尽量保持同一个会话，避免频繁更换浏览器状态。
- 如果任务涉及邮箱、企业系统、网银等场景，建议先人工完成一次登录，再交给 Agent 继续操作。
- 如果浏览器状态异常，可以重新启动浏览器服务后再测试。
- 建议让 `PLAYWRIGHT_CDP_URL` 与 `config.yaml` 中的远程调试地址、端口保持一致。
- 建议保持 `BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE=0`，避免模型把浏览器任务拆成过多短调用。

## 7. 相关代码与配置索引
下面这些文件是浏览器工具链路中最重要的入口。

### 前端
- `jiuwenbot/web/src/components/BrowserPanel/index.tsx`
  - 前端浏览器服务面板
  - 负责读取路径、保存路径、触发“启动浏览器服务”

### 后端应用入口
- `app.py`
  - 提供 `path.get`、`path.set`、`browser.start` 等前端调用入口

### Chrome 启动脚本
- `jiuwenbot/agentserver/tools/browser_start_client.py`
  - 读取 `config/config.yaml` 中的 `browser.*` 配置
  - 启动带远程调试能力的 Chrome

### 浏览器 MCP 接入
- `jiuwenbot/agentserver/tools/browser_tools.py`
  - 浏览器 MCP wrapper 的接入、自动拉起、client patch、配置构建

### 浏览器运行时
- `jiuwenbot/agentserver/tools/browser-move/src/playwright_runtime_mcp_server.py`
  - 浏览器 runtime 的 MCP server 入口
- `jiuwenbot/agentserver/tools/browser-move/src/playwright_runtime/runtime.py`
  - 浏览器 runtime 编排层
- `jiuwenbot/agentserver/tools/browser-move/src/playwright_runtime/service.py`
  - 浏览器任务执行、session 复用、timeout guardrails
- `jiuwenbot/agentserver/tools/browser-move/src/playwright_runtime/agents.py`
  - 主编排 agent 与浏览器 worker agent 的提示词和构造逻辑
- `jiuwenbot/agentserver/tools/browser-move/src/playwright_runtime/config.py`
  - Playwright MCP 与浏览器运行时配置解析

### 配置文件
- `config/config.yaml`
  - Chrome 启动参数
- `.env`
  - 浏览器 runtime、MCP、Playwright、超时等环境变量
- `.env.template`
  - 环境变量模板

## 8. 一句话总结
浏览器工具的本质，是让 Agent 在用户已经授权过的真实 Chrome 上执行网页操作；前端负责配置和启动，后端负责接管和自动化执行。
