mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 22:37: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` + `}`。
联网检索插件（HomeAgent）
给 agent 补上真正的信息检索能力：检索交给本地 SearXNG（多引擎聚合、结构化 JSON）， 并补上「读完前 K 篇再回答」的深检索。
为什么需要它（背景）
agent 原本只有 browser_* 那套浏览器工具，联网检索实际只有 browser_search 一个入口，而它是
「抓 Bing HTML + 正则解析」：
| 缺陷 | 实测结果 |
|---|---|
标题取的是结果块里第一个 <a> |
拿到的是 Bing 的「来源行」而非标题 → deepin.orghttps://www.deepin.org |
摘要正则 <div class="b_caption">.*?<p> |
对现代 Bing 命中 0/10（摘要已迁到 p.b_lineclamp*）→ 结果完全没有摘要 |
用 www.bing.com |
程序化请求直接 302；cn.bing.com 才返回 10 个结果块 |
| 单引擎、无兜底、无去重、无站点读取 | 模型只能反复换词重搜（日志里 8 秒 6 连击） |
结果就是日志里那句用户反馈：「你的搜索能力好像不太行啊」。
依赖：本地 SearXNG（由本插件托管）
插件会自己管后端：
- 启动时：探
healthz；已在跑就直接接管（不重启），没跑就docker compose up -d并等就绪（上限 6s） - 停止时：跑
docker compose stop -t 2关闭它
配置项 manage_searxng（默认 true）与 searxng_dir（默认 /root/searxng-agent）控制这套行为；
stop_searxng_on_exit（默认 true）设 false 可让后端在插件停止后继续跑（插件重载频繁时建议设 false，
否则每次重载都会把后端重启一遍）。
生命周期契约（依据内核源码，非猜测）
| 环节 | 内核行为 |
|---|---|
| 停止插件 | 发 plugin.stop → 插件先跑 RunStopHandlers（LIFO、幂等） → 再 Stop() → exit(0) |
| 宽限期 | 5 秒；未退出则直接 SIGKILL —— 所以关闭动作限时 4s（searxShutdownBudget） |
| stdin 关闭 | 同样会跑 handlers + Stop() |
| 崩溃/被 kill | 关闭动作不会执行，后端会留在运行态；下次启动探测到就直接接管（更安全的失败方向） |
| 自动重启 | SetAutoRestart(true) 由注入的 runtime 在 plugin.start 后经 lifecycle.autoRestart 显式上报内核 |
SearXNG 侧配置
部署在 .60，127.0.0.1:8888：
/root/searxng-agent/docker-compose.yml # host 网络（要访问宿主 clash）
/root/searxng-agent/settings.yml # json 输出 + limiter 关闭 + 出站走 clash
两个必须知道的坑：
search.formats必须含json，否则/search?format=json返回 403（看起来像网络问题，其实是配置）。- 该镜像默认
GRANIAN_PORT=8080，而 granian 的GRANIAN_*优先级高于 settings.yml： .60 上 8080 被 homeagent 占用 → 不改SEARXNG_PORT就是无休止的Address already in use崩溃循环。
实测可用的引擎（2026-09-12）：duckduckgo、brave、google cse；quark 时好时坏；
baidu/google 经代理出口触发 CAPTCHA，sogou 崩溃，wikidata 报 HTTP error（已关）。
工具
| 工具 | 说明 |
|---|---|
deepsearch_search |
联网检索（首选）：标题 + URL + 摘要 + 发布时间，支持 engines/category/time_range/language，自动按 URL 去重并按分数排序；会回报引擎覆盖度与无响应引擎 |
deepsearch_news |
新闻检索：news 类别 + 默认最近一周；新闻为空时自动回退 general + 时间范围 |
deepsearch_fetch |
抓单个网页并抽正文（去脚本/样式/导航），返回标题 + 纯文本，可设截断长度 |
deepsearch_deep |
深检索：检索 → 并行抓前 K 篇正文 → 一次返回「候选清单 + 证据正文」；单篇失败不影响整体 |
deepsearch_status |
自检：healthz、json 是否可用、延迟、哪些引擎真的在返回结果（检索出问题先跑这个） |
配置项
| 键 | 默认 | 说明 |
|---|---|---|
searxng_url |
http://127.0.0.1:8888 |
本地 SearXNG 地址 |
max_results |
8 |
默认条数（控制上下文体积） |
language |
zh-CN |
检索语言 |
safesearch |
0 |
0 关 / 1 中 / 2 严 |
request_timeout |
20 |
单次请求超时（秒） |
fetch_max_chars |
4000 |
deepsearch_fetch 正文上限 |
proxy |
空 | 仅作用于本插件直连抓取（搜索出网由 SearXNG 侧负责） |
user_agent |
Chrome UA | 抓取用 |
每次调用前重读配置，改完即时生效。
开发与验证
go test -count=1 -race ./... # 11 项测试（httptest 打桩 SearXNG）
# 真实后端联调（默认跳过）：跑的就是当初失败的那条查询
DEEPSEARCH_LIVE_SEARXNG=http://127.0.0.1:8888 go test -run TestLiveSearxng -v ./...
hmapdev build # 产出 dist/deep_search_bundle.hmap
已知边界
- 知乎等站点对直连抓取返回 403（反爬），
deepsearch_deep会如实标注该篇抓取失败并继续； 这类页面请改用浏览器工具（browser_navigate+browser_render）。 - 引擎可用性随出口 IP 与目标站点风控变化；
deepsearch_status与每次结果里的「覆盖度」行就是给这个用的。 - 未做正文去重/相似度合并：同一事件的多篇转载会各占一条（摘要已能区分）。