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

# 浏览器自动化中间件

浏览器自动化中间件让 ChatKit 客户端可以操作承载对话的浏览器页面。它把一组安全的 Playwright 风格页面动作暴露为客户端工具，让智能体能够查看当前页面、点击控件、填写表单、滚动、跳转、等待页面状态，并在 DOM 定位不足时通过截图和视口坐标继续操作。

中间件 provider 名称是 `browser-automation`。

## 适用场景

当智能体需要处理用户浏览器中打开的页面时，可以使用浏览器自动化中间件：

* 辅助用户操作 Web 应用、管理后台、仪表板或表单。
* 在行动前读取页面结构并选择目标元素。
* 填写搜索条件或业务表单，然后等待页面刷新。
* 操作 SAP/Fiori、iframe 较多或 DOM 标签不稳定的复杂企业页面。
* 与 [ChatKit 浏览器扩展](/docs/ai/tutorial/chatkit-browser-extension) 配合使用。

## 工作方式

浏览器自动化中间件基于 ChatKit 客户端工具中间件实现：

1. 中间件向模型声明 `host_page_*` 工具。
2. 模型调用工具时，ChatKit 将请求发送到浏览器客户端。
3. 浏览器客户端执行页面操作并返回工具结果。
4. 中间件发出可读的工具调用消息，并把结果回灌到模型上下文。
5. 对于截图结果，中间件会把图片附加到下一次模型调用，并提供 `host_page_pointer` 的坐标换算提示。

它还会额外注入一个服务端等待工具 `host_page_wait`，用于在页面渲染、动画、跳转或异步请求后等待一段时间。

## 配置项

| 字段                | 类型        | 默认值    | 说明                                                                     |
| ----------------- | --------- | ------ | ---------------------------------------------------------------------- |
| `allowNavigation` | `boolean` | `true` | 是否暴露 `host_page_navigate`，让智能体可以把宿主页面跳转到 HTTP(S) URL。不希望智能体离开当前页面时可关闭。 |

示例：

```json theme={null}
{
  "allowNavigation": true
}
```

## 客户端要求

浏览器自动化需要 ChatKit 客户端实现这些客户端工具调用。Xpert ChatKit 浏览器扩展已内置支持，并可优先使用 Chrome DevTools Protocol 获得更丰富的快照、截图和真实鼠标/键盘输入。其他 ChatKit 宿主可以使用 ChatKit JavaScript 仓库中的 host automation handler。

如果客户端没有实现某个工具，模型可能会收到失败的工具调用，或无法完成对应浏览器任务。

## 可用工具

| 工具                     | 能力                                                          |
| ---------------------- | ----------------------------------------------------------- |
| `host_page_snapshot`   | 获取 URL、标题、视口、滚动位置、页面状态、可操作元素、表单标签、附近文本、可访问性摘要、命中测试信息和客户端能力。 |
| `host_page_click`      | 使用 `ref`、`axRef`、角色/名称、文本、测试 ID、选择器或视口坐标点击目标。               |
| `host_page_fill`       | 填写输入框、文本域或 contenteditable 元素。                              |
| `host_page_press`      | 按下 `Enter`、`Escape`、`Tab`、`F8` 等键。                          |
| `host_page_select`     | 在选择框中选择一个或多个值。                                              |
| `host_page_scroll`     | 滚动页面或指定可滚动元素。                                               |
| `host_page_navigate`   | 当 `allowNavigation` 开启时，跳转到 HTTP(S) URL。                    |
| `host_page_hover`      | 将指针悬停到目标元素。                                                 |
| `host_page_focus`      | 聚焦目标元素。                                                     |
| `host_page_pointer`    | 使用视口 CSS 坐标执行低层级指针动作。                                       |
| `host_page_screenshot` | 在客户端支持时截取页面截图，并把图片附加到下一次模型调用。                               |
| `host_page_wait_for`   | 在客户端等待目标变为 attached、visible、hidden 或 detached。              |
| `host_page_wait`       | 在服务端等待 3 到 60 秒。                                            |

## 推荐智能体行为

为了提高浏览器任务稳定性，建议让智能体按以下顺序行动：

1. 先用 `host_page_snapshot` 理解页面并获取稳定的 refs。
2. 表单操作优先使用 `host_page_fill`、`host_page_select` 和 `host_page_press`。
3. 如果一次 DOM/ref 点击后页面没有变化，不要重复点击同一目标，改用 `host_page_screenshot` 和 `host_page_pointer`。
4. 页面跳转、动画、SPA 刷新或慢请求后使用 `host_page_wait_for` 或 `host_page_wait`。
5. 指针坐标是页面视口 CSS 像素，不是操作系统屏幕坐标，也不包含浏览器工具栏或 ChatKit 侧边栏。

## 截图处理

当 `host_page_screenshot` 返回图片数据时，中间件会压缩工具消息，并追加一个包含截图的新模型输入。如果截图包含视口尺寸和图片尺寸，中间件还会给模型坐标换算公式：

```text theme={null}
cssX = imageX / imageWidth * viewportWidth
cssY = imageY / imageHeight * viewportHeight
```

这对 DOM 或可访问性快照难以描述的可视化控件尤其有用。

## 排障建议

* **没有页面跳转工具**：检查 `allowNavigation` 是否关闭。
* **智能体无法操作页面**：确认 ChatKit 客户端实现了宿主页面自动化，并且目标页面是 HTTP(S) 页面。
* **重复点击但没有进展**：要求智能体在第一次点击无变化后切换到截图和坐标操作。
* **坐标落点不对**：确认使用的是视口 CSS 像素，而不是屏幕像素。