|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
02cc74ce11
|
fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除
根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，
工具/stage handler/IO 通道全留在注册表里指向死进程，
模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。
## 四层修复
### 1. 专职 waitLoop（进程收割）
- 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点
- 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来）
- 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与
os/exec 的内部关闭竞争
- host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段
### 2. 集中台账 Supervisor
- proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack
- StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill
- 关停后才完成握手的进程被立即结束，不会活过内核
- 消除「孤儿进程持共享段映射 → SIGBUS」的隐患
### 3. 注册面摘除（detachPlugin）
- 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler
- 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道
- 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin
- StopAndUnload 漏了 IO 通道也一并补上
### 4. 自动重启
- onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」
- scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s
- 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载
- 崩溃计数窗口过期自动归零
### 5. 主动停止 vs 崩溃的区分
- proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true)
- handleExit 读 stopping 标志，主动停止不上报 onCrash
- 防止重载/禁用/卸载被误判为崩溃触发多余重启
### 6. Linux Pdeathsig 兜底
- procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL
- 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景
- macOS/Windows 无等价物，空实现
### 7. pluginmgr 升级
- PluginManager 接口新增 PluginRuntime / ListPluginRuntimes
- plugin_list 输出运行态：loaded / alive / pid / crash_count / channel
- 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总
- 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件）
### 测试
- process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack /
StopAll 无孤儿）
- crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 /
退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别）
- stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op /
工具+stage 双摘后可重新注册同名）
|
2026-09-03 12:37:58 +08:00 |
|
|
|
d62430a71b
|
feat(proc): 子进程通道 —— RPC 协议 + 进程管理（Part 2 核心）
协议面（protocol.go，§3.2 method id 平移为 method 名）:
- NDJSON 帧，双向复用同一对 stdio；ID>0 需应答，ID==0 为通知(post-and-forget)
- 51 个 C ABI method id 全部平移为可读 method 名并标注原编号对照
编号本身扔掉——加能力不用改两边常量表，不再有 47 夹在 7 和 8 之间的痕迹
- case 25(CORE_FREE_STRING) 无对应 method：进程模型下各自 GC，概念消失
- case 23/24(事件订阅) 与 io.setToolBlocks 今日均为空实现「给不了」，
子进程下首次真正可给（§3.8 能力对齐）
- 新增 stage.lock/stage.unlock（C ABI 下不存在跨进程锁概念）
- StageInvokeParams 不含 StageContext 数据本身——数据在共享段，只带 stage 名 + seq
进程面（process.go，§2.3 保留现有生命周期机制）:
- Spawn: 启动 + 握手（协议版本不匹配显式拒绝，不半兼容运行）
- readLoop: NDJSON 分派应答/插件反向请求，1MB 单帧上限（大 payload 走 arena）
- CallContext: ctx 取消时立即返回**且清理 pending 条目**
对比 cgo：超时只让调用方返回，goroutine 永久卡在 C 调用里（现网泄漏 26 次）
- Notify: ID=0 不占 pending 表，满足约束 B（流式逐 token 发布不得等待消费者）
- markExited: EOF/退出 → 唤醒全部在途调用 → onExit 回调
这是「把 panic 捕获换成进程退出检测」的落点，plugin_health 逻辑完全复用
- Stop: plugin.stop → 宽限期 → 超时 Kill；Kill 后 OS 回收全部资源，零泄漏
- serveRequest 带 panic 隔离：内核 handler panic 不带崩 readLoop
验证（10 项，真实子进程而非 mock，含 -race）:
- 握手/工具调用/错误上报（插件失败调用方收到 error，非假成功）
- 插件反向调用内核（tool.register + settings.get 双向往返）
- **崩溃隔离**：插件 panic → 子进程 exit 2，内核存活、收到 onExit、在途调用不挂死
- 优雅停止 / **Kill 卡死插件**（ctx 超时返回 + pending 清零 + 资源回收）
- 通知不等应答（100 条 < 1s）/ 50 并发调用应答不串 / 协议版本不匹配拒绝
接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空
|
2026-09-02 10:59:59 +08:00 |
|
