mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 06:17:25 +00:00
74e2c654ed
## 用户的三条要求 1. 「所有插件都默认自启会占启动时间，还在 llms 上下文塞大量工具」 ⇒ 纯工具型改为按需加载，靠 skill 让 agent 知道要先拉起。 2. 「会向 agent 注入输入的部分插件不能这样做」 ⇒ 9 个必须常驻，其余 13 个按需。 3. 「sdk 是不是没有暴露插件声明自身行为的方案」 ⇒ 对：auto_start 只在 internal/plugin/manifest.go 有，SDK 零命中。 ## 定级依据（代码证据，不是猜描述） 注入 / 钩子 ⇒ 必须常驻（9 个）： qq HTTP 监听 NapCat 推送，消息到达要立刻注入 rss 轮询订阅源，新文章主动推送 calendar 30s ticker 检查提醒 memo 5min ticker 检查待办到期 a2a TCP 监听外部 Agent 请求 acp TCP 监听 ACP 客户端 browser ticker + 长命令完成回调 sanitizer 注册 stage 钩子（无工具，要每轮生效） luademo 注册 stage 钩子做示范 纯工具型 ⇒ 按需（13 个）： weather ocr music bili ai_image files editdoc deepsearch plugindev recoverydiag vanblog vikunja commondev ★ commondev 值得单独说：它虽然有 6 处 Inject 调用，但**注入源是自己的 sidecar 完成回投**，而 sidecar 只在 commondev_agent_up 时才拉起 （Start() 里不启 sidecar，通道也在 agent_up 时才注册）。所以没有 agent 调用它时，它不需要做任何事 —— 可以按需。44 个工具 ≈726 tokens 省下来可观。 ## 改动 · 22 个插件各配一个 skill，写明：何时用、先 plugin_start、 工具清单、**用 plugin_stop 而不是 plugin_disable** · 13 个 plg.json 加 `auto_start: false` · `sdk/autostart.go`：把三态语义与"按需插件必须有 skill"的理由写进公开 SDK · hmapdev 打包期校验：`auto_start=false` 但无 skill/ 目录 ⇒ 直接 exit 1 （理由：缺 skill 的按需插件**等价于没装**，比没装更糟 —— 占着磁盘让人以为可用） · 修 Lua 打包路径：它**完全不走** rawfile/skill 收集，luademo 的 skill 永远打不进去 · 修 build-examples.sh：原来 `[ ! -x ]` 判"二进制在不在"，改了 hmapdev 源码后 重新打包**仍用旧工具链**（实测：luademo 的 skill 一直是 0） · 补 mocksdk.ToolDef.Timeout（上一轮加 ToolDef.Timeout 时漏了镜像） ## 判据 · TestHasSkillDirRequiresRealSkillMd（空目录/.gitkeep/无 SKILL.md 都不算） · TestBuildRejectsOnDemandWithoutSkill（打包期必须真拦住 + exit 1） · TestLuaPackagingCollectsSkillAndRawfiles（**验代码行**，不验注释 —— 第一版 只查符号存在，把 createHmapWithRaw 换回 createHmap 判据照样通过） ## 踩过的坑 · Lua 分支的结束边界原是 `// Resolve build config`，但那个注释在文件里 **出现多次**（Go 路径里也有），用它截取会把 Go 分支一起包进来 ⇒ 变异测不出。改成截到 Lua 分支自己的 `return` + `}`。
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