> ## 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 浏览器扩展自动化操作浏览器 ChatKit 浏览器扩展可以把已发布的 XpertAI 数字专家放进 Chrome 侧边栏或网页浮窗中使用。配合 Xpert 后端的 `browser-automation` 中间件，智能体还可以通过一组 `host_page_*` 客户端工具读取当前网页状态、点击、填写表单、滚动、跳转页面，并在需要时使用截图和坐标继续操作复杂页面。 典型流程是：先在 XpertAI 平台用“客户端浏览器自动化智能体”模版创建并发布数字专家，然后把数字专家的 `xpertId`、Xpert API 地址、ChatKit frame 地址和凭据配置到 Chrome 扩展中。 ## 重要资源 * [ChatKit JavaScript 仓库](https://github.com/xpert-ai/chatkit-js) * [ChatKit 浏览器扩展发布包](https://github.com/xpert-ai/chatkit-js/releases) * [XpertAI 平台](https://app.xpertai.cn/) * [XpertAI API 接入文档](/zh-Hans/ai/chatkit/sdk/integrate-xpertai-api) * [浏览器自动化中间件](/zh-Hans/ai/middleware/built-in/browser-automation) ## 工作原理 | 组件 | 作用 | | ------------------------ | ------------------------------------------------------------------------------------- | | Xpert 数字专家 | 由模版创建，后端工作流包含 `browser-automation` 中间件。 | | `browser-automation` 中间件 | 在服务端把 `host_page_*` 能力声明为 ChatKit 客户端工具，并把工具调用结果回灌到模型上下文。 | | ChatKit 浏览器扩展 | 在 Chrome 侧边栏或网页浮窗中渲染 `xpertai-chatkit`，读取本地扩展配置，并处理客户端工具调用。 | | 宿主页面自动化 | 优先使用 Chrome `debugger` 权限通过 CDP 获取更丰富的快照、截图和真实鼠标/键盘输入；不可用时回退到 content script DOM 执行器。 | 扩展本身提供两个入口： * Chrome side panel：适合持续对话和跨页面任务。 * Page overlay：按需注入到当前 HTTP(S) 标签页，可用 Pet launcher 或完整聊天面板形式出现。 ## 准备工作 开始前请确认： * 你可以登录 XpertAI 平台，并能创建、发布数字专家。 * 已安装或可加载 [ChatKit Chrome 扩展](https://github.com/xpert-ai/chatkit-js/releases)。 * 已准备一个可访问的 XpertAI AI API 地址。 * 公有云默认值：`https://api.xpertai.cn/api/ai` * 私有部署请替换为自己的 API 地址 * 已准备 ChatKit frame 地址。 * 公有云默认值：`https://app.xpertai.cn/chatkit` * 私有部署请替换为自己的 ChatKit 前端地址 * 目标网页是 HTTP(S) 页面。Chrome 的 `chrome://` 页面、Chrome Web Store、扩展页面等受限页面不能注入网页浮窗，也不能被普通宿主页面自动化操作。 扩展的 `Client Secret / API Key` 会保存在 `chrome.storage.local` 中。生产环境建议使用专用、最小权限、可轮换的凭据；如果你的部署支持短期 `client_secret`，优先使用短期凭据，不要在非受控浏览器中长期保存高权限 API Key。 ## 第一步：用模版创建数字专家 1. 登录 [XpertAI 平台](https://app.xpertai.cn/)。 2. 进入模版或探索页面，搜索“客户端浏览器自动化智能体”。 3. 使用该模版创建数字专家。 4. 打开智能体编排页面，确认工作流中包含 `Browser Automation` / `浏览器自动化` 中间件。 5. 如果希望智能体可以跳转当前页面，保持 `Allow Navigation` / `允许页面跳转` 开启。该选项会暴露 `host_page_navigate` 工具。 6. 按需调整主智能体提示词。模版默认提示词会引导智能体帮助用户操作浏览器，并在动作失败时切换到截图和坐标方式。 7. 发布数字专家版本。 8. 复制已发布数字专家的 `xpertId`。 9. 在数字专家的开发接口或工作区 API Key 页面创建访问 Key。更多 API Key 说明可参考 [开发接口](/docs/ai/agent/development-api)。 模版底层使用的配置文件是 `xpert--client-browser-automation-tools`。其中关键节点是 provider 为 `browser-automation` 的中间件，默认 `allowNavigation: true`。 ## 第二步：安装 Chrome 扩展 如果你使用 [ChatKit 浏览器扩展发布包](https://github.com/xpert-ai/chatkit-js/releases)，解压后在 Chrome 中加载扩展目录即可。 如果你从源码构建，源码仓库见 [xpert-ai/chatkit-js](https://github.com/xpert-ai/chatkit-js)： ```bash theme={null} cd chatkit-js pnpm install pnpm --filter @xpert-ai/chatkit-browser-extension build ``` 构建产物位于： ```text theme={null} chatkit-js/packages/browser-extension/dist/chrome ``` 在 Chrome 中打开 `chrome://extensions`： 1. 开启 Developer mode。 2. 点击 Load unpacked。 3. 选择 `dist/chrome` 目录。 4. 固定浏览器工具栏中的 Xpert ChatKit 扩展图标。 当前扩展生成的是 Chrome Manifest V3 扩展，使用到的核心权限包括 `storage`、`sidePanel`、`scripting`、`activeTab` 和 `debugger`。 ## 第三步：配置扩展 点击扩展图标，然后打开 Options / 设置页，填写以下字段： | 配置项 | 说明 | 示例 | | ------------------------------------- | ------------------------------------------------------- | -------------------------------- | | ChatKit frame URL | ChatKit iframe 页面地址。 | `https://app.xpertai.cn/chatkit` | | Xpert API URL | XpertAI AI API 地址。 | `https://api.xpertai.cn/api/ai` | | Xpert ID | 已发布数字专家的 `xpertId`。 | `your-xpert-id` | | Client Secret / API Key | ChatKit 运行时使用的凭据。扩展会通过 `getClientSecret` 返回该值。 | `sk-x-...` 或短期 secret | | Locale | 扩展和 ChatKit 的语言。可选浏览器默认、`en`、`zh-Hans`。 | `zh-Hans` | | Launch mode | 网页浮窗的启动模式。`Pet launcher` 先显示宠物入口，`Chat panel` 直接显示聊天面板。 | `Pet launcher` | | Color scheme | 浅色或深色主题。 | `Light` | | Enable Chrome side panel | 是否允许从扩展弹窗打开 Chrome 侧边栏。 | 开启 | | Enable page overlay | 是否允许在当前网页注入 ChatKit 浮窗。 | 开启 | | Auto launch page pet | 新的 HTTP(S) 标签页加载完成后自动打开 Pet 浮窗。仅在 `Pet launcher` 模式下生效。 | 可选 | | Overlay width / height | 网页浮窗尺寸。宽度范围 `320`-`900`，高度范围 `360`-`1200`。 | `420` x `720` | | Overlay position | 网页浮窗位置。支持右下、左下、右上、左上。 | 右下 | | Allow agents to operate the host page | 是否把智能体发起的 `host_page_*` 工具调用转交给当前网页执行。 | 开启 | 保存后，扩展弹窗会显示当前配置是否完整。缺少 `frameUrl`、`apiUrl` 或凭据时，ChatKit 会显示配置提示。 ## 第四步：开始使用 1. 打开一个普通 HTTP(S) 网页。 2. 点击 Xpert ChatKit 扩展图标。 3. 选择 Open side panel，或点击 Toggle page overlay 在当前页面打开浮窗。 4. 在 ChatKit 中输入任务，例如： ```text theme={null} 请查看当前页面，概括主要内容。 ``` ```text theme={null} 请找到页面上的搜索框，搜索“browser automation”，并打开第一个结果。 ``` ```text theme={null} 请帮我填写当前表单。姓名填 Alice，邮箱填 alice@example.com，然后停在提交前让我确认。 ``` 侧边栏模式下，自动化会作用于当前活动标签页。网页浮窗模式下，自动化会作用于浮窗所在的宿主页面。 ## 可用自动化能力 `browser-automation` 中间件会向模型暴露以下客户端工具： | 工具 | 能力 | | ---------------------- | -------------------------------------------------------------------- | | `host_page_snapshot` | 获取当前页面 URL、标题、视口、滚动位置、可操作元素、表单标签、可访问性摘要等结构化快照。 | | `host_page_click` | 按 `ref`、`axRef`、角色/名称、文本、CSS selector 或坐标点击元素。 | | `host_page_fill` | 填写输入框或文本区域。 | | `host_page_press` | 发送键盘按键，例如 `Enter`、`Tab`、`F8`。 | | `host_page_select` | 选择下拉框选项。 | | `host_page_scroll` | 滚动页面或指定元素。 | | `host_page_navigate` | 跳转到 HTTP(S) URL。仅在中间件开启 `allowNavigation` 时暴露。 | | `host_page_hover` | 悬停到元素。 | | `host_page_focus` | 聚焦元素。 | | `host_page_pointer` | 使用视口 CSS 坐标执行低层级指针动作。复杂企业页面、SAP/Fiori 或 iframe 页面中，DOM 点击无效时可配合截图使用。 | | `host_page_screenshot` | 捕获当前宿主页面截图，并把图片作为后续模型输入。Chrome CDP 可用时效果最好。 | | `host_page_wait_for` | 等待元素出现、可见、隐藏或移除。 | 后端还会提供服务端等待工具 `host_page_wait`，用于在页面渲染、动画、跳转或异步请求后等待 3 到 60 秒。 推荐的操作顺序是： 1. 先调用 `host_page_snapshot` 理解页面和定位元素。 2. 对明确字段优先使用 `host_page_fill`、`host_page_press`、`host_page_select`。 3. 如果一次点击后页面没有变化，不要重复点击同一目标；改用 `host_page_wait_for`、`host_page_screenshot` 或 `host_page_pointer`。 4. 使用截图坐标时，坐标是页面视口 CSS 像素，不是操作系统屏幕坐标，也不包含浏览器工具栏或 ChatKit 侧边栏。 ## 常见问题 ### 打开 ChatKit 后提示需要配置 检查扩展 Options 中的 `ChatKit frame URL`、`Xpert API URL` 和 `Client Secret / API Key` 是否为空。还要确认 `xpertId` 对应的数字专家已经发布。 ### 网页浮窗无法打开 网页浮窗只能注入 HTTP(S) 页面。请避开 `chrome://`、Chrome Web Store、PDF 查看器、扩展页面、浏览器设置页等受限页面。 ### 智能体无法点击或填写页面 确认扩展 Options 中已开启 `Allow agents to operate the host page`。如果 Chrome 弹出调试器授权提示，请允许扩展连接当前标签页。对于复杂页面，让智能体先截图，再用 `host_page_pointer` 按视口坐标操作，通常比重复 DOM 点击更可靠。 ### 私有部署或本地 ChatKit frame 被 Chrome 阻止 确认 `frameUrl` 指向的服务允许被扩展页面嵌入。不要返回会阻止嵌入的 `X-Frame-Options`，并检查 `Content-Security-Policy: frame-ancestors` 是否允许扩展使用。 ### 自动打开 Pet 不生效 确认同时满足以下条件：`Enable page overlay` 已开启，`Auto launch page pet` 已开启，`Launch mode` 是 `Pet launcher`，当前标签页是 HTTP(S) 页面，并且基础配置校验通过。