jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-19 16:40:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
116 Commits 5 Branches 10 Tags
main
Commit Graph

55 Commits

Author SHA1 Message Date
JianFeeeee
cfa72df3e9 fix(qq): 权限身份改为绑帧，修中断抢占/运行中到达导致的串权与失效 
问题（都是插件全局 p.auth 一份状态引起）：
- 中断抢占当前轮并把现场压栈，中断轮收尾 afterOutput 清空全局身份；外层
  恢复（resumeTask 复用同帧、不重跑 StageOnInput）后 auth.active=false，
  beforeToolcall 在 !active 处直接返回 —— 该轮剩余工具调用**完全不受门**。
- 运行中到达的新消息会调 activateAuthContext 改写全局身份，把正在跑的那一轮
  换成另一方的身份：换高即越权，换低即误拒。

改法：身份在 StageOnInput 绑定到本帧的 StageContext.Extra 上，beforeToolcall
以帧上身份为准（无绑定时才回退插件全局，兼容单测）。帧随中断栈一起压栈/恢复，
身份自然跟着走。

顺带：合并中断正文里的整批 message_id 现在全部消费（原来只清第一个，其余要等
generation 回收），新增 qqMessageIDsRe 支持 message_id=100,101,102 连写。
新增 4 条测试覆盖：中断恢复、运行中到达、整批 id 消费、非 QQ 轮不受门。
 2026-09-14 16:45:09 +08:00
JianFeeeee
fe1c4cdb09 feat(qq): Bot 所有者消息升到 L2；普通消息保持 L1 
jianf：所有者的话不该被普通人的消息打断/挤到队尾。

- 新增 interruptLevel(owner)：owner → PriorityL2（一般提醒），其余 → PriorityL1（后台）。
  一批里只要有一条来自 owner，整批按 L2 投递。
- 为什么不是 L3：L3 是时钟/终端那类"实时"，QQ 是异步消息，抬到 L3 会打断真正实时的工作。
- 新增测试 TestOwnerMessagesGetHigherInterruptLevel 钉住 owner=L2 / 普通人=L1。
 2026-09-14 16:31:27 +08:00
JianFeeeee
a01fe21ab1 feat(qq): 同一会话连续消息合并为一次中断 + 示例 SDK 指回仓库源码 
需求（jianf）：同一个人连发的数条消息应打包成一次中断，别逐条唤醒 Agent。

- debounce 合并：同一会话 + 同一发送者（群聊按 群号+QQ、私聊按 QQ）在
  batch_window_ms（默认 1500）内的连续消息合成一批，每来一条重置计时；
  整批不超过 batch_max_ms（默认 30000），避免对方持续刷屏时一直不投。
- n>1 时中断说明「短时间连续发来 N 条」并列出 message_id，建议一次
  get_history 拿全上下文；n==1 沿用原文，行为与合并前逐字一致。
- 可配置 batch_window_ms / batch_max_ms，0 = 关闭合并（逐条投递）。
- Stop 时 flush 未到点批次，别把对方消息吞掉。
- 新增 4 条测试（同发送者合并 / 不同发送者不合并 / 窗口 0 逐条 / 单条沿用原文）。

顺带：deepsearch / vikunja 的 go.mod 与 plg.json 此前指向本地安装的 SDK 1.2.0，
导致无法用当前 SDK 重编（缺 InjectOptions.Priority）。改回 ../../ 仓库源码，
与其余示例一致。
 2026-09-14 16:09:45 +08:00
HomeAgent Agent
f09891f054 fix(lua-sdk): 同步注入在 Lua 中明确标记为不可用（避免自锁） 
sdk.inject_input_sync / *_sync_opts / inject_input_media_sync* 要等本轮回复，
而 Lua 代码只在持有插件锁的回调里执行 ⇒ 必然自锁。mock 不再假装返回
(reply,nil)，改为与内核一致的明确错误，避免离线测试误以为可用。
 2026-09-13 21:58:58 +08:00
HomeAgent Agent
efb396d7b3 feat(lua): Lua SDK 全量对齐 1.3.0 + hmapdev 单一 mock 源/版本标记/语法预检 
内核侧 Lua 桥此前停在 v0.8.0 时代能力面，而 1.1/1.2/1.3 新增的
媒体、注入标志位、中断优先级、事件订阅、动态通道注销只在 Go 侧存在，
文档却宣称『能力完全对齐』——属于静默漂移。

本仓（事实源）：
- 新增 sdk/lua/sdk.lua：Lua mock 的单一事实源，补齐全部新 API
  （*_opts / inject_input_sync / inject_*_media / set_tool_blocks /
  unregister_output_channel / events / plugin_mgr / insert_with_media /
  sentence_text+media_digests / attachments / context_policy）。
- scripts/sync-lua-sdk.sh：把事实源同步到 hmapdev assets、luademo、
  以及被 vendored 时的内核副本；三份 sdk.lua 不再各自漂移。
- hmapdev init --lua：优先从激活 SDK 拷权威 mock，内嵌模板降级为
  assets/sdk.lua 回退，不再内联手写副本。
- hmapdev build（Lua）：plugin.json 写入 SDK 版本（能力可追溯），
  打包前用 luac -p / lua loadfile 做语法预检，失败以非零码退出。
- hmapdev debug --lua：优先用激活 SDK 的权威 mock（HMAPDEV_SDK_LUA）。
- luademo 升级为全能力示例（新增 luademo_probe_v2）。
 2026-09-13 19:56:12 +08:00
