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
424 Commits 6 Branches 27 Tags
f2ec46480ec83dbfe1442e35bffeb3ade6150a29
Commit Graph

12 Commits

Author SHA1 Message Date
JianFeeeee
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
JianFeeeee
d1959cbe80 feat(core): 注入行为的记忆/裁剪标志位落地 + jieba 词库内嵌 + Windows 改走 WSL 
配套 SDK 提交：homeagent-sdk ba49dfd（公开 API 纯追加，无签名变更）。
本仓第三方的库镜像同步至该版本，以保证全新 clone 能编译。

## 1. 注入标志位（内核侧）

- 7 条注入路径（排队/中断/同步 × 纯文本/带媒体 + 旧 NoMem 变体）解析并转发
  no_memory / context_policy / cleaner_name；策略在入口**校验**，
  非法值报错而不是静默降级成 none（降级会让调用方以为自己声明的裁剪在生效）。
- 新增 validateContextPolicy（与 tool.register 同一套规则）与 pubSdkInjectOpts。
- input.register 不再手写字段白名单重建 ChannelDef，改为整体传递 + 补 ContextPolicy。
- io 层：applyInjectOpts 把标志位写进事件 payload，仅非零时写
  （零值与旧 payload 逐字节一致，事件订阅方与旧内核都不受影响）。
- ioAdapter / procCore / internal-sdk 别名补齐六个 *Opts 实现。

## 2. 修掉「输入无条件裁剪」这个真缺陷

eventloop 此前对**每条非中断输入**都调 `context.Prune(...)`：破坏性（低相关事件被
归档移出上下文）且无法从调用点看出是谁触发的。改为 pruneOnInput/pruneDeclared：

  优先级：注入点声明（payload.context_policy）> 通道声明（ChannelDef.ContextPolicy）
          > 默认**不裁剪**

查询向量仍取清洗后的内容；新增 cleanInputFor 解析清洗文本，优先级为
注入点声明的 cleaner（cleaner_name）> 按 source 查到的通道 cleaner > 原文，
名字查不到时**记日志再回退**（注入是 fire-and-forget，插件看不到错误，
至少要在内核日志留下「你声明的清洗没生效」的痕迹）。

## 3. jieba 词库内嵌（修「猜 GOMODCACHE → 静默失效」）

原 jiebaDictDir() 去猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块
缓存 → GetJieba() 返回 nil → 分词/关键词提取/NLP 依存解析（进而 doc→graph 三元组
抽取）/静态词向量 tokenizer **一律静默返回空列表**，只有一行日志。本机看起来正常
只因开发机与生产机重合、恰好有那份缓存。

现在词库随二进制分发：internal/memory/jiebadict/ 5 文件约 11.6MB + go:embed，
按**内容哈希**命名缓存目录落盘（词库升级不复用旧文件），已齐全则跳过写入。
模块缓存降为兜底。homed 体积 32MB。

顺带确认（并有测试佐证）：gojieba 的 Tag() 不需要 pos_dict/ 目录——
cppjieba 的 PosTagger 从主词典每行的词性列取 tag。

## 4. homed 放弃 Windows 原生，改走 WSL2

插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，Windows 既无 fd
继承语义，其句柄模型也无法表达后者；强行适配等于再维护一套平台专属 ABI
（C ABI 时代三套 ABI 并存曾导致改写型插件在某平台静默失效）。

- cmd/homed/platform_{windows,other}.go：原生 Windows 启动即拒绝并打印 WSL2 指引。
- internal/plugin/proc/shmalloc_windows.go：allocShm 直接返回「请用 WSL2」，
  **不返回半可用的段**（与 shmalloc_other.go 同风格：未支持平台显式报错）；
  procEnvForShm 返回 nil。顺手修掉两处长期编译错误
  （cryptorand→rand、h.evData→h.unified.evtData），使 GOOS=windows 至少能编译。
  注：homed 本就编不出 Windows——internal/memory 依赖 cgo-only 的 gojieba。
