Files
ViewDesignEngine/docs/design/plugin-ecosystem-handoff.md
hm e27068f828 feat(P4-11): 插件 ABI 1.5 optimizer + io_batch 扩展点(1.0.83)
### ABI 1.5
- VDE_PLUGIN_ABI_MINOR 5;VdePluginKind OPTIMIZER=9/IO_BATCH=10;
  VdeOptimizer*/VdeIoBatch* 结构(JSON 输入输出回调);VdePluginRegistration 尾追加两指针 56→72B(offset 56/64),
  旧 1.0–1.4 按 struct_size 安全加载、新 kind 结构不足拒绝;
- PluginManager:OptimizerInfo/IoBatchInfo、optimizers()/invoke_optimizer、io_batches()/invoke_io_batch、
  校验/失败隔离/卸载清理(IO_BATCH 支持 PARTIAL);
- sample_optimizer/sample_io_batch(mock);ABI 矩阵 1.0–1.5 accepted=6+2.0 rejected;--abi/--check 适配;
- test_plugin_abi15 6/6 + fixtures;既有 ABI 1.4 断言适配;
- 文档 plugin-development §16/§17、plugin-distribution ABI 矩阵、plugin-ecosystem-handoff/ecosystem、plugin-ci-template;

### WP/claim
- WP-P4-11 交付并移入 Delivered;claim Released 归档;统计 42=31 Delivered+11 Candidate;
- claim check 修正:Released claim 可指向 Delivered WP(仅 Active 需要释放);

### 工程
- 版本 1.0.83;全量构建 0 error(421 targets);全量 ctest 7576 注册、7481/7481 PASS(0 failed,25 skipped,302.66s);
- 收录 1.0.82 独立验证报告 80。
2026-10-29 18:44:12 +08:00

17 KiB
Raw Permalink Blame History

插件生态团队交接与规划(P4)

读者:插件生态团队(T6)及协作方(内核 T1、CAE/CAM T3、宿主集成 T7、验证发布 T8)。 目的:把 1.0.78 已交付的插件 SDK/ABI/分发能力交接给生态团队,并给出 ABI 1.4/1.5、SDK、分发、 认证/评审、市场/远程仓库 的演进规划与边界(1.5 optimizer/io_batch 已交付,见 §3.6)。

配套:插件架构、插件安全、 插件分发指南、发布者指南、 插件 CI 模板、多团队体系、 工作包目录(WP-P4-01/07/08/11)。


1. 交接范围与团队边界