JianFeeeee
4852d70d77 fix(qq): 输出工具不再受"当前会话身份"限制（修「可信 QQ 会话身份不完整」误拒） 
现场（用户线上，驻留子联调回执原文）：
  被**子的中断**唤醒的一轮里，父 agent 调用 output_send__qq（meta 带齐 user_id）被拒：
  「QQ 权限策略拒绝工具 output_send__qq：可信 QQ 会话身份不完整；请不要改用其他会话 ID 重试」

根因：`sessionToolArgsAllowed` 对**所有**工具都先要求"本轮能精确匹配可信 OneBot 事件"。
`onInputAuthContext` 在来源是 QQ 但匹配不到可信事件时会降权成
`auth = qqAuthContext{active: true}`（无 peer、非 owner）⇒ `currentPeer == 0`
⇒ 连**输出**也一并被拒 ✗。

但输出是 agent 的**主动调用**：发到哪个会话由它自己给的 meta（group_id / user_id）决定，
`handleChannelOutput` 已经强制要求该字段存在（缺了给明确报错）。再要求"当前会话身份"
是多余的门，而且会把合法发送一起挡掉 —— 设计上收到输入后可以往任意（已授权）通道
发任意多次。

改法：`output_send__qq` 在身份判据**之前**直接放行；「只能访问当前会话」这类限制
保留给**读取类**工具（get_history / mark_read / get_message）—— 那才真的不能跨会话读。

判据 `TestDowngradedAuthStillAllowsQQOutput`：
降权态下输出放行、读取类仍被当前会话限制挡住。
扰动验证：去掉放行分支 ⇒ 该判据报出与现场**一字不差**的那句拒绝。
线上实测：CLI 发起的轮次里 output_send__qq 返回 ok，插件日志 handleChannelOutput 确认送达。
 2026-09-13 16:03:24 +08:00
JianFeeeee
21221f20c5 feat(example): plugindev 插件 —— 把 hmapdev 工具链封装成 Agent 可调用的工具 
用户要求：把 SDK 的 hmapdev 额外封装为 HomeAgent 插件并装上。

## 为什么

hmapdev 原本是"给人/CI 用"的命令行。做成插件后，Agent 能自己完成
「新建插件 → 构建 → 安装 → 重载」全流程（配合已有的 plugin_install / plgreload）：

  plugindev_init → plugindev_build → plugin_install(path) → plgreload

## 工具面（5 个）

`plugindev_status`（可用性/版本/当前 SDK/工作区，排障首选）、
`plugindev_init`（脚手架，插件名约束 `[a-zA-Z0-9_-]{1,64}`）、
`plugindev_build`（在工程目录构建打包，返回产物路径与下一步提示）、
`plugindev_sdk`（SDK 版本 list/current/path/latest/install/use，`from` 支持本地源码）、
`plugindev_projects`（列出工作区已有工程与产物）。

## 安全边界（实现里落实）

- 只 exec **hmapdev 一个可执行文件**，不做 shell 拼接；
- `plugindev_build` 只接受含 `plg.json` 的目录 —— 这个工具不会变成"对任意目录跑构建"；
- 子进程全部带超时；输出截断（6000 字符，保留首尾）后才返回，避免几百 KB 构建日志灌爆模型上下文；
- 工作区默认落在 `<data_dir>/plugindev`，配置可改。

## 现场验证

已在本机生产装上（`plugin_install` 带 path）：5 个工具注册成功、
启动日志 `[plugindev] 就绪：hmapdev=/usr/local/bin/hmapdev 工作区=/home/newqqagent/plugindev`，
`hmapdev` 已装到 `/usr/local/bin/hmapdev`（版本 1.3.0）。
 2026-09-13 14:16:46 +08:00
JianFeeeee
11303e3ee4 chore(example): a2a 1.3.0→1.3.1、acp 1.2.0→1.2.1（补 RegisterInputChannel 后升 patch） 
上一提交（4cb3a0b）给这两个示例补了显式 `RegisterInputChannel`，但没有升版本号，
于是生产上"重装"出来的包与实际安装版本同名（1.3.0/1.2.0），既不好追溯也没法用版本比较升级。

本次只改版本号（`plg.json` 是仓库里的真源；`plugin.json` 由 `hmapdev build` 从它同步，不入库）。

实测：升级并 reload 后，内核启动日志里这两个插件的"只声明了出站通道"告警消失
（它们此前是真实缺口 —— 部署件是 9-11 的旧构建）。
 2026-09-13 14:09:07 +08:00
JianFeeeee
4cb3a0bda4 feat(sdk): 通道方向契约落地 + 模板工程/示例插件显式登记 inputch + 生成器两处修正 
## 背景：内核侧发现的真问题

在真实二进制压力测试里发现：插件只调 `RegisterOutputChannel("cli", ...)`，
却用同一个通道名 `InjectTextSync("cli", ...)` 注入输入 ⇒ 内核 inputch 登记表里
**没有**这个通道，"把 inputch 划给驻留子"直接失败（`划入 inputch cli: inputch 未注册`）。

根因是**契约没有落到插件与 SDK 面上**：inputch 是内核最基本的**输入路由单位**，
"谁会往这个通道注入输入"必须显式声明，而 SDK 文档没说清它与 RegisterOutputChannel
的分工，示例与模板工程也没有示范。

## SDK 面

