|
|
e849f39663
|
feat(examples): 内置插件外置化 —— cmd/localuse/mcp 迁入 example + files 新增按行号精确编辑
## 背景
主仓按「只有必须使用内部 SDK 能力的插件才内置」的判定标准（见主仓
ARCHITECTURE「内置插件的判定标准」）把纯公开 SDK 插件移出编译期内置清单。
本仓为它们提供外部插件工程（example/ 下，hmapdev 可直接构建）。
★ 终审翻案：kbtree 与 multimodal **不**在本次外置之列 —— 逐方法对照
公开 SDK 后发现它们依赖内部专有能力（kbtree 要 KnowledgeAPI 的
Subtree/CategoryCounts/SearchIn/Categories 与树视图类型；multimodal 要
LLMAPI.Chat 与多模态消息类型），公开面没有，已加回主仓内置清单。
## 新增工程（全部对齐当前模板 + 随用随起契约）
| 工程 | 工具 | auto_start | 说明 |
|---|---|---|---|
| cmd | cmd_run | false（按需） | 沙箱执行 shell 命令 |
| localuse | screensee/screensue/camerasue/speakeruse/clipboardsee/clipboardsue/computeruse | false（按需） | 本机外设 |
| mcp | mcp_add/list/remove/restart_server | false（按需） | MCP 服务器接入（stdio/SSE） |
每工程：plg.json（含 sdk 字段声明）+ skill/<name>-tools/SKILL.md +
README。按 auto_start 契约（sdk/autostart.go 的 OnDemandNeedsSkill），
**auto_start=false 必须配 skill**，否则工具不出现在初始清单 ⇒ 模型不知道
它存在 ⇒ 永远不会被拉起，等于没装还占地方。
## 移植要点
- 注册：内置版 init()+RegisterFactory → 外部版导出 NewPluginFactory；
RegisterPluginMeta 的显示名进 plg.json/plugin.json。
- mcp：本地 rpcRequest/rpcResponse/rpcError 与 hmapdev 生成的
z_proc_gen.go 同名冲突（构建期生成物与本目录源码同包编译），
本地类型改名 mcpRPC*；internal/safeclose 内联为 safeCloseChan
（外部插件不能引 internal 包，close-of-closed-channel 纪律随之带过来）。
- module 名：cmd 的 go.mod 用 homeagent-cmd（避免与标准库 cmd 混淆）；
name_en 对齐插件名，hmapdev 以 toSnake(name_en) 命名产物
（此前误写 Command/Local，产物成了 command_/local_）。
## files：新增 files_edit_line（按行号精确编辑）
files_edit 要求 old 文本全文件唯一，改「第三个 case 的 break」这类
非唯一文本时只能退化为整文件重写（有损）。files_edit_line 按行号
定位，op=replace/insert/delete，支持：
- 多条 edit 从后往前应用（前面行号不漂移）
- expect 安全闸：行内容与预期不符则整体拒绝（防行号过期改错位置）
- CRLF/末尾换行保真
skill 同步补 edit_line 行。测试 5 条（含 expect 拒绝路径）。
## 验证
hmapdev build 四工程全过：cmd/localuse/mcp/files 产物齐；
go test files 全绿。
|
2026-10-19 22:01:07 +08:00 |
|
|
|
bea410f891
|
fix(qq): 私聊历史拉不到 —— group_id=0 被当成"查群 0"
现场（2026-10-19 内核日志，13 次调用全灭）：
用户反复说"gethistory 拉不到私聊消息"，纠正多次仍不改。
查日志：qq_get_history 失败 13 次，错误全部是
napcat get_group_msg_history: retcode=200: 消息undefined不存在
而 get_friend_msg_history 一次都没被调用过。
## 根因
handleGetHistory 用 `convInt64(args["group_id"])` 的 **err==nil** 判"调用方给了群号"，
而 convInt64 对 0 也成功返回。于是：
模型 qq_get_message 取私聊正文
→ 返回体无条件带 "group_id": 0（QQ 协议里私聊群号就是 0）
→ 模型把字段原样抄进 qq_get_history
→ 代码认为"要查群 0" → get_group_msg_history(group_id=0)
→ NapCat 回「消息undefined不存在」，看起来像历史拉不到
实机验证：直接 POST NapCat
get_group_msg_history {"group_id":0} → retcode=200 消息undefined不存在
get_friend_msg_history {"user_id":…} → retcode=0 正常
## 改动
1. 新增 argPeerID：把 0 判为"未提供"（群号/QQ号都是正整数，0 从不是合法会话）。
权限门用的 argInt64 早有 parsed!=0 检查 —— 本仓此前是「权限门严、取数松」。
2. handleGetHistory 改用它，并区分三种情况：只给 user_id 走私聊、只给 group_id
走群聊、两个都给直接报错（旧实现静默选群分支，把私聊打成群查询）。
3. 同一零值缺陷一并修：handleSendFile（group_id=0 会发往不存在的群）、
handleMarkRead（markChatRead(0) 静默清空不存在的会话）、
handleResolveNickname（group_id=0 打群成员端点）。
4. **msgToGetMsgResult 私聊不再输出 group_id** —— 这是根因的上游。只改下游判据
只能止血，模型仍会一次次把 0 抄回来。
5. schema 写死参数语义：「私聊必须省略 group_id、只传 user_id；不要传 0」。
模型需要知道自己该传什么，否则会反复试错。
6. skill 补「拉私聊历史」整节 + 常见报错对照表；顺带修正一句错述
（原文称"本插件声明 auto_start: false"，实际三方都未声明，按契约默认自启）。
7. 新增 history_endpoint_test.go：5 条判据钉住端点选择与返回体契约，
用 httptest 打桩 NapCat，断言真实命中的 action。
## 版本
1.4.3 → 1.4.4。已构建 hmap 并经 plugin_install 装到本机生产实例，
增量重载后 qq 子进程换新、工具全部重注册、skill 移交 skillmgr。
|
2026-10-19 20:27:23 +08:00 |
|
|
|
cca6fdaa6b
|
fix(qq): 打字指示器挂到正确路径 + 状态限流改为补发而非丢弃
用户反馈两处仍然不对：
「qq插件的通过在线状态展示agent工作状态还是不正确」
「正在输入中显示也不正确」
## 缺陷 1：打字指示器一次都没触发过
诊断日志给出了决定性证据（加临时探针跑真实私聊）：
[qq-dbg] before_output: input_source="" qq_uid=<nil>(has=false) extra_keys=0
`extra_keys=0` —— 说明触发的是**另一条路径的 before_output**。
`before_output` 被两个语义共用：
emitResponse（eventloop.go） = 一轮的回复，turn 边界
output.go = 单次 output_send__* 的工具输出
**真正把消息发出去的是后者**，而它构造 stageCtx 时**连 Extra 都没初始化**
（nil）。我把打字指示器挂在它上面，读了永远不存在的 qq_uid。
修法：内核 output.go 的 stageCtx.Extra 补三个键
output_channel 目标通道
output_meta 本次发送的 meta 原文（user_id / group_id）
output_type text / image / file
插件据此在**消息发出前** startTyping，发出后 stopTyping。
群聊不发（QQ 的「正在输入」只在私聊标题栏有意义）。
## 缺陷 2：output.go 路径没有 after_output
它才是"消息真的送达"的时刻，却只发了 before_output。没有配对的收尾，
指示器只能等 30 秒超时自己灭。补上 after_output。
★ 但 after_output 现在被两条路径共用，必须区分：
单次发送 → stopTypingAfterOutput（配对的收尾）
turn 边界 → stopTypingForTurn + auth 清理 + **状态归位「在线」**
状态归位**只能由 turn 边界触发**：一轮可能发多条消息，若每条发完都归位
「在线」，状态会在干活期间反复跳回空闲 —— 那正是"用状态展示工作进度"
失效的原因之一。
## 缺陷 3：限流把期望状态丢掉了
`applyStatusMaybe` 命中 2 秒限流时直接 `return`，**期望状态被丢弃**。
而 stage 之间常常不到 2 秒：
pre_action(学习中) --0.5s--> before_toolcall(搬砖中)
⇒ "搬砖中" 被丢
状态是「当前工作阶段」的**投影**，不是事件流 —— 投影必须最终收敛到最新值。
改为：限流只限制发送频率，被推迟的记进 `pending`，窗口结束后补发**最新**值
（不是补发被拒的那个：窗口内可能连来多个，中间值没有独立意义）。
`restoreStatus` 停机时先取消待补发，否则定时器会在连接拆除后醒来。
## 实测（真实私聊 webhook）
17:58:15 对方正在输入中 → 开始（uid=2198972886，消息发出前）
17:58:15 对方正在输入中 → 结束（uid=2198972886，消息已发出）
状态序列体现出工作阶段：
17:58:05 学习中（限流后补发）
17:58:07 搬砖中
17:58:09 学习中（限流后补发）
17:58:15 搬砖中
17:58:19 在线（turn 边界，任务结束）
## 判据
新增 TestOnlineResetOnlyOnTurnBoundary（变异咬：单次发送也归位 → 报错）。
★ 修了判据自身的假绿：typing_test 的 bodyOf 用"找行首 }"截函数体，
stageAfterOutput 新增 if 分支后，第一个行首 } 是**内层块**的结尾
⇒ 判据只看到前半段 ⇒ 后半段的调用"看不见"、删掉也不咬。
改用括号计数的 funcBody。
|
2026-10-18 18:01:00 +08:00 |
|
|
|
c6c39aa2a8
|
feat(qq): Qzone 说说、群发硬拦截、@全体不算@bot、状态语义修正
## 1. Qzone 说说（send_qzone_msg / delete_qzone_msg）
一次真实的误判，值得记下来：我曾断言「生产 NapCat 不支持发说说」，
依据是探测返回「不支持的Api SendQzoneMsg」——**是我的调用名错了**。
router.ts 里声明的是下划线式 `send_qzone_msg`，我用的是源码**类名**
`SendQzoneMsg`。换对名字后一次成功。
教训：「API 不存在」这个结论必须用真实 action 名验证；源码里的
类名/文件名/方法名都不是调用名。判据 TestQzoneActionNamesAreSnakeCase
把这条钉住了。
本地校验 ugc_right 白名单（1/4/16/64/128）与 16/128 必带 target_uins，
省一次跨进程往返、给模型更直接的反馈。
## 2. 内部委派不得向群聊发送（现场事故）
offload 子 agent 的「分诊汇报」把本该私聊给用户的进度播报**发到了群里**：
17:15:41 executing tool: output_send__qq
17:15:41 handleChannelOutput meta={"group_id": 979911915}
17:15:42 群友质问「又没@你，你就这么确定是找你的？」
根因：子 agent 被授予全部输出通道（AllowedOutputs=nil，用户明确要求
"持有全部输出通道"），于是它能自己选目标——而它只从上下文里看到一个
群号，就选了群。
修法：`beforeToolcall` 在 internal 放行前调用 outputSendGroupTarget，
识别出群目标就写 denial。为什么不放在 handleChannelOutput：ToolHandler
只收 args，拿不到帧上的 comefrom（SDK 契约如此），只有 stage 帧能看到。
## 3. @全体成员不算 @bot
原实现 `if v == botIDStr || v == "all" { return true }` —— 任何人
@全体都会拉起 bot。那不是"在叫 bot"，是"在叫所有人"：一个是针对性请求，
一个是广播，语义完全不同。
群里误响应的代价不是"多回一句"，而是**在未被邀请的场合发言**。
宁可漏响应（用户会再 @ 一次），不能误响应。
## 4. 状态语义按用户定义重排
学习中 = 等待 LLM 搬砖中 = 执行 toolcall 在线 = 空闲
pre_action → 学习中（stepLLM 之前，唯一能提前标记"要等模型"处）
before_toolcall → 搬砖中
after_toolcall → 学习中（工具回来了，又要等 LLM）
before_output → 不改（LLM 已回、即将输出，不是等模型）
after_output → 在线（force，绕防抖）
原先「学习中」挂在 before_output 是错的：那个时刻 LLM 已经返回。
## 5. 「对方正在输入中」按轮驱动
起点从 HTTP 入口（消息刚到）改到 before_output（每轮只触发一次），
终点从 output_send（任何发送都停，含群聊/发给别人）改到 after_output。
身份由 InjectOptions.Payload 携带 `qq_uid`，内核透传到 stageCtx.Extra。
不用全局 p.auth：并发私聊会串号（A 的指示打到 B 身上）。
## 6. 启动日志不再硬编码工具数
`log.Printf("... (%d tools)", p.name, 15)` 硬编码了 15，工具加到 24 后
仍报 15 —— 排查"qzone 装上没"时被误导了好几轮。改成真实计数 p.toolCount。
## 判据（新增 13 条，变异 8/8 咬）
Qzone 5 条、群发拦截 5 条、@门 4 条、状态映射 7 条、打字 7 条。
★ 两个判据自身缺陷被变异抓出并修掉：
· @门判据用字符串找 `}\n\t}` 截分支，而 joined 已 strip 缩进 ⇒ 找不到
⇒ 分支延伸到文件末尾 ⇒ "文件里任何别处的 return"都让它通过。
改用括号计数 ifBlockAt。
· 状态判据只查常量名，`_ = qqStatusStudy` 就蒙混过关。改查真实调用
applyStatus(qqStatusStudy)。
|
2026-10-18 17:39:40 +08:00 |
|
|
|
4a9705ca41
|
feat(hmapdev): 构建期告警「同一 stage 被重复注册」+ qq 合并写法
## 用户指出的关键：告警要给**开发者**看，所以必须在构建期
我第一版把告警放进了工具链生成的 proc_main 模板（插件**运行期**打日志）。
用户直接指出：「本身工具链这个编译器警告就是给开发者看的」——运行期日志
是给运维/用户看的，开发者看不到。已撤销，改为构建期静态检查。
## 缺陷（真实事故，2026-10-18）
插件侧把 stage handler 存在 `map[string]sdk.StageHandler`（stage 名为键）⇒
**同一 stage 注册两次，后者静默覆盖前者**。
QQ 插件当时写成：
RegisterStage(BeforeToolcall, 权限门) ← 被下一条覆盖
RegisterStage(BeforeToolcall, 切状态) ← 实际生效
后果不只是状态不切换 —— **权限门被静默关掉了**（那几版部署里任何人
发消息都能调任何工具）。编译器不报、运行时不报错、内核日志还显示
`2 handlers [qq qq]`（看着完全正常）。只有静态检查能发现。
## 实现
· `stage_dup_check.go`：扫构建目录下的 .go（排除 _test.go 与 z_proc*），
统计每个 stage 常量被 RegisterStage 引用几次，>1 就告警
· 接入 `buildTarget` 开头 ⇒ 所有 target（含 lua）都检查
· **只告警不中断**：存量插件里重复注册可能是本意，直接 fail 会让它们
升 SDK 后无法构建
· `example/qq`：三个重复 stage 合并成单 handler（权限门 + 状态切换）
## 判据（4 条）
· 同 stage 两次 ⇒ 报出来
· 不同 stage 各一次 ⇒ 不误报
· **注释里的示例注册不计入**
· 测试文件 / 工具链生成文件不计入
★ 「注释」这条是这个检查器**第一版自己栽的坑**：直接对全文跑正则，
把插件里「当初写错了、留在注释里当教训」的那几行也统计进去，于是
修好之后照样报「注册了 3 次」（实测）。现在逐行跳 `//` 与跨行 `/* */`。
本项目已多次绊倒在「注释里有、代码里没有」上，这次轮到检查器自己。
## 实测
qq 修好后构建： packaged qq_linux_amd64.hmap（无告警）
故意加一条重复： ⚠️ 警告: stage StageBeforeOutput 注册了 2 次
建议：把多个功能合并进同一个 handler
|
2026-10-18 15:38:52 +08:00 |
|
|
|
61a871cf88
|
feat(qq): 在线状态随内核阶段自动切换 + 手动设置工具
## 用户要的两件事
1. 「在不同内核工作阶段自动切换 QQ 状态，比如 toolcall 阶段切忙碌中、
生成文字阶段切思考中」
2. 失败不阻塞、不重试、只写日志（完全非致命错误）
## 取值以 NapCat 源码为准（不是我猜的）
我最初拿 `status=11` 试探，NapCat 返回 retcode=0 **但那是无效状态**
（它不校验）。拉了源码 `SetOnlineStatus.ts` 的 actionDescription 才拿到
权威取值表：
在线 status=10 ext=0 忙碌 status=50 ext=0
离开 status=30 ext=0 请勿打扰 status=70 ext=0
隐身 status=40 ext=0 搬砖中 status=10 ext=2023
学习中 status=10 ext=1018 听歌中 status=10 ext=1028
## 阶段映射
StageBeforeToolcall → 搬砖中（status=10, ext=2023）
StageBeforeOutput → 学习中（status=10, ext=1018）★ QQ 无"思考中"预置项
StageAfterOutput → 在线 （status=10, ext=0）
`after_toolcall` 不切：工具刚结束还要继续，频繁切换只会闪。
## 失败处理（用户明确要求的设计）
三个钩子**永远 return nil**，不重试：
· 不返回 error ⇒ 内核不会因状态失败而中断工具调用或改写回复
· 不重试 ⇒ NapCat 掉线时不会每轮打 HTTP + 打日志
· 失败只在 applyStatus 记日志（首次 + 每 10 次），不刷屏
## 其它
· 默认**关闭**（`status_auto`）：改 QQ 状态对外可见，属于"内核替用户
做决定"，与 offload 同类的显式特权。
· 手动工具两个：`qq_set_status`（预置状态，收中英文名）、
`qq_set_diy_status`（自定义 face_id + wording）。
· 防抖：同状态跳过、最短间隔 2s —— stage 每轮都触发，不防抖会打满 NapCat。
· `Stop()` 里恢复在线：否则停机时停在"搬砖中"，用户看到一个永久错位
且不知道是谁改的状态。★ 恢复判据用**实际应用过什么**（applied），
不能用 status_auto —— 手动工具设的状态在开关关闭时也要能恢复。
## 判据（5 条，变异 2/2 咬）
· 指向必拒绝的地址时三个钩子仍返回 nil（不阻塞）
· 开关关闭时完全不发请求
· 状态名归一化（含中文别名）
· 阶段映射用**权威取值**（忙碌必须是 50，不是 11）
· 未知状态名被拒且不发请求
## 实机验证（生产 NapCat 192.168.2.106:25570）
qq_set_status busy → map[ext_status:0 status:忙碌 status_num:50]
qq_set_status working → map[ext_status:2023 status:搬砖中 status_num:10]
qq_set_status online → map[ext_status:0 status:在线 status_num:10]
qq_set_status 乱写的 → 未知状态名: 乱写的（拒绝，未发请求）
注：`get_status` 只返回 online/good，不回显具体状态 —— 那是该接口的
特性，不是设置失败。
|
2026-10-18 14:34:17 +08:00 |
|
|
|
74e2c654ed
|
feat(sdk): 22 个示例插件配齐 skill + 三态启动声明 + 打包期校验
## 用户的三条要求
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` + `}`。
|
2026-10-18 13:21:47 +08:00 |
|
|
|
e1b458a710
|
fix(commondev): interrupt 的"是否真中断"判定改用 pi 的 isIdle + 真机 e2e
## 找不到的缺陷（变异测出来的）
静态判据全绿、真机也报 interrupted=true —— 但我把 sidecar 里的
`await session.abort()` **删掉**后，判据照样通过。原因：
const hadInflight = inflight > 0;
...
interrupted: hadInflight, // ← 只看"中断前有没有在跑"
任务还在跑 ⇒ inflight 仍 >0 ⇒ 照样回报"已中断"。**那正是最坏的情形：
用户以为停了，任务还在改代码、推分支。**
## 第二版又反向错了
改用"中断前后 inflight 的变化"：
interrupted: before > 0 && inflight < before
实测 before=1 / inflight=1 ⇒ 误报"未中断"，而任务其实已经停了。
原因：inflight 是**包装层**计数，只在后台 promise 的 finally 里递减，
而 abort() 返回时那个 promise 还没收尾。
反向的谎报同样有害：用户以为没停，重复发一遍任务。
## 最终：用 pi 自己的 isIdle
session.isIdle 是 pi 的权威视图（"当前没有在跑的任务"）
interrupted: !wasIdle && session.isIdle
实测应答：{"ok":true,"interrupted":true,"was_idle":false,"now_idle":true}
## 真机 e2e（3 条，HA_PI_E2E / HA_ZCODE_E2E 控制）
· TestRealPiInterruptStopsRunningTask
真 pi 会话跑 60 步任务，12s 后中断 → interrupted=true，且会话仍可用
· TestRealPiSameTaskWithoutInterruptStillRunning ★对照组
同样任务不中断，15s 时仍在跑 ⇒ 证明"已中断"不是"任务碰巧跑完了"
实测不中断时 >100s 仍未完成
· TestRealZcodeInterruptKillsChildAndClearsHandle
假 CLI（持续输出的 node 脚本）→ interrupt 真的 killed_pid，
第二次 interrupt 回 no_running_turn（句柄已清，不误杀下一轮）
## 变异（这次全咬）
删掉 await session.abort() → 咬（now_idle=false 暴露任务仍在跑）
把 interrupted 改回 hadInflight（代码行） → 咬
★ 静态判据里查 hadInflight 时**只查代码行、跳过注释** —— 全文 Contains
会把解释性注释当成缺陷（实测误报一次）。
## 顺带
两份 pi sidecar（工程根 = 单测/SSH e2e 用，rawfile/ = 部署用）必须
逐字一致：既有判据 TestSidecarScriptShipsWithPackage 会比对。
|
2026-10-18 10:52:02 +08:00 |
|
|
|
330c0c9246
|
test(commondev): 守住 rawfile/ 不进库却决定包能否运行的隐患
## 背景
`example/commondev/rawfile/.gitignore` 写着 `*`：rawfile 里是随包资源
（可能是上百兆 node/pi 二进制），进版本库会让克隆变慢、每次升级产生
巨型 diff。**这是设计意图**，不是疏忽。
但代价很具体：
本地打包 → 包里 571 个 runtime 条目（工作区已备好资源）→ 冒烟通过
CI 打包 → 包里 0 个 runtime 条目（干净克隆没有资源） → 插件起不来
而两次构建的**日志都写着"成功"**。这类"本地绿、别处坏"我们吃过一次：
TestHmapdevTemplateImplementsAllPluginMgrMethods 读了 gitignore 的文件，
本地绿、CI 红。
本次尤其危险：interrupt 的实现**同时**落在 sidecar.mjs（已进库）和
rawfile/runtime/*/sidecar.mjs（未进库）两处。只改前者，判据全绿、
包里的 sidecar 却还是旧的 —— 取消能力在发布版里根本不存在。
## 判据做什么
不能要求 rawfile/ 必须有内容（干净克隆本来就没有）。但可以：
· 有内容时，每个 CLI 目录必须有 sidecar.mjs 或 driver.json
· pi/zcode 的 sidecar **必须**支持 interrupt
· 没有内容时，用 t.Logf **大声说明**"此状态下打出的包不含 sidecar"，
让这件事出现在测试输出里，而不是静默
## 变异
删掉 rawfile/runtime/pi/sidecar.mjs 的 interrupt case →
判据报"打包后 commondev_agent_interrupt 会失效（源码改了但资源没同步）"
|
2026-10-18 10:18:40 +08:00 |
|
|
|
28c162cf81
|
feat(commondev): 支持取消正在运行的任务（commondev_agent_interrupt）
## 缺陷（用户实测反馈）
「commondev 无法取消正在运行的 session，agent 反馈它无法取消错误的
pi session，只能等它跑完。」
日志佐证：agent 在 09:07 收到 interrupt 请求后只能如实回答无法取消。
## 根因不是"没实现取消"，而是取消能力从来没被暴露
pi 的 AgentSession **本身就有** abort()（agent-session.d.ts:598，
"Abort current operation and wait for agent to become idle"）。
但 commondev 注册的 30 个工具里一个 cancel/stop 都没有，
sidecar 也只有 ping/prompt/state/close 四个 method。
这是异步投递（2026-10-17）带来的新缺口：改动之前 prompt 是同步的，
调用方阻塞到任务结束，没有"中途要停"这个需求；改成异步投递后，
任务在后台长跑，用户却失去了停止它的手段。
## 改动
**sidecar 三个平台各有各的取消方式：**
pi → session.abort()（协作式中断，必须 await：不 await 会立刻
回"已中断"而实际还在跑 = 谎报成功）
zcode → 整组杀掉当前回合的子进程（没有 abort API）
spawn 时 detached=true 建了独立进程组，killTree 整组杀
**interrupt 语义如实回报：**
interrupted=true 确实有任务在跑并被终止
interrupted=false 当时没有在跑的任务（不算错误）
ok=false + error 该 CLI 没实现 / 调用失败
**三个收尾分支都清 currentChild**（timeout / error / close）：
不清的话 interrupt 会拿到已死的子进程去杀，或更糟 —— 误杀下一轮。
## 判据（4 条 + 「不谎报」）
· pi 的两个 sidecar 都有 interrupt 且用 await session.abort()
· zcode 的 interrupt 真的 killTree 且用 currentChild
· 三个 sidecar 无重复声明（我写的时候真撞了：zcode 已有 currentChild）
· **不谎报成功**：sidecar 没跑 / CLI 没实现时必须 interrupted=false
## 变异验证
pi 删 interrupt case → 咬
pi 去掉 await → 咬（"会谎报已中断"）
zcode 不 killTree → 咬（"只回 ok 不真杀"）
## 顺带
既有判据 TestEveryRegisteredToolHasHandler 立刻抓到我加了 RegisterTool
但没在 handlerFor 映射里登记 —— 它比我先发现漏了接线。
|
2026-10-18 10:17:08 +08:00 |
|
|
|
c9b7a6534c
|
fix(commondev): 完成通知回填投递台账（原先永远停在 accepted）
## 缺陷（2026-10-18 本机实例日志实测）
异步投递上线后，台账里的记录全是 accepted、result 永远为空：
07:39:09 accepted result=None
07:40:09 accepted result=None
07:41:18 accepted result=None ← 13 条全是
而回投本身**是正常的**（[plugin] 日志有 5 次 `回投任务结果…event=prompt_done`）。
缺的是：完成通知到达后没人把它写回台账。
实测后果（同一天日志，agent 自己起的轮询）：
[timer] firing: 【轮询轮次 2/6】…检查是否有新 result 回填…
agent 为此安排了 6 轮 timer 去等一个**永远不会出现**的回填，白等 30 分钟。
更根本的是：看板与任何查询方都拿不到任务结果。
## 修法
`completeDelivery`：把完成/失败结果回填到该 branch 下**最新一条**
未回填的 accepted。`recordDelivery` 改为返回 key（追溯用）。
匹配用"最新未完成"而不是按 key：完成通知里没有 key（sidecar 不知道它），
而同一 branch 的投递是串行投给同一个 pi 会话的，最新未完成那条就是它。
## 判据（6 条）
回填最新 / 不串 branch / 不覆盖已回填 / 无匹配不 panic / 返回 key /
**完成通知真的调用了回填**（接线判据）
## ★ 写判据时踩的两个坑（都记在注释里）
1. **判据没覆盖接线 → 变异不咬**：前 5 条测的是 completeDelivery 自身行为。
把 sidecar.go 里**那一行调用删掉**，它们依然全绿 —— 而"函数写得对但
没人调"正是原始缺陷的形态。补了第 6 条读源码验接线。
2. **偏移错位导致假绿**：分段用 `seg := block[k:]` 后找 "case "，会命中
k 自己（n=0）⇒ seg 不截断、含整个函数剩余部分 ⇒ done 分支删掉回填也照样
"找到" error 分支那一行。改成跳过 `case "x":` 本身的长度再找。
|
2026-10-18 07:53:45 +08:00 |
|
|
|
4387e12ca8
|
fix(commondev): 投递任务改成真异步，不再同步等 pi 跑完
## 缺陷（用户质疑"投递不就是发一条消息"后实测确认）
`deliverToPi` 的注释写着"把给 pi 发消息包装一下"，但实际是：
await s.prompt(text) // 同步等 pi 把**整个任务**跑完
而 pi/zcode 开工程线干活（克隆/改代码/跑测试）要几十秒到 20 分钟。
生产日志实测两次：
23:04:03 executing tool: output_send__commondev_br-...
23:05:03 ★ timed out after 60s
通道的语义是"**投递**任务"（见 outputch 描述），不是"等完成"。
把它实现成同步等待，就必然撞上内核的 60s 工具超时。
★ 我一开始的诊断是错的：以为"超时值太小"，给 output_send 声明了 3m
—— 那是掩盖症状。投递本该瞬时返回，慢是 bug 不是需求。已撤回。
## 改动
投递 → 立即回 status=accepted（瞬时）
→ pi 在后台跑
→ 跑完推**主动通知**（id=0）
→ Go 侧 onNotify 经 inputch 注入回 agent
`sidecar.go` 的 readLoop 里早就留好了这个扩展位：
if resp.ID == 0 { // 主动通知（暂未使用，保留扩展位）
现在接上了 `makePromptNotifier`。
pi 与 zcode 两份 sidecar.mjs 都改了（rawfile/ 里那两份同步更新）。
## 判据抓到我三次（都是真问题）
1. `TestSidecarScriptShipsWithPackage`：rawfile/ 与工程根不一致
—— 我只改了根那份
2. `TestZcodeMissingCLIErrorIsActionable`：`inflight is not defined`
—— zcode 版用了未声明变量
3. 同一条判据随后**卡死 2 分钟**：CLI 不存在本该立刻报，异步后错误
被吞进后台通知 ⇒ 用户先收到"已受理"、几秒后才知道配置错。
改成**受理阶段就校验 CLI**（配置错是立刻可判定的，不该推迟）。
判据还逼我保住语义：原 `TestZcodeSidecarArgvBehavior` 断言首轮拿到
真实 `sess_` id，异步后要到完成通知里才有 —— 断言保留、改从通知取，
没有削弱。
## 真机 e2e（三条全过，都要求真改工程文件）
TestZcodeFullPipeline 42.1s
TestZcodeOverSSH 72.4s
TestZcodeOverSSHWithPerHostEndpoints 75.1s
受理现在是瞬时的 ⇒ 内核工具不会再 60s 超时。
|
2026-10-18 06:39:24 +08:00 |
|
|
|
81a3efa4df
|
feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象（pi/zcode） (#3)
* feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象（pi/zcode）
## 是什么
agent 统筹开发流程的插件：登记项目 → 开工程线（每条线一个隔离工作目录 +
一个 sidecar 子进程 + 一对通道）→ 投递任务 → 同会话续投 → 评审/合入。
38 个工具：project_*/branch_*/workdir_*/job_*/review_*/test_*/
endpoint_*/agent_*/pi_*/conflict_check。
## sidecar 后端抽象（本轮核心）
传输层（local/ssh）与后端（pi/zcode/自定义）**正交**，四个自由组合：
driver.json 描述一个后端：script / cliPath / env / args / llmConfig
三级查找：插件数据目录 → **随包 rawfile** → 内置 pi 描述
占位符：{workdir} {dataDir} {pluginDir} {rawfile} {sessionId}
★ 内置 pi 回退**与默认后端解耦**（2026-10-17 修）：原实现写
`if cli == defaultAgentCLI { return builtinPiDriver() }`，把"给谁兜底"
和"默认选谁"耦合到同一常量 —— 一旦有人改默认，pi 当场失去兜底，
显式 cli="pi" 开始报「驱动不存在」。现在判断字面 "pi"。
默认后端保持 **pi**（我们本地主用）；交付方用 zcode 走两种局部开关：
· 单线：commondev_branch_open(cli="zcode")
· 按机器：commondev_endpoint_set(host=..., cli="zcode")
## zcode 接入（三条真机判据，全部要求真改工程文件）
· TestZcodeFullPipeline（29-34s）：随包 driver + 真实 ZCode CLI
· TestZcodeOverSSH（39s）：真 ssh + scp，远端 node 跑 zcode
· TestZcodeOverSSHWithPerHostEndpoints（68s）：两个 host 别名配不同
cli_path，走端点表而不是全局 settings
★ 会话库必须隔离到工作区（sidecar.mjs 的 ensureWorkspaceSessionStore）：
实测 ZCode 的会话库路径**硬编码 homedir()**，`ZCODE_DATA_BASE_DIR` 对它
完全无效（26 个会话全落全局库）。但 `<workdir>/.zcode/config.json` 的
`storage.sessionDbPath` **确实生效**。所以启动前写一份工作区配置，
一举解决：多线不共用历史 / 不污染全局 ~/.zcode / 删线不留孤儿会话。
只在不存在时写 —— 用户手工放的要尊重。
## 其他
· rawfile：项目根 rawfile/ 默认全收，解到 <插件目录>/rawfile/，绝对路径拒绝
· 凭证：命名引用 + ${ENV_VAR}，独立 0600 文件，绝不进 config.db(0644)
· secretshell：给不受信 agent 用的安全 shell（ackey + safeshell）
· 冲突检查 / 评审判据 / 镜像 / 每条线独立 workdir（hash 命名，合并后删除）
判据 30+ 条，含 4 条「判据本身的判据」（防止判据假绿）。
* fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
## 核心缺陷：插件往 stdout 打日志 = 污染 JSON-RPC 协议通道
子进程插件与内核用 stdout 传 NDJSON 帧，stderr 才是日志通道。
脚手架模板（及 4 个示例插件）用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本：
[proc] weather 收到非法 JSON 帧（21 字节）: invalid character 'i'
**生产实测 1038 条**（huawei_smarthome 720 / weather 113 / rss 103 / calendar 102）。
后果不只是日志噪音：那一行日志被**丢弃**，插件看起来"没启动"。
修法：
- hmapdev 模板 `fmt.Printf` → `log.Printf`（9 处）
- 示例插件 4 个 14 处：ai_image(2) calendar(5) rss(4) weather(3)
+ 补 "log" import
- 内核侧（主仓）同步让报错可定位：内容摘要 + 可能原因 + 修法
判别法：`package main` = 子进程（协议通道，禁用 stdout 打日志）；
普通库包 = 进程内插件（编译进内核，写真实终端，**不是**缺陷）——
`internal/plugins/cli` 的 `fmt.Println` 属后者。
## hmapdev
- `cmd_build.go` +136：平台产物精确匹配（`--target` 是**append** 语义，
原脚本 `ls dist/*.hmap | head -1` 会按字典序抓到 amd64，
**导致 arm64 包里装的是 x86-64 二进制**，且退出码 0、校验和通过）
- `cmd_init.go` +46：脚手架 stdio 纪律
- `templates/proc_main.go.tmpl`：补齐 mgrStop/mgrStart/mgrIsRuntimeStopped
三态能力（插件管理器运行态停启）
- `templates/plg.json.tmpl` 删除（合并进 cmd_init）
## 判据
- `scaffold_stdout_test.go`（3 条）：扫模板生成的代码不得写 stdout。
★ 判据自身先假红过一次：**模板的注释里就写了 `fmt.Printf`** ⇒
必须 `stripTemplateComments()` 之后才判
- `example_stdout_test.go`（2 条）：扫全部 20 个子进程示例插件，
报错给**文件:行号**；变异咬住并给出准确行号
- `package_examples_test.go`（2 条）：**执行真实打包脚本**
（第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬）
- `cmd_build` / `cmd_init` 新判据
## 其他
- sdk/settings.go +15（三态能力透传）
- `docs/versions.md` +§示例插件协议通道纪律（含生产 1038 条实测表格）
- `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律（正误代码对比）
* fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定（修 CI 红）
CI 上 `Examples (linux/amd64)` 与 `(darwin/arm64)` 双红，只有两个失败：
✗ commondev 构建失败
✗ editdoc 构建失败
error: 项目声明 sdk=1.4.0，但本地 SDK 存储里没有这个版本
其余 20 个示例全部成功 —— 说明不是通用问题，而是这两个被改坏了。
## 根因（两个叠加）
**① go.mod 被本机绝对路径污染**
我在上一个提交里用 `git add -A`，把本机 `go build` **自动改写**过的
go.mod 一并提交了：
require github.com/JianFeeeee/homeagentsdk v1.4.0
replace github.com/JianFeeeee/homeagentsdk => /root/.homeagent/hmapdev/sdk/v1.4.0
基线（origin/main）是：
require github.com/JianFeeeee/homeagentsdk v0.0.0
replace github.com/JianFeeeee/homeagentsdk => ../../
本机那个目录真的存在 ⇒ 本地全绿；CI 没有 ⇒ 必红。
**② plg.json 声明了 `"sdk": "1.4.0"`**
一声明版本，hmapdev 就去**本地 SDK store** 找它，找不到直接拒绝构建。
全仓 20+ 示例**都不声明**，只有我改过的这两个声明了。
示例的正确依赖表达是 go.mod 的 `v0.0.0` + `replace ../../`。
## 修法
两个文件都恢复到与其余示例一致的写法。
## 判据（3 条，都是新加的）
· `TestExampleGoModHasNoAbsoluteReplace`：任何示例 go.mod 不得含
`/root/`、`/home/`、`/Users/`、`C:\`
· `TestExampleGoModUsesRelativeSDKReplace`：replace 必须是相对路径 `../../`
· `TestExamplePlgJsonDoesNotPinSDKVersion`：plg.json 不得声明 sdk
变异 2/2 咬住（重新引入绝对路径 / 重新声明 sdk，都准确报出文件路径）。
## 本地验证（模拟 CI 干净环境）
用干净 HOME 跑 `package/build-examples.sh`：
· 修复前：成功 18 / 失败 4（commondev, editdoc, browser, rss）
· 修复后：成功 20 / 失败 2（browser, rss —— **本机代理不通**，
`proxy.golang.org` 超时；用本地 modcache 验证这两个可正常构建）
即 22/22 源码都能构建，CI 有网络不受影响。
## 教训
`git add -A` 会把「构建工具自动改写的文件」一起提交。
提交前必须 `git status` 逐个看，尤其 go.mod / go.sum。
---------
Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
|
2026-10-17 19:44:15 +08:00 |
|
|
|
65d2bd9e61
|
fix(qq): NapCat 确认超时提示「不要盲目重发」，版本 1.4.2 → 1.4.3
生产实测（2026-10-13）：一次回复发出 4 条相同消息，日志中 3 次
output_send__qq 的调用 id 各不相同 —— 是模型看到「发送失败」后自己重试。
根因（在 NapCat 运行代码 /app/napcat/napcat.mjs 中确认）：
sendMsg 把消息交给 QQ 内核后，等 onMsgInfoListUpdate 事件匹配
guildId + KSEND_STATUS_SUCCESS，内部固定等待 10s（附件更长）。
主机 IO 饱和（iowait 94–96%）时主线程被 10–30s 长任务阻塞，回调排不上队，
于是 NapCat 抛 "Timeout: NTEvent ... sendMsg" → 非零 retcode（实测 200）。
但消息**已被 QQ 送达**：同一窗口内确有 16 条「发送 -> 私聊」成功记录。
这与已修的 HTTP 客户端超时是两条不同路径：
- HTTP 超时：client.Post 返回 err（bd26c2a 已告警）
- NapCat 超时：HTTP 200 + 响应体带 NTEvent 字样（本次补）
只报「失败」不说「可能已送出」，模型必重发。
改动：
- napcat() 对发送类动作（napcatSendActions）的 NTEvent 超时包装
errNapcatTimeout，并附「很可能已送出、不要盲目重发」的告警；
查询类动作保持普通失败（可安全重试）。
- 不按 retcode 判定：该超时来自 callNormalEventV2 的普通 Error，
retcode 本身不携带「超时」语义。
- 不以 serviceAndMethod == sendMsg 为条件：调用方已限定发送动作，
该收紧既无生产证据支持，又会把同类超时退回普通失败重新诱发重发。
测试（全部穿过 napcat() 真实调用链）：
- TestNapcatSendTimeoutWarnsAgainstBlindResend（生产原文 retcode=200）
- TestNapcatQueryTimeoutIsNotSendTimeout
- TestNapcatSendActionTimeoutRegardlessOfServiceName
变异验证（3 项，均按预期失败后退回）：
① 删告警分支 → 发送用例失败 ② 加回 sendMsg 限定 → 不限服务名用例失败
③ 去掉发送动作门禁 → 查询用例失败
|
2026-10-13 12:52:55 +08:00 |
|
|
|
b73a95bb31
|
chore(qq): 版本 1.4.1 → 1.4.2（长超时客户端 + OneBot retcode 校验）
对应插件侧修复 bd26c2a：发送类端点用 120s 超时客户端并校验 OneBot
retcode/status，消除「消息其实已送达、却报发送失败」进而导致模型重复发送。
|
2026-10-13 10:22:34 +08:00 |
|
|
|
bd26c2a402
|
fix(qq): 发送类端点用长超时客户端 + 校验 OneBot retcode，消除「已发出却报失败」
## 真实故障（2026-10-13，生产日志实证）
从 `<data>/log/week_2026-W41.tar.gz` 解出的历史日志 + `memory/context.json`
拿到完整错误文本：
napcat send_private_msg: Post "http://192.168.2.106:25570/send_private_msg":
context deadline exceeded (Client.Timeout exceeded while awaiting headers)
对应日志时序（~30s 恰好撞上客户端超时）：
17:50:07 executing tool: output_send__qq
17:50:47 result: 通过 [qq] 通道发送失败: ... Post "...": ... ← 40s
21:47:15 → 21:47:47 ← 32s
08:17:39 → 08:18:09 ← 30s
**消息其实发出去了**，证据有二：
① agent 自己在上下文里总结（memory/context.json 原文）：
「其余几次 send 是 napcat 的 25570 接口超时重试，用户只收到一份，不会刷屏」
「napcat 这会儿接口有点不稳（好几次 context deadline exceeded），
不过关键的那一发是成功的」
② 同一内容重试后用户只收到一份 —— 那是 qq 循环保险拦住的，属侥幸而非正确行为。
根因：`httpClient.Timeout = 30s` 被**查询与发送共用**。而 QQ 发送要经
NapCat 的 `NodeIKernelMsgService/sendMsg`，慢时响应头 30s 回不来 ⇒
把已送达的消息报成失败 ⇒ 模型重试。
## 另一个独立缺陷：不校验 OneBot retcode
`napcat()` 原来只看 HTTP 通不通、JSON 能不能解，**从不看响应体里的
成败字段**。而 OneBot v11 的成败在 body 里：
成功 {"status":"ok","retcode":0,"data":{"message_id":...}}
失败 {"status":"failed","retcode":100,"message":"..."}
或 {"data":null,"message":"Timeout: NTEvent ...sendMsg","status":"failed"}
历史日志里实测到 NapCat 返回 `data:null` + `sendMsg Timeout`（真失败）
却被当作发送成功。两个方向都错，必须靠 retcode 判定。
## 改动
- 新增 `sendClient`（120s + Transport 显式配 `IdleConnTimeout`/`ResponseHeaderTimeout`）。
发送类端点（send_private_msg / send_group_msg / send_msg）走它；查询类
保持 30s（幂等，快速失败更利于排查）。
- `Transport.IdleConnTimeout=30s`：默认 Transport 的空闲连接无上限等待，
复用对端已单向关闭的 keep-alive 连接会得到"请求已写入/对端已处理，
本地读响应 EOF"——又一种「已发送却报失败」。
- `napcat()` 校验 OneBot `retcode`/`status`，失败转 error。
- 超时单独包 `errNapcatTimeout`，错误文案明写「**可能已送达并已发出，
不要盲目重发**」——只说"失败"会诱发模型重发 → 重复消息。
## 判据（4 条，两条经变异测试修正）
- `TestOneBotError_FailedResponses`：7 组 retcode/status 组合的判定
- `TestNapcatConvertsOneBotFailureToError`：**端到端**——napcat() 必须把
OneBot 失败转 error。★ 变异（删掉 napcat() 里的 oneBotError 调用）
实测发现：只测 oneBotError 的判据照样全绿（判据没穿过调用链）
⇒ 补这条才咬住。
- `TestNapcatSendUsesSendClient`：**真的验证路由**（用 Transport 重写 host
观测哪个 client 实际发了请求）。★ 变异（删掉路由分支）实测发现：
只断言两个 client 的 Timeout 字段值照样全绿 ⇒ 重写为观测实际请求。
- `TestNapcatTimeoutErrorIsActionable`：超时错误必须含「可能已送达」
与「不要盲目重发」
27 条判据全绿（含既有 23 条）。
|
2026-10-13 08:02:45 +08:00 |
|
|
|
777c3a0ad3
|
fix(proc,qq)!: shm 模板 v2 —— fExtraBag 透传插件自建 Extra 键；qq 身份可序列化绑帧
内核 shm 桥 v2 前（见主仓同步提交）只透传 4 个具名 Extra 键，插件自建键
（qq 的 qq_auth 绑帧身份）在 stage 之间静默丢失 → before_toolcall 永远回落
可变全局身份 → 权限门绑帧在 proc 插件下整体失效（owner 被误拒/非 owner
可能被误放，2026-10-12 生产实证）。
模板（proc_main.go.tmpl）：
- shmStageFieldCount 18→19、shmVersion 1→2（与内核镜像同步）
- fExtraBag：具名 4 键之外的自建键整体 JSON 装袋，read/snapshot/dirty 全链接入
- ReadInto：bag 先打平、具名键后覆盖（具名键永远赢，防御袋污染）
qq 插件：
- qqAuthContext 字段导出 + json tag：非导出字段过 JSON 桥会静默丢空
（原根因链一环）
- authOnFrame 双形态：值形态（进程内/单测）+ map 形态（proc 桥往返，
数字 float64）；半截身份拒绝 —— 宁回落全局也不猜（owner 误判即提权）
- authFromMap 按 json tag 重建，逐字段校验类型
判据（plugin_test.go）：往返无损/降权保持/半截拒绝（逐键）/帧身份优先于
全局（含 owner 被误拒的原始故障场景反向）。变异 Q1-Q4 全杀。
|
2026-10-12 08:28:41 +08:00 |
|
|
|
0b497f4876
|
fix(browser)!: 升级 chromedp v0.9.5→v0.20.1，修视口截图必挂 (#1)
用户报告截图不对（此前已改为落盘返回路径）。查下去发现**两个叠加的问题**，
其中一个是既有的、与上次改动无关的严重缺陷。
## ① 协议解析失败：chromedp v0.9.5 不认 Chrome 154
```
ERROR: could not unmarshal event: parse error: expected string near offset 411 of 'cookiePart...'
```
cdproto 把 `partitionKey` 定义为 `string`，而 Chrome 154 已改成对象
（`cookiePartitionKey`）。新版 cdproto 定义了 `CookiePartitionKey` 结构体，
且 `UnmarshalJSON` **双向兼容**（字符串 → 结构体，旧浏览器也不坏）。
副作用：`Navigate` 从 2.5s 降到 85ms（解析错误消失，不再反复重试）。
## ② 视口截图在 headless 下**永远挂住**（既有缺陷，不是升级引入）
`Screenshot(sel)` 内部是 `QueryAfter` + `NodeVisible`，而 NodeVisible 在
headless Chromium 上永远不满足 —— 两步单独看都成功，但它一直等下去：
```
Do(Query body) ✓ Do(WaitReady body) ✓
Do(WaitVisible body) ✗挂住 Do(WaitVisible html) ✗挂住
Run(Screenshot html) ✗挂住 Run(FullScreenshot) ✓
Run(CaptureScreenshot) ✓（70KB）
```
**决定性对照：旧版 chromedp v0.9.5 在同一个后端上同样挂。**
所以这不是升级引入的。生产日志也佐证：
- 成功的 8 次 —— agent 都传了 `full:true`（走 FullScreenshot）
- 超时的 5 次 —— 都是默认分支（走 Screenshot("body")）
且 `NodeVisible` 的两步实测都正常（`dom.GetBoxModel` 300µs 成功、
`visibleJS` 返回 true / offsetWidth=480），就是等待机制本身不返回。
没有深挖到 chromedp 内部的根因，但**换用 `CaptureScreenshot` 完全绕开这条链**，
且语义更对：「不传 full 就只截当前视口」本来就是 API 文档的含义。
## 迁移方式：兼容层收敛，业务代码最小改动
v0.20 是**泛型重写**（`Action[T]` 返回值而不填指针），25 处调用点受影响。
新增 `chromedp_compat.go` 把新 API 收敛成几个小助手
（`chromedpDo` / `newRemoteAllocator` / `chromedpCaptureScreenshot` …），
业务代码保持旧写法。
为何不逐处改：20+ 处机械改写会把 diff 淹没，真正要审的
「行为变了没有」反而看不清。
`NewRemoteAllocator` 在 v0.20 移到了独立子模块 `remote`（核心模块现在
只用标准库 + cdproto，需要 websocket 的东西全部搬出去）。
## 顺带修掉 go.mod 的重复 replace
`go mod tidy` 清掉了 4 条重复的 `replace ... => ../../`（hmapdev 往已有
go.mod 追加却不去重导致的）。Go 容忍它，但 `go mod tidy` 会报错。
## 判据（可杀变异，实测）
`chromedp_compat_test.go`：
- 视口截图必须走 `CaptureScreenshot`，不得退回 `Screenshot(sel)`
（改回挂住的写法 → FAIL ×2）
- 兼容层关键助手都在（去掉 CaptureScreenshot → build FAIL）
- 无旧式「传指针接收截图」残留
全部 20 个 example `go vet` 通过；SDK 根 module build/test 通过。
生产实测：agent 做视口截图返回
`/home/newqqagent/browser_screenshots/shot-20261011-104225.610-browser_1.png`
（1280×713 PNG / 70518 字节），不再超时。
Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
|
2026-10-11 10:45:41 +08:00 |
|
|
|
25bd243662
|
fix(browser)!: 截图落盘返回路径，不再回 base64
用户报告：截图直接返回二进制（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 模式构建通过。
|
2026-10-10 23:26:19 +08:00 |
|
|
|
b6a6168e65
|
chore(module)!: module 路径随托管地迁移 gitcode → github
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 产物
|
2026-10-09 07:25:25 +08:00 |
|
|
|
e417c69fc8
|
fix(example/bili): 进程组隔离 + 可取消的下载 —— 修拖死内核关停
## 现象
线上关停必超时：systemd 报 `State 'stop-sigterm' timed out. Killing.`，
其中只有 bili 报 `[proc] bili SIGKILL 后 2s 仍未被收割`，之后近 90 秒无日志。
## 根因
本插件用 `exec.Command("yt-dlp", ...)` + `cmd.Run()`：
- 无 CommandContext ⇒ Stop 无法取消
- 无 Setpgid ⇒ yt-dlp 与本插件同进程组
- Stop() 是 `return nil` ⇒ 内核 Kill 插件本体时，yt-dlp 变孤儿
yt-dlp 还会再 fork ffmpeg，**孙进程继承本插件的 stdout 管道写端**。
插件被 SIGKILL 后孙进程仍持有写端 ⇒ 内核 readLoop 永远等不到 EOF
⇒ `Kill()` 末尾的 readerWG.Wait 永不返回 ⇒ 整个关停挂死。
## 改法
1. 两处 `exec.Command` → `exec.CommandContext`，Stop 里 cancel 能掐掉
2. `setPgid` 让命令自成进程组：yt-dlp 拉起的 ffmpeg 也在组内，
kill(-pgid) 能一次带走整棵子进程树，不留孤儿
3. `Stop()` 不再是空实现：cancel 之后**必须 wait**。
只 cancel 不 wait 的话内核会先释放共享段，而 yt-dlp 还在写 stdout ——
那正是内核 readLoop 挂死的成因。`runWG` 等它真正退出。
顺带：取消时返回明确文案（"已取消（插件停止）"）而不是含糊的 exec 错误。
内核侧的三处修法（Setpgid / 杀进程组 / readerWG 超时）在主仓 ceeef0b，
对所有 8 个同样 exec.Command 且无进程组隔离的插件都有效。
验证：hmapdev build 通过；主仓部署后实测关停 90s → 1s、
`[homed] stopped` 打出、孙进程无残留。
|
2026-09-26 17:08:34 +08:00 |
|
|
|
7717bf5ca5
|
feat(sdk): RecallPolicy —— 声明工具输出是否触发记忆召回
与 ContextPolicy **正交**，但默认值刻意相反：
| | 管什么 | 默认 |
|---|---|---|
| ContextPolicy | **裁剪**：把低相关 L0 事件归档 | 关（剪裁是破坏性的，须显式声明） |
| RecallPolicy | **召回**：把 L2/L3 相关记忆注入本轮 | 输入/注入 `auto`，**工具 `none`** |
工具默认 none 的理由：多数工具输出是噪声，据它召回会把无关记忆拉进来
（源码注释原文）。需要「取回真实内容后据它召回」的工具才显式声明 auto。
## qq 的落地（本改动想解决的具体问题）
qq 通道到达的是**中断通知（meta）**而不是用户正文。原先用这条 meta 文本
去触发召回 —— 那是无关词，召不回真正相关的东西。改为：
- 通道声明 `RecallPolicy: none`（meta 不该据它召回）
- `qq_get_message` 声明 `auto`：消息正文取回后**由正文**触发召回
- `qq_get_history` 同样 `auto` + `prune`：拉回的历史消息既用完即裁、
又据正文召回（否则有「记忆里有、但拉历史时不注入」的盲区）
注：本实现已先随主仓 vendored 副本进入 main（两份经 diff 校验字节一致，
0 行差异），此处是把 SDK 仓自身补齐，使两仓 HEAD 对齐。
|
2026-09-20 09:15:34 +08:00 |
|
|
|
7ef9bc2ad3
|
docs(example): 为每个插件补 README
此前 example/ 下 21 个插件里，13 个完全没有 README，另 4 个是
`hmapdev init` 生成的脚手架样板（`# <name>` + `plugin build` + `Install` 三行，
等于从没被写过）。只有 deepsearch / vikunja / plugindev / luademo 是真实文档。
本次为 **17 个**插件写了真文档（13 个缺失 + 4 个样板），现在 21 个全部有内容。
## 写法
每个 README 覆盖：能力一句话 → 为什么需要 → 工具表 → 配置项表 →
通道与钩子（有才写）→ 构建 → 已知边界。
**事实全部从源码读出来，不推测**：
- 工具名核对到注册点（含 `tp+"x"` / `p.name+"_x"` 前缀拼接，展开成最终名）
- 配置键与默认值取自 `RegisterDef` / getStr 默认值
- 通道名、钩子名、依赖命令逐条 grep 确认
- 版本号与已部署实例交叉核对，17 个里 16 个一致
## 几处按源码写、与直觉不同的点
- **rss**：订阅时会把抓到的历史条目一次性标为 seen，所以订阅一个源
**不会**把历史文章全推一遍 —— 这是避免刷屏的关键，写进了文档。
- **files**：路径校验是**两道**（规范化后判断 + 解析符号链接后再判断），
只做前者的话沙箱里的软链接就能逃逸。两种情况报错文案不同。
- **qq**：身份必须**绑帧**而非存插件全局，源码注释记录了由此产生的两个真实故障
（中断抢占恢复后权限门整体失效、运行中到达的消息改写正在跑那一轮的身份）。
多来源合并时权限取**交集**。硬私有工具按前缀一律拒绝。这些是安全关键，
单独成节写清楚。
- **memo**：待办与备忘录**刻意分两类**（一提醒一不提醒），提醒注入带 NoMemory。
- **sanitizer**：不注册任何工具，只挂三个阶段钩子；依赖 ABI v2 的 stage 写回能力。
- **editdoc**：本目录是 v1.0.0（单工具），而线上跑 v2.0.0（全能版，源码未公开）——
在文档开头显式标注，**不按 v2 描述**，避免读者以为这里就是线上那份。
## 验证
- 21/21 文件非空且非样板（最小 913B，最大 6845B）
- 逐个核对 README 中出现的工具名能在源码找到依据；5 处报警经复核**全是误报**
（`ai_image_generate`/`music_*` 前缀来自 metadata 的 name，`on_input` 等是钩子不是工具）
- README 版本号 vs 线上 plugin.json：16/17 一致，editdoc 的差异已显式说明
注：本仓既有未提交改动（example/qq/plugin.go、sdk/plugin.go）**未纳入本次提交**。
|
2026-09-20 00:43:06 +08:00 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
81bfdfce1d
|
fix(examples): a2a/acp 回复闭环 + 会话延续 + 同步注入
入站请求从 InjectInterruptText(202 submitted) 改为 InjectInputSync
同步等待回复，直接返回回复文本；支持 params.session_id 延续多轮
上下文；注册为输出通道让回复有落点。详见 TrueAgent 仓库同名 commit。
|
2026-08-26 19:16:49 +08:00 |
|
|
|
e3f93e254b
|
chore(recoverydiag): 补齐 go.mod 与 main.go（与其他插件结构一致）
|
2026-08-26 17:05:24 +08:00 |
|
|
|
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 |
|
