docs: 在 AGENTS.md 记录 WindowsAppSDK 2.4.0 self-contained 打包 bug + 修法

首次 build 后启动会报 AppNotificationManager.Register() 0x8007007E 找不到 Microsoft.WindowsAppRuntime.Insights.Resource.dll。

原因是 WindowsAppSDK 2.4.0 的 NuGet 包没把 Insights Resource DLL 打进 build 目录,只在系统级 WindowsAppRuntime 安装里才有。

提供两种修法:

- dev:从 C:\Program Files\WSL\wslsettings\(或任何已装 WindowsAppSDK 的程序)拷贝 5 个 DLL 到 build 目录

- prod:目标机器装 WindowsAppRuntime system-wide(winget install Microsoft.WindowsAppRuntime.2),或者 publish 后手工补这 5 个 DLL

已在 Gitea 的 build 验证里实测有效。
This commit is contained in:
2026-09-06 20:30:48 +08:00
parent e53c0585f7
commit 4c2575317e
+4 -2
View File
@@ -66,8 +66,10 @@ V1 暂不做(避免范围蔓延):多 Gotify Server、消息过滤、GUI 完整
```
- 反向代理(Nginx / NPM)必须透传 WebSocket Upgrade 头,详见方案文档第 14 节
- 任意代码改动后必须执行: `dotnet restore && dotnet build -c Release`,并在目标 Windows 10/11 上跑一次端到端
## Gotify protocol 约束
- **已知 WindowsAppSDK 2.4.0 self-contained 打包 bug**:`dotnet build` 出来的 `bin\...\win-x64\` 缺 `Microsoft.WindowsAppRuntime.Insights.Resource.dll`,首次启动 `AppNotificationManager.Register()` 会报 `0x8007007E 找不到指定的模块`。
- 修法 A(dev):从已装 WindowsAppSDK 的程序(如 `C:\Program Files\WSL\wslsettings\`)拷贝 5 个 DLL 到 build 目录:
- `Microsoft.WindowsAppRuntime.Bootstrap.dll`、`Microsoft.WindowsAppRuntime.Bootstrap.Net.dll`、`Microsoft.WindowsAppRuntime.dll`、`Microsoft.WindowsAppRuntime.Insights.Resource.dll`、`Microsoft.WindowsAppRuntime.pri`
- 修法 B(prod):`dotnet publish` 后同样需要补这 5 个文件,或者目标机器装 WindowsAppRuntime system-wide(`winget install Microsoft.WindowsAppRuntime.2`)
- `/stream` 是 WebSocket 端点,`/message?limit=&since=` 是历史补偿端点,二者都只接受 `Client Token`
- 消息去重锚点 = `state.LastMessageId`,只处理 `Id > LastMessageId` 的消息,启动时用 `since=LastMessageId` 拉增量