jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-20 08:58:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
73 Commits 5 Branches 10 Tags
219b11a1f9952042f3812a8cc6d15e2e8e73a59c
Commit Graph

15 Commits

Author SHA1 Message Date
JianFeeeee
ce5bff9275 feat(sdk): 多模态贯通插件边界——媒体字段、媒体注入接口与并发修复 
记忆系统在核心 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
插件把 Triple / Doc 交进来，媒体一律无处安放，且**不报错**。本版补上公开接口
侧缺失的表达能力。

## 一、类型与接口（全部新增，无签名变更）

- `Triple` += `SentenceText`、`MediaDigests`
- `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment`
- `TextEvent` += `Attachments`
- `DocMemoryAPI` += `InsertWithMedia`
- `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia`
- `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有，
  插件只能自己去拿 injector）

`MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（内核按字节
去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索
可能命中几十份媒体，把字节全塞回来会撑爆跨进程消息。

媒体注入为什么不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用，
且媒体要等**下一条** tool message 才到模型手上。插件主动发起一轮带媒体的对话、
以及中断注入，需要各自的签名，且媒体在**本轮**就随消息发出。

`Triple.MediaDigests` 非空而 `SentenceText` 为空时，内核会用媒体标记本身充当句子
——媒体引用挂在句子上，没有句子就无处挂起。插件只需填 digest，标记由内核拼：
要求调用方知道格式，等于让一个拼写错误静默切断引用绑定而全链路无人报错。

## 二、修掉两处并发竞态

`sdk/stress_test.go` 的 `-race` 实测报 11 处 DATA RACE，收敛到两个字段：

1. **`PluginSDK` 的 API 字段无锁**。写方是内核（加载/重载插件时依次注入
   injector、memory、doc、llm…），读方是插件在 `Start()` 里起的后台 goroutine
   ——轮询、监听、定时器都要拿 injector 往管道注消息。生产表现是插件重载瞬间
   偶发崩溃：读到半个接口值就 nil 解引用。
2. **`autoRestart` 标志无锁**。`SetAutoRestart` 的文档用法本身就是「外部连接建好
   后再决定能否自动重启」，而连接建立通常在后台 goroutine；内核 registry 在另一个
   goroutine 读 `AutoRestart()` 决定崩溃后重启策略。这对读写天然跨 goroutine。

加 `apiMu sync.RWMutex`。关键约定写进注释：**只在持锁期间取字段值，取完立刻
释放再调用**。持锁调用会把 `InjectInputSync`（阻塞到 agent 回复，可达数分钟）
与 `SetIOInjector` 串到一起，让插件重载卡死。

## 三、压测（sdk/stress_test.go，13 例）

SDK 是被多个 goroutine 同时使用的共享对象，单线程单测全绿不代表并发路径成立。
断言的是不变量而非吞吐：

- 媒体注入高并发不丢不串——每次调用带唯一 tag，逐条校验文本与图片 URL 配对。
  「不串」是重点：若实现里出现任何共享中间状态（把 blocks 暂存到字段再读出），
  高并发下会出现 A 的文本配 B 的图，而两者单独看都「成功」了；
- injector 热替换（含替换成 nil，即内核卸载 API 的真实状态）；
- stop / onRemove handler 恰好一次——契约是「执行后清空，幂等」，执行两次的后果
  从重复写文件到 close 已关闭 channel 直接 panic；
- `StageContext` 并发读改写无 lost update（媒体链路让 Extra 成为新热点，
  而 map 并发写在 Go 里是直接 fatal，recover 接不住）；
- `OwnTools` scope 不跨插件泄漏；
- 媒体类型 JSON 往返字节级一致（9 种长度，含 0/1/2/3 与 base64 分组边界）
  ——`[]byte` 在 JSON 里是 base64，往返不一致意味着图片静默损坏，
  要到 CAS 校验 digest 时才发现，那时已无从追查；
- `omitempty` 真的生效（读路径不能出现 `"data"` 键）；
- nil 依赖全部静默降级不 panic。

## 四、工具链同步

- `proc_main.go.tmpl`：`procIO` 三个媒体方法、`procDocMemory.InsertWithMedia`。
  模板不跟上的后果是**每个外部插件都编不过**（接口未实现），是硬失败；
- `proc_runtime_test.go`：方法清单补 `io.injectMedia*` 与 `doc.insertWithMedia`。
  漏接线时插件调 `InjectInputMedia` 会静默无效果——模板不发这个 RPC，内核也就
  收不到，两边都不报错；
- `yaegi/mocksdk`：与公开 SDK 对齐。它此前漂移严重且**没有任何代码对着它编译**，
  所以漂移不会被编译器抓到：`Triple` 用的是 `Predicate`，而公开 SDK 一直叫
  `Relation` —— 插件在 yaegi 调试期写 `Relation:` 报未知字段，写 `Predicate:` 则
  编成 plugin.bin 时报错，两边都不对。
- README 中英双语补媒体接口文档与用法示例。

## 兼容性

存量插件不需要改一行也不需要重编：新增方法由**插件调用、内核实现**，不调就不
受影响。17 个 example 插件源码零改动通过类型检查；用 SDK 0.9.2 编的旧 plugin.bin
在新内核上直接建链通过（握手校验的是 ProtocolVersion=1，不是 SDK 版本）。

