jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 09:28:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
357 Commits 6 Branches 27 Tags
50ba4a64cb347498f755dbb43fd110836387d1b4
Commit Graph

8 Commits

Author SHA1 Message Date
JianFeeeee
50ba4a64cb feat(shm): 文档/知识正文入共享内存 + 协议版本 bump 到 2(§13.13) 
## 数据面补齐

- doc.insert / doc.insertWithMedia：新增 doc_ref / attachments_ref，
  模板序列化后 putValueInArena
- knowledge.add：新增 content_ref（内容是 JSON 字符串，读出后再解一层）
- 抽出通用 resolveJSONRef（resolveBlocks 也改用它），三处共用一套
  “共享优先、内联回退”逻辑

## 协议版本 bump：让错配显式失败，而不是静默坏

这是本轮更重要的部分。§13.6/§13.13 改了内核→插件 payload 的承载方式，
两种错配都不会报错、只会静默失效：

- v1 插件只读内联 args（tool/cleaner/output）→ 遇到 v2 内核拿到空参数
- v2 插件发 blocks_ref → v1 内核反序列化时静默忽略（旧内核
  io.setToolBlocks 还是桩实现）

现场表现为“输出变空 / 图注入没反应”，极难定位。所以把 ProtocolVersion
与模板 procProtocolVersion 一起 bump 到 2：双方都是等值校验，v1 插件遇上
v2 内核会在建链时明确报“协议版本不匹配…请用配套 plugindev 重编”。

测试里把“错误必须带出重编指令”也断言上了——生产上碰到它的现场就是
“只更新了内核没重编插件”，光报“不匹配”定位不到行动。

testdata 8 个插件的 protocol 同步更新（badprotoplugin 仍用 999 验证拒绝）。
工具链已重建并安装（协议 2，内嵌 blocks_ref/doc_ref/content_ref），
回滚副本 plugindev.bak-20260910-232544。

验证：-race 全绿。新增 KnowledgeAddViaArena(12000B 正文)、
KnowledgeAddInline、DocInsertViaArena、SetToolBlocks 三例 +
真实模板 e2e + 协议不匹配断言强化。

§13.13 第 5 条（反向大结果）范围更大——需把内核→插件的应答路径整体改成
“大结果写段 + 返回 ref”，涉及 callCore 的返回处理与 doc.query/llm.chat 等
所有读大结果的 method。已在 plan.md 标注未做，不冒充完成。
 2026-09-10 23:26:16 +08:00
JianFeeeee
15d912ef34 feat(shm): 媒体块入共享内存 + 实现 setToolBlocks 桩(§13.13) 
两个问题叠在一起，先发现的是第二个：

1. **io.setToolBlocks 在内核侧是桩实现**——直接返回“多模态注入待共享段
   二进制通道落地”。也就是**子进程插件调 SetToolBlocks 必然失败**（模板
   只 log 一行），只有内置插件（multimodal）能用。之前还有测试把这个错误
   当作预期行为断言着。
2. 媒体块（injectMedia 系列 + setToolBlocks）把 blocks 内联在 RPC JSON 里，
   而本地生成的图/音频是 base64 data URL，一张图可达数 MB。

顺带修掉一条与设计相悖的旧注释：injectMediaParams 写着“data URL 已是
base64 文本、再套一层二进制不会更小，所以走 JSON”。那只算了体积，漏了
两件更重要的事——内联时整份 base64 要在 RPC 报文里再编码/再拷贝一遍；
以及内容本体不在共享段里，插件回调就无法就地改写，只能各持一份拷贝。
共享内存的意义是后者。

实现：
- injectMediaParams 加 BlocksRef；新增 resolveBlocks（共享优先、内联回退）
- 真正实现 MethodIOSetToolBlocks（空块明确报错，不静默成功）
- CoreSDK 接口加 SetToolBlocks，procCore 转调 internal/sdk
- 模板：SetToolBlocks / injectMedia 三兄弟经 putValueInArena 传 blocks_ref；
  同步调用用 mediaArgsOwned 拿释放函数，**不能在应答返回前释放槽**，
  否则内核读到已释放内存

