mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-21 09:28:14 +00:00
docs: Part 6.6 文档收尾 —— 迁移计划/接口矩阵/PLUGIN_DEV 全量更新
## 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 处），其余全部清理。
This commit is contained in:
JianFeeeee
@ -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 <mod@path> # 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.<goos>.<goarch>`;
|
||||
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 |
|
||||
|-----------|-----------|
|
||||
|
||||
@ -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 <mod@path> # 追加 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 <mod@path> # 追加 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.<goos>.<goarch>` 区分各平台，安装时内核挑当前平台
|
||||
那份重命名为 `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)`）**
|
||||
|
||||
| 子表 | 函数 |
|
||||
|------|------|
|
||||
|
||||
Reference in New Issue
Block a user