jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-20 17:08:01 +00:00
Code Issues Packages Projects Releases Wiki Activity
105 Commits 5 Branches 10 Tags
4cb3a0bda46e49ac3a2bfcf925bab24540ab6a93
Commit Graph

18 Commits

Author SHA1 Message Date
JianFeeeee
b93fe6b878 chore(version): main 路牌推到 1.3.0（v1.2.0 已从 release/v1.2.x 发出） 
按版本纪律：release/v1.2.x 停在 v1.2.0 的发布提交（140cd34），主干 meta.Version
永远是「下一个未发布中版本」。
 2026-09-12 14:16:46 +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
12cabcb290 fix(meta): SDK main 的路牌回到 1.2.0 —— beta 不发 SDK 
我上一提交（44bd915）把 SDK main 从 1.2.0 推到 1.3.0，判据用错了。

当时照搬的是 核心仓 e4be966 的先例（§七.4「两仓 main 都是下一个未发布中版本」），
但那个先例的前提是**核心那一版已经正式发布过**：当时 v1.1.0 / v1.1.1 都已打 tag，
main 才推进到 1.2.0。

而按 §七.2，**beta 不伴随 SDK 发版**：SDK 1.2.0 要等核心的**正式** tag 才定版、
建 release/v1.2.x、打 tag（§七.3）。在此之前 1.2.0 仍然是 SDK **尚未发布**的中版本，
所以「下一个未发布中版本」就是 1.2.0 —— 推到 1.3.0 等于宣称 1.2.0 已经存在。

核心 main 是 1.3.0 并没有错：核心切出 release/v1.2.x 后，1.2.0 就归发布线所有。
**两仓在这个阶段故意不对称**，已在 meta.go 注释里写明，避免再被「对齐」回去。
 2026-09-12 09:00:19 +08:00
JianFeeeee
44bd915fbf chore(meta): SDK main 的版本路牌推到 1.3.0 
按 核心仓 docs/git-branching.md §七.4，两仓 main 都遵守 §2.1：meta.Version 是
**下一个未发布中版本**。核心 1.2.x 线已开（release/v1.2.x 承载 1.2.0），所以
两仓 main 一起指向 1.3.0——核心仓同一时刻也做了同样的推进（chore(meta)）。

它标记「main 正在积攒 1.3 的东西」，不表示 1.3.0 已经存在。
SDK 1.2.0 的定版与 tag 不在现在做：按 §七.3，SDK 的 release/v1.2.x、meta.Version
定为 1.2.0、tag v1.2.0 都与核心的**正式** tag 一起执行（beta 阶段不发 SDK）。
 2026-09-12 08:24:44 +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
da01af1ad7 chore(meta): main 的版本路牌推到 1.2.0 
按 核心仓 docs/git-branching.md §2.1，两仓 main 的 meta.Version 都是
**下一个未发布中版本**。1.1.x 线正在发布中，所以 main 指向 1.2.0。

SDK 版本跟随核心的中版本（§七.1）：release/v1.1.x 上定版 1.1.0，
整条核心 1.1.x 线共用它。

**此 commit 不 cherry-pick 到发布分支**（§五）。
 2026-09-06 10:04:26 +08:00
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
5ed8d65479 meta: 版本升到 1.0.0，删除 C ABI 时代的死常量 
## 为何是主版本号

公开 SDK 接口（sdk/ 目录）本轮**零改动**，插件业务代码一行不用改。
但产物形态变了：plugin.so → plugin.bin。0.9.x 内核只会 dlopen `.so`，
本版工具链产出的 `plugin.bin` 在旧内核上根本不会被识别——
这是不可互操作的破坏性变化，故 CoreVersion 也升 1.0.0 作为**硬下限**
而非建议值。

## 删掉的死代码

ABIVersion / ABIVersionMin / CABINum / CABINumMin / 51 个 Core<Method>
整数 ID，全部无使用者：

    grep -rn "CABINum" --include=*.go --include=*.tmpl .   → 只有定义处
    grep -rn "meta.Core[A-Z]" ...                          → 无

它们随 Part 6.2 删除 internal/plugin/cabi/ 就已失效：
  - 整数 method id 平移为 method 名字符串（proc/protocol.go 的 Method* 常量）
  - 版本协商改为握手帧里的 protocol 字段

留着有实际危害——下一个读这个文件的人会以为 C 层协商还在生效，
或者以为加 method 时要同步维护那张整数表。

## 协议版本与语义版本解耦

新注释写明：子进程 RPC 的 protocol 是独立小整数（当前 1），
只在帧格式或握手语义变化时升；语义版本变动频繁（修 bug、加字段）
不应牵动 wire 协议。这两者以前被 ABIVersion = CoreVersion 绑在一起，
现在分开。

验证：go build ./... 通过；git diff sdk/ 为空（接口冻结不变量）。
 2026-09-02 22:40:15 +08:00
JianFeeeee
5c1574be25 bump: sdk v0.9.2 (SetToolBlocks + DataDir) 2026-08-27 09:32:01 +08:00
JianFeeeee
cf77bf389e chore: bump version to v0.9.1 
- Version: 0.9.0 -> 0.9.1
- CoreVersion: 0.9.0 -> 0.9.1

与主仓库 HomeAgent v0.9.1 配套发布。SDK Go 代码自 33a79de 后无变更。
 2026-08-25 13:22:18 +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
JianFeeeee
6527a40539 fix: CABINumMin 恢复为 1 兼容旧 ABI 插件(仅缺 stage 写回) 2026-08-15 16:34:25 +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
root
b166697dd7 bump version to v0.8.0 2026-07-29 15:45:33 +08:00
JianFeeeee
04837f237d plugindev: 全面 plg.json 持久化 + --replace 支持 + 文档 2026-07-25 15:47:49 +08:00
JianFeeeee
1fa3c843ab refactor: centralize ABI metadata into meta/meta.go 
- meta/meta.go: add ABIVersion, ABIVersionMin, 45 dispatch method IDs
- tools/plugindev/cmd_init.go: cabiVersion -> meta.ABIVersion
- tools/plugindev/templates.go: C header comments reference meta.go
 2026-07-25 14:42:32 +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
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