WeKnora/docs/browser-skill-integration.md

14 KiB
Raw Blame History

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 显式覆盖:

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 后,将产物复制到下列路径,或将变量改为产物的实际绝对路径。连接地址同样默认从页面自动生成:

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。详细授权、重连、多副本路由、迁移及容量边界见 生产部署链路。

扩展使用官方 MIT 许可,分发时保留 BrowserSkill-LICENSE。配对、UI 定位和预览属于本次提出的网关协议约定,并非已经发布的 BrowserSkill 稳定接口。

验证

go test -race ./internal/browserskill ./internal/agent/... ./internal/handler/session \
  ./internal/router ./internal/application/service ./internal/container ./internal/middleware

原生/真实扩展测试另设:

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。跨设备同步和用户已有历史分组仍需真实 Chrome 验收。