验证（-race 全绿）：
- TestCoreHandler_SetToolBlocksViaArena / Inline / EmptyRejected
- TestE2E_RealTemplateSetToolBlocksViaArena：真实 SDK 模板编译的插件，
  9000 字节 base64 图经 blocks_ref 完整送达

工具链已同步：/usr/local/bin/plugindev 重建为新协议（内嵌 blocks_ref），
回滚副本 plugindev.bak-20260910-224255。注意内核与全部插件必须同批替换
——只换一边会静默坏（新内核+旧插件=输出 payload 变空；新插件+旧内核=
媒体注入静默失效），已记入长期记忆。
 2026-09-10 22:45:19 +08:00
JianFeeeee
e2672c56d6 feat(shm): 输出通道 payload 走共享内存调用帧(§13.6) 
§13.3 给 ToolInvokeParams 加了调用帧，但 OutputInvokeParams 没跟上——
payload 仍内联在 RPC JSON 里。核实后确认这个 lane 只做了半边：注入侧
（injectParams.TextRef + resolveText）可用，输出侧从内核到插件仍是内联。

改法照搬工具调用的 funccall 帧模型：

- OutputInvokeParams 加 Frame/ArgsLen（Args 仅留给直连 RPC 的测试）
- invokeOutput 序列化参数 → Alloc 帧 → 写帧 → 只传偏移描述符 → defer Free
- 帧尾不预留结果区：output 应答很小（"ok"/status map），走 RPC 应答字段即可。
  但 OutputInvokeResult 支持插件把大结果写回帧（ResultRef），并识别
  sharedRefFlagExpand 单独归还扩容块——与 invokeTool 一致。
- 模板 output.invoke 用 frameInput 从帧读参数，无帧才回退内联 Args

为什么要做：output payload 在真机上可能含图片/文件描述等大字段，内联会
撑爆 stdin/stdout 管道。

验证：
- TestPlugin_OutputPayloadViaArena：9000 字节 payload 经帧完整送达（插件回报
  实收长度，不是只看返回值）+ 调用后 arena 归零
- TestE2E_RealTemplateOutputPayloadViaFrame：同上，但用真实 SDK 模板编译的
  插件——生产插件走的就是模板，模板不读帧则此改动等于没做
- TestPlugin_OutputChannelReportsRealFailure 仍绿：同步等真实结果、失败必须
  上报（§9.4）的语义未被破坏
- go test -race ./internal/plugin/... 全绿

plan.md §13.5 也如实标注：注入 side 内核→插件方向仍未接线（procCore.InjectText
直接传字符串，从不 Alloc/Put 构造 TextRef），不是仅打勾的项。
 2026-09-10 21:28:56 +08:00
JianFeeeee
b096e8ba2c refactor(shm): 变长块分配器 + 工具调用 funccall 调用帧(§13.2/§13.3) 
按架构约束推进两步：

1) 分配器收回内核后，定长槽失去了唯一存在理由
   （定长槽只是为了绕开"跨进程无法安全变长分配"），
   于是 arena 换成**变长块分配器**：first-fit + 邻块合并，
   块头 16B（size/state/owner/prevSize）。内核可以按需标定每块大小，
   payload 不再受固定槽容量限制（旧上限 16KB）。

   - Alloc/Put/Read/Free/ReclaimOwner 全在内核进程内，一把 sync.Mutex
   - Free 走块链校验 offset 是已分配块的数据起点 + owner 匹配，
     伪造引用不能改动分配器状态
   - Read 允许块内偏移（调用帧的结果区就在帧块中间），但不许跨块边界
   - arena 4MB，底层 memfd 惰性分配：未触碰的页不占物理内存