- `RegisterInputChannel` / `RegisterOutputChannel` 的文档补齐**方向契约**：
  入站（谁会注入）与出站（output_send__<name> 的回复发给谁）是分开登记的两件事；
  凡是用 `InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...)` 注入的
  通道名都要 RegisterInputChannel。README 同步补了一段契约说明。

## 示例插件（全部补齐，之前只有 qq/weather 是对的）

`a2a`、`acp`、`browser`、`memo`：注入用 `p.name` ⇒ 登记 `p.name`；
`calendar`、`rss`：注入用字面量通道名 ⇒ 登记同名通道。
（这些插件此前是"能注入、但通道不在登记表里"，与 cli 同类问题。）

## 模板工程（生成器 templates.go）

- `tmplPluginGo`：示范入站+出站两个方向（含 ChannelDef/NoMemory 说明与 `inputch 未注册` 的成因）。
- `tmplMainLua`：同样两个方向（`register_input_channel` / `register_output_channel`）。
- `tmplReadme`：新增 "Channels" 一节（方向对照表 + 兜底告警说明）。
- 实测：`hmapdev init` 生成的 Go/Lua 工程都含通道代码，Go 工程可构建打包出 `.hmap`；
  `--lua` 工程同样生成通道代码。

## 生成器两处修正（都是实测踩出来的）

1. `sdk install --from <dir>`：install 原本只能从 Release 归档下载，而 SDK 开发期的新能力
   （如 proc 桥要透传的 `InjectOptions.Priority`）还没发版 ⇒ 生成的工程必然编译失败
   （`z_proc_gen.go: opts.Priority undefined`）。现在可用本地源码装一个版本并激活。
   实测：`hmapdev sdk install --from <local sdk>` → 装成 v1.3.0 并激活 → 工程构建通过。
2. 构建前置校验 `sdkHasInjectPriority`：proc 桥模板需要 `InjectOptions.Priority`，
   旧 SDK 没有时应给出**可执行**的报错（升级 SDK 或用 `--from`），
   而不是把两条 `opts.Priority undefined` 编译错误甩给用户（那些错误指向生成物，
   完全看不出是 SDK 版本问题）。实测：声明 sdk=1.2.0 的工程构建时正确命中该提示。

## 未决（发布期事项）

`InjectOptions.Priority` 属本特性线新增能力，**已发布的 SDK v1.2.0 不含它**；
发版时 SDK 版本需随之内含该能力（当前源码 meta 已是 1.3.0），否则外部开发者
按文档生成的工程会撞上上面那条守卫。
 2026-09-13 11:37:36 +08:00
JianFeeeee
e50bffa34f fix(deepsearch): 只关自己拉起的 SearXNG；条数改由插件侧截断 
两个都由「真调用/真测试」暴露，且都会让线上搜索表现为「后端不可用」。

一、归属：接管不等于拥有（例：E2E 测试把生产后端带走）
  旧实现只要探活成功就认领关闭责任 → 同机第二个实例（测试拉起的插件、另一个 daemon）
  退出时就 docker compose stop 掉**线上正在用的**后端。实测：跑一次
  `go test ./internal/plugins/ -run TestRealPlugin_DeepSearch`，teardown 即关停
  127.0.0.1:8888，用户看到的就是「搜索后端起不来」。
  修：只有真正执行过 `docker compose up -d` 的实例才算「我们起的」；探到已在运行只接管。

二、条数：SearXNG 不认 count/limit（count/max_results 形同虚设）
  实测 ?count=3、?limit=3、不带参数返回**完全相同的 35 条**，所以截断必须在插件里做。
  旧实现把 count 当 limit 参数发给 SearXNG 就以为生效了 → 模型每次吞 35~58 条带摘要结果，
  还会把「命中 N 条」当成「拿到了 N 条」报给用户（实测发生过）。
  修：新增 limitResults（默认取 max_results，上限 20）；输出改成
  「命中 N 条，返回前 M 条」；不再发无意义的 limit 参数。

验证：22 项单测全过、-race 干净、vet/gofmt 干净；两条归属测试做过扰动（把旧语义放回
去后必红，并如实打出它执行的 `docker compose stop -t 2`）；内核 E2E 三条通过且
**跑完 healthz 仍 200、容器未重启**；线上 1.1.2 实测 count=3 → 「命中 40 条，返回前 3 条」。

版本 1.1.0 → 1.1.2。
 2026-09-13 09:55:27 +08:00
JianFeeeee
4f4a03d368 feat(sdk): InjectOptions.Priority —— 插件声明自己中断的级别（L1-L3） 
内核的输入调度器区分两类别：中断输入（可抢占）与排队输入（可被任何中断打断）。
中断的级别是“这项工作有多不能等”的声明，由插件在注入时给出：

    p.sdk.InjectInterruptTextOpts(src, ch, text, sdk.InjectOptions{
        NoMemory: true,
        Priority: sdk.PriorityL2,   // L1 完全可等 / L2 一般提醒 / L3 需及时
    })

- 新增 `InjectOptions.Priority string` 与 `PriorityL1/L2/L3` 常量（纯追加）。
- 空/非法值一律降级为 L1（默认级）——拼写错误不会被静默当成别的级别。
- **L4 由内核独占**（panic 中断、内核事件中断 selfip），插件声明 L4 会被内核
  夹到 L3，远端常量的取值域里也不提供 L4。
- 排队注入（InjectText*/InjectInputSync*）没有级别：它们本就是“不需及时处理”
  的那一类，可被任何中断打断；传了 Priority 也不会生效。