- deploy/packaging/installer.nsi：不再安装 homed.exe/initconfig.exe，改为携带
  **linux payload** 并调用新的 install-via-wsl.ps1；退出码 20/21 表示
  「需先装 WSL/发行版」，走指引而非报错。
- deploy/packaging/windows/install-via-wsl.ps1（新）：检测 WSL → 引导安装 →
  确保 WSL2 → 送包进发行版 → 在 WSL 内按 Linux 方式安装。**复用 Linux 包与
  linux/setup.sh**，不另写一套安装逻辑；落点与 deb 布局统一
  （/usr/bin/homed + /usr/lib/homeagent/setup.sh）。
- deploy/packaging/linux/setup.sh：API Key 允许 HOMEAGENT_API_KEY 覆盖
  （否则安装器界面显示一份、config.db 里另一份 → 登录不上）。
- deploy/packaging/build.sh：windows 目标只构建 waiter + gui，并新增
  stage_linux_payload 把 Linux 包暂存给安装器；homed/initconfig 在 windows
  目标下明确拒绝。

## 5. 插件调用点统一写明意图

- webui 的 OpenAI 兼容端点（固定提示词模板）→ InjectTextSyncNoMemory。
- agentcli 的 5 处纯状态通知（已启动/超时/执行结束/进程退出/读取结束）→ NoMemory；
  **带输出**的 2 处（定时反馈、有新输出）刻意保留记忆并注明理由。
- timer 的定时提醒 → NoMemory（中断本来也隐含 NoMemory，这里是写明意图）。

## 6. 版本

meta.Version 仍为 1.2.0（main 是下一个未发布中版本）；
SDKCompatibleVersion 1.1.0 → **1.2.0**（本内核已实现 SDK 1.2.0 全部新增方法）。

## 测试

- core：默认不裁剪（无声明/none/空）、通道 opt-in、注入点双向覆盖通道、
  nil context/io 安全、cleaner 优先级与未知名回退。
- io：零值 opts 与历史 payload 逐键相同；text/中断/媒体三类注入标志位都落到
  payload；旧方法仍生效。
- proc：validateContextPolicy 只接受 ""/none/prune，报错含位置与实际值；
  **跨进程** e2e——testdata 插件经 io.injectText 送出三个标志位，断言它们穿过 RPC
  到达内核。
- memory：模块缓存不可见时内嵌词库仍可用（分词与 POS 内容词均非空）、
  落盘幂等、内容哈希稳定。

验证：go build ./... / go vet ./... / go vet -tags onnxruntime ./...
      go test -short ./internal/memory/... ./internal/nlp/... ./internal/plugin/...
      ./internal/agent/{core,io}/... ./pkg/...
 2026-09-11 20:31:50 +08:00
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
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
5608abdf5a feat(shm): Cleaner 迁移到 SharedRef(§13.4) 
- CleanerInvokeParams/Result 的 Text 改为 TextRef SharedRef
- cleanerProxy: 写 text 到 arena，传 SharedRef，读结果 SharedRef
- 插件侧 cleaner.invoke: 从 SharedRef 读 input，清洗后写回 arena 返回 TextRef
- NewHost(): 分配空间含 arena（256KB）
 2026-09-10 15:30:00 +08:00
JianFeeeee
ad016e4410 feat(shm): 统一共享内存区域(§13.1) — 单 memfd 容纳 SuperBlock+StageContext+EvtRing 
- unified.go: SuperBlock 布局 + SharedRef 类型
- NewHost(): 两段 memfd 合并为单一 memfd，fd 3 = 统一区域，fd 4 = eventfd
- 子进程侧: testdata 插件从 SuperBlock 解析 ctxOff/evtOff
- streaming 测试: EvtConsumer 协程在 host.Close 前 Stop+Wait 防 SIGSEGV
 2026-09-10 11:42:22 +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
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
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
dev
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