使用 ChatKit 浏览器扩展自动化操作浏览器

ChatKit 浏览器扩展可以把已发布的 XpertAI 数字专家放进 Chrome 侧边栏或网页浮窗中使用。配合 Xpert 后端的 browser-automation 中间件，智能体还可以通过一组 host_page_* 客户端工具读取当前网页状态、点击、填写表单、滚动、跳转页面，并在需要时使用截图和坐标继续操作复杂页面。

典型流程是：先在 XpertAI 平台用“客户端浏览器自动化智能体”模版创建并发布数字专家，然后把数字专家的 xpertId、Xpert API 地址、ChatKit frame 地址和凭据配置到 Chrome 扩展中。

​

重要资源

• ChatKit JavaScript 仓库
• ChatKit 浏览器扩展发布包
• XpertAI 平台
• XpertAI API 接入文档
• 浏览器自动化中间件

​

工作原理

组件	作用
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 扩展。
• 已准备一个可访问的 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 平台。
2. 进入模版或探索页面，搜索“客户端浏览器自动化智能体”。
3. 使用该模版创建数字专家。
4. 打开智能体编排页面，确认工作流中包含 Browser Automation / 浏览器自动化 中间件。
5. 如果希望智能体可以跳转当前页面，保持 Allow Navigation / 允许页面跳转 开启。该选项会暴露 host_page_navigate 工具。
6. 按需调整主智能体提示词。模版默认提示词会引导智能体帮助用户操作浏览器，并在动作失败时切换到截图和坐标方式。
7. 发布数字专家版本。
8. 复制已发布数字专家的 xpertId。
9. 在数字专家的开发接口或工作区 API Key 页面创建访问 Key。更多 API Key 说明可参考 开发接口。

模版底层使用的配置文件是 xpert--client-browser-automation-tools。其中关键节点是 provider 为 browser-automation 的中间件，默认 allowNavigation: true。

​

第二步：安装 Chrome 扩展

如果你使用 ChatKit 浏览器扩展发布包，解压后在 Chrome 中加载扩展目录即可。

如果你从源码构建，源码仓库见 xpert-ai/chatkit-js：

cd chatkit-js
pnpm install
pnpm --filter @xpert-ai/chatkit-browser-extension build

构建产物位于：

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 中输入任务，例如：

请查看当前页面，概括主要内容。

请找到页面上的搜索框，搜索“browser automation”，并打开第一个结果。

请帮我填写当前表单。姓名填 Alice，邮箱填 [e-mail]，然后停在提交前让我确认。

侧边栏模式下，自动化会作用于当前活动标签页。网页浮窗模式下，自动化会作用于浮窗所在的宿主页面。

​

可用自动化能力

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) 页面，并且基础配置校验通过。