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 模式构建通过。
67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# 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`：强制 Chromium
|
||
- `quick`：纯 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` 段，抓取前校验目标地址，避免被诱导访问内网。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
go test -count=1 ./...
|
||
```
|
||
|
||
`testdata/bing_cn.html` 是搜索解析的固定样本，用它做离线断言，避免测试依赖真实网络。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
hmapdev build
|
||
```
|