Files
marqdo/doc/design/change-plugin-sdk.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

4.0 KiB
Executable File
Raw Blame History

变更记录:插件 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 本文件