- 贯通链路：sdk.InjectOptions -> proc RPC 参数（priority）-> 内核 payload；
  tools/hmapdev 模板同步透传（三个注入的 6 个 Opts 变体共用 applyInjectOpts）。
- example/qq 显式声明 L1：QQ 消息既不是时钟那样的实时工作，也不是紧急工作。

兼容性：零值等价于旧行为（L1），既有插件无需改动。
 2026-09-13 07:00:59 +08:00
JianFeeeee
4482235312 fix(vikunja): body 里的 ID 必须是 JSON 数字（建任务/指派在 v2 下必定 422） 
线上真调用暴露：vikunja_task_create 把 project_id 当字符串发出 →
422 validation failed: expected integer at body.project_id。同类的还有指派，
而且 v2 的 assignees **根本不接受 username 字段**（422 unexpected property），
两个分支都是坏的。单测没盖到，因为从未发过真实请求体。

实测（vikunja v2.6.0，2026-09-12）：
  {"project_id":"1"}    → 422 expected integer
  {"user_id":"1"}       → 422 expected integer
  {"username":"jianf"}  → 422 unexpected property
  {"user_id":1}          → 201 ✓
  {"label_id":1}         → 201 ✓（插件本来就 Atoi，无需改）

修法：
- taskBody：project_id 走 parseID（数字）
- 新增 resolveUserID：用户名 → 数字 id，查 GET /users?q=（v1 用 ?s=）；
  **只认精确匹配**，不做「只有一条就用它」的模糊兜底 —— 指派是写别人任务的动作，猜错人更贵
- assigneeBody：v2 只发 {"user_id":N}，不再带 username
- task_assignees remove：路径也用解析后的数字 id

新增 5 项回归测试钉住请求体形状（数字 project_id / user_id、无 username 字段、
数字 ID 不查用户表、移除走数字路径、未知用户给可读错误）。
版本 1.0.0 → 1.0.1。线上复验：create(project_id=1, assignees=jianf) 不再报错、
add→list 显示 jianf、标签 add/remove 正常，测试数据已清理（任务/标签残留 0）。
 2026-09-12 23:43:08 +08:00
JianFeeeee
4cf2df5be6 feat(vikunja): Vikunja 任务管理插件（28 工具） 
token 走 password+Secret 配置项、每次调用前 ensure() 重读（换 token 无需重启）；
v1/v2 差异在插件内处理（建任务 PUT/POST、改任务整对象/PATCH、搜索 ?s=/?q=、
标签对象/{label_id}、TimeEntry 无 seconds 语义）；16 项单测 + 沙盒 homed 实测 28 工具全注册。
 2026-09-12 23:16:33 +08:00
JianFeeeee
ebd700eaf9 fix(browser): browser_search 解析现代 Bing 版式，并把解析失败显式报错 
旧实现三处叠加，模型只拿到「标题=来源行 URL 串、无摘要」，表现为反复换词重搜：
- www.bing.com 对程序化请求常回 302，拿不到结果块 → 改 cn.bing.com
- 块内第一个 <a> 当标题 → 抓到来源行 `deepin.orghttps://www.deepin.org`；改取 h2 > a，
  并解开 /ck/a?...&u=a1<base64url> 跳转包装
- 摘要正则 <div class="b_caption">.*?<p> 对现代版式 0 命中（已迁到 p.b_lineclamp*）
- 分块不再用 (.*?)</li>：块内可能嵌套 <li>（deep links）会在错误位置截断
- 解析不出结果时明确报错，不再伪装成 "No results found."

夹具 testdata/bing_cn.html 为真实 cn.bing.com 响应裁剪；新增 5 项单测。
版本 2.4.0 → 2.4.1（2.4.0 = 交互式 timeout 改必填，此前已提交）。

验证：go test -race 全过、vet/gofmt 干净；线上实测返回真实标题+摘要+规整链接。
 2026-09-12 23:16:23 +08:00
JianFeeeee
7c0b7a1fb0 feat(deepsearch): 联网检索插件 + SearXNG 生命周期托管 
把原 websearch 示例改名为 deepsearch（目录/go.mod/plg.json/工具前缀/README 全量对齐，
工具名 websearch_* → deepsearch_*）。

新增 searxng.go：插件自己托管搜索后端
- 启动探 healthz：已在跑则直接接管（不重启），没跑就 docker compose up -d 并等就绪
- 关闭动作注册为 stop handler（幂等、限时 4s < 内核 5s 宽限期）
- 配置 manage_searxng / searxng_dir / stop_searxng_on_exit
- 崩溃/被 kill 时不关后端（下次启动接管）：安全失败方向
- 可注入 cmdRunner + 时间预算，8 项单测离线覆盖接管/拉起/失败/幂等/保留

契约依据（internal/plugin/proc）：停止插件 = plugin.stop → RunStopHandlers（LIFO、
幂等）→ Stop() → exit(0)，宽限期 5s；stdin 关闭同路径。

验证：19 项单测（18 通过 + 1 联调跳过）、-race 干净、vet/gofmt 干净；内核 E2E 真调用
返回 58 条/37 条、58/58 带摘要；线上 daemon 实测 stop handler 与冷启动（约 3s）。
 2026-09-12 23:16:23 +08:00
JianFeeeee
8c10b7ecc7 feat(browser): 交互式会话的 timeout 改为必填，并补参数校验与测试 
此前 `timeout` 默认 10m：Agent 不传也能开会话，于是"忘记设时长"会静默拿到一个
10 分钟就自己消失的浏览器会话，排查起来像是浏览器不稳。

