新增工作区成员 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
4.0 KiB
4.0 KiB
变更记录:插件 ABI 共享 crate(marqdo-plugin-sdk)
| 状态 | Implemented |
| 日期 | 2026-10-22 |
| 来源 | 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 必需的导出:
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 |
本文件 |