mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-15 12:15:11 +00:00
b6a6168e65
SDK 仓已迁到 GitHub 作为权威源，go module 路径同步： `gitcode.com/JianFeeeee/homeagent-sdk` → `github.com/JianFeeeee/homeagentsdk` ## 范围 74 个文件：71 个 Go 源码 + go.mod/go.sum + hmapdev 模板 + CI 与打包脚本。 主仓（HomeAgent）侧对应改动是 6d38a164。本仓这些文件当时**不在工作树上** （见下），所以那次的批量替换扫不到它们——这里是补偿。 ## 为何这批文件当时不在工作树上（事故与恢复） 10-08 07:58 主仓做 checkout/cherry-pick 序列时，把本仓工作树的 20 个文件 误清理了（`example/*/plugin.go` + `plg.json`，10 个示例）。 根因是**结构误判**：本仓是「一目录两仓库」结构下主仓 `third_party/` 里的 **独立 git 仓库**，而主仓 .gitignore 忽略了 `example/`，于是它在主仓 `git status` 里不可见 —— 看着像「不受跟踪的构建产物」，实际是本仓受跟踪的源码。 已全部恢复（`git checkout -- <D 文件>`，只恢复删除、不动迁移改动）， 20 个文件与 HEAD 逐字节一致。 **破坏的连锁后果**：恢复出来的 `plugin.go` 仍写着旧 module 路径， 因为迁移时它们已不在工作树上。所以这次补偿是必须的，不是可选优化。 ## 保留 gitcode 引用 以下位置的 `gitcode` **有意保留**，不要"顺手清掉"： - README.md / docs 里「二进制实际分发地址目前是 gitcode」的说明 - mkdocs.yml 的 gitcode 镜像链接（国内直连更快） - `tools/hmapdev/templates.go` 里「SDK 已从 gitcode 迁到 GitHub」的注释 gitcode 仍是**只读镜像**（源码同步；release 附件暂时仍在那边）。 ## 验证 - 本仓根 module：`go build ./...` + `go test ./...` 全通过 - 全部 20 个 example：`go vet` 通过（补偿前 10 个因旧 module 路径失败） - example/qq：`go test` 通过，且能从源码 build 出可用 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 |
截图 |
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