- 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。
4.0 KiB
Executable File
4.0 KiB
Executable File
变更记录:插件 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 |
本文件 |