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