# 插件分发指南(P3-13):打包 / 索引 / 签名 / 安装 > 适用范围:VDE 微内核插件(format / CAE / CAM / GCS / UI / binding 等)的离线分发最小闭环: > 插件包 → 仓库索引 `index.json` → Ed25519 签名 → 校验与安装。 > 工具:`vde_plugin_tool`(P3-13 新增 `--build-index` / `--verify-index` / `--install` / `--gen-keypair`)。 > 版本基线:1.0.71+;插件 ABI 1.5(宿主 1.x 兼容 1.0–1.5)。 ## 1. 概念与目录布局 | 概念 | 说明 | |---|---| | 插件包(package) | 一个目录:`vde-plugin.json` + 动态库(`entry`)+ 可选数据文件;`artifacts` 为包内全部普通文件的相对路径 + SHA-256 | | 仓库索引(index) | 一个 JSON 文件,列出可用插件及其版本、ABI、能力、artifact 哈希;可整体 Ed25519 签名 | | 签名种子(seed) | 32 字节 Ed25519 私钥种子;**仅发布者持有**,不进入插件/索引/客户端 | | 公钥(public key) | 32 字节 Ed25519 公钥;随信任配置分发给宿主/安装器 | | 安装布局 | `//vde-plugin.json` + 动态库 + 数据文件(可直接作为宿主插件搜索路径) | 示例仓库布局: ```text repo/ index.json packages/ com.example.format/ vde-plugin.json vde_template_format.dll com.example.gcs/ vde-plugin.json vde_template_gcs.dll ``` `index.json` 中每个插件的 `path` 是**相对 index.json 所在目录**的包目录(如 `packages/com.example.format`); 构建与安装时都会拒绝 `..`、绝对路径、盘符等逃逸路径。 ## 2. index.json schema v1 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `schema_version` | int | 是 | 当前为 `1`;不匹配时工具拒绝 | | `generated_at` | string | 是 | UTC ISO-8601(`YYYY-MM-DDTHH:MM:SSZ`,仅审计用途) | | `generator` | string | 是 | 生成工具(当前 `vde_plugin_tool`) | | `publisher` | string | 否 | 发布者名(进入签名载荷) | | `key_id` | string | 否 | 签名密钥标识(进入签名载荷;吊销/轮换用) | | `signature` | string | 否 | 索引签名:`ed25519:`(**不进入签名载荷**) | | `plugins[]` | array | 是 | 插件条目;空数组合法(空仓库/占位索引) | `plugins[]` 条目: | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `id` | string | 是 | 反域名唯一 id(不得含路径分隔符) | | `name` | string | 否 | 显示名 | | `version` | string | 是 | 语义化版本 `x.y.z` | | `kind` | string | 是 | `format` / `cae_solver` / `cam_strategy` / `gcs_solver` / `ui` / `binding` / `geom_op` | | `abi` | object | 是 | `{ "major": 1, "minor": 3 }`;宿主只接受 major 相等且 minor ≤ 宿主 minor | | `capabilities` | array | 否 | 能力 ID 列表(与清单一致) | | `license` | string | 否 | SPDX 标识/许可说明 | | `requires` | array | 否 | 依赖声明:`[{ "id": "", "version_range": ">=1.2.0" }]`(简化 semver:exact / `>=` / `>` / `<=` / `<` / `^` / `~` / `*`,空格分隔=AND) | | `entry` | string | 是 | 平台动态库文件名(与清单一致) | | `path` | string | 是 | 包目录相对 index.json 的路径 | | `manifest_sha256` | string | 否 | `vde-plugin.json` 的 SHA-256(审计/快速比对) | | `signature` | string | 否 | 插件清单自身签名(P3-5 可选;索引签名覆盖整个索引) | | `artifacts[]` | array | 是 | `[{ "path": <包内相对路径>, "sha256": <64 hex>, "url": <可选绝对/相对索引URL> }]`;至少 1 项 | 最小示例(unsigned;正式分发必须签名): ```json { "schema_version": 1, "generated_at": "2026-10-29T00:00:00Z", "generator": "vde_plugin_tool", "plugins": [ { "id": "com.example.format", "name": "Example Format", "version": "0.1.0", "kind": "format", "abi": { "major": 1, "minor": 3 }, "capabilities": ["format:example.read", "format:example.write"], "entry": "vde_template_format.dll", "path": "packages/com.example.format", "manifest_sha256": "", "artifacts": [ { "path": "vde-plugin.json", "sha256": "" }, { "path": "vde_template_format.dll", "sha256": "" } ] } ], "key_id": "release-2026", "signature": "ed25519:" } ``` 仓库内 `plugins/index.json` 是**占位/空索引**(`plugins: []`),用于文档与仓库结构示例; 发布时由 `--build-index` 生成实际索引。 ## 3. 签名规范(复用 P3-5) - 签名算法:Ed25519(RFC 8032,32B 公钥 / 64B 签名 / 32B 私钥种子); - 签名载荷:`canonical_manifest_payload(index_json)`——即索引 JSON **去掉顶层 `signature` 字段**后的 确定性序列化(对象键字典序、无空白、数组保序、数字最短往返、UTF-8);与插件清单签名同规则; - `key_id`、`publisher`、`generated_at`、全部插件条目与 artifacts 哈希都在签名载荷内(防篡改); - 索引签名串:`ed25519:`;`signature` 字段自身不参与签名; - 插件清单的 `signature`(P3-5)与索引签名相互独立:前者由宿主 `verify` 校验,后者由 `--verify-index`/`--install` 校验;生产建议两者都签。 ## 4. 命令与退出码 工具位置:`/tools/vde_plugin_tool`(Windows `.exe`)。 ### 4.1 生成密钥(测试/开发) ```powershell vde_plugin_tool --gen-keypair --out-dir keys/ # keys/plugin_signing.key(seed hex,保密) # keys/plugin_signing.pub(公钥 hex,分发) ``` > 生产签名应在离线/受控环境执行;工具仅提供测试/开发用密钥生成。公钥通过可信通道分发 > (宿主配置/安装器内置/企业 PKI),不要从索引或插件包内读取公钥。 ### 4.2 打包 + 构建索引(可签名) ```powershell # 1) 打包:把插件构建产物(vde-plugin.json + DLL + 数据)复制到 repo/packages// # 注意不要带 build 中间产物;artifacts 由 --build-index 自动计算 SHA-256。 # 2) 构建索引(签名可选但生产必需): vde_plugin_tool --build-index repo/packages -o repo/index.json ` --sign keys/plugin_signing.key --key-id release-2026 --publisher "Example Corp" ``` 输出包含每个插件的 id/version/ABI/artifact 数与公钥指纹;`--sign` 缺省生成 unsigned 索引。 ### 4.3 校验索引 ```powershell vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub # 校验:schema、签名、路径安全、每个 artifact 存在且 SHA-256 一致、ABI 与宿主兼容、重复条目 ``` `--allow-unsigned` 仅用于内网/开发;正式分发应始终带 `--pubkey` 并拒绝 unsigned。 > `--pubkey` 支持内联 `ed25519:` 或文件路径;文件内容需为单行纯 hex/base64 或 `ed25519:<...>`(`--gen-keypair` 生成的 `.pub` 可直接使用;若手工拼接,确保没有多余换行/前缀)。 **吊销签名 key(P3-13b)**:`--verify-index`/`--install`/`--upgrade` 支持 `--revoked-keys `,验签后若索引 `key_id` 命中吊销列表则退出码 3(诊断含 `index signing key_id '' is revoked`)。文件格式:每行一个 key_id(`#` 注释、可逗号分隔) 或 JSON `{"revoked_key_ids":["..."]}`;格式错误/空文件同样退出 3(诊断含 `invalid --revoked-keys`)。吊销列表由调用方/宿主策略显式提供,**不要**从索引内读取。 ```powershell # 拒绝已吊销 key_id 签名的索引(行格式吊销文件) vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub ` --revoked-keys revoked_keys.txt # JSON 格式 vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub ` --revoked-keys revoked_keys.json ``` ### 4.4 安装 ```powershell # 从索引安装(推荐;自动验签/哈希/ABI) vde_plugin_tool --install repo/index.json --dest installed/ ` --id com.example.format --pubkey keys/plugin_signing.pub # 指定版本(索引可含同一 id 多版本;缺省选最高 semver) vde_plugin_tool --install repo/index.json --dest installed/ ` --id com.example.format --version 0.1.0 --pubkey keys/plugin_signing.pub # 从本地插件目录安装(开发便利;无签名校验,host 侧仍可 verify) vde_plugin_tool --install path/to/plugin_dir --dest installed/ ``` 安装结果:`//`(vde-plugin.json + 动态库 + 数据文件)。已存在时需 `--force` 覆盖。 安装同样支持 `--revoked-keys `:索引签名 key_id 被吊销时在任何文件写入前拒绝(退出码 3)。 ### 4.5 退出码 | 退出码 | 含义 | |---|---| | `0` | 成功 | | `2` | 用法/参数错误(含非法公钥文本) | | `3` | 校验失败:schema/签名/哈希/路径逃逸/ABI 不兼容/插件不存在/目标已存在/**签名 key_id 被吊销(--revoked-keys)** | | `4` | 加密不可用:签名索引未提供 `--pubkey`,或工具未链接 `vde_license`(无 Ed25519) | ### 4.6 远程索引获取(`--fetch-index`,P3-17) ```powershell vde_plugin_tool --fetch-index -o \ [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--verify-artifacts] ``` - 来源支持本地路径/`file://`、`http://`/`https://`(Windows 构建经 WinHTTP;Linux/macOS 当前仅本地文件, URL 获取返回明确错误); - 获取后写入 `-o`,随即复用索引校验:schema → 签名(`--pubkey` 必填,unsigned 需 `--allow-unsigned`)→ 路径安全 → ABI 兼容; - `--verify-artifacts`:额外校验索引中每个 artifact 的 SHA-256;要求 `-o` 所在目录已有对应 `path` 的 package(例如先解包/下载插件包再 fetch 到同目录);远程只取索引作元数据时可不开; - 失败语义与 `--verify-index` 一致:0 成功、2 用法、3 校验/网络/格式失败、4 签名索引缺 pubkey 或工具无 Ed25519; - 信任模型:公钥必须来自可信通道(宿主内置/企业 PKI/发布说明);**不要**信任从索引或同一站点下载的公钥。 示例(本地镜像,离线/CI 常用): ```powershell # 已有仓库目录 repo/(index.json + packages/): vde_plugin_tool --fetch-index repo/index.json -o fetched/index.json \ --pubkey keys/plugin_signing.pub --verify-artifacts # 指定包目录在 fetched/ 下时,artifacts 会按索引相对路径校验。 ``` ### 4.7 远程包安装与依赖解析(`--fetch-packages`,P3-17c) ```powershell vde_plugin_tool --install --dest [--id ] [--version ] \ --fetch-packages [--verify-artifacts] \ [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--force] ``` - 包文件获取:URL 索引按索引 URL 相对路径下载(`http(s)` 经 WinHTTP;`artifact.url` 可覆盖为绝对/相对 URL); 本地索引从索引目录复制;每个 artifact 写入 `/.vde-staging-*` 后立即校验 SHA-256; - 依赖解析(`requires`):已安装版本满足则跳过;否则从索引选择最高满足版本,递归闭包一并安装; 缺失依赖/版本冲突/循环依赖返回退出码 3 与明确错误;依赖按 postorder 先装; - 原子性:所有包先落 staging 并校验,全部成功后再 rename 到 `//`;任一步失败清理 staging、 回滚本批已提交的包(含覆盖前的备份),不留部分安装; - 远程索引 URL 必须配合 `--fetch-packages`(否则退出码 3);`--verify-artifacts` 与 `--fetch-packages` 语义合并(都要求逐工件获取并校验哈希); - 失败语义:0 成功、2 用法、3 校验/下载/依赖/哈希/路径失败; ### 4.8 卸载(`--uninstall`,P3-17c) ```powershell vde_plugin_tool --uninstall --dest ``` - 安全校验:id 不得含路径分隔符或 `..`;目标必须位于 `--dest` 规范化路径下且含 `vde-plugin.json`; - **P4-41 增强**:新增 `--root` 别名;目标必须是安装根直接子目录;读取 manifest 校验 id 匹配后才删除; - 只删除 `//`;未知 id/非法路径/非插件目录/id 不匹配退出码 3; ### 4.9 原子升级(`--upgrade`,P3-17c) ```powershell vde_plugin_tool --upgrade --id --dest [--version ] \ [--fetch-packages] [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--force] \ [--revoked-keys ] ``` - 流程:检查已安装版本(未安装/同版本拒绝)→ 索引选版本(`--version` 或最高)→ 补装缺失依赖 → staging 下载 + SHA-256 校验 → 旧目录备份 `.vde-bak-*` → 同卷 rename 原子替换 → 成功清理备份; - 失败(下载/哈希/路径/依赖/替换)恢复旧版本并清理 staging,不破坏现有安装; - `--version` 可选择回滚到索引保留的旧版本(原子替换同样适用); - 失败语义:0 成功、2 用法、3 校验/下载/依赖/哈希/替换失败,或签名 key_id 被 `--revoked-keys` 吊销; ### 4.10 打包(`package`,P4-41) ```powershell vde_plugin_tool package -o ``` - 校验:`vde-plugin.json` 可解析、id/version/entry 非空、entry 文件存在、capabilities 非空、 ABI 与当前宿主兼容(major 相等且 minor ≤ 宿主);限制 10000 文件 / 1GiB; - 自定义**确定性归档**(`VDEPKG1`,不依赖 zip 库):magic + 单行 JSON metadata (id/version/kind/abi/entry/files)+ 按路径字典序的 `FILE ` 头 + 按序 payload;不写时间戳/权限,同一输入重复打包 SHA-256 相同; - 输出归档 SHA-256 到 stdout,并写 `.sha256` sidecar(` `); - 失败语义:2 用法错误、3 manifest/entry/ABI/capabilities/IO 校验失败; ### 4.11 校验与解包(`verify-package` / `unpack`,P4-41) ```powershell vde_plugin_tool verify-package vde_plugin_tool unpack --dest ``` - `verify-package`:校验 magic/metadata、文件表、每个 payload 的 SHA-256;不写文件; - `unpack`:校验通过后按归档内相对路径写出(自动建目录),存在则覆盖; 拒绝绝对路径、`..` 逃逸与非法路径(`is_artifact_path_safe`),并校验目标规范化后仍位于 dest 下; - 失败语义:2 用法错误、3 归档损坏/校验失败/路径逃逸/IO 失败; ### 4.12 列出已安装插件(`list`,P4-41) ```powershell vde_plugin_tool list # 兼容旧写法:vde_plugin_tool --list ``` - 递归扫描 `` 下的 `vde-plugin.json`,逐项输出 id/version/kind/ABI/entry/ capabilities/manifest 路径/status; - `status=installed`:manifest 位于 `//vde-plugin.json` 且 manifest.id 等于目录名; 其它位置为 `discovered`;无效 manifest 计为 invalid 并以退出码 3 汇总; ### 4.13 卸载安全增强(`uninstall`,P4-41) ```powershell vde_plugin_tool uninstall --root # 兼容旧写法(--dest 同义):vde_plugin_tool --uninstall --dest ``` - 路径安全:id 禁止 `/`、`\`、`.`、`..`;目标必须为 `` 的直接子目录(规范化 parent == root); - id 匹配:读取 `//vde-plugin.json` 并解析,manifest.id 必须等于请求 id,否则拒绝删除; - 只删除目标 `//`;未安装、非插件目录、id 不匹配、路径逃逸均退出码 3; - 回归:`tests/plugin/package_tool_smoke.cmake` 覆盖 pack→verify→unpack 往返、确定性/SHA-256、list(installed/discovered)、uninstall 仅删目标/id 匹配/路径逃逸、坏 manifest/缺 DLL/归档路径逃逸; ### 4.14 包升级与回滚(`upgrade`,P4-48) ```powershell vde_plugin_tool upgrade --root [--force] [--rollback] ``` - **verify**:完整校验归档 magic/metadata/FILE 表/逐 payload SHA-256、manifest 存在、id/version; 先解包到 `/.vde-stage--`,再解析 staged manifest 并校验 id/version/entry 一致; - **semver 门控**:读取已安装 `//vde-plugin.json` 版本;默认仅允许 **严格更高** 版本, 相等版本(重装)或降级会被拒绝;`--force` 允许相等/降级/覆盖重装;未安装时等同 install; - **原子替换**:旧目录 rename 为 `/.vde-bak-` → staged rename 为 `/`; 任一步失败自动恢复旧版本并清理 stage;成功后清理备份;stage 位于同一 root(同卷 rename 原子); - **`--rollback`**:在 `` 下查找 `.vde-bak-*` 备份并恢复**最新**一个;当前版本先移到 `.vde-old-`,若恢复失败则回滚该移动;无备份/非安装根/路径不合法退出码 3; - **路径安全**:id 禁止 `/`、`\`、`.`、`..`、以 `.` 开头;target 必须是 `` 直接子目录 (规范化 parent == root);归档内相对路径禁止 `..`/绝对路径逃逸; - 退出码:0 成功、2 用法错误、3 verify/semver/IO/回滚失败; - 回归:`tests/plugin/upgrade_tool_smoke.cmake` 覆盖未安装安装、相等/降级拒绝与 `--force`、 正常升级、坏包/归档路径逃逸后旧版本保留、`--rollback` 恢复人工备份、无备份错误; - 说明:`--upgrade --id ... --dest ...` 仍为 P3-17c 的索引/远程升级入口; 本命令是 P4-41 `.vdeplugin` 本地包升级入口。 --- ## 5. 端到端示例(sample_vbox + sample_gcs) > 以下命令在 VDE 构建目录执行(`build-fb-dist` 为本轮独立构建目录);包内容为构建产物 > `plugins/sample_vbox/`、`plugins/sample_gcs/`。 ```powershell # 1) 打包 New-Item -ItemType Directory -Force repo/packages/sample_vbox, repo/packages/sample_gcs | Out-Null Copy-Item /plugins/sample_vbox/vde-plugin.json, /plugins/sample_vbox/vde_sample_vbox.dll repo/packages/sample_vbox/ Copy-Item /plugins/sample_gcs/vde-plugin.json, /plugins/sample_gcs/vde_sample_gcs.dll repo/packages/sample_gcs/ # 2) 生成密钥并签名建索引 vde_plugin_tool --gen-keypair --out-dir keys/ vde_plugin_tool --build-index repo/packages -o repo/index.json --sign keys/plugin_signing.key --key-id test-key --publisher example vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub # 3) 安装并检查 vde_plugin_tool --install repo/index.json --dest installed/ --id com.vde.sample.vbox --pubkey keys/plugin_signing.pub vde_plugin_tool --install repo/index.json --dest installed/ --id com.vde.sample.gcs --pubkey keys/plugin_signing.pub vde_plugin_tool --check installed/com.vde.sample.vbox vde_plugin_tool --list installed/ ; # 宿主 PluginManager 指向 installed/ 即可发现 ``` 本轮实测(1.0.71 / MinGW Release):签名为 `ed25519`;索引含 2 插件;安装后 `--check` PASS; 负例(篡改 artifact、改索引内容导致坏签名、路径逃逸、ABI 2.0 不兼容、unsigned 未加 `--allow-unsigned`、已存在目标未加 `--force`)均返回非 0(详见报告记录)。 ## 6. 信任模型与密钥管理 1. **私钥离线**:签名种子只在发布流水线/离线机使用;泄露需立即轮换并吊销旧 `key_id`; 2. **公钥可信分发**:宿主/安装器内置公钥或从企业 PKI 获取;**不要**信任索引里的公钥; 3. **key_id**:索引顶层 `key_id` 标识签名密钥;配合 P3-5 的 `trusted_keys`/`revoked_key_ids` 策略,宿主可按 key_id 选择/吊销;P3-13b 起工具内置索引级吊销:`--verify-index`/`--install`/ `--upgrade --revoked-keys ` 在验签通过后强制拒绝已吊销 key_id(退出 3);吊销列表须由 调用方显式提供(可信通道),**不要**信任索引内自带列表; 4. **多层校验**:`--verify-index` 校验索引签名 + artifact 哈希;插件清单签名(P3-5)可再 由宿主 `verify` 校验;两者独立; 5. **路径安全**:索引里 `path`/artifact 路径必须是包内相对路径;`--verify-index`/`--install` 拒绝 `..`、绝对路径、盘符,防止 zip-slip 类逃逸; 6. **ABI 门禁**:安装前按宿主 ABI 拒绝不兼容插件(major 必须相等、minor ≤ 宿主 minor); 7. **审计**:索引记录 `generated_at`/`publisher`/`key_id`/artifact 哈希,可用于发布审计与 供应链比对。 ## 7. 升级 / 回滚 / 卸载 - **升级(推荐)**:`--upgrade --id --dest [--version x.y.z] [--fetch-packages]`; 先下载/校验到 staging,再备份旧目录并同卷 rename 原子替换,失败自动恢复旧版; - **回滚**:对索引保留的旧版本条目执行 `--upgrade --version `;成功升级会清理临时备份; - **卸载**:`--uninstall --dest `(id/路径安全校验,只删目标插件目录); - **原子性**:P3-17c 起 install/upgrade 均为 staging + 原子提交;批量依赖安装失败会回滚本批已提交包; 断电等极端场景建议同时保留发布侧备份与幂等重试。 ## 8. 发布者检查清单(CI 建议) ```text [ ] 插件在独立 build 目录用 SDK 头构建通过;--check 通过 [ ] 包内容只含 vde-plugin.json + 动态库 + 必要数据(无构建中间产物/调试符号) [ ] --build-index --sign 生成索引;--verify-index --pubkey 通过 [ ] 负例回归:篡改任一 artifact / 改索引内容 / 改 ABI / 路径逃逸均失败 [ ] 在干净宿主安装目录上 --install 并通过 PluginManager 发现/加载/调用/卸载 [ ] 公钥/指纹与发布说明一致;key_id 登记;旧版本保留可回滚 [ ] 吊销预案:发布侧登记 key_id;安装/校验侧提供 --revoked-keys(本地策略文件),负例验证被吊销 key 拒绝 ``` ## 9. 当前边界(后续 roadmap) - 远程包安装/依赖解析/卸载/原子升级:P3-17c 已提供 `--install --fetch-packages`(http(s)/本地、 SHA-256 校验、`requires` 简化 semver 解析、staging 原子提交与回滚)、`--uninstall`、`--upgrade`; 尚未提供:远程仓库索引刷新(`--fetch-index` 已可单独使用)、增量/差量更新、吊销列表自动分发/在线 CRL、容器/隔离安装; - 索引级吊销(P3-13b):`--verify-index`/`--install`/`--upgrade` 支持显式 `--revoked-keys ` 并在验签后强制拒绝已吊销签名 `key_id`(退出 3);吊销列表由调用方/宿主策略提供,自动分发/CRL 待后续; - 依赖解析为简化 semver(单 token 比较/空格 AND;无预发布版本/复杂范围);升级为单插件原子替换,不批量升级依赖; - 索引签名只覆盖索引文件本身;插件清单签名/工件签名可叠加(P3-5),生产建议双签; - 与 P3-14 外部服务、P3-12 模板包/`--check`、P3-17 scaffold/`--fetch-index` 配合: `scaffold` 生成工程 → `--check` → 打包 → 索引 → 签名 → fetch/verify/install。 ## 10. 独立 vde-plugin-sdk 包(P3-12b) 插件开发者可不依赖 VDE 源码树/内核,仅安装纯 C ABI SDK: ```powershell cmake --install --prefix --component vde-plugin-sdk ``` - 内容:`include/vde/plugin/vde_plugin_api.h`(纯 C ABI 契约)+ `lib/cmake/vde-plugin-sdk/` 配置; - consumer:`find_package(vde-plugin-sdk CONFIG REQUIRED)` → `target_link_libraries(my_plugin PRIVATE vde::plugin-sdk)` (header-only,无库依赖;版本 SameMajorVersion); - 与插件分发关系:SDK 只用于**编译**插件;插件包的上架/下载/安装/升级走本文索引与 `--build-index/--fetch-index/--install/--upgrade` 流程; - 生成条件:`VDE_INSTALL=ON` 且 `VDE_INSTALL_SDK=ON`(默认);`VDE_INSTALL=OFF` 时 SDK 包不生成; - 端到端回归:CTest `VDE_PluginSdkConsumerSmoke`(安装 SDK component → 独立纯 C consumer 构建/运行 PASS); - 限制:不含 `plugin_manager.h` 等宿主 C++ API(改由 `vde-kernel` 包/宿主提供);不含模板与示例。 ## 11. 相关文档 - 插件开发指南:`docs/guides/plugin-development.md`(ABI/扩展点/`--check`); - 插件安全:`docs/design/plugin-security.md`(签名规范/策略/密钥轮换); - 路线图:`docs/design/architecture-plugin-roadmap.md`(P3-13); - 示例插件:`plugins/official/*`、`plugins/sample_vbox`、`plugins/sample_gcs`; - 模板与 scaffold:`plugins/templates/`(四类最小插件工程)、`docs/guides/plugin-development.md` §14.4; - 远程索引:`--fetch-index`(本文 §4.6)。 ## 12. 插件 ABI 兼容矩阵(1.0–1.5) 宿主 ABI 1.5 对插件清单 `abi` 字段的加载规则:`major` 必须相等,`minor <= 宿主 minor`。 | 插件 ABI | 新增内容 | 注册结构(64-bit) | 宿主 1.5 行为 | |---|---|---|---| | 1.0 | 格式插件基础(format/generic) | 24B | 接受 | | 1.1 | 宿主服务 `body_from_mesh`(尾部追加) | 24B | 接受 | | 1.2 | CAE solver / CAM strategy 扩展点 | 40B | 接受 | | 1.3 | GCS solver 扩展点 | 48B | 接受(旧 48B 安全) | | 1.4 | **Mesher 扩展点**(`VdeMesherPlugin`) | 56B | 接受(旧 56B 安全) | | 1.5 | **Optimizer + IO_BATCH 扩展点**(`VdeOptimizerPlugin` / `VdeIoBatchPlugin`) | **72B**(optimizer offset 56、io_batch offset 64) | 接受 | | 2.0+ | major 不兼容 | — | **拒绝**(动态库加载前) | - 注册结构按 `struct_size` 尾扩展:宿主只读取声明尺寸内字段;旧插件无需重编; - 声明 kind=optimizer/io_batch 但 `struct_size < 72` 的插件会被明确拒绝;旧 1.4(56B)插件正常加载; - 能力前缀约定:`format:` / `cae_solver:` / `cam_strategy:` / `gcs:` / `mesher:` / **`optimizer:`** / **`io_batch:`** (`vde_plugin_tool --check` 对不匹配仅 warning); - P4 示例:`plugins/sample_mesher/`(1.4,capability `mesher:tet`)、`plugins/sample_optimizer/`(1.5,`optimizer:mock`)、 `plugins/sample_io_batch/`(1.5,`io_batch:mock`); - ABI 矩阵回归:`plugins/abi_matrix`(接受 1.0–1.5,拒绝 2.0);`tests/plugin/test_plugin_mesher.cpp`(1.4)与 `tests/plugin/test_plugin_abi15.cpp`(1.5:72B/offset 56/64、旧 1.4 兼容、56B 声明新 kind 拒绝); - `vde_plugin_tool --abi` 打印当前宿主 ABI(1.5)、注册结构尺寸与 Optimizer/IoBatch 结构尺寸; 发布索引 `abi` 字段应据此声明;旧宿主(1.4)会拒绝 1.5 插件(minor > 宿主),需要旧宿主兼容时按 1.4 构建发布。 ## 13. 本地/自托管索引服务(P4-07) 无外部服务/runner 时,可用工具自带的纯标准库 HTTP 服务演示完整分发链路: 生成签名索引 → HTTP 获取索引 → 远程下载插件包并安装。 ### 13.1 启动 ```powershell python tools/vde_index_server.py --root repo/ --host 127.0.0.1 --port 0 \ [--index index.json] [--log] ``` - `--root `:仓库根目录(含 `index.json` 与 `packages/`); - `--host` 默认 `127.0.0.1`;`--port 0` 为 ephemeral(自动分配,启动后打印实际端口), 也可指定固定端口;`--index` 为相对 root 的索引路径(默认 `index.json`);`--log` 打印请求日志; - 启动输出(stdout,flush):`VDE_INDEX_SERVER http://127.0.0.1:/`、`root=...`、`index=...`; 支持 Ctrl+C 退出。 ### 13.2 路由与安全 - `GET/HEAD /` 或 `GET/HEAD /`:返回索引 JSON; - `GET/HEAD /`:返回 root 下静态文件(插件包/artifact),带 `Content-Type`、`Content-Length`、 `Cache-Control: no-cache`、`ETag`(内容 SHA-256); - 条件刷新:请求带 `If-None-Match: ` 且内容未变时返回 **304**、空 body,避免重复下载索引/包; - 路径安全:URL 解码后规范化,拒绝 `..`、绝对路径/盘符、反斜杠、空字节与符号链接逃逸; 越界返回 **403**,不存在返回 **404**,非 GET/HEAD 返回 **405**(Allow: GET, HEAD),不列目录; - 只读、单 root、无鉴权/无 TLS:**仅用于本地开发/CI/可信内网**,不要直接暴露公网; 多租户/权限/审计/TLS/限流等真实市场能力后续提供。 ### 13.3 端到端示例 ```powershell # 1) 生成密钥、构建并签名索引(repo/index.json + repo/packages/...) vde_plugin_tool --gen-keypair --out-dir keys/ vde_plugin_tool --build-index repo/packages -o repo/index.json \ --sign keys/plugin_signing.key --key-id test-key --publisher example # 2) 启动本地索引服务(记下打印的端口) python tools/vde_index_server.py --root repo/ --port 0 # 3) 另一终端:HTTP 获取索引 + 远程安装插件包 vde_plugin_tool --fetch-index http://127.0.0.1:/index.json \ -o repo/index_fetched.json --pubkey keys/plugin_signing.pub --verify-artifacts vde_plugin_tool --install http://127.0.0.1:/index.json --dest installed/ \ --id com.example.format --fetch-packages --pubkey keys/plugin_signing.pub ``` 说明:`--fetch-index --verify-artifacts` 按输出目录旁本地 packages 校验哈希(用于离线缓存场景); 远程安装由 `--install --fetch-packages` 从服务下载每个 artifact 并逐项 SHA-256 校验。 ### 13.4 自动回归 ```powershell python tests/plugin/index_server_smoke.py --tool /tools/vde_plugin_tool ``` - 自动查找 `build*/tools/vde_plugin_tool[.exe]`(也可用 `--tool` / `VDE_PLUGIN_TOOL_EXE` 指定); - 覆盖:gen-keypair → build-index 签名 → 启动服务(ephemeral)→ HTTP fetch-index (签名+artifact 哈希)→ HTTP install(下载+安装)→ 直接 GET artifact; - 负例:404、路径逃逸(403/404 且不泄漏 root 外文件)、篡改 artifact 哈希(fetch/install 均失败); - 仅依赖 Python 标准库与已构建的 `vde_plugin_tool`。 ### 13.5 限制 - 只读静态服务,不提供上传/发布/删除/鉴权/审计; - 无 TLS、无限流、无多 root/虚拟主机;生产市场请置于反向代理/对象存储/鉴权网关之后; - 与 P4-08(CRL/吊销分发)配合时,可复用同目录静态托管 `revoked-keys` 文件(本服务只负责托管); - 端口/目录安全语义以本文为准;若需公网部署,必须补充 TLS 与访问控制。 > `--rollback` 语义补充:仅从 `/.vde-bak-*` 备份目录恢复最近一次备份;成功 upgrade 后会清理本次自动备份,因此无人工/外部备份时 `--rollback` 会正确拒绝。