Merge pull request #2 from VelaShellLabs/dev

依赖管理调整为 csproj 明确版本并同步文档

Author: joesdu

.github/workflows/release.yml

@@ -11,7 +11,7 @@
 #
 # **另外三个包不在这里发**(2026-08-27 拆库起):
 #      VelaShell.PluginSdk / .Testing …… VelaShellLabs/velashell-plugin-sdk
-#      VelaShell.Plugin.Templates ……… joesdu/velashell-plugin-templates
+#      VelaShell.Plugin.Templates ……… VelaShellLabs/velashell-plugin-templates
 # 三个仓库各有各的版本号。本仓库发 1.5.3 不代表契约动了,也不要求模板跟着发。
 #
 # 📌 版本号:**发版前在本地落好、随功能改动一起合进 main**。
@@ -23,10 +23,10 @@
 #    下面的 Stamp 步骤只改 runner 上的工作区,**不回写仓库**:产物版本号因此永远等于
 #    Release 标签,与仓库里当时提交了什么无关。忘了第 ① 步的兜底是 CI 的版本同步体检。
 #
-# ⚠️ 想让插件作者吃到**新契约**,得另外手工抬 Directory.Build.props 里的
-#    VelaSdkDependencyVersion(Set-Version.ps1 刻意不碰它)—— 那是一次独立的决定,
-#    不该被"发个补丁版"顺手带上。抬完 VerifyAvaloniaVersionPin 会在构建期核对
-#    Avalonia 版本锁是否也要跟着动(VELA1006)。
+# ⚠️ 想让插件作者吃到**新契约**,得另外抬两个 csproj 里 VelaShell.PluginSdk 的
+#    PackageReference 版本(Set-Version.ps1 刻意不碰它;Dependabot 会替你提 PR)——
+#    那是一次独立的决定,不该被"发个补丁版"顺手带上。抬完 VerifyAvaloniaVersionPin
+#    会在构建期核对 Avalonia 版本锁是否也要跟着动(VELA1006)。
 #
 # ⚠️ 发完新版 .Build 之后,若希望 `dotnet new velaplugin` 生成的工程指向它,
 #    要去 velashell-plugin-templates 抬 VelaBuildPackageVersion 再发一版模板。

Directory.Build.props

@@ -24,8 +24,10 @@
 
       **与契约 SDK 解耦**(2026-08-27 拆库起):VelaShell.PluginSdk 在
       VelaShellLabs/velashell-plugin-sdk,有自己的版本号。SDK 发 1.6.0 不要求本仓库跟着发;
-      本仓库发 1.5.3 也不代表契约动了。想吃到新契约时,把下面的
-      VelaSdkDependencyVersion 抬上来再发一版即可。
+      本仓库发 1.5.3 也不代表契约动了。想吃到新契约时,直接把两个 csproj 里
+      VelaShell.PluginSdk 的 PackageReference 版本抬上来再发一版即可 —— 走 NuGet
+      (或合掉 Dependabot 的 PR)更新,**不要**抽成 MSBuild 属性:Version="$(...)"
+      会让 Dependabot 与 `dotnet add package` 认不出这条依赖。
 
       CI 发包时用 -p:VelaToolsVersion= 覆盖(取自 Release 标签)。
     -->

README.md