2) 工具调用 payload **始终**走共享内存，取消按大小切内联的分支。
   按 funccall 模型，内核（caller）标定调用帧交给插件（callee）：

       [0, ArgsLen)              参数 JSON
       [ArgsLen, Frame.Length)   结果区（内核预留的预算）

   结果超出预算时插件才 `arena.alloc` 扩容块，引用上打
   sharedRefFlagExpand 让内核单独归还。Cleaner 复用同一帧模型。
   ToolInvokeParams.Args / ToolInvokeResult.Result 仅剩给直连 RPC 的
   测试（process/bench 不建 Host）；生产路径永远走帧。

测试：
- TestArena_*（分配/归属/回收/并发唯一/耗尽/超限/伪造 offset/
  相邻合并/对齐/布局校验）
- TestPlugin_ToolInvokeArgsResultViaArena：大**小** payload 都经帧往返，
  结果一致且 arena 归零（"小 payload 同样走调用帧"是本轮行为变更）
- TestPlugin_ArenaAllocFreeAcrossProcess、TestE2E_* 保持通过
- 顺手修 process_test.go 一处预存 doc-comment 分段
 2026-09-10 18:54:36 +08:00
JianFeeeee
ca584bda3f refactor(shm): 内核独占共享槽池，插件经 RPC 申请/归还(§13.2/§13.3) 
推翻前两版跨进程分配器设计，根因是"共享内存里放了只被单一进程
更新的可变游标"：

- v1 在 SuperBlock 放 arenaUsed 游标，内核 CAS bump。但插件模板里
  arenaUsed 是**进程本地变量**，两进程各自 bump 必写同一段内存；
  arenaReset 还会重置共享游标覆盖对方数据。
- v2 把位图 CAS 下沉到插件模板，正确但把分配器实现泄漏进插件运行时，
  且插件必须与内核保持位图布局同步。

新设计（用户明确的架构约束）：内核全权管理共享内存，插件通过
syscall 风格 RPC 申请/归还，内核返回偏移与大小。分配器只存在于内核
进程内，一把 sync.Mutex 即可。共享内存是内部实现，不对插件开发者
暴露——SDK 公开 API 仍是普通字符串/Map。

主要改动：
- arena.go: 定长槽 + 位图，Alloc/Put/Read/Free/ReclaimOwner，内核独占；
  槽头记录 owner，Free 校验归属；payload 超槽容量退回内联 RPC
- protocol.go: 新增 arena.alloc / arena.free（CapCore）
- capability.go: 登记两个新 method（checkAllMethodsClassified 要求）
- corehandler.go: 实现 arena.alloc/free；Cleaner 改为内核预分配
  请求槽 + 响应槽（插件完全不分配）
- plugin.go: Start 领 ownerID；handleExit 调 ReclaimOwner 回收残留槽
- unified.go: 移除坏的 bump 分配器；arena 基址 8 字节对齐
- 删除 toollane.go: ring 状态机是死代码（从未接线），且把 RPC 已有的
  请求 ID 关联/错误传递/ctx 取消重新实现了一遍。控制面保留 RPC，
  只把 payload 搬进共享槽。
- 测试: TestArena_*（归属/回收/并发唯一/耗尽/超限/非法引用/布局）+
  TestPlugin_ArenaAllocFreeAcrossProcess（真进程申请→写入→随业务
  RPC 回传→归还→内核读回一致且池归零）
 2026-09-10 17:56:50 +08:00
JianFeeeee
7a328679da feat(proc): Cleaner 跨进程修复(tool/input/output) + 共享内存安全模式 + plan §13 
- Cleaner 协议统一为 cleaner.invoke(scope,name,text)，覆盖工具/输入/输出三类
- 新增 ShmSecurityMode (safe/debug/full)，Linux 审计探针，Windows crypto nonce
- plan.md 追加 §13 步骤分组
 2026-09-10 10:21:50 +08:00
JianFeeeee
687e5655bc feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干 
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。

## 一、公开 SDK：补上媒体的表达能力（全部新增，无签名变更）

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

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

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