改为**必填**：
- 新增 `parseBrowserSessionTimeout`（空值 → "timeout is required；创建浏览器会话时必须
  明确指定关闭时长，如 15m 或 2h"；非法或 ≤0 → 明确报错），工具 schema 的
  `required` 加上 `timeout` 并同步描述；
- 缺参时返回可读错误结果（而不是静默套默认值）；
- 新增 `plugin_test.go`（62 行）钉住「不传 timeout 必须报错」等边界；
- 示例版本 2.3.0 → 2.4.0，顺带对齐结构体字段（gofmt）。

验证：`go vet ./...` 干净、`go test ./...` → ok（browser 模块自带 go.mod）。
 2026-09-12 20:17:18 +08:00
JianFeeeee
b237787c90 refactor(toolchain)!: 工具链 plugindev 更名为 hmapdev，module path 改回 gitcode 
- 目录 tools/plugindev → tools/hmapdev，可执行文件名/平台产物名同步
  （hmapdev_linux_amd64 等；包格式仍叫 .hmap）
- module path github.com/JianFeeeee/homeagent-sdk/tools/... → gitcode.com/...
  （与仓库实际托管一致；核心仓不依赖该 path，改动无外部影响）
- SDK 存储目录 ~/.homeagent/plugindev/sdk → ~/.homeagent/hmapdev/sdk
  新目录不存在而旧目录存在时沿用旧目录 → 已装 SDK 版本不会丢失
- 命令表/usage/--help/生成项目 README/示例 README/NSIS 安装器/
  package/build.sh/build-examples.sh 全部同步；PLUGINDEV 环境变量保留兼容
- sdk/ 目录零改动（公开接口不变）

验证：
- go build ./... ok；go test ./tools/hmapdev/ ok（含模板接线守卫 TestProcTemplate_CoversAllCoreMethods）
- bash -n package/{build,build-examples}.sh ok
- 端到端：hmapdev init demo && hmapdev build → dist/demo_bundle.hmap（linux+darwin）
- 本机安装 /usr/local/bin/hmapdev，旧名以软链保留；sdk list/current 正常
 2026-09-12 12:30:20 +08:00
JianFeeeee
ba49dfda44 feat(sdk): 注入行为的记忆/裁剪标志位（纯追加）+ plugindev 退出码修复 + 示例 hmap 随发版 
## 1. 注入标志位（公开 API 纯追加，无签名变更）

给注入行为补上工具早已有的两类声明位，并让通道定义也带上：
- `InjectOptions{NoMemory, ContextPolicy, CleanerName}`
- `IOInjector` 新增六个 `*Opts` 变体（排队/中断/同步 × 纯文本/带媒体）
- `ChannelDef.ContextPolicy`，并**补上 JSON tag**（Cleaner 标 `json:"-"`）

零值 InjectOptions 与旧的三参数方法完全等价（记入记忆 + 不裁剪），
存量插件不需要改一行、也不需要重编；旧方法保留为转发到零值 opts 的语法糖。

三条设计要点：
- **默认不裁剪**：裁剪会归档丢弃低相关事件，必须显式声明（ContextPolicy=prune）。
- **中断也允许声明 prune**（已确认）：中断同样携带内容进上下文。
- `CleanerName`：注入的 source 未必是注册过的输入通道名，而注入内容常带
  ANSI/JSON 包装；允许显式指定用哪个已注册 cleaner 清洗。

顺带修掉一个易静默丢字段的坑：`ChannelDef` 原来没有 JSON tag，只能手写字段
白名单跨进程传（`{"NoMemory": ...}`），新增字段会被丢掉。现在模板整体传 `def`。

## 2. 示例调用点统一写明意图
rss/memo/calendar/qq 的中断注入显式 `NoMemory: true`（行为等价，写清语义）。

## 3. plugindev 出错却 exit 0（真缺陷）
`buildBundle`/`buildTarget` 遇错只 Printf 后 return，`cmdBuild` 返回 void，
于是**构建失败也退 0**。实测中一个示例的 windows 目标编译失败，批量脚本却报
「17/17 全绿」，并因此少产出 16 个 .hmap。现在累计 `buildFailed` 并以非零退出。

## 4. 平台策略：插件目标去掉 windows
homed 已放弃 Windows 原生（见核心仓 cmd/homed/platform_windows.go：插件体系依赖
fd 继承 + 统一共享内存区的段内偏移解引用，Windows 句柄模型无法表达），
插件只运行在 homed 能跑的平台上，故 `allBundleTargets` 去掉 windows，
并对 windows 目标给出**可执行的报错**（指引 WSL2），而不是让它死在一句
`undefined: attachUnifiedShm` 上。

## 5. 发版附带各示例插件的 .hmap
新增 `package/build-examples.sh` 并接入 `package/build.sh`（组件 all|plugindev|examples）：
- 用**刚构建出来的**那把工具链构建示例，保证与本次发版同源
- 逐平台 `--no-bundle --target <os/arch>`（bundle 会连 windows 一起编）
- 判成功同时看**退出码 + 产物存在**
- 全部产物齐了才 `sha256sum`（边打边算会漏掉后生成的包）
- 有任一失败即整体失败，不生成 SHA256SUMS

## 6. 版本
SDK 仍为 1.2.0（main 是下一个未发布中版本）；1.2.0 条目补记本次新增接口，
并注明新标志位需核心 1.2.0+（旧核心会忽略这些字段，不报错但不生效）。
 2026-09-11 20:29:30 +08:00
