|
|
b15d0bd114
|
refactor(plugin)!: 重编提示与模板路径改用 hmapdev；文档全面对齐 1.2.0
工具链在 SDK 1.2.0 更名为 hmapdev（原 plugindev）。核心侧三处功能耦合同步：
1. 用户可见报错：旧 C ABI 产物 / 协议版本不匹配 / 共享段版本不匹配
三处「请用配套 plugindev 重编」→ hmapdev（对应两条测试断言同步）
2. e2e_template_test 的模板路径改为 tools/hmapdev/templates，
并保留旧路径回退（旧 SDK 检出仍能跑测试）
3. 注释与文档同步
文档更新（用户可见面）：
- assets/docs/{zh,en}/PLUGIN_DEV.md：工具链章节整体改为 hmapdev，
补改名说明与 SDK 存储目录迁移；命令示例全部更新
- assets/docs/{zh,en}/ARCHITECTURE.md：**流程图与章节对齐 v1.2.0** ——
· 向量化章节改为三层降级：统一多模态空间（主）→ 词嵌入 → TF-IDF（回退），
写明「同指纹且同维度才参与融合」
· 媒体记忆章节重写：媒体是一等记忆块（无独立 GC / 无引用计数 / 无描述式索引 /
正文不再写 media marker），并写明 reembedStaleMedia 的跨空间迁移与写回
- README{,_EN}.md、docs/zh/plugin-interface-matrix.md：工具名与模板路径同步
（历史条目标注「当时名为 plugindev」）
验证：go test ./internal/plugin/ ./internal/plugin/proc/ ok，
含 4 条真实模板 E2E（模板路径切换后仍通过）。
|
2026-09-12 12:42:43 +08:00 |
|
|
|
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 |
|
|
|
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 |
|
|
|
d027c964e2
|
proc: Windows 共享内存 + 事件通知适配（Part 6.2 内核侧）
补齐内核侧的 Windows 创建端，与 6.1 的插件侧打开端配对。三平台
（linux/darwin/windows）现在都能构建 internal/plugin/proc。
## Windows 走命名内核对象（无 fd 继承语义）
os/exec 的 ExtraFiles 在 Windows 实现里不被支持，故：
- shmalloc_windows.go：CreateFileMappingW（INVALID_HANDLE_VALUE + 命名 →
系统页文件支撑的匿名段，不落盘）+ MapViewOfFile
- evtfd_windows.go：CreateEventW 命名 Event 对象 + SetEvent 通知
- shmpass_windows.go：把段名/对象名经环境变量注入子进程
（HOMEAGENT_SHM_STAGE / HOMEAGENT_SHM_EVTRING / HOMEAGENT_EVT_EVENT）
名字带 PID + 递增序号：多个 homed 实例并存时不能撞名。
Event 与 eventfd 的语义差异：Event 是二元信号，多次 SetEvent 只对应一次
唤醒，不累积。不影响正确性——消费者被唤醒后按 readSeq 追 writeSeq 批量
drain，丢的是"唤醒次数"不是"事件"；事件环本身就允许溢出丢弃并让消费者
知道丢了（dropped 计数），通知面从来不是可靠投递语义。
## 传递机制抽象为 shmpass_*.go
Plugin.Start 不再直接构造 ExtraFiles 列表，改为问 Host 要：
Env: p.host.procEnvForShm() // Windows 返回段名，Unix 返回 nil
ExtraFiles: p.host.procExtraFilesForShm() // Unix 返回 fd 列表，Windows 返回 nil
平台差异被收敛到这一对函数，Plugin/coreHandler/stage 全部平台无关。
## macOS pipe 生命周期修正
原实现只返回读端 fd，写端 *os.File 无人持有 → 可能被 GC 回收 →
读端收到 EOF 而非阻塞 → 消费循环变忙转。改为 pipePair 表同时持有两端，
evtfdClose 一并关闭。
## E2E 测试跟进模板拆分
模板从单文件拆成三个（主体 + unix/windows 挂载），测试需要一并落盘，
否则编译报 attachStageShm undefined。procRuntimeTemplates 表必须与
SDK 仓 proc_runtime.go 的 procRuntimeFiles 一致。
验证：三平台 go build ./internal/plugin/... 通过（gojieba 的 cgo 依赖
导致 internal/memory 在非 linux 失败，与本次无关）；
go test -race ./internal/plugin/... 全绿，含 2 项真实模板 E2E。
Ref: docs/zh/架构迁移评估.md §9.2、docs/zh/plugin-migration-plan.md Part 6
|
2026-09-02 19:07:14 +08:00 |
|
|
|
11c1bbcebb
|
plugin: 子进程通道接通 registry（proc 通道端到端可运行）
Part 3 收尾。tryLoadProc 从桩位变成真实加载路径，plugin.bin 插件现在
经 registry 完整跑起来：spawn → 握手（共享段 fd 3）→ init/start →
反向注册 → 工具调用 → stage 共享内存读改写。
registry 侧：
- Registry 持有 procHost（惰性创建，**全部 .bin 插件共用一块段**）。
每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成
副本模型，lost update 原样复现（§8.4 实测 35.8~36.8%）。
- tryDynamic 分派到 Registry.loadProc；tryLoadProc 退为纯静态校验
（构造需要 Host，只有 Registry 有）。
- StopAll 在锁外释放共享段：插件还持有映射时拆段，它们下一次访问就是
SIGBUS；且持锁调用会与 onProcCrash 回调产生锁序风险。
- onProcCrash 把子进程退出转成 EventSystem 事件，不在回调里直接重载
（重载需 registry 锁，而回调可能来自持锁路径的 goroutine）。
proc_core.go —— 权限梯度的类型系统落点（§3.8）：
- procCore 用**命名字段**持有 *isdk.PluginSDK，不是嵌入。嵌入会提升全部
方法，外部插件就能经类型断言拿到 Supervisor/Tracker/Adapter/Indexer/
Status/Selftest。命名字段下只有显式写出的方法存在——权限梯度从
「C ABI 表达能力的意外产物」变成显式声明并强制的策略。
- 能力访问器把内部超集接口收窄到公开面（isdk.KnowledgeAPI 内嵌
pubsdk.KnowledgeAPI 再加 Stats/Remove，isdk.MemoryAPI 加 GraphData，
isdk.LLMAPI 加 Chat/ReloadFromConfig）；nil 保护避免类型化 nil 让
corehandler 的判空失效。
- procPluginAdapter 转接 Start(*isdk.PluginSDK) → Start(proc.CoreSDK)，
Close 对 closeDynamic 可见故重载能真 kill 子进程（对比 dlclose 对
Go c-shared 是 no-op，§1.1）。
共享段分配按平台拆分（原先 host.go 直接调 unix.MemfdCreate，darwin/windows
交叉编译失败）：Linux memfd；macOS 立即 unlink 的临时文件（无 memfd_create，
但语义一致：无残留、fd 可经 ExtraFiles 传递、子进程 mmap 同一 inode）；
其余平台明确报错而非静默降级成「无共享段」——那会让 stage 静默失去数据面。
测试 +13 项：
- e2e_template_test.go 用**真实 plugindev 模板**（而非 testdata 手写假插件）
编译插件跑全链路，验证「模板 ↔ 内核」协议/布局真的对齐，不只是内核自己
跟自己对齐。含 lifecycle.autoRestart 上报、工具调用、stage 读改写、
FinalText 回传（C ABI 下 after_toolcall 看不到此字段，§8.3 10→16）、
只读插件不覆盖改写插件。
- proc_load_test.go 验证 Host 唯一性/惰性、chmod +x 错误提示、
Close 可见性，以及 procCore 不暴露内核内部机制的断言。
验证：go build ./... 通过；go test -race ./internal/plugin/... 全绿；
全仓 go test 无新增失败；git diff third_party/homeagent-sdk/sdk/ 为空。
既有告警 cabi/loader.go:156 unsafe.Pointer 非本次引入。
Ref: docs/zh/架构迁移评估.md §3.3/§3.4/§3.8、docs/zh/plugin-migration-plan.md Part 3
|
2026-09-02 13:03:57 +08:00 |
|