## 二、内核桥接层：原先在静默裁字段

`internal/sdk/memory_impl.go` 此前只搬自己认识的几个字段，其余丢弃且返回 nil：

- 图记忆丢 `Confidence`/`SubjectType`/`ObjectType`/`SentenceText`，又走 `Commit`
  而非 `CommitWithMedia`（不回 sentenceIDs）→ 媒体绑定链 `SentenceText → sentences
  → sentence_id → media_refs` 一步都走不通，插件即便按格式写好标记也永远挂不上；
- 知识库 `Query` 只回 ID/Title/Content，`Insert` 只写这三个；`Remove` 不解引用，
  于是那些媒体永久处于「被引用」状态，GC 收不掉、磁盘只增不减
  （内核的归档路径 `releaseDocMedia` 做了这一步，插件路径漏了同一步）。

规则改为：**内部结构有的字段一律透传**。标记格式处理作为包级私有辅助留在桥接
层自己手里，但必须与内核 `mediaSummaryForEvent` 字节兼容——两边要能互读对方
写下的标记。

标记插入必须在 `ds.Insert` **之前**（向量索引取 `Summary + " " + Content`，
之后补的标记检索不到），引用绑定必须在**之后**（owner_id 是 Insert 生成的 ID）。

## 三、跨进程链路：不接线就是全体外部插件编译失败

`go test` 直接把这一层拍出来了——`procIO does not implement sdk.IOInjector`。
公开接口加方法后，生成模板不跟上，**每个外部插件都编不过**，是硬失败不是软降级。
六处接线：`protocol.go` 四个 method 常量、`capability.go` 能力归属、
`corehandler.go` 四个分派分支、`proc_core.go` 委托、`proc_main.go.tmpl` 模板侧
实现、以及三个测试替身。

## 四、统一输入主干：把模态从「函数选择」降级为「字段」

`processTextInput` / `processMediaInput` 合并为 `processInput`。这个分叉是历史
产物而非设计：`processTextInput` 本来就处理媒体（`bindEventMedia` +
`mediaSummaryForEvent`，与媒体路径尾部完全相同），`process()` 只看
`stageCtx.Extra["media_blocks"]`、根本不认识 `evt.Type`。模态是输入的**属性**，
不是输入的**种类**。

媒体路径由此获得它一直缺的六项：去重、`no_memory`、通道 `Cleaner`、中断语义、
`_consolidation_` 路由、正确的 `EventRawInput`。

最后一项是个真 bug：媒体路径发布 `"content": evt.Payload`（一个 map），而
`webui/handler.go` 断言 `.(string)` → 断言失败、`content == ""`、提前返回。
**用户发的图从来没出现在 WebUI 聊天记录里。**

`media_blocks` 同时接受 `[]agentAPI.ContentBlock` 与 `[]pubsdk.ContentBlock`：
字段一致但 Go 不自动转换，只认一种的后果是另一种被静默丢弃。

## 五、模型可调用的三个工具

`memory_commit` 的 `sentence_text` **从未暴露给模型**，而它是绑定链上的必经环节；
连同 `media_digests` 一起补进 JSON schema 与工具文档。`doc_commit` 加
`media_digests`。`doc_query` 把关联媒体单独一行附在结果末尾（正文按 2000 字截断，
标记通常就在尾部）。

标记由**内核**生成而非插件/模型拼装：要求调用方知道格式，等于让一个拼写错误
静默切断引用绑定，而全链路无人报错。

## 六、WebUI 上传走真实媒体链路

图片/音频读回字节拼 data URL 注入 `media_blocks`（8MB 上限，超限退回按路径处理）。
此前只注入一句「文件已保存到 <路径>」，指望模型自己调 `files_read`——但那返回
文本，图片字节对模型永远不可见。附件类型识别扩展到 audio 并在缺 Content-Type
时按扩展名兜底（判错不只是卡片样式问题，图片被当普通文件就进不了视觉链路）。