媒体接口需要核心 1.1.1+（更早的核心没有对应 RPC，调用返回 unknown method）。
`CoreVersion` 保持 1.0.0：它是「SDK 能在其上运行」的下限，媒体是可选能力。
 2026-09-06 10:03:36 +08:00
JianFeeeee
e256023399 docs+plugindev: README 同步子进程架构，scaffold 修 entry 与 go.sum 死路 
三类问题，都会让新用户第一次上手就走错：

1. README 仍写 plugin.so
   plugin.json 示例的 entry、entry 字段说明、.hmap 包格式三处描述的都是
   已退场的 C ABI 产物。改为 plugin.bin，并补 bundle 模式下
   plugin.bin.<goos>.<goarch> 的命名与安装时挑平台的行为。

2. cmd_init.go 的 entry := "plugin.so"
   scaffold 出来的 plg.json 带着一个已退场的 entry 值。build 实际不看这个
   值（只用它区分 Lua），但跟着模板走会误以为自己在做 C ABI 插件。

3. 生成的项目第一次 build 必定失败
   go.mod 只 require 一个 gitcode 模块版本号且不生成 go.sum。gitcode 不在
   proxy.golang.org 上，于是：
     go build     → missing go.sum entry
     go mod tidy  → 去公共 proxy 拉一个不存在的条目，超时
   原来 cmdBuild 里那句 `go mod download <mod>` 走的正是这条死路，失败后
   只打一行 warn 就继续编译，紧接着死在同一个错误上——用户看到两段无关报错。

   修法分两处：
   - 生成的 go.mod 直接写指向本机 SDK 的 replace（replace 到目录时 go 不
     需要也不校验 go.sum）
   - 新增 ensureSDKResolvable：三级策略（已有本地 replace → 探测本机 SDK
     并写入 → 兜底 go mod tidy 带 -mod=mod，失败给可操作提示）。存量项目
     go.mod 无 replace 时走第二级救回。

bin/ 5 个预编译二进制不再进仓库（改为 release 附件）：
5 个平台各 26-28MB，每次重编都在 git 历史里再叠一份，而它们本质是可从源码
复现的产物。README 的下载说明同步改为 release 附件 URL + 从源码编译。
 2026-09-03 19:27:03 +08:00
JianFeeeee
fc876c5554 feat: 单插件重载等 PluginMgr 能力导出到外部 SDK 
- meta: CORE_PLUGIN_RELOAD_ONE(48) / LIST_LOADED(49) / IS_DISABLED(50)
- sdk: PluginMgrAPI 接口(ReloadOne/ListLoadedPlugins/IsPluginDisabled) +
  PluginSDK.SetPluginMgrAPI/PluginMgr() 访问器
- plugindev 模板: dispatchPluginMgr 桥接注入,走 C ABI 48/49/50
 2026-08-23 19:47:55 +08:00
root
f3d87ec35f docs: 生命周期文档补全 onRemove（删除清理）说明 
- README.md/README_EN.md：新增删除清理（onRemove）小节——语义（仅卸载
  触发、重载/禁用不触发，Stop 之后执行）、内核配套清理（工具注册/disabled/
  配置项定义 plugin.<name>.*/配置表 config_<name>）、示例清单与代码片段
- plugindev 模板 README.md.tmpl：新增 Lifecycle 段（RegisterStopHandler 每次
  停止、RegisterOnRemoveHandler 仅卸载）
 2026-08-02 15:23:22 +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
db5d3133ea docs: document pre-built plugindev binaries in bin/ 2026-07-31 13:17:19 +08:00
root
bc1a005885 docs: fix plugindev install endpoint and build output; examples table; fix NewPluginFactory in bridge template 
- README 构建与安装：输出目录为 dist/，安装端点为 pluginmgr POST /plugins（JSON 或 raw body），删除不存在的 /api/plugins/install
- 示例表：weather/luademo 新增、qq 更新 17 工具（补入 2b54814 未提交部分）
- templates.go: go_init_plugin 调用 NewPluginFactory（模板插件仅导出该函数）
 2026-07-31 13:00:09 +08:00
root
78ef7998c2 docs: add RegisterInputChannel, ChannelDef to SDK README 2026-07-29 15:51:32 +08:00
JianFeeeee
c7c66b8d39 docs: 修正 plugindev 工具链描述 + 补充入口函数/Lua 插件说明 + 补全示例插件列表 2026-07-28 21:56:54 +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
d38d42e57f docs: update output channel interface (payload/meta/type) in SDK docs 2026-07-19 10:35:25 +08:00
root
2284d8897c feat: restore bili plugin, merge only web+webfetch into browser plugin 2026-07-18 21:11:18 +08:00
root
0856a9b2c3 feat: merge web/webfetch/bili into single browser plugin (search/fetch/render/video) 2026-07-18 21:06:56 +08:00
root
1762f0c34b docs: 修正全部文档使其与源码实现一致 
- Plugin.Start(sdk *PluginSDK) 接口签名改为指针
- 方法表重写: 移除 CallLLM/QueryKnowledge/SetMemory 等不存在方法
- IOInjector 参数顺序修正为 (source, channel, text)
- 删除虚构 SDKConfig, 替换为实际 New() 构造函数签名
- .hmap 内容描述一致化 (plugin.so + plugin.dll + main.lua)
- 添加 meta/ 包元数据文件
 2026-07-18 20:47:17 +08:00