浏览器扩展(Buddy)
让用户的浏览器接上您部署的站点,Agent 才能打开标签页、读页面、摘图、填表。不需要浏览器能力的部署可以跳过。
← 文档索引
Buddy 是什么
Agent 的浏览器工具(打开 / 切换标签页、读页面、抽取图片、填表、点击)执行的一端不在服务器上, 而在用户自己电脑的 Chrome 里:服务端只把指令下发到用户的浏览器,由 Buddy 扩展执行,再把结果送回。 所以那一端必须由用户在桌面上装好扩展,并且那个标签页保持打开。
两种部署形态都支持:
| 用户的站点 | 扩展怎么接上 |
|---|---|
agenti.chat(官方域) |
装好即用,官方域写死在扩展里 |
| 您自己的域名(私有化部署) | 装好后把本站域名加进扩展的「自建站点」,见下文 |
Chrome 的扩展通道是静态清单:一个域能不能直接和扩展说话,在扩展发布时就定死了,运行时改不了。 自建域走的是另一条路——扩展会为用户显式添加过的域名注入一段桥接脚本,页面经它转发请求。 所以「加域名」这一步不是可选项,是这条链路的前提。添加即授权:被添加站点上的页面可以直接驱动 扩展,只添加自己部署的站点。
前提
- 桌面版 Chrome 或 Chromium 系浏览器。手机浏览器跑不了:iOS 上只有 Safari 支持扩展,Android 上只有 Firefox,两者都不是 Chrome 扩展的宿主。手机可以发指令,但执行永远在桌面那台电脑上。
- 用户在自己的浏览器账号里装扩展(可以让 IT 统一推送)。
- 服务端打开了浏览器工具开关,见下一节。
服务端开关
两处,缺一不可:
| 位置 | 变量 | 作用 |
|---|---|---|
thia-agent 的 ConfigMap |
BROWSER_TOOLS_ENABLED=true |
给模型启用浏览器工具。false 时模型连工具都看不到 |
thia-web 的 ConfigMap |
EXTENSION_STORE_URL=https://chromewebstore.google.com/detail/<id> |
站内「安装扩展」页的下载入口;扩展 id 也从这里解析出来 |
BROWSER_TOOLS_ENABLED=false时探针、日志、对话全部正常,只是模型没有浏览器工具可用—— 这是最容易漏的一处「装了但没打开」。
另外把 thia-agent 的 agentic.yaml(以 ConfigMap 挂载,见逐服务手动部署)顶层的
webBaseUrl 填成本站地址,例如 webBaseUrl: 'https://<your-domain>'。浏览器工具失败时模型要靠它
给出站内安装页的链接;不填只是少给一个链接,不影响工具本身。
升级已有的 thia-agent
新环境跑 数据库表结构 里那份初始化脚本就够了。已经部署过 thia-agent 的
则要多跑一条:CREATE TABLE IF NOT EXISTS 对已存在的表是空操作,不会给 sse_subscriptions 补列。
先执行这条,再换镜像:
ALTER TABLE sse_subscriptions
ADD COLUMN IF NOT EXISTS can_execute BOOLEAN NOT NULL DEFAULT TRUE;
顺序反了也不会报错——写这一列会失败并被忽略,服务退化成「只有本 pod 的连接才算数」, 也就是改之前的行为:页面上「连上了但跑不了工具」会被说成「没有页面连着」。补跑这条即可恢复。
让扩展认识您的域名
用户操作,每台电脑做一次(站点列表存在 Chrome 同步存储里:登录了 Chrome 账号的,同一账号的其它电脑会在 下次启动浏览器时同步;没登录的只存本机):
- 在 Chrome 里装好 Buddy。
- 在同一个 Chrome 里打开本站点,例如
https://<your-domain>/agent。 - 点工具栏的 Buddy 图标打开侧边栏 → 找到「自建站点」一块 → 输入本站地址(如
https://<your-domain>)→「添加」。 - 添加后扩展会为这个域注入桥接脚本,并把已经打开的那个标签页刷新一次;页面不会自己变成可用状态, 这次刷新就是让它重新连接。
要点:
- 直接填域名即可(如
thia.example.com),会自动补成https://;写完整地址也行,路径会被丢掉。 只接受https,本机调试的http://localhost/http://127.0.0.1是唯一例外;带账号密码的地址不接受。 - 官方域始终在列表顶部(标「始终可用」),不可删除;用户自己最多加 8 个。
- 侧边栏里看不到「自建站点」一块,说明扩展版本太旧,先在扩展管理页更新到最新版。
- 同一台电脑上开了多个站点也没问题:每个域各加一条,页面各自连接。
第二层权限:按站点授权
加了域名只是让这一页能连上扩展,不等于允许 Agent 随便读任何网站。对话第一次要在某个站点上操作时,
聊天里会弹一张授权卡,由用户按站点放行(read = 只读,interact = 可操作);允许过的站点在侧边栏「对话可使用的站点」里,
随时可以撤销;「禁用站点」里登记的站点不会出现摘取按钮。
所以在私有化部署里,用户第一次让 Agent 干活时会看到一次授权卡,这是正常的,不是没配好。
验收
- 在装好扩展、加好域名的 Chrome 里打开
https://<your-domain>/agent。 - 问一句「列一下我现在打开的标签页」。
- 期望:返回真实的标签页列表。
失败时模型说的话就是对症的线索,三种情况互不相同:
| 模型说 | 含义 | 处理 |
|---|---|---|
| 没有页面连着(并让您在那台电脑上打开聊天页) | 这一页没连上服务端(标签页关了、切走了、登出) | 打开 /agent 并保持 |
| 页面开着,但它报跑不了浏览器工具 | 页面连上了,但没有桥:扩展没装、被禁用,或本站域名没加进「自建站点」 | 按上一节把域名加进去,然后刷新页面 |
| 有页面连着但没回应(像是等您点确认) | 链路通了,卡在聊天里的授权卡 / 验证码 | 回到聊天查看待处理的卡片 |
服务端日志:前两种是同一条 browser tool dispatch skipped: no capable bridge subscriber,靠 audience 字段
(none / connected-only)区分;第三种走的是超时(TIMEOUT)。
排障
| 症状 | 常见原因 |
|---|---|
| 侧边栏没有「自建站点」 | 扩展版本旧,更新扩展 |
| 添加时报「请输入 https 地址」 | 写的是 http:// 的非本机地址、地址里带了账号密码,或根本不是地址 |
| 添加后页面仍是「跑不了工具」 | 没刷新那一页;或添加的是另一个域(www. 与裸域、测试域与生产域要分别加) |
| 别的电脑上不生效 | 站点列表随 Chrome 账号同步,在另一台电脑上重启浏览器后再看一次 |
| 模型说「没有页面连着」但页面明明开着 | 该页的 SSE 断了(网络 / 反向代理超时);刷新页面 |
反向代理侧要保证 /events 是长连接、不被缓冲:X-Accel-Buffering: no 与足够的读超时,
详见边缘 nginx。