### 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。
17 KiB
17 KiB
插件生态团队交接与规划(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(几何能力) |
边界规则:
- 生态团队可独立修改插件 ABI 的尾扩展与工具/文档,但 ABI 变更须 T1 评审 + T8 ABI 矩阵验证;
- 内核 ABI(
vde::kernel/C API)由 T1 拥有,生态团队只读;需要内核新能力时提「接口请求」WP; - 格式插件(STL/OBJ/PLY/STEP/IGES/DXF)的格式语义归 T2,插件壳/构建归 T6,变更需双 owner 评审;
- 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_matrixsmoke); - 旧插件(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 已知限制(交接时明确)
- 进程内插件无强隔离:校验与
dlopen之间有 TOCTOU 窗口;无 OS Authenticode(P4-08 候选); - 吊销文件需宿主/安装器分发(工具
--revoked-keys消费,无在线 CRL/自动刷新); - 远程仓库服务器/索引自动刷新/增量更新未实现(工具支持 fetch/index/install/upgrade,P4-07 候选);
- 官方格式插件仅导入为主;STEP/IGES 写与 3MF/glTF 导出为 P4-06 候选;
- Python 绑定 ctypes 路径可用,pybind 跨平台/packaging 为 P4-12 候选;
- 真实 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 契约设计(原则)
VDE_PLUGIN_ABI_MINOR1.3 → 4;VDE_PLUGIN_ABI_MAJOR仍为 1;VdePluginKind追加MESHER = 8(只追加,不改变旧值);VdePluginRegistration尾部追加mesher指针:struct_size48 → 56;旧插件struct_size=48时宿主 按 0/未提供处理(安全);- 新增纯 C 结构(均首字段
struct_size、版本/名称、回调/错误码):VdeMesherPlugin、VdeMesherOptions、VdeMesherRequest、VdeMesherResult、VdeMesherStatus; - 输入/输出:沿用现有 host services/句柄模式(B-Rep/网格经宿主句柄或请求/响应文件),不引入 C++/STL 类型;
- 生命周期/错误:init/query 与其它 kind 一致;mesher 调用返回状态码 + 错误字符串;复用现有超时/隔离机制;
- 能力 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: |
VdePluginRegistration56B → 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 资产与 WP-P4-01/07/08/11;
- 建立独立构建目录与 CI(插件 CI 模板),跑通四类模板 + scaffold + SDK consumer 基线;
- 按 §6 认证清单评审现有官方/示例插件(先内部试点,再对外发布);
- 每批更新本文件与 work-packages.md 状态。
8. 开放问题
- ABI 1.4 mesher / 1.5 optimizer/io_batch 的输入输出内存所有权、资源/超时/文件访问边界(需与 T1/T3/T7 确认);
- 索引 schema v2 的
certification/lifecycle字段是否纳入 v1 的 additive 扩展(保持 v1 兼容); - Authenticode 与自有 Ed25519 的双签名策略(发布者/企业签名);
- 认证收费/审核人力模型(当前仅流程定义,不涉及商业条款);
- Python 插件(脚本插件)与原生 ABI 的边界(P4-11 能力 schema 时评估)。