JianFeeeee
0a164fe4b9 feat(qq): qq_get_message 声明 ContextPolicy=prune（§13.8 验证项） 
消息正文只在当轮需要（决定怎么回复），用完即裁剪。不裁的后果是每条 QQ
消息的完整正文都留在 L0 上下文里，长会话下持续挤占 token 预算。

内核侧 §13.8 早已就位：StageAfterToolcall 之后按 ToolDef.ContextPolicy
调 RelevanceContext.Prune（772a494），但 QQ 侧一直没声明，等于功能空转。
 2026-09-10 21:18:16 +08:00
JianFeeeee
fd5a291df1 feat(qq): 权限门 + 单轮循环保险 + 极简发送回执 (v1.4.0) 
回应 problem.md：核心把「发送成功」的富回执喂给模型，模型读成
「这步成功，继续下一步」而重复调用 output_send__qq。

- handleChannelOutput 成功只返回 "ok"，不回传 NapCat 原始响应（含 message_id）
- 全局权限门 on_input/before_toolcall/post_action：工具白名单、私人资源边界、
  高风险命令 confirm 校验；before_toolcall 的 Response 只用于拒绝单个工具，
  post_action 负责清除以免被内核误当作结束推理的最终响应
- 单轮循环保险：max_qq_tool_calls=200 / max_qq_output_calls=20 /
  max_duplicate_qq_send=1，只拦参数完全相同的重复调用，不误杀必需的多次调用
- plg.json 1.2.0 → 1.4.0
 2026-09-10 20:36:43 +08:00
JianFeeeee
61f307be1a feat(qq): msg_id→get_history 7天兜底 + list_chats/mark_read 会话列表 v1.2.0 
## 问题

1. NapCat get_msg 的 message_id 是 QQ 服务端临时短号，约 3 天后失效。
   实测 1306 条真实 webhook 消息，141 条（10.8%）现在查回报「消息不存在」，
   全是 3 天前的旧消息；1 小时内的消息可正常查回。NapCat 侧无保留时长配置项
   （napcat.json / onebot11_*.json / webui.json 均无），是 QQ 协议硬限制。
   模型收到 not_found 后曾编造正文（虚构 message_id + 虚构需求），
   已在核心 prompt 加事实性约束，此处从插件层根治取不到正文的问题。

2. 插件与真人客户端差距大：没有会话列表、消息不按到达先后排序、无未读提醒，
   模型只能靠单条中断消息被动响应，导致消息处理不及时。

## 改动

### msg_id → get_history 兜底（不缓存正文）
- 新增 msgRef{peerID,isGroup,time}：只记 msg_id → (peer, 时间) 映射，7 天 TTL
  （qqMsgTTL），超 2000 条时惰性清理过期项。不缓存消息正文。
- handleGetMessage 改为包装层：命中映射且 <7 天 → getMsgFromHistoryByTime()
  按 peer 拉 get_history(count=50)，取时间最接近的一条，
  经 msgToGetMsgResult() 包装为与 get_msg 同构的结果（附 resolved_via:history）；
  未命中或超 7 天 → 回退原 NapCat get_msg（重命名为 getMsgFromNapcat）。
- 超 7 天的消息由 get_history 自行处理，插件不做长期缓存。
- not_found 文案改为明确引导改用 qq_get_history / qq_list_chats。

### 会话列表（对齐真人客户端）
- 新增 chatMeta：会话名、未读数、最新一条 ≤60 字摘要（qqLastSumLen）、最新时间。
  只维护最新一条摘要，不存历史。
- 新增 qq_list_chats：按最新消息时间降序返回会话列表，每项含
  peer_id/type/name/unread/last_text/last_nick/last_time。
- 新增 qq_mark_read：按 group_id/user_id 清零未读；get_history 拉取某会话后
  自动标已读（看过=已读，与真人客户端一致）。
- webhook 记录时机前移：策略允许的消息（群/私聊、是否 @bot 均记）都进入映射与
  会话状态，@bot 只决定是否发中断——与真人客户端一致能看到全部会话。

### 中断模板
- 补 fallback 路径与私聊 user_id（原模板只给 message_id，取不到正文时
  模型没有 peer 信息可用于 get_history）：
  「先用 get_message 取正文；若取不到（已过期），改用 get_history(...) 按会话拉取，
   或用 list_chats 查看未读会话。用 output_send__qq 回复」

## 验证

用重建的 plugindev build --target linux/amd64 产出 dist/qq_linux_amd64.hmap，
经内核 plugin_install(overwrite=true) 安装（action=reinstalled, config_kept=true），
重启 homed 后内核注册 20 个 qq_* 工具（原 18 + list_chats + mark_read）。
实测 qq_list_chats(count=8) 返回按时间排序的会话，unread=6 正确累积。

注意：cgo c-shared 插件带完整 Go runtime，dlclose 后引用计数不归零，
同路径 dlopen 复用旧映像，plgreload 无法热替换 .so，换 .so 必须重启 homed。
 2026-08-30 17:11:57 +08:00
JianFeeeee
130f805b6e feat(sdk): SettingsAPI.DataDir() + plugindev dispatchSettings 补 DataDir 
SDK SettingsAPI 新增 DataDir() 插件专属数据目录；
plugindev 工具链 dispatchSettings 模板补 DataDir 实现（callString 51）。
ai_image example 改用 DataDir + 本地交付。详见 TrueAgent 仓库。
 2026-08-26 21:41:28 +08:00
