feat(build)!: VelaShell.PluginSdk.Build 与 .vpx 打包器搬进契约仓库

[joesdu]

VelaShell.PluginSdk.Build 决定的是插件作者编译时看到的那份契约,所以它属于契约仓库 —— 它应该和 SDK 一起发版。这个 PR 把它(以及 .vpx 打包器)搬了过来。

配套 PR:VelaShellLabs/velashell-plugin-cli#17(那边删掉 .Build,只留 vela-plugin 单独发版)。

搬来了什么

新增	说明
src/VelaShell.PluginSdk.Build/	插件工程只需引用的那一个包。契约引用从跨仓库 PackageReference 换成 ProjectReference
src/VelaShell.PluginSdk.Packer/	.vpx 打包器,IsPackable=false —— 只以构建产物的形式随 .Build 包的 tools/ 分发
scripts/Invoke-Smoke.ps1 + tests/smoke/	端到端冒烟:一个手写的最小插件工程,从刚打出的包还原 → 构建 → 出 .vpx → 读回容器

本仓库现在一次发布产出三个同版本的包:VelaShell.PluginSdk / .Testing / .Build。

两个设计决定

.Build 用 ProjectReference 引契约。 于是它发给插件工程的那份契约,就是本仓库这一版 ——「.Build 引用的是哪一版 SDK」这个旋钮,连同它漂移的可能,一并消失。打出来的 nuspec 依赖是 VelaShell.PluginSdk <同版本>,include 资产元数据与搬迁前逐字一致。

打包器做进本仓库,而不是继续引用 vela-plugin。 中途试过后者(.Build 引用 CLI 的已发布包,只取 tools/ 下的载荷),能跑,但换来一个要人盯着的跨仓库版本旋钮。而 .vpx 的定义 —— VpxContainer 与 PluginManifestReader —— 本来就在 VelaShell.PluginSdk 里,vela-plugin 也只是它的另一个调用方。现在"打包器与契约同版本"是构建出来的事实,不是版本号约定,两个仓库之间没有任何依赖。

打包器刻意是独立进程而不是 MSBuild 任务:VS 的 MSBuild 跑在 .NET Framework 上,而本仓库是 net11.0,<UsingTask> 会让插件作者在 VS 里每次生成都失败(清单校验是 AfterTargets="Build" 的)。dotnet exec 与调用方的 MSBuild 是哪种运行时无关。

其它

• Avalonia 版本锁核对改读同仓库的 $(VelaAvaloniaVersion),少一跳。宿主那一侧照旧走包里的 buildTransitive props,不受影响
• CI / release 的 pack 列表加上 .Build,各加一步端到端冒烟。冒烟用的打包器从刚打出的包里取,顺带核对"打包器真的进了包"

验证

检查	结果
dotnet test	50 通过
端到端冒烟(插件工程 → -t:PackVpx → 读回容器 → 查共享程序集泄漏)	通过
.Build 包内容	tools/net11.0/ 是新打包器;依赖只剩 VelaShell.PluginSdk(同版本)+ Avalonia [12.1.2]
pack -k key.pem 签出的包交给 vela-plugin verify	摘要一致、签名 Valid(两套实现格式互通)
故意让 VelaAvaloniaVersion 漂移	VELA1006 如期报错
版本同步体检(模拟 CI 无 docs)	通过

⚠️ 合并后、发版前要做的事

在 nuget.org 为 VelaShell.PluginSdk.Build 重建一条可信发布策略(Repository 填 velashell-plugin-sdk,Workflow 填 release.yml)。现有那条指向 velashell-plugin-cli —— 不重建的话,发版推到第三个包时会被拒,而前两个已经推上去了。

另:.Build 在 nuget.org 上最新是 2.0.2,而 VelaShell.PluginSdk 已发到 2.0.4,所以下一次发版(≥2.0.5)会让 .Build 的版本号跳一段。单调递增,没问题,只是发布记录上会有个缺口。

velashell-docs 还没动 —— 按 AGENTS.md 的约定那是单独一个 PR,zh|en 各 7 篇会说错话。

🤖 Generated with Claude Code

https://claude.ai/code/session_01GuPc3rAEeVHYfnicxv4p7y