## 测试

- `internal/sdk/memory_impl_test.go`（12 例，此前该包**没有任何测试文件**）
- `internal/agent/core/inputunify_test.go`（统一主干 + 双静态类型 + 三工具媒体）
- `third_party/homeagent-sdk/sdk/stress_test.go`（13 例并发压测）

压测抓到两处**真**竞态（不是理论风险）：`PluginSDK` 的 API 字段与 `autoRestart`
无锁，而写方（内核注入 API、插件 `SetAutoRestart`）与读方（插件后台 goroutine
注入、内核 registry 读 `AutoRestart`）天然跨 goroutine。加 `apiMu` 修掉；约定
只在持锁期间取字段值，取完即释放再调用——持锁调用会把 `InjectInputSync` 这类
阻塞到 agent 回复（可达数分钟）的方法与 `SetIOInjector` 串起来，让插件重载卡死。

测试还抓出两个自身缺陷：`bindDocMedia` 把同一份媒体数两次（`AddRef` 幂等所以表
是对的，但日志说「绑定 2 个」而实际 1 条——误导后续排查），以及用单字符实体名
时 `validEntityName` 静默跳过、`Commit` 返回 nil 却什么都没写。

存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
 2026-09-06 09:51:31 +08:00
dev
82dcc86173 feat(proc): Plugin 加载器 + 51 method handler + RunStage 接共享段（Part 2 完成 / Part 4 闭环） 
corehandler.go —— cabi/loader.go 51 个 case 体的整块平移（§3.2）:
- 参数从「s1/s2/s3 + i1/i2 五个固定槽」改为结构化 JSON，语义不变
- CoreSDK 接口刻意只含外部插件应得能力：无 Selftest/Supervisor/Tracker/
  Status/Adapter/Config/Tool/Indexer/OutputChan/Publish
  → 权限梯度从「C ABI 表达能力的意外产物」变成「显式声明并强制的策略」（§3.8）
- 事件订阅(case 23/24)与 SetToolBlocks 明确返回未实现，不再像 C ABI 那样静默成功
  （静默成功后收不到事件比报错更难排查）
- ToolDef.Cleaner / ChannelDef.Cleaner 是函数，跨进程置 nil（§3.5 回调型资源）

host.go —— 共享段所有权中心:
- ❗ 全部子进程插件共享**同一块 memfd**。若每插件一段，
  「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成副本模型，
  最后回读者覆盖前者，§8.4 的 35.8~36.8% lost update 原样复现
- stageMu 串行化整次 stage 对段的独占（内核可能并发触发 RunStage）
- 首个进入者写入段，最后离开者回读 + Compact（此时无插件持锁，满足 §3.3 前提）

stage.go —— RunStage 接线（风险 3.4 落点）:
- 并发扇出保留（§0.2 第 1 条：并发扇出是原始设计，不是缺陷）
- 插件失败时 ForceReleaseLock，避免后续插件死锁（实验 9，无需 robust mutex）

plugin.go —— registry 可加载的插件实体:
- Start: spawn（fd 3 传共享段）→ 握手 → plugin.init → plugin.start
- Close: **真 kill + wait**，对比 cabi 的 Close 只做 dlclose 而后者是 no-op（§1.1）
- invokeOutput **同步等真实结果**，失败上报 error —— §9.4 根治

验证（34 项测试全绿，含 -race，全部用真实子进程）:
- 单插件 stage 读改写经共享段回到内核 StageContext
- sanitizer(改写) + weather(只读) 并发：清洗结果不被覆盖（现网场景）
- **5 个独立进程并发 append 同一 FinalText：5 个标记全部保留，零丢失零撕裂**
  （实验 8 在真实 RPC + 真实 RunStage 下的复刻）
- 工具注册可调用 / 输出通道真实失败上报 / start 期间反向调用
- 未知 method 与未实现能力被拒绝 / stage 外加锁被拒绝

接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空
 2026-09-02 11:34:33 +08:00