JianFeeeee
cd1984e26e feat(ai_image): base_url 设置项支持自定义 OpenAI 兼容网关 v1.1.0 
generateOpenAI 支持配置 base_url 指向 OpenAI 兼容网关（如本机
llmsproxy），为空保持官方直连。已实测经 llmsproxy→siliconflow
(Kwai-Kolors/Kolors) 生图出有效 PNG。
 2026-08-26 19:47:01 +08:00
JianFeeeee
6184736fd4 feat(examples): a2a/acp 会话历史查询 + 出站 session_id 透传 
a2a tasks.get/session.get 返回会话近N条消息；acp 新增 session/get；
a2a_query/acp_query 接受 session_id 延续对方会话。详见 TrueAgent 仓库。
 2026-08-26 19:30:34 +08:00
JianFeeeee
81bfdfce1d fix(examples): a2a/acp 回复闭环 + 会话延续 + 同步注入 
入站请求从 InjectInterruptText(202 submitted) 改为 InjectInputSync
同步等待回复，直接返回回复文本；支持 params.session_id 延续多轮
上下文；注册为输出通道让回复有落点。详见 TrueAgent 仓库同名 commit。
 2026-08-26 19:16:49 +08:00
JianFeeeee
e3f93e254b chore(recoverydiag): 补齐 go.mod 与 main.go（与其他插件结构一致） 2026-08-26 17:05:24 +08:00
JianFeeeee
d57c5eaf3e fix(examples): 全插件安全审查修复（qq/a2a/memo/calendar/rss/browser/bili/recoverydiag） 
审查发现并修复 7 项问题：
- P1 qq: downloadURL 裸 http.Get 无超时 → 120s client
- P2 a2a: inbound http.Server 零超时 → Read 30s/Write 120s/Idle 60s
- P3 bili: output_dir 配置项零校验 → 系统目录黑名单（/、/etc、/usr、/var 等）
- P4 recoverydiag: db_path LLM 可控任意 sqlite → 强制限制 data 目录内
- P5 memo/calendar/rss: os.WriteFile 直写 → atomicWriteJSON (temp+rename)
- P6 qq: 3 处后台 goroutine（已读/rcon转发/下载）加 panic recover
- P7 browser: dump-dom failback Kill 后补 wait 回收僵尸进程

recoverydiag 此前被 .gitignore 排除，但其 db_path 安全修复
属生产代码，故取消忽略并入库。

全部经 plugindev 重打包升版安装验证 config_kept=true。
 2026-08-26 17:04:41 +08:00
JianFeeeee
5c5df9cfb9 demo(luademo): pre_action stage 展示写回(llm_text 追加标记) 2026-08-15 18:11:33 +08:00
JianFeeeee
c91739d670 fix(qq): parseIDList 兼容科学计数法存库的历史坏值 
配置里 QQ 号被 WebUI 以科学计数法(2.198972886e+09)存库时,
ParseInt 解析失败导致 adminIDs 为空、老大消息不被标记。
ParseInt 失败后回退 ParseFloat, 整数值转为 int64。
 2026-08-15 17:24:21 +08:00
JianFeeeee
392f391f68 v0.9.0: C ABI v2 stage 写回 + ABI 版本对齐核心版本号 
- meta: ABI 标识版本改为字符串 semver（ABIVersion=CoreVersion="0.9.0"），
  C 层协商用派生整数 CABINum=900（major*100+minor），不再用独立数字编码
- plugindev 模板: invoke_stage 增加 result out 参数（stage 写回），
  插件在 OnInput/AfterToolcall/PostAction 修改 StageContext 后回传内核
- cmd_init: CABIVersion 改用 CABINum
- example/sanitizer: 增强为全链路清洗（坏 UTF-8/U+FFFD/ANSI 转义），
  挂载 OnInput/AfterToolcall/PostAction 三阶段（依赖 stage 写回能力）
 2026-08-15 15:52:10 +08:00
JianFeeeee
cca9fdce9c example: 新增 acp(ACP 代理通信)、vanblog(VanBlog 博客管理) 插件; 多插件工具调用检测与清理改进; weather 移除 onRemove/文本记忆; plugindev 精简 2026-08-15 09:03:05 +08:00
root
b6e30f9279 tools: plugindev 工具链支持公共 IOInjector.InjectInputSync（CORE_INJECT_INPUT_SYNC=47，z_bridge dispatchIO 桥接），重建 bin 预编译二进制；example/memo: plg.json 修复（name_en 去斜杠、去 BOM）；sdk/plugin.go 注释精简 2026-08-02 16:24:59 +08:00
root
8e5610c494 example/memo: 待办与备忘分离（待办提醒、备忘纯记事） 
- 待办（todo_add/todo_complete/todo_list）：保留原有主动提醒能力——
  stagePreAction 注入未完成条数 + periodicCheck 每 5 分钟 InjectInterruptText；
  数据文件 todos.json
- 备忘（memo_create/memo_list/memo_delete）：纯记事用途，不参与任何提醒
  （无 stage 注入、无周期中断）；数据文件 memos.json
- cleanupData 卸载时清理两个数据文件；ID 各自独立递增
 2026-08-02 15:47:37 +08:00
root
aee63a4f98 example: 演示插件 onRemove 清理补齐（memo/rss/weather） 
- memo: 卸载时删除 memos.json 数据文件
- rss: 卸载时清理 .homeagent/rss 订阅数据目录
- weather: 卸载时清理 .homeagent/weather 缓存目录
- 与 calendar（events.json）一致：仅删除触发、重载不触发；
  files（filesDir 为用户配置的访问根目录）、bili/qq（用户下载资产）、
  ocr（临时目录函数内自清理）按语义不加入删除回调
 2026-08-02 13:37:59 +08:00