@@ -48,23 +48,26 @@ sdk 仓库要去引用 CLI 包,于是 SDK 发版被 CLI 卡住 —— 正是拆
 
 ```
 velashell-plugin-sdk                  契约,无上游
-        ↓ NuGet: VelaShell.PluginSdk        ← 版本旋钮 VelaSdkDependencyVersion
+        ↓ NuGet: VelaShell.PluginSdk        ← 版本写在两个 csproj 的 PackageReference 上
 velashell-plugin-cli                  ← 本仓库
         ↓ NuGet: VelaShell.PluginSdk.Build  ← 模板里那个 sdkVersion 默认值
 velashell-plugin-templates
 ```
 
 另外两个相关仓库:[joesdu/VelaShell](https://github.com/joesdu/VelaShell)(宿主主程序)、
-[joesdu/velashell-plugins](https://github.com/VelaShellLabs/velashell-plugins)(第一方插件)。
+[VelaShellLabs/velashell-plugins](https://github.com/VelaShellLabs/velashell-plugins)(第一方插件)。
 
 ## 两个跨仓库旋钮
 
-都在 `Directory.Build.props`,**都不由 `Set-Version.ps1` 管**——它们是需要想清楚的独立决定:
+**都不由 `Set-Version.ps1` 管**——它们是需要想清楚的独立决定:
 
-| 旋钮 | 含义 | 抬它意味着 |
+| 旋钮 | 在哪 | 抬它意味着 |
 | --- | --- | --- |
-| `VelaSdkDependencyVersion` | 引用哪一版契约 SDK | 插件作者的**编译目标契约**变新。发一个只改了输出格式的补丁版时不该顺手带上 |
-| `VelaAvaloniaVersion` | 锁给插件工程的 Avalonia 版本 | 权威在 sdk 仓库,这里只是副本。改它必须跟着 SDK 走 |
+| `VelaShell.PluginSdk` 的 `PackageReference`(引用哪一版契约 SDK) | `src/VelaShell.Plugin.Cli` 与 `src/VelaShell.PluginSdk.Build` 两个 csproj,**必须同版本** | 插件作者的**编译目标契约**变新。发一个只改了输出格式的补丁版时不该顺手带上 |
+| `VelaAvaloniaVersion`(锁给插件工程的 Avalonia 版本) | `Directory.Build.props` | 权威在 sdk 仓库,这里只是副本。改它必须跟着 SDK 走 |
+
+契约 SDK 的版本刻意写成**字面量**、不抽成 MSBuild 属性:`Version="$(...)"` 会让
+Dependabot 与 `dotnet add package` 认不出这条依赖,而这个包正是要靠它们来更新的。
 
 第二个有构建期硬核对:`VelaShell.PluginSdk` 包把权威值导出成
 `$(VelaSdkPinnedAvaloniaVersion)`,`VerifyAvaloniaVersionPin` 拿它跟本仓库的副本、
@@ -87,7 +90,7 @@ pwsh scripts/Invoke-Smoke.ps1 -Feed ./artifacts/nuget -Version 1.5.0
 **插件工程是仓库外环境,仓库内的构建约定一条也吃不到**,而这个冒烟的全部价值就在这里。
 
 想验一版还没发布的契约 SDK:在 sdk 仓库 `dotnet pack -o <这里>/local-packages`,
-再把 `VelaSdkDependencyVersion` 临时指过去(见 `nuget.config` 的注释)。
+再把两个 csproj 里 `VelaShell.PluginSdk` 的版本临时指过去(见 `nuget.config` 的注释)。
 
 本仓库**不做强名称签名**,因此不需要 `STRONG_NAME_KEY` —— 未签名程序集可以引用
 已签名的,方向是对的。

docs-en/cli.md

@@ -1,7 +1,7 @@
 # `vela-plugin` CLI Manual
 
 > Applies to vela-plugin **1.5.0** (`vela-plugin --version` tells you what you have).
-> See also (other repositories): [Development Guide](https://github.com/joesdu/velashell-plugin-templates/blob/main/docs-en/dev-guide.md) · [Packaging and Publishing](https://github.com/joesdu/velashell-plugin-templates/blob/main/docs-en/publishing.md) · [SDK Reference](https://github.com/VelaShellLabs/velashell-plugin-sdk/blob/main/docs-en/sdk-reference.md)
+> See also (other repositories): [Development Guide](https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs-en/dev-guide.md) · [Packaging and Publishing](https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs-en/publishing.md) · [SDK Reference](https://github.com/VelaShellLabs/velashell-plugin-sdk/blob/main/docs-en/sdk-reference.md)
 
 `vela-plugin` is the plugin author's command-line tool. It calls the same implementation the
 host uses (`VelaShell.PluginSdk`: manifest parsing, `.vpx` container, signature verification),

docs/cli.md

@@ -1,7 +1,7 @@
 # `vela-plugin` 命令行手册
 
 > 适用版本:vela-plugin **1.5.0**(`vela-plugin --version` 看本机装的是哪版)。
-> 相关文档(在别的仓库):[开发指南](https://github.com/joesdu/velashell-plugin-templates/blob/main/docs/dev-guide.md) · [打包与发布](https://github.com/joesdu/velashell-plugin-templates/blob/main/docs/publishing.md) · [SDK 参考](https://github.com/VelaShellLabs/velashell-plugin-sdk/blob/main/docs/sdk-reference.md)
+> 相关文档(在别的仓库):[开发指南](https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs/dev-guide.md) · [打包与发布](https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs/publishing.md) · [SDK 参考](https://github.com/VelaShellLabs/velashell-plugin-sdk/blob/main/docs/sdk-reference.md)
 
 `vela-plugin` 是插件作者的命令行工具。它与宿主共用同一份实现(`VelaShell.PluginSdk`
 里的清单解析、`.vpx` 容器读写、签名校验),所以**不存在"工具认、宿主不认"的缝**。

docs/release-process.md

@@ -3,7 +3,7 @@
 > 本篇只讲**本仓库**怎么发版。契约 SDK 见
 > [velashell-plugin-sdk](https://github.com/VelaShellLabs/velashell-plugin-sdk/blob/main/docs/release-process.md),
 > `dotnet new` 模板见
-> [velashell-plugin-templates](https://github.com/joesdu/velashell-plugin-templates/blob/main/docs/release-process.md)。
+> [velashell-plugin-templates](https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs/release-process.md)。
 
 本仓库一次发布产出两个包,共用 Release 标签里的版本号:
 
@@ -103,12 +103,17 @@ Actions 页面 → 选 Release 工作流 → Run workflow → 填标签。推送
 
 ## 四、两个跨仓库旋钮:`Set-Version.ps1` 刻意不碰
 
-都在 `Directory.Build.props`。它们不是「版本号」,是**依赖决定**:
+它们不是「版本号」,是**依赖决定**:
 
-### `VelaSdkDependencyVersion` —— 引用哪一版契约 SDK
+### `VelaShell.PluginSdk` 的 `PackageReference` —— 引用哪一版契约 SDK
+
+落点是 `src/VelaShell.Plugin.Cli` 与 `src/VelaShell.PluginSdk.Build` 两个 csproj,
+**两处必须同版本**。刻意写字面量而不抽成 `Directory.Build.props` 里的 MSBuild 属性:
+`Version="$(...)"` 会让 Dependabot 与 `dotnet add package` 认不出这条依赖,而这个包
+正是要靠它们来更新的 —— 合掉 Dependabot 的 PR 就是常规抬法,它会把两处一起抬。
 
 抬它 = 让插件作者的**编译目标契约**变新。发一个只改了 `vela-plugin` 输出格式的补丁版时,
-不该顺手把这个也换掉 —— 所以它是一次独立的、需要想清楚的手工修改。
+不该顺手把这个也换掉 —— 所以它是一次独立的、需要想清楚的决定。
 
 抬完记得:
 
@@ -145,7 +150,7 @@ Actions 页面 → 选 Release 工作流 → Run workflow → 填标签。推送
 
 看你想不想让 `dotnet new velaplugin` 生成的工程指向新版 `.Build`。
 
-想 → 去 [velashell-plugin-templates](https://github.com/joesdu/velashell-plugin-templates)
+想 → 去 [velashell-plugin-templates](https://github.com/VelaShellLabs/velashell-plugin-templates)
 抬 `VelaBuildPackageVersion` 再发一版模板。
 
 不想 → 什么都不用做。新建的工程只是继续引用上一版 `.Build` 包,那是完全可用的 ——

scripts/Invoke-Smoke.ps1

@@ -5,7 +5,7 @@
 
 .DESCRIPTION
     拆库(2026-08-27)之前这一步是"装模板 → dotnet new → 构建 → 出 .vpx"。模板搬去
-    joesdu/velashell-plugin-templates 之后,本仓库不能再依赖那个包来验自己的包
+    VelaShellLabs/velashell-plugin-templates 之后,本仓库不能再依赖那个包来验自己的包
     —— 否则模板仓库出问题会让本仓库的 CI 无端变红,而且发本仓库的包时还得先有模板包。
 
     所以夹具改成自带:tests/smoke/ 下是一个**手写的最小插件工程**,与 velaplugin-ui

scripts/Set-Version.ps1

@@ -17,10 +17,11 @@
 
     docs 那两处不影响功能,但它们是给人照抄的,过期版本号会被原样粘进别人的工程。
 
-    **注意本脚本不碰 VelaSdkDependencyVersion。** 那是"本仓库引用哪一版契约 SDK",
+    **注意本脚本不碰 VelaShell.PluginSdk 的引用版本。** 那是"本仓库引用哪一版契约 SDK",
     与"本仓库自己发什么版本"是两件事 —— 拆库(2026-08-27)之后正是要让它们分开:
     发一个只改了 vela-plugin 输出格式的补丁版,不该顺手把插件作者的编译目标契约也换掉。
-    要抬契约版本就手工改 Directory.Build.props,那是一次独立的、需要想清楚的决定。
+    要抬契约版本就直接改两个 csproj 里的 PackageReference(或合掉 Dependabot 的 PR),
+    那是一次独立的、需要想清楚的决定。
 
     **不在本仓库的落点**(各自由所在仓库的同名脚本管):
       · VelaPluginApi.SdkVersion / apiLevel 纪律 ……… velashell-plugin-sdk

src/VelaShell.PluginSdk.Build/README.md

@@ -36,4 +36,4 @@ dotnet build -c Release -t:PackVpx -p:VelaSigningKey=/path/to/key.pem
 | `VelaValidateManifestOnBuild` | `true` | 构建后是否校验清单 |
 | `VelaSkipAvaloniaVersionCheck` | `false` | 跳过 Avalonia 版本一致性检查 |
 
-完整开发指南:<https://github.com/joesdu/velashell-plugin-templates/blob/main/docs/dev-guide.md>
+完整开发指南:<https://github.com/VelaShellLabs/velashell-plugin-templates/blob/main/docs/dev-guide.md>

src/VelaShell.PluginSdk.Build/VelaShell.PluginSdk.Build.csproj

@@ -28,7 +28,12 @@
          插件工程里的 .axaml 根本不会被编译,现象是运行时找不到控件而不是构建报错。 -->
     <PackageReference Include="Avalonia" Version="[$(VelaAvaloniaVersion)]" ExcludeAssets="runtime" PrivateAssets="none" />
     <!-- 拆库(2026-08-27)之后契约 SDK 也走 NuGet(原先是 ProjectReference)。
-         版本旋钮 VelaSdkDependencyVersion 在仓库根 Directory.Build.props。
+         版本就写在下面这一行的字面量上,由 NuGet(或合掉 Dependabot 的 PR)直接更新
+         —— **不要**把它抽成 MSBuild 属性:Version="$(...)" 会让 Dependabot 与
+         `dotnet add package` 认不出这条依赖,而这个包正是要靠它们来更新的。
+         ⚠️ src/VelaShell.Plugin.Cli 里还有一条同包引用,两处必须同版本:.Build 传给
+         插件工程的那份契约,与打包器在插件作者机器上加载的那份,漂了就是同名类型
+         来自两份不同程序集。Dependabot 会把两处一起抬,手工改时别落下另一处。
          这一条同时是下面 VerifyAvaloniaVersionPin 的**信息来源**:SDK 包的
          buildTransitive props 会把权威 Avalonia 版本导出成 $(VelaSdkPinnedAvaloniaVersion)。 -->
     <PackageReference Include="VelaShell.PluginSdk" Version="1.5.1" ExcludeAssets="runtime" PrivateAssets="none" />
@@ -73,11 +78,11 @@
 
     <Error Condition="'$(VelaSdkPinnedAvaloniaVersion)' == ''"
            Code="VELA1005"
-           Text="The referenced VelaShell.PluginSdk package ($(VelaSdkDependencyVersion)) does not export VelaSdkPinnedAvaloniaVersion. That property is the only channel through which the contract SDK tells this package which Avalonia the host loads; without it the cross-repository pin check is silently disabled. Reference VelaShell.PluginSdk 1.5.0 or newer (set VelaSdkDependencyVersion in Directory.Build.props)." />
+           Text="The referenced VelaShell.PluginSdk package does not export VelaSdkPinnedAvaloniaVersion. That property is the only channel through which the contract SDK tells this package which Avalonia the host loads; without it the cross-repository pin check is silently disabled. Bump the VelaShell.PluginSdk PackageReference in this project (and the matching one in src/VelaShell.Plugin.Cli) to 1.5.0 or newer." />
 
     <Error Condition="'$(VelaSdkPinnedAvaloniaVersion)' != '' and '$(VelaSdkPinnedAvaloniaVersion)' != '$(VelaAvaloniaVersion)'"
            Code="VELA1006"
-           Text="Avalonia version pin drifted across repositories: VelaShell.PluginSdk $(VelaSdkDependencyVersion) pins Avalonia '$(VelaSdkPinnedAvaloniaVersion)' (that is the authoritative value, and the value the VelaShell host is verified against), but this repository pins '$(VelaAvaloniaVersion)'. Plugins built with this package would compile against an Avalonia the host does not load. Update VelaAvaloniaVersion in Directory.Build.props and build/VelaShell.PluginSdk.Build.props to '$(VelaSdkPinnedAvaloniaVersion)', or point VelaSdkDependencyVersion at the SDK release that matches." />
+           Text="Avalonia version pin drifted across repositories: VelaShell.PluginSdk $(VelaSdkPackageVersion) pins Avalonia '$(VelaSdkPinnedAvaloniaVersion)' (that is the authoritative value, and the value the VelaShell host is verified against), but this repository pins '$(VelaAvaloniaVersion)'. Plugins built with this package would compile against an Avalonia the host does not load. Update VelaAvaloniaVersion in Directory.Build.props and build/VelaShell.PluginSdk.Build.props to '$(VelaSdkPinnedAvaloniaVersion)', or move the VelaShell.PluginSdk PackageReference to the SDK release that matches." />
   </Target>
 
   <!-- 把 vela-plugin 的构建产物收进包的 tools/net11.0/(dotnet exec 需要 dll + runtimeconfig + deps)。