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
This commit is contained in:
JianFeeeee
2026-09-02 13:03:57 +08:00
parent 82dcc86173
commit 11c1bbcebb
9 changed files with 881 additions and 50 deletions

View File

@ -0,0 +1,171 @@
package plugin
import (
"gitcode.com/JianFeeeee/HomeAgent/internal/plugin/proc"
isdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
)
// procCore 把内核的 *internal/sdk.PluginSDK 收窄成子进程插件可见的能力面。
//
// ❗ **必须用命名字段,不能嵌入** `*isdk.PluginSDK`:嵌入会让全部方法被提升,
// 外部插件通道就能经类型断言拿到 Supervisor()/Tracker()/Adapter()/Indexer()
// 这些内核内部机制——权限梯度退化成纸面约定。命名字段下只有下面显式写出的
// 方法存在,这才是 §3.8 说的「从 C ABI 表达能力的意外产物变成显式声明并强制的策略」。
//
// 另一个必要性internal/sdk 的接口是公开 SDK 的**超集**isdk.KnowledgeAPI
// 内嵌 pubsdk.KnowledgeAPI 再加 Stats()/Remove()isdk.MemoryAPI 加 GraphData()
// isdk.LLMAPI 加 Chat()/ReloadFromConfig()Go 方法签名精确匹配下
// *isdk.PluginSDK 本就不满足 proc.CoreSDK。
//
// 内置插件走的仍是原路径(直接持 *isdk.PluginSDK拿到全量接口不受影响。
type procCore struct {
sdk *isdk.PluginSDK
}
// newProcCore 包装内核 SDK 供子进程插件使用。
func newProcCore(s *isdk.PluginSDK) procCore { return procCore{sdk: s} }
func (c procCore) PluginName() string { return c.sdk.PluginName() }
// ---- 能力访问器:内部超集接口 → 公开 SDK 接口 ----
//
// nil 保护是必要的corehandler 用 `if xxx == nil` 判断能力不可用并返回
// errUnavailable若把「类型化的 nil」透过去判空会失效——插件收到的是
// panic 而不是"能力不可用"。
func (c procCore) Settings() pubsdk.SettingsAPI {
if s := c.sdk.Settings(); s != nil {
return s
}
return nil
}
func (c procCore) Memory() pubsdk.MemoryAPI {
if m := c.sdk.Memory(); m != nil {
return m
}
return nil
}
func (c procCore) TextMemory() pubsdk.TextMemoryAPI {
if m := c.sdk.TextMemory(); m != nil {
return m
}
return nil
}
func (c procCore) DocMemory() pubsdk.DocMemoryAPI {
if m := c.sdk.DocMemory(); m != nil {
return m
}
return nil
}
func (c procCore) Knowledge() pubsdk.KnowledgeAPI {
if k := c.sdk.Knowledge(); k != nil {
return k
}
return nil
}
func (c procCore) LLM() pubsdk.LLMAPI {
if l := c.sdk.LLM(); l != nil {
return l
}
return nil
}
func (c procCore) Social() pubsdk.SocialAPI {
if s := c.sdk.Social(); s != nil {
return s
}
return nil
}
func (c procCore) PluginMgr() pubsdk.PluginMgrAPI {
if m := c.sdk.PluginMgr(); m != nil {
return m
}
return nil
}
// ---- 注册面 ----
func (c procCore) RegisterTool(name string, def pubsdk.ToolDef, handler pubsdk.ToolHandler) error {
return c.sdk.RegisterTool(name, def, handler)
}
func (c procCore) RegisterStage(stage pubsdk.Stage, handler pubsdk.StageHandler, scope ...pubsdk.StageScope) {
c.sdk.RegisterStage(stage, handler, scope...)
}
func (c procCore) RegisterPluginAPI(name string) error {
return c.sdk.RegisterPluginAPI(name)
}
func (c procCore) RegisterOutputChannel(name string, caps int, desc string, def pubsdk.ChannelDef, handler pubsdk.ToolHandler) error {
return c.sdk.RegisterOutputChannel(name, caps, desc, def, handler)
}
func (c procCore) RegisterInputChannel(name string, def pubsdk.ChannelDef) error {
return c.sdk.RegisterInputChannel(name, def)
}
// ---- IO 注入 ----
func (c procCore) InjectText(source, channel, text string) {
c.sdk.InjectText(source, channel, text)
}
func (c procCore) InjectInterruptText(source, channel, text string) {
c.sdk.InjectInterruptText(source, channel, text)
}
func (c procCore) InjectTextNoMemory(source, channel, text string) {
c.sdk.InjectTextNoMemory(source, channel, text)
}
// InjectInputSync 收窄为公开 SDK 的三参数文本形态。
//
// internal/sdk.PluginSDK 的同名方法是 (source, channel, eventType, payload)
// → *agentIO.OutputEvent暴露了内核 IO 事件结构;外部插件只该看到回复文本。
// 取值方式与 C ABI 路径一致internal/plugin/cabi/loader.go 的 case 47
func (c procCore) InjectInputSync(source, channel, text string) string {
out := c.sdk.InjectInputSync(source, channel, "text", map[string]interface{}{
"content": text,
})
if out == nil {
return ""
}
reply, _ := out.Payload["content"].(string)
return reply
}
// ---- 生命周期 ----
func (c procCore) SetAutoRestart(enabled bool) { c.sdk.SetAutoRestart(enabled) }
// 编译期确认收窄面正好满足子进程插件的能力契约。
var _ proc.CoreSDK = procCore{}
// procPluginAdapter 把 *proc.Plugin 适配到 registry 的 sdk.Plugin 接口。
//
// 两者只差 Start 的参数类型registry 传 *isdk.PluginSDK全量能力
// 而子进程插件只该拿到收窄后的 proc.CoreSDK。转接在此发生
// 权限收窄就成了**类型系统强制**的事而不是约定§3.8)。
//
// Name/Stop/Close 经嵌入指针提升Close 对 registry.closeDynamic 可见,
// 故重载时能真正 kill 子进程——对比 cabi 路径的 Close 只做 dlclose
// 而 dlclose 对 Go c-shared 是 no-op§1.1,热重载静默失效的根因)。
type procPluginAdapter struct {
*proc.Plugin
}
// Start 把内核全量 SDK 收窄成子进程可见的能力面后启动进程。
func (a procPluginAdapter) Start(s *isdk.PluginSDK) error {
return a.Plugin.Start(newProcCore(s))
}
// 编译期确认适配器满足 registry 的插件接口。
var _ isdk.Plugin = procPluginAdapter{}