WeKnora/docs/browser-skill-integration.md

109 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# BrowserSkill 本机浏览器接入
WeKnora 使用 Tencent/BrowserSkill 的官方 daemon 和扩展执行浏览器操作,通过 `local_browser` 薄工具适配接入,无需沙箱、浏览器技能包或用户运行本机命令。
## 使用流程
1. Docker 部署使用包含 BrowserSkill 的 app 和 frontend 镜像,默认从用户当前页面生成连接地址。原生部署需先运行 `./scripts/build_browserskill.sh`,配置下面的两个文件路径并重启服务。
2. 用户在个人设置 → 浏览器连接下载配套扩展,解压后在 Chrome 扩展程序页面加载。当前没有商店发布版本。
3. 在设置页复制一次性配对链接,粘贴到扩展的「远程连接」,核对服务器并连接。同一空间内多个对话共用设备授权。
4. 回到对话描述浏览器任务。首次工具调用会在现有 Chrome 窗口创建后台任务标签,以绿色「WeKnora」标签组标识。模型切换目标标签不会切走用户正在看的页面。
5. 主对话小预览可定位任务标签、暂停操作、继续操作或结束浏览器任务。暂停中断当前浏览器调用并保留页面,结束会关闭任务新建标签、归还借用标签;这些按钮只控制当前对话的浏览器,不会停止整段对话或撤销浏览器配对。请求人工帮助时先显示提示;不会自动激活标签或窗口。借用已有标签必须经过原生确认,归还时解除控制,保留原位置。
浏览器操作期间,从当前任务页通过新窗口链接(包括 `rel=noopener`)或 `window.open` 打开的标签,会按来源登记到当前任务,加入任务标签组,并在结束时一起回收。若 Chrome 默认激活新标签,扩展会恢复此前查看的标签;浏览器原生激活可能带来短暂切换。任务空闲时手动新建或拖入标签组的页面不会自动获得任务归属。
授权只覆盖任务创建的标签和用户明确批准借用的标签;标签组仅提供视觉标识,不作为权限依据。即使用户把其他标签拖入组内,模型也不会获得其控制权。结束任务只清理任务创建的标签,不关闭共用窗口及其他对话的标签。上游的本机 daemon 连接模式仍使用原有独立窗口。
## 预览与命令
自动化命令按对话串行执行。UI 预览通过扩展现有 WSS 的独立请求获取,不进入 daemon 自动化队列,因此长导航或人工等待不会占住截图通道。
预览获取当前任务标签的 CDP 画面,不调用激活窗口/标签 API。JPEG 宽度最多 640 像素。预览直接截取视口,再缩小实际位图,不在每次轮询前额外调用布局查询。任务活动期间,前端每次获取画面后间隔 1 秒刷新;服务端短缓存和扩展在途合并限制重复截图。页面隐藏时停止刷新,回到页面后立即更新。它是约 1 fps 的低帧率截图同步,不是视频流;失败超过 5 秒会提示画面暂未更新。
后台任务标签在调试连接期间启用 CDP `Emulation.setFocusEmulationEnabled`,让页面的可见性/焦点与绘制回调继续工作,不激活 Chrome 标签或窗口。仅任务新建或明确借用的标签启用此行为,释放调试连接时由 Chrome 恢复。否则依赖 `requestAnimationFrame` 或可见性事件加载内容的页面可能停在 Loading,直到用户切到该标签。
扩展对截图命令设置 3 秒等待上限,对 DOM 快照、无障碍树等读取命令设置 10 秒上限;读取超时立即终止本次快照,不继续走同一页面的回退读取。错误保留具体 CDP 命令,扩展后台控制台记录超过 2 秒的命令及耗时。此保护不等于取消已经交给 Chrome 的命令,也不自动重放点击或提交。截图超时后仍保留在途标记,直到 Chrome 实际返回或调试连接释放;期间预览不再发送重复截图。框架自动附加配置按调试会话复用,断开后重建,失败后可重试。
上述上限针对单条 CDP 命令,并非整个 `observe`。复杂页面还要在扩展中进行语义树转换和文本渲染;重复操作按钮的上下文收集复用已扫描的兄弟节点前缀,避免逐按钮重复扫描整个列表。缓存仅存在于本次渲染,按作用域、目标名称和已有上下文隔离,每个父节点最多保留 64 种缓存项。慢观察会以 `[bsk observe] slow observation completed` 输出总耗时和分阶段耗时(不含页面内容);CDP 超过 2 秒时的提示是等待中告警,`slow command settled` 记录 Chrome 实际返回的耗时,`outcome` 区分返回和失败,`late: true` 表示扩展已经超时但 Chrome 此时才完成;本地超时单独记录为 `command failed`。
本轮 Agent 执行结束时,通过工具清理钩子释放当前任务的 Chrome 调试连接。成功完成的普通查询默认关闭任务创建的页面并归还借用标签,避免每轮留下任务分组;输入框的本机浏览器选择偏好仍保留。调用时可设置顶层 `keep_open: true`,为用户要求保留的页面、交付结果或未完成的人工步骤保留整项任务;该标记仅对本轮有效。`request_help` 自动保留任务,人工步骤完成后可通过后续调用的 `keep_open: false` 恢复自动回收。报错、取消、暂停的任务保留现场,不自动关闭。扩展先阻止新截图,再等待在途截图和操作完成,最后释放连接;结束任务也使用同一截图屏障。空闲时服务端只返回缓存画面,卡片显示「已保留最后画面」,不重复截图,下一次浏览器调用恢复连接。Chrome 提示条的消失可能晚于连接释放;同一扩展有其他活动任务时,提示仍可能保留。
导航默认等待 `domcontentloaded`,避免已经可读的页面被慢图片等资源拖住;需要完整加载或网络空闲时可显式指定 `wait_until: "load"` 或 `"networkidle"`。文档就绪不代表异步应用内容已加载,操作前仍需观察目标内容是否出现。
模型调用采用扁平参数,例如 `{"method":"navigate","url":"https://example.com"}`、`{"method":"click","ref":"e3"}`、`{"method":"observe"}`。Schema 不再提供 `params` 字段,旧的嵌套格式直接拒绝。服务端校验所选动作的必填字段、字段类型及定位条件,再将参数转换为 BrowserSkill 原生 RPC 信封;会话和设备 ID 始终由服务端绑定。
`wait_ms` 的外层参数为 `duration_ms`,范围 0–10000 毫秒;工具描述、参数 schema 和执行前校验保持一致。命令超时或中断后暂停任务,不自动重放点击/提交。前端显示具体浏览器动作与可读错误,结果卡片分别展示网页内容、截图或标签列表,不展示原始协议 JSON。标签组统一显示 WeKnora,不再附带内部任务 ID。
## 构建与部署
固定源码提交 `5aaa36bf79a201ec40b277ce6c24f2ce23ce37ca`、官方 daemon v0.2.1、协议 v1.1。构建脚本应用 `patches/browserskill/remote-extension-connection.patch`,以冻结依赖构建扩展,并验证 daemon 下载包 SHA-256。产物位于 `artifacts/browserskill/`,不提交二进制。
后台页面绘制和读取超时的修复位于扩展中。更新服务端后,已有用户仍需下载新的配套 ZIP,覆盖原解压目录并在 Chrome 扩展程序页面重新加载;仅重启服务端不会更新已安装的扩展。
### Docker 部署
`docker/Dockerfile.app` 在独立 Node 构建阶段生成配套扩展,按目标 `linux/amd64` 或 `linux/arm64` 下载 daemon,并将 `bsk`、扩展 ZIP 和许可证复制到运行镜像的 `/opt/weknora/browserskill/`。镜像已预设 `BROWSERSKILL_BINARY` 和 `BROWSERSKILL_EXTENSION_PATH`,无需安装 Chrome 或启用沙箱。不要用宿主机的 macOS `bsk` 替换容器中的 Linux 文件。
默认无需设置 `BROWSERSKILL_PUBLIC_URL`。设置页在申请配对时提交 `window.location.origin`,服务端保留域名和端口,将 HTTPS 转为 WSS(本机 HTTP 转为 WS),追加 `/api/v1/local-browser/extension`。例如访问 `https://weknora.example.com:8443`,自动生成 `wss://weknora.example.com:8443/api/v1/local-browser/extension`。地址不依赖反向代理传递的内部 Host 或协议。
仅当网关使用独立域名、自定义代理路径等特殊部署时,在 `.env` 显式覆盖:
```dotenv
BROWSERSKILL_PUBLIC_URL=wss://weknora.example.com/api/v1/local-browser/extension
```
将 app 和 frontend 更新到包含本次修改的镜像后,使用 `docker compose up -d app frontend` 重新创建服务;`docker compose restart` 不会加载修改后的环境变量。需要关闭此功能时,在 `.env` 显式设置 `BROWSERSKILL_BINARY=`。
配套 frontend Nginx 已处理扩展 WebSocket Upgrade,授权 POST 走普通 API 转发,集群内部接口返回 404。若外层还有 Ingress/Nginx,仍需为扩展路径转发 WebSocket,并提供浏览器信任的 TLS 证书;直接暴露 app 的部署须自行屏蔽公共入口的 `/api/v1/local-browser/internal`。
### 原生部署
构建需要 Git、Node.js(镜像使用 Node 24)和 Python 3,以及访问固定的上游源码、npm 依赖和发行包的网络。执行 `./scripts/build_browserskill.sh` 后,将产物复制到下列路径,或将变量改为产物的实际绝对路径。连接地址同样默认从页面自动生成:
```dotenv
BROWSERSKILL_BINARY=/opt/weknora/browserskill/bsk
BROWSERSKILL_EXTENSION_PATH=/opt/weknora/browserskill/browser-skill-weknora-0.2.1.zip
```
构建脚本第二个参数可指定目标平台,例如 `./scripts/build_browserskill.sh ./artifacts/browserskill-linux linux/amd64`;不传时按宿主机系统和架构下载。
本机调试可用 `ws://localhost:8080/api/v1/local-browser/extension`;远程部署要求 WSS,内网可使用受浏览器信任的企业 CA。详细授权、重连、多副本路由、迁移及容量边界见 [生产部署链路](browser-skill-production.md)。
扩展使用官方 MIT 许可,分发时保留 `BrowserSkill-LICENSE`。配对、UI 定位和预览属于本次提出的网关协议约定,并非已经发布的 BrowserSkill 稳定接口。
## 验证
```bash
go test -race ./internal/browserskill ./internal/agent/... ./internal/handler/session \
./internal/router ./internal/application/service ./internal/container ./internal/middleware
```
原生/真实扩展测试另设:
```dotenv
BROWSERSKILL_TEST_BINARY=/absolute/path/to/bsk
BROWSERSKILL_TEST_EXTENSION=/absolute/path/to/unpacked-extension
BROWSERSKILL_TEST_CHROMIUM=/absolute/path/to/Chromium
BROWSERSKILL_TEST_PLAYWRIGHT=/absolute/path/to/playwright-core/index.mjs
BROWSERSKILL_TEST_HEADED=1
BROWSERSKILL_TEST_TASK_WINDOW=1 # 可选:通过扩展界面启用独立窗口并验证其生命周期
```
测试使用独立浏览器资料目录,覆盖配对、后台标签组、导航/输入/点击、目标标签截图、人工等待期间预览、显式定位、暂停/继续/结束、任务隔离、授权持久化和双节点路由。目标部署网络、真实模型任务与规模容量仍须现场验收;本机浏览器不保证免除网站验证或 403。
补丁中的 `task-focus.browser.test.ts` 使用独立 Chrome 与原生 CDP 验证后台绘制、内容读取、截图和释放后的可见性恢复,避免 Playwright 默认的焦点模拟掩盖问题。在应用补丁后的 BrowserSkill 源码中,设置 `BSK_GEOMETRY_CHROME` 为测试 Chrome 路径,再执行 `pnpm --filter @browser-skill/extension exec vitest run src/browser-driver/__tests__/task-focus.browser.test.ts`(Node 20 另需 `NODE_OPTIONS=--experimental-websocket`)。
### 输入框选择本机浏览器
扩展弹窗中的“任务打开方式”提供“后台标签组(默认)”和“独立窗口(保持可见)”。设置保存在本机扩展中,仅对新浏览器任务生效;已有任务需要先结束,或使用新对话。独立窗口不额外创建 Chrome 标签组,开始时会打开到前台,后续创建、选择任务标签只在该窗口内切换;请手动与聊天窗口并排放置。完全遮挡或最小化仍可能导致读取变慢,因此此模式不是不可见后台运行的性能保证。结束任务只清理明确归属于任务的标签,用户后来移入窗口的页面会保留。
Agent 模式的输入框提供“本机浏览器”开关,可与联网搜索同时开启。选中后,请求携带 `local_browser_enabled: true`;本轮提示词明确要求使用 `local_browser` 完成适用的网页查询与操作,而不是把设备已配对当作使用意图。知识库、MCP、Skill、Shell 等工具仍按智能体配置和本轮选择正常提供,可以配合检索、处理内容及生成文件。联网搜索与浏览器同时开启时,可以先搜索发现链接,再用浏览器读取和操作网页。
浏览器不可用时必须说明原因,不能隐瞒失败或声称已通过浏览器读取。该选择不缩减工具注册范围,实际调用由模型遵循提示词和用户任务安排。选择状态随会话最近一次输入设置恢复,切换智能体会清除;关闭浏览器选择不会改变其他开关。此功能需要使用 Agent 接口,普通问答接口拒绝该字段为 true 的请求。
### 标签组回收
默认标签组模式在结束任务时,先将明确归属于任务的标签移出分组,再关闭这些标签;不会按名称清理所有 WeKnora 分组,也不会移出用户后来加入的标签。取消分组失败时保留任务供重试,不报告清理成功。独立窗口模式不创建标签组。旧版本已经保存且关闭的历史分组不会追溯删除,需要用户在 Chrome 中选择“删除分组”;关闭书签栏显示仅隐藏入口,不等于删除。
Chrome 公开扩展 API 不提供直接删除历史已保存分组的接口。移出分组再关闭利用的是本地分组成员变更路径,参见 [Chromium LocalTabGroupListener](https://chromium.googlesource.com/chromium/src/+/f4e2f70d6dd6d88f0ccb887c1935f0cba9fb802f/chrome/browser/ui/tabs/saved_tab_groups/local_tab_group_listener.cc)。跨设备同步和用户已有历史分组仍需真实 Chrome 验收。