root
fb07081929 插件删除回调（onRemove）与模板/示例同步 
- sdk: RegisterOnRemoveHandler/RunOnRemoveHandlers（仅卸载时触发，重载不触发；
  后注册先执行、幂等），与 RegisterStopHandler/RunStopHandlers 并存
- plugindev: 模板 main.go.tmpl 新增 onRemove 演示（删配置键），templates.go 同步
- example/calendar: RegisterOnRemoveHandler(p.cleanupData) 卸载时清理 events.json
- README/README_EN: 生命周期文档补充 onRemove
- example/calendar/plg.json: 版本对齐
 2026-08-02 13:33:25 +08:00
root
2b54814037 examples: update weather with v0.8.0 API surface, add luademo Lua example, fix go.mod replaces 2026-07-31 10:59:13 +08:00
root
84bf100a12 example/qq: add typing indicator on private messages 
- setInputStatus helper wrapping NapCat set_input_status API
- startTyping/stopTyping with goroutine-based typing manager
  (5s interval, 30s auto-timeout)
- start typing on webhook private message receipt
- stop typing when output channel sends a response
- fix plg.json UTF-8 BOM that broke plugindev parse
 2026-07-30 09:24:20 +08:00
root
4d01e75282 example/qq: use relative replace path, disable bundle mode 2026-07-29 15:24:43 +08:00
root
c5bcae9404 sdk: add RegisterInputChannel + NoMemory/Cleaner support 
- ChannelDef struct: NoMemory bool + Cleaner func(string) string
- InputChannelRegistrar interface + RegisterInputChannel method
- RegisterOutputChannel now takes ChannelDef parameter
- QQ example registers input channel with NoMemory:true + Cleaner
 2026-07-29 14:46:15 +08:00
JianFeeeee
04837f237d plugindev: 全面 plg.json 持久化 + --replace 支持 + 文档 2026-07-25 15:47:49 +08:00
JianFeeeee
cb7999ca71 feat: sdk NoMemory/Cleaner + example build fixes 
- sdk/plugin.go: ToolDef adds NoMemory/Cleaner fields
- sdk/plugin_test.go: unit tests for NoMemory/Cleaner
- all example plugins: NoMemory/Cleaner annotated for each tool
- plugindev/templates.go: template shows NoMemory/Cleaner pattern
- plugindev/cmd_build.go: fix ensureGoMod, buildBundle/buildTarget sdkPath param, NewPluginFactory
- example/go.mod: add external dependency declarations (chromedp, gofeed)
- add main.go stubs for all example plugins
 2026-07-25 11:17:21 +08:00
root
34f91ebd1a fix(browser): pre-allocate chromedp context, remove timeout contexts from interactive handlers 
- Pre-allocate browser in handleBrowserStart with chromedp.Run(s.ctx)
  to avoid the first-Run timeout killing the browser process
- Replace all per-action context.WithTimeout with s.ctx in navigate,
  click, type, screenshot, html, scroll handlers
- Add cleanupLoop goroutine for session-level timeout safety
- This matches chromedp docs warning: first Run with timeout context
  stops the entire browser
 2026-07-23 13:53:40 +08:00
root
5e0c8d5a40 feat(qq): download task tracking with qq_get_download_tasks, sync re-added 2026-07-23 10:41:08 +08:00
root
e182b89983 feat(qq): async file download, get_private_file_url, mark-as-read, get_recent_contacts 2026-07-23 10:36:49 +08:00
root
e030a9b9f9 refactor(qq): remove local message cache, direct NapCat query, URL-based file download 2026-07-23 10:27:55 +08:00
root
7705e4eb3b feat(a2a): add management tools (a2a_configure, a2a_restart, a2a_status) for dynamic config 2026-07-22 17:32:28 +08:00
root
ab3c0bfd2d fix(qq): use file_id instead of file field for group file download 
NapCat file messages have file_id in data["file_id"], not data["file"].
data["file"] is the filename, causing get_file API to return empty.
Also pass url field to downloadFile for URL-direct fallback.
 2026-07-21 15:33:41 +08:00
root
1a3e72e899 fix: use short config keys in RegisterDef, remove generics helpers 
- qq, a2a, bili, files, rss: RegisterDef keys changed from
  namespaced (e.g. "plugin.qq.listen") to short flat keys ("listen")
- a2a, bili: Get() calls updated to match short keys
- rss: replaced readCfg generics with getSetting, added SetAutoRestart(true)
- files: already uses short key Get, only RegisterDef needed fixing
 2026-07-21 13:20:13 +08:00
root
52dc22f86f feat: add example plugins (ai_image, calendar, music, rss, weather), fix .gitignore, move gengskill to tools/ 2026-07-21 12:45:17 +08:00
root
75ae2b4692 fix: napcat returns json.RawMessage to avoid double-quoting in C ABI bridge 
go_invoke_tool does json.Marshal(r) on handler results. When r is a string,
the raw JSON gets wrapped in quotes and escapes, causing the core's
json.Unmarshal into map[string]interface{} to fail (displayed as map[]).

Changed return type to json.RawMessage (implements json.Marshaler, outputs
raw bytes inline). Added rawString() helper for callers that need the
string representation.
 2026-07-20 17:51:36 +08:00