diff --git a/AGENTS.md b/AGENTS.md
index d3e42ee..da0e759 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,8 @@ dotnet run --project src/GUI # Launch the Avalonia de
## Known Issues / Gotchas
+- **升级 Avalonia 版本时，必须同步更新所有次级包引用。** 仅修改主包 `Avalonia` 的 Version 不会自动更新 `Avalonia.Desktop`、`Avalonia.Themes.Fluent`、`Avalonia.Fonts.Inter` 等次级包。必须手动逐个修改，然后执行 `dotnet clean && dotnet restore`。否则运行时的原生库（如 `libAvaloniaNative.dylib`）会混用新旧版本，导致 macOS 上的 `StorageProvider` 文件/文件夹选择对话框在回调时 SIGSEGV 崩溃。
+ - 相关 Avalonia issues: [#21102](https://github.com/AvaloniaUI/Avalonia/issues/21102), [#21150](https://github.com/AvaloniaUI/Avalonia/issues/21150), [#21313](https://github.com/AvaloniaUI/Avalonia/issues/21313)，修复 PR: [#21104](https://github.com/AvaloniaUI/Avalonia/pull/21104)。
- **Tests create temp files/directories** under `Path.GetTempPath()` and clean them up via `IDisposable`. Don't rely on a real audio directory for tests.
- **`AudioMetadataReader` tests** use real WAV files from `data/source/` (not in git). When files are absent, tests silently return early (`if (wavFiles.Length == 0) return;`) — they pass without actually running assertions, not `Skip.If`. Running `dotnet test` will report 12 passes regardless of whether the fixture files exist.
- **`.atl.txt` fixture files** are generated by `AtlFieldExtractor`. If the WAV files or the ATL library version change, re-run the extractor to regenerate them before running metadata tests.
diff --git a/src/GUI/GUI.csproj b/src/GUI/GUI.csproj
index 4a94da3..36d9b4a 100644
--- a/src/GUI/GUI.csproj
+++ b/src/GUI/GUI.csproj
@@ -14,16 +14,17 @@
-
-
-
-
+
+
+
+
None
All
+