资产 路径 交接后 owner 协作方
插件 ABI 头 include/vde/plugin/vde_plugin_api.h T6 T1(内核消费者/ABI 评审)、T8(ABI 矩阵验证)
插件管理器/安全/外部服务 include/vde/plugin/**, src/plugin/** T6 T3(求解器实现)、T7(宿主服务)
插件工具链 tools/vde_plugin_tool/** T6 T7(构建/CI)
SDK/模板/示例插件 sdk/vde-plugin-sdk/**, plugins/templates/**, plugins/sample_*, plugins/official/**(格式插件归 T2) T6(格式插件 T2) T2/T3
分发/签名/索引 工具 + docs/guides/plugin-distribution.md T6 T8(安全验证)、宿主安装器
发布者指南/CI 模板 docs/guides/plugin-publishing.md, plugin-ci-template.md T6 T7(CI runner)、T8(独立复核)
宿主几何服务表 include/vde/plugin/geometry_host_services.h, 实现 T7 T6(ABI 契约)、T1(几何能力)

边界规则:

  1. 生态团队可独立修改插件 ABI 的尾扩展与工具/文档,但 ABI 变更须 T1 评审 + T8 ABI 矩阵验证;
  2. 内核 ABI(vde::kernel/C API)由 T1 拥有,生态团队只读;需要内核新能力时提「接口请求」WP;
  3. 格式插件(STL/OBJ/PLY/STEP/IGES/DXF)的格式语义归 T2,插件壳/构建归 T6,变更需双 owner 评审;
  4. CAE/CAM/GCS/mesher 扩展点的算法/语义归 T3,ABI 结构与生命周期归 T6。

2. 现状交接清单(1.0.78 基线 → 当前 ABI 1.5)

2.1 ABI 与扩展点

  • 当前主线 ABI 1.5:format、CAE solver、CAM strategy、GCS solver(1.3)、Mesher(1.4)、 Optimizer + IO_BATCH(1.5)扩展点;VdePluginHost 宿主服务表;
  • 兼容规则:宿主接受 major 相等 && plugin.minor <= host.minor;结构 struct_size 尾扩展(注册结构 1.4=56B、1.5=72B);枚举只追加;
  • ABI 矩阵:宿主 1.5 接受插件 1.0–1.5、拒绝 2.0(plugins/abi_matrix + vde_plugin_abi_matrix smoke);
  • 旧插件(1.0–1.4)在新宿主不重编可用(CI/矩阵覆盖)。

2.2 SDK / 模板 / 工具

能力 入口 证据
独立 SDK 包(纯 C 头 + vde::plugin-sdk) cmake --install --component vde-plugin-sdk;find_package(vde-plugin-sdk CONFIG) 验证报告 74 §4.2;CTest VDE_PluginSdkConsumerSmoke
四类模板(format/cae/cam/gcs) plugins/templates/**(独立 CMake,不加入默认构建) 模板 README/文档 §14
scaffold vde_plugin_tool scaffold <kind> <name> --out CTest VDE_PluginToolScaffoldSmoke
自检/诊断 --check/--list/--inspect/--abi 工具帮助与文档
索引/签名/安装 --gen-keypair/--build-index/--verify-index/--install/--fetch-index/--fetch-packages/--uninstall/--upgrade/--revoked-keys 验证报告 74 §4.3
发布/CI 指导 docs/guides/plugin-publishing.md、plugin-ci-template.md 验证报告 74 §4.4

2.3 已知限制(交接时明确)

  1. 进程内插件无强隔离:校验与 dlopen 之间有 TOCTOU 窗口;无 OS Authenticode(P4-08 候选);
  2. 吊销文件需宿主/安装器分发(工具 --revoked-keys 消费,无在线 CRL/自动刷新);
  3. 远程仓库服务器/索引自动刷新/增量更新未实现(工具支持 fetch/index/install/upgrade,P4-07 候选);
  4. 官方格式插件仅导入为主;STEP/IGES 写与 3MF/glTF 导出为 P4-06 候选;
  5. Python 绑定 ctypes 路径可用,pybind 跨平台/packaging 为 P4-12 候选;
  6. 真实 MSVC/Linux CI 首跑待完成(P4-10),当前基准平台为 MinGW UCRT/Linux GCC。

3. ABI 1.4 交付:mesher 扩展点(WP-P4-01,1.0.79 已交付)

3.1 动机

  • 外部生态团队需要提供网格生成插件(面网格/体网格/FEA),当前只能走 CAE 求解器或外部服务;
  • 在 ABI 1.3 基础上做尾扩展,保持 1.0–1.3 旧插件二进制兼容(不重编可用)。

3.2 契约设计(原则)

  1. VDE_PLUGIN_ABI_MINOR 1.3 → 4;VDE_PLUGIN_ABI_MAJOR 仍为 1;
  2. VdePluginKind 追加 MESHER = 8(只追加,不改变旧值);
  3. VdePluginRegistration 尾部追加 mesher 指针:struct_size 48 → 56;旧插件 struct_size=48 时宿主 按 0/未提供处理(安全);
  4. 新增纯 C 结构(均首字段 struct_size、版本/名称、回调/错误码): VdeMesherPlugin、VdeMesherOptions、VdeMesherRequest、VdeMesherResult、VdeMesherStatus;
  5. 输入/输出:沿用现有 host services/句柄模式(B-Rep/网格经宿主句柄或请求/响应文件),不引入 C++/STL 类型;
  6. 生命周期/错误:init/query 与其它 kind 一致;mesher 调用返回状态码 + 错误字符串;复用现有超时/隔离机制;
  7. 能力 ID:mesher:<vendor>.<feature>(与 kind 前缀规则一致)。

3.3 兼容矩阵(1.4 宿主)

宿主 ABI \ 插件 ABI 1.0 1.1 1.2 1.3 1.4 2.0
1.4 ✅ ✅ ✅ ✅ ✅ ❌
1.3(旧宿主) ✅ ✅ ✅ ✅ ❌(minor 大于宿主) ❌

3.4 交付内容(DoD)

  • 头文件/尺寸/枚举/注册表尾扩展;
  • PluginManager:扫描/校验(ABI 1.0–1.4、struct_size、kind)、mesher 查询/调用(错误/超时/隔离复用);
  • plugins/sample_mesher/**(CMake/manifest/README/最小实现,默认不加入主构建);
  • ABI 矩阵更新(接受 1.4/拒绝 2.0;vde_plugin_abi_matrix 覆盖);
  • 测试:1.4 注册、1.3 旧插件兼容、sample 调用、错误路径、二进制布局断言;
  • vde_plugin_tool --abi/--check 适配;文档:plugin-development ABI 1.4 节、plugin-distribution 兼容矩阵;
  • 证据:默认 build 0 error、ABI/插件测试全绿、独立验证(T8)、验证报告/版本由 Lead 收口。

3.5 风险与开放问题

风险 缓解
旧插件二进制布局/struct_size 误用 只追加尾部字段;旧尺寸判空;ABI 矩阵回归
网格数据跨 ABI 传递(体积/大数组) 优先句柄/文件路径;限制单次输出预算;文档明确内存所有权
宿主服务在 kernel-only/无几何服务时不可用 mesher 插件 init 时校验必需服务;错误码明确
与 CAE 求解器扩展点职责重叠 文档定义边界:mesher 只产网格,求解由 CAE solver 消费
1.4 发布后旧宿主拒绝新插件 兼容矩阵/发布说明;需要旧宿主时按 1.3 构建发布

3.6 ABI 1.5 交付:optimizer / io_batch 扩展点(task-115,P4)

ABI 1.4 → 1.5 尾扩展,新增两类插件扩展点(旧 1.0–1.4 插件无需重编):

项 Optimizer IO_BATCH
kind VDE_PLUGIN_KIND_OPTIMIZER = 9 VDE_PLUGIN_KIND_IO_BATCH = 10
接口 VdeOptimizerPlugin(optimize 回调) VdeIoBatchPlugin(run 回调)
Options VdeOptimizerOptions{struct_size,max_iterations,tolerance,flags} VdeIoBatchOptions{struct_size,format,flags}
Result VdeOptimizerResult{struct_size,status,objective_value,iterations,reserved,result_json} VdeIoBatchResult{struct_size,status,processed,failed,reserved,result_json}
输入/输出 options/input JSON → output JSON(host->alloc / free_buffer) options/request JSON → response JSON
宿主 API optimizers() / invoke_optimizer(...) io_batches() / invoke_io_batch(...)
示例 plugins/sample_optimizer/(id com.vde.sample.optimizer,capability optimizer:mock) plugins/sample_io_batch/(id com.vde.sample.io_batch,capability io_batch:mock)
能力前缀 optimizer: io_batch:
  • VdePluginRegistration 56B → 72B(optimizer offset 56、io_batch offset 64);旧 1.4(56B)安全; 声明新 kind 但 struct_size < 72 会被明确拒绝;
  • 测试 tests/plugin/test_plugin_abi15.cpp:72B/offset、注册/调用、错误隔离/unload、旧 1.4 兼容、56B 拒绝、 ABI 矩阵 1.0–1.5 accepted + 2.0 rejected;vde_plugin_tool --abi/--check 已适配;
  • 文档:plugin-development §16(optimizer)/§17(io_batch)、plugin-distribution §12 矩阵、本文。

3.7 兼容矩阵(1.5 宿主)

宿主 ABI \ 插件 ABI 1.0 1.1 1.2 1.3 1.4 1.5 2.0
1.5(当前主线) ✅ ✅ ✅ ✅ ✅ ✅ ❌
1.4(旧宿主) ✅ ✅ ✅ ✅ ✅ ❌(minor 大于宿主) ❌
1.3(旧宿主) ✅ ✅ ✅ ✅ ❌ ❌ ❌

后续(P4 候选):optimizer/io_batch 的生产实现与安全边界(文件访问/资源限制/超时)、批量导入导出与格式写能力、 插件市场对 optimizer/io_batch 的能力展示与认证。


4. SDK / 模板 / 工具演进

4.1 SDK

  • 现状:vde-plugin-sdk 组件(1.0.78)只含 vde_plugin_api.h + INTERFACE target,纯 C consumer 已验证;
  • 现状:随 ABI 1.4/1.5 更新头文件版本;mesher/optimizer/io_batch 示例;保持 SameMajorVersion(SDK 1.x 对应 ABI 1.x);
  • 版本策略:SDK 版本与内核发布版本解耦但同批发布(SDK 1.5.x 支持 ABI 1.0–1.5);
  • 发布物:vde-plugin-sdk 安装包 + 校验和/签名(随 1.0.x release artifacts 或独立 SDK 包)。

4.2 模板/scaffold

  • 现有四类模板;mesher(1.4)/optimizer/io_batch(1.5)模板可后续以同样方式加入(scaffold kind 扩展需 T6 排期);
  • 模板默认 ABI 版本随宿主主线(当前 1.5);旧宿主兼容场景用 VDE_PLUGIN_ABI_MINOR_OVERRIDE 构建 + 清单对齐(见 CI 模板 §6);
  • scaffold 替换规则/P3-17b 两阶段 token 替换已稳定,新增模板需加对应 CTest 冒烟。

4.3 工具链

  • 命令面已覆盖:scaffold/check/list/inspect/abi/gen-keypair/build-index/verify-index/install/fetch-index/ fetch-packages/uninstall/upgrade/revoked-keys;退出码 0/2/3/4;
  • 现状:--abi/--check 已支持 ABI 1.5 与 optimizer:/io_batch: 前缀;索引 schema 扩展(可选 certification/lifecycle 字段,见 §6)后续;
  • 兼容:CLI 参数只增不删;JSON 输出字段只增;旧索引(schema v1)继续可读。

5. 分发与市场演进

5.1 现状(离线/自托管闭环)

  • 索引 schema v1 + Ed25519 签名 + artifact SHA-256 + 路径安全 + ABI 门禁;
  • 本地/HTTP 获取、远程安装、依赖解析、卸载、原子升级、索引级吊销(--revoked-keys);
  • 发布者指南/CI 模板已交付(托管建议、key 轮换、负例门禁)。

5.2 演进路线

阶段 内容 WP
P4 近期 远程仓库服务器/索引刷新/镜像(自托管);吊销文件自动分发/缓存;OS 代码签名(Authenticode)作为纵深防御 WP-P4-07/08
P4 中期 插件市场元数据(认证徽章/兼容矩阵/评分可选)、官方/认证/社区三级目录;索引 schema v2(additive) WP-P4-07
P4 后续 增量/差量更新、批量升级依赖、企业私有市场/镜像同步、在线 CRL 候选

5.3 目录与生命周期策略

  • 官方插件:随 VDE 发布(版本一致、完整测试/ABI 矩阵、签名/索引由发布流程生成);
  • 认证第三方:通过 §6 认证清单,获得 certified 元数据(签名者/审核人/日期/ABI 范围/平台);
  • 社区插件:自签名/自托管,宿主按安全策略决定是否信任;市场仅做索引聚合,不做安全担保;
  • 生命周期:active/deprecated/revoked;下架需保留历史索引与吊销说明(旧版本仍可校验/回滚)。

6. 插件认证 / 评审清单

6.1 等级

等级 要求 适用
Official 随 VDE 发布流程构建/测试/签名;ABI 矩阵 + 全量回归 + 独立验证 官方格式/求解器插件
Certified 以下 §6.2 清单全通过 + 审核记录 + 至少一个宿主平台验证 生态伙伴/商业插件
Community 基本清单(manifest/ABI/构建/签名) 社区发布

6.2 评审清单(Certified 最小集)

[ ] 清单合法:id/version/kind/entry/abi/capabilities/license/permissions 完整;semver 规范
[ ] ABI:与目标宿主兼容(1.x 规则);struct_size/旧字段安全;能力前缀与 kind 一致
[ ] 构建:独立 build(仅 SDK 头,不链接内核);Release 可复现;无调试符号/中间产物入库
[ ] 自检:--check/--list PASS;--abi 基线记录;ABI 矩阵覆盖旧宿主/旧插件
[ ] 签名/哈希:清单与索引签名、artifact SHA-256、key_id 登记;生产不共用测试密钥
[ ] 负例:篡改工件/坏签名/路径逃逸/unsigned/吊销 均按预期失败(退出码 3/4)
[ ] 安全:无未声明权限;不读取无权限数据;外部服务/网络符合 sandbox 契约;TOCTOU 缓解说明
[ ] 文档:README(构建/安装/调用/卸载/错误码/支持矩阵);升级/回滚说明
[ ] 测试:宿主功能用例(导入/求解/调用/卸载)、失败隔离、重复加载/卸载;性能基线
[ ] 平台:Windows(MSVC/MinGW)与 Linux 至少各一(声明支持者);macOS 如声明支持则验证
[ ] 生命周期:版本策略(semver)、弃用窗口(≥1 minor)、安全联系方式

6.3 评审角色(RACI)

活动 T6 生态 T3 领域 T1 内核 T7 宿主 T8 验证
插件 ABI/清单评审 A/R C C(内核消费者) I C
求解器/格式语义评审 C A/R(T3/T2) I I C
签名/分发/安全评审 A/R I I C R(独立验证)
认证决定 A C C C R
市场目录收录 A/R I I C I

R=执行,A=负责/批准,C=咨询,I=知会;认证决定需 T6 + T8 双签。

7. 交接计划与里程碑

里程碑 内容 版本/时间 依赖
M1(已交付) ABI 1.4 mesher 扩展点 + sample + 矩阵 + 文档 1.0.79(WP-P4-01) —
M1b(已交付) ABI 1.5 optimizer/io_batch 扩展点 + sample + 矩阵 + 文档 P4(task-115,WP-P4-11) —
M2 生态团队独立接单:插件 CI 模板/认证清单落地;远程仓库/CRL 规划评审 1.0.80 M1、WP-P4-03
M3 市场/远程仓库自托管 + 吊销自动分发/Authenticode;认证插件目录上线 1.0.8x P4-07/08
M4 SDK/模板(mesher)、Python 发布、跨平台插件矩阵 P4 后续 P4-02/10/12

交接动作:

  1. 生态团队认领 §1 资产与 WP-P4-01/07/08/11;
  2. 建立独立构建目录与 CI(插件 CI 模板),跑通四类模板 + scaffold + SDK consumer 基线;
  3. 按 §6 认证清单评审现有官方/示例插件(先内部试点,再对外发布);
  4. 每批更新本文件与 work-packages.md 状态。

8. 开放问题

  1. ABI 1.4 mesher / 1.5 optimizer/io_batch 的输入输出内存所有权、资源/超时/文件访问边界(需与 T1/T3/T7 确认);
  2. 索引 schema v2 的 certification/lifecycle 字段是否纳入 v1 的 additive 扩展(保持 v1 兼容);
  3. Authenticode 与自有 Ed25519 的双签名策略(发布者/企业签名);
  4. 认证收费/审核人力模型(当前仅流程定义,不涉及商业条款);
  5. Python 插件(脚本插件)与原生 ABI 的边界(P4-11 能力 schema 时评估)。

9. 参考