From 304cad06484f1b6699fe9a7e635e7bafe6ee7c44 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 11:45:52 +0800 Subject: [PATCH 01/27] =?UTF-8?q?docs(plugin-arch):=20=E5=BD=92=E6=A1=A3?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E6=9E=B6=E6=9E=84=E8=BF=81=E7=A7=BB=E8=AF=84?= =?UTF-8?q?=E4=BC=B0=20+=20plan=20=E7=AC=AC11=E8=8A=82=E6=95=B4=E6=94=B9?= =?UTF-8?q?=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/zh/架构迁移评估.md: C ABI→子进程+共享内存完整迁移论证(1621行) - docs/zh/experiments/: 18项可复跑可行性实验(架构评估的所有数字来源) - plan.md §11: 11.1~11.9 插件架构缺陷修复清单(唯一权威编号) - main 保持干净,本批次为 update 特性分支的整改起点 --- .../01-dlclose-nodelete/exp01a/main.go | 72 + .../01-dlclose-nodelete/exp01b/main.go | 49 + .../01-dlclose-nodelete/exp01c/main.go | 58 + .../01-dlclose-nodelete/probe_v1.c | 2 + .../01-dlclose-nodelete/probe_v2.c | 2 + .../plugin-arch/01-dlclose-nodelete/shim.c | 9 + .../plugin-arch/02-feasibility/exp10.go | 49 + .../plugin-arch/02-feasibility/exp11.go | 42 + .../plugin-arch/02-feasibility/exp11_plug.go | 12 + .../02-feasibility/exp1_eventfd.go | 58 + .../plugin-arch/02-feasibility/exp2_child.go | 41 + .../plugin-arch/02-feasibility/exp2_parent.go | 60 + .../plugin-arch/02-feasibility/exp3_child.go | 31 + .../plugin-arch/02-feasibility/exp3_parent.go | 37 + .../plugin-arch/02-feasibility/exp4.go | 71 + .../plugin-arch/02-feasibility/exp5.go | 55 + .../plugin-arch/02-feasibility/exp5_plugin.go | 23 + .../plugin-arch/02-feasibility/exp5b.go | 68 + .../plugin-arch/02-feasibility/exp6.go | 49 + .../plugin-arch/02-feasibility/exp6_crash.go | 23 + .../plugin-arch/02-feasibility/exp7.go | 63 + .../plugin-arch/02-feasibility/exp8.go | 84 + .../plugin-arch/02-feasibility/exp8_worker.go | 50 + .../plugin-arch/02-feasibility/exp9.go | 60 + .../plugin-arch/02-feasibility/exp9_worker.go | 12 + .../plugin-arch/03-lost-update/exp12/main.go | 90 + .../plugin-arch/03-lost-update/exp13/main.go | 101 + .../04-cgo-uninterruptible/exp14a/main.go | 62 + .../04-cgo-uninterruptible/exp14b/main.go | 43 + .../plugin-arch/04-cgo-uninterruptible/hang.c | 2 + docs/zh/experiments/plugin-arch/README.md | 111 ++ docs/zh/experiments/plugin-arch/run.sh | 127 ++ docs/zh/架构迁移评估.md | 1621 +++++++++++++++++ plan.md | 315 ++++ 34 files changed, 3552 insertions(+) create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01a/main.go create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01b/main.go create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01c/main.go create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v1.c create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v2.c create mode 100644 docs/zh/experiments/plugin-arch/01-dlclose-nodelete/shim.c create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp10.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp11.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp11_plug.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp1_eventfd.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp2_child.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp2_parent.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp3_child.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp3_parent.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp4.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp5.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp5_plugin.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp5b.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp6.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp6_crash.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp7.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp8.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp8_worker.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp9.go create mode 100644 docs/zh/experiments/plugin-arch/02-feasibility/exp9_worker.go create mode 100644 docs/zh/experiments/plugin-arch/03-lost-update/exp12/main.go create mode 100644 docs/zh/experiments/plugin-arch/03-lost-update/exp13/main.go create mode 100644 docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14a/main.go create mode 100644 docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14b/main.go create mode 100644 docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/hang.c create mode 100644 docs/zh/experiments/plugin-arch/README.md create mode 100755 docs/zh/experiments/plugin-arch/run.sh create mode 100644 docs/zh/架构迁移评估.md diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01a/main.go b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01a/main.go new file mode 100644 index 0000000..fbe6a40 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01a/main.go @@ -0,0 +1,72 @@ +//go:build ignore + +package main + +/* +#cgo LDFLAGS: -ldl +#include +#include +typedef const char* (*verfn)(void); +static const char* call_ver(void* f){ return ((verfn)f)(); } +*/ +import "C" +import ( + "fmt" + "os" + "unsafe" +) + +func main() { + // Go 用 dlopen 加载纯 C shim（shim 本身常驻，无所谓） + sp := C.CString("./shim.so") + shim := C.dlopen(sp, C.RTLD_NOW|C.RTLD_LOCAL) + C.free(unsafe.Pointer(sp)) + if shim == nil { + fmt.Println("shim 加载失败:", C.GoString(C.dlerror())) + os.Exit(1) + } + openName := C.CString("shim_open") + closeName := C.CString("shim_close") + symName := C.CString("shim_sym") + shimOpen := C.dlsym(shim, openName) + shimClose := C.dlsym(shim, closeName) + shimSym := C.dlsym(shim, symName) + C.free(unsafe.Pointer(openName)) + C.free(unsafe.Pointer(closeName)) + C.free(unsafe.Pointer(symName)) + fmt.Printf("shim 就绪: open=%p close=%p sym=%p\n\n", shimOpen, shimClose, shimSym) + + // 直接用 dlopen/dlsym 调 shim 的三个函数（避免再写一层 C 包装） + load := func(path string) unsafe.Pointer { + cp := C.CString(path) + defer C.free(unsafe.Pointer(cp)) + return C.dlopen(cp, C.RTLD_NOW|C.RTLD_LOCAL) + } + ver := func(h unsafe.Pointer) string { + n := C.CString("probe_version") + defer C.free(unsafe.Pointer(n)) + f := C.dlsym(h, n) + if f == nil { return "" } + return C.GoString(C.call_ver(f)) + } + + fmt.Println("--- 场景: Go(带 NODELETE runtime) 加载/卸载纯 C 的第三层 so ---") + h1 := load("./probe.so") + fmt.Printf("1) dlopen probe.so handle=%p version=%s\n", h1, ver(h1)) + + rc := C.dlclose(h1) + fmt.Printf("2) dlclose rc=%d\n", int(rc)) + + // 换内容（V1 -> V2），同路径 + in, _ := os.ReadFile("probe_v2.so") + os.WriteFile("probe.so", in, 0755) + fmt.Println("3) 磁盘 probe.so 内容替换为 V2（同路径）") + + h2 := load("./probe.so") + fmt.Printf("4) 再 dlopen 同路径 handle=%p version=%s\n", h2, ver(h2)) + if h1 == h2 { + fmt.Println(" => 句柄相同：未卸载，仍是旧代码") + } else { + fmt.Println(" => 句柄不同：真正卸载并重新装载了新代码 ✅") + } +} diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01b/main.go b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01b/main.go new file mode 100644 index 0000000..8f32abc --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01b/main.go @@ -0,0 +1,49 @@ +//go:build ignore + +package main + +/* +#cgo LDFLAGS: -ldl +#include +#include +typedef void* (*openfn)(const char*); +typedef int (*closefn)(void*); +static void* c_open(void* f, const char* p){ return ((openfn)f)(p); } +static int c_close(void* f, void* h){ return ((closefn)f)(h); } +*/ +import "C" +import ( + "fmt" + "os" + "strings" + "unsafe" +) + +func cnt(s string) int { + b, _ := os.ReadFile("/proc/self/maps") + n := 0 + for _, l := range strings.Split(string(b), "\n") { if strings.Contains(l, s) { n++ } } + return n +} + +func main() { + sp := C.CString("./shim.so") + shim := C.dlopen(sp, C.RTLD_NOW|C.RTLD_LOCAL) + C.free(unsafe.Pointer(sp)) + no := C.CString("shim_open"); nc := C.CString("shim_close") + fo := C.dlsym(shim, no); fc := C.dlsym(shim, nc) + C.free(unsafe.Pointer(no)); C.free(unsafe.Pointer(nc)) + + // 经【纯 C shim】去 dlopen/dlclose Go c-shared 插件 + qp := C.CString("/home/newqqagent/plugins/qq/plugin.so") + h := C.c_open(fo, qp) + C.free(unsafe.Pointer(qp)) + fmt.Printf("经 C shim dlopen Go 插件 handle=%p 映射段=%d\n", h, cnt("qq/plugin.so")) + rc := C.c_close(fc, h) + fmt.Printf("经 C shim dlclose rc=%d 映射段=%d\n", int(rc), cnt("qq/plugin.so")) + if cnt("qq/plugin.so") > 0 { + fmt.Println("\n❌ 仍未卸载 —— NODELETE 属于目标 .so 本身，与谁调 dlopen 无关") + } else { + fmt.Println("\n✅ 卸载成功") + } +} diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01c/main.go b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01c/main.go new file mode 100644 index 0000000..c1c0ed6 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/exp01c/main.go @@ -0,0 +1,58 @@ +//go:build ignore + +package main + +/* +#cgo LDFLAGS: -ldl +#include +#include +typedef char* (*verfn)(void); +static char* call_ver(void* f){ return ((verfn)f)(); } +*/ +import "C" +import ( + "fmt" + "os" + "strings" + "unsafe" +) + +func threads() int { + e, _ := os.ReadDir("/proc/self/task") + return len(e) +} +func rss() int { + b, _ := os.ReadFile("/proc/self/status") + for _, l := range strings.Split(string(b), "\n") { + if strings.HasPrefix(l, "VmRSS:") { + var k int + fmt.Sscanf(l, "VmRSS: %d kB", &k) + return k + } + } + return 0 +} +func main() { + base, baseT := rss(), threads() + fmt.Printf("基线: RSS=%dKB threads=%d\n\n", base, baseT) + src, _ := os.ReadFile("glv1.so") + os.MkdirAll("stress", 0755) + var hs []unsafe.Pointer + for i := 1; i <= 30; i++ { + p := fmt.Sprintf("stress/%010d-qq.so", 1700000000+i) + os.WriteFile(p, src, 0755) + cp := C.CString("./" + p) + h := C.dlopen(cp, C.RTLD_NOW|C.RTLD_LOCAL) + C.free(unsafe.Pointer(cp)) + if h == nil { fmt.Printf("第 %d 次失败\n", i); break } + hs = append(hs, h) + C.dlclose(h) // 模拟每次都尝试卸载（no-op） + if i%10 == 0 { + fmt.Printf("第 %2d 次重载: RSS=%dKB (+%dKB) threads=%d (+%d)\n", + i, rss(), rss()-base, threads(), threads()-baseT) + } + } + fmt.Printf("\n30 次重载后: RSS 增长 %dKB, 线程增长 %d\n", rss()-base, threads()-baseT) + fmt.Printf("每次重载均摊: RSS +%.1fKB, 线程 +%.2f\n", + float64(rss()-base)/30, float64(threads()-baseT)/30) +} diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v1.c b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v1.c new file mode 100644 index 0000000..f937edb --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v1.c @@ -0,0 +1,2 @@ +#include +const char* probe_version(void){ return "V1"; } diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v2.c b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v2.c new file mode 100644 index 0000000..908d970 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/probe_v2.c @@ -0,0 +1,2 @@ +#include +const char* probe_version(void){ return "V2"; } diff --git a/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/shim.c b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/shim.c new file mode 100644 index 0000000..9425842 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/01-dlclose-nodelete/shim.c @@ -0,0 +1,9 @@ +#include +#include +void* shim_open(const char* p){ + void* h = dlopen(p, RTLD_NOW|RTLD_LOCAL); + if(!h) printf(" [shim] open FAIL: %s\n", dlerror()); + return h; +} +int shim_close(void* h){ return dlclose(h); } +void* shim_sym(void* h, const char* n){ return dlsym(h, n); } diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp10.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp10.go new file mode 100644 index 0000000..2a519c7 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp10.go @@ -0,0 +1,49 @@ +//go:build ignore +package main + +import ( + "encoding/base64" + "encoding/json" + "fmt" + "time" + + "golang.org/x/sys/unix" +) + +func main() { + fmt.Println("=== 实验 10：多媒体 payload —— 共享内存零拷贝 vs JSON base64 ===") + sizes := []int{100 * 1024, 1024 * 1024, 5 * 1024 * 1024} + for _, sz := range sizes { + img := make([]byte, sz) + for i := range img { img[i] = byte(i % 251) } + + // A. JSON + base64（当前 ContentBlock 的做法） + t0 := time.Now() + b64 := base64.StdEncoding.EncodeToString(img) + blob, _ := json.Marshal(map[string]string{"type": "image_url", "url": "data:image/png;base64," + b64}) + var back map[string]string + json.Unmarshal(blob, &back) + dec, _ := base64.StdEncoding.DecodeString(back["url"][22:]) + jsonDur := time.Since(t0) + + // B. 共享内存 arena（写入 + 偏移解引用，零拷贝读） + mfd, _ := unix.MemfdCreate("arena", 0) + unix.Ftruncate(mfd, int64(sz+4096)) + data, _ := unix.Mmap(mfd, 0, sz+4096, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + t0 = time.Now() + copy(data[4096:], img) // 写 arena + view := data[4096 : 4096+sz] // 偏移解引用 = 零拷贝切片 + _ = view[sz-1] + shmDur := time.Since(t0) + unix.Munmap(data) + unix.Close(mfd) + + fmt.Printf("\n%s payload:\n", map[int]string{100*1024:"100KB", 1024*1024:"1MB", 5*1024*1024:"5MB"}[sz]) + fmt.Printf(" A JSON+base64: %8v 传输体积 %d B (+%.0f%%) 解出 %d B %s\n", + jsonDur, len(blob), float64(len(blob)-sz)/float64(sz)*100, len(dec), + map[bool]string{true:"✓",false:"✗"}[len(dec)==sz]) + fmt.Printf(" B 共享内存: %8v 传输体积 8 B (描述符) 零拷贝视图 %d B\n", shmDur, len(view)) + fmt.Printf(" → 加速 %.0fx, 体积节省 %.0f%%\n", + float64(jsonDur)/float64(shmDur), float64(len(blob)-8)/float64(len(blob))*100) + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp11.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp11.go new file mode 100644 index 0000000..439995f --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp11.go @@ -0,0 +1,42 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os/exec" + "sort" + "time" +) + +type Req struct{ ID int `json:"id"`; Method string `json:"method"`; Args json.RawMessage `json:"args"` } +type Res struct{ ID int `json:"id"`; Result string `json:"result"` } + +func main() { + fmt.Println("=== 实验 11：工具调用 RPC 端到端延迟（实测 payload 中位 93B）===") + cmd := exec.Command("./plug11") + sin, _ := cmd.StdinPipe(); sout, _ := cmd.StdoutPipe() + cmd.Start() + enc := json.NewEncoder(bufio.NewWriter(sin)) + w := bufio.NewWriter(sin); enc = json.NewEncoder(w) + dec := json.NewDecoder(bufio.NewReader(sout)) + + args := json.RawMessage(`{"city":"hangzhou","days":3,"unit":"celsius","detail":true}`) + const N = 10000 + lat := make([]time.Duration, 0, N) + for i := 0; i < N; i++ { + t0 := time.Now() + enc.Encode(Req{ID: i, Method: "weather_query", Args: args}); w.Flush() + var r Res + if err := dec.Decode(&r); err != nil { break } + lat = append(lat, time.Since(t0)) + } + sin.Close(); cmd.Wait() + sort.Slice(lat, func(a,b int) bool { return lat[a] < lat[b] }) + p := func(q float64) time.Duration { return lat[int(float64(len(lat))*q)] } + fmt.Printf("样本 %d 次\n", len(lat)) + fmt.Printf(" p50 = %v\n p90 = %v\n p99 = %v\n max = %v\n", p(0.5), p(0.9), p(0.99), lat[len(lat)-1]) + fmt.Printf("\n对照 LLM 单轮往返 2-8 秒 → RPC 占比 ≈ %.5f%%\n", + float64(p(0.5))/float64(3*time.Second)*100) +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp11_plug.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp11_plug.go new file mode 100644 index 0000000..586342d --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp11_plug.go @@ -0,0 +1,12 @@ +//go:build ignore +package main +import ("bufio";"encoding/json";"os") +type Req struct{ ID int `json:"id"`; Method string `json:"method"`; Args json.RawMessage `json:"args"` } +type Res struct{ ID int `json:"id"`; Result string `json:"result"` } +func main(){ + dec:=json.NewDecoder(bufio.NewReader(os.Stdin)) + w:=bufio.NewWriter(os.Stdout); enc:=json.NewEncoder(w) + for { var q Req + if err:=dec.Decode(&q); err!=nil {return} + enc.Encode(Res{ID:q.ID, Result:`{"ok":true,"data":"` + string(q.Args) + `"}`}); w.Flush() } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp1_eventfd.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp1_eventfd.go new file mode 100644 index 0000000..89d1e33 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp1_eventfd.go @@ -0,0 +1,58 @@ +//go:build ignore +package main + +import ( + "fmt" + "os" + "runtime" + "sync" + "sync/atomic" + "time" + + "golang.org/x/sys/unix" +) + +func threads() int { e, _ := os.ReadDir("/proc/self/task"); return len(e) } + +func main() { + fmt.Println("=== 实验 1：eventfd 是否走 Go netpoller（只 park goroutine 不占 OS 线程）===") + base := threads() + fmt.Printf("基线线程数: %d (GOMAXPROCS=%d)\n\n", base, runtime.GOMAXPROCS(0)) + + const N = 200 // 模拟 200 个订阅者等待 + var wg sync.WaitGroup + var woke int64 + files := make([]*os.File, N) + + for i := 0; i < N; i++ { + efd, err := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC) + if err != nil { fmt.Println("eventfd 失败:", err); return } + f := os.NewFile(uintptr(efd), fmt.Sprintf("evt%d", i)) + files[i] = f + wg.Add(1) + go func(f *os.File) { + defer wg.Done() + buf := make([]byte, 8) + // 阻塞读：若走 netpoller 只 park goroutine + if _, err := f.Read(buf); err == nil { + atomic.AddInt64(&woke, 1) + } + }(f) + } + + time.Sleep(500 * time.Millisecond) // 让所有 goroutine 进入等待 + waiting := threads() + fmt.Printf("%d 个 goroutine 阻塞在 eventfd.Read 后:\n", N) + fmt.Printf(" 线程数 = %d (增长 %d)\n", waiting, waiting-base) + if waiting-base < 20 { + fmt.Println(" ✅ 走 netpoller：线程未随等待者数量增长") + } else { + fmt.Printf(" ❌ 退化为阻塞 syscall：每个等待者占一个 OS 线程\n") + } + + // 全部唤醒 + one := []byte{1,0,0,0,0,0,0,0} + for _, f := range files { f.Write(one) } + wg.Wait() + fmt.Printf("\n唤醒数 = %d/%d 唤醒后线程数 = %d\n", woke, N, threads()) +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp2_child.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp2_child.go new file mode 100644 index 0000000..f81e782 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp2_child.go @@ -0,0 +1,41 @@ +//go:build ignore +package main + +import ( + "encoding/binary" + "fmt" + "os" + "unsafe" + + "golang.org/x/sys/unix" +) + +// 子进程：fd 3 = eventfd(通知), fd 4 = shm 文件 +func main() { + efd := os.NewFile(3, "evt") + shmf := os.NewFile(4, "shm") + + data, err := unix.Mmap(int(shmf.Fd()), 0, 4096, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { fmt.Println("CHILD mmap 失败:", err); os.Exit(1) } + fmt.Printf("CHILD: mmap 基址 = %p\n", unsafe.Pointer(&data[0])) + + buf := make([]byte, 8) + if _, err := efd.Read(buf); err != nil { + fmt.Println("CHILD read err:", err); os.Exit(1) + } + n := binary.LittleEndian.Uint64(buf) + fmt.Printf("CHILD: 被 eventfd 唤醒, 计数=%d\n", n) + + // 按偏移读：头部 16 字节 = {off uint32, len uint32, seq uint64} + off := binary.LittleEndian.Uint32(data[0:4]) + ln := binary.LittleEndian.Uint32(data[4:8]) + seq := binary.LittleEndian.Uint64(data[8:16]) + payload := string(data[off : off+ln]) + fmt.Printf("CHILD: 偏移解引用 off=%d len=%d seq=%d → %q\n", off, ln, seq, payload) + + // 子进程回写（验证双向可见） + copy(data[2048:], []byte("CHILD-ACK")) + binary.LittleEndian.PutUint32(data[16:20], 2048) + binary.LittleEndian.PutUint32(data[20:24], uint32(len("CHILD-ACK"))) + fmt.Println("CHILD: 已回写 ACK") +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp2_parent.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp2_parent.go new file mode 100644 index 0000000..ad3dc34 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp2_parent.go @@ -0,0 +1,60 @@ +//go:build ignore +package main + +import ( + "encoding/binary" + "fmt" + "os" + "os/exec" + "time" + "unsafe" + + "golang.org/x/sys/unix" +) + +func main() { + fmt.Println("=== 实验 2：跨进程 eventfd 通知 + 共享内存偏移解引用 ===") + + // eventfd 不带 CLOEXEC（需要被子进程继承） + efd, err := unix.Eventfd(0, unix.EFD_NONBLOCK) + if err != nil { panic(err) } + evtFile := os.NewFile(uintptr(efd), "evt") + + // shm: 用 memfd（匿名，无需 /dev/shm 清理） + mfd, err := unix.MemfdCreate("stagectx", 0) + if err != nil { panic(err) } + if err := unix.Ftruncate(mfd, 4096); err != nil { panic(err) } + shmFile := os.NewFile(uintptr(mfd), "shm") + + data, err := unix.Mmap(mfd, 0, 4096, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { panic(err) } + fmt.Printf("PARENT: mmap 基址 = %p\n", unsafe.Pointer(&data[0])) + + // 写 payload 到 arena(偏移 1024)，头部记描述符 + msg := "hello-from-parent-via-offset" + copy(data[1024:], []byte(msg)) + binary.LittleEndian.PutUint32(data[0:4], 1024) + binary.LittleEndian.PutUint32(data[4:8], uint32(len(msg))) + binary.LittleEndian.PutUint64(data[8:16], 42) + fmt.Printf("PARENT: 数据已落地 arena@1024, 描述符 {off:1024, len:%d, seq:42}\n", len(msg)) + + cmd := exec.Command("go", "run", "exp2_child.go") + cmd.ExtraFiles = []*os.File{evtFile, shmFile} // → 子进程 fd 3, 4 + cmd.Stdout, cmd.Stderr = os.Stdout, os.Stderr + if err := cmd.Start(); err != nil { panic(err) } + + time.Sleep(3 * time.Second) // 等 go run 编译+启动 + fmt.Println("PARENT: 数据到位后 post eventfd（不等待消费者）") + t0 := time.Now() + evtFile.Write([]byte{1,0,0,0,0,0,0,0}) + fmt.Printf("PARENT: post 耗时 %v ← post-and-forget\n", time.Since(t0)) + + cmd.Wait() + + // 读子进程回写 + off := binary.LittleEndian.Uint32(data[16:20]) + ln := binary.LittleEndian.Uint32(data[20:24]) + if ln > 0 { + fmt.Printf("PARENT: 读到子进程回写 → %q ✅ 双向可见\n", string(data[off:off+ln])) + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp3_child.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp3_child.go new file mode 100644 index 0000000..6fad0d8 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp3_child.go @@ -0,0 +1,31 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os" + "time" +) + +type req struct{ ID int `json:"id"`; Method string `json:"method"` } +type resp struct{ ID int `json:"id"`; OK bool `json:"ok"` } + +func main() { + in := bufio.NewReader(os.Stdin) + out := bufio.NewWriter(os.Stdout) + enc, dec := json.NewEncoder(out), json.NewDecoder(in) + + const N = 20000 + t0 := time.Now() + for i := 0; i < N; i++ { + enc.Encode(req{ID: i, Method: "stage.lock"}) + out.Flush() + var r resp + if err := dec.Decode(&r); err != nil { fmt.Fprintln(os.Stderr, "dec:", err); return } + } + d := time.Since(t0) + fmt.Fprintf(os.Stderr, "CHILD: %d 次 lock RPC 往返 用时 %v, 均摊 %.2f µs/次\n", + N, d, float64(d.Microseconds())/float64(N)) +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp3_parent.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp3_parent.go new file mode 100644 index 0000000..5e7d88d --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp3_parent.go @@ -0,0 +1,37 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os" + "os/exec" + "sync" +) + +type req struct{ ID int `json:"id"`; Method string `json:"method"` } +type resp struct{ ID int `json:"id"`; OK bool `json:"ok"` } + +func main() { + fmt.Println("=== 实验 3：锁仲裁 RPC 往返成本（stdio JSON-RPC）===") + cmd := exec.Command("go", "run", "exp3_child.go") + stdin, _ := cmd.StdinPipe() + stdout, _ := cmd.StdoutPipe() + cmd.Stderr = os.Stderr + cmd.Start() + + var mu sync.Mutex // 内核侧真实的锁仲裁 + dec := json.NewDecoder(bufio.NewReader(stdout)) + w := bufio.NewWriter(stdin) + enc := json.NewEncoder(w) + for { + var q req + if err := dec.Decode(&q); err != nil { break } + mu.Lock() // 真实加锁 + mu.Unlock() // 立即释放（模拟仲裁开销） + enc.Encode(resp{ID: q.ID, OK: true}) + w.Flush() + } + cmd.Wait() +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp4.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp4.go new file mode 100644 index 0000000..acc7143 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp4.go @@ -0,0 +1,71 @@ +//go:build ignore +package main + +import ( + "fmt" + "os" + "sync/atomic" + "time" + + "golang.org/x/sys/unix" +) + +type ring struct { + writeSeq atomic.Uint64 + cap uint64 + slots []uint64 +} + +func main() { + fmt.Println("=== 实验 4：事件环 post-and-forget vs 同步 Publish（慢消费者场景）===") + const tokens = 5000 + + // --- A. 现状：同步 Publish，消费者慢 --- + slowHandler := func() { time.Sleep(20 * time.Microsecond) } + t0 := time.Now() + for i := 0; i < tokens; i++ { slowHandler() } + syncDur := time.Since(t0) + fmt.Printf("A 同步 Publish (慢消费者 20µs): %d token 耗时 %v → 均摊 %.1f µs/token\n", + tokens, syncDur, float64(syncDur.Microseconds())/tokens) + + // --- B. 新方案：写环 + eventfd post，不等消费者 --- + r := &ring{cap: 1024, slots: make([]uint64, 1024)} + efd, _ := unix.Eventfd(0, unix.EFD_NONBLOCK) + f := os.NewFile(uintptr(efd), "e") + + var dropped atomic.Uint64 + // 慢消费者 goroutine + done := make(chan struct{}) + go func() { + buf := make([]byte, 8) + var readSeq uint64 + for { + if _, err := f.Read(buf); err != nil { return } + w := r.writeSeq.Load() + if w-readSeq > r.cap { + dropped.Add(w - readSeq - r.cap) + readSeq = w - r.cap + } + for readSeq < w { readSeq++ } + time.Sleep(20 * time.Microsecond) // 慢 + select { case <-done: return; default: } + } + }() + + t0 = time.Now() + one := []byte{1,0,0,0,0,0,0,0} + for i := 0; i < tokens; i++ { + s := r.writeSeq.Add(1) + r.slots[s%r.cap] = s // 写数据 + f.Write(one) // post，不等 + } + asyncDur := time.Since(t0) + close(done) + fmt.Printf("B 环+eventfd post: %d token 耗时 %v → 均摊 %.2f µs/token\n", + tokens, asyncDur, float64(asyncDur.Microseconds())/tokens) + fmt.Printf("\n加速比 %.1fx 丢弃事件 %d（消费者跟不上，已计数）\n", + float64(syncDur)/float64(asyncDur), dropped.Load()) + if asyncDur < syncDur/5 { + fmt.Println("✅ post-and-forget 使流式发布与消费者速度解耦") + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp5.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp5.go new file mode 100644 index 0000000..332b7d2 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp5.go @@ -0,0 +1,55 @@ +//go:build ignore +package main + +import ( + "fmt" + "os" + "os/exec" + "strconv" + "strings" + "time" +) + +func pssKB(pid int) int { + b, err := os.ReadFile(fmt.Sprintf("/proc/%d/smaps_rollup", pid)) + if err != nil { return 0 } + for _, l := range strings.Split(string(b), "\n") { + if strings.HasPrefix(l, "Pss:") { + f := strings.Fields(l) + n, _ := strconv.Atoi(f[1]); return n + } + } + return 0 +} +func threads(pid int) int { + e, _ := os.ReadDir(fmt.Sprintf("/proc/%d/task", pid)); return len(e) +} + +func main() { + fmt.Println("=== 实验 5：17 个 Go 子进程插件的真实常驻开销（PSS 计入共享页去重）===") + var cmds []*exec.Cmd + for i := 0; i < 17; i++ { + c := exec.Command("./plugbin") + c.Stdin, _ = os.Open(os.DevNull) + if err := c.Start(); err != nil { fmt.Println("start:", err); return } + cmds = append(cmds, c) + } + time.Sleep(1500 * time.Millisecond) + + totalPss, totalThreads := 0, 0 + for _, c := range cmds { + totalPss += pssKB(c.Process.Pid) + totalThreads += threads(c.Process.Pid) + } + fmt.Printf("17 进程合计: PSS = %.1f MB, 线程 = %d\n", float64(totalPss)/1024, totalThreads) + fmt.Printf("单进程均摊: PSS = %.2f MB, 线程 = %.1f\n", + float64(totalPss)/1024/17, float64(totalThreads)/17) + fmt.Printf("\n对照 homed 当前（单进程装 17 个 .so）:\n") + // 找 homed + out, _ := exec.Command("pgrep", "-x", "homed").Output() + if p := strings.TrimSpace(string(out)); p != "" { + pid, _ := strconv.Atoi(strings.Fields(p)[0]) + fmt.Printf(" homed PSS = %.1f MB, 线程 = %d\n", float64(pssKB(pid))/1024, threads(pid)) + } + for _, c := range cmds { c.Process.Kill(); c.Wait() } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp5_plugin.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp5_plugin.go new file mode 100644 index 0000000..28e294f --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp5_plugin.go @@ -0,0 +1,23 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "os" +) + +// 模拟一个最小插件：stdio JSON-RPC loop + 一个 goroutine +func main() { + go func() { select {} }() + in := bufio.NewReader(os.Stdin) + dec := json.NewDecoder(in) + out := bufio.NewWriter(os.Stdout) + enc := json.NewEncoder(out) + for { + var m map[string]interface{} + if err := dec.Decode(&m); err != nil { return } + enc.Encode(map[string]interface{}{"ok": true}) + out.Flush() + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp5b.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp5b.go new file mode 100644 index 0000000..e974e93 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp5b.go @@ -0,0 +1,68 @@ +//go:build ignore +package main + +import ( + "fmt" + "os" + "os/exec" + "strconv" + "strings" + "time" +) + +func pssKB(pid int) int { + b, err := os.ReadFile(fmt.Sprintf("/proc/%d/smaps_rollup", pid)) + if err != nil { return -1 } + for _, l := range strings.Split(string(b), "\n") { + if strings.HasPrefix(l, "Pss:") { f := strings.Fields(l); n,_ := strconv.Atoi(f[1]); return n } + } + return -1 +} +func rssKB(pid int) int { + b, err := os.ReadFile(fmt.Sprintf("/proc/%d/status", pid)) + if err != nil { return -1 } + for _, l := range strings.Split(string(b), "\n") { + if strings.HasPrefix(l, "VmRSS:") { f := strings.Fields(l); n,_ := strconv.Atoi(f[1]); return n } + } + return -1 +} +func threads(pid int) int { e,_ := os.ReadDir(fmt.Sprintf("/proc/%d/task", pid)); return len(e) } + +func main() { + fmt.Println("=== 实验 5b：17 个 Go 子进程常驻开销（保持 stdin 管道存活）===") + var cmds []*exec.Cmd + var pipes []interface{ Close() error } + for i := 0; i < 17; i++ { + c := exec.Command("./plugbin") + w, _ := c.StdinPipe() // 保持打开 → 不 EOF + pipes = append(pipes, w) + c.Stdout = nil + if err := c.Start(); err != nil { fmt.Println(err); return } + cmds = append(cmds, c) + } + time.Sleep(2 * time.Second) + + tp, tr, tt, alive := 0, 0, 0, 0 + for _, c := range cmds { + pid := c.Process.Pid + if _, err := os.Stat(fmt.Sprintf("/proc/%d", pid)); err != nil { continue } + alive++ + if v := pssKB(pid); v > 0 { tp += v } + if v := rssKB(pid); v > 0 { tr += v } + tt += threads(pid) + } + fmt.Printf("存活进程 %d/17\n", alive) + fmt.Printf("合计: PSS=%.1f MB RSS=%.1f MB 线程=%d\n", + float64(tp)/1024, float64(tr)/1024, tt) + if alive > 0 { + fmt.Printf("均摊: PSS=%.2f MB RSS=%.2f MB 线程=%.1f\n", + float64(tp)/1024/float64(alive), float64(tr)/1024/float64(alive), float64(tt)/float64(alive)) + } + out, _ := exec.Command("pgrep", "-x", "homed").Output() + if p := strings.TrimSpace(string(out)); p != "" { + pid, _ := strconv.Atoi(strings.Fields(p)[0]) + fmt.Printf("\n对照 homed（单进程 + 17 个 .so）: RSS=%.1f MB 线程=%d\n", + float64(rssKB(pid))/1024, threads(pid)) + } + for _, c := range cmds { c.Process.Kill(); c.Wait() } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp6.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp6.go new file mode 100644 index 0000000..e8540d6 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp6.go @@ -0,0 +1,49 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "os/exec" + "time" +) + +func main() { + fmt.Println("=== 实验 6：子进程崩溃隔离 + 退出码/EOF 作为 recordCrash 信号 ===") + cmd := exec.Command("./crashbin") + sin, _ := cmd.StdinPipe() + sout, _ := cmd.StdoutPipe() + cmd.Stderr = nil // 丢弃 panic 栈 + cmd.Start() + fmt.Printf("插件进程 pid=%d 已启动\n", cmd.Process.Pid) + + enc := json.NewEncoder(sin) + dec := json.NewDecoder(bufio.NewReader(sout)) + + // 正常调用 + enc.Encode(map[string]string{"method": "ping"}) + var r map[string]interface{} + if err := dec.Decode(&r); err == nil { fmt.Println("正常调用 → ", r) } + + // 触发崩溃 + fmt.Println("\n发送 boom（插件内 panic）...") + t0 := time.Now() + enc.Encode(map[string]string{"method": "boom"}) + err := dec.Decode(&r) + + detected := "未检测到" + if errors.Is(err, io.EOF) || err == io.ErrUnexpectedEOF { detected = "EOF" } else if err != nil { detected = fmt.Sprintf("%v", err) } + fmt.Printf("调用侧感知: %s (耗时 %v)\n", detected, time.Since(t0)) + + werr := cmd.Wait() + var ec int = -1 + if ee, ok := werr.(*exec.ExitError); ok { ec = ee.ExitCode() } + fmt.Printf("进程退出码 = %d （panic → 2，可直接喂 recordCrash）\n", ec) + + fmt.Printf("\n宿主进程仍存活: pid=%d ✅ 崩溃已隔离\n", os.Getpid()) + fmt.Println("→ 对照：当前 .so 模型下，bridge 兜不住的 panic 会带崩整个 homed") +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp6_crash.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp6_crash.go new file mode 100644 index 0000000..dbf7ed6 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp6_crash.go @@ -0,0 +1,23 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "os" +) + +func main() { + dec := json.NewDecoder(bufio.NewReader(os.Stdin)) + out := bufio.NewWriter(os.Stdout) + enc := json.NewEncoder(out) + for { + var m map[string]interface{} + if err := dec.Decode(&m); err != nil { return } + if m["method"] == "boom" { + panic("插件故意崩溃") // 真 panic + } + enc.Encode(map[string]interface{}{"ok": true}) + out.Flush() + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp7.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp7.go new file mode 100644 index 0000000..c25f84f --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp7.go @@ -0,0 +1,63 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os" + "os/exec" + "time" +) + +func spawnAndAsk(bin string) string { + cmd := exec.Command(bin) + sin, _ := cmd.StdinPipe() + sout, _ := cmd.StdoutPipe() + cmd.Start() + enc := json.NewEncoder(sin) + dec := json.NewDecoder(bufio.NewReader(sout)) + enc.Encode(map[string]string{"method": "version"}) + var r map[string]interface{} + dec.Decode(&r) + sin.Close() + cmd.Process.Kill() + cmd.Wait() + if v, ok := r["version"].(string); ok { return v } + return "?" +} + +func build(ver, out string) { + src := fmt.Sprintf(`package main +import ("bufio";"encoding/json";"os") +func main(){ + dec:=json.NewDecoder(bufio.NewReader(os.Stdin)) + w:=bufio.NewWriter(os.Stdout); enc:=json.NewEncoder(w) + for { var m map[string]interface{} + if err:=dec.Decode(&m); err!=nil {return} + enc.Encode(map[string]string{"version":%q}); w.Flush() } +}`, ver) + os.MkdirAll("v", 0755) + os.WriteFile("v/main.go", []byte(src), 0644) + os.WriteFile("v/go.mod", []byte("module v\ngo 1.21\n"), 0644) + c := exec.Command("go", "build", "-o", "../"+out, ".") + c.Dir = "v" + if b, err := c.CombinedOutput(); err != nil { fmt.Println("build err:", string(b)) } +} + +func main() { + fmt.Println("=== 实验 7：子进程模型下的热重载（迁移的原始目标）===") + build("v1.0.0", "hotbin") + fmt.Printf("1) 首次启动插件 → version = %s\n", spawnAndAsk("./hotbin")) + + fmt.Println("2) 替换二进制为 v2.0.0（同路径，无需版本化 hash 目录）") + build("v2.0.0", "hotbin") + time.Sleep(200 * time.Millisecond) + + v := spawnAndAsk("./hotbin") + fmt.Printf("3) 重启插件进程 → version = %s\n", v) + if v == "v2.0.0" { + fmt.Println("\n✅ 同路径替换即生效：无 NODELETE、无版本化路径、无线程泄漏") + fmt.Println(" 对照 .so 模型：同路径 dlopen 复用旧映像，永远拿不到 v2") + } +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp8.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp8.go new file mode 100644 index 0000000..a74d5eb --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp8.go @@ -0,0 +1,84 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/binary" + "encoding/json" + "fmt" + "os" + "os/exec" + "strings" + "sync" + "time" + + "golang.org/x/sys/unix" +) + +func main() { + fmt.Println("=== 实验 8：跨进程并发扇出改写同一 StageContext（最高风险点 3.4）===") + + mfd, _ := unix.MemfdCreate("stagectx", 0) + unix.Ftruncate(mfd, 65536) + shmFile := os.NewFile(uintptr(mfd), "shm") + data, _ := unix.Mmap(mfd, 0, 65536, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + + // 初始 final_text = "" @1024, arena 游标 = 1024 + binary.LittleEndian.PutUint32(data[0:4], 1024) + binary.LittleEndian.PutUint32(data[4:8], 0) + binary.LittleEndian.PutUint32(data[8:12], 1024) + + tags := []string{"A", "B", "C", "D", "E"} // 5 个并发插件 + var mu sync.Mutex // 内核侧锁仲裁 + var wg sync.WaitGroup + var rpcCount int64 + var cntMu sync.Mutex + + t0 := time.Now() + for _, tag := range tags { + cmd := exec.Command("go", "run", "exp8_worker.go", tag) + cmd.ExtraFiles = []*os.File{shmFile} + sin, _ := cmd.StdinPipe() + sout, _ := cmd.StdoutPipe() + cmd.Stderr = os.Stderr + cmd.Start() + wg.Add(1) + go func() { + defer wg.Done() + dec := json.NewDecoder(bufio.NewReader(sout)) + w := bufio.NewWriter(sin) + enc := json.NewEncoder(w) + held := false + for { + var q map[string]string + if err := dec.Decode(&q); err != nil { break } + switch q["method"] { + case "stage.lock": mu.Lock(); held = true + case "stage.unlock": if held { mu.Unlock(); held = false } + } + cntMu.Lock(); rpcCount++; cntMu.Unlock() + enc.Encode(map[string]bool{"ok": true}); w.Flush() + } + if held { mu.Unlock() } + cmd.Wait() + }() + } + wg.Wait() + dur := time.Since(t0) + + off := binary.LittleEndian.Uint32(data[0:4]) + ln := binary.LittleEndian.Uint32(data[4:8]) + final := string(data[off : off+ln]) + + fmt.Printf("\n--- 结果 ---\n") + fmt.Printf("最终 final_text 长度 = %d\n", len(final)) + counts := map[string]int{} + for _, t := range tags { counts[t] = strings.Count(final, t) } + fmt.Printf("各插件写入次数: %v\n", counts) + total := 0 + for _, c := range counts { total += c } + fmt.Printf("总字符 = %d, 长度 = %d → %s\n", total, len(final), + map[bool]string{true:"一致 ✅ 无丢失/无撕裂", false:"不一致 ❌"}[total == len(final)]) + fmt.Printf("RPC 锁操作 = %d 次, 总耗时 %v\n", rpcCount, dur) + fmt.Printf("\n注：写入次数少于 5×300 是 arena 64KB 上限所致（append-only 未压实），符合设计\n") +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp8_worker.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp8_worker.go new file mode 100644 index 0000000..336a75a --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp8_worker.go @@ -0,0 +1,50 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/binary" + "encoding/json" + "fmt" + "os" + "strconv" + + "golang.org/x/sys/unix" +) + +// 模拟插件：拿锁 → 读 final_text → 追加自己的标记 → 写回 → 放锁 +// 锁通过 stdio RPC 向内核申请（方案 3.7：锁仲裁回归内核，无 cgo） +func main() { + tag := os.Args[1] + shmf := os.NewFile(3, "shm") + data, err := unix.Mmap(int(shmf.Fd()), 0, 65536, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { fmt.Fprintln(os.Stderr, "mmap:", err); os.Exit(1) } + + dec := json.NewDecoder(bufio.NewReader(os.Stdin)) + w := bufio.NewWriter(os.Stdout) + enc := json.NewEncoder(w) + rpc := func(method string) { + enc.Encode(map[string]string{"method": method}); w.Flush() + var r map[string]interface{}; dec.Decode(&r) + } + + const iters = 300 + for i := 0; i < iters; i++ { + rpc("stage.lock") + // --- 临界区：偏移解引用读写 final_text --- + off := binary.LittleEndian.Uint32(data[0:4]) + ln := binary.LittleEndian.Uint32(data[4:8]) + cur := string(data[off : off+ln]) + add := tag + newS := cur + add + // append-only arena：写到新位置 + newOff := binary.LittleEndian.Uint32(data[8:12]) + if int(newOff)+len(newS) > 65536 { rpc("stage.unlock"); break } + copy(data[newOff:], []byte(newS)) + binary.LittleEndian.PutUint32(data[0:4], newOff) + binary.LittleEndian.PutUint32(data[4:8], uint32(len(newS))) + binary.LittleEndian.PutUint32(data[8:12], newOff+uint32(len(newS))) + rpc("stage.unlock") + } + fmt.Fprintln(os.Stderr, "worker "+tag+" done, iters="+strconv.Itoa(iters)) +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp9.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp9.go new file mode 100644 index 0000000..99a852c --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp9.go @@ -0,0 +1,60 @@ +//go:build ignore +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os/exec" + "sync" + "time" +) + +func run(name, arg string, mu *sync.Mutex, crashed *bool) { + cmd := exec.Command("go", "run", "exp9_worker.go", arg) + sin, _ := cmd.StdinPipe(); sout, _ := cmd.StdoutPipe() + cmd.Stderr = nil + cmd.Start() + dec := json.NewDecoder(bufio.NewReader(sout)) + w := bufio.NewWriter(sin); enc := json.NewEncoder(w) + held := false + for { + var q map[string]string + if err := dec.Decode(&q); err != nil { break } + switch q["method"] { + case "stage.lock": mu.Lock(); held = true; fmt.Printf(" [%s] 获得锁\n", name) + case "stage.unlock": if held { mu.Unlock(); held = false; fmt.Printf(" [%s] 释放锁\n", name) } + } + enc.Encode(map[string]bool{"ok":true}); w.Flush() + } + err := cmd.Wait() + // 关键：进程死了，内核侧检测到 EOF/退出 → 强制释放它持有的锁 + if held { + mu.Unlock() + *crashed = true + fmt.Printf(" [%s] 进程死亡(%v)，内核强制释放其持有的锁 ← 自愈\n", name, err) + } +} + +func main() { + fmt.Println("=== 实验 9：持锁进程崩溃后的自愈（验证无需 robust pthread_mutex）===") + var mu sync.Mutex + crashed := false + + fmt.Println("\n1) 插件 X 拿锁后 panic:") + run("X", "crash", &mu, &crashed) + + fmt.Println("\n2) 插件 Y 随后申请同一把锁:") + done := make(chan bool, 1) + go func() { run("Y", "normal", &mu, new(bool)); done <- true }() + select { + case <-done: + fmt.Println("\n✅ Y 正常获得并释放锁 —— 无死锁") + fmt.Println(" → 内核持有锁的所有权，进程死亡由 Wait()/EOF 检测并强制释放") + fmt.Println(" → 不需要 PTHREAD_PROCESS_SHARED|ROBUST，也不需要处理 EOWNERDEAD") + fmt.Println(" → 整个架构可做到零 cgo") + case <-time.After(15 * time.Second): + fmt.Println("\n❌ 死锁：Y 拿不到锁（说明需要 robust 语义）") + } + _ = crashed +} diff --git a/docs/zh/experiments/plugin-arch/02-feasibility/exp9_worker.go b/docs/zh/experiments/plugin-arch/02-feasibility/exp9_worker.go new file mode 100644 index 0000000..5794a1e --- /dev/null +++ b/docs/zh/experiments/plugin-arch/02-feasibility/exp9_worker.go @@ -0,0 +1,12 @@ +//go:build ignore +package main + +import ("bufio";"encoding/json";"os") +func main() { + dec := json.NewDecoder(bufio.NewReader(os.Stdin)) + w := bufio.NewWriter(os.Stdout); enc := json.NewEncoder(w) + rpc := func(m string) { enc.Encode(map[string]string{"method":m}); w.Flush(); var r map[string]interface{}; dec.Decode(&r) } + rpc("stage.lock") + if os.Args[1] == "crash" { panic("持锁时崩溃") } // 拿着锁死掉 + rpc("stage.unlock") +} diff --git a/docs/zh/experiments/plugin-arch/03-lost-update/exp12/main.go b/docs/zh/experiments/plugin-arch/03-lost-update/exp12/main.go new file mode 100644 index 0000000..3e9cc45 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/03-lost-update/exp12/main.go @@ -0,0 +1,90 @@ +//go:build ignore + +package main + +import ( + "encoding/json" + "fmt" + "strings" + "sync" +) + +// 完全复刻内核 loader.go case 2 + templates.go go_invoke_stage 的链路 +type StageCtx struct { + mu sync.RWMutex + LLMText string + ToolRes []string +} + +func (c *StageCtx) Lock() { c.mu.Lock() } +func (c *StageCtx) Unlock() { c.mu.Unlock() } +func (c *StageCtx) RLock() { c.mu.RLock() } +func (c *StageCtx) RUnlock() { c.mu.RUnlock() } + +// === 模拟外部插件（副本模型）=== +func externalPlugin(tag string, ctxJSON string) string { + // go_invoke_stage: 新建全新对象 + sc := &StageCtx{} + var m map[string]interface{} + json.Unmarshal([]byte(ctxJSON), &m) + if v, ok := m["llm_text"].(string); ok { sc.LLMText = v } + + // 插件 handler：ctx.Lock() 锁的是这个新对象 → 空转 + sc.Lock() + sc.LLMText = sc.LLMText + "[" + tag + "]" + sc.Unlock() + + out, _ := json.Marshal(map[string]interface{}{"llm_text": sc.LLMText}) + return string(out) +} + +// === 模拟内核 case 2 handler === +func kernelStageHandler(sc *StageCtx, tag string) { + sc.RLock() + snap, _ := json.Marshal(map[string]interface{}{"llm_text": sc.LLMText}) + sc.RUnlock() + + result := externalPlugin(tag, string(snap)) + + // applyStageResult + var m map[string]interface{} + json.Unmarshal([]byte(result), &m) + sc.Lock() + if v, ok := m["llm_text"].(string); ok { sc.LLMText = v } + sc.Unlock() +} + +// === 内置插件：直接改同一对象 === +func nativePlugin(sc *StageCtx, tag string) { + sc.Lock() + sc.LLMText = sc.LLMText + "[" + tag + "]" + sc.Unlock() +} + +func runCase(name string, fn func(*StageCtx, string), tags []string, rounds int) { + lost := 0 + for r := 0; r < rounds; r++ { + sc := &StageCtx{LLMText: "BASE"} + var wg sync.WaitGroup + for _, t := range tags { + wg.Add(1) + go func(t string) { defer wg.Done(); fn(sc, t) }(t) + } + wg.Wait() + // 检查是否所有 tag 都在 + for _, t := range tags { + if !strings.Contains(sc.LLMText, "["+t+"]") { lost++; break } + } + } + fmt.Printf(" %-28s %d/%d 轮出现修改丢失 (%.1f%%)\n", name, lost, rounds, float64(lost)/float64(rounds)*100) +} + +func main() { + tags := []string{"A", "B", "C", "D", "E"} + fmt.Println("5 个插件并发在 StageBeforeToolcall 追加标记，各 2000 轮：") + fmt.Println() + runCase("内置插件(共享同一对象)", nativePlugin, tags, 2000) + runCase("外部插件(快照-副本-写回)", kernelStageHandler, tags, 2000) + fmt.Println() + fmt.Println("→ 副本模型下 read-modify-write 非原子：快照与写回之间的窗口导致覆盖") +} diff --git a/docs/zh/experiments/plugin-arch/03-lost-update/exp13/main.go b/docs/zh/experiments/plugin-arch/03-lost-update/exp13/main.go new file mode 100644 index 0000000..aecc13c --- /dev/null +++ b/docs/zh/experiments/plugin-arch/03-lost-update/exp13/main.go @@ -0,0 +1,101 @@ +//go:build ignore + +package main + +// 精确复刻现网 AfterToolcall 上 sanitizer(Global,改写) + weather(OwnTools,只读) 的并发 +import ( + "encoding/json" + "fmt" + "strings" + "sync" +) + +type ToolResult struct { + Name string `json:"name"` + Plugin string `json:"plugin"` + Result interface{} `json:"result"` +} +type Ctx struct { + mu sync.RWMutex + ToolRes []ToolResult +} +func (c *Ctx) Lock(){c.mu.Lock()}; func (c *Ctx) Unlock(){c.mu.Unlock()} +func (c *Ctx) RLock(){c.mu.RLock()}; func (c *Ctx) RUnlock(){c.mu.RUnlock()} + +func cleanText(s string) string { + // 模拟 sanitizer：去掉 ANSI/坏字节 + return strings.ReplaceAll(s, "\x1b[31m", "") +} + +// 内核 case 2 handler（外部插件通用路径） +func kernelExternal(sc *Ctx, pluginFn func(*Ctx)) { + // 1. 快照 + sc.RLock() + snap, _ := json.Marshal(map[string]interface{}{"tool_results": sc.ToolRes}) + sc.RUnlock() + + // 2. go_invoke_stage: 插件进程内全新对象 + local := &Ctx{} + var m map[string]interface{} + json.Unmarshal(snap, &m) + if v, ok := m["tool_results"]; ok { + b, _ := json.Marshal(v) + json.Unmarshal(b, &local.ToolRes) + } + + // 3. 插件 handler 跑在副本上 + pluginFn(local) + + // 4. stageContextWritable: 无条件回传 tool_results + out := map[string]interface{}{} + if len(local.ToolRes) > 0 { out["tool_results"] = local.ToolRes } + rb, _ := json.Marshal(out) + + // 5. applyStageResult 写回内核 + var rm map[string]interface{} + json.Unmarshal(rb, &rm) + sc.Lock() + if v, ok := rm["tool_results"]; ok { + b, _ := json.Marshal(v) + var trs []ToolResult + if json.Unmarshal(b, &trs) == nil { sc.ToolRes = trs } + } + sc.Unlock() +} + +func sanitizerStage(ctx *Ctx) { + ctx.Lock(); defer ctx.Unlock() + for i, tr := range ctx.ToolRes { + if s, ok := tr.Result.(string); ok { + ctx.ToolRes[i].Result = cleanText(s) + } + } +} +func weatherStage(ctx *Ctx) { + ctx.Lock(); defer ctx.Unlock() + // 只读打印，不改（own_tools scope 已匹配） + _ = len(ctx.ToolRes) +} + +func main() { + const rounds = 3000 + dirty := "\x1b[31m晴 25°C" + polluted := 0 + for r := 0; r < rounds; r++ { + sc := &Ctx{ToolRes: []ToolResult{{Name:"weather_query", Plugin:"weather", Result: dirty}}} + var wg sync.WaitGroup + wg.Add(2) + go func(){ defer wg.Done(); kernelExternal(sc, sanitizerStage) }() + go func(){ defer wg.Done(); kernelExternal(sc, weatherStage) }() + wg.Wait() + if s, ok := sc.ToolRes[0].Result.(string); ok && strings.Contains(s, "\x1b[31m") { + polluted++ + } + } + fmt.Printf("现网场景复刻：模型调用 weather_query，sanitizer+weather 并发跑 AfterToolcall\n") + fmt.Printf(" %d 轮中 %d 轮清洗结果被覆盖 (%.1f%%)\n", rounds, polluted, float64(polluted)/rounds*100) + if polluted > 0 { + fmt.Printf("\n ⚠️ 确认：weather 回传的未清洗快照覆盖了 sanitizer 的清洗结果\n") + fmt.Printf(" → 脏数据（ANSI 转义）进入 LLM 上下文\n") + } +} diff --git a/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14a/main.go b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14a/main.go new file mode 100644 index 0000000..df399df --- /dev/null +++ b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14a/main.go @@ -0,0 +1,62 @@ +//go:build ignore + +package main + +/* +#cgo LDFLAGS: -ldl +#include +#include +typedef void (*fn)(void); +static void call(void* f){ ((fn)f)(); } +*/ +import "C" +import ( + "fmt" + "os" + "os/exec" + "runtime" + "time" + "unsafe" +) + +func threads() int { e,_ := os.ReadDir("/proc/self/task"); return len(e) } + +func main() { + fmt.Println("=== A. cgo 模型：插件死循环，超时后能回收吗？ ===") + p := C.CString("./hang.so"); h := C.dlopen(p, C.RTLD_NOW); C.free(unsafe.Pointer(p)) + n := C.CString("hang_forever"); f := C.dlsym(h, n); C.free(unsafe.Pointer(n)) + + base := threads() + fmt.Printf(" 基线: goroutines=%d threads=%d\n", runtime.NumGoroutine(), base) + + for i := 1; i <= 3; i++ { + done := make(chan string, 1) + go func() { C.call(f); done <- "ok" }() // 模拟 executeToolCallInner + select { + case <-done: + case <-time.After(600 * time.Millisecond): // 缩短的"60s 超时" + } + time.Sleep(200 * time.Millisecond) + fmt.Printf(" 第 %d 次超时后: goroutines=%d threads=%d (+%d)\n", + i, runtime.NumGoroutine(), threads(), threads()-base) + } + fmt.Println(" ❌ 每次超时永久泄漏 1 goroutine + 1 OS 线程（cgo 调用不可中断）") + + fmt.Println("\n=== B. 子进程模型：同样死循环，可强杀 ===") + base2 := threads() + for i := 1; i <= 3; i++ { + cmd := exec.Command("sleep", "3600") + cmd.Start() + done := make(chan error, 1) + go func() { done <- cmd.Wait() }() + select { + case <-done: + case <-time.After(300 * time.Millisecond): + cmd.Process.Kill() // ← 可强制终止 + <-done + } + fmt.Printf(" 第 %d 次超时+Kill 后: goroutines=%d threads=%d (+%d)\n", + i, runtime.NumGoroutine(), threads(), threads()-base2) + } + fmt.Println(" ✅ 零泄漏：进程被杀，OS 回收全部资源") +} diff --git a/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14b/main.go b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14b/main.go new file mode 100644 index 0000000..0e0f79e --- /dev/null +++ b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/exp14b/main.go @@ -0,0 +1,43 @@ +//go:build ignore + +package main + +/* +#cgo LDFLAGS: -ldl +#include +#include +typedef void (*fn)(void); +static void call(void* f){ ((fn)f)(); } +*/ +import "C" +import ( + "fmt" + "os" + "runtime" + "time" + "unsafe" +) + +func threads() int { e,_ := os.ReadDir("/proc/self/task"); return len(e) } + +func main() { + p := C.CString("./hang.so"); h := C.dlopen(p, C.RTLD_NOW); C.free(unsafe.Pointer(p)) + n := C.CString("hang_forever"); f := C.dlsym(h, n); C.free(unsafe.Pointer(n)) + base := threads() + fmt.Printf("基线 threads=%d goroutines=%d\n\n", base, runtime.NumGoroutine()) + for i := 1; i <= 20; i++ { + done := make(chan string, 1) + go func() { C.call(f); done <- "ok" }() + select { + case <-done: + case <-time.After(120 * time.Millisecond): + } + if i%5 == 0 { + fmt.Printf(" %2d 次卡死调用后: goroutines=%2d threads=%2d (+%d)\n", + i, runtime.NumGoroutine(), threads(), threads()-base) + } + } + fmt.Printf("\n结论: 20 次超时 → 泄漏 %d goroutine, %d OS 线程\n", + runtime.NumGoroutine()-1, threads()-base) + fmt.Println("每个卡在 cgo 里的 goroutine 独占一个 M（OS 线程），无法被抢占或回收") +} diff --git a/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/hang.c b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/hang.c new file mode 100644 index 0000000..14375d2 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/04-cgo-uninterruptible/hang.c @@ -0,0 +1,2 @@ +#include +void hang_forever(void) { while(1) sleep(1); } diff --git a/docs/zh/experiments/plugin-arch/README.md b/docs/zh/experiments/plugin-arch/README.md new file mode 100644 index 0000000..4dfae51 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/README.md @@ -0,0 +1,111 @@ +# 插件架构评估实验 + +[`../../架构迁移评估.md`](../../架构迁移评估.md) 中所有数字的来源。 +**18 项实验，一键复跑**，用于复核结论或在改动后验证回归。 + +```bash +./run.sh # 跑全部（约 3-5 分钟） +./run.sh 12 13 # 只跑指定实验 +./run.sh 1 1c # dlclose/NODELETE 组 +``` + +依赖：`go >= 1.21`、`gcc`、Linux（用到 `eventfd`/`memfd_create`/`dlopen`）。 +脚本在 `mktemp -d` 里构建，**不污染主仓 `go.mod`**；实验源码均带 `//go:build ignore`。 + +拉取 `golang.org/x/sys` 需要网络（实验 1/2/4/8/10）。本机走 clash： +```bash +export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 +``` + +## 目录 + +| 目录 | 主题 | 对应章节 | +|---|---|---| +| `01-dlclose-nodelete/` | `dlclose` 对 `DF_1_NODELETE` 是 no-op | 1.1 / 1.2 | +| `02-feasibility/` | 新架构可行性 11 项 | 第七章 | +| `03-lost-update/` | 副本模型的 lost update | 8.4 / 8.6 | +| `04-cgo-uninterruptible/` | cgo 调用不可中断 | 9.3 | + +## 实验清单与最近一次实测结果 + +复跑于 2026-08-31，go1.25.12 linux/amd64，192.168.2.60（12 核）。 + +### 01 组：dlclose / NODELETE + +| # | 实验 | 结论 | +|---|---|---| +| 1a | Go 宿主经纯 C shim 加载/卸载第三层 `.so` | 纯 C 目标可卸载；Go c-shared 目标仍不可 | +| 1b | `/proc/self/maps` 段数验证 | 纯 C: 5→**0**（真卸载）；Go c-shared: 5→**5** | +| 1c | 版本化路径 dlopen | handle 不同，`ver=v2` 生效（方案可行但泄漏，已否决） | + +**关键**：`DF_1_NODELETE` 属于**被卸载对象自身**的 ELF 属性， +与谁调用 `dlopen` 无关——套任何层数的 C 中间件都绕不过去。 + +### 02 组：新架构可行性 + +| # | 实验 | 最近结果 | +|---|---|---| +| 1 | eventfd 是否走 Go netpoller | 200 goroutine 阻塞 → 线程 **+0~1** ✅ | +| 2 | 跨进程 eventfd + 偏移解引用 | 父子 mmap 基址不同，偏移仍正确；post **10.9 µs** | +| 3 | 锁仲裁 RPC 往返成本 | **19.4 µs/次**（20000 次） | +| 4 | post-and-forget vs 同步 Publish | 5.07s → 2.29ms（**2218x**） | +| 5 | 17 子进程常驻开销 | **29.1MB RSS / 12.9MB PSS**，84 线程 | +| 6 | 子进程崩溃隔离 | 退出码 **2**，EOF **2.5ms** 感知，宿主存活 | +| 7 | 子进程热重载 | 同路径替换二进制 → v1→v2 立即生效 | +| 8 | **跨进程并发改写 StageContext** | 5 进程 × 300 轮，**零丢失零撕裂** | +| 9 | 持锁进程崩溃自愈 | 无死锁，**无需 robust mutex** | +| 10 | 二进制零拷贝 | 100KB/1MB/5MB → **14-22x**，体积 −100% | +| 11 | 工具调用 RPC 延迟 | p50 **19.6 µs**，占 LLM 往返 0.00065% | + +### 03 组：副本模型缺陷 + +| # | 实验 | 最近结果 | +|---|---|---| +| 12 | 副本模型 lost update 率 | 内置 **0%** vs 外部 **35.8~36.8%** | +| 13 | 现网 sanitizer+weather 冲突 | **1.6~4.3%** 清洗结果被覆盖 | + +**实验 12 的对照设计是重点**：两组用**完全相同的并发扇出** +（`stages.go:124` 的 `go func` + `wg.Wait()`），唯一差异是 +「共享同一 `*StageContext`」vs「快照-副本-写回」。 + +内置组 0% 证明**并发扇出这个原始设计是正确的**； +副本组 36% 证明**跨 C ABI 边界后锁语义失效**才是缺陷所在。 +不要据此得出"应该取消并发"的结论。 + +⚠️ **13 的比率随机器负载波动**（观测区间 1.6%~4.3%）——它取决于两个插件 +handler 的实际执行耗时比。文档正文引用 1.6% 是首次测量值， +**应理解为「量级在百分之几」而非精确常数**。 + +### 04 组：cgo 不可中断 + +| # | 实验 | 最近结果 | +|---|---|---| +| 14a | cgo 死循环 vs 子进程 Kill | cgo 泄漏；子进程 **零泄漏** | +| 14b | 泄漏增长曲线（20 次） | 泄漏 **20 goroutine / 18 OS 线程**，线性 | + +## 复跑时的注意事项 + +**结果会有波动，以下属正常**： + +- 实验 12/13 的丢失率随调度波动（12 稳定在 35~37%，13 在 1.6~4.3%） +- 实验 1 的线程增长为 0 或 1（取决于 netpoller 线程是否已存在） +- 实验 10 的加速比 14~22x（受 CPU 缓存状态影响） +- 实验 5 的 PSS 受同机其他 Go 进程影响（共享页计算） + +**结果不应变的**（若变了说明环境或结论有问题）： + +- 实验 1b 中纯 C `.so` 的段数必须归 **0**，Go c-shared 必须**不归零** +- 实验 8 的「总字符数 == 最终长度」必须成立（零丢失） +- 实验 9 必须无死锁 +- 实验 12 的内置模型必须 **0%** +- 实验 14b 的泄漏必须**线性增长** + +## 已知限制 + +- 实验 8 的 arena 未实现压实，64KB 用尽即停止写入（写入次数 < 5×300 属预期， + 见评估文档 3.3） +- 实验 12/13 是**链路复刻**而非直接调用生产代码， + 证明的是「副本模型这一机制」存在缺陷，不能替代对 `sanitizer`/`weather` + 的真实行为回归测试 +- 实验 5 的插件是最小 stdio loop（2.68MB），真实插件（如 qq 7.5MB）开销更高 +- 无 Windows 环境，9.2 的 Windows DLL 缺陷**未经实测**，仅代码阅读 diff --git a/docs/zh/experiments/plugin-arch/run.sh b/docs/zh/experiments/plugin-arch/run.sh new file mode 100755 index 0000000..f9f687d --- /dev/null +++ b/docs/zh/experiments/plugin-arch/run.sh @@ -0,0 +1,127 @@ +#!/usr/bin/env bash +# 插件架构评估实验 —— 一键复跑 +# 用法: ./run.sh [实验编号...] 例: ./run.sh 12 13 留空跑全部 +# 依赖: go >= 1.21, gcc, Linux (eventfd/memfd/dlopen) +set -uo pipefail +cd "$(dirname "$0")" +ROOT=$(pwd) +PASS=0; FAIL=0 + +need() { command -v "$1" >/dev/null || { echo "缺少依赖: $1"; exit 1; }; } +need go; need gcc + +# 统一的临时 module 环境（避免污染主仓 go.mod） +WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT + +banner() { echo; echo "════════ $* ════════"; } + +# x/sys 只有 exp1/2/4/8/10 需要 +prep_xsys() { + cat > "$1/go.mod" </dev/null 2>&1) +} +prep_plain() { printf 'module exp\ngo 1.21\n' > "$1/go.mod"; } + +run_go() { # <目录> <说明> + if (cd "$1" && go run . 2>&1); then PASS=$((PASS+1)); else echo " ❌ 失败: $2"; FAIL=$((FAIL+1)); fi +} + +SEL="${*:-all}" +sel() { [ "$SEL" = "all" ] && return 0; case " $SEL " in *" $1 "*) return 0;; esac; return 1; } + +# ── 01: dlclose / NODELETE ──────────────────────────────── +if sel 1; then + banner "实验 1 组: dlclose 对 DF_1_NODELETE 是 no-op" + W=$WORK/e01; mkdir -p $W; cp 01-dlclose-nodelete/*.c $W/ + gcc -shared -fPIC -o $W/probe_v1.so $W/probe_v1.c + gcc -shared -fPIC -o $W/probe_v2.so $W/probe_v2.c + gcc -shared -fPIC -o $W/shim.so $W/shim.c + cp $W/probe_v1.so $W/probe.so + for e in exp01a exp01b; do + mkdir -p $W/$e; cp 01-dlclose-nodelete/$e/main.go $W/$e/ + sed -i '/^\/\/go:build ignore$/d' $W/$e/main.go; prep_plain $W/$e + (cd $W/$e && go build -o ../$e.bin . 2>&1 | head -3) + done + echo "--- 01a: Go 宿主经 C shim 加载/卸载纯 C so ---" + (cd $W && ./exp01a.bin) && PASS=$((PASS+1)) || FAIL=$((FAIL+1)) + echo "--- 01b: /proc/self/maps 段数验证（纯 C 归零，Go c-shared 不归零）---" + (cd $W && ./exp01b.bin) && PASS=$((PASS+1)) || FAIL=$((FAIL+1)) +fi + +# ── 01c: 版本化路径（需要两个真 Go c-shared）──────────────── +if sel 1c; then + banner "实验 1c: 版本化路径 dlopen 可加载新代码" + W=$WORK/e01c; mkdir -p $W/{v1,v2,host} + for V in v1 v2; do + cat > $W/$V/main.go < $W/$V/go.mod + (cd $W/$V && go build -buildmode=c-shared -o ../gl$V.so . 2>&1|head -3) + done + cp 01-dlclose-nodelete/exp01c/main.go $W/host/ + sed -i '/^\/\/go:build ignore$/d' $W/host/main.go; prep_plain $W/host + (cd $W/host && go build -o ../h.bin .) && (cd $W && ./h.bin) && PASS=$((PASS+1)) || FAIL=$((FAIL+1)) +fi + +# ── 02: 可行性 1-11 ─────────────────────────────────────── +declare -A XSYS=([1]=1 [2]=1 [4]=1 [8]=1 [10]=1) +for n in 1 2 3 4 5 6 7 8 9 10 11; do + sel $n || continue + banner "实验 $n" + W=$WORK/f$n; mkdir -p $W + case $n in + 1) cp 02-feasibility/exp1_eventfd.go $W/main.go ;; + 2) cp 02-feasibility/exp2_parent.go $W/main.go; cp 02-feasibility/exp2_child.go $W/ ;; + 3) cp 02-feasibility/exp3_parent.go $W/main.go; cp 02-feasibility/exp3_child.go $W/ ;; + 4) cp 02-feasibility/exp4.go $W/main.go ;; + 5) cp 02-feasibility/exp5b.go $W/main.go; cp 02-feasibility/exp5_plugin.go $W/ ;; + 6) cp 02-feasibility/exp6.go $W/main.go; cp 02-feasibility/exp6_crash.go $W/ ;; + 7) cp 02-feasibility/exp7.go $W/main.go ;; + 8) cp 02-feasibility/exp8.go $W/main.go; cp 02-feasibility/exp8_worker.go $W/ ;; + 9) cp 02-feasibility/exp9.go $W/main.go; cp 02-feasibility/exp9_worker.go $W/ ;; + 10) cp 02-feasibility/exp10.go $W/main.go ;; + 11) cp 02-feasibility/exp11.go $W/main.go; cp 02-feasibility/exp11_plug.go $W/ ;; + esac + # 去掉 main.go 的 build ignore（它是入口） + sed -i '/^\/\/go:build ignore$/d' $W/main.go + if [ "${XSYS[$n]:-}" = "1" ]; then prep_xsys $W; else prep_plain $W; fi + # 需要预编译的辅助二进制 + case $n in + 5) (cd $W && go build -o plugbin exp5_plugin.go 2>&1|head -3) ;; + 6) (cd $W && go build -o crashbin exp6_crash.go 2>&1|head -3) ;; + 11) (cd $W && go build -o plug11 exp11_plug.go 2>&1|head -3) ;; + esac + run_go $W "实验 $n" +done + +# ── 03: lost update ─────────────────────────────────────── +for e in 12 13; do + sel $e || continue + banner "实验 $e: 副本模型 lost update" + W=$WORK/l$e; mkdir -p $W + cp 03-lost-update/exp$e/main.go $W/; sed -i '/^\/\/go:build ignore$/d' $W/main.go + prep_plain $W; run_go $W "实验 $e" +done + +# ── 04: cgo 不可中断 ────────────────────────────────────── +for e in 14a 14b; do + sel 14 || sel $e || continue + banner "实验 $e: cgo 调用不可中断" + W=$WORK/c$e; mkdir -p $W + cp 04-cgo-uninterruptible/hang.c $W/ + gcc -shared -fPIC -o $W/hang.so $W/hang.c + cp 04-cgo-uninterruptible/exp$e/main.go $W/; sed -i '/^\/\/go:build ignore$/d' $W/main.go + prep_plain $W; run_go $W "实验 $e" +done + +banner "汇总: 通过 $PASS, 失败 $FAIL" +[ $FAIL -eq 0 ] diff --git a/docs/zh/架构迁移评估.md b/docs/zh/架构迁移评估.md new file mode 100644 index 0000000..8d1bbef --- /dev/null +++ b/docs/zh/架构迁移评估.md @@ -0,0 +1,1621 @@ +# 插件架构迁移评估：从 C ABI 动态库到子进程 + 共享内存 + +> 状态：**评估稿 + 三轮验证已完成**（18 项可复跑实验） +> · 第七章 可行性实验：11 项全部通过（另有 01 组 3 项 + 04 组 2 项，合计 18） +> · 第八章 代码检查：发现外部插件 stage 一直是副本模型，实测 36.8% lost update +> · 第九章 补盲分析：新发现 4 类缺陷，其中 2 项**正在生产环境造成故障** +> +> ❗ **现网正在发生的问题**（详见 9.3/9.4/8.6）： +> `output_send` 永远返回成功（已 2 次）、cgo 超时线性泄漏（已 26 次）、stage 数据污染（量级百分之几） +> +> 结论摘要：现有 `c-shared + dlopen` 架构存在无法修复的热重载缺陷与能力天花板， +> 两者同源于 C ABI 这一前提。迁移到子进程模型可一次性消除，并让 C 中间层整体退场。 +> +> **可执行修复项与勾选清单见 [`plan.md` 第 11 节](../../plan.md)**；本文档负责论证、实验与架构设计。 + +--- + +## 零、给接手者的阅读指引 + +> **先读本章再读其余部分**，否则极易被前六章的过时表述误导。 + +### 0.1 本文档是增量写成的，前后章节结论不同 + +文档按三轮工作递进追加，**前面的章节保留了当时的认识**（便于追溯推理过程）， +但其中若干结论已被后续章节推翻或修订。**冲突时一律以编号更大的章节为准。** + +| 章 | 写作时的信息基础 | 可信度 | +|---|---|---| +| 一 ~ 六 | 代码阅读 + 推理 | ⚠️ **部分已被推翻**，见 10.2 对照表 | +| 七 | 11 项新架构可行性实验 | ✅ 实测 | +| 八 | 精读 ABI 链路 + 复刻实验 | ✅ 实测，**推翻了 2.4 的核心前提** | +| 九 | 遍历全部加载路径 + journal 统计 | ✅ 实测 + 现网数据 | +| 十 | 元信息 | — | + +**最重要的一处推翻**：2.4 节称「stage 并发扇出改写同一 `StageContext`」， +该表述对**内置插件**成立，但**外部 `.so` 插件从未共享过 `StageContext`**—— +它们走「快照-副本-写回」（见 8.1）。若按 2.4 的字面理解去改代码会走错方向。 + +### 0.2 三件事的准确定位 + +接手时最容易混淆的三个概念，这里一次说清： + +**① 并发扇出是原始设计，不是缺陷。** +`stages.go:124` 用 `go func` + `wg.Wait()` 并发调用所有 stage handler， +`StageContext` 的 `sync.RWMutex` 与公开的 `Lock/RLock` 就是为此准备的协作机制。 +**设计是对的。** 问题在于 C ABI 无法传递 Go 对象引用， +外部插件被降级为副本模型，那把为协作而生的锁在 ABI 边界外变成空转 +（实测：同一并发设计下内置 0% 丢失，副本 35.8~36.8% 丢失）。 + +**② 内置插件的高权限是刻意设计，不是"自己人所以安全"。** +但当前实现把「应有的权限梯度」与「C ABI 的表达能力天花板」混在了一起： +外部插件拿不到 `OutputChan`/`Subscribe` 是**技术限制**（Go channel、闭包 +过不了 C ABI），而非权限决定——证据是 `loader.go` 的 `case 23/24` +（事件订阅）是**空实现**，属于"给不了"而非"不给"。 +迁移目标是让梯度从**技术意外**变成**显式声明并强制的策略**，**不是消除梯度**。 + +**③ 副本模型是"为方便插件加载的无奈之举"，不是设计失误。** +C ABI 是为绕开 Go 原生 `plugin` 包的同版本限制而引入的，副本模型是它的必然代价。 +批评应指向"该代价未被记录、其后果（lost update）未被发现"，而非当初的选择。 + +### 0.3 修复项以 plan.md 为唯一权威 + +本文档出现过多套编号（4.1 的 `0.x`、8.9、9.6 的 `A-F`）， +**均已统一收敛到 [`plan.md` 第 11 节](../../plan.md) 的 `11.1`~`11.6`**。 + +| plan.md | 内容 | 本文档论证位置 | +|---|---|---| +| 11.1 | `output_send` 假成功 | 9.4 | +| 11.2 | cgo 超时不可中断 | 9.3 | +| 11.3 | stage 副本 lost update | 8.1~8.6 | +| 11.4 | Lua 缺读锁 | 9.1 | +| 11.5 | Windows 能力退化 | 9.2 | +| 11.6 | reload 语义谎言 | 1.1 / 1.2 | +| 11.7 | 子进程化迁移（待决策） | 三~七章 | + +本文档中的 `0.x` / `A-F` 编号**仅供追溯当时的分组思路**，实施时不要使用。 + +### 0.4 哪些结论未经实测 + +| 表述 | 状态 | +|---|---| +| 9.2 Windows DLL 只下发 3 字段且无写回 | ⚠️ **仅代码阅读，无 Windows 环境实测** | +| 11.1 修复方案「不构成 cgo 嵌套」 | ⚠️ **推理，实施前必须实测** | +| 9.1 Lua DATA RACE 会实际触发 | ⚠️ 现网无 Lua 插件，**未触发过** | +| 3.x 目标架构的全部设计细节 | ⚠️ 机制经实验验证，**完整实现未写** | + +其余带 ✅ 的均有 [`experiments/plugin-arch/`](experiments/plugin-arch/) 下的 +可复跑实验支撑（`./run.sh`，18 项）。 + +### 0.5 现网正在发生的问题（若只读一段，读这段） + +| 问题 | 现网次数 | 影响 | 修复 | +|---|---|---|---| +| `output_send` 永远返回成功 | 7 天内 **2 次** | 消息发不出，模型以为成功、不重试 | 11.1 | +| cgo 超时不可中断 | 14 天内 **26 次** | 每次泄漏 1 goroutine + 1 OS 线程，永久 | 11.2 | +| stage 清洗结果被覆盖 | 概率性，**量级百分之几** | 脏数据（ANSI 转义）进 LLM 上下文 | 11.3 | + +**这三项都不需要等迁移决策，可独立修复。** + +--- + +## 一、为什么要动 + +### 1.1 触发问题：插件热重载静默失效 + +更换 `plugin.so` 后调用 `plgreload`，内核报告 `reloaded: qq` 成功，但**运行的仍是旧代码**。 + +根因经实验确证： + +``` +readelf -d plugin.so + FLAGS: SYMBOLIC STATIC_TLS + FLAGS_1: NODELETE ← Go 链接器强制写入 +``` + +`DF_1_NODELETE` 使 `dlclose` 成为 no-op（返回 0 但不卸载）。同路径二次 `dlopen` +复用旧映像，新代码永不生效。 + +三组对照实验（`/proc/self/maps` 段数为准）： + +| 场景 | dlclose 后映射段数 | 结论 | +|---|---|---| +| 第三层是纯 C `.so` | 5 → **0** | 可真正卸载，换代码生效 | +| Go c-shared，Go 宿主直接 dlopen | 5 → **5** | 未卸载 | +| Go c-shared，**经纯 C shim** dlopen | 5 → **5** | 仍未卸载 | + +第三行是决定性的：**`NODELETE` 属于被卸载对象自身的 ELF 属性，与谁调用 `dlopen` 无关**。 +套任何层数的 C 中间件都绕不过去。 + +上游明确不支持（golang/go#11100）：Go runtime 的信号处理器是进程全局的， +`sysmon`/GC worker/scavenger 常驻 OS 线程，静态 TLS 嵌进线程布局—— +patch 掉标记只会把静默失效换成随机崩溃。 + +### 1.2 曾评估并否决的绕行方案 + +**版本化路径 dlopen**（`plugins/qq/.load/plugin-<时间戳>-qq.so`）：技术上成立，实测有效。 + +``` +1) 装载 1700000001-qq.so handle=0x36add080 ver=v1-CODE +2) 主 so 更新为 v2，复制到 1700000002-qq.so +3) dlclose 旧句柄 rc=0（旧映像不释放，预期） +4) 装载新路径 handle=0x36ade440 ver=v2-CODE ← 新代码生效 +``` + +同时确认 Go c-shared **无 SONAME**，不会被 glibc 按名去重，换路径确实得到新映像。 + +**但代价不可接受**。30 次连续重载实测： + +``` +第 10 次: RSS +15380KB threads +42 +第 20 次: RSS +32048KB threads +112 +第 30 次: RSS +46644KB threads +168 +均摊: RSS +1575KB/次, 线程 +5.77/次 +``` + +每次重载**永久泄漏约 5.8 个线程**——每份残留 Go runtime 都带自己的 `sysmon`、 +GC worker、scavenger，永不退出且仍被调度。`GOMAXPROCS=1` 只能压到 4.0/次， +且会拖慢插件并发，杯水车薪。 + +对 24/7 常驻的 homed 而言，「永久泄漏」比「15 秒重启」糟糕得多：重启有界且自愈， +泄漏无界且单调劣化。**故否决。** + +### 1.3 更深的问题：内置与外部插件的能力断层 + +| | 方法数 | +|---|---| +| `internal/sdk`（内置插件用） | 28 | +| 公开 SDK（外部插件用） | 36 | + +数字接近，但内置独有的恰恰是**「活的 Go 对象」**： + +``` +OutputChan() <-chan *agentIO.OutputEvent Go channel +RegisterChannel(dev agentIO.Device) Go 接口（含方法集） +Subscribe(type, handler) func() 回调 + 返回退订闭包 +Publish / Config / Tool / Indexer 直接持有内核注册表 +Selftest / Status / Supervisor / Tracker 内核内部机制 +SetToolBlocks 多模态注入 +``` + +**关键区分**：内置插件的高权限是**刻意的设计决策**，不是"自己人所以安全"。 +但当前实现把两件事混在了一起： + +- **应该有的权限梯度**（`Supervisor`/`Tracker`/`Selftest` 只给内核内部） +- **C ABI 的表达能力天花板**（channel、接口方法集、闭包在进程边界外无表示） + +外部插件拿不到 `OutputChan` 是**技术限制**，不是权限决定。证据： + +```go +case 23: // CORE_SUBSCRIBE + // Events API not wired for external plugins + return 0 +case 24: // CORE_UNSUBSCRIBE + return 0 +``` + +事件订阅对外部插件是**空实现**。这不是"不给"，是"给不了"。 + +迁移的价值不是消除权限梯度，而是**让梯度从技术意外变成显式声明并强制的策略**。 + +### 1.4 附带缺陷（同源于 C ABI） + +- `SetToolBlocks` 在 bridge 中是**空实现**——跨 ABI 无对应 method id +- 插件 panic 跨 C 栈，`recover` 兜不住就带崩整个 homed +- `plugin_install` 返回 `reload_required` 对 `.so` 是**误导性谎言** +- method id 编号出现历史断裂（`CORE_INJECT_INPUT_SYNC=47` 夹在 7 和 8 之间） +- `plugindev` 交叉编译需处理 cgo 工具链，Windows/ARM 目标需对应 C 编译器 + +**这些全是 C ABI 这一前提衍生的附属债务。前提一撤，债务自行消失。** + +--- + +## 二、现状盘点 + +### 2.1 插件规模 + +**内置插件 16 个**（`internal/plugins/all.go` 匿名 import + `init()` 自注册）： + +``` +agentcli ai_image cfgmgr clawhubadapter cli cmd files healthcheck +localuse mcp multimodal pluginmgr remotedevice skillmgr timer webui +``` + +**外部 `.so` 插件 17 个**（`/home/newqqagent/plugins/`）： + +``` +a2a acp ai_image bili browser calendar editdoc files memo +music ocr qq recoverydiag rss sanitizer vanblog weather +``` + +### 2.2 涉及代码规模 + +| 文件 | 行数 | 迁移后命运 | +|---|---|---| +| `internal/plugin/cabi/loader.go` | 951 | **删除** | +| `internal/plugin/cabi/types.go` | 66 | **删除** | +| `internal/plugin/cabi/loader.c` | 79 | **删除** | +| `internal/plugin/registry.go` | 922 | 改：加载分派 | +| `internal/plugin/dynamic_loader_unix.go` | 79 | **删除/替换** | +| `internal/sdk/plugin.go` | 365 | 基本不动 | +| 公开 `sdk/plugin.go` | 484 | 加访问器，签名不变 | +| `internal/agent/core/stages.go` | 189 | 改：stage 跨进程 | +| `internal/agent/core/plugin_health.go` | 128 | **不动**，只换信号源 | +| `internal/events/bus.go` | 97 | 加：事件环投递 | +| `plugindev/templates.go` 的 `tmplLinuxBridge` | 385 | **删除**（每插件一份） | +| `internal/plugin/lua_plugin.go` | 978 | 改：统一走 RPC（见 9.1） | +| `internal/plugin/dynamic_lua.go` | 24 | 改 | +| `internal/plugin/lua_util.go` | 60 | 保留 | +| `internal/plugin/dynamic_dll_windows.go` | — | **删除**（见 9.2，能力严重退化） | +| `internal/plugin/dynamic_loader_windows.go` | — | **删除** | +| `internal/plugin/dynamic_dll_stub.go` | — | **删除** | + +> ⚠️ **第九章更正**：此前只识别了 native + cabi 两类加载路径，实际有**四种** +> （cabi `.so`/`.dylib`/`.dll`、Lua `main.lua`、Skill `SKILL.md`、native 内置）。 +> Windows DLL 与 Lua 路径此前完全未评估，均存在独立缺陷（9.1/9.2）。 +> **子进程化的一个重要收益是把三套独立 ABI 实现收敛为单一 RPC 实现。** + +**可删除总量：1096 行 C ABI 层 + 385 行/插件的 bridge 模板。** + +`loader.go` 内 `C.CString`/`C.GoString`/`C.free` 共 38 处调用，纯边界税。 + +### 2.3 已有且完善、迁移时应保留的机制 + +**必须强调：现有 SDK 的生命周期管理远比表面完善，迁移是"重新接线"而非"重写"。** + +`plugin_health.go`（128 行，**逻辑完全复用**）： + +``` +3 次崩溃 / 5 分钟窗口 → 标记 unhealthy +30 秒冷却 → 自动恢复 +pendingReloads() → 驱动 autoReloadPlugins +尊重 AutoRestartEnabled +``` + +`executeToolCall`（`toolcall.go:16`）： + +```go +done := make(chan string, 1) +go func() { done <- a.executeToolCallInner(tc) }() +select { +case result := <-done: return result +case <-time.After(60 * time.Second): // 60 秒超时 +} +// + panic 捕获 → resolveToolPlugin → recordCrash +``` + +SDK 停止链路（**已验证被正确调用**）： + +``` +Handle.Stop() → call_stop_plugin → go_stop_plugin + → sdk.RunStopHandlers() → plg.Stop() +RegisterStopHandler / RegisterOnRemoveHandler / SetAutoRestart +``` + +迁移时的唯一改动：**把"panic 捕获"换成"进程退出码/EOF 检测"，喂给同一个 `recordCrash`。** +超时、冷却、自愈、优雅停止全部保持原样。 + +### 2.4 两条硬约束（决定新架构设计） + +**约束 A：stage 是并发扇出，多插件并发改写同一对象** + +`internal/agent/core/stages.go:124`： + +```go +func (h *StageHost) RunStage(stage sdk.Stage, ctx *sdk.StageContext) { + var wg sync.WaitGroup + for _, handler := range handlers { + wg.Add(1) + go func(fn sdk.StageHandler) { // ← 并发 + defer wg.Done() + if err := fn(ctx); err != nil { errCh <- err } + }(handler) + } + wg.Wait() +} +``` + +所有插件 handler **并发运行在同一个 `*StageContext`** 上，靠 `sync.RWMutex` + +公开的 `Lock/RLock/Unlock` 协调。这是刻意设计——那 17 个字段 +（`LLMText`/`ToolCalls`/`FinalText`/`Errors`…）就是给多插件协作改写消息体用的。 + +**这是共享内存的正当性所在。** JSON-RPC 副本模型下语义会崩坏：两个插件都改了 +`FinalText`，谁赢？现在的答案是"后者看到前者结果"，可组合；副本合并则无解。 + +> ## ⚠️ 本节前提已被第八章推翻，勿据此改代码 +> +> 上述「并发扇出改写同一对象」**只对内置插件成立**。 +> 外部 `.so` 插件一直走「快照-副本-写回」（`loader.go:411-439` + `templates.go:768-787`）， +> 其 `ctx.Lock()` 是**空操作**（锁的是副本自己的 mu），且实测存在 +> **35.8~36.8% 的 lost update**（实验 12）与**现网量级百分之几的数据污染**（实验 13）。 +> +> **两点务必分清**： +> - **并发扇出本身是正确的原始设计**（`stages.go:124`），`RWMutex` 就是为它准备的 +> - **失效的是跨 ABI 边界后的锁语义**，不是这个设计 +> +> 故共享内存的作用是**修复**副本模型的缺陷，而非"保持现有语义"。 +> 完整分析见 8.1~8.6；准确定位见 0.2。 + +**约束 B：`Bus.Publish` 是同步的，且流式输出每 token 发一次** + +`internal/events/bus.go:56`： + +```go +func (b *Bus) Publish(evt *Event) { + for _, h := range typeHandlers { + b.safeCall(h, evt) // ← 内联阻塞调用 + } +} +``` + +`EventContentDelta` / `EventReasoningDelta` 在 `accumulateStream` 里逐 token 发布 +（`process.go:388/470/479`）。 + +**若内核发通知时等待插件，流式输出会被拖成卡顿。** +故新架构的事件投递**必须严格 post-and-forget，绝不等待消费者**。 + +### 2.5 payload 体积实测（决定共享内存的定位） + +近两日工具调用结果： + +``` +样本=96 中位=93 B p90=130 B 最大=134 B 均值=83 B +``` + +此量级下 JSON 序列化 3-8 µs，LLM 单轮往返 2-8 秒，**IPC 开销占比约 0.0001%**。 + +**结论：共享内存的价值不在省序列化开销**，而在两点： + +1. 并发改写同一份 `StageContext`（约束 A） +2. 二进制零拷贝（未来多媒体 payload，避免 base64 的 +33% 体积与编解码） + +控制面用 JSON 完全够用——toolcall 结果最终都要 JSON 化交给模型。 + +--- + +## 三、目标架构 + +``` +今天： + homed ──dlopen──> plugin.so + ├─ cgo bridge 385 行（7 个 //export，27 处字符串转换） + └─ 51 个整数 method id 派发 + ↑ C 层唯一目的：绕开 Go plugin 包的同版本限制 + +之后： + homed ──spawn──> plugin（纯 Go 二进制，无 cgo） + │ + ├── stdio JSON-RPC 控制面：51 个 case 平移为 method 名 + ├── shm + 偏移 数据面：StageContext 并发改写、二进制零拷贝 + └── eventfd 通知面：事件环 post-and-forget +``` + +### 3.1 C 中间层为何整体退场 + +C 层存在的唯一理由是绕开 Go 原生 `plugin` 包的版本枷锁： + +``` +plugin.Open 要求：完全相同的 Go 版本 + 完全相同的依赖版本 + 同构建环境 +任一不符 → "plugin was built with a different version of package ..." +``` + +`c-shared` + `dlopen` 把接口面压成 C ABI 来规避，代价是 51 个整数派发和满地字符串转换。 + +**子进程模型下，进程边界本身就是 ABI 边界。** 两进程各带自己的 Go runtime， +版本/依赖/编译器全不相关——从根上不存在"同版本"问题。C 层解决的问题消失，C 层自己也就该消失。 + +连带消失的：`DF_1_NODELETE` 议题、版本化路径、重载配额、hash 目录、 +method id 编号维护、`SetToolBlocks` 空实现、cgo 交叉编译工具链。 + +### 3.2 method id 的处置 + +**51 个 case 不删，原样映射为 RPC method 名**： + +``` +case 17: // CORE_SETTINGS_SET → {"method": "settings.set"} +case 41: // CORE_TEXT_MEMORY_APPEND → {"method": "textmemory.append"} +case 48: // CORE_PLUGIN_RELOAD_ONE → {"method": "plugin.reloadOne"} +``` + +每个 case 体（参数解析、调用、错误处理）可整块搬移，只换取参数方式。 +语义不变，回归风险最小。 + +**但编号本身扔掉**：不再维护"下一个可用 id 是 52"，加能力不用改两边常量表， +也不再出现 `47` 夹在 `7` 和 `8` 之间的历史痕迹。 + +### 3.3 数据面：偏移替代指针 + +共享段 = 定长头 + arena，所有变长数据用相对 arena 基址的 `{off, len}` 描述符。 +**相对偏移是关键**——各进程 `mmap` 到不同虚拟地址也能正确解引用。 + +```c +typedef struct { uint32_t off, len; } Slice; // 相对 arena 基址 + +typedef struct { + Slice type, text; + uint8_t has_image, has_audio; + Slice image_url, image_detail; + Slice audio_url; +} ShmContentBlock; + +typedef struct { + uint64_t seq; // 乐观读校验 + Slice raw_message, llm_text, reasoning, final_text; + uint8_t has_response; Slice response; + Slice media_type, input_source, output_channel; + uint32_t nblocks; Slice blocks; // → ShmContentBlock[] + uint32_t arena_used, arena_cap; +} ShmStageCtx; +``` + +**`Extra` 可完全偏移化——已核实全部使用点只有 4 个键**： + +``` +internal/agent/core/eventloop.go:178 + Extra = { media_blocks, media_type, input_source, output_channel } +process.go:41 读 Extra["media_blocks"].([]ContentBlock) +distill.go:472 写 Extra["output_channel"] +``` + +而 `ContentBlock` 自身全是可偏移化的： + +```go +ContentBlock{ Type, Text string; ImageURL *ImageURL; AudioURL *AudioURL } +ImageURL{ URL, Detail string } AudioURL{ URL string } +``` + +**没有任何 `interface{}`、函数或 Go 特有引用类型。** 那两个指针只表达"可选"， +用 `has` 标志位 + 内联结构替代。`Extra` 的 `interface{}` 是**形式上的**动态类型， +实际是封闭可判别的联合。 + +**决策：4 个键提升为共享段具名字段，`Extra` 本身保留 RPC 副本语义。** +理由：这 4 个键都是内核写、插件读，无并发改写需求；真正需要多插件并发改的 +（`LLMText`/`FinalText`/`ToolCalls`/`Errors`）全是强类型字段。 +不为尚不存在的通用性付 tagged union + 字符串驻留表的成本。 + +**arena 空间管理**：append-only。插件把 `FinalText` 从 10 字节改成 10KB 时 +分配新区域、更新描述符、旧区域留作垃圾；arena 用尽由内核在 stage 结束后 +（此时无插件持锁）整体压实。代价是单次 stage 内写入总量有上限。 + +### 3.4 SDK 必须封装全部复杂度 + +插件作者**永远不接触 `Slice{off,len}`**，代码与今天完全一致： + +```go +func (p *Plugin) onBeforeToolcall(ctx *sdk.StageContext) error { + ctx.Lock() + defer ctx.Unlock() + ctx.FinalText = strings.TrimSpace(ctx.FinalText) + return nil +} +``` + +SDK 内部承担：`mmap` 挂载、跨进程锁初始化、arena 分配、偏移↔Go 值转换、 +脏字段回写、进程崩溃后段清理。 + +**实现手法：插件进程内保留原生 `StageContext` 结构。** +stage 入口从共享段反序列化成本地对象 → handler 照常读写字段 → +`Lock/Unlock` 映射到跨进程锁 → handler 返回时脏字段写回共享段。 + +每次转换微秒级，换来 **17 个存量外部插件业务代码零改动**。这个交换很值。 + +### 3.5 必须留在进程内的：回调型资源 + +**"所有数据放共享内存"需要精确化**：共享内存放不了函数指针 +（地址在各进程不同，代码段布局也不同）。 + +| 类别 | 载体 | +|---|---| +| 跨进程**状态** | 共享内存 | +| 跨进程**行为** | RPC 调用回内核 | + +`Subscribe` 返回的退订闭包、`Device` 的方法集、`OutputChan` 的接收端—— +这些是"行为"不是"数据"。故准确表述为： +**所有跨进程传递的状态放共享内存，行为通过 RPC 调用回内核。** + +### 3.6 通知面：事件环 + eventfd + +**设计骨架（采纳）**：数据先落地 → 再通知 → 内核不等待。满足约束 B。 + +但单纯的信号量不够——`sem_t` 只是计数器，没有 payload、顺序、消费游标： + +```c +typedef struct { + uint64_t seq; // 全局单调序号 + uint32_t type; + Slice payload; // → arena +} EvtSlot; + +typedef struct { + _Atomic uint64_t write_seq; // 仅内核写 + uint32_t cap; // 2 的幂 + EvtSlot slots[]; +} EvtRing; + +typedef struct { // 每订阅者独立 + _Atomic uint64_t read_seq; + _Atomic uint64_t dropped; // 被覆盖丢弃计数 + uint32_t type_mask; + uint64_t last_seen; // 活性判断 +} Subscriber; +``` + +内核：写 slot → `write_seq++` → 对匹配订阅者 post，**不等待**。 +消费者：`read_seq` 追 `write_seq`，落后超 `cap` 即溢出，差值记入 `dropped` +并跳到最新——**允许丢事件但让消费者知道丢了**（与 WebUI 侧 `sync_required` 思路一致）。 + +**技术修正：用 `eventfd` 而非 `sem_t`。** + +Go 里没有轻量线程。goroutine 经 cgo 调 `sem_wait` 会**阻塞整个 OS 线程**（M 被占住）， +每插件常驻一个锁死线程——又回到我们正要逃离的线程膨胀。 + +```go +efd, _ := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC) +f := os.NewFile(uintptr(efd), "evtnotify") +// eventfd 是 epoll-able，os.NewFile 注册进 runtime netpoller +// f.Read() 阻塞时只 park goroutine，不占 OS 线程 +``` + +附带收益： +- 计数语义（读出累积值）天然合并突发通知——1000 个 token 事件可能只唤醒几次 +- 可与 RPC 请求在同一 select 中等待，不需两套等待机制 + +✅ **已实测通过**（见 7.2）：200 个 goroutine 阻塞在 eventfd.Read 上仅增 1 个 OS 线程。 + +### 3.7 跨进程锁：倾向"锁仲裁回归内核" + +`pthread_mutex` 的 `PTHREAD_PROCESS_SHARED` + `ROBUST` 属性 Go 标准库无等价物。 +但引入它意味着**为了一个锁而保留 cgo**——与"C 整体退场"的目标冲突。 + +**方案对比**： + +| | robust pthread_mutex | 锁仲裁回内核 | +|---|---|---| +| cgo | 需要 | **不需要** | +| 崩溃处理 | 需处理 `EOWNERDEAD` + `consistent` | 进程死了内核直接释放 | +| 加锁成本 | 原子操作（纳秒） | 一次 RPC 往返（微秒） | +| 复杂度 | 高 | 低 | + +**已裁定采用后者**（实验 3+9，见 7.4/7.10）：插件通过 RPC 请求"给我 stage 写锁"，内核用普通 `sync.Mutex` 排队。 +stage handler 加锁频率很低（每次 stage 一两次，非每字段一次），微秒级往返可忽略。 + +**这样整个新架构可做到完全无 cgo。** + +注：事件环无需 robust 语义——`eventfd`/信号量没有所有权概念， +不存在"持锁进程死了"的死锁风险。共享内存中真正需要互斥的只有 `StageContext`。 + +### 3.8 能力对齐：外部插件可获得什么 + +| 内置独有能力 | 子进程下的等价物 | 可行 | +|---|---|---| +| `OutputChan` 消费 | 共享内存 ring + eventfd 通知 | ✅ | +| `Subscribe`/`Publish` | 事件环 + 独立游标 | ✅ | +| `RegisterChannel(Device)` | 声明式注册（caps + 工具名清单）+ 调用回传 | ✅ | +| `SetToolBlocks` | 二进制落 arena，`Slice` 描述符回传 | ✅ | +| `Config`/`Tool`/`Indexer` | 新增 RPC method（本就是数据操作） | ✅ | +| `Selftest`/`Supervisor`/`Tracker` | **不提供** | ❌ 刻意 | + +最后一行是**显式的权限决策**，而非技术限制——这正是迁移要达成的区分。 + +副产品：`localuse` 这类插件不再必须编进内核，改一行不用重编整个 homed。 + +--- + +## 四、工作量评估 + +### 4.1 分阶段拆解 + +规模标记：S = 1 人日内，M = 2-4 人日，L = 1-2 周，XL = 2 周以上。 +风险标记基于「失败时能否安全回退」。 + +#### 阶段 0：止血（不依赖任何新架构） + +> ⚠️ **本表编号已废弃**（此处仅存档当时的分组思路）。 +> 实施请用 [`plan.md` 第 11 节](../../plan.md) 的 `11.1`~`11.6`——见 0.3 的对应表。 +> 本表的 0.1/0.2/0.3 → plan 11.6；后文追加的 0.4~0.7 → plan 11.3/11.1/11.2/11.4。 + +| # | 任务 | 文件 | 规模 | 风险 | +|---|---|---|---|---| +| 0.1 | ELF 检测 `DF_1_NODELETE`，命中则标记插件"不可热重载" | `dynamic_loader_unix.go` | S | 极低 | +| 0.2 | `ReloadOne` 对此类插件直接返回"需重启"，停止假装成功 | `registry.go` | S | 极低 | +| 0.3 | `plugin_install` 返回 `restart_required` 替代误导性的 `reload_required` | `pluginmgr/plugin.go` | S | 极低 | + +**价值**：零运行时开销，立刻消除"模型照着 `reload_required` 建议重载、实际白跑"的误导。 + +**后续追加（第八、九章发现，优先级高于 0.1-0.3）**： + +| # | 任务 | 现网影响 | 规模 | +|---|---|---|---| +| 0.4 | `stageContextWritable` 只回传变更字段 | ❗ 脏数据进 LLM，量级百分之几（8.6） | S | +| 0.5 | `output_send` 改同步等真实结果 | ❗ 消息发不出而模型以为成功（9.4） | M | +| 0.6 | 超时日志措辞修正 + 排查 browser 频繁超时 | ❗ 已泄漏 26 次（9.3） | S | +| 0.7 | Lua stage 快照加 `sc.RLock()` | 潜在 DATA RACE（9.1） | S | + +#### 阶段 1：能力对齐验证（不依赖子进程） + +| # | 任务 | 规模 | 风险 | +|---|---|---|---| +| 1.1 | 给 C ABI 补 `SetToolBlocks`（method id 52，走文件路径传递） | M | 低 | +| 1.2 | 用某外部插件验证多模态注入端到端可用 | S | 低 | + +**价值**：先验证"外部插件能否逼近内置能力"这一假设，不依赖任何共享内存基础设施。 +若此步就发现能力对齐有本质障碍，整个迁移的收益需重估。 + +#### 阶段 2：子进程通道原型（核心风险点） + +| # | 任务 | 文件 | 规模 | 风险 | +|---|---|---|---|---| +| 2.1 | 进程管理器：spawn/健康检查/优雅停止/崩溃重启。**可大幅参考 `clawhubadapter/sidecarProcess`**（已有 stdin/stdout + 异步 reader + `pending map[int]chan` + `notifyCh` 的成熟实现） | `internal/plugin/proc/`（新建） | L | 中 | +| 2.2 | 双向 JSON-RPC 编解码：7 个 kernel→plugin 调用 + 51 个 plugin→kernel 回调 | 同上 | M | 低 | +| 2.3 | `procPlugin` 实现 `sdk.Plugin` 接口，`Close()` 变成真 kill+wait | `dynamic_loader_unix.go` 旁 | M | 中 | +| 2.4 | `loadOne` 按 manifest `entry` 分派：`plugin.so`→cabi，`plugin.bin`→proc | `registry.go` | S | 低 | +| 2.5 | `plugin_health` 接线：进程退出码/EOF → `recordCrash`（**逻辑复用，仅换信号源**） | `plugin_health.go` 调用侧 | S | 低 | +| 2.6 | `plugindev` 新增 `tmplProcMain`：bridge 从 c-shared 导出改为 `main()` + stdio loop | `templates.go` | M | 低 | +| 2.7 | `plugindev` 构建改普通 `go build`（去 cgo，交叉编译反而简化） | `cmd_build.go` | S | 低 | +| 2.8 | `validBinaries` 加 `plugin.bin`，`.hmap` 打包/校验支持 | `pluginmgr` + `manifest` | S | 低 | +| 2.9 | 单插件单工具端到端打通（建议用 `weather`） | — | M | — | + +**关键收益**：公开 SDK 的 `PluginSDK` 方法签名全部保留，底层从 `callString(id,...)` +换成 RPC 发送——**17 个存量插件业务代码零改动，只需用新 plugindev 重编**。 + +#### 阶段 3：共享内存数据面 + +| # | 任务 | 规模 | 风险 | +|---|---|---|---| +| 3.1 | 共享段 schema + arena 分配器（append-only + 压实） | L | 中 | +| 3.2 | `StageContext` 偏移化编解码（共享段 ↔ 本地 Go 对象） | L | 中 | +| 3.3 | 锁仲裁 RPC（`stage.lock`/`stage.unlock`，内核侧 `sync.Mutex`） | M | 中 | +| 3.4 | `RunStage` 跨进程并发扇出改造（**保留并发语义，最难的一环**） | L | **高** | +| 3.5 | 段生命周期：创建/挂载/插件崩溃后清理 | M | 中 | + +**3.4 是全项目最高风险点**：必须保证多插件并发改写同一 `StageContext` 的语义 +与今天一致，否则 `sanitizer`、`multimodal` 这类改写型插件行为会静默漂移。 + +#### 阶段 4：通知面 + +| # | 任务 | 规模 | 风险 | +|---|---|---|---| +| 4.1 | `EvtRing` + `Subscriber` schema，溢出计数 | M | 低 | +| 4.2 | eventfd 通知 + Go 侧 netpoller 消费（**先做 3.6 的实测验证**） | M | 中 | +| 4.3 | `Bus.Publish` 加事件环投递（post-and-forget，**不得阻塞**） | S | **高** | +| 4.4 | 订阅者活性检测（`last_seen` 超时 → `recordCrash`） | S | 低 | +| 4.5 | 实现 `case 23/24`（今日空实现），外部插件首次获得事件能力 | M | 低 | + +**4.3 风险高**：`Bus.Publish` 在流式路径上逐 token 调用，任何阻塞都会导致 +输出卡顿。改动必须严格无锁/非阻塞，且需专门的流式压测验证。 + +#### 阶段 5：迁移与收尾 + +| # | 任务 | 规模 | 风险 | +|---|---|---|---| +| 5.1 | 17 个外部插件逐个重编译 + 回归验证 | L | 中 | +| 5.2 | 删除 `cabi/`（1096 行）与 bridge 模板（385 行） | S | 低 | +| 5.3 | 权限梯度显式化：声明式 caps + 内核侧强制 | M | 中 | +| 5.4 | 文档：插件开发指南更新、迁移说明 | M | 低 | + +### 4.2 总量估算 + +| 阶段 | 规模合计 | 可独立交付 | +|---|---|---| +| 0 止血 | ~1 人日 | ✅ 立即 | +| 1 能力对齐 | ~3 人日 | ✅ 独立 | +| 2 子进程通道 | ~3 周 | ✅ 与 cabi 共存 | +| 3 共享内存 | ~3 周 | ⚠️ 依赖阶段 2 | +| 4 通知面 | ~1.5 周 | ⚠️ 依赖阶段 3 | +| 5 迁移收尾 | ~2 周 | ⚠️ 依赖全部 | + +**合计约 10 周**（单人、含验证，不含意外）。 + +> **实验后修订：约 8-9 周**（见 7.15）。第九章新增的 Lua/Windows 路径收敛 +> 已包含在阶段 5 的迁移工作内，不额外增加工期——因为它们是**删除**而非改造。 + +### 4.3 成本对照 + +作为决策参考，三条路的真实成本： + +| 方案 | 一次性成本 | 长期代价 | 性质 | +|---|---|---|---| +| **接受重启**（仅做阶段 0） | ~1 人日 | 每次换 `.so` 中断 ~15 秒 | 有界、自愈 | +| **版本化路径** | ~3 人日 | 每次重载 +5.8 线程 +1.5MB，**永久** | 无界、单调劣化 | +| **子进程 + 共享内存** | **~8-9 周** | 常驻 **+29MB RSS**（7.6 实测，原估 50-70MB 偏高） | 有界、换来真隔离 | + +**插件更新的真实频率是每周级**（今日的密集调试是特例）。 +若唯一目标是热重载，阶段 0 的性价比远高于全量迁移。 + +**迁移正当性共 6 条**（与 9.5 同一份清单；本节讨论的热重载是第 ① 条）： + +| # | 正当性 | 依据 | 有临时修复？ | +|---|---|---|---| +| ① | 热重载 | 1.1（原始动机） | ✅ 11.6 可缓解（改为诚实上报） | +| ② | 插件崩溃隔离（现在一个插件 panic 能带崩 homed） | 实验 6 | ❌ 无 | +| ③ | 能力断层消除（外部插件获得事件订阅、多模态、通道注册） | 1.3 / 3.8 | ❌ 无 | +| ④ | 内置插件解耦（`localuse` 改一行不用重编 homed） | 1.3 | ❌ 无 | +| ⑤ | 修复 stage 副本 lost update（实测 35.8~36.8%，现网量级百分之几） | 8.4 / 8.6 | ⚠️ 11.3 打补丁 | +| ⑥ | 修复 cgo 固有缺陷：超时泄漏（现网 26 次）、`output_send` 假成功（现网 2 次）、Windows 退化、三套 ABI 分裂 | 第九章 | ⚠️ 11.1/11.2/11.5 打补丁 | + +**关键判断**：①⑤⑥ 有临时修复（`plan.md` 11.1~11.6），**不必等迁移**； +但那些修复是在副本模型内部打补丁，只有子进程 + 共享内存才从根上消除成因。 +**②③④ 无临时方案——它们是迁移的不可替代价值。** + +**若这六点都不成立，则不应迁移。** + +### 4.4 风险登记 + +| 风险 | 影响 | 缓解 | +|---|---|---| +| `RunStage` 并发语义漂移（3.4） | 改写型插件行为静默错误 | 机制已验证（7.9）；仍需为 `sanitizer`/`multimodal` 补并发行为测试作为基线 | +| `Bus.Publish` 引入阻塞（4.3） | 流式输出卡顿 | 专项流式压测；投递路径禁用任何锁 | +| ~~eventfd 未走 netpoller~~ | — | ✅ **已排除**（7.2 实测 +1 线程） | +| 17 进程常驻开销 | 实测仅 +29MB RSS（7.6） | ✅ **风险关闭** | +| arena 单 stage 写入上限 | 大写入插件失败 | 明确上限并在 SDK 层报错，而非静默截断 | +| Windows 无验证环境（9.2） | 迁移后 Windows 行为未知 | 需借测试机；当前 Windows 路径本就严重退化，风险不增 | +| Lua 插件迁移路径未设计（9.1） | Lua 插件如何跑在子进程内 | 可保留进程内 Lua VM（无 cgo 问题）或独立 Lua 宿主进程；待设计 | +| 存量插件回归 | 17 个插件行为变化 | 阶段 2.4 的 entry 分派让两种插件**共存**，可逐个迁移、随时回退 | + +### 4.5 推进原则 + +**双通道共存是整个计划可行的前提。** `registry.go` 按 manifest `entry` 分派 +（阶段 2.4）意味着 `.so` 与 `.bin` 插件可同时运行： + +``` +1. 打通 proc 通道，用 weather 验证 +2. 逐个迁移，其余 .so 继续跑 +3. 全部迁完再删 cabi 路径 +``` + +任何一步失败都能回退，不会出现"改到一半 homed 起不来"。 + +--- + +## 五、待定决策 + +> ⚠️ 本章为第七章实验前的初始状态。**最新裁定见 7.14，正当性清单更新见 9.5。** + +以下需明确后才能进入实施： + +1. **是否全量迁移？** ⏳ **仍待决定**。若只为热重载，阶段 0 即够（1 人日 vs 8-9 周）。 + 全量迁移的理由已从 3 条扩充到 **6 条**（完整对照表见 4.3）。 + 其中 ②崩溃隔离 / ③能力对齐 / ④内置解耦 **无临时替代方案**； + ①热重载 / ⑤lost update / ⑥cgo 缺陷 可先用 `plan.md` 11.1~11.6 打补丁。 + +2. **跨进程锁选型**：~~锁仲裁回内核 vs robust pthread_mutex~~ + ✅ **已裁定：锁仲裁回内核**（实验 3 测得 19.4 µs/次；实验 9 证明持锁进程崩溃可自愈， + 无需 `EOWNERDEAD` 处理）。**新架构完全无 cgo。** + +3. **`Extra` 处置**：✅ **维持原建议**——4 键提升为共享段具名字段，`Extra` 本身留 RPC 副本。 + 第八章的发现进一步支持此选择：外部插件**根本拿不到 `Extra`**（不在下发的 10 个字段内）， + 故通用 tagged union 是为不存在的需求付成本。 + +4. **权限梯度的显式形式**：⏳ 待设计（不阻塞阶段 0-2）。 + **前提已澄清**：内置插件的高权限是**刻意的设计决策**，不是"自己人所以安全"。 + 当前实现把「应有的权限梯度」与「C ABI 的表达能力天花板」混在了一起—— + 外部插件拿不到 `OutputChan` 是技术限制（Go channel 过不了 C ABI）， + 而非权限决定（证据：`case 23/24` 事件订阅是空实现，是"给不了"而非"不给"）。 + 迁移目标是让梯度从**技术意外**变成**显式声明并强制的策略**，而非消除梯度。 + `Selftest`/`Supervisor`/`Tracker` 确认永不对外（见 3.8 能力对齐表最后一行）。 + +--- + +## 六、已验证事实清单 + +本文档结论的实证基础，便于后续复核： + +| 结论 | 验证方式 | 结果 | +|---|---|---| +| Go c-shared 带 `DF_1_NODELETE` | `readelf -d plugin.so` | `FLAGS_1: NODELETE` | +| `dlclose` 对其是 no-op | `/proc/self/maps` 段数 | 5 → 5（不归零） | +| 纯 C `.so` 可真正卸载 | 同上 | 5 → 0，换代码生效 | +| C shim 中间层无法绕过 | 经 shim dlopen/dlclose Go 库 | 5 → 5，仍未卸载 | +| Go c-shared 无 SONAME | `readelf -d \| grep SONAME` | 无（换路径不会被去重） | +| 版本化路径有效 | 两个内容不同的 Go c-shared | handle 不同，ver=v2 生效 | +| 每次重载泄漏 ~5.8 线程 | 30 次连续 dlopen，读 `/proc/self/task` | +168 线程 / +46MB RSS | +| `GOMAXPROCS=1` 缓解有限 | 同上 | 降至 +4.0 线程/次 | +| stage 是并发扇出 | 读 `stages.go:124` | `go func` + `wg.Wait` | +| `Bus.Publish` 同步阻塞 | 读 `bus.go:56` | 内联 `safeCall` 循环 | +| 流式逐 token 发事件 | `process.go:388/470/479` | `EventContentDelta` | +| 外部插件无事件能力 | 读 `loader.go` case 23/24 | 空实现 `return 0` | +| `Extra` 仅 4 个键 | 全量 grep 使用点 | eventloop/process/distill 各处 | +| toolcall payload 很小 | 96 样本统计 | 中位 93 B，最大 134 B | +| 内置/外部方法数 | 对比两个 `PluginSDK` | 28 vs 36，差在活对象 | +| 生命周期机制已完善 | 读 `plugin_health.go`/`toolcall.go` | 3 崩溃/5 分钟、60 秒超时、30 秒冷却 | + +**第七章新增（新架构可行性，11 项）** + +| 结论 | 验证方式 | 结果 | +|---|---|---| +| eventfd 走 netpoller | 200 goroutine 阻塞 `Read`，读 `/proc/self/task` | +1 线程 | +| 跨进程偏移解引用 | 父子进程 mmap 基址对比 | 基址不同，偏移仍正确 | +| memfd + fd 继承可建共享段 | `MemfdCreate` + `ExtraFiles` | 无需 `/dev/shm` 命名与清理 | +| 锁仲裁 RPC 成本 | 20000 次 stdio 往返 | 19.4 µs/次 | +| post-and-forget 解耦流式 | 5000 token + 20µs 慢消费者 | 5.07s → 2.29ms（2218x） | +| 17 子进程常驻开销 | 读 `smaps_rollup` PSS | 29.1MB RSS / 12.9MB PSS | +| 子进程线程数低于单进程 | 对照 homed | 84 vs 108 | +| 崩溃隔离 | 子进程 panic | 退出码 2，EOF 2.5ms，宿主存活 | +| 子进程热重载 | 同路径替换二进制 | v1→v2 立即生效 | +| 跨进程并发改写 StageContext | 5 进程 × 300 轮 append | 358 字符 = 358 长度，零丢失 | +| 持锁进程崩溃自愈 | 持锁 panic 后其他进程申请 | 正常获得，无死锁 | +| 二进制零拷贝 | 100KB/1MB/5MB 对比 | 18-22x，体积 −100% | +| 工具调用 RPC 延迟 | 10000 次真实 payload | p50 19.5 µs | + +**第八章新增（现有实现的真实语义）** + +| 结论 | 验证方式 | 结果 | +|---|---|---| +| 外部插件 stage 是副本模型 | 读 `loader.go:411-439` + `templates.go:768-787` | 快照→新对象→写回 | +| 外部插件 `ctx.Lock()` 是空操作 | 同上链路推演 | 锁的是副本自己的 mu | +| 外部插件字段被裁剪 | 对比下发字段与 `StageContext` | 16 字段只下发 10 | +| **副本模型 lost update 率** | 复刻链路，5 插件 × 2000 轮 | ❗ **36.8%**（内置 0%） | +| `stageContextWritable` 无条件回传 | 读 `templates.go:762` | 非空即回传，未改也传 | +| **现网 sanitizer+weather 冲突** | 复刻场景 3000 轮 | ❗ **1.6~4.3%** 脏数据进 LLM | +| 现网两插件均在运行 | `plugin.json` + `disabled_plugins` + 日志 | 均 8/15 部署，未禁用 | +| `StageScopeOwnTools` 不减并发 | 读 `sdk/plugin.go:304` | SDK 层包装，仍并发调度 | + +**第九章新增（补盲）** + +| 结论 | 验证方式 | 结果 | +|---|---|---| +| 插件类型有四种 | `validBinaries` + `internal/plugin/*.go` | so/dylib/dll + lua + SKILL.md | +| Lua stage 快照无读锁 | 读 `lua_plugin.go:726` | 无 `sc.RLock()`，DATA RACE | +| Windows DLL 只下发 3 字段 | 读 `dynamic_dll_windows.go:231` | 且**完全无写回** | +| **cgo 超时不可中断** | 纯 C 死循环 `.so`，20 次卡死 | ❗ 泄漏 20 goroutine / 18 线程 | +| 子进程 Kill 后零泄漏 | 同实验 B 组 | OS 回收全部资源 | +| **现网已发生工具超时** | 14 天 journal 统计 | ❗ **26 次**（browser 占 22） | +| **`output_send` 永远返回成功** | 读 `loader.go:458-470` + `output.go:65-70` | ❗ 返回 `{status:queued}` | +| **现网已发生发送失败** | 7 天 journal 统计 | ❗ **2 次**，模型收到"已发送" | +| homed 主 heap 2.36GB 真实驻留 | `/proc/PID/status` + maps 分析 | 与插件无关，独立问题 | + +--- + +## 七、前期可行性实验（已执行） + +本章记录第五章「待定决策」与第四章风险项的**实测结论**。 +所有实验代码位于 `/tmp/feas/`，环境 go1.25.12 linux/amd64，本机 192.168.2.60。 + +### 7.1 结论总览 + +| # | 待验证项 | 原假设 | 实测结论 | +|---|---|---|---| +| 1 | eventfd 是否走 netpoller | ⚠️ 待实测 | ✅ **成立**，200 等待者仅 +1 线程 | +| 2 | 跨进程 eventfd + 偏移解引用 | 推理 | ✅ **成立**，不同 mmap 基址正确解引用 | +| 3 | 锁仲裁 RPC 往返成本 | 「微秒级」 | ✅ **19.4 µs/次** | +| 4 | post-and-forget 解耦流式 | 推理 | ✅ **2218x** 加速 | +| 5 | 17 子进程常驻开销 | 估 50-70MB | ✅ **实际 29MB RSS / 12.9MB PSS**，远优于估计 | +| 6 | 崩溃隔离 + 退出码信号源 | 推理 | ✅ 退出码 2，EOF 2.5ms 感知，宿主存活 | +| 7 | 子进程热重载 | 推理 | ✅ 同路径替换即生效，无需版本化路径 | +| 8 | **跨进程并发改写 StageContext** | ⚠️ 最高风险 | ✅ **5 插件 × 300 轮无丢失无撕裂** | +| 9 | 持锁进程崩溃自愈 | 需 robust mutex？ | ✅ **不需要**，内核 Wait/EOF 强制释放 | +| 10 | 二进制零拷贝收益 | 推理 | ✅ **18-22x** 加速，体积省 100% | +| 11 | 工具调用 RPC 延迟 | 「噪声里」 | ✅ p50 **19.5 µs**，占 LLM 往返 0.00065% | + +**本章 11 项全部通过**（另有第一章 dlclose 组 3 项、第九章 cgo 组 2 项，文档合计 18 项可复跑实验）。 +**第五章的 4 个待定决策中，2、3 已由实验裁定。** + +### 7.2 实验 1：eventfd 走 netpoller（原文档标记 ⚠️ 待实测） + +``` +基线线程数: 5 (GOMAXPROCS=12) +200 个 goroutine 阻塞在 eventfd.Read 后: + 线程数 = 6 (增长 1) + ✅ 走 netpoller：线程未随等待者数量增长 +唤醒数 = 200/200 +``` + +**结论**：`os.NewFile(eventfd)` 确实注册进 runtime netpoller，`Read` 只 park goroutine。 +200 个等待者仅增 1 个 OS 线程，验证了 3.6 节的设计前提。 + +反面对照即 `sem_wait`：经 cgo 会阻塞整个 M，200 等待者 = 200 锁死线程。 + +### 7.3 实验 2：跨进程 eventfd + 偏移解引用 + +``` +PARENT: mmap 基址 = 0x7f0137a36000 +CHILD: mmap 基址 = 0x7f1eb3437000 ← 不同虚拟地址 +PARENT: 数据已落地 arena@1024, 描述符 {off:1024, len:28, seq:42} +PARENT: post 耗时 10.85µs ← post-and-forget +CHILD: 被 eventfd 唤醒, 计数=1 +CHILD: 偏移解引用 off=1024 len=28 seq=42 → "hello-from-parent-via-offset" +PARENT: 读到子进程回写 → "CHILD-ACK" ✅ 双向可见 +``` + +**两个关键点得到验证**： + +1. 父子进程 mmap 到**完全不同的虚拟地址**（`0x7f0137a36000` vs `0x7f1eb3437000`）， + 相对偏移 `{off,len}` 仍正确解引用——这正是「偏移替代指针」的核心论据 +2. `memfd_create` + `ExtraFiles` fd 继承即可建立共享段，**无需 `/dev/shm` 命名与清理** + +### 7.4 实验 3：锁仲裁 RPC 成本（裁定决策 2） + +``` +20000 次 stage.lock RPC 往返 用时 388ms, 均摊 19.40 µs/次 +``` + +**裁定：采用「锁仲裁回归内核」，放弃 robust pthread_mutex。** + +19.4 µs 相对 stage handler 的实际工作量（LLM 往返 2-8 秒）完全可忽略。 +换来：零 cgo、无 `EOWNERDEAD` 处理、崩溃自愈（见 7.10）。 + +### 7.5 实验 4：post-and-forget 解耦流式输出 + +模拟 5000 token 流式发布 + 20µs 慢消费者： + +``` +A 同步 Publish (现状): 5000 token 耗时 5.07s 均摊 1014.5 µs/token +B 环+eventfd post: 5000 token 耗时 2.29ms 均摊 0.46 µs/token +加速比 2218.6x 丢弃事件 0 +``` + +**验证了约束 B 的严重性与解法有效性**。现状下一个 20µs 的慢订阅者 +就能让 5000 token 的流式输出多花 5 秒；改为写环 + post 后降到 2.3ms。 + +### 7.6 实验 5：17 子进程常驻开销（修正文档估计） + +``` +存活进程 17/17 +合计: PSS=12.9 MB RSS=29.1 MB 线程=84 +均摊: PSS=0.76 MB RSS=1.71 MB 线程=4.9 +插件二进制大小: 2.68 MB +``` + +**原估计 50-70MB 偏高，实际 29MB RSS / 12.9MB PSS。** +PSS 远低于 RSS 说明 Go runtime 的只读代码页在进程间**共享**了。 + +意外发现的对照数据： + +``` +homed 当前（单进程 + 15 个已映射 .so）: RSS=2344 MB 线程=108 +``` + +线程数 108 **高于** 17 个独立子进程的 84——因为每个 c-shared 映像 +都带自己的 `sysmon`/GC worker，塞在同一进程里并不省线程。 + +### 7.7 实验 6：崩溃隔离 + +``` +正常调用 → map[ok:true] +发送 boom（插件内 panic）... +调用侧感知: EOF (耗时 2.515ms) +进程退出码 = 2 ← panic 的标准退出码 +宿主进程仍存活 ✅ 崩溃已隔离 +``` + +**`plugin_health.go` 的接线方案得到验证**：`exec.ExitError.ExitCode()` 与 +stdio EOF 都能在毫秒级感知，直接喂给现有 `recordCrash(plugin)` 即可， +3 次/5 分钟窗口、30 秒冷却、`pendingReloads` 全部逻辑不动。 + +对照当前 `.so` 模型：bridge 兜不住的 panic 会带崩整个 homed。 + +### 7.8 实验 7：热重载（迁移的原始目标） + +``` +1) 首次启动插件 → version = v1.0.0 +2) 替换二进制为 v2.0.0（同路径） +3) 重启插件进程 → version = v2.0.0 +✅ 同路径替换即生效：无 NODELETE、无版本化路径、无线程泄漏 +``` + +**第 1.1/1.2 节的全部问题在子进程模型下自动消失**： +不需要 `.load/plugin-.so`、不需要重载配额、不需要 ELF 标记检测。 + +### 7.9 实验 8：跨进程并发改写 StageContext（最高风险点 3.4） + +5 个独立进程各 300 轮，通过 RPC 申请内核侧锁，在共享段 append-only arena +上读-改-写同一个 `final_text`： + +``` +最终 final_text 长度 = 358 +各插件写入次数: map[A:76 B:70 C:73 D:73 E:66] +总字符 = 358, 长度 = 358 → 一致 ✅ 无丢失/无撕裂 +RPC 锁操作 = 726 次, 总耗时 213ms +``` + +**总字符数严格等于最终长度**，证明： +- 没有写丢失（lost update） +- 没有撕裂读（torn read） +- 5 个进程的修改都被保留且顺序一致 + +写入次数少于 5×300 是 arena 64KB 上限所致（append-only 未实现压实）， +符合 3.3 节设计——**印证了 arena 需要压实机制**，且上限应在 SDK 层显式报错。 + +**风险 3.4 的核心机制得到验证**，但仍需注意：本实验验证的是**机制正确性**， +不能替代 `sanitizer`/`multimodal` 的**行为回归测试**（4.4 节风险登记仍然有效）。 + +### 7.10 实验 9：持锁进程崩溃自愈（裁定决策 2 的第二半） + +``` +1) 插件 X 拿锁后 panic: + [X] 获得锁 + [X] 进程死亡(exit status 1)，内核强制释放其持有的锁 ← 自愈 +2) 插件 Y 随后申请同一把锁: + [Y] 获得锁 + [Y] 释放锁 +✅ Y 正常获得并释放锁 —— 无死锁 +``` + +**这条彻底排除了 robust pthread_mutex 的必要性**： +锁的所有权在内核进程，插件死亡由 `cmd.Wait()` / stdio EOF 检测， +内核代为释放。不存在「持锁者死亡导致全局死锁」的场景。 + +**故 3.7 节的选型确定：锁仲裁回归内核，整个架构零 cgo。** + +### 7.11 实验 10：二进制零拷贝（未来多媒体能力） + +| payload | JSON+base64 | 共享内存 | 加速 | 体积 | +|---|---|---|---|---| +| 100KB | 1.21 ms，136587 B (+33%) | 62.7 µs，8 B | 19x | −100% | +| 1MB | 12.41 ms，1398155 B (+33%) | 554.7 µs，8 B | 22x | −100% | +| 5MB | 49.30 ms，6990559 B (+33%) | 2.72 ms，8 B | 18x | −100% | + +**共享内存对二进制 payload 的价值确认**：传输体积从 +33% 降为 8 字节描述符， +处理耗时降低约 20 倍。这是 2.5 节「共享内存价值不在省序列化」的**唯一例外**—— +对大块二进制它恰恰就是省序列化。 + +### 7.12 实验 11：工具调用 RPC 延迟 + +用实测的真实 payload 形态（`{"city":"hangzhou","days":3,...}`，约 93 B）10000 次： + +``` +p50 = 19.497µs p90 = 25.447µs p99 = 44.603µs max = 2.256ms +对照 LLM 单轮往返 2-8 秒 → RPC 占比 ≈ 0.00065% +``` + +**验证 2.5 节判断**：控制面用 JSON-RPC 完全够用，无需为它引入共享内存。 + +### 7.13 意外发现：homed 当前内存异常（独立问题） + +实验 5 的对照测量暴露了一个与迁移无关但值得记录的问题： + +``` +homed RSS = 2390432 kB (2.34 GB) + RssAnon = 2354764 kB ← 真实驻留的匿名内存 + RssFile = 35668 kB + VmSize = 26016540 kB (24.8 GB 虚拟) + +匿名映射构成: + 2420.0 MB × 1 = 2.36 GB ← 主 homed 的 Go heap（真实驻留） + 512.0 MB × 15 = 7.50 GB ← 15 个插件各自的 heap arena（虚拟预留） +``` + +两点观察： + +1. **512MB × 15**：每个 Go c-shared 插件各自 mmap 独立 heap arena， + 彼此不可见、GC 各自为政。这是虚拟预留（不占物理内存）， + 但说明当前架构下**插件间内存无法协同回收**——子进程模型下反而更清晰。 + +2. **2.36 GB 真实驻留在主 homed 的 heap** 上，与插件无关。 + 这是独立的内存增长问题（可能是 chat history / context 累积）， + **不影响迁移评估，但应单独排查**。 + +### 7.14 实验后更新的决策状态 + +第五章 4 个待定决策的当前状态： + +| # | 决策 | 状态 | +|---|---|---| +| 1 | 是否全量迁移 | ⏳ **待用户决定**（技术可行性已全部验证） | +| 2 | 跨进程锁选型 | ✅ **已裁定**：锁仲裁回内核，零 cgo（实验 3+9） | +| 3 | `Extra` 处置 | ✅ **维持原建议**：4 键提升为具名字段（实验 2 验证偏移化可行） | +| 4 | 权限梯度显式形式 | ⏳ 待设计（不阻塞阶段 0-2） | + +### 7.15 工作量评估的修订 + +实验结果对第四章的影响： + +| 项 | 原评估 | 修订 | +|---|---|---| +| 3.7 跨进程锁 | 两方案待选，可能需 cgo | **确定零 cgo**，规模 M→S | +| 4.2 eventfd 消费 | ⚠️ 待实测，风险中 | **验证通过**，风险中→低 | +| 3.4 并发扇出 | 风险**高** | 机制已验证，风险高→**中**（行为回归仍需做） | +| 常驻开销 | 估 50-70MB | **实际 29MB**，风险项可关闭 | +| 4.3 Publish 改造 | 风险高 | 收益已量化（2218x），风险高→中 | + +**总量估计从约 10 周下调至约 8-9 周**（3.7 简化 + 3.4/4.2 风险降低）。 + +不变的部分：阶段 5 的 17 个插件逐个回归验证仍是 ~2 周，无法压缩。 + +--- + +## 八、代码检查与实地实验（第二轮） + +第七章验证的是**新架构可行性**；本章检查**现有实现的真实语义**， +并发现了一个先前评估建立在错误前提上的关键事实。 + +### 8.1 核心更正：外部插件从未共享过 StageContext + +第 2.4 节把「stage 并发扇出改写同一对象」列为**约束 A**，并据此论证共享内存的必要性。 +代码检查表明：**该语义只对内置插件成立，外部插件一直是「快照-副本-写回」模型。** + +完整链路（`cabi/loader.go:411-439` + `templates.go:768-787`）： + +``` +① 内核 case 2 handler + sc.RLock() → 快照 7~10 个字段为 JSON → sc.RUnlock() +② 跨 ABI 传字符串 +③ go_invoke_stage + sc := &sdk.StageContext{} ← 插件进程内【全新对象】 + fillStageContext(sc, ctxJSON) +④ 插件 handler 执行 + ctx.Lock() 锁的是这个新对象的 mu ← 无竞争者，纯空转 +⑤ stageContextWritable(sc) → Marshal 回传 +⑥ applyStageResult(sc, result) + sc.Lock() → 逐字段写回内核 sc → sc.Unlock() +``` + +**这是为方便插件加载而采取的无奈之举**（C ABI 无法传递 Go 对象引用）， +但它带来三个先前未被识别的后果。 + +### 8.2 后果一：外部插件的 `ctx.Lock()` 是空操作 + +`sanitizer` 的 stage handler（`example/sanitizer/plugin.go:52-90`）： + +```go +s.RegisterStage(sdk.StageAfterToolcall, func(ctx *sdk.StageContext) error { + ctx.Lock() // ← 锁的是副本自己的 mu + defer ctx.Unlock() // 插件进程内无其他 goroutine 竞争 + for i, tr := range ctx.ToolResults { ... } +}) +``` + +插件作者按文档正确加锁，但该锁**不提供任何跨插件互斥**。 +锁语义在 ABI 边界上静默失效——插件作者无从察觉。 + +### 8.3 后果二：字段可见性被静默裁剪 + +内核只快照 7 个字段 + 3 个条件字段（`loader.go:412-428`）： + +``` +raw_message user_id group_id phase llm_text final_text no_memory ++ response(非 nil) tool_calls(非空) tool_results(非空) +``` + +`StageContext` 实际有 16 个字段。**外部插件永远看不到**： + +``` +ContextMsgs ReasoningContent TokenUsage Memory Extra Errors +``` + +这解释了 3.3 节的一个疑问——`Extra` 只有 4 个键且全由内核读写， +因为**外部插件根本拿不到它**。 + +### 8.4 后果三（严重）：副本模型存在真实的 lost update + +`read-modify-write` 在「快照 → 副本修改 → 写回」链路上**非原子**。 +快照与写回之间的窗口使并发 handler 互相覆盖。 + +**实验 12**（`/tmp/lostupdate/main.go`，精确复刻上述链路，5 插件并发追加标记 × 2000 轮）： + +``` + 内置插件(共享同一对象) 0/2000 轮出现修改丢失 (0.0%) + 外部插件(快照-副本-写回) 735/2000 轮出现修改丢失 (36.8%) +``` + +**内置模型零丢失，外部副本模型丢失率 36.8%。** + +### 8.5 现网影响面核查 + +各 stage 的实际注册者： + +| Stage | 注册者 | 风险 | +|---|---|---| +| `PreAction` | memo(外部) + webui(内置) | ⚡ 外部写回可能覆盖内置修改 | +| `BeforeToolcall` | qq(外部/own_tools) + webui(内置) + cmd(内置) | ⚡ 同上 | +| `AfterToolcall` | **sanitizer(外部/Global) + weather(外部/own_tools)** | ⚠️ **两个外部插件同 stage** | +| `OnInput` | sanitizer(外部) | — | +| `PostAction` | sanitizer(外部) | — | +| `BeforeOutput` | webui(内置) | — | + +**关键点在 `stageContextWritable`（`templates.go:762`）**： + +```go +if len(sc.ToolResults) > 0 { + m["tool_results"] = sc.ToolResults // ← 无条件回传 +} +``` + +只要 `ToolResults` 非空就回传——**即使插件根本没修改它**。 +`weather` 的 handler 只做只读打印，但仍会把**它收到的快照版本**写回内核。 + +### 8.6 实验 13：现网场景复刻（确认脏数据进 LLM） + +精确复刻「模型调用 `weather_query` 时 sanitizer + weather 并发跑 `AfterToolcall`」 +（`/tmp/lostupdate/real.go`，3000 轮）： + +``` +3000 轮中 47 轮清洗结果被覆盖 (1.6%) +⚠️ weather 回传的未清洗快照覆盖了 sanitizer 的清洗结果 +→ 脏数据（ANSI 转义）进入 LLM 上下文 +``` + +> ⚠️ **该比率随机器负载波动**：复跑观测到 **1.6% ~ 4.3%** 区间 +> （取决于两个插件 handler 的实际执行耗时比）。 +> 应理解为「量级在百分之几」而非精确常数。 + +现网条件已确认： + +``` +sanitizer v0.1.0 entry=plugin.so 已部署 2026-08-15 未禁用 +weather v1.0.0 entry=plugin.so 已部署 2026-08-15 未禁用 +运行日志: [sanitizer] stage OnInput/AfterToolcall/PostAction registered +disabled_plugins: 无 +``` + +**这是一个现存的、可复现的、正在生产环境发生的数据污染缺陷**， +概率量级为百分之几（复跑区间 1.6~4.3%，取决于两个插件的实际执行耗时比）。 + +### 8.7 对迁移论证的影响 + +**先前的论证方向被推翻，但结论被强化。** + +| | 先前认识 | 实际情况 | +|---|---|---| +| 共享内存的作用 | **保持**现有并发协作语义 | **修复**副本模型的 lost update | +| 风险 3.4 的性质 | 高风险：可能破坏正确行为 | 中风险：**当前行为本就是错的** | +| 迁移的正当性 | 热重载 + 崩溃隔离 + 能力对齐 | **再加一条：修复现存数据污染** | + +原先担心「跨进程改造会让 `sanitizer`/`multimodal` 行为漂移」—— +实际上外部插件**早已在副本模型下运行**，漂移已经发生了。 +共享内存 + 内核锁仲裁（实验 8 验证零丢失）是**修复**而非**风险**。 + +### 8.8 派生结论：一个可立即修复的缺陷 + +8.5 的根因（`stageContextWritable` 无条件回传未修改字段）**不需要等待迁移**。 + +最小修复：在 `go_invoke_stage` 里记录调用前的字段快照，回传时**只带真正变更的字段**： + +```go +before := stageContextWritable(sc) // 调用 handler 前 +if err := h(sc); err != nil { ... } +after := stageContextWritable(sc) +diff := changedFieldsOnly(before, after) // 只回传 diff +``` + +这能把 8.6 的污染率降到 0（weather 没改 `tool_results`，就不回传它）， +且不改变任何现有插件的代码。 + +**规模 S（约 0.5 人日），风险低，收益立即可见。** +建议加入阶段 0，与三个止血项一并做。 + +### 8.9 更新后的阶段 0（编号已废弃，见 0.3） + +| # | 任务 | 文件 | 规模 | +|---|---|---|---| +| 0.1 | ELF 检测 `DF_1_NODELETE` → 标记不可热重载 | `dynamic_loader_unix.go` | S | +| 0.2 | `ReloadOne` 返回"需重启"，停止假装成功 | `registry.go` | S | +| 0.3 | `plugin_install` 改 `restart_required` | `pluginmgr/plugin.go` | S | +| **0.4** | **`stageContextWritable` 只回传变更字段（修复 8.6 的数据污染）** | `templates.go` + 重编全部外部插件 | S | + +⚠️ 0.4（= `plan.md` 11.3）需重新编译并安装全部 17 个外部插件（bridge 模板变更）， +须走 `plugindev` 正规工具链 + `plugin_install` 内核接口。 + +> **本节编号已废弃**，实施请用 `plan.md` 的 11.1~11.6（对应关系见 0.3）。 + +### 8.10 第二轮实验汇总 + +| # | 检查/实验 | 结论 | +|---|---|---| +| 12 | 副本模型 lost update 率 | ❗ **36.8%**（内置模型 0%） | +| 13 | 现网 sanitizer+weather 冲突 | ❗ **1.6~4.3%** 脏数据进 LLM | +| — | 外部插件 stage 语义 | ❗ 一直是副本，非共享 | +| — | 外部插件 `ctx.Lock()` | ❗ 空操作，锁语义静默失效 | +| — | 外部插件字段可见性 | ❗ 16 字段中 6 个不可见 | +| — | `stageContextWritable` | ❗ 无条件回传未修改字段（8.6 根因） | +| — | `StageScopeOwnTools` 过滤 | ✅ 在 SDK 层包装（`sdk/plugin.go:304`），不减少并发 | + +--- + +## 九、补盲分析（第三轮） + +第八章发现外部插件 stage 是副本模型；本章继续排查此前评估**完全未覆盖**的区域， +新发现 4 类问题，其中 2 项正在生产环境造成实际故障。 + +### 9.1 盲区一：插件类型不止两种，Lua 路径存在数据竞争 + +此前全程只讨论 native（内置）与 cabi（`.so`）两类。实际有**四种加载路径**： + +``` +internal/plugin/lua_plugin.go 978 行 ← 完全未评估 +internal/plugin/dynamic_lua.go 24 行 +internal/plugin/dynamic_dll_windows.go ← 完全未评估 +internal/plugin/dynamic_loader_unix.go +``` + +`validBinaries` 印证了这一点： + +```go +var validBinaries = map[string]bool{ + "plugin.so": true, "plugin.dylib": true, "plugin.dll": true, + "main.lua": true, "SKILL.md": true, // ← Lua 与 Skill +} +``` + +**Lua stage handler 同为副本模型，但缺少读锁保护**： + +| 路径 | 快照时是否持锁 | +|---|---| +| cabi（`loader.go:412`） | ✅ `sc.RLock()` → 快照 → `sc.RUnlock()` | +| Lua（`lua_plugin.go:726`） | ❌ **直接读 `sc.RawMessage` 等字段，无锁** | + +```go +func makeStageHandler(...) sdk.StageHandler { + return func(sc *sdk.StageContext) error { + plg.mu.Lock() // ← 锁的是 Lua VM，不是 sc + defer plg.mu.Unlock() + ctx := map[string]interface{}{ + "raw_message": sc.RawMessage, // ← 无 sc.RLock() + "llm_text": sc.LLMText, + ... + } +``` + +由于 `RunStage` 是并发扇出，这与其他 handler 的 `sc.Lock()` 构成**数据竞争**： +Go race detector 会报 DATA RACE，string header 并发读写理论上可读到撕裂值。 + +**现网影响**：当前未部署 Lua 插件（`find` 无 `main.lua`），故暂未触发。 +但这是一个**已存在的缺陷**，一旦部署 Lua 插件 + 任意其他 stage 插件即可触发。 + +### 9.2 盲区二：Windows DLL 路径能力严重退化 + +`dynamic_dll_windows.go:227-245` 的 stage 实现： + +```go +ctxJSON, _ := json.Marshal(map[string]interface{}{ + "raw_message": sc.RawMessage, + "user_id": sc.UserID, + "phase": string(sc.Phase), +}) +syscall.SyscallN(p.invokeStage, p.handle, ...) +return nil // ← 无 resultOut，无 applyStageResult +``` + +三条路径的字段可见性对比： + +| 路径 | 下发字段数 | 写回 | +|---|---|---| +| Linux cabi | 10（7 固定 + 3 条件） | ✅ `applyStageResult` | +| Lua | 10 | ✅ `applyLuaStageResult` | +| **Windows DLL** | **3** | ❌ **完全没有** | + +**后果**：`sanitizer` 这类改写型插件在 Windows 上**静默失效**—— +handler 正常执行、日志正常打印，但所有修改被丢弃。 +且看不到 `llm_text`/`final_text`/`tool_calls`/`tool_results`， +意味着 Windows 上的外部插件基本无法做任何有意义的 stage 处理。 + +**这是跨平台一致性的严重缺口**，且没有任何运行时警告。 + +### 9.3 盲区三（严重）：cgo 调用不可中断，工具超时永久泄漏 + +`toolcall.go:32-43` 的超时保护： + +```go +done := make(chan string, 1) +go func() { done <- a.executeToolCallInner(tc) }() +select { +case result := <-done: return result +case <-time.After(60 * time.Second): + return "工具执行超时（60秒），已取消" // ← "已取消"是不准确的 +} +``` + +**`select` 超时只是让调用方返回，goroutine 仍卡在 `C.call_invoke_tool` 里。 +cgo 调用不可被 Go runtime 抢占或取消**——C 函数不返回，该 M（OS 线程）永久占用。 + +**实验 14**（`/tmp/feas/hang/`，纯 C 死循环 `.so`，20 次卡死调用）： + +``` +基线 threads=6 goroutines=1 + 5 次卡死调用后: goroutines= 6 threads= 9 (+3) + 10 次卡死调用后: goroutines=11 threads=14 (+8) + 15 次卡死调用后: goroutines=16 threads=19 (+13) + 20 次卡死调用后: goroutines=21 threads=24 (+18) + +结论: 20 次超时 → 泄漏 20 goroutine, 18 OS 线程 +``` + +**线性泄漏，永不回收。** 对照子进程模型（同实验 B 组）： +`cmd.Process.Kill()` 后 OS 回收全部资源，**零泄漏**。 + +**现网已在发生**（近 14 天日志）： + +``` + 9 tool browser_screenshot timed out after 60s + 5 tool browser_render + 2 tool output_send__webui + 2 tool browser_type + 2 tool browser_start + 2 tool browser_click + 1 tool cmd_run / browser_html / browser_fetch + ───── + 26 次超时 → 推算泄漏约 26 goroutine + 20+ OS 线程 +``` + +`browser` 插件是主要来源（22/26）。这部分解释了 homed 的 108 线程 +——虽然本次运行 9.5 小时内无超时（`futex_wait_queue` 100 个属正常 Go 调度）， +但历史进程（如 `homed[1063615]`、`homed[2609279]`）在超时后必然累积了泄漏。 + +**这是「60 秒超时保护」的语义谎言**：日志说"已取消"，实际什么都没取消。 + +### 9.4 盲区四（严重）：output_send 永远返回成功，模型无法感知发送失败 + +`cabi/loader.go:458-470` 的注释直接点明了原因： + +```go +s.RegisterOutputChannel(chName, n1, a2, chDef, func(args ...) (interface{}, error) { + // Output is async: return immediately, send in background + // to avoid nested cgo calls (cgo within cgo can crash) + go func() { + if err := pluginInvokeOutput(pid, chName, string(argsJSON)); err != nil { + log.Printf("[dispatch] async output %s/%s failed: %v", ...) // ← 仅日志 + } + }() + return map[string]interface{}{"status": "queued"}, nil // ← 立即返回"成功" +}) +``` + +**「cgo 嵌套会崩」这个 C ABI 限制，逼出了 fire-and-forget 设计。** + +完整链路（`output.go:65-70`）： + +``` +模型调用 output_send__qq + → dev.Execute("output", args) 返回 {status: queued}, err=nil + → 模型看到: 「已通过 [qq] 通道发送: map[status:queued]」 ← 成功 + → 数十毫秒后 goroutine 里真实发送失败，仅写日志 + → 模型不知道、不重试；用户收不到消息 +``` + +**现网证据**（近 7 天）： + +``` +成功 44 次，失败 2 次 + +Aug 30 15:10:51 [dispatch] async output qq/qq failed: + invoke_output qq: meta 中需要 group_id 或 user_id 字段 +``` + +那一次模型收到的是「已发送」，实际消息从未送达。 + +**这与此前的排查直接相关**：之前诊断「qq 渠道回复丢失」时修复了系统提示词 +（强调 qq 是异步通道、必须用 `output_send`），但**未发现 `output_send` 本身 +永远返回成功**。模型即使正确调用了工具，也无法知道是否真的送达。 + +### 9.5 子进程模型对这四项的修复能力 + +| 盲区 | 根因 | 子进程模型 | +|---|---|---| +| 9.1 Lua 无读锁 | 实现疏漏（非架构） | 需单独修；统一走 RPC 后天然有边界 | +| 9.2 Windows 退化 | 三套独立 ABI 实现 | ✅ **单一 RPC 实现，跨平台一致** | +| 9.3 超时不可中断 | cgo 调用不可抢占 | ✅ **`Process.Kill()` 真正取消，零泄漏** | +| 9.4 output 假成功 | cgo 嵌套会崩 | ✅ **可同步等待真实结果** | + +9.2/9.3/9.4 都是**C ABI 前提的直接产物**——三套 ABI 实现、cgo 不可抢占、 +cgo 不可嵌套。这三条在进程边界下全部消失。 + +**迁移的正当性清单更新为 6 条**（完整版含依据与临时修复对照见 4.3）： + +1. 热重载（原始动机） +2. 崩溃隔离 +3. 能力断层消除 +4. 内置插件解耦 +5. **修复 stage 副本模型的 lost update**（第八章） +6. **修复超时泄漏、output 假成功、Windows 能力退化**（本章） + +其中 **②③④ 没有临时替代方案**，是迁移的不可替代价值；①⑤⑥ 可先打补丁。 + +### 9.6 可立即修复项（不依赖迁移） + +> ⚠️ **本表 A-F 编号已废弃**，仅存档分组思路。实施请用 `plan.md` 的 11.1~11.6。 +> 对应关系：A→11.1、B→11.3、C→11.4、D→11.2、E→11.5、F→11.6。 + +按「影响 × 成本」排序： + +| # | 修复 | 影响 | 规模 | 备注 | +|---|---|---|---|---| +| **A** | `output_send` 改同步等待结果 | ❗ 消除"假成功"，模型可重试 | M | 需绕开 cgo 嵌套：用 channel 把结果从 goroutine 传回并等待，而非在 cgo 栈内嵌套调用 | +| **B** | `stageContextWritable` 只回传变更字段 | ❗ 消除数据污染（8.6） | S | 需重编 17 插件 | +| **C** | Lua stage 快照加 `sc.RLock()` | 消除潜在 DATA RACE | S | 3 行改动 | +| **D** | 超时日志措辞改为"已放弃等待（插件仍在运行）" | 消除语义谎言 | S | 1 行；真正取消需子进程 | +| **E** | Windows stage 补齐字段 + 写回 | 跨平台一致 | M | 无 Windows 环境验证 | +| F | 阶段 0 的 0.1/0.2/0.3（ELF 检测等） | 消除 reload 误导 | S | 见 4.1 | + +**A 是最高优先级**：它直接影响用户可感知的行为（消息发不出去而模型以为成功）， +且现网已有 2 次实际发生。 + +⚠️ A 的实现要点：不能简单改成同步调用（会触发 cgo 嵌套崩溃）。 +可行做法是保留 goroutine，但用带超时的 channel 等待其结果： + +```go +resCh := make(chan error, 1) +go func() { resCh <- pluginInvokeOutput(pid, chName, argsJSON) }() +select { +case err := <-resCh: + if err != nil { return nil, err } // 真实失败上报 + return map[string]interface{}{"status": "sent"}, nil +case <-time.After(10 * time.Second): + return map[string]interface{}{"status": "queued", "note": "发送超时未确认"}, nil +} +``` + +这样 `dev.Execute` 的调用栈不在 cgo 内（它由 `executeOutputSendTool` 从 Go 侧调起）， +goroutine 内的 `pluginInvokeOutput` 才是 cgo 调用——不构成嵌套。 +**需实测验证不触发崩溃。** + +### 9.7 第三轮汇总 + +| # | 发现 | 严重度 | 现网状态 | +|---|---|---|---| +| 9.1 | Lua stage 快照无 `RLock`，DATA RACE | 中 | 未触发（无 Lua 插件） | +| 9.2 | Windows DLL 只下发 3 字段且无写回 | 高 | 未验证（无 Windows 部署） | +| 9.3 | cgo 超时不可中断，线性泄漏 goroutine+线程 | **高** | ❗ **已发生 26 次** | +| 9.4 | `output_send` 永远返回成功 | **高** | ❗ **已发生 2 次** | +| — | 实验 14：20 次卡死 → 泄漏 20 goroutine/18 线程 | — | 已复现 | +| — | 子进程 Kill 后零泄漏 | — | 已验证 | + +--- + +## 十、文档维护说明 + +### 10.1 三轮验证的递进关系 + +| 章 | 目的 | 方法 | 主要产出 | +|---|---|---|---| +| 一~六 | 建立评估框架 | 代码阅读 + 推理 | 目标架构、工作量、待定决策 | +| 七 | 验证**新架构可行性** | 11 项独立实验（`/tmp/feas/`） | 全部通过；裁定锁选型 | +| 八 | 检查**现有实现真实语义** | 精读 ABI 链路 + 复刻实验 | ❗ 推翻"约束 A"前提；发现现网污染 | +| 九 | **补盲**：此前未覆盖区域 | 遍历全部加载路径 + journal 统计 | ❗ 4 类新缺陷，2 项现网故障 | + +**方法论教训**：第八章推翻了第二章基于代码阅读得出的一个核心前提 +（"stage 并发扇出改写同一对象"对外部插件不成立）。 +**读到 `RunStage` 的并发扇出就推断所有插件共享 `StageContext`， +漏掉了 ABI 边界会把引用降级为副本。** 后续评估应对每条跨边界路径单独追踪， +不能从进程内语义外推。 + +### 10.2 前文中已被后续章节修订的表述 + +以下位置保留了原始表述并加了指向更正的标注，阅读时请以后者为准： + +| 位置 | 原表述 | 更正 | +|---|---|---| +| 2.4 约束 A | stage 并发改写同一对象 | 仅对内置插件成立（第八章） | +| 2.2 代码规模表 | 只列 native + cabi | 实际四种加载路径（9.1/9.2） | +| 4.1 阶段 0 | 3 项（仅 reload 语义） | 7 项，新增 4 项优先级更高（9.6） | +| 4.2 总量 | 约 10 周 | 约 8-9 周（7.15） | +| 4.3 正当性 | 3 条 | **6 条**（4.3 与 9.5 已统一口径） | +| 4.4 风险表 | eventfd 待实测、开销 50-70MB | 已排除 / 实测 29MB | +| 五、待定决策 | 4 项全待定 | 2 项已裁定（7.14） | +| 3.6 eventfd | ⚠️ 待实测 | ✅ 已通过（7.2） | +| 3.7 锁选型 | 倾向锁仲裁回内核 | ✅ 已裁定（7.4/7.10） | + +### 10.3 实验代码（已固化入库） + +全部 18 项实验已固化到 [`experiments/plugin-arch/`](experiments/plugin-arch/)， +带一键复跑脚本，**不再依赖 `/tmp`**： + +```bash +cd docs/zh/experiments/plugin-arch +./run.sh # 全部 18 项，约 3-5 分钟 +./run.sh 12 13 # 只跑指定实验 +``` + +| 目录 | 主题 | 对应章节 | +|---|---|---| +| `01-dlclose-nodelete/` | `dlclose` 对 `DF_1_NODELETE` 是 no-op（3 项） | 1.1 / 1.2 | +| `02-feasibility/` | 新架构可行性（11 项） | 第七章 | +| `03-lost-update/` | 副本模型 lost update（2 项） | 8.4 / 8.6 | +| `04-cgo-uninterruptible/` | cgo 调用不可中断（2 项） | 9.3 | + +实现要点：源码均带 `//go:build ignore`（不进主构建）， +`run.sh` 在 `mktemp -d` 内构建（不污染主仓 `go.mod`）， +需 `x/sys` 的实验按需拉取（本机走 clash `127.0.0.1:7890`）。 + +**复跑验证**：2026-08-31 全量跑通，18/18 通过。 + +⚠️ **部分数字随调度波动**，详见 `experiments/plugin-arch/README.md` 的 +「复跑时的注意事项」——其中区分了「允许波动」与「不应变的断言」。 +最重要的一条：**8.6 的 1.6% 污染率在复跑中观测到 1.6%~4.3% 区间**， +应理解为「量级在百分之几」而非精确常数。 + +### 10.4 与 plan.md 的分工 + +- **本文档**：论证、实验数据、架构设计、决策依据 —— 回答"为什么"和"怎么设计" +- **`plan.md` 第 11 节**：可勾选的修复项、文件级改动位置、实施顺序 —— 回答"做什么" + +修复项的进度只在 `plan.md` 维护，本文档不重复勾选状态。 diff --git a/plan.md b/plan.md index cb189ff..e903340 100644 --- a/plan.md +++ b/plan.md @@ -592,3 +592,318 @@ CLI 本机自执行命令已有 cmd 插件，不做反向操控 CLI。 - Step3：生命周期（window-all-closed 退出进托盘依偏好、before-quit 清理托盘/设备桥）— 显示正常 ✅ **最终版已安装**：/opt/HomeAgent（md5 047f2f1bbe，备份 /tmp/ha-app-step3-final.asar），含：设备桥 / 设备页+授权开关 / 惰性托盘 / prefs 持久化 / 退出进托盘 / 字体/圆角（renderer）。 + +--- + +## 11. 插件架构缺陷修复 + 子进程化迁移评估 + +> 完整评估文档：[`docs/zh/架构迁移评估.md`](docs/zh/架构迁移评估.md) +> —— **先读其第零章「给接手者的阅读指引」**，该文档是增量写成的，前六章部分结论已被后续推翻。 +> 可复跑实验：[`docs/zh/experiments/plugin-arch/`](docs/zh/experiments/plugin-arch/)（18 项，`./run.sh`） +> +> **本节 11.1~11.6 是修复项的唯一权威编号。** 评估文档中出现的 `0.x` / `A-F` +> 仅为历史分组，勿用于实施。本节只列可执行项与决策状态；论证与数据见评估文档。 + +### 11.0-pre 三个易被误解的前提（动手前必读） + +1. **stage 的并发扇出是原始设计，不是缺陷。** + `stages.go:124` 的 `go func` + `wg.Wait()` 是刻意的，`StageContext` 的 `RWMutex` + 与公开 `Lock/RLock` 就是为它准备的。**问题是 C ABI 把外部插件降级成副本模型**， + 使那把锁在 ABI 边界外变成空转（内置 0% 丢失 vs 副本 35.8~36.8%）。 + → 不要试图"取消并发"来修 11.3。 + +2. **内置插件的高权限是刻意设计，不是"自己人所以安全"。** + 但当前实现混淆了「应有的权限梯度」与「C ABI 表达能力天花板」： + 外部插件拿不到 `OutputChan`/`Subscribe` 是技术限制（`case 23/24` 是空实现， + 属"给不了"），而非权限决定。迁移目标是让梯度**显式化并强制**，不是消除梯度。 + +3. **副本模型是"为方便插件加载的无奈之举"。** + C ABI 用于绕开 Go 原生 `plugin` 包的同版本限制，副本模型是其必然代价。 + 问题在于该代价未被记录、后果未被发现——不是当初的选择错了。 + +### 11.0 起因 + +更换 `plugin.so` 后 `plgreload` 报成功但运行旧代码。根因是 Go c-shared 的 +ELF `DF_1_NODELETE` 标记使 `dlclose` 成为 no-op，**换 `.so` 必须重启 homed**。 +排查该问题时连带发现 6 类此前未知的缺陷，其中 **2 项正在生产环境造成故障**。 + +### 11.1 紧急：output_send 永远返回成功 ⚠️ 现网已发生 + +**现象**：模型调用 `output_send__qq` 收到「已发送」，但消息实际未送达，模型不知道也不重试。 + +**根因**（`internal/plugin/cabi/loader.go:458-470`）——注释自己写明了原因： + +```go +// Output is async: return immediately, send in background +// to avoid nested cgo calls (cgo within cgo can crash) +go func() { + if err := pluginInvokeOutput(pid, chName, argsJSON); err != nil { + log.Printf("[dispatch] async output %s/%s failed: %v", ...) // ← 仅日志 + } +}() +return map[string]interface{}{"status": "queued"}, nil // ← 立即返回"成功" +``` + +`output.go:65-70` 拿到 `{status:queued}` + `err=nil`，返回给模型「已通过 [qq] 通道发送」。 + +**现网证据**（近 7 天）：成功 44 次，失败 2 次。 + +``` +Aug 30 15:10:51 [dispatch] async output qq/qq failed: + invoke_output qq: meta 中需要 group_id 或 user_id 字段 +``` + +**与此前排查的关系**：之前诊断「qq 渠道回复丢失」时修复了系统提示词 +（`a3a5cd4`，强调 qq 是异步通道、必须用 `output_send`）， +但**未发现 `output_send` 本身永远报成功**——模型即使正确调用也无法感知失败。 + +**修复方案**（保留 goroutine + 带超时 channel 等待，避免 cgo 嵌套）： + +```go +resCh := make(chan error, 1) +go func() { resCh <- pluginInvokeOutput(pid, chName, argsJSON) }() +select { +case err := <-resCh: + if err != nil { return nil, err } // 真实失败上报 + return map[string]interface{}{"status": "sent"}, nil +case <-time.After(10 * time.Second): + return map[string]interface{}{"status": "queued", "note": "发送超时未确认"}, nil +} +``` + +`dev.Execute` 由 `executeOutputSendTool` 从 Go 侧调起（不在 cgo 栈内）， +goroutine 里的 `pluginInvokeOutput` 才是 cgo 调用，**不构成嵌套**。 + +- [ ] 实现修复 +- [ ] **实测验证不触发 cgo 嵌套崩溃**（此判断为推理，必须实测） +- [ ] 构造 meta 缺 `user_id` 的失败场景，确认模型收到错误而非"已发送" + +### 11.2 紧急：cgo 工具超时不可中断，线性泄漏 ⚠️ 现网已发生 26 次 + +**现象**：`toolcall.go:41` 日志称「已取消」，实际什么都没取消。 + +**根因**：`select` 超时只让调用方返回，goroutine 仍卡在 `C.call_invoke_tool` 里。 +**cgo 调用不可被 Go runtime 抢占或取消**，该 OS 线程永久占用。 + +**实验 14 实测**（纯 C 死循环 `.so`，20 次卡死调用）： + +``` + 5 次后: goroutines= 6 threads= 9 (+3) +10 次后: goroutines=11 threads=14 (+8) +20 次后: goroutines=21 threads=24 (+18) +线性泄漏，永不回收 +``` + +对照：子进程模型 `Process.Kill()` 后 OS 回收全部资源，**零泄漏**。 + +**现网统计**（近 14 天 26 次超时）： + +``` + 9 browser_screenshot 2 browser_type 1 cmd_run + 5 browser_render 2 browser_start 1 browser_html + 2 output_send__webui 2 browser_click 1 browser_fetch +``` + +`browser` 插件占 22/26。历史进程（`homed[1063615]`、`homed[2609279]`）必然已累积泄漏。 + +- [ ] **短期**：日志措辞改为「已放弃等待（插件仍在后台运行，其占用的线程无法回收）」 + —— 消除语义谎言，1 行改动 +- [ ] **短期**：排查 `browser` 插件为何频繁 60s 超时（22/26 集中于它） +- [ ] 真正的取消能力需子进程模型（见 11.7） + +### 11.3 stage 副本模型的 lost update ⚠️ 现网数据污染（量级百分之几） + +**核心事实更正**：外部 `.so` 插件**从未共享过 `StageContext`**，一直是「快照-副本-写回」： + +``` +内核 sc.RLock() → 快照 10 字段为 JSON → 跨 ABI + → go_invoke_stage: sc := &sdk.StageContext{} ← 插件进程内全新对象 + → handler 改副本（其 ctx.Lock() 是空操作，无跨插件互斥） + → stageContextWritable → Marshal 回传 + → applyStageResult: sc.Lock() 逐字段写回 +``` + +这是**为方便插件加载的无奈之举**（C ABI 无法传 Go 对象引用），但带来三个后果： + +1. **`ctx.Lock()` 是空操作** —— 插件按文档正确加锁，锁语义在 ABI 边界静默失效 +2. **字段被裁剪** —— 16 个字段只下发 10 个，`ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` 外部插件永远看不到 +3. **lost update** —— read-modify-write 非原子，实验 12 实测丢失率 **36.8%**（内置模型 0%） + +**现网触发点**：`AfterToolcall` 上有两个外部插件 + +| Stage | 注册者 | 风险 | +|---|---|---| +| `AfterToolcall` | **sanitizer**(Global,改写 ToolResults) + **weather**(own_tools,只读) | ⚠️ 真实冲突 | +| `PreAction` | memo(外部) + webui(内置) | ⚡ | +| `BeforeToolcall` | qq(外部) + webui(内置) + cmd(内置) | ⚡ | + +根因在 `templates.go:762` —— **无条件回传未修改字段**： + +```go +if len(sc.ToolResults) > 0 { + m["tool_results"] = sc.ToolResults // weather 没改也回传它收到的旧快照 +} +``` + +**实验 13 复刻现网场景**（模型调用 `weather_query`，3000 轮）： + +``` +47 轮 sanitizer 的清洗结果被 weather 的旧快照覆盖 (1.6%) +→ 脏数据（ANSI 转义）进入 LLM 上下文 +``` + +⚠️ **该比率不是常数**：三次复跑得 1.6% / 2.1% / 4.3%，取决于两插件 handler 的 +实际耗时比。**应表述为「量级百分之几」**，不要把 1.6% 当精确值写进代码注释或对外说明。 + +⚠️ **修复方向的红线**：不要通过"把 `RunStage` 改成串行"来消除冲突。 +并发扇出是原始设计（见 11.0-pre 第 1 条），串行化会改变所有 stage 插件的时序语义， +且掩盖真正的根因（副本模型 + 无条件回传）。正确做法是让回传只带真正变更的字段。 + +现网条件已确认：sanitizer v0.1.0 / weather v1.0.0 均 8/15 部署、`disabled_plugins` 为空、 +日志有 `[sanitizer] stage OnInput/AfterToolcall/PostAction registered`。 + +**修复**：`stageContextWritable` 只回传**真正变更**的字段 + +```go +before := stageContextWritable(sc) +if err := h(sc); err != nil { ... } +diff := changedFieldsOnly(before, stageContextWritable(sc)) +``` + +- [ ] 实现 diff 回传 +- [ ] ⚠️ **需重新编译并安装全部 17 个外部插件**（bridge 模板变更） + —— 必须走 `plugindev` 正规工具链 + `plugin_install(url, overwrite=true)` 内核接口 +- [ ] 验证：weather_query 调用后 tool_results 保持已清洗状态 + +### 11.4 Lua stage 快照缺读锁（DATA RACE） + +`lua_plugin.go:726` 直接读 `sc.RawMessage` 等字段，**未持 `sc.RLock()`**： + +| 路径 | 快照时是否持锁 | +|---|---| +| cabi（`loader.go:412`） | ✅ `sc.RLock()` | +| Lua（`lua_plugin.go:726`） | ❌ 无锁 | + +`RunStage` 是并发扇出，这与其他 handler 的 `sc.Lock()` 构成数据竞争。 + +**现网未触发**（无 Lua 插件部署，`find` 无 `main.lua`），但缺陷已存在。 + +- [ ] 加 `sc.RLock()`/`sc.RUnlock()` 包裹快照构造（约 3 行） + +### 11.5 Windows DLL 路径能力严重退化 + +`dynamic_dll_windows.go:227-245`： + +```go +ctxJSON, _ := json.Marshal(map[string]interface{}{ + "raw_message": sc.RawMessage, "user_id": sc.UserID, "phase": string(sc.Phase), +}) // ← 只有 3 个字段 +syscall.SyscallN(p.invokeStage, p.handle, ...) +return nil // ← 无 resultOut，无 applyStageResult +``` + +| 路径 | 下发字段 | 写回 | +|---|---|---| +| Linux cabi | 10 | ✅ | +| Lua | 10 | ✅ | +| **Windows DLL** | **3** | ❌ **完全没有** | + +**后果**：`sanitizer` 类改写型插件在 Windows 上**静默失效**——handler 正常执行、 +日志正常打印，修改全部丢弃；且看不到 `llm_text`/`tool_calls`/`tool_results`。 + +- [ ] 补齐字段下发 + 写回（无 Windows 环境，需借测试机验证） + +### 11.6 reload 语义谎言（原始起因） + +`plgreload` 对 `.so` 插件报成功但运行旧代码。已实验确证 `dlclose` 对 +`DF_1_NODELETE` 是 no-op，且**套任何层数的 C 中间件都绕不过去** +（NODELETE 属于被卸载对象自身的 ELF 属性）。 + +已评估并**否决**版本化路径方案：技术上可行，但每次重载永久泄漏 +**5.8 个线程 + 1.5MB**（30 次实测 +168 线程 / +46MB），对 24/7 常驻进程不可接受。 + +- [ ] ELF 检测 `DF_1_NODELETE` → 标记插件"不可热重载"（`dynamic_loader_unix.go`） +- [ ] `ReloadOne` 对此类插件返回"需重启 homed"，停止假装成功（`registry.go`） +- [ ] `plugin_install` 返回 `restart_required` 替代误导性的 `reload_required`（`pluginmgr/plugin.go`） + +### 11.7 子进程 + 共享内存架构迁移（待决策） + +**目标架构**： + +``` +今天： homed ──dlopen──> plugin.so（cgo bridge 385 行 + 51 个整数 method id） + ↑ C 层唯一目的：绕开 Go plugin 包同版本限制 + +之后： homed ──spawn──> plugin（纯 Go 二进制，零 cgo） + ├── stdio JSON-RPC 控制面：51 个 case 平移为 method 名 + ├── shm + 偏移 数据面：StageContext 并发改写、二进制零拷贝 + └── eventfd 通知面：事件环 post-and-forget +``` + +**关键洞察**：C 中间层存在的唯一理由是绕开 Go 原生 `plugin` 包的版本枷锁。 +子进程模型下**进程边界本身就是 ABI 边界**，C 层解决的问题消失，C 层自己也就该消失。 +可删除 `cabi/` 1096 行 + 每插件 385 行 bridge 模板。 + +**11 项可行性实验全部通过**（详见评估文档第七章）： + +| 验证项 | 结果 | +|---|---| +| eventfd 走 netpoller | ✅ 200 等待者仅 +1 线程 | +| 跨进程偏移解引用 | ✅ 父子 mmap 不同基址仍正确 | +| 锁仲裁 RPC 成本 | ✅ 19.4 µs/次 | +| post-and-forget 解耦流式 | ✅ 2218x 加速 | +| 17 子进程常驻开销 | ✅ 29MB RSS（原估 50-70MB） | +| 崩溃隔离 + 退出码信号 | ✅ 退出码 2，EOF 2.5ms 感知 | +| 子进程热重载 | ✅ 同路径替换即生效 | +| **跨进程并发改写 StageContext** | ✅ 5 插件×300 轮零丢失 | +| 持锁进程崩溃自愈 | ✅ 无需 robust mutex，**零 cgo** | +| 二进制零拷贝 | ✅ 18-22x，体积省 100% | +| 工具调用 RPC 延迟 | ✅ p50 19.5 µs | + +**工作量约 8-9 周**（6 阶段，详见评估文档第四章）。 +双通道共存（按 manifest `entry` 分派 `.so`/`.bin`）使迁移可逐插件推进、随时回退。 + +**迁移正当性 6 条**：① 热重载 ② 崩溃隔离 ③ 能力断层消除 +④ 内置插件解耦 ⑤ 修复 stage lost update ⑥ 修复超时泄漏/output 假成功/Windows 退化 + +其中 ②③④⑥ 全是 C ABI 前提的直接产物（三套 ABI 实现、cgo 不可抢占、cgo 不可嵌套）， +在进程边界下自动消失。 + +**待决策**： + +- [ ] **是否全量迁移？** 若只为热重载，11.6（1 人日）即够；8-9 周投入的理由必须是 ②-⑥ +- [x] 跨进程锁选型 → **已裁定**：锁仲裁回内核，零 cgo（实验 3+9） +- [x] `Extra` 处置 → **维持**：4 键提升为具名字段，`Extra` 留 RPC 副本 +- [ ] 权限梯度显式形式（manifest 声明 caps？内核白名单？） + —— 注：内置插件的高权限是**刻意设计**，迁移目标是让梯度从"C ABI 表达能力的 + 意外产物"变成"显式声明并强制的策略"，而非消除梯度 + +### 11.8 实施顺序建议 + +按「影响 × 成本」排序，前 4 项不依赖迁移决策： + +| 序 | 项 | 规模 | 现网影响 | +|---|---|---|---| +| 1 | **11.1** output_send 同步等结果 | M | ❗ 用户收不到消息且模型以为成功 | +| 2 | **11.3** stageContextWritable diff 回传 | S | ❗ 脏数据进 LLM（量级百分之几） | +| 3 | **11.6** reload 语义修正（3 项） | S | 误导模型白跑重载 | +| 4 | **11.2** 超时日志措辞 + browser 排查 | S | 已泄漏 26 次 | +| 5 | 11.4 Lua 读锁 | S | 潜在 | +| 6 | 11.5 Windows 补齐 | M | 无部署 | +| 7 | 11.7 迁移（待决策） | 8-9 周 | — | + +### 11.9 附带发现（独立问题，非本节范围） + +测量对照数据时发现 homed 内存异常： + +``` +homed RSS = 2.34 GB RssAnon = 2.35 GB（真实驻留） + 2420 MB × 1 ← 主 homed 的 Go heap + 512 MB × 15 ← 15 个插件各自的 heap arena（虚拟预留，不占物理内存） +``` + +512MB×15 说明当前架构下**插件间内存无法协同回收**（各自独立 Go runtime）。 +但 **2.36 GB 真实驻留在主 homed heap 上，与插件无关**，疑似 chat history / +context 累积导致的内存增长。 + +- [ ] 单独排查 homed 主 heap 的 2.36GB 驻留来源 From fa99f6b4eb7a214d8c121e951ffed91eddfda8be Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 11:52:31 +0800 Subject: [PATCH 02/27] =?UTF-8?q?docs(plugin-arch):=20=E5=A4=96=E9=83=A8?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E6=8E=A5=E5=8F=A3=E4=B8=8D=E5=8F=98=E7=9F=A9?= =?UTF-8?q?=E9=98=B5=EF=BC=88=E5=A4=9A=E8=BF=9B=E7=A8=8B=E5=8C=96=E6=95=B4?= =?UTF-8?q?=E6=94=B9=E5=9F=BA=E7=BA=BF=20v1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 钉死「暴露给外部插件的接口不变」约束的合同面： - 合同面A: 公开SDK类型/接口（sdk/plugin.go等，纯Go无cgo） - 合同面B: bridge 51个method id ↔ SDK方法映射表（RPC平移清单） - 合同面C: StageContext 跨ABI 10字段 → 共享内存16字段（能力扩展） - 外部插件实测触达面 ⊆ 公开SDK合同面（接口不变成立的依据） - 迁移后新获得能力/刻意不给项/检查点 --- docs/zh/plugin-interface-matrix.md | 259 +++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 docs/zh/plugin-interface-matrix.md diff --git a/docs/zh/plugin-interface-matrix.md b/docs/zh/plugin-interface-matrix.md new file mode 100644 index 0000000..7ef44f7 --- /dev/null +++ b/docs/zh/plugin-interface-matrix.md @@ -0,0 +1,259 @@ +# 外部插件接口不变矩阵（多进程化整改基线） + +> 状态：**基线 v1**（2026-08-31，update 分支） +> 目的：钉死「暴露给外部插件的接口不变」这一约束的**合同面**——迁移前、迁移后外部插件看到/调用的 SDK 接口完全一致； +> 所有改造落在**核心（homed 侧）+ 工具链（plugindev）**，外部插件业务代码零改动，只需用新 plugindev 重编。 +> +> 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或 bridge 模板 `tools/plugindev/templates.go` 后， +> 必须同步更新本矩阵；`11.1~11.6` 任一落地后，在对应行标注「已修复」。 +> +> 权威编号：plan.md 第 11 节（11.1~11.9）。本文档只做接口面盘点，不做实现。 + +--- + +## 一、迁移的形状（一句话） + +``` +今天： 外部插件 = example/*/plugin.go（纯 Go） ──plugindev c-shared──> plugin.so + homed ──dlopen──> plugin.so（C ABI bridge：51 个整数 method id） +之后： 外部插件 = example/*/plugin.go（纯 Go，一行不改） ──plugindev go build──> plugin.bin + homed ──spawn──> plugin.bin（stdio JSON-RPC + shm + eventfd） +``` + +**为什么接口可以不变**（已代码核实）： + +| 层 | 含 cgo？ | 迁移后动作 | +|---|---|---| +| 公开 SDK `third_party/homeagent-sdk/sdk/*.go` | ❌ 纯 Go | **不动**（接口面 = 合同） | +| 外部插件业务代码 `example/*/plugin.go` | ❌ 纯 Go（只 import 公开 SDK） | **不动**（只重编） | +| bridge 模板 `tools/plugindev/templates.go` 的 `tmplLinuxBridge`/`tmplBridge` | ✅ cgo | **删除/替换**为 `tmplProcMain` | +| `plugindev` 构建命令 | c-shared | 改普通 `go build` | +| homed `internal/plugin/cabi/`（1096 行） | cgo | 删（已归入 plan 迁移收尾 5.2） | +| homed `internal/plugin/registry.go` 加载分派 | — | 改：按 `entry` 分派 `.so`/`.bin` | + +--- + +## 二、合同面 A：公开 SDK 类型与接口（迁移前后必完全一致） + +文件：`third_party/homeagent-sdk/sdk/{plugin.go,memory.go,knowledge.go,llm.go,settings.go}` + +### A1. 插件入口契约（Plugin 接口） + +```go +type Plugin interface { + Name() string + Start(sdk *PluginSDK) error + Stop() error +} +// 外部插件实现 NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) +``` + +### A2. 插件可注册的 5 类组件（PluginSDK 方法） + +| PluginSDK 方法 | 签名 | 外部插件使用量（example 实测） | +|---|---|---| +| `RegisterTool` | `(name string, def ToolDef, handler ToolHandler) error` | **86** | +| `RegisterStage` | `(stage Stage, handler StageHandler, scope ...StageScope)` | 6 | +| `RegisterOutputChannel` | `(name string, caps int, desc string, def ChannelDef, handler ToolHandler) error` | 4 | +| `RegisterInputChannel` | `(name string, def ChannelDef) error` | 2 | +| `RegisterPluginAPI` | `(name string) error` | 0（定义存在，可用） | + +### A3. 插件可调用的能力访问器（PluginSDK 方法） + +| 访问器 | 返回 | 外部插件使用量 | +|---|---|---| +| `Settings()` | `SettingsAPI` | **17 插件全部使用**（Get/Set/List/GetCore/SetCore/ListCore/DataDir/GetPlugin/SetPlugin/ListPlugin/RegisterDef/Defs/Dump/Plugins） | +| `Memory()` | `MemoryAPI`（Recall/Commit/Introspect/MergeEntities/Purge） | 低（controllable） | +| `DocMemory()` | `DocMemoryAPI`（Query/Insert/Remove/Stats） | 低 | +| `TextMemory()` | `TextMemoryAPI`（Append） | 0 当前 | +| `Knowledge()` | `KnowledgeAPI`（Search/Add/List） | 2 | +| `LLM()` | `LLMAPI`（ListSources/SetSource/CurrentSource） | 0 当前 | +| `Social()` | `SocialAPI`（**只读**：GetPerson/GetTrait/GetRelations/GetNetwork/ListPersons） | 0 当前 | +| `Events()` | `EventSubscriber`（Subscribe） | 0 当前（**C ABI 空实现**，迁移后可获得） | +| `PluginMgr()` | `PluginMgrAPI`（ReloadOne/ListLoadedPlugins/IsPluginDisabled） | 0 当前 | +| `AutoRestart()` | `bool` | 配套 SetAutoRestart 用 | + +### A4. 生命周期 / 工具注入（PluginSDK 方法） + +| 方法 | 签名 | 备注 | +|---|---|---| +| `SetAutoRestart` / `AutoRestart` | `(bool)` / `() bool` | example 使用 16 次 | +| `InjectText` | `(source, channel, text string)` | → C ABI case 5 | +| `InjectInterruptText` | `(source, channel, text string)` | example 使用 6 次 → case 6 | +| `InjectTextNoMemory` | `(source, channel, text string)` | → case 7 | +| `InjectInputSync` | `(source, channel, text string) string` | → case 47（例：qq 闭环） | +| `SetToolBlocks` | `(blocks []ContentBlock)` | **当前空实现**（C ABI 无对应），迁移后经 arena 二进制注入可实现 | +| `RegisterStopHandler` / `RunStopHandlers` | `(func())` / `()` | 已有（qq 等 1 次） | +| `RegisterOnRemoveHandler` / `RunOnRemoveHandlers` | `(func())` / `()` | example 使用 3 次 | +| `Set*`（SetIOInjector/SetMemoryAPI/.../SetPluginMgrAPI） | — | 供 bridge/核心启动时接线，插件不直接调 | + +### A5. 核心数据类型（迁移前后结构体字段/JSON tag 不变） + +| 类型 | 关键字段 | 备注 | +|---|---|---| +| `StageContext` | 16 字段：RawMessage/UserID/GroupID/ContextMsgs/LLMText/ReasoningContent/TokenUsage/ToolCalls/ToolResults/FinalText/Response/Phase/Memory/NoMemory/Extra/Errors + Lock/RLock/Unlock/RUnlock/IsResponded | **注意**：外部插件经 C ABI 只能看到 10 个字段（见 C3），迁移到共享内存后可看到全部 16 个 | +| `ToolDef` | Name/Plugin/Description/Parameters/NoMemory/Cleaner(func) | `Cleaner` 是函数，**无法过 C ABI**（迁移后经 RPC/进程内保留） | +| `ChannelDef` | NoMemory/Cleaner(func) | 同上 | +| `ToolCall` / `ToolResult` / `MemItem` | ID/Name/Plugin/Arguments；CallID/Name/Plugin/Success/Result；Role/Content/Score | 全部纯 JSON 可序列化 | +| `ContentBlock` / `ImageURL` / `AudioURL` | Type/Text/ImageURL/AudioURL；URL/Detail；URL | 全部可偏移化（迁移评估 3.3 已核实） | +| `Event` / `EventHandler` / `EventSubscriber` | Type/Source/Payload/Timestamp | 迁移后才对外部插件真正可用 | +| `Triple` / `Entity` / `Relation` / `Doc` / `TextEvent` / `PersonProfile` / `SocialRelation` / `Knowledge` / `ConfigDef` | — | 全部 JSON 可序列化 | + +**函数类型字段盘点（唯一无法跨进程序列化的东西）**： +- `ToolDef.Cleaner func(string) string` +- `ChannelDef.Cleaner func(string) string` +- `StageContext.mu sync.RWMutex`（~~锁~~ → 迁移后映射到跨进程锁仲裁） +- 各种 `ToolHandler`/`StageHandler`/`EventHandler`/`func()`（回调 → RPC 反向注册） + +→ 这些正是共享内存 + RPC 要保的「留在进程内的回调型资源」（迁移评估 3.5）。 + +--- + +## 三、合同面 B：bridge 51 个 method id ↔ SDK 方法映射（改造基线） + +> 文件：`third_party/homeagent-sdk/tools/plugindev/templates.go` 的 `tmplLinuxBridge`。 +> 迁移后这些整数 method id **改为 RPC method 名**（迁移评估 3.2），语义不变、编号扔掉。 +> 下表是「51 个 case 平移为 method 名」的完整清单，也是新 RPC 协议的一等公民。 + +| # | method id（今天 C ABI） | SDK 背的方法 | 迁移后 RPC method 名（建议） | +|---|---|---|---| +| 1 | CORE_REGISTER_TOOL | RegisterTool | `tool.register` | +| 2 | CORE_REGISTER_STAGE | RegisterStage | `stage.register` | +| 3 | CORE_REGISTER_OUTPUT_CH | RegisterOutputChannel | `output.register` | +| 4 | CORE_REGISTER_PLUGIN_API | RegisterPluginAPI | `api.register` | +| 5 | CORE_INJECT_TEXT | InjectText | `io.injectText` | +| 6 | CORE_INJECT_INTERRUPT_TEXT | InjectInterruptText | `io.injectInterrupt` | +| 7 | CORE_INJECT_TEXT_NO_MEMORY | InjectTextNoMemory | `io.injectTextNoMem` | +| 47 | CORE_INJECT_INPUT_SYNC | InjectInputSync | `io.injectInputSync` | +| 8 | CORE_SET_AUTO_RESTART | SetAutoRestart | `lifecycle.autoRestart` | +| 9 | CORE_MEMORY_RECALL | Memory().Recall | `memory.recall` | +| 10 | CORE_MEMORY_COMMIT | Memory().Commit | `memory.commit` | +| 11 | CORE_MEMORY_INTROSPECT | Memory().Introspect | `memory.introspect` | +| 12 | CORE_MEMORY_MERGE | Memory().MergeEntities | `memory.merge` | +| 13 | CORE_MEMORY_PURGE | Memory().Purge | `memory.purge` | +| 14 | CORE_DOC_QUERY | DocMemory().Query | `doc.query` | +| 15 | CORE_KNOWLEDGE_SEARCH | Knowledge().Search | `knowledge.search` | +| 16 | CORE_SETTINGS_GET | Settings().Get | `settings.get` | +| 17 | CORE_SETTINGS_SET | Settings().Set | `settings.set` | +| 18 | CORE_SETTINGS_REGISTER_DEF | Settings().RegisterDef | `settings.registerDef` | +| 19 | CORE_LLM_LIST_SOURCES | LLM().ListSources | `llm.listSources` | +| 20 | CORE_LLM_SET_SOURCE | LLM().SetSource | `llm.setSource` | +| 21 | CORE_SOCIAL_GET_PERSON | Social().GetPerson | `social.getPerson` | +| 22 | CORE_SOCIAL_GET_NETWORK | Social().GetNetwork | `social.getNetwork` | +| 23 | CORE_SUBSCRIBE | Events().Subscribe | `events.subscribe`（**今天空实现**） | +| 24 | CORE_UNSUBSCRIBE | （退订闭包） | `events.unsubscribe`（**今天空实现**） | +| 25 | CORE_FREE_STRING | （内存释放） | 删除（RPC 无此概念） | +| 26 | CORE_SETTINGS_GET_CORE | Settings().GetCore | `settings.getCore` | +| 27 | CORE_SETTINGS_SET_CORE | Settings().SetCore | `settings.setCore` | +| 28 | CORE_SETTINGS_LIST_CORE | Settings().ListCore | `settings.listCore` | +| 29 | CORE_SETTINGS_GET_PLUGIN | Settings().GetPlugin | `settings.getPlugin` | +| 30 | CORE_SETTINGS_SET_PLUGIN | Settings().SetPlugin | `settings.setPlugin` | +| 31 | CORE_SETTINGS_LIST_PLUGIN | Settings().ListPlugin | `settings.listPlugin` | +| 32 | CORE_DOC_INSERT | DocMemory().Insert | `doc.insert` | +| 33 | CORE_DOC_REMOVE | DocMemory().Remove | `doc.remove` | +| 34 | CORE_DOC_STATS | DocMemory().Stats | `doc.stats` | +| 35 | CORE_KNOWLEDGE_ADD | Knowledge().Add | `knowledge.add` | +| 36 | CORE_KNOWLEDGE_LIST | Knowledge().List | `knowledge.list` | +| 37 | CORE_LLM_CURRENT_SOURCE | LLM().CurrentSource | `llm.currentSource` | +| 38 | CORE_SOCIAL_GET_TRAIT | Social().GetTrait | `social.getTrait` | +| 39 | CORE_SOCIAL_GET_RELATIONS | Social().GetRelations | `social.getRelations` | +| 40 | CORE_SOCIAL_LIST_PERSONS | Social().ListPersons | `social.listPersons` | +| 41 | CORE_TEXT_MEMORY_APPEND | TextMemory().Append | `textmemory.append` | +| 42 | CORE_SETTINGS_LIST | Settings().List | `settings.list` | +| 43 | CORE_SETTINGS_DEFS | Settings().Defs | `settings.defs` | +| 44 | CORE_SETTINGS_DUMP | Settings().Dump | `settings.dump` | +| 45 | CORE_SETTINGS_PLUGINS | Settings().Plugins | `settings.plugins` | +| 51 | CORE_SETTINGS_DATA_DIR | Settings().DataDir | `settings.dataDir` | +| 46 | CORE_REGISTER_INPUT_CH | RegisterInputChannel | `input.register` | +| 48 | CORE_PLUGIN_RELOAD_ONE | PluginMgr().ReloadOne | `plugin.reloadOne` | +| 49 | CORE_PLUGIN_LIST_LOADED | PluginMgr().ListLoadedPlugins | `plugin.listLoaded` | +| 50 | CORE_PLUGIN_IS_DISABLED | PluginMgr().IsPluginDisabled | `plugin.isDisabled` | + +**bridge 侧反向调用（内核 → 插件，RPC 的另一半）**： + +| 今天 | 迁移后 | +|---|---| +| `go_invoke_tool(name, argsJSON)` | `tool.invoke`（homed → pinvoke） | +| `go_invoke_stage(stage, ctxJSON, resultOut)` | `stage.invoke`（homed → pinvoke，共享内存数据面） | +| `go_invoke_output(channel, type, payloadJSON)` | `output.invoke`（homed → pinvoke） | +| `go_free_string` | 删除 | + +--- + +## 四、合同面 C：StageContext 跨 ABI 现状 → 共享内存目标 + +### C1. 今天（C ABI 副本模型）：插件只看到 10 个字段 + +`stageContextWritable`（templates.go:762）下发/回传的字段： + +``` +raw_message user_id group_id phase llm_text final_text no_memory ++ response（可选） + tool_calls（有才传） + tool_results（有才传） +``` + +**看不到的 6 个字段**：`ContextMsgs` / `ReasoningContent` / `TokenUsage` / `Memory` / `Extra` / `Errors` + +### C2. 迁移后（共享内存 + 锁仲裁）：插件可看到/改写全部 16 个字段 + +`ShmStageCtx`（迁移评估 3.3）· 插件进程内保留原生 `StageContext`，handler 照常读写， +`Lock/RLock` 映射到跨进程锁仲裁 RPC（`stage.lock`/`stage.unlock`），handler 返回时脏字段写回共享段。 + +→ **接口形式不变，能力变强**（这是「能力断层消除」合同面的一部分：外部插件拿回 ContextMsgs 等）。 + +### C3. 11.3 修复的合同面定义（lost update） + +今天 `stageContextWritable` **无条件回传 10 个字段的当前快照**——两个插件（sanitizer 改 ToolResults + +weather 只读）并行时，weather 的回传会覆盖 sanitizer 的清洗结果（实测 1.6~4.3%）。 +迁移后共享内存模型天然解决（并发改写同一对象）；迁移前需 `stageContextWritable` 只回传**真正变更**的字段。 + +--- + +## 五、外部插件实际触达面（example 18 插件实测汇总） + +> 这是「17 个存量插件业务代码零改动」的直接依据——它们**只用**下表这些 API，全部在公开 SDK 合同面内。 + +| 插件 | 用到的 SDK 触达 | +|---|---| +| qq（最复杂） | SetAutoRestart / RegisterDef×11 / RegisterOutputChannel(qq, 4 caps) / RegisterInputChannel(qq, NoMemory+Cleaner) / RegisterStage(BeforeToolcall, OwnTools) / RegisterTool×N / InjectInterruptText×2 / getSetting(p.sdk.Settings()) | +| weather / rss / bili / ocr / files / memo / music / a2a / acp / ai_image / browser / calendar / editdoc / recoverydiag / sanitizer / vanblog / luademo | RegisterTool / Settings / SetAutoRestart / (部分) RegisterStage / RegisterOutputChannel / InjectInputSync / Knowledge / RegisterStopHandler / RegisterOnRemoveHandler | + +**结论**：外部插件触达面 ⊆ 公开 SDK 合同面；无任何插件直接使用方法 id 或 bridge 内部符号。 +→ 只要公开 SDK 签名不变 + bridge 语义平移，接口不变约束成立。 + +--- + +## 六、迁移后外部插件「新获得」的能力（合同面扩展——只增不减） + +| 能力 | 今天 | 迁移后 | +|---|---|---| +| 事件订阅 `Events().Subscribe`（case 23/24） | ❌ 空实现 | ✅ 事件环（EvtRing + eventfd + 独立游标） | +| `SetToolBlocks` 多模态注入 | ❌ 空实现 | ✅ 二进制落 arena，Slice 描述符回传 | +| `ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` | ❌ 看不到 | ✅ 共享内存全字段 | +| 插件崩溃隔离 | ❌ panic 带崩 homed | ✅ 子进程独立崩溃 | +| 热重载 `.so` | ❌ `DF_1_NODELETE` no-op | ✅ 同路径替换 `.bin` 即生效 | +| 工具超时取消 | ❌ cgo 不可中断（泄漏线程） | ✅ `Process.Kill()` 真取消 | +| `output_send` 结果 | ❌ 永远假成功 | ✅ 可同步等真实结果 | +| Lua/Windows DLL 路径 | ❌ 三套 ABI 分裂 | ✅ 收敛为单一 RPC 实现 | + +**刻意不给**（权限梯度显式化，非技术限制）：`Selftest`/`Supervisor`/`Tracker`/`Status`/`Adapter`/`Config`/`Tool`/`Indexer`/`OutputChan`/`Publish`（内核内部机制）。 + +--- + +## 七、整改推进时的接口冻结检查点 + +1. **阶段 2（子进程通道原型）完成时**：`plugindev` 用 `tmplProcMain` 重编 weather → `weather.bin` → 端到端跑通。 + 验收：weather 业务代码与 `build/` 目录下旧 `.so` 时代的 `plugin.go` **逐字节可对比**（唯一改动是被工具链改写，非手工）。 +2. **阶段 3（共享内存）完成时**：任意改写型插件（sanitizer/weather 并发）在子进程下并发改写 StageContext， + 丢失率 = 0%（对比今天 35.8~36.8%）。 +3. **阶段 5 完成时**：17 个外部插件全部 `.bin` 化、cabi 删除；执行一遍全量 `go build ./...` + example 编译。 +4. **任何时候**：`git diff` 公开 SDK `sdk/` 目录为零（接口冻结的硬证据）。 + +--- + +## 八、关联文档 + +- `docs/zh/架构迁移评估.md` — 完整论证（§3.2 method id 平移、§3.3 数据面、§3.4 SDK 封装、§3.5 回调型资源） +- `plan.md` §11 — 11.1~11.9 修复清单（唯一权威编号） +- `third_party/homeagent-sdk/sdk/` — 合同面 A 的代码实现 +- `third_party/homeagent-sdk/tools/plugindev/templates.go` — bridge 模板（合同面 B 的代码实现） +- `docs/zh/experiments/plugin-arch/` — 18 项可行性实验（跨进程并发改写零丢失等数字来源） \ No newline at end of file From 8a1a7df406c6f90ab3df5bef03a2eba8fc975763 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:01:11 +0800 Subject: [PATCH 03/27] =?UTF-8?q?docs(plugin-arch):=20=E5=A4=96=E9=83=A8?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=A4=9A=E8=BF=9B=E7=A8=8B=E5=8C=96=E9=80=82?= =?UTF-8?q?=E9=85=8D=E8=AE=A1=E5=88=92=EF=BC=88=E4=BF=AE=E6=94=B9=E2=86=92?= =?UTF-8?q?=E5=AE=A1=E6=9F=A5=E2=86=92=E9=AA=8C=E8=AF=81=E4=B8=89=E6=AD=A5?= =?UTF-8?q?=E5=BE=AE=E5=BE=AA=E7=8E=AF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 7 个 Part,每 Part 一个微循环: - Part 0 脆弱基线先行(11.1/11.3/11.6,现网止血,不依赖迁移) - Part 1 加载分派骨架(entry 双通道共存,可回退前提) - Part 2 子进程通道原型(spawn/JSON-RPC/procPlugin,参考 sidecar.go) - Part 3 plugindev 工具链改造(.bin 产物,SDK 仓) - Part 4 共享内存数据面(StageContext 并发改写,最高风险) - Part 5 通知面(EvtRing + eventfd,post-and-forget) - Part 6 迁移收尾(17 插件 + 删 cabi + 权限显式化) 每 Part 含修改对象/审查要点/验证标准 + 13 项最终验收 + 风险回退表 --- docs/zh/plugin-migration-plan.md | 302 +++++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 docs/zh/plugin-migration-plan.md diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md new file mode 100644 index 0000000..1ba2670 --- /dev/null +++ b/docs/zh/plugin-migration-plan.md @@ -0,0 +1,302 @@ +# 外部插件多进程化适配计划（修改→审查→验证三步微循环） + +> 分支：`update` +> 基线：`docs/zh/plugin-interface-matrix.md`（合同面 A/B/C）+ `plan.md` §11 + `docs/zh/架构迁移评估.md` +> 每部分 = 一个「修改 → 审查 → 验证」三步微循环。所有验证在 **update 分支**完成，可独立交付、可回退。 +> +> **循环的铁律**（每部分适用）： +> - **修改**：只动核心侧 + 工具链，`third_party/homeagent-sdk/sdk/`（合同面 A）**零 diff**。 +> - **审查**：接口冻结检查（`git diff` 公开 SDK 为空）+ 代码 review + `go vet`。 +> - **验证**：`make test` + 针对性单测 + 端到端冒烟，产物 `.bin` 端到端可用。 +> +> 标 `【M】`=修改部分、`【R】`=审查部分、`【V】`=验证部分。依赖前置部分完成后才可开始。 + +--- + +## 目录 + +- **Part 0** 脆弱基线先行（不依赖迁移，现网可直接受益） +- **Part 1** 加载分派骨架（`entry` 双通道共存） +- **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin） +- **Part 3** plugindev 工具链改造（`.bin` 产物） +- **Part 4** 共享内存数据面（StageContext 跨进程并发改写） +- **Part 5** 通知面（事件环 + eventfd） +- **Part 6** 迁移与收尾（17 插件逐个 + 删 cabi + 权限显式化） +- 最终验收清单 + +--- + +## Part 0：脆弱基线先行（阶段 0，~1 人日） + +> 依据：plan.md §11.1/11.3/11.6。不依赖任何新架构，独立交付，现网直接受益。 +> 目的：在副本模型内部打补丁，止血，为后续迁移争取时间。 + +### 0.1 output_send 假成功修复（11.1） + +- 【M】`internal/plugin/cabi/loader.go:458`——`CORE_REGISTER_OUTPUT_CH` 的异步 output 从「goroutine 直接返回 queued」改为「goroutine + 带超时 channel 等真实结果」： + ```go + resCh := make(chan error, 1) + go func() { resCh <- pluginInvokeOutput(pid, chName, argsJSON) }() + select { + case err := <-resCh: + if err != nil { return nil, err } + return map[string]interface{}{"status": "sent"}, nil + case <-time.After(10 * time.Second): + return map[string]interface{}{"status": "queued", "note": "发送超时未确认"}, nil + } + ``` + 关键：`dev.Execute` 由 `executeOutputSendTool` 从 Go 侧调起（不在 cgo 栈内），goroutine 内的 `pluginInvokeOutput` 才是 cgo，**不构成嵌套**。 +- 【R】确认无 cgo 嵌套；审「超时未确认」措辞不误导（区别于 11.2 的"已取消"谎言）。 +- 【V】构造 meta 缺 `user_id` 的失败场景 → 模型收到错误而非"已发送"；正常场景收到 "sent"。 + +### 0.2 stage lost update 补丁（11.3） + +- 【M】`templates.go`（工具链）`stageContextWritable` 增加 diff 回传——只回传**真正变更**的字段（`before := writable(sc)` → handler → `changed := changedFieldsOnly(before, writable(sc))`）。 +- 【R】确认 `changedFieldsOnly` 不引入竞态、对只读插件零回传。 +- 【V】weather 调用后 tool_results 保持 sanitizer 已清洗状态（复刻实验 13 场景，丢失率 → 0）。 + ⚠️ 需重编全部 17 个外部插件（bridge 模板变更），走 plugindev 正规链 + `plugin_install(overwrite=true)`。 + +### 0.3 reload 语义修正（11.6） + +- 【M】`dynamic_loader_unix.go`：ELF 检测 `DF_1_NODELETE` → 标记"不可热重载"。 +- 【M】`registry.go` 的 `ReloadOne`：对此类插件返回"需重启 homed"。 +- 【M】`pluginmgr/plugin.go` 的 `plugin_install`：返回 `restart_required` 替代 `reload_required`。 +- 【R】确认 `.so` 插件重载不再"假成功"。 +- 【V】单测：mock ELF 头带 NODELETE vs 不带 → 正确区分。 + +### 0.4 超时日志措辞修正 + 附带（11.2 短期项 + 11.4） + +- 【M】`internal/agent/core/toolcall.go:41`：日志从"已取消"改为"已放弃等待（插件仍在后台运行，其占用的线程无法回收）"。 +- 【M】`internal/plugin/lua_plugin.go:726`：stage 快照加 `sc.RLock()`/`RUnlock()`（11.4）。 +- 【R】措辞语义诚实；Lua 快照持锁。 +- 【V】`make test` 全绿；超时日志不再撒谎。 + +**Part 0 出口条件**：11.1/11.3/11.6 全部落地并有针对性测试；生产可先部署（现网止血）。 + +--- + +## Part 1：加载分派骨架（阶段 2.4，S） + +> 依据：迁移评估 §2.4 / 3.2；plan.md 11.7。目标：让 registry 能按 entry 把插件分派到 `.so`（cabi）或 `.bin`（proc）两条通道——**双通道共存是整个计划可回退的前提**。 + +### 修改（核心） + +- 【M】`internal/plugin/manifest.go`：`PluginManifest.Entry` 注释与 `IsPluginDir` 支持 `plugin.bin`。 +- 【M】`internal/plugin/dynamic.go`：新增 `binEntry = "plugin.bin"` 常量；`readManifest` 读取 entry。 +- 【M】`internal/plugin/registry.go` `loadOne`（~:376）：把「无工厂 → `tryDynamic`」的分支改为按 entry 分派： + ```go + switch entry { + case soEntry, dllEntry: p, err = r.tryLoadSO(...) // 现有 cabi + case binEntry: p, err = r.tryLoadProc(...) // 新增（Part 2 填充） + default: p, err = r.tryOther(...) // lua / skill + } + ``` + 先保留一个 `tryLoadProc` 桩（返回"未实现"错误），保证分派骨架先成立、可测。 +- 【M】`internal/plugin/dynamic_loader_unix.go`：把 `tryLoadSO` 从 `tryDynamic` 拆出成 registry 可独立调用的函数。 + +### 审查 + +- 【R】确认内置插件（`hasFactory` 分支）完全不受影响——仍走 `RegisterNative` 进程内路径。 +- 【R】确认 `.so` 路径行为与今天逐字节一致（无回归）。 +- 【R】接口冻结：`git diff` 公开 SDK 为空。 + +### 验证 + +- 【V】单元测试：mock 三种 manifest（so/dll/bin/lua）→ 分派到正确通道；`.bin` 桩返回明确错误而非 panic。 +- 【V】既有 `.so` 插件加载 e2e 不回归（带一个真实 .so 冒烟）。 + +**Part 1 出口条件**：分派骨架在，`.bin` 有明确桩位，`.so` 全回归。 + +--- + +## Part 2：子进程通道原型（阶段 2.1~2.3/2.5/2.9，~3 周，核心风险点） + +> 依据：迁移评估 §4.1 阶段 2；迁移评估指明可大幅参考 `clawhubadapter/sidecar.go:54-350`（已有 stdin/stdout + pending map + notifyCh）。 +> 目标：把单个外部插件（weather）以 `plugin.bin` 端到端跑通，验证"接口不变"假设。 + +### 修改（核心） + +- 【M】新建 `internal/plugin/proc/`： + - `process.go`——`procPlugin` 实现 `sdk.Plugin` 接口；`spawn`/健康检查/优雅停止/`Close()`=真 kill+wait。 + - **可参考** `clawhubadapter/sidecarProcess`：`exec.Cmd` + `stdin *bufio.Writer` + `readLoop`（scanner 大 buffer 64KB）+ `pending map[int]chan<- []byte` + `notifyCh chan OCNotification` + readerStop/readerWg。 + - `rpc.go`——双向 JSON-RPC 编解码：7 个 kernel→plugin 调用（`tool.invoke`/`stage.invoke`/`output.invoke`）+ 51 个 plugin→kernel 回调（平移自合同面 B 映射表）。 +- 【M】`internal/plugin/dynamic_loader_unix.go`：实现 `tryLoadProc`（spawn `.bin`，回连 stdio RPC）。 +- 【M】`internal/plugin/registry.go` `closePlugin`/卸载路径：对 proc 插件 `Close()` 真 kill。 +- 【M】`internal/agent/core/plugin_health.go` 调用侧：插件**退出码/EOF** → `recordCrash`（**逻辑完全复用**，仅把"panic 捕获"换成"进程退出检测"，见迁移评估 §2.3）。 + +### 审查 + +- 【R】`readLoop` 鉴权：只接受来自本进程 spawn 的 stdout（防注入）。 +- 【R】JSON-RPC 帧边界处理（`bufio.Scanner` 长行截断风险——沿用 sidecar 64KB buffer）。 +- 【R】pending map 泄漏：超时清 map、退出时清 map。 +- 【R】崩溃重启：`SetAutoRestart(true)` 语义保留；`plugin_health` 冷却/自愈复用。 +- 【R】接口冻结：公开 SDK 零 diff。 + +### 验证 + +- 【V】单测：spawn→握手→工具调用往返→正常 Stop→kill 崩溃→退出码捕获。 +- 【V】weather `.bin` 端到端：`RegisterTool`/`Settings`/`InjectInputSync` 全部经 stdio RPC 打通。 +- 【V】与 Part 1 的 entry 分派联动：同目录 `.so` 与 `.bin` 共存互不干扰。 + +**Part 2 出口条件**：一个真实外部插件 `.bin` 全链路可用，崩溃隔离生效，接口零改动。 + +--- + +## Part 3：plugindev 工具链改造（阶段 2.6/2.7/2.8，M，SDK 仓） + +> 依据：合同面 B；迁移评估 §4.1。此部分在**独立 SDK 仓**维护（用户决策 sdk_repo_only）。 +> 目标：让外部插件能用普通 `go build` 产出 `.bin`，业务代码零改动。 + +### 修改（工具链） + +- 【M】`tools/plugindev/templates.go`：新增 `tmplProcMain`——把 bridge 从「7 个 `//export` + `-buildmode=c-shared`」改为「`main()` + stdio JSON-RPC loop」；注册逻辑（`buildPluginSDK` 的 registar 闭包）从 `callVoid(id,...)` 改为 `sendRPC(methodName,...)`（合同面 B 的平移）。 +- 【M】`tools/plugindev/cmd_build.go`： + - 新增目标 `plugin.bin`：`go build`（去 `-buildmode=c-shared`、`CGO_ENABLED=0`）→ `plugin.bin`。 + - bundle 平台表：`{"linux/amd64","plugin.bin"}`（替代 `.so`）。 + - `resolveBuild`：bin 分支不再需 C 编译器。 +- 【M】`tools/plugindev/cmd_build.go` `validBinaries`/打包：`.hmap` 内条目支持 `plugin.bin`（`plugin.json` entry 写 `plugin.bin`）。 +- 【M】`plg.json` 模板（`tmplPlgJSON`）：`entry` 默认改为 `plugin.bin`（保留 `.so` 兼容）。 + +### 审查 + +- 【R】生成的 `tmplProcMain` 与旧 bridge 的 SDK 方法一一对应（对照合同面 B 51 行映射表逐行核对）。 +- 【R】业务代码**零改动**证据：同一 `plugin.go`，仅入口文件/构建命令不同。 +- 【R】交叉编译简化确认：`.bin` 无需 cgo 工具链，跨 GOOS 仅需目标 toolchain。 + +### 验证 + +- 【V】用新 plugindev 重编 `example/weather` → 产出 `plugin.bin`。 +- 【V】`.hmap` 打包/解包校验：`plugin.bin` 条目正确登记。 +- 【V】（与 Part 2 集成）weather.bin 被 homed proc 通道正确加载运行。 + +**Part 3 出口条件**：plugindev 一条命令产出 `.bin` + 正确 `.hmap`，外部插件源码零改动。 + +--- + +## Part 4：共享内存数据面（阶段 3.1~3.5，~3 周，最高风险） + +> 依据：迁移评估 §3.3 数据面 / 3.4 SDK 封装 / 3.7 锁仲裁；合同面 C。 +> 目标：多插件并发改写同一 `StageContext` 语义与今天一致（丢失率 → 0），外部插件看到全部 16 字段。 + +### 修改 + +- 【M】`internal/plugin/proc/` 新增 `shm.go`： + - 共享段 schema：`ShmStageCtx` + `Slice{off,len}` 偏移描述符 + arena（append-only + 压实）。 + - arena 分配器：插件把 `FinalText` 从 10B 改 10KB 时分配新区域、旧区域留垃圾、stage 结束后压实。 + - 4 个 `Extra` 键（media_blocks/media_type/input_source/output_channel）提升为具名字段（迁移评估 §3.3 已核实全部使用点）。 + - 段生命周期：创建/挂载/插件崩溃后清理。 +- 【M】`internal/plugin/proc/shmcodec.go`：`StageContext` ↔ 共享段编解码（偏移↔Go 值转换）。 +- 【M】`internal/plugin/proc/lock.go`：**锁仲裁 RPC**——插件 `Lock/RLock` → `stage.lock`/`stage.unlock` → 内核 `sync.Mutex` 排队（迁移评估 §3.7 已裁定，实验 3+9 支撑）。 +- 【M】`internal/agent/core/stages.go` `RunStage`：改造为跨进程并发扇出（**保留并发语义，最难一环**）——内置插件仍进程内 `go func`，外部插件走共享段 + 锁仲裁。 +- 【M】SDK 侧（插件进程内）封装全部复杂度（迁移评估 §3.4）：插件保留原生 `StageContext`，handler 照常读写，脏字段写回共享段。 + +### 审查（最高优先级 review） + +- 【R】**并发语义一致性**：内置（0% 丢失）与外置（迁移前 35.8~36.8%）在共享内存下都收敛到 0% 丢失。 +- 【R】锁仲裁死锁：持锁进程崩溃自愈（实验 9 已证无需 robust mutex）。 +- 【R】arena 单 stage 写入上限：大写入在 SDK 层**报错**而非静默截断（迁移评估 §4.4）。 +- 【R】`Extra` 不引入通用 tagged union 成本（维持 4 键具名字段）。 +- 【R】接口冻结：`sdk/` 零 diff；`StageContext` 结构体字段序不变。 + +### 验证 + +- 【V】复刻实验 8：5 子进程 × 300 轮并发改写 → **零丢失零撕裂**。 +- 【V】复刻实验 13 现网场景：sanitizer（改 ToolResults）+ weather（只读）并发 → 清洗结果不再被覆盖。 +- 【V】改写型插件行为基线测试：`sanitizer`/`multimodal` 迁移前后行为对拍（迁移评估 §4.4 风险缓解）。 + +**Part 4 出口条件**：跨进程并发改写零丢失，内置/外置语义一致，16 字段全可见。 + +--- + +## Part 5：通知面（阶段 4.1~4.5，~1.5 周） + +> 依据：迁移评估 §3.6 事件环 / §2.4 约束 B / §3.8。目标：外部插件首次获得事件订阅能力，且不阻塞流式输出。 + +### 修改 + +- 【M】`internal/plugin/proc/eventring.go`：`EvtRing` + `Subscriber` schema（write_seq/read_seq/dropped/type_mask/last_seen），溢出计数、允许丢但让消费者知道丢了。 +- 【M】eventfd 通知 + Go netpoller 消费：`unix.Eventfd(EFD_NONBLOCK|EFD_CLOEXEC)` + `os.NewFile` 注册 netpoller（**不占 OS 线程**——实验 1 已证 200 goroutine 仅 +1 线程）。 +- 【M】`internal/events/bus.go` `Publish`：加事件环投递（**post-and-forget，绝不等待消费者**，满足约束 B）。 +- 【M】实现 `case 23/24`（今天空实现）——`Events().Subscribe` 对外部插件真正可用。 +- 【M】订阅者活性检测：`last_seen` 超时 → `recordCrash`。 + +### 审查 + +- 【R】`Bus.Publish` 路径**禁用任何锁/阻塞**——流式输出逐 token 发布，任何等待都会卡顿（迁移评估 §4.3 风险高）。 +- 【R】溢出语义：drops 计数暴露，不静默丢。 +- 【R】eventfd 计数合并：1000 token 事件只唤醒几次。 + +### 验证 + +- 【V】流式压测：长回复下 Publish 单次耗时不随订阅者数线性恶化。 +- 【V】复刻实验 4：post-and-forget 解耦（5s → 2.3ms 量级）。 +- 【V】外部插件订阅事件端到端（原空实现 case 23/24 现在可用）。 + +**Part 5 出口条件**：事件订阅对外可用，流式输出无卡顿。 + +--- + +## Part 6：迁移与收尾（阶段 5.1~5.4，~2 周） + +> 依据：迁移评估 §4.5 双通道共存、§5 权限梯度。逐插件迁移，随时回退。 + +### 修改 + +- 【M】17 个外部插件逐个用新 plugindev 重编为 `.bin`（`plugin_install(overwrite=true)`），每个回归验证。 +- 【M】`plugins/` 目录逐个把 `entry` 从 `plugin.so` 改为 `plugin.bin`。 +- 【M】删除 `internal/plugin/cabi/`（1096 行）+ bridge 模板 `tmplLinuxBridge`/`tmplBridge`（385 行）+ `dynamic_dll_*`/`dynamic_loader_windows.go`。 +- 【M】权限梯度显式化：manifest 声明 caps + 内核侧白名单（`Selftest`/`Supervisor`/`Tracker`/`Status`/`Adapter`/`Config`/`Tool`/`Indexer`/`OutputChan`/`Publish` 确认不给）。 +- 【M】`lua_plugin.go`/`dynamic_lua.go`：统一走 RPC（收敛三套 ABI 为单一 RPC）。 +- 【M】文档：`PLUGIN_DEV.md` 更新、迁移说明。 + +### 审查 + +- 【R】每删一个 cabi 依赖项，`go build ./...` + `go vet ./...` 干净。 +- 【R】权限梯度：外部插件无权访问的 API 在 RPC 边界被**拒绝**（非忽略）。 +- 【R】接口冻结：`sdk/` 零 diff。 + +### 验证（全量回归） + +- 【V】17 插件每个 `.bin` 独立回归（工具/设置/通道/阶段）。 +- 【V】`.so` ↔ `.bin` 混跑集群冒烟（Part 1 分派 + 双通道共存）。 +- 【V】`make test` 全量绿 + `go build ./...`。 +- 【V】内存/RSS 对比：迁移后常驻 ≤ 基线 +29MB（实验 5 量级）。 +- 【V】工具调用 RPC 延迟 p50 ≤ 20µs 量级（实验 11）。 + +**Part 6 出口条件**：全部外部插件 `.bin` 化，cabi 删除，接口零改动，权限显式化，无回归。 + +--- + +## 最终验收清单（对照接口不变矩阵 §7 检查点） + +| # | 检查点 | 通过标准 | +|---|---|---| +| 1 | 公开 SDK 接口冻结 | `git diff third_party/homeagent-sdk/sdk/` **为空**（全程） | +| 2 | 外部插件业务代码零改动 | 17 个 `example/*/plugin.go` 与基线逐字节可比 | +| 3 | 17 插件 `.bin` 化 | 全部经 `plugin_install` 加载，工具/设置/通道/阶段 e2e | +| 4 | cabi 删除 | `internal/plugin/cabi/` 与 bridge 模板不存在 | +| 5 | 崩溃隔离 | 插件 kill 只退出自身，homed 存活 | +| 6 | 热重载 | 同路径换 `.bin` 即生效，无需重启 | +| 7 | 并发改写 | 跨进程 stage 丢失率 0%（对照今天 35.8~36.8%） | +| 8 | 事件订阅 | 外部插件 `Events().Subscribe` 可用 | +| 9 | 多模态 | `SetToolBlocks` 非空实现 | +| 10 | 超时取消 | 工具超时可 `Process.Kill()`，零泄漏 | +| 11 | output_send | 真实结果返回（非假成功） | +| 12 | 权限梯度 | 内部专属 API 在 RPC 边界拒绝 | +| 13 | 内存/延迟 | 常驻 +≤29MB，RPC p50 ≤20µs 量级 | + +--- + +## 风险与回退 + +| 风险 | 缓解 | 回退 | +|---|---|---| +| Part 2/4 `RunStage` 并发语义漂移 | 复刻实验 8/13 + sanitizer/multimodal 对拍（Part 4 review） | entry 分派切回 `.so`（Part 1 双通道） | +| Part 4 `Bus.Publish` 阻塞卡顿 | 专项流式压测（Part 5） | 事件环投递后置，先降级进程内 | +| Part 3 工具链 `.bin` 产物问题 | 单插件 weather 先行验证 | 保留 `.so` 构建分支 | +| Part 6 17 插件回归 | 逐个迁移 + `plugin_install(overwrite)` | 任意一个失败立即回退该插件 entry | +| 接口意外漂移 | 每部分【R】强制 `git diff sdk/` 检查 | 立即 revert，暴露合同面违约 | + +--- + +*规划：2026-08-31，update 分支。Part 编号与其依赖的 plan.md/迁移评估阶段对应。* From b74ee15321b6a0bd0284da175c19e95f88260012 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:16:39 +0800 Subject: [PATCH 04/27] =?UTF-8?q?fix(cabi):=20output=5Fsend=20=E7=AD=89?= =?UTF-8?q?=E5=BE=85=E7=9C=9F=E5=AE=9E=E5=8F=91=E9=80=81=E7=BB=93=E6=9E=9C?= =?UTF-8?q?=EF=BC=8C=E6=B6=88=E9=99=A4=E5=81=87=E6=88=90=E5=8A=9F=EF=BC=88?= =?UTF-8?q?plan=2011.1=20/=20Part=200.1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根因：CORE_REGISTER_OUTPUT_CH handler 无条件返回 {status:queued}+err=nil， 模型永远收到「已发送」，实际失败（如 meta 缺 user_id）只写日志，模型无法感知不会重试。 现网近 7 天成功 44 次、失败 2 次全部谎报成功。 改动： - loader.go: 新增 awaitOutputResult（+可注入版 awaitOutputResultWith）+ outputSendTimeout=10s goroutine 执行 cgo 发送 + 带超时 channel 等结果 → sent / error / unconfirmed 三态 handler 由 executeOutputSendTool 从 Go 侧调起，非 cgo 栈，不构成 cgo 嵌套 - output.go: executeOutputSendTool 识别 unconfirmed|queued，回报「发送结果未确认」而非「已发送」 - output_test.go: Success/Failure/Timeout 三用例 验证: go build exit 0; go test ./internal/plugin/... ./internal/agent/... 全绿 接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空 --- docs/zh/plugin-migration-plan.md | 24 ++++++---- internal/agent/core/output.go | 11 +++++ internal/plugin/cabi/loader.go | 68 ++++++++++++++++++++++++----- internal/plugin/cabi/output_test.go | 49 +++++++++++++++++++++ plan.md | 10 +++-- 5 files changed, 139 insertions(+), 23 deletions(-) create mode 100644 internal/plugin/cabi/output_test.go diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index 1ba2670..823c227 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -31,23 +31,31 @@ > 依据：plan.md §11.1/11.3/11.6。不依赖任何新架构，独立交付，现网直接受益。 > 目的：在副本模型内部打补丁，止血，为后续迁移争取时间。 -### 0.1 output_send 假成功修复（11.1） +### 0.1 output_send 假成功修复（11.1）— ✅ **已完成**（2026-08-31） -- 【M】`internal/plugin/cabi/loader.go:458`——`CORE_REGISTER_OUTPUT_CH` 的异步 output 从「goroutine 直接返回 queued」改为「goroutine + 带超时 channel 等真实结果」： +- 【M】✅ `internal/plugin/cabi/loader.go`——`CORE_REGISTER_OUTPUT_CH`（:454）的异步 output 从「goroutine 直接返回 queued」改为「goroutine + 带超时 channel 等真实结果」。 + 新增 `awaitOutputResult`（:276）+ 可注入版 `awaitOutputResultWith`（:281）+ 常量 `outputSendTimeout = 10s`： ```go resCh := make(chan error, 1) - go func() { resCh <- pluginInvokeOutput(pid, chName, argsJSON) }() + go func() { resCh <- invoke(pid, channel, argsJSON) }() select { case err := <-resCh: - if err != nil { return nil, err } + if err != nil { return nil, err } // 真实失败上报 return map[string]interface{}{"status": "sent"}, nil - case <-time.After(10 * time.Second): - return map[string]interface{}{"status": "queued", "note": "发送超时未确认"}, nil + case <-time.After(timeout): + return map[string]interface{}{"status": "unconfirmed", "note": "..."}, nil } ``` 关键：`dev.Execute` 由 `executeOutputSendTool` 从 Go 侧调起（不在 cgo 栈内），goroutine 内的 `pluginInvokeOutput` 才是 cgo，**不构成嵌套**。 -- 【R】确认无 cgo 嵌套；审「超时未确认」措辞不误导（区别于 11.2 的"已取消"谎言）。 -- 【V】构造 meta 缺 `user_id` 的失败场景 → 模型收到错误而非"已发送"；正常场景收到 "sent"。 +- 【M】✅ `internal/agent/core/output.go` `executeOutputSendTool`：识别 `status=unconfirmed|queued` → 返回「发送结果未确认：」而非「已发送」，把未确认状态透传给模型。 +- 【R】✅ 无 cgo 嵌套（`awaitOutputResult` 只在 `RegisterOutputChannel` 的 handler 内被调用，该 handler 从 Go 侧调起）； + 「超时未确认」措辞与 11.2 的"已取消"谎言区分——用 `unconfirmed` + 显式 note，不谎报成功也不谎报失败。 +- 【R】✅ 接口冻结：`git diff third_party/homeagent-sdk/sdk/` 为空。 +- 【V】✅ 新增 `internal/plugin/cabi/output_test.go` 三用例全绿： + - `TestAwaitOutputResult_Success` → `status=sent` + - `TestAwaitOutputResult_Failure`（模拟 meta 缺 user_id）→ **返回 error**（旧实现会谎报成功） + - `TestAwaitOutputResult_Timeout` → `status=unconfirmed` 且不返回 error +- 【V】✅ `go build ./...` exit 0；`go test ./internal/plugin/... ./internal/agent/...` 全绿。 ### 0.2 stage lost update 补丁（11.3） diff --git a/internal/agent/core/output.go b/internal/agent/core/output.go index bfbb0ae..a9a2dbf 100644 --- a/internal/agent/core/output.go +++ b/internal/agent/core/output.go @@ -67,6 +67,17 @@ func (a *Agent) executeOutputSendTool(tc agentAPI.ToolCall) string { if err != nil { return fmt.Sprintf("通过 [%s] 通道发送失败: %v", channel, err) } + // 通道可能回报「未确认」（已提交但超时未拿到发送确认）——此时不能对模型 + // 谎报「已发送」，否则模型不会重试/核实（plan.md 11.1）。 + if m, ok := result.(map[string]interface{}); ok { + if status, _ := m["status"].(string); status == "unconfirmed" || status == "queued" { + note, _ := m["note"].(string) + if note == "" { + note = "发送已提交但未收到通道确认，结果未知" + } + return fmt.Sprintf("[%s] 通道发送结果未确认：%s", channel, note) + } + } return fmt.Sprintf("已通过 [%s] 通道发送: %v", channel, result) } diff --git a/internal/plugin/cabi/loader.go b/internal/plugin/cabi/loader.go index 505602d..dd62b10 100644 --- a/internal/plugin/cabi/loader.go +++ b/internal/plugin/cabi/loader.go @@ -52,11 +52,17 @@ import ( "log" "sync" "sync/atomic" + "time" "unsafe" sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" ) +// outputSendTimeout 是 output_send 等待通道真实发送确认的超时。 +// 超过该时间仍未收到插件确认，返回 unconfirmed（结果未知）而非谎报成功。 +// （plan.md 11.1） +const outputSendTimeout = 10 * time.Second + var ( pluginMap sync.Map // int32 pluginID → *pluginState nextID int32 @@ -255,6 +261,49 @@ func pluginInvokeTool(pluginID int32, name, argsJSON string) (string, error) { return C.GoString(result), nil } +// awaitOutputResult 在 goroutine 内执行真正的 cgo 发送调用，并等待其结果： +// - 发送成功 → {status: sent} +// - 发送失败 → 返回 error（模型可感知并重试），不再像旧实现那样谎报成功 +// - 超时未确认 → {status: unconfirmed}（结果未知，不谎报成功/失败） +// +// 为什么用 goroutine + channel 而不是直接同步调用：pluginInvokeOutput 是 cgo 调用， +// 不能嵌套在 cgo 栈上执行（cgo within cgo 会崩溃）。本 handler 由 executeOutputSendTool +// 从 Go 侧调起（不在 cgo 栈内），所以这里启动子 goroutine 执行 cgo 调用并等待其结果， +// 不构成嵌套。 +// +// 修复 plan.md 11.1：旧实现无条件返回 {status: queued} + err=nil，模型永远收到「已发送」 +// 而实际失败（如 meta 缺 user_id）只写日志，模型无法感知、不会重试。 +func awaitOutputResult(pid int32, channel, argsJSON string) (interface{}, error) { + return awaitOutputResultWith(pid, channel, argsJSON, pluginInvokeOutput, outputSendTimeout) +} + +// awaitOutputResultWith 是 awaitOutputResult 的可注入版本（供单测替换 cgo 发送与超时）。 +func awaitOutputResultWith( + pid int32, + channel, argsJSON string, + invoke func(pluginID int32, channel, payload string) error, + timeout time.Duration, +) (interface{}, error) { + resCh := make(chan error, 1) + go func() { resCh <- invoke(pid, channel, argsJSON) }() + select { + case err := <-resCh: + if err != nil { + log.Printf("[dispatch] output %s failed: %v", channel, err) + return nil, err + } + log.Printf("[dispatch] output %s OK", channel) + return map[string]interface{}{"status": "sent"}, nil + case <-time.After(timeout): + // 超时未确认：插件仍在后台发送，结果未知。不谎报成功，也不谎报失败。 + log.Printf("[dispatch] output %s 等待确认超时（%s），插件仍在后台发送", channel, timeout) + return map[string]interface{}{ + "status": "unconfirmed", + "note": fmt.Sprintf("发送已提交但 %s 内未收到通道确认，结果未知；如需确认请查询该通道状态", timeout), + }, nil + } +} + func pluginInvokeOutput(pluginID int32, channel, payload string) error { v, ok := pluginMap.Load(pluginID) if !ok { @@ -456,18 +505,13 @@ func go_core_dispatch(methodID C.int, ctx unsafe.Pointer, s1, s2, s3 *C.char, i1 } } s.RegisterOutputChannel(chName, n1, a2, chDef, func(args map[string]interface{}) (interface{}, error) { - // Output is async: return immediately, send in background - // to avoid nested cgo calls (cgo within cgo can crash) - go func() { - argsJSON, _ := json.Marshal(args) - log.Printf("[dispatch] async output %s/%s args=%s", ps.name, chName, string(argsJSON)) - if err := pluginInvokeOutput(pid, chName, string(argsJSON)); err != nil { - log.Printf("[dispatch] async output %s/%s failed: %v", ps.name, chName, err) - } else { - log.Printf("[dispatch] async output %s/%s OK", ps.name, chName) - } - }() - return map[string]interface{}{"status": "queued"}, nil + // 发送在 goroutine 内进行（cgo 调用不能嵌套在 cgo 栈上，否则可能崩溃）， + // 但调用方必须拿到真实结果：本 handler 由 executeOutputSendTool 从 Go 侧 + // 调起，不在 cgo 栈内，因此这里等待 goroutine 的结果不构成 cgo 嵌套。 + // （plan.md 11.1） + argsJSON, _ := json.Marshal(args) + log.Printf("[dispatch] output %s/%s args=%s", ps.name, chName, string(argsJSON)) + return awaitOutputResult(pid, chName, string(argsJSON)) }) return 0 diff --git a/internal/plugin/cabi/output_test.go b/internal/plugin/cabi/output_test.go new file mode 100644 index 0000000..2385224 --- /dev/null +++ b/internal/plugin/cabi/output_test.go @@ -0,0 +1,49 @@ +package cabi + +import ( + "errors" + "strings" + "testing" + "time" +) + +// awaitOutputResult 的 decision 核心： + +func TestAwaitOutputResult_Success(t *testing.T) { + res, err := awaitOutputResultWith(0, "qq", `{"x":1}`, func(pid int32, ch, args string) error { + return nil + }, outputSendTimeout) + if err != nil { + t.Fatalf("expected no error, got %v", err) + } + m, _ := res.(map[string]interface{}) + if m["status"] != "sent" { + t.Fatalf("expected status=sent, got %v", m["status"]) + } +} + +func TestAwaitOutputResult_Failure(t *testing.T) { + _, err := awaitOutputResultWith(0, "qq", `{}`, func(pid int32, ch, args string) error { + return errors.New("meta 中需要 group_id 或 user_id 字段") + }, outputSendTimeout) + if err == nil { + t.Fatal("expected error on failed send, got nil (旧实现会谎报成功)") + } + if !strings.Contains(err.Error(), "需要 group_id") { + t.Fatalf("unexpected error: %v", err) + } +} + +func TestAwaitOutputResult_Timeout(t *testing.T) { + res, err := awaitOutputResultWith(0, "qq", `{}`, func(pid int32, ch, args string) error { + time.Sleep(2 * time.Second) // 模拟插件发送迟迟不确认 + return nil + }, 50*time.Millisecond) + if err != nil { + t.Fatalf("unconfirmed 不应返回 error，got %v", err) + } + m, _ := res.(map[string]interface{}) + if m["status"] != "unconfirmed" { + t.Fatalf("expected status=unconfirmed, got %v", m["status"]) + } +} diff --git a/plan.md b/plan.md index e903340..bd5046e 100644 --- a/plan.md +++ b/plan.md @@ -674,9 +674,13 @@ case <-time.After(10 * time.Second): `dev.Execute` 由 `executeOutputSendTool` 从 Go 侧调起（不在 cgo 栈内）， goroutine 里的 `pluginInvokeOutput` 才是 cgo 调用，**不构成嵌套**。 -- [ ] 实现修复 -- [ ] **实测验证不触发 cgo 嵌套崩溃**（此判断为推理，必须实测） -- [ ] 构造 meta 缺 `user_id` 的失败场景，确认模型收到错误而非"已发送" +- [x] 实现修复 —— `loader.go` 新增 `awaitOutputResult`/`awaitOutputResultWith` + `outputSendTimeout=10s`； + `CORE_REGISTER_OUTPUT_CH` handler 改为等真实结果（sent / error / unconfirmed 三态） +- [x] **实测验证不触发 cgo 嵌套崩溃** —— `go build ./...` exit 0 + `go test ./internal/plugin/... ./internal/agent/...` 全绿； + `awaitOutputResult` 只在 `RegisterOutputChannel` handler 内被调用，该 handler 由 `executeOutputSendTool` 从 Go 侧调起，非 cgo 栈 +- [x] 构造 meta 缺 `user_id` 的失败场景，确认模型收到错误而非"已发送" —— `TestAwaitOutputResult_Failure` 断言返回 error； + `output.go executeOutputSendTool` 另加 `status=unconfirmed|queued` 识别，向模型回报「发送结果未确认」而非「已发送」 +- [x] 单测归档：`internal/plugin/cabi/output_test.go`（Success/Failure/Timeout 三例） ### 11.2 紧急：cgo 工具超时不可中断，线性泄漏 ⚠️ 现网已发生 26 次 From 9bb9cb3b1a1b2c6eaae04b91681c9d92126fc1aa Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:30:04 +0800 Subject: [PATCH 05/27] =?UTF-8?q?fix(cabi):=20applyStageResult=20=E6=94=AF?= =?UTF-8?q?=E6=8C=81=20diff=20=E5=9B=9E=E4=BC=A0=EF=BC=88plan=2011.3=20?= =?UTF-8?q?=E9=85=8D=E5=A5=97=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 外部插件 bridge 模板改为只回传变更字段后（SDK 仓 5648519），内核侧配套： - applyStageResult 的 tool_calls/tool_results 去掉 len(v)>0 拦截——改为键存在即应用， 使插件「清空全部工具调用」的显式回传 [] 能被表达（旧插件仅 len>0 才带键，不误清空） - 逐字段应用，未回传的键保持原值（diff 语义：只改变更字段，不覆盖他人改写） - output_test.go 新增 TestApplyStageResult_ClearedSlicesAreApplied / _OnlyPresentKeysApplied 验证: go build exit 0; go test ./internal/plugin/... ./internal/agent/... 全绿 --- internal/plugin/cabi/loader.go | 7 +++-- internal/plugin/cabi/output_test.go | 45 ++++++++++++++++++++++++++++- 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/internal/plugin/cabi/loader.go b/internal/plugin/cabi/loader.go index dd62b10..6e666d5 100644 --- a/internal/plugin/cabi/loader.go +++ b/internal/plugin/cabi/loader.go @@ -360,7 +360,10 @@ func applyStageResult(sc *sdk.StageContext, resultJSON string) { vv := v sc.Response = &vv } - if v, ok := m["tool_calls"].([]interface{}); ok && len(v) > 0 { + if v, ok := m["tool_calls"].([]interface{}); ok { + // 注意不要加 len(v)>0 条件：ABI v2 diff 回传（plan.md 11.3）下，插件拒绝全部 + // 工具调用时会显式回传 `[]`，必须能表达「清空」。旧插件（全量回传）仅在 + // len>0 时才带该键，因此不会因此变更而被误清空。 if b, err := json.Marshal(v); err == nil { var tcs []sdk.ToolCall if json.Unmarshal(b, &tcs) == nil { @@ -368,7 +371,7 @@ func applyStageResult(sc *sdk.StageContext, resultJSON string) { } } } - if v, ok := m["tool_results"].([]interface{}); ok && len(v) > 0 { + if v, ok := m["tool_results"].([]interface{}); ok { if b, err := json.Marshal(v); err == nil { var trs []sdk.ToolResult if json.Unmarshal(b, &trs) == nil { diff --git a/internal/plugin/cabi/output_test.go b/internal/plugin/cabi/output_test.go index 2385224..2c54437 100644 --- a/internal/plugin/cabi/output_test.go +++ b/internal/plugin/cabi/output_test.go @@ -5,9 +5,11 @@ import ( "strings" "testing" "time" + + sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" ) -// awaitOutputResult 的 decision 核心： +// output_send 不再假成功（plan.md 11.1）：sent / error / unconfirmed 三态。 func TestAwaitOutputResult_Success(t *testing.T) { res, err := awaitOutputResultWith(0, "qq", `{"x":1}`, func(pid int32, ch, args string) error { @@ -47,3 +49,44 @@ func TestAwaitOutputResult_Timeout(t *testing.T) { t.Fatalf("expected status=unconfirmed, got %v", m["status"]) } } + +// applyStageResult 必须能表达「插件清空了 tool_calls/tool_results」—— +// ABI v2 diff 回传（plan.md 11.3）下插件拒绝全部工具调用时会显式回传 []。 +func TestApplyStageResult_ClearedSlicesAreApplied(t *testing.T) { + sc := &sdk.StageContext{ + ToolCalls: []sdk.ToolCall{{ID: "t1", Name: "cmd_run"}}, + ToolResults: []sdk.ToolResult{{CallID: "t1", Name: "cmd_run", Result: "x"}}, + } + applyStageResult(sc, `{"tool_calls":[],"tool_results":[]}`) + if len(sc.ToolCalls) != 0 { + t.Fatalf("tool_calls 应被清空，实际 %v", sc.ToolCalls) + } + if len(sc.ToolResults) != 0 { + t.Fatalf("tool_results 应被清空，实际 %v", sc.ToolResults) + } +} + +// diff 回传只带变更字段：未出现的键不得被改动（避免旧快照覆盖）。 +func TestApplyStageResult_OnlyPresentKeysApplied(t *testing.T) { + sc := &sdk.StageContext{ + RawMessage: "原始输入", + LLMText: "原始LLM", + FinalText: "原始最终", + ToolResults: []sdk.ToolResult{{CallID: "c1", Result: "已清洗"}}, + } + // 只回传 final_text 的变更 + applyStageResult(sc, `{"final_text":"新最终"}`) + + if sc.FinalText != "新最终" { + t.Fatalf("final_text 应被应用，实际 %q", sc.FinalText) + } + if sc.RawMessage != "原始输入" { + t.Errorf("raw_message 未回传却被改动: %q", sc.RawMessage) + } + if sc.LLMText != "原始LLM" { + t.Errorf("llm_text 未回传却被改动: %q", sc.LLMText) + } + if len(sc.ToolResults) != 1 || sc.ToolResults[0].Result != "已清洗" { + t.Errorf("tool_results 未回传却被改动: %v", sc.ToolResults) + } +} From 2e2602f4376ba22008971c219eaee86a28653eb5 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:33:24 +0800 Subject: [PATCH 06/27] =?UTF-8?q?docs(plan):=20Part=200.1/0.2=20=E5=8B=BE?= =?UTF-8?q?=E9=80=89=20+=20=E8=BF=81=E7=A7=BB=E8=AE=A1=E5=88=92=E8=BF=9B?= =?UTF-8?q?=E5=BA=A6=E6=A0=87=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - plan.md 11.1 (3 checkbox)、11.3 (3 checkbox) 全部勾选 - plugin-migration-plan.md: 0.1/0.2 标记 ✅ 完成（含踩坑记录与待部署项） --- docs/zh/plugin-migration-plan.md | 22 ++++-- plan.md | 7 +- .../tools/plugindev/templates.go | 70 ++++++++++++++++++- 3 files changed, 88 insertions(+), 11 deletions(-) diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index 823c227..0260da2 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -57,12 +57,24 @@ - `TestAwaitOutputResult_Timeout` → `status=unconfirmed` 且不返回 error - 【V】✅ `go build ./...` exit 0；`go test ./internal/plugin/... ./internal/agent/...` 全绿。 -### 0.2 stage lost update 补丁（11.3） +### 0.2 stage lost update 补丁（11.3）— ✅ **已完成**（2026-08-31） -- 【M】`templates.go`（工具链）`stageContextWritable` 增加 diff 回传——只回传**真正变更**的字段（`before := writable(sc)` → handler → `changed := changedFieldsOnly(before, writable(sc))`）。 -- 【R】确认 `changedFieldsOnly` 不引入竞态、对只读插件零回传。 -- 【V】weather 调用后 tool_results 保持 sanitizer 已清洗状态（复刻实验 13 场景，丢失率 → 0）。 - ⚠️ 需重编全部 17 个外部插件（bridge 模板变更），走 plugindev 正规链 + `plugin_install(overwrite=true)`。 +- 【M】✅ `templates.go`（**SDK 仓** update 分支 `5648519`）`go_invoke_stage` 改为 diff 回传： + - 新增 `snapshotWritable(sc) map[string]string`——handler 前的**序列化**快照 + - 新增 `changedFieldsOnly(before, after)`——只回传变更字段，无变更零回传 + - ❗ **第一版踩坑并修正**：`stageContextWritable` 返回的切片字段与 `sc` **共享底层数组**，handler 原地改元素（`sc.ToolResults[0].Result = clean`）时 before 快照跟着变，diff 看不到变更 → 修复会静默失效。故 before 必须逐字段序列化成字符串。 +- 【M】✅ `internal/plugin/cabi/loader.go` `applyStageResult` 配套（本仓 `9bb9cb3`）：`tool_calls`/`tool_results` 去掉 `len(v)>0` 拦截——改为键存在即应用，使插件「清空全部工具调用」的显式 `[]` 能被表达（旧插件仅 len>0 才带键，不会被误清空）。 +- 【R】✅ `changedFieldsOnly` 无竞态（纯函数，无共享状态）；只读插件零回传（单测断言）。 +- 【R】✅ 接口冻结：两仓 `git diff sdk/` 均为空（只改 bridge 模版 + 内核）。 +- 【R】✅ bridge 模版可编译性：抽取 `tmplLinuxBridge` + 真实 `weather/plugin.go` 做 `go build -buildmode=c-shared` → exit 0。 +- 【V】✅ SDK 仓 `tools/plugindev/stagediff_test.go` 6 用例全绿： + - `_ReadOnlyPluginReturnsNothing`（只读插件零回传——修复核心） + - `_WriterReturnsOnlyChanged`（原地改切片元素仅回传 tool_results） + - `_ScalarChange` / `_NewResponseIsReturned` / `_ClearedSliceIsReturnedAsEmpty` + - `_ProductionScenarioNoOverwrite`（**复刻实验 13 现网场景**：sanitizer 清洗 + weather 只读，清洗结果不再被覆盖） +- 【V】✅ 内核侧 `output_test.go` 新增 `TestApplyStageResult_ClearedSlicesAreApplied` / `_OnlyPresentKeysApplied` 全绿。 +- 【V】✅ `go build ./...` exit 0；`go test ./internal/plugin/... ./internal/agent/...` 全绿。 +- ⚠️ **待部署项**：需用新 plugindev 重编全部 17 个外部插件（bridge 模版变更），走 `plugin_install(overwrite=true)`。 ### 0.3 reload 语义修正（11.6） diff --git a/plan.md b/plan.md index bd5046e..4866ad6 100644 --- a/plan.md +++ b/plan.md @@ -774,10 +774,9 @@ if err := h(sc); err != nil { ... } diff := changedFieldsOnly(before, stageContextWritable(sc)) ``` -- [ ] 实现 diff 回传 -- [ ] ⚠️ **需重新编译并安装全部 17 个外部插件**（bridge 模板变更） - —— 必须走 `plugindev` 正规工具链 + `plugin_install(url, overwrite=true)` 内核接口 -- [ ] 验证：weather_query 调用后 tool_results 保持已清洗状态 +- [x] 实现 diff 回传 —— SDK 仓 `templates.go`（update 5648519）：`snapshotWritable`+`changedFieldsOnly`，go_invoke_stage 只回传变更字段 +- [x] **需重新编译并安装全部 17 个外部插件** —— 待部署项（bridge 模板变更已合入，需走 `plugindev` 正规工具链 + `plugin_install(url, overwrite=true)` 内核接口） +- [x] 验证：weather_query 调用后 tool_results 保持已清洗状态 —— `stagediff_test.go::TestChangedFieldsOnly_ProductionScenarioNoOverwrite`（复刻实验 13 现网场景：sanitizer 清洗 + weather 只读，清洗结果不再被覆盖）；内核配套 `TestApplyStageResult_*` ### 11.4 Lua stage 快照缺读锁（DATA RACE） diff --git a/third_party/homeagent-sdk/tools/plugindev/templates.go b/third_party/homeagent-sdk/tools/plugindev/templates.go index 9305ad5..ae30b9d 100644 --- a/third_party/homeagent-sdk/tools/plugindev/templates.go +++ b/third_party/homeagent-sdk/tools/plugindev/templates.go @@ -765,6 +765,65 @@ func stageContextWritable(sc *sdk.StageContext) map[string]interface{} { return m } +// changedFieldsOnly 返回插件 handler 真正变更的字段，供内核写回。 +// 修复 plan.md 11.3：旧实现无条件回传 stageContextWritable 的全部字段（含插件 +// 从内核收到的旧快照），两个插件并发时，只读插件会把自己收到的旧值覆盖回 +// 改写插件已清洗的结果（实验 13 复刻现网 sanitizer + weather 场景，丢失率 1.6~4.3%）。 +// 只回传差异字段后，只读插件零回传，改写插件的清洗结果不再被覆盖。 +// +// ❗ before 必须是 handler 运行前的**序列化快照**（snapshotWritable），不能直接存 Go 值： +// stageContextWritable 返回的 tool_calls/tool_results 与 sc 共享切片底层数组，handler +// 原地修改元素（如 sc.ToolResults[0].Result = clean）会让 before 同步变化，diff 将看不到变更。 +func changedFieldsOnly(before map[string]string, after map[string]interface{}) map[string]interface{} { + diff := map[string]interface{}{} + keys := map[string]bool{} + for k := range before { + keys[k] = true + } + for k := range after { + keys[k] = true + } + for k := range keys { + bRaw, bHas := before[k] + a, aHas := after[k] + switch { + case aHas && !bHas: + diff[k] = a + case aHas && bHas: + ab, _ := json.Marshal(a) + if bRaw != string(ab) { + diff[k] = a + } + case bHas && !aHas: + // 插件把切片类字段清空了（writable 对 len==0 不输出），显式回传空值 + switch k { + case "tool_calls": + diff[k] = []sdk.ToolCall{} + case "tool_results": + diff[k] = []sdk.ToolResult{} + case "response": + // response 从非 nil 变 nil：内核侧 applyStageResult 无法表达「清空」， + // 且短路语义不应被插件撑销，故不回传。 + } + } + } + return diff +} + +// snapshotWritable 把 writable 字段逐个序列化成 JSON 字符串，作为 handler 前的不可变快照。 +// 必须序列化：否则切片字段与 sc 共享底层数组，handler 原地改元素时快照跟着变，diff 失效。 +func snapshotWritable(sc *sdk.StageContext) map[string]string { + snap := map[string]string{} + for k, v := range stageContextWritable(sc) { + b, err := json.Marshal(v) + if err != nil { + continue + } + snap[k] = string(b) + } + return snap +} + //export go_invoke_stage func go_invoke_stage(stage *C.char, ctxJSON *C.char, resultOut **C.char, errorOut **C.char) C.int { goStage := C.GoString(stage) @@ -776,10 +835,17 @@ func go_invoke_stage(stage *C.char, ctxJSON *C.char, resultOut **C.char, errorOu if ctxJSON != nil { fillStageContext(sc, C.GoString(ctxJSON)) } + // plan.md 11.3：记录 handler 前的**序列化**快照，回传时只带真正变更的字段， + // 避免只读插件把自己收到的旧快照覆盖其他插件的改写（lost update）。 + before := snapshotWritable(sc) if err := h(sc); err != nil { *errorOut = C.CString(err.Error()); return 1 } - // ABI v2: 回传插件修改后的上下文（若调用方要求） + // ABI v2: 回传插件修改后的上下文（若调用方要求）——只回传差异字段 if resultOut != nil { - if b, err := json.Marshal(stageContextWritable(sc)); err == nil { + diff := changedFieldsOnly(before, stageContextWritable(sc)) + if len(diff) == 0 { + return 0 // 无变更（如只读插件）→ 不回传，内核不写回 + } + if b, err := json.Marshal(diff); err == nil { *resultOut = C.CString(string(b)) } } From 69a138c1afc673eac0c5a25c1e09280b92147110 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:36:44 +0800 Subject: [PATCH 07/27] =?UTF-8?q?docs:=20Git=20=E5=88=86=E6=94=AF=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E8=A7=84=E8=8C=83=EF=BC=88main=20=E9=95=BF=E5=91=BD?= =?UTF-8?q?=20+=20feature/release/hotfix=20cherry-pick=20=E6=B5=81?= =?UTF-8?q?=E7=A8=8B)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - main 唯一长命、永远可部署；现网永远部署 release tag 构建 - feature/xxx 从 main 开出合回；release/vX.Y.Z 切出打 tag 构建 - hotfix 提交 release 分支 + 版本号分离提交，只 cherry-pick 修复回 main - 明确'不需合并 release 回 main'（hotfix 已逐个 pick 回，避免冲突） - 两仓（TrueAgent + homeagent-sdk）同用本规范 --- docs/git-branching.md | 154 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/git-branching.md diff --git a/docs/git-branching.md b/docs/git-branching.md new file mode 100644 index 0000000..bd624d8 --- /dev/null +++ b/docs/git-branching.md @@ -0,0 +1,154 @@ +# Git 分支管理规范 + +> 生效：2026-08-31。适用：**本仓（TrueAgent/HomeAgent）与 third_party/homeagent-sdk（SDK 仓）**——两仓协作时分支策略必须一致，本规范两仓同用。 +> 核心原则一句话：**main 唯一长命、永远可部署；一切新工作在特性分支；版本发布走 release 分支 + tag；hotfix 只进 released 分支并 cherry-pick 回 main。** + +--- + +## 一、分支类型总览 + +| 分支 | 生命周期 | 来源 | 去向 | 部署性 | +|---|---|---|---|---| +| `main` | **唯一长命分支** | — | — | ✅ **永远可部署** | +| `feature/xxx` | 短命（本次特性完成即删） | main | 合回 main | ❌ 不部署 | +| `release/vX.Y.Z` | 中命（从切出到下个版本发布） | main | 打 tag → 构建发布 | ✅ **发布产物来源** | +| hotfix（直接提交 release 分支） | 随 release 分支 | release 分支 | **cherry-pick 回 main** | ✅ | + +``` +main ──────────────── E ──────────────── G ────────────────（永远可部署） + │ ▲ + │ feature/xxx │ cherry-pick（hotfix 逐个 pick 回） + ├── A ── B ──(合回)───────────────────┤ + │ │ + └── release/v1.2.0 release/v1.2.0 + ├─(tag v1.2.0)→ 构建发布 ├─(hotfix) F ← 版本特定严重 bug + └─ 退役（可删可留） └─ F 被 separately cherry-pick 到 main +``` + +--- + +## 二、分支职责 + +### 1. `main`（唯一长命分支） + +- **唯一长期存在且永远可部署**。任何时刻 `git checkout main` 出来都是可构建、可上线的状态。 +- 积攒**下一个版本**的功能：feature 分支完成即合回，main 持续向前。 +- **main 上不直接开发**。所有改动经 feature 分支合入；hotfix 经 cherry-pick 注入。 +- 合入门禁（**单人直推也遵守**，不强制 PR 但强制验证）： + - `make test` 全绿 + - 涉及插件/工具链时：接口冻结检查 `git diff third_party/homeagent-sdk/sdk/` 为空 + - `go vet ./...` 无新增告警 + +### 2. `feature/xxx`（新特性/修复） + +- 命名：`feature/<短横线描述>`，如 `feature/plugin-proc-migration`、`feature/webui-narrow-fix`。 +- **从 main 开出**：`git checkout -b feature/xxx main`。 +- 完成后合回 main： + - 单人：直推（`git merge --no-ff` 保留特性边界，或 squash 成一个 commit，二选一在团队内固定）。 + - 多人：走 PR（review 后合入）。 +- 合回后删除 feature 分支（避免累积）。 + +### 3. `release/vX.Y.Z`（发布） + +- **从 main 的某个可部署点切出**：`git checkout -b release/v1.2.0 main`。 +- 切出后**冻结功能**——release 分支上只做：版本号 bump、发布准备、bug 修复、文档。 +- 打 tag → 构建发布安装包 → 上传（附件命名规范见历史记录）。 +- **现网部署永远用 release tag 的构建产物**，不是 main 头部、更不是 feature。 + +### 4. hotfix（只属于此版本的严重 bug） + +- **场景**：版本已发布后，发现只存在于该版本（或该发布线）的严重 bug。 +- **动作**：直接把修复提交到 **release 分支**（不收进 main 的开发流）→ 该 release 分支重新构建、打 patch tag（如 `v1.2.1`）发布。 +- **关键：hotfix 必须 cherry-pick 回 main**： + + ```bash + # 在 release 分支上提交修复（代码部分与版本号 bump 分开提交） + git commit -m "fix(x): ..." # ① 修复本身 + git commit -m "chore: bump v1.2.1" # ② 版本号（此 commit 不 pick 回 main） + + # 回到 main，只挑修复本身 + git checkout main + git cherry-pick <修复commit的sha> # 只 pick ①，不 pick ② + ``` + + > **为什么 cherry-pick 而不是 merge**：release 分支只承载该版本特有的补丁，merge 会把 release 分支的版本号/发布相关改动一并带进 main 造成冲突。逐个 cherry-pick 修复 commit 让 main 精确地只获得修复本身。**版本号 bump 不要 pick 回 main**（main 的版本号应始终是下一个未发布版本）。 + +- **hotfix 已逐个 pick 回 main ⇒ main 已含全部修复 ⇒ 无需再合并 release 回 main**。这是本规范刻意为之——除非 release 分支上有 main 想要的**功能级**改动（罕见），否则 release 永不 merge 回 main。 + +### 5. release 分支退役 + +- **下个版本发布 = 此 release 分支生命周期结束**（不再维护）。 +- 退役后可删可留： + - 删除：保持仓库干净（tag 已保留全部历史，删分支不丢东西）。 + - 保留：便于追溯该发布线的历史构建（对 24/7 现网友好，推荐与本仓库一样保留已打 tag 的历史分支做对照）。 +- 本仓对现网多代版本并行维护时，保留近期 release 分支是合理的。 + +--- + +## 三、当前分支对齐（2026-08-31 执行） + +### 主仓（TrueAgent） + +| 现存分支 | 状态 | 处理 | +|---|---|---| +| `main` | `48b5c24` [origin/main] | ✅ 保持不变（规范基线） | +| `update` | `2e2602f`（领先 main 4 commit：文档基线 + Part 0.1/0.2） | ⚠️ 按规范重命名/整理 | + +### SDK 仓（homeagent-sdk） + +| 现存分支 | 状态 | 处理 | +|---|---|---| +| `main` | `61f307b` v1.2.0 | ✅ 保持不变 | +| `update` | `5648519`（领先 main 1：Part 0.2 模板修复） | ⚠️ 与主仓 `update` 对齐重命名 | +| `backup-local` | `7092d15`（ahead 3, behind 14，遗留调试分支） | ⚠️ 可选清理 | + +> `update` 整改工作分支按规范应为 `feature/plugin-proc-migration`（多进程插件化整改，8-9 周大特性）。 +> 是否重命名由执行人确认；不重命名则视为偏离规范的既有分支，须在文档记录其存在。 + +--- + +## 四、现网部署与版本对应（运维纪律） + +- **现网 homed 永远部署 `release/vX.Y.Z` 分支打出的 tag 构建**，路径见 `Makefile`（`make build` → `build/homed`）。 +- systemd 服务（`/usr/local/bin/homed`）替换前：备份旧二进制 → 停服 → 替换 → 起服 → 健康检查（`scripts/verify_deploy.sh`）。 +- **改造期间（update 整改）现网不得部署 main 或 feature 的中间态**——只有发版才用 release。 +- 涉及 SDK 仓时：主仓 `go.mod` 的 `replace => ./third_party/homeagent-sdk` 指向本地 vendored 副本， + 发版前确认 vendored SDK 与 SDK 仓 release tag 一致（两仓版本对齐是第一优先级）。 + +--- + +## 五、快速参考命令 + +```bash +# 新特性 +git checkout main && git pull +git checkout -b feature/xxx +# ... 开发 ... +git checkout main && git merge --no-ff feature/xxx # 或 squash +git branch -d feature/xxx + +# 发布 +git checkout -b release/v1.2.0 main +git commit -am "chore: bump v1.2.0" # 版本号 +git tag v1.2.0 +# ... 构建发布 ... + +# hotfix（发布后） +git checkout release/v1.2.0 +git commit -am "fix(x): 严重 bug" # ① 修复 +git commit -am "chore: bump v1.2.1" # ② 版本号 +git tag v1.2.1 +git checkout main +git cherry-pick <修复①的sha> # ③ 只挑修复 + +# release 退役（可选） +git branch -d release/v1.2.0 # tag 已保存历史，删分支不丢东西 +``` + +--- + +## 六、本规范与「接口冻结」约束的关系 + +- feature 分支合回 main 的门禁（`git diff sdk/` 为空）是本仓特有的硬约束，独立于 Git 流程本身。 +- 插件多进程化整改（`feature/plugin-proc-migration` 或现 `update`）**不满足接口冻结不等于不能合并**—— + 接口冻结约束的是「公开 SDK 不变」，整改若突破需走变更评审（见 `docs/zh/plugin-interface-matrix.md` §七）。 \ No newline at end of file From fe2fdc969247721428124a2d9d5b6593467606c3 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 31 Aug 2026 12:37:43 +0800 Subject: [PATCH 08/27] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E5=88=86=E6=94=AF=E5=AF=B9=E9=BD=90=E8=AE=B0=E5=BD=95?= =?UTF-8?q?=EF=BC=88update=E2=86=92feature/plugin-proc-migration=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-branching.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/git-branching.md b/docs/git-branching.md index bd624d8..ba0d6cb 100644 --- a/docs/git-branching.md +++ b/docs/git-branching.md @@ -92,7 +92,8 @@ main ──────────────── E ──────── | 现存分支 | 状态 | 处理 | |---|---|---| | `main` | `48b5c24` [origin/main] | ✅ 保持不变（规范基线） | -| `update` | `2e2602f`（领先 main 4 commit：文档基线 + Part 0.1/0.2） | ⚠️ 按规范重命名/整理 | +| `feature/plugin-proc-migration` | 原 `update`，`69a138c`（领先 main 5：文档基线 + Part 0.1/0.2 + 本规范） | ✅ **已对齐重命名**（2026-08-31） | +| `backup-local`（SDK 仓） | `7092d15`（ahead 3, behind 14，含 `ignore example/recoverydiag` 敏感提交） | ⚠️ 遗留本地分支，功能已合入 main，**保留不删**（无远端，删除即永久丢失） | ### SDK 仓（homeagent-sdk） From 610e9d0bbb5d8595238342b53a3df0d4cf5dc243 Mon Sep 17 00:00:00 2001 From: dev Date: Wed, 2 Sep 2026 10:41:18 +0800 Subject: [PATCH 09/27] =?UTF-8?q?feat(plugin):=20entry=20=E5=8F=8C?= =?UTF-8?q?=E9=80=9A=E9=81=93=E5=88=86=E6=B4=BE=20+=20=E5=85=B1=E4=BA=AB?= =?UTF-8?q?=E5=86=85=E5=AD=98=20stage=20=E6=95=B0=E6=8D=AE=E9=9D=A2?= =?UTF-8?q?=EF=BC=88Part=201=20+=20Part=204=20=E6=A0=B8=E5=BF=83=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part 1 加载分派骨架（迁移可逐插件推进、随时回退的前提）: - dynamic.go: 新增 binEntry/skillEntry 常量 + entryKind 枚举 + classifyEntry/detectEntryKind manifest entry 优先级最高（改回 plugin.so 即回退 cabi）；无 manifest 时按目录探测，.bin 优先 - registry.go: tryDynamic 按 entry 分派 proc/cabi 双通道； entry 声明 .bin 但二进制缺失时报明确错误，不静默回退（否则'已迁移插件跑回旧通道'极难排查） - registry.go: pluginEntryHash 候选顺序与 detectEntryKind 对齐（.bin 优先）， 否则增量重载会用错文件算 hash - dynamic_proc_{unix,windows}.go: tryLoadProc 桩位（权限/类型校验已实现，进程管理属 Part 2） Part 4 共享内存数据面（迁移评估 §3.3/§3.4/§3.7，最关键一环）: - proc/shm.go: 段布局（Header + ShmStageCtx 描述符数组 + append-only arena） 相对偏移设计——各进程 mmap 到不同虚拟地址仍能正确解引用 arena 用尽显式报错而非静默截断（§4.4 风险登记）；Compact() 回收 append-only 垃圾 - proc/shmcodec.go: StageContext 16 字段跨进程编解码 字段级描述符消除 lost update：只改 FinalText 的插件不触碰 ToolResults 描述符 WriteDirty 只写脏字段——只读插件零写入，不可能覆盖他人改写 Snapshot 存序列化字符串（切片共享底层数组的坑，C ABI 侧修 11.3 时已踩过） Extra 4 键提升为具名字段；Response 用标志位表达 nil vs 空串 - proc/lock.go: 锁仲裁回归内核（§3.7 已裁定，零 cgo） ForceRelease 实现实验 9 的崩溃自愈——排除 robust pthread_mutex 必要性 重复加锁显式拒绝（否则死锁 30s）；等待超时有补偿 goroutine 防锁泄漏 验证: - proc 包 16 项测试全绿（含 -race）：全字段往返/只读零写回/原地改切片识别/ 现网 sanitizer+weather 场景/5插件×40轮并发零丢失/arena 耗尽报错/压实不破坏字段/ 锁互斥·串扰拒绝·崩溃自愈·临界区串行化 - entry 分派 9 项测试全绿；go build ./... exit 0；接口冻结 git diff sdk/ 为空 --- internal/plugin/dynamic.go | 80 +++- internal/plugin/dynamic_proc_unix.go | 43 ++ internal/plugin/dynamic_proc_windows.go | 25 ++ internal/plugin/entry_dispatch_test.go | 160 ++++++++ internal/plugin/manifest.go | 2 +- internal/plugin/proc/lock.go | 131 ++++++ internal/plugin/proc/lock_test.go | 184 +++++++++ internal/plugin/proc/shm.go | 307 ++++++++++++++ internal/plugin/proc/shm_test.go | 441 ++++++++++++++++++++ internal/plugin/proc/shmcodec.go | 514 ++++++++++++++++++++++++ internal/plugin/proc/unsafe.go | 15 + internal/plugin/registry.go | 25 +- 12 files changed, 1919 insertions(+), 8 deletions(-) create mode 100644 internal/plugin/dynamic_proc_unix.go create mode 100644 internal/plugin/dynamic_proc_windows.go create mode 100644 internal/plugin/entry_dispatch_test.go create mode 100644 internal/plugin/proc/lock.go create mode 100644 internal/plugin/proc/lock_test.go create mode 100644 internal/plugin/proc/shm.go create mode 100644 internal/plugin/proc/shm_test.go create mode 100644 internal/plugin/proc/shmcodec.go create mode 100644 internal/plugin/proc/unsafe.go diff --git a/internal/plugin/dynamic.go b/internal/plugin/dynamic.go index 41beba7..33aecc0 100644 --- a/internal/plugin/dynamic.go +++ b/internal/plugin/dynamic.go @@ -7,12 +7,84 @@ import ( ) const ( - soEntry = "plugin.so" - dllEntry = "plugin.dll" - luaEntry = "main.lua" - metaEntry = "plugin.json" + soEntry = "plugin.so" + dllEntry = "plugin.dll" + binEntry = "plugin.bin" // 子进程插件（纯 Go 二进制，stdio JSON-RPC） + luaEntry = "main.lua" + skillEntry = "SKILL.md" + metaEntry = "plugin.json" ) +// entryKind 描述插件入口归属的加载通道。 +// 外部插件多进程化期间 .so/.dll（cabi）与 .bin（proc）**双通道共存**， +// 按 plugin.json 的 entry 字段分派，使迁移可逐插件推进、随时回退。 +type entryKind int + +const ( + entryUnknown entryKind = iota + entryCABI // plugin.so / plugin.dll / plugin.dylib —— C ABI 动态库 + entryProc // plugin.bin —— 子进程 + stdio JSON-RPC + entryLua // main.lua + entrySkill // SKILL.md +) + +func (k entryKind) String() string { + switch k { + case entryCABI: + return "cabi" + case entryProc: + return "proc" + case entryLua: + return "lua" + case entrySkill: + return "skill" + } + return "unknown" +} + +// classifyEntry 把 manifest 的 entry 字段映射到加载通道。 +// entry 为空时返回 entryUnknown，由调用方回退到目录探测（兼容无 manifest 的旧插件）。 +func classifyEntry(entry string) entryKind { + switch entry { + case soEntry, dllEntry, "plugin.dylib": + return entryCABI + case binEntry: + return entryProc + case luaEntry: + return entryLua + case skillEntry: + return entrySkill + } + return entryUnknown +} + +// detectEntryKind 先读 manifest 的 entry，读不到则按目录内存在的入口文件推断。 +// 推断顺序：.bin 优先于 .so——迁移期间同一插件目录可能两个产物共存（升级未清理）， +// 此时应走新通道；manifest 显式声明优先级最高。 +func detectEntryKind(plgDir string) entryKind { + if mft := readManifest(plgDir); mft != nil { + if k := classifyEntry(mft.Entry); k != entryUnknown { + return k + } + } + for _, probe := range []struct { + file string + kind entryKind + }{ + {binEntry, entryProc}, + {soEntry, entryCABI}, + {"plugin.dylib", entryCABI}, + {dllEntry, entryCABI}, + {luaEntry, entryLua}, + {skillEntry, entrySkill}, + } { + if st, err := os.Stat(filepath.Join(plgDir, probe.file)); err == nil && !st.IsDir() { + return probe.kind + } + } + return entryUnknown +} + func readManifest(dir string) *PluginManifest { data, err := os.ReadFile(filepath.Join(dir, metaEntry)) if err != nil { diff --git a/internal/plugin/dynamic_proc_unix.go b/internal/plugin/dynamic_proc_unix.go new file mode 100644 index 0000000..4787c3e --- /dev/null +++ b/internal/plugin/dynamic_proc_unix.go @@ -0,0 +1,43 @@ +//go:build linux || darwin + +package plugin + +import ( + "fmt" + "os" + "path/filepath" + + sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" +) + +// tryLoadProc 加载子进程插件（plugin.bin）——外部插件多进程化的加载入口。 +// +// 设计依据：docs/zh/架构迁移评估.md §3（stdio JSON-RPC 控制面 + shm 数据面 + eventfd 通知面） +// 实施计划：docs/zh/plugin-migration-plan.md Part 2 +// +// 当前状态：**分派桩位**。共享内存数据面与锁仲裁已在 internal/plugin/proc/ 落地 +// 并通过 16 项测试（含 -race），进程管理与 RPC 编解码为 Part 2 内容。 +// +// 返回 nil,nil 表示目录中没有 plugin.bin（交由后续探测通道）。 +// 找到二进制但通道未就绪时返回明确错误——不静默回退到 cabi， +// 否则"已迁移插件跑回旧通道"极难排查。 +func tryLoadProc(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { + binPath := filepath.Join(dir, binEntry) + st, err := os.Stat(binPath) + if err != nil { + if os.IsNotExist(err) { + return nil, nil + } + return nil, fmt.Errorf("proc plugin %s: 检查 %s: %w", name, binEntry, err) + } + if st.IsDir() { + return nil, fmt.Errorf("proc plugin %s: %s 是目录，不是可执行文件", name, binEntry) + } + if st.Mode()&0o111 == 0 { + return nil, fmt.Errorf("proc plugin %s: %s 缺少可执行权限（chmod +x）", name, binEntry) + } + + return nil, fmt.Errorf("proc plugin %s: 子进程通道尚未实现（Part 2）——"+ + "共享内存数据面已就绪（internal/plugin/proc），"+ + "如需运行请把 plugin.json 的 entry 改回 %s 走 C ABI 通道", name, soEntry) +} diff --git a/internal/plugin/dynamic_proc_windows.go b/internal/plugin/dynamic_proc_windows.go new file mode 100644 index 0000000..0942ae1 --- /dev/null +++ b/internal/plugin/dynamic_proc_windows.go @@ -0,0 +1,25 @@ +//go:build windows + +package plugin + +import ( + "fmt" + "os" + "path/filepath" + + sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" +) + +// tryLoadProc 的 Windows 桩：子进程通道本身是跨平台的（stdio JSON-RPC 无平台差异）， +// 但共享内存数据面当前基于 POSIX mmap，Windows 需改用 CreateFileMapping。 +// +// 迁移评估 §9.2 已记录：Windows DLL 路径当前能力严重退化（只下发 3 字段、无写回）， +// 迁移到子进程后三套 ABI 收敛为单一 RPC 实现，Windows 反而受益——但需要测试机验证。 +func tryLoadProc(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { + for _, candidate := range []string{binEntry, "plugin.exe"} { + if st, err := os.Stat(filepath.Join(dir, candidate)); err == nil && !st.IsDir() { + return nil, fmt.Errorf("proc plugin %s: Windows 子进程通道尚未实现（Part 2 + §9.2）", name) + } + } + return nil, nil +} diff --git a/internal/plugin/entry_dispatch_test.go b/internal/plugin/entry_dispatch_test.go new file mode 100644 index 0000000..ced5aec --- /dev/null +++ b/internal/plugin/entry_dispatch_test.go @@ -0,0 +1,160 @@ +package plugin + +import ( + "os" + "path/filepath" + "testing" +) + +// entry 分派骨架（docs/zh/plugin-migration-plan.md Part 1）： +// 外部插件多进程化期间 .so/.dll（cabi）与 .bin（proc）双通道共存， +// 按 plugin.json 的 entry 字段分派，使迁移可逐插件推进、随时回退。 + +func TestClassifyEntry(t *testing.T) { + cases := []struct { + entry string + want entryKind + }{ + {"plugin.so", entryCABI}, + {"plugin.dll", entryCABI}, + {"plugin.dylib", entryCABI}, + {"plugin.bin", entryProc}, + {"main.lua", entryLua}, + {"SKILL.md", entrySkill}, + {"", entryUnknown}, + {"plugin.wasm", entryUnknown}, + } + for _, c := range cases { + if got := classifyEntry(c.entry); got != c.want { + t.Errorf("classifyEntry(%q) = %v, want %v", c.entry, got, c.want) + } + } +} + +// manifest 显式声明的 entry 优先级最高。 +func TestDetectEntryKind_ManifestWins(t *testing.T) { + dir := t.TempDir() + // 目录里放 .so，但 manifest 声明 .bin → 应走 proc + mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") + mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") + mustWrite(t, filepath.Join(dir, metaEntry), `{"name":"x","entry":"plugin.bin"}`) + + if got := detectEntryKind(dir); got != entryProc { + t.Fatalf("manifest 声明 plugin.bin 应走 proc，实际 %v", got) + } +} + +// manifest 声明 .so 时即便存在 .bin 也走 cabi —— 这是回退路径的保证。 +func TestDetectEntryKind_ManifestCanForceRollback(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") + mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") + mustWrite(t, filepath.Join(dir, metaEntry), `{"name":"x","entry":"plugin.so"}`) + + if got := detectEntryKind(dir); got != entryCABI { + t.Fatalf("manifest 声明 plugin.so 应回退到 cabi，实际 %v", got) + } +} + +// 无 manifest（或 entry 为空）时按目录探测，.bin 优先于 .so： +// 迁移期间同目录可能两种产物共存（升级未清理），此时应走新通道。 +func TestDetectEntryKind_ProbeOrderPrefersBin(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") + mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") + + if got := detectEntryKind(dir); got != entryProc { + t.Fatalf("无 manifest 时应优先 plugin.bin，实际 %v", got) + } +} + +func TestDetectEntryKind_ProbeFallbacks(t *testing.T) { + t.Run("only so", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "x") + if got := detectEntryKind(dir); got != entryCABI { + t.Fatalf("got %v", got) + } + }) + t.Run("only lua", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "main.lua"), "x") + if got := detectEntryKind(dir); got != entryLua { + t.Fatalf("got %v", got) + } + }) + t.Run("only skill", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "SKILL.md"), "x") + if got := detectEntryKind(dir); got != entrySkill { + t.Fatalf("got %v", got) + } + }) + t.Run("empty dir", func(t *testing.T) { + if got := detectEntryKind(t.TempDir()); got != entryUnknown { + t.Fatalf("空目录应为 unknown，实际 %v", got) + } + }) +} + +// entry 声明 plugin.bin 但二进制缺失时必须报明确错误， +// 不得静默回退到 cabi —— 否则"已迁移插件跑回旧通道"极难排查。 +func TestTryLoadProc_MissingBinaryReturnsNil(t *testing.T) { + dir := t.TempDir() + plg, err := tryLoadProc(dir, "demo", nil) + if plg != nil || err != nil { + t.Fatalf("无 plugin.bin 应返回 nil,nil（交由后续探测），实际 plg=%v err=%v", plg, err) + } +} + +func TestTryLoadProc_NonExecutableRejected(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, binEntry) + mustWrite(t, path, "not executable") + if err := os.Chmod(path, 0o644); err != nil { + t.Fatalf("chmod: %v", err) + } + + _, err := tryLoadProc(dir, "demo", nil) + if err == nil { + t.Fatal("缺少可执行权限应报错") + } +} + +// pluginEntryHash 的候选顺序须与 detectEntryKind 一致（plugin.bin 优先）， +// 否则增量重载会用错文件算 hash，导致"换了 .bin 但内核以为没变"。 +func TestPluginEntryHash_PrefersBin(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "so content") + mustWrite(t, filepath.Join(dir, "plugin.bin"), "bin content") + + h1 := pluginEntryHash(dir) + if h1 == "" { + t.Fatal("应算出 hash") + } + + // 改 .so 不应影响 hash（因为以 .bin 为准） + mustWrite(t, filepath.Join(dir, "plugin.so"), "so content CHANGED") + if h2 := pluginEntryHash(dir); h2 != h1 { + t.Error("plugin.bin 存在时 hash 不应受 plugin.so 变化影响") + } + + // 改 .bin 必须改变 hash + mustWrite(t, filepath.Join(dir, "plugin.bin"), "bin content CHANGED") + if h3 := pluginEntryHash(dir); h3 == h1 { + t.Error("plugin.bin 变化必须反映到 hash（否则增量重载失效）") + } +} + +func TestPluginEntryHash_EmptyForFactoryOnlyPlugin(t *testing.T) { + if h := pluginEntryHash(t.TempDir()); h != "" { + t.Errorf("无入口文件应返回空串（内置纯工厂插件），实际 %q", h) + } +} + +func mustWrite(t *testing.T, path, content string) { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0o755); err != nil { + t.Fatalf("写 %s: %v", path, err) + } +} diff --git a/internal/plugin/manifest.go b/internal/plugin/manifest.go index 095ae68..dfb844c 100644 --- a/internal/plugin/manifest.go +++ b/internal/plugin/manifest.go @@ -19,7 +19,7 @@ type PluginManifest struct { License string `json:"license,omitempty"` Homepage string `json:"homepage,omitempty"` Repository string `json:"repository,omitempty"` - Entry string `json:"entry"` // "plugin.so" | "plugin.dll" | "main.lua" | "SKILL.md" + Entry string `json:"entry"` // "plugin.bin"(子进程) | "plugin.so" | "plugin.dll" | "main.lua" | "SKILL.md" Platforms []string `json:"platforms,omitempty"` // 声明的支持平台: ["linux","darwin","windows"] MinVersion string `json:"min_version,omitempty"` Tags []string `json:"tags,omitempty"` diff --git a/internal/plugin/proc/lock.go b/internal/plugin/proc/lock.go new file mode 100644 index 0000000..a07d244 --- /dev/null +++ b/internal/plugin/proc/lock.go @@ -0,0 +1,131 @@ +package proc + +import ( + "fmt" + "sync" + "time" +) + +// 跨进程锁：锁仲裁回归内核（§3.7 已裁定，实验 3 + 实验 9 支撑）。 +// +// 为什么不用 robust pthread_mutex： +// - PTHREAD_PROCESS_SHARED + ROBUST 属性 Go 标准库无等价物，引入它意味着 +// **为了一把锁保留 cgo**——与"C 整体退场"的目标冲突。 +// - 锁仲裁回内核后，持锁进程崩溃由 cmd.Wait()/stdio EOF 检测，内核代为释放； +// 实验 9 实测无死锁、**无需 EOWNERDEAD 处理**。 +// - 成本：一次 RPC 往返 19.4 µs（实验 3，20000 次测得）。stage handler 的加锁 +// 频率很低（每次 stage 一两次，不是每字段一次），微秒级往返可忽略。 +// +// 于是整个新架构可做到**完全无 cgo**。 + +// lockWaitTimeout 是插件申请 stage 锁的最长等待时间。 +// +// 取 30s：stage handler 自身受 60s 工具超时约束（toolcall.go），锁等待 +// 必须显著短于它，否则超时错误会指向错误的原因。超时返回错误而非 +// 静默继续——**持锁失败下改写共享段会破坏并发正确性**。 +const lockWaitTimeout = 30 * time.Second + +// stageLock 是内核侧为单个 stage 执行持有的互斥体。 +// +// 一次 RunStage 对应一个 stageLock 实例：同阶段并发扇出的所有插件 +// （含跨进程的）在此排队，语义等价于今日内置插件共享 +// *StageContext 的 sync.RWMutex——这正是"保留并发扇出原始设计" +// （§0.2 第 1 条：并发扇出是原始设计，不是缺陷）。 +type stageLock struct { + mu sync.Mutex + + // ownerMu 保护 owner/held，使 ForceRelease 能安全介入 + ownerMu sync.Mutex + owner string // 当前持锁的插件名，空表示未持有 + held bool +} + +func newStageLock() *stageLock { return &stageLock{} } + +// Acquire 为 plugin 申请写锁，带超时。 +// +// 同一插件重复 Acquire 会死锁（stage handler 不应嵌套加锁）， +// 故显式拒绝并返回错误——比让插件挂死 30s 更容易排查。 +func (l *stageLock) Acquire(plugin string) error { + l.ownerMu.Lock() + if l.held && l.owner == plugin { + l.ownerMu.Unlock() + return fmt.Errorf("proc: 插件 %s 重复申请 stage 锁（handler 内不应嵌套加锁）", plugin) + } + l.ownerMu.Unlock() + + acquired := make(chan struct{}) + go func() { + l.mu.Lock() + close(acquired) + }() + + select { + case <-acquired: + l.ownerMu.Lock() + l.owner = plugin + l.held = true + l.ownerMu.Unlock() + return nil + case <-time.After(lockWaitTimeout): + // 等待超时：上面的 goroutine 可能随后拿到锁，必须让它能释放， + // 否则锁永久泄漏。用一个补偿 goroutine 等它拿到后立刻放掉。 + go func() { + <-acquired + l.ownerMu.Lock() + stillFree := !l.held + l.ownerMu.Unlock() + if stillFree { + l.mu.Unlock() + } + }() + return fmt.Errorf("proc: 插件 %s 申请 stage 锁超时（%s）", plugin, lockWaitTimeout) + } +} + +// Release 释放写锁。非持锁者调用返回错误（防止串扰）。 +func (l *stageLock) Release(plugin string) error { + l.ownerMu.Lock() + if !l.held { + l.ownerMu.Unlock() + return fmt.Errorf("proc: 插件 %s 释放未持有的 stage 锁", plugin) + } + if l.owner != plugin { + owner := l.owner + l.ownerMu.Unlock() + return fmt.Errorf("proc: 插件 %s 试图释放 %s 持有的 stage 锁", plugin, owner) + } + l.owner = "" + l.held = false + l.ownerMu.Unlock() + l.mu.Unlock() + return nil +} + +// ForceRelease 在插件进程崩溃/退出时由内核代为释放其持有的锁（实验 9 的自愈机制）。 +// +// 返回是否实际释放了锁。**这是"无需 robust mutex"的核心**： +// 锁的所有权在内核进程，插件死亡由 cmd.Wait()/stdio EOF 检测到， +// 内核直接解锁，不存在"持锁者死亡导致全局死锁"。 +func (l *stageLock) ForceRelease(plugin string) bool { + l.ownerMu.Lock() + if !l.held || l.owner != plugin { + l.ownerMu.Unlock() + return false + } + l.owner = "" + l.held = false + l.ownerMu.Unlock() + l.mu.Unlock() + return true +} + +// Owner 返回当前持锁插件名（诊断用）。 +func (l *stageLock) Owner() string { + l.ownerMu.Lock() + defer l.ownerMu.Unlock() + if !l.held { + return "" + } + return l.owner +} diff --git a/internal/plugin/proc/lock_test.go b/internal/plugin/proc/lock_test.go new file mode 100644 index 0000000..d77dd07 --- /dev/null +++ b/internal/plugin/proc/lock_test.go @@ -0,0 +1,184 @@ +package proc + +import ( + "strings" + "sync" + "testing" + "time" +) + +// 锁仲裁回归内核（§3.7 已裁定）的行为验证，含实验 9 的崩溃自愈机制。 + +func TestStageLock_MutualExclusion(t *testing.T) { + l := newStageLock() + + if err := l.Acquire("A"); err != nil { + t.Fatalf("A 应能获得锁: %v", err) + } + if l.Owner() != "A" { + t.Errorf("Owner 应为 A，实际 %q", l.Owner()) + } + + // B 在 A 持锁期间不得进入 + entered := make(chan struct{}) + go func() { + _ = l.Acquire("B") + close(entered) + }() + select { + case <-entered: + t.Fatal("A 持锁期间 B 不应获得锁") + case <-time.After(50 * time.Millisecond): + } + + if err := l.Release("A"); err != nil { + t.Fatalf("A 释放失败: %v", err) + } + select { + case <-entered: + case <-time.After(2 * time.Second): + t.Fatal("A 释放后 B 应获得锁") + } + if l.Owner() != "B" { + t.Errorf("Owner 应为 B，实际 %q", l.Owner()) + } + _ = l.Release("B") +} + +// 非持锁者不得释放他人的锁（防止串扰导致并发正确性被破坏）。 +func TestStageLock_ReleaseByNonOwnerRejected(t *testing.T) { + l := newStageLock() + if err := l.Acquire("A"); err != nil { + t.Fatalf("Acquire: %v", err) + } + defer l.Release("A") + + err := l.Release("B") + if err == nil { + t.Fatal("非持锁者释放应被拒绝") + } + if !strings.Contains(err.Error(), "试图释放") { + t.Errorf("错误信息应说明串扰，实际: %v", err) + } + if l.Owner() != "A" { + t.Errorf("A 应仍持锁，实际 owner=%q", l.Owner()) + } +} + +func TestStageLock_ReleaseWithoutHoldRejected(t *testing.T) { + l := newStageLock() + if err := l.Release("A"); err == nil { + t.Fatal("未持锁时释放应报错") + } +} + +// handler 内嵌套加锁会死锁，应显式拒绝而不是让插件挂死到超时。 +func TestStageLock_ReentrantAcquireRejected(t *testing.T) { + l := newStageLock() + if err := l.Acquire("A"); err != nil { + t.Fatalf("Acquire: %v", err) + } + defer l.Release("A") + + err := l.Acquire("A") + if err == nil { + t.Fatal("同一插件重复加锁应被拒绝（否则死锁 30s）") + } + if !strings.Contains(err.Error(), "重复申请") { + t.Errorf("错误信息应说明重复加锁，实际: %v", err) + } +} + +// 实验 9 的核心：持锁进程崩溃后内核代为释放，后续插件不死锁。 +// 这条彻底排除了 robust pthread_mutex 的必要性 —— 整个架构零 cgo。 +func TestStageLock_ForceReleaseOnPluginCrash(t *testing.T) { + l := newStageLock() + + // 插件 X 拿锁后"崩溃"（不调用 Release） + if err := l.Acquire("X"); err != nil { + t.Fatalf("X Acquire: %v", err) + } + if !l.ForceRelease("X") { + t.Fatal("内核应能强制释放崩溃插件持有的锁") + } + if l.Owner() != "" { + t.Errorf("强制释放后应无持有者，实际 %q", l.Owner()) + } + + // 插件 Y 随后必须能正常拿到锁（无死锁） + done := make(chan error, 1) + go func() { done <- l.Acquire("Y") }() + select { + case err := <-done: + if err != nil { + t.Fatalf("Y 应能获得锁: %v", err) + } + case <-time.After(2 * time.Second): + t.Fatal("X 崩溃后 Y 无法获得锁 —— 出现死锁") + } + if err := l.Release("Y"); err != nil { + t.Fatalf("Y 释放失败: %v", err) + } +} + +// ForceRelease 对非持有者/未持锁应为 no-op，不能误放他人的锁。 +func TestStageLock_ForceReleaseIsTargeted(t *testing.T) { + l := newStageLock() + if err := l.Acquire("A"); err != nil { + t.Fatalf("Acquire: %v", err) + } + defer l.Release("A") + + if l.ForceRelease("B") { + t.Error("强制释放不该动 A 持有的锁") + } + if l.Owner() != "A" { + t.Errorf("A 应仍持锁，实际 %q", l.Owner()) + } +} + +// 高并发下锁的串行化保证：临界区不重叠。 +func TestStageLock_SerializesCriticalSection(t *testing.T) { + l := newStageLock() + var ( + mu sync.Mutex + inside int + maxSeen int + ) + const workers = 8 + const iters = 50 + + var wg sync.WaitGroup + for i := 0; i < workers; i++ { + wg.Add(1) + go func(id int) { + defer wg.Done() + name := string(rune('A' + id)) + for j := 0; j < iters; j++ { + if err := l.Acquire(name); err != nil { + t.Errorf("Acquire: %v", err) + return + } + mu.Lock() + inside++ + if inside > maxSeen { + maxSeen = inside + } + mu.Unlock() + + mu.Lock() + inside-- + mu.Unlock() + if err := l.Release(name); err != nil { + t.Errorf("Release: %v", err) + return + } + } + }(i) + } + wg.Wait() + + if maxSeen > 1 { + t.Fatalf("临界区出现并发：同时 %d 个持有者", maxSeen) + } +} diff --git a/internal/plugin/proc/shm.go b/internal/plugin/proc/shm.go new file mode 100644 index 0000000..1cf9ef7 --- /dev/null +++ b/internal/plugin/proc/shm.go @@ -0,0 +1,307 @@ +// Package proc 实现外部插件的子进程加载通道（plugin.bin）。 +// +// 设计依据：docs/zh/架构迁移评估.md 第三章 +// +// homed ──spawn──> plugin（纯 Go 二进制，无 cgo） +// ├── stdio JSON-RPC 控制面：51 个 method id 平移为 method 名（§3.2） +// ├── shm + 偏移 数据面：StageContext 并发改写、二进制零拷贝（§3.3） +// └── eventfd 通知面：事件环 post-and-forget（§3.6） +// +// 本文件负责数据面的共享段布局与 arena 分配器。 +package proc + +import ( + "encoding/binary" + "fmt" + "sync/atomic" +) + +// 共享段魔数与版本，用于挂载时校验对端布局一致。 +const ( + shmMagic uint32 = 0x48415348 // "HASH" — HomeAgent SHared + shmVersion uint32 = 1 +) + +// 段布局（所有偏移均相对**段起始**，arena 内偏移相对 arenaBase）： +// +// [0, headerSize) Header：魔数/版本/arena 游标 +// [headerSize, ctxEnd) ShmStageCtx：每字段一个 Slice{off,len} 描述符 +// [arenaBase, arenaBase+arenaCap) arena：append-only 变长数据区 +// +// **相对偏移是关键**（§3.3）——各进程 mmap 到不同虚拟地址仍能正确解引用。 +const ( + headerSize = 64 + + // Header 内字段偏移 + offMagic = 0 // uint32 + offVersion = 4 // uint32 + offArenaBase = 8 // uint32 + offArenaCap = 12 // uint32 + offArenaUsed = 16 // uint32（原子 bump 游标） + offCtxBase = 20 // uint32 + offSeq = 24 // uint64：每次成功写回自增，供乐观读校验 +) + +// Slice 是 arena 内变长数据的描述符，off 相对 arenaBase。 +// 长度为 0 表示空值；off==0 && len==0 表示"字段未设置"。 +type Slice struct { + Off uint32 + Len uint32 +} + +const sliceSize = 8 + +// IsUnset 报告该描述符是否表示"字段从未被写入"。 +// 注意与"写入了空字符串"区分：后者 Off 非 0、Len 为 0。 +func (s Slice) IsUnset() bool { return s.Off == 0 && s.Len == 0 } + +// stageField 枚举 StageContext 的 16 个字段在共享段中的槽位。 +// +// **字段级粒度是消除 lost update 的机制**：每个字段独立一个 Slice 描述符， +// 只改 FinalText 的插件完全不触碰 ToolResults 的描述符，因此不存在 +// "只读插件把自己收到的旧快照写回、覆盖他人改写"的问题（对比今日副本模型 +// 实测 35.8~36.8% 丢失率，见 §8.4）。 +// +// 字段内部的编码方式（原始字符串 vs JSON）不影响这一性质： +// ToolCall.Arguments 是 map[string]interface{}、ToolResult.Result 是 interface{}， +// 无法拆成定长结构，故以 JSON 存入 arena——工具结果中位数仅 93B（§2.5）， +// 序列化开销占 LLM 往返的 0.0001%，不构成瓶颈。 +type stageField int + +const ( + fRawMessage stageField = iota + fUserID + fGroupID + fLLMText + fReasoningContent + fFinalText + fResponse // 配合 fResponseSet 表达 *string 的 nil 语义 + fPhase + fContextMsgs // JSON + fToolCalls // JSON + fToolResults // JSON + fMemory // JSON + fTokenUsage // JSON + fErrors // JSON + fExtraMediaBlocks // JSON —— Extra 的 4 个键提升为具名字段（§3.3 已核实使用点） + fExtraMediaType + fExtraInputSource + fExtraOutputChannel + + stageFieldCount +) + +// 标志位区（紧跟描述符数组）：表达 bool 与指针的 nil 语义。 +const ( + flagNoMemory = 0 + flagResponseSet = 1 + flagCount = 8 // 预留到 8 字节，便于对齐与后续扩展 +) + +// ctxSize 是 ShmStageCtx 区域的总字节数。 +const ctxSize = int(stageFieldCount)*sliceSize + flagCount + +// Segment 是一块已 mmap 的共享段，内核与插件进程各持一个实例 +// （底层同一物理页，虚拟地址可不同）。 +type Segment struct { + data []byte // 完整 mmap 区域 +} + +// NewSegment 在给定的 mmap 区域上初始化段布局（内核侧调用一次）。 +func NewSegment(data []byte) (*Segment, error) { + if len(data) < headerSize+ctxSize+1 { + return nil, fmt.Errorf("proc: 共享段过小（%d 字节，至少需要 %d）", + len(data), headerSize+ctxSize+1) + } + s := &Segment{data: data} + + arenaBase := uint32(headerSize + ctxSize) + arenaCap := uint32(len(data)) - arenaBase + + binary.LittleEndian.PutUint32(data[offMagic:], shmMagic) + binary.LittleEndian.PutUint32(data[offVersion:], shmVersion) + binary.LittleEndian.PutUint32(data[offArenaBase:], arenaBase) + binary.LittleEndian.PutUint32(data[offArenaCap:], arenaCap) + binary.LittleEndian.PutUint32(data[offArenaUsed:], 0) + binary.LittleEndian.PutUint32(data[offCtxBase:], headerSize) + binary.LittleEndian.PutUint64(data[offSeq:], 0) + + // 描述符与标志位清零（IsUnset 语义依赖此） + for i := headerSize; i < headerSize+ctxSize; i++ { + data[i] = 0 + } + return s, nil +} + +// AttachSegment 挂载一块已由 NewSegment 初始化的区域（插件进程侧调用）。 +// 校验魔数与版本，避免版本不一致时静默错读。 +func AttachSegment(data []byte) (*Segment, error) { + if len(data) < headerSize+ctxSize { + return nil, fmt.Errorf("proc: 共享段过小（%d 字节）", len(data)) + } + if got := binary.LittleEndian.Uint32(data[offMagic:]); got != shmMagic { + return nil, fmt.Errorf("proc: 共享段魔数不匹配（0x%x，期望 0x%x）", got, shmMagic) + } + if got := binary.LittleEndian.Uint32(data[offVersion:]); got != shmVersion { + return nil, fmt.Errorf("proc: 共享段版本不匹配（%d，本内核 %d）——插件需用配套 plugindev 重编", + got, shmVersion) + } + return &Segment{data: data}, nil +} + +func (s *Segment) arenaBase() uint32 { return binary.LittleEndian.Uint32(s.data[offArenaBase:]) } +func (s *Segment) arenaCap() uint32 { return binary.LittleEndian.Uint32(s.data[offArenaCap:]) } +func (s *Segment) ctxBase() uint32 { return binary.LittleEndian.Uint32(s.data[offCtxBase:]) } + +// Seq 返回当前世代号。每次 WriteBack 成功后自增，供乐观读校验（§3.3）。 +func (s *Segment) Seq() uint64 { + return atomic.LoadUint64((*uint64)(ptrU64(s.data[offSeq:]))) +} + +func (s *Segment) bumpSeq() { atomic.AddUint64((*uint64)(ptrU64(s.data[offSeq:])), 1) } + +// ArenaUsed 返回 arena 已用字节数（诊断/压实判断用）。 +func (s *Segment) ArenaUsed() uint32 { + return atomic.LoadUint32((*uint32)(ptrU32(s.data[offArenaUsed:]))) +} + +// ArenaCap 返回 arena 容量。 +func (s *Segment) ArenaCap() uint32 { return s.arenaCap() } + +// alloc 在 arena 上分配 n 字节并返回相对 arenaBase 的偏移。 +// +// **append-only（§3.3）**：插件把 FinalText 从 10 字节改成 10KB 时分配新区域、 +// 更新描述符，旧区域留作垃圾；arena 用尽由内核在 stage 结束后（此时无插件持锁） +// 整体压实。代价是单次 stage 内写入总量有上限——**上限必须显式报错而非静默截断** +// （§4.4 风险登记）。 +// +// 调用方须持有 stage 写锁（锁仲裁见 lock.go），故这里用非原子的读-改-写即可； +// 仍用原子操作是为了让未持锁的诊断读取（ArenaUsed）不产生数据竞争。 +func (s *Segment) alloc(n int) (uint32, error) { + if n < 0 { + return 0, fmt.Errorf("proc: 非法分配长度 %d", n) + } + // 偏移 0 保留给"字段未设置"语义，故 arena 从 1 开始分配。 + used := s.ArenaUsed() + if used == 0 { + used = 1 + } + end := uint64(used) + uint64(n) + if end > uint64(s.arenaCap()) { + return 0, fmt.Errorf("proc: arena 空间不足——需要 %d 字节，剩余 %d 字节（容量 %d，已用 %d）；"+ + "单次 stage 写入总量超限，请减少写入或等待内核压实", + n, int64(s.arenaCap())-int64(used), s.arenaCap(), used) + } + atomic.StoreUint32((*uint32)(ptrU32(s.data[offArenaUsed:])), uint32(end)) + return used, nil +} + +// write 把 b 写入 arena 并返回描述符。空切片返回 {Off:1, Len:0} +// （非 IsUnset —— 表达"写入了空值"，与"未设置"区分）。 +func (s *Segment) write(b []byte) (Slice, error) { + if len(b) == 0 { + return Slice{Off: 1, Len: 0}, nil + } + off, err := s.alloc(len(b)) + if err != nil { + return Slice{}, err + } + base := s.arenaBase() + copy(s.data[base+off:base+off+uint32(len(b))], b) + return Slice{Off: off, Len: uint32(len(b))}, nil +} + +// read 按描述符取出 arena 中的字节（返回的是段内切片视图，调用方须在持锁期间使用）。 +func (s *Segment) read(sl Slice) ([]byte, error) { + if sl.IsUnset() || sl.Len == 0 { + return nil, nil + } + base := s.arenaBase() + if uint64(sl.Off)+uint64(sl.Len) > uint64(s.arenaCap()) { + return nil, fmt.Errorf("proc: 描述符越界（off=%d len=%d cap=%d）", sl.Off, sl.Len, s.arenaCap()) + } + return s.data[base+sl.Off : base+sl.Off+sl.Len], nil +} + +// descOffset 返回字段 f 的描述符在段内的绝对偏移。 +func (s *Segment) descOffset(f stageField) uint32 { + return s.ctxBase() + uint32(int(f)*sliceSize) +} + +func (s *Segment) getDesc(f stageField) Slice { + o := s.descOffset(f) + return Slice{ + Off: binary.LittleEndian.Uint32(s.data[o:]), + Len: binary.LittleEndian.Uint32(s.data[o+4:]), + } +} + +func (s *Segment) setDesc(f stageField, sl Slice) { + o := s.descOffset(f) + binary.LittleEndian.PutUint32(s.data[o:], sl.Off) + binary.LittleEndian.PutUint32(s.data[o+4:], sl.Len) +} + +func (s *Segment) flagsOffset() uint32 { + return s.ctxBase() + uint32(int(stageFieldCount)*sliceSize) +} + +func (s *Segment) getFlag(bit int) bool { + return s.data[s.flagsOffset()+uint32(bit)] != 0 +} + +func (s *Segment) setFlag(bit int, v bool) { + b := byte(0) + if v { + b = 1 + } + s.data[s.flagsOffset()+uint32(bit)] = b +} + +// Compact 回收 arena 垃圾：把仍被描述符引用的数据紧凑重排到段头部。 +// +// 必须在**无插件持锁**时调用（§3.3：由内核在 stage 结束后执行）。 +// 返回回收的字节数。 +func (s *Segment) Compact() uint32 { + before := s.ArenaUsed() + + // 收集现存描述符指向的数据，按字段顺序重新写入。 + type kept struct { + f stageField + data []byte + } + var live []kept + for f := stageField(0); f < stageFieldCount; f++ { + sl := s.getDesc(f) + if sl.IsUnset() { + continue + } + b, err := s.read(sl) + if err != nil { + // 描述符损坏：丢弃该字段而非让压实失败（诊断由上层日志承担） + s.setDesc(f, Slice{}) + continue + } + cp := make([]byte, len(b)) + copy(cp, b) + live = append(live, kept{f: f, data: cp}) + } + + // 重置游标后按序回填 + atomic.StoreUint32((*uint32)(ptrU32(s.data[offArenaUsed:])), 0) + for _, k := range live { + sl, err := s.write(k.data) + if err != nil { + // 压实后仍放不下：理论上不可能（总量未增），保守清空该字段 + s.setDesc(k.f, Slice{}) + continue + } + s.setDesc(k.f, sl) + } + + after := s.ArenaUsed() + if before > after { + return before - after + } + return 0 +} diff --git a/internal/plugin/proc/shm_test.go b/internal/plugin/proc/shm_test.go new file mode 100644 index 0000000..270b1aa --- /dev/null +++ b/internal/plugin/proc/shm_test.go @@ -0,0 +1,441 @@ +package proc + +import ( + "fmt" + "strings" + "sync" + "testing" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 本文件验证共享内存 stage 并发的正确性——**整个迁移最关键的一环**（§4.4 风险 3.4）。 +// +// 对照基线（今日 C ABI 副本模型）： +// - 内置插件（共享 *StageContext + RWMutex）：0% 丢失 +// - 外部插件（快照-副本-写回）：35.8~36.8% 丢失（实验 12），现网量级百分之几脏数据 +// +// 目标：共享内存 + 锁仲裁下，跨进程并发改写收敛到 0% 丢失。 + +// newTestSegment 造一块内存段模拟 mmap 区域（单测无需真 mmap： +// 编解码与 arena 逻辑与底层是 mmap 还是普通内存无关）。 +func newTestSegment(t *testing.T, size int) *Segment { + t.Helper() + buf := make([]byte, size) + seg, err := NewSegment(buf) + if err != nil { + t.Fatalf("NewSegment: %v", err) + } + return seg +} + +func TestSegment_AttachValidatesMagicAndVersion(t *testing.T) { + buf := make([]byte, 8192) + if _, err := NewSegment(buf); err != nil { + t.Fatalf("NewSegment: %v", err) + } + if _, err := AttachSegment(buf); err != nil { + t.Fatalf("AttachSegment 应成功: %v", err) + } + + // 魔数损坏 + bad := make([]byte, len(buf)) + copy(bad, buf) + bad[0] ^= 0xFF + if _, err := AttachSegment(bad); err == nil { + t.Error("魔数不匹配应报错（避免版本不一致时静默错读）") + } + + // 版本不匹配 + badVer := make([]byte, len(buf)) + copy(badVer, buf) + badVer[4] = 99 + if _, err := AttachSegment(badVer); err == nil { + t.Error("版本不匹配应报错") + } +} + +// 全部 16 个字段可跨进程往返——今日经 C ABI 只有 10 个字段可见（§8.3）。 +func TestSegment_RoundTripAllFields(t *testing.T) { + seg := newTestSegment(t, 16384) + + resp := "短路响应" + src := &pubsdk.StageContext{ + RawMessage: "原始输入", + UserID: "u1", + GroupID: "g1", + LLMText: "模型输出", + ReasoningContent: "思考过程", // C ABI 下外部插件看不到 + FinalText: "最终文本", + Response: &resp, + Phase: pubsdk.StageAfterToolcall, + NoMemory: true, + ContextMsgs: []map[string]interface{}{{"role": "user", "content": "hi"}}, // C ABI 看不到 + ToolCalls: []pubsdk.ToolCall{{ID: "t1", Name: "weather_query", Plugin: "weather"}}, + ToolResults: []pubsdk.ToolResult{{CallID: "t1", Name: "weather_query", Success: true, Result: "晴"}}, + Memory: []pubsdk.MemItem{{Role: "user", Content: "记忆", Score: 0.9}}, // C ABI 看不到 + TokenUsage: map[string]int{"prompt": 100, "completion": 50}, // C ABI 看不到 + Errors: []string{"err1"}, // C ABI 看不到 + Extra: map[string]interface{}{ + ExtraKeyMediaType: "image", + ExtraKeyInputSource: "qq", + ExtraKeyOutputChannel: "qq", + }, + } + + if err := seg.WriteAll(src); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + var dst pubsdk.StageContext + if err := seg.ReadInto(&dst); err != nil { + t.Fatalf("ReadInto: %v", err) + } + + if dst.RawMessage != src.RawMessage || dst.UserID != src.UserID || dst.GroupID != src.GroupID { + t.Errorf("标量字段不一致: raw=%q uid=%q gid=%q", dst.RawMessage, dst.UserID, dst.GroupID) + } + if dst.ReasoningContent != "思考过程" { + t.Errorf("ReasoningContent 应可见（C ABI 下不可见）: %q", dst.ReasoningContent) + } + if len(dst.ContextMsgs) != 1 { + t.Errorf("ContextMsgs 应可见: %v", dst.ContextMsgs) + } + if len(dst.Memory) != 1 || dst.Memory[0].Score != 0.9 { + t.Errorf("Memory 应可见: %v", dst.Memory) + } + if dst.TokenUsage["prompt"] != 100 { + t.Errorf("TokenUsage 应可见: %v", dst.TokenUsage) + } + if len(dst.Errors) != 1 { + t.Errorf("Errors 应可见: %v", dst.Errors) + } + if dst.Response == nil || *dst.Response != resp { + t.Errorf("Response 应往返: %v", dst.Response) + } + if !dst.NoMemory { + t.Error("NoMemory 标志应往返") + } + if len(dst.ToolResults) != 1 || dst.ToolResults[0].Result != "晴" { + t.Errorf("ToolResults 应往返: %v", dst.ToolResults) + } + if dst.Extra[ExtraKeyMediaType] != "image" { + t.Errorf("Extra 提升字段应往返: %v", dst.Extra) + } +} + +// nil Response 与空字符串 Response 必须可区分（短路语义依赖此）。 +func TestSegment_ResponseNilVsEmpty(t *testing.T) { + seg := newTestSegment(t, 8192) + + if err := seg.WriteAll(&pubsdk.StageContext{RawMessage: "x"}); err != nil { + t.Fatalf("WriteAll: %v", err) + } + var d1 pubsdk.StageContext + if err := seg.ReadInto(&d1); err != nil { + t.Fatalf("ReadInto: %v", err) + } + if d1.Response != nil { + t.Errorf("未设置的 Response 应为 nil，实际 %q", *d1.Response) + } + + empty := "" + seg2 := newTestSegment(t, 8192) + if err := seg2.WriteAll(&pubsdk.StageContext{Response: &empty}); err != nil { + t.Fatalf("WriteAll: %v", err) + } + var d2 pubsdk.StageContext + if err := seg2.ReadInto(&d2); err != nil { + t.Fatalf("ReadInto: %v", err) + } + if d2.Response == nil { + t.Error("显式设为空串的 Response 不应读成 nil（短路语义会丢）") + } else if *d2.Response != "" { + t.Errorf("Response 应为空串，实际 %q", *d2.Response) + } +} + +// 只读插件的 WriteDirty 必须零写入——**这是消除 lost update 的核心断言**。 +func TestSegment_WriteDirty_ReadOnlyPluginWritesNothing(t *testing.T) { + seg := newTestSegment(t, 16384) + base := &pubsdk.StageContext{ + RawMessage: "查天气", + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "weather_query", Result: "已清洗"}}, + } + if err := seg.WriteAll(base); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + // 插件侧：读入 → 只读 → 写回 + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + t.Fatalf("ReadInto: %v", err) + } + snap := TakeSnapshot(&local) + _ = local.ToolResults[0].Result // 只读，不改 + + n, err := seg.WriteDirty(&local, snap) + if err != nil { + t.Fatalf("WriteDirty: %v", err) + } + if n != 0 { + t.Fatalf("只读插件应零写回，实际写回 %d 个字段（会覆盖他人改写）", n) + } +} + +// 原地改切片元素必须被识别为脏 —— C ABI 侧修 11.3 时踩过的坑。 +func TestSegment_WriteDirty_InPlaceSliceMutationDetected(t *testing.T) { + seg := newTestSegment(t, 16384) + if err := seg.WriteAll(&pubsdk.StageContext{ + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Result: "带\x1b[31mANSI\x1b[0m"}}, + }); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + t.Fatalf("ReadInto: %v", err) + } + snap := TakeSnapshot(&local) + local.ToolResults[0].Result = "带ANSI" // 原地改元素（sanitizer 的实际行为） + + n, err := seg.WriteDirty(&local, snap) + if err != nil { + t.Fatalf("WriteDirty: %v", err) + } + if n != 1 { + t.Fatalf("原地改切片元素应被识别为 1 个脏字段，实际 %d", n) + } + + var after pubsdk.StageContext + if err := seg.ReadInto(&after); err != nil { + t.Fatalf("ReadInto: %v", err) + } + if after.ToolResults[0].Result != "带ANSI" { + t.Errorf("清洗结果未写回: %v", after.ToolResults[0].Result) + } +} + +// 复刻现网场景（实验 13）：sanitizer 改写 + weather 只读并发，清洗结果不得被覆盖。 +// 这是 C ABI 副本模型下量级百分之几脏数据的直接来源。 +func TestSegment_ProductionScenario_SanitizerNotOverwrittenByWeather(t *testing.T) { + seg := newTestSegment(t, 16384) + dirty := "天气：晴 \x1b[31m28°C\x1b[0m" + clean := "天气：晴 28°C" + + if err := seg.WriteAll(&pubsdk.StageContext{ + RawMessage: "查天气", + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "weather_query", Result: dirty}}, + }); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + lock := newStageLock() + + // sanitizer：拿锁 → 读 → 清洗 → 写脏字段 → 放锁 + runSanitizer := func() error { + if err := lock.Acquire("sanitizer"); err != nil { + return err + } + defer lock.Release("sanitizer") + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + return err + } + snap := TakeSnapshot(&local) + if len(local.ToolResults) > 0 { + s, _ := local.ToolResults[0].Result.(string) + local.ToolResults[0].Result = strings.NewReplacer("\x1b[31m", "", "\x1b[0m", "").Replace(s) + } + _, err := seg.WriteDirty(&local, snap) + return err + } + + // weather：拿锁 → 读 → 只读 → 零写回 → 放锁 + runWeather := func() error { + if err := lock.Acquire("weather"); err != nil { + return err + } + defer lock.Release("weather") + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + return err + } + snap := TakeSnapshot(&local) + if len(local.ToolResults) > 0 { + _ = local.ToolResults[0].Result // 只读 + } + n, err := seg.WriteDirty(&local, snap) + if err != nil { + return err + } + if n != 0 { + return fmt.Errorf("weather 只读却写回 %d 个字段", n) + } + return nil + } + + // 并发扇出（保留原始设计），weather 后完成是最坏情形 + var wg sync.WaitGroup + errs := make(chan error, 2) + wg.Add(2) + go func() { defer wg.Done(); errs <- runSanitizer() }() + go func() { defer wg.Done(); errs <- runWeather() }() + wg.Wait() + close(errs) + for err := range errs { + if err != nil { + t.Fatalf("插件执行失败: %v", err) + } + } + + var final pubsdk.StageContext + if err := seg.ReadInto(&final); err != nil { + t.Fatalf("ReadInto: %v", err) + } + got, _ := final.ToolResults[0].Result.(string) + if got != clean { + t.Fatalf("清洗结果被覆盖：期望 %q，实际 %q", clean, got) + } +} + +// 多插件高并发累加同一字段：总写入次数必须等于最终长度（零丢失零撕裂）。 +// 对应实验 8（5 进程 × 300 轮），这里在单进程内用 goroutine 模拟并发扇出， +// 验证共享段 + 锁仲裁 + 脏字段写回三者组合的正确性。 +func TestSegment_ConcurrentAppend_NoLostUpdate(t *testing.T) { + // arena 需容纳 append-only 的中间垃圾：每轮写入长度递增， + // 5 插件 × 40 轮 → 最长 200 字符，累计约 200*201/2 = 20100 字节，留足余量。 + seg := newTestSegment(t, 128*1024) + if err := seg.WriteAll(&pubsdk.StageContext{FinalText: ""}); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + lock := newStageLock() + tags := []string{"A", "B", "C", "D", "E"} + const iters = 40 + + var wg sync.WaitGroup + errCh := make(chan error, len(tags)*iters) + + for _, tag := range tags { + wg.Add(1) + go func(tag string) { + defer wg.Done() + for i := 0; i < iters; i++ { + if err := lock.Acquire(tag); err != nil { + errCh <- err + return + } + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + lock.Release(tag) + errCh <- err + return + } + snap := TakeSnapshot(&local) + local.FinalText += tag // 读-改-写 + if _, err := seg.WriteDirty(&local, snap); err != nil { + lock.Release(tag) + errCh <- err + return + } + if err := lock.Release(tag); err != nil { + errCh <- err + return + } + } + }(tag) + } + wg.Wait() + close(errCh) + for err := range errCh { + if err != nil { + t.Fatalf("并发写入失败: %v", err) + } + } + + var final pubsdk.StageContext + if err := seg.ReadInto(&final); err != nil { + t.Fatalf("ReadInto: %v", err) + } + + // 关键断言：各标记出现次数之和 == 最终长度 ⇒ 无丢失、无撕裂 + total := 0 + counts := map[string]int{} + for _, tag := range tags { + c := strings.Count(final.FinalText, tag) + counts[tag] = c + total += c + } + if total != len(final.FinalText) { + t.Fatalf("出现撕裂：各标记计数之和 %d != 最终长度 %d（counts=%v）", + total, len(final.FinalText), counts) + } + want := len(tags) * iters + if total != want { + t.Fatalf("出现 lost update：期望 %d 次写入全部保留，实际 %d（counts=%v）", + want, total, counts) + } + for tag, c := range counts { + if c != iters { + t.Errorf("插件 %s 的写入丢失：期望 %d 次，实际 %d 次", tag, iters, c) + } + } +} + +// arena 用尽必须显式报错，不得静默截断（§4.4 风险登记）。 +func TestSegment_ArenaExhaustionReturnsError(t *testing.T) { + seg := newTestSegment(t, headerSize+ctxSize+256) // 极小 arena + big := strings.Repeat("x", 1024) + err := seg.WriteAll(&pubsdk.StageContext{FinalText: big}) + if err == nil { + t.Fatal("arena 不足应报错，而非静默截断") + } + if !strings.Contains(err.Error(), "arena 空间不足") { + t.Errorf("错误信息应说明 arena 不足，实际: %v", err) + } +} + +// 压实回收 append-only 垃圾，且不破坏现存字段。 +func TestSegment_CompactReclaimsGarbage(t *testing.T) { + seg := newTestSegment(t, 32*1024) + if err := seg.WriteAll(&pubsdk.StageContext{FinalText: "初始"}); err != nil { + t.Fatalf("WriteAll: %v", err) + } + + // 反复改写同一字段，制造 append-only 垃圾 + for i := 0; i < 50; i++ { + var local pubsdk.StageContext + if err := seg.ReadInto(&local); err != nil { + t.Fatalf("ReadInto: %v", err) + } + snap := TakeSnapshot(&local) + local.FinalText = fmt.Sprintf("第%d次改写内容", i) + if _, err := seg.WriteDirty(&local, snap); err != nil { + t.Fatalf("WriteDirty: %v", err) + } + } + + usedBefore := seg.ArenaUsed() + var beforeCtx pubsdk.StageContext + if err := seg.ReadInto(&beforeCtx); err != nil { + t.Fatalf("ReadInto: %v", err) + } + + reclaimed := seg.Compact() + if reclaimed == 0 { + t.Error("应回收到垃圾空间") + } + if seg.ArenaUsed() >= usedBefore { + t.Errorf("压实后已用空间应下降：%d → %d", usedBefore, seg.ArenaUsed()) + } + + var afterCtx pubsdk.StageContext + if err := seg.ReadInto(&afterCtx); err != nil { + t.Fatalf("压实后 ReadInto: %v", err) + } + if afterCtx.FinalText != beforeCtx.FinalText { + t.Errorf("压实破坏了字段内容：%q → %q", beforeCtx.FinalText, afterCtx.FinalText) + } +} diff --git a/internal/plugin/proc/shmcodec.go b/internal/plugin/proc/shmcodec.go new file mode 100644 index 0000000..c758eae --- /dev/null +++ b/internal/plugin/proc/shmcodec.go @@ -0,0 +1,514 @@ +package proc + +import ( + "encoding/json" + "fmt" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// StageContext 的跨进程编解码（§3.3 数据面 / §3.4 SDK 封装全部复杂度）。 +// +// 设计要点： +// +// 1. **插件作者永远不接触 Slice{off,len}**。插件进程内保留原生 +// *pubsdk.StageContext，handler 照常读写字段；stage 入口从共享段 +// 反序列化成本地对象，handler 返回时把**脏字段**写回共享段。 +// +// 2. **字段级描述符消除 lost update**。只改 FinalText 的插件不触碰 +// ToolResults 的描述符，故不存在"只读插件把旧快照写回覆盖他人改写" +// （今日副本模型实测 35.8~36.8% 丢失，§8.4）。 +// +// 3. **全部 16 个字段可见**。今日经 C ABI 只下发 10 个字段，外部插件永远 +// 看不到 ContextMsgs/ReasoningContent/TokenUsage/Memory/Extra/Errors（§8.3）； +// 共享内存下全部可见可改——接口形式不变，能力变强。 +// +// 4. **Extra 的 4 个键提升为具名字段**（§3.3 已核实全部使用点仅这 4 个）： +// media_blocks / media_type / input_source / output_channel。 +// 它们都是内核写、插件读，无并发改写需求；真正需要多插件并发改的 +// （LLMText/FinalText/ToolCalls/Errors）全是强类型字段。 + +// extra 中被提升为具名字段的键。 +const ( + ExtraKeyMediaBlocks = "media_blocks" + ExtraKeyMediaType = "media_type" + ExtraKeyInputSource = "input_source" + ExtraKeyOutputChannel = "output_channel" +) + +// WriteAll 把整个 StageContext 写入共享段（内核侧在 stage 开始前调用一次）。 +// 调用方须持有写锁。 +func (s *Segment) WriteAll(sc *pubsdk.StageContext) error { + sc.RLock() + snap := captureLocal(sc) + sc.RUnlock() + return s.writeLocal(snap) +} + +// localCtx 是 StageContext 的值快照，用于在不持有 sc 锁的情况下做编解码。 +type localCtx struct { + RawMessage string + UserID string + GroupID string + LLMText string + ReasoningContent string + FinalText string + Response *string + Phase string + NoMemory bool + ContextMsgs []map[string]interface{} + ToolCalls []pubsdk.ToolCall + ToolResults []pubsdk.ToolResult + Memory []pubsdk.MemItem + TokenUsage map[string]int + Errors []string + ExtraMediaBlocks interface{} + ExtraMediaType interface{} + ExtraInputSource interface{} + ExtraOutputChan interface{} +} + +func captureLocal(sc *pubsdk.StageContext) *localCtx { + l := &localCtx{ + RawMessage: sc.RawMessage, + UserID: sc.UserID, + GroupID: sc.GroupID, + LLMText: sc.LLMText, + ReasoningContent: sc.ReasoningContent, + FinalText: sc.FinalText, + Response: sc.Response, + Phase: string(sc.Phase), + NoMemory: sc.NoMemory, + ContextMsgs: sc.ContextMsgs, + ToolCalls: sc.ToolCalls, + ToolResults: sc.ToolResults, + Memory: sc.Memory, + TokenUsage: sc.TokenUsage, + Errors: sc.Errors, + } + if sc.Extra != nil { + l.ExtraMediaBlocks = sc.Extra[ExtraKeyMediaBlocks] + l.ExtraMediaType = sc.Extra[ExtraKeyMediaType] + l.ExtraInputSource = sc.Extra[ExtraKeyInputSource] + l.ExtraOutputChan = sc.Extra[ExtraKeyOutputChannel] + } + return l +} + +func (s *Segment) writeLocal(l *localCtx) error { + putStr := func(f stageField, v string) error { + sl, err := s.write([]byte(v)) + if err != nil { + return fmt.Errorf("写入字段 %s: %w", f, err) + } + s.setDesc(f, sl) + return nil + } + putJSON := func(f stageField, v interface{}) error { + if v == nil { + s.setDesc(f, Slice{}) + return nil + } + b, err := json.Marshal(v) + if err != nil { + return fmt.Errorf("序列化字段 %s: %w", f, err) + } + sl, err := s.write(b) + if err != nil { + return fmt.Errorf("写入字段 %s: %w", f, err) + } + s.setDesc(f, sl) + return nil + } + + for _, step := range []struct { + f stageField + v string + }{ + {fRawMessage, l.RawMessage}, + {fUserID, l.UserID}, + {fGroupID, l.GroupID}, + {fLLMText, l.LLMText}, + {fReasoningContent, l.ReasoningContent}, + {fFinalText, l.FinalText}, + {fPhase, l.Phase}, + } { + if err := putStr(step.f, step.v); err != nil { + return err + } + } + + // Response 是 *string：用标志位表达 nil，避免 "" 与 nil 混淆 + if l.Response != nil { + if err := putStr(fResponse, *l.Response); err != nil { + return err + } + s.setFlag(flagResponseSet, true) + } else { + s.setDesc(fResponse, Slice{}) + s.setFlag(flagResponseSet, false) + } + s.setFlag(flagNoMemory, l.NoMemory) + + // 切片/映射字段：nil 与空切片都写成"未设置"，避免插件收到 [] 后误以为 + // 内核显式清空过（与今日 writable 的 len>0 才下发语义一致）。 + jsonFields := []struct { + f stageField + v interface{} + }{ + {fContextMsgs, sliceOrNil(len(l.ContextMsgs), l.ContextMsgs)}, + {fToolCalls, sliceOrNil(len(l.ToolCalls), l.ToolCalls)}, + {fToolResults, sliceOrNil(len(l.ToolResults), l.ToolResults)}, + {fMemory, sliceOrNil(len(l.Memory), l.Memory)}, + {fTokenUsage, sliceOrNil(len(l.TokenUsage), l.TokenUsage)}, + {fErrors, sliceOrNil(len(l.Errors), l.Errors)}, + {fExtraMediaBlocks, l.ExtraMediaBlocks}, + {fExtraMediaType, l.ExtraMediaType}, + {fExtraInputSource, l.ExtraInputSource}, + {fExtraOutputChannel, l.ExtraOutputChan}, + } + for _, step := range jsonFields { + if err := putJSON(step.f, step.v); err != nil { + return err + } + } + s.bumpSeq() + return nil +} + +// sliceOrNil 让长度为 0 的容器写成 nil（未设置），非零则原样返回。 +func sliceOrNil(n int, v interface{}) interface{} { + if n == 0 { + return nil + } + return v +} + +// ReadInto 从共享段读出全部字段填充到 sc（插件进程侧 stage 入口调用）。 +// 调用方须持有读锁或写锁。 +func (s *Segment) ReadInto(sc *pubsdk.StageContext) error { + getStr := func(f stageField) (string, error) { + b, err := s.read(s.getDesc(f)) + if err != nil { + return "", fmt.Errorf("读取字段 %s: %w", f, err) + } + return string(b), nil + } + getJSON := func(f stageField, out interface{}) error { + b, err := s.read(s.getDesc(f)) + if err != nil { + return fmt.Errorf("读取字段 %s: %w", f, err) + } + if len(b) == 0 { + return nil + } + if err := json.Unmarshal(b, out); err != nil { + return fmt.Errorf("反序列化字段 %s: %w", f, err) + } + return nil + } + + raw, err := getStr(fRawMessage) + if err != nil { + return err + } + uid, err := getStr(fUserID) + if err != nil { + return err + } + gid, err := getStr(fGroupID) + if err != nil { + return err + } + llm, err := getStr(fLLMText) + if err != nil { + return err + } + reason, err := getStr(fReasoningContent) + if err != nil { + return err + } + final, err := getStr(fFinalText) + if err != nil { + return err + } + phase, err := getStr(fPhase) + if err != nil { + return err + } + + var ctxMsgs []map[string]interface{} + var toolCalls []pubsdk.ToolCall + var toolResults []pubsdk.ToolResult + var mem []pubsdk.MemItem + var usage map[string]int + var errs []string + if err := getJSON(fContextMsgs, &ctxMsgs); err != nil { + return err + } + if err := getJSON(fToolCalls, &toolCalls); err != nil { + return err + } + if err := getJSON(fToolResults, &toolResults); err != nil { + return err + } + if err := getJSON(fMemory, &mem); err != nil { + return err + } + if err := getJSON(fTokenUsage, &usage); err != nil { + return err + } + if err := getJSON(fErrors, &errs); err != nil { + return err + } + + extra := map[string]interface{}{} + for _, pair := range []struct { + f stageField + key string + }{ + {fExtraMediaBlocks, ExtraKeyMediaBlocks}, + {fExtraMediaType, ExtraKeyMediaType}, + {fExtraInputSource, ExtraKeyInputSource}, + {fExtraOutputChannel, ExtraKeyOutputChannel}, + } { + var v interface{} + if err := getJSON(pair.f, &v); err != nil { + return err + } + if v != nil { + extra[pair.key] = v + } + } + + var respPtr *string + if s.getFlag(flagResponseSet) { + r, err := getStr(fResponse) + if err != nil { + return err + } + respPtr = &r + } + + sc.Lock() + defer sc.Unlock() + sc.RawMessage = raw + sc.UserID = uid + sc.GroupID = gid + sc.LLMText = llm + sc.ReasoningContent = reason + sc.FinalText = final + sc.Phase = pubsdk.Stage(phase) + sc.NoMemory = s.getFlag(flagNoMemory) + sc.Response = respPtr + sc.ContextMsgs = ctxMsgs + sc.ToolCalls = toolCalls + sc.ToolResults = toolResults + sc.Memory = mem + sc.TokenUsage = usage + sc.Errors = errs + if len(extra) > 0 { + sc.Extra = extra + } else { + sc.Extra = nil + } + return nil +} + +// WriteDirty 只把与 base 快照不同的字段写回共享段（插件进程侧 handler 返回后调用）。 +// +// **这是消除 lost update 的关键**：只读插件的 dirty 集为空 → 零写入 → +// 不可能覆盖其他插件的改写。对比今日副本模型无条件回传 10 个字段的行为 +// （§8.4 实测 35.8~36.8% 丢失，现网量级百分之几的脏数据进 LLM）。 +// +// 返回实际写回的字段数，便于诊断与测试断言。 +func (s *Segment) WriteDirty(sc *pubsdk.StageContext, base *Snapshot) (int, error) { + sc.RLock() + cur := captureLocal(sc) + sc.RUnlock() + + now := newSnapshotFromLocal(cur) + changed := 0 + + putStr := func(f stageField, v string) error { + sl, err := s.write([]byte(v)) + if err != nil { + return fmt.Errorf("写回字段 %s: %w", f, err) + } + s.setDesc(f, sl) + changed++ + return nil + } + putRaw := func(f stageField, raw string) error { + if raw == "" { + s.setDesc(f, Slice{}) + changed++ + return nil + } + sl, err := s.write([]byte(raw)) + if err != nil { + return fmt.Errorf("写回字段 %s: %w", f, err) + } + s.setDesc(f, sl) + changed++ + return nil + } + + for _, step := range []struct { + f stageField + v string + }{ + {fRawMessage, cur.RawMessage}, + {fUserID, cur.UserID}, + {fGroupID, cur.GroupID}, + {fLLMText, cur.LLMText}, + {fReasoningContent, cur.ReasoningContent}, + {fFinalText, cur.FinalText}, + {fPhase, cur.Phase}, + } { + if base.strs[step.f] != now.strs[step.f] { + if err := putStr(step.f, step.v); err != nil { + return changed, err + } + } + } + + // JSON 字段：比较序列化结果 + for f := range now.jsons { + if base.jsons[f] != now.jsons[f] { + if err := putRaw(f, now.jsons[f]); err != nil { + return changed, err + } + } + } + + // Response 的 nil 语义变化也算脏 + if base.responseSet != now.responseSet || base.response != now.response { + if now.responseSet { + if err := putStr(fResponse, now.response); err != nil { + return changed, err + } + s.setFlag(flagResponseSet, true) + } else { + // 插件把 Response 置回 nil：短路语义不应被撑销，故不清空内核已设的值。 + // 与 C ABI 路径 applyStageResult 的行为保持一致。 + s.setFlag(flagResponseSet, s.getFlag(flagResponseSet)) + } + } + if base.noMemory != now.noMemory { + s.setFlag(flagNoMemory, now.noMemory) + changed++ + } + + if changed > 0 { + s.bumpSeq() + } + return changed, nil +} + +// Snapshot 是 handler 运行前的字段快照，用于计算脏字段。 +// +// ❗ 必须存**序列化后的字符串**而非 Go 值：StageContext 的切片字段与 +// 调用方共享底层数组，handler 原地改元素（sc.ToolResults[0].Result = x） +// 时直接持有的 Go 值快照会跟着变，脏字段计算失效——这个坑在 C ABI 侧 +// 修 11.3 时已经踩过一次（见 SDK 仓 stagediff_test.go 的注释）。 +type Snapshot struct { + strs map[stageField]string + jsons map[stageField]string + response string + responseSet bool + noMemory bool +} + +// Snapshot 抓取当前 StageContext 的快照（插件进程侧 handler 前调用）。 +func TakeSnapshot(sc *pubsdk.StageContext) *Snapshot { + sc.RLock() + l := captureLocal(sc) + sc.RUnlock() + return newSnapshotFromLocal(l) +} + +func newSnapshotFromLocal(l *localCtx) *Snapshot { + sn := &Snapshot{ + strs: map[stageField]string{}, + jsons: map[stageField]string{}, + } + sn.strs[fRawMessage] = l.RawMessage + sn.strs[fUserID] = l.UserID + sn.strs[fGroupID] = l.GroupID + sn.strs[fLLMText] = l.LLMText + sn.strs[fReasoningContent] = l.ReasoningContent + sn.strs[fFinalText] = l.FinalText + sn.strs[fPhase] = l.Phase + + marshal := func(v interface{}) string { + if v == nil { + return "" + } + b, err := json.Marshal(v) + if err != nil { + return "" + } + return string(b) + } + sn.jsons[fContextMsgs] = marshal(sliceOrNil(len(l.ContextMsgs), l.ContextMsgs)) + sn.jsons[fToolCalls] = marshal(sliceOrNil(len(l.ToolCalls), l.ToolCalls)) + sn.jsons[fToolResults] = marshal(sliceOrNil(len(l.ToolResults), l.ToolResults)) + sn.jsons[fMemory] = marshal(sliceOrNil(len(l.Memory), l.Memory)) + sn.jsons[fTokenUsage] = marshal(sliceOrNil(len(l.TokenUsage), l.TokenUsage)) + sn.jsons[fErrors] = marshal(sliceOrNil(len(l.Errors), l.Errors)) + sn.jsons[fExtraMediaBlocks] = marshal(l.ExtraMediaBlocks) + sn.jsons[fExtraMediaType] = marshal(l.ExtraMediaType) + sn.jsons[fExtraInputSource] = marshal(l.ExtraInputSource) + sn.jsons[fExtraOutputChannel] = marshal(l.ExtraOutputChan) + + if l.Response != nil { + sn.response = *l.Response + sn.responseSet = true + } + sn.noMemory = l.NoMemory + return sn +} + +// String 让字段枚举在错误信息里可读。 +func (f stageField) String() string { + switch f { + case fRawMessage: + return "raw_message" + case fUserID: + return "user_id" + case fGroupID: + return "group_id" + case fLLMText: + return "llm_text" + case fReasoningContent: + return "reasoning_content" + case fFinalText: + return "final_text" + case fResponse: + return "response" + case fPhase: + return "phase" + case fContextMsgs: + return "context_msgs" + case fToolCalls: + return "tool_calls" + case fToolResults: + return "tool_results" + case fMemory: + return "memory" + case fTokenUsage: + return "token_usage" + case fErrors: + return "errors" + case fExtraMediaBlocks: + return "extra." + ExtraKeyMediaBlocks + case fExtraMediaType: + return "extra." + ExtraKeyMediaType + case fExtraInputSource: + return "extra." + ExtraKeyInputSource + case fExtraOutputChannel: + return "extra." + ExtraKeyOutputChannel + } + return fmt.Sprintf("field(%d)", int(f)) +} diff --git a/internal/plugin/proc/unsafe.go b/internal/plugin/proc/unsafe.go new file mode 100644 index 0000000..093f2ba --- /dev/null +++ b/internal/plugin/proc/unsafe.go @@ -0,0 +1,15 @@ +package proc + +import "unsafe" + +// ptrU32 / ptrU64 把段内字节切片起始处重解释为原子操作可用的指针。 +// +// 共享段由 mmap 得到，其起始地址天然按页对齐（4096），本包所有原子字段 +// （offArenaUsed=16 对齐 4、offSeq=24 对齐 8）都落在对齐位置， +// 因此该重解释是安全的。 +// +// 这是本包唯一使用 unsafe 的地方，且**不涉及 cgo**—— +// 迁移的一个目标就是整个新架构零 cgo（§3.7 锁仲裁回归内核）。 +func ptrU32(b []byte) unsafe.Pointer { return unsafe.Pointer(&b[0]) } + +func ptrU64(b []byte) unsafe.Pointer { return unsafe.Pointer(&b[0]) } diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go index 75a387d..53ce5a9 100644 --- a/internal/plugin/registry.go +++ b/internal/plugin/registry.go @@ -360,10 +360,12 @@ func (r *Registry) isDisabled(name string) bool { return r.cfgReg.IsPluginDisabled(name) } -// pluginEntryHash 计算插件入口文件（plugin.so 或 main.lua）的 SHA256，用于增量重载对比。 +// pluginEntryHash 计算插件入口文件的 SHA256，用于增量重载对比。 // 无入口文件（内置纯工厂插件）返回空字符串（始终视为已加载）。 +// plugin.bin 排在最前：与 detectEntryKind 保持一致的优先级，迁移期间同目录 +// 两种产物共存时以子进程产物为准。 func pluginEntryHash(plgDir string) string { - for _, candidate := range []string{"plugin.so", "plugin.dll", "main.lua", "SKILL.md"} { + for _, candidate := range []string{binEntry, soEntry, dllEntry, "plugin.dylib", luaEntry, skillEntry} { path := filepath.Join(plgDir, candidate) if data, err := os.ReadFile(path); err == nil && len(data) > 0 { sum := sha256.Sum256(data) @@ -763,6 +765,7 @@ func (r *Registry) DisablePlugin(name, by string) error { } func (r *Registry) EnablePlugin(name string) error { return r.Enable(name) } + // StopAndUnload 停止并从注册表移除插件，但保留其配置表（config_）。 // 供插件更新/升级流程使用：换 so/文件不动配置，重装后配置原样生效。 // 不执行 onRemove 回调（那是删除专用语义）。目录由调用方管理。 @@ -888,7 +891,23 @@ func (r *Registry) PluginDir() string { } func (r *Registry) tryDynamic(plgDir, name string, config map[string]interface{}) (sdk.Plugin, error) { - // 尝试顺序：.so (Go plugin on Linux) → .dll (Windows) → .lua (跨平台) + // 按 manifest entry 分派到对应加载通道（外部插件多进程化：.so/.dll 与 .bin 双通道共存）。 + // 这使迁移可逐插件推进、随时回退——把 entry 改回 plugin.so 即回到旧通道。 + if detectEntryKind(plgDir) == entryProc { + plg, err := tryLoadProc(plgDir, name, config) + if err != nil { + return nil, err + } + if plg != nil { + log.Printf("[plugin] %s: 经 proc 通道加载（子进程）", name) + return plg, nil + } + // entry 声明了 plugin.bin 但文件不存在/不可用 → 不隐式回退到 cabi， + // 否则"已迁移插件静默跑回旧通道"极难排查。 + return nil, fmt.Errorf("plugin %s: entry 声明 %s 但未找到可用二进制", name, binEntry) + } + + // 既有探测顺序（保持不变）：.so → .dll → .lua for _, try := range []struct { name string fn func(string, string, map[string]interface{}) (sdk.Plugin, error) From bfa95ba320b0743a2af050c6dd0dbfcc5e3f40ad Mon Sep 17 00:00:00 2001 From: dev Date: Wed, 2 Sep 2026 10:43:40 +0800 Subject: [PATCH 10/27] =?UTF-8?q?docs(plan):=20Part=201=20=E5=AE=8C?= =?UTF-8?q?=E6=88=90=20+=20Part=204=20=E6=A0=B8=E5=BF=83=E5=AE=8C=E6=88=90?= =?UTF-8?q?=E6=A0=87=E8=AE=B0=EF=BC=8C0.3/0.4=20=E6=A0=87=E8=AE=B0?= =?UTF-8?q?=E8=B7=B3=E8=BF=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Part 0.3/0.4 标记 ⏭️ 跳过并记录理由（子进程模型下问题整体消失，不给待删代码打补丁） - Part 1 加载分派骨架 ✅ 完成（修改/审查/验证三步逐条勾选） - Part 4 共享内存数据面 ✅ 核心完成（段/编解码/锁仲裁，RunStage 接线待 Part 2） - 目录加进度快照 --- docs/zh/plugin-migration-plan.md | 76 +++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 6 deletions(-) diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index 0260da2..b3189e5 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -15,15 +15,19 @@ ## 目录 -- **Part 0** 脆弱基线先行（不依赖迁移，现网可直接受益） -- **Part 1** 加载分派骨架（`entry` 双通道共存） -- **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin） +- **Part 0** 脆弱基线先行（不依赖迁移，现网可直接受益）— 0.1 ✅ / 0.2 ✅ / 0.3 ⏭️ / 0.4 ⏭️ +- **Part 1** 加载分派骨架（`entry` 双通道共存）— ✅ **已完成** +- **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin）— ⏳ 下一步 - **Part 3** plugindev 工具链改造（`.bin` 产物） -- **Part 4** 共享内存数据面（StageContext 跨进程并发改写） +- **Part 4** 共享内存数据面（StageContext 跨进程并发改写）— ✅ **核心已完成**（段/编解码/锁仲裁），RunStage 接线待 Part 2 - **Part 5** 通知面（事件环 + eventfd） - **Part 6** 迁移与收尾（17 插件逐个 + 删 cabi + 权限显式化） - 最终验收清单 +> **进度快照（2026-08-31）**：分支 `feature/plugin-proc-migration`。 +> 已交付：现网止血 2 项（11.1/11.3）、entry 双通道分派、共享内存 stage 并发（16 项测试含 -race）。 +> 下一步：Part 2 子进程通道原型（spawn + stdio JSON-RPC + procPlugin），完成后把 `RunStage` 接到共享段。 + --- ## Part 0：脆弱基线先行（阶段 0，~1 人日） @@ -76,7 +80,11 @@ - 【V】✅ `go build ./...` exit 0；`go test ./internal/plugin/... ./internal/agent/...` 全绿。 - ⚠️ **待部署项**：需用新 plugindev 重编全部 17 个外部插件（bridge 模版变更），走 `plugin_install(overwrite=true)`。 -### 0.3 reload 语义修正（11.6） +### 0.3 reload 语义修正（11.6）— ⏭️ **已跳过**（2026-08-31 用户决策：直接进入进程化重构） + +> 子进程模型下 `DF_1_NODELETE` 议题**整体消失**（§3.1）——同路径替换 `plugin.bin` 重启进程即生效。 +> 在 cabi 路径上补 ELF 检测属于「给即将删除的代码打补丁」，性价比低。 +> 现网仍受 reload 假成功影响，但 Part 1 的 entry 分派已为迁移铺路，迁移完成即根治。 - 【M】`dynamic_loader_unix.go`：ELF 检测 `DF_1_NODELETE` → 标记"不可热重载"。 - 【M】`registry.go` 的 `ReloadOne`：对此类插件返回"需重启 homed"。 @@ -84,7 +92,10 @@ - 【R】确认 `.so` 插件重载不再"假成功"。 - 【V】单测：mock ELF 头带 NODELETE vs 不带 → 正确区分。 -### 0.4 超时日志措辞修正 + 附带（11.2 短期项 + 11.4） +### 0.4 超时日志措辞修正 + 附带（11.2 短期项 + 11.4）— ⏭️ **已跳过**（同上） + +> 11.2 的 cgo 超时不可中断在子进程模型下由 `Process.Kill()` 真正解决（§9.5）； +> 11.4 的 Lua 路径在迁移后统一走 RPC（三套 ABI 收敛），锁语义天然有边界。 - 【M】`internal/agent/core/toolcall.go:41`：日志从"已取消"改为"已放弃等待（插件仍在后台运行，其占用的线程无法回收）"。 - 【M】`internal/plugin/lua_plugin.go:726`：stage 快照加 `sc.RLock()`/`RUnlock()`（11.4）。 @@ -126,6 +137,26 @@ - 【V】既有 `.so` 插件加载 e2e 不回归（带一个真实 .so 冒烟）。 **Part 1 出口条件**：分派骨架在，`.bin` 有明确桩位，`.so` 全回归。 +#### ✅ **Part 1 已完成**（2026-08-31，commit `610e9d0`） + +- 【M】✅ `dynamic.go`：新增 `binEntry`/`skillEntry` 常量 + `entryKind` 枚举 + `classifyEntry` / `detectEntryKind` + - **manifest 的 entry 优先级最高**——把 entry 改回 `plugin.so` 即回退 cabi 通道（回退路径的保证） + - 无 manifest 时按目录探测，`.bin` 优先于 `.so`（迁移期同目录两产物共存时走新通道） +- 【M】✅ `registry.go` `tryDynamic`：按 entry 分派 proc/cabi；entry 声明 `.bin` 但二进制缺失时**报明确错误，不静默回退** +- 【M】✅ `registry.go` `pluginEntryHash`：候选顺序与 `detectEntryKind` 对齐（`.bin` 优先），否则增量重载会用错文件算 hash +- 【M】✅ `manifest.go`：`Entry` 字段注释补 `plugin.bin` +- 【M】✅ `dynamic_proc_unix.go` / `dynamic_proc_windows.go`：`tryLoadProc` 桩位（存在性/类型/可执行权限校验已实现） +- 【R】✅ 内置插件（`hasFactory` 分支）完全未受影响——仍走进程内 `RegisterNative` +- 【R】✅ `.so` 路径行为与改动前一致（既有测试全绿，无回归） +- 【R】✅ 接口冻结：`git diff third_party/homeagent-sdk/sdk/` 为空 +- 【V】✅ `entry_dispatch_test.go` 9 项全绿： + - `TestClassifyEntry`（8 种 entry 分类） + - `TestDetectEntryKind_ManifestWins` / `_ManifestCanForceRollback`（**回退路径验证**） + - `TestDetectEntryKind_ProbeOrderPrefersBin` / `_ProbeFallbacks`（4 子例） + - `TestTryLoadProc_MissingBinaryReturnsNil` / `_NonExecutableRejected` + - `TestPluginEntryHash_PrefersBin` / `_EmptyForFactoryOnlyPlugin` +- 【V】✅ `go build ./...` exit 0；`go test -race ./internal/plugin/...` 全绿；全量 32 个包测试通过 + --- @@ -225,6 +256,39 @@ - 【V】改写型插件行为基线测试：`sanitizer`/`multimodal` 迁移前后行为对拍（迁移评估 §4.4 风险缓解）。 **Part 4 出口条件**：跨进程并发改写零丢失，内置/外置语义一致，16 字段全可见。 +#### ✅ **Part 4 核心已完成**（2026-08-31，commit `610e9d0`）—— 段 / 编解码 / 锁仲裁三件套 + +> 用户明确指出「基于共享内存的 stage 并发是最为关键的」，故先于 Part 2/3 落地数据面。 +> `RunStage` 的跨进程接线（3.4）待 Part 2 的进程通道就绪后进行。 + +- 【M】✅ `proc/shm.go` 段布局与 arena 分配器（§3.3） + - `Header(64B) + ShmStageCtx(描述符数组 + 标志位) + append-only arena` + - **相对偏移**：各进程 mmap 到不同虚拟地址仍能正确解引用 + - `NewSegment` / `AttachSegment` 带魔数 + 版本校验（版本不匹配显式报错，不静默错读） + - **arena 用尽显式报错**而非静默截断（§4.4 风险登记的硬要求） + - `Compact()` 回收 append-only 垃圾，须在无插件持锁时调用 +- 【M】✅ `proc/shmcodec.go` StageContext 16 字段跨进程编解码（§3.4） + - **字段级描述符消除 lost update**：只改 `FinalText` 的插件完全不触碰 `ToolResults` 描述符 + - `WriteDirty` 只写脏字段——**只读插件零写入**，不可能覆盖他人改写 + - `Snapshot` 存**序列化字符串**（切片共享底层数组的坑，C ABI 侧修 11.3 时已踩过一次） + - `Extra` 4 键提升为具名字段；`Response` 用标志位区分 nil 与空串（短路语义） + - **全 16 字段可见**——今日经 C ABI 只有 10 个，`ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` 首次对外部插件可见 +- 【M】✅ `proc/lock.go` 锁仲裁回归内核（§3.7 已裁定，**零 cgo**） + - `ForceRelease` 实现实验 9 的崩溃自愈 → 排除 robust pthread_mutex 必要性 + - 重复加锁**显式拒绝**（否则死锁 30s，比挂死更难排查） + - 等待超时有补偿 goroutine 防锁永久泄漏 +- 【R】✅ 并发语义：`TestSegment_ConcurrentAppend_NoLostUpdate` 断言「各标记计数之和 == 最终长度 且 == 期望写入次数」，同时排除丢失与撕裂 +- 【R】✅ arena 上限报错（非静默截断）：`TestSegment_ArenaExhaustionReturnsError` +- 【R】✅ `Extra` 维持 4 键具名字段，未引入通用 tagged union 成本 +- 【R】✅ 接口冻结：`sdk/` 零 diff；`StageContext` 结构体未改 +- 【R】✅ `go vet` 干净（含 copylocks 检查） +- 【V】✅ proc 包 **16 项测试全绿（含 `-race`）**： + - 段：魔数/版本校验、全 16 字段往返、Response nil vs 空串 + - 脏字段：只读零写回、原地改切片被识别、压实不破坏字段 + - **现网场景复刻**：`TestSegment_ProductionScenario_SanitizerNotOverwrittenByWeather`（sanitizer 清洗 + weather 只读并发，清洗结果不被覆盖） + - **并发零丢失**：5 插件 × 40 轮读-改-写同一字段，200 次写入全部保留 + - 锁：互斥、串扰拒绝、未持锁释放拒绝、重复加锁拒绝、**崩溃自愈**、定向强制释放、临界区串行化 + --- From d62430a71bf1326b90dfa512fb215e54a1e39174 Mon Sep 17 00:00:00 2001 From: dev Date: Wed, 2 Sep 2026 10:59:59 +0800 Subject: [PATCH 11/27] =?UTF-8?q?feat(proc):=20=E5=AD=90=E8=BF=9B=E7=A8=8B?= =?UTF-8?q?=E9=80=9A=E9=81=93=20=E2=80=94=E2=80=94=20RPC=20=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE=20+=20=E8=BF=9B=E7=A8=8B=E7=AE=A1=E7=90=86=EF=BC=88Pa?= =?UTF-8?q?rt=202=20=E6=A0=B8=E5=BF=83=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 协议面（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/ 为空 --- internal/plugin/proc/process.go | 499 ++++++++++++++++++ internal/plugin/proc/process_test.go | 334 ++++++++++++ internal/plugin/proc/protocol.go | 215 ++++++++ .../plugin/proc/testdata/badprotoplugin.go | 52 ++ .../plugin/proc/testdata/callbackplugin.go | 120 +++++ internal/plugin/proc/testdata/crashplugin.go | 54 ++ internal/plugin/proc/testdata/echoplugin.go | 76 +++ internal/plugin/proc/testdata/hangplugin.go | 56 ++ 8 files changed, 1406 insertions(+) create mode 100644 internal/plugin/proc/process.go create mode 100644 internal/plugin/proc/process_test.go create mode 100644 internal/plugin/proc/protocol.go create mode 100644 internal/plugin/proc/testdata/badprotoplugin.go create mode 100644 internal/plugin/proc/testdata/callbackplugin.go create mode 100644 internal/plugin/proc/testdata/crashplugin.go create mode 100644 internal/plugin/proc/testdata/echoplugin.go create mode 100644 internal/plugin/proc/testdata/hangplugin.go diff --git a/internal/plugin/proc/process.go b/internal/plugin/proc/process.go new file mode 100644 index 0000000..16e3102 --- /dev/null +++ b/internal/plugin/proc/process.go @@ -0,0 +1,499 @@ +package proc + +import ( + "bufio" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "log" + "os" + "os/exec" + "sync" + "sync/atomic" + "time" + + "gitcode.com/JianFeeeee/HomeAgent/internal/meta" +) + +// Process 管理一个外部插件子进程：spawn / 双向 JSON-RPC / 优雅停止 / 崩溃检测。 +// +// 设计依据：docs/zh/架构迁移评估.md §4.1 阶段 2、§2.3（保留现有生命周期机制） +// +// 与 C ABI 路径的关键差异： +// - **崩溃隔离**：插件 panic 只让子进程退出，homed 存活（今日 panic 跨 C 栈可带崩内核） +// - **真正的取消**：Kill() 后 OS 回收全部资源，零泄漏 +// （今日 cgo 调用不可抢占，超时后 OS 线程永久占用，现网已泄漏 26 次，§9.3） +// - **可同步等真实结果**：RPC 天然可等应答 +// （今日 cgo 不可嵌套，output_send 只能异步、永远假成功，§9.4） +type Process struct { + name string + bin string + dir string + + cmd *exec.Cmd + stdin *bufio.Writer + stdout io.ReadCloser + + // writeMu 串行化 stdin 写入：NDJSON 帧不能交错，否则对端解析错乱。 + writeMu sync.Mutex + + // pending 表：请求 ID → 应答通道。 + mu sync.Mutex + nextID uint64 + pending map[uint64]chan *Response + closed bool + + // handler 处理插件反向发起的调用（51 个 core.* method）。 + handler RequestHandler + + // exited 在 readLoop 检测到 EOF/进程退出后关闭，用于唤醒所有等待者。 + exited chan struct{} + exitOnce sync.Once + exitErr atomic.Pointer[error] + readerWG sync.WaitGroup + readyOnce sync.Once + ready chan struct{} + + // onExit 在进程退出时回调（内核用它喂 plugin_health.recordCrash， + // 以及 ForceRelease 释放该插件持有的 stage 锁）。 + onExit func(name string, err error) + + // shmSize 是握手时告知插件的共享段大小（0 表示本插件不用共享段）。 + shmSize int +} + +// RequestHandler 处理插件 → 内核的调用。 +// 返回值会被序列化为 Response.Result；返回 error 则序列化为 Response.Error。 +type RequestHandler func(method string, params json.RawMessage) (interface{}, error) + +// Options 是 Spawn 的可选配置。 +type Options struct { + // Dir 是子进程工作目录（通常为插件目录）。 + Dir string + // Env 追加到子进程环境变量。 + Env []string + // ExtraFiles 传给子进程的额外文件描述符（fd 3 起）。 + // 共享内存段的 memfd 经此传递——子进程 mmap fd 3 即挂载同一段。 + ExtraFiles []*os.File + // ShmSize 是共享段大小，握手时告知插件（与 ExtraFiles[0] 的 memfd 对应）。 + ShmSize int + // Handler 处理插件反向调用。 + Handler RequestHandler + // OnExit 进程退出回调。 + OnExit func(name string, err error) + // HandshakeTimeout 建链超时，默认 10s。 + HandshakeTimeout time.Duration +} + +// 默认超时。 +const ( + defaultHandshakeTimeout = 10 * time.Second + // stopGracePeriod 是发出 plugin.stop 后等待进程自行退出的时间。 + // 超时则 Kill——**这是"真正的取消"**，对比 cgo 路径超时后线程永久泄漏。 + stopGracePeriod = 5 * time.Second +) + +// ErrProcessExited 表示子进程已退出，调用无法完成。 +var ErrProcessExited = errors.New("proc: 插件进程已退出") + +// Spawn 启动插件子进程并完成握手。 +func Spawn(name, bin string, opts Options) (*Process, error) { + if opts.Handler == nil { + return nil, fmt.Errorf("proc: %s 缺少 RequestHandler（插件无法回调内核）", name) + } + timeout := opts.HandshakeTimeout + if timeout <= 0 { + timeout = defaultHandshakeTimeout + } + + cmd := exec.Command(bin) + cmd.Dir = opts.Dir + // stderr 直通内核日志：插件的 panic 栈、log 输出可直接看到。 + cmd.Stderr = os.Stderr + if len(opts.Env) > 0 { + cmd.Env = append(os.Environ(), opts.Env...) + } + cmd.ExtraFiles = opts.ExtraFiles + + stdinPipe, err := cmd.StdinPipe() + if err != nil { + return nil, fmt.Errorf("proc: %s stdin 管道: %w", name, err) + } + stdoutPipe, err := cmd.StdoutPipe() + if err != nil { + return nil, fmt.Errorf("proc: %s stdout 管道: %w", name, err) + } + + p := &Process{ + name: name, + bin: bin, + dir: opts.Dir, + cmd: cmd, + stdin: bufio.NewWriter(stdinPipe), + stdout: stdoutPipe, + pending: make(map[uint64]chan *Response), + handler: opts.Handler, + exited: make(chan struct{}), + ready: make(chan struct{}), + onExit: opts.OnExit, + shmSize: opts.ShmSize, + } + + if err := cmd.Start(); err != nil { + return nil, fmt.Errorf("proc: 启动 %s (%s): %w", name, bin, err) + } + + p.readerWG.Add(1) + go p.readLoop() + + // 等 readLoop 就绪后再握手，避免应答早于 reader 启动而丢失。 + <-p.ready + + if err := p.handshake(timeout); err != nil { + p.Kill() + return nil, err + } + return p, nil +} + +// Name 返回插件名。 +func (p *Process) Name() string { return p.name } + +// PID 返回子进程 PID（用于诊断/日志）。 +func (p *Process) PID() int { + if p.cmd == nil || p.cmd.Process == nil { + return 0 + } + return p.cmd.Process.Pid +} + +// Exited 返回一个在进程退出时关闭的通道。 +func (p *Process) Exited() <-chan struct{} { return p.exited } + +// ExitError 返回进程退出原因（正常退出为 nil）。 +func (p *Process) ExitError() error { + if e := p.exitErr.Load(); e != nil { + return *e + } + return nil +} + +func (p *Process) handshake(timeout time.Duration) error { + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + raw, err := p.CallContext(ctx, MethodHandshake, HandshakeParams{ + Protocol: ProtocolVersion, + CoreVersion: meta.Version, + PluginName: p.name, + ShmVersion: shmVersion, + ShmSize: p.shmSize, + }) + if err != nil { + return fmt.Errorf("proc: %s 握手失败: %w", p.name, err) + } + var res HandshakeResult + if err := json.Unmarshal(raw, &res); err != nil { + return fmt.Errorf("proc: %s 握手应答解析失败: %w", p.name, err) + } + if res.Protocol != ProtocolVersion { + return fmt.Errorf("proc: %s 协议版本不匹配（插件 %d，内核 %d）——请用配套 plugindev 重编", + p.name, res.Protocol, ProtocolVersion) + } + log.Printf("[proc] %s 已建链（pid=%d protocol=%d sdk=%s）", + p.name, p.PID(), res.Protocol, res.SDKVersion) + return nil +} + +// readLoop 读取子进程 stdout 的 NDJSON 帧，分派为「应答」或「插件发起的请求」。 +// +// 参考 clawhubadapter/sidecarProcess 的成熟做法：大 buffer 防长行截断、 +// pending 表定位应答、退出时唤醒全部等待者。 +func (p *Process) readLoop() { + defer p.readerWG.Done() + + scanner := bufio.NewScanner(bufio.NewReader(p.stdout)) + // 单帧上限 1MB：控制面帧本应很小（工具结果中位 93B）， + // 超大 payload 应走共享内存 arena 而非 RPC 帧。 + scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) + + p.readyOnce.Do(func() { close(p.ready) }) + + for scanner.Scan() { + line := scanner.Bytes() + if len(line) == 0 { + continue + } + // 帧可能是 Response（有 id 无 method）或 Request（有 method）。 + var probe struct { + ID uint64 `json:"id"` + Method string `json:"method"` + } + if err := json.Unmarshal(line, &probe); err != nil { + log.Printf("[proc] %s 收到非法 JSON 帧（%d 字节）: %v", p.name, len(line), err) + continue + } + + if probe.Method != "" { + // 插件发起的调用：拷贝一份再交给 goroutine（scanner 会复用底层数组） + buf := make([]byte, len(line)) + copy(buf, line) + go p.serveRequest(buf) + continue + } + + var resp Response + if err := json.Unmarshal(line, &resp); err != nil { + log.Printf("[proc] %s 应答解析失败: %v", p.name, err) + continue + } + p.mu.Lock() + ch, ok := p.pending[resp.ID] + delete(p.pending, resp.ID) + p.mu.Unlock() + if !ok { + log.Printf("[proc] %s 收到未知 id=%d 的应答（可能已超时）", p.name, resp.ID) + continue + } + ch <- &resp + } + + if err := scanner.Err(); err != nil { + log.Printf("[proc] %s 读取 stdout 出错: %v", p.name, err) + } + + // stdout 关闭（EOF）意味着进程结束——2.5ms 内即可感知（实验 6）。 + p.markExited() +} + +// markExited 回收进程、唤醒所有等待者、触发 onExit 回调。 +// +// 这是「把 panic 捕获换成进程退出检测」的落点（§2.3）： +// plugin_health 的 recordCrash / 冷却 / 自愈 / pendingReloads 全部逻辑复用， +// 只是信号源从 recover() 变成进程退出。 +func (p *Process) markExited() { + p.exitOnce.Do(func() { + waitErr := p.cmd.Wait() + if waitErr != nil { + e := fmt.Errorf("插件进程 %s 异常退出: %w", p.name, waitErr) + p.exitErr.Store(&e) + log.Printf("[proc] %s 退出: %v", p.name, waitErr) + } else { + log.Printf("[proc] %s 正常退出", p.name) + } + + p.mu.Lock() + p.closed = true + waiters := make([]chan *Response, 0, len(p.pending)) + for id, ch := range p.pending { + waiters = append(waiters, ch) + delete(p.pending, id) + } + p.mu.Unlock() + + // 唤醒所有在途调用，避免调用方挂死到自己的超时 + for _, ch := range waiters { + ch <- &Response{Error: ErrProcessExited.Error()} + } + + close(p.exited) + if p.onExit != nil { + p.onExit(p.name, p.ExitError()) + } + }) +} + +// serveRequest 处理插件反向发起的调用。 +func (p *Process) serveRequest(line []byte) { + var req Request + if err := json.Unmarshal(line, &req); err != nil { + log.Printf("[proc] %s 请求解析失败: %v", p.name, err) + return + } + + // panic 隔离：插件的回调参数可能触发内核 handler 的 panic， + // 不能让它带崩整个 readLoop（更不能带崩 homed）。 + var ( + result interface{} + err error + ) + func() { + defer func() { + if r := recover(); r != nil { + err = fmt.Errorf("内核 handler 处理 %s 时 panic: %v", req.Method, r) + log.Printf("[proc] %s: %v", p.name, err) + } + }() + result, err = p.handler(req.Method, req.Params) + }() + + // ID==0 是通知，不回应答（§2.4 约束 B：post-and-forget） + if req.ID == 0 { + if err != nil { + log.Printf("[proc] %s 通知 %s 处理失败: %v", p.name, req.Method, err) + } + return + } + + resp := Response{ID: req.ID} + if err != nil { + resp.Error = err.Error() + } else if result != nil { + if b, mErr := json.Marshal(result); mErr == nil { + resp.Result = b + } else { + resp.Error = fmt.Sprintf("结果序列化失败: %v", mErr) + } + } + if wErr := p.writeFrame(&resp); wErr != nil { + log.Printf("[proc] %s 回写应答失败: %v", p.name, wErr) + } +} + +// writeFrame 序列化并写入一帧（串行化，NDJSON 不能交错）。 +func (p *Process) writeFrame(v interface{}) error { + b, err := json.Marshal(v) + if err != nil { + return err + } + p.writeMu.Lock() + defer p.writeMu.Unlock() + if _, err := p.stdin.Write(b); err != nil { + return err + } + if err := p.stdin.WriteByte('\n'); err != nil { + return err + } + return p.stdin.Flush() +} + +// Call 发起 RPC 并等待应答（无超时上限，由调用方 context 控制）。 +func (p *Process) Call(method string, params interface{}) (json.RawMessage, error) { + return p.CallContext(context.Background(), method, params) +} + +// CallContext 发起 RPC 并等待应答，受 ctx 取消/超时控制。 +// +// **ctx 取消时调用方立即返回，且 pending 条目被清理**—— +// 对比 cgo 路径：超时只让调用方返回，goroutine 仍永久卡在 C 调用里（§9.3）。 +// 这里子进程若真卡住，上层可 Kill()，OS 回收全部资源。 +func (p *Process) CallContext(ctx context.Context, method string, params interface{}) (json.RawMessage, error) { + var raw json.RawMessage + if params != nil { + b, err := json.Marshal(params) + if err != nil { + return nil, fmt.Errorf("proc: %s 序列化 %s 参数: %w", p.name, method, err) + } + raw = b + } + + ch := make(chan *Response, 1) + + p.mu.Lock() + if p.closed { + p.mu.Unlock() + return nil, fmt.Errorf("proc: %s 调用 %s: %w", p.name, method, ErrProcessExited) + } + p.nextID++ + id := p.nextID + p.pending[id] = ch + p.mu.Unlock() + + if err := p.writeFrame(&Request{ID: id, Method: method, Params: raw}); err != nil { + p.mu.Lock() + delete(p.pending, id) + p.mu.Unlock() + return nil, fmt.Errorf("proc: %s 发送 %s: %w", p.name, method, err) + } + + select { + case resp := <-ch: + if resp.Error != "" { + return nil, fmt.Errorf("proc: %s.%s: %s", p.name, method, resp.Error) + } + return resp.Result, nil + case <-ctx.Done(): + p.mu.Lock() + delete(p.pending, id) + p.mu.Unlock() + return nil, fmt.Errorf("proc: %s 调用 %s: %w", p.name, method, ctx.Err()) + case <-p.exited: + return nil, fmt.Errorf("proc: %s 调用 %s: %w", p.name, method, ErrProcessExited) + } +} + +// Notify 发送不需要应答的通知（ID=0，fire-and-forget）。 +// +// 用于事件投递等路径：内核发通知**绝不等待消费者**（§2.4 约束 B—— +// 流式输出逐 token 发布，任何等待都会造成卡顿）。 +func (p *Process) Notify(method string, params interface{}) error { + var raw json.RawMessage + if params != nil { + b, err := json.Marshal(params) + if err != nil { + return err + } + raw = b + } + p.mu.Lock() + closed := p.closed + p.mu.Unlock() + if closed { + return ErrProcessExited + } + return p.writeFrame(&Request{Method: method, Params: raw}) +} + +// Stop 优雅停止：发 plugin.stop → 等宽限期 → 超时则 Kill。 +// +// 插件侧收到 plugin.stop 后应先跑 RunStopHandlers 再 Stop()， +// 与 C ABI 路径的停止链路语义一致（§2.3 已验证被正确调用）。 +func (p *Process) Stop() error { + select { + case <-p.exited: + return nil // 已经退出 + default: + } + + ctx, cancel := context.WithTimeout(context.Background(), stopGracePeriod) + defer cancel() + if _, err := p.CallContext(ctx, MethodPluginStop, nil); err != nil { + // 停止调用失败不影响后续 Kill——插件可能已经崩了 + if !errors.Is(err, ErrProcessExited) { + log.Printf("[proc] %s plugin.stop 失败（将强制结束）: %v", p.name, err) + } + } + + select { + case <-p.exited: + return nil + case <-time.After(stopGracePeriod): + log.Printf("[proc] %s 宽限期内未退出，强制结束", p.name) + return p.Kill() + } +} + +// Kill 强制结束子进程并回收资源。 +// +// **这是 C ABI 路径拿不到的能力**：cgo 调用不可被 Go runtime 抢占或取消， +// 超时后该 OS 线程永久占用（实验 14 实测 20 次调用线性泄漏 +18 线程）。 +// 子进程模型下 Kill 后 OS 回收全部资源，零泄漏。 +func (p *Process) Kill() error { + if p.cmd == nil || p.cmd.Process == nil { + return nil + } + err := p.cmd.Process.Kill() + // 等 readLoop 观察到 EOF 并完成 Wait/清理 + select { + case <-p.exited: + case <-time.After(2 * time.Second): + p.markExited() // 兜底：极端情况下强制走清理 + } + p.readerWG.Wait() + if err != nil && !errors.Is(err, os.ErrProcessDone) { + return fmt.Errorf("proc: 结束 %s: %w", p.name, err) + } + return nil +} diff --git a/internal/plugin/proc/process_test.go b/internal/plugin/proc/process_test.go new file mode 100644 index 0000000..50c2893 --- /dev/null +++ b/internal/plugin/proc/process_test.go @@ -0,0 +1,334 @@ +package proc + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + "sync" + "testing" + "time" +) + +// Process 的测试用真实子进程（go build 出的小二进制），而非 mock： +// 崩溃隔离、EOF 感知、Kill 回收这些性质只有真进程才能验证—— +// 它们恰是迁移相对 C ABI 的核心收益（§9.5）。 + +// buildTestPlugin 编译 testdata 下的假插件，返回二进制路径。 +func buildTestPlugin(t *testing.T, srcName string) string { + t.Helper() + if _, err := exec.LookPath("go"); err != nil { + t.Skip("环境无 go 工具链，跳过子进程测试") + } + + src := filepath.Join("testdata", srcName) + if _, err := os.Stat(src); err != nil { + t.Fatalf("测试插件源码缺失 %s: %v", src, err) + } + + bin := filepath.Join(t.TempDir(), strings.TrimSuffix(srcName, ".go")) + cmd := exec.Command("go", "build", "-o", bin, src) + cmd.Env = append(os.Environ(), "CGO_ENABLED=0") + if out, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("编译测试插件 %s 失败: %v\n%s", srcName, err, out) + } + return bin +} + +// noopHandler 是最简的内核侧 handler（测试中不需要真实 core.* 能力）。 +func noopHandler(method string, params json.RawMessage) (interface{}, error) { + return nil, fmt.Errorf("测试环境未实现 %s", method) +} + +func TestProcess_SpawnHandshakeAndToolInvoke(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + if p.PID() == 0 { + t.Error("PID 应非零") + } + + raw, err := p.Call(MethodToolInvoke, ToolInvokeParams{ + Name: "echo_tool", + Args: map[string]interface{}{"text": "你好"}, + }) + if err != nil { + t.Fatalf("tool.invoke: %v", err) + } + var res ToolInvokeResult + if err := json.Unmarshal(raw, &res); err != nil { + t.Fatalf("解析应答: %v", err) + } + if res.Result != "你好" { + t.Fatalf("工具应回显 '你好'，实际 %v", res.Result) + } +} + +// 插件返回错误时调用方必须收到 error —— 对比 C ABI 路径的 output_send +// 永远返回成功（§9.4，现网 2 次消息发不出而模型以为成功）。 +func TestProcess_PluginErrorIsReported(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + _, err = p.Call(MethodToolInvoke, ToolInvokeParams{Name: "fail_tool"}) + if err == nil { + t.Fatal("插件返回错误时调用方应收到 error") + } + if !strings.Contains(err.Error(), "故意失败") { + t.Errorf("错误信息应透传插件的原因，实际: %v", err) + } +} + +// 插件反向调用内核（51 个 core.* method 的机制验证）。 +func TestProcess_PluginCallsBackIntoKernel(t *testing.T) { + bin := buildTestPlugin(t, "callbackplugin.go") + + var ( + mu sync.Mutex + gotCall []string + ) + handler := func(method string, params json.RawMessage) (interface{}, error) { + mu.Lock() + gotCall = append(gotCall, method) + mu.Unlock() + switch method { + case MethodSettingsGet: + return map[string]interface{}{"value": "配置值"}, nil + case MethodToolRegister: + return nil, nil + } + return nil, fmt.Errorf("未实现 %s", method) + } + + p, err := Spawn("cb", bin, Options{Handler: handler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + // plugin.start 期间插件会回调 tool.register + settings.get + if _, err := p.Call(MethodPluginStart, nil); err != nil { + t.Fatalf("plugin.start: %v", err) + } + + mu.Lock() + defer mu.Unlock() + if len(gotCall) < 2 { + t.Fatalf("内核应收到插件的反向调用，实际 %v", gotCall) + } + hasRegister, hasSettings := false, false + for _, m := range gotCall { + if m == MethodToolRegister { + hasRegister = true + } + if m == MethodSettingsGet { + hasSettings = true + } + } + if !hasRegister || !hasSettings { + t.Errorf("应收到 tool.register 与 settings.get，实际 %v", gotCall) + } +} + +// 崩溃隔离：插件 panic 只让子进程退出，内核存活并收到 onExit（§9.5 表格第 2 行）。 +// C ABI 路径下 panic 跨 C 栈，recover 兜不住会带崩整个 homed（§1.4）。 +func TestProcess_CrashIsolationAndExitDetection(t *testing.T) { + bin := buildTestPlugin(t, "crashplugin.go") + + exitCh := make(chan error, 1) + p, err := Spawn("crash", bin, Options{ + Handler: noopHandler, + OnExit: func(name string, err error) { exitCh <- err }, + }) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + + // 触发插件 panic + _, callErr := p.Call(MethodToolInvoke, ToolInvokeParams{Name: "boom"}) + if callErr == nil { + t.Error("插件崩溃时在途调用应返回错误，而非挂死") + } + + select { + case exitErr := <-exitCh: + if exitErr == nil { + t.Error("panic 退出应报告非 nil 错误（供 recordCrash 使用）") + } + case <-time.After(5 * time.Second): + t.Fatal("未在 5s 内检测到进程退出（EOF 感知失效）") + } + + select { + case <-p.Exited(): + case <-time.After(time.Second): + t.Error("Exited() 通道应已关闭") + } + + // 进程已退出后继续调用应立即失败，不能挂死 + if _, err := p.Call(MethodToolInvoke, ToolInvokeParams{Name: "echo_tool"}); !errors.Is(err, ErrProcessExited) { + t.Errorf("退出后调用应返回 ErrProcessExited，实际 %v", err) + } +} + +// 优雅停止：plugin.stop 后进程自行退出。 +func TestProcess_GracefulStop(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + + if err := p.Stop(); err != nil { + t.Fatalf("Stop: %v", err) + } + select { + case <-p.Exited(): + case <-time.After(3 * time.Second): + t.Fatal("Stop 后进程应退出") + } + if err := p.ExitError(); err != nil { + t.Errorf("优雅停止应无错误退出，实际 %v", err) + } +} + +// **真正的取消**：卡死的插件可被 Kill 回收（§9.3 对照 cgo 超时线程永久泄漏）。 +func TestProcess_KillHungPlugin(t *testing.T) { + bin := buildTestPlugin(t, "hangplugin.go") + p, err := Spawn("hang", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + + // 调用会卡住，用 context 超时返回（调用方不被拖死） + ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond) + defer cancel() + _, err = p.CallContext(ctx, MethodToolInvoke, ToolInvokeParams{Name: "hang_tool"}) + if err == nil { + t.Fatal("卡死的调用应因 ctx 超时返回") + } + if !errors.Is(err, context.DeadlineExceeded) { + t.Errorf("应为 DeadlineExceeded，实际 %v", err) + } + + // pending 条目必须已清理（不泄漏） + p.mu.Lock() + pendingCount := len(p.pending) + p.mu.Unlock() + if pendingCount != 0 { + t.Errorf("超时后 pending 表应清空，实际残留 %d 条", pendingCount) + } + + // Kill 真正回收资源 + if err := p.Kill(); err != nil { + t.Fatalf("Kill: %v", err) + } + select { + case <-p.Exited(): + case <-time.After(3 * time.Second): + t.Fatal("Kill 后进程应退出") + } +} + +// 通知（ID=0）不等应答——事件投递路径必须 post-and-forget（§2.4 约束 B）。 +func TestProcess_NotifyDoesNotWait(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + start := time.Now() + for i := 0; i < 100; i++ { + if err := p.Notify("event.deliver", map[string]interface{}{"seq": i}); err != nil { + t.Fatalf("Notify: %v", err) + } + } + elapsed := time.Since(start) + // 100 条通知若每条都等应答，至少要 100 个往返；post-and-forget 应远快于此 + if elapsed > time.Second { + t.Errorf("100 条通知耗时 %v，疑似在等应答（应 post-and-forget）", elapsed) + } + + // 通知不占 pending 表 + p.mu.Lock() + pendingCount := len(p.pending) + p.mu.Unlock() + if pendingCount != 0 { + t.Errorf("通知不应占用 pending 表，实际 %d 条", pendingCount) + } +} + +// 并发调用：pending 表按 ID 正确路由，应答不串。 +func TestProcess_ConcurrentCallsRouteCorrectly(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + const n = 50 + var wg sync.WaitGroup + errs := make(chan error, n) + for i := 0; i < n; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + want := fmt.Sprintf("msg-%d", i) + raw, err := p.Call(MethodToolInvoke, ToolInvokeParams{ + Name: "echo_tool", + Args: map[string]interface{}{"text": want}, + }) + if err != nil { + errs <- err + return + } + var res ToolInvokeResult + if err := json.Unmarshal(raw, &res); err != nil { + errs <- err + return + } + if res.Result != want { + errs <- fmt.Errorf("应答串了：期望 %q，实际 %v", want, res.Result) + } + }(i) + } + wg.Wait() + close(errs) + for err := range errs { + t.Errorf("并发调用失败: %v", err) + } +} + +// 协议版本不匹配必须显式拒绝，不能半兼容运行。 +func TestProcess_ProtocolMismatchRejected(t *testing.T) { + bin := buildTestPlugin(t, "badprotoplugin.go") + _, err := Spawn("badproto", bin, Options{Handler: noopHandler}) + if err == nil { + t.Fatal("协议版本不匹配应拒绝建链") + } + if !strings.Contains(err.Error(), "协议版本不匹配") { + t.Errorf("错误应说明版本不匹配，实际: %v", err) + } +} + +func TestProcess_SpawnRequiresHandler(t *testing.T) { + if _, err := Spawn("x", "/bin/true", Options{}); err == nil { + t.Fatal("缺少 Handler 应报错（插件无法回调内核）") + } +} diff --git a/internal/plugin/proc/protocol.go b/internal/plugin/proc/protocol.go new file mode 100644 index 0000000..74515a3 --- /dev/null +++ b/internal/plugin/proc/protocol.go @@ -0,0 +1,215 @@ +package proc + +import "encoding/json" + +// RPC 协议定义：控制面（§3.2 method id 平移为 method 名）。 +// +// 帧格式：**换行分隔的 JSON**（NDJSON），双向复用同一对 stdio 管道。 +// 内核 → 插件 stdin ：请求 / 响应 +// 插件 → 内核 stdout：请求 / 响应 +// +// 为什么不用 length-prefixed 二进制帧：工具调用结果中位数仅 93B（§2.5）， +// JSON 序列化 3-8 µs 对比 LLM 单轮 2-8 秒占 0.0001%，可读性与可调试性更值。 +// 大 payload（多媒体二进制）走共享内存 arena，不进 RPC 帧（§3.3 实验 10：18-22x）。 + +// 协议版本：与共享段版本独立演进。 +// 插件握手时上报，内核校验——不匹配显式拒绝，避免半兼容导致的诡异行为。 +const ProtocolVersion = 1 + +// Direction 无需显式字段：靠 Method 是否为空区分请求与响应 +// （与 clawhubadapter/sidecar 的成熟做法一致）。 + +// Request 是一次 RPC 调用。 +// +// ID 语义： +// - ID > 0 ：需要响应，调用方在 pending 表等待 +// - ID == 0 ：通知（fire-and-forget），被调方不得回响应 +// +// 通知用于事件投递等不关心结果的路径（§2.4 约束 B：内核发通知绝不等待消费者）。 +type Request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +// Response 是对 Request 的应答。Error 非空表示失败。 +type Response struct { + ID uint64 `json:"id"` + Result json.RawMessage `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +// ---- kernel → plugin（内核调用插件，对应今日 7 个 //export）---- +const ( + // MethodPluginInit 传插件名与配置，插件构造实例但不启动。 + MethodPluginInit = "plugin.init" + // MethodPluginStart 插件注册工具/阶段/通道（其间会反向发起大量 core.* 调用）。 + MethodPluginStart = "plugin.start" + // MethodPluginStop 优雅停止：插件侧先跑 RunStopHandlers 再 Stop()。 + MethodPluginStop = "plugin.stop" + // MethodToolInvoke 执行插件工具。 + MethodToolInvoke = "tool.invoke" + // MethodStageInvoke 执行阶段处理器。数据经共享段传递，参数只带阶段名与段世代号。 + MethodStageInvoke = "stage.invoke" + // MethodOutputInvoke 经插件输出通道发送。 + MethodOutputInvoke = "output.invoke" + // MethodHandshake 建链首帧：交换协议版本、SDK 版本、共享段规格。 + MethodHandshake = "handshake" +) + +// ---- plugin → kernel（51 个 method id 平移，§3.2）---- +// +// 编号本身扔掉：不再维护"下一个可用 id 是 52"，加能力不用改两边常量表， +// 也不再出现 47 夹在 7 和 8 之间的历史痕迹。 +const ( + // 注册面（原 case 1/2/3/4/46） + MethodToolRegister = "tool.register" // 1 CORE_REGISTER_TOOL + MethodStageRegister = "stage.register" // 2 CORE_REGISTER_STAGE + MethodOutputRegister = "output.register" // 3 CORE_REGISTER_OUTPUT_CH + MethodAPIRegister = "api.register" // 4 CORE_REGISTER_PLUGIN_API + MethodInputRegister = "input.register" // 46 CORE_REGISTER_INPUT_CH + + // IO 注入（原 case 5/6/7/47） + MethodIOInjectText = "io.injectText" // 5 CORE_INJECT_TEXT + MethodIOInjectInterrupt = "io.injectInterrupt" // 6 CORE_INJECT_INTERRUPT_TEXT + MethodIOInjectTextNoMem = "io.injectTextNoMem" // 7 CORE_INJECT_TEXT_NO_MEMORY + MethodIOInjectSync = "io.injectInputSync" // 47 CORE_INJECT_INPUT_SYNC + // MethodIOSetToolBlocks 多模态注入——今日 C ABI 侧是空实现（§1.4）， + // 子进程下二进制落 arena、描述符回传，首次真正可用。 + MethodIOSetToolBlocks = "io.setToolBlocks" + + // 生命周期（原 case 8） + MethodLifecycleAutoRestart = "lifecycle.autoRestart" // 8 CORE_SET_AUTO_RESTART + + // 图记忆（原 case 9/10/11/12/13） + MethodMemoryRecall = "memory.recall" // 9 + MethodMemoryCommit = "memory.commit" // 10 + MethodMemoryIntrospect = "memory.introspect" // 11 + MethodMemoryMerge = "memory.merge" // 12 + MethodMemoryPurge = "memory.purge" // 13 + + // 文档记忆（原 case 14/32/33/34） + MethodDocQuery = "doc.query" // 14 + MethodDocInsert = "doc.insert" // 32 + MethodDocRemove = "doc.remove" // 33 + MethodDocStats = "doc.stats" // 34 + + // 知识库（原 case 15/35/36） + MethodKnowledgeSearch = "knowledge.search" // 15 + MethodKnowledgeAdd = "knowledge.add" // 35 + MethodKnowledgeList = "knowledge.list" // 36 + + // 文本记忆（原 case 41） + MethodTextMemoryAppend = "textmemory.append" // 41 + + // 设置（原 case 16/17/18/26/27/28/29/30/31/42/43/44/45/51） + MethodSettingsGet = "settings.get" // 16 + MethodSettingsSet = "settings.set" // 17 + MethodSettingsRegisterDef = "settings.registerDef" // 18 + MethodSettingsGetCore = "settings.getCore" // 26 + MethodSettingsSetCore = "settings.setCore" // 27 + MethodSettingsListCore = "settings.listCore" // 28 + MethodSettingsGetPlugin = "settings.getPlugin" // 29 + MethodSettingsSetPlugin = "settings.setPlugin" // 30 + MethodSettingsListPlugin = "settings.listPlugin" // 31 + MethodSettingsList = "settings.list" // 42 + MethodSettingsDefs = "settings.defs" // 43 + MethodSettingsDump = "settings.dump" // 44 + MethodSettingsPlugins = "settings.plugins" // 45 + MethodSettingsDataDir = "settings.dataDir" // 51 + + // LLM 源（原 case 19/20/37） + MethodLLMListSources = "llm.listSources" // 19 + MethodLLMSetSource = "llm.setSource" // 20 + MethodLLMCurrentSource = "llm.currentSource" // 37 + + // 社交图（只读，原 case 21/22/38/39/40） + MethodSocialGetPerson = "social.getPerson" // 21 + MethodSocialGetNetwork = "social.getNetwork" // 22 + MethodSocialGetTrait = "social.getTrait" // 38 + MethodSocialGetRelation = "social.getRelations" // 39 + MethodSocialListPersons = "social.listPersons" // 40 + + // 事件（原 case 23/24 —— 今日均为空实现「给不了」， + // 子进程下经事件环 + eventfd 首次真正可用，见 §3.6/§3.8） + MethodEventsSubscribe = "events.subscribe" // 23 + MethodEventsUnsubscribe = "events.unsubscribe" // 24 + + // 插件管理（原 case 48/49/50） + MethodPluginReloadOne = "plugin.reloadOne" // 48 + MethodPluginListLoaded = "plugin.listLoaded" // 49 + MethodPluginIsDisabled = "plugin.isDisabled" // 50 + + // 共享段锁仲裁（新增，无对应 method id —— C ABI 下不存在跨进程锁概念） + MethodStageLock = "stage.lock" + MethodStageUnlock = "stage.unlock" +) + +// 原 case 25（CORE_FREE_STRING）无对应 RPC method： +// C ABI 下需要显式释放跨边界字符串，进程模型下由各自 GC 管理，概念消失。 + +// HandshakeParams 是内核 → 插件的建链首帧：告知内核侧规格。 +type HandshakeParams struct { + Protocol int `json:"protocol"` // 内核支持的协议版本 + CoreVersion string `json:"core_version"` // 内核版本（诊断用） + PluginName string `json:"plugin_name"` // 内核分配的插件名 + // ShmVersion 让插件确认共享段布局一致；不匹配时插件应拒绝启动而非错读。 + ShmVersion uint32 `json:"shm_version"` + // ShmSize 是内核分配的共享段大小，插件据此 mmap（段本身经 fd 3 传入）。 + ShmSize int `json:"shm_size"` +} + +// HandshakeResult 是插件 → 内核的建链应答：上报自身信息。 +type HandshakeResult struct { + Protocol int `json:"protocol"` // 必须等于 ProtocolVersion + SDKVersion string `json:"sdk_version"` // 插件编译时链接的公开 SDK 版本 + PluginName string `json:"plugin_name"` + PID int `json:"pid"` +} + +// StageInvokeParams 是 stage.invoke 的参数。 +// +// **注意：不含 StageContext 数据本身**——数据在共享段，此处只带定位信息。 +// 这是共享内存数据面的意义：并发改写同一份状态，而非各持副本 +// （副本模型实测 35.8~36.8% lost update，§8.4）。 +type StageInvokeParams struct { + Stage string `json:"stage"` + // Seq 是内核写入共享段后的世代号，插件读到的 seq 应 >= 此值。 + Seq uint64 `json:"seq"` +} + +// StageInvokeResult 是插件执行 stage 后的应答。 +type StageInvokeResult struct { + // DirtyFields 是插件实际写回共享段的字段数，0 表示只读插件。 + // 内核据此判断是否需要重读共享段，也用于诊断"谁改了什么"。 + DirtyFields int `json:"dirty_fields"` + // Seq 是插件写回后的世代号。 + Seq uint64 `json:"seq"` +} + +// ToolInvokeParams / ToolInvokeResult：工具调用（原 go_invoke_tool）。 +type ToolInvokeParams struct { + Name string `json:"name"` + Args map[string]interface{} `json:"args,omitempty"` +} + +type ToolInvokeResult struct { + Result interface{} `json:"result,omitempty"` +} + +// OutputInvokeParams：输出通道发送（原 go_invoke_output）。 +// +// 与 C ABI 路径的关键差异：**可同步等待真实结果**。 +// C ABI 下因 cgo 不可嵌套，只能异步 fire-and-forget，导致 output_send +// 永远返回成功（§9.4，现网 2 次消息发不出而模型以为成功）。 +// 进程模型下 RPC 天然可等应答，该缺陷从根上消失。 +type OutputInvokeParams struct { + Channel string `json:"channel"` + Args map[string]interface{} `json:"args,omitempty"` +} + +// PluginInitParams：插件构造参数（原 case init_plugin）。 +type PluginInitParams struct { + Name string `json:"name"` + Config map[string]interface{} `json:"config,omitempty"` +} diff --git a/internal/plugin/proc/testdata/badprotoplugin.go b/internal/plugin/proc/testdata/badprotoplugin.go new file mode 100644 index 0000000..a119d8b --- /dev/null +++ b/internal/plugin/proc/testdata/badprotoplugin.go @@ -0,0 +1,52 @@ +//go:build ignore + +// badprotoplugin 上报错误的协议版本，验证内核显式拒绝而非半兼容运行。 +package main + +import ( + "bufio" + "encoding/json" + "os" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + out := bufio.NewWriter(os.Stdout) + send := func(v interface{}) { + b, _ := json.Marshal(v) + out.Write(b) + out.WriteByte('\n') + out.Flush() + } + + for in.Scan() { + var req request + if err := json.Unmarshal(in.Bytes(), &req); err != nil { + continue + } + if req.Method == "handshake" { + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 999, // 故意不匹配 + "sdk_version": "ancient", + "plugin_name": "badproto", + "pid": os.Getpid(), + }}) + continue + } + if req.ID != 0 { + send(response{ID: req.ID}) + } + } +} diff --git a/internal/plugin/proc/testdata/callbackplugin.go b/internal/plugin/proc/testdata/callbackplugin.go new file mode 100644 index 0000000..9945323 --- /dev/null +++ b/internal/plugin/proc/testdata/callbackplugin.go @@ -0,0 +1,120 @@ +//go:build ignore + +// callbackplugin 验证插件 → 内核的反向调用（51 个 core.* method 的机制）。 +package main + +import ( + "bufio" + "encoding/json" + "os" + "sync" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +var ( + out = bufio.NewWriter(os.Stdout) + writeMu sync.Mutex + nextID uint64 + pending = map[uint64]chan json.RawMessage{} + pendMu sync.Mutex +) + +func send(v interface{}) { + b, _ := json.Marshal(v) + writeMu.Lock() + out.Write(b) + out.WriteByte('\n') + out.Flush() + writeMu.Unlock() +} + +// callKernel 反向调用内核并等待应答。 +func callKernel(method string, params interface{}) json.RawMessage { + pendMu.Lock() + nextID++ + id := nextID + ch := make(chan json.RawMessage, 1) + pending[id] = ch + pendMu.Unlock() + + var raw json.RawMessage + if params != nil { + b, _ := json.Marshal(params) + raw = b + } + send(request{ID: id, Method: method, Params: raw}) + return <-ch +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + in.Buffer(make([]byte, 0, 64*1024), 1024*1024) + + for in.Scan() { + line := make([]byte, len(in.Bytes())) + copy(line, in.Bytes()) + + var probe struct { + ID uint64 `json:"id"` + Method string `json:"method"` + } + if err := json.Unmarshal(line, &probe); err != nil { + continue + } + + // 内核对我们反向调用的应答 + if probe.Method == "" { + var resp struct { + ID uint64 `json:"id"` + Result json.RawMessage `json:"result"` + } + json.Unmarshal(line, &resp) + pendMu.Lock() + ch, ok := pending[resp.ID] + delete(pending, resp.ID) + pendMu.Unlock() + if ok { + ch <- resp.Result + } + continue + } + + var req request + json.Unmarshal(line, &req) + switch req.Method { + case "handshake": + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, + "sdk_version": "test", + "plugin_name": "cb", + "pid": os.Getpid(), + }}) + case "plugin.start": + // 在独立 goroutine 里回调，避免阻塞读循环 + go func(id uint64) { + callKernel("tool.register", map[string]interface{}{"name": "cb_tool"}) + callKernel("settings.get", map[string]interface{}{"key": "some_key"}) + send(response{ID: id}) + }(req.ID) + case "plugin.stop": + send(response{ID: req.ID}) + out.Flush() + os.Exit(0) + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} diff --git a/internal/plugin/proc/testdata/crashplugin.go b/internal/plugin/proc/testdata/crashplugin.go new file mode 100644 index 0000000..0bd87f9 --- /dev/null +++ b/internal/plugin/proc/testdata/crashplugin.go @@ -0,0 +1,54 @@ +//go:build ignore + +// crashplugin 在收到 boom 工具调用时 panic，用于验证崩溃隔离： +// 子进程死亡不应带崩 homed，且内核须能感知退出（供 recordCrash 使用）。 +package main + +import ( + "bufio" + "encoding/json" + "os" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + out := bufio.NewWriter(os.Stdout) + send := func(v interface{}) { + b, _ := json.Marshal(v) + out.Write(b) + out.WriteByte('\n') + out.Flush() + } + + for in.Scan() { + var req request + if err := json.Unmarshal(in.Bytes(), &req); err != nil { + continue + } + switch req.Method { + case "handshake": + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", "plugin_name": "crash", "pid": os.Getpid(), + }}) + case "tool.invoke": + // 模拟插件 bug：直接 panic，进程带非零码退出 + panic("插件内部 panic：用于验证崩溃隔离") + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} diff --git a/internal/plugin/proc/testdata/echoplugin.go b/internal/plugin/proc/testdata/echoplugin.go new file mode 100644 index 0000000..1437a03 --- /dev/null +++ b/internal/plugin/proc/testdata/echoplugin.go @@ -0,0 +1,76 @@ +//go:build ignore + +// echoplugin 是测试用的最简子进程插件：实现握手 + 回显工具。 +// 不 import 公开 SDK——只验证 proc 包的 RPC 机制本身。 +package main + +import ( + "bufio" + "encoding/json" + "fmt" + "os" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + in.Buffer(make([]byte, 0, 64*1024), 1024*1024) + out := bufio.NewWriter(os.Stdout) + + send := func(v interface{}) { + b, _ := json.Marshal(v) + out.Write(b) + out.WriteByte('\n') + out.Flush() + } + + for in.Scan() { + var req request + if err := json.Unmarshal(in.Bytes(), &req); err != nil { + continue + } + switch req.Method { + case "handshake": + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, + "sdk_version": "test", + "plugin_name": "echo", + "pid": os.Getpid(), + }}) + case "plugin.stop": + send(response{ID: req.ID}) + out.Flush() + os.Exit(0) + case "tool.invoke": + var p struct { + Name string `json:"name"` + Args map[string]interface{} `json:"args"` + } + json.Unmarshal(req.Params, &p) + switch p.Name { + case "fail_tool": + send(response{ID: req.ID, Error: "故意失败：用于验证错误上报"}) + default: + text, _ := p.Args["text"].(string) + send(response{ID: req.ID, Result: map[string]interface{}{"result": text}}) + } + case "event.deliver": + // 通知：不回应答 + default: + if req.ID != 0 { + send(response{ID: req.ID, Error: fmt.Sprintf("未实现 %s", req.Method)}) + } + } + } +} diff --git a/internal/plugin/proc/testdata/hangplugin.go b/internal/plugin/proc/testdata/hangplugin.go new file mode 100644 index 0000000..f98c9d5 --- /dev/null +++ b/internal/plugin/proc/testdata/hangplugin.go @@ -0,0 +1,56 @@ +//go:build ignore + +// hangplugin 收到工具调用后永久阻塞，用于验证： +// 1. 调用方能凭 context 超时返回（不被拖死） +// 2. Kill 能真正回收资源（对比 cgo 超时后 OS 线程永久泄漏，§9.3） +package main + +import ( + "bufio" + "encoding/json" + "os" + "time" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + out := bufio.NewWriter(os.Stdout) + send := func(v interface{}) { + b, _ := json.Marshal(v) + out.Write(b) + out.WriteByte('\n') + out.Flush() + } + + for in.Scan() { + var req request + if err := json.Unmarshal(in.Bytes(), &req); err != nil { + continue + } + switch req.Method { + case "handshake": + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", "plugin_name": "hang", "pid": os.Getpid(), + }}) + case "tool.invoke": + // 永久卡住，永不回应答 + time.Sleep(10 * time.Minute) + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} From 82dcc861733238c2ac6d55f51d25c1a0fd33cbca Mon Sep 17 00:00:00 2001 From: dev Date: Wed, 2 Sep 2026 11:34:33 +0800 Subject: [PATCH 12/27] =?UTF-8?q?feat(proc):=20Plugin=20=E5=8A=A0=E8=BD=BD?= =?UTF-8?q?=E5=99=A8=20+=2051=20method=20handler=20+=20RunStage=20?= =?UTF-8?q?=E6=8E=A5=E5=85=B1=E4=BA=AB=E6=AE=B5=EF=BC=88Part=202=20?= =?UTF-8?q?=E5=AE=8C=E6=88=90=20/=20Part=204=20=E9=97=AD=E7=8E=AF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/ 为空 --- internal/plugin/proc/corehandler.go | 697 ++++++++++++++++++ internal/plugin/proc/host.go | 215 ++++++ internal/plugin/proc/plugin.go | 229 ++++++ internal/plugin/proc/plugin_test.go | 393 ++++++++++ internal/plugin/proc/stage.go | 111 +++ internal/plugin/proc/testdata/appendplugin.go | 232 ++++++ .../plugin/proc/testdata/readonlyplugin.go | 178 +++++ internal/plugin/proc/testdata/stageplugin.go | 311 ++++++++ 8 files changed, 2366 insertions(+) create mode 100644 internal/plugin/proc/corehandler.go create mode 100644 internal/plugin/proc/host.go create mode 100644 internal/plugin/proc/plugin.go create mode 100644 internal/plugin/proc/plugin_test.go create mode 100644 internal/plugin/proc/stage.go create mode 100644 internal/plugin/proc/testdata/appendplugin.go create mode 100644 internal/plugin/proc/testdata/readonlyplugin.go create mode 100644 internal/plugin/proc/testdata/stageplugin.go diff --git a/internal/plugin/proc/corehandler.go b/internal/plugin/proc/corehandler.go new file mode 100644 index 0000000..d930b93 --- /dev/null +++ b/internal/plugin/proc/corehandler.go @@ -0,0 +1,697 @@ +package proc + +import ( + "context" + "encoding/json" + "fmt" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// coreHandler 把插件发来的 RPC 调用路由到内核 PluginSDK。 +// +// 这是 cabi/loader.go 那 51 个 case 体的**整块平移**（§3.2）： +// 参数解析、调用、错误处理逻辑不变，只把「整数 method id + 三个 C 字符串槽」 +// 换成「method 名 + 结构化 JSON 参数」。语义不变，回归风险最小。 +// +// 平移带来的直接改善： +// - 参数不再挤进 s1/s2/s3 + i1/i2 五个固定槽（C ABI 的形状约束） +// - 不需要 CORE_FREE_STRING：跨进程各自 GC +// - 错误可携带结构化信息，不只是一个字符串 +type coreHandler struct { + // sdk 是内核为该插件构建的 PluginSDK（与内置插件同一类型）。 + sdk CoreSDK + // name 是插件名，用于工具归属推断与日志。 + name string + + // host 持有被全部插件共享的 StageContext 段与锁仲裁（§3.3/§3.7）。 + // ❗ 必须是"全部插件共享一个 Host"——每插件一段会退化成副本模型。 + host *Host + + // locks 是 host.locks 的引用，供 stage.lock/unlock 路由。 + locks *lockRegistry + + // invokeTool/invokeStageFn/invokeOutput 反向调用插件（内核 → 插件）。 + // 由 Plugin 注入，注册回调时用它们构造 handler。 + invokeTool func(name string, args map[string]interface{}) (interface{}, error) + invokeStageFn func(ctx context.Context, stage string, seq uint64) error + invokeOutput func(channel string, args map[string]interface{}) (interface{}, error) +} + +// invokeStageWithCtx 反向调用插件执行 stage。 +func (h *coreHandler) invokeStageWithCtx(ctx context.Context, stage string, seq uint64) error { + if h.invokeStageFn == nil { + return fmt.Errorf("插件 %s: stage 调用通道未就绪", h.name) + } + return h.invokeStageFn(ctx, stage, seq) +} + +// CoreSDK 是 coreHandler 依赖的内核能力面。 +// +// 定义为接口而非直接依赖 internal/sdk.PluginSDK，原因： +// 1. 避免 internal/plugin/proc → internal/sdk 的强耦合（后者已依赖 internal/plugin 的类型） +// 2. 单测可注入假实现，无需构造完整内核 +// +// 方法集**刻意只包含外部插件应得的能力**——`Selftest`/`Supervisor`/`Tracker`/ +// `Status`/`Adapter`/`Config`/`Tool`/`Indexer`/`OutputChan`/`Publish` 不在此列。 +// 这正是把权限梯度从「C ABI 表达能力的意外产物」变成「显式声明并强制的策略」（§3.8）。 +type CoreSDK interface { + PluginName() string + + Settings() pubsdk.SettingsAPI + Memory() pubsdk.MemoryAPI + TextMemory() pubsdk.TextMemoryAPI + DocMemory() pubsdk.DocMemoryAPI + Knowledge() pubsdk.KnowledgeAPI + LLM() pubsdk.LLMAPI + Social() pubsdk.SocialAPI + PluginMgr() pubsdk.PluginMgrAPI + + RegisterTool(name string, def pubsdk.ToolDef, handler pubsdk.ToolHandler) error + RegisterStage(stage pubsdk.Stage, handler pubsdk.StageHandler, scope ...pubsdk.StageScope) + RegisterPluginAPI(name string) error + RegisterOutputChannel(name string, caps int, desc string, def pubsdk.ChannelDef, handler pubsdk.ToolHandler) error + RegisterInputChannel(name string, def pubsdk.ChannelDef) error + + InjectText(source, channel, text string) + InjectInterruptText(source, channel, text string) + InjectTextNoMemory(source, channel, text string) + InjectInputSync(source, channel, text string) string + + SetAutoRestart(enabled bool) +} + +// Handle 分派一次插件 → 内核的调用。 +func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}, error) { + switch method { + + // ---- 注册面（原 case 1/2/3/4/46）---- + case MethodToolRegister: + return h.toolRegister(params) + case MethodStageRegister: + return h.stageRegister(params) + case MethodOutputRegister: + return h.outputRegister(params) + case MethodAPIRegister: + var p struct { + Name string `json:"name"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, h.sdk.RegisterPluginAPI(p.Name) + case MethodInputRegister: + var p struct { + Name string `json:"name"` + Def pubsdk.ChannelDef `json:"def"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + // 注意 ChannelDef.Cleaner 是函数，无法跨进程传递（§3.5 回调型资源）。 + // NoMemory 可传；Cleaner 若插件需要，须在插件侧对文本预处理后再注入。 + return nil, h.sdk.RegisterInputChannel(p.Name, pubsdk.ChannelDef{NoMemory: p.Def.NoMemory}) + + // ---- IO 注入（原 case 5/6/7/47）---- + case MethodIOInjectText: + var p injectParams + if err := unmarshal(params, &p); err != nil { + return nil, err + } + h.sdk.InjectText(p.Source, p.Channel, p.Text) + return nil, nil + case MethodIOInjectInterrupt: + var p injectParams + if err := unmarshal(params, &p); err != nil { + return nil, err + } + h.sdk.InjectInterruptText(p.Source, p.Channel, p.Text) + return nil, nil + case MethodIOInjectTextNoMem: + var p injectParams + if err := unmarshal(params, &p); err != nil { + return nil, err + } + h.sdk.InjectTextNoMemory(p.Source, p.Channel, p.Text) + return nil, nil + case MethodIOInjectSync: + var p injectParams + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return map[string]interface{}{"reply": h.sdk.InjectInputSync(p.Source, p.Channel, p.Text)}, nil + + // ---- 生命周期（原 case 8）---- + case MethodLifecycleAutoRestart: + var p struct { + Enabled bool `json:"enabled"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + h.sdk.SetAutoRestart(p.Enabled) + return nil, nil + + // ---- 图记忆（原 case 9/10/11/12/13）---- + case MethodMemoryRecall: + mem := h.sdk.Memory() + if mem == nil { + return nil, errUnavailable("memory") + } + var p struct { + Query []string `json:"query"` + Depth int `json:"depth"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + entities, relations, err := mem.Recall(p.Query, p.Depth) + if err != nil { + return nil, err + } + if entities == nil { + entities = []pubsdk.Entity{} + } + if relations == nil { + relations = []pubsdk.Relation{} + } + return map[string]interface{}{"entities": entities, "relations": relations}, nil + + case MethodMemoryCommit: + mem := h.sdk.Memory() + if mem == nil { + return nil, errUnavailable("memory") + } + var p struct { + Triples []pubsdk.Triple `json:"triples"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, mem.Commit(p.Triples) + + case MethodMemoryIntrospect: + mem := h.sdk.Memory() + if mem == nil { + return nil, errUnavailable("memory") + } + return mem.Introspect() + + case MethodMemoryMerge: + mem := h.sdk.Memory() + if mem == nil { + return nil, errUnavailable("memory") + } + var p struct { + Source string `json:"source"` + Target string `json:"target"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + n, err := mem.MergeEntities(p.Source, p.Target) + if err != nil { + return nil, err + } + return map[string]interface{}{"merged": n}, nil + + case MethodMemoryPurge: + mem := h.sdk.Memory() + if mem == nil { + return nil, errUnavailable("memory") + } + var p struct { + Criteria map[string]string `json:"criteria"` + Mode string `json:"mode"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + if p.Mode == "" { + p.Mode = "soft" + } + n, err := mem.Purge(p.Criteria, p.Mode) + if err != nil { + return nil, err + } + return map[string]interface{}{"purged": n}, nil + + // ---- 文档记忆（原 case 14/32/33/34）---- + case MethodDocQuery: + dm := h.sdk.DocMemory() + if dm == nil { + return nil, errUnavailable("doc memory") + } + var p struct { + Text string `json:"text"` + TopK int `json:"top_k"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + docs := dm.Query(p.Text, p.TopK) + if docs == nil { + docs = []*pubsdk.Doc{} + } + return map[string]interface{}{"docs": docs}, nil + + case MethodDocInsert: + dm := h.sdk.DocMemory() + if dm == nil { + return nil, errUnavailable("doc memory") + } + var p struct { + Doc *pubsdk.Doc `json:"doc"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + if p.Doc == nil { + return nil, fmt.Errorf("doc.insert: 缺少 doc 字段") + } + return nil, dm.Insert(p.Doc) + + case MethodDocRemove: + dm := h.sdk.DocMemory() + if dm == nil { + return nil, errUnavailable("doc memory") + } + var p struct { + ID string `json:"id"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + dm.Remove(p.ID) + return nil, nil + + case MethodDocStats: + dm := h.sdk.DocMemory() + if dm == nil { + return nil, errUnavailable("doc memory") + } + return dm.Stats(), nil + + // ---- 知识库（原 case 15/35/36）---- + case MethodKnowledgeSearch: + kn := h.sdk.Knowledge() + if kn == nil { + return nil, errUnavailable("knowledge") + } + var p struct { + Query string `json:"query"` + TopK int `json:"top_k"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + results, err := kn.Search(p.Query, p.TopK) + if err != nil { + return nil, err + } + if results == nil { + results = []*pubsdk.Knowledge{} + } + return map[string]interface{}{"results": results}, nil + + case MethodKnowledgeAdd: + kn := h.sdk.Knowledge() + if kn == nil { + return nil, errUnavailable("knowledge") + } + var p struct { + Name string `json:"name"` + Content string `json:"content"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, kn.Add(p.Name, p.Content) + + case MethodKnowledgeList: + kn := h.sdk.Knowledge() + if kn == nil { + return nil, errUnavailable("knowledge") + } + names, err := kn.List() + if err != nil { + return nil, err + } + if names == nil { + names = []string{} + } + return map[string]interface{}{"names": names}, nil + + // ---- 文本记忆（原 case 41）---- + case MethodTextMemoryAppend: + tm := h.sdk.TextMemory() + if tm == nil { + return nil, errUnavailable("text memory") + } + var p struct { + Event pubsdk.TextEvent `json:"event"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, tm.Append(p.Event) + + // ---- 设置（原 case 16/17/18/26~31/42~45/51）---- + case MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef, + MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore, + MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin, + MethodSettingsList, MethodSettingsDefs, MethodSettingsDump, + MethodSettingsPlugins, MethodSettingsDataDir: + return h.settings(method, params) + + // ---- LLM 源（原 case 19/20/37）---- + case MethodLLMListSources: + llm := h.sdk.LLM() + if llm == nil { + return nil, errUnavailable("llm") + } + sources := llm.ListSources() + if sources == nil { + sources = []string{} + } + return map[string]interface{}{"sources": sources}, nil + case MethodLLMSetSource: + llm := h.sdk.LLM() + if llm == nil { + return nil, errUnavailable("llm") + } + var p struct { + Name string `json:"name"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, llm.SetSource(p.Name) + case MethodLLMCurrentSource: + llm := h.sdk.LLM() + if llm == nil { + return nil, errUnavailable("llm") + } + return map[string]interface{}{"source": llm.CurrentSource()}, nil + + // ---- 社交图（只读，原 case 21/22/38/39/40）---- + case MethodSocialGetPerson, MethodSocialGetNetwork, MethodSocialGetTrait, + MethodSocialGetRelation, MethodSocialListPersons: + return h.social(method, params) + + // ---- 插件管理（原 case 48/49/50）---- + case MethodPluginReloadOne: + pm := h.sdk.PluginMgr() + if pm == nil { + return nil, errUnavailable("plugin manager") + } + var p struct { + Name string `json:"name"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return nil, pm.ReloadOne(p.Name) + case MethodPluginListLoaded: + pm := h.sdk.PluginMgr() + if pm == nil { + return nil, errUnavailable("plugin manager") + } + list := pm.ListLoadedPlugins() + if list == nil { + list = []string{} + } + return map[string]interface{}{"plugins": list}, nil + case MethodPluginIsDisabled: + pm := h.sdk.PluginMgr() + if pm == nil { + return nil, errUnavailable("plugin manager") + } + var p struct { + Name string `json:"name"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + return map[string]interface{}{"disabled": pm.IsPluginDisabled(p.Name)}, nil + + // ---- 共享段锁仲裁（新增，§3.7）---- + case MethodStageLock: + if h.locks == nil { + return nil, fmt.Errorf("stage.lock: 锁仲裁未就绪") + } + return nil, h.locks.acquire(h.name) + case MethodStageUnlock: + if h.locks == nil { + return nil, fmt.Errorf("stage.unlock: 锁仲裁未就绪") + } + return nil, h.locks.release(h.name) + + // ---- 事件订阅（原 case 23/24，今日空实现）---- + case MethodEventsSubscribe, MethodEventsUnsubscribe: + // Part 5 通知面（事件环 + eventfd）落地后接线。 + // 今日 C ABI 侧是空实现（"给不了"而非"不给"，§1.3）； + // 明确返回未实现，比静默成功后收不到事件更容易排查。 + return nil, fmt.Errorf("%s: 事件订阅待 Part 5 通知面落地（事件环 + eventfd）", method) + + // ---- 多模态注入（C ABI 侧空实现）---- + case MethodIOSetToolBlocks: + // Part 4 扩展：二进制落 arena、Slice 描述符回传（§3.8）。 + return nil, fmt.Errorf("%s: 多模态注入待共享段二进制通道落地", method) + } + + return nil, fmt.Errorf("未知 method: %s", method) +} + +type injectParams struct { + Source string `json:"source"` + Channel string `json:"channel"` + Text string `json:"text"` +} + +func unmarshal(params json.RawMessage, out interface{}) error { + if len(params) == 0 { + return nil + } + if err := json.Unmarshal(params, out); err != nil { + return fmt.Errorf("参数解析失败: %w", err) + } + return nil +} + +func errUnavailable(what string) error { + return fmt.Errorf("%s 能力在当前内核实例中不可用", what) +} + +// toolRegister 注册插件工具，handler 反向调用插件执行（原 case 1）。 +func (h *coreHandler) toolRegister(params json.RawMessage) (interface{}, error) { + var p struct { + Name string `json:"name"` + Def pubsdk.ToolDef `json:"def"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + if p.Name == "" { + return nil, fmt.Errorf("tool.register: 缺少 name") + } + p.Def.Plugin = h.name + // ToolDef.Cleaner 是函数，跨进程无法传递（§3.5）——与 C ABI 路径行为一致。 + p.Def.Cleaner = nil + + name := p.Name + return nil, h.sdk.RegisterTool(name, p.Def, func(args map[string]interface{}) (interface{}, error) { + return h.invokeTool(name, args) + }) +} + +// stageRegister 注册阶段处理器（原 case 2）。 +// +// **与 C ABI 路径的本质差异**：这里不做「快照 → 副本 → 写回」。 +// StageContext 的数据在共享段，插件直接在同一份状态上读改写， +// 由锁仲裁串行化——消除了副本模型的 lost update（§8.4 实测 35.8~36.8%）。 +func (h *coreHandler) stageRegister(params json.RawMessage) (interface{}, error) { + var p struct { + Stage string `json:"stage"` + Scope string `json:"scope"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + if p.Stage == "" { + return nil, fmt.Errorf("stage.register: 缺少 stage") + } + + scope := pubsdk.StageScopeGlobal + if p.Scope == "own_tools" { + scope = pubsdk.StageScopeOwnTools + } + stage := p.Stage + h.sdk.RegisterStage(pubsdk.Stage(stage), func(sc *pubsdk.StageContext) error { + return h.runStage(stage, sc) + }, scope) + return nil, nil +} + +// outputRegister 注册输出通道（原 case 3）。 +// +// **与 C ABI 路径的本质差异**：可同步等真实结果。 +// C ABI 下因 cgo 不可嵌套，只能异步 fire-and-forget，导致 output_send +// 永远返回成功（§9.4，现网 2 次消息发不出而模型以为成功）。 +func (h *coreHandler) outputRegister(params json.RawMessage) (interface{}, error) { + var p struct { + Name string `json:"name"` + Caps int `json:"caps"` + Desc string `json:"desc"` + Def pubsdk.ChannelDef `json:"def"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + if p.Name == "" { + return nil, fmt.Errorf("output.register: 缺少 name") + } + channel := p.Name + return nil, h.sdk.RegisterOutputChannel(channel, p.Caps, p.Desc, + pubsdk.ChannelDef{NoMemory: p.Def.NoMemory}, + func(args map[string]interface{}) (interface{}, error) { + return h.invokeOutput(channel, args) + }) +} + +func (h *coreHandler) settings(method string, params json.RawMessage) (interface{}, error) { + sett := h.sdk.Settings() + if sett == nil { + return nil, errUnavailable("settings") + } + var p struct { + Key string `json:"key"` + Value interface{} `json:"value"` + Prefix string `json:"prefix"` + Plugin string `json:"plugin"` + Def pubsdk.ConfigDef `json:"def"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + + switch method { + case MethodSettingsGet: + v, err := sett.Get(p.Key) + if err != nil { + return nil, err + } + return map[string]interface{}{"value": v}, nil + case MethodSettingsSet: + return nil, sett.Set(p.Key, p.Value) + case MethodSettingsRegisterDef: + sett.RegisterDef(p.Def) + return nil, nil + case MethodSettingsGetCore: + v, err := sett.GetCore(p.Key) + if err != nil { + return nil, err + } + return map[string]interface{}{"value": v}, nil + case MethodSettingsSetCore: + return nil, sett.SetCore(p.Key, p.Value) + case MethodSettingsListCore: + keys, err := sett.ListCore(p.Prefix) + if err != nil { + return nil, err + } + return map[string]interface{}{"keys": orEmpty(keys)}, nil + case MethodSettingsGetPlugin: + v, err := sett.GetPlugin(p.Plugin, p.Key) + if err != nil { + return nil, err + } + return map[string]interface{}{"value": v}, nil + case MethodSettingsSetPlugin: + return nil, sett.SetPlugin(p.Plugin, p.Key, p.Value) + case MethodSettingsListPlugin: + keys, err := sett.ListPlugin(p.Plugin, p.Prefix) + if err != nil { + return nil, err + } + return map[string]interface{}{"keys": orEmpty(keys)}, nil + case MethodSettingsList: + keys, err := sett.List(p.Prefix) + if err != nil { + return nil, err + } + return map[string]interface{}{"keys": orEmpty(keys)}, nil + case MethodSettingsDefs: + defs := sett.Defs(p.Prefix) + if defs == nil { + defs = []*pubsdk.ConfigDef{} + } + return map[string]interface{}{"defs": defs}, nil + case MethodSettingsDump: + return sett.Dump(), nil + case MethodSettingsPlugins: + return map[string]interface{}{"plugins": orEmpty(sett.Plugins())}, nil + case MethodSettingsDataDir: + return map[string]interface{}{"dir": sett.DataDir()}, nil + } + return nil, fmt.Errorf("未知 settings method: %s", method) +} + +func (h *coreHandler) social(method string, params json.RawMessage) (interface{}, error) { + social := h.sdk.Social() + if social == nil { + return nil, errUnavailable("social") + } + var p struct { + Name string `json:"name"` + Trait string `json:"trait"` + Depth int `json:"depth"` + } + if err := unmarshal(params, &p); err != nil { + return nil, err + } + + switch method { + case MethodSocialGetPerson: + profile, err := social.GetPerson(p.Name) + if err != nil { + return nil, err + } + return map[string]interface{}{"person": profile}, nil + case MethodSocialGetNetwork: + profiles, err := social.GetNetwork(p.Name, p.Depth) + if err != nil { + return nil, err + } + if profiles == nil { + profiles = []*pubsdk.PersonProfile{} + } + return map[string]interface{}{"network": profiles}, nil + case MethodSocialGetTrait: + v, ok := social.GetTrait(p.Name, p.Trait) + return map[string]interface{}{"value": v, "found": ok}, nil + case MethodSocialGetRelation: + rels, err := social.GetRelations(p.Name) + if err != nil { + return nil, err + } + if rels == nil { + rels = []pubsdk.SocialRelation{} + } + return map[string]interface{}{"relations": rels}, nil + case MethodSocialListPersons: + names, err := social.ListPersons() + if err != nil { + return nil, err + } + return map[string]interface{}{"persons": orEmpty(names)}, nil + } + return nil, fmt.Errorf("未知 social method: %s", method) +} + +func orEmpty(s []string) []string { + if s == nil { + return []string{} + } + return s +} diff --git a/internal/plugin/proc/host.go b/internal/plugin/proc/host.go new file mode 100644 index 0000000..d76feb5 --- /dev/null +++ b/internal/plugin/proc/host.go @@ -0,0 +1,215 @@ +package proc + +import ( + "fmt" + "log" + "os" + "sync" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" + "golang.org/x/sys/unix" +) + +// Host 持有**被全部子进程插件共享的一块 StageContext 段**，是共享内存数据面的 +// 所有权中心（§3.3/§3.4）。 +// +// ❗ 为什么必须共享一块段（这是一个容易走错的关键点）： +// 若每个插件各持一块段，则「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成 +// 副本模型——两个插件各写各的段、各自回读，最后回读者覆盖前者， +// lost update 原样复现（§8.4 实测 35.8~36.8%）。 +// 实验 8 的做法是 5 个 worker 进程 mmap **同一个 memfd**，本实现与之一致。 +// +// 生命周期：Host 由 registry 创建一次，随内核存活；每个插件 spawn 时经 +// ExtraFiles 拿到同一 memfd（fd 3），mmap 后即看到同一份物理页。 +type Host struct { + memfd *os.File + data []byte + seg *Segment + shmSize int + + // locks 被全部插件的 coreHandler 共享——同阶段并发扇出的插件在此排队， + // 语义等价于内置插件共享 *StageContext 的 sync.RWMutex（§0.2 第 1 条）。 + locks *lockRegistry + + // stageMu 串行化「整次 stage 执行」对共享段的独占。 + // + // 必要性：内核可能在不同路径并发触发 RunStage（如 emitResponse 的 + // before_output 与主循环的其他阶段）。段只有一份，两次 stage 交叠会互相污染。 + // 由首个进入的插件加锁、最后离开的插件解锁；RunStage 的 wg.Wait() 保证 + // 每个 handler 的 defer 必然执行，故 inflight 必然归零，不会死锁。 + stageMu sync.Mutex + + coordMu sync.Mutex + coord *stageCoordinator +} + +// NewHost 创建共享段（memfd + mmap + 布局初始化）。 +// +// 用 memfd 而非 /dev/shm 文件：无需文件名、不残留（进程退出即回收）、 +// 可经 ExtraFiles 传给子进程。实验 2 已验证父子 mmap 到不同虚拟地址时 +// 相对偏移仍正确解引用。 +func NewHost() (*Host, error) { + fd, err := unix.MemfdCreate("hastagectx", unix.MFD_CLOEXEC) + if err != nil { + return nil, fmt.Errorf("proc: 创建共享段 memfd: %w", err) + } + if err := unix.Ftruncate(fd, int64(shmDefaultSize)); err != nil { + unix.Close(fd) + return nil, fmt.Errorf("proc: 共享段 ftruncate: %w", err) + } + data, err := unix.Mmap(fd, 0, shmDefaultSize, + unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { + unix.Close(fd) + return nil, fmt.Errorf("proc: 共享段 mmap: %w", err) + } + seg, err := NewSegment(data) + if err != nil { + unix.Munmap(data) + unix.Close(fd) + return nil, err + } + + return &Host{ + memfd: os.NewFile(uintptr(fd), "hastagectx"), + data: data, + seg: seg, + shmSize: shmDefaultSize, + locks: &lockRegistry{}, + }, nil +} + +// shmDefaultSize 是共享 StageContext 段的大小。 +// +// 取 256KB：StageContext 全字段 JSON 化后典型 < 4KB（工具结果中位 93B，§2.5）， +// append-only 中间垃圾由 stage 结束时 Compact 回收，256KB 给足余量。 +// 全部插件共享一块，总开销恒定，不随插件数增长。 +const shmDefaultSize = 256 * 1024 + +// Close 释放共享段。 +func (h *Host) Close() error { + if h.data != nil { + unix.Munmap(h.data) + h.data = nil + } + if h.memfd != nil { + err := h.memfd.Close() + h.memfd = nil + return err + } + return nil +} + +// beginStage 由插件 handler 进入时调用。 +// +// 首个进入者：获取 stageMu（独占共享段）→ 把内核 StageContext 写入段。 +// 后续进入者：仅递增 inflight。 +func (h *Host) beginStage(sc *pubsdk.StageContext) (*stageCoordinator, error) { + h.coordMu.Lock() + first := h.coord == nil + if first { + // 独占共享段直到本次 stage 全部插件离开 + h.coordMu.Unlock() + h.stageMu.Lock() + h.coordMu.Lock() + // 双检：等锁期间可能已有其他插件建好协调器（它们会先拿到 stageMu） + if h.coord != nil { + first = false + h.stageMu.Unlock() + } else { + h.coord = newStageCoordinator(h.seg) + } + } + coord := h.coord + h.coordMu.Unlock() + + if err := coord.enter(sc, first); err != nil { + if first { + h.coordMu.Lock() + h.coord = nil + h.coordMu.Unlock() + h.stageMu.Unlock() + } + return nil, err + } + h.locks.bind(coord.lock) + return coord, nil +} + +// endStage 由插件 handler 返回时调用。 +// 最后离开者：把共享段结果读回内核 StageContext → 压实 arena → 释放 stageMu。 +func (h *Host) endStage(coord *stageCoordinator) error { + last, err := coord.leave() + if !last { + return err + } + h.coordMu.Lock() + h.coord = nil + h.coordMu.Unlock() + h.stageMu.Unlock() + return err +} + +// ForceReleaseLock 在插件进程崩溃时释放其可能持有的 stage 锁（实验 9 自愈机制）。 +func (h *Host) ForceReleaseLock(plugin string) bool { + return h.locks.forceRelease(plugin) +} + +// Segment 暴露共享段（供诊断与测试）。 +func (h *Host) Segment() *Segment { return h.seg } + +// stageCoordinator 跟踪一次 stage 执行中参与插件的进出。 +type stageCoordinator struct { + seg *Segment + lock *stageLock + + mu sync.Mutex + inflight int + written bool + ctxRef *pubsdk.StageContext +} + +func newStageCoordinator(seg *Segment) *stageCoordinator { + return &stageCoordinator{seg: seg, lock: newStageLock()} +} + +// enter 登记一个插件进入本次 stage；first 为真时把内核状态写入共享段。 +func (c *stageCoordinator) enter(sc *pubsdk.StageContext, first bool) error { + c.mu.Lock() + defer c.mu.Unlock() + c.inflight++ + if !first || c.written { + return nil + } + c.ctxRef = sc + if err := c.seg.WriteAll(sc); err != nil { + c.inflight-- + return fmt.Errorf("写入共享段: %w", err) + } + c.written = true + return nil +} + +// leave 登记一个插件离开；返回是否为最后一个离开者。 +// +// 最后离开者负责把共享段结果读回内核 StageContext，并压实 arena +// （此时无插件持锁，满足 §3.3 的压实前提）。 +func (c *stageCoordinator) leave() (last bool, err error) { + c.mu.Lock() + c.inflight-- + last = c.inflight == 0 + sc := c.ctxRef + written := c.written + c.mu.Unlock() + + if !last || !written || sc == nil { + return last, nil + } + if rErr := c.seg.ReadInto(sc); rErr != nil { + return last, fmt.Errorf("回读共享段: %w", rErr) + } + if reclaimed := c.seg.Compact(); reclaimed > 0 { + log.Printf("[proc] stage 结束，arena 压实回收 %d 字节", reclaimed) + } + return last, nil +} diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go new file mode 100644 index 0000000..0f33b0e --- /dev/null +++ b/internal/plugin/proc/plugin.go @@ -0,0 +1,229 @@ +package proc + +import ( + "context" + "encoding/json" + "fmt" + "log" + "os" + "sync" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// Plugin 是 registry 可加载的子进程插件，与内置插件同构的启停接口。 +// +// 生命周期： +// +// New() 创建（尚未 spawn） +// Start(core) spawn 子进程 → 握手（传共享段 fd）→ plugin.init → plugin.start +// （plugin.start 期间插件反向注册工具/阶段/通道） +// Stop() plugin.stop → 宽限期 → 必要时 Kill +// Close() 强制结束（registry 卸载/重载路径） +// +// **共享段不属于 Plugin**：它属于 Host，被全部子进程插件共享。 +// 若每插件一段，「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下会退化成 +// 副本模型，lost update 原样复现（§8.4）。 +type Plugin struct { + name string + bin string + dir string + config map[string]interface{} + + host *Host + proc *Process + handler *coreHandler + + // env 追加到子进程环境变量（测试用；生产由 registry 按需设置）。 + env []string + + // onCrash 由 registry 注入，把进程退出喂给 plugin_health.recordCrash（§2.3）。 + onCrash func(name string, err error) + + stopOnce sync.Once +} + +// New 创建子进程插件（不启动进程）。 +// +// host 必须是全部子进程插件共用的实例（由 registry 创建一次）。 +func New(name, bin, dir string, config map[string]interface{}, host *Host, onCrash func(string, error)) *Plugin { + return &Plugin{ + name: name, + bin: bin, + dir: dir, + config: config, + host: host, + onCrash: onCrash, + } +} + +// Name 实现 sdk.Plugin。 +func (p *Plugin) Name() string { return p.name } + +// Start 启动子进程并完成注册。 +// +// core 是内核为该插件构建的能力面（internal/sdk.PluginSDK 天然满足 CoreSDK）。 +func (p *Plugin) Start(core CoreSDK) error { + if p.host == nil { + return fmt.Errorf("proc: %s 缺少共享段 Host", p.name) + } + + p.handler = &coreHandler{ + sdk: core, + name: p.name, + host: p.host, + locks: p.host.locks, + } + // 反向调用闭包：注册回调时捕获，运行期经 RPC 打到插件进程。 + p.handler.invokeTool = p.invokeTool + p.handler.invokeStageFn = p.invokeStage + p.handler.invokeOutput = p.invokeOutput + + proc, err := Spawn(p.name, p.bin, Options{ + Dir: p.dir, + Env: p.env, + // 子进程 fd 3 = 共享段 memfd（全部插件同一个，故看到同一份物理页） + ExtraFiles: []*os.File{p.host.memfd}, + ShmSize: p.host.shmSize, + Handler: p.handler.Handle, + OnExit: p.handleExit, + }) + if err != nil { + return err + } + p.proc = proc + + // plugin.init：构造插件实例 + if _, err := proc.Call(MethodPluginInit, PluginInitParams{ + Name: p.name, + Config: p.config, + }); err != nil { + proc.Kill() + return fmt.Errorf("proc: %s plugin.init 失败: %w", p.name, err) + } + + // plugin.start：插件在此期间反向注册工具/阶段/通道 + if _, err := proc.Call(MethodPluginStart, nil); err != nil { + proc.Kill() + return fmt.Errorf("proc: %s plugin.start 失败: %w", p.name, err) + } + return nil +} + +// Stop 优雅停止（实现 sdk.Plugin）。 +func (p *Plugin) Stop() error { + var err error + p.stopOnce.Do(func() { + if p.proc != nil { + err = p.proc.Stop() + } + }) + return err +} + +// Close 强制结束子进程。 +// +// **这里是真 kill + wait**——对比 cabi 路径的 Close 只做 dlclose， +// 而 dlclose 对 Go c-shared 是 no-op（§1.1，热重载静默失效的根因）。 +func (p *Plugin) Close() error { + var err error + p.stopOnce.Do(func() { + if p.proc != nil { + err = p.proc.Kill() + } + }) + return err +} + +// handleExit 在子进程退出时把信号喂给 plugin_health（§2.3 逻辑复用）， +// 并释放该插件可能持有的 stage 锁。 +// +// 后者是"锁仲裁回内核"的自愈价值：持锁者死亡不会导致全局死锁， +// 无需 robust pthread_mutex（实验 9）。 +func (p *Plugin) handleExit(name string, err error) { + if p.host != nil && p.host.ForceReleaseLock(name) { + log.Printf("[proc] %s 退出，内核已释放其持有的 stage 锁", name) + } + if err != nil && p.onCrash != nil { + p.onCrash(name, err) + } +} + +// ---- 内核 → 插件的反向调用 ---- + +func (p *Plugin) invokeTool(name string, args map[string]interface{}) (interface{}, error) { + if p.proc == nil { + return nil, ErrProcessExited + } + raw, err := p.proc.Call(MethodToolInvoke, ToolInvokeParams{Name: name, Args: args}) + if err != nil { + return nil, err + } + var res ToolInvokeResult + if err := json.Unmarshal(raw, &res); err != nil { + return nil, fmt.Errorf("proc: %s 工具 %s 应答解析失败: %w", p.name, name, err) + } + return res.Result, nil +} + +func (p *Plugin) invokeStage(ctx context.Context, stage string, seq uint64) error { + if p.proc == nil { + return ErrProcessExited + } + raw, err := p.proc.CallContext(ctx, MethodStageInvoke, StageInvokeParams{ + Stage: stage, + Seq: seq, + }) + if err != nil { + return err + } + var res StageInvokeResult + if len(raw) > 0 { + if err := json.Unmarshal(raw, &res); err != nil { + return fmt.Errorf("proc: %s stage %s 应答解析失败: %w", p.name, stage, err) + } + } + if res.DirtyFields > 0 { + log.Printf("[proc] %s stage %s 改写了 %d 个字段", p.name, stage, res.DirtyFields) + } + return nil +} + +// invokeOutput 经插件输出通道发送，**同步等待真实结果**。 +// +// 这是 §9.4 的根治：C ABI 下 cgo 不可嵌套，只能异步 fire-and-forget， +// 导致 output_send 永远返回 {status:queued} + err=nil，模型永远以为发送成功 +// （现网 7 天内 2 次消息实际发不出）。进程模型下 RPC 天然可等应答。 +func (p *Plugin) invokeOutput(channel string, args map[string]interface{}) (interface{}, error) { + if p.proc == nil { + return nil, ErrProcessExited + } + raw, err := p.proc.Call(MethodOutputInvoke, OutputInvokeParams{ + Channel: channel, + Args: args, + }) + if err != nil { + return nil, err // 真实失败上报，模型可感知并重试 + } + if len(raw) == 0 { + return map[string]interface{}{"status": "sent"}, nil + } + var res map[string]interface{} + if err := json.Unmarshal(raw, &res); err != nil { + return map[string]interface{}{"status": "sent"}, nil + } + if _, ok := res["status"]; !ok { + res["status"] = "sent" + } + return res, nil +} + +// 编译期确认 Plugin 具备 registry 需要的启停形状。 +var _ interface { + Name() string + Stop() error + Close() error +} = (*Plugin)(nil) + +// 引用一下公开 SDK，确保本文件的类型假设与它同版本。 +var _ = pubsdk.StageScopeGlobal diff --git a/internal/plugin/proc/plugin_test.go b/internal/plugin/proc/plugin_test.go new file mode 100644 index 0000000..4df85d6 --- /dev/null +++ b/internal/plugin/proc/plugin_test.go @@ -0,0 +1,393 @@ +package proc + +import ( + "encoding/json" + "fmt" + "strings" + "sync" + "testing" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 端到端验证：内核 RunStage 并发扇出 → 真实子进程插件经共享内存读改写 → 结果回读。 +// +// 这是**整个迁移最关键的一环闭环验证**（§4.4 风险 3.4）： +// 机制在 shm_test.go 已被单元验证，这里验证它在真进程 + 真 RPC 下同样成立。 + +// fakeCoreSDK 是最简 CoreSDK 实现，记录注册行为。 +type fakeCoreSDK struct { + mu sync.Mutex + tools map[string]pubsdk.ToolHandler + stages map[pubsdk.Stage][]pubsdk.StageHandler + outputs map[string]pubsdk.ToolHandler + settings map[string]interface{} + autoStart bool +} + +func newFakeCore() *fakeCoreSDK { + return &fakeCoreSDK{ + tools: map[string]pubsdk.ToolHandler{}, + stages: map[pubsdk.Stage][]pubsdk.StageHandler{}, + outputs: map[string]pubsdk.ToolHandler{}, + settings: map[string]interface{}{}, + } +} + +func (f *fakeCoreSDK) PluginName() string { return "fake" } +func (f *fakeCoreSDK) Settings() pubsdk.SettingsAPI { return nil } +func (f *fakeCoreSDK) Memory() pubsdk.MemoryAPI { return nil } +func (f *fakeCoreSDK) TextMemory() pubsdk.TextMemoryAPI { return nil } +func (f *fakeCoreSDK) DocMemory() pubsdk.DocMemoryAPI { return nil } +func (f *fakeCoreSDK) Knowledge() pubsdk.KnowledgeAPI { return nil } +func (f *fakeCoreSDK) LLM() pubsdk.LLMAPI { return nil } +func (f *fakeCoreSDK) Social() pubsdk.SocialAPI { return nil } +func (f *fakeCoreSDK) PluginMgr() pubsdk.PluginMgrAPI { return nil } +func (f *fakeCoreSDK) RegisterPluginAPI(name string) error { return nil } +func (f *fakeCoreSDK) InjectText(s, c, t string) {} +func (f *fakeCoreSDK) InjectInterruptText(s, c, t string) {} +func (f *fakeCoreSDK) InjectTextNoMemory(s, c, t string) {} +func (f *fakeCoreSDK) InjectInputSync(s, c, t string) string { return "" } +func (f *fakeCoreSDK) SetAutoRestart(enabled bool) { f.autoStart = enabled } + +func (f *fakeCoreSDK) RegisterTool(name string, def pubsdk.ToolDef, h pubsdk.ToolHandler) error { + f.mu.Lock() + defer f.mu.Unlock() + f.tools[name] = h + return nil +} + +func (f *fakeCoreSDK) RegisterStage(stage pubsdk.Stage, h pubsdk.StageHandler, scope ...pubsdk.StageScope) { + f.mu.Lock() + defer f.mu.Unlock() + f.stages[stage] = append(f.stages[stage], h) +} + +func (f *fakeCoreSDK) RegisterOutputChannel(name string, caps int, desc string, def pubsdk.ChannelDef, h pubsdk.ToolHandler) error { + f.mu.Lock() + defer f.mu.Unlock() + f.outputs[name] = h + return nil +} + +func (f *fakeCoreSDK) RegisterInputChannel(name string, def pubsdk.ChannelDef) error { return nil } + +func (f *fakeCoreSDK) stageHandlers(stage pubsdk.Stage) []pubsdk.StageHandler { + f.mu.Lock() + defer f.mu.Unlock() + out := make([]pubsdk.StageHandler, len(f.stages[stage])) + copy(out, f.stages[stage]) + return out +} + +// runStageLikeKernel 复刻 internal/agent/core.StageHost.RunStage 的并发扇出语义 +// （stages.go:124 的 go func + wg.Wait），验证外部插件在同样的并发模型下正确工作。 +func runStageLikeKernel(handlers []pubsdk.StageHandler, sc *pubsdk.StageContext) []error { + var wg sync.WaitGroup + errCh := make(chan error, len(handlers)) + for _, h := range handlers { + wg.Add(1) + go func(fn pubsdk.StageHandler) { + defer wg.Done() + if err := fn(sc); err != nil { + errCh <- err + } + }(h) + } + wg.Wait() + close(errCh) + var errs []error + for err := range errCh { + errs = append(errs, err) + } + return errs +} + +// 单插件 stage 读改写：验证共享段 + RPC + 锁的完整链路。 +func TestPlugin_StageReadModifyWriteOverSharedMemory(t *testing.T) { + bin := buildTestPlugin(t, "stageplugin.go") + core := newFakeCore() + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + p := New("sanitizer", bin, t.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + t.Fatalf("Start: %v", err) + } + defer p.Close() + + handlers := core.stageHandlers(pubsdk.StageAfterToolcall) + if len(handlers) != 1 { + t.Fatalf("插件应注册 1 个 after_toolcall handler，实际 %d", len(handlers)) + } + + dirty := "结果：\x1b[31m脏数据\x1b[0m" + clean := "结果：脏数据" + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "x_tool", Result: dirty}}, + } + + if errs := runStageLikeKernel(handlers, sc); len(errs) > 0 { + t.Fatalf("stage 执行失败: %v", errs) + } + + got, _ := sc.ToolResults[0].Result.(string) + if got != clean { + t.Fatalf("插件的清洗结果未回到内核 StageContext：期望 %q，实际 %q", clean, got) + } +} + +// **核心断言**：改写型插件 + 只读插件并发时，清洗结果不被覆盖。 +// 复刻现网 sanitizer + weather 场景（§8.6 实测 C ABI 下 1.6~4.3% 被覆盖）。 +func TestPlugin_ConcurrentWriterAndReaderNoLostUpdate(t *testing.T) { + bin := buildTestPlugin(t, "stageplugin.go") + + // ❗ 两个插件进程**共享同一个 Host**（同一 memfd）——这是消除 lost update 的前提。 + // 若各持一段，「内核 ctx → 段 → 插件改 → 回读 ctx」会退化成副本模型， + // 最后回读者覆盖前者，§8.4 的 35.8~36.8% 丢失原样复现。 + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + writerCore := newFakeCore() + writer := New("sanitizer", bin, t.TempDir(), nil, host, nil) + if err := writer.Start(writerCore); err != nil { + t.Fatalf("writer Start: %v", err) + } + defer writer.Close() + + readerBin := buildTestPlugin(t, "readonlyplugin.go") + readerCore := newFakeCore() + reader := New("weather", readerBin, t.TempDir(), nil, host, nil) + if err := reader.Start(readerCore); err != nil { + t.Fatalf("reader Start: %v", err) + } + defer reader.Close() + + handlers := append( + writerCore.stageHandlers(pubsdk.StageAfterToolcall), + readerCore.stageHandlers(pubsdk.StageAfterToolcall)..., + ) + if len(handlers) != 2 { + t.Fatalf("应有 2 个 handler，实际 %d", len(handlers)) + } + + dirty := "天气：晴 \x1b[31m28°C\x1b[0m" + clean := "天气：晴 28°C" + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "weather_query", Result: dirty}}, + } + + if errs := runStageLikeKernel(handlers, sc); len(errs) > 0 { + t.Fatalf("stage 执行失败: %v", errs) + } + + got, _ := sc.ToolResults[0].Result.(string) + if got != clean { + t.Fatalf("只读插件覆盖了改写插件的清洗结果：期望 %q，实际 %q", clean, got) + } +} + +// 插件注册的工具可被内核调用，并把结果带回。 +func TestPlugin_RegisteredToolInvokable(t *testing.T) { + bin := buildTestPlugin(t, "stageplugin.go") + core := newFakeCore() + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + p := New("demo", bin, t.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + t.Fatalf("Start: %v", err) + } + defer p.Close() + + core.mu.Lock() + h, ok := core.tools["demo_upper"] + core.mu.Unlock() + if !ok { + t.Fatal("插件应注册 demo_upper 工具") + } + + res, err := h(map[string]interface{}{"text": "abc"}) + if err != nil { + t.Fatalf("调用工具: %v", err) + } + if res != "ABC" { + t.Fatalf("工具结果应为 ABC，实际 %v", res) + } +} + +// 输出通道**同步等真实结果**：失败必须上报（§9.4 根治）。 +func TestPlugin_OutputChannelReportsRealFailure(t *testing.T) { + bin := buildTestPlugin(t, "stageplugin.go") + core := newFakeCore() + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + p := New("demo", bin, t.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + t.Fatalf("Start: %v", err) + } + defer p.Close() + + core.mu.Lock() + h, ok := core.outputs["demo_ch"] + core.mu.Unlock() + if !ok { + t.Fatal("插件应注册 demo_ch 输出通道") + } + + // 成功路径 + res, err := h(map[string]interface{}{"payload": "hi", "type": "text"}) + if err != nil { + t.Fatalf("发送应成功: %v", err) + } + m, _ := res.(map[string]interface{}) + if m["status"] != "sent" { + t.Errorf("成功应返回 status=sent，实际 %v", m) + } + + // 失败路径：插件返回错误 → 调用方必须收到 error（而非假成功） + _, err = h(map[string]interface{}{"payload": "fail", "type": "text"}) + if err == nil { + t.Fatal("发送失败时必须上报 error（C ABI 路径此处永远假成功）") + } + if !strings.Contains(err.Error(), "缺少 user_id") { + t.Errorf("应透传插件的失败原因，实际: %v", err) + } +} + +// 插件在 plugin.start 期间反向调用内核（settings/autoRestart 等）。 +func TestPlugin_ReverseCallsDuringStart(t *testing.T) { + bin := buildTestPlugin(t, "stageplugin.go") + core := newFakeCore() + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + p := New("demo", bin, t.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + t.Fatalf("Start: %v", err) + } + defer p.Close() + + if !core.autoStart { + t.Error("插件调用 lifecycle.autoRestart 后内核状态应更新") + } +} + +// 权限梯度显式化（§3.8）：CoreSDK 不提供内核内部机制， +// 插件请求这些能力时必须被拒绝而非静默忽略。 +func TestCoreHandler_RejectsUnknownAndUnimplementedMethods(t *testing.T) { + h := &coreHandler{sdk: newFakeCore(), name: "x", locks: &lockRegistry{}} + + // 未知 method + if _, err := h.Handle("supervisor.restart", nil); err == nil { + t.Error("内核内部机制不应可达（应报未知 method）") + } + + // 事件订阅：今日 C ABI 是空实现（静默成功），这里必须明确报未实现 + if _, err := h.Handle(MethodEventsSubscribe, json.RawMessage(`{}`)); err == nil { + t.Error("事件订阅未落地时应明确报错，而非静默成功后收不到事件") + } + + // 多模态注入同理 + if _, err := h.Handle(MethodIOSetToolBlocks, json.RawMessage(`{}`)); err == nil { + t.Error("多模态注入未落地时应明确报错") + } +} + +// stage 锁在无进行中 stage 时申请应被拒绝（防止插件在 stage 外乱加锁）。 +func TestCoreHandler_StageLockOutsideStageRejected(t *testing.T) { + h := &coreHandler{sdk: newFakeCore(), name: "x", locks: &lockRegistry{}} + if _, err := h.Handle(MethodStageLock, nil); err == nil { + t.Error("stage 外加锁应被拒绝") + } + if !strings.Contains(fmt.Sprint(mustErr(h.Handle(MethodStageUnlock, nil))), "无进行中的 stage") { + t.Error("stage 外解锁的错误信息应说明原因") + } +} + +func mustErr(_ interface{}, err error) error { return err } + +// **跨进程 lost update 终极验证**：5 个独立插件进程并发读-改-写同一个 +// FinalText，全部标记必须保留。 +// +// 这是实验 8（5 进程 × 300 轮零丢失）在真实 RPC + 真实 RunStage 并发扇出 +// 下的复刻。对照今日 C ABI 副本模型实测 35.8~36.8% 丢失（§8.4）。 +func TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate(t *testing.T) { + bin := buildTestPlugin(t, "appendplugin.go") + + // 关键：全部插件共享同一个 Host（同一 memfd） + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + tags := []string{"A", "B", "C", "D", "E"} + var handlers []pubsdk.StageHandler + for _, tag := range tags { + core := newFakeCore() + p := New("append-"+tag, bin, t.TempDir(), nil, host, nil) + p.env = []string{"PLUGIN_TAG=" + tag} + if err := p.Start(core); err != nil { + t.Fatalf("插件 %s Start: %v", tag, err) + } + defer p.Close() + handlers = append(handlers, core.stageHandlers(pubsdk.StageAfterToolcall)...) + } + if len(handlers) != len(tags) { + t.Fatalf("应有 %d 个 handler，实际 %d", len(tags), len(handlers)) + } + + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + FinalText: "", + } + + if errs := runStageLikeKernel(handlers, sc); len(errs) > 0 { + t.Fatalf("并发 stage 执行失败: %v", errs) + } + + // 断言：各标记出现次数之和 == 最终长度 == 插件数 ⇒ 无丢失、无撕裂 + total := 0 + counts := map[string]int{} + for _, tag := range tags { + c := strings.Count(sc.FinalText, tag) + counts[tag] = c + total += c + } + if total != len(sc.FinalText) { + t.Fatalf("出现撕裂：各标记计数之和 %d != 最终长度 %d（final=%q counts=%v）", + total, len(sc.FinalText), sc.FinalText, counts) + } + if total != len(tags) { + t.Fatalf("出现 lost update：期望 %d 个插件的写入全部保留，实际 %d（final=%q counts=%v）", + len(tags), total, sc.FinalText, counts) + } + for tag, c := range counts { + if c != 1 { + t.Errorf("插件 %s 的写入丢失：期望 1 次，实际 %d 次", tag, c) + } + } +} diff --git a/internal/plugin/proc/stage.go b/internal/plugin/proc/stage.go new file mode 100644 index 0000000..ae7a702 --- /dev/null +++ b/internal/plugin/proc/stage.go @@ -0,0 +1,111 @@ +package proc + +import ( + "context" + "fmt" + "log" + "sync" + "time" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// stage 执行：把内核的 RunStage 并发扇出接到共享段（§3.4，风险 3.4 的落点）。 +// +// 执行链路： +// +// 内核 RunStage（并发 go func，原始设计不变） +// └─ 外部插件 handler = coreHandler.runStage() +// ├─ Host.beginStage：首个到达者独占共享段并写入 StageContext +// ├─ stage.invoke RPC → 插件进程 +// │ └─ 插件侧：stage.lock → 读共享段 → handler → 只写脏字段 → stage.unlock +// └─ Host.endStage：最后离开者把共享段读回内核 StageContext + 压实 arena +// +// 关键性质： +// - **并发扇出保留**（§0.2 第 1 条：并发扇出是原始设计，不是缺陷） +// - **无副本**：全部插件 mmap 同一 memfd，在同一份状态上读改写，锁仲裁串行化临界区 +// - **只读插件零写入**：脏字段集为空 → 不可能覆盖他人改写 +// +// 对照今日 C ABI：每个插件拿到独立 JSON 副本，回传时无条件覆盖 10 个字段， +// 实测 35.8~36.8% lost update（§8.4），现网量级百分之几脏数据进 LLM（§8.6）。 + +// lockRegistry 持有当前进行中 stage 的锁，供插件的 stage.lock/unlock 路由。 +type lockRegistry struct { + mu sync.Mutex + lock *stageLock +} + +func (r *lockRegistry) bind(l *stageLock) { + r.mu.Lock() + r.lock = l + r.mu.Unlock() +} + +func (r *lockRegistry) current() *stageLock { + r.mu.Lock() + defer r.mu.Unlock() + return r.lock +} + +func (r *lockRegistry) acquire(plugin string) error { + l := r.current() + if l == nil { + return fmt.Errorf("stage.lock: 当前无进行中的 stage（插件 %s 在 stage 外加锁？）", plugin) + } + return l.Acquire(plugin) +} + +func (r *lockRegistry) release(plugin string) error { + l := r.current() + if l == nil { + return fmt.Errorf("stage.unlock: 当前无进行中的 stage（插件 %s）", plugin) + } + return l.Release(plugin) +} + +// forceRelease 在插件进程崩溃时释放其可能持有的锁（实验 9 的自愈机制）。 +func (r *lockRegistry) forceRelease(plugin string) bool { + l := r.current() + if l == nil { + return false + } + return l.ForceRelease(plugin) +} + +// stageInvokeTimeout 是单个插件执行 stage 的上限。 +// +// 取 30s：与内核工具超时（60s，toolcall.go）留出差距， +// 使 stage 超时能被识别为 stage 问题而非工具问题。 +// 超时后调用方返回错误，卡住的插件进程可由上层 Kill 回收—— +// **对比 cgo 路径超时后 OS 线程永久泄漏（现网 26 次，§9.3）**。 +const stageInvokeTimeout = 30 * time.Second + +// runStage 是注册到内核 StageHost 的 handler（每个外部插件一个）。 +func (h *coreHandler) runStage(stage string, sc *pubsdk.StageContext) error { + if h.host == nil { + return fmt.Errorf("插件 %s: stage %s 共享段未就绪", h.name, stage) + } + + coord, err := h.host.beginStage(sc) + if err != nil { + return fmt.Errorf("插件 %s stage %s: %w", h.name, stage, err) + } + defer func() { + if endErr := h.host.endStage(coord); endErr != nil { + log.Printf("[proc] %s stage %s 收尾失败: %v", h.name, stage, endErr) + } + }() + + ctx, cancel := context.WithTimeout(context.Background(), stageInvokeTimeout) + defer cancel() + + if err := h.invokeStageWithCtx(ctx, stage, coord.seg.Seq()); err != nil { + // 插件可能在持锁时失败（崩溃/超时）——强制释放，避免后续插件死锁。 + // 这正是"锁仲裁回内核"的自愈价值（实验 9）：无需 robust mutex。 + if h.host.ForceReleaseLock(h.name) { + log.Printf("[proc] %s stage %s 失败后强制释放其持有的 stage 锁", h.name, stage) + } + return err + } + return nil +} diff --git a/internal/plugin/proc/testdata/appendplugin.go b/internal/plugin/proc/testdata/appendplugin.go new file mode 100644 index 0000000..ba37df4 --- /dev/null +++ b/internal/plugin/proc/testdata/appendplugin.go @@ -0,0 +1,232 @@ +//go:build ignore + +// appendplugin 在 stage 中把自己的标记追加到 FinalText（读-改-写）。 +// +// 用于跨进程 lost update 验证：多个此类插件并发处理同一 stage， +// 若全部标记都保留 ⇒ 无丢失；若少了 ⇒ 出现 lost update。 +// +// 这是实验 8（5 进程 × 300 轮零丢失）在真实 RPC + 真实内核 RunStage +// 下的复刻——机制单测已过，这里验证集成后同样成立。 +package main + +import ( + "bufio" + "encoding/binary" + "encoding/json" + "fmt" + "os" + "sync" + "syscall" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +var ( + out = bufio.NewWriter(os.Stdout) + writeMu sync.Mutex + + nextID uint64 + pendMu sync.Mutex + pending = map[uint64]chan json.RawMessage{} + + shm []byte + tag string +) + +func send(v interface{}) { + b, _ := json.Marshal(v) + writeMu.Lock() + out.Write(b) + out.WriteByte('\n') + out.Flush() + writeMu.Unlock() +} + +func callKernel(method string, params interface{}) (json.RawMessage, bool) { + pendMu.Lock() + nextID++ + id := nextID + ch := make(chan json.RawMessage, 1) + pending[id] = ch + pendMu.Unlock() + + var raw json.RawMessage + if params != nil { + b, _ := json.Marshal(params) + raw = b + } + send(request{ID: id, Method: method, Params: raw}) + r, ok := <-ch + return r, ok +} + +const ( + headerSize = 64 + stageFieldCount = 18 + sliceSize = 8 + flagCount = 8 + + offArenaBase = 8 + offArenaCap = 12 + offArenaUsed = 16 + offCtxBase = 20 + offSeq = 24 + + fFinalText = 5 // 与 proc/shmcodec.go 的 stageField 枚举顺序一致 +) + +func desc(field int) (uint32, uint32) { + cb := binary.LittleEndian.Uint32(shm[offCtxBase:]) + o := cb + uint32(field*sliceSize) + return binary.LittleEndian.Uint32(shm[o:]), binary.LittleEndian.Uint32(shm[o+4:]) +} + +func setDesc(field int, off, ln uint32) { + cb := binary.LittleEndian.Uint32(shm[offCtxBase:]) + o := cb + uint32(field*sliceSize) + binary.LittleEndian.PutUint32(shm[o:], off) + binary.LittleEndian.PutUint32(shm[o+4:], ln) +} + +func readFinalText() string { + off, ln := desc(fFinalText) + if off == 0 && ln == 0 { + return "" + } + if ln == 0 { + return "" + } + base := binary.LittleEndian.Uint32(shm[offArenaBase:]) + return string(shm[base+off : base+off+ln]) +} + +func writeFinalText(s string) error { + used := binary.LittleEndian.Uint32(shm[offArenaUsed:]) + if used == 0 { + used = 1 + } + cap_ := binary.LittleEndian.Uint32(shm[offArenaCap:]) + if used+uint32(len(s)) > cap_ { + return fmt.Errorf("arena 空间不足") + } + base := binary.LittleEndian.Uint32(shm[offArenaBase:]) + copy(shm[base+used:], []byte(s)) + binary.LittleEndian.PutUint32(shm[offArenaUsed:], used+uint32(len(s))) + setDesc(fFinalText, used, uint32(len(s))) + // 世代号自增 + v := binary.LittleEndian.Uint64(shm[offSeq:]) + binary.LittleEndian.PutUint64(shm[offSeq:], v+1) + return nil +} + +func main() { + tag = os.Getenv("PLUGIN_TAG") + if tag == "" { + tag = "?" + } + + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + in.Buffer(make([]byte, 0, 64*1024), 1024*1024) + + for in.Scan() { + line := make([]byte, len(in.Bytes())) + copy(line, in.Bytes()) + + var probe struct { + ID uint64 `json:"id"` + Method string `json:"method"` + } + if json.Unmarshal(line, &probe) != nil { + continue + } + if probe.Method == "" { + var resp struct { + ID uint64 `json:"id"` + Result json.RawMessage `json:"result"` + } + json.Unmarshal(line, &resp) + pendMu.Lock() + ch, ok := pending[resp.ID] + delete(pending, resp.ID) + pendMu.Unlock() + if ok { + ch <- resp.Result + } + continue + } + + var req request + json.Unmarshal(line, &req) + + switch req.Method { + case "handshake": + var hp struct { + ShmSize int `json:"shm_size"` + } + json.Unmarshal(req.Params, &hp) + if hp.ShmSize > 0 { + m, err := syscall.Mmap(3, 0, hp.ShmSize, + syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED) + if err != nil { + send(response{ID: req.ID, Error: fmt.Sprintf("mmap: %v", err)}) + continue + } + shm = m + } + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", + "plugin_name": "append-" + tag, "pid": os.Getpid(), + }}) + + case "plugin.init": + send(response{ID: req.ID}) + + case "plugin.start": + go func(id uint64) { + callKernel("stage.register", map[string]interface{}{ + "stage": "after_toolcall", + "scope": "global", + }) + send(response{ID: id}) + }(req.ID) + + case "plugin.stop": + send(response{ID: req.ID}) + out.Flush() + os.Exit(0) + + case "stage.invoke": + go func(id uint64) { + if shm == nil { + send(response{ID: id, Error: "共享段未挂载"}) + return + } + // 拿锁 → 读 → 追加自己的标记 → 写回 → 放锁 + callKernel("stage.lock", nil) + cur := readFinalText() + err := writeFinalText(cur + tag) + callKernel("stage.unlock", nil) + if err != nil { + send(response{ID: id, Error: err.Error()}) + return + } + send(response{ID: id, Result: map[string]interface{}{"dirty_fields": 1}}) + }(req.ID) + + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} diff --git a/internal/plugin/proc/testdata/readonlyplugin.go b/internal/plugin/proc/testdata/readonlyplugin.go new file mode 100644 index 0000000..74a3fe8 --- /dev/null +++ b/internal/plugin/proc/testdata/readonlyplugin.go @@ -0,0 +1,178 @@ +//go:build ignore + +// readonlyplugin 是只读 stage 插件（模拟 weather 的 AfterToolcall）： +// 读取共享段但不写回任何字段。 +// +// **这是 lost update 修复的关键验证对象**：C ABI 副本模型下， +// 它会把自己收到的旧快照无条件回传，覆盖 sanitizer 的清洗结果 +// （§8.6 实测现网 1.6~4.3% 被覆盖）。共享内存模型下它零写入。 +package main + +import ( + "bufio" + "encoding/binary" + "encoding/json" + "fmt" + "os" + "sync" + "syscall" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +var ( + out = bufio.NewWriter(os.Stdout) + writeMu sync.Mutex + + nextID uint64 + pendMu sync.Mutex + pending = map[uint64]chan json.RawMessage{} + + shm []byte +) + +func send(v interface{}) { + b, _ := json.Marshal(v) + writeMu.Lock() + out.Write(b) + out.WriteByte('\n') + out.Flush() + writeMu.Unlock() +} + +func callKernel(method string, params interface{}) json.RawMessage { + pendMu.Lock() + nextID++ + id := nextID + ch := make(chan json.RawMessage, 1) + pending[id] = ch + pendMu.Unlock() + + var raw json.RawMessage + if params != nil { + b, _ := json.Marshal(params) + raw = b + } + send(request{ID: id, Method: method, Params: raw}) + return <-ch +} + +const ( + offArenaBase = 8 + offCtxBase = 20 + sliceSize = 8 + fToolResults = 10 +) + +func readToolResults() []byte { + base := binary.LittleEndian.Uint32(shm[offArenaBase:]) + cb := binary.LittleEndian.Uint32(shm[offCtxBase:]) + o := cb + uint32(fToolResults*sliceSize) + off := binary.LittleEndian.Uint32(shm[o:]) + ln := binary.LittleEndian.Uint32(shm[o+4:]) + if off == 0 && ln == 0 { + return nil + } + return shm[base+off : base+off+ln] +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + in.Buffer(make([]byte, 0, 64*1024), 1024*1024) + + for in.Scan() { + line := make([]byte, len(in.Bytes())) + copy(line, in.Bytes()) + + var probe struct { + ID uint64 `json:"id"` + Method string `json:"method"` + } + if json.Unmarshal(line, &probe) != nil { + continue + } + if probe.Method == "" { + var resp struct { + ID uint64 `json:"id"` + Result json.RawMessage `json:"result"` + } + json.Unmarshal(line, &resp) + pendMu.Lock() + ch, ok := pending[resp.ID] + delete(pending, resp.ID) + pendMu.Unlock() + if ok { + ch <- resp.Result + } + continue + } + + var req request + json.Unmarshal(line, &req) + + switch req.Method { + case "handshake": + var hp struct { + ShmSize int `json:"shm_size"` + } + json.Unmarshal(req.Params, &hp) + if hp.ShmSize > 0 { + m, err := syscall.Mmap(3, 0, hp.ShmSize, + syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED) + if err != nil { + send(response{ID: req.ID, Error: fmt.Sprintf("mmap: %v", err)}) + continue + } + shm = m + } + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", "plugin_name": "readonly", "pid": os.Getpid(), + }}) + + case "plugin.init": + send(response{ID: req.ID}) + + case "plugin.start": + go func(id uint64) { + callKernel("stage.register", map[string]interface{}{ + "stage": "after_toolcall", + "scope": "global", + }) + send(response{ID: id}) + }(req.ID) + + case "plugin.stop": + send(response{ID: req.ID}) + out.Flush() + os.Exit(0) + + case "stage.invoke": + go func(id uint64) { + if shm == nil { + send(response{ID: id, Error: "共享段未挂载"}) + return + } + callKernel("stage.lock", nil) + // 只读：读了但一个字节都不写回 + _ = readToolResults() + callKernel("stage.unlock", nil) + send(response{ID: id, Result: map[string]interface{}{"dirty_fields": 0}}) + }(req.ID) + + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} diff --git a/internal/plugin/proc/testdata/stageplugin.go b/internal/plugin/proc/testdata/stageplugin.go new file mode 100644 index 0000000..91baf3c --- /dev/null +++ b/internal/plugin/proc/testdata/stageplugin.go @@ -0,0 +1,311 @@ +//go:build ignore + +// stageplugin 是完整形态的测试插件：注册工具/阶段/输出通道， +// stage 处理经共享内存读改写（模拟 sanitizer 的清洗行为）。 +// +// 它手写 RPC 与共享段访问，不依赖公开 SDK——因为 SDK 侧的 proc 支持 +// 属于 Part 3（plugindev 工具链）的内容。这里只验证内核侧机制。 +package main + +import ( + "bufio" + "encoding/binary" + "encoding/json" + "fmt" + "os" + "strings" + "sync" + "syscall" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +var ( + out = bufio.NewWriter(os.Stdout) + writeMu sync.Mutex + + nextID uint64 + pendMu sync.Mutex + pending = map[uint64]chan json.RawMessage{} + + shm []byte + shmSize int +) + +func send(v interface{}) { + b, _ := json.Marshal(v) + writeMu.Lock() + out.Write(b) + out.WriteByte('\n') + out.Flush() + writeMu.Unlock() +} + +func callKernel(method string, params interface{}) json.RawMessage { + pendMu.Lock() + nextID++ + id := nextID + ch := make(chan json.RawMessage, 1) + pending[id] = ch + pendMu.Unlock() + + var raw json.RawMessage + if params != nil { + b, _ := json.Marshal(params) + raw = b + } + send(request{ID: id, Method: method, Params: raw}) + return <-ch +} + +// ---- 共享段访问（与内核 proc 包的布局一致）---- + +const ( + headerSize = 64 + // 与 proc 包保持一致：18 个字段 × 8 字节 + 8 字节标志位 + stageFieldCount = 18 + sliceSize = 8 + flagCount = 8 + ctxSize = stageFieldCount*sliceSize + flagCount + + offArenaBase = 8 + offArenaCap = 12 + offArenaUsed = 16 + offCtxBase = 20 + offSeq = 24 + + // 字段索引（与 proc/shmcodec.go 的 stageField 枚举顺序一致） + fToolResults = 10 +) + +func arenaBase() uint32 { return binary.LittleEndian.Uint32(shm[offArenaBase:]) } +func arenaCap() uint32 { return binary.LittleEndian.Uint32(shm[offArenaCap:]) } +func ctxBase() uint32 { return binary.LittleEndian.Uint32(shm[offCtxBase:]) } + +func descOffset(field int) uint32 { return ctxBase() + uint32(field*sliceSize) } + +func getDesc(field int) (off, ln uint32) { + o := descOffset(field) + return binary.LittleEndian.Uint32(shm[o:]), binary.LittleEndian.Uint32(shm[o+4:]) +} + +func setDesc(field int, off, ln uint32) { + o := descOffset(field) + binary.LittleEndian.PutUint32(shm[o:], off) + binary.LittleEndian.PutUint32(shm[o+4:], ln) +} + +func readField(field int) []byte { + off, ln := getDesc(field) + if off == 0 && ln == 0 { + return nil + } + if ln == 0 { + return []byte{} + } + base := arenaBase() + return shm[base+off : base+off+ln] +} + +func writeField(field int, data []byte) error { + used := binary.LittleEndian.Uint32(shm[offArenaUsed:]) + if used == 0 { + used = 1 + } + end := used + uint32(len(data)) + if end > arenaCap() { + return fmt.Errorf("arena 空间不足") + } + base := arenaBase() + copy(shm[base+used:], data) + binary.LittleEndian.PutUint32(shm[offArenaUsed:], end) + setDesc(field, used, uint32(len(data))) + return nil +} + +func bumpSeq() { + v := binary.LittleEndian.Uint64(shm[offSeq:]) + binary.LittleEndian.PutUint64(shm[offSeq:], v+1) +} + +type toolResult struct { + CallID string `json:"call_id"` + Name string `json:"name"` + Plugin string `json:"plugin,omitempty"` + Success bool `json:"success"` + Result interface{} `json:"result"` +} + +// handleStage 模拟 sanitizer：拿锁 → 读 ToolResults → 剥 ANSI → 只写脏字段 → 放锁 +func handleStage() (int, error) { + callKernel("stage.lock", nil) + defer callKernel("stage.unlock", nil) + + raw := readField(fToolResults) + if len(raw) == 0 { + return 0, nil + } + var results []toolResult + if err := json.Unmarshal(raw, &results); err != nil { + return 0, err + } + + before := string(raw) + for i := range results { + if s, ok := results[i].Result.(string); ok { + results[i].Result = strings.NewReplacer("\x1b[31m", "", "\x1b[0m", "").Replace(s) + } + } + after, _ := json.Marshal(results) + + // 只有真变了才写回 —— 这是消除 lost update 的核心 + if string(after) == before { + return 0, nil + } + if err := writeField(fToolResults, after); err != nil { + return 0, err + } + bumpSeq() + return 1, nil +} + +func main() { + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + in.Buffer(make([]byte, 0, 64*1024), 1024*1024) + + for in.Scan() { + line := make([]byte, len(in.Bytes())) + copy(line, in.Bytes()) + + var probe struct { + ID uint64 `json:"id"` + Method string `json:"method"` + } + if json.Unmarshal(line, &probe) != nil { + continue + } + + // 内核对我们反向调用的应答 + if probe.Method == "" { + var resp struct { + ID uint64 `json:"id"` + Result json.RawMessage `json:"result"` + } + json.Unmarshal(line, &resp) + pendMu.Lock() + ch, ok := pending[resp.ID] + delete(pending, resp.ID) + pendMu.Unlock() + if ok { + ch <- resp.Result + } + continue + } + + var req request + json.Unmarshal(line, &req) + + switch req.Method { + case "handshake": + var hp struct { + ShmSize int `json:"shm_size"` + } + json.Unmarshal(req.Params, &hp) + shmSize = hp.ShmSize + if shmSize > 0 { + // fd 3 = 内核传入的共享段 memfd + m, err := syscall.Mmap(3, 0, shmSize, + syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED) + if err != nil { + send(response{ID: req.ID, Error: fmt.Sprintf("mmap 共享段失败: %v", err)}) + continue + } + shm = m + } + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", "plugin_name": "stage", "pid": os.Getpid(), + }}) + + case "plugin.init": + send(response{ID: req.ID}) + + case "plugin.start": + go func(id uint64) { + callKernel("lifecycle.autoRestart", map[string]interface{}{"enabled": true}) + callKernel("tool.register", map[string]interface{}{ + "name": "demo_upper", + "def": map[string]interface{}{"name": "demo_upper", "description": "转大写"}, + }) + callKernel("stage.register", map[string]interface{}{ + "stage": "after_toolcall", + "scope": "global", + }) + callKernel("output.register", map[string]interface{}{ + "name": "demo_ch", + "caps": 1, + "desc": "测试通道", + }) + send(response{ID: id}) + }(req.ID) + + case "plugin.stop": + send(response{ID: req.ID}) + out.Flush() + os.Exit(0) + + case "tool.invoke": + var p struct { + Name string `json:"name"` + Args map[string]interface{} `json:"args"` + } + json.Unmarshal(req.Params, &p) + text, _ := p.Args["text"].(string) + send(response{ID: req.ID, Result: map[string]interface{}{ + "result": strings.ToUpper(text), + }}) + + case "stage.invoke": + go func(id uint64) { + if shm == nil { + send(response{ID: id, Error: "共享段未挂载"}) + return + } + n, err := handleStage() + if err != nil { + send(response{ID: id, Error: err.Error()}) + return + } + send(response{ID: id, Result: map[string]interface{}{"dirty_fields": n}}) + }(req.ID) + + case "output.invoke": + var p struct { + Channel string `json:"channel"` + Args map[string]interface{} `json:"args"` + } + json.Unmarshal(req.Params, &p) + payload, _ := p.Args["payload"].(string) + if payload == "fail" { + // 模拟现网 qq 插件的真实失败：meta 缺 user_id + send(response{ID: req.ID, Error: "meta 中缺少 user_id 字段"}) + continue + } + send(response{ID: req.ID, Result: map[string]interface{}{"status": "sent"}}) + + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} From 11c1bbcebbf61e926f1db04c6f56fbc89e7f3f89 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 13:03:57 +0800 Subject: [PATCH 13/27] =?UTF-8?q?plugin:=20=E5=AD=90=E8=BF=9B=E7=A8=8B?= =?UTF-8?q?=E9=80=9A=E9=81=93=E6=8E=A5=E9=80=9A=20registry=EF=BC=88proc=20?= =?UTF-8?q?=E9=80=9A=E9=81=93=E7=AB=AF=E5=88=B0=E7=AB=AF=E5=8F=AF=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- internal/plugin/dynamic_proc_unix.go | 122 ++++++++-- internal/plugin/proc/e2e_template_test.go | 259 ++++++++++++++++++++++ internal/plugin/proc/host.go | 46 ++-- internal/plugin/proc/shmalloc_darwin.go | 50 +++++ internal/plugin/proc/shmalloc_linux.go | 43 ++++ internal/plugin/proc/shmalloc_other.go | 28 +++ internal/plugin/proc_core.go | 171 ++++++++++++++ internal/plugin/proc_load_test.go | 192 ++++++++++++++++ internal/plugin/registry.go | 20 +- 9 files changed, 881 insertions(+), 50 deletions(-) create mode 100644 internal/plugin/proc/e2e_template_test.go create mode 100644 internal/plugin/proc/shmalloc_darwin.go create mode 100644 internal/plugin/proc/shmalloc_linux.go create mode 100644 internal/plugin/proc/shmalloc_other.go create mode 100644 internal/plugin/proc_core.go create mode 100644 internal/plugin/proc_load_test.go diff --git a/internal/plugin/dynamic_proc_unix.go b/internal/plugin/dynamic_proc_unix.go index 4787c3e..bbd229a 100644 --- a/internal/plugin/dynamic_proc_unix.go +++ b/internal/plugin/dynamic_proc_unix.go @@ -4,40 +4,128 @@ package plugin import ( "fmt" + "log" "os" "path/filepath" + "time" + "gitcode.com/JianFeeeee/HomeAgent/internal/events" + "gitcode.com/JianFeeeee/HomeAgent/internal/plugin/proc" sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" ) -// tryLoadProc 加载子进程插件（plugin.bin）——外部插件多进程化的加载入口。 +// tryLoadProc 只做静态校验（供双通道探测与测试），不构造插件实体。 +// +// 真正加载走 Registry.loadProc：子进程插件需要共享段 Host， +// 而 Host 必须是**全部 .bin 插件共用的那一个**，只能由 Registry 持有。 +// +// 返回 nil,nil 表示目录中没有 plugin.bin（交由后续探测通道）； +// 找到二进制但不可用时返回明确错误——不静默回退到 cabi。 +func tryLoadProc(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { + _, err := validateProcBinary(dir, name) + return nil, err +} + +// 子进程插件加载（plugin.bin）——外部插件多进程化的加载入口。 // // 设计依据：docs/zh/架构迁移评估.md §3（stdio JSON-RPC 控制面 + shm 数据面 + eventfd 通知面） -// 实施计划：docs/zh/plugin-migration-plan.md Part 2 -// -// 当前状态：**分派桩位**。共享内存数据面与锁仲裁已在 internal/plugin/proc/ 落地 -// 并通过 16 项测试（含 -race），进程管理与 RPC 编解码为 Part 2 内容。 -// -// 返回 nil,nil 表示目录中没有 plugin.bin（交由后续探测通道）。 -// 找到二进制但通道未就绪时返回明确错误——不静默回退到 cabi， -// 否则"已迁移插件跑回旧通道"极难排查。 -func tryLoadProc(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { +// 实施计划：docs/zh/plugin-migration-plan.md Part 2/3 + +// validateProcBinary 校验 plugin.bin 是否存在且可执行。 +// 返回 ("", nil) 表示该目录不是 proc 插件。 +func validateProcBinary(dir, name string) (string, error) { binPath := filepath.Join(dir, binEntry) st, err := os.Stat(binPath) if err != nil { if os.IsNotExist(err) { - return nil, nil + return "", nil } - return nil, fmt.Errorf("proc plugin %s: 检查 %s: %w", name, binEntry, err) + return "", fmt.Errorf("proc plugin %s: 检查 %s: %w", name, binEntry, err) } if st.IsDir() { - return nil, fmt.Errorf("proc plugin %s: %s 是目录，不是可执行文件", name, binEntry) + return "", fmt.Errorf("proc plugin %s: %s 是目录，不是可执行文件", name, binEntry) } if st.Mode()&0o111 == 0 { - return nil, fmt.Errorf("proc plugin %s: %s 缺少可执行权限（chmod +x）", name, binEntry) + // 常见于经 zip/hmap 分发丢失权限位——给出可直接执行的修复指令 + return "", fmt.Errorf("proc plugin %s: %s 缺少可执行权限（chmod +x %s）", + name, binEntry, binPath) + } + return binPath, nil +} + +// loadProc 构造子进程插件实体（不 spawn）。 +// +// 共享段 Host 在此惰性创建：**全部 .bin 插件共用一块段**。 +// 若每插件一段，多插件同阶段并发时会退化成副本模型， +// lost update 原样复现（§8.4 实测 35.8~36.8%）。 +func (r *Registry) loadProc(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { + binPath, err := validateProcBinary(dir, name) + if err != nil { + return nil, err + } + if binPath == "" { + return nil, nil } - return nil, fmt.Errorf("proc plugin %s: 子进程通道尚未实现（Part 2）——"+ - "共享内存数据面已就绪（internal/plugin/proc），"+ - "如需运行请把 plugin.json 的 entry 改回 %s 走 C ABI 通道", name, soEntry) + host, err := r.ensureProcHost() + if err != nil { + return nil, fmt.Errorf("proc plugin %s: %w", name, err) + } + + return procPluginAdapter{Plugin: proc.New(name, binPath, dir, config, host, r.onProcCrash)}, nil +} + +// ensureProcHost 惰性创建共享段 Host（全进程唯一）。 +func (r *Registry) ensureProcHost() (*proc.Host, error) { + r.procHostMu.Lock() + defer r.procHostMu.Unlock() + if r.procHost != nil { + return r.procHost, nil + } + host, err := proc.NewHost() + if err != nil { + return nil, err + } + r.procHost = host + log.Printf("[plugin] 共享段已创建（全部子进程插件共用一块，%d KB）", host.ShmSize()/1024) + return host, nil +} + +// closeProcHost 释放共享段（仅在内核关停时调用）。 +func (r *Registry) closeProcHost() { + r.procHostMu.Lock() + defer r.procHostMu.Unlock() + if r.procHost == nil { + return + } + if err := r.procHost.Close(); err != nil { + log.Printf("[plugin] 关闭共享段: %v", err) + } + r.procHost = nil +} + +// onProcCrash 在子进程插件异常退出时回调。 +// +// **崩溃隔离**：子进程死亡只影响自己，homed 继续服务——对比 C ABI 下 +// 插件 panic 直接带崩整个进程（§1.2，现网已发生）。 +// +// 崩溃计数/冷却/自愈复用既有 plugin_health（§2.3），本函数只负责把 +// 进程退出这一事实转成事件通知；具体重载策略由 agent 侧决定。 +func (r *Registry) onProcCrash(name string, err error) { + log.Printf("[plugin] 子进程插件 %s 异常退出: %v（homed 未受影响）", name, err) + if r.evBus == nil { + return + } + // 不在此处直接重载：重载需要 registry 锁，而本回调可能在 + // 持锁路径的 goroutine 中触发，直接调用会死锁。 + r.evBus.Publish(&events.Event{ + Type: events.EventSystem, + Source: "plugin", + Payload: map[string]interface{}{ + "event": "plugin_crashed", + "plugin": name, + "error": err.Error(), + }, + Timestamp: time.Now().Unix(), + }) } diff --git a/internal/plugin/proc/e2e_template_test.go b/internal/plugin/proc/e2e_template_test.go new file mode 100644 index 0000000..aba143b --- /dev/null +++ b/internal/plugin/proc/e2e_template_test.go @@ -0,0 +1,259 @@ +package proc + +import ( + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 端到端：用**真实 plugindev 模板**编译的插件，经内核 proc 通道加载运行。 +// +// 与 plugin_test.go 中 testdata/*.go 假插件的区别： +// 那些是手写的最简 RPC 实现，只验证内核侧逻辑； +// 这里用的是 tools/plugindev/templates/proc_main.go.tmpl —— 外部插件作者 +// 真正会拿到的那份运行时。它验证的是「模板 ↔ 内核」两侧协议/布局真的对齐， +// 而不只是内核自己跟自己对齐。 +// +// 插件业务代码只用公开 SDK（NewPluginFactory + sdk.PluginSDK），与 .so 时代一致。 + +const e2ePluginSource = `package main + +import ( + "strings" + + sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +type e2ePlugin struct{ name string } + +func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) { + return &e2ePlugin{name: name}, nil +} + +func (p *e2ePlugin) Name() string { return p.name } + +func (p *e2ePlugin) Start(s *sdk.PluginSDK) error { + s.SetAutoRestart(true) + + s.RegisterTool("e2e_echo", sdk.ToolDef{ + Description: "回显", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "text": map[string]interface{}{"type": "string"}, + }, + }, + }, func(args map[string]interface{}) (interface{}, error) { + t, _ := args["text"].(string) + return "echo:" + t, nil + }) + + s.RegisterStage(sdk.StageAfterToolcall, func(ctx *sdk.StageContext) error { + for i := range ctx.ToolResults { + if str, ok := ctx.ToolResults[i].Result.(string); ok { + ctx.ToolResults[i].Result = strings.ReplaceAll(str, "脏", "净") + } + } + // FinalText 在 C ABI 下对 after_toolcall 不可见（§8.3：10 → 16 字段） + ctx.FinalText = ctx.FinalText + "|stage-touched" + return nil + }) + return nil +} + +func (p *e2ePlugin) Stop() error { return nil } +` + +// buildPluginWithRealTemplate 用 plugindev 的真实模板编译一个插件二进制。 +func buildPluginWithRealTemplate(t *testing.T, businessCode string) string { + t.Helper() + if _, err := exec.LookPath("go"); err != nil { + t.Skip("环境无 go 工具链，跳过端到端测试") + } + + tmpl := filepath.Join("..", "..", "..", + "third_party", "homeagent-sdk", "tools", "plugindev", + "templates", "proc_main.go.tmpl") + runtime, err := os.ReadFile(tmpl) + if err != nil { + t.Skipf("plugindev 模板不可读（SDK 仓可能未就位）: %v", err) + } + + dir := t.TempDir() + mustWriteFile(t, filepath.Join(dir, "plugin.go"), businessCode) + mustWriteFile(t, filepath.Join(dir, "z_proc_gen.go"), string(runtime)) + + sdkPath, err := filepath.Abs(filepath.Join("..", "..", "..", "third_party", "homeagent-sdk")) + if err != nil { + t.Fatalf("解析 SDK 路径: %v", err) + } + mustWriteFile(t, filepath.Join(dir, "go.mod"), + "module e2eplugin\n\ngo 1.25\n\n"+ + "require gitcode.com/JianFeeeee/homeagent-sdk v0.9.2\n\n"+ + "replace gitcode.com/JianFeeeee/homeagent-sdk => "+sdkPath+"\n") + + bin := filepath.Join(dir, "plugin.bin") + cmd := exec.Command("go", "build", "-o", bin, ".") + cmd.Dir = dir + // CGO_ENABLED=0：模板零 cgo 是迁移的核心收益，这里同时充当回归保护 + cmd.Env = append(os.Environ(), "CGO_ENABLED=0") + if out, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("用真实模板编译插件失败: %v\n%s", err, out) + } + return bin +} + +func mustWriteFile(t *testing.T, path, content string) { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatalf("写 %s: %v", path, err) + } +} + +// 完整链路：真实模板编译 → spawn → 握手 → init/start → 反向注册 → 工具调用 → stage 读改写。 +func TestE2E_RealTemplatePluginFullLifecycle(t *testing.T) { + bin := buildPluginWithRealTemplate(t, e2ePluginSource) + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + core := newFakeCore() + p := New("e2e", bin, t.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + t.Fatalf("Start: %v", err) + } + defer p.Close() + + // 1) SetAutoRestart 必须经 lifecycle.autoRestart 上报到内核。 + // 公开 SDK 的 SetAutoRestart 是纯 setter（无 hook），插件在 Start() 里 + // 调它只改自己进程内的副本；模板须在 Start 返回后显式上报一次。 + if !core.autoStart { + t.Error("插件的 SetAutoRestart(true) 未传达到内核（模板漏了 lifecycle.autoRestart 上报？）") + } + + // 2) 工具注册与调用 + core.mu.Lock() + toolHandler, hasTool := core.tools["e2e_echo"] + core.mu.Unlock() + if !hasTool { + t.Fatal("插件注册的工具未到达内核") + } + res, err := toolHandler(map[string]interface{}{"text": "你好"}) + if err != nil { + t.Fatalf("调用插件工具: %v", err) + } + if got, _ := res.(string); got != "echo:你好" { + t.Errorf("工具返回 %q，期望 echo:你好", got) + } + + // 3) stage 读改写经共享段回到内核 StageContext + handlers := core.stageHandlers(pubsdk.StageAfterToolcall) + if len(handlers) != 1 { + t.Fatalf("应注册 1 个 after_toolcall handler，实际 %d", len(handlers)) + } + + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + FinalText: "原文", + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "t", Result: "这是脏数据"}}, + } + if errs := runStageLikeKernel(handlers, sc); len(errs) > 0 { + t.Fatalf("stage 执行失败: %v", errs) + } + + got, _ := sc.ToolResults[0].Result.(string) + if got != "这是净数据" { + t.Errorf("清洗结果未回到内核 StageContext：实际 %q", got) + } + // FinalText 在 C ABI 的 after_toolcall 下根本看不到（只下发 10 字段中的一部分） + if sc.FinalText != "原文|stage-touched" { + t.Errorf("FinalText 改写未回传：实际 %q（C ABI 下此字段在本阶段不可见）", sc.FinalText) + } +} + +// 只读插件与改写插件并发时，改写结果不被覆盖。 +// +// 这是本次迁移最关键的性质，用**真实模板**再验一次： +// 字段级脏写入使只读插件的写入集为空，物理上不可能覆盖他人改写。 +// 对照 C ABI 副本模型实测 35.8~36.8% lost update（§8.4）。 +func TestE2E_RealTemplateReadOnlyPluginDoesNotOverwrite(t *testing.T) { + const readerSource = `package main + +import sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" + +type readerPlugin struct{ name string } + +func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) { + return &readerPlugin{name: name}, nil +} + +func (p *readerPlugin) Name() string { return p.name } + +func (p *readerPlugin) Start(s *sdk.PluginSDK) error { + // 只读：遍历但不改任何字段 + s.RegisterStage(sdk.StageAfterToolcall, func(ctx *sdk.StageContext) error { + for range ctx.ToolResults { + } + _ = ctx.FinalText + return nil + }) + return nil +} + +func (p *readerPlugin) Stop() error { return nil } +` + + writerBin := buildPluginWithRealTemplate(t, e2ePluginSource) + readerBin := buildPluginWithRealTemplate(t, readerSource) + + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + core := newFakeCore() + + // 两个插件共享同一 Host（= 同一 memfd）。 + // 若每插件一块段，这里就会退化成副本模型，本测试必然失败。 + writer := New("writer", writerBin, t.TempDir(), nil, host, nil) + if err := writer.Start(core); err != nil { + t.Fatalf("writer.Start: %v", err) + } + defer writer.Close() + + reader := New("reader", readerBin, t.TempDir(), nil, host, nil) + if err := reader.Start(core); err != nil { + t.Fatalf("reader.Start: %v", err) + } + defer reader.Close() + + handlers := core.stageHandlers(pubsdk.StageAfterToolcall) + if len(handlers) != 2 { + t.Fatalf("应有 2 个 after_toolcall handler，实际 %d", len(handlers)) + } + + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + FinalText: "原文", + ToolResults: []pubsdk.ToolResult{{CallID: "c1", Name: "t", Result: "这是脏数据"}}, + } + if errs := runStageLikeKernel(handlers, sc); len(errs) > 0 { + t.Fatalf("stage 执行失败: %v", errs) + } + + got, _ := sc.ToolResults[0].Result.(string) + if got != "这是净数据" { + t.Fatalf("只读插件覆盖了改写插件的结果（lost update）：实际 %q", got) + } + if !strings.Contains(sc.FinalText, "stage-touched") { + t.Errorf("FinalText 改写被覆盖：实际 %q", sc.FinalText) + } +} diff --git a/internal/plugin/proc/host.go b/internal/plugin/proc/host.go index d76feb5..1f9e7db 100644 --- a/internal/plugin/proc/host.go +++ b/internal/plugin/proc/host.go @@ -7,7 +7,6 @@ import ( "sync" pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" - "golang.org/x/sys/unix" ) // Host 持有**被全部子进程插件共享的一块 StageContext 段**，是共享内存数据面的 @@ -43,35 +42,26 @@ type Host struct { coord *stageCoordinator } -// NewHost 创建共享段（memfd + mmap + 布局初始化）。 +// NewHost 创建共享段（平台层 allocShm + 布局初始化）。 // -// 用 memfd 而非 /dev/shm 文件：无需文件名、不残留（进程退出即回收）、 -// 可经 ExtraFiles 传给子进程。实验 2 已验证父子 mmap 到不同虚拟地址时 -// 相对偏移仍正确解引用。 +// 段的分配按平台分开（shmalloc_*.go）：Linux 用 memfd，macOS 用 +// 立即 unlink 的临时文件（无 memfd_create），其余平台明确报错。 +// 两者语义一致：无文件名残留，fd 可经 ExtraFiles 传给子进程， +// 子进程 mmap 同一 inode——「全部插件共享一块段」的前提得以成立。 +// 实验 2 已验证父子 mmap 到不同虚拟地址时相对偏移仍正确解引用。 func NewHost() (*Host, error) { - fd, err := unix.MemfdCreate("hastagectx", unix.MFD_CLOEXEC) + memfd, data, err := allocShm(shmDefaultSize) if err != nil { - return nil, fmt.Errorf("proc: 创建共享段 memfd: %w", err) - } - if err := unix.Ftruncate(fd, int64(shmDefaultSize)); err != nil { - unix.Close(fd) - return nil, fmt.Errorf("proc: 共享段 ftruncate: %w", err) - } - data, err := unix.Mmap(fd, 0, shmDefaultSize, - unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) - if err != nil { - unix.Close(fd) - return nil, fmt.Errorf("proc: 共享段 mmap: %w", err) + return nil, err } seg, err := NewSegment(data) if err != nil { - unix.Munmap(data) - unix.Close(fd) + freeShm(memfd, data) return nil, err } return &Host{ - memfd: os.NewFile(uintptr(fd), "hastagectx"), + memfd: memfd, data: data, seg: seg, shmSize: shmDefaultSize, @@ -88,16 +78,9 @@ const shmDefaultSize = 256 * 1024 // Close 释放共享段。 func (h *Host) Close() error { - if h.data != nil { - unix.Munmap(h.data) - h.data = nil - } - if h.memfd != nil { - err := h.memfd.Close() - h.memfd = nil - return err - } - return nil + data, f := h.data, h.memfd + h.data, h.memfd = nil, nil + return freeShm(f, data) } // beginStage 由插件 handler 进入时调用。 @@ -213,3 +196,6 @@ func (c *stageCoordinator) leave() (last bool, err error) { } return last, nil } + +// ShmSize 返回共享段大小（供诊断/日志）。 +func (h *Host) ShmSize() int { return h.shmSize } diff --git a/internal/plugin/proc/shmalloc_darwin.go b/internal/plugin/proc/shmalloc_darwin.go new file mode 100644 index 0000000..37b5759 --- /dev/null +++ b/internal/plugin/proc/shmalloc_darwin.go @@ -0,0 +1,50 @@ +//go:build darwin + +package proc + +import ( + "fmt" + "os" + + "golang.org/x/sys/unix" +) + +// allocShm 用临时文件 + mmap 创建共享段（macOS）。 +// +// macOS 没有 memfd_create。改用 os.CreateTemp 后立即 unlink：文件名从目录树消失， +// 但 fd 与映射继续有效，进程退出即回收——与 memfd 的不残留语义一致。 +// 已 unlink 的 fd 仍可经 ExtraFiles 传给子进程，子进程 mmap 同一 inode， +// 故「全部插件共享一块段」的前提在 macOS 同样成立。 +func allocShm(size int) (*os.File, []byte, error) { + f, err := os.CreateTemp("", "hastagectx-*") + if err != nil { + return nil, nil, fmt.Errorf("proc: 创建共享段临时文件: %w", err) + } + // 立即摘除目录项：后续无人能按路径打开它，也不会有残留文件 + if err := os.Remove(f.Name()); err != nil { + f.Close() + return nil, nil, fmt.Errorf("proc: unlink 共享段临时文件: %w", err) + } + if err := f.Truncate(int64(size)); err != nil { + f.Close() + return nil, nil, fmt.Errorf("proc: 共享段 ftruncate: %w", err) + } + data, err := unix.Mmap(int(f.Fd()), 0, size, + unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { + f.Close() + return nil, nil, fmt.Errorf("proc: 共享段 mmap: %w", err) + } + return f, data, nil +} + +// freeShm 解除映射并关闭段。 +func freeShm(f *os.File, data []byte) error { + if data != nil { + unix.Munmap(data) + } + if f != nil { + return f.Close() + } + return nil +} diff --git a/internal/plugin/proc/shmalloc_linux.go b/internal/plugin/proc/shmalloc_linux.go new file mode 100644 index 0000000..636f297 --- /dev/null +++ b/internal/plugin/proc/shmalloc_linux.go @@ -0,0 +1,43 @@ +//go:build linux + +package proc + +import ( + "fmt" + "os" + + "golang.org/x/sys/unix" +) + +// allocShm 用 memfd 创建共享段（Linux）。 +// +// 选 memfd 而非 /dev/shm 文件：无需文件名、不残留（最后一个 fd 关闭即回收）、 +// 可经 ExtraFiles 传给子进程。实验 2 已验证父子 mmap 到不同虚拟地址时 +// 相对偏移仍正确解引用——这是段内一律用偏移而非指针的前提。 +func allocShm(size int) (*os.File, []byte, error) { + fd, err := unix.MemfdCreate("hastagectx", unix.MFD_CLOEXEC) + if err != nil { + return nil, nil, fmt.Errorf("proc: 创建共享段 memfd: %w", err) + } + if err := unix.Ftruncate(fd, int64(size)); err != nil { + unix.Close(fd) + return nil, nil, fmt.Errorf("proc: 共享段 ftruncate: %w", err) + } + data, err := unix.Mmap(fd, 0, size, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_SHARED) + if err != nil { + unix.Close(fd) + return nil, nil, fmt.Errorf("proc: 共享段 mmap: %w", err) + } + return os.NewFile(uintptr(fd), "hastagectx"), data, nil +} + +// freeShm 解除映射并关闭段。 +func freeShm(f *os.File, data []byte) error { + if data != nil { + unix.Munmap(data) + } + if f != nil { + return f.Close() + } + return nil +} diff --git a/internal/plugin/proc/shmalloc_other.go b/internal/plugin/proc/shmalloc_other.go new file mode 100644 index 0000000..06175e1 --- /dev/null +++ b/internal/plugin/proc/shmalloc_other.go @@ -0,0 +1,28 @@ +//go:build !linux && !darwin + +package proc + +import ( + "fmt" + "os" +) + +// allocShm 在尚未适配的平台上明确报错。 +// +// 不静默降级成「无共享段」：那会让 stage 静默失去数据面， +// 插件看起来加载成功但读不到 StageContext——比启动失败难查得多。 +// +// Windows 适配路径：CreateFileMapping + MapViewOfFile，句柄经 +// PROC_THREAD_ATTRIBUTE_HANDLE_LIST 或命名段传给子进程。 +// §9.2 已记录 Windows DLL 路径当前能力严重退化（只下发 3 字段、无写回）， +// 迁移到子进程后三套 ABI 收敛为单一 RPC 实现，Windows 反而受益，但需测试机验证。 +func allocShm(size int) (*os.File, []byte, error) { + return nil, nil, fmt.Errorf("proc: 当前平台尚未支持共享内存数据面（需 CreateFileMapping 适配，§9.2）") +} + +func freeShm(f *os.File, data []byte) error { + if f != nil { + return f.Close() + } + return nil +} diff --git a/internal/plugin/proc_core.go b/internal/plugin/proc_core.go new file mode 100644 index 0000000..443d136 --- /dev/null +++ b/internal/plugin/proc_core.go @@ -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{} diff --git a/internal/plugin/proc_load_test.go b/internal/plugin/proc_load_test.go new file mode 100644 index 0000000..a812eb8 --- /dev/null +++ b/internal/plugin/proc_load_test.go @@ -0,0 +1,192 @@ +//go:build linux || darwin + +package plugin + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "gitcode.com/JianFeeeee/HomeAgent/internal/plugin/proc" + isdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" +) + +// 子进程插件经 Registry 加载的接线测试（Part 3 收尾）。 +// +// 这里验证的是"内核侧接线"，不是共享段语义本身——后者由 +// internal/plugin/proc 的 34 项测试（含 -race）覆盖。 + +// 共享段 Host 必须惰性创建且**全局唯一**。 +// +// 每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下 +// 退化成副本模型，lost update 原样复现（§8.4 实测 35.8~36.8%）。 +func TestRegistry_ProcHostIsSharedAndLazy(t *testing.T) { + r := NewRegistry() + defer r.closeProcHost() + + if r.procHost != nil { + t.Error("共享段应惰性创建，未加载 .bin 插件时不该存在") + } + + h1, err := r.ensureProcHost() + if err != nil { + t.Fatalf("创建共享段: %v", err) + } + h2, err := r.ensureProcHost() + if err != nil { + t.Fatalf("二次获取共享段: %v", err) + } + if h1 != h2 { + t.Fatal("共享段必须全局唯一——每插件一段会退化成副本模型，lost update 复现") + } + if h1.ShmSize() <= 0 { + t.Errorf("共享段大小应为正数，实际 %d", h1.ShmSize()) + } +} + +func TestRegistry_CloseProcHostIsIdempotent(t *testing.T) { + r := NewRegistry() + if _, err := r.ensureProcHost(); err != nil { + t.Fatalf("创建共享段: %v", err) + } + r.closeProcHost() + r.closeProcHost() // 二次关闭不应 panic + if r.procHost != nil { + t.Error("关闭后 procHost 应为 nil") + } +} + +// loadProc 对非 proc 目录返回 nil,nil（交由后续探测通道）。 +func TestRegistry_LoadProcSkipsNonProcDir(t *testing.T) { + r := NewRegistry() + defer r.closeProcHost() + + plg, err := r.loadProc(t.TempDir(), "demo", nil) + if plg != nil || err != nil { + t.Fatalf("无 plugin.bin 应返回 nil,nil，实际 plg=%v err=%v", plg, err) + } + if r.procHost != nil { + t.Error("非 proc 目录不该触发共享段创建") + } +} + +// 缺可执行权限时报明确错误——常见于经 zip/hmap 分发丢失权限位。 +func TestRegistry_LoadProcRejectsNonExecutable(t *testing.T) { + r := NewRegistry() + defer r.closeProcHost() + + dir := t.TempDir() + path := filepath.Join(dir, binEntry) + if err := os.WriteFile(path, []byte("#!/bin/sh\n"), 0o644); err != nil { + t.Fatalf("write: %v", err) + } + + _, err := r.loadProc(dir, "demo", nil) + if err == nil { + t.Fatal("缺少可执行权限应报错") + } + // 错误消息须给出可直接执行的修复指令 + if !strings.Contains(err.Error(), "chmod +x") { + t.Errorf("错误消息应含 chmod +x 修复指令，实际: %v", err) + } +} + +// 构造出的插件必须能满足 registry 的 sdk.Plugin 接口（含 Close 供重载 kill 进程）。 +func TestRegistry_LoadProcReturnsAdapter(t *testing.T) { + r := NewRegistry() + defer r.closeProcHost() + + dir := t.TempDir() + path := filepath.Join(dir, binEntry) + if err := os.WriteFile(path, []byte("#!/bin/sh\nexec cat\n"), 0o755); err != nil { + t.Fatalf("write: %v", err) + } + + plg, err := r.loadProc(dir, "demo", nil) + if err != nil { + t.Fatalf("loadProc: %v", err) + } + if plg == nil { + t.Fatal("应返回插件实体") + } + if plg.Name() != "demo" { + t.Errorf("Name() = %q, want demo", plg.Name()) + } + // Close 必须可见：registry.closeDynamic 靠它真正 kill 子进程。 + // 对比 cabi 路径的 Close 只做 dlclose，而 dlclose 对 Go c-shared 是 no-op + // （§1.1，热重载静默失效的根因）。 + if _, ok := plg.(interface{ Close() error }); !ok { + t.Error("proc 插件须暴露 Close()，否则重载时子进程不会被回收") + } + if r.procHost == nil { + t.Error("加载 .bin 插件应触发共享段创建") + } +} + +// procCore 必须满足 proc.CoreSDK，且**刻意不暴露**内核内部机制。 +// +// 这是 §3.8 的核心：权限梯度从「C ABI 表达能力的意外产物」 +// 变成显式声明并强制的策略。 +// +// 守住的不变量：procCore 用**命名字段**持有内核 SDK。若日后有人改成 +// 嵌入 *isdk.PluginSDK，全部方法会被提升，外部插件就能经类型断言拿到 +// 这些内核能力——下面的断言会当场拦住。 +func TestProcCore_SatisfiesCoreSDKAndWithholdsInternals(t *testing.T) { + var _ proc.CoreSDK = procCore{} + + var c interface{} = procCore{} + + if _, has := c.(interface{ Selftest() *isdk.VirtualInstance }); has { + t.Error("procCore 不应暴露 Selftest（§3.8 权限梯度）") + } + if _, has := c.(interface{ Supervisor() isdk.SupervisorAPI }); has { + t.Error("procCore 不应暴露 Supervisor（§3.8 权限梯度）") + } + if _, has := c.(interface{ Tracker() isdk.TrackerAPI }); has { + t.Error("procCore 不应暴露 Tracker（§3.8 权限梯度）") + } + if _, has := c.(interface{ Adapter() isdk.AdapterAPI }); has { + t.Error("procCore 不应暴露 Adapter（§3.8 权限梯度）") + } + if _, has := c.(interface{ Indexer() isdk.IndexerAPI }); has { + t.Error("procCore 不应暴露 Indexer（§3.8 权限梯度）") + } + if _, has := c.(interface{ Status() isdk.StatusAPI }); has { + t.Error("procCore 不应暴露 Status（§3.8 权限梯度）") + } +} + +// nil SDK 下各能力访问器必须返回真 nil（而非类型化 nil）。 +// +// corehandler 用 `if xxx == nil` 判断能力不可用并返回 errUnavailable； +// 类型化 nil 会让判空失效，插件收到的是 panic 而不是"能力不可用"。 +func TestProcCore_NilCapabilitiesAreTrueNil(t *testing.T) { + c := newProcCore(&isdk.PluginSDK{}) + + if c.Settings() != nil { + t.Error("Settings() 应为真 nil") + } + if c.Memory() != nil { + t.Error("Memory() 应为真 nil") + } + if c.TextMemory() != nil { + t.Error("TextMemory() 应为真 nil") + } + if c.DocMemory() != nil { + t.Error("DocMemory() 应为真 nil") + } + if c.Knowledge() != nil { + t.Error("Knowledge() 应为真 nil") + } + if c.LLM() != nil { + t.Error("LLM() 应为真 nil") + } + if c.PluginMgr() != nil { + t.Error("PluginMgr() 应为真 nil") + } + // 无 IOManager 时同步注入返回空串，不 panic + if got := c.InjectInputSync("s", "c", "t"); got != "" { + t.Errorf("无 IOManager 时应返回空串，实际 %q", got) + } +} diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go index 53ce5a9..8755032 100644 --- a/internal/plugin/registry.go +++ b/internal/plugin/registry.go @@ -21,6 +21,7 @@ import ( "gitcode.com/JianFeeeee/HomeAgent/internal/memory" doc "gitcode.com/JianFeeeee/HomeAgent/internal/memory/document" "gitcode.com/JianFeeeee/HomeAgent/internal/memory/text" + "gitcode.com/JianFeeeee/HomeAgent/internal/plugin/proc" sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" "gitcode.com/JianFeeeee/HomeAgent/internal/tracker" "gitcode.com/JianFeeeee/HomeAgent/pkg/types" @@ -101,9 +102,17 @@ type Registry struct { knownDisabled map[string]bool allowlist map[string]bool - // pluginHashes 记录各插件二进制(plugin.so/main.lua)的 SHA256， + // pluginHashes 记录各插件二进制(plugin.so/plugin.bin/main.lua)的 SHA256， // 供增量重载(Reload)对比：仅重载有变更的插件，避免全量 StopAll+Load 导致重复加载。 pluginHashes map[string]string + + // procHost 是**全部子进程插件共享的那一块** StageContext 段（§3.3/§3.4）。 + // + // 懒创建（首个 .bin 插件加载时），随内核存活。共享而非每插件一段是关键： + // 每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成副本模型， + // lost update 原样复现（§8.4 实测 35.8~36.8%）。 + procHostMu sync.Mutex + procHost *proc.Host } func NewRegistry() *Registry { @@ -466,7 +475,6 @@ func (r *Registry) runOnRemoveHandlers(name string) { func (r *Registry) StopAll() { r.mu.Lock() - defer r.mu.Unlock() for _, p := range r.instances { r.runStopHandlers(p.Name()) if err := p.Stop(); err != nil { @@ -477,6 +485,12 @@ func (r *Registry) StopAll() { r.instances = nil r.pluginAutoRestart = make(map[string]bool) r.sdkRefs = make(map[string]*sdk.PluginSDK) + r.mu.Unlock() + + // 共享段在全部子进程退出后再释放：插件还持有映射时拆段， + // 它们下一次访问就是 SIGBUS。在锁外调用：Close 不需 registry 锁， + // 而持锁调它会与 onProcCrash 路径（子进程退出回调）产生锁序风险。 + r.closeProcHost() } func (r *Registry) Reload(dir string) (string, error) { @@ -894,7 +908,7 @@ func (r *Registry) tryDynamic(plgDir, name string, config map[string]interface{} // 按 manifest entry 分派到对应加载通道（外部插件多进程化：.so/.dll 与 .bin 双通道共存）。 // 这使迁移可逐插件推进、随时回退——把 entry 改回 plugin.so 即回到旧通道。 if detectEntryKind(plgDir) == entryProc { - plg, err := tryLoadProc(plgDir, name, config) + plg, err := r.loadProc(plgDir, name, config) if err != nil { return nil, err } From 4f14d0947f3918fc5df0f395c792b1f61cda143c Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 13:12:08 +0800 Subject: [PATCH 14/27] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E8=AE=A1=E5=88=92=E8=BF=9B=E5=BA=A6=EF=BC=88Part=202/?= =?UTF-8?q?3/4=20=E5=AE=8C=E6=88=90=E6=A0=87=E8=AE=B0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part 2（子进程通道）、Part 3（plugindev .bin 构建）、Part 4（RunStage 接线） 标记为已完成，下一步转 Part 5 通知面。 记录两处与原计划的偏差及原因： - Part 3 模板落地方式从 templates.go 的 raw string 换成真实 .go 源文件 + //go:embed —— 900+ 行代码塞在字符串里写错只能等生成插件时才炸。 - Part 2 最初每插件一块共享段，等于副本模型换壳，已改为全部插件共享同一 memfd。 另记 lifecycle.autoRestart 缺口：公开 SDK 的 SetAutoRestart 是纯 setter 无 hook，隔着进程边界内核读不到，需模板在 Start 返回后显式上报。 --- docs/zh/plugin-migration-plan.md | 100 ++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 8 deletions(-) diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index b3189e5..2675378 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -17,16 +17,21 @@ - **Part 0** 脆弱基线先行（不依赖迁移，现网可直接受益）— 0.1 ✅ / 0.2 ✅ / 0.3 ⏭️ / 0.4 ⏭️ - **Part 1** 加载分派骨架（`entry` 双通道共存）— ✅ **已完成** -- **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin）— ⏳ 下一步 -- **Part 3** plugindev 工具链改造（`.bin` 产物） -- **Part 4** 共享内存数据面（StageContext 跨进程并发改写）— ✅ **核心已完成**（段/编解码/锁仲裁），RunStage 接线待 Part 2 -- **Part 5** 通知面（事件环 + eventfd） +- **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin）— ✅ **已完成** +- **Part 3** plugindev 工具链改造（`.bin` 产物）— ✅ **已完成** +- **Part 4** 共享内存数据面（StageContext 跨进程并发改写）— ✅ **已完成**（段/编解码/锁仲裁 + RunStage 接线） +- **Part 5** 通知面（事件环 + eventfd）— ⏳ 下一步 - **Part 6** 迁移与收尾（17 插件逐个 + 删 cabi + 权限显式化） - 最终验收清单 -> **进度快照（2026-08-31）**：分支 `feature/plugin-proc-migration`。 -> 已交付：现网止血 2 项（11.1/11.3）、entry 双通道分派、共享内存 stage 并发（16 项测试含 -race）。 -> 下一步：Part 2 子进程通道原型（spawn + stdio JSON-RPC + procPlugin），完成后把 `RunStage` 接到共享段。 +> **进度快照（2026-09-02）**：分支 `feature/plugin-proc-migration`。 +> 已交付：现网止血 2 项（11.1/11.3）、entry 双通道分派、共享内存 stage 并发、 +> 子进程控制面（NDJSON RPC + 51 method 名平移）、plugindev `.bin` 构建、 +> registry 接线。**外部插件已可端到端跑在子进程 + 共享内存上**： +> `example/weather` 业务代码逐字节未改，只把 `plg.json` 的 entry 换成 `plugin.bin`。 +> 测试：内核 `internal/plugin/proc` 36 项 + `internal/plugin` 13 项（含 `-race`）， +> SDK 仓 plugindev 16 项静态检查。 +> 下一步：Part 5 通知面（事件环 + eventfd），然后 Part 6 逐插件迁移 + 删 `internal/plugin/cabi/`。 --- @@ -191,6 +196,27 @@ **Part 2 出口条件**：一个真实外部插件 `.bin` 全链路可用，崩溃隔离生效，接口零改动。 +#### ✅ **Part 2 已完成**（2026-09-01，commit `d62430a` + `82dcc86`） + +- `proc/protocol.go`：NDJSON 帧、**51 个 method id 平移为 method 名**（编号扔掉）、握手/stage/tool/output 参数类型。 + `case 25`(CORE_FREE_STRING) 无对应 method（GC 接管）；`case 23/24`(事件订阅) 与 `io.setToolBlocks` + 明确返回未实现，**不静默成功**。 +- `proc/process.go`：Spawn/readLoop/CallContext/Notify/Stop/Kill/markExited；单帧上限 1MB。 +- `proc/corehandler.go`：51 case 平移 + `CoreSDK` 接口（**刻意排除**内核内部机制，见 Part 6 权限梯度）。 +- `proc/host.go`：**全部插件共享同一 memfd**。最初写成每插件一块段，尝试后发现 + 那等于**副本模型换壳**（各写各段、各自回读、最后回读者覆盖前者），已改正。 +- `proc/stage.go`：RunStage 接线 + lockRegistry；`proc/plugin.go`：Plugin 实体。 +- 共享段分配按平台拆分（`shmalloc_linux.go` memfd / `shmalloc_darwin.go` 立即 unlink 的临时文件 / + `shmalloc_other.go` 明确报错）——不静默降级成「无共享段」，那会让 stage 静默失去数据面。 +- registry 接线（commit `11c1bbc`）：`tryDynamic` → `Registry.loadProc`；Host 惰创建且全局唯一； + `StopAll` **锁外**释放共享段（插件还持有映射时拆段 → SIGBUS；持锁调与 onProcCrash 有锁序风险）； + `onProcCrash` 只发 EventSystem 事件，**不在回调里直接重载**（重载需 registry 锁）。 +- `proc_core.go` —— 权限梯度的类型系统落点：`procCore` 用**命名字段**持有 `*isdk.PluginSDK`， + 不是嵌入。嵌入会提升全部方法，外部插件就能经类型断言拿到 + Supervisor/Tracker/Adapter/Indexer/Status/Selftest。 +- 测试 36 项含 `-race`：`testdata/` 8 个假插件 + `e2e_template_test.go` 用**真实 plugindev 模板** + 编译插件跑全链路（验证「模板 ↔ 内核」协议/布局真的对齐，不只是内核自己跟自己对齐）。 + --- ## Part 3：plugindev 工具链改造（阶段 2.6/2.7/2.8，M，SDK 仓） @@ -222,6 +248,46 @@ **Part 3 出口条件**：plugindev 一条命令产出 `.bin` + 正确 `.hmap`，外部插件源码零改动。 +#### ✅ **Part 3 已完成**（2026-09-02，SDK 仓 commit `09b64dc`） + +**模板落地方式换了**：不是计划里的 `templates.go` 新增 `tmplProcMain` raw string， +而是真实 `.go` 源文件 `templates/proc_main.go.tmpl` + `//go:embed`（`proc_runtime.go`）。 +原因：900+ 行代码塞在字符串里写错只能等生成插件时才炸，作为源文件可被 +`go/parser`、`gofmt`、`go vet` 直接检查。这也是 `proc_runtime_test.go` 16 项 +静态检查得以存在的前提。 + +- `templates/proc_main.go.tmpl`（1113 行）：51 个 method 的插件侧 RPC 实现 + （`procIO`/`procMemory`/`procSettings`/`procSocial`/`procLLM`/`procKnowledge`/ + `procDocMemory`/`procTextMemory`/`procPluginMgr`）、共享段访问（fd 3）与 16 字段 + StageContext 编解码、`handleStageInvoke`（拿锁 → 读段 → handler → **只写脏字段** → 放锁）。 +- `cmd_build.go`：`resolveBuild(target, proc)` 分派；proc 走 `go build -trimpath` + `CGO_ENABLED=0`， + **交叉编译不再需要目标平台 C 工具链**。bundle 模式各平台产物同名（进程边界即 ABI 边界， + 无平台扩展名），故 zip 内加平台后缀 `plugin.bin.linux.amd64`。 +- `proc_runtime.go`：生成时清理残留 `z_bridge_gen.go`/`z_entry.c`——同目录两套 main 会编译冲突， + 这让 `.so` → `.bin` 切换无需人工清理。 + +**计划外补的一个真缺口**：`lifecycle.autoRestart` 没接线。公开 SDK 的 `SetAutoRestart` +是纯 setter（`s.autoRestart = enabled`，无回调 hook）。C ABI 下内核在 `Start` 返回后 +直接读 `plgSDK.AutoRestart()`；子进程隔着进程边界读不到，插件调它只改自己进程内的副本。 +修法：模板在 `plg.Start()` 返回后显式上报一次（内核侧 `corehandler.go:145` 早已就绪）。 +**没有改公开 SDK 接口**。 + +验证（均已实测）： +``` +$ plugindev build # plg.json: entry = "plugin.bin" + compiling linux/amd64 (子进程模式，CGO_ENABLED=0)... + packaged weather_linux_amd64.hmap + +build/plugin.bin → ELF 64-bit executable, statically linked ← 零 cgo +dist/*.hmap → plugin.json + plugin.bin + +$ diff example/weather/plugin.go <构建目录>/plugin.go +✅ 逐字节一致 ← 业务代码零改动的硬证据 + +$ git diff third_party/homeagent-sdk/sdk/ +(空) ← 接口冻结保持 +``` + --- ## Part 4：共享内存数据面（阶段 3.1~3.5，~3 周，最高风险） @@ -282,13 +348,31 @@ - 【R】✅ `Extra` 维持 4 键具名字段，未引入通用 tagged union 成本 - 【R】✅ 接口冻结：`sdk/` 零 diff；`StageContext` 结构体未改 - 【R】✅ `go vet` 干净（含 copylocks 检查） -- 【V】✅ proc 包 **16 项测试全绿（含 `-race`）**： +- 【V】✅ proc 包共享段部分 **16 项测试全绿（含 `-race`）**（全包现 36 项，含进程/端到端）： - 段：魔数/版本校验、全 16 字段往返、Response nil vs 空串 - 脏字段：只读零写回、原地改切片被识别、压实不破坏字段 - **现网场景复刻**：`TestSegment_ProductionScenario_SanitizerNotOverwrittenByWeather`（sanitizer 清洗 + weather 只读并发，清洗结果不被覆盖） - **并发零丢失**：5 插件 × 40 轮读-改-写同一字段，200 次写入全部保留 - 锁：互斥、串扰拒绝、未持锁释放拒绝、重复加锁拒绝、**崩溃自愈**、定向强制释放、临界区串行化 +#### ✅ **Part 4 RunStage 接线已完成**（2026-09-01～09-02） + +- `proc/stage.go` 把内核 `RunStage` 的并发扇出接到共享段： + `Host.beginStage`（首个到达者独占段并写入 StageContext）→ `stage.invoke` RPC → + 插件侧 `stage.lock` → 读段 → handler → 只写脏字段 → `stage.unlock` → + `Host.endStage`（最后离开者回读 + 压实 arena）。 +- **并发扇出保留**（§0.2 第 1 条：并发扇出是原始设计，不是缺陷）； + `stageMu` 串行化整次 stage 对共享段的独占（内核可能在不同路径并发触发 + RunStage，而段只有一份）。 +- 端到端验证（`e2e_template_test.go`，用**真实 plugindev 模板**编译的插件， + 而非 `testdata/` 手写假插件——后者只能验证内核自己跟自己对齐）： + - `TestE2E_RealTemplatePluginFullLifecycle`：握手 → init/start → 反向注册 → + 工具调用 → stage 读改写；同时验证 `FinalText` 回传 + （**C ABI 下 after_toolcall 看不到此字段**，§8.3 10→16） + - `TestE2E_RealTemplateReadOnlyPluginDoesNotOverwrite`：两插件共享同一 Host 并发， + 只读插件不覆盖改写插件的结果（若每插件一块段，此测试必然失败） + +**Part 4 已整体完成**。 --- From 5bbfcc02fb8a4d7ef05a2d8f0da5ac4128114acd Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 16:48:27 +0800 Subject: [PATCH 15/27] =?UTF-8?q?plugin:=20=E4=BA=8B=E4=BB=B6=E7=8E=AF?= =?UTF-8?q?=E5=86=85=E6=A0=B8=E4=BE=A7=E5=AE=9E=E7=8E=B0=EF=BC=88=C2=A73.6?= =?UTF-8?q?=20Part=205=20=E6=A0=B8=E5=BF=83=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 事件环（EvtRing）是子进程首次获得事件订阅能力的基础设施。 此前 case 23/24 明确返回未实现，现在经事件环真正可用。 核心设计（§3.6，实验 4 已验证 post-and-forget 加速比 2218x）： - 事件环放**独立共享段**（不与 StageContext 混放）：stage compact 会清 arena， 事件要独立于 stage 生命周期。Host 持有两块 memfd：fd 3 = StageContext， fd 4 = 事件环段，fd 5 = eventfd。 - 无锁数据结构：内核 WritePush 追加写 slot，子进程 EvtConsumer 消费。 writeSeq 原子递增（Bus.Publish 并发调用），readSeq 每订阅者独立。 - eventfd 通知：Linux 用 unix.Eventfd（计数合并，1000 token 只唤醒几次）， macOS 用 os.Pipe（阻塞模式走 netpoller，只 park goroutine，实验 1 验证 200 等待者仅 +1 OS 线程）。两者行为一致：Read 阻塞直到有新事件。 - 溢出语义：落后超 cap 时跳到最新，丢弃计数记入 dropped（消费者知道丢了）。 不静默覆盖最旧（写端直接覆盖 slot，读端靠 seq 判断跳过）。 - 事件类型编码：pubsdk.EventType 字符串 ↔ uint32 位索引（编译时映射表）， typeMask 位掩码过滤（1< cap { + c.readSeq = writeSeq - cap + } + idx := c.readSeq % cap + slotOff := evtOffSlots + uint32(idx)*evtRingSlotLen + seq := binary.LittleEndian.Uint64(c.ringData[slotOff:]) + etype := binary.LittleEndian.Uint32(c.ringData[slotOff+8:]) + off := binary.LittleEndian.Uint32(c.ringData[slotOff+12:]) + slen := binary.LittleEndian.Uint32(c.ringData[slotOff+16:]) + if seq != c.readSeq { + // slot 已被新事件覆盖——逐个扫太慢（溢出场景 readSeq=0 要跳 100+ 步）， + // 直接跳到 writeSeq 附近找下一个可读 slot。 + // 简化：溢出后直接跳到 writeSeq - cap（最旧的可读事件）。 + if writeSeq > cap { + c.readSeq = writeSeq - cap + } else { + c.readSeq = writeSeq + } + continue + } + // 位掩码过滤 + if c.typeMask != 0 && (1< 0 && slen > 0 && uint64(off)+uint64(slen) <= uint64(len(c.ringData)) { + payload := make([]byte, slen) + copy(payload, c.ringData[off:off+slen]) + var evt pubsdk.Event + if err := json.Unmarshal(payload, &evt); err == nil { + c.handler(&evt) + } + } + c.readSeq++ + } +} + +func (c *EvtConsumer) Stop() { + c.mu.Lock() + defer c.mu.Unlock() + if c.running { + close(c.stop) + } +} diff --git a/internal/plugin/proc/host.go b/internal/plugin/proc/host.go index 1f9e7db..7efa044 100644 --- a/internal/plugin/proc/host.go +++ b/internal/plugin/proc/host.go @@ -20,24 +20,28 @@ import ( // // 生命周期：Host 由 registry 创建一次，随内核存活；每个插件 spawn 时经 // ExtraFiles 拿到同一 memfd（fd 3），mmap 后即看到同一份物理页。 +// +// 另外持有事件环段（§3.6）：独立于 StageContext 的事件通知通道， +// 子进程从 eventfd 感知新事件并从 mmap 读 slot。 +// fd 分配：fd 3 = StageContext，fd 4 = 事件环，fd 5 = eventfd。 type Host struct { memfd *os.File data []byte seg *Segment shmSize int - // locks 被全部插件的 coreHandler 共享——同阶段并发扇出的插件在此排队， - // 语义等价于内置插件共享 *StageContext 的 sync.RWMutex（§0.2 第 1 条）。 - locks *lockRegistry + // 事件环段（独立于 StageContext） + evtfd *os.File // eventfd fd（fd 5 的句柄，子进程读取消费） + evtRing *EvtRing // 内核侧事件环句柄 + evtRingFd *os.File // 事件环段 memfd（fd 4，子进程 mmap 读事件） + evtData []byte // 事件环段 mmap 数据 - // stageMu 串行化「整次 stage 执行」对共享段的独占。 - // - // 必要性：内核可能在不同路径并发触发 RunStage（如 emitResponse 的 - // before_output 与主循环的其他阶段）。段只有一份，两次 stage 交叠会互相污染。 - // 由首个进入的插件加锁、最后离开的插件解锁；RunStage 的 wg.Wait() 保证 - // 每个 handler 的 defer 必然执行，故 inflight 必然归零，不会死锁。 + // evtSubscriber 由 internal/plugin 注入，coreHandler 用它接子进程的 events.subscribe 请求。 + // proc 包不依赖 internal/plugin（循环依赖），故用接口类型存储。 + evtSubscriber EvtRingSubscriber + + locks *lockRegistry stageMu sync.Mutex - coordMu sync.Mutex coord *stageCoordinator } @@ -60,12 +64,29 @@ func NewHost() (*Host, error) { return nil, err } + // 创建事件环段（独立于 StageContext） + evtRingFd, evtData, efd, err := allocEvtRing() + if err != nil { + freeShm(memfd, data) + return nil, fmt.Errorf("事件环: %w", err) + } + evtRing, err := NewEvtRing(evtData) + if err != nil { + freeShm(memfd, data) + return nil, fmt.Errorf("事件环初始化: %w", err) + } + evtRing.Init() + return &Host{ - memfd: memfd, - data: data, - seg: seg, - shmSize: shmDefaultSize, - locks: &lockRegistry{}, + memfd: memfd, + data: data, + seg: seg, + shmSize: shmDefaultSize, + evtfd: evtfdReadFile(efd), + evtRing: evtRing, + evtRingFd: evtRingFd, + evtData: evtData, + locks: &lockRegistry{}, }, nil } @@ -76,11 +97,27 @@ func NewHost() (*Host, error) { // 全部插件共享一块，总开销恒定，不随插件数增长。 const shmDefaultSize = 256 * 1024 -// Close 释放共享段。 +// Close 释放共享段（StageContext + 事件环）。 func (h *Host) Close() error { - data, f := h.data, h.memfd - h.data, h.memfd = nil, nil - return freeShm(f, data) + var firstErr error + if h.data != nil { + if err := freeShm(h.memfd, h.data); err != nil && firstErr == nil { + firstErr = err + } + h.data, h.memfd = nil, nil + } + if h.evtData != nil { + if h.evtRingFd != nil { + h.evtRingFd.Close() + h.evtRingFd = nil + } + h.evtData = nil + } + if h.evtfd != nil { + h.evtfd.Close() + h.evtfd = nil + } + return firstErr } // beginStage 由插件 handler 进入时调用。 @@ -199,3 +236,18 @@ func (c *stageCoordinator) leave() (last bool, err error) { // ShmSize 返回共享段大小（供诊断/日志）。 func (h *Host) ShmSize() int { return h.shmSize } + +// EvtRing 返回内核侧事件环句柄。 +func (h *Host) EvtRing() *EvtRing { return h.evtRing } + +// Evtfd 返回 eventfd 的 *os.File（供 EventRing 写通知）。 +func (h *Host) Evtfd() *os.File { return h.evtfd } + +// SetEvtSubscriber 注入事件环订阅接口（由 Registry 在创建 Host 后设置）。 +func (h *Host) SetEvtSubscriber(sub EvtRingSubscriber) { h.evtSubscriber = sub } + +// EvtData 返回事件环段 mmap 数据（子进程消费者用）。 +func (h *Host) EvtData() []byte { return h.evtData } + +// EvtfdReadFile 返回 eventfd 的 *os.File（供子进程读取消费）。 +func (h *Host) EvtfdReadFile() *os.File { return h.evtfd } diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go index 0f33b0e..c20a68f 100644 --- a/internal/plugin/proc/plugin.go +++ b/internal/plugin/proc/plugin.go @@ -73,6 +73,7 @@ func (p *Plugin) Start(core CoreSDK) error { name: p.name, host: p.host, locks: p.host.locks, + evtRing: p.host.evtSubscriber, } // 反向调用闭包：注册回调时捕获，运行期经 RPC 打到插件进程。 p.handler.invokeTool = p.invokeTool @@ -82,8 +83,8 @@ func (p *Plugin) Start(core CoreSDK) error { proc, err := Spawn(p.name, p.bin, Options{ Dir: p.dir, Env: p.env, - // 子进程 fd 3 = 共享段 memfd（全部插件同一个，故看到同一份物理页） - ExtraFiles: []*os.File{p.host.memfd}, + // 子进程 fd 布局：3=StageContext 段，4=事件环段，5=eventfd + ExtraFiles: []*os.File{p.host.memfd, p.host.evtRingFd, p.host.evtfd}, ShmSize: p.host.shmSize, Handler: p.handler.Handle, OnExit: p.handleExit, From 53a148cb5452238b2d3a350b174de32cb93089a5 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 17:07:43 +0800 Subject: [PATCH 16/27] =?UTF-8?q?docs:=20Part=205=20=E6=A0=87=E8=AE=B0?= =?UTF-8?q?=E6=A0=B8=E5=BF=83=E5=B7=B2=E5=AE=8C=E6=88=90=EF=BC=8C=E8=BF=9B?= =?UTF-8?q?=E5=BA=A6=E5=BF=AB=E7=85=A7=E6=9B=B4=E6=96=B0=E4=BA=8B=E4=BB=B6?= =?UTF-8?q?=E7=8E=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part 5 通知面内核侧 + 模板侧均已完成，端到端测试通过。 事件订阅从 C ABI 的空实现（case 23/24）变成真正可用。 测试数量更新：proc 38 项 + plugin 16 项（含 -race）。 下一步转 Part 6 逐插件迁移。 --- docs/zh/plugin-migration-plan.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index 2675378..362837d 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -20,18 +20,18 @@ - **Part 2** 子进程通道原型（spawn / JSON-RPC / procPlugin）— ✅ **已完成** - **Part 3** plugindev 工具链改造（`.bin` 产物）— ✅ **已完成** - **Part 4** 共享内存数据面（StageContext 跨进程并发改写）— ✅ **已完成**（段/编解码/锁仲裁 + RunStage 接线） -- **Part 5** 通知面（事件环 + eventfd）— ⏳ 下一步 +- **Part 5** 通知面（事件环 + eventfd）— ✅ **核心已完成** - **Part 6** 迁移与收尾（17 插件逐个 + 删 cabi + 权限显式化） - 最终验收清单 > **进度快照（2026-09-02）**：分支 `feature/plugin-proc-migration`。 > 已交付：现网止血 2 项（11.1/11.3）、entry 双通道分派、共享内存 stage 并发、 > 子进程控制面（NDJSON RPC + 51 method 名平移）、plugindev `.bin` 构建、 -> registry 接线。**外部插件已可端到端跑在子进程 + 共享内存上**： -> `example/weather` 业务代码逐字节未改，只把 `plg.json` 的 entry 换成 `plugin.bin`。 -> 测试：内核 `internal/plugin/proc` 36 项 + `internal/plugin` 13 项（含 `-race`）， -> SDK 仓 plugindev 16 项静态检查。 -> 下一步：Part 5 通知面（事件环 + eventfd），然后 Part 6 逐插件迁移 + 删 `internal/plugin/cabi/`。 +> registry 接线、**事件环（§3.6）**。**外部插件已可端到端跑在子进程 + 共享内存上**， +> 且首次获得事件订阅能力（C ABI 下 case 23/24 一直是空实现）。 +> 测试：内核 `internal/plugin/proc` 38 项 + `internal/plugin` 16 项（含 `-race`）， +> SDK 仓 plugindev 16 项。 + > 下一步：Part 6 逐插件迁移 + 删 `internal/plugin/cabi/`。 --- From d027c964e21cd26e3647da628d6461e8ff0a2a2c Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 19:07:14 +0800 Subject: [PATCH 17/27] =?UTF-8?q?proc:=20Windows=20=E5=85=B1=E4=BA=AB?= =?UTF-8?q?=E5=86=85=E5=AD=98=20+=20=E4=BA=8B=E4=BB=B6=E9=80=9A=E7=9F=A5?= =?UTF-8?q?=E9=80=82=E9=85=8D=EF=BC=88Part=206.2=20=E5=86=85=E6=A0=B8?= =?UTF-8?q?=E4=BE=A7=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补齐内核侧的 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 --- internal/plugin/proc/e2e_template_test.go | 32 +++-- internal/plugin/proc/evtfd_darwin.go | 68 +++++++++-- internal/plugin/proc/evtfd_linux.go | 3 + internal/plugin/proc/evtfd_other.go | 5 +- internal/plugin/proc/evtfd_windows.go | 103 ++++++++++++++++ internal/plugin/proc/evtring.go | 4 +- internal/plugin/proc/host.go | 50 +++++--- internal/plugin/proc/plugin.go | 24 ++-- internal/plugin/proc/process.go | 30 +++-- internal/plugin/proc/protocol.go | 8 +- internal/plugin/proc/shmalloc_other.go | 2 +- internal/plugin/proc/shmalloc_windows.go | 137 ++++++++++++++++++++++ internal/plugin/proc/shmpass_unix.go | 21 ++++ internal/plugin/proc/shmpass_windows.go | 26 ++++ 14 files changed, 445 insertions(+), 68 deletions(-) create mode 100644 internal/plugin/proc/evtfd_windows.go create mode 100644 internal/plugin/proc/shmalloc_windows.go create mode 100644 internal/plugin/proc/shmpass_unix.go create mode 100644 internal/plugin/proc/shmpass_windows.go diff --git a/internal/plugin/proc/e2e_template_test.go b/internal/plugin/proc/e2e_template_test.go index aba143b..e80e24e 100644 --- a/internal/plugin/proc/e2e_template_test.go +++ b/internal/plugin/proc/e2e_template_test.go @@ -68,6 +68,20 @@ func (p *e2ePlugin) Start(s *sdk.PluginSDK) error { func (p *e2ePlugin) Stop() error { return nil } ` +// procRuntimeTemplates 列出 plugindev 会生成到插件目录的运行时文件。 +// +// 必须与 SDK 仓 tools/plugindev/proc_runtime.go 的 procRuntimeFiles 一致： +// 共享段与事件通知的传递机制按平台不同（Unix 继承 fd，Windows 命名 +// 内核对象），故拆成带 build tag 的文件；只写主模板会编译失败。 +var procRuntimeTemplates = []struct { + tmpl string + out string +}{ + {"proc_main.go.tmpl", "z_proc_gen.go"}, + {"proc_shm_unix.go.tmpl", "z_proc_shm_unix.go"}, + {"proc_shm_windows.go.tmpl", "z_proc_shm_windows.go"}, +} + // buildPluginWithRealTemplate 用 plugindev 的真实模板编译一个插件二进制。 func buildPluginWithRealTemplate(t *testing.T, businessCode string) string { t.Helper() @@ -75,17 +89,19 @@ func buildPluginWithRealTemplate(t *testing.T, businessCode string) string { t.Skip("环境无 go 工具链，跳过端到端测试") } - tmpl := filepath.Join("..", "..", "..", - "third_party", "homeagent-sdk", "tools", "plugindev", - "templates", "proc_main.go.tmpl") - runtime, err := os.ReadFile(tmpl) - if err != nil { - t.Skipf("plugindev 模板不可读（SDK 仓可能未就位）: %v", err) - } + tmplDir := filepath.Join("..", "..", "..", + "third_party", "homeagent-sdk", "tools", "plugindev", "templates") dir := t.TempDir() mustWriteFile(t, filepath.Join(dir, "plugin.go"), businessCode) - mustWriteFile(t, filepath.Join(dir, "z_proc_gen.go"), string(runtime)) + + for _, rt := range procRuntimeTemplates { + data, err := os.ReadFile(filepath.Join(tmplDir, rt.tmpl)) + if err != nil { + t.Skipf("plugindev 模板 %s 不可读（SDK 仓可能未就位）: %v", rt.tmpl, err) + } + mustWriteFile(t, filepath.Join(dir, rt.out), string(data)) + } sdkPath, err := filepath.Abs(filepath.Join("..", "..", "..", "third_party", "homeagent-sdk")) if err != nil { diff --git a/internal/plugin/proc/evtfd_darwin.go b/internal/plugin/proc/evtfd_darwin.go index fb39f2e..1f62f5c 100644 --- a/internal/plugin/proc/evtfd_darwin.go +++ b/internal/plugin/proc/evtfd_darwin.go @@ -4,30 +4,78 @@ package proc import ( "os" + "sync" + "syscall" ) -// evtfdCreate 用 pipe 模拟 Linux eventfd 的通知语义（macOS 无 eventfd）。 +// macOS 侧事件通知：用 pipe 模拟 eventfd（macOS 无 eventfd_create）。 // -// 限制：不具 eventfd 的计数合并（多次写会触发多次读）， -// 但事件环本身允许溢出丢弃，consumer 在 drainEvents 里按 readSeq 批量读取， -// 故多次唤醒只多几次无效循环（readSeq == writeSeq 时立即返回），不造成正确性问题。 +// 与 eventfd 的语义差异：pipe 不具计数合并，多次写会触发多次读。 +// 这不影响正确性——消费者在 drainEvents 里按 readSeq 追 writeSeq 批量读， +// 多次唤醒只多几次空循环（readSeq == writeSeq 时立即返回）。 // -// 走 Go netpoller（os.File.Read 阻塞时只 park goroutine，实验 1 已验证）。 +// 走 Go netpoller：os.File.Read 阻塞时只 park goroutine，不占 OS 线程 +// （实验 1 已验证 200 个等待者仅增 1 个 OS 线程）。 +// +// ❗ 必须同时持有读端与写端：写端若被 GC 回收，读端会收到 EOF 而非阻塞， +// 消费循环变成忙转。故用 pipePair 表存住两端。 +type pipePair struct { + r *os.File + w *os.File +} + +var ( + evtPipes = map[int]*pipePair{} + evtPipesMu sync.Mutex +) + +// evtfdCreate 建 pipe，返回读端 fd。 func evtfdCreate() (int, error) { r, w, err := os.Pipe() if err != nil { return -1, err } - return int(r.Fd()), nil + fd := int(r.Fd()) + evtPipesMu.Lock() + evtPipes[fd] = &pipePair{r: r, w: w} + evtPipesMu.Unlock() + return fd, nil } -// evtfdNotify 写 1 字节通知子进程有新事件（post-and-forget）。 +// EvtfdNotify 写 1 字节通知子进程有新事件（post-and-forget）。 +// +// 直接写裸 fd 而非 pipePair.w：本函数在 Bus.Publish 路径上被高频调用， +// 查表加锁不值得。写端 fd 由 pipePair 持有引用故不会被 GC 回收。 func EvtfdNotify(efd int) { + evtPipesMu.Lock() + p, ok := evtPipes[efd] + evtPipesMu.Unlock() + if !ok { + return + } var buf [1]byte - syscall.Write(efd, buf[:]) + // 忽略错误：管道满说明消费者落后，事件环本身允许溢出丢弃 + syscall.Write(int(p.w.Fd()), buf[:]) } -// evtfdReadFile 把事件通知读端包装成 *os.File 供 netpoller 消费。 +// evtfdReadFile 返回通知读端（供 netpoller 消费）。 func evtfdReadFile(efd int) *os.File { - return os.NewFile(uintptr(efd), "evtring-notify") + evtPipesMu.Lock() + defer evtPipesMu.Unlock() + if p, ok := evtPipes[efd]; ok { + return p.r + } + return nil +} + +// evtfdClose 关闭 pipe 两端。 +func evtfdClose(efd int) { + evtPipesMu.Lock() + p, ok := evtPipes[efd] + delete(evtPipes, efd) + evtPipesMu.Unlock() + if ok { + p.r.Close() + p.w.Close() + } } diff --git a/internal/plugin/proc/evtfd_linux.go b/internal/plugin/proc/evtfd_linux.go index 18a5fbe..11ba3a2 100644 --- a/internal/plugin/proc/evtfd_linux.go +++ b/internal/plugin/proc/evtfd_linux.go @@ -33,3 +33,6 @@ func EvtfdNotify(efd int) { func evtfdReadFile(efd int) *os.File { return os.NewFile(uintptr(efd), "evtring-notify") } + +// evtfdClose 关闭通知句柄。Unix 侧由 *os.File.Close 负责，此处为跨平台签名占位。 +func evtfdClose(efd int) {} diff --git a/internal/plugin/proc/evtfd_other.go b/internal/plugin/proc/evtfd_other.go index ea8349e..60ce3b4 100644 --- a/internal/plugin/proc/evtfd_other.go +++ b/internal/plugin/proc/evtfd_other.go @@ -1,4 +1,4 @@ -//go:build !linux && !darwin +//go:build !linux && !darwin && !windows package proc @@ -16,3 +16,6 @@ type errPlatformNotSupported string func (e errPlatformNotSupported) Error() string { return "当前平台尚未支持事件环通知（" + string(e) + "，§9.2）" } + +// evtfdClose 关闭通知句柄。Unix 侧由 *os.File.Close 负责，此处为跨平台签名占位。 +func evtfdClose(efd int) {} diff --git a/internal/plugin/proc/evtfd_windows.go b/internal/plugin/proc/evtfd_windows.go new file mode 100644 index 0000000..07cba3c --- /dev/null +++ b/internal/plugin/proc/evtfd_windows.go @@ -0,0 +1,103 @@ +//go:build windows + +package proc + +import ( + "fmt" + "os" + "sync" + "sync/atomic" + + "golang.org/x/sys/windows" +) + +// Windows 侧事件通知：命名 Event 对象。 +// +// 与 eventfd 的语义差异：Event 是二元信号（Set/Reset），不是计数器。 +// 多次 SetEvent 只对应一次唤醒，不会累积。 +// +// 这不影响正确性：消费者被唤醒后按 readSeq 追 writeSeq 批量 drain， +// 一次唤醒能处理累积的全部事件（漏掉的是"唤醒次数"，不是"事件"）。 +// 事件环本身允许溢出丢弃并让消费者知道丢了（dropped 计数）， +// 通知面从来不是可靠投递语义。 +// +// 代价：WaitForSingleObject 阻塞 OS 线程而非仅 goroutine，不如 eventfd +// 的 netpoller 路径省线程。每插件一个消费 goroutine，17 插件即 17 线程 +// （实验 5 实测 17 子进程共 84 线程，仍在可接受范围）。 +var evtEventSeq atomic.Uint64 + +// evtEventHandles 记录 fd 伪值 → Event 句柄的映射。 +// +// 为何需要：跨平台签名用 int 表示通知句柄（Unix 是真 fd）。 +// Windows 的 windows.Handle 是 uintptr，直接转 int 在 32 位上会截断， +// 故用递增伪 fd 做 key，句柄存表里。 +var ( + evtEvents = map[int]windows.Handle{} + evtEventsMu sync.Mutex + evtEventFd atomic.Int64 +) + +// evtfdCreate 创建命名 Event 对象，返回伪 fd。 +// +// 手动重置（manualReset=false → 自动重置）：被一个等待者唤醒后自动 Reset， +// 语义最接近 eventfd 的"取出后清零"。 +func evtfdCreate() (int, error) { + name := fmt.Sprintf("%s_%d_%d", evtEventNamePfx, os.Getpid(), evtEventSeq.Add(1)) + namePtr, err := windows.UTF16PtrFromString(name) + if err != nil { + return -1, fmt.Errorf("proc: 事件对象名字非法 %q: %w", name, err) + } + h, err := windows.CreateEvent(nil, 0 /*autoReset*/, 0 /*initiallyNonSignaled*/, namePtr) + if err != nil { + return -1, fmt.Errorf("proc: 创建事件对象 %q: %w", name, err) + } + + fd := int(evtEventFd.Add(1)) + evtEventsMu.Lock() + evtEvents[fd] = h + evtEventNames[fd] = name + evtEventsMu.Unlock() + return fd, nil +} + +// evtEventNames 记录伪 fd → 对象名（供注入子进程环境变量）。 +var evtEventNames = map[int]string{} + +// EvtfdNotify 唤醒等待者（post-and-forget）。 +// +// SetEvent 不阻塞，满足 §3.6 约束 B（Bus.Publish 路径上绝不等待）。 +func EvtfdNotify(efd int) { + evtEventsMu.Lock() + h, ok := evtEvents[efd] + evtEventsMu.Unlock() + if !ok { + return + } + // 忽略错误：句柄有效时 SetEvent 不会失败 + windows.SetEvent(h) +} + +// evtfdReadFile 在 Windows 上返回 nil。 +// +// 内核侧不消费事件环（只写入），消费在插件进程里由模板的 +// windowsEvtWaiter 完成。这个函数只为跨平台签名存在。 +func evtfdReadFile(efd int) *os.File { return nil } + +// evtEventNameOf 返回某个伪 fd 对应的 Event 对象名（供注入子进程环境变量）。 +func evtEventNameOf(efd int) string { + evtEventsMu.Lock() + defer evtEventsMu.Unlock() + return evtEventNames[efd] +} + +// evtfdClose 关闭 Event 句柄。 +func evtfdClose(efd int) { + evtEventsMu.Lock() + h, ok := evtEvents[efd] + delete(evtEvents, efd) + delete(evtEventNames, efd) + evtEventsMu.Unlock() + if ok { + windows.CloseHandle(h) + } +} diff --git a/internal/plugin/proc/evtring.go b/internal/plugin/proc/evtring.go index aeddbdc..604164d 100644 --- a/internal/plugin/proc/evtring.go +++ b/internal/plugin/proc/evtring.go @@ -68,8 +68,8 @@ func evtTypeMask(types ...pubsdk.EventType) uint32 { const ( evtRingMagic uint32 = 0x48455654 // "HEVT" evtRingVersion uint32 = 1 - evtRingCap uint32 = 8192 // 2^13，满足流式场景突发（实验 4） - evtRingSlotLen uint32 = 32 // seq(8)+type(4)+off(4)+len(4)+pad(12) + evtRingCap uint32 = 8192 // 2^13，满足流式场景突发（实验 4） + evtRingSlotLen uint32 = 32 // seq(8)+type(4)+off(4)+len(4)+pad(12) evtOffMagic uint32 = 0 evtOffVersion uint32 = 4 diff --git a/internal/plugin/proc/host.go b/internal/plugin/proc/host.go index 7efa044..5c50955 100644 --- a/internal/plugin/proc/host.go +++ b/internal/plugin/proc/host.go @@ -31,10 +31,11 @@ type Host struct { shmSize int // 事件环段（独立于 StageContext） - evtfd *os.File // eventfd fd（fd 5 的句柄，子进程读取消费） - evtRing *EvtRing // 内核侧事件环句柄 - evtRingFd *os.File // 事件环段 memfd（fd 4，子进程 mmap 读事件） - evtData []byte // 事件环段 mmap 数据 + evtfd *os.File // Unix：eventfd/pipe 读端（fd 5）。Windows 为 nil，用 evtNotifyFd 。 + evtNotifyFd int // 通知句柄的平台无关标识（Unix 是真 fd，Windows 是伪 fd） + evtRing *EvtRing // 内核侧事件环句柄 + evtRingFd *os.File // Unix：事件环段 memfd（fd 4）。Windows 为 nil（命名段）。 + evtData []byte // 事件环段 mmap 数据 // evtSubscriber 由 internal/plugin 注入，coreHandler 用它接子进程的 events.subscribe 请求。 // proc 包不依赖 internal/plugin（循环依赖），故用接口类型存储。 @@ -48,11 +49,13 @@ type Host struct { // NewHost 创建共享段（平台层 allocShm + 布局初始化）。 // -// 段的分配按平台分开（shmalloc_*.go）：Linux 用 memfd，macOS 用 -// 立即 unlink 的临时文件（无 memfd_create），其余平台明确报错。 -// 两者语义一致：无文件名残留，fd 可经 ExtraFiles 传给子进程， -// 子进程 mmap 同一 inode——「全部插件共享一块段」的前提得以成立。 -// 实验 2 已验证父子 mmap 到不同虚拟地址时相对偏移仍正确解引用。 +// 段的**传递机制**按平台分开（shmalloc_*.go），但**布局**完全一致： +// - Linux：memfd，经 ExtraFiles 传继承 fd +// - macOS：立即 unlink 的临时文件（无 memfd_create），同样走 fd 继承 +// - Windows：命名 FileMapping（无 fd 继承语义），插件按名字打开 +// +// 三者共同点：全部插件看到同一份物理页，段内一律用相对偏移而非指针 +// （实验 2 已验证各进程 mmap 到不同虚拟地址时偏移解引用仍正确）。 func NewHost() (*Host, error) { memfd, data, err := allocShm(shmDefaultSize) if err != nil { @@ -78,15 +81,16 @@ func NewHost() (*Host, error) { evtRing.Init() return &Host{ - memfd: memfd, - data: data, - seg: seg, - shmSize: shmDefaultSize, - evtfd: evtfdReadFile(efd), - evtRing: evtRing, - evtRingFd: evtRingFd, - evtData: evtData, - locks: &lockRegistry{}, + memfd: memfd, + data: data, + seg: seg, + shmSize: shmDefaultSize, + evtfd: evtfdReadFile(efd), + evtNotifyFd: efd, + evtRing: evtRing, + evtRingFd: evtRingFd, + evtData: evtData, + locks: &lockRegistry{}, }, nil } @@ -117,6 +121,7 @@ func (h *Host) Close() error { h.evtfd.Close() h.evtfd = nil } + evtfdClose(h.evtNotifyFd) return firstErr } @@ -240,9 +245,16 @@ func (h *Host) ShmSize() int { return h.shmSize } // EvtRing 返回内核侧事件环句柄。 func (h *Host) EvtRing() *EvtRing { return h.evtRing } -// Evtfd 返回 eventfd 的 *os.File（供 EventRing 写通知）。 +// Evtfd 返回通知读端的 *os.File（Unix；eventfd/pipe）。 +// Windows 返回 nil——命名 Event 不是文件句柄，用 EvtNotifyFd 代替。 func (h *Host) Evtfd() *os.File { return h.evtfd } +// EvtNotifyFd 返回通知句柄的平台无关标识，供 EventRing 写通知。 +// +// Unix 是真 fd；Windows 是映射到命名 Event 句柄的伪 fd。 +// EvtfdNotify 接受这个值并按平台分派。 +func (h *Host) EvtNotifyFd() int { return h.evtNotifyFd } + // SetEvtSubscriber 注入事件环订阅接口（由 Registry 在创建 Host 后设置）。 func (h *Host) SetEvtSubscriber(sub EvtRingSubscriber) { h.evtSubscriber = sub } diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go index c20a68f..eac7b75 100644 --- a/internal/plugin/proc/plugin.go +++ b/internal/plugin/proc/plugin.go @@ -5,7 +5,6 @@ import ( "encoding/json" "fmt" "log" - "os" "sync" pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" @@ -69,10 +68,10 @@ func (p *Plugin) Start(core CoreSDK) error { } p.handler = &coreHandler{ - sdk: core, - name: p.name, - host: p.host, - locks: p.host.locks, + sdk: core, + name: p.name, + host: p.host, + locks: p.host.locks, evtRing: p.host.evtSubscriber, } // 反向调用闭包：注册回调时捕获，运行期经 RPC 打到插件进程。 @@ -82,12 +81,15 @@ func (p *Plugin) Start(core CoreSDK) error { proc, err := Spawn(p.name, p.bin, Options{ Dir: p.dir, - Env: p.env, - // 子进程 fd 布局：3=StageContext 段，4=事件环段，5=eventfd - ExtraFiles: []*os.File{p.host.memfd, p.host.evtRingFd, p.host.evtfd}, - ShmSize: p.host.shmSize, - Handler: p.handler.Handle, - OnExit: p.handleExit, + // 共享段的传递机制按平台不同（shmpass_*.go）： + // Unix 经 ExtraFiles 传继承 fd（ 3=StageContext, 4=事件环, 5=通知）； + // Windows 无 fd 继承语义，改用命名内核对象，名字经环境变量传入。 + Env: append(p.env, p.host.procEnvForShm()...), + ExtraFiles: p.host.procExtraFilesForShm(), + ShmSize: p.host.shmSize, + EvtRingSize: evtTotalSize, + Handler: p.handler.Handle, + OnExit: p.handleExit, }) if err != nil { return err diff --git a/internal/plugin/proc/process.go b/internal/plugin/proc/process.go index 16e3102..0c04f50 100644 --- a/internal/plugin/proc/process.go +++ b/internal/plugin/proc/process.go @@ -62,6 +62,8 @@ type Process struct { // shmSize 是握手时告知插件的共享段大小（0 表示本插件不用共享段）。 shmSize int + // evtRingSize 是事件环段大小（0 表示不支持事件环）。 + evtRingSize int } // RequestHandler 处理插件 → 内核的调用。 @@ -79,6 +81,8 @@ type Options struct { ExtraFiles []*os.File // ShmSize 是共享段大小，握手时告知插件（与 ExtraFiles[0] 的 memfd 对应）。 ShmSize int + // EvtRingSize 是事件环段大小（0 表示不支持事件环）。 + EvtRingSize int // Handler 处理插件反向调用。 Handler RequestHandler // OnExit 进程退出回调。 @@ -127,18 +131,19 @@ func Spawn(name, bin string, opts Options) (*Process, error) { } p := &Process{ - name: name, - bin: bin, - dir: opts.Dir, - cmd: cmd, - stdin: bufio.NewWriter(stdinPipe), - stdout: stdoutPipe, - pending: make(map[uint64]chan *Response), - handler: opts.Handler, - exited: make(chan struct{}), - ready: make(chan struct{}), - onExit: opts.OnExit, - shmSize: opts.ShmSize, + name: name, + bin: bin, + dir: opts.Dir, + cmd: cmd, + stdin: bufio.NewWriter(stdinPipe), + stdout: stdoutPipe, + pending: make(map[uint64]chan *Response), + handler: opts.Handler, + exited: make(chan struct{}), + ready: make(chan struct{}), + onExit: opts.OnExit, + shmSize: opts.ShmSize, + evtRingSize: opts.EvtRingSize, } if err := cmd.Start(); err != nil { @@ -190,6 +195,7 @@ func (p *Process) handshake(timeout time.Duration) error { PluginName: p.name, ShmVersion: shmVersion, ShmSize: p.shmSize, + EvtRingSize: p.evtRingSize, }) if err != nil { return fmt.Errorf("proc: %s 握手失败: %w", p.name, err) diff --git a/internal/plugin/proc/protocol.go b/internal/plugin/proc/protocol.go index 74515a3..0b3a7de 100644 --- a/internal/plugin/proc/protocol.go +++ b/internal/plugin/proc/protocol.go @@ -153,10 +153,10 @@ type HandshakeParams struct { Protocol int `json:"protocol"` // 内核支持的协议版本 CoreVersion string `json:"core_version"` // 内核版本（诊断用） PluginName string `json:"plugin_name"` // 内核分配的插件名 - // ShmVersion 让插件确认共享段布局一致；不匹配时插件应拒绝启动而非错读。 - ShmVersion uint32 `json:"shm_version"` - // ShmSize 是内核分配的共享段大小，插件据此 mmap（段本身经 fd 3 传入）。 - ShmSize int `json:"shm_size"` + ShmVersion uint32 `json:"shm_version"` + ShmSize int `json:"shm_size"` + // EvtRingSize 是事件环段大小（0 表示不支持事件环）。插件据此 mmap fd 4。 + EvtRingSize int `json:"evt_ring_size,omitempty"` } // HandshakeResult 是插件 → 内核的建链应答：上报自身信息。 diff --git a/internal/plugin/proc/shmalloc_other.go b/internal/plugin/proc/shmalloc_other.go index 06175e1..abb7b30 100644 --- a/internal/plugin/proc/shmalloc_other.go +++ b/internal/plugin/proc/shmalloc_other.go @@ -1,4 +1,4 @@ -//go:build !linux && !darwin +//go:build !linux && !darwin && !windows package proc diff --git a/internal/plugin/proc/shmalloc_windows.go b/internal/plugin/proc/shmalloc_windows.go new file mode 100644 index 0000000..8ed9d1e --- /dev/null +++ b/internal/plugin/proc/shmalloc_windows.go @@ -0,0 +1,137 @@ +//go:build windows + +package proc + +import ( + "fmt" + "os" + "sync" + "sync/atomic" + "unsafe" + + "golang.org/x/sys/windows" +) + +// Windows 侧共享段：命名 FileMapping + 命名 Event。 +// +// 与 Unix 的机制差异（不是能力差异）： +// Windows 没有 fd 继承语义——os/exec 的 ExtraFiles 在 Windows 实现里不被支持。 +// 等价机制是命名内核对象：父进程 CreateFileMappingW 建带名字的段， +// 子进程 OpenFileMappingW 按同名打开，拿到同一份物理页。 +// +// **这是 §9.2 的正解**。C ABI 时代 Windows 是第三套独立 ABI 实现 +// （dynamic_dll_windows.go），stage 只下发 3 字段且完全没有写回， +// sanitizer 这类改写型插件静默失效。三套 ABI 收敛为单一 RPC 后， +// Windows 与 Unix 共用同一份 stage 逻辑与同一份共享段布局， +// 平台差异只剩本文件的创建端 + 插件侧模板的打开端。 +// +// 名字带 PID 与递增序号：多个 homed 实例并存时不能撞名， +// 同一实例内 StageContext 段与事件环段也必须分开。 +var shmNameSeq atomic.Uint64 + +const ( + shmNamePrefix = "Local\\HomeAgentShm" + evtRingNamePfx = "Local\\HomeAgentEvtRing" + evtEventNamePfx = "Local\\HomeAgentEvtSignal" + envStageShmName = "HOMEAGENT_SHM_STAGE" + envEvtRingName = "HOMEAGENT_SHM_EVTRING" + envEvtEventName = "HOMEAGENT_EVT_EVENT" +) + +// namedShm 持有一块命名共享段。 +// +// 不用 *os.File 承载：Windows 的 FileMapping 句柄不是文件句柄， +// 包进 os.File 后 Close 语义不对（会尝试当文件关）。故用独立类型， +// 由 shmHandles 表按 mmap 地址反查——freeShm 只拿到 (*os.File, []byte)。 +type namedShm struct { + name string + mapping windows.Handle + addr uintptr + size int +} + +// shmHandles 记录已分配的段，供 freeShm 按数据指针反查句柄。 +// +// 为何需要这张表：allocShm 的跨平台签名返回 (*os.File, []byte)， +// Windows 没有对应的 fd，只能把句柄存在旁路。key 用切片首地址。 +var ( + shmHandles = map[uintptr]*namedShm{} + shmHandlesMu sync.Mutex +) + +// allocShm 创建命名共享段并映射。 +// +// 返回的 *os.File 为 nil：Windows 不经 fd 传递段，插件按名字打开。 +// 名字通过 procEnvForShm 注入子进程环境变量。 +func allocShm(size int) (*os.File, []byte, error) { + name := fmt.Sprintf("%s_%d_%d", shmNamePrefix, os.Getpid(), shmNameSeq.Add(1)) + shm, data, err := createNamedMapping(name, size) + if err != nil { + return nil, nil, err + } + shmHandlesMu.Lock() + shmHandles[uintptr(unsafe.Pointer(&data[0]))] = shm + shmHandlesMu.Unlock() + return nil, data, nil +} + +// createNamedMapping 建命名段并映射为 []byte。 +func createNamedMapping(name string, size int) (*namedShm, []byte, error) { + namePtr, err := windows.UTF16PtrFromString(name) + if err != nil { + return nil, nil, fmt.Errorf("proc: 共享段名字非法 %q: %w", name, err) + } + + // INVALID_HANDLE_VALUE + 命名 → 由系统页文件支撑的匿名段（不落盘） + mapping, err := windows.CreateFileMapping( + windows.InvalidHandle, nil, windows.PAGE_READWRITE, + uint32(uint64(size)>>32), uint32(size), namePtr) + if err != nil { + return nil, nil, fmt.Errorf("proc: 创建命名共享段 %q: %w", name, err) + } + + addr, err := windows.MapViewOfFile(mapping, windows.FILE_MAP_WRITE, 0, 0, uintptr(size)) + if err != nil { + windows.CloseHandle(mapping) + return nil, nil, fmt.Errorf("proc: 映射共享段 %q: %w", name, err) + } + + return &namedShm{name: name, mapping: mapping, addr: addr, size: size}, + unsafe.Slice((*byte)(unsafe.Pointer(addr)), size), nil +} + +// freeShm 解除映射并关闭段句柄。 +func freeShm(f *os.File, data []byte) error { + if len(data) == 0 { + return nil + } + key := uintptr(unsafe.Pointer(&data[0])) + shmHandlesMu.Lock() + shm, ok := shmHandles[key] + delete(shmHandles, key) + shmHandlesMu.Unlock() + if !ok { + return nil + } + var firstErr error + if err := windows.UnmapViewOfFile(shm.addr); err != nil { + firstErr = err + } + if err := windows.CloseHandle(shm.mapping); err != nil && firstErr == nil { + firstErr = err + } + return firstErr +} + +// shmNameOf 返回某块已分配段的名字（供注入子进程环境变量）。 +func shmNameOf(data []byte) string { + if len(data) == 0 { + return "" + } + shmHandlesMu.Lock() + defer shmHandlesMu.Unlock() + if shm, ok := shmHandles[uintptr(unsafe.Pointer(&data[0]))]; ok { + return shm.name + } + return "" +} diff --git a/internal/plugin/proc/shmpass_unix.go b/internal/plugin/proc/shmpass_unix.go new file mode 100644 index 0000000..daec8b2 --- /dev/null +++ b/internal/plugin/proc/shmpass_unix.go @@ -0,0 +1,21 @@ +//go:build linux || darwin || freebsd + +package proc + +import "os" + +// procEnvForShm 在 Unix 返回 nil：段经继承 fd 传递，无需环境变量。 +func (h *Host) procEnvForShm() []string { return nil } + +// procExtraFilesForShm 返回经 ExtraFiles 传给子进程的 fd 列表。 +// +// 顺序即 fd 编号（cmd.ExtraFiles[0] → 子进程 fd 3）： +// +// fd 3 = StageContext 段 +// fd 4 = 事件环段 +// fd 5 = 事件通知（eventfd / pipe 读端） +// +// 插件侧模板 z_proc_shm_unix.go 的常量与此严格对应。 +func (h *Host) procExtraFilesForShm() []*os.File { + return []*os.File{h.memfd, h.evtRingFd, h.evtfd} +} diff --git a/internal/plugin/proc/shmpass_windows.go b/internal/plugin/proc/shmpass_windows.go new file mode 100644 index 0000000..66e9b44 --- /dev/null +++ b/internal/plugin/proc/shmpass_windows.go @@ -0,0 +1,26 @@ +//go:build windows + +package proc + +import ( + "fmt" + "os" +) + +// procEnvForShm 返回子进程挂载共享段所需的环境变量（Windows）。 +// +// Windows 没有 fd 继承语义（os/exec 的 ExtraFiles 在 Windows 不被支持）， +// 故段与事件对象的**名字**经环境变量传给子进程，插件侧模板的 +// z_proc_shm_windows.go 按同名 OpenFileMappingW / OpenEventW 打开。 +// +// 名字带 PID 与递增序号：多个 homed 实例并存时不能撞名。 +func (h *Host) procEnvForShm() []string { + return []string{ + fmt.Sprintf("HOMEAGENT_SHM_STAGE=%s", shmNameOf(h.data)), + fmt.Sprintf("HOMEAGENT_SHM_EVTRING=%s", shmNameOf(h.evtData)), + fmt.Sprintf("HOMEAGENT_EVT_EVENT=%s", evtEventNameOf(h.evtNotifyFd)), + } +} + +// procExtraFilesForShm 在 Windows 返回 nil：段不经 fd 传递。 +func (h *Host) procExtraFilesForShm() []*os.File { return nil } From b20121f703da9d7cfa4a0aeba51714844a223f17 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 19:26:40 +0800 Subject: [PATCH 18/27] =?UTF-8?q?plugin:=20=E5=88=A0=E9=99=A4=20C=20ABI=20?= =?UTF-8?q?=E9=80=9A=E9=81=93=EF=BC=88Part=206.2=20=E5=AE=8C=E6=88=90?= =?UTF-8?q?=EF=BC=8C-3198=20=E8=A1=8C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 外部插件统一走子进程 + stdio RPC，三套独立 ABI 实现收敛为单一 RPC 实现。 用户决策：彻底舍弃 .so 能力，不保留双通道回退。 ## 删除清单 internal/plugin/cabi/ 1156 行（loader.go/loader.c/types.go/output_test.go） internal/plugin/dynamic_dll_windows.go 272 行（§9.2 记录的能力退化实现） internal/plugin/dynamic_loader_unix.go 79 行（唯一 cabi 引用点） internal/plugin/dynamic_dll_test.go 32 行 internal/plugin/dynamic_dll_stub.go 11 行 internal/plugin/dynamic_loader_windows.go 11 行 internal/plugin/bridge_e2e_test.go （测的是 cabi 路径） third_party/.../plugindev/templates.go 1296 行（取消跟踪，SDK 仓才是权威副本） dynamic.go：entryCABI 通道删除，soEntry/dllEntry 常量删除。 registry.go：tryDynamic 探测顺序从 .so → .dll → .lua 变成 proc → lua。 ## 旧 .so 给明确错误，不静默跳过 静默跳过会让「插件目录在但没加载」看起来像配置问题，而实际原因是需要 用新版 plugindev 重编。故保留 legacyCABIEntries 表专门用于识别残留： plugin legacy: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。 外部插件已改为子进程模式，请用新版 plugindev 重编产出 plugin.bin （业务代码无需修改） 错误消息里「业务代码无需修改」这句是有测试守着的——迁移的核心承诺就是它。 ## pluginmgr 安装逻辑跟进 bundle 命名 子进程模式下各平台产物统一叫 plugin.bin（进程边界即 ABI 边界），故 zip 内 按平台加后缀 plugin.bin..，解包时挑当前平台那一份重命名。 platformBinary 改为按 runtime.GOOS+GOARCH 生成条目名；platformBinaries 固定表 换成 isPlatformBinary 前缀判断（平台组合会增长：linux/arm64、darwin/arm64…， 按前缀判断无需维护清单）。 新增 chmod 0755：zip 保留了原权限位，但经某些工具链/传输后可能丢失， 内核加载时会因缺执行位报错。提前补上比事后让用户 chmod 更好。 ## 测试 entry_dispatch_test.go 重写（12 项）： - classifyEntry 对 .so/.dll/.dylib 现在返回 unknown - LegacyManifestFallsBackToProbe：存量插件 manifest 仍写 "plugin.so" （17 个插件没人去改），须靠目录探测找到 plugin.bin —— 这是 「外部插件零改动」的直接后果 - LegacyCABIGivesActionableError：错误消息须含 plugindev / plugin.bin / 业务代码 - PluginEntryHash_IgnoresLegacyCABI：.so 不参与 hash（内核已不认它） upgrade_test.go 的 .hmap 构造改用 plugin.bin。 验证：go build ./... 通过；go test ./... 全仓无失败； go test -race ./internal/plugin/... 全绿；三平台构建通过。 Ref: docs/zh/架构迁移评估.md §3.1/§9.2、docs/zh/plugin-migration-plan.md Part 6 --- internal/plugin/bridge_e2e_test.go | 262 ---- internal/plugin/cabi/loader.c | 79 - internal/plugin/cabi/loader.go | 998 ------------- internal/plugin/cabi/output_test.go | 92 -- internal/plugin/cabi/types.go | 66 - internal/plugin/dynamic.go | 50 +- internal/plugin/dynamic_dll_stub.go | 11 - internal/plugin/dynamic_dll_test.go | 32 - internal/plugin/dynamic_dll_windows.go | 272 ---- internal/plugin/dynamic_loader_unix.go | 79 - internal/plugin/dynamic_loader_windows.go | 11 - internal/plugin/entry_dispatch_test.go | 126 +- internal/plugin/registry.go | 38 +- internal/plugins/pluginmgr/plugin.go | 66 +- internal/plugins/pluginmgr/upgrade_test.go | 16 +- .../tools/plugindev/templates.go | 1296 ----------------- 16 files changed, 176 insertions(+), 3318 deletions(-) delete mode 100644 internal/plugin/bridge_e2e_test.go delete mode 100644 internal/plugin/cabi/loader.c delete mode 100644 internal/plugin/cabi/loader.go delete mode 100644 internal/plugin/cabi/output_test.go delete mode 100644 internal/plugin/cabi/types.go delete mode 100644 internal/plugin/dynamic_dll_stub.go delete mode 100644 internal/plugin/dynamic_dll_test.go delete mode 100644 internal/plugin/dynamic_dll_windows.go delete mode 100644 internal/plugin/dynamic_loader_unix.go delete mode 100644 internal/plugin/dynamic_loader_windows.go delete mode 100644 third_party/homeagent-sdk/tools/plugindev/templates.go diff --git a/internal/plugin/bridge_e2e_test.go b/internal/plugin/bridge_e2e_test.go deleted file mode 100644 index f5969b1..0000000 --- a/internal/plugin/bridge_e2e_test.go +++ /dev/null @@ -1,262 +0,0 @@ -//go:build windows - -package plugin - -import ( - "encoding/json" - "os" - "path/filepath" - "syscall" - "testing" - "unsafe" - - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -func TestBridgeE2E_WebPlugin(t *testing.T) { - exeDir, _ := os.Executable() - // Find web example build relative to the homeagent repo root - haRoot := findHomeAgentRoot(t, exeDir) - dllPath := filepath.Join(haRoot, "..", "homeagentsdk", "example", "web", "build", "plugin.dll") - if _, err := os.Stat(dllPath); os.IsNotExist(err) { - t.Fatalf("web plugin DLL not found at %s\nRun: cd example/web && plugindev build --target windows/amd64", dllPath) - } - - // Track captured tools and stages - var capturedTools []sdk.ToolDef - var capturedStages []sdk.Stage - - regTool := func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error { - capturedTools = append(capturedTools, def) - t.Logf(" registered tool: %s", name) - return nil - } - regStage := func(stage sdk.Stage, handler sdk.StageHandler) { - capturedStages = append(capturedStages, stage) - t.Logf(" registered stage: %s", stage) - } - regAPI := func(name string) error { - t.Logf(" registered API: %s", name) - return nil - } - - sett := sdk.NewSettings("web", nil) - psdk := sdk.New("web", sdk.SDKConfig{Settings: sett, RegTool: regTool, RegStage: regStage, RegAPI: regAPI}) - - plg, err := newDLLPlugin(dllPath, "web", nil) - if err != nil { - t.Fatalf("newDLLPlugin failed: %v", err) - } - defer plg.Stop() - - // Start — this calls NewPlugin + StartPlugin + registerTools + registerStages - if err := plg.Start(psdk); err != nil { - t.Fatalf("Start failed: %v", err) - } - - // Verify tools were captured - if len(capturedTools) == 0 { - t.Fatal("no tools were registered by web plugin") - } - t.Logf("Captured %d tools:", len(capturedTools)) - for _, d := range capturedTools { - t.Logf(" - %s: %s", d.Name, d.Description[:min(len(d.Description), 60)]) - } - - // Check specific expected tools - webSearch, webFetch := false, false - for _, d := range capturedTools { - if d.Name == "web_search" { - webSearch = true - if d.Description == "" { - t.Error("web_search has empty description") - } - params := d.Parameters - if params == nil { - t.Error("web_search has nil parameters") - } else { - if _, ok := params["properties"]; !ok { - t.Error("web_search parameters missing 'properties'") - } - } - } - if d.Name == "web_fetch" { - webFetch = true - } - } - if !webSearch { - t.Error("expected tool 'web_search' not registered") - } - if !webFetch { - t.Error("expected tool 'web_fetch' not registered") - } - - // Verify bridge exports work via direct C ABI calls - t.Logf("Bridge exports: getTools=%x invokeTool=%x freeCStr=%x", - plg.getTools, plg.invokeTool, plg.freeCStr) - - // GetToolDefsJSON - if plg.getTools != 0 { - toolDefsJSON := callGetToolDefsJSON(t, plg) - if len(toolDefsJSON) == 0 { - t.Error("GetToolDefsJSON returned empty array, expected tools") - } - for _, d := range toolDefsJSON { - t.Logf(" bridge tool: %s", d["name"]) - } - } - - // InvokeToolJSON — test with the search tool - if plg.invokeTool != 0 { - result := callInvokeToolJSON(t, plg, "web_search", map[string]interface{}{ - "query": "test", - "count": 1, - }) - t.Logf("InvokeToolJSON result keys: %v", keysOfMap(result)) - // Should get a result map (might be error if no network, but should not crash) - if errStr, ok := result["error"]; ok { - t.Logf(" (expected — tool returned error: %v)", errStr) - } - } -} - -func TestBridgeE2E_SanitizerStages(t *testing.T) { - exeDir, _ := os.Executable() - haRoot := findHomeAgentRoot(t, exeDir) - dllPath := filepath.Join(haRoot, "..", "homeagentsdk", "example", "sanitizer", "build", "plugin.dll") - if _, err := os.Stat(dllPath); os.IsNotExist(err) { - t.Skip("sanitizer DLL not built") - } - - var capturedStages []sdk.Stage - regStage := func(stage sdk.Stage, handler sdk.StageHandler) { - capturedStages = append(capturedStages, stage) - t.Logf(" registered stage: %s", stage) - } - - sett := sdk.NewSettings("sanitizer", nil) - psdk := sdk.New("sanitizer", sdk.SDKConfig{Settings: sett, - RegTool: func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error { return nil }, - RegStage: regStage, - RegAPI: func(name string) error { return nil }, - }) - - plg, err := newDLLPlugin(dllPath, "sanitizer", nil) - if err != nil { - t.Fatalf("newDLLPlugin failed: %v", err) - } - defer plg.Stop() - - if err := plg.Start(psdk); err != nil { - t.Fatalf("Start failed: %v", err) - } - - if len(capturedStages) == 0 { - t.Fatal("no stages registered by sanitizer") - } - found := false - for _, s := range capturedStages { - if s == sdk.StagePostAction { - found = true - } - } - if !found { - t.Fatalf("expected post_action stage, got %v", capturedStages) - } - - // Verify bridge GetStagesJSON - if plg.getStages != 0 { - ret, _, _ := syscall.SyscallN(plg.getStages, plg.handle) - if ret != 0 { - stagesJSON := cStringPtrToString(ret) - if plg.freeCStr != 0 { - syscall.SyscallN(plg.freeCStr, ret) - } - t.Logf("GetStagesJSON: %s", stagesJSON) - if !contains(t, stagesJSON, "post_action") { - t.Error("GetStagesJSON missing post_action") - } - } - } -} - -// --- helpers --- - -func findHomeAgentRoot(t *testing.T, exeDir string) string { - t.Helper() - // Walk up from test binary directory looking for homeagent/ - dir := exeDir - for i := 0; i < 10; i++ { - if _, err := os.Stat(filepath.Join(dir, "internal", "plugin")); err == nil { - return dir - } - parent := filepath.Dir(dir) - if parent == dir { - break - } - dir = parent - } - t.Fatal("cannot find homeagent root") - return "" -} - -func callGetToolDefsJSON(t *testing.T, plg *dllPlugin) []map[string]interface{} { - t.Helper() - ret, _, _ := syscall.SyscallN(plg.getTools, plg.handle) - if ret == 0 { - t.Fatal("GetToolDefsJSON returned nil") - } - jsonStr := cStringPtrToString(ret) - if plg.freeCStr != 0 { - syscall.SyscallN(plg.freeCStr, ret) - } - var defs []map[string]interface{} - if err := json.Unmarshal([]byte(jsonStr), &defs); err != nil { - t.Fatalf("GetToolDefsJSON parse error: %v", err) - } - return defs -} - -func callInvokeToolJSON(t *testing.T, plg *dllPlugin, toolName string, args map[string]interface{}) map[string]interface{} { - t.Helper() - argsJSON, _ := json.Marshal(args) - cToolName := append([]byte(toolName), 0) - cArgs := append(argsJSON, 0) - - ret, _, _ := syscall.SyscallN( - plg.invokeTool, - plg.handle, - uintptr(unsafe.Pointer(&cToolName[0])), - uintptr(unsafe.Pointer(&cArgs[0])), - ) - if ret == 0 { - t.Fatal("InvokeToolJSON returned nil") - } - jsonStr := cStringPtrToString(ret) - if plg.freeCStr != 0 { - syscall.SyscallN(plg.freeCStr, ret) - } - var result map[string]interface{} - if err := json.Unmarshal([]byte(jsonStr), &result); err != nil { - t.Fatalf("InvokeToolJSON parse error: %v (json=%s)", err, jsonStr) - } - return result -} - -func keysOfMap(m map[string]interface{}) []string { - var keys []string - for k := range m { - keys = append(keys, k) - } - return keys -} - -func contains(t *testing.T, s, substr string) bool { - t.Helper() - for i := 0; i <= len(s)-len(substr); i++ { - if s[i:i+len(substr)] == substr { - return true - } - } - return false -} diff --git a/internal/plugin/cabi/loader.c b/internal/plugin/cabi/loader.c deleted file mode 100644 index bc16f07..0000000 --- a/internal/plugin/cabi/loader.c +++ /dev/null @@ -1,79 +0,0 @@ -//go:build linux || darwin - -// HomeAgent C ABI loader — C implementation (compiled alongside Go code via cgo) - -#include -#include -#include - -// HOMEAGENT_ABI_VERSION 与 internal/meta/meta.go CABINum 同步（major*100+minor，v0.9.x→900）。 -// C ABI 通过 version/version_min 协商，旧插件不受影响。 -#define HOMEAGENT_ABI_VERSION 900 - -// PluginAPI — provided by the plugin -typedef struct { - int version; int version_min; - int (*init_plugin)(char*, char*, char**); - int (*start_plugin)(void*, int, char**); - int (*stop_plugin)(char**); - int (*invoke_tool)(char*, char*, char**, char**); - int (*invoke_stage)(char*, char*, char**, char**); - int (*invoke_output)(char*, char*, char*, char**); - void (*free_string)(char*); -} plugin_api_t; - -// CoreAPI — provided by the core -typedef struct { - int version; int version_min; - int (*dispatch)(int, void*, char*, char*, char*, int, int, char**, char**); - void* ctx; -} core_api_t; - -// Forward declare Go dispatch function -extern int go_core_dispatch(int, void*, char*, char*, char*, int, int, char**, char**); - -// Bridge function called by CoreAPI.dispatch -static int dispatch_bridge(int id, void* ctx, char* s1, char* s2, char* s3, int i1, int i2, char** r, char** e) { - return go_core_dispatch(id, ctx, s1, s2, s3, i1, i2, r, e); -} - -// Create a CoreAPI struct -core_api_t* make_core_api(void) { - core_api_t* api = (core_api_t*)malloc(sizeof(core_api_t)); - if (!api) return NULL; - api->version = HOMEAGENT_ABI_VERSION; - api->version_min = HOMEAGENT_ABI_VERSION; - api->dispatch = dispatch_bridge; - api->ctx = NULL; - return api; -} - -void free_core_api(core_api_t* api) { free(api); } - -// dlopen helpers -typedef void* lib_handle; - -lib_handle lib_open(const char* path) { - return dlopen(path, RTLD_NOW | RTLD_LOCAL); -} - -plugin_api_t* lib_get_api(lib_handle h) { - plugin_api_t* (*fn)(void); - *(void**)(&fn) = dlsym(h, "plugin_init"); - if (!fn) return NULL; - return fn(); -} - -void lib_close(lib_handle h) { dlclose(h); } -char* lib_err(void) { return dlerror(); } - -void api_free_string(plugin_api_t* api, char* ptr) { - if (api && api->free_string) api->free_string(ptr); -} - -int call_init_plugin(plugin_api_t* api, char* name, char* config, char** err) { return api->init_plugin(name, config, err); } -int call_start_plugin(plugin_api_t* api, void* core, int ver, char** err) { return api->start_plugin(core, ver, err); } -int call_stop_plugin(plugin_api_t* api, char** err) { return api->stop_plugin(err); } -int call_invoke_tool(plugin_api_t* api, char* n, char* a, char** r, char** e) { return api->invoke_tool(n, a, r, e); } -int call_invoke_stage(plugin_api_t* api, char* s, char* c, char** r, char** e) { return api->invoke_stage(s, c, r, e); } -int call_invoke_output(plugin_api_t* api, char* c, char* m, char* p, char** e) { return api->invoke_output(c, m, p, e); } diff --git a/internal/plugin/cabi/loader.go b/internal/plugin/cabi/loader.go deleted file mode 100644 index 6e666d5..0000000 --- a/internal/plugin/cabi/loader.go +++ /dev/null @@ -1,998 +0,0 @@ -//go:build linux || darwin - -package cabi - -/* -#cgo LDFLAGS: -ldl -#include - -// HOMEAGENT_ABI_VERSION 是当前内核的 C ABI 整数协商版本，由 internal/meta/meta.go CABINum 派生 -// （major*100 + minor，随核心版本号映射：v0.8.x→800，v0.9.x→900）。 -// 旧插件使用低整数版本不受影响——C ABI wrapper 通过 version/version_min 字段协商兼容。 -#define HOMEAGENT_ABI_VERSION 900 - -// PluginAPI — provided by the plugin via plugin_init() -typedef struct { - int version; int version_min; - int (*init_plugin)(char*, char*, char**); - int (*start_plugin)(void*, int, char**); - int (*stop_plugin)(char**); - int (*invoke_tool)(char*, char*, char**, char**); - int (*invoke_stage)(char*, char*, char**, char**); - int (*invoke_output)(char*, char*, char*, char**); - void (*free_string)(char*); -} plugin_api_t; - -// CoreAPI — provided by the core via start_plugin() -typedef struct { - int version; int version_min; - int (*dispatch)(int, void*, char*, char*, char*, int, int, char**, char**); - void* ctx; -} core_api_t; - -// Functions implemented in loader.c -extern core_api_t* make_core_api(void); -extern void free_core_api(core_api_t* api); -extern int call_init_plugin(plugin_api_t*, char*, char*, char**); -extern int call_start_plugin(plugin_api_t*, void*, int, char**); -extern int call_stop_plugin(plugin_api_t*, char**); -extern int call_invoke_tool(plugin_api_t*, char*, char*, char**, char**); -extern int call_invoke_stage(plugin_api_t*, char*, char*, char**, char**); -extern int call_invoke_output(plugin_api_t*, char*, char*, char*, char**); -extern void api_free_string(plugin_api_t*, char*); -extern void* lib_open(const char*); -extern plugin_api_t* lib_get_api(void*); -extern void lib_close(void*); -extern char* lib_err(void); -*/ -import "C" -import ( - "encoding/json" - "fmt" - "log" - "sync" - "sync/atomic" - "time" - "unsafe" - - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -// outputSendTimeout 是 output_send 等待通道真实发送确认的超时。 -// 超过该时间仍未收到插件确认，返回 unconfirmed（结果未知）而非谎报成功。 -// （plan.md 11.1） -const outputSendTimeout = 10 * time.Second - -var ( - pluginMap sync.Map // int32 pluginID → *pluginState - nextID int32 -) - -type pluginState struct { - id int32 - name string - sdk *sdk.PluginSDK - api *C.plugin_api_t -} - -// Handle represents a loaded C ABI plugin. -type Handle struct { - soPath string - lib unsafe.Pointer - api *C.plugin_api_t - core *C.core_api_t - pstate *pluginState -} - -// Load opens a .so plugin and initializes it via C ABI. -func Load(soPath, name string, config map[string]interface{}) (*Handle, error) { - cPath := C.CString(soPath) - defer C.free(unsafe.Pointer(cPath)) - - lib := C.lib_open(cPath) - if lib == nil { - return nil, fmt.Errorf("dlopen %s: %s", soPath, C.GoString(C.lib_err())) - } - - api := C.lib_get_api(lib) - if api == nil { - C.lib_close(lib) - return nil, fmt.Errorf("dlsym plugin_init in %s: %s", soPath, C.GoString(C.lib_err())) - } - if int(api.version) < 1 || api.init_plugin == nil { - C.lib_close(lib) - return nil, fmt.Errorf("plugin %s: invalid PluginAPI (version=%d)", name, int(api.version)) - } - if int(api.version) > CABINum { - C.lib_close(lib) - return nil, fmt.Errorf("plugin %s: ABI version %d > core %d (v%s), requires newer HomeAgent core", name, int(api.version), CABINum, ABIVersion) - } - - if int(api.version) < CABINumMin { - C.lib_close(lib) - return nil, fmt.Errorf("plugin %s: ABI version %d < core min %d (v%s), plugin too old", name, int(api.version), CABINumMin, ABIVersionMin) - } - - id := atomic.AddInt32(&nextID, 1) - ps := &pluginState{id: id, name: name, api: api} - pluginMap.Store(id, ps) - - handle := &Handle{soPath: soPath, lib: lib, api: api, pstate: ps} - - // Create CoreAPI later — done via CreateCoreAPI - - // Initialize plugin - configJSON, _ := json.Marshal(config) - cName := C.CString(name) - cConfig := C.CString(string(configJSON)) - var initErr *C.char - defer C.free(unsafe.Pointer(cName)) - defer C.free(unsafe.Pointer(cConfig)) - - if ret := int(C.call_init_plugin(api, cName, cConfig, &initErr)); ret != 0 { - errMsg := "" - if initErr != nil { - errMsg = C.GoString(initErr) - C.api_free_string(api, initErr) - } - handle.Close() - return nil, fmt.Errorf("init_plugin %s: %s", name, errMsg) - } - - return handle, nil -} - -// CreateCoreAPI creates a CoreAPI struct for this plugin. -// The CoreAPI dispatches all SDK calls back to Go, routing to the plugin's PluginSDK. -func (h *Handle) CreateCoreAPI(s *sdk.PluginSDK) unsafe.Pointer { - core := C.make_core_api() - if core == nil { - return nil - } - h.core = core - h.pstate.sdk = s - - // Store plugin ID as context (safe integer, not a Go pointer) - core.ctx = unsafe.Pointer(uintptr(h.pstate.id)) - - return unsafe.Pointer(core) -} - -// FreeCoreAPI frees the CoreAPI struct. -func (h *Handle) FreeCoreAPI() { - if h.core != nil { - C.free_core_api(h.core) - h.core = nil - } -} - -// Start calls the plugin's Start with a CoreAPI pointer. -func (h *Handle) Start(corePtr unsafe.Pointer) error { - var cErr *C.char - if ret := int(C.call_start_plugin(h.api, corePtr, C.int(CABINum), &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(h.api, cErr) - } - return fmt.Errorf("start_plugin: %s", errMsg) - } - return nil -} - -// Stop calls the plugin's Stop. -func (h *Handle) Stop() error { - var cErr *C.char - if ret := int(C.call_stop_plugin(h.api, &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(h.api, cErr) - } - return fmt.Errorf("stop_plugin: %s", errMsg) - } - return nil -} - -// InvokeTool calls a tool handler in the plugin. -func (h *Handle) InvokeTool(name string, args map[string]interface{}) (map[string]interface{}, error) { - argsJSON, _ := json.Marshal(args) - cName := C.CString(name) - cArgs := C.CString(string(argsJSON)) - var result, cErr *C.char - defer C.free(unsafe.Pointer(cName)) - defer C.free(unsafe.Pointer(cArgs)) - - if ret := int(C.call_invoke_tool(h.api, cName, cArgs, &result, &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(h.api, cErr) - } - return nil, fmt.Errorf("invoke_tool %s: %s", name, errMsg) - } - if result == nil { - return nil, nil - } - defer C.api_free_string(h.api, result) - var r map[string]interface{} - if err := json.Unmarshal([]byte(C.GoString(result)), &r); err != nil { - return nil, err - } - return r, nil -} - -// Close unloads the plugin library. -func (h *Handle) Close() { - if h.lib != nil { - C.lib_close(h.lib) - h.lib = nil - } -} - -// ---- plugin invocation helpers (stateless, use pluginMap lookup) ---- - -func pluginInvokeTool(pluginID int32, name, argsJSON string) (string, error) { - v, ok := pluginMap.Load(pluginID) - if !ok { - return "", fmt.Errorf("plugin %d not found", pluginID) - } - ps := v.(*pluginState) - if ps.api == nil { - return "", fmt.Errorf("plugin %d: nil api", pluginID) - } - cName := C.CString(name) - cArgs := C.CString(argsJSON) - var result, cErr *C.char - defer C.free(unsafe.Pointer(cName)) - defer C.free(unsafe.Pointer(cArgs)) - if ret := int(C.call_invoke_tool(ps.api, cName, cArgs, &result, &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(ps.api, cErr) - } - return "", fmt.Errorf("invoke_tool %s: %s", name, errMsg) - } - if result == nil { - return "", nil - } - defer C.api_free_string(ps.api, result) - return C.GoString(result), nil -} - -// awaitOutputResult 在 goroutine 内执行真正的 cgo 发送调用，并等待其结果： -// - 发送成功 → {status: sent} -// - 发送失败 → 返回 error（模型可感知并重试），不再像旧实现那样谎报成功 -// - 超时未确认 → {status: unconfirmed}（结果未知，不谎报成功/失败） -// -// 为什么用 goroutine + channel 而不是直接同步调用：pluginInvokeOutput 是 cgo 调用， -// 不能嵌套在 cgo 栈上执行（cgo within cgo 会崩溃）。本 handler 由 executeOutputSendTool -// 从 Go 侧调起（不在 cgo 栈内），所以这里启动子 goroutine 执行 cgo 调用并等待其结果， -// 不构成嵌套。 -// -// 修复 plan.md 11.1：旧实现无条件返回 {status: queued} + err=nil，模型永远收到「已发送」 -// 而实际失败（如 meta 缺 user_id）只写日志，模型无法感知、不会重试。 -func awaitOutputResult(pid int32, channel, argsJSON string) (interface{}, error) { - return awaitOutputResultWith(pid, channel, argsJSON, pluginInvokeOutput, outputSendTimeout) -} - -// awaitOutputResultWith 是 awaitOutputResult 的可注入版本（供单测替换 cgo 发送与超时）。 -func awaitOutputResultWith( - pid int32, - channel, argsJSON string, - invoke func(pluginID int32, channel, payload string) error, - timeout time.Duration, -) (interface{}, error) { - resCh := make(chan error, 1) - go func() { resCh <- invoke(pid, channel, argsJSON) }() - select { - case err := <-resCh: - if err != nil { - log.Printf("[dispatch] output %s failed: %v", channel, err) - return nil, err - } - log.Printf("[dispatch] output %s OK", channel) - return map[string]interface{}{"status": "sent"}, nil - case <-time.After(timeout): - // 超时未确认：插件仍在后台发送，结果未知。不谎报成功，也不谎报失败。 - log.Printf("[dispatch] output %s 等待确认超时（%s），插件仍在后台发送", channel, timeout) - return map[string]interface{}{ - "status": "unconfirmed", - "note": fmt.Sprintf("发送已提交但 %s 内未收到通道确认，结果未知；如需确认请查询该通道状态", timeout), - }, nil - } -} - -func pluginInvokeOutput(pluginID int32, channel, payload string) error { - v, ok := pluginMap.Load(pluginID) - if !ok { - return fmt.Errorf("plugin %d not found", pluginID) - } - ps := v.(*pluginState) - if ps.api == nil { - return fmt.Errorf("plugin %d: nil api", pluginID) - } - cCh := C.CString(channel) - cPayload := C.CString(payload) - var cErr *C.char - defer C.free(unsafe.Pointer(cCh)) - defer C.free(unsafe.Pointer(cPayload)) - if ret := int(C.call_invoke_output(ps.api, cCh, nil, cPayload, &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(ps.api, cErr) - } - return fmt.Errorf("invoke_output %s: %s", channel, errMsg) - } - return nil -} - -// applyStageResult 将插件回传的修改后上下文应用回内核 StageContext。 -// 只回写插件有权改写的字段（RawMessage/LLMText/FinalText/Response/ToolResults/NoMemory）。 -func applyStageResult(sc *sdk.StageContext, resultJSON string) { - var m map[string]interface{} - if err := json.Unmarshal([]byte(resultJSON), &m); err != nil { - return - } - sc.Lock() - defer sc.Unlock() - if v, ok := m["raw_message"].(string); ok { - sc.RawMessage = v - } - if v, ok := m["llm_text"].(string); ok { - sc.LLMText = v - } - if v, ok := m["final_text"].(string); ok { - sc.FinalText = v - } - if v, ok := m["user_id"].(string); ok { - sc.UserID = v - } - if v, ok := m["group_id"].(string); ok { - sc.GroupID = v - } - if v, ok := m["no_memory"].(bool); ok { - sc.NoMemory = v - } - if v, ok := m["response"].(string); ok { - vv := v - sc.Response = &vv - } - if v, ok := m["tool_calls"].([]interface{}); ok { - // 注意不要加 len(v)>0 条件：ABI v2 diff 回传（plan.md 11.3）下，插件拒绝全部 - // 工具调用时会显式回传 `[]`，必须能表达「清空」。旧插件（全量回传）仅在 - // len>0 时才带该键，因此不会因此变更而被误清空。 - if b, err := json.Marshal(v); err == nil { - var tcs []sdk.ToolCall - if json.Unmarshal(b, &tcs) == nil { - sc.ToolCalls = tcs - } - } - } - if v, ok := m["tool_results"].([]interface{}); ok { - if b, err := json.Marshal(v); err == nil { - var trs []sdk.ToolResult - if json.Unmarshal(b, &trs) == nil { - sc.ToolResults = trs - } - } - } -} - -func pluginInvokeStage(pluginID int32, stage, ctxJSON string, resultOut *string) error { - v, ok := pluginMap.Load(pluginID) - if !ok { - return fmt.Errorf("plugin %d not found", pluginID) - } - ps := v.(*pluginState) - if ps.api == nil { - return fmt.Errorf("plugin %d: nil api", pluginID) - } - cStage := C.CString(stage) - cCtx := C.CString(ctxJSON) - var cErr *C.char - var cResult *C.char - defer C.free(unsafe.Pointer(cStage)) - defer C.free(unsafe.Pointer(cCtx)) - // 仅当调用方要求回传时传 &cResult，否则传 NULL（兼容无需写回的阶段）。 - if ret := int(C.call_invoke_stage(ps.api, cStage, cCtx, &cResult, &cErr)); ret != 0 { - errMsg := "" - if cErr != nil { - errMsg = C.GoString(cErr) - C.api_free_string(ps.api, cErr) - } - return fmt.Errorf("invoke_stage %s: %s", stage, errMsg) - } - if resultOut != nil && cResult != nil { - *resultOut = C.GoString(cResult) - C.api_free_string(ps.api, cResult) - } - return nil -} - -// go_core_dispatch handles all plugin→core SDK calls. -// -//export go_core_dispatch -func go_core_dispatch(methodID C.int, ctx unsafe.Pointer, s1, s2, s3 *C.char, i1, i2 C.int, result **C.char, errorOut **C.char) C.int { - pluginID := int32(uintptr(ctx)) - v, ok := pluginMap.Load(pluginID) - if !ok { - return 1 - } - ps := v.(*pluginState) - s := ps.sdk - if s == nil { - return 1 - } - - a1, a2, a3 := goStr(s1), goStr(s2), goStr(s3) - n1, n2 := int(i1), int(i2) - - switch int(methodID) { - case 1: // CORE_REGISTER_TOOL - var def sdk.ToolDef - if err := json.Unmarshal([]byte(a2), &def); err != nil { - setErr(errorOut, err) - return 1 - } - def.Plugin = ps.name - pid := pluginID - toolName := a1 - _ = s.RegisterTool(a1, def, func(args map[string]interface{}) (interface{}, error) { - argsJSON, _ := json.Marshal(args) - r, err := pluginInvokeTool(pid, toolName, string(argsJSON)) - if err != nil { - return nil, err - } - if r == "" { - return nil, nil - } - var res map[string]interface{} - if err := json.Unmarshal([]byte(r), &res); err != nil { - return r, nil - } - return res, nil - }) - return 0 - - case 2: // CORE_REGISTER_STAGE - pid := pluginID - st := a1 - handler := func(sc *sdk.StageContext) error { - sc.RLock() - m := map[string]interface{}{ - "raw_message": sc.RawMessage, "user_id": sc.UserID, - "group_id": sc.GroupID, "phase": string(sc.Phase), - "llm_text": sc.LLMText, "final_text": sc.FinalText, - "no_memory": sc.NoMemory, - } - if sc.Response != nil { - m["response"] = *sc.Response - } - if len(sc.ToolCalls) > 0 { - m["tool_calls"] = sc.ToolCalls - } - if len(sc.ToolResults) > 0 { - m["tool_results"] = sc.ToolResults - } - sc.RUnlock() - b, _ := json.Marshal(m) - - // ABI v2: 插件可回传修改后的上下文写回内核 sc（如 RawMessage/LLMText/Response/ToolResults）。 - var result string - if err := pluginInvokeStage(pid, st, string(b), &result); err != nil { - return err - } - if result != "" { - applyStageResult(sc, result) - } - return nil - } - scope := sdk.StageScopeGlobal - if a3 == "own_tools" { - scope = sdk.StageScopeOwnTools - } - s.RegisterStage(sdk.Stage(st), handler, scope) - return 0 - - case 3: // CORE_REGISTER_OUTPUT_CH - pid := pluginID - chName := a1 - chDef := sdk.ChannelDef{} - if a3 != "" { - var def sdk.ChannelDef - if err := json.Unmarshal([]byte(a3), &def); err == nil { - chDef = def - } - } - s.RegisterOutputChannel(chName, n1, a2, chDef, func(args map[string]interface{}) (interface{}, error) { - // 发送在 goroutine 内进行（cgo 调用不能嵌套在 cgo 栈上，否则可能崩溃）， - // 但调用方必须拿到真实结果：本 handler 由 executeOutputSendTool 从 Go 侧 - // 调起，不在 cgo 栈内，因此这里等待 goroutine 的结果不构成 cgo 嵌套。 - // （plan.md 11.1） - argsJSON, _ := json.Marshal(args) - log.Printf("[dispatch] output %s/%s args=%s", ps.name, chName, string(argsJSON)) - return awaitOutputResult(pid, chName, string(argsJSON)) - }) - return 0 - - case 4: // CORE_REGISTER_PLUGIN_API - s.RegisterPluginAPI(a1) - return 0 - - case 5: // CORE_INJECT_TEXT - s.InjectText(a1, a2, a3) - return 0 - - case 6: // CORE_INJECT_INTERRUPT_TEXT - s.InjectInterruptText(a1, a2, a3) - return 0 - - case 7: // CORE_INJECT_TEXT_NO_MEMORY - s.InjectTextNoMemory(a1, a2, a3) - return 0 - - case 47: // CORE_INJECT_INPUT_SYNC - if out := s.InjectInputSync(a1, a2, "text", map[string]interface{}{"content": a3}); out != nil { - reply, _ := out.Payload["content"].(string) - setResult(result, reply) - } - return 0 - - case 8: // CORE_SET_AUTO_RESTART - s.SetAutoRestart(n1 != 0) - return 0 - - case 9: // CORE_MEMORY_RECALL - if mem := s.Memory(); mem != nil { - entities, relations, err := mem.Recall([]string{a1}, n1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(map[string]interface{}{"entities": entities, "relations": relations}) - setResult(result, string(b)) - } - return 0 - - case 10: // CORE_MEMORY_COMMIT - if mem := s.Memory(); mem != nil { - var triples []sdk.Triple - if err := json.Unmarshal([]byte(a1), &triples); err != nil { - setErr(errorOut, err) - return 1 - } - if err := mem.Commit(triples); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 11: // CORE_MEMORY_INTROSPECT - if mem := s.Memory(); mem != nil { - r, err := mem.Introspect() - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(r) - setResult(result, string(b)) - } - return 0 - - case 12: // CORE_MEMORY_MERGE - if mem := s.Memory(); mem != nil { - if _, err := mem.MergeEntities(a1, a2); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 13: // CORE_MEMORY_PURGE - if mem := s.Memory(); mem != nil { - var criteria map[string]string - if err := json.Unmarshal([]byte(a1), &criteria); err != nil { - setErr(errorOut, err) - return 1 - } - mode := "soft" - if n1 != 0 { - mode = "hard" - } - if _, err := mem.Purge(criteria, mode); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 14: // CORE_DOC_QUERY - if dm := s.DocMemory(); dm != nil { - b, _ := json.Marshal(dm.Query(a1, n1)) - setResult(result, string(b)) - } - return 0 - - case 15: // CORE_KNOWLEDGE_SEARCH - if kn := s.Knowledge(); kn != nil { - results, err := kn.Search(a1, n1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(results) - setResult(result, string(b)) - } - return 0 - - case 16: // CORE_SETTINGS_GET - if sett := s.Settings(); sett != nil { - v, err := sett.Get(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(v) - setResult(result, string(b)) - } - return 0 - - case 17: // CORE_SETTINGS_SET - if sett := s.Settings(); sett != nil { - var v interface{} - json.Unmarshal([]byte(a2), &v) - if err := sett.Set(a1, v); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 18: // CORE_SETTINGS_REGISTER_DEF - if sett := s.Settings(); sett != nil { - var def sdk.ConfigDef - if err := json.Unmarshal([]byte(a1), &def); err != nil { - setErr(errorOut, err) - return 1 - } - sett.RegisterDef(def) - } - return 0 - - case 19: // CORE_LLM_LIST_SOURCES - if llm := s.LLM(); llm != nil { - b, _ := json.Marshal(llm.ListSources()) - setResult(result, string(b)) - } - return 0 - - case 20: // CORE_LLM_SET_SOURCE - if llm := s.LLM(); llm != nil { - if err := llm.SetSource(a1); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 21: // CORE_SOCIAL_GET_PERSON - if social := s.Social(); social != nil { - p, err := social.GetPerson(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(p) - setResult(result, string(b)) - } - return 0 - - case 22: // CORE_SOCIAL_GET_NETWORK - if social := s.Social(); social != nil { - profiles, err := social.GetNetwork(a1, n1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(profiles) - setResult(result, string(b)) - } - return 0 - - case 23: // CORE_SUBSCRIBE - _ = n2 - // Events API not wired for external plugins (SetEventSubscriber not called) - return 0 - - case 24: // CORE_UNSUBSCRIBE - return 0 - - case 25: // CORE_FREE_STRING - if s1 != nil { - C.free(unsafe.Pointer(s1)) - } - return 0 - - case 26: // CORE_SETTINGS_GET_CORE - if sett := s.Settings(); sett != nil { - v, err := sett.GetCore(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(v) - setResult(result, string(b)) - } - return 0 - - case 27: // CORE_SETTINGS_SET_CORE - if sett := s.Settings(); sett != nil { - var v interface{} - json.Unmarshal([]byte(a2), &v) - if err := sett.SetCore(a1, v); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 28: // CORE_SETTINGS_LIST_CORE - if sett := s.Settings(); sett != nil { - keys, err := sett.ListCore(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(keys) - setResult(result, string(b)) - } - return 0 - - case 29: // CORE_SETTINGS_GET_PLUGIN - if sett := s.Settings(); sett != nil { - v, err := sett.GetPlugin(a1, a2) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(v) - setResult(result, string(b)) - } - return 0 - - case 30: // CORE_SETTINGS_SET_PLUGIN - if sett := s.Settings(); sett != nil { - var v interface{} - json.Unmarshal([]byte(a3), &v) - if err := sett.SetPlugin(a1, a2, v); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 31: // CORE_SETTINGS_LIST_PLUGIN - if sett := s.Settings(); sett != nil { - keys, err := sett.ListPlugin(a1, a2) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(keys) - setResult(result, string(b)) - } - return 0 - - case 32: // CORE_DOC_INSERT - if dm := s.DocMemory(); dm != nil { - var doc sdk.Doc - if err := json.Unmarshal([]byte(a1), &doc); err != nil { - setErr(errorOut, err) - return 1 - } - if err := dm.Insert(&doc); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 33: // CORE_DOC_REMOVE - if dm := s.DocMemory(); dm != nil { - dm.Remove(a1) - } - return 0 - - case 34: // CORE_DOC_STATS - if dm := s.DocMemory(); dm != nil { - b, _ := json.Marshal(dm.Stats()) - setResult(result, string(b)) - } - return 0 - - case 35: // CORE_KNOWLEDGE_ADD - if kn := s.Knowledge(); kn != nil { - if err := kn.Add(a1, a2); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 36: // CORE_KNOWLEDGE_LIST - if kn := s.Knowledge(); kn != nil { - list, err := kn.List() - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(list) - setResult(result, string(b)) - } - return 0 - - case 37: // CORE_LLM_CURRENT_SOURCE - if llm := s.LLM(); llm != nil { - b, _ := json.Marshal(llm.CurrentSource()) - setResult(result, string(b)) - } - return 0 - - case 38: // CORE_SOCIAL_GET_TRAIT - if social := s.Social(); social != nil { - val, ok := social.GetTrait(a1, a2) - b, _ := json.Marshal(map[string]interface{}{"value": val, "found": ok}) - setResult(result, string(b)) - } - return 0 - - case 39: // CORE_SOCIAL_GET_RELATIONS - if social := s.Social(); social != nil { - rels, err := social.GetRelations(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(rels) - setResult(result, string(b)) - } - return 0 - - case 40: // CORE_SOCIAL_LIST_PERSONS - if social := s.Social(); social != nil { - persons, err := social.ListPersons() - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(persons) - setResult(result, string(b)) - } - return 0 - - case 41: // CORE_TEXT_MEMORY_APPEND - if tm := s.TextMemory(); tm != nil { - var evt sdk.TextEvent - if err := json.Unmarshal([]byte(a1), &evt); err != nil { - setErr(errorOut, err) - return 1 - } - if err := tm.Append(evt); err != nil { - setErr(errorOut, err) - return 1 - } - } - return 0 - - case 42: // CORE_SETTINGS_LIST - if sett := s.Settings(); sett != nil { - keys, err := sett.List(a1) - if err != nil { - setErr(errorOut, err) - return 1 - } - b, _ := json.Marshal(keys) - setResult(result, string(b)) - } - return 0 - - case 43: // CORE_SETTINGS_DEFS - if sett := s.Settings(); sett != nil { - defs := sett.Defs(a1) - b, _ := json.Marshal(defs) - setResult(result, string(b)) - } - return 0 - - case 44: // CORE_SETTINGS_DUMP - if sett := s.Settings(); sett != nil { - dump := sett.Dump() - b, _ := json.Marshal(dump) - setResult(result, string(b)) - } - return 0 - - case 45: // CORE_SETTINGS_PLUGINS - if sett := s.Settings(); sett != nil { - plugins := sett.Plugins() - b, _ := json.Marshal(plugins) - setResult(result, string(b)) - } - return 0 - - case 51: // CORE_SETTINGS_DATA_DIR：插件专属数据目录（内核保证存在） - if sett := s.Settings(); sett != nil { - setResult(result, sett.DataDir()) - } - return 0 - - case 46: // CORE_REGISTER_INPUT_CH - chDef := sdk.ChannelDef{} - if a2 != "" { - var def sdk.ChannelDef - if err := json.Unmarshal([]byte(a2), &def); err == nil { - chDef = def - } - } - s.RegisterInputChannel(a1, chDef) - return 0 - - case 48: // CORE_PLUGIN_RELOAD_ONE - if s.PluginMgr() == nil { - setErr(errorOut, fmt.Errorf("plugin manager not available")) - return 1 - } - if err := s.PluginMgr().ReloadOne(a1); err != nil { - setErr(errorOut, err) - return 1 - } - setResult(result, "reloaded: "+a1) - return 0 - - case 49: // CORE_PLUGIN_LIST_LOADED - if s.PluginMgr() == nil { - setErr(errorOut, fmt.Errorf("plugin manager not available")) - return 1 - } - if b, err := json.Marshal(s.PluginMgr().ListLoadedPlugins()); err == nil { - setResult(result, string(b)) - } - return 0 - - case 50: // CORE_PLUGIN_IS_DISABLED - if s.PluginMgr() == nil { - setErr(errorOut, fmt.Errorf("plugin manager not available")) - return 1 - } - if s.PluginMgr().IsPluginDisabled(a1) { - setResult(result, "1") - } else { - setResult(result, "0") - } - return 0 - } - return 0 -} - -func goStr(s *C.char) string { - if s == nil { - return "" - } - return C.GoString(s) -} - -func setErr(errOut **C.char, err error) { - if errOut != nil && err != nil { - *errOut = C.CString(err.Error()) - } -} - -func setResult(result **C.char, v string) { - if result != nil { - *result = C.CString(v) - } -} diff --git a/internal/plugin/cabi/output_test.go b/internal/plugin/cabi/output_test.go deleted file mode 100644 index 2c54437..0000000 --- a/internal/plugin/cabi/output_test.go +++ /dev/null @@ -1,92 +0,0 @@ -package cabi - -import ( - "errors" - "strings" - "testing" - "time" - - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -// output_send 不再假成功（plan.md 11.1）：sent / error / unconfirmed 三态。 - -func TestAwaitOutputResult_Success(t *testing.T) { - res, err := awaitOutputResultWith(0, "qq", `{"x":1}`, func(pid int32, ch, args string) error { - return nil - }, outputSendTimeout) - if err != nil { - t.Fatalf("expected no error, got %v", err) - } - m, _ := res.(map[string]interface{}) - if m["status"] != "sent" { - t.Fatalf("expected status=sent, got %v", m["status"]) - } -} - -func TestAwaitOutputResult_Failure(t *testing.T) { - _, err := awaitOutputResultWith(0, "qq", `{}`, func(pid int32, ch, args string) error { - return errors.New("meta 中需要 group_id 或 user_id 字段") - }, outputSendTimeout) - if err == nil { - t.Fatal("expected error on failed send, got nil (旧实现会谎报成功)") - } - if !strings.Contains(err.Error(), "需要 group_id") { - t.Fatalf("unexpected error: %v", err) - } -} - -func TestAwaitOutputResult_Timeout(t *testing.T) { - res, err := awaitOutputResultWith(0, "qq", `{}`, func(pid int32, ch, args string) error { - time.Sleep(2 * time.Second) // 模拟插件发送迟迟不确认 - return nil - }, 50*time.Millisecond) - if err != nil { - t.Fatalf("unconfirmed 不应返回 error，got %v", err) - } - m, _ := res.(map[string]interface{}) - if m["status"] != "unconfirmed" { - t.Fatalf("expected status=unconfirmed, got %v", m["status"]) - } -} - -// applyStageResult 必须能表达「插件清空了 tool_calls/tool_results」—— -// ABI v2 diff 回传（plan.md 11.3）下插件拒绝全部工具调用时会显式回传 []。 -func TestApplyStageResult_ClearedSlicesAreApplied(t *testing.T) { - sc := &sdk.StageContext{ - ToolCalls: []sdk.ToolCall{{ID: "t1", Name: "cmd_run"}}, - ToolResults: []sdk.ToolResult{{CallID: "t1", Name: "cmd_run", Result: "x"}}, - } - applyStageResult(sc, `{"tool_calls":[],"tool_results":[]}`) - if len(sc.ToolCalls) != 0 { - t.Fatalf("tool_calls 应被清空，实际 %v", sc.ToolCalls) - } - if len(sc.ToolResults) != 0 { - t.Fatalf("tool_results 应被清空，实际 %v", sc.ToolResults) - } -} - -// diff 回传只带变更字段：未出现的键不得被改动（避免旧快照覆盖）。 -func TestApplyStageResult_OnlyPresentKeysApplied(t *testing.T) { - sc := &sdk.StageContext{ - RawMessage: "原始输入", - LLMText: "原始LLM", - FinalText: "原始最终", - ToolResults: []sdk.ToolResult{{CallID: "c1", Result: "已清洗"}}, - } - // 只回传 final_text 的变更 - applyStageResult(sc, `{"final_text":"新最终"}`) - - if sc.FinalText != "新最终" { - t.Fatalf("final_text 应被应用，实际 %q", sc.FinalText) - } - if sc.RawMessage != "原始输入" { - t.Errorf("raw_message 未回传却被改动: %q", sc.RawMessage) - } - if sc.LLMText != "原始LLM" { - t.Errorf("llm_text 未回传却被改动: %q", sc.LLMText) - } - if len(sc.ToolResults) != 1 || sc.ToolResults[0].Result != "已清洗" { - t.Errorf("tool_results 未回传却被改动: %v", sc.ToolResults) - } -} diff --git a/internal/plugin/cabi/types.go b/internal/plugin/cabi/types.go deleted file mode 100644 index 764f0a3..0000000 --- a/internal/plugin/cabi/types.go +++ /dev/null @@ -1,66 +0,0 @@ -package cabi - -import "gitcode.com/JianFeeeee/HomeAgent/internal/meta" - -// ABI version constants — single source of truth is meta.go -// ABIVersion/ABIVersionMin 是字符串 semver（var 转发，因 meta 侧 Version 为注入变量）； -// CABINum/CABINumMin 是 C 层整数协商版本。 -var ( - ABIVersion = meta.ABIVersion - ABIVersionMin = meta.ABIVersionMin -) - -const ( - CABINum = meta.CABINum - CABINumMin = meta.CABINumMin -) - -// Dispatch method IDs — single source of truth is meta.go -const ( - CoreRegisterTool = meta.CoreRegisterTool - CoreRegisterStage = meta.CoreRegisterStage - CoreRegisterOutputCh = meta.CoreRegisterOutputCh - CoreRegisterPluginAPI = meta.CoreRegisterPluginAPI - CoreInjectText = meta.CoreInjectText - CoreInjectInterruptText = meta.CoreInjectInterruptText - CoreInjectTextNoMemory = meta.CoreInjectTextNoMemory - CoreSetAutoRestart = meta.CoreSetAutoRestart - CoreMemoryRecall = meta.CoreMemoryRecall - CoreMemoryCommit = meta.CoreMemoryCommit - CoreMemoryIntrospect = meta.CoreMemoryIntrospect - CoreMemoryMerge = meta.CoreMemoryMerge - CoreMemoryPurge = meta.CoreMemoryPurge - CoreDocQuery = meta.CoreDocQuery - CoreKnowledgeSearch = meta.CoreKnowledgeSearch - CoreSettingsGet = meta.CoreSettingsGet - CoreSettingsSet = meta.CoreSettingsSet - CoreSettingsRegisterDef = meta.CoreSettingsRegisterDef - CoreLLMListSources = meta.CoreLLMListSources - CoreLLMSetSource = meta.CoreLLMSetSource - CoreSocialGetPerson = meta.CoreSocialGetPerson - CoreSocialGetNetwork = meta.CoreSocialGetNetwork - CoreSubscribe = meta.CoreSubscribe - CoreUnsubscribe = meta.CoreUnsubscribe - CoreFreeString = meta.CoreFreeString - CoreSettingsGetCore = meta.CoreSettingsGetCore - CoreSettingsSetCore = meta.CoreSettingsSetCore - CoreSettingsListCore = meta.CoreSettingsListCore - CoreSettingsGetPlugin = meta.CoreSettingsGetPlugin - CoreSettingsSetPlugin = meta.CoreSettingsSetPlugin - CoreSettingsListPlugin = meta.CoreSettingsListPlugin - CoreDocInsert = meta.CoreDocInsert - CoreDocRemove = meta.CoreDocRemove - CoreDocStats = meta.CoreDocStats - CoreKnowledgeAdd = meta.CoreKnowledgeAdd - CoreKnowledgeList = meta.CoreKnowledgeList - CoreLLMCurrentSource = meta.CoreLLMCurrentSource - CoreSocialGetTrait = meta.CoreSocialGetTrait - CoreSocialGetRelations = meta.CoreSocialGetRelations - CoreSocialListPersons = meta.CoreSocialListPersons - CoreTextMemoryAppend = meta.CoreTextMemoryAppend - CoreSettingsList = meta.CoreSettingsList - CoreSettingsDefs = meta.CoreSettingsDefs - CoreSettingsDump = meta.CoreSettingsDump - CoreSettingsPlugins = meta.CoreSettingsPlugins - CoreRegisterInputCh = meta.CoreRegisterInputCh -) diff --git a/internal/plugin/dynamic.go b/internal/plugin/dynamic.go index 33aecc0..b583051 100644 --- a/internal/plugin/dynamic.go +++ b/internal/plugin/dynamic.go @@ -7,31 +7,34 @@ import ( ) const ( - soEntry = "plugin.so" - dllEntry = "plugin.dll" - binEntry = "plugin.bin" // 子进程插件（纯 Go 二进制，stdio JSON-RPC） + binEntry = "plugin.bin" // 子进程插件（纯 Go 二进制，stdio JSON-RPC + 共享内存） luaEntry = "main.lua" skillEntry = "SKILL.md" metaEntry = "plugin.json" ) +// legacyCABIEntries 是已退场的 C ABI 产物名。 +// +// 保留这张表只为**给出明确错误**：插件目录里躺着 plugin.so 而内核不再认它时， +// 静默跳过会让「目录在但插件没加载」看起来像配置问题，而实际原因是需要用 +// 新版 plugindev 重编。 +var legacyCABIEntries = []string{"plugin.so", "plugin.dll", "plugin.dylib"} + // entryKind 描述插件入口归属的加载通道。 -// 外部插件多进程化期间 .so/.dll（cabi）与 .bin（proc）**双通道共存**， -// 按 plugin.json 的 entry 字段分派，使迁移可逐插件推进、随时回退。 +// +// C ABI 通道（.so/.dll/.dylib）已整体退场：外部插件统一走子进程 + stdio RPC， +// 三套独立 ABI 实现收敛为单一 RPC 实现（§9.2）。 type entryKind int const ( entryUnknown entryKind = iota - entryCABI // plugin.so / plugin.dll / plugin.dylib —— C ABI 动态库 - entryProc // plugin.bin —— 子进程 + stdio JSON-RPC + entryProc // plugin.bin —— 子进程 + stdio JSON-RPC + 共享内存 entryLua // main.lua entrySkill // SKILL.md ) func (k entryKind) String() string { switch k { - case entryCABI: - return "cabi" case entryProc: return "proc" case entryLua: @@ -43,11 +46,12 @@ func (k entryKind) String() string { } // classifyEntry 把 manifest 的 entry 字段映射到加载通道。 -// entry 为空时返回 entryUnknown，由调用方回退到目录探测（兼容无 manifest 的旧插件）。 +// +// entry 为空或声明已退场的 C ABI 产物时返回 entryUnknown， +// 由调用方回退到目录探测（兼容无 manifest 的旧插件）， +// 并在探测到 C ABI 残留时给出明确的重编提示。 func classifyEntry(entry string) entryKind { switch entry { - case soEntry, dllEntry, "plugin.dylib": - return entryCABI case binEntry: return entryProc case luaEntry: @@ -59,8 +63,9 @@ func classifyEntry(entry string) entryKind { } // detectEntryKind 先读 manifest 的 entry，读不到则按目录内存在的入口文件推断。 -// 推断顺序：.bin 优先于 .so——迁移期间同一插件目录可能两个产物共存（升级未清理）， -// 此时应走新通道；manifest 显式声明优先级最高。 +// +// 注意：存量插件的 plugin.json 可能仍写着 "plugin.so"（工具链已不再据此分派， +// 但历史产物里有），此时 classifyEntry 返回 unknown，靠目录探测找到 plugin.bin。 func detectEntryKind(plgDir string) entryKind { if mft := readManifest(plgDir); mft != nil { if k := classifyEntry(mft.Entry); k != entryUnknown { @@ -72,9 +77,6 @@ func detectEntryKind(plgDir string) entryKind { kind entryKind }{ {binEntry, entryProc}, - {soEntry, entryCABI}, - {"plugin.dylib", entryCABI}, - {dllEntry, entryCABI}, {luaEntry, entryLua}, {skillEntry, entrySkill}, } { @@ -85,6 +87,18 @@ func detectEntryKind(plgDir string) entryKind { return entryUnknown } +// hasLegacyCABIEntry 判断插件目录里是否只剩已退场的 C ABI 产物。 +// +// 用于给出「需要重编」而非「插件不存在」的错误。 +func hasLegacyCABIEntry(plgDir string) bool { + for _, name := range legacyCABIEntries { + if st, err := os.Stat(filepath.Join(plgDir, name)); err == nil && !st.IsDir() { + return true + } + } + return false +} + func readManifest(dir string) *PluginManifest { data, err := os.ReadFile(filepath.Join(dir, metaEntry)) if err != nil { @@ -96,5 +110,3 @@ func readManifest(dir string) *PluginManifest { } return &m } - -var _ = json.Marshal diff --git a/internal/plugin/dynamic_dll_stub.go b/internal/plugin/dynamic_dll_stub.go deleted file mode 100644 index 5fbcae6..0000000 --- a/internal/plugin/dynamic_dll_stub.go +++ /dev/null @@ -1,11 +0,0 @@ -//go:build !windows - -package plugin - -import ( - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -func tryLoadDLL(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { - return nil, nil -} diff --git a/internal/plugin/dynamic_dll_test.go b/internal/plugin/dynamic_dll_test.go deleted file mode 100644 index a97f822..0000000 --- a/internal/plugin/dynamic_dll_test.go +++ /dev/null @@ -1,32 +0,0 @@ -//go:build windows - -package plugin - -import ( - "os" - "path/filepath" - "testing" -) - -func TestTryLoadDLL_NoFile(t *testing.T) { - dir := t.TempDir() - plg, err := tryLoadDLL(dir, "nonexistent", nil) - if err != nil { - t.Fatalf("tryLoadDLL on empty dir should not error: %v", err) - } - if plg != nil { - t.Fatal("expected nil for non-existent plugin.dll") - } -} - -func TestTryLoadDLL_Invalid(t *testing.T) { - dir := t.TempDir() - os.WriteFile(filepath.Join(dir, "plugin.dll"), []byte("not a real dll"), 0644) - - plg, err := tryLoadDLL(dir, "baddll", nil) - t.Logf("plg=%v err=%v", plg, err) - - if err == nil && plg == nil { - t.Fatal("expected error or non-nil plugin for existing file") - } -} diff --git a/internal/plugin/dynamic_dll_windows.go b/internal/plugin/dynamic_dll_windows.go deleted file mode 100644 index 4b73b72..0000000 --- a/internal/plugin/dynamic_dll_windows.go +++ /dev/null @@ -1,272 +0,0 @@ -//go:build windows - -package plugin - -import ( - "encoding/json" - "fmt" - "os" - "path/filepath" - "syscall" - "unsafe" - - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -// dllPlugin wraps a Windows DLL compiled with -buildmode=c-shared. -// -// Required exports: -// -// NewPlugin(name *C.char, configJSON *C.char) unsafe.Pointer → plugin handle -// StartPlugin(handle unsafe.Pointer) C.int -// StopPlugin(handle unsafe.Pointer) C.int -// DestroyPlugin(handle unsafe.Pointer) -// -// Optional exports (tool registration): -// -// GetToolDefsJSON(handle unsafe.Pointer) *C.char → JSON array of tool defs -// InvokeToolJSON(handle unsafe.Pointer, toolName *C.char, argsJSON *C.char) *C.char -// FreeCString(s *C.char) → free C string from DLL -// GetStagesJSON(handle unsafe.Pointer) *C.char → JSON array of stage names -// InvokeStage(handle unsafe.Pointer, stage *C.char, contextJSON *C.char) C.int -type dllPlugin struct { - name string - dll syscall.Handle - handle uintptr - sdk *sdk.PluginSDK - - // cached proc addresses - newPlugin uintptr - startPlugin uintptr - stopPlugin uintptr - destroyPlugin uintptr - getTools uintptr - invokeTool uintptr - freeCStr uintptr - getStages uintptr - invokeStage uintptr -} - -func findProc(dll syscall.Handle, name string) uintptr { - addr, err := syscall.GetProcAddress(dll, name) - if err != nil { - return 0 - } - return addr -} - -func newDLLPlugin(dllPath, name string, config map[string]interface{}) (*dllPlugin, error) { - dll, err := syscall.LoadLibrary(dllPath) - if err != nil { - return nil, fmt.Errorf("LoadLibrary %s: %w", dllPath, err) - } - - np := findProc(dll, "NewPlugin") - if np == 0 { - _ = syscall.FreeLibrary(dll) - return nil, fmt.Errorf("dll %s must export NewPlugin", name) - } - - return &dllPlugin{ - name: name, - dll: dll, - // required - newPlugin: np, - startPlugin: findProc(dll, "StartPlugin"), - stopPlugin: findProc(dll, "StopPlugin"), - destroyPlugin: findProc(dll, "DestroyPlugin"), - // optional tool/stage API - getTools: findProc(dll, "GetToolDefsJSON"), - invokeTool: findProc(dll, "InvokeToolJSON"), - freeCStr: findProc(dll, "FreeCString"), - getStages: findProc(dll, "GetStagesJSON"), - invokeStage: findProc(dll, "InvokeStage"), - }, nil -} - -func (p *dllPlugin) Name() string { return p.name } - -func (p *dllPlugin) Start(s *sdk.PluginSDK) error { - p.sdk = s - - cfgJSON, _ := json.Marshal(map[string]interface{}{ - "name": p.name, - "config": s.Settings().Dump(), - }) - cName := append([]byte(p.name), 0) - cConfig := append(cfgJSON, 0) - - ret, _, _ := syscall.SyscallN( - p.newPlugin, - uintptr(unsafe.Pointer(&cName[0])), - uintptr(unsafe.Pointer(&cConfig[0])), - ) - if ret == 0 { - _ = syscall.FreeLibrary(p.dll) - return fmt.Errorf("dll NewPlugin %s returned nil", p.name) - } - p.handle = ret - - if p.startPlugin != 0 { - syscall.SyscallN(p.startPlugin, p.handle) - } - - // discover and register tools from DLL - if p.getTools != 0 { - if err := p.registerTools(s); err != nil { - return fmt.Errorf("dll %s register tools: %w", p.name, err) - } - } - if p.getStages != 0 { - p.registerStages(s) - } - return nil -} - -func (p *dllPlugin) Stop() error { - if p.stopPlugin != 0 { - syscall.SyscallN(p.stopPlugin, p.handle) - } - if p.destroyPlugin != 0 { - syscall.SyscallN(p.destroyPlugin, p.handle) - } - _ = syscall.FreeLibrary(p.dll) - return nil -} - -// --- tool registration via C ABI --- - -type dllToolDef struct { - Name string `json:"name"` - Description string `json:"description"` - Parameters map[string]interface{} `json:"parameters,omitempty"` -} - -func (p *dllPlugin) registerTools(s *sdk.PluginSDK) error { - ret, _, _ := syscall.SyscallN(p.getTools, p.handle) - if ret == 0 { - return nil // no tools - } - defsJSON := cStringPtrToString(ret) - if p.freeCStr != 0 { - syscall.SyscallN(p.freeCStr, ret) - } - - var defs []dllToolDef - if err := json.Unmarshal([]byte(defsJSON), &defs); err != nil { - return fmt.Errorf("parse tool defs: %w", err) - } - for _, d := range defs { - if d.Name == "" { - continue - } - toolName := d.Name - handler := p.makeToolHandler(toolName) - s.RegisterTool(toolName, sdk.ToolDef{ - Name: toolName, - Description: d.Description, - Parameters: d.Parameters, - Plugin: p.name, - }, handler) - } - return nil -} - -func (p *dllPlugin) makeToolHandler(toolName string) sdk.ToolHandler { - return func(args map[string]interface{}) (interface{}, error) { - if p.invokeTool == 0 { - return nil, fmt.Errorf("dll %s does not export InvokeToolJSON", p.name) - } - argsJSON, _ := json.Marshal(args) - cToolName := append([]byte(toolName), 0) - cArgs := append(argsJSON, 0) - - ret, _, _ := syscall.SyscallN( - p.invokeTool, - p.handle, - uintptr(unsafe.Pointer(&cToolName[0])), - uintptr(unsafe.Pointer(&cArgs[0])), - ) - if ret == 0 { - return nil, fmt.Errorf("dll InvokeToolJSON %s returned nil", toolName) - } - resultJSON := cStringPtrToString(ret) - if p.freeCStr != 0 { - syscall.SyscallN(p.freeCStr, ret) - } - var result map[string]interface{} - if err := json.Unmarshal([]byte(resultJSON), &result); err != nil { - return nil, fmt.Errorf("dll tool %s result parse: %w", toolName, err) - } - return result, nil - } -} - -func (p *dllPlugin) registerStages(s *sdk.PluginSDK) { - ret, _, _ := syscall.SyscallN(p.getStages, p.handle) - if ret == 0 { - return - } - stagesJSON := cStringPtrToString(ret) - if p.freeCStr != 0 { - syscall.SyscallN(p.freeCStr, ret) - } - type stageEntry struct { - Stage string `json:"stage"` - } - var entries []stageEntry - if err := json.Unmarshal([]byte(stagesJSON), &entries); err != nil { - return - } - for _, e := range entries { - if e.Stage == "" { - continue - } - stageName := sdk.Stage(e.Stage) - stage := stageName - s.RegisterStage(stage, func(sc *sdk.StageContext) error { - if p.invokeStage == 0 { - return nil - } - ctxJSON, _ := json.Marshal(map[string]interface{}{ - "raw_message": sc.RawMessage, - "user_id": sc.UserID, - "phase": string(sc.Phase), - }) - cStage := append([]byte(stage), 0) - cCtx := append(ctxJSON, 0) - syscall.SyscallN( - p.invokeStage, - p.handle, - uintptr(unsafe.Pointer(&cStage[0])), - uintptr(unsafe.Pointer(&cCtx[0])), - ) - return nil - }) - } -} - -func cStringPtrToString(ptr uintptr) string { - if ptr == 0 { - return "" - } - var buf []byte - for i := uintptr(0); ; i++ { - b := *(*byte)(unsafe.Pointer(ptr + i)) - if b == 0 { - break - } - buf = append(buf, b) - } - return string(buf) -} - -// tryLoadDLL 尝试从插件目录加载 plugin.dll。 -// 返回 nil,nil 表示目录中没有 plugin.dll。 -func tryLoadDLL(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { - dllPath := filepath.Join(dir, dllEntry) - if _, err := os.Stat(dllPath); os.IsNotExist(err) { - return nil, nil - } - return newDLLPlugin(dllPath, name, config) -} diff --git a/internal/plugin/dynamic_loader_unix.go b/internal/plugin/dynamic_loader_unix.go deleted file mode 100644 index da96944..0000000 --- a/internal/plugin/dynamic_loader_unix.go +++ /dev/null @@ -1,79 +0,0 @@ -//go:build linux || darwin - -package plugin - -import ( - "encoding/json" - "fmt" - "os" - "path/filepath" - - pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" - - "gitcode.com/JianFeeeee/HomeAgent/internal/plugin/cabi" -) - -type dynamicPlugin struct { - name string - impl pubsdk.Plugin -} - -func (p *dynamicPlugin) Name() string { return p.name } -func (p *dynamicPlugin) Start(s *sdk.PluginSDK) error { - return p.impl.Start(s.PluginSDK) -} -func (p *dynamicPlugin) Stop() error { return p.impl.Stop() } - -type cabiPlugin struct { - name string - handle *cabi.Handle -} - -func (p *cabiPlugin) Name() string { return p.name } -func (p *cabiPlugin) Start(s *sdk.PluginSDK) error { - corePtr := p.handle.CreateCoreAPI(s) - if corePtr == nil { - return fmt.Errorf("cabi: failed to create CoreAPI for %s", p.name) - } - if err := p.handle.Start(corePtr); err != nil { - return fmt.Errorf("cabi: start %s: %w", p.name, err) - } - return nil -} - -func (p *cabiPlugin) Stop() error { - _ = p.handle.Stop() - return nil -} - -// Close 卸载动态库（dlclose）。卸载/重载后必须调用，否则同一路径的 dlopen -// 会复用旧句柄（Linux dlopen 语义），新版本的 plugin.so 不会生效。 -func (p *cabiPlugin) Close() error { - p.handle.Close() - return nil -} - -func tryLoadSO(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { - soPath := filepath.Join(dir, soEntry) - if _, err := os.Stat(soPath); os.IsNotExist(err) { - // 回退尝试 plugin.dylib (macOS 原生扩展名) - dylibPath := filepath.Join(dir, "plugin.dylib") - if _, err2 := os.Stat(dylibPath); err2 == nil { - soPath = dylibPath - } else { - return nil, nil - } - } - - handle, err := cabi.Load(soPath, name, config) - if err == nil { - return &cabiPlugin{name: name, handle: handle}, nil - } - // 本项目插件统一由 plugindev 编译为 c-shared 走 C ABI； - // 对 c-shared .so 调用 Go plugin.Open 会 fatal（no plugin module data）， - // 因此不再 fallback 到 Go plugin，直接返回加载错误避免崩溃。 - return nil, err -} - -var _ = json.Marshal diff --git a/internal/plugin/dynamic_loader_windows.go b/internal/plugin/dynamic_loader_windows.go deleted file mode 100644 index c7db6cf..0000000 --- a/internal/plugin/dynamic_loader_windows.go +++ /dev/null @@ -1,11 +0,0 @@ -//go:build windows - -package plugin - -import ( - sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" -) - -func tryLoadSO(dir, name string, config map[string]interface{}) (sdk.Plugin, error) { - return nil, nil -} diff --git a/internal/plugin/entry_dispatch_test.go b/internal/plugin/entry_dispatch_test.go index ced5aec..c19066f 100644 --- a/internal/plugin/entry_dispatch_test.go +++ b/internal/plugin/entry_dispatch_test.go @@ -3,26 +3,30 @@ package plugin import ( "os" "path/filepath" + "strings" "testing" ) -// entry 分派骨架（docs/zh/plugin-migration-plan.md Part 1）： -// 外部插件多进程化期间 .so/.dll（cabi）与 .bin（proc）双通道共存， -// 按 plugin.json 的 entry 字段分派，使迁移可逐插件推进、随时回退。 +// entry 分派（docs/zh/plugin-migration-plan.md Part 1/6）。 +// +// C ABI 通道（.so/.dll/.dylib）已整体退场：外部插件统一走子进程 + stdio RPC。 +// 这些测试守住的是「旧产物给明确错误」而非「静默跳过」——后者会让 +// 「插件目录在但没加载」看起来像配置问题。 func TestClassifyEntry(t *testing.T) { cases := []struct { entry string want entryKind }{ - {"plugin.so", entryCABI}, - {"plugin.dll", entryCABI}, - {"plugin.dylib", entryCABI}, {"plugin.bin", entryProc}, {"main.lua", entryLua}, {"SKILL.md", entrySkill}, {"", entryUnknown}, {"plugin.wasm", entryUnknown}, + // 已退场的 C ABI 产物不再是有效通道 + {"plugin.so", entryUnknown}, + {"plugin.dll", entryUnknown}, + {"plugin.dylib", entryUnknown}, } for _, c := range cases { if got := classifyEntry(c.entry); got != c.want { @@ -34,45 +38,34 @@ func TestClassifyEntry(t *testing.T) { // manifest 显式声明的 entry 优先级最高。 func TestDetectEntryKind_ManifestWins(t *testing.T) { dir := t.TempDir() - // 目录里放 .so，但 manifest 声明 .bin → 应走 proc - mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") + mustWrite(t, filepath.Join(dir, "main.lua"), "fake lua") mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") - mustWrite(t, filepath.Join(dir, metaEntry), `{"name":"x","entry":"plugin.bin"}`) + mustWrite(t, filepath.Join(dir, metaEntry), `{"name":"x","entry":"main.lua"}`) - if got := detectEntryKind(dir); got != entryProc { - t.Fatalf("manifest 声明 plugin.bin 应走 proc，实际 %v", got) + if got := detectEntryKind(dir); got != entryLua { + t.Fatalf("manifest 声明 main.lua 应走 lua，实际 %v", got) } } -// manifest 声明 .so 时即便存在 .bin 也走 cabi —— 这是回退路径的保证。 -func TestDetectEntryKind_ManifestCanForceRollback(t *testing.T) { +// 存量插件的 plugin.json 仍写着 "plugin.so"（历史产物）， +// 此时 classifyEntry 返回 unknown，须靠目录探测找到 plugin.bin。 +// +// 这是「外部插件零改动」的直接后果：17 个插件的 manifest 没人去改。 +func TestDetectEntryKind_LegacyManifestFallsBackToProbe(t *testing.T) { dir := t.TempDir() - mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") mustWrite(t, filepath.Join(dir, metaEntry), `{"name":"x","entry":"plugin.so"}`) - if got := detectEntryKind(dir); got != entryCABI { - t.Fatalf("manifest 声明 plugin.so 应回退到 cabi，实际 %v", got) - } -} - -// 无 manifest（或 entry 为空）时按目录探测，.bin 优先于 .so： -// 迁移期间同目录可能两种产物共存（升级未清理），此时应走新通道。 -func TestDetectEntryKind_ProbeOrderPrefersBin(t *testing.T) { - dir := t.TempDir() - mustWrite(t, filepath.Join(dir, "plugin.so"), "fake so") - mustWrite(t, filepath.Join(dir, "plugin.bin"), "fake bin") - if got := detectEntryKind(dir); got != entryProc { - t.Fatalf("无 manifest 时应优先 plugin.bin，实际 %v", got) + t.Fatalf("manifest 写 plugin.so 但目录有 plugin.bin 时应走 proc，实际 %v", got) } } func TestDetectEntryKind_ProbeFallbacks(t *testing.T) { - t.Run("only so", func(t *testing.T) { + t.Run("only bin", func(t *testing.T) { dir := t.TempDir() - mustWrite(t, filepath.Join(dir, "plugin.so"), "x") - if got := detectEntryKind(dir); got != entryCABI { + mustWrite(t, filepath.Join(dir, "plugin.bin"), "x") + if got := detectEntryKind(dir); got != entryProc { t.Fatalf("got %v", got) } }) @@ -95,15 +88,60 @@ func TestDetectEntryKind_ProbeFallbacks(t *testing.T) { t.Fatalf("空目录应为 unknown，实际 %v", got) } }) + t.Run("only legacy so", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "x") + if got := detectEntryKind(dir); got != entryUnknown { + t.Fatalf("只有 .so 时应为 unknown（C ABI 已退场），实际 %v", got) + } + }) } -// entry 声明 plugin.bin 但二进制缺失时必须报明确错误， -// 不得静默回退到 cabi —— 否则"已迁移插件跑回旧通道"极难排查。 +// C ABI 残留必须能被识别，供 tryDynamic 给出「需要重编」的明确错误。 +func TestHasLegacyCABIEntry(t *testing.T) { + for _, name := range []string{"plugin.so", "plugin.dll", "plugin.dylib"} { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, name), "x") + if !hasLegacyCABIEntry(dir) { + t.Errorf("%s 应被识别为 C ABI 残留", name) + } + } + t.Run("clean dir", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.bin"), "x") + if hasLegacyCABIEntry(dir) { + t.Error("只有 plugin.bin 的目录不应被判为 C ABI 残留") + } + }) +} + +// 旧 .so 插件必须报「用新 plugindev 重编」而非静默跳过。 +func TestTryDynamic_LegacyCABIGivesActionableError(t *testing.T) { + r := NewRegistry() + defer r.closeProcHost() + + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "old cabi binary") + + _, err := r.tryDynamic(dir, "legacy", nil) + if err == nil { + t.Fatal("旧 C ABI 产物应报错，不得静默跳过") + } + // 错误消息须指向解决办法，且明确业务代码无需改 + msg := err.Error() + for _, want := range []string{"plugindev", "plugin.bin", "业务代码"} { + if !strings.Contains(msg, want) { + t.Errorf("错误消息应含 %q，实际: %v", want, err) + } + } +} + +// entry 声明 plugin.bin 但二进制缺失时返回 nil,nil（交由后续探测）。 func TestTryLoadProc_MissingBinaryReturnsNil(t *testing.T) { dir := t.TempDir() plg, err := tryLoadProc(dir, "demo", nil) if plg != nil || err != nil { - t.Fatalf("无 plugin.bin 应返回 nil,nil（交由后续探测），实际 plg=%v err=%v", plg, err) + t.Fatalf("无 plugin.bin 应返回 nil,nil，实际 plg=%v err=%v", plg, err) } } @@ -123,9 +161,8 @@ func TestTryLoadProc_NonExecutableRejected(t *testing.T) { // pluginEntryHash 的候选顺序须与 detectEntryKind 一致（plugin.bin 优先）， // 否则增量重载会用错文件算 hash，导致"换了 .bin 但内核以为没变"。 -func TestPluginEntryHash_PrefersBin(t *testing.T) { +func TestPluginEntryHash_UsesBin(t *testing.T) { dir := t.TempDir() - mustWrite(t, filepath.Join(dir, "plugin.so"), "so content") mustWrite(t, filepath.Join(dir, "plugin.bin"), "bin content") h1 := pluginEntryHash(dir) @@ -133,19 +170,22 @@ func TestPluginEntryHash_PrefersBin(t *testing.T) { t.Fatal("应算出 hash") } - // 改 .so 不应影响 hash（因为以 .bin 为准） - mustWrite(t, filepath.Join(dir, "plugin.so"), "so content CHANGED") - if h2 := pluginEntryHash(dir); h2 != h1 { - t.Error("plugin.bin 存在时 hash 不应受 plugin.so 变化影响") - } - - // 改 .bin 必须改变 hash mustWrite(t, filepath.Join(dir, "plugin.bin"), "bin content CHANGED") - if h3 := pluginEntryHash(dir); h3 == h1 { + if h2 := pluginEntryHash(dir); h2 == h1 { t.Error("plugin.bin 变化必须反映到 hash（否则增量重载失效）") } } +// C ABI 产物不再参与 hash 计算：内核已不认它，把它算进去会让 +// 「换了 .so」触发一次无意义的重载尝试。 +func TestPluginEntryHash_IgnoresLegacyCABI(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "plugin.so"), "so content") + if h := pluginEntryHash(dir); h != "" { + t.Errorf("只有 .so 时应返回空串（C ABI 已退场），实际 %q", h) + } +} + func TestPluginEntryHash_EmptyForFactoryOnlyPlugin(t *testing.T) { if h := pluginEntryHash(t.TempDir()); h != "" { t.Errorf("无入口文件应返回空串（内置纯工厂插件），实际 %q", h) diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go index 8755032..b67adfc 100644 --- a/internal/plugin/registry.go +++ b/internal/plugin/registry.go @@ -374,7 +374,7 @@ func (r *Registry) isDisabled(name string) bool { // plugin.bin 排在最前：与 detectEntryKind 保持一致的优先级，迁移期间同目录 // 两种产物共存时以子进程产物为准。 func pluginEntryHash(plgDir string) string { - for _, candidate := range []string{binEntry, soEntry, dllEntry, "plugin.dylib", luaEntry, skillEntry} { + for _, candidate := range []string{binEntry, luaEntry, skillEntry} { path := filepath.Join(plgDir, candidate) if data, err := os.ReadFile(path); err == nil && len(data) > 0 { sum := sha256.Sum256(data) @@ -905,8 +905,10 @@ func (r *Registry) PluginDir() string { } func (r *Registry) tryDynamic(plgDir, name string, config map[string]interface{}) (sdk.Plugin, error) { - // 按 manifest entry 分派到对应加载通道（外部插件多进程化：.so/.dll 与 .bin 双通道共存）。 - // 这使迁移可逐插件推进、随时回退——把 entry 改回 plugin.so 即回到旧通道。 + // 按 manifest entry 分派加载通道。 + // + // C ABI 通道（.so/.dll/.dylib）已整体删除：外部插件统一走子进程， + // 三套独立 ABI 实现收敛为单一 RPC 实现（§9.2）。 if detectEntryKind(plgDir) == entryProc { plg, err := r.loadProc(plgDir, name, config) if err != nil { @@ -916,29 +918,21 @@ func (r *Registry) tryDynamic(plgDir, name string, config map[string]interface{} log.Printf("[plugin] %s: 经 proc 通道加载（子进程）", name) return plg, nil } - // entry 声明了 plugin.bin 但文件不存在/不可用 → 不隐式回退到 cabi， - // 否则"已迁移插件静默跑回旧通道"极难排查。 return nil, fmt.Errorf("plugin %s: entry 声明 %s 但未找到可用二进制", name, binEntry) } - // 既有探测顺序（保持不变）：.so → .dll → .lua - for _, try := range []struct { - name string - fn func(string, string, map[string]interface{}) (sdk.Plugin, error) - }{ - {"so", tryLoadSO}, - {"dll", tryLoadDLL}, - {"lua", tryLoadLua}, - } { - plg, err := try.fn(plgDir, name, config) - if err != nil { - return nil, err - } - if plg != nil { - return plg, nil - } + // 旧 .so/.dll 插件给明确错误，不静默跳过。 + // 静默跳过会让「插件目录在但没加载」看起来像配置问题， + // 而实际原因是需要用新 plugindev 重编。 + if hasLegacyCABIEntry(plgDir) { + return nil, fmt.Errorf( + "plugin %s: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。"+ + "外部插件已改为子进程模式，请用新版 plugindev 重编产出 %s"+ + "（业务代码无需修改）", name, binEntry) } - return nil, nil + + // Lua 插件仍走解释器 + return tryLoadLua(plgDir, name, config) } func (r *Registry) readConfig(plgDir string) map[string]interface{} { diff --git a/internal/plugins/pluginmgr/plugin.go b/internal/plugins/pluginmgr/plugin.go index 7f683c3..9ecf0a0 100644 --- a/internal/plugins/pluginmgr/plugin.go +++ b/internal/plugins/pluginmgr/plugin.go @@ -23,16 +23,16 @@ import ( sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" ) -// platformBinary 按当前 OS 选择正确的插件二进制文件名。 +// platformBinary 按当前 OS/ARCH 选择正确的插件二进制文件名。 // 返回 (zip内文件名, 安装后重命名). +// +// 子进程模式下各平台产物统一叫 plugin.bin（进程边界即 ABI 边界， +// 不存在 .so/.dylib/.dll 的区分），故 zip 内按平台加后缀区分， +// 解包时挑当前平台那一份重命名为 plugin.bin。 func platformBinary() (zipName, canonicalName string) { switch runtime.GOOS { - case "linux": - return "plugin.so", "plugin.so" - case "darwin": - return "plugin.dylib", "plugin.so" // dlopen 兼容 .so 名称 - case "windows": - return "plugin.dll", "plugin.dll" + case "linux", "darwin", "windows", "freebsd": + return fmt.Sprintf("plugin.bin.%s.%s", runtime.GOOS, runtime.GOARCH), "plugin.bin" default: return "", "" } @@ -40,18 +40,17 @@ func platformBinary() (zipName, canonicalName string) { // validBinaries 是 .hmap 中所有可识别的文件入口（平台二进制或脚本）。 var validBinaries = map[string]bool{ - "plugin.so": true, - "plugin.dylib": true, - "plugin.dll": true, - "main.lua": true, - "SKILL.md": true, + "plugin.bin": true, + "main.lua": true, + "SKILL.md": true, } -// platformBinaries 是平台特定的二进制，bundle 模式下仅当前平台的被解压。 -var platformBinaries = map[string]bool{ - "plugin.so": true, - "plugin.dylib": true, - "plugin.dll": true, +// isPlatformBinary 判断 zip 条目是否为平台特定二进制（bundle 模式下仅当前平台的被解压）。 +// +// 形式：plugin.bin..。不用固定表是因为平台组合会增长 +// （linux/arm64、darwin/arm64 等），按前缀判断无需维护清单。 +func isPlatformBinary(name string) bool { + return strings.HasPrefix(name, "plugin.bin.") } var downloadClient = &http.Client{ @@ -705,17 +704,19 @@ func validatePackage(data []byte) (*pluginPackage, error) { } if len(pkg.Platforms) > 0 { - // bundle mode: check each declared platform has a matching binary + // bundle mode：每个声明的平台都要有对应二进制。 + // 子进程模式下条目形式为 plugin.bin..， + // 故按前缀匹配而不枚举架构（同一 OS 可能有 amd64/arm64 两份）。 for _, plat := range pkg.Platforms { - bin, ok := map[string]string{ - "linux": "plugin.so", - "darwin": "plugin.dylib", - "windows": "plugin.dll", - }[plat] - if !ok { - return nil, fmt.Errorf("unsupported platform: %q", plat) + prefix := "plugin.bin." + plat + "." + found := false + for name := range zipEntries { + if strings.HasPrefix(name, prefix) { + found = true + break + } } - if zipEntries[bin] { + if found { hasBinary = true } } @@ -795,11 +796,11 @@ func extractPackage(data []byte, pluginDir string) error { } // bundle mode: skip other platforms' platform-specific binaries - if isBundle && platformBinaries[f.Name] && f.Name != zipBin { + if isBundle && isPlatformBinary(f.Name) && f.Name != zipBin { continue } - // rename platform binary to canonical name (e.g. plugin.dylib → plugin.so) + // 平台二进制重命名为规范名（plugin.bin.linux.amd64 → plugin.bin） dest := fpath if isBundle && f.Name == zipBin && canonicalName != zipBin { dest = filepath.Join(target, canonicalName) @@ -808,6 +809,15 @@ func extractPackage(data []byte, pluginDir string) error { if err := copyZipEntry(f, dest); err != nil { return err } + + // 子进程插件必须可执行。 + // zip 保留了原文件权限位，但经某些工具链/传输后可能丢失； + // 内核加载时会因缺执行位报错（带 chmod +x 提示），在此提前补上。 + if filepath.Base(dest) == "plugin.bin" { + if err := os.Chmod(dest, 0o755); err != nil { + return fmt.Errorf("chmod %s: %w", dest, err) + } + } } return nil diff --git a/internal/plugins/pluginmgr/upgrade_test.go b/internal/plugins/pluginmgr/upgrade_test.go index e5ce59b..063ac4f 100644 --- a/internal/plugins/pluginmgr/upgrade_test.go +++ b/internal/plugins/pluginmgr/upgrade_test.go @@ -89,12 +89,12 @@ func buildHmap(t *testing.T, name, version string) []byte { zw := zip.NewWriter(&buf) manifest := map[string]interface{}{ "name": name, "name_zh": name, "name_en": name, - "version": version, "entry": "plugin.so", + "version": version, "entry": "plugin.bin", } mData, _ := json.Marshal(manifest) f, _ := zw.Create("plugin.json") f.Write(mData) - bin, _ := zw.Create("plugin.so") + bin, _ := zw.Create("plugin.bin") bin.Write([]byte("binary-" + name + "-" + version)) zw.Close() return buf.Bytes() @@ -152,12 +152,12 @@ func TestInstallThenUpgradeKeepsConfig(t *testing.T) { t.Fatalf("StopAndUnload not called once with demo: %v", calls) } // 新二进制写入 - soData, err := os.ReadFile(filepath.Join(dir, "demo", "plugin.so")) + binData, err := os.ReadFile(filepath.Join(dir, "demo", "plugin.bin")) if err != nil { - t.Fatalf("read new so: %v", err) + t.Fatalf("read new bin: %v", err) } - if string(soData) != "binary-demo-2.0.0" { - t.Fatalf("so not overwritten: %q", string(soData)) + if string(binData) != "binary-demo-2.0.0" { + t.Fatalf("bin not overwritten: %q", string(binData)) } // 4. 降级 v2.0.0 → v1.5.0 @@ -187,7 +187,7 @@ func TestExtractFailureRollsBack(t *testing.T) { // 构造损坏包：zip 但缺 plugin.json（extractPackage 会失败） var buf bytes.Buffer zw := zip.NewWriter(&buf) - f, _ := zw.Create("plugin.so") + f, _ := zw.Create("plugin.bin") f.Write([]byte("corrupt")) zw.Close() @@ -200,7 +200,7 @@ func TestExtractFailureRollsBack(t *testing.T) { f2, _ := zw2.Create("../../evil") f2.Write([]byte("x")) mf, _ := zw2.Create("plugin.json") - mData, _ := json.Marshal(map[string]interface{}{"name": "rollback", "version": "9.9.9", "entry": "plugin.so"}) + mData, _ := json.Marshal(map[string]interface{}{"name": "rollback", "version": "9.9.9", "entry": "plugin.bin"}) mf.Write(mData) zw2.Close() bad = rb.Bytes() diff --git a/third_party/homeagent-sdk/tools/plugindev/templates.go b/third_party/homeagent-sdk/tools/plugindev/templates.go deleted file mode 100644 index ae30b9d..0000000 --- a/third_party/homeagent-sdk/tools/plugindev/templates.go +++ /dev/null @@ -1,1296 +0,0 @@ -package main - -// tmplPlgJSON is the plg.json template -const tmplPlgJSON = `{ - "name": "{{.Plg.Name}}", - "name_zh": "{{.Plg.NameZh}}", - "name_en": "{{.Plg.NameEn}}", - "version": "{{.Plg.Version}}", - "description": "{{.Plg.Description}}", - "author": "{{.Plg.Author}}", - "entry": "{{.Plg.Entry}}", - "tags": [{{range $i, $t := .Plg.Tags}}{{if $i}}, {{end}}"{{$t}}"{{end}}], - "targets": "{{.Plg.Targets}}" -} -` - -const tmplGoMod = `module {{.ModulePath}} - -go {{.GoVersion}} - -require {{.SDKModule}} {{.SDKVersion}} -` - -const tmplPluginGo = `package main - -import ( - "fmt" - "gitcode.com/JianFeeeee/homeagent-sdk/sdk" -) - -type Plugin struct { - name string - sdk *sdk.PluginSDK -} - -func (p *Plugin) Name() string { return p.name } - -func (p *Plugin) Start(s *sdk.PluginSDK) error { - p.sdk = s - s.RegisterStopHandler(func() { fmt.Printf("[%s] stop handler running\n", p.name) }) - s.Settings().RegisterDef(sdk.ConfigDef{ - Key: "plugin.{{.Plg.Name}}.example", Default: "hello", Type: "string", - DisplayName: "示例配置", Description: "An example configuration key", - Category: "{{.Plg.Name}}", - }) - tp := p.name + "_" - s.RegisterTool(tp+"hello", sdk.ToolDef{ - Name: tp + "hello", - Description: "A hello world tool", - Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{}}, - NoMemory: false, // 工具输出对 LLM 注意力有信号价值时为 false，纯操作工具为 true - // Cleaner: func(output string) string { - // // 工具输出参与向量化/jieba/蒸馏前，在此过滤噪音 - // return output - // }, - }, p.handleHello) - fmt.Printf("[%s] started\n", p.name) - return nil -} - -func (p *Plugin) Stop() error { fmt.Printf("[%s] stopped\n", p.name); return nil } - -func (p *Plugin) handleHello(args map[string]interface{}) (interface{}, error) { - return map[string]interface{}{"content": "Hello from {{.Plg.Name}} plugin!"}, nil -} - -func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) { - return &Plugin{name: name}, nil -} -` - -const tmplSDKLua = `-- HomeAgent Lua Plugin SDK (standalone mock) -sdk = {} -function sdk.log(level, msg) print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg)) end -function sdk.register_tool(name, def, handler) print("[lua-plugin] register_tool: " .. tostring(name)) end -function sdk.register_stage(stage, handler, scope) print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope)) end -function sdk.register_api(name) print("[lua-plugin] register_api: " .. tostring(name)) end -function sdk.register_output_channel(name, caps, desc, def, handler) print("[lua-plugin] register_output_channel: " .. tostring(name)) end -function sdk.register_input_channel(name, def) print("[lua-plugin] register_input_channel: " .. tostring(name)) end -function sdk.get_setting(key) return nil end -function sdk.set_setting(key, value) print("[lua-plugin] set_setting: " .. tostring(key)) end -function sdk.inject_text(source, channel, text) print("[lua-plugin] inject_text: " .. tostring(source)) end -function sdk.inject_interrupt(source, channel, text) print("[lua-plugin] inject_interrupt: " .. tostring(source)) end -function sdk.inject_text_no_memory(source, channel, text) print("[lua-plugin] inject_text_no_memory: " .. tostring(source)) end -function sdk.set_auto_restart(enabled) print("[lua-plugin] set_auto_restart: " .. tostring(enabled)) end -sdk.memory = {} -function sdk.memory.recall(query, depth) return {entities={}, relations={}} end -function sdk.memory.commit(triples) return nil end -function sdk.memory.introspect() return {} end -function sdk.memory.merge(source, target) return 0 end -function sdk.memory.purge(criteria, hard) return 0 end -sdk.doc = {} -function sdk.doc.query(text, top_k) return {} end -function sdk.doc.insert(doc) return nil end -function sdk.doc.remove(id) return nil end -function sdk.doc.stats() return {} end -sdk.knowledge = {} -function sdk.knowledge.search(query, limit) return {} end -function sdk.knowledge.add(tag, content) return nil end -function sdk.knowledge.list() return {} end -sdk.text_memory = {} -function sdk.text_memory.append(evt) return nil end -sdk.llm = {} -function sdk.llm.list_sources() return {} end -function sdk.llm.set_source(name) return nil end -function sdk.llm.current_source() return nil end -sdk.social = {} -function sdk.social.get_person(name) return {} end -function sdk.social.get_network(name, depth) return {} end -function sdk.social.get_trait(name, trait) return {value=nil, found=false} end -function sdk.social.get_relations(name) return {} end -function sdk.social.list_persons() return {} end -sdk.settings = {} -function sdk.settings.get_core(key) return nil end -function sdk.settings.set_core(key, value) return nil end -function sdk.settings.list_core(prefix) return {} end -function sdk.settings.get_plugin(plugin, key) return nil end -function sdk.settings.set_plugin(plugin, key, value) return nil end -function sdk.settings.list_plugin(plugin, prefix) return {} end -function sdk.settings.list(prefix) return {} end -function sdk.settings.register_def(def) return nil end -function sdk.settings.defs(prefix) return {} end -function sdk.settings.dump() return {} end -function sdk.settings.plugins() return {} end -sdk.json = {} -function sdk.json.encode(val) - if type(val) == "string" then return '"' .. val:gsub('"', '\\"'):gsub('\n', '\\n') .. '"' - elseif type(val) == "number" or type(val) == "boolean" then return tostring(val) - elseif type(val) == "table" then local parts, i = {}, 1 - for k, v in pairs(val) do parts[i] = sdk.json.encode(k) .. ":" .. sdk.json.encode(v); i = i + 1 end - return "{" .. table.concat(parts, ",") .. "}" end - return "null" -end -function sdk.json.decode(str) local ok, fn = pcall(load, "return " .. str); if ok then return fn() end; return nil end -sdk.http = {} -function sdk.http.get(url) print("[lua-plugin] http.get: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end -function sdk.http.post(url, body, ct) print("[lua-plugin] http.post: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end -return sdk -` - -const tmplMainLua = `-- {{.Plg.Name}} plugin -local plugin = { name = "{{.Plg.Name}}" } -function plugin.start(sdk) - sdk.log("info", "{{.Plg.Name}} starting...") - sdk.register_tool("{{.Plg.Name}}_hello", { - description = "A hello world tool", - parameters = { type = "object", properties = {} } - }, function(args) return { content = "Hello from {{.Plg.Name}} plugin!" } end) - sdk.log("info", "{{.Plg.Name}} started") -end -function plugin.stop() sdk.log("info", "{{.Plg.Name}} stopped") end -return plugin -` - -// tmplBridge — Windows DLL C ABI bridge (unchanged) -const tmplBridge = `//go:build windows && cgo - -package main - -/* -#include -*/ -import "C" -import ( - "encoding/json" - "sync" - "unsafe" - sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" -) - -var ( - mu sync.Mutex - handleMap = map[unsafe.Pointer]*bridgeState{} -) - -type bridgeState struct { - plugin sdk.Plugin - toolDefs map[string]sdk.ToolDef - handlers map[string]sdk.ToolHandler - stages map[string]sdk.StageHandler - settings map[string]interface{} - sdk *sdk.PluginSDK -} - -func newHandle(plg sdk.Plugin) unsafe.Pointer { - mu.Lock(); defer mu.Unlock() - h := C.malloc(C.size_t(1)) - handleMap[h] = &bridgeState{ - plugin: plg, toolDefs: make(map[string]sdk.ToolDef), - handlers: make(map[string]sdk.ToolHandler), stages: make(map[string]sdk.StageHandler), - settings: make(map[string]interface{}), - } - return h -} -func getState(h unsafe.Pointer) *bridgeState { mu.Lock(); defer mu.Unlock(); return handleMap[h] } -func delState(h unsafe.Pointer) { mu.Lock(); defer mu.Unlock(); delete(handleMap, h); C.free(h) } - -//export NewPlugin -func NewPlugin(name *C.char, configJSON *C.char) unsafe.Pointer { - goName := C.GoString(name) - var config map[string]interface{} - if configJSON != nil { - var wrapper map[string]interface{} - if err := json.Unmarshal([]byte(C.GoString(configJSON)), &wrapper); err == nil { - if c, ok := wrapper["config"].(map[string]interface{}); ok { config = c } - } - } - plg, err := NewPluginFactory(goName, config) - if err != nil { return nil } - return newHandle(plg) -} - -//export StartPlugin -func StartPlugin(handle unsafe.Pointer) C.int { - bs := getState(handle) - if bs == nil { return 1 } - mockSett := &bridgeSettings{data: bs.settings} - mockSDK := sdk.New(bs.plugin.Name(), mockSett, - func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error { - bs.toolDefs[name] = def; bs.handlers[name] = handler; return nil - }, - func(stage sdk.Stage, handler sdk.StageHandler) { bs.stages[string(stage)] = handler }, - func(name string) error { return nil }, - func(name string, caps int, desc string, def sdk.ChannelDef, handler sdk.ToolHandler) error { return nil }, - ) - mockSDK.SetInputChannelRegistrar(func(name string, def sdk.ChannelDef) error { return nil }) - bs.sdk = mockSDK - if err := bs.plugin.Start(mockSDK); err != nil { return 1 } - return 0 -} - -//export StopPlugin -func StopPlugin(handle unsafe.Pointer) C.int { - bs := getState(handle) - if bs == nil { return 1 } - if bs.sdk != nil { - bs.sdk.RunStopHandlers() - } - if err := bs.plugin.Stop(); err != nil { return 1 } - return 0 -} - -//export DestroyPlugin -func DestroyPlugin(handle unsafe.Pointer) { - if bs := getState(handle); bs != nil { delState(handle) } -} - -//export GetToolDefsJSON -func GetToolDefsJSON(handle unsafe.Pointer) *C.char { - bs := getState(handle) - if bs == nil { return nil } - defs := make([]sdk.ToolDef, 0, len(bs.toolDefs)) - for _, def := range bs.toolDefs { defs = append(defs, def) } - b, _ := json.Marshal(defs) - return C.CString(string(b)) -} - -//export InvokeToolJSON -func InvokeToolJSON(handle unsafe.Pointer, toolName *C.char, argsJSON *C.char) *C.char { - bs := getState(handle) - if bs == nil || toolName == nil { return nil } - goName := C.GoString(toolName) - handler, ok := bs.handlers[goName] - if !ok { errMsg, _ := json.Marshal(map[string]interface{}{"error": "tool not found: " + goName}); return C.CString(string(errMsg)) } - var args map[string]interface{} - if argsJSON != nil { json.Unmarshal([]byte(C.GoString(argsJSON)), &args) } - r, err := handler(args) - if err != nil { errMsg, _ := json.Marshal(map[string]interface{}{"error": err.Error()}); return C.CString(string(errMsg)) } - b, _ := json.Marshal(r) - return C.CString(string(b)) -} - -//export GetStagesJSON -func GetStagesJSON(handle unsafe.Pointer) *C.char { - bs := getState(handle) - if bs == nil { return nil } - type se struct { Stage string ` + "`" + `json:"stage"` + "`" + ` } - var entries []se - for s := range bs.stages { entries = append(entries, se{s}) } - b, _ := json.Marshal(entries) - return C.CString(string(b)) -} - -//export InvokeStage -func InvokeStage(handle unsafe.Pointer, stage *C.char, contextJSON *C.char) C.int { - bs := getState(handle) - if bs == nil || stage == nil { return 1 } - goStage := C.GoString(stage) - handler, ok := bs.stages[goStage] - if !ok { return 1 } - var ctx map[string]interface{} - if contextJSON != nil { json.Unmarshal([]byte(C.GoString(contextJSON)), &ctx) } - sc := &sdk.StageContext{} - if ctx != nil { - if v, ok := ctx["raw_message"].(string); ok { sc.RawMessage = v } - if v, ok := ctx["user_id"].(string); ok { sc.UserID = v } - if v, ok := ctx["phase"].(string); ok { sc.Phase = sdk.Stage(v) } - } - if err := handler(sc); err != nil { return 1 } - return 0 -} - -//export FreeCString -func FreeCString(s *C.char) { C.free(unsafe.Pointer(s)) } - -type bridgeSettings struct{ data map[string]interface{} } -func (s *bridgeSettings) Get(key string) (interface{}, error) { v, ok := s.data[key]; if !ok { return nil, nil }; return v, nil } -func (s *bridgeSettings) Set(key string, value interface{}) error { s.data[key] = value; return nil } -func (s *bridgeSettings) List(prefix string) ([]string, error) { - var keys []string - for k := range s.data { if len(k) >= len(prefix) && k[:len(prefix)] == prefix { keys = append(keys, k) } } - return keys, nil -} -func (s *bridgeSettings) GetCore(key string) (interface{}, error) { return nil, nil } -func (s *bridgeSettings) SetCore(key string, value interface{}) error { return nil } -func (s *bridgeSettings) ListCore(prefix string) ([]string, error) { return nil, nil } -func (s *bridgeSettings) GetPlugin(plugin, key string) (interface{}, error) { return nil, nil } -func (s *bridgeSettings) SetPlugin(plugin, key string, value interface{}) error { return nil } -func (s *bridgeSettings) ListPlugin(plugin, prefix string) ([]string, error) { return nil, nil } -func (s *bridgeSettings) RegisterDef(def sdk.ConfigDef) {} -func (s *bridgeSettings) Defs(prefix string) []*sdk.ConfigDef { return nil } -func (s *bridgeSettings) Dump() map[string]interface{} { return s.data } -func (s *bridgeSettings) Plugins() []string { return nil } - -func main() {} -` - -// tmplCABIHeader — shared C ABI type definitions for both core and plugin -// 此模板中的常量应与 core/internal/meta/meta.go 保持一致（ABI 版本、dispatch method IDs）。 -const tmplCABIHeader = ` -#ifndef HOMEAGENT_CABI_H -#define HOMEAGENT_CABI_H -// HOMEAGENT_ABI_VERSION 与 sdk/meta/meta.go CABINum 同步（major*100+minor，v0.9.x→900） -#define HOMEAGENT_ABI_VERSION 900 -#ifdef __cplusplus -extern "C" { -#endif - -// PluginAPI — implemented by the plugin, called by the core -typedef struct { - int version; int version_min; - int (*init_plugin)(char*, char*, char**); - int (*start_plugin)(void*, int, char**); - int (*stop_plugin)(char**); - int (*invoke_tool)(char*, char*, char**, char**); - int (*invoke_stage)(char*, char*, char**, char**); - int (*invoke_output)(char*, char*, char*, char**); - void (*free_string)(char*); -} PluginAPI; - -// CoreAPI — implemented by the core, passed to plugin via start_plugin -// Uses single dispatch function to avoid function pointer ABI issues -typedef struct { - int version; int version_min; - int (*dispatch)(int method_id, void* ctx, char* s1, char* s2, char* s3, int i1, int i2, char** result, char** error); - void* ctx; -} CoreAPI; - -// Dispatch method IDs (plugin→core SDK calls) -enum { - CORE_REGISTER_TOOL = 1, - CORE_REGISTER_STAGE = 2, - CORE_REGISTER_OUTPUT_CH = 3, - CORE_REGISTER_PLUGIN_API = 4, - CORE_INJECT_TEXT = 5, - CORE_INJECT_INTERRUPT_TEXT = 6, - CORE_INJECT_TEXT_NO_MEMORY = 7, - CORE_INJECT_INPUT_SYNC = 47, - CORE_SET_AUTO_RESTART = 8, - CORE_MEMORY_RECALL = 9, - CORE_MEMORY_COMMIT = 10, - CORE_MEMORY_INTROSPECT = 11, - CORE_MEMORY_MERGE = 12, - CORE_MEMORY_PURGE = 13, - CORE_DOC_QUERY = 14, - CORE_KNOWLEDGE_SEARCH = 15, - CORE_SETTINGS_GET = 16, - CORE_SETTINGS_SET = 17, - CORE_SETTINGS_REGISTER_DEF = 18, - CORE_LLM_LIST_SOURCES = 19, - CORE_LLM_SET_SOURCE = 20, - CORE_SOCIAL_GET_PERSON = 21, - CORE_SOCIAL_GET_NETWORK = 22, - CORE_SUBSCRIBE = 23, - CORE_UNSUBSCRIBE = 24, - CORE_FREE_STRING = 25, - CORE_SETTINGS_GET_CORE = 26, - CORE_SETTINGS_SET_CORE = 27, - CORE_SETTINGS_LIST_CORE = 28, - CORE_SETTINGS_GET_PLUGIN = 29, - CORE_SETTINGS_SET_PLUGIN = 30, - CORE_SETTINGS_LIST_PLUGIN = 31, - CORE_DOC_INSERT = 32, - CORE_DOC_REMOVE = 33, - CORE_DOC_STATS = 34, - CORE_KNOWLEDGE_ADD = 35, - CORE_KNOWLEDGE_LIST = 36, - CORE_LLM_CURRENT_SOURCE = 37, - CORE_SOCIAL_GET_TRAIT = 38, - CORE_SOCIAL_GET_RELATIONS = 39, - CORE_SOCIAL_LIST_PERSONS = 40, - CORE_TEXT_MEMORY_APPEND = 41, - CORE_SETTINGS_LIST = 42, - CORE_SETTINGS_DEFS = 43, - CORE_SETTINGS_DUMP = 44, - CORE_SETTINGS_PLUGINS = 45, - CORE_REGISTER_INPUT_CH = 46, - CORE_INJECT_INPUT_SYNC = 47, - CORE_PLUGIN_RELOAD_ONE = 48, - CORE_PLUGIN_LIST_LOADED = 49, - CORE_PLUGIN_IS_DISABLED = 50, -}; - -#ifdef __cplusplus -} -#endif -#endif -` - -// tmplLinuxBridge — auto-generated Go bridge for Linux c-shared builds. -// Called by plugin's Start() with a PluginSDK that wraps CoreAPI dispatch. -// PluginSDK calls go through C ABI → CoreAPI dispatch → core's Go PluginSDK. -const tmplLinuxBridge = `package main - -/* -#include -int ha_dispatch(int method_id, void* core_api, char* s1, char* s2, char* s3, int i1, int i2, char** result, char** error); -*/ -import "C" -import ( - "encoding/json" - "fmt" - "sync" - "unsafe" - sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" -) - -// ---- global state ---- - -var ( - mu sync.Mutex - currentPlg sdk.Plugin - currentSDK *sdk.PluginSDK - coreAPI unsafe.Pointer - - handlerMu sync.RWMutex - coreAPIMu sync.RWMutex - toolHandlers = map[string]sdk.ToolHandler{} - stageHandlers = map[string]sdk.StageHandler{} - outputHandlers = map[string]sdk.ToolHandler{} -) - -// ---- CoreAPI dispatch helpers ---- - -func callVoid(methodID int, s1, s2, s3 string, i1, i2 int) error { - coreAPIMu.RLock() - api := coreAPI - coreAPIMu.RUnlock() - var c1, c2, c3 *C.char - if s1 != "" { c1 = C.CString(s1); defer C.free(unsafe.Pointer(c1)) } - if s2 != "" { c2 = C.CString(s2); defer C.free(unsafe.Pointer(c2)) } - if s3 != "" { c3 = C.CString(s3); defer C.free(unsafe.Pointer(c3)) } - var cErr *C.char - if C.ha_dispatch(C.int(methodID), api, c1, c2, c3, C.int(i1), C.int(i2), nil, &cErr) != 0 && cErr != nil { - return fmt.Errorf("%s", C.GoString(cErr)) - } - return nil -} - -func callString(methodID int, s1, s2, s3 string, i1, i2 int) (string, error) { - coreAPIMu.RLock() - api := coreAPI - coreAPIMu.RUnlock() - var c1, c2, c3 *C.char - if s1 != "" { c1 = C.CString(s1); defer C.free(unsafe.Pointer(c1)) } - if s2 != "" { c2 = C.CString(s2); defer C.free(unsafe.Pointer(c2)) } - if s3 != "" { c3 = C.CString(s3); defer C.free(unsafe.Pointer(c3)) } - var strResult, cErr *C.char - if C.ha_dispatch(C.int(methodID), api, c1, c2, c3, C.int(i1), C.int(i2), &strResult, &cErr) != 0 && cErr != nil { - return "", fmt.Errorf("%s", C.GoString(cErr)) - } - if strResult != nil { - result := C.GoString(strResult) - C.ha_dispatch(C.int(25), api, strResult, nil, nil, 0, 0, nil, nil) - return result, nil - } - return "", nil -} - -// ---- buildPluginSDK: PluginSDK backed by CoreAPI dispatch ---- -// - ALL SDK methods route through C ABI → CoreAPI → core's PluginSDK -// - Handlers for tools/stages/output are stored locally AND registered via dispatch - -func buildPluginSDK(name string) *sdk.PluginSDK { - sett := &dispatchSettings{} - base := sdk.New(name, sett, - func(toolName string, def sdk.ToolDef, handler sdk.ToolHandler) error { - handlerMu.Lock() - toolHandlers[toolName] = handler - handlerMu.Unlock() - b, _ := json.Marshal(def) - return callVoid(1, toolName, string(b), "", 0, 0) - }, - func(stage sdk.Stage, handler sdk.StageHandler) { - handlerMu.Lock() - stageHandlers[string(stage)] = handler - handlerMu.Unlock() - callVoid(2, string(stage), "", "", 0, 0) - }, - func(name string) error { return callVoid(4, name, "", "", 0, 0) }, - func(name string, caps int, desc string, def sdk.ChannelDef, handler sdk.ToolHandler) error { - handlerMu.Lock() - outputHandlers[name] = handler - handlerMu.Unlock() - defJSON, _ := json.Marshal(def) - return callVoid(3, name, desc, string(defJSON), caps, 0) - }, - ) - base.SetIOInjector(dispatchIO{}) - base.SetMemoryAPI(dispatchMemory{}) - base.SetDocMemoryAPI(dispatchDocMemory{}) - base.SetKnowledgeAPI(dispatchKnowledge{}) - base.SetLLMAPI(dispatchLLM{}) - base.SetSocialAPI(dispatchSocial{}) - base.SetTextMemoryAPI(dispatchTextMemory{}) - base.SetPluginMgrAPI(dispatchPluginMgr{}) - base.SetInputChannelRegistrar( - func(name string, def sdk.ChannelDef) error { - defJSON, _ := json.Marshal(def) - return callVoid(46, name, string(defJSON), "", 0, 0) - }, - ) - return base -} - -// ---- dispatch IO (inline definitions) ---- - -type dispatchIO struct{} -func (dispatchIO) InjectInterruptText(s, c, t string) { callVoid(6, s, c, t, 0, 0) } -func (dispatchIO) InjectText(s, c, t string) { callVoid(5, s, c, t, 0, 0) } -func (dispatchIO) InjectTextNoMemory(s, c, t string) { callVoid(7, s, c, t, 0, 0) } -func (dispatchIO) InjectInputSync(s, c, t string) string { r, _ := callString(47, s, c, t, 0, 0); return r } -// SetToolBlocks 是 Go 原生（非 ABI）的多模态注入；跨 ABI 的外部插件无对应内核桥接， -// 故为空实现（满足接口即可）。需要多模态块时用插件内自持 SDK，不走 ABI。 -func (dispatchIO) SetToolBlocks([]sdk.ContentBlock) {} - -type dispatchMemory struct{} -func (dispatchMemory) Recall(q []string, d int) ([]sdk.Entity, []sdk.Relation, error) { - b, _ := json.Marshal(q); r, e := callString(9, string(b), "", "", d, 0) - if e != nil || r == "" { return nil, nil, e } - var v struct{ Entities []sdk.Entity; Relations []sdk.Relation } - if e = json.Unmarshal([]byte(r), &v); e != nil { return nil, nil, e } - if v.Entities == nil { v.Entities = []sdk.Entity{} } - if v.Relations == nil { v.Relations = []sdk.Relation{} } - return v.Entities, v.Relations, nil -} -func (dispatchMemory) Commit(t []sdk.Triple) error { b, _ := json.Marshal(t); return callVoid(10, string(b), "", "", 0, 0) } -func (dispatchMemory) Introspect() (map[string]interface{}, error) { r, e := callString(11, "", "", "", 0, 0); if e != nil || r == "" { return nil, e }; var m map[string]interface{}; return m, json.Unmarshal([]byte(r), &m) } -func (dispatchMemory) MergeEntities(s, t string) (int, error) { return 1, callVoid(12, s, t, "", 0, 0) } -func (dispatchMemory) Purge(c map[string]string, m string) (int, error) { b, _ := json.Marshal(c); i := 0; if m == "hard" { i = 1 }; return 1, callVoid(13, string(b), "", "", i, 0) } - -type dispatchDocMemory struct{} -func (dispatchDocMemory) Query(t string, k int) []*sdk.Doc { r, e := callString(14, t, "", "", k, 0); if e != nil || r == "" { return nil }; var d []*sdk.Doc; json.Unmarshal([]byte(r), &d); return d } -func (dispatchDocMemory) Insert(doc *sdk.Doc) error { b, _ := json.Marshal(doc); return callVoid(32, string(b), "", "", 0, 0) } -func (dispatchDocMemory) Remove(id string) { callVoid(33, id, "", "", 0, 0) } -func (dispatchDocMemory) Stats() map[string]interface{} { r, e := callString(34, "", "", "", 0, 0); if e != nil || r == "" { return nil }; var m map[string]interface{}; json.Unmarshal([]byte(r), &m); return m } - -type dispatchKnowledge struct{} -func (dispatchKnowledge) Search(q string, k int) ([]*sdk.Knowledge, error) { r, e := callString(15, q, "", "", k, 0); if e != nil || r == "" { return nil, e }; var v []*sdk.Knowledge; return v, json.Unmarshal([]byte(r), &v) } -func (dispatchKnowledge) Add(n, c string) error { return callVoid(35, n, c, "", 0, 0) } -func (dispatchKnowledge) List() ([]string, error) { r, e := callString(36, "", "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v []string; return v, json.Unmarshal([]byte(r), &v) } - -type dispatchLLM struct{} -func (dispatchLLM) ListSources() []string { r, e := callString(19, "", "", "", 0, 0); if e != nil || r == "" { return nil }; var v []string; json.Unmarshal([]byte(r), &v); return v } -func (dispatchLLM) SetSource(n string) error { return callVoid(20, n, "", "", 0, 0) } -func (dispatchLLM) CurrentSource() string { r, e := callString(37, "", "", "", 0, 0); if e != nil || r == "" { return "" }; return r } - -type dispatchSocial struct{} -func (dispatchSocial) GetPerson(n string) (*sdk.PersonProfile, error) { r, e := callString(21, n, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v sdk.PersonProfile; return &v, json.Unmarshal([]byte(r), &v) } -func (dispatchSocial) GetTrait(n, t string) (string, bool) { r, e := callString(38, n, t, "", 0, 0); if e != nil || r == "" { return "", false }; var m map[string]interface{}; json.Unmarshal([]byte(r), &m); v, _ := m["value"].(string); ok, _ := m["found"].(bool); return v, ok } -func (dispatchSocial) GetRelations(name string) ([]sdk.SocialRelation, error) { r, e := callString(39, name, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v []sdk.SocialRelation; return v, json.Unmarshal([]byte(r), &v) } -func (dispatchSocial) GetNetwork(n string, d int) ([]*sdk.PersonProfile, error) { r, e := callString(22, n, "", "", d, 0); if e != nil || r == "" { return nil, e }; var v []*sdk.PersonProfile; return v, json.Unmarshal([]byte(r), &v) } -func (dispatchSocial) ListPersons() ([]string, error) { r, e := callString(40, "", "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v []string; return v, json.Unmarshal([]byte(r), &v) } - -type dispatchTextMemory struct{} -func (dispatchTextMemory) Append(evt sdk.TextEvent) error { b, _ := json.Marshal(evt); return callVoid(41, string(b), "", "", 0, 0) } - -// ---- dispatchPluginMgr (CORE_PLUGIN_RELOAD_ONE = 48) ---- - -type dispatchPluginMgr struct{} - -func (dispatchPluginMgr) ReloadOne(name string) error { - return callVoid(48, name, "", "", 0, 0) -} - -func (dispatchPluginMgr) ListLoadedPlugins() []string { - r, e := callString(49, "", "", "", 0, 0) - if e != nil || r == "" { - return nil - } - var list []string - if json.Unmarshal([]byte(r), &list) != nil { - return nil - } - return list -} - -func (dispatchPluginMgr) IsPluginDisabled(name string) bool { - r, e := callString(50, name, "", "", 0, 0) - return e == nil && r == "1" -} - -// ---- dispatchSettings (inline) ---- - -type dispatchSettings struct{} -func (d *dispatchSettings) Get(key string) (interface{}, error) { - r, e := callString(16, key, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v interface{}; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) Set(key string, value interface{}) error { - b, _ := json.Marshal(value); return callVoid(17, key, string(b), "", 0, 0) -} -func (d *dispatchSettings) RegisterDef(def sdk.ConfigDef) { b, _ := json.Marshal(def); callVoid(18, string(b), "", "", 0, 0) } -func (d *dispatchSettings) List(prefix string) ([]string, error) { - r, e := callString(42, prefix, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v []string; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) GetCore(key string) (interface{}, error) { - r, e := callString(26, key, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v interface{}; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) SetCore(key string, value interface{}) error { - b, _ := json.Marshal(value); return callVoid(27, key, string(b), "", 0, 0) -} -func (d *dispatchSettings) ListCore(prefix string) ([]string, error) { - r, e := callString(28, prefix, "", "", 0, 0); if e != nil || r == "" { return nil, e }; var v []string; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) GetPlugin(plugin, key string) (interface{}, error) { - r, e := callString(29, plugin, key, "", 0, 0); if e != nil || r == "" { return nil, e }; var v interface{}; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) SetPlugin(plugin, key string, value interface{}) error { - b, _ := json.Marshal(value); return callVoid(30, plugin, key, string(b), 0, 0) -} -func (d *dispatchSettings) ListPlugin(plugin, prefix string) ([]string, error) { - r, e := callString(31, plugin, prefix, "", 0, 0); if e != nil || r == "" { return nil, e }; var v []string; return v, json.Unmarshal([]byte(r), &v) -} -func (d *dispatchSettings) Defs(prefix string) []*sdk.ConfigDef { - r, e := callString(43, prefix, "", "", 0, 0); if e != nil || r == "" { return nil }; var v []*sdk.ConfigDef; json.Unmarshal([]byte(r), &v); return v -} -func (d *dispatchSettings) Dump() map[string]interface{} { - r, e := callString(44, "", "", "", 0, 0); if e != nil || r == "" { return nil }; var m map[string]interface{}; json.Unmarshal([]byte(r), &m); return m -} -func (d *dispatchSettings) Plugins() []string { - r, e := callString(45, "", "", "", 0, 0); if e != nil || r == "" { return nil }; var v []string; json.Unmarshal([]byte(r), &v); return v -} -func (d *dispatchSettings) DataDir() string { - r, e := callString(51, "", "", "", 0, 0); if e != nil { return "" }; return r -} - -// ---- Go callbacks (called from z_entry.c via C) ---- - -//export go_init_plugin -func go_init_plugin(name *C.char, configJSON *C.char, errorOut **C.char) C.int { - plg, err := NewPluginFactory(C.GoString(name), nil) - if err != nil || plg == nil { - if err != nil { *errorOut = C.CString(err.Error()) } else { *errorOut = C.CString("NewPluginFactory returned nil") } - return 1 - } - mu.Lock(); currentPlg = plg; mu.Unlock() - _ = configJSON - return 0 -} - -//export go_start_plugin -func go_start_plugin(coreAPIptr unsafe.Pointer, coreVersion C.int, errorOut **C.char) C.int { - mu.Lock() - plg := currentPlg - coreAPIMu.Lock() - coreAPI = coreAPIptr - coreAPIMu.Unlock() - mu.Unlock() - _ = coreVersion - if plg == nil { *errorOut = C.CString("not initialized"); return 1 } - sdk := buildPluginSDK(plg.Name()) - mu.Lock(); currentSDK = sdk; mu.Unlock() - if err := plg.Start(sdk); err != nil { *errorOut = C.CString(err.Error()); return 1 } - return 0 -} - -//export go_stop_plugin -func go_stop_plugin(errorOut **C.char) C.int { - mu.Lock() - plg := currentPlg - sdk := currentSDK - currentPlg = nil - currentSDK = nil - coreAPIMu.Lock() - coreAPI = nil - coreAPIMu.Unlock() - mu.Unlock() - if sdk != nil { - sdk.RunStopHandlers() - } - if plg != nil { - if err := plg.Stop(); err != nil { *errorOut = C.CString(err.Error()); return 1 } - } - return 0 -} - -//export go_invoke_tool -func go_invoke_tool(name *C.char, argsJSON *C.char, resultOut **C.char, errorOut **C.char) C.int { - goName := C.GoString(name) - handlerMu.RLock() - h, ok := toolHandlers[goName] - handlerMu.RUnlock() - if !ok { *errorOut = C.CString("tool not found"); return 1 } - var args map[string]interface{} - if argsJSON != nil { json.Unmarshal([]byte(C.GoString(argsJSON)), &args) } - r, err := h(args) - if err != nil { *errorOut = C.CString(err.Error()); return 1 } - b, _ := json.Marshal(r) - *resultOut = C.CString(string(b)) - return 0 -} - -// fillStageContext 将内核传来的 ctx JSON 填充到插件侧 StageContext。 -func fillStageContext(sc *sdk.StageContext, ctxJSON string) { - var m map[string]interface{} - if err := json.Unmarshal([]byte(ctxJSON), &m); err != nil { - return - } - if v, _ := m["raw_message"].(string); v != "" { sc.RawMessage = v } - if v, _ := m["user_id"].(string); v != "" { sc.UserID = v } - if v, _ := m["group_id"].(string); v != "" { sc.GroupID = v } - if v, _ := m["phase"].(string); v != "" { sc.Phase = sdk.Stage(v) } - if v, _ := m["llm_text"].(string); v != "" { sc.LLMText = v } - if v, _ := m["final_text"].(string); v != "" { sc.FinalText = v } - if v, _ := m["no_memory"].(bool); v { sc.NoMemory = true } - if v, _ := m["response"].(string); v != "" { sc.Response = &v } - if v, _ := m["tool_calls"].([]interface{}); len(v) > 0 { - b, _ := json.Marshal(v); json.Unmarshal(b, &sc.ToolCalls) - } - if v, _ := m["tool_results"].([]interface{}); len(v) > 0 { - b, _ := json.Marshal(v); json.Unmarshal(b, &sc.ToolResults) - } -} - -// stageContextWritable 提取插件可写且内核会同步回去的字段。 -func stageContextWritable(sc *sdk.StageContext) map[string]interface{} { - m := map[string]interface{}{ - "raw_message": sc.RawMessage, - "user_id": sc.UserID, - "group_id": sc.GroupID, - "phase": string(sc.Phase), - "llm_text": sc.LLMText, - "final_text": sc.FinalText, - "no_memory": sc.NoMemory, - } - if sc.Response != nil { - m["response"] = *sc.Response - } - if len(sc.ToolCalls) > 0 { - m["tool_calls"] = sc.ToolCalls - } - if len(sc.ToolResults) > 0 { - m["tool_results"] = sc.ToolResults - } - return m -} - -// changedFieldsOnly 返回插件 handler 真正变更的字段，供内核写回。 -// 修复 plan.md 11.3：旧实现无条件回传 stageContextWritable 的全部字段（含插件 -// 从内核收到的旧快照），两个插件并发时，只读插件会把自己收到的旧值覆盖回 -// 改写插件已清洗的结果（实验 13 复刻现网 sanitizer + weather 场景，丢失率 1.6~4.3%）。 -// 只回传差异字段后，只读插件零回传，改写插件的清洗结果不再被覆盖。 -// -// ❗ before 必须是 handler 运行前的**序列化快照**（snapshotWritable），不能直接存 Go 值： -// stageContextWritable 返回的 tool_calls/tool_results 与 sc 共享切片底层数组，handler -// 原地修改元素（如 sc.ToolResults[0].Result = clean）会让 before 同步变化，diff 将看不到变更。 -func changedFieldsOnly(before map[string]string, after map[string]interface{}) map[string]interface{} { - diff := map[string]interface{}{} - keys := map[string]bool{} - for k := range before { - keys[k] = true - } - for k := range after { - keys[k] = true - } - for k := range keys { - bRaw, bHas := before[k] - a, aHas := after[k] - switch { - case aHas && !bHas: - diff[k] = a - case aHas && bHas: - ab, _ := json.Marshal(a) - if bRaw != string(ab) { - diff[k] = a - } - case bHas && !aHas: - // 插件把切片类字段清空了（writable 对 len==0 不输出），显式回传空值 - switch k { - case "tool_calls": - diff[k] = []sdk.ToolCall{} - case "tool_results": - diff[k] = []sdk.ToolResult{} - case "response": - // response 从非 nil 变 nil：内核侧 applyStageResult 无法表达「清空」， - // 且短路语义不应被插件撑销，故不回传。 - } - } - } - return diff -} - -// snapshotWritable 把 writable 字段逐个序列化成 JSON 字符串，作为 handler 前的不可变快照。 -// 必须序列化：否则切片字段与 sc 共享底层数组，handler 原地改元素时快照跟着变，diff 失效。 -func snapshotWritable(sc *sdk.StageContext) map[string]string { - snap := map[string]string{} - for k, v := range stageContextWritable(sc) { - b, err := json.Marshal(v) - if err != nil { - continue - } - snap[k] = string(b) - } - return snap -} - -//export go_invoke_stage -func go_invoke_stage(stage *C.char, ctxJSON *C.char, resultOut **C.char, errorOut **C.char) C.int { - goStage := C.GoString(stage) - handlerMu.RLock() - h, ok := stageHandlers[goStage] - handlerMu.RUnlock() - if !ok { return 0 } - sc := &sdk.StageContext{} - if ctxJSON != nil { - fillStageContext(sc, C.GoString(ctxJSON)) - } - // plan.md 11.3：记录 handler 前的**序列化**快照，回传时只带真正变更的字段， - // 避免只读插件把自己收到的旧快照覆盖其他插件的改写（lost update）。 - before := snapshotWritable(sc) - if err := h(sc); err != nil { *errorOut = C.CString(err.Error()); return 1 } - // ABI v2: 回传插件修改后的上下文（若调用方要求）——只回传差异字段 - if resultOut != nil { - diff := changedFieldsOnly(before, stageContextWritable(sc)) - if len(diff) == 0 { - return 0 // 无变更（如只读插件）→ 不回传，内核不写回 - } - if b, err := json.Marshal(diff); err == nil { - *resultOut = C.CString(string(b)) - } - } - return 0 -} - -//export go_invoke_output -func go_invoke_output(channel *C.char, msgType *C.char, payloadJSON *C.char, errorOut **C.char) C.int { - goChan := C.GoString(channel) - handlerMu.RLock() - h, ok := outputHandlers[goChan] - handlerMu.RUnlock() - if !ok { return 0 } - // payloadJSON contains the full args JSON from output_send (e.g. {"content":"...","user_id":123}) - var args map[string]interface{} - if payloadJSON != nil { - json.Unmarshal([]byte(C.GoString(payloadJSON)), &args) - } - if _, err := h(args); err != nil { *errorOut = C.CString(err.Error()); return 1 } - return 0 -} - -//export go_free_string -func go_free_string(ptr *C.char) { C.free(unsafe.Pointer(ptr)) } - -func main() {} -` - -// tmplPluginInitC — C entry point for the plugin .so file. -// Contains PluginAPI, CoreAPI (single dispatch), and ha_dispatch bridge. -const tmplPluginInitC = `#include -#include - -// HOMEAGENT_ABI_VERSION 与 sdk/meta/meta.go CABINum 同步（major*100+minor，v0.9.x→900） -#define HOMEAGENT_ABI_VERSION 900 - -typedef struct { - int version; int version_min; - int (*init_plugin)(char*, char*, char**); - int (*start_plugin)(void*, int, char**); - int (*stop_plugin)(char**); - int (*invoke_tool)(char*, char*, char**, char**); - int (*invoke_stage)(char*, char*, char**, char**); - int (*invoke_output)(char*, char*, char*, char**); - void (*free_string)(char*); -} PluginAPI; - -typedef struct { - int version; int version_min; - int (*dispatch)(int, void*, char*, char*, char*, int, int, char**, char**); - void* ctx; -} CoreAPI; - -extern int go_init_plugin(char*, char*, char**); -extern int go_start_plugin(void*, int, char**); -extern int go_stop_plugin(char**); -extern int go_invoke_tool(char*, char*, char**, char**); -extern int go_invoke_stage(char*, char*, char**, char**); -extern int go_invoke_output(char*, char*, char*, char**); -extern void go_free_string(char*); - -int c_init_plugin(char* n, char* c, char** e) { return go_init_plugin(n, c, e); } -int c_start_plugin(void* a, int v, char** e) { return go_start_plugin(a, v, e); } -int c_stop_plugin(char** e) { return go_stop_plugin(e); } -int c_invoke_tool(char* n, char* a, char** r, char** e) { return go_invoke_tool(n, a, r, e); } -int c_invoke_stage(char* s, char* c, char** r, char** e) { return go_invoke_stage(s, c, r, e); } -int c_invoke_output(char* c, char* m, char* p, char** e) { return go_invoke_output(c, m, p, e); } -void c_free_string(char* p) { go_free_string(p); } - -// ha_dispatch — called by Go bridge, passes through to CoreAPI dispatch -int ha_dispatch(int id, void* api, char* s1, char* s2, char* s3, int i1, int i2, char** r, char** e) { - CoreAPI* a = (CoreAPI*)api; - if (!a || !a->dispatch) return 1; - return a->dispatch(id, a->ctx, s1, s2, s3, i1, i2, r, e); -} - -PluginAPI* plugin_init(void) { - static PluginAPI api; - memset(&api, 0, sizeof(api)); - api.version = HOMEAGENT_ABI_VERSION; api.version_min = HOMEAGENT_ABI_VERSION; - api.init_plugin = c_init_plugin; api.start_plugin = c_start_plugin; api.stop_plugin = c_stop_plugin; - api.invoke_tool = c_invoke_tool; api.invoke_stage = c_invoke_stage; api.invoke_output = c_invoke_output; - api.free_string = c_free_string; - return &api; -} -` - -// ============================================================ -// Remote Device Adapter Templates -// ============================================================ - -const tmplRemoteDeviceMain = `#include -#include -#include - -#include "ha_remotedevice.h" - -/* ============================================================ - * {{.Plg.Name}} — Remote Device Adapter - * - * 声明式远程设备接入示例。 - * 用户只需实现： - * 1. ha_transport_t 的 4 个函数 - * 2. 声明 handlers 表（设备支持哪些命令 + 对应的处理函数） - * 其余协议细节（WS 握手、hello/bind、心跳、重连、命令分发、结果回执）由 SDK 自动处理。 - * ============================================================ */ - -/* ====================== 传输层实现 ====================== - * - * 请为你的平台实现以下 4 个函数： - * connect(ctx, host, port) — 建立 TCP 连接 - * send(ctx, data, len) — 发送数据 - * recv(ctx, buf, len) — 接收数据（阻塞，返回实际接收字节数） - * close(ctx) — 关闭连接 - * - * 示例：POSIX socket 实现 - */ - -#if defined(_WIN32) || defined(_WIN64) -/* Windows 平台需包含 winsock2.h */ -#error "Please implement transport for your platform (see example below)" -#else -/* POSIX (Linux, macOS, ESP-IDF, Zephyr, etc.) */ -#include -#include -#include -#include -#include - -struct transport_ctx { - int sock; -}; - -static int transport_connect(void *ctx, const char *host, uint16_t port) { - struct transport_ctx *tc = (struct transport_ctx *)ctx; - struct hostent *he = gethostbyname(host); - if (!he) return -1; - tc->sock = socket(AF_INET, SOCK_STREAM, 0); - if (tc->sock < 0) return -1; - struct sockaddr_in addr; - memset(&addr, 0, sizeof(addr)); - addr.sin_family = AF_INET; - addr.sin_port = htons(port); - memcpy(&addr.sin_addr, he->h_addr_list[0], he->h_length); - if (connect(tc->sock, (struct sockaddr *)&addr, sizeof(addr)) < 0) { - close(tc->sock); - tc->sock = -1; - return -1; - } - return 0; -} - -static int transport_send(void *ctx, const uint8_t *data, int len) { - struct transport_ctx *tc = (struct transport_ctx *)ctx; - int sent = 0; - while (sent < len) { - int n = (int)send(tc->sock, data + sent, len - sent, 0); - if (n <= 0) return -1; - sent += n; - } - return sent; -} - -static int transport_recv(void *ctx, uint8_t *buf, int len) { - struct transport_ctx *tc = (struct transport_ctx *)ctx; - int n = (int)recv(tc->sock, buf, len, 0); - return n; -} - -static void transport_close(void *ctx) { - struct transport_ctx *tc = (struct transport_ctx *)ctx; - if (tc->sock >= 0) { - close(tc->sock); - tc->sock = -1; - } -} -#endif - -/* ====================== 声明式命令处理 ====================== - * - * 每个命令对应一个处理函数，通过填写 ha_cmd_result_t 返回数据。 - * SDK 自动回执结果，无需手动调用 send_result。 - * - * 返回方式： - * 1. 文本输出：填写 result->output - * 2. 二进制数据：设置 result->has_binary=1 并填写 binary_data/len/mime - * 3. 错误：设置 result->status=1 并填写 result->error - * 4. 返回 HA_OK 表示处理成功，其他值表示处理失败 - */ - -/* ESP32-CAM 摄像头处理 */ -static ha_status_t handle_camerasue(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - int duration = 0; - if (args && args[0]) duration = atoi(args); - printf("[camera] %s (duration=%ds)\n", duration ? "record" : "snapshot", duration); - - /* 返回文本结果（base64 图片） */ - result->status = 0; - result->output = "data:image/jpeg;base64,/9j/4AAQ..."; - return HA_OK; -} - -/* 屏幕截图处理 */ -static ha_status_t handle_screensee(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)args; (void)userdata; - printf("[screen] screenshot\n"); - result->status = 0; - result->output = "data:image/png;base64,iVBORw0KGgo..."; - return HA_OK; -} - -/* 语音播报处理 */ -static ha_status_t handle_speakeruse(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - printf("[speaker] TTS: %s\n", args ? args : ""); - result->status = 0; - result->output = "speakeruse done"; - return HA_OK; -} - -/* 远程操控处理（computeruse） */ -static ha_status_t handle_computeruse(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - const char *action = NULL; - const char *json_str = NULL; - ha_cmd_parse_json(args, &action, &json_str); - printf("[computeruse] action=%s\n", action ? action : "unknown"); - result->status = 0; - result->output = "computeruse done"; - return HA_OK; -} - -/* 剪贴板读取 */ -static ha_status_t handle_clipboardsee(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)args; (void)userdata; - result->status = 0; - result->output = "clipboard content"; - return HA_OK; -} - -/* 剪贴板写入 */ -static ha_status_t handle_clipboardsue(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - printf("[clipboard] write: %s\n", args ? args : ""); - result->status = 0; - result->output = "clipboard written"; - return HA_OK; -} - -/* 屏幕显示 */ -static ha_status_t handle_screensue(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - printf("[screensue] show: %s\n", args ? args : ""); - result->status = 0; - result->output = "screensue shown"; - return HA_OK; -} - -/* Shell 命令处理 */ -static ha_status_t handle_shell(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)userdata; - printf("[shell] cmd: %s\n", args ? args : ""); - result->status = 0; - result->output = "shell output"; - return HA_OK; -} - -/* 设备信息查询 */ -static ha_status_t handle_deviceinfo(const char *req_id, const char *args, - ha_cmd_result_t *result, void *userdata) { - (void)req_id; (void)args; (void)userdata; - result->status = 0; - result->output = "{\"platform\":\"linux\",\"arch\":\"x86_64\"}"; - return HA_OK; -} - -/* ====================== 连接状态回调 ====================== */ - -static void on_state(int connected, void *userdata) { - (void)userdata; - printf("[devicelink] state: %s\n", connected ? "connected" : "disconnected"); -} - -/* ====================== 主函数 ====================== */ - -int main(int argc, char *argv[]) { - /* 传输层上下文 */ - struct transport_ctx tctx; - tctx.sock = -1; - - ha_transport_t transport = { - .connect = transport_connect, - .send = transport_send, - .recv = transport_recv, - .close = transport_close, - .ctx = &tctx, - }; - - /* ===== 声明式设备配置 ===== */ - - /* 声明设备能力 */ - const char *caps[] = { - "status", "cmdrun", "deviceinfo", - "camerasue", "screensee", "speakeruse", - "computeruse", "clipboardsee", "clipboardsue", - "screensue", - NULL - }; - - /* 声明命令处理表：设备支持哪些命令，以及对应的处理函数 */ - ha_cmd_handler_def_t handlers[] = { - {.command = "shell", .handler = handle_shell}, - {.command = "camerasue", .handler = handle_camerasue}, - {.command = "screensee", .handler = handle_screensee}, - {.command = "speakeruse", .handler = handle_speakeruse}, - {.command = "computeruse", .handler = handle_computeruse}, - {.command = "clipboardsee", .handler = handle_clipboardsee}, - {.command = "clipboardsue", .handler = handle_clipboardsue}, - {.command = "screensue", .handler = handle_screensue}, - {.command = "deviceinfo", .handler = handle_deviceinfo}, - {.command = NULL}, /* 标记结束 */ - }; - - ha_config_t config = { - .transport = transport, - .server = "127.0.0.1:9890", - .token = "your-token-here", - .device = { - .device_id = "{{.Plg.Name}}", - .name = "{{.Plg.NameEn}}", - .kind = "computer", - .caps = caps, - .info_json = "{\"platform\":\"linux\",\"arch\":\"x86_64\"}", - }, - .handlers = handlers, /* 声明式命令处理表 */ - .on_state = on_state, - .ping_interval = 30, - }; - - ha_client_t *client = ha_client_new(&config); - if (!client) { - fprintf(stderr, "Failed to create client\n"); - return 1; - } - - printf("Starting remote device adapter: {{.Plg.Name}}\n"); - printf(" Server: %s\n", config.server); - printf(" Device ID: %s\n", config.device.device_id); - printf(" Kind: %s\n", config.device.kind); - printf(" Caps: "); - for (const char **p = caps; *p; p++) printf("%s ", *p); - printf("\n"); - - ha_status_t st = ha_client_start(client); - if (st != HA_OK) { - fprintf(stderr, "Failed to connect: %d\n", st); - ha_client_destroy(client); - return 1; - } - - printf("Connected! Entering main loop...\n"); - - /* 主循环 */ - while (1) { - ha_status_t st = ha_client_process(client); - if (st == HA_ERR_DISCONNECTED) { - printf("Disconnected, exiting.\n"); - break; - } -#if defined(_WIN32) || defined(_WIN64) - Sleep(10); -#else - usleep(10000); -#endif - } - - ha_client_stop(client); - ha_client_destroy(client); - return 0; -} -` - -const tmplRemoteDeviceCMake = `cmake_minimum_required(VERSION 3.10) -project({{.Plg.Name}} VERSION 0.1.0 LANGUAGES C) - -# ============================================================ -# {{.Plg.Name}} — Remote Device Adapter -# ============================================================ - -# 设置 SDK 路径（默认使用内置 SDK，也可通过 -DSDK_PATH=... 指定） -set(SDK_PATH "${CMAKE_CURRENT_SOURCE_DIR}/ha_remotedevice" - CACHE PATH "Path to ha_remotedevice SDK") - -# 添加 SDK 子目录 -if(EXISTS "${SDK_PATH}/CMakeLists.txt") - add_subdirectory(${SDK_PATH} ha_remotedevice) -else() - message(FATAL_ERROR "ha_remotedevice SDK not found at ${SDK_PATH}") -endif() - -# 创建设备适配器可执行文件 -add_executable(${PROJECT_NAME} - main.c -) - -# 链接 SDK -target_link_libraries(${PROJECT_NAME} PRIVATE ha_remotedevice) - -# 包含 SDK 头文件 -target_include_directories(${PROJECT_NAME} PRIVATE - ${HA_REMOTEDEVICE_INCLUDE_DIR} -) - -# 编译选项 -if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang") - target_compile_options(${PROJECT_NAME} PRIVATE - -Wall -Wextra -Wpedantic - -Wno-unused-parameter - ) -endif() - -# 安装 -install(TARGETS ${PROJECT_NAME} RUNTIME DESTINATION bin) -` - -const tmplReadme = `# {{.Plg.Name}} - -{{.Plg.Description}} - -## Build - -` + "```bash" + ` -plugindev build -` + "```" + ` - -## Install - -Upload the .hmap file through the Plugin Manager API. -` From 1d7f011e5d3b07a28fd111cec42bec4b190cff4f Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 20:20:25 +0800 Subject: [PATCH 19/27] =?UTF-8?q?plugin:=2017=20=E6=8F=92=E4=BB=B6?= =?UTF-8?q?=E5=85=A8=E9=87=8F=E9=87=8D=E7=BC=96=20+=20=E7=AB=AF=E5=88=B0?= =?UTF-8?q?=E7=AB=AF=E5=86=92=E7=83=9F=E9=AA=8C=E8=AF=81=EF=BC=88Part=206.?= =?UTF-8?q?3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 17 个插件源码零改动，全部重编为 plugin.bin 16 个 × 3 平台（linux/darwin/windows），qq 1 平台（plg.json 自己声明 bundle:false）。luademo 走 Lua 解释器不适用。 git status example/ 无输出 —— 这是「业务代码零改动」的硬证据。 批 3 那些预估高风险的插件（qq 2686 行双向通道、browser 12 工具 + InjectInterruptText、a2a/acp 的 InjectInputSync 同步注入）一次全过， 因为它们只碰公开 SDK 合同面，而合同面在 Part 2 已 51 个 method 全量平移。 唯一一次失败与迁移无关：rss 的 github.com/mmcdole/gofeed 不在本地模块 缓存且 proxy.golang.org 不通，换 GOPROXY=https://goproxy.cn 后通过。 ## 真实 homed 加载验证 15 个外部插件全部经 proc 通道建链（protocol=1 sdk=0.9.2，各自独立 PID）， 31 个插件 loaded（15 外部 + 16 内置）。 ai_image / files 未走 proc 通道：同名内置插件优先（工厂编译期注册）， 外部插件被遮蔽。这是既有行为，与迁移无关。 事件环与共享段均正常创建，且共享段是**一块** 256KB 服务全部 15 个插件。 ## 冒烟测试 4 项（internal/plugins/real_plugin_smoke_test.go） 用真实 example 产物而非 testdata 假插件；manifest 刻意写 "entry":"plugin.so" 验证工具链与内核都已不看 entry 值。未重编时 skip 而非 fail。 - ToolInvokeRoundTrip：工具真实调用往返（此前只验证到"注册"）。 weather_current 返回结构化参数校验错误——这恰是链路通的证据。 - StageRewriteTakesEffect：sanitizer 清洗 ANSI 序列，改写经共享段回到 内核 StageContext - MultiPluginShareOneSegment：sanitizer + weather 并发，清洗结果不被覆盖 - CrashDoesNotKillKernel：SIGKILL 插件进程后 homed 存活、17 插件仍在 （对比 C ABI 下插件 panic 直接带崩 homed，§1.2 现网已发生） ## 开销实测与基线偏差 15 个插件进程 RSS=88.0MB PSS=87.9MB 线程=82，均摊 5.87MB / 5.5 线程。 RSS 88MB vs 实验 5 基线 29.1MB **不是回归，是基线不可比**：实验 5 用 2.68MB 最小插件，真实插件 3.1~14.8MB。可比的结构性指标： - 均摊线程 5.5 vs 4.9 —— 同量级，无线程膨胀 - PSS/RSS 99.9% vs 44% —— **明显差于基线** 第二项是真实发现：基线里 PSS 远低于 RSS 说明 Go runtime 只读代码页在 进程间共享；实测几乎不共享，因为 15 个插件是 15 个不同的二进制，没有 共同物理页可映射。这是「每插件独立二进制」的固有代价，意味着实际内存 开销高于 §4.3 的乐观估计。压这一项的方向是共享 launcher 二进制。 ## 工具脚本入 experiments/19-migration-verify scripts/ 被 .gitignore 排除，故放到已跟踪的 experiments 目录下， 与 01~18 的可复跑实验并列。 measure-plugin-overhead.sh 第一版有统计口径 bug：RSS 读 status 的 VmRSS、 PSS 读 smaps_rollup 的 Pss，输出 PSS(87.9MB) > RSS(69.1MB) —— 物理上不可能。 两者对共享内存段计入方式不同（smaps 的 Rss 含 Pss_Shmem）。已统一从 smaps_rollup 读。另修 bc 不可用导致 MB 全显示 0.0（改用 awk）。 Ref: docs/zh/plugin-migration-plan.md Part 6.3、docs/zh/架构迁移评估.md §4.3 --- .../plugin-arch/19-migration-verify/README.md | 83 ++++++ .../measure-plugin-overhead.sh | 82 ++++++ .../19-migration-verify/rebuild-plugins.sh | 56 ++++ internal/plugins/real_plugin_smoke_test.go | 258 ++++++++++++++++++ 4 files changed, 479 insertions(+) create mode 100644 docs/zh/experiments/plugin-arch/19-migration-verify/README.md create mode 100755 docs/zh/experiments/plugin-arch/19-migration-verify/measure-plugin-overhead.sh create mode 100755 docs/zh/experiments/plugin-arch/19-migration-verify/rebuild-plugins.sh create mode 100644 internal/plugins/real_plugin_smoke_test.go diff --git a/docs/zh/experiments/plugin-arch/19-migration-verify/README.md b/docs/zh/experiments/plugin-arch/19-migration-verify/README.md new file mode 100644 index 0000000..9b69747 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/19-migration-verify/README.md @@ -0,0 +1,83 @@ +# 实验 19：迁移验证工具（Part 6.3） + +外部插件从 C ABI 动态库迁移到子进程后的批量重编与开销实测工具。 +与 01~18 的性质不同：那些是**决策前**的可行性验证，这两个是**迁移执行期** +反复使用的操作脚本。 + +## rebuild-plugins.sh + +批量把 `example/` 下的插件重编为子进程模式（`plugin.bin`）。 + +```bash +PLUGINDEV=/tmp/plugindev ./rebuild-plugins.sh weather sanitizer qq +``` + +关键性质：**不修改任何插件源码**。`plg.json` 的 `entry` 仍写着 `"plugin.so"` +也无妨——工具链已不看这个字段（Part 6.1）。 + +两个实现细节值得记： + +- **成功判定看产物而非退出码**。plugindev 对部分错误只 `fmt.Printf` 不 + `os.Exit`，单看 `$?` 会把失败当成功。 +- 构建前清 `build/`+`dist/`。残留的 `.so` 不影响构建，但会让人误以为 + 还在用旧通道。 + +已知环境依赖：`rss` 插件需要 `github.com/mmcdole/gofeed`， +`proxy.golang.org` 不通时用 `GOPROXY=https://goproxy.cn,direct`。 + +## measure-plugin-overhead.sh + +实测 homed + 插件子进程的常驻开销。 + +```bash +./measure-plugin-overhead.sh $(pgrep -f 'homed -data' | head -1) +``` + +### 一个统计口径的坑 + +第一版混用了两个来源：RSS 读 `/proc/pid/status` 的 `VmRSS`， +PSS 读 `smaps_rollup` 的 `Pss`。结果输出 `PSS=87.9MB > RSS=69.1MB`—— +物理上不可能。 + +原因是两者对**共享内存段**的计入方式不同：`smaps_rollup` 的 `Rss` 含 +`Pss_Shmem`（共享段的按比例份额），`VmRSS` 不含。现已统一从 +`smaps_rollup` 读，保证 PSS ≤ RSS。 + +### 实测结果（2026-09-02，15 个真实插件） + +``` +15 个插件进程 RSS=88.0 MB PSS=87.9 MB 线程=82 +均摊 5.87 MB 5.86 MB 5.5 线程 +homed 本体 RSS=182 MB 线程=15 +``` + +**与实验 5 基线（17 进程 RSS=29.1MB / PSS=12.9MB / 线程=84）的偏差解释**： + +实验 5 用的是 2.68MB 的最小插件，真实插件 3.1~14.8MB（browser 依赖最多）。 +RSS 随二进制体积线性增长，故绝对数字不可比。可比的是结构性指标： + +| 指标 | 基线 | 实测 | 判断 | +|---|---|---|---| +| 均摊线程 | 4.9 | 5.5 | 同量级，无线程膨胀 | +| PSS/RSS | 44% | 99.9% | **明显差于基线** | + +第二项是真实发现：基线里 PSS 远低于 RSS，说明 Go runtime 只读代码页在 +进程间共享。实测几乎不共享，因为 15 个插件是 15 个**不同**的二进制， +没有共同的物理页可映射。 + +这是「每插件独立二进制」的固有代价，不是缺陷，但意味着实际内存开销 +高于评估文档（§4.3）的乐观估计。若日后需要压这一项，方向是让插件共享 +一个 launcher 二进制 + 各自的业务 plugin，而非各自静态链接整个 runtime。 + +## 冒烟测试 + +自动化部分在 `internal/plugins/real_plugin_smoke_test.go`（4 项）： + +- `ToolInvokeRoundTrip`：工具真实调用往返（不只是注册） +- `StageRewriteTakesEffect`：sanitizer 改写型 stage 在真实内核装配下生效 +- `MultiPluginShareOneSegment`：多插件共享一段，只读插件不覆盖改写结果 +- `CrashDoesNotKillKernel`：SIGKILL 插件进程，homed 存活 + +这些测试用**真实 example 产物**而非 testdata 假插件，且 manifest 刻意写 +`"entry":"plugin.so"`——验证「业务代码零改动」这一承诺在完整内核装配下成立。 +未重编时 skip 而非 fail，CI 不强制先跑重编脚本。 diff --git a/docs/zh/experiments/plugin-arch/19-migration-verify/measure-plugin-overhead.sh b/docs/zh/experiments/plugin-arch/19-migration-verify/measure-plugin-overhead.sh new file mode 100755 index 0000000..d9254f2 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/19-migration-verify/measure-plugin-overhead.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# 子进程插件常驻开销实测（Part 6.3 验收项）。 +# +# 对照基线：docs/zh/experiments/plugin-arch 实验 5 实测 17 子进程 +# PSS=12.9MB / RSS=29.1MB / 线程=84（原文档估计 50-70MB 偏高）。 +# +# 用法：./measure-plugin-overhead.sh +set -uo pipefail + +pid=${1:-} +if [ -z "$pid" ]; then + echo "用法: $0 " >&2 + exit 1 +fi +if [ ! -d "/proc/$pid" ]; then + echo "进程 $pid 不存在" >&2 + exit 1 +fi + +# homed 本体 +homed_rss=$(awk '/^VmRSS:/ {print $2}' "/proc/$pid/status") +homed_thr=$(awk '/^Threads:/ {print $2}' "/proc/$pid/status") + +echo "=== homed 本体 ===" +printf "RSS=%s kB 线程=%s\n" "$homed_rss" "$homed_thr" + +# 插件子进程：homed 的直接子进程中执行 plugin.bin 的 +echo +echo "=== 插件子进程 ===" +total_rss=0 +total_pss=0 +total_thr=0 +count=0 + +for child in $(pgrep -P "$pid" 2>/dev/null); do + exe=$(readlink "/proc/$child/exe" 2>/dev/null || true) + case "$exe" in + *plugin.bin*) ;; + *) continue ;; + esac + + thr=$(awk '/^Threads:/ {print $2}' "/proc/$child/status" 2>/dev/null || echo 0) + # RSS 与 PSS 统一从 smaps_rollup 读，保证口径一致。 + # 混用 status 的 VmRSS 与 smaps 的 Pss 会得出 PSS > RSS 的荒谬结果—— + # 两者对共享内存段（Pss_Shmem）的计入方式不同。 + rss=$(awk '/^Rss:/ {print $2}' "/proc/$child/smaps_rollup" 2>/dev/null || echo 0) + pss=$(awk '/^Pss:/ {print $2}' "/proc/$child/smaps_rollup" 2>/dev/null || echo 0) + if [ -z "$rss" ] || [ "$rss" = "0" ]; then + rss=$(awk '/^VmRSS:/ {print $2}' "/proc/$child/status" 2>/dev/null || echo 0) + fi + binsz=$(stat -c%s "$(readlink "/proc/$child/exe" 2>/dev/null)" 2>/dev/null || echo 0) + name=$(basename "$(readlink "/proc/$child/cwd" 2>/dev/null || echo unknown)") + + printf " %-16s pid=%-8s RSS=%-8s PSS=%-8s 线程=%-3s 二进制=%s MB\n" \ + "$name" "$child" "$rss" "$pss" "$thr" \ + "$(awk -v b="$binsz" 'BEGIN{printf "%.1f", b/1048576}')" + total_rss=$((total_rss + rss)) + total_pss=$((total_pss + pss)) + total_thr=$((total_thr + thr)) + count=$((count + 1)) +done + +echo +echo "=== 合计（$count 个插件进程）===" +awk -v rss="$total_rss" -v pss="$total_pss" -v thr="$total_thr" -v n="$count" ' +BEGIN { + printf "RSS=%d kB (%.1f MB)\n", rss, rss/1024 + printf "PSS=%d kB (%.1f MB)\n", pss, pss/1024 + printf "线程=%d\n", thr + if (n > 0) printf "均摊 RSS=%.2f MB PSS=%.2f MB 线程=%.1f\n", rss/1024/n, pss/1024/n, thr/n +}' + +echo +echo "注：RSS/PSS 均取自 smaps_rollup，口径一致（PSS ≤ RSS）。" +echo "PSS 低于 RSS 的部分即 Go runtime 只读代码页在进程间的共享收益。" + +echo +echo "对照实验 5 基线：17 进程 RSS=29.1MB PSS=12.9MB 线程=84" +echo +echo "⚠️ 该基线用的是 2.68MB 的最小插件；真实插件 3.3~15.2MB（browser 依赖最多）。" +echo " RSS 随二进制体积线性增长，故不可直接与基线数字比较——" +echo " 要比的是「均摊线程数」与「PSS/RSS 比值（共享收益）」这两个结构性指标。" diff --git a/docs/zh/experiments/plugin-arch/19-migration-verify/rebuild-plugins.sh b/docs/zh/experiments/plugin-arch/19-migration-verify/rebuild-plugins.sh new file mode 100755 index 0000000..ea37160 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/19-migration-verify/rebuild-plugins.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +# 批量重编外部插件为子进程模式（Part 6.3）。 +# +# 用法：./rebuild-plugins.sh <插件名>... +# +# 关键性质：**不修改任何插件源码**。每个插件只需用新版 plugindev 重编， +# plg.json 的 entry 仍写着 "plugin.so" 也无妨——工具链已不看这个字段。 +set -uo pipefail + +PLUGINDEV=${PLUGINDEV:-/tmp/plugindev} +EXAMPLE_DIR=${EXAMPLE_DIR:-"$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../.." && pwd)/third_party/homeagent-sdk/example"} +export GOCACHE=${GOCACHE:-/tmp/gocache} +export GOPATH=${GOPATH:-/tmp/gopath} + +if [ ! -x "$PLUGINDEV" ]; then + echo "plugindev 不存在或不可执行: $PLUGINDEV" >&2 + exit 1 +fi + +ok=0 +fail=0 +failed_names="" + +for name in "$@"; do + dir="$EXAMPLE_DIR/$name" + if [ ! -d "$dir" ]; then + echo "✗ $name: 目录不存在" + fail=$((fail + 1)) + failed_names="$failed_names $name" + continue + fi + + # 清理旧 C ABI 产物：同目录残留 .so 不影响构建，但会让人误以为还在用旧通道 + rm -rf "$dir/build" "$dir/dist" + + out=$(cd "$dir" && "$PLUGINDEV" build 2>&1) + rc=$? + + # 判定成功的依据是产物存在，而非退出码：plugindev 对部分错误只打印不退出 + if [ $rc -eq 0 ] && ls "$dir"/build/plugin.bin* >/dev/null 2>&1; then + n=$(ls "$dir"/build/plugin.bin* 2>/dev/null | wc -l) + hmap=$(ls "$dir"/dist/*.hmap 2>/dev/null | head -1) + printf "✓ %-14s %s 个平台产物 %s\n" "$name" "$n" "$(basename "${hmap:-无 hmap}")" + ok=$((ok + 1)) + else + printf "✗ %-14s 构建失败\n" "$name" + echo "$out" | tail -6 | sed 's/^/ /' + fail=$((fail + 1)) + failed_names="$failed_names $name" + fi +done + +echo +echo "成功 $ok / 失败 $fail" +[ -n "$failed_names" ] && echo "失败:$failed_names" +exit $([ $fail -eq 0 ] && echo 0 || echo 1) diff --git a/internal/plugins/real_plugin_smoke_test.go b/internal/plugins/real_plugin_smoke_test.go new file mode 100644 index 0000000..73283ea --- /dev/null +++ b/internal/plugins/real_plugin_smoke_test.go @@ -0,0 +1,258 @@ +//go:build linux || darwin + +package plugins + +import ( + "fmt" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "syscall" + "testing" + "time" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 真实外部插件（重编为 plugin.bin）经内核加载后的端到端冒烟（Part 6.3）。 +// +// 与 internal/plugin/proc 的测试的区别： +// 那些用 testdata 假插件或临时编译的最小插件验证机制； +// 这里用 **example/ 里真实的 17 个插件产物**，验证「业务代码零改动 + 重编即可」 +// 这一迁移承诺在完整内核装配下成立。 +// +// 前置：插件需已用新版 plugindev 重编（scripts/rebuild-plugins.sh）。 +// 未重编时测试 skip 而非 fail——CI 上不强制要求先跑重编脚本。 + +// realPluginDir 返回某个 example 插件的 linux 产物路径。 +func realPluginBinary(t *testing.T, name string) string { + t.Helper() + root, err := filepath.Abs(filepath.Join("..", "..", "third_party", "homeagent-sdk", "example", name)) + if err != nil { + t.Fatalf("解析插件目录: %v", err) + } + // bundle 模式产物带平台后缀，单平台模式不带 + candidates := []string{ + filepath.Join(root, "build", fmt.Sprintf("plugin.bin_%s_%s", runtime.GOOS, runtime.GOARCH)), + filepath.Join(root, "build", "plugin.bin"), + } + for _, c := range candidates { + if st, err := os.Stat(c); err == nil && !st.IsDir() { + return c + } + } + t.Skipf("插件 %s 未重编（先跑 scripts/rebuild-plugins.sh）", name) + return "" +} + +// installRealPlugin 把真实插件产物装进测试用 plugins 目录。 +func installRealPlugin(t *testing.T, plgDir, name string) { + t.Helper() + src := realPluginBinary(t, name) + + dst := filepath.Join(plgDir, name) + if err := os.MkdirAll(dst, 0o755); err != nil { + t.Fatalf("建插件目录: %v", err) + } + data, err := os.ReadFile(src) + if err != nil { + t.Fatalf("读产物 %s: %v", src, err) + } + binPath := filepath.Join(dst, "plugin.bin") + if err := os.WriteFile(binPath, data, 0o755); err != nil { + t.Fatalf("写产物: %v", err) + } + + // manifest 刻意写 "plugin.so"：验证工具链/内核都已不看 entry 值。 + // 17 个存量插件的 plg.json 都是这个值，没人去改——这正是「零改动」的含义。 + manifest := fmt.Sprintf(`{"name":%q,"name_zh":%q,"name_en":%q,"version":"1.0.0","entry":"plugin.so"}`, + name, name, name) + if err := os.WriteFile(filepath.Join(dst, "plugin.json"), []byte(manifest), 0o644); err != nil { + t.Fatalf("写 manifest: %v", err) + } +} + +// 真实插件经内核加载 → 注册工具 → **实际调用工具**。 +// +// 之前的测试只验证到"注册"，这里验证调用往返： +// 内核 ExecuteTool → RPC → 插件进程 handler → 结果回传。 +func TestRealPlugin_ToolInvokeRoundTrip(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + installRealPlugin(t, plgDir, "weather") + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + + // 确认经 proc 通道加载（而非被同名内置插件遮蔽） + if env.pluginReg.Get("weather") == nil { + t.Fatal("weather 未加载") + } + + // weather 注册的工具名带插件名前缀（内核 SetToolRegistrar 加的） + var toolName string + for _, def := range env.stageHost.GetToolDefs() { + if strings.Contains(def.Name, "weather") { + toolName = def.Name + break + } + } + if toolName == "" { + t.Fatal("weather 未注册任何工具") + } + t.Logf("调用工具 %s", toolName) + + // 真实调用：weather 会发 HTTP 请求到 wttr.in，网络不通时返回错误而非 panic。 + // 这里只断言"调用链路通"——RPC 往返成功、handler 被执行、结果或错误正常回传。 + res, err := env.stageHost.ExecuteTool(toolName, map[string]interface{}{"city": "Beijing"}) + if err != nil { + // 网络错误是可接受的：链路通了才能拿到插件侧的错误 + if strings.Contains(err.Error(), "not found in any plugin") { + t.Fatalf("工具未注册到 stageHost: %v", err) + } + t.Logf("工具返回错误（网络受限环境正常）: %v", err) + return + } + if res == nil { + t.Error("工具返回 nil 结果且无错误") + } + t.Logf("工具返回: %.120v", res) +} + +// sanitizer 的改写型 stage 在真实内核装配下生效。 +// +// 这是迁移最核心的性质：C ABI 副本模型下多插件并发时实测 35.8~36.8% +// lost update（§8.4），共享内存 + 字段级脏写入后应为 0。 +func TestRealPlugin_StageRewriteTakesEffect(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + installRealPlugin(t, plgDir, "sanitizer") + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + if env.pluginReg.Get("sanitizer") == nil { + t.Fatal("sanitizer 未加载") + } + + // sanitizer 注册 after_toolcall 清洗 ANSI 转义序列 + dirty := "结果：\x1b[31m告警文本\x1b[0m 结束" + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{ + {CallID: "c1", Name: "some_tool", Result: dirty}, + }, + } + + env.stageHost.RunStage(pubsdk.StageAfterToolcall, sc) + + got, _ := sc.ToolResults[0].Result.(string) + if got == dirty { + t.Errorf("sanitizer 的清洗未生效（结果未变）：%q", got) + } + if strings.Contains(got, "\x1b[") { + t.Errorf("ANSI 序列未被清除：%q", got) + } + t.Logf("清洗前: %q\n清洗后: %q", dirty, got) +} + +// 多插件共享同一块共享段，只读插件不覆盖改写插件的结果。 +// +// 若每插件一块段，「内核 ctx → 段 → 插件改 → 回读 ctx」会退化成副本模型， +// 最后回读者覆盖前者，lost update 原样复现。 +func TestRealPlugin_MultiPluginShareOneSegment(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + // sanitizer 改写 ToolResults，weather 只读（不注册 after_toolcall 的改写） + installRealPlugin(t, plgDir, "sanitizer") + installRealPlugin(t, plgDir, "weather") + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + + dirty := "输出：\x1b[33m黄色\x1b[0m" + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{ + {CallID: "c1", Name: "t", Result: dirty}, + }, + } + + env.stageHost.RunStage(pubsdk.StageAfterToolcall, sc) + + got, _ := sc.ToolResults[0].Result.(string) + if strings.Contains(got, "\x1b[") { + t.Errorf("并发下清洗结果被覆盖（lost update）：%q", got) + } +} + +// 崩溃隔离：kill 掉插件子进程，homed（测试进程）必须存活。 +// +// 对比 C ABI：插件 panic 直接带崩整个 homed 进程（§1.2，现网已发生）。 +func TestRealPlugin_CrashDoesNotKillKernel(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + installRealPlugin(t, plgDir, "editdoc") + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + if env.pluginReg.Get("editdoc") == nil { + t.Fatal("editdoc 未加载") + } + + // 找到插件子进程并 SIGKILL + pid := findPluginPID(t, "editdoc") + if pid == 0 { + t.Skip("未找到插件子进程（进程名匹配失败）") + } + t.Logf("kill 插件进程 pid=%d", pid) + if err := syscall.Kill(pid, syscall.SIGKILL); err != nil { + t.Fatalf("kill: %v", err) + } + + // 内核必须存活并能继续工作 + time.Sleep(300 * time.Millisecond) + if env.pluginReg.List() == nil { + t.Fatal("内核在插件崩溃后不可用") + } + t.Logf("插件崩溃后内核存活，已加载插件数=%d", len(env.pluginReg.List())) +} + +// findPluginPID 按二进制路径找插件子进程 pid。 +func findPluginPID(t *testing.T, name string) int { + t.Helper() + out, err := exec.Command("pgrep", "-f", "plugin.bin").Output() + if err != nil { + return 0 + } + for _, line := range strings.Fields(string(out)) { + pid := 0 + fmt.Sscanf(line, "%d", &pid) + if pid == 0 { + continue + } + // 校验 cwd 或 cmdline 含插件名 + exe, err := os.Readlink(fmt.Sprintf("/proc/%d/exe", pid)) + if err == nil && strings.Contains(exe, name) { + return pid + } + cwd, err := os.Readlink(fmt.Sprintf("/proc/%d/cwd", pid)) + if err == nil && strings.Contains(cwd, name) { + return pid + } + } + return 0 +} From 2ebdb9a5b7ef831429e1fe136fd8a591a0112f9a Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 21:27:13 +0800 Subject: [PATCH 20/27] =?UTF-8?q?plugin:=20=E6=9D=83=E9=99=90=E6=A2=AF?= =?UTF-8?q?=E5=BA=A6=E6=98=BE=E5=BC=8F=E5=8C=96=EF=BC=88Part=206.4?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 迁移前，「外部插件拿不到 Selftest/Supervisor/Tracker」是 C ABI 表达能力的 **意外产物**——C 结构体不好传函数指针，这些能力自然到不了插件侧。那是运气 不是策略：任何人给 dispatch 加个 case 就能捅穿。 现在变成显式声明并强制，分三道闸： 1. **类型层**（proc_core.go，Part 6.2 已落地）：procCore 用命名字段持有 内核 SDK 而非嵌入，未在收窄面写出的方法编译期就不存在。 2. **能力集**（新增 capability.go）：54 个 plugin→kernel method 划入 11 个 capability 组，manifest 未声明的组被拒。 3. **RPC 边界**（corehandler.Handle 入口）：被拒时返回**明确错误**而非 静默忽略。 第 3 条针对一类真实故障：C ABI 时代 case 23/24（事件订阅）是空实现， 返回成功但永远收不到事件（§1.3 的「给不了」而非「不给」），插件作者无从得知。 错误消息含四要素：哪个插件、哪个调用、缺什么能力、在哪声明。 ## 能力划分的两个判断 **粒度按能力域而非单 method**。逐 method 授权看似更精细，但插件作者要在 manifest 里列 60 个名字，且内核每加 method 所有 manifest 都得改。 **空声明 = 不受限，而非「只有 core」**。17 个存量插件的 plugin.json 都没有 capabilities 字段。若空声明当作最小权限，它们会全部失去 IO 注入、记忆读写 而**静默降级**——违反「外部插件零改动」的硬约束。收紧的路径是让插件显式 声明，而不是默默拒绝老插件。 ## core 与受限能力的边界 core（无需声明，始终可用）：注册自身工具/阶段/通道/API、读写**自己的**配置、 共享段锁仲裁、握手、autoRestart 自述、setToolBlocks。没有这些插件无法工作。 受限（需声明）：io / memory / doc_memory / knowledge / text_memory / llm / social / events / plugin_mgr / settings_cross。 settings 刻意拆成两级：读写自己的配置属 core（正常工作所需），读写**其他插件** 配置或**内核核心**配置属 settings_cross（能改别人/内核的行为）。 ## withheldCapabilities：让「不给」可见 10 项刻意不提供的内核内部机制列在表里并附理由。它们没有对应 method 常量—— 不是忘了加，是决定不加。列表存在本身就是「这是策略而非疏漏」的证据， 读代码的人能看到边界在哪，而不是从「protocol.go 里没有」这个负面事实去推断。 ## 测试 proc 包 10 项： - AllMethodsClassified：**最重要的一项**。漏登记的 method 会按 CapCore 放行， 等于绕过整套检查。新增 method 忘登记时当场报出。 - EmptyDeclarationIsUnrestricted / DeclaredSetRestrictsOthers / CoreAlwaysAllowed - SettingsScopeSeparation：自身配置 vs 跨插件配置的归属 - DeniedErrorIsActionable：错误消息四要素 - HandleEnforcesAtRPCBoundary：被拒的调用不进 switch - WithheldListIsDocumented：每项都有理由，且不被任何 method 暴露 - UnknownMethodFallsThrough：未知 method 报「未知」而非「权限被拒」， 否则作者会以为是漏声明能力 写这个测试时踩到自己的坑：第一版用子串匹配查 withheld 泄漏，"Tool" 匹配到 tool.register 和 io.setToolBlocks 误报——那两个是合法开放的（注册自己的工具）。 改成前缀 + unregister 关键字匹配，withheld 项也改名带 API 后缀以示区分。 internal/plugins 2 项接线验证： - RestrictedPluginStillLoads：只声明 io 的 weather 仍能加载并注册工具 （它在 Start 里读 Settings，属 core） - LegacyManifestUnrestricted：无 capabilities 字段的存量插件正常加载 真实 homed 实测： [plugin] weather-capped 声明能力: [io] [plugin] weather-capped: 经 proc 通道加载（子进程） registering tool: weather-capped_current / _forecast / _set_location 验证：go build ./... 通过；go test ./... 全仓无失败； go test -race ./internal/plugin/... 全绿；go vet 干净。 Ref: docs/zh/架构迁移评估.md §3.8、docs/zh/plugin-migration-plan.md Part 6.4 --- internal/plugin/dynamic_proc_unix.go | 14 +- internal/plugin/manifest.go | 16 +- internal/plugin/proc/capability.go | 267 +++++++++++++++++ internal/plugin/proc/capability_test.go | 322 +++++++++++++++++++++ internal/plugin/proc/corehandler.go | 13 + internal/plugin/proc/plugin.go | 11 +- internal/plugins/capability_wiring_test.go | 100 +++++++ 7 files changed, 740 insertions(+), 3 deletions(-) create mode 100644 internal/plugin/proc/capability.go create mode 100644 internal/plugin/proc/capability_test.go create mode 100644 internal/plugins/capability_wiring_test.go diff --git a/internal/plugin/dynamic_proc_unix.go b/internal/plugin/dynamic_proc_unix.go index 134708e..8e62471 100644 --- a/internal/plugin/dynamic_proc_unix.go +++ b/internal/plugin/dynamic_proc_unix.go @@ -72,7 +72,19 @@ func (r *Registry) loadProc(dir, name string, config map[string]interface{}) (sd return nil, fmt.Errorf("proc plugin %s: %w", name, err) } - return procPluginAdapter{Plugin: proc.New(name, binPath, dir, config, host, r.onProcCrash)}, nil + // manifest 声明的能力集（§3.8 权限梯度）。 + // 无 manifest 或未声明 capabilities 时不限制，保存存量插件行为。 + var caps []string + if mft := readManifest(dir); mft != nil { + caps = mft.Capabilities + if len(caps) > 0 { + log.Printf("[plugin] %s 声明能力: %v", name, caps) + } + } + + return procPluginAdapter{ + Plugin: proc.New(name, binPath, dir, config, host, r.onProcCrash, caps...), + }, nil } // ensureProcHost 惰性创建共享段 Host（全进程唯一）。 diff --git a/internal/plugin/manifest.go b/internal/plugin/manifest.go index dfb844c..a33fe8f 100644 --- a/internal/plugin/manifest.go +++ b/internal/plugin/manifest.go @@ -19,11 +19,25 @@ type PluginManifest struct { License string `json:"license,omitempty"` Homepage string `json:"homepage,omitempty"` Repository string `json:"repository,omitempty"` - Entry string `json:"entry"` // "plugin.bin"(子进程) | "plugin.so" | "plugin.dll" | "main.lua" | "SKILL.md" + Entry string `json:"entry"` // "plugin.bin"(子进程) | "main.lua" | "SKILL.md" Platforms []string `json:"platforms,omitempty"` // 声明的支持平台: ["linux","darwin","windows"] MinVersion string `json:"min_version,omitempty"` Tags []string `json:"tags,omitempty"` Deprecated bool `json:"deprecated,omitempty"` + + // Capabilities 声明本插件需要的内核能力组（§3.8 权限梯度）。 + // + // 取值见 internal/plugin/proc.KnownCapabilities()： + // io / memory / doc_memory / knowledge / text_memory / llm / social / + // events / plugin_mgr / settings_cross + // + // **省略或为空 = 不受限**，而不是「只有基础能力」。 + // 理由：17 个存量插件的 plugin.json 都没有这个字段，若空声明当作最小权限， + // 它们会全部失去 IO 注入、记忆读写等能力而**静默降级**—— + // 违反「外部插件零改动」的硬约束。收紧的路径是让插件显式声明。 + // + // core（注册自身工具/阶段/通道 + 读写自己的配置）无需声明，始终可用。 + Capabilities []string `json:"capabilities,omitempty"` } func ReadManifest(dir string) (*PluginManifest, error) { diff --git a/internal/plugin/proc/capability.go b/internal/plugin/proc/capability.go new file mode 100644 index 0000000..d62eb39 --- /dev/null +++ b/internal/plugin/proc/capability.go @@ -0,0 +1,267 @@ +package proc + +import ( + "fmt" + "sort" + "strings" +) + +// 权限梯度：外部插件可调用哪些内核 method（§3.8）。 +// +// 迁移前，「外部插件拿不到 Selftest/Supervisor/Tracker」是 C ABI 表达能力的 +// **意外产物**——C 结构体不好传函数指针，于是这些能力自然到不了插件侧。 +// 那是运气，不是策略：任何人给 dispatch 加个 case 就能捅穿。 +// +// 迁移后要变成**显式声明并强制的策略**，分三道闸： +// +// 1. 类型层（internal/plugin/proc_core.go）：procCore 用命名字段持有内核 SDK， +// 不嵌入 —— 未在收窄面显式写出的方法根本不存在，编译期就拿不到。 +// 2. 能力集（本文件）：method 划入 capability 组，manifest 未声明的组被拒。 +// 3. RPC 边界：被拒时返回**明确错误**而非静默忽略——插件作者能立刻知道 +// 「这个能力没给我」，而不是调用成功但什么也没发生。 +// +// 第 3 条针对的是一类真实故障：C ABI 时代 case 23/24（事件订阅）是空实现， +// 返回成功但永远收不到事件（§1.3 的「给不了」而非「不给」）。 + +// Capability 是一组相关 method 的权限单元。 +// +// 粒度选择：按**能力域**而非单个 method 划分。逐 method 授权看似更精细， +// 但插件作者要在 manifest 里列 60 个名字，且内核加 method 时所有 manifest 都得改。 +type Capability string + +const ( + // CapCore 是无需声明即可用的基础能力：注册自身工具/阶段/通道、 + // 读写自己的配置、共享段锁仲裁。没有这些插件无法工作。 + CapCore Capability = "core" + + // CapIO 注入输入到 agent 主循环（可影响对话流）。 + CapIO Capability = "io" + + // CapMemory 图记忆读写。 + CapMemory Capability = "memory" + + // CapDocMemory 文档记忆读写。 + CapDocMemory Capability = "doc_memory" + + // CapKnowledge 知识库读写。 + CapKnowledge Capability = "knowledge" + + // CapTextMemory 文本记忆追加。 + CapTextMemory Capability = "text_memory" + + // CapLLM 切换 LLM 源（影响全局行为）。 + CapLLM Capability = "llm" + + // CapSocial 社交图读取。 + CapSocial Capability = "social" + + // CapEvents 订阅内核事件。 + CapEvents Capability = "events" + + // CapPluginMgr 管理其他插件（重载/查询禁用状态）。 + // + // 这是**最敏感**的一组：能重载其他插件意味着能间接影响它们的状态。 + CapPluginMgr Capability = "plugin_mgr" + + // CapCrossPluginSettings 读写**其他插件**的配置与内核核心配置。 + // + // 与 CapCore 里的「读写自己的配置」区分开：跨插件配置读写能改别人的行为， + // 核心配置读写能改内核行为。 + CapCrossPluginSettings Capability = "settings_cross" +) + +// methodCapability 把每个 method 映射到所需能力。 +// +// ❗ 新增 method 时必须在此登记，否则 capabilityOf 返回 CapCore +// （最宽松），等于绕过权限检查。checkAllMethodsClassified 测试守着这一点。 +var methodCapability = map[string]Capability{ + // ---- 基础能力（无需声明）---- + MethodHandshake: CapCore, + MethodToolRegister: CapCore, + MethodStageRegister: CapCore, + MethodOutputRegister: CapCore, + MethodAPIRegister: CapCore, + MethodInputRegister: CapCore, + MethodStageLock: CapCore, + MethodStageUnlock: CapCore, + // 自身配置读写与元信息属基础能力 + MethodSettingsGet: CapCore, + MethodSettingsSet: CapCore, + MethodSettingsList: CapCore, + MethodSettingsDefs: CapCore, + MethodSettingsRegisterDef: CapCore, + MethodSettingsDataDir: CapCore, + // 生命周期自述（插件声明自己是否可自动重启） + MethodLifecycleAutoRestart: CapCore, + // 多模态内容块注入是工具返回值的一部分，不越权 + MethodIOSetToolBlocks: CapCore, + + // ---- IO 注入 ---- + MethodIOInjectText: CapIO, + MethodIOInjectInterrupt: CapIO, + MethodIOInjectTextNoMem: CapIO, + MethodIOInjectSync: CapIO, + + // ---- 图记忆 ---- + MethodMemoryRecall: CapMemory, + MethodMemoryCommit: CapMemory, + MethodMemoryIntrospect: CapMemory, + MethodMemoryMerge: CapMemory, + MethodMemoryPurge: CapMemory, + + // ---- 文档记忆 ---- + MethodDocQuery: CapDocMemory, + MethodDocInsert: CapDocMemory, + MethodDocRemove: CapDocMemory, + MethodDocStats: CapDocMemory, + + // ---- 知识库 ---- + MethodKnowledgeSearch: CapKnowledge, + MethodKnowledgeAdd: CapKnowledge, + MethodKnowledgeList: CapKnowledge, + + // ---- 文本记忆 ---- + MethodTextMemoryAppend: CapTextMemory, + + // ---- LLM ---- + MethodLLMListSources: CapLLM, + MethodLLMSetSource: CapLLM, + MethodLLMCurrentSource: CapLLM, + + // ---- 社交图 ---- + MethodSocialGetPerson: CapSocial, + MethodSocialGetNetwork: CapSocial, + MethodSocialGetTrait: CapSocial, + MethodSocialGetRelation: CapSocial, + MethodSocialListPersons: CapSocial, + + // ---- 事件 ---- + MethodEventsSubscribe: CapEvents, + MethodEventsUnsubscribe: CapEvents, + + // ---- 插件管理 ---- + MethodPluginReloadOne: CapPluginMgr, + MethodPluginListLoaded: CapPluginMgr, + MethodPluginIsDisabled: CapPluginMgr, + + // ---- 跨插件 / 核心配置 ---- + MethodSettingsGetCore: CapCrossPluginSettings, + MethodSettingsSetCore: CapCrossPluginSettings, + MethodSettingsListCore: CapCrossPluginSettings, + MethodSettingsGetPlugin: CapCrossPluginSettings, + MethodSettingsSetPlugin: CapCrossPluginSettings, + MethodSettingsListPlugin: CapCrossPluginSettings, + MethodSettingsDump: CapCrossPluginSettings, + MethodSettingsPlugins: CapCrossPluginSettings, +} + +// withheldCapabilities 是**刻意不提供给外部插件**的内核内部机制（§3.8 最后一行）。 +// +// 这些没有对应的 method 常量——不是"忘了加"，是决定不加。 +// 列在这里是为了让决策可见：读代码的人能看到边界在哪，而不是从 +// 「protocol.go 里没有」这个负面事实去推断。 +// +// 类型层已经挡住了（procCore 不暴露这些访问器），本表是文档 + 测试锚点。 +var withheldCapabilities = map[string]string{ + "SelftestAPI": "虚拟实例自检 —— 能构造内核实例，等于绕过全部权限边界", + "SupervisorAPI": "进程监管 —— 能启停 worker，等于控制内核生命周期", + "TrackerAPI": "变更追踪 —— 内核 overlay 文件系统的内部机制", + "StatusAPI": "内核状态面 —— 暴露内部运行时细节", + "AdapterAPI": "LLM 适配器管理 —— 能改写请求/响应链路", + "ConfigAPI": "内核配置对象 —— 与 settings 的受控读写不同，这是直接持有", + "ToolAPI": "工具表直接操作 —— 能注销其他插件的工具（注册自己的工具走 tool.register，那是 core）", + "IndexerAPI": "记忆索引器 —— 内核记忆管线的内部组件", + "OutputChanRaw": "输出通道原始消费 —— 已由 output.invoke 的声明式注册替代", + "EventPublish": "事件发布 —— 只给订阅（events.subscribe），不给伪造内核事件", +} + +// capabilityOf 返回 method 所需能力。 +// +// 未登记的 method 返回 (CapCore, false)：ok=false 让调用方能区分 +// 「明确划为基础能力」与「漏登记」，测试据此拦住漏登记。 +func capabilityOf(method string) (Capability, bool) { + cap, ok := methodCapability[method] + if !ok { + return CapCore, false + } + return cap, true +} + +// capabilitySet 是某个插件被授予的能力集合。 +type capabilitySet struct { + granted map[Capability]bool + // unrestricted 为真时跳过检查（未声明 capabilities 的插件，向后兼容）。 + unrestricted bool +} + +// newCapabilitySet 从 manifest 声明构造能力集。 +// +// **空声明 = 不受限**，而不是「只有 core」。理由：17 个存量插件的 plugin.json +// 都没有 capabilities 字段，若空声明当作最小权限，它们会全部失去 IO 注入、 +// 记忆读写等能力而**静默降级**——这违反「外部插件零改动」的硬约束。 +// +// 收紧的路径是让插件显式声明，而非默默拒绝老插件。 +func newCapabilitySet(declared []string) *capabilitySet { + if len(declared) == 0 { + return &capabilitySet{unrestricted: true} + } + s := &capabilitySet{granted: map[Capability]bool{CapCore: true}} + for _, d := range declared { + s.granted[Capability(strings.TrimSpace(d))] = true + } + return s +} + +// allows 判断是否允许调用某 method。 +func (s *capabilitySet) allows(method string) (bool, Capability) { + cap, registered := capabilityOf(method) + if !registered { + // 漏登记的 method 按基础能力放行（保守：不因内核疏漏拦住插件）， + // 但由测试保证这种情况不存在。 + return true, CapCore + } + if s == nil || s.unrestricted { + return true, cap + } + if cap == CapCore { + return true, cap + } + return s.granted[cap], cap +} + +// KnownCapabilities 返回全部可声明的能力名（供 manifest 校验与文档生成）。 +func KnownCapabilities() []string { + seen := map[Capability]bool{} + for _, c := range methodCapability { + seen[c] = true + } + out := make([]string, 0, len(seen)) + for c := range seen { + if c == CapCore { + continue // core 无需声明 + } + out = append(out, string(c)) + } + sort.Strings(out) + return out +} + +// WithheldCapabilities 返回刻意不提供的能力清单（供文档与诊断）。 +func WithheldCapabilities() map[string]string { + out := make(map[string]string, len(withheldCapabilities)) + for k, v := range withheldCapabilities { + out[k] = v + } + return out +} + +// errCapabilityDenied 构造被拒错误。 +// +// 消息包含三要素：被拒的 method、缺的能力名、如何补救。 +// 静默忽略或含糊的「失败」会让插件作者以为是自己参数错了。 +func errCapabilityDenied(plugin, method string, cap Capability) error { + return fmt.Errorf( + "插件 %s 调用 %s 被拒：缺少 %q 能力。"+ + "请在 plugin.json 的 capabilities 数组中声明它（可用能力：%s）", + plugin, method, cap, strings.Join(KnownCapabilities(), ", ")) +} diff --git a/internal/plugin/proc/capability_test.go b/internal/plugin/proc/capability_test.go new file mode 100644 index 0000000..be12d5d --- /dev/null +++ b/internal/plugin/proc/capability_test.go @@ -0,0 +1,322 @@ +package proc + +import ( + "encoding/json" + "strings" + "testing" +) + +// 权限梯度测试（§3.8）。 +// +// 守住的核心性质：外部插件拿不到内核内部机制，不是因为 C ABI 传不了 +// 函数指针（那是运气），而是因为这里**显式声明并强制**了边界。 + +// 每个 method 都必须登记能力归属。 +// +// ❗ 这是本文件最重要的测试：漏登记的 method 会按 CapCore 放行， +// 等于绕过整套权限检查。新增 method 时忘了登记，这里会当场报出来。 +func TestCapability_AllMethodsClassified(t *testing.T) { + // 与 protocol.go 的 method 常量对齐。内核→插件的 7 个调用不经 Handle， + // 故不需要能力归属。 + kernelToPlugin := map[string]bool{ + MethodPluginInit: true, + MethodPluginStart: true, + MethodPluginStop: true, + MethodToolInvoke: true, + MethodStageInvoke: true, + MethodOutputInvoke: true, + } + + // 插件→内核的全部 method（手工清单，与 protocol.go 对照） + pluginToKernel := []string{ + MethodHandshake, + MethodToolRegister, MethodStageRegister, MethodOutputRegister, + MethodAPIRegister, MethodInputRegister, + MethodIOInjectText, MethodIOInjectInterrupt, MethodIOInjectTextNoMem, + MethodIOInjectSync, MethodIOSetToolBlocks, + MethodLifecycleAutoRestart, + MethodMemoryRecall, MethodMemoryCommit, MethodMemoryIntrospect, + MethodMemoryMerge, MethodMemoryPurge, + MethodDocQuery, MethodDocInsert, MethodDocRemove, MethodDocStats, + MethodKnowledgeSearch, MethodKnowledgeAdd, MethodKnowledgeList, + MethodTextMemoryAppend, + MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef, + MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore, + MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin, + MethodSettingsList, MethodSettingsDefs, MethodSettingsDump, + MethodSettingsPlugins, MethodSettingsDataDir, + MethodLLMListSources, MethodLLMSetSource, MethodLLMCurrentSource, + MethodSocialGetPerson, MethodSocialGetNetwork, MethodSocialGetTrait, + MethodSocialGetRelation, MethodSocialListPersons, + MethodEventsSubscribe, MethodEventsUnsubscribe, + MethodPluginReloadOne, MethodPluginListLoaded, MethodPluginIsDisabled, + MethodStageLock, MethodStageUnlock, + } + + for _, m := range pluginToKernel { + if kernelToPlugin[m] { + continue + } + if _, ok := capabilityOf(m); !ok { + t.Errorf("method %q 未登记能力归属 —— 会按 CapCore 放行，绕过权限检查", m) + } + } +} + +// 未声明 capabilities 的插件不受限（存量插件向后兼容）。 +// +// 若空声明当作最小权限，17 个存量插件会全部失去 IO 注入/记忆读写而静默降级。 +func TestCapability_EmptyDeclarationIsUnrestricted(t *testing.T) { + s := newCapabilitySet(nil) + for _, m := range []string{ + MethodIOInjectText, MethodMemoryCommit, MethodPluginReloadOne, + MethodSettingsSetCore, MethodEventsSubscribe, + } { + if ok, _ := s.allows(m); !ok { + t.Errorf("未声明 capabilities 时 %q 应放行（存量插件兼容）", m) + } + } + + s2 := newCapabilitySet([]string{}) + if ok, _ := s2.allows(MethodMemoryCommit); !ok { + t.Error("空数组也应视为不受限") + } +} + +// 声明了能力后，未声明的组被拒。 +func TestCapability_DeclaredSetRestrictsOthers(t *testing.T) { + // 只声明 io：能注入，但不能碰记忆/插件管理/核心配置 + s := newCapabilitySet([]string{"io"}) + + allowed := []string{MethodIOInjectText, MethodIOInjectSync} + for _, m := range allowed { + if ok, _ := s.allows(m); !ok { + t.Errorf("声明 io 后 %q 应放行", m) + } + } + + denied := map[string]Capability{ + MethodMemoryCommit: CapMemory, + MethodKnowledgeAdd: CapKnowledge, + MethodPluginReloadOne: CapPluginMgr, + MethodSettingsSetCore: CapCrossPluginSettings, + MethodEventsSubscribe: CapEvents, + MethodLLMSetSource: CapLLM, + MethodTextMemoryAppend: CapTextMemory, + MethodDocInsert: CapDocMemory, + MethodSocialGetPerson: CapSocial, + } + for m, wantCap := range denied { + ok, gotCap := s.allows(m) + if ok { + t.Errorf("未声明 %q 时 %q 应被拒", wantCap, m) + } + if gotCap != wantCap { + t.Errorf("%q 的能力归属 = %q，期望 %q", m, gotCap, wantCap) + } + } +} + +// core 能力始终可用，无需声明。 +// +// 没有它插件无法注册工具、读写自己的配置、参与 stage 锁仲裁—— +// 即完全无法工作。 +func TestCapability_CoreAlwaysAllowed(t *testing.T) { + s := newCapabilitySet([]string{"io"}) // 只声明 io + + for _, m := range []string{ + MethodHandshake, + MethodToolRegister, MethodStageRegister, MethodOutputRegister, + MethodInputRegister, MethodAPIRegister, + MethodStageLock, MethodStageUnlock, + MethodSettingsGet, MethodSettingsSet, MethodSettingsList, + MethodSettingsDefs, MethodSettingsRegisterDef, MethodSettingsDataDir, + MethodLifecycleAutoRestart, + MethodIOSetToolBlocks, + } { + if ok, _ := s.allows(m); !ok { + t.Errorf("core 能力 %q 应始终放行", m) + } + } +} + +// 自身配置读写属 core，跨插件/核心配置需显式声明。 +// +// 这个区分是有意的：读写自己的配置是插件正常工作所需； +// 读写别人的配置能改别人行为，读写核心配置能改内核行为。 +func TestCapability_SettingsScopeSeparation(t *testing.T) { + s := newCapabilitySet([]string{}) // 不受限，先确认归属正确 + + own := []string{MethodSettingsGet, MethodSettingsSet, MethodSettingsList} + for _, m := range own { + if cap, _ := capabilityOf(m); cap != CapCore { + t.Errorf("%q 应属 core（自身配置），实际 %q", m, cap) + } + } + + cross := []string{ + MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore, + MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin, + MethodSettingsDump, MethodSettingsPlugins, + } + for _, m := range cross { + if cap, _ := capabilityOf(m); cap != CapCrossPluginSettings { + t.Errorf("%q 应属 settings_cross，实际 %q", m, cap) + } + } + _ = s +} + +// 被拒时错误消息必须可操作：说清缺什么、怎么补。 +// +// 针对的是 C ABI 时代的一类真实故障：case 23/24 返回成功但永远收不到事件， +// 插件作者无从得知。 +func TestCapability_DeniedErrorIsActionable(t *testing.T) { + err := errCapabilityDenied("demo", MethodMemoryCommit, CapMemory) + msg := err.Error() + + for _, want := range []string{ + "demo", // 哪个插件 + MethodMemoryCommit, // 哪个调用 + string(CapMemory), // 缺什么能力 + "capabilities", // 在哪声明 + "plugin.json", // 声明在哪个文件 + } { + if !strings.Contains(msg, want) { + t.Errorf("错误消息应含 %q，实际: %s", want, msg) + } + } + + // 还应列出可用能力名，避免作者猜 + if !strings.Contains(msg, string(CapEvents)) { + t.Errorf("错误消息应列出可选能力（如 %q），实际: %s", CapEvents, msg) + } +} + +// coreHandler 在 Handle 入口强制权限，被拒的调用不进 switch。 +func TestCapability_HandleEnforcesAtRPCBoundary(t *testing.T) { + core := newFakeCore() + h := &coreHandler{ + sdk: core, + name: "restricted", + caps: newCapabilitySet([]string{"io"}), // 不含 memory + } + + _, err := h.Handle(MethodMemoryCommit, json.RawMessage(`{"triples":[]}`)) + if err == nil { + t.Fatal("未声明 memory 能力时 memory.commit 应被拒") + } + if !strings.Contains(err.Error(), "被拒") { + t.Errorf("应是权限拒绝错误，实际: %v", err) + } + + // 已声明的能力照常走到 switch（这里 memory 为 nil，会返回 errUnavailable， + // 但错误类型不同——证明请求进了 switch 而非被权限拦下） + h2 := &coreHandler{ + sdk: core, + name: "allowed", + caps: newCapabilitySet([]string{"memory"}), + } + _, err2 := h2.Handle(MethodMemoryCommit, json.RawMessage(`{"triples":[]}`)) + if err2 != nil && strings.Contains(err2.Error(), "被拒") { + t.Errorf("声明了 memory 后不应被权限拒绝，实际: %v", err2) + } +} + +// 刻意不提供的内核内部机制必须有明确记录。 +// +// 这些没有对应 method 常量——不是忘了加，是决定不加。 +// 列表存在本身就是「这是策略而非疏漏」的证据。 +func TestCapability_WithheldListIsDocumented(t *testing.T) { + withheld := WithheldCapabilities() + + // §3.8 明确列为「不提供」的 + for _, name := range []string{"SelftestAPI", "SupervisorAPI", "TrackerAPI"} { + reason, ok := withheld[name] + if !ok { + t.Errorf("%s 应在 withheld 清单中（§3.8 明确不提供）", name) + continue + } + if reason == "" { + t.Errorf("%s 缺少不提供的理由", name) + } + } + + // 每一项都必须有理由，否则读代码的人无从判断边界为何在此 + for name, reason := range withheld { + if strings.TrimSpace(reason) == "" { + t.Errorf("withheld 项 %q 缺少理由", name) + } + } + + // 这些能力不应被任何 method 暴露。 + // + // 匹配用的是去掉 API 后缀的词根 + 词边界，而非直接子串： + // 直接子串匹配会把 tool.register / io.setToolBlocks 误判为泄露 ToolAPI， + // 而那两个是合法开放的（注册自己的工具、设置自己工具的返回块）。 + // 真正要拦的是形如 "tool.unregister" / "tracker.diff" 这类新增的越权 method。 + forbiddenPrefixes := map[string]string{ + "selftest.": "SelftestAPI", + "supervisor.": "SupervisorAPI", + "tracker.": "TrackerAPI", + "status.": "StatusAPI", + "adapter.": "AdapterAPI", + "config.": "ConfigAPI", + "indexer.": "IndexerAPI", + "outputchan.": "OutputChanRaw", + "events.publish": "EventPublish", + } + for m := range methodCapability { + lower := strings.ToLower(m) + for prefix, capName := range forbiddenPrefixes { + if strings.HasPrefix(lower, prefix) { + t.Errorf("method %q 暴露了刻意不提供的能力 %q", m, capName) + } + } + // 工具表直接操作：注册自己的工具合法，注销别人的不合法 + if strings.Contains(lower, "unregister") { + t.Errorf("method %q 暴露了工具注销能力（ToolAPI，刻意不提供）", m) + } + } +} + +// KnownCapabilities 不含 core（无需声明），且与 methodCapability 一致。 +func TestCapability_KnownListExcludesCore(t *testing.T) { + known := KnownCapabilities() + for _, k := range known { + if k == string(CapCore) { + t.Error("KnownCapabilities 不应含 core（无需声明）") + } + } + + // 每个非 core 能力都应可声明 + declared := map[string]bool{} + for _, k := range known { + declared[k] = true + } + for _, cap := range methodCapability { + if cap == CapCore { + continue + } + if !declared[string(cap)] { + t.Errorf("能力 %q 在 methodCapability 中使用但不在 KnownCapabilities 里", cap) + } + } +} + +// 未知 method 走 Handle 的兜底分支，不因权限检查提前返回误导性错误。 +func TestCapability_UnknownMethodFallsThrough(t *testing.T) { + h := &coreHandler{ + sdk: newFakeCore(), + name: "demo", + caps: newCapabilitySet([]string{"io"}), + } + _, err := h.Handle("nonexistent.method", nil) + if err == nil { + t.Fatal("未知 method 应报错") + } + // 应是「未知 method」而非「权限被拒」——否则作者会以为是漏声明能力 + if strings.Contains(err.Error(), "被拒") { + t.Errorf("未知 method 不应报权限错误，实际: %v", err) + } +} diff --git a/internal/plugin/proc/corehandler.go b/internal/plugin/proc/corehandler.go index fd3cf5d..2a36dab 100644 --- a/internal/plugin/proc/corehandler.go +++ b/internal/plugin/proc/corehandler.go @@ -39,6 +39,11 @@ type coreHandler struct { // evtRing 是事件环的订阅接口（实现由 internal/plugin 提供，避免循环依赖）。 evtRing EvtRingSubscriber + + // caps 是本插件被授予的能力集（§3.8 权限梯度）。 + // nil 或 unrestricted 时不限制——存量插件未声明 capabilities， + // 若按最小权限处理会让它们静默降级。 + caps *capabilitySet } // EvtRingSubscriber 是事件环订阅接口，由 internal/plugin.EventRing 实现。 @@ -91,7 +96,15 @@ type CoreSDK interface { } // Handle 分派一次插件 → 内核的调用。 +// +// 权限梯度在此强制（§3.8）：manifest 未声明的能力组被**明确拒绝**。 +// 不静默忽略：C ABI 时代 case 23/24 返回成功但永远收不到事件 +// （§1.3 的「给不了」而非「不给」），插件作者无从得知。 func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}, error) { + if ok, cap := h.caps.allows(method); !ok { + return nil, errCapabilityDenied(h.name, method, cap) + } + switch method { // ---- 注册面（原 case 1/2/3/4/46）---- diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go index eac7b75..3c99cd3 100644 --- a/internal/plugin/proc/plugin.go +++ b/internal/plugin/proc/plugin.go @@ -39,13 +39,20 @@ type Plugin struct { // onCrash 由 registry 注入，把进程退出喂给 plugin_health.recordCrash（§2.3）。 onCrash func(name string, err error) + // caps 是 manifest 声明的能力集（§3.8 权限梯度）。 + caps *capabilitySet + stopOnce sync.Once } // New 创建子进程插件（不启动进程）。 // // host 必须是全部子进程插件共用的实例（由 registry 创建一次）。 -func New(name, bin, dir string, config map[string]interface{}, host *Host, onCrash func(string, error)) *Plugin { +// New 创建子进程插件（不启动进程）。 +// +// host 必须是全部子进程插件共用的实例（由 registry 创建一次）。 +// capabilities 来自 manifest 的 capabilities 字段；为空时不限制（存量插件向后兼容）。 +func New(name, bin, dir string, config map[string]interface{}, host *Host, onCrash func(string, error), capabilities ...string) *Plugin { return &Plugin{ name: name, bin: bin, @@ -53,6 +60,7 @@ func New(name, bin, dir string, config map[string]interface{}, host *Host, onCra config: config, host: host, onCrash: onCrash, + caps: newCapabilitySet(capabilities), } } @@ -73,6 +81,7 @@ func (p *Plugin) Start(core CoreSDK) error { host: p.host, locks: p.host.locks, evtRing: p.host.evtSubscriber, + caps: p.caps, } // 反向调用闭包：注册回调时捕获，运行期经 RPC 打到插件进程。 p.handler.invokeTool = p.invokeTool diff --git a/internal/plugins/capability_wiring_test.go b/internal/plugins/capability_wiring_test.go new file mode 100644 index 0000000..b606b68 --- /dev/null +++ b/internal/plugins/capability_wiring_test.go @@ -0,0 +1,100 @@ +//go:build linux || darwin + +package plugins + +import ( + "fmt" + "os" + "path/filepath" + "strings" + "testing" +) + +// manifest 声明的 capabilities 在真实内核加载路径上生效（Part 6.4）。 +// +// capability_test.go 在 proc 包内验证判定逻辑；这里验证**接线**： +// manifest → readManifest → proc.New(caps...) → coreHandler.Handle 的强制。 + +// installPluginWithCaps 装插件并写入指定 capabilities 声明。 +func installPluginWithCaps(t *testing.T, plgDir, name string, caps []string) { + t.Helper() + src := realPluginBinary(t, name) + + dst := filepath.Join(plgDir, name) + if err := os.MkdirAll(dst, 0o755); err != nil { + t.Fatalf("建插件目录: %v", err) + } + data, err := os.ReadFile(src) + if err != nil { + t.Fatalf("读产物: %v", err) + } + if err := os.WriteFile(filepath.Join(dst, "plugin.bin"), data, 0o755); err != nil { + t.Fatalf("写产物: %v", err) + } + + capsJSON := "" + if caps != nil { + quoted := make([]string, len(caps)) + for i, c := range caps { + quoted[i] = fmt.Sprintf("%q", c) + } + capsJSON = fmt.Sprintf(`,"capabilities":[%s]`, strings.Join(quoted, ",")) + } + manifest := fmt.Sprintf( + `{"name":%q,"name_zh":%q,"name_en":%q,"version":"1.0.0","entry":"plugin.so"%s}`, + name, name, name, capsJSON) + if err := os.WriteFile(filepath.Join(dst, "plugin.json"), []byte(manifest), 0o644); err != nil { + t.Fatalf("写 manifest: %v", err) + } +} + +// 声明了受限能力集的插件仍能正常加载并注册工具。 +// +// core 能力（注册工具/阶段/通道 + 读写自己的配置）无需声明， +// 否则插件根本无法启动——weather 在 Start 里就要读 Settings。 +func TestCapability_RestrictedPluginStillLoads(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + // 只声明 io：weather 用到的 Settings 属 core，应放行 + installPluginWithCaps(t, plgDir, "weather", []string{"io"}) + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + if env.pluginReg.Get("weather") == nil { + t.Fatal("声明受限能力后插件应仍能加载（core 能力无需声明）") + } + + // 工具注册也属 core + found := false + for _, def := range env.stageHost.GetToolDefs() { + if strings.Contains(def.Name, "weather") { + found = true + break + } + } + if !found { + t.Error("受限插件仍应能注册工具（tool.register 属 core）") + } +} + +// 未声明 capabilities 的插件不受限——存量插件向后兼容。 +// +// 17 个存量插件的 plugin.json 都没有这个字段。若空声明当作最小权限， +// 它们会静默失去 IO 注入/记忆读写等能力，违反「外部插件零改动」。 +func TestCapability_LegacyManifestUnrestricted(t *testing.T) { + env := setupIntegration(t) + defer env.cleanup() + + plgDir := filepath.Join(env.tmpDir, "plugins") + installPluginWithCaps(t, plgDir, "weather", nil) // 无 capabilities 字段 + + if err := env.pluginReg.Load(plgDir); err != nil { + t.Fatalf("加载插件: %v", err) + } + if env.pluginReg.Get("weather") == nil { + t.Fatal("未声明 capabilities 的存量插件必须能正常加载") + } +} From 2572688c51f0046a41367d686fb95c418f6ec2b3 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 21:42:18 +0800 Subject: [PATCH 21/27] =?UTF-8?q?proc:=20=E6=80=A7=E8=83=BD=E5=9F=BA?= =?UTF-8?q?=E5=87=86=20+=20=E6=B5=81=E5=BC=8F=E5=8E=8B=E6=B5=8B=EF=BC=88Pa?= =?UTF-8?q?rt=206.6=20=E9=AA=8C=E6=94=B6=E9=A1=B9=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 此前只做了功能冒烟与内存快照，延迟与压测都没测。这两项是计划里 明确列出的验收条件，补上。 ## 基准结果（AMD Ryzen 7 7840HS） | 项目 | 实测 | 基线 | |---|---|---| | 工具调用 RPC 往返 | 24.1 µs | 实验 11: 19.6 µs（同量级） | | 锁仲裁（内核侧） | 0.76 µs | 见下注 | | 事件环写入 | 95 ns | — | | 事件环并发写入 | 83 ns | 无锁竞争恶化 | | 完整 stage 往返 | 132 µs | 含 3 次进程间往返 | | 共享段编解码 | 3.7 µs | 占 stage 的 2.8% | **锁仲裁 0.76µs 不可与实验 3 的 19.40µs 对照**——测的不是同一个东西： 实验 3 测插件经 RPC 请求锁的完整跨进程往返，本基准只测内核侧 lockRegistry.acquire/release。真实成本仍在 20µs 量级。 基准原名 BenchmarkStageLockRoundTrip 有误导性，已改为 BenchmarkStageLockArbitration，并在注释里写明不可对照的理由—— 否则日后有人拿 0.76µs 去比 19.4µs 会得出「优化了 25 倍」的错误结论。 **stage 往返 132µs 的成本构成**：共享段编解码只占 3.7µs，其余是 一次 stage 要走 3 次进程间往返（stage.invoke + 插件侧反向的 stage.lock / stage.unlock）。相对 LLM 往返 2-8 秒可忽略；要优化的方向是 把 lock/unlock 合入 stage.invoke 的请求/应答，省掉两次往返。 ## 流式压测：§4.3 标记「风险高」的那一项通过 原文担忧：「Bus.Publish 路径禁用任何锁/阻塞——流式输出逐 token 发布， 任何等待都会卡顿」。事件环是 Part 5 新加在这条路径上的，必须验。 ``` 5000 次 Publish + 每条睡 20µs 的慢消费者 实测 2.29ms，均摊 457 ns/token 同步语义理论下限 100ms 订阅者 1 个：1.547ms（515 ns/次） 订阅者 8 个：1.518ms（506 ns/次） ← 无线性恶化 环溢出（无消费者写 30000 次，cap=8192）：均摊 35 ns/次 ← 仍 O(1) ``` 2.29ms 与实验 4 的数字完全一致（那次也是 2.29ms / 0.46µs per token）， post-and-forget 在实现中成立。 第三项的意义：消费者完全停摆时写端覆盖最旧 slot，这条路径仍是 O(1)， 故「消费者卡住」不会连带拖慢内核主循环。 Ref: docs/zh/plugin-migration-plan.md Part 6.6、docs/zh/架构迁移评估.md §4.3 --- .../plugin-arch/19-migration-verify/README.md | 54 +++++ internal/plugin/proc/bench_test.go | 222 ++++++++++++++++++ internal/plugin/proc/streaming_test.go | 157 +++++++++++++ 3 files changed, 433 insertions(+) create mode 100644 internal/plugin/proc/bench_test.go create mode 100644 internal/plugin/proc/streaming_test.go diff --git a/docs/zh/experiments/plugin-arch/19-migration-verify/README.md b/docs/zh/experiments/plugin-arch/19-migration-verify/README.md index 9b69747..bfa29c6 100644 --- a/docs/zh/experiments/plugin-arch/19-migration-verify/README.md +++ b/docs/zh/experiments/plugin-arch/19-migration-verify/README.md @@ -81,3 +81,57 @@ RSS 随二进制体积线性增长，故绝对数字不可比。可比的是结 这些测试用**真实 example 产物**而非 testdata 假插件，且 manifest 刻意写 `"entry":"plugin.so"`——验证「业务代码零改动」这一承诺在完整内核装配下成立。 未重编时 skip 而非 fail，CI 不强制先跑重编脚本。 + +## 压测与延迟（Part 6.6 验收） + +基准与压测在代码里而非独立脚本： +`internal/plugin/proc/bench_test.go` + `streaming_test.go`。 + +```bash +go test -run '^$' -bench . ./internal/plugin/proc/ +go test -run 'TestStreaming_' -v ./internal/plugin/proc/ +``` + +### 实测（2026-09-02，AMD Ryzen 7 7840HS） + +| 项目 | 实测 | 基线 | 判断 | +|---|---|---|---| +| 工具调用 RPC 往返 | 24.1 µs | 实验 11: 19.6 µs | 同量级 | +| 锁仲裁（内核侧） | 0.76 µs | — | 见下注 | +| 事件环写入 | 95 ns | — | 亚微秒 | +| 事件环并发写入 | 83 ns | — | 无锁竞争恶化 | +| 完整 stage 往返 | 132 µs | — | 含 3 次进程间往返 | +| 共享段编解码 | 3.7 µs | — | 占 stage 的 2.8% | + +**锁仲裁 0.76µs 不可与实验 3 的 19.40µs 对照**——两者测的不是同一个东西： +实验 3 测插件经 RPC 请求锁的完整跨进程往返，本基准只测内核侧 +`lockRegistry.acquire/release`。真实成本仍在 20µs 量级（那部分是 RPC 往返）。 +基准原名 `BenchmarkStageLockRoundTrip` 有误导性，已改为 +`BenchmarkStageLockArbitration`。 + +**stage 往返 132µs 的成本构成**：共享段编解码只占 3.7µs（2.8%）， +其余是**一次 stage 要走 3 次进程间往返**——`stage.invoke` 加上插件侧反向的 +`stage.lock` / `stage.unlock`。相对 LLM 往返 2-8 秒可忽略；若日后要优化， +方向是把 lock/unlock 合入 `stage.invoke` 的请求/应答，省掉两次往返。 + +### 流式压测（§4.3 标记「风险高」的那一项） + +原文的担忧：「`Bus.Publish` 路径禁用任何锁/阻塞——流式输出逐 token 发布， +任何等待都会卡顿」。 + +``` +5000 次 Publish + 每条睡 20µs 的慢消费者 + 实测 2.29ms，均摊 457 ns/token + 同步语义理论下限 100ms（5000 × 20µs） + +订阅者 1 个：1.547ms（515 ns/次） +订阅者 8 个：1.518ms（506 ns/次） ← 几乎不变，无线性恶化 + +环溢出（无消费者写 30000 次，cap=8192）：均摊 35 ns/次 ← 仍 O(1) +``` + +2.29ms 与实验 4 的数字完全一致（那次也是 2.29ms / 0.46µs per token）—— +post-and-forget 在实现中成立。 + +最后一项的意义：消费者完全停摆时写端覆盖最旧 slot，这条路径仍是 O(1)， +故「消费者卡住」不会连带拖慢内核主循环。 diff --git a/internal/plugin/proc/bench_test.go b/internal/plugin/proc/bench_test.go new file mode 100644 index 0000000..24f4bb2 --- /dev/null +++ b/internal/plugin/proc/bench_test.go @@ -0,0 +1,222 @@ +package proc + +import ( + "os" + "os/exec" + "path/filepath" + "testing" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 子进程架构的性能基准（Part 6.6 验收项）。 +// +// 对照基线来自 docs/zh/experiments/plugin-arch： +// +// 实验 3 锁仲裁 RPC 往返 19.40 µs/次 +// 实验 4 post-and-forget 5.07s → 2.29ms（5000 token + 20µs 慢消费者） +// 实验 11 工具调用 RPC p50 19.6 µs +// +// 这些基准回答的是「进程边界的代价是否可忽略」——相对 stage handler 的实际 +// 工作量（LLM 往返 2-8 秒），微秒级往返不构成问题；但若退化到毫秒级， +// 高频工具调用就会被感知。 +// +// 实测结果（2026-09-02，AMD Ryzen 7 7840HS）： +// +// ToolInvoke 24.1 µs/op ← 对照实验 11 的 19.6µs，同量级 +// StageLockArbitration 0.76 µs/op ← 仅内核侧仲裁，不跨进程 +// EvtRingWritePush 95 ns/op +// EvtRingWritePushConcurrent 83 ns/op ← 并发不恶化 +// StageInvokeSharedMemory 132 µs/op ← 含 3 次进程间往返 +// SegmentWriteAllReadInto 3.7 µs/op ← 占 stage 的 2.8% + +// buildBenchPlugin 编译 testdata 里的测试插件（benchmark 版）。 +func buildBenchPlugin(b *testing.B, srcName string) string { + b.Helper() + src := filepath.Join("testdata", srcName) + if _, err := os.Stat(src); err != nil { + b.Skipf("测试插件源码缺失 %s: %v", src, err) + } + bin := filepath.Join(b.TempDir(), "benchplugin") + cmd := exec.Command("go", "build", "-o", bin, src) + cmd.Env = append(os.Environ(), "CGO_ENABLED=0") + if out, err := cmd.CombinedOutput(); err != nil { + b.Fatalf("编译 %s: %v\n%s", srcName, err, out) + } + return bin +} + +// BenchmarkToolInvoke 测量内核 → 插件的工具调用往返。 +// +// 链路：Call 写 stdin → 插件读循环 → handler → 写 stdout → +// 内核 readLoop → pending channel 唤醒。对照实验 11 的 19.6µs。 +func BenchmarkToolInvoke(b *testing.B) { + bin := buildBenchPlugin(b, "echoplugin.go") + + p, err := Spawn("echo", bin, Options{Handler: noopHandler}) + if err != nil { + b.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + args := map[string]interface{}{"text": "benchmark"} + + b.ResetTimer() + for i := 0; i < b.N; i++ { + if _, err := p.Call(MethodToolInvoke, ToolInvokeParams{ + Name: "echo_tool", + Args: args, + }); err != nil { + b.Fatalf("第 %d 次调用失败: %v", i, err) + } + } +} + +// BenchmarkStageLockArbitration 测量**内核侧锁仲裁本身**的成本。 +// +// ⚠️ 不要拿这个数字对照实验 3 的 19.40µs——两者测的不是同一个东西： +// - 实验 3：插件经 RPC 请求锁的**完整跨进程往返** +// - 本基准：仅 lockRegistry.acquire/release，不跨进程 +// +// 真实成本仍在 20µs 量级（那部分是 RPC 往返，见 BenchmarkToolInvoke）。 +// 本基准的用途是确认仲裁逻辑自身不是瓶颈：若它也到了微秒级， +// 说明 sync.Mutex 之外又引入了什么开销。 +func BenchmarkStageLockArbitration(b *testing.B) { + lock := newStageLock() + r := &lockRegistry{} + r.bind(lock) + + b.ResetTimer() + for i := 0; i < b.N; i++ { + if err := r.acquire("bench"); err != nil { + b.Fatalf("acquire: %v", err) + } + if err := r.release("bench"); err != nil { + b.Fatalf("release: %v", err) + } + } +} + +// BenchmarkEvtRingWritePush 测量事件环写入（Bus.Publish 路径）。 +// +// 这是 §4.3 标记「风险高」的那一项：流式输出逐 token 发布， +// Publish 路径上任何阻塞都会直接卡顿。 +func BenchmarkEvtRingWritePush(b *testing.B) { + host, err := NewHost() + if err != nil { + b.Fatalf("NewHost: %v", err) + } + defer host.Close() + + ring := host.EvtRing() + payload := []byte(`{"type":"content_delta","payload":{"text":"token"}}`) + + b.ResetTimer() + for i := 0; i < b.N; i++ { + ring.WritePush(pubsdk.EventContentDelta, payload) + } +} + +// BenchmarkEvtRingWritePushConcurrent 并发写入。 +// +// 内核有多条路径并发发布事件（主循环、工具调用、流式增量）， +// writeSeq 是 atomic 而 arena 分配有锁——确认锁不是瓶颈。 +func BenchmarkEvtRingWritePushConcurrent(b *testing.B) { + host, err := NewHost() + if err != nil { + b.Fatalf("NewHost: %v", err) + } + defer host.Close() + + ring := host.EvtRing() + payload := []byte(`{"type":"content_delta","payload":{"text":"tok"}}`) + + b.ResetTimer() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + ring.WritePush(pubsdk.EventContentDelta, payload) + } + }) +} + +// BenchmarkStageInvokeSharedMemory 测量完整 stage 往返： +// 写共享段 → RPC → 插件读改写 → 回读 → 压实。 +// +// 这是迁移引入的最重路径，每次 stage 都要走一遍。 +// +// 实测 ~132µs，比单次 RPC（~24µs）高 5 倍，因为**一次 stage 要走 3 次 +// 进程间往返**：stage.invoke + 插件侧反向的 stage.lock / stage.unlock。 +// 共享段编解码只占 3.7µs（2.8%）——成本在往返次数而非数据搬运。 +// +// 相对 LLM 往返 2-8 秒可忽略。若日后要优化，方向是把 lock/unlock +// 合入 stage.invoke 的请求/应答，省掉两次往返。 +func BenchmarkStageInvokeSharedMemory(b *testing.B) { + bin := buildBenchPlugin(b, "stageplugin.go") + + host, err := NewHost() + if err != nil { + b.Fatalf("NewHost: %v", err) + } + defer host.Close() + + core := newFakeCore() + p := New("sanitizer", bin, b.TempDir(), nil, host, nil) + if err := p.Start(core); err != nil { + b.Fatalf("Start: %v", err) + } + defer p.Close() + + handlers := core.stageHandlers(pubsdk.StageAfterToolcall) + if len(handlers) != 1 { + b.Fatalf("应注册 1 个 handler，实际 %d", len(handlers)) + } + handler := handlers[0] + + b.ResetTimer() + for i := 0; i < b.N; i++ { + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + ToolResults: []pubsdk.ToolResult{ + {CallID: "c1", Name: "t", Result: "结果：\x1b[31m脏\x1b[0m"}, + }, + } + if err := handler(sc); err != nil { + b.Fatalf("第 %d 次 stage 失败: %v", i, err) + } + } +} + +// BenchmarkSegmentWriteAllReadInto 只测共享段编解码（不含 RPC）。 +// +// 用于拆分 stage 往返的成本构成：编解码 vs 进程间通信。 +func BenchmarkSegmentWriteAllReadInto(b *testing.B) { + host, err := NewHost() + if err != nil { + b.Fatalf("NewHost: %v", err) + } + defer host.Close() + seg := host.Segment() + + sc := &pubsdk.StageContext{ + Phase: pubsdk.StageAfterToolcall, + RawMessage: "用户输入的一段话", + UserID: "u1", + LLMText: "模型输出的文本", + FinalText: "最终文本", + ToolResults: []pubsdk.ToolResult{ + {CallID: "c1", Name: "tool_a", Result: "结果 A"}, + {CallID: "c2", Name: "tool_b", Result: "结果 B"}, + }, + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + if err := seg.WriteAll(sc); err != nil { + b.Fatalf("WriteAll: %v", err) + } + if err := seg.ReadInto(sc); err != nil { + b.Fatalf("ReadInto: %v", err) + } + seg.Compact() + } +} diff --git a/internal/plugin/proc/streaming_test.go b/internal/plugin/proc/streaming_test.go new file mode 100644 index 0000000..0418f94 --- /dev/null +++ b/internal/plugin/proc/streaming_test.go @@ -0,0 +1,157 @@ +package proc + +import ( + "sync" + "sync/atomic" + "testing" + "time" + + pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" +) + +// 流式输出压测（§4.3 标记「风险高」的那一项）。 +// +// 担忧的原文：「Bus.Publish 路径禁用任何锁/阻塞——流式输出逐 token 发布， +// 任何等待都会卡顿」。实验 4 的数据：同步 Publish + 一个 20µs 慢订阅者， +// 5000 token 耗时 5.07s；改为写环 + post 后 2.29ms（加速比 2218x）。 +// +// 这里验证事件环侧的 post-and-forget 性质在实现中成立。 + +// 慢消费者不拖慢 Publish。 +// +// 判据：若 Publish 等消费者，5000 × 20µs = 100ms 是理论下限。 +// post-and-forget 应远低于此。 +func TestStreaming_SlowConsumerDoesNotBlockPublish(t *testing.T) { + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + ring := host.EvtRing() + + var consumed atomic.Int64 + consumer := NewEvtConsumer(host.EvtData(), host.EvtfdReadFile(), 0, + func(evt *pubsdk.Event) error { + time.Sleep(20 * time.Microsecond) // 刻意的慢订阅者 + consumed.Add(1) + return nil + }) + go consumer.Run() + defer consumer.Stop() + + const tokens = 5000 + payload := []byte(`{"type":"content_delta","payload":{"text":"t"}}`) + + start := time.Now() + for i := 0; i < tokens; i++ { + ring.WritePush(pubsdk.EventContentDelta, payload) + EvtfdNotify(host.EvtNotifyFd()) + } + elapsed := time.Since(start) + perToken := elapsed / tokens + + t.Logf("%d 次 Publish 耗时 %v，均摊 %v/token（消费者每条睡 20µs）", + tokens, elapsed, perToken) + t.Logf("同步语义下的理论下限：%v", tokens*20*time.Microsecond) + + if elapsed > 100*time.Millisecond { + t.Errorf("Publish 疑似被慢消费者阻塞：耗时 %v ≥ 同步下限 100ms", elapsed) + } + if perToken > 20*time.Microsecond { + t.Errorf("均摊 %v/token ≥ 消费者处理时间 20µs，说明存在等待", perToken) + } +} + +// 订阅者增多不使 Publish 线性恶化。 +// +// §4.3 的具体要求：「长回复下 Publish 单次耗时不随订阅者数线性恶化」。 +func TestStreaming_PublishLatencyFlatAcrossSubscribers(t *testing.T) { + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + ring := host.EvtRing() + payload := []byte(`{"type":"content_delta","payload":{"text":"t"}}`) + const rounds = 3000 + + measure := func(consumers int) time.Duration { + var wg sync.WaitGroup + active := make([]*EvtConsumer, 0, consumers) + for i := 0; i < consumers; i++ { + c := NewEvtConsumer(host.EvtData(), host.EvtfdReadFile(), 0, + func(evt *pubsdk.Event) error { + time.Sleep(10 * time.Microsecond) + return nil + }) + active = append(active, c) + wg.Add(1) + go func(cc *EvtConsumer) { + defer wg.Done() + cc.Run() + }(c) + } + defer func() { + for _, c := range active { + c.Stop() + } + }() + + // 让消费者先就位 + time.Sleep(10 * time.Millisecond) + + start := time.Now() + for i := 0; i < rounds; i++ { + ring.WritePush(pubsdk.EventContentDelta, payload) + EvtfdNotify(host.EvtNotifyFd()) + } + return time.Since(start) + } + + d1 := measure(1) + d8 := measure(8) + + t.Logf("1 个消费者：%v（均摊 %v/次）", d1, d1/rounds) + t.Logf("8 个消费者：%v（均摊 %v/次）", d8, d8/rounds) + + // 线性恶化的判据：8 倍订阅者不应接近 8 倍耗时。 + // 阈值取 4 倍——测量噪声与调度抖动都会影响。 + if d8 > d1*4 { + t.Errorf("订阅者 1→8，Publish 从 %v 涨到 %v（>4 倍），疑似线性恶化", d1, d8) + } +} + +// 事件环溢出时 Publish 不退化。 +// +// 消费者完全停摆时写端会覆盖最旧 slot。这条路径必须仍是 O(1)， +// 否则「消费者卡住」会连带拖慢内核主循环。 +func TestStreaming_PublishStaysFastWhenRingOverflows(t *testing.T) { + host, err := NewHost() + if err != nil { + t.Fatalf("NewHost: %v", err) + } + defer host.Close() + + ring := host.EvtRing() + payload := []byte(`{"type":"content_delta","payload":{"text":"t"}}`) + + // 无消费者：环必然溢出（cap=8192） + const rounds = 30000 + + start := time.Now() + for i := 0; i < rounds; i++ { + ring.WritePush(pubsdk.EventContentDelta, payload) + } + elapsed := time.Since(start) + perPush := elapsed / rounds + + t.Logf("无消费者写入 %d 次（环 cap=%d，必然溢出）：%v，均摊 %v/次", + rounds, evtRingCap, elapsed, perPush) + + // 溢出路径仍应是亚微秒级 + if perPush > 5*time.Microsecond { + t.Errorf("溢出时均摊 %v/次，超出预期（应亚微秒级）", perPush) + } +} From 62bdfa2b5445e3af8c592886ec9eaf46ef924c66 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 22:40:47 +0800 Subject: [PATCH 22/27] =?UTF-8?q?meta:=20=E5=86=85=E6=A0=B8=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=8D=87=E5=88=B0=201.0.0=EF=BC=9B=E7=94=9F=E4=BA=A7?= =?UTF-8?q?=E5=88=87=E6=8D=A2=E8=84=9A=E6=9C=AC=E6=94=B9=E8=B5=B0=20hmap?= =?UTF-8?q?=20=E6=AD=A3=E8=A7=84=E9=80=9A=E9=81=93=EF=BC=88Part=206.5?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 版本号 1.0.0：外部插件从 C ABI 动态库迁到子进程 + 共享内存。首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件必须用新版 plugindev 重编）。 SDKCompatibleVersion 同步升 1.0.0。 同时删掉 ABIVersion / CABINum / 51 个 Core 整数 ID —— 随 Part 6.2 删 internal/plugin/cabi/ 就已无使用者（grep 确认只剩定义处）。留着会让人 以为 C 层协商还在生效，或以为加 method 要同步维护那张整数表。 ⚠️ 注意 Makefile 的 `VERSION ?= $(shell git describe --tags --dirty)`： 实际注入值来自 git tag，meta.go 里的默认值只在不带 ldflags 时生效。 make build 当前注入 v0.9.1-56-g2572688-dirty。要让 1.0.0 真正生效需打 v1.0.0 tag 或显式传 VERSION=1.0.0。 ## 生产切换脚本重写 第一版是手工拷 plugin.bin + 手改 plugin.json 的 entry —— 那等于**重新实现 了一遍 hmap 解包逻辑，且实现得更差**。漏掉的东西： platforms 字段 hmap 内的 plugin.json 本来就写对了 平台二进制选择 我硬编码 _linux_amd64，正规路径用 platformBinary() overwrite 语义 StopAndUnload 停旧实例但**保留配置表** 失败回滚 os.Rename 备份旧目录，解包失败自动恢复 校验 validatePackage 查 manifest + 各平台二进制齐全 配置保留那条尤其关键：生产 17 个插件都有配置（qq 账号、weather 默认城市、 browser profile 路径）。我的脚本恰好没碰配置表所以侥幸不丢，但那是运气 不是设计。 改为 POST 到 pluginmgr 的 HTTP 端点（127.0.0.1:9876/plugins）， 传 {path, overwrite:true} 走 installFromPath → installFromData。 保留的一个设计：**先全部校验再动手**。任一插件缺 hmap 就整批中止—— 新 homed 不认 .so，「一半装了一半没装」的中间态最难排查。 ## 生产切换已执行 顺序（先换二进制再装包，而非反过来）： 1. systemctl stop homeagent 2. 换 /usr/local/bin/homed 3. 起服务 —— 15 个 .so 插件报可操作错误被跳过，homed 本体与 16 个内置正常 4. 逐个 POST 装 17 个 hmap（overwrite=true） 5. 待重启核对 第 3 步顺带在真实二进制上验证了 Part 6.2 的可操作错误： [plugin] dynamic weather: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。 外部插件已改为子进程模式，请用新版 plugindev 重编产出 plugin.bin （业务代码无需修改） 不崩溃，只跳过。若反过来先装包，旧 homed 的 StopAndUnload 会停掉 qq 消息通道且无法重载 .bin，会卡在「插件全挂」的状态。 结果：17/17 成功，全部 config_kept=true；0 个残留 .so；17 个 plugin.bin 均有执行位；17 个 manifest 的 entry 均为 plugin.bin；无 .bak 残留。 bundle 包正确挑了当前平台（weather 目录只留 8.7MB 的 linux/amd64 那份）。 备份：/home/newqqagent-migration-backup-20260902-214812 （plugins 全目录 + homed.old + homeagent.service，162MB） 验证：go build ./... 通过；go test ./... 全仓无失败。 Ref: docs/zh/plugin-migration-plan.md Part 6.5 --- .../19-migration-verify/switch-production.py | 132 ++++++++++++++++++ internal/meta/meta.go | 99 +++---------- 2 files changed, 150 insertions(+), 81 deletions(-) create mode 100755 docs/zh/experiments/plugin-arch/19-migration-verify/switch-production.py diff --git a/docs/zh/experiments/plugin-arch/19-migration-verify/switch-production.py b/docs/zh/experiments/plugin-arch/19-migration-verify/switch-production.py new file mode 100755 index 0000000..3faecc7 --- /dev/null +++ b/docs/zh/experiments/plugin-arch/19-migration-verify/switch-production.py @@ -0,0 +1,132 @@ +#!/usr/bin/env python3 +"""生产切换：经 pluginmgr 正规通道安装 17 个 hmap（Part 6.5）。 + +与手工拷贝方案的区别 —— 这里复用内核自己的安装逻辑： + + validatePackage 校验 manifest + 平台二进制齐全 + StopAndUnload 停旧实例但**保留配置表** + os.Rename 备份 解包失败自动回滚到旧版本 + platformBinary() 按 runtime 挑当前平台那份，重命名为 plugin.bin + chmod 0755 补执行位 + +手工拷贝会重新实现这一套，且必然实现得更差（第一版就漏了 platforms 字段 +与配置保留语义）。 + +用法： + switch-production.py 演练 + switch-production.py --apply 实际安装 +""" + +import json +import os +import sys +import urllib.error +import urllib.request + +PROD_PLUGINS = "/home/newqqagent/plugins" +SDK_EXAMPLE = "/home/program/TrueAgent/third_party/homeagent-sdk/example" +PLUGINMGR = "http://127.0.0.1:9876/plugins" + + +def find_hmap(name): + """找插件的 hmap 包。 + + bundle:true -> _bundle.hmap（含多平台二进制） + bundle:false -> __.hmap（qq 是这种） + """ + dist = os.path.join(SDK_EXAMPLE, name, "dist") + if not os.path.isdir(dist): + return None + cands = [f for f in os.listdir(dist) if f.endswith(".hmap")] + if not cands: + return None + for c in cands: + if c.endswith("_bundle.hmap"): + return os.path.join(dist, c) + return os.path.join(dist, sorted(cands)[0]) + + +def install(path): + """POST 到 pluginmgr。overwrite=true 走原地更新分支，保留配置表。""" + body = json.dumps({"path": path, "overwrite": True}).encode() + req = urllib.request.Request( + PLUGINMGR, data=body, + headers={"Content-Type": "application/json"}, + method="POST") + try: + with urllib.request.urlopen(req, timeout=180) as resp: + return json.loads(resp.read().decode()), None + except urllib.error.HTTPError as e: + return None, "HTTP %d: %s" % (e.code, e.read().decode()[:300]) + except Exception as e: + return None, str(e) + + +def main(): + apply = "--apply" in sys.argv + + targets = sorted( + d for d in os.listdir(PROD_PLUGINS) + if os.path.isfile(os.path.join(PROD_PLUGINS, d, "plugin.so")) + or os.path.isfile(os.path.join(PROD_PLUGINS, d, "plugin.bin")) + ) + print("生产外部插件: %d 个" % len(targets)) + + # 先全部校验，任一缺包就整批中止。 + # 理由：新 homed 不认 .so，「一半装了一半没装」的中间态最难排查。 + plan = [] + missing = [] + for name in targets: + h = find_hmap(name) + if h is None: + missing.append(name) + else: + plan.append((name, h)) + + if missing: + print("\n✗ 中止：以下插件缺 hmap 包：") + for m in missing: + print(" " + m) + print("\n先跑 rebuild-plugins.sh 重编。") + return 1 + + print("✓ 全部 %d 个 hmap 就位\n" % len(plan)) + for name, h in plan: + print(" %-16s %-44s %6d KB" % ( + name, os.path.basename(h), os.path.getsize(h) // 1024)) + + if not apply: + print("\n[演练] 加 --apply 才实际安装") + return 0 + + print("\n经 pluginmgr 安装（overwrite=true，保留配置）...") + ok = 0 + failed = [] + for name, h in plan: + result, err = install(h) + if err: + print(" ✗ %-16s %s" % (name, err)) + failed.append(name) + continue + if "error" in result: + print(" ✗ %-16s %s: %s" % ( + name, result["error"], result.get("details", ""))) + failed.append(name) + continue + print(" ✓ %-16s %-12s v%s -> v%s config_kept=%s" % ( + name, + result.get("action", "?"), + result.get("previous_version", "?"), + result.get("version", "?"), + result.get("config_kept", False))) + ok += 1 + + print("\n成功 %d / 失败 %d" % (ok, len(failed))) + if failed: + print("失败: " + " ".join(failed)) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/internal/meta/meta.go b/internal/meta/meta.go index cb47670..1d8d464 100644 --- a/internal/meta/meta.go +++ b/internal/meta/meta.go @@ -1,13 +1,16 @@ // Package meta 收集 HomeAgent 内核的全部元数据。 // 版本号通过 `go build -ldflags` 注入，默认值为 dev 版本。 -// 此文件是 ABI 版本号与 dispatch method ID 的唯一数据源。 // SDK 仓的 meta/meta.go 应与此保持同步。 package meta var ( // Version 是 HomeAgent 内核版本号。 // 通过 `-ldflags="-X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Version=vX.Y.Z"` 注入。 - Version = "0.9.1" + // + // 1.0.0：外部插件从 C ABI 动态库迁到子进程 + 共享内存。 + // 这是首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件必须 + // 用新版 plugindev 重编），故跃到主版本号。 + Version = "1.0.0" // Commit 是构建时的 Git commit hash。 Commit = "unknown" @@ -19,7 +22,7 @@ var ( KernelName = "HomeAgent" // SDKCompatibleVersion 是此内核可兼容的最高 SDK 版本（semver）。 - SDKCompatibleVersion = "0.9.1" + SDKCompatibleVersion = "1.0.0" ) // FullVersion 返回完整的版本字符串。 @@ -27,81 +30,15 @@ func FullVersion() string { return KernelName + " v" + Version + " (" + Commit + ")" } -// ---- ABI 版本（C ABI 协议版本，插件与内核通信用） ---- -// ABI 版本直接取内核版本号字符串（semver），与核心 Version 保持一致，不再使用独立数字编码。 -// 协商层（C 结构体 int version 字段）使用 CABINum：由版本字符串派生的整数（major*100 + minor）。 -// 映射：v0.8.x → CABINum=800；v0.9.x → CABINum=900（invoke_stage 写回）。 -// 小版本（patch）演进不影响 ABI，CABINum 不变。version_min 保证旧 ABI 插件仍可加载。 - -var ( - // ABIVersion 是 ABI 标识版本（字符串 semver，与核心 Version 对齐）。 - ABIVersion = Version - // ABIVersionMin 是兼容的最低 ABI 标识版本。 - ABIVersionMin = "0.8.0" -) - -const ( - // CABINum 是 C 层协商用的整数版本（major*100 + minor），随 ABIVersion 派生。 - CABINum = 900 - // CABINumMin 是 C 层兼容的最低整数版本。 - // 旧工具链（v0.8 之前）写入的整数 version=1，无写回能力但与新内核结构兼容， - // 因此最小值保持 1 以兼容全部旧插件（新插件 900 匹配，旧插件 1/2 通过）； - // 仅当未来内核 ABI 破坏兼容时才提高该值。 - CABINumMin = 1 -) - -// ---- Dispatch Method IDs ---- -// 核心→插件：这些 ID 通过 CoreAPI.dispatch 传递，标识 SDK 调用。 -// 插件端的 C enum 定义在 plugindev 的 C ABI header 模板中。 -const ( - CoreRegisterTool = 1 - CoreRegisterStage = 2 - CoreRegisterOutputCh = 3 - CoreRegisterPluginAPI = 4 - CoreInjectText = 5 - CoreInjectInterruptText = 6 - CoreInjectTextNoMemory = 7 - CoreSetAutoRestart = 8 - CoreMemoryRecall = 9 - CoreMemoryCommit = 10 - CoreMemoryIntrospect = 11 - CoreMemoryMerge = 12 - CoreMemoryPurge = 13 - CoreDocQuery = 14 - CoreKnowledgeSearch = 15 - CoreSettingsGet = 16 - CoreSettingsSet = 17 - CoreSettingsRegisterDef = 18 - CoreLLMListSources = 19 - CoreLLMSetSource = 20 - CoreSocialGetPerson = 21 - CoreSocialGetNetwork = 22 - CoreSubscribe = 23 - CoreUnsubscribe = 24 - CoreFreeString = 25 - CoreSettingsGetCore = 26 - CoreSettingsSetCore = 27 - CoreSettingsListCore = 28 - CoreSettingsGetPlugin = 29 - CoreSettingsSetPlugin = 30 - CoreSettingsListPlugin = 31 - CoreDocInsert = 32 - CoreDocRemove = 33 - CoreDocStats = 34 - CoreKnowledgeAdd = 35 - CoreKnowledgeList = 36 - CoreLLMCurrentSource = 37 - CoreSocialGetTrait = 38 - CoreSocialGetRelations = 39 - CoreSocialListPersons = 40 - CoreTextMemoryAppend = 41 - CoreSettingsList = 42 - CoreSettingsDefs = 43 - CoreSettingsDump = 44 - CoreSettingsPlugins = 45 - CoreRegisterInputCh = 46 - CoreInjectInputSync = 47 - CorePluginReloadOne = 48 - CorePluginListLoaded = 49 - CorePluginIsDisabled = 50 -) +// ---- 协议版本 ---- +// +// 子进程 RPC 的协议版本是一个独立的小整数，与内核语义版本解耦： +// 语义版本变动频繁（修 bug、加字段），而 wire 协议只在**帧格式或握手语义** +// 变化时才升。当前值见 internal/plugin/proc/protocol.go 的 ProtocolVersion。 +// +// C ABI 时代的 ABIVersion / CABINum / 51 个 Core 整数 ID 已随 +// Part 6.2 删除 internal/plugin/cabi/ 一并退场： +// - 整数 method id 平移为 method 名字符串（proc/protocol.go 的 Method* 常量） +// - 版本协商改为握手帧里的 protocol 字段 +// +// 保留那些常量只会让人以为它们还在生效。 From 670efcd426b99668f846abbdb3b3eff4ec53c2ed Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Wed, 2 Sep 2026 23:02:26 +0800 Subject: [PATCH 23/27] =?UTF-8?q?sdk:=20=E5=90=8C=E6=AD=A5=20SDK=20?= =?UTF-8?q?=E4=BB=93=20meta=20=E5=88=B0=201.0.0=EF=BC=88vendored=20?= =?UTF-8?q?=E4=BE=A7=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SDK 仓的 5ed8d65 在主仓这边的对应提交。主仓经 replace 引用 third_party/homeagent-sdk，其 sdk/ 与 meta/ 由主仓一并跟踪 （只有 example/ 与 tools/ 被 .gitignore 忽略）。 --- third_party/homeagent-sdk/meta/meta.go | 100 ++++++------------------- 1 file changed, 21 insertions(+), 79 deletions(-) diff --git a/third_party/homeagent-sdk/meta/meta.go b/third_party/homeagent-sdk/meta/meta.go index 883bbba..1e0619c 100644 --- a/third_party/homeagent-sdk/meta/meta.go +++ b/third_party/homeagent-sdk/meta/meta.go @@ -1,12 +1,15 @@ // Package meta 收集 HomeAgent SDK 的全部元数据。 // 版本号应与核心 meta.Version 保持一致。 -// ABI 版本与 Dispatch Method ID 应与核心仓 internal/meta/meta.go 保持一致。 package meta var ( // Version 是 HomeAgent SDK 版本号。 // 通过 `-ldflags="-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=vX.Y.Z"` 注入。 - Version = "0.9.2" + // + // 1.0.0：插件运行模型从 C ABI 动态库改为子进程 + 共享内存。 + // 公开 SDK 接口（sdk/ 目录）**零改动**——插件业务代码不需要改一行， + // 但产物形态变了（plugin.so → plugin.bin），必须用新版 plugindev 重编。 + Version = "1.0.0" // Commit 是构建时的 Git commit hash。 Commit = "unknown" @@ -21,7 +24,10 @@ var ( CoreModule = "gitcode.com/JianFeeeee/HomeAgent" // CoreVersion 是此 SDK 所兼容的最低核心版本。 - CoreVersion = "0.9.2" + // + // 1.0.0 是硬下限而非建议值：0.9.x 内核只会 dlopen `.so`， + // 本版工具链产出的 `plugin.bin` 在旧内核上根本不会被识别。 + CoreVersion = "1.0.0" ) // FullVersion 返回完整的版本字符串。 @@ -29,79 +35,15 @@ func FullVersion() string { return SDKName + " v" + Version + " (" + Commit + ")" } -// ---- ABI 版本（与核心仓 internal/meta/meta.go 同步） ---- -// ABI 标识版本直接取内核版本号字符串（semver），与核心 Version 保持一致，不使用独立数字编码。 -// 协商层（C 结构体 int version 字段）使用 CABINum：由版本字符串派生的整数（major*100 + minor）。 -// 映射：v0.8.x → CABINum=800；v0.9.x → CABINum=900（invoke_stage 写回）。 -// 小版本（patch）演进不影响 ABI，CABINum 不变。version_min 保证旧 ABI 插件仍可加载。 - -var ( - // ABIVersion 是 ABI 标识版本（字符串 semver，与 SDK CoreVersion 对齐）。 - ABIVersion = CoreVersion - // ABIVersionMin 是兼容的最低 ABI 标识版本。 - ABIVersionMin = "0.8.0" -) - -const ( - // CABINum 是 C 层协商用的整数版本（major*100 + minor），随 ABIVersion 派生。 - CABINum = 900 - // CABINumMin 是 C 层兼容的最低整数版本。 - // 旧工具链（v0.8 之前）写入的整数 version=1，无写回能力但与新内核结构兼容， - // 因此最小值保持 1 以兼容全部旧插件（新插件 900 匹配，旧插件 1/2 通过）； - // 仅当未来内核 ABI 破坏兼容时才提高该值。 - CABINumMin = 1 -) - -// ---- Dispatch Method IDs（与核心仓 internal/meta/meta.go 同步） ---- -const ( - CoreRegisterTool = 1 - CoreRegisterStage = 2 - CoreRegisterOutputCh = 3 - CoreRegisterPluginAPI = 4 - CoreInjectText = 5 - CoreInjectInterruptText = 6 - CoreInjectTextNoMemory = 7 - CoreSetAutoRestart = 8 - CoreMemoryRecall = 9 - CoreMemoryCommit = 10 - CoreMemoryIntrospect = 11 - CoreMemoryMerge = 12 - CoreMemoryPurge = 13 - CoreDocQuery = 14 - CoreKnowledgeSearch = 15 - CoreSettingsGet = 16 - CoreSettingsSet = 17 - CoreSettingsRegisterDef = 18 - CoreLLMListSources = 19 - CoreLLMSetSource = 20 - CoreSocialGetPerson = 21 - CoreSocialGetNetwork = 22 - CoreSubscribe = 23 - CoreUnsubscribe = 24 - CoreFreeString = 25 - CoreSettingsGetCore = 26 - CoreSettingsSetCore = 27 - CoreSettingsListCore = 28 - CoreSettingsGetPlugin = 29 - CoreSettingsSetPlugin = 30 - CoreSettingsListPlugin = 31 - CoreDocInsert = 32 - CoreDocRemove = 33 - CoreDocStats = 34 - CoreKnowledgeAdd = 35 - CoreKnowledgeList = 36 - CoreLLMCurrentSource = 37 - CoreSocialGetTrait = 38 - CoreSocialGetRelations = 39 - CoreSocialListPersons = 40 - CoreTextMemoryAppend = 41 - CoreSettingsList = 42 - CoreSettingsDefs = 43 - CoreSettingsDump = 44 - CoreSettingsPlugins = 45 - CoreRegisterInputCh = 46 - CoreInjectInputSync = 47 - CorePluginReloadOne = 48 - CorePluginListLoaded = 49 - CorePluginIsDisabled = 50 -) +// ---- 协议版本 ---- +// +// 子进程 RPC 的协议版本是一个独立的小整数，与 SDK/内核语义版本解耦： +// 语义版本变动频繁（修 bug、加字段），而 wire 协议只在**帧格式或握手语义** +// 变化时才升。当前值见核心仓 internal/plugin/proc/protocol.go 的 ProtocolVersion。 +// +// C ABI 时代的 ABIVersion / CABINum / 51 个 Core 整数 ID 已随 +// Part 6.2 删除 internal/plugin/cabi/ 一并退场： +// - 整数 method id 平移为 method 名字符串（proc/protocol.go 的 Method* 常量） +// - 版本协商改为握手帧里的 protocol 字段 +// +// 保留那些常量只会让人以为它们还在生效。 From 2a03a83ce0ad62a825255d33fa8a5becb8ee5b32 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 3 Sep 2026 08:12:30 +0800 Subject: [PATCH 24/27] =?UTF-8?q?docs:=20Part=206.6=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=94=B6=E5=B0=BE=20=E2=80=94=E2=80=94=20=E8=BF=81=E7=A7=BB?= =?UTF-8?q?=E8=AE=A1=E5=88=92/=E6=8E=A5=E5=8F=A3=E7=9F=A9=E9=98=B5/PLUGIN?= =?UTF-8?q?=5FDEV=20=E5=85=A8=E9=87=8F=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## plugin-migration-plan.md Part 6 标记完成，并**记录实际执行与计划的偏离**而非假装一致： 原计划「逐插件迁移，随时回退」。用户决策改为彻底舍弃 .so、无回退通道， 本轮直接删 internal/plugin/cabi/。因此【V】的「.so ↔ .bin 混跑集群冒烟」 不再适用——新内核根本不认 .so。改为验证「新内核面对旧 .so 给可操作错误 且不崩溃」，已在真实二进制上确认。 最终验收清单加「结果」列，13 项逐项对账。**两项未完全达标，如实标注**： - #9 SetToolBlocks：method 已定义并划入 CapCore，但内核侧仍返回未实现。 C ABI 时代它也是空实现（§1.4），故不是回归，但也没兑现 §3.8 的承诺。 - #13 内存：15 进程 RSS=88.0MB，远超「基线 +29MB」。根因是每插件静态链接 整个 Go runtime，15 个不同二进制无共同物理页（PSS/RSS 99.9% vs 基线 44%）。 实验 5 基线用的是 2.68MB 最小插件，绝对数字不可比；结构性指标 （均摊线程 5.5 vs 4.9）同量级。 新增两节实录：Part 6.5 生产切换（执行顺序为何不能反过来、hmap 正规通道 vs 手工拷贝的对照表、真实 QQ 消息的端到端证据链）与 Part 6.6 压测数据。 ## plugin-interface-matrix.md 状态从「基线 v1」升为「完成 v2」。三个合同面逐一标注达成情况： - 合同面 B：51 个整数 method id 已平移为 Method* 字符串常量。保留原表作 历史对照，但注明 case 25（CoreFreeString）无对应 method（内存管理是 C 层 特有问题），以及 io.setToolBlocks 已定义但内核侧未实现。 - 合同面 C：C1 标题从「今天」改为「迁移前」（迁移已完成，「今天」会误导）； C2 补上「全部插件共享同一块 memfd」这个关键决定及其理由——第一版设计 是每插件一段，那会退化成副本模型复现 lost update。 - 第六节「新获得的能力」加「实际结果」列。事件订阅标注机制已完成但 零用户使用，故未经真实负载检验——这比只写 ✅ 诚实。 「刻意不给」清单同步为带 API 后缀的新命名（SelftestAPI 等），与 capability.go 的 withheldCapabilities 对齐，并说明为何加后缀： 不加时子串匹配会把 tool.register / io.setToolBlocks 误判为泄漏 ToolAPI。 ## PLUGIN_DEV.md（中英双份） C ABI 时代的描述全部改掉： - 「动态 .so/.dll 插件」→「子进程插件」 - 「生成 C ABI bridge（z_bridge_gen.go + z_entry.c）」→ 子进程运行时三文件 - 「go build -buildmode=c-shared」→「go build（CGO_ENABLED=0）」 - 平台二进制表：三平台统一 plugin.bin（bundle 包内按 goos.goarch 区分） - 「不能跨 C ABI 边界序列化」→「不能跨进程序列化」 - 「ABI v2 写回」→「Stage 写回」 新增 v1.0.0 破坏性变更提示框，五条要点：.so 不再加载、业务代码不需改、 entry 字段对 Go 插件已无意义、不再需要 cgo、Windows 从 3 字段升到全字段。 保留 .so 字样的只有变更说明本身（3 处），其余全部清理。 --- assets/docs/en/PLUGIN_DEV.md | 48 ++++-- assets/docs/zh/PLUGIN_DEV.md | 40 +++-- docs/zh/plugin-interface-matrix.md | 132 ++++++++++++----- docs/zh/plugin-migration-plan.md | 226 +++++++++++++++++++++++++---- 4 files changed, 348 insertions(+), 98 deletions(-) diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md index 5da2c56..b4705b6 100644 --- a/assets/docs/en/PLUGIN_DEV.md +++ b/assets/docs/en/PLUGIN_DEV.md @@ -29,7 +29,7 @@ type Plugin interface { | Method | Use Case | Complexity | |--------|----------|------------| -| **Dynamic .so/.dll plugin (recommended)** | Independently distributed third-party plugins | Medium, generated using `plugindev` toolchain | +| **Subprocess plugin (recommended)** | Independently distributed third-party plugins | Medium, generated using `plugindev` toolchain | | **Built-in plugin** | Released with HomeAgent | Simple, requires merging into main repo | | **Lua script plugin** | Lightweight rapid prototyping | Simple, generated using `plugindev init --lua` | @@ -114,7 +114,7 @@ myplugin/ └── thirdpart/ — Optional external source code directory ``` -C ABI bridge files (`z_bridge_gen.go` + `z_entry.c`) are auto-generated at build time. +Subprocess runtime files (`z_proc_gen.go` and friends) are auto-generated at build time. **Lua plugin**: @@ -142,8 +142,8 @@ plugindev build --replace # append a go.mod replace directive (repeat Execution process: 1. Reads `plg.json` `targets`/`bundle` fields to determine build targets (bundle takes priority, see below) -2. Auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`; Windows only `z_bridge_gen.go`) -3. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` / `.dylib` / `.dll`) +2. Auto-generates subprocess runtime code (`z_proc_gen.go` + `z_proc_shm_unix.go` + `z_proc_shm_windows.go`) +3. **Go plugin**: Runs `go build` (a plain executable, `CGO_ENABLED=0`) 4. **Lua plugin**: Packages source code directly, no compilation needed (contents: `plugin.json` + `main.lua`, plus optional `README.md`, `LICENSE`, `thirdpart/*.lua`) 5. Generates `plugin.json` output manifest 6. Packages as `.hmap` distribution (zip format, containing `plugin.json` + binary) @@ -155,13 +155,28 @@ Execution process: | `plg.json` | Project metadata, maintained by developer | `targets` — single-target build list (e.g. `"linux/amd64,windows/amd64"`); `bundle` — multi-platform bundle switch (default `true`) | | `plugin.json` | Build artifact manifest, auto-generated | `entry` — entry filename; `platforms` — declared platforms | -Each target produces a separate `.hmap`; binary name by platform: +Each target produces a separate `.hmap`. Subprocess plugins are plain executables with +**no platform-specific extension**: | Platform | Binary | |----------|--------| -| Linux | `plugin.so` | -| macOS | `plugin.dylib` | -| Windows | `plugin.dll` | +| Linux / macOS / Windows | `plugin.bin` | + +Inside a bundle package the per-platform entries are named `plugin.bin..`; +the kernel picks the one matching the current platform and renames it to `plugin.bin`. + +> ⚠️ **v1.0.0 breaking change**: external plugins moved from C ABI shared libraries to +> **subprocess + shared memory**. +> +> - `plugin.so` / `plugin.dylib` / `plugin.dll` are **no longer loaded**. The new kernel +> skips legacy artifacts with an actionable error instead of crashing. +> - **Business code needs no changes** — the public SDK interface is unchanged; just +> rebuild with the new `plugindev`. +> - The `entry` field in `plg.json` is **meaningless for Go plugins** now (leaving +> `plugin.so` there is harmless); it only distinguishes Lua plugins. +> - Artifacts no longer need cgo, so cross-compiling requires no target C toolchain. +> - Windows went from "only 3 stage fields delivered, no writeback" to all 16 fields +> visible plus writeback, sharing the same RPC implementation as Unix. ### Build Targets & Multi-platform Bundle @@ -269,8 +284,11 @@ func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { } ``` -At build time, `plugindev build` auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`), -shared by both Windows DLL and Linux/macOS .so builds. No manual bridge code needed. +At build time, `plugindev build` auto-generates subprocess runtime code +(`z_proc_gen.go` for the platform-independent part, plus `z_proc_shm_unix.go` / +`z_proc_shm_windows.go`). All three platforms share the same entry point and the same +RPC logic; only the cross-process resource-passing mechanism differs (inherited fds on +Unix, named kernel objects on Windows). No manual bridge code needed. ### PluginSDK Core API @@ -322,7 +340,7 @@ Tool output → valuable for LLM attention? └── No → Normal memory, no extra handling ``` -> **Note**: `Cleaner` is a Go `func` type (`json:"-"`), cannot cross C ABI boundaries, so it is unavailable for C/C++/Rust remote plugins. **Lua plugins are not affected**: pass a Lua function in the def table (`cleaner = function(text) return text end`) — the Go bridge calls it back per invocation during memory computation. +> **Note**: `Cleaner` is a Go `func` type (`json:"-"`), cannot be serialized across process boundaries, so it is unavailable for C/C++/Rust remote plugins. **Lua plugins are not affected**: pass a Lua function in the def table (`cleaner = function(text) return text end`) — the Go bridge calls it back per invocation during memory computation. #### Stage Hooks — Intervene in message processing flow @@ -527,7 +545,7 @@ Lua plugins run inside the kernel process on a gopher-lua interpreter (single Lu - **Passive callback model**: `main.lua` executes only once at load time. Afterward, tools, stage hooks, output/input channels, and registered APIs are all invoked by the kernel via callbacks into Lua functions. Plugins cannot start background tasks on their own. - **No concurrency / no long-running services**: Lua has no goroutines, coroutine scheduling, `os`/`io` libraries, or socket listening. The only outbound capability is `sdk.http.get/post` (synchronous). Any blocking loop will stall every call of that plugin while holding the lock. -- **For long-running services (listening on a port, background polling, timers) use a Go plugin** (`.so`/`.dll` built with the toolchain, which may spawn goroutines — see the webui/cli plugins). The Lua equivalent is event-driven: register tools/stage hooks/channels to be called back by the kernel, or interact with external processes via `sdk.http`. +- **For long-running services (listening on a port, background polling, timers) use a Go plugin** (`plugin.bin` built with the toolchain, which may spawn goroutines — see the webui/cli plugins). The Lua equivalent is event-driven: register tools/stage hooks/channels to be called back by the kernel, or interact with external processes via `sdk.http`. ### Plugin Structure @@ -576,7 +594,7 @@ When running inside the kernel, `sdk.*` global variables are injected by the Go ### Lua SDK API -The `sdk.*` API of Lua plugins is fully aligned with external plugins (C ABI / toolchain-built `.so`/`.dll`): registration functions raise a Lua error on failure; data functions uniformly return `(result, err)` with `err == nil` on success. Subsystems not wired by the core (e.g. SocialAPI) return empty values instead of errors. +The `sdk.*` API of Lua plugins is fully aligned with external plugins (toolchain-built `plugin.bin` subprocesses): registration functions raise a Lua error on failure; data functions uniformly return `(result, err)` with `err == nil` on success. Subsystems not wired by the core (e.g. SocialAPI) return empty values instead of errors. **Registration** @@ -594,7 +612,7 @@ The `sdk.*` API of Lua plugins is fully aligned with external plugins (C ABI / t Stage handlers receive the full context (same as external plugins): `raw_message`, `user_id`, `group_id`, `phase`, `llm_text`, `final_text`, `no_memory`, `response` (when responded), `tool_calls`, `tool_results`. -**Stage writeback (ABI v2)**: the `ctx` table passed to the handler is a reference — mutating writable fields inside the handler syncs back to the core `StageContext` (aligned with the C ABI v2 external-plugin capability): +**Stage writeback**: the `ctx` table passed to the handler is a reference — mutating writable fields inside the handler syncs back to the core `StageContext` (aligned with subprocess external-plugin capability): ```lua sdk.register_stage("on_input", function(ctx) @@ -622,7 +640,7 @@ Writable fields: `raw_message`, `llm_text`, `final_text`, `user_id`, `group_id`, | `sdk.inject_interrupt(source, channel, text)` | Interrupt delivery | | `sdk.inject_text_no_memory(source, channel, text)` | Deliver without memory computation | -**Data APIs (aligned with C ABI, all return `(result, err)`)** +**Data APIs (aligned with subprocess external plugins, all return `(result, err)`)** | Sub-table | Functions | |-----------|-----------| diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md index 2b56859..2e947e0 100644 --- a/assets/docs/zh/PLUGIN_DEV.md +++ b/assets/docs/zh/PLUGIN_DEV.md @@ -30,7 +30,7 @@ type Plugin interface { | 方式 | 适用场景 | 复杂度 | |------|---------|--------| -| **动态 .so/.dll 插件（推荐）** | 独立分发的第三方插件 | 中等，使用 `plugindev` 工具链生成 | +| **子进程插件（推荐）** | 独立分发的第三方插件 | 中等，使用 `plugindev` 工具链生成 | | **内置插件** | 随 HomeAgent 一起发布 | 简单，需合入主仓库 | | **Lua 脚本插件** | 轻量快速原型 | 简单，使用 `plugindev init --lua` 生成 | @@ -115,7 +115,7 @@ myplugin/ └── thirdpart/ — 外部源码存放目录（可选） ``` -编译时自动生成 C ABI bridge 文件（`z_bridge_gen.go` + `z_entry.c`），无需手动创建。 +编译时自动生成子进程运行时文件（`z_proc_gen.go` 等），无需手动创建。 **Lua 插件**： @@ -143,8 +143,8 @@ plugindev build --replace # 追加 go.mod replace 指令（可多次 执行过程： 1. 读取 `plg.json` 的 `targets`/`bundle` 字段确定构建目标（bundle 模式优先，见下节） -2. 自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`，Windows 仅 `z_bridge_gen.go`） -3. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` / `.dylib` / `.dll`） +2. 自动生成子进程运行时代码（`z_proc_gen.go` + `z_proc_shm_unix.go` + `z_proc_shm_windows.go`） +3. **Go 插件**：执行 `go build`（普通可执行文件，`CGO_ENABLED=0`） 4. **Lua 插件**：直接打包源码，无需编译（打包内容：`plugin.json` + `main.lua`，以及可选的 `README.md`、`LICENSE`、`thirdpart/*.lua`） 5. 生成 `plugin.json` 输出清单 6. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + 二进制） @@ -156,13 +156,25 @@ plugindev build --replace # 追加 go.mod replace 指令（可多次 | `plg.json` | 项目元信息，由开发者维护 | `targets` — 单平台构建目标（如 `"linux/amd64,windows/amd64"`）；`bundle` — 多平台合集开关（默认 `true`）| | `plugin.json` | 构建产物清单，`plugindev build` 自动生成 | `entry` — 入口文件名；`platforms` — 声明的支持平台 | -每个目标生成单独的 `.hmap`，二进制文件名由平台决定： +每个目标生成单独的 `.hmap`。子进程插件是普通可执行文件，**不分平台后缀**： | 平台 | 二进制 | |------|--------| -| Linux | `plugin.so` | -| macOS | `plugin.dylib` | -| Windows | `plugin.dll` | +| Linux / macOS / Windows | `plugin.bin` | + +bundle 包内按 `plugin.bin..` 区分各平台，安装时内核挑当前平台 +那份重命名为 `plugin.bin`。 + +> ⚠️ **v1.0.0 破坏性变更**：外部插件从 C ABI 动态库改为**子进程 + 共享内存**。 +> +> - `plugin.so` / `plugin.dylib` / `plugin.dll` **不再被加载**。新内核遇到旧产物 +> 会跳过并报可操作错误，不崩溃。 +> - **业务代码不需要改一行**——公开 SDK 接口零改动，只需用新版 `plugindev` 重编。 +> - `plg.json` 的 `entry` 字段对 Go 插件**已无意义**（写着 `plugin.so` 也无妨）， +> 它现在只用于区分 Lua 插件。 +> - 产物不再需要 cgo，交叉编译无需目标平台 C 工具链。 +> - Windows 从「只下发 3 个 stage 字段、无写回」升级到 16 字段全可见 + 写回， +> 与 Unix 共用同一套 RPC 实现。 ### 构建目标与多平台打包（bundle） @@ -269,7 +281,7 @@ func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { } ``` -编译时 `plugindev build` 根据目标平台自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`），无需手动编写。Windows DLL 和 Linux/macOS .so 共享同一入口。 +编译时 `plugindev build` 自动生成子进程运行时代码（`z_proc_gen.go` 平台无关 + `z_proc_shm_unix.go` / `z_proc_shm_windows.go` 平台特定），无需手动编写。三平台共享同一入口与同一套 RPC 逻辑，仅跨进程资源传递机制不同（Unix 继承 fd，Windows 命名内核对象）。 ### PluginSDK 核心 API @@ -321,7 +333,7 @@ s.RegisterTool("weather_query", sdk.ToolDef{ └── 否 → 正常记忆，无需额外处理 ``` -> **注意**：`Cleaner` 是 Go `func` 类型（`json:"-"`），不能跨 C ABI 边界序列化，因此 C/C++/Rust 等远程插件无法使用。**Lua 插件不受此限**：def 表中直接传 Lua 函数即可（`cleaner = function(text) return text end`），Go 桥接层会在计算层调用时逐次回调 Lua。 +> **注意**：`Cleaner` 是 Go `func` 类型（`json:"-"`），不能跨进程序列化，因此 C/C++/Rust 等远程插件无法使用。**Lua 插件不受此限**：def 表中直接传 Lua 函数即可（`cleaner = function(text) return text end`），Go 桥接层会在计算层调用时逐次回调 Lua。 #### 阶段钩子 — 干预消息处理流 @@ -526,7 +538,7 @@ Lua 插件运行在内核进程内的 gopher-lua 解释器中（单 Lua 状态 + - **被动回调模型**：`main.lua` 仅在加载时执行一次，此后插件的工具、阶段钩子、输出/输入通道、注册 API 全部由内核事件驱动回调 Lua 函数；插件不能自己启动后台任务。 - **无并发/无常驻服务能力**：Lua 侧没有 goroutine、协程调度、`os`/`io` 库和 socket 监听能力，唯一主动出站通道是 `sdk.http.get/post`（同步请求）。任何阻塞循环都会持锁卡死该插件的所有调用。 -- **常驻服务（如监听端口、后台轮询、定时任务）请使用 Go 插件**（工具链编译的 `.so`/`.dll`，可自行启动 goroutine，参见 webui/cli 插件）。Lua 插件的等价做法是事件驱动：注册工具/阶段钩子/通道由内核回调，或经 `sdk.http` 与外部进程交互。 +- **常驻服务（如监听端口、后台轮询、定时任务）请使用 Go 插件**（工具链编译的 `plugin.bin`，可自行启动 goroutine，参见 webui/cli 插件）。Lua 插件的等价做法是事件驱动：注册工具/阶段钩子/通道由内核回调，或经 `sdk.http` 与外部进程交互。 ### 插件结构 @@ -575,7 +587,7 @@ lua main.lua ### Lua SDK API -Lua 插件的 `sdk.*` API 与外部插件（C ABI / 工具链编译的 `.so`/`.dll`）能力完全对齐：注册类函数调用即时报错（抛 Lua error），数据类函数统一返回 `(result, err)`，`err` 为 nil 表示成功。核心未装配的子系统（如 SocialAPI）返回空值而非报错。 +Lua 插件的 `sdk.*` API 与外部插件（工具链编译的 `plugin.bin` 子进程）能力完全对齐：注册类函数调用即时报错（抛 Lua error），数据类函数统一返回 `(result, err)`，`err` 为 nil 表示成功。核心未装配的子系统（如 SocialAPI）返回空值而非报错。 **注册类** @@ -593,7 +605,7 @@ Lua 插件的 `sdk.*` API 与外部插件（C ABI / 工具链编译的 `.so`/`.d `register_stage` 的 handler 收到完整上下文（与外部插件一致）：`raw_message`、`user_id`、`group_id`、`phase`、`llm_text`、`final_text`、`no_memory`、`response`（已响应时）、`tool_calls`、`tool_results`。 -**Stage 写回（ABI v2）**：handler 收到的 `ctx` 是引用 table——在 handler 内直接修改可写回字段并同步至内核 `StageContext`（与 C ABI v2 外部插件能力对齐）： +**Stage 写回**：handler 收到的 `ctx` 是引用 table——在 handler 内直接修改可写回字段并同步至内核 `StageContext`（与子进程外部插件能力对齐）： ```lua sdk.register_stage("on_input", function(ctx) @@ -621,7 +633,7 @@ end) | `sdk.inject_interrupt(source, channel, text)` | 中断投递 | | `sdk.inject_text_no_memory(source, channel, text)` | 免记忆投递 | -**数据类（与 C ABI 对齐，均返回 `(result, err)`）** +**数据类（与子进程外部插件对齐，均返回 `(result, err)`）** | 子表 | 函数 | |------|------| diff --git a/docs/zh/plugin-interface-matrix.md b/docs/zh/plugin-interface-matrix.md index 7ef44f7..e771b94 100644 --- a/docs/zh/plugin-interface-matrix.md +++ b/docs/zh/plugin-interface-matrix.md @@ -1,11 +1,14 @@ # 外部插件接口不变矩阵（多进程化整改基线） -> 状态：**基线 v1**（2026-08-31，update 分支） +> 状态：**完成 v2**（2026-09-03）——迁移已落地并上生产，内核 v1.0.0。 > 目的：钉死「暴露给外部插件的接口不变」这一约束的**合同面**——迁移前、迁移后外部插件看到/调用的 SDK 接口完全一致； > 所有改造落在**核心（homed 侧）+ 工具链（plugindev）**，外部插件业务代码零改动，只需用新 plugindev 重编。 > -> 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或 bridge 模板 `tools/plugindev/templates.go` 后， -> 必须同步更新本矩阵；`11.1~11.6` 任一落地后，在对应行标注「已修复」。 +> **结果（已验证）**：`git diff third_party/homeagent-sdk/sdk/` 全程为空；17 个 `example/*/plugin.go` 逐字节未改 +> （`git status example/` 无输出）；生产 17 插件全部经子进程通道运行。 +> +> 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或模板 `tools/plugindev/templates/` 后， +> 必须同步更新本矩阵。 > > 权威编号：plan.md 第 11 节（11.1~11.9）。本文档只做接口面盘点，不做实现。 @@ -111,9 +114,14 @@ type Plugin interface { ## 三、合同面 B：bridge 51 个 method id ↔ SDK 方法映射（改造基线） -> 文件：`third_party/homeagent-sdk/tools/plugindev/templates.go` 的 `tmplLinuxBridge`。 -> 迁移后这些整数 method id **改为 RPC method 名**（迁移评估 3.2），语义不变、编号扔掉。 -> 下表是「51 个 case 平移为 method 名」的完整清单，也是新 RPC 协议的一等公民。 +> ⏹️ **已完成（2026-09-03）**：整数 method id 已全部平移为 RPC method 名字符串， +> 定义在 `internal/plugin/proc/protocol.go` 的 `Method*` 常量（共 60 个，含内核→插件方向）。 +> 原 `tmplLinuxBridge` 与 `meta.Core` 整数表**均已删除**。 +> +> 两个遗留点：`case 25`（`CoreFreeString`）无对应 method（内存管理是 C 层特有问题）； +> `io.setToolBlocks` 已定义但内核侧仍返回未实现（C ABI 时代也是空实现，非回归）。 +> +> 下表保留作为历史对照。 | # | method id（今天 C ABI） | SDK 背的方法 | 迁移后 RPC method 名（建议） | |---|---|---|---| @@ -182,7 +190,11 @@ type Plugin interface { ## 四、合同面 C：StageContext 跨 ABI 现状 → 共享内存目标 -### C1. 今天（C ABI 副本模型）：插件只看到 10 个字段 +> ✅ **已达成（2026-09-03）**：子进程插件现在看到全部 18 个字段（枚举见 +> `internal/plugin/proc/shm.go`），且可写回。生产实测：sanitizer 在另一个进程里 +> 改写 13590 字节文本，内核读到改写结果（`stage post_action 改写了 1 个字段`）。 + +### C1. 迁移前（C ABI 副本模型）：插件只看到 10 个字段 `stageContextWritable`（templates.go:762）下发/回传的字段： @@ -193,18 +205,31 @@ raw_message user_id group_id phase llm_text final_text no_memory **看不到的 6 个字段**：`ContextMsgs` / `ReasoningContent` / `TokenUsage` / `Memory` / `Extra` / `Errors` -### C2. 迁移后（共享内存 + 锁仲裁）：插件可看到/改写全部 16 个字段 +### C2. 迁移后（共享内存 + 锁仲裁）：插件可看到/改写全部字段 — ✅ 已实现 -`ShmStageCtx`（迁移评估 3.3）· 插件进程内保留原生 `StageContext`，handler 照常读写， -`Lock/RLock` 映射到跨进程锁仲裁 RPC（`stage.lock`/`stage.unlock`），handler 返回时脏字段写回共享段。 +字段级 `Slice{Off,Len}` 描述符 + 内核仲裁锁。插件进程内保留原生 `StageContext`， +handler 照常读写，`Lock/RLock` 映射到跨进程锁仲裁 RPC（`stage.lock`/`stage.unlock`）， +handler 返回时脏字段写回共享段。 -→ **接口形式不变，能力变强**（这是「能力断层消除」合同面的一部分：外部插件拿回 ContextMsgs 等）。 +**关键设计决定**：全部子进程插件共享**同一块 memfd**。第一版设计是每插件一段， +那会退化成副本模型，复现 §8.4 的 35.8~36.8% lost update。 -### C3. 11.3 修复的合同面定义（lost update） +→ **接口形式不变，能力变强**（能力断层消除：外部插件拿回 ContextMsgs 等）。 -今天 `stageContextWritable` **无条件回传 10 个字段的当前快照**——两个插件（sanitizer 改 ToolResults + -weather 只读）并行时，weather 的回传会覆盖 sanitizer 的清洗结果（实测 1.6~4.3%）。 -迁移后共享内存模型天然解决（并发改写同一对象）；迁移前需 `stageContextWritable` 只回传**真正变更**的字段。 +Windows 同步受益：从「只下发 3 字段、无写回」升到全字段可见 + 写回， +与 Unix 共用同一套 RPC 实现与共享段布局。 + +### C3. lost update 的合同面定义 — ✅ 已消除 + +C ABI 时代 `stageContextWritable` **无条件回传 10 个字段的当前快照**——两个插件 +（sanitizer 改 ToolResults + weather 只读）并行时，weather 的回传会覆盖 sanitizer +的清洗结果（实测 1.6~4.3%，高并发下 35.8~36.8%）。 + +Part 0.2 先做了过渡补丁（只回传真正变更的字段）；Part 4 的共享内存模型从根上解决 +（字段级描述符 + 锁仲裁，并发改写同一对象）。 + +回归基线：`TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate`、 +`TestSegment_ProductionScenario_SanitizerNotOverwrittenByWeather`。 --- @@ -224,36 +249,69 @@ weather 只读）并行时，weather 的回传会覆盖 sanitizer 的清洗结 ## 六、迁移后外部插件「新获得」的能力（合同面扩展——只增不减） -| 能力 | 今天 | 迁移后 | -|---|---|---| -| 事件订阅 `Events().Subscribe`（case 23/24） | ❌ 空实现 | ✅ 事件环（EvtRing + eventfd + 独立游标） | -| `SetToolBlocks` 多模态注入 | ❌ 空实现 | ✅ 二进制落 arena，Slice 描述符回传 | -| `ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` | ❌ 看不到 | ✅ 共享内存全字段 | -| 插件崩溃隔离 | ❌ panic 带崩 homed | ✅ 子进程独立崩溃 | -| 热重载 `.so` | ❌ `DF_1_NODELETE` no-op | ✅ 同路径替换 `.bin` 即生效 | -| 工具超时取消 | ❌ cgo 不可中断（泄漏线程） | ✅ `Process.Kill()` 真取消 | -| `output_send` 结果 | ❌ 永远假成功 | ✅ 可同步等真实结果 | -| Lua/Windows DLL 路径 | ❌ 三套 ABI 分裂 | ✅ 收敛为单一 RPC 实现 | +| 能力 | 迁移前 | 迁移后 | 实际结果 | +|---|---|---|---| +| 事件订阅 `Events().Subscribe`（case 23/24） | ❌ 空实现 | ✅ 事件环（EvtRing + eventfd + 独立游标） | ✅ 已接线（当前零用户） | +| `SetToolBlocks` 多模态注入 | ❌ 空实现 | ✅ 二进制落 arena，Slice 描述符回传 | ⚠️ method 已定义，内核侧仍未实现 | +| `ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` | ❌ 看不到 | ✅ 共享内存全字段 | ✅ 18 字段全可见可写 | +| 插件崩溃隔离 | ❌ panic 带崩 homed | ✅ 子进程独立崩溃 | ✅ 测试 + 生产验证 | +| 热重载 `.so` | ❌ `DF_1_NODELETE` no-op | ✅ 同路径替换 `.bin` 即生效 | ✅ 生产实测 | +| 工具超时取消 | ❌ cgo 不可中断（泄漏线程） | ✅ `Process.Kill()` 真取消 | ✅ 整套新架构零 cgo | +| `output_send` 结果 | ❌ 永远假成功 | ✅ 可同步等真实结果 | ✅ 生产实测 `map[status:sent]` | +| Lua/Windows DLL 路径 | ❌ 三套 ABI 分裂 | ✅ 收敛为单一 RPC 实现 | ⚠️ Windows 已收敛；Lua 仍独立（留待后续） | -**刻意不给**（权限梯度显式化，非技术限制）：`Selftest`/`Supervisor`/`Tracker`/`Status`/`Adapter`/`Config`/`Tool`/`Indexer`/`OutputChan`/`Publish`（内核内部机制）。 +**三项未完全兼得的说明**： + +- `SetToolBlocks`：`io.setToolBlocks` 已在 protocol 定义并划入 `CapCore`，但内核侧 handler + 仍返回未实现。C ABI 时代它也是空实现（§1.4），故**不是回归**，但也没兑现承诺。 +- Lua：`lua_plugin.go`/`dynamic_lua.go` 仍走自己的路径。Lua 经解释器不经 C ABI， + 不属于本轮要消除的 6 类缺陷，因此不阻塞。收敛第三套 ABI 是独立优化。 +- 事件订阅：机制已完成（内核侧 `EvtRing` + 模板侧 `evtConsumerLoop`）， + 但**无任何现有插件使用 `Events().Subscribe`**，所以生产上未经真实负载检验。 + +**刻意不给**（权限梯度显式化，非技术限制）：`SelftestAPI`/`SupervisorAPI`/`TrackerAPI`/ +`StatusAPI`/`AdapterAPI`/`ConfigAPI`/`ToolAPI`/`IndexerAPI`/`OutputChanRaw`/`EventPublish` +（内核内部机制）。清单与理由记在 `internal/plugin/proc/capability.go` 的 +`withheldCapabilities`，`TestCapability_WithheldListIsDocumented` 守护。 + +这一项从「C ABI 表达能力的意外产物」变成**显式策略**：以前拿不到是因为 +C 结构体不好传函数指针（那是运气，任何人给 dispatch 加个 case 就能捅穿）； +现在是三道闸：类型层（`procCore` 命名字段不嵌入）+ 能力集（manifest 声明） ++ RPC 边界（返回明确错误而非静默忽略）。 --- -## 七、整改推进时的接口冻结检查点 +## 七、接口冻结检查点（全部已通过） -1. **阶段 2（子进程通道原型）完成时**：`plugindev` 用 `tmplProcMain` 重编 weather → `weather.bin` → 端到端跑通。 - 验收：weather 业务代码与 `build/` 目录下旧 `.so` 时代的 `plugin.go` **逐字节可对比**（唯一改动是被工具链改写，非手工）。 -2. **阶段 3（共享内存）完成时**：任意改写型插件（sanitizer/weather 并发）在子进程下并发改写 StageContext， - 丢失率 = 0%（对比今天 35.8~36.8%）。 -3. **阶段 5 完成时**：17 个外部插件全部 `.bin` 化、cabi 删除；执行一遍全量 `go build ./...` + example 编译。 -4. **任何时候**：`git diff` 公开 SDK `sdk/` 目录为零（接口冻结的硬证据）。 +1. ✅ **阶段 2（子进程通道原型）**：`plugindev` 重编 weather → `plugin.bin` → 端到端跑通。 + 验收：weather 业务代码逐字节未改（`git status example/` 无输出）。 +2. ✅ **阶段 3（共享内存）**：子进程并发改写 StageContext 丢失率 = 0% + （`TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate` 与 + `TestSegment_ProductionScenario_SanitizerNotOverwrittenByWeather`）。 +3. ✅ **阶段 5**：17 个外部插件全部 `.bin` 化、cabi 删除（-3198 行）； + `go build ./...` 与全仓 `go test ./...` 均通过。 +4. ✅ **全程**：`git diff third_party/homeagent-sdk/sdk/` 为零——接口冻结的硬证据。 + +生产端到端（2026-09-03，真实 QQ 消息）： + +``` +input from qq → response (83293ms, tools=[qq_get_message qq_get_history + output_send__qq output_send__qq qq_mark_read]) +[sanitizer] cleaned 2 bytes (before=13590 after=13588) +[proc] sanitizer stage post_action 改写了 1 个字段 +tool output_send__qq result: 已通过 [qq] 通道发送: map[status:sent] +``` --- ## 八、关联文档 -- `docs/zh/架构迁移评估.md` — 完整论证（§3.2 method id 平移、§3.3 数据面、§3.4 SDK 封装、§3.5 回调型资源） +- `docs/zh/架构迁移评估.md` — 完整论证（§3.2 method id 平移、§3.3 数据面、§3.4 SDK 封装、§3.5 回调型资源、§3.8 能力对齐） +- `docs/zh/plugin-migration-plan.md` — Part 0~6 执行计划与完成实录（含 Part 6.5 生产切换、Part 6.6 压测） - `plan.md` §11 — 11.1~11.9 修复清单（唯一权威编号） -- `third_party/homeagent-sdk/sdk/` — 合同面 A 的代码实现 -- `third_party/homeagent-sdk/tools/plugindev/templates.go` — bridge 模板（合同面 B 的代码实现） -- `docs/zh/experiments/plugin-arch/` — 18 项可行性实验（跨进程并发改写零丢失等数字来源） \ No newline at end of file +- `third_party/homeagent-sdk/sdk/` — 合同面 A 的代码实现（全程零 diff） +- `internal/plugin/proc/protocol.go` — 合同面 B 的代码实现（`Method*` 常量，取代已删的 bridge 模板） +- `internal/plugin/proc/shm.go` — 合同面 C 的代码实现（共享段布局与 18 字段枚举） +- `internal/plugin/proc/capability.go` — 权限梯度（capability 组 + `withheldCapabilities`） +- `third_party/homeagent-sdk/tools/plugindev/templates/` — 子进程运行时模板（三文件） +- `docs/zh/experiments/plugin-arch/` — 18 项可行性实验 + `19-migration-verify/` 迁移执行期工具 \ No newline at end of file diff --git a/docs/zh/plugin-migration-plan.md b/docs/zh/plugin-migration-plan.md index 362837d..6c318fd 100644 --- a/docs/zh/plugin-migration-plan.md +++ b/docs/zh/plugin-migration-plan.md @@ -404,54 +404,72 @@ $ git diff third_party/homeagent-sdk/sdk/ --- -## Part 6：迁移与收尾（阶段 5.1~5.4，~2 周） +## Part 6：迁移与收尾（阶段 5.1~5.4，~2 周）— ✅ **已完成**（2026-09-03） -> 依据：迁移评估 §4.5 双通道共存、§5 权限梯度。逐插件迁移，随时回退。 +> 依据：迁移评估 §4.5 双通道共存、§5 权限梯度。 +> +> ⚠️ **实际执行偏离计划的一处**：原计划「逐插件迁移，随时回退」。 +> 用户决策改为**彻底舍弃 `.so` 能力，无回退通道**（不做 `--cabi` 开关）， +> 本轮直接删 `internal/plugin/cabi/`，生产全量切换。代价是某插件出问题 +> 只能紧急修复或 `git revert` 整批。因此下方【V】的「`.so` ↔ `.bin` 混跑」 +> 不再适用——新内核根本不认 `.so`。 ### 修改 -- 【M】17 个外部插件逐个用新 plugindev 重编为 `.bin`（`plugin_install(overwrite=true)`），每个回归验证。 -- 【M】`plugins/` 目录逐个把 `entry` 从 `plugin.so` 改为 `plugin.bin`。 -- 【M】删除 `internal/plugin/cabi/`（1096 行）+ bridge 模板 `tmplLinuxBridge`/`tmplBridge`（385 行）+ `dynamic_dll_*`/`dynamic_loader_windows.go`。 -- 【M】权限梯度显式化：manifest 声明 caps + 内核侧白名单（`Selftest`/`Supervisor`/`Tracker`/`Status`/`Adapter`/`Config`/`Tool`/`Indexer`/`OutputChan`/`Publish` 确认不给）。 -- 【M】`lua_plugin.go`/`dynamic_lua.go`：统一走 RPC（收敛三套 ABI 为单一 RPC）。 -- 【M】文档：`PLUGIN_DEV.md` 更新、迁移说明。 +- ✅【M】**6.1** 工具链 entry 语义收敛（SDK 仓 `9f84412`）：`isProcEntry` 删除，Go 插件一律产出 `plugin.bin` 不看 entry 值；`templates.go` 1296→516 行。 +- ✅【M】**6.3** 17 插件全量重编（`1d7f011`）：16 个×3 平台 + qq×1；`git status example/` 无输出（业务代码零改动）。 +- ✅【M】**6.5** 生产切换（`62bdfa2`）：经 `pluginmgr` 的 hmap 正规通道安装，17/17 成功且 `config_kept=true`。 +- ✅【M】**6.6** 压测 + 版本 1.0.0 + 文档（`2572688`、`670efcd`、tag `v1.0.0`）。 +- ✅【M】**6.2** 内核侧 Windows（`d027c96`）+ 删 C ABI（`b20121f`，-3198 行）：删 `internal/plugin/cabi/`(1156)、`dynamic_dll_windows.go`(272)、`dynamic_loader_unix.go`(79) + bridge 模板；新增 `shmalloc_windows.go` + `evtfd_windows.go` + `shmpass_{unix,windows}.go`；顺带修 macOS pipe 写端被 GC 回收的真 bug。 +- ✅【M】**6.4** 权限梯度显式化（`2ebdb9a`）：54 个 method 划入 11 个 capability 组；`coreHandler.Handle` 入口强制；`withheldCapabilities` 表记录 10 项刻意不提供的内核机制及理由（`SelftestAPI`/`SupervisorAPI`/`TrackerAPI`/`StatusAPI`/`AdapterAPI`/`ConfigAPI`/`ToolAPI`/`IndexerAPI`/`OutputChanRaw`/`EventPublish`）。 +- ⏭️【M】`lua_plugin.go`/`dynamic_lua.go` 统一走 RPC —— **留待后续**。Lua 走解释器不经 C ABI，不阻塞本轮目标（消除 C ABI 前提缺陷）。收敛第三套 ABI 是独立优化。 +- ✅【M】文档：本文与 `plugin-interface-matrix.md` 更新；切换实录见下方。 ### 审查 -- 【R】每删一个 cabi 依赖项，`go build ./...` + `go vet ./...` 干净。 -- 【R】权限梯度：外部插件无权访问的 API 在 RPC 边界被**拒绝**（非忽略）。 -- 【R】接口冻结：`sdk/` 零 diff。 +- ✅【R】每删一个 cabi 依赖项，`go build ./...` + `go vet ./...` 干净。 +- ✅【R】权限梯度：被拒 API 在 RPC 边界返回**明确错误**（非忽略）。错误消息含四要素：哪个插件、哪个调用、缺什么能力、在哪声明。`TestCapability_DeniedErrorIsActionable` 守护。 +- ✅【R】接口冻结：`git diff third_party/homeagent-sdk/sdk/` 全程为空。 ### 验证（全量回归） -- 【V】17 插件每个 `.bin` 独立回归（工具/设置/通道/阶段）。 -- 【V】`.so` ↔ `.bin` 混跑集群冒烟（Part 1 分派 + 双通道共存）。 -- 【V】`make test` 全量绿 + `go build ./...`。 -- 【V】内存/RSS 对比：迁移后常驻 ≤ 基线 +29MB（实验 5 量级）。 -- 【V】工具调用 RPC 延迟 p50 ≤ 20µs 量级（实验 11）。 +- ✅【V】17 插件经 `plugin_install(overwrite=true)` 加载，工具/设置/通道/阶段 e2e。 +- ⏭️【V】~~`.so` ↔ `.bin` 混跑集群冒烟~~ —— 不适用（无回退通道，见上方偏离说明）。改为验证**新内核面对旧 `.so` 给可操作错误且不崩溃**，已在真实二进制上确认。 +- ✅【V】`make test` 全量绿 + `go build ./...`。 +- ⚠️【V】内存：**未达成计划目标**。15 个插件进程 RSS=88.0MB / PSS=87.9MB，远超「基线 +29MB」。根因是每插件静态链接整个 Go runtime，15 个不同二进制无共同物理页可映射（PSS/RSS 99.9% vs 基线 44%）。这是「每插件独立二进制」的固有代价，实际开销高于 §4.3 乐观估计。压缩方向：共享 launcher 二进制 + 各自业务模块。 +- ✅【V】工具调用 RPC 延迟 24.1µs（实验 11 基线 19.6µs，同量级）。 -**Part 6 出口条件**：全部外部插件 `.bin` 化，cabi 删除，接口零改动，权限显式化，无回归。 +**Part 6 出口条件**：全部外部插件 `.bin` 化 ✅，cabi 删除 ✅，接口零改动 ✅，权限显式化 ✅，无回归 ✅。 --- ## 最终验收清单（对照接口不变矩阵 §7 检查点） -| # | 检查点 | 通过标准 | -|---|---|---| -| 1 | 公开 SDK 接口冻结 | `git diff third_party/homeagent-sdk/sdk/` **为空**（全程） | -| 2 | 外部插件业务代码零改动 | 17 个 `example/*/plugin.go` 与基线逐字节可比 | -| 3 | 17 插件 `.bin` 化 | 全部经 `plugin_install` 加载，工具/设置/通道/阶段 e2e | -| 4 | cabi 删除 | `internal/plugin/cabi/` 与 bridge 模板不存在 | -| 5 | 崩溃隔离 | 插件 kill 只退出自身，homed 存活 | -| 6 | 热重载 | 同路径换 `.bin` 即生效，无需重启 | -| 7 | 并发改写 | 跨进程 stage 丢失率 0%（对照今天 35.8~36.8%） | -| 8 | 事件订阅 | 外部插件 `Events().Subscribe` 可用 | -| 9 | 多模态 | `SetToolBlocks` 非空实现 | -| 10 | 超时取消 | 工具超时可 `Process.Kill()`，零泄漏 | -| 11 | output_send | 真实结果返回（非假成功） | -| 12 | 权限梯度 | 内部专属 API 在 RPC 边界拒绝 | -| 13 | 内存/延迟 | 常驻 +≤29MB，RPC p50 ≤20µs 量级 | +| # | 检查点 | 通过标准 | 结果 | +|---|---|---|---| +| 1 | 公开 SDK 接口冻结 | `git diff third_party/homeagent-sdk/sdk/` **为空**（全程） | ✅ 每次审查均确认 | +| 2 | 外部插件业务代码零改动 | 17 个 `example/*/plugin.go` 与基线逐字节可比 | ✅ `git status example/` 无输出 | +| 3 | 17 插件 `.bin` 化 | 全部经 `plugin_install` 加载，工具/设置/通道/阶段 e2e | ✅ 17/17，`config_kept=true` | +| 4 | cabi 删除 | `internal/plugin/cabi/` 与 bridge 模板不存在 | ✅ -3198 行（`b20121f`） | +| 5 | 崩溃隔离 | 插件 kill 只退出自身，homed 存活 | ✅ `TestRealPlugin_CrashDoesNotKillKernel` | +| 6 | 热重载 | 同路径换 `.bin` 即生效，无需重启 | ✅ 生产实测（`unloaded (config kept)` → 重载） | +| 7 | 并发改写 | 跨进程 stage 丢失率 0%（对照今天 35.8~36.8%） | ✅ `TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate` | +| 8 | 事件订阅 | 外部插件 `Events().Subscribe` 可用 | ✅ 事件环已接线（当前零用户） | +| 9 | 多模态 | `SetToolBlocks` 非空实现 | ⚠️ method 已定义并划入 core 能力，内核侧仍返回未实现 | +| 10 | 超时取消 | 工具超时可 `Process.Kill()`，零泄漏 | ✅ 整套新架构零 cgo | +| 11 | output_send | 真实结果返回（非假成功） | ✅ 生产实测 `map[status:sent]` | +| 12 | 权限梯度 | 内部专属 API 在 RPC 边界拒绝 | ✅ 12 项测试（`2ebdb9a`） | +| 13 | 内存/延迟 | 常驻 +≤29MB，RPC p50 ≤20µs 量级 | ⚠️ 延迟 24.1µs 达标；内存 88MB **未达标** | + +**两项未完全达标的说明**： + +- **#9 SetToolBlocks**：`io.setToolBlocks` 已在 protocol 定义并划入 `CapCore`， + 但内核侧 handler 仍返回未实现。C ABI 时代它也是空实现（§1.4）， + 故**不是回归**，但也没兑现 §3.8 的承诺。当前无插件使用。 +- **#13 内存**：15 个进程 RSS=88.0MB，远超「基线 +29MB」。根因是每插件 + 静态链接整个 Go runtime，15 个不同二进制无共同物理页（PSS/RSS 99.9% + vs 基线 44%）。实验 5 的基线用的是 2.68MB 最小插件，而真实插件 3.1~14.8MB， + 绝对数字不可比。结构性指标（均摊线程 5.5 vs 4.9）同量级。 --- @@ -468,3 +486,147 @@ $ git diff third_party/homeagent-sdk/sdk/ --- *规划：2026-08-31，update 分支。Part 编号与其依赖的 plan.md/迁移评估阶段对应。* + +--- + +## Part 6.5 生产切换实录（2026-09-03） + +### 执行顺序（先换二进制，再装包） + +``` +1. systemctl stop homeagent +2. 换 /usr/local/bin/homed +3. 起服务 —— 15 个 .so 插件报可操作错误被跳过，homed 与 16 个内置正常 +4. 逐个 POST 装 17 个 hmap（overwrite=true） +5. 重启核对 +``` + +**为何不能反过来**：若先装包，旧 homed 的 `StopAndUnload` 会停掉 qq +消息通道，而它又无法加载 `.bin`，会卡在「插件全挂」的状态。 + +第 3 步顺带在真实二进制上验证了 Part 6.2 的可操作错误： + +``` +[plugin] dynamic weather: plugin weather: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。 +外部插件已改为子进程模式，请用新版 plugindev 重编产出 plugin.bin（业务代码无需修改） +``` + +不崩溃，只跳过该插件。 + +### 走 hmap 正规通道，而非手工拷贝 + +第一版切换脚本是手工拷 `plugin.bin` + 手改 `plugin.json` 的 entry —— +那等于**重新实现了一遍 hmap 解包逻辑，且实现得更差**。漏掉的东西： + +| | 手工拷贝 | hmap 正规通道 | +|---|---|---| +| `platforms` 字段 | 漏了 | 包内 manifest 本来就写对 | +| 平台二进制选择 | 硬编码 `_linux_amd64` | `platformBinary()` 按 runtime 选 | +| `overwrite` 语义 | 无 | `StopAndUnload` **保留配置表** | +| 失败回滚 | 无 | `os.Rename` 备份，解包失败自动恢复 | +| 校验 | 只查文件存在 | `validatePackage` 查 manifest + 各平台二进制齐全 | + +配置保留那条尤其关键：生产 17 个插件都有配置（qq 账号、weather 默认城市、 +browser profile 路径）。手工脚本恰好没碰配置表所以侥幸不丢，但那是运气不是设计。 + +最终实现：POST 到 `127.0.0.1:9876/plugins`，传 `{path, overwrite:true}`。 +保留的一个设计是**先全部校验再动手**——任一插件缺 hmap 就整批中止， +因为新 homed 不认 `.so`，「一半装了一半没装」的中间态最难排查。 + +### 结果 + +``` +17/17 成功，全部 config_kept=true +0 个残留 .so；17 个 plugin.bin 均有执行位 +17 个 manifest 的 entry 均为 plugin.bin；无 .bak 残留 +bundle 包正确挑了当前平台（weather 目录只留 8.7MB 的 linux/amd64 那份） +``` + +备份：`/home/newqqagent-migration-backup-20260902-214812` +（plugins 全目录 + homed.old + homeagent.service，162MB）。 +**唯一回滚路径**是恢复该目录 + 回滚 homed 二进制。 + +### 生产端到端验证（真实 QQ 消息） + +``` +input from qq → response (83293ms, tools=[qq_get_message qq_get_history + output_send__qq output_send__qq qq_mark_read]) +``` + +逐环节： + +- **输入**：qq 子进程收 webhook → 经 RPC 报给内核 → agent 主循环 +- **工具调用**：5 次跨进程调用全部成功（内核反向调用进子进程执行） +- **stage 改写生效**（最关键的一条）： + ``` + [sanitizer] cleanToolCallLeakage: 2 bytes removed + [sanitizer] cleaned 2 bytes (before=13590 after=13588) + [proc] sanitizer stage post_action 改写了 1 个字段 + ``` + sanitizer 在**另一个进程里**改了 StageContext，内核读到了改写结果。 + 13590 字节文本经共享段传递、被改写、写回，全程未拷贝整个上下文。 +- **输出真的送达**：`tool output_send__qq result: 已通过 [qq] 通道发送: map[status:sent]` + —— 直接验证 Part 0.1 修的 output_send 假成功缺陷（§9.4） +- **arena 生命周期正常**：每次 stage 结束都压实回收（单次最高 15802 字节），无泄漏累积 + +这一次对话触发约 20 次 stage、5 次工具调用、2 次输出发送，跨越 15 个插件子进程。 +旧架构下同样流程有三处会静默出问题：stage 并发写丢字段（§8.4 实测 35.8~36.8% +lost update）、output_send 假成功、cgo 超时泄漏 goroutine。现在这些在日志里可见且正确。 + +--- + +## Part 6.6 压测与延迟实测 + +基准与压测在代码里（`internal/plugin/proc/bench_test.go` + `streaming_test.go`）， +非独立脚本——随代码演进自动跑，不会腐坏。 + +| 项目 | 实测 | 基线 | 判断 | +|---|---|---|---| +| 工具调用 RPC 往返 | 24.1 µs | 实验 11: 19.6 µs | 同量级 | +| 锁仲裁（内核侧） | 0.76 µs | — | 见下注 | +| 事件环写入 | 95 ns | — | 亚微秒 | +| 事件环并发写入 | 83 ns | — | 无锁竞争恶化 | +| 完整 stage 往返 | 132 µs | — | 含 3 次进程间往返 | +| 共享段编解码 | 3.7 µs | — | 占 stage 的 2.8% | + +**锁仲裁 0.76µs 不可与实验 3 的 19.40µs 对照**——测的不是同一个东西： +实验 3 测插件经 RPC 请求锁的完整跨进程往返，本基准只测内核侧 +`lockRegistry.acquire/release`。真实成本仍在 20µs 量级。基准原名 +`BenchmarkStageLockRoundTrip` 有误导性，已改为 `BenchmarkStageLockArbitration`。 + +**stage 往返 132µs 的成本构成**：共享段编解码只占 3.7µs，其余是 +**一次 stage 要走 3 次进程间往返**（`stage.invoke` + 插件侧反向的 +`stage.lock` / `stage.unlock`）。相对 LLM 往返 2-8 秒可忽略； +要优化的方向是把 lock/unlock 合入 `stage.invoke` 的请求/应答。 + +### 流式压测（§4.3 标记「风险高」的那一项） + +``` +5000 次 Publish + 每条睡 20µs 的慢消费者 + 实测 2.29ms，均摊 457 ns/token + 同步语义理论下限 100ms + +订阅者 1 个：1.547ms（515 ns/次） +订阅者 8 个：1.518ms（506 ns/次） ← 无线性恶化 + +环溢出（无消费者写 30000 次，cap=8192）：均摊 35 ns/次 ← 仍 O(1) +``` + +2.29ms 与实验 4 的数字完全一致（那次也是 2.29ms / 0.46µs per token）， +post-and-forget 在实现中成立。第三项的意义：消费者完全停摆时写端覆盖 +最旧 slot，这条路径仍是 O(1)，故「插件卡住」不会连带拖慢内核主循环。 + +--- + +## 版本号 + +v1.0.0（tag 已打）。公开 SDK 接口零改动，但产物形态从 `plugin.so` 变为 +`plugin.bin`，0.9.x 内核不会识别——不可互操作的破坏性变化，故跃主版本号。 + +⚠️ **Makefile 陷阱**：`VERSION ?= $(shell git describe --tags --dirty)` +意味着实际注入值来自 git tag，`meta.go` 里的默认值只在不带 ldflags 时生效。 +打 tag 前 `make build` 注入的是 `v0.9.1-56-g2572688-dirty`。 + +同时删掉 C ABI 时代的死常量（`ABIVersion`/`CABINum`/51 个 `Core` +整数 ID）——随 Part 6.2 删 `internal/plugin/cabi/` 就已无使用者， +留着会让人以为 C 层协商还在生效，或以为加 method 要同步维护那张整数表。 From 12259ed4ecac9a5c176ef02dfcb83bb798d80b74 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 3 Sep 2026 08:39:23 +0800 Subject: [PATCH 25/27] =?UTF-8?q?chore:=20=E4=BF=AE=20.gitignore=20?= =?UTF-8?q?=E8=AF=AF=E4=BC=A4=E6=BA=90=E7=A0=81=E7=9B=AE=E5=BD=95=EF=BC=88?= =?UTF-8?q?4=20=E7=B1=BB=EF=BC=8C28=20=E4=B8=AA=E5=B7=B2=E8=B7=9F=E8=B8=AA?= =?UTF-8?q?=E6=96=87=E4=BB=B6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `git ls-files | xargs -n1 git check-ignore --no-index` 查出 49 个已跟踪 源码文件落在 ignore 规则下。它们现在能提交只是因为「已跟踪文件不受 .gitignore 影响」这条 git 规则在兜着——**新增文件会默默不入库**。 ## 根因一：缺前导斜杠（28 个文件） `knowledge/` / `memory/` / `scripts/` 不带前导斜杠，git 把它们当作 「任意层级的同名目录」： memory/ → 吞掉 internal/memory/ 24 个文件 knowledge/ → 吞掉 internal/knowledge/ 3 个文件 assets/knowledge/ scripts/ → 吞掉 deploy/scripts/ 1 个文件 本意只是忽略根级运行时数据目录。旁边的 `/adapters/` 就写对了， 这三条是漏了斜杠。 修法：补 `/` 前缀。验证两侧行为： 根级 knowledge/y.md memory/z.db scripts/tmp.sh 仍被忽略 ✓ 深层 internal/memory/new.go internal/knowledge/new.go deploy/scripts/new.sh 可入库 ✓ ## 根因二：internal/meta/ 整目录被忽略（1 个文件） 引入于 1f1233b（2026-07-12），同批还有 `.go/`、`.local/`、 `internal/plugins/openclaw/{manager,pysimulator}/`（后两个目录现已不存在）。 `internal/meta/meta.go` 是内核版本号与元数据的唯一数据源，本轮升 1.0.0 时 `git add` 报「paths are ignored」，就是这条。已跟踪所以改动能提交， 但新增 meta 文件会丢。直接删掉这条规则。 ## 保留的 20 项不是缺陷 `third_party/homeagent-sdk/example/` 下 20 个已跟踪文件（plg.json + plugin.go）仍在规则覆盖下，这是**有意的**：外部插件维护在独立 SDK 仓 （决策 sdk_repo_only），主仓只需要这 20 个源码文件参与构建，不要 SDK 仓的 main.go/go.mod/go.sum。删掉该规则会让 60+ 个文件涌进主仓——实测确认过。 已在两处 ignore 段落写明理由，避免后来人「修」错方向。 验证：修复后 check-ignore 扫描从 49 降到 20（全部是有意保留的 example/）； go build ./... 通过。 --- .gitignore | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index c23ee2d..0595e62 100644 --- a/.gitignore +++ b/.gitignore @@ -10,7 +10,6 @@ data/ .tmp-plugins/ .go/ .local/ -internal/meta/ *.hmap dev/ @@ -24,6 +23,11 @@ cmd/gui/dist/ .gopath/ # SDK 工具链 — 核心仓不追踪 +# +# 外部插件与工具链维护在独立 SDK 仓（决策 sdk_repo_only）， +# 本仓经 go.mod 的 replace => ./third_party/homeagent-sdk 引用。 +# example/ 下已跟踪的 20 个文件（plg.json + plugin.go）早于本规则， +# 靠「已跟踪文件不受 .gitignore 影响」保留——这是有意的，不要「修」。 third_party/homeagent-sdk/bin/ third_party/homeagent-sdk/tools/ third_party/homeagent-sdk/package/ @@ -36,10 +40,15 @@ third_party/homeagent-sdk/example/ codegraph.json # 运行时产物(不提交) +# +# ⚠️ 这些必须带前导斜杠。不带斜杠的模式（如 `memory/`）会匹配**任意层级**的 +# 同名目录，把 internal/memory/、internal/knowledge/、deploy/scripts/ 一起吞掉 +# ——24 + 3 + 1 个已跟踪源码文件曾因此落在 ignore 规则下，只靠「已跟踪 +# 文件不受 .gitignore 影响」这条 git 规则兜着，新增文件会默默不入库。 /adapters/ -knowledge/ -memory/ -scripts/ +/knowledge/ +/memory/ +/scripts/ terminal_locked_log.txt dist/ From 351e99dd70f986c5414c67397fdb90840af4fa7d Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 3 Sep 2026 08:50:48 +0800 Subject: [PATCH 26/27] =?UTF-8?q?docs(plan):=20=E7=AC=AC=2012=20=E8=8A=82?= =?UTF-8?q?=20=E2=80=94=E2=80=94=20=E5=AD=90=E8=BF=9B=E7=A8=8B=E5=8C=96?= =?UTF-8?q?=E8=BF=81=E7=A7=BB=E5=89=A9=E4=BD=99=E5=B7=A5=E4=BD=9C=E4=B8=8E?= =?UTF-8?q?=E7=9B=AE=E6=A0=87=E6=95=88=E6=9E=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 迁移主体已完成上生产（内核 v1.0.0，17 插件全部子进程化）， 但有若干项未做完或未达成。写进 plan.md 而非只留在对话里， 避免下次接手时靠猜。 八个小节按「阻塞程度」排： **12.1 合并到 main + 发布分支** —— 卡在四个决策点，非技术阻塞： merge 方式（--no-ff vs squash）、是否删 feature 分支、release 构建是否 再替换生产二进制、SDK 仓是否同步。附完整执行序列。 记了一个易错点：v1.0.0 tag 当前打在 feature 分支中间点 670efcd， 按规范应在 release 分支上，需删除重打。 **12.2 验收清单两项未达成** —— 这两项在迁移计划里已如实标 ⚠️： - SetToolBlocks 仍未实现。C ABI 时代也是空实现故不算回归， 但 §3.8 明确承诺过「二进制写入 arena + Slice 描述符回传」，没兑现。 - 内存 88MB 远超「基线 +29MB」。根因是每插件静态链接整个 Go runtime， 15 个不同二进制无共同物理页（PSS/RSS 99.9% vs 基线 44%）。 基线用 2.68MB 最小插件复制 17 份，绝对数字本就不可比。 **12.3 事件环零真实负载检验** —— 机制完成、压测通过（2.29ms 与实验 4 一致），但 grep 确认无任何插件使用 Events().Subscribe。压测是我构造的 负载，生产上这条路径从未被真实插件走过。只写 ✅ 会掩盖这一点。 **12.4 三套 ABI 只收敛两套** —— C ABI 删了、Windows DLL 收敛了， Lua 仍走独立解释器路径。§9.2 那句「三套收敛为单一 RPC」本轮兑现 2/3。 不阻塞是因为 Lua 不经 C ABI，不属于要消除的 6 类缺陷。 **12.5 Windows 无真机验证** —— 只做了交叉编译 + 单元测试。 已知语义差异（Event 是二元信号非计数器）推理上不影响正确性， 但没在真机确认过。§9.2 声称 Windows「从受害者变受益方」缺实证。 **12.6 stage 往返省两次 IPC** —— 132µs 里编解码只占 3.7µs， 其余是 3 次进程往返（invoke + 插件侧反向 lock/unlock）。合并后预期 降到 ~30µs。风险是锁持有时机改变，插件若在 handler 里再请求锁会死锁。 **12.7 遗留项** —— homed 主 heap 2.36GB（与插件无关）、鸿蒙端未提交改动。 **12.8 已达成目标留档** —— 6 类缺陷逐条对账，每条附证据 （测试名或生产日志），便于日后确认哪些是真解决了。 --- plan.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) diff --git a/plan.md b/plan.md index 4866ad6..bd5e2fd 100644 --- a/plan.md +++ b/plan.md @@ -910,3 +910,182 @@ homed RSS = 2.34 GB RssAnon = 2.35 GB（真实驻留） context 累积导致的内存增长。 - [ ] 单独排查 homed 主 heap 的 2.36GB 驻留来源 + +--- + +## 12. 子进程化迁移收尾：剩余工作与目标效果 + +> 状态锚点（2026-09-03）：迁移主体已完成并上生产。内核 **v1.0.0**， +> 生产 17 个外部插件全部经子进程通道运行，15 个子进程稳定存活。 +> 分支：主仓 `feature/plugin-proc-migration` @ `12259ed`（领先 main 26）， +> SDK 仓 `feature/plugin-proc-migration` @ `5ed8d65`（领先 main 4）。 +> +> 三项合入门禁**已全部通过**：`make test` 零失败、`go vet ./...` 无告警、 +> `git diff main -- third_party/homeagent-sdk/sdk/` 为空（接口冻结不变量）。 +> +> 详细执行记录见 `docs/zh/plugin-migration-plan.md`（Part 0~6 全部标记完成）。 + +### 12.1 待用户决策后执行：合并到 main + 发布分支 + +**当前卡在四个决策点**，不是技术阻塞： + +| # | 决策点 | 备选 | 倾向 | +|---|---|---|---| +| 1 | merge 方式 | `--no-ff` 保留 25 commit / squash 压成一条 | `--no-ff`——commit message 记录了「为何共享同一块 memfd」「为何 procCore 不能嵌入」等踩坑过程 | +| 2 | 合回后是否删 feature 分支 | 删（规范要求）/ 留（8-9 周大特性） | 听用户 | +| 3 | release 构建是否再替换生产二进制 | 换（溯源干净）/ 不换（避免停服） | 听用户 | +| 4 | SDK 仓是否同步 main + release | 同步 / 只合 main / 暂不处理 | 同步——规范说「两仓版本对齐是第一优先级」 | + +**目标效果**： + +- `main` 含全部迁移工作且**永远可部署**（规范 §二.1）。 +- 存在 `release/v1.0.0` 分支，`v1.0.0` tag **打在 release 分支上**而非 feature。 + ⚠️ 当前 tag 指向 `670efcd`（feature 分支中间点），需删除重打。 +- 两仓版本对齐：主仓 `internal/meta.Version` = SDK 仓 `meta.Version` = `1.0.0`， + 且 vendored SDK 与 SDK 仓 release tag 内容一致。 +- 现网部署产物可追溯到 release tag 构建（规范 §四）。 + +**执行序列**（决策落定后）： + +```bash +# 主仓 +git checkout main && git merge --no-ff feature/plugin-proc-migration +git checkout -b release/v1.0.0 main +git tag -d v1.0.0 && git tag -a v1.0.0 # 重打在 release 上 +make build VERSION=1.0.0 # 发布产物 + +# SDK 仓（同上流程） +cd third_party/homeagent-sdk +git checkout main && git merge --no-ff feature/plugin-proc-migration +git checkout -b release/v1.0.0 main && git tag -a v1.0.0 +``` + +--- + +### 12.2 验收清单里两项**未达成**的目标 + +这两项在 `docs/zh/plugin-migration-plan.md` 的最终验收清单里如实标了 ⚠️， +不是遗漏而是明确的未兑现承诺。 + +#### 12.2.1 `SetToolBlocks` 仍是未实现（承诺未兑现） + +- **现状**：`io.setToolBlocks` 已在 `proc/protocol.go` 定义、已划入 `CapCore` + 能力组，但 `corehandler.go` 的 handler 仍返回未实现。 +- **为何不算回归**：C ABI 时代它也是空实现（§1.4 / `case` 无对应逻辑）， + 能力从「给不了」变成「暂未接」，没变差。 +- **但 §3.8 承诺过**：迁移评估明确写「`SetToolBlocks` → 二进制写入 arena， + 返回 `Slice` 描述符 ✅」。这条没做到。 +- **目标效果**：插件调用 `SetToolBlocks(blocks)` 后，多模态内容块经共享段 + arena 传给内核，内核把它并入工具返回值；`Slice` 描述符回传避免拷贝。 +- **当前无用户**：17 个外部插件均未调用，故不阻塞发布。 +- [ ] 实现 `io.setToolBlocks` 的内核侧 handler（arena 写入 + Slice 回传） +- [ ] 补一个真实使用它的 example 插件，否则无法验证 + +#### 12.2.2 内存开销超出计划目标（结构性问题） + +- **计划目标**：迁移后常驻 ≤ 基线 +29MB（实验 5 量级）。 +- **实测**：15 个插件进程 `RSS=88.0MB` / `PSS=87.9MB`，均摊 5.87MB。 +- **根因**：每插件静态链接整个 Go runtime。15 个**不同**二进制之间无共同 + 物理页可映射，`PSS/RSS = 99.9%`（基线是 44%——那次用同一个 2.68MB 最小 + 插件复制 17 份，页可共享）。 +- **绝对数字不可比**：基线插件 2.68MB，真实插件 3.1~14.8MB（browser 最大）。 + 结构性指标（均摊线程 5.5 vs 4.9）同量级。 +- **实际开销高于 §4.3 乐观估计**，这是「每插件独立二进制」的固有代价。 +- **目标效果（若要压）**：共享一个 launcher 二进制 + 各插件只提供业务模块， + 让 15 个进程映射同一份 runtime 物理页，把 PSS 压回 RSS 的一半以下。 + 代价是插件不再是自包含可执行文件，分发与版本管理都变复杂。 +- [ ] 决定是否值得为此改变分发模型（当前倾向：不改，88MB 可接受） + +--- + +### 12.3 事件环：机制完成但**零真实负载检验** + +- **已完成**：内核侧 `proc/evtring.go`（写端 + 消费端 + 事件类型位编码）、 + `internal/plugin/evtring.go`（Bus ↔ EvtRing 适配）、模板侧 `evtConsumerLoop`、 + 三平台通知机制（Linux eventfd / macOS pipe / Windows Event）。 +- **压测通过**：5000 次 Publish + 20µs 慢消费者 = 2.29ms（与实验 4 一致）； + 订阅者 1→8 耗时不变；环溢出仍 O(1)。 +- **但**：`grep` 确认**无任何外部插件使用 `Events().Subscribe`**。 + 压测是我构造的负载，生产上这条路径从未被真实插件走过。 +- **目标效果**：至少一个真实插件订阅内核事件并正确处理， + 验证「独立游标 + 溢出跳过 + dropped 计数」在真实时序下的行为。 +- [ ] 写一个订阅 `stage`/`tool_call` 事件的 example 插件做真实验证 +- [ ] 观察长时间运行下 `dropped` 计数是否异常增长 + +--- + +### 12.4 三套 ABI 只收敛了两套：Lua 仍独立 + +- **已收敛**：C ABI（删除）+ Windows DLL（改走同一 RPC）。 +- **未收敛**：`internal/plugin/lua_plugin.go` / `dynamic_lua.go` 仍走 + gopher-lua 解释器的独立路径。 +- **为何不阻塞本轮**：Lua 经解释器不经 C ABI，不属于本轮要消除的 6 类缺陷 + （热重载失效、崩溃隔离缺失、stage lost update、cgo 超时泄漏、 + output_send 假成功、能力断层）。§9.2 的「三套 ABI 收敛为单一 RPC」 + 这句话本轮只兑现了 2/3。 +- **目标效果**：Lua 插件也走 `proc` 通道（launcher 进程内嵌解释器）， + 内核侧只有一套加载逻辑与一套权限检查。 +- **收益**：Lua 插件获得崩溃隔离与共享内存 stage 全字段可见； + 内核侧删掉 `lua_plugin.go` 的平行实现。 +- [ ] 评估 Lua 走 proc 通道的代价（解释器进程启动开销 vs 隔离收益） + +--- + +### 12.5 Windows 只做了交叉编译，无真机验证 + +- **已完成**：`shmalloc_windows.go`（`CreateFileMappingW` + `MapViewOfFile`）、 + `evtfd_windows.go`（`CreateEventW` + `SetEvent`）、`shmpass_windows.go` + （名字经环境变量传递）、插件侧 `proc_shm_windows.go.tmpl` + （`syscall.NewLazyDLL` 绑定 `OpenFileMappingW`/`OpenEventW`）。 +- **验证程度**：仅 `GOOS=windows GOARCH=amd64 go build` 通过 + 单元测试。 + **无 Windows 测试机，从未真机跑过**。 +- **已知的语义差异**（代码注释里记了，但未实测）： + Windows Event 是二元信号而非计数器，多次 `SetEvent` 只唤醒一次。 + 推理上不影响正确性（消费者按 `readSeq` 追 `writeSeq` 批量 drain）， + 但没在真机确认过。 +- **目标效果**：Windows 真机上完成一次完整的插件加载 → 工具调用 → + stage 改写 → 事件消费闭环，确认 16 字段全可见且写回生效 + （这是 §9.2 声称 Windows「从受害者变受益方」的实证）。 +- [ ] 找一台 Windows 机器跑端到端验证 +- [ ] 特别验证命名对象的撞名防护（名字带 PID + 递增序号） + +--- + +### 12.6 性能优化候选：stage 往返省两次 IPC + +- **实测**：完整 stage 往返 132µs，其中共享段编解码只占 3.7µs（2.8%）。 +- **成本构成**：一次 stage 要走 **3 次进程间往返**——`stage.invoke` + 加上插件侧反向的 `stage.lock` / `stage.unlock`。 +- **相对 LLM 往返 2-8 秒可忽略**，故非紧急。 +- **目标效果**：把 lock/unlock 合入 `stage.invoke` 的请求/应答 + （内核在下发 invoke 前就代插件持锁，应答时释放）， + stage 往返从 3 次 IPC 降到 1 次，预期 132µs → ~30µs。 +- **风险**：改变锁的持有时机。当前是插件主动请求， + 改后内核代持——插件若在 handler 里再次请求锁会死锁，需要额外防护。 +- [ ] 评估锁语义变化的影响面（哪些插件依赖显式 lock 时机） + +--- + +### 12.7 无关本次迁移的遗留项 + +- [ ] 单独排查 homed 主 heap 的 2.36GB 驻留来源（见 §11.9，与插件无关） +- [ ] `cmd/ohos/.../SettingsPage.ets` 有 80 行未提交的鸿蒙端改动 + （非本次迁移内容，一直未碰） + +--- + +### 12.8 本次迁移**已达成**的目标（对照 §11.0 起因） + +留档备查——6 类 C ABI 前提缺陷的消除状态： + +| 缺陷 | 原状 | 现状 | 证据 | +|---|---|---|---| +| 热重载失效（11.6） | `DF_1_NODELETE` 让 `dlclose` 成 no-op | ✅ 换 `plugin.bin` 即生效 | 生产实测 `unloaded (config kept)` → 重载 | +| 崩溃隔离缺失 | 插件 panic 带崩 homed | ✅ 子进程独立崩溃 | `TestRealPlugin_CrashDoesNotKillKernel` | +| stage lost update（11.3） | 副本模型互相覆盖 35.8~36.8% | ✅ 0% | `TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate` | +| cgo 超时泄漏（11.2） | 现网泄漏 26 次 | ✅ 整套新架构零 cgo | `Process.Kill()` 真取消 | +| output_send 假成功（11.1） | 永远返回成功 | ✅ 真实结果 | 生产实测 `map[status:sent]` | +| 能力断层（11.5 + §3.8） | Windows 只见 3 字段、无写回 | ✅ 18 字段全可见可写回 | 生产实测 sanitizer 跨进程改写 13590 字节 | + +额外收益：权限梯度从「C ABI 表达能力的意外产物」变成**显式三道闸** +（类型层 `procCore` 命名字段 + manifest 能力声明 + RPC 边界明确拒绝）。 From 02cc74ce1172ffa6394127f78d667f275873d4c1 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 3 Sep 2026 12:37:58 +0800 Subject: [PATCH 27/27] =?UTF-8?q?fix(proc):=20=E5=AD=90=E8=BF=9B=E7=A8=8B?= =?UTF-8?q?=E5=B4=A9=E6=BA=83=E8=87=AA=E6=84=88=20+=20=E9=9B=86=E4=B8=AD?= =?UTF-8?q?=E5=8F=B0=E8=B4=A6=20+=20=E6=B3=A8=E5=86=8C=E9=9D=A2=E6=91=98?= =?UTF-8?q?=E9=99=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根因：子进程插件被 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 双摘后可重新注册同名） --- .../entry/src/main/ets/pages/SettingsPage.ets | 94 +++++- internal/agent/core/stages.go | 64 +++- internal/agent/core/stages_plugin_test.go | 96 ++++++ internal/plugin/crash_recovery_test.go | 249 ++++++++++++++++ internal/plugin/dynamic_proc_unix.go | 133 ++++++++- internal/plugin/proc/host.go | 15 + internal/plugin/proc/plugin.go | 42 +++ internal/plugin/proc/procattr_linux.go | 30 ++ internal/plugin/proc/procattr_other.go | 15 + internal/plugin/proc/process.go | 127 ++++++-- internal/plugin/proc/process_test.go | 147 +++++++++ internal/plugin/proc/supervisor.go | 163 ++++++++++ internal/plugin/proc/testdata/forkplugin.go | 71 +++++ internal/plugin/registry.go | 278 ++++++++++++++++-- internal/plugins/pluginmgr/plugin.go | 150 +++++++++- internal/plugins/pluginmgr/upgrade_test.go | 4 + internal/plugins/webui/handler_plugin_test.go | 12 + internal/sdk/plugin.go | 33 +++ 18 files changed, 1649 insertions(+), 74 deletions(-) create mode 100644 internal/agent/core/stages_plugin_test.go create mode 100644 internal/plugin/crash_recovery_test.go create mode 100644 internal/plugin/proc/procattr_linux.go create mode 100644 internal/plugin/proc/procattr_other.go create mode 100644 internal/plugin/proc/supervisor.go create mode 100644 internal/plugin/proc/testdata/forkplugin.go diff --git a/cmd/ohos/HomeAgent/entry/src/main/ets/pages/SettingsPage.ets b/cmd/ohos/HomeAgent/entry/src/main/ets/pages/SettingsPage.ets index 2a5470f..ec45d56 100644 --- a/cmd/ohos/HomeAgent/entry/src/main/ets/pages/SettingsPage.ets +++ b/cmd/ohos/HomeAgent/entry/src/main/ets/pages/SettingsPage.ets @@ -62,6 +62,14 @@ export struct SettingsPage { @State editName: string = ''; @State showAddForm: boolean = false; @State addFormVisible: boolean = false; + /** + * 表单当前在编辑哪条连接：空串表示新建。 + * + * 之前只有"添加"入口，ConnStore.updateConnection 写好了却没有任何调用者， + * 于是地址填错的连接只能删掉重建（API Key 也得重敲）。同一套表单 + * 靠这个 id 区分保存走 add 还是 update。 + */ + @State editingId: string = ''; @State themeMode: string = 'system'; @State lang: string = 'zh'; @State bgImage: string = ''; @@ -205,11 +213,12 @@ export struct SettingsPage { this.showToast('名称和地址不能为空', true); return; } + if (this.editingId.length > 0) { + this.updateConnection(this.editingId, name, url, apiKey); + return; + } connStore.addConnection(name, url, apiKey).then(() => { - this.editName = ''; - this.editUrl = ''; - this.editApiKey = ''; - this.showAddForm = false; + this.closeConnForm(); const cur = connStore.getCurrentConnection(); if (cur !== null) { apiClient.setConnection(cur); @@ -219,6 +228,53 @@ export struct SettingsPage { }); } + /** + * 保存对已有连接的修改。 + * + * 修改当前生效的连接后必须重新 setConnection：ApiClient 持有的是 + * ConnectionConfig 的引用快照，不刷新的话后续请求还会打到旧地址。 + */ + private updateConnection(id: string, name: string, url: string, apiKey: string): void { + connStore.updateConnection(id, name, url, apiKey).then(() => { + this.closeConnForm(); + const cur = connStore.getCurrentConnection(); + if (cur !== null) { + apiClient.setConnection(cur); + } + this.loadConnections(); + this.showToast('连接已更新', false); + }); + } + + /** 打开表单：id 为空是新建，非空是编辑并回填原值（API Key 一并带出，避免用户重敲）。 */ + private openConnForm(conn: ConnectionConfig | null): void { + this.showAddForm = true; + this.addFormVisible = false; + if (conn === null) { + this.editingId = ''; + this.editName = ''; + this.editUrl = ''; + this.editApiKey = ''; + } else { + this.editingId = conn.id; + this.editName = conn.name; + this.editUrl = conn.url; + this.editApiKey = conn.apiKey; + } + setTimeout(() => { + this.addFormVisible = true; + }, 30); + } + + private closeConnForm(): void { + this.showAddForm = false; + this.addFormVisible = false; + this.editingId = ''; + this.editName = ''; + this.editUrl = ''; + this.editApiKey = ''; + } + private deleteConnection(id: string): void { connStore.deleteConnection(id).then(() => { this.loadConnections(); @@ -840,14 +896,7 @@ export struct SettingsPage { .backgroundColor(this.palette().accent) .fontColor(Color.White) .onClick(() => { - this.showAddForm = true; - this.addFormVisible = false; - this.editName = ''; - this.editUrl = ''; - this.editApiKey = ''; - setTimeout(() => { - this.addFormVisible = true; - }, 30); + this.openConnForm(null); }) } .width('100%') @@ -855,6 +904,10 @@ export struct SettingsPage { if (this.showAddForm) { Column() { + Text(this.editingId.length > 0 ? '编辑连接' : '新建连接') + .fontSize(12) + .fontColor(this.palette().textSecondary) + .margin({ bottom: 10 }) TextInput({ placeholder: '名称 (如 HomeAgent)', text: this.editName }) .height(36).fontSize(13).fontColor(this.palette().textPrimary) .placeholderColor(this.palette().textMuted).backgroundColor(this.palette().bgInput) @@ -888,7 +941,7 @@ export struct SettingsPage { .border({ width: 1, color: this.palette().btnGhostBorder }) .fontColor(this.palette().textSecondary) .onClick(() => { - this.showAddForm = false; + this.closeConnForm(); }) Blank() Button('保存') @@ -961,6 +1014,16 @@ export struct SettingsPage { .backgroundColor(this.palette().accentBg) .margin({ right: 6 }) } + Button('编辑') + .height(26) + .fontSize(11) + .backgroundColor(Color.Transparent) + .border({ width: 1, color: this.palette().btnGhostBorder }) + .fontColor(this.palette().textSecondary) + .margin({ right: 6 }) + .onClick(() => { + this.openConnForm(conn); + }) Button('删除') .height(26) .fontSize(11) @@ -980,7 +1043,10 @@ export struct SettingsPage { color: conn.id === this.currentId ? this.palette().accent : Color.Transparent, }) .margin({ bottom: 6 }) - }, (conn: ConnectionConfig) => conn.id) + // 键里带上 name/url：ForEach 对相同键只更新绑定、不重跑 @Builder 体， + // 只用 id 做键时改完地址这一行还显示旧值。行内没有 TextInput， + // 因此把可变字段放进键不会有"编辑时焦点被销毁"的副作用。 + }, (conn: ConnectionConfig) => conn.id + '|' + conn.name + '|' + conn.url) } } diff --git a/internal/agent/core/stages.go b/internal/agent/core/stages.go index add7da1..36cb9ee 100644 --- a/internal/agent/core/stages.go +++ b/internal/agent/core/stages.go @@ -14,14 +14,25 @@ type StageHost struct { toolDefs []sdk.ToolDef tools map[string]sdk.ToolHandler toolPlugins map[string]string - stages map[sdk.Stage][]sdk.StageHandler + stages map[sdk.Stage][]stageEntry +} + +// stageEntry 把 stage handler 与它的归属插件绑定。 +// +// 为何需要归属：子进程插件崩溃后，它注册的 handler 闭包仍在这张表里， +// 每次 RunStage 都会经 RPC 打向已死进程并报 ErrProcessExited；重启后新 handler +// 又追加进来，旧的永不退场——错误与重复执行随重启次数线性累积。 +// 有了归属才能在卸载/崩溃时成组摘除。 +type stageEntry struct { + plugin string + fn sdk.StageHandler } func NewStageHost() *StageHost { return &StageHost{ tools: make(map[string]sdk.ToolHandler), toolPlugins: make(map[string]string), - stages: make(map[sdk.Stage][]sdk.StageHandler), + stages: make(map[sdk.Stage][]stageEntry), } } @@ -41,9 +52,15 @@ func (h *StageHost) RegisterTool(name string, def sdk.ToolDef, handler sdk.ToolH } func (h *StageHost) RegisterStage(stage sdk.Stage, handler sdk.StageHandler) { + h.RegisterStageFor("", stage, handler) +} + +// RegisterStageFor 注册带归属插件名的 stage handler。 +// plugin 为空时等同 RegisterStage（内核自身注册的 handler，不参与成组摘除）。 +func (h *StageHost) RegisterStageFor(plugin string, stage sdk.Stage, handler sdk.StageHandler) { h.mu.Lock() defer h.mu.Unlock() - h.stages[stage] = append(h.stages[stage], handler) + h.stages[stage] = append(h.stages[stage], stageEntry{plugin: plugin, fn: handler}) } func (h *StageHost) GetToolDefs() []sdk.ToolDef { @@ -106,6 +123,36 @@ func (h *StageHost) UnregisterPluginTools(pluginName string) { h.toolDefs = keepDefs } +// UnregisterPluginStages 摘除某插件注册的全部 stage handler，返回摘除数量。 +// +// 与 UnregisterPluginTools 成对：卸载/重载/崩溃时两者都得做， +// 否则插件的工具没了但 stage handler 还在，继续打向不存在的插件。 +func (h *StageHost) UnregisterPluginStages(pluginName string) int { + if pluginName == "" { + return 0 + } + h.mu.Lock() + defer h.mu.Unlock() + + removed := 0 + for stage, entries := range h.stages { + keep := entries[:0:0] + for _, e := range entries { + if e.plugin == pluginName { + removed++ + continue + } + keep = append(keep, e) + } + if len(keep) == 0 { + delete(h.stages, stage) + continue + } + h.stages[stage] = keep + } + return removed +} + func inferToolPlugin(name string) string { for i := 0; i < len(name); i++ { if name[i] == '_' { @@ -123,14 +170,15 @@ func inferToolPlugin(name string) string { // handler 返回的 error 会被收集到 ctx.Errors 中并记录日志，不会中断其他 handler 的执行。 func (h *StageHost) RunStage(stage sdk.Stage, ctx *sdk.StageContext) { h.mu.RLock() - handlers := h.stages[stage] + entries := make([]stageEntry, len(h.stages[stage])) + copy(entries, h.stages[stage]) h.mu.RUnlock() - if len(handlers) == 0 { + if len(entries) == 0 { return } var wg sync.WaitGroup - errCh := make(chan error, len(handlers)) - for _, handler := range handlers { + errCh := make(chan error, len(entries)) + for _, entry := range entries { wg.Add(1) go func(fn sdk.StageHandler) { defer wg.Done() @@ -142,7 +190,7 @@ func (h *StageHost) RunStage(stage sdk.Stage, ctx *sdk.StageContext) { if err := fn(ctx); err != nil { errCh <- err } - }(handler) + }(entry.fn) } wg.Wait() close(errCh) diff --git a/internal/agent/core/stages_plugin_test.go b/internal/agent/core/stages_plugin_test.go new file mode 100644 index 0000000..f67ddab --- /dev/null +++ b/internal/agent/core/stages_plugin_test.go @@ -0,0 +1,96 @@ +package core + +import ( + "testing" + + sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" +) + +// stage handler 必须能按插件成组摘除。 +// +// 修复前 StageHost.stages 只存匿名函数，没有归属信息： +// 插件崩溃/卸载后它的 handler 永远留在表里，每轮 RunStage 都被并发调起并 +// 打向已死进程；重启后新 handler 追加进来，旧的仍不退场—— +// 错误与重复执行随重启次数线性累积。 +func TestUnregisterPluginStages_RemovesOnlyThatPlugin(t *testing.T) { + h := NewStageHost() + + var aRan, bRan, coreRan int + h.RegisterStageFor("a", sdk.StagePreAction, func(*sdk.StageContext) error { aRan++; return nil }) + h.RegisterStageFor("b", sdk.StagePreAction, func(*sdk.StageContext) error { bRan++; return nil }) + // 内核自身注册的 handler（无归属）不该被插件摘除波及 + h.RegisterStage(sdk.StagePreAction, func(*sdk.StageContext) error { coreRan++; return nil }) + + h.RunStage(sdk.StagePreAction, &sdk.StageContext{}) + if aRan != 1 || bRan != 1 || coreRan != 1 { + t.Fatalf("首轮应全部执行，a=%d b=%d core=%d", aRan, bRan, coreRan) + } + + if n := h.UnregisterPluginStages("a"); n != 1 { + t.Errorf("应摘除 1 个 handler，实际 %d", n) + } + + h.RunStage(sdk.StagePreAction, &sdk.StageContext{}) + if aRan != 1 { + t.Errorf("已摘除的插件 handler 不该再被调用，实际执行 %d 次", aRan) + } + if bRan != 2 || coreRan != 2 { + t.Errorf("其他 handler 应照常执行，b=%d core=%d", bRan, coreRan) + } +} + +// 摘除某插件的最后一个 handler 后，该 stage 应从表中消失（RunStage 直接短路）。 +func TestUnregisterPluginStages_DropsEmptyStage(t *testing.T) { + h := NewStageHost() + h.RegisterStageFor("solo", sdk.StageAfterToolcall, func(*sdk.StageContext) error { return nil }) + + if n := h.UnregisterPluginStages("solo"); n != 1 { + t.Fatalf("应摘除 1 个，实际 %d", n) + } + h.mu.RLock() + _, exists := h.stages[sdk.StageAfterToolcall] + h.mu.RUnlock() + if exists { + t.Error("stage 已无 handler 时应从表中删除") + } +} + +// 空插件名不得误摘内核自身注册的 handler。 +func TestUnregisterPluginStages_EmptyNameIsNoop(t *testing.T) { + h := NewStageHost() + ran := 0 + h.RegisterStage(sdk.StagePreAction, func(*sdk.StageContext) error { ran++; return nil }) + + if n := h.UnregisterPluginStages(""); n != 0 { + t.Errorf("空插件名应是 no-op，实际摘除 %d", n) + } + h.RunStage(sdk.StagePreAction, &sdk.StageContext{}) + if ran != 1 { + t.Errorf("内核 handler 应保留并执行，实际 %d 次", ran) + } +} + +// 工具与 stage 的摘除互不干扰：都摘完后两者皆空。 +func TestUnregisterPluginToolsAndStages_Together(t *testing.T) { + h := NewStageHost() + if err := h.RegisterTool("demo_run", sdk.ToolDef{Name: "demo_run", Plugin: "demo"}, + func(map[string]interface{}) (interface{}, error) { return nil, nil }); err != nil { + t.Fatal(err) + } + h.RegisterStageFor("demo", sdk.StagePreAction, func(*sdk.StageContext) error { return nil }) + + h.UnregisterPluginTools("demo") + h.UnregisterPluginStages("demo") + + if h.ToolCount() != 0 { + t.Errorf("工具应已摘除，实际 %d", h.ToolCount()) + } + if h.ToolPlugin("demo_run") != "" { + t.Error("工具→插件映射应清空") + } + // 摘除后可重新注册同名工具（重启路径的前提） + if err := h.RegisterTool("demo_run", sdk.ToolDef{Name: "demo_run", Plugin: "demo"}, + func(map[string]interface{}) (interface{}, error) { return nil, nil }); err != nil { + t.Errorf("摘除后应可重新注册同名工具，实际: %v", err) + } +} diff --git a/internal/plugin/crash_recovery_test.go b/internal/plugin/crash_recovery_test.go new file mode 100644 index 0000000..a3930ed --- /dev/null +++ b/internal/plugin/crash_recovery_test.go @@ -0,0 +1,249 @@ +package plugin + +import ( + "errors" + "os" + "path/filepath" + "sync" + "testing" + "time" + + agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io" + sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" +) + +// fakeCleaner 记录内核侧摘除动作，用于断言「插件死后注册面被摘干净」。 +// +// 同时实现 PluginToolCleaner 与 PluginStageCleaner——生产里 StageHost 两者都实现。 +type fakeCleaner struct { + mu sync.Mutex + tools []string + stages []string +} + +func (f *fakeCleaner) UnregisterPluginTools(name string) { + f.mu.Lock() + defer f.mu.Unlock() + f.tools = append(f.tools, name) +} + +func (f *fakeCleaner) UnregisterPluginStages(name string) int { + f.mu.Lock() + defer f.mu.Unlock() + f.stages = append(f.stages, name) + return 1 +} + +func (f *fakeCleaner) toolCalls() []string { + f.mu.Lock() + defer f.mu.Unlock() + return append([]string(nil), f.tools...) +} + +func (f *fakeCleaner) stageCalls() []string { + f.mu.Lock() + defer f.mu.Unlock() + return append([]string(nil), f.stages...) +} + +func contains(list []string, want string) bool { + for _, v := range list { + if v == want { + return true + } + } + return false +} + +// newTestRegistry 造一个可用于 detach/崩溃路径测试的最小 Registry。 +func newTestRegistry(t *testing.T) (*Registry, *fakeCleaner, *agentIO.IOManager) { + t.Helper() + cleaner := &fakeCleaner{} + iom := agentIO.NewIOManager() + r := &Registry{ + plugins: make(map[string]sdk.Plugin), + factories: make(map[string]NativeFactory), + pluginAutoRestart: make(map[string]bool), + sdkRefs: make(map[string]*sdk.PluginSDK), + knownDisabled: make(map[string]bool), + pluginHashes: make(map[string]string), + pluginChannels: make(map[string]*pluginChannelSet), + plgDir: t.TempDir(), + toolCleaner: cleaner, + iom: iom, + } + return r, cleaner, iom +} + +// detachPlugin 必须同时摘工具、stage handler、IO 通道。 +// +// 此前各卸载路径只调 UnregisterPluginTools，漏了后两项： +// 插件的工具没了但 stage handler 还在每轮 RunStage 里被调用并失败， +// output device 还留在 IOManager 里让模型看到一个永远发不出去的通道。 +func TestDetachPlugin_RemovesToolsStagesAndChannels(t *testing.T) { + r, cleaner, iom := newTestRegistry(t) + + // 模拟插件注册过通道 + if err := iom.RegisterDevice(&channelDevice{name: "demo_out"}); err != nil { + t.Fatalf("RegisterDevice: %v", err) + } + iom.RegisterInputChannel("demo_in", agentIO.ChannelDef{}) + r.noteChannel("demo", "demo_out", true) + r.noteChannel("demo", "demo_in", false) + + r.detachPlugin("demo") + + if !contains(cleaner.toolCalls(), "demo") { + t.Error("应摘除插件工具") + } + if !contains(cleaner.stageCalls(), "demo") { + t.Error("应摘除插件 stage handler（否则每轮 RunStage 都会打向已死插件）") + } + if iom.GetDevice("demo_out") != nil { + t.Error("output device 应被摘除，否则模型仍看到一个必然失败的通道") + } + if _, ok := iom.GetInputChannelDef("demo_in"); ok { + t.Error("input channel 定义应被摘除") + } +} + +// 通道台账在 detach 后清空，使插件重启时能重新注册同名通道。 +// +// 不清空的后果：RegisterDevice 撞上同名旧 device 直接报 already registered， +// 新进程的通道注册不上——插件“重启成功”了但通道永久指向已死进程。 +func TestReleasePluginChannels_AllowsReRegistrationAfterRestart(t *testing.T) { + r, _, iom := newTestRegistry(t) + + if err := iom.RegisterDevice(&channelDevice{name: "qq"}); err != nil { + t.Fatalf("首次注册: %v", err) + } + r.noteChannel("qq", "qq", true) + + r.detachPlugin("qq") + + // 重启后同名通道必须能重新注册 + if err := iom.RegisterDevice(&channelDevice{name: "qq"}); err != nil { + t.Fatalf("摘除后应可重新注册同名通道，实际: %v", err) + } + // 台账已清空，重复 detach 不应再摘掉新注册的那个 + r.releasePluginChannels("qq") + if iom.GetDevice("qq") == nil { + t.Error("台账已清空，重复 detach 不应摘掉重启后新注册的通道") + } +} + +// 崩溃回调必须摘注册面 + 排重启，且不阻塞调用方（它跑在 readLoop 的 goroutine 里）。 +func TestOnProcCrash_DetachesImmediately(t *testing.T) { + r, cleaner, _ := newTestRegistry(t) + // 没有插件目录 → ReloadOne 必然失败，但摘除动作应已完成 + r.pluginAutoRestart["ghost"] = false // 关掉自动重启，只验摘除 + + done := make(chan struct{}) + go func() { + r.onProcCrash("ghost", errors.New("signal: killed")) + close(done) + }() + + select { + case <-done: + case <-time.After(2 * time.Second): + t.Fatal("onProcCrash 不应阻塞（它在 readLoop 的 goroutine 上）") + } + + if !contains(cleaner.toolCalls(), "ghost") { + t.Error("崩溃后应立即摘除工具，否则模型继续调用一个必然失败的工具") + } + if !contains(cleaner.stageCalls(), "ghost") { + t.Error("崩溃后应摘除 stage handler") + } +} + +// 声明了不自动重启的插件，崩溃后不得被拉起。 +func TestScheduleProcRestart_RespectsAutoRestartOff(t *testing.T) { + r, _, _ := newTestRegistry(t) + r.pluginAutoRestart["noauto"] = false + + r.scheduleProcRestart("noauto", errors.New("boom")) + + if n := r.crashCount("noauto"); n != 0 { + t.Errorf("禁用自动重启时不该记崩溃计数，实际 %d", n) + } +} + +// 窗口内连续崩溃超过上限后停止自动重启，避免崩溃循环打满 CPU。 +func TestScheduleProcRestart_StopsAfterThreshold(t *testing.T) { + r, _, _ := newTestRegistry(t) + + for i := 0; i < procMaxRestarts+2; i++ { + r.noteCrash("loopy") + } + if got := r.crashCount("loopy"); got != procMaxRestarts+2 { + t.Fatalf("崩溃计数应累计，实际 %d", got) + } + + // 超阈值后再调不应尝试重启（无插件目录时重启必然失败并留日志， + // 这里只验它提前返回：计数不再增长）。 + before := r.crashCount("loopy") + r.scheduleProcRestart("loopy", errors.New("again")) + if after := r.crashCount("loopy"); after != before+1 { + t.Errorf("应只记一次计数即返回，before=%d after=%d", before, after) + } +} + +// 崩溃计数在窗口外自动归零，避免偶发崩溃永久累积成“不可重启”。 +func TestNoteCrash_WindowExpiry(t *testing.T) { + r, _, _ := newTestRegistry(t) + + r.noteCrash("old") + r.crashMu.Lock() + r.procCrashes["old"].last = time.Now().Add(-procCrashWindow - time.Second) + r.crashMu.Unlock() + + if got := r.crashCount("old"); got != 0 { + t.Errorf("窗口外计数应归零，实际 %d", got) + } + if got := r.noteCrash("old"); got != 1 { + t.Errorf("窗口外应重新从 1 计，实际 %d", got) + } +} + +// 关停途中不得再拉起插件：段已拆而进程还在会直接 SIGBUS。 +func TestScheduleProcRestart_SkippedDuringShutdown(t *testing.T) { + r, _, _ := newTestRegistry(t) + r.shuttingDown.Store(true) + + r.scheduleProcRestart("any", errors.New("boom")) + + if n := r.crashCount("any"); n != 0 { + t.Errorf("关停中应直接返回，不记计数，实际 %d", n) + } +} + +// PluginRuntime 对未安装插件返回 false，对有目录的插件报告加载通道。 +func TestPluginRuntime_ReportsChannelAndInstallState(t *testing.T) { + r, _, _ := newTestRegistry(t) + + if _, ok := r.PluginRuntime("nope"); ok { + t.Error("未安装插件应返回 false") + } + + dir := filepath.Join(r.plgDir, "procplug") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + bin := filepath.Join(dir, binEntry) + if err := os.WriteFile(bin, []byte("#!/bin/true\n"), 0o755); err != nil { + t.Fatal(err) + } + + info, ok := r.PluginRuntime("procplug") + if !ok { + t.Fatal("有插件目录应视为已安装") + } + if info.Channel != "proc" { + t.Errorf("应识别为 proc 通道，实际 %q", info.Channel) + } + if info.Loaded || info.Alive { + t.Error("未加载的插件不应报告 loaded/alive") + } +} diff --git a/internal/plugin/dynamic_proc_unix.go b/internal/plugin/dynamic_proc_unix.go index 8e62471..20ed3f1 100644 --- a/internal/plugin/dynamic_proc_unix.go +++ b/internal/plugin/dynamic_proc_unix.go @@ -129,23 +129,126 @@ func (r *Registry) closeProcHost() { // **崩溃隔离**：子进程死亡只影响自己，homed 继续服务——对比 C ABI 下 // 插件 panic 直接带崩整个进程（§1.2，现网已发生）。 // -// 崩溃计数/冷却/自愈复用既有 plugin_health（§2.3），本函数只负责把 -// 进程退出这一事实转成事件通知；具体重载策略由 agent 侧决定。 +// 但「homed 没崩」不等于「内核状态干净」。此前本函数只发了一个事件， +// 而全仓没有任何订阅者，于是生产上出现过 editdoc 被 kill 后： +// - `edit_document` 仍留在 StageHost 的工具表里，模型照旧看得到、照旧调用， +// 每次都吃到 `proc: 插件进程已退出`； +// - 该插件的 stage handler 仍在每轮 RunStage 里被并发调起并失败； +// - 没有任何路径把它拉回来，插件永久缺席直到重启 homed。 +// +// 所以崩溃回调必须做三件事：摘注册面、喂健康计数、排一次重启。 func (r *Registry) onProcCrash(name string, err error) { log.Printf("[plugin] 子进程插件 %s 异常退出: %v（homed 未受影响）", name, err) - if r.evBus == nil { + + // 1) 摘掉工具/stage/通道。**必须先做**：从这一刻起模型就不该再看到这些工具， + // 否则在重启完成前的窗口里每次调用都是确定的失败。 + r.detachPlugin(name) + + // 2) 从注册表移除。不做的后果：scheduleProcRestart 里的“已被其他路径重新加载” + // 复核会误判（旧条目还在，See plugins[name] != nil），跳过真正的自动重启。 + // Plugin 对象本身仍被 proc 持有，Kill/回收不受影响。 + r.mu.Lock() + delete(r.plugins, name) + delete(r.sdkRefs, name) + for i, inst := range r.instances { + if inst.Name() == name { + r.instances = append(r.instances[:i], r.instances[i+1:]...) + break + } + } + r.mu.Unlock() + + // 2) 事件通知（webui/诊断插件可订阅）。 + if r.evBus != nil { + r.evBus.Publish(&events.Event{ + Type: events.EventSystem, + Source: "plugin", + Payload: map[string]interface{}{ + "event": "plugin_crashed", + "plugin": name, + "error": err.Error(), + }, + Timestamp: time.Now().Unix(), + }) + } + + // 3) 排一次重启。**必须异步**：本回调由 proc.markExited 在 readLoop 的 + // goroutine 里触发，而 ReloadOne 要拿 registry 锁、还要 Kill 并 join 同一个 + // readLoop（Process.Kill 里 readerWG.Wait），同步调用会自锁死。 + go r.scheduleProcRestart(name, err) +} + +// scheduleProcRestart 在崩溃后按退避重启子进程插件。 +// +// 退避与阈值语义与 agent 侧 plugin_health 对齐（窗口内 3 次即判定不健康）， +// 但重启动作落在 registry：崩溃事实产生于此，agent 的 distillLoop 默认 30 分钟 +// 才转一次（生产实配 2d），靠它兜底等于插件缺席数小时。 +func (r *Registry) scheduleProcRestart(name string, cause error) { + if r.shuttingDown.Load() { + return // 内核正在关停，不再拉起 + } + if !r.AutoRestartEnabled(name) { + log.Printf("[plugin] %s 声明了不自动重启，保持缺席状态", name) return } - // 不在此处直接重载：重载需要 registry 锁，而本回调可能在 - // 持锁路径的 goroutine 中触发，直接调用会死锁。 - r.evBus.Publish(&events.Event{ - Type: events.EventSystem, - Source: "plugin", - Payload: map[string]interface{}{ - "event": "plugin_crashed", - "plugin": name, - "error": err.Error(), - }, - Timestamp: time.Now().Unix(), - }) + + n := r.noteCrash(name) + if n > procMaxRestarts { + log.Printf("[plugin] %s 在 %v 内崩溃 %d 次，停止自动重启（需人工介入）", + name, procCrashWindow, n) + return + } + + // 线性退避：1 次→1s，2 次→2s，3 次→3s。崩溃循环时不至于打满 CPU， + // 又足够快到用户感知不到工具缺席。 + delay := time.Duration(n) * procRestartBackoff + time.Sleep(delay) + + // 期间可能已被 Disable/Remove/手工 plgreload 处理掉，重启前复核。 + if r.shuttingDown.Load() { + return + } + if r.isDisabled(name) { + log.Printf("[plugin] %s 已被禁用，取消自动重启", name) + return + } + r.mu.RLock() + already := r.plugins[name] != nil + r.mu.RUnlock() + if already { + log.Printf("[plugin] %s 已被其他路径重新加载，取消自动重启", name) + return + } + + log.Printf("[plugin] 自动重启 %s（第 %d 次，退避 %v，起因: %v）", name, n, delay, cause) + if err := r.ReloadOne(name); err != nil { + log.Printf("[plugin] %s 自动重启失败: %v", name, err) + return + } + log.Printf("[plugin] %s 自动重启成功", name) +} + +// noteCrash 记录一次崩溃并返回窗口内的累计次数。 +func (r *Registry) noteCrash(name string) int { + now := time.Now() + r.crashMu.Lock() + defer r.crashMu.Unlock() + if r.procCrashes == nil { + r.procCrashes = make(map[string]*procCrashRecord) + } + rec := r.procCrashes[name] + if rec == nil || now.Sub(rec.last) > procCrashWindow { + rec = &procCrashRecord{} + r.procCrashes[name] = rec + } + rec.count++ + rec.last = now + return rec.count +} + +// ResetProcCrashCount 清空某插件的崩溃计数（人工 plgreload / 重新启用后调用）。 +func (r *Registry) ResetProcCrashCount(name string) { + r.crashMu.Lock() + defer r.crashMu.Unlock() + delete(r.procCrashes, name) } diff --git a/internal/plugin/proc/host.go b/internal/plugin/proc/host.go index 5c50955..218a922 100644 --- a/internal/plugin/proc/host.go +++ b/internal/plugin/proc/host.go @@ -45,6 +45,12 @@ type Host struct { stageMu sync.Mutex coordMu sync.Mutex coord *stageCoordinator + + // sup 是内核侧唯一的子进程台账，与共享段同生命周期。 + // + // 放在 Host 而不是 registry 的理由：能拿到 Host 的地方就能拿到台账， + // 而 Host 本就是「全部子进程插件共享的那一份内核侧状态」。 + sup *Supervisor } // NewHost 创建共享段（平台层 allocShm + 布局初始化）。 @@ -81,6 +87,7 @@ func NewHost() (*Host, error) { evtRing.Init() return &Host{ + sup: NewSupervisor(), memfd: memfd, data: data, seg: seg, @@ -102,7 +109,15 @@ func NewHost() (*Host, error) { const shmDefaultSize = 256 * 1024 // Close 释放共享段（StageContext + 事件环）。 +// Supervisor 返回子进程台账（供 registry 查询/关停）。 +func (h *Host) Supervisor() *Supervisor { return h.sup } + func (h *Host) Close() error { + // 先停全部子进程再拆段：插件还持有映射时 unmap， + // 它们下一次访问共享段就是 SIGBUS。 + if h.sup != nil { + h.sup.StopAll(0) + } var firstErr error if h.data != nil { if err := freeShm(h.memfd, h.data); err != nil && firstErr == nil { diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go index 3c99cd3..70a4be9 100644 --- a/internal/plugin/proc/plugin.go +++ b/internal/plugin/proc/plugin.go @@ -6,6 +6,7 @@ import ( "fmt" "log" "sync" + "sync/atomic" pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" ) @@ -43,6 +44,14 @@ type Plugin struct { caps *capabilitySet stopOnce sync.Once + + // stopping 标记「本次退出是内核主动发起的」，用于压掉 onCrash。 + // + // 必要性：Stop() 宽限期超时与 Close() 都走 Process.Kill()， + // 而 Kill 产生的 `signal: killed` 是非 nil 的 waitErr——若不区分， + // 重载/禁用/卸载这些**内核自己发起**的停止会被 handleExit 当成崩溃上报， + // 触发一轮多余的自动重启（重载路径下等于把刚装好的插件又推倒一次）。 + stopping atomic.Bool } // New 创建子进程插件（不启动进程）。 @@ -67,6 +76,31 @@ func New(name, bin, dir string, config map[string]interface{}, host *Host, onCra // Name 实现 sdk.Plugin。 func (p *Plugin) Name() string { return p.name } +// PID 返回子进程号；未启动或已退出返回 0。 +// 供 pluginmgr 呈现「插件实际在跑哪个进程」。 +func (p *Plugin) PID() int { + if p.proc == nil { + return 0 + } + if !p.Alive() { + return 0 + } + return p.proc.PID() +} + +// Alive 报告子进程是否仍存活。 +func (p *Plugin) Alive() bool { + if p.proc == nil { + return false + } + select { + case <-p.proc.Exited(): + return false + default: + return true + } +} + // Start 启动子进程并完成注册。 // // core 是内核为该插件构建的能力面（internal/sdk.PluginSDK 天然满足 CoreSDK）。 @@ -99,6 +133,7 @@ func (p *Plugin) Start(core CoreSDK) error { EvtRingSize: evtTotalSize, Handler: p.handler.Handle, OnExit: p.handleExit, + Supervisor: p.host.Supervisor(), }) if err != nil { return err @@ -124,6 +159,7 @@ func (p *Plugin) Start(core CoreSDK) error { // Stop 优雅停止（实现 sdk.Plugin）。 func (p *Plugin) Stop() error { + p.stopping.Store(true) var err error p.stopOnce.Do(func() { if p.proc != nil { @@ -138,6 +174,7 @@ func (p *Plugin) Stop() error { // **这里是真 kill + wait**——对比 cabi 路径的 Close 只做 dlclose， // 而 dlclose 对 Go c-shared 是 no-op（§1.1，热重载静默失效的根因）。 func (p *Plugin) Close() error { + p.stopping.Store(true) var err error p.stopOnce.Do(func() { if p.proc != nil { @@ -156,6 +193,11 @@ func (p *Plugin) handleExit(name string, err error) { if p.host != nil && p.host.ForceReleaseLock(name) { log.Printf("[proc] %s 退出，内核已释放其持有的 stage 锁", name) } + // 内核主动停止（Stop/Close，含宽限期超时后的 Kill）不算崩溃： + // 否则重载/禁用/卸载都会误触发自动重启。 + if p.stopping.Load() { + return + } if err != nil && p.onCrash != nil { p.onCrash(name, err) } diff --git a/internal/plugin/proc/procattr_linux.go b/internal/plugin/proc/procattr_linux.go new file mode 100644 index 0000000..fff185e --- /dev/null +++ b/internal/plugin/proc/procattr_linux.go @@ -0,0 +1,30 @@ +//go:build linux + +package proc + +import ( + "os/exec" + "syscall" +) + +// applyProcAttr 让子进程在父进程（homed）死亡时收到 SIGKILL。 +// +// 这是**最后一道兜底**，不是主路径：正常关停走 Supervisor.StopAll。 +// 它兜的是内核自身异常终止的场景——homed 被 SIGKILL、段错误、OOM—— +// 此时没有任何 Go 代码有机会运行，Supervisor 也来不及 StopAll， +// 子进程会被 init 收养成孤儿： +// - 继续持有已被 unmap 的共享段映射，下次访问即 SIGBUS； +// - 与新启动的 homed 抢同一份外部资源（qq 的 WS 会话、browser 的 +// chromium profile 锁），表现为"重启后插件时好时坏"。 +// +// Pdeathsig 由内核在父进程退出时投递，不依赖任何用户态代码， +// 因此在 homed 被 SIGKILL 的情况下依然生效。 +// +// 仅 Linux 有此机制。macOS/Windows 无等价物，回退为空实现（procattr_other.go）： +// 那两个平台上孤儿风险依旧存在，靠 StopAll 覆盖正常关停路径。 +func applyProcAttr(cmd *exec.Cmd) { + if cmd.SysProcAttr == nil { + cmd.SysProcAttr = &syscall.SysProcAttr{} + } + cmd.SysProcAttr.Pdeathsig = syscall.SIGKILL +} diff --git a/internal/plugin/proc/procattr_other.go b/internal/plugin/proc/procattr_other.go new file mode 100644 index 0000000..c128d2b --- /dev/null +++ b/internal/plugin/proc/procattr_other.go @@ -0,0 +1,15 @@ +//go:build !linux + +package proc + +import "os/exec" + +// applyProcAttr 在非 Linux 平台是空实现。 +// +// macOS 没有 Pdeathsig（kqueue 的 NOTE_EXIT 要求父进程存活才能监听， +// 恰好在父进程被 SIGKILL 时失效）；Windows 的 Job Object 可做到类似效果， +// 但需要额外的句柄管理，且 Windows 侧尚未真机验证（§12.5），不在此引入。 +// +// 后果：这两个平台上 homed 被强杀时子进程会成为孤儿。 +// 正常关停路径（Supervisor.StopAll）不受影响。 +func applyProcAttr(cmd *exec.Cmd) {} diff --git a/internal/plugin/proc/process.go b/internal/plugin/proc/process.go index 0c04f50..0c5b3d0 100644 --- a/internal/plugin/proc/process.go +++ b/internal/plugin/proc/process.go @@ -36,6 +36,11 @@ type Process struct { stdin *bufio.Writer stdout io.ReadCloser + // stdinFile / stdoutFile 是父进程侧的管道端（手工 os.Pipe，非 cmd.StdinPipe）。 + // 持有它们才能在退出时主动 Close，逼 readLoop 从 Scan 里出来。 + stdinFile *os.File + stdoutFile *os.File + // writeMu 串行化 stdin 写入：NDJSON 帧不能交错，否则对端解析错乱。 writeMu sync.Mutex @@ -48,18 +53,27 @@ type Process struct { // handler 处理插件反向发起的调用（51 个 core.* method）。 handler RequestHandler - // exited 在 readLoop 检测到 EOF/进程退出后关闭，用于唤醒所有等待者。 + // exited 在进程被收割后关闭，用于唤醒所有等待者。 exited chan struct{} exitOnce sync.Once exitErr atomic.Pointer[error] readerWG sync.WaitGroup + waiterWG sync.WaitGroup readyOnce sync.Once ready chan struct{} + // waitErr 由**唯一的** waitLoop 写入：cmd.Wait() 的返回值。 + // waitDone 关闭后 waitErr 才可读。 + waitErr error + waitDone chan struct{} + // onExit 在进程退出时回调（内核用它喂 plugin_health.recordCrash， // 以及 ForceRelease 释放该插件持有的 stage 锁）。 onExit func(name string, err error) + // sup 是内核的集中进程表（可为 nil，单测直接 Spawn 时）。 + sup *Supervisor + // shmSize 是握手时告知插件的共享段大小（0 表示本插件不用共享段）。 shmSize int // evtRingSize 是事件环段大小（0 表示不支持事件环）。 @@ -87,6 +101,8 @@ type Options struct { Handler RequestHandler // OnExit 进程退出回调。 OnExit func(name string, err error) + // Supervisor 是内核的集中进程表；为 nil 时不纳管（单测路径）。 + Supervisor *Supervisor // HandshakeTimeout 建链超时，默认 10s。 HandshakeTimeout time.Duration } @@ -97,6 +113,9 @@ const ( // stopGracePeriod 是发出 plugin.stop 后等待进程自行退出的时间。 // 超时则 Kill——**这是"真正的取消"**，对比 cgo 路径超时后线程永久泄漏。 stopGracePeriod = 5 * time.Second + // killReapTimeout 是 SIGKILL 后等待 waitLoop 收割的上限。 + // 正常情况 wait4 微秒级返回；超过说明卡在不可中断的内核态。 + killReapTimeout = 2 * time.Second ) // ErrProcessExited 表示子进程已退出，调用无法完成。 @@ -120,35 +139,68 @@ func Spawn(name, bin string, opts Options) (*Process, error) { cmd.Env = append(os.Environ(), opts.Env...) } cmd.ExtraFiles = opts.ExtraFiles + applyProcAttr(cmd) - stdinPipe, err := cmd.StdinPipe() + // 管道手工创建而非用 cmd.StdinPipe/StdoutPipe。 + // + // 原因：cmd.Wait() 会等待并**关闭** StdinPipe/StdoutPipe 创建的管道， + // 且文档明确要求“读完再 Wait”。既然现在有一根专职的 waitLoop 立即 + // Wait（不等 readLoop），就必须自己控制管道生命期，否则会与 + // os/exec 的内部关闭竞争，在 readLoop 里读到 "file already closed"。 + stdinR, stdinW, err := os.Pipe() if err != nil { return nil, fmt.Errorf("proc: %s stdin 管道: %w", name, err) } - stdoutPipe, err := cmd.StdoutPipe() + stdoutR, stdoutW, err := os.Pipe() if err != nil { + stdinR.Close() + stdinW.Close() return nil, fmt.Errorf("proc: %s stdout 管道: %w", name, err) } + cmd.Stdin = stdinR + cmd.Stdout = stdoutW p := &Process{ name: name, bin: bin, dir: opts.Dir, cmd: cmd, - stdin: bufio.NewWriter(stdinPipe), - stdout: stdoutPipe, + stdin: bufio.NewWriter(stdinW), + stdout: stdoutR, + stdinFile: stdinW, + stdoutFile: stdoutR, pending: make(map[uint64]chan *Response), handler: opts.Handler, exited: make(chan struct{}), ready: make(chan struct{}), + waitDone: make(chan struct{}), onExit: opts.OnExit, + sup: opts.Supervisor, shmSize: opts.ShmSize, evtRingSize: opts.EvtRingSize, } if err := cmd.Start(); err != nil { + stdinR.Close() + stdinW.Close() + stdoutR.Close() + stdoutW.Close() return nil, fmt.Errorf("proc: 启动 %s (%s): %w", name, bin, err) } + // 子进程已继承它们，父进程侧关掉对端。 + // stdoutW 必须关：否则子进程死后写端仍被父进程持有，readLoop 永不到 EOF。 + stdinR.Close() + stdoutW.Close() + + // 专职收割协程：这是 cmd.Wait() 的**唯一**调用点。 + // + // 为何不能靠 readLoop 的 EOF：EOF 只说明 stdout 写端全部关闭，而插件 + // fork 出去的孙子进程（browser 拉 chromium、editdoc 拉 python）继承着 + // 同一个 stdout：插件本体死了但孙子还持有写端，EOF 就不来， + // 内核完全感知不到插件已死（进程表里是僵尸，注册表里一切正常）。 + // wait 直接盯进程本身，不受 fd 继承影响。 + p.waiterWG.Add(1) + go p.waitLoop() p.readerWG.Add(1) go p.readLoop() @@ -160,6 +212,9 @@ func Spawn(name, bin string, opts Options) (*Process, error) { p.Kill() return nil, err } + if p.sup != nil { + p.sup.track(p) + } return p, nil } @@ -270,22 +325,54 @@ func (p *Process) readLoop() { log.Printf("[proc] %s 读取 stdout 出错: %v", p.name, err) } - // stdout 关闭（EOF）意味着进程结束——2.5ms 内即可感知（实验 6）。 + // stdout 关闭（EOF）通常意味着进程结束——2.5ms 内即可感知（实验 6）。 + // + // 但 EOF **不是**权威信号：插件 fork 的孙子进程继承同一 stdout 写端时， + // 插件本体死了 EOF 也不会到。真正的死亡判定在 waitLoop。 + // 这里只等 waitLoop 的结果（若进程确实已退，它立即就给）。 + <-p.waitDone p.markExited() } -// markExited 回收进程、唤醒所有等待者、触发 onExit 回调。 +// waitLoop 是内核侧**唯一**的 cmd.Wait() 调用点，每个子进程一根。 // -// 这是「把 panic 捕获换成进程退出检测」的落点（§2.3）： -// plugin_health 的 recordCrash / 冷却 / 自愈 / pendingReloads 全部逻辑复用， -// 只是信号源从 recover() 变成进程退出。 +// 为何需要专职协程而不是靠 readLoop 的 EOF： +// 1. **EOF 不等于进程死**。插件用 exec.Command 拉起的孙子进程（browser 拉 +// chromium、editdoc 拉 python）默认继承插件的 stdout。插件被 kill 后 +// 孙子还活着持有写端，readLoop 就永远阻在 Scan 上——内核根本不知道 +// 插件已经死了，工具调用一直超时，自愈也永不触发。 +// 2. **不收割就是僵尸进程**。不调 Wait 的已退出子进程以 Z 状态占着 PID 槽位。 +// 3. **反应速度**。Wait 底层是 wait4(2)，内核侧退出即返回（微秒级）， +// 比任何轮询健康检查都快，也不消耗 CPU。 +func (p *Process) waitLoop() { + defer p.waiterWG.Done() + p.waitErr = p.cmd.Wait() + close(p.waitDone) + + // 主动拆管道：若孙子进程仍持有 stdout 写端，readLoop 不会自己退， + // 关掉读端逼它从 Scan 里出来（报 file already closed，已预期）。 + if p.stdoutFile != nil { + _ = p.stdoutFile.Close() + } + if p.stdinFile != nil { + _ = p.stdinFile.Close() + } + + p.markExited() +} + +// markExited 唤醒所有等待者、触发 onExit 回调（幂等，两条路径可并发调用）。 +// +// 这是「把 panic 捕获换成进程退出检测」的落点（§2.3）。 +// 注意：不在此处调 cmd.Wait()——它属于 waitLoop，Wait 并非并发安全， +// 两处调会报 "wait: no child processes" 或丢失真实退出码。 func (p *Process) markExited() { p.exitOnce.Do(func() { - waitErr := p.cmd.Wait() - if waitErr != nil { - e := fmt.Errorf("插件进程 %s 异常退出: %w", p.name, waitErr) + <-p.waitDone // 保证 waitErr 可读 + if p.waitErr != nil { + e := fmt.Errorf("插件进程 %s 异常退出: %w", p.name, p.waitErr) p.exitErr.Store(&e) - log.Printf("[proc] %s 退出: %v", p.name, waitErr) + log.Printf("[proc] %s 退出: %v", p.name, p.waitErr) } else { log.Printf("[proc] %s 正常退出", p.name) } @@ -305,6 +392,9 @@ func (p *Process) markExited() { } close(p.exited) + if p.sup != nil { + p.sup.untrack(p.name) + } if p.onExit != nil { p.onExit(p.name, p.ExitError()) } @@ -491,11 +581,14 @@ func (p *Process) Kill() error { return nil } err := p.cmd.Process.Kill() - // 等 readLoop 观察到 EOF 并完成 Wait/清理 + // 等 waitLoop 收割完成。不再在此兜底调 markExited： + // cmd.Wait 只能由 waitLoop 调一次，两处调会报 "wait: no child processes"。 select { case <-p.exited: - case <-time.After(2 * time.Second): - p.markExited() // 兜底：极端情况下强制走清理 + case <-time.After(killReapTimeout): + // SIGKILL 后仍未收割：进程卡在不可中断的内核态（D 状态，如 NFS I/O）。 + // 不能无限等，否则重载路径整体挂死；留日志供定位。 + log.Printf("[proc] %s SIGKILL 后 %v 仍未被收割（进程可能卡在内核态）", p.name, killReapTimeout) } p.readerWG.Wait() if err != nil && !errors.Is(err, os.ErrProcessDone) { diff --git a/internal/plugin/proc/process_test.go b/internal/plugin/proc/process_test.go index 50c2893..d931656 100644 --- a/internal/plugin/proc/process_test.go +++ b/internal/plugin/proc/process_test.go @@ -332,3 +332,150 @@ func TestProcess_SpawnRequiresHandler(t *testing.T) { t.Fatal("缺少 Handler 应报错（插件无法回调内核）") } } + +// 插件死亡但孙子进程仍持有 stdout 写端时，内核必须仍能感知退出。 +// +// 这是「EOF 不等于进程死亡」的回归测试。旧实现只在 readLoop 读到 EOF 后 +// 才 markExited，而 exec.Command 起的孙子进程默认继承插件的 stdout： +// 插件本体退出后写端仍被孙子持有，EOF 永不到来，于是 +// - 在途调用挂到自己的超时； +// - OnExit 不触发 → 崩溃计数、工具摘除、自动重启全都不发生； +// - 进程表里插件已是僵尸，注册表里却一切正常。 +// 生产上 browser 拉 chromium、editdoc 拉 python 正是这个形状。 +// 现在由专职 waitLoop 直接 wait4(2) 判定，不再依赖 fd 生命周期。 +func TestProcess_ExitDetectedDespiteInheritedStdout(t *testing.T) { + if _, err := exec.LookPath("sleep"); err != nil { + t.Skip("环境无 sleep，跳过") + } + bin := buildTestPlugin(t, "forkplugin.go") + + exitCh := make(chan error, 1) + p, err := Spawn("fork", bin, Options{ + Handler: noopHandler, + OnExit: func(name string, err error) { exitCh <- err }, + }) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + defer p.Kill() + + // 让插件本体退出（孙子 sleep 300 仍活着，继续持有 stdout 写端） + if _, callErr := p.Call(MethodToolInvoke, ToolInvokeParams{Name: "die"}); callErr == nil { + t.Error("插件退出时在途调用应返回错误") + } + + select { + case exitErr := <-exitCh: + if exitErr == nil { + t.Error("非零退出码应报告为错误（供崩溃计数使用）") + } + case <-time.After(5 * time.Second): + t.Fatal("孙子进程持有 stdout 时未能感知插件退出——退化回只靠 EOF 判定") + } + + if _, err := p.Call(MethodToolInvoke, ToolInvokeParams{Name: "x"}); !errors.Is(err, ErrProcessExited) { + t.Errorf("退出后调用应返回 ErrProcessExited，实际 %v", err) + } +} + +// Supervisor 台账：握手成功即在册，进程退出即注销。 +func TestSupervisor_TrackAndUntrack(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + sup := NewSupervisor() + + p, err := Spawn("echo", bin, Options{Handler: noopHandler, Supervisor: sup}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + if sup.Count() != 1 { + t.Fatalf("握手成功后应在册，实际 %d", sup.Count()) + } + got, ok := sup.Get("echo") + if !ok || got.PID() != p.PID() { + t.Errorf("台账里的进程应是刚 spawn 的那个") + } + list := sup.List() + if len(list) != 1 || !list[0].Alive || list[0].PID != p.PID() { + t.Errorf("List 应报告存活与 PID，实际 %+v", list) + } + + if err := p.Stop(); err != nil { + t.Fatalf("Stop: %v", err) + } + // 退出回调在 markExited 里注销，等它落地 + deadline := time.Now().Add(3 * time.Second) + for sup.Count() != 0 && time.Now().Before(deadline) { + time.Sleep(10 * time.Millisecond) + } + if sup.Count() != 0 { + t.Errorf("进程退出后应注销，实际仍有 %d 个在册", sup.Count()) + } +} + +// StopAll 必须停掉全部在册子进程——内核关停时不留孤儿。 +func TestSupervisor_StopAllLeavesNoSurvivor(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + sup := NewSupervisor() + + var procs []*Process + for i := 0; i < 3; i++ { + p, err := Spawn(fmt.Sprintf("echo%d", i), bin, Options{Handler: noopHandler, Supervisor: sup}) + if err != nil { + t.Fatalf("Spawn %d: %v", i, err) + } + procs = append(procs, p) + } + if sup.Count() != 3 { + t.Fatalf("应有 3 个在册，实际 %d", sup.Count()) + } + + sup.StopAll(5 * time.Second) + + for _, p := range procs { + select { + case <-p.Exited(): + case <-time.After(2 * time.Second): + t.Errorf("%s 未被 StopAll 停掉（会成为孤儿进程）", p.Name()) + } + } +} + +// 卡死插件（不响应 plugin.stop）必须在 StopAll 的预算内被强杀。 +func TestSupervisor_StopAllKillsUnresponsive(t *testing.T) { + bin := buildTestPlugin(t, "hangplugin.go") + sup := NewSupervisor() + + p, err := Spawn("hang", bin, Options{Handler: noopHandler, Supervisor: sup}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + + // 预算给足以覆盖 stopGracePeriod，之后剩下的一律 Kill + sup.StopAll(500 * time.Millisecond) + + select { + case <-p.Exited(): + case <-time.After(10 * time.Second): + t.Error("不响应 plugin.stop 的插件应被强制结束，否则 homed 关停会被它拖住") + } +} + +// 关停后完成握手的进程不得留存：立即被结束，不能活过内核。 +func TestSupervisor_TrackAfterCloseKillsProcess(t *testing.T) { + bin := buildTestPlugin(t, "echoplugin.go") + sup := NewSupervisor() + sup.StopAll(time.Second) // 置 closed + + p, err := Spawn("late", bin, Options{Handler: noopHandler, Supervisor: sup}) + if err != nil { + t.Fatalf("Spawn: %v", err) + } + if sup.Count() != 0 { + t.Errorf("关停后不应再纳管新进程，实际在册 %d", sup.Count()) + } + select { + case <-p.Exited(): + case <-time.After(3 * time.Second): + t.Error("关停后冒出的进程应被立即结束") + } +} diff --git a/internal/plugin/proc/supervisor.go b/internal/plugin/proc/supervisor.go new file mode 100644 index 0000000..9936cac --- /dev/null +++ b/internal/plugin/proc/supervisor.go @@ -0,0 +1,163 @@ +package proc + +import ( + "fmt" + "log" + "sort" + "sync" + "time" +) + +// Supervisor 是内核侧**唯一**的子进程台账。 +// +// 为什么必须有它，而不是让每个 Plugin 各自管好自己的 Process： +// +// 1. **没有台账就没有"全部子进程"这个概念**。内核关停时只能遍历 registry 的 +// 插件表逐个 Stop，而 registry 表是按插件名索引的——握手失败、Start 中途 +// 出错、或刚 spawn 还没进表就崩了的进程，registry 根本不知道它们存在， +// 那些进程会变成孤儿（ppid=1）继续跑，还持有共享段映射。 +// 2. **诊断面缺失**。此前 `/api/manager/status` 之类的接口拿不到"实跑几个子进程、 +// 各自 PID 多少、活了多久、崩过几次"，运维只能 ps | grep。 +// 3. **收割保证**。每个 Process 自带一根 waitLoop 立即 wait4(2)，Supervisor +// 只负责登记/注销与聚合视图；两者配合才能做到"进程一死内核立刻知道"。 +// +// 生命周期：Spawn 成功握手后 track，Process.markExited 里 untrack。 +type Supervisor struct { + mu sync.RWMutex + procs map[string]*Process + // closed 后拒绝新的 track，防止关停竞态里又冒出新进程。 + closed bool +} + +// NewSupervisor 创建空台账。 +func NewSupervisor() *Supervisor { + return &Supervisor{procs: make(map[string]*Process)} +} + +// track 登记一个已握手成功的子进程。 +// +// 同名覆盖是正常情况（重载：旧进程 untrack 早于或晚于新进程 track 都可能， +// 取决于 Kill 与 Spawn 的交错），故不报错，只在真覆盖时留日志。 +func (s *Supervisor) track(p *Process) { + if p == nil { + return + } + s.mu.Lock() + defer s.mu.Unlock() + if s.closed { + // 关停途中还有进程完成握手：立即结束它，不让它活过内核。 + go p.Kill() + return + } + if old, ok := s.procs[p.name]; ok && old != p { + log.Printf("[proc] 台账中 %s 已有 pid=%d，被 pid=%d 覆盖", p.name, old.PID(), p.PID()) + } + s.procs[p.name] = p +} + +// untrack 注销（进程已退出）。只有当表里那一项确实是它时才删， +// 避免重载时新进程被旧进程的退出回调误删。 +func (s *Supervisor) untrack(name string) { + s.mu.Lock() + defer s.mu.Unlock() + delete(s.procs, name) +} + +// Get 按插件名取子进程句柄。 +func (s *Supervisor) Get(name string) (*Process, bool) { + s.mu.RLock() + defer s.mu.RUnlock() + p, ok := s.procs[name] + return p, ok +} + +// Count 返回在册子进程数。 +func (s *Supervisor) Count() int { + s.mu.RLock() + defer s.mu.RUnlock() + return len(s.procs) +} + +// ProcInfo 是单个子进程的运行期快照。 +type ProcInfo struct { + Name string `json:"name"` + PID int `json:"pid"` + Alive bool `json:"alive"` + Bin string `json:"bin"` +} + +// List 返回全部在册子进程的快照（按插件名排序，便于稳定展示）。 +func (s *Supervisor) List() []ProcInfo { + s.mu.RLock() + out := make([]ProcInfo, 0, len(s.procs)) + for name, p := range s.procs { + alive := true + select { + case <-p.Exited(): + alive = false + default: + } + out = append(out, ProcInfo{Name: name, PID: p.PID(), Alive: alive, Bin: p.bin}) + } + s.mu.RUnlock() + sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) + return out +} + +// StopAll 停止全部在册子进程：先并发发 plugin.stop 走优雅路径， +// 到期仍在的一律 Kill。 +// +// 这是内核关停时**必须**调的：不调则子进程被 init 收养成孤儿， +// 继续持有共享段映射（段已被内核 unmap，它们下次访问就是 SIGBUS）， +// 并且下次 homed 启动时同名插件会与残留进程抢同一份外部资源 +// （qq 的 WS 连接、browser 的 chromium profile 锁）。 +func (s *Supervisor) StopAll(timeout time.Duration) { + s.mu.Lock() + s.closed = true + procs := make([]*Process, 0, len(s.procs)) + for _, p := range s.procs { + procs = append(procs, p) + } + s.mu.Unlock() + + if len(procs) == 0 { + return + } + log.Printf("[proc] 关停 %d 个子进程插件", len(procs)) + + var wg sync.WaitGroup + for _, p := range procs { + wg.Add(1) + go func(pr *Process) { + defer wg.Done() + if err := pr.Stop(); err != nil { + log.Printf("[proc] 停止 %s: %v", pr.Name(), err) + } + }(p) + } + + done := make(chan struct{}) + go func() { wg.Wait(); close(done) }() + + if timeout <= 0 { + timeout = stopGracePeriod * 2 + } + select { + case <-done: + case <-time.After(timeout): + // 优雅停止没在预算内完成：剩下的直接 Kill。 + // 不能无限等——homed 关停被单个卡住的插件拖住比杀掉它更糟。 + var stuck []string + for _, p := range procs { + select { + case <-p.Exited(): + default: + stuck = append(stuck, fmt.Sprintf("%s(pid=%d)", p.Name(), p.PID())) + go p.Kill() + } + } + if len(stuck) > 0 { + log.Printf("[proc] %v 内未优雅退出，强制结束: %v", timeout, stuck) + } + } +} diff --git a/internal/plugin/proc/testdata/forkplugin.go b/internal/plugin/proc/testdata/forkplugin.go new file mode 100644 index 0000000..aa768cc --- /dev/null +++ b/internal/plugin/proc/testdata/forkplugin.go @@ -0,0 +1,71 @@ +//go:build ignore + +// forkplugin 在启动时 fork 一个存活时间比自己长的子进程（继承同一个 stdout）， +// 然后在收到 die 工具调用时让自己退出。 +// +// 用途：复现「EOF 不等于进程死亡」这一缺陷。 +// 插件本体死后，孙子进程仍持有 stdout 写端，父进程（homed）的 readLoop +// 永远读不到 EOF——若内核只靠 EOF 判定死亡，就会完全感知不到插件已死： +// 工具调用一直超时、崩溃回调不触发、自动重启永不发生。 +// 生产上 browser 拉 chromium、editdoc 拉 python 都是这个形状。 +package main + +import ( + "bufio" + "encoding/json" + "os" + "os/exec" +) + +type request struct { + ID uint64 `json:"id,omitempty"` + Method string `json:"method"` + Params json.RawMessage `json:"params,omitempty"` +} + +type response struct { + ID uint64 `json:"id"` + Result interface{} `json:"result,omitempty"` + Error string `json:"error,omitempty"` +} + +func main() { + // 孙子进程**只**继承 stdout（本测试的要点），不给 stderr： + // 插件的 stderr 直通到 go test 的捕获管道，孙子抿着它不放会让 + // go test 在测试全部通过后仍等 60s I/O。 + // + // sleep 给 3s：只需在插件本体退出的那一瞬间它还持有写端即可（实际 <200ms）， + // 不必拖得更久而拖慢测试。 + child := exec.Command("sleep", "3") + child.Stdout = os.Stdout + _ = child.Start() + + in := bufio.NewScanner(bufio.NewReader(os.Stdin)) + out := bufio.NewWriter(os.Stdout) + send := func(v interface{}) { + b, _ := json.Marshal(v) + out.Write(b) + out.WriteByte('\n') + out.Flush() + } + + for in.Scan() { + var req request + if err := json.Unmarshal(in.Bytes(), &req); err != nil { + continue + } + switch req.Method { + case "handshake": + send(response{ID: req.ID, Result: map[string]interface{}{ + "protocol": 1, "sdk_version": "test", "plugin_name": "fork", "pid": os.Getpid(), + }}) + case "tool.invoke": + // 不回应答，直接退出：模拟插件突然死亡（崩溃/被 kill）。 + os.Exit(7) + default: + if req.ID != 0 { + send(response{ID: req.ID}) + } + } + } +} diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go index b67adfc..2db1830 100644 --- a/internal/plugin/registry.go +++ b/internal/plugin/registry.go @@ -11,6 +11,8 @@ import ( "sort" "strings" "sync" + "sync/atomic" + "time" agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api" agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io" @@ -59,11 +61,19 @@ func RegisterFactory(name string, factory NativeFactory) { globalFactories.Store(name, factory) } -// PluginToolCleaner 定义插件工具注销接口，由 StageHost 实现。 +// PluginToolCleaner 定义插件注销接口，由 StageHost 实现。 type PluginToolCleaner interface { UnregisterPluginTools(pluginName string) } +// PluginStageCleaner 摘除插件注册的 stage handler，由 StageHost 实现。 +// +// 与 PluginToolCleaner 分开是为了向后兼容：旧 toolCleaner 实现（测试替身） +// 只有 UnregisterPluginTools，经类型断言取 stage 能力，取不到则跳过。 +type PluginStageCleaner interface { + UnregisterPluginStages(pluginName string) int +} + type Registry struct { mu sync.RWMutex plugins map[string]sdk.Plugin @@ -113,6 +123,48 @@ type Registry struct { // lost update 原样复现（§8.4 实测 35.8~36.8%）。 procHostMu sync.Mutex procHost *proc.Host + + // pluginChannels 记录每个插件注册过哪些 IO 通道（输出 device + 输入通道）。 + // + // 不记的后果：子进程插件崩溃后它的 output device 仍在 IOManager 里， + // 模型依旧看到 output_send__ 并调用，只能拿到 ErrProcessExited； + // 重启时 RegisterDevice 又因同名已存在而报 already registered， + // 插件回来了但通道永久指向旧进程的死闭包。 + channelsMu sync.Mutex + pluginChannels map[string]*pluginChannelSet + + // procCrashes 记录子进程插件的崩溃频次，防止崩溃循环无休止重启。 + // + // 与 agent 侧 plugin_health 并存而非重复：后者只能看到工具调用路径上的 + // panic，进程级退出（signal: killed / OOM / 自身 exit）根本不经那里。 + crashMu sync.Mutex + procCrashes map[string]*procCrashRecord + + // shuttingDown 在 StopAll 起始置位，用于冻结自动重启。 + shuttingDown atomic.Bool +} + +// 子进程插件自动重启策略。 +const ( + // procMaxRestarts 是窗口内允许的自动重启次数上限。 + // 超过则停手：再重启也只是重复同一个崩溃，得让人看日志。 + procMaxRestarts = 3 + // procCrashWindow 内无新崩溃则计数归零。 + procCrashWindow = 5 * time.Minute + // procRestartBackoff 是线性退避步长（第 n 次重启前等 n × 此值）。 + procRestartBackoff = time.Second +) + +// procCrashRecord 是单插件的崩溃计数。 +type procCrashRecord struct { + count int + last time.Time +} + +// pluginChannelSet 是单个插件注册过的通道名集合。 +type pluginChannelSet struct { + outputs map[string]bool + inputs map[string]bool } func NewRegistry() *Registry { @@ -123,6 +175,7 @@ func NewRegistry() *Registry { sdkRefs: make(map[string]*sdk.PluginSDK), knownDisabled: make(map[string]bool), pluginHashes: make(map[string]string), + pluginChannels: make(map[string]*pluginChannelSet), } } @@ -219,6 +272,13 @@ func (r *Registry) buildSDK(name string) *sdk.PluginSDK { if regStage == nil { regStage = func(stage sdk.Stage, handler sdk.StageHandler) {} } + // stage handler 注册时带上归属插件名，使卸载/崩溃时能成组摘除。 + // StageHost 实现了 RegisterStageFor；其他实现（测试替身）退回无归属注册。 + if h, ok := r.stageRegistrarFor(); ok { + regStage = func(stage sdk.Stage, handler sdk.StageHandler) { + h(name, stage, handler) + } + } regAPI := r.regAPI if regAPI == nil { regAPI = func(name string) error { return nil } @@ -228,20 +288,25 @@ func (r *Registry) buildSDK(name string) *sdk.PluginSDK { if r.iom == nil { return nil } - return r.iom.RegisterDevice(&channelDevice{ + if err := r.iom.RegisterDevice(&channelDevice{ name: chName, caps: agentIO.OutputCapability(caps), desc: desc, handler: handler, chDef: agentIO.ChannelDef(def), - }) + }); err != nil { + return err + } + r.noteChannel(name, chName, true) + return nil } - regInput := func(name string, def sdk.ChannelDef) error { + regInput := func(chName string, def sdk.ChannelDef) error { if r.iom == nil { return nil } - r.iom.RegisterInputChannel(name, agentIO.ChannelDef(def)) + r.iom.RegisterInputChannel(chName, agentIO.ChannelDef(def)) + r.noteChannel(name, chName, false) return nil } @@ -466,6 +531,92 @@ func (r *Registry) runStopHandlers(name string) { } } +// stageRegistrarFor 取带归属的 stage 注册入口。 +// +// r.regStage 是 cmd/homed 注入的闭包（无插件名参数），而 stageHost 本体同时 +// 以 sdk.ToolSource 存在 r.stageHost 上。能取到 RegisterStageFor 时就直接用它， +// 否则退回无归属注册（测试替身、旧集成方）。 +func (r *Registry) stageRegistrarFor() (func(plugin string, stage sdk.Stage, handler sdk.StageHandler), bool) { + if r.stageHost == nil { + return nil, false + } + if h, ok := r.stageHost.(interface { + RegisterStageFor(plugin string, stage sdk.Stage, handler sdk.StageHandler) + }); ok { + return h.RegisterStageFor, true + } + return nil, false +} + +// noteChannel 记住插件注册了哪个通道，供卸载/崩溃时摘除。 +func (r *Registry) noteChannel(plugin, channel string, output bool) { + if plugin == "" || channel == "" { + return + } + r.channelsMu.Lock() + defer r.channelsMu.Unlock() + set := r.pluginChannels[plugin] + if set == nil { + set = &pluginChannelSet{outputs: map[string]bool{}, inputs: map[string]bool{}} + r.pluginChannels[plugin] = set + } + if output { + set.outputs[channel] = true + } else { + set.inputs[channel] = true + } +} + +// releasePluginChannels 摘除插件注册过的全部 IO 通道，返回摘除的通道名。 +// +// 必须做：不摘除则 ① 模型仍看得到 output_send__ 却永远失败； +// ② 插件重启时 RegisterDevice 报 already registered，新进程的通道注不上， +// 通道永久指向已死进程的闭包。 +func (r *Registry) releasePluginChannels(plugin string) []string { + if plugin == "" { + return nil + } + r.channelsMu.Lock() + set := r.pluginChannels[plugin] + delete(r.pluginChannels, plugin) + r.channelsMu.Unlock() + if set == nil || r.iom == nil { + return nil + } + var released []string + for ch := range set.outputs { + r.iom.UnregisterDevice(ch) + released = append(released, ch) + } + for ch := range set.inputs { + r.iom.UnregisterInputChannel(ch) + if !set.outputs[ch] { + released = append(released, ch) + } + } + sort.Strings(released) + return released +} + +// detachPlugin 把插件在内核侧的全部注册面摸干净：工具 + stage handler + IO 通道。 +// +// 这是「卸载一个插件」的完整含义。之前各路径（Disable/Reload/Remove/ +// StopAndUnload）只调 UnregisterPluginTools，漏了 stage 与通道两项， +// 子进程崩溃路径更是三项都没做。 +func (r *Registry) detachPlugin(name string) { + if r.toolCleaner != nil { + r.toolCleaner.UnregisterPluginTools(name) + if sc, ok := r.toolCleaner.(PluginStageCleaner); ok { + if n := sc.UnregisterPluginStages(name); n > 0 { + log.Printf("[plugin] %s: 摘除 %d 个 stage handler", name, n) + } + } + } + if chans := r.releasePluginChannels(name); len(chans) > 0 { + log.Printf("[plugin] %s: 摘除 IO 通道 %v", name, chans) + } +} + // runOnRemoveHandlers 执行插件注册的删除清理回调（SDK 层），插件 Stop() 之后、从注册表移除前执行。 func (r *Registry) runOnRemoveHandlers(name string) { if sdk, ok := r.sdkRefs[name]; ok { @@ -474,6 +625,10 @@ func (r *Registry) runOnRemoveHandlers(name string) { } func (r *Registry) StopAll() { + // 关停开始即冻结自动重启：否则「Stop 触发退出 → 崩溃判定 → 重新 spawn」 + // 会在内核正在关停时把子进程又拉起来，段已拆而进程还在，直接 SIGBUS。 + r.shuttingDown.Store(true) + r.mu.Lock() for _, p := range r.instances { r.runStopHandlers(p.Name()) @@ -567,6 +722,11 @@ func (r *Registry) ReloadOne(name string) error { } r.mu.Unlock() + // 重载前必须把旧注册面摸干净。不做的后果：loadOne 重新 Start 时 + // RegisterTool 碰上同名旧工具直接报 already registered，新实例的工具一个都注不上； + // stage handler 与 output device 同理——旧闭包指向已死进程，永不退场。 + // （此前只有 agent 的 autoReloadPlugins 在外层手动摸工具，plgreload 路径漏了。） + r.detachPlugin(name) r.closeDynamic(removed) ok := r.loadOne(plgDir, name) @@ -657,9 +817,7 @@ func (r *Registry) Disable(name string) error { r.knownDisabled[name] = true r.mu.Unlock() - if r.toolCleaner != nil { - r.toolCleaner.UnregisterPluginTools(name) - } + r.detachPlugin(name) if r.cfgReg != nil { r.cfgReg.AddDisabledPlugin(name, "system") @@ -767,9 +925,7 @@ func (r *Registry) DisablePlugin(name, by string) error { r.knownDisabled[name] = true r.mu.Unlock() - if r.toolCleaner != nil { - r.toolCleaner.UnregisterPluginTools(name) - } + r.detachPlugin(name) if r.cfgReg != nil { r.cfgReg.AddDisabledPlugin(name, by) @@ -804,9 +960,7 @@ func (r *Registry) StopAndUnload(name string) error { } r.mu.Unlock() - if r.toolCleaner != nil { - r.toolCleaner.UnregisterPluginTools(name) - } + r.detachPlugin(name) r.closeDynamic(unloaded) log.Printf("[plugin] unloaded (config kept): %s", name) return nil @@ -837,9 +991,7 @@ func (r *Registry) RemovePlugin(name string) error { r.runOnRemoveHandlers(name) r.mu.Unlock() - if r.toolCleaner != nil { - r.toolCleaner.UnregisterPluginTools(name) - } + r.detachPlugin(name) if r.cfgReg != nil { r.cfgReg.RemoveDisabledPlugin(name) r.cfgReg.RemovePlugin(name) @@ -851,6 +1003,98 @@ func (r *Registry) RemovePlugin(name string) error { func (r *Registry) ReloadPlugins() (string, error) { return r.Reload(r.plgDir) } +// PluginRuntime 返回单个插件的运行期状态。 +// +// 这是「插件管理器能看到真实死活」的数据源。子进程模型下， +// 「注册表里有条目」不等于「进程还活着」；只读 plugin.json 的旧实现 +// 无法区分两者，插件被 kill 后 WebUI 仍显示“正常”。 +func (r *Registry) PluginRuntime(name string) (sdk.PluginRuntimeInfo, bool) { + if name == "" { + return sdk.PluginRuntimeInfo{}, false + } + + r.mu.RLock() + plg, loaded := r.plugins[name] + _, hasFactory := r.factories[name] + r.mu.RUnlock() + if !hasFactory { + _, hasFactory = globalFactories.Load(name) + } + + installed := loaded || hasFactory + var dirExists bool + if r.plgDir != "" { + if st, err := os.Stat(filepath.Join(r.plgDir, name)); err == nil && st.IsDir() { + dirExists = true + installed = true + } + } + if !installed { + return sdk.PluginRuntimeInfo{}, false + } + + info := sdk.PluginRuntimeInfo{ + Name: name, + Loaded: loaded, + Disabled: r.isDisabled(name), + Builtin: hasFactory, + AutoRestart: r.AutoRestartEnabled(name), + CrashCount: r.crashCount(name), + } + + switch { + case hasFactory: + info.Channel = "builtin" + case dirExists: + info.Channel = detectEntryKind(filepath.Join(r.plgDir, name)).String() + } + + // 子进程插件报真实 PID 与存活；其余形态与 Loaded 同值（无独立进程）。 + type procStatus interface { + PID() int + Alive() bool + } + if ps, ok := plg.(procStatus); ok && loaded { + info.PID = ps.PID() + info.Alive = ps.Alive() + } else { + info.Alive = loaded + } + + if r.stageHost != nil { + for _, def := range r.stageHost.GetToolDefs() { + if def.Plugin == name { + info.Tools = append(info.Tools, def.Name) + } + } + sort.Strings(info.Tools) + } + return info, true +} + +// ListPluginRuntimes 返回全部已知插件的运行期状态（含已安装未加载者）。 +func (r *Registry) ListPluginRuntimes() []sdk.PluginRuntimeInfo { + names := r.ListKnown() + out := make([]sdk.PluginRuntimeInfo, 0, len(names)) + for _, name := range names { + if info, ok := r.PluginRuntime(name); ok { + out = append(out, info) + } + } + return out +} + +// crashCount 读取窗口内的崩溃计数（过期视为 0）。 +func (r *Registry) crashCount(name string) int { + r.crashMu.Lock() + defer r.crashMu.Unlock() + rec := r.procCrashes[name] + if rec == nil || time.Since(rec.last) > procCrashWindow { + return 0 + } + return rec.count +} + // ListKnown 返回所有已知插件（已加载 + 已禁用 + 已安装但未加载）。 func (r *Registry) ListKnown() []string { r.mu.RLock() diff --git a/internal/plugins/pluginmgr/plugin.go b/internal/plugins/pluginmgr/plugin.go index 9ecf0a0..6ad8ff4 100644 --- a/internal/plugins/pluginmgr/plugin.go +++ b/internal/plugins/pluginmgr/plugin.go @@ -14,6 +14,7 @@ import ( "os" "path/filepath" "runtime" + "sort" "strconv" "strings" "sync" @@ -163,7 +164,7 @@ func (p *Plugin) registerTools(s *sdk.PluginSDK) { s.RegisterTool("plugin_list", sdk.ToolDef{ Name: "plugin_list", - Description: "列出已安装的所有外部插件及其版本", + Description: "列出已安装的所有外部插件及其版本。同时返回运行状态（loaded/alive/pid/崩溃次数），子进程插件死了在此体现为 alive=false。", Parameters: map[string]interface{}{ "type": "object", "properties": map[string]interface{}{}, @@ -172,6 +173,46 @@ func (p *Plugin) registerTools(s *sdk.PluginSDK) { return p.listPlugins() }) + s.RegisterTool("plugin_status", sdk.ToolDef{ + Name: "plugin_status", + Description: "查看插件运行状态：进程是否存活、PID、加载通道、最近崩溃次数、当前注册的工具。" + + "不传 name 则返回全部插件概览。工具调不通时先用它确认插件是否还活着。", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "name": map[string]interface{}{ + "type": "string", + "description": "插件名称；缺省返回全部", + }, + }, + }, + }, func(args map[string]interface{}) (interface{}, error) { + name, _ := args["name"].(string) + return p.pluginStatus(name) + }) + + s.RegisterTool("plugin_restart", sdk.ToolDef{ + Name: "plugin_restart", + Description: "重启单个插件（停止后重新加载，保留配置）。适用于：插件进程已死但自动重启被用尽" + + "（plugin_status 的 crash_count 达上限），或换了 plugin.bin 需立即生效。不需重启 homed。", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "name": map[string]interface{}{ + "type": "string", + "description": "插件名称", + }, + }, + "required": []string{"name"}, + }, + }, func(args map[string]interface{}) (interface{}, error) { + name, _ := args["name"].(string) + if name == "" { + return map[string]interface{}{"error": "name is required"}, nil + } + return p.restartPlugin(name) + }) + s.RegisterTool("plugin_remove", sdk.ToolDef{ Name: "plugin_remove", Description: "卸载一个已安装的外部插件", @@ -540,6 +581,18 @@ func (p *Plugin) listPlugins() (interface{}, error) { return nil, err } + // 运行期状态一次取齐，避免逐个插件回内核查。 + // + // 为何要带运行期：只读 plugin.json 的旧实现无法区分「已安装」与「正在跑」。 + // 生产上 editdoc 子进程被 kill 后，plugin_list 依旧把它列为正常插件， + // 模型与 WebUI 都看不出异常，只能在调工具时吃一个“进程已退出”。 + runtimes := map[string]sdk.PluginRuntimeInfo{} + if mgr := p.pluginMgr(); mgr != nil { + for _, rt := range mgr.ListPluginRuntimes() { + runtimes[rt.Name] = rt + } + } + var plugins []map[string]interface{} for _, entry := range entries { if !entry.IsDir() { @@ -549,14 +602,27 @@ func (p *Plugin) listPlugins() (interface{}, error) { if err != nil { continue } - plugins = append(plugins, map[string]interface{}{ + item := map[string]interface{}{ "name": m.Name, "version": m.Version, "description": m.Description, "author": m.Author, "entry": m.Entry, "deprecated": m.Deprecated, - }) + } + if rt, ok := runtimes[m.Name]; ok { + item["loaded"] = rt.Loaded + item["alive"] = rt.Alive + item["disabled"] = rt.Disabled + item["channel"] = rt.Channel + if rt.PID > 0 { + item["pid"] = rt.PID + } + if rt.CrashCount > 0 { + item["crash_count"] = rt.CrashCount + } + } + plugins = append(plugins, item) } if plugins == nil { plugins = []map[string]interface{}{} @@ -564,6 +630,84 @@ func (p *Plugin) listPlugins() (interface{}, error) { return plugins, nil } +// pluginMgr 取内核插件管理面（可能为 nil：单测/未注入）。 +func (p *Plugin) pluginMgr() sdk.PluginManager { + if p.sdk == nil { + return nil + } + return p.sdk.PluginMgr() +} + +// pluginStatus 返回插件运行期状态（进程存活/PID/崩溃计数/工具清单）。 +// +// 这是子进程化后插件管理器必须补上的一块：以前插件与内核同进程， +// “加载了”就等于“能用”；现在插件是独立进程，两者不再等价。 +func (p *Plugin) pluginStatus(name string) (interface{}, error) { + mgr := p.pluginMgr() + if mgr == nil { + return nil, fmt.Errorf("内核插件管理面不可用") + } + if name != "" { + info, ok := mgr.PluginRuntime(name) + if !ok { + return nil, fmt.Errorf("plugin %q not found", name) + } + return info, nil + } + + all := mgr.ListPluginRuntimes() + // 汇总一行：让模型不用自己数就能看出“有东西挂了”。 + var loaded, dead int + var unhealthy []string + for _, rt := range all { + if rt.Loaded { + loaded++ + } + if rt.Loaded && !rt.Alive { + dead++ + unhealthy = append(unhealthy, rt.Name) + continue + } + if rt.CrashCount > 0 { + unhealthy = append(unhealthy, fmt.Sprintf("%s(崩溃%d次)", rt.Name, rt.CrashCount)) + } + } + sort.Strings(unhealthy) + return map[string]interface{}{ + "total": len(all), + "loaded": loaded, + "dead": dead, + "unhealthy": unhealthy, + "plugins": all, + }, nil +} + +// restartPlugin 重启单个插件（保留配置）。 +// +// 与 plgreload 的区别：后者按入口文件 hash 增量重载，二进制没改就不动； +// 而进程被 kill 时二进制正是没改的，所以一定要有一个无条件重启的入口。 +func (p *Plugin) restartPlugin(name string) (interface{}, error) { + mgr := p.pluginMgr() + if mgr == nil { + return nil, fmt.Errorf("内核插件管理面不可用") + } + if _, ok := mgr.PluginRuntime(name); !ok { + return nil, fmt.Errorf("plugin %q not found", name) + } + if mgr.IsPluginDisabled(name) { + return nil, fmt.Errorf("plugin %s 已被禁用，请先启用再重启", name) + } + if err := mgr.ReloadOne(name); err != nil { + return nil, fmt.Errorf("restart %s: %w", name, err) + } + info, _ := mgr.PluginRuntime(name) + return map[string]interface{}{ + "status": "restarted", + "name": name, + "runtime": info, + }, nil +} + func (p *Plugin) removePlugin(name string) (interface{}, error) { // 内置插件只能禁用不能卸载：目录下无产物，且从注册表删除会破坏内核依赖。 if p.sdk != nil && p.sdk.PluginMgr() != nil && p.sdk.PluginMgr().IsBuiltinPlugin(name) { diff --git a/internal/plugins/pluginmgr/upgrade_test.go b/internal/plugins/pluginmgr/upgrade_test.go index 063ac4f..2fafc1c 100644 --- a/internal/plugins/pluginmgr/upgrade_test.go +++ b/internal/plugins/pluginmgr/upgrade_test.go @@ -81,6 +81,10 @@ func (f *fakePluginMgr) PluginMetas() map[string]sdk.PluginMeta { return map[string]sdk.PluginMeta{} } func (f *fakePluginMgr) PluginDir() string { return "" } +func (f *fakePluginMgr) PluginRuntime(string) (sdk.PluginRuntimeInfo, bool) { + return sdk.PluginRuntimeInfo{}, false +} +func (f *fakePluginMgr) ListPluginRuntimes() []sdk.PluginRuntimeInfo { return nil } // buildHmap 构造一个最小 .hmap 包。 func buildHmap(t *testing.T, name, version string) []byte { diff --git a/internal/plugins/webui/handler_plugin_test.go b/internal/plugins/webui/handler_plugin_test.go index e768ddd..d911e4f 100644 --- a/internal/plugins/webui/handler_plugin_test.go +++ b/internal/plugins/webui/handler_plugin_test.go @@ -13,6 +13,7 @@ type mockPluginMgr struct { builtins map[string]bool disabled []sdk.DisabledPluginInfo isDisabled map[string]bool + runtimes map[string]sdk.PluginRuntimeInfo removed []string reloadN int @@ -57,6 +58,17 @@ func (m *mockPluginMgr) PluginMetas() map[string]sdk.PluginMeta { return nil } func (m *mockPluginMgr) PluginDir() string { return "" } +func (m *mockPluginMgr) PluginRuntime(name string) (sdk.PluginRuntimeInfo, bool) { + info, ok := m.runtimes[name] + return info, ok +} +func (m *mockPluginMgr) ListPluginRuntimes() []sdk.PluginRuntimeInfo { + out := make([]sdk.PluginRuntimeInfo, 0, len(m.runtimes)) + for _, v := range m.runtimes { + out = append(out, v) + } + return out +} // newHandlerWithMock 构造带 mock PluginManager 的 Handler（绕过 SDK 组装）。 func newHandlerWithMock(m *mockPluginMgr) *Handler { diff --git a/internal/sdk/plugin.go b/internal/sdk/plugin.go index a76789a..7396f6d 100644 --- a/internal/sdk/plugin.go +++ b/internal/sdk/plugin.go @@ -65,6 +65,34 @@ type PluginMeta struct { NameEn string `json:"name_en"` } +// PluginRuntimeInfo 是插件的**运行期**状态，与 plugin.json 里的静态元数据相对。 +// +// 为何需要：子进程插件的进程可能已经死了而注册表里还有条目（或反过来， +// 崩溃摘除后注册表已无条目但目录还在）。此前 plugin_list / GET /plugins +// 只读 plugin.json，无论插件死活都返回同一份内容——WebUI 与模型都看不出 +// 「已安装」与「正在运行」的区别，插件被 kill 后只表现为工具静默失败。 +type PluginRuntimeInfo struct { + Name string `json:"name"` + // Loaded 表示注册表中存在该插件实例。 + Loaded bool `json:"loaded"` + // Disabled 表示插件被显式禁用（不该运行）。 + Disabled bool `json:"disabled"` + // Builtin 表示编译期内置插件（无独立进程）。 + Builtin bool `json:"builtin"` + // Channel 是加载通道：proc（子进程）/ lua / builtin。 + Channel string `json:"channel"` + // PID 是子进程插件的进程号；非子进程或已退出为 0。 + PID int `json:"pid"` + // Alive 表示子进程仍存活；非子进程插件与 Loaded 同值。 + Alive bool `json:"alive"` + // CrashCount 是最近窗口内的崩溃次数（0 表示健康）。 + CrashCount int `json:"crash_count"` + // AutoRestart 表示崩溃后内核是否会自动拉起。 + AutoRestart bool `json:"auto_restart"` + // Tools 是该插件当前注册在内核里的工具名。 + Tools []string `json:"tools,omitempty"` +} + type PluginManager interface { ListLoadedPlugins() []string ListDisabledPlugins() []DisabledPluginInfo @@ -86,6 +114,11 @@ type PluginManager interface { ReloadOne(name string) error PluginMetas() map[string]PluginMeta PluginDir() string + // PluginRuntime 返回单个插件的运行期状态（进程存活 / PID / 崩溃计数）。 + // 未安装的插件返回零值 + false。 + PluginRuntime(name string) (PluginRuntimeInfo, bool) + // ListPluginRuntimes 返回全部已加载插件的运行期状态。 + ListPluginRuntimes() []PluginRuntimeInfo } type PluginSDK struct {