mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-15 12:15:11 +00:00
25bd243662
用户报告：截图直接返回二进制（base64）对 agent 十分不友好。确认属实，且
生产日志里有 agent 的**绕行实证**（2026-10-10）：
browser_screenshot → cmd_run（自己 base64 解码写盘）→ describe_image
那一轮跑了 920 秒。
## 为什么 base64 是错的
工具结果是 JSON 文本，base64 PNG 会**整段进模型上下文**，而模型看不见
这些字符里的图 —— 纯粹浪费：
视口截图 100-500KB ⇒ base64 后 137-685KB（约 3-17 万 token）
更关键的是它把「解码 + 写文件」这件重复劳动推给了每个消费方，而模型做不到。
内核早有对应约定：`describe_image` 的 path 参数描述写着
「★处理设备/工具回传的媒体时必须传（screensee / camerasue 会回传 file 路径）」。
本插件返回路径才是合上这个约定。
## 改动
- 截图落盘到 `<data_dir>/browser_screenshots/`，返回**绝对路径**
- 结果里带 `hint` 直接告诉模型「调 describe_image(path=...)」——
工具描述模型可能漏看，结果里的提示更近
- `inline=true` 才额外带 base64/data_uri（只有确实拿不到文件系统的场景才用）
- 落盘失败**明确报错**，不静默退回 base64：那会让「上下文被灌爆」
在磁盘满/权限错时重新出现且没有迹象
- 文件名带毫秒时间戳 + 会话 id：同一轮内多次截图是常态
（生产日志里一轮截了 3 次），固定名会静默覆盖
- 会话 id 过滤路径分隔符（它来自模型且被拼进路径，否则 `../` 能写出目录外）
- 未注入 data_dir 时降级到临时目录，而不是让截图整条失败
## 判据（5 条，可杀变异，逐个实测）
`screenshot_test.go`：
- 落盘 + 返回绝对路径 + 内容逐字节一致
- 连续截图不互相覆盖（文件名去时间戳 → FAIL）
- 会话 id 路径穿越被挡（`../../etc/evil` 仍在目录内）
- 未注入目录时降级而非报错
- 工具描述必须提 path 与 describe_image（描述退回 base64 → FAIL）
- handleScreenshot 返回结构必须是 path 而非 base64
（整段替换为旧实现 → FAIL；保留 path 但无条件加 base64 → FAIL）
**判据本身修过两次（都是变异测试发现的）**：
1. 第一版只看 `res["base64"] = b64`，把 base64 写成 map 字面量的键就绕过了
2. 第二版按整段文本查 "inline"，而**注释里也有 "inline"** ⇒ 把保护开关
改成 `if false` 仍能通过。改为先 `stripLineComments` 再查真实代码行
全 20 个 example 编译通过；browser 插件 `go test` + plugin 模式构建通过。
browser · 统一浏览器
一个插件覆盖三种"访问网页"的能力，从最轻到最重。按需选层是这个插件的重点 —— 绝大多数抓取用 HTTP 就够，不该为了一句话启动 Chromium。
三种能力层
| 层 | 工具 | 何时用 |
|---|---|---|
| 搜索 | browser_search |
要的是"找到哪些页面"，不是页面本身 |
| quick（纯 HTTP） | browser_fetch（mode=quick） |
静态页、API、能直接拿到 HTML |
| normal（无头渲染） | browser_render / browser_fetch（mode=render） |
JS 渲染的页面，HTTP 拿不到内容 |
| interactive（CDP） | browser_start + navigate/click/type/scroll/html/screenshot |
需要交互：登录、点按、翻页 |
browser_fetch 的 mode：
auto（默认）：先试 HTTP，遇 403/429 才降级用 Chromium 渲染render：强制 Chromiumquick：纯 HTTP，不降级
工具
| 工具 | 说明 |
|---|---|
browser_search |
网页搜索 |
browser_fetch |
抓取 URL 内容，三种 mode 见上 |
browser_render |
无头 Chromium 渲染并提取文本（normal） |
browser_start |
启动交互式浏览器会话（CDP） |
browser_navigate |
导航到指定 URL |
browser_click |
点击元素 |
browser_type |
输入文本 |
browser_scroll |
滚动页面 |
browser_html |
取当前页 HTML |
browser_screenshot |
截图，保存为 PNG 并返回路径（拿 path 调 describe_image / ocr_image） |
browser_install |
安装 systemd 托管的共享浏览器后端 |
browser_close |
关闭会话 |
共享浏览器后端
browser_install 安装 homeagent-browser.service（systemd 托管）。
装上之后所有 agent 共享同一个 Chromium 实例与登录态，各自占独立标签页互不干扰
（同 source 复用自己的标签页）。
前提：本机已有 chromium 二进制，没有会提示先装（apt install chromium 或等价）。
实现要点
- 搜索用
cn.bing.com而不是www.bing.com：后者对程序化请求常回 302（同意/重定向页）， 根本拿不到结果块。 - 标题取
<h2>里的<a>：直接抓结果块里第一个<a>会拿到来源行而非标题。 - 摘要认
b_lineclamp：旧版 Bing 用b_caption，新版已迁走，两套都匹配。 - 有 SSRF 防护：见源码
SSRF段，抓取前校验目标地址，避免被诱导访问内网。
测试
go test -count=1 ./...
testdata/bing_cn.html 是搜索解析的固定样本，用它做离线断言，避免测试依赖真实网络。
构建
hmapdev build