新增工作区成员 crates/marqdo-plugin-sdk:ABI 类型、HOST_* 静态回调、 host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/ take_host_string/init_plugin,以及生成四个 #[no_mangle] 导出的 marqdo_plugin! 宏。ABI 常量、符号名、结构体布局一律未变。 5 个插件改为依赖 SDK + 一行宏调用: agent 1237 → 929 (-308) quantum 1045 → 835 (-210) linalg 688 → 524 (-164) llm 405 → 278 (-127) demo 170 → 73 (-97) SDK 新增 232 行 → 净减约 674 行 迁移中发现并修正三次"编译通过但语义已变": 1. 注册项抽取漏 11 项 —— 正则 [a-z_0-9]+ 匹配不到 mcp_server::agent_mcp_serve、 sandbox::* 这类路径限定函数名;改为允许 :: 后重抽。 已用脚本逐项比对 (名称, 参数串, 函数) 三元组:agent 63/63、quantum 41/41、 linalg 31/31、llm 2/2、demo 2/2,全部 0 差异。 2. mcp_client 被误判死模块(删 327 行后才发现 agent_mcp_client 正注册它)→ 恢复。 3. 量子插件两个"未使用"函数删除时连带吃掉 density_from_amps/flat_to_nested → 恢复原文件并改为 #[allow(dead_code)]。 验证:cargo build --release(含 5 个插件)零警告; cargo test --release 609 passed / 0 failed; 量子金样实跑 p00-ok / p11-ok / ping-ok。 文档:doc/design/change-plugin-sdk.md
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Implemented** |
|
||
| 日期 | 2026-10-22 |
|
||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
|
||
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
|
||
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
|
||
|
||
---
|
||
|
||
## 1. 问题
|
||
|
||
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
|
||
|
||
| 复制的内容 | 说明 |
|
||
|-----------|------|
|
||
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
|
||
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
|
||
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
|
||
| `register` + `#[no_mangle]` 四导出 | 样板 |
|
||
|
||
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
|
||
|
||
## 2. 方案
|
||
|
||
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
|
||
|
||
```rust
|
||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||
("llm_ping", "", llm_ping),
|
||
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
|
||
]);
|
||
```
|
||
|
||
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
|
||
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
|
||
|
||
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
|
||
|
||
## 3. 安全措施:注册项逐一核对
|
||
|
||
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
|
||
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
|
||
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
|
||
|
||
补救:正则允许 `::`,并把新旧两张表逐项比对:
|
||
|
||
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|
||
|------|------------|--------|------|
|
||
| agent | 63 | 63 | **0** |
|
||
| quantum | 41 | 41 | 0 |
|
||
| linalg | 31 | 31 | 0 |
|
||
| llm | 2 | 2 | 0 |
|
||
| demo | 2 | 2 | 0 |
|
||
|
||
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
|
||
|
||
另外两次由"编译通过但语义已变"暴露的问题:
|
||
|
||
| 问题 | 现象 | 处理 |
|
||
|------|------|------|
|
||
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
|
||
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
|
||
|
||
## 4. 收益
|
||
|
||
| 插件 | 迁移前 | 迁移后 | 变化 |
|
||
|------|--------|--------|------|
|
||
| agent | 1,237 | 929 | −308 |
|
||
| quantum | 1,045 | 835 | −210 |
|
||
| linalg | 688 | 524 | −164 |
|
||
| llm | 405 | 278 | −127 |
|
||
| demo | 170 | 73 | −97 |
|
||
| 新增 SDK | — | 232 | +232 |
|
||
|
||
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
|
||
|
||
## 5. 验证
|
||
|
||
| 项 | 结果 |
|
||
|----|------|
|
||
| `cargo build --release`(含 5 个插件) | 零警告 |
|
||
| `cargo test --release` | **609 passed / 0 failed** |
|
||
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
|
||
| 注册项三元组比对 | 5 个插件全部 0 差异 |
|
||
|
||
## 6. 边界
|
||
|
||
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
|
||
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
|
||
- 后续新增插件只需依赖 SDK + 一行宏调用。
|
||
|
||
## 7. 变更清单
|
||
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
|
||
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
|
||
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
|
||
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
|
||
| `doc/design/change-plugin-sdk.md` | 本文件 |
|