diff --git a/AGENTS.md b/AGENTS.md
index da0e759..d6cc679 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,10 @@ dotnet run --project src/GUI                            # Launch the Avalonia de
 
 ## Known Issues / Gotchas
 
+
+- 扫描时如果报错，报错信息可能会填满整个窗口，导致Overlay无法关闭。
+- 读取时如果报错，没有任何警告，会静默报错。需要有一个界面右下方的toast，或是发送系统通知告知用户遇到了错误。
+- 扫描界面的宽度会因为文件名而发生变化。固定为窗口宽度的50%。如果文件名超过这个宽度则省略中间的字符，仅保留开头以及最后10个字符。
 - **升级 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.
diff --git a/src/GUI/ViewModels/ScanProgressViewModel.cs b/src/GUI/ViewModels/ScanProgressViewModel.cs
index 0f60be9..05b89da 100644
--- a/src/GUI/ViewModels/ScanProgressViewModel.cs
+++ b/src/GUI/ViewModels/ScanProgressViewModel.cs
@@ -25,10 +25,21 @@ public partial class ScanProgressViewModel : ViewModelBase
         Task.Run(() => ScanDirectoryInternal(directory));
     }
 
+    [ObservableProperty] private bool _hasError;
+
+    [RelayCommand]
+    private void Dismiss()
+    {
+        IsScanning = false;
+        HasError = false;
+        StatusText = "准备扫描...";
+    }
+
     private void ScanDirectoryInternal(string directory)
     {
         try
         {
+            HasError = false;
             IsScanning = true;
             StatusText = "正在发现文件...";
 
@@ -93,11 +104,13 @@ public partial class ScanProgressViewModel : ViewModelBase
         }
         catch (Exception ex)
         {
+            HasError = true;
             StatusText = $"扫描出错：{ex.Message}";
         }
         finally
         {
-            IsScanning = false;
+            if (!HasError)
+                IsScanning = false;
             ScanCompleted?.Invoke();
         }
     }
diff --git a/src/GUI/Views/MainWindow.axaml b/src/GUI/Views/MainWindow.axaml
index 6364cd1..a1862be 100644
--- a/src/GUI/Views/MainWindow.axaml
+++ b/src/GUI/Views/MainWindow.axaml
@@ -51,6 +51,15 @@
                     BorderThickness="1,0,0,0">
                 <views:MetadataPanelView DataContext="{Binding MetadataPanelVM}"/>
             </Border>
+
+            <!-- 扫描进度遮罩 -->
+            <Border Grid.ColumnSpan="5"
+                    IsVisible="{Binding ScanProgressVM.IsScanning}"
+                    Background="#80000000">
+                <views:ScanProgressView DataContext="{Binding ScanProgressVM}"
+                                        HorizontalAlignment="Center"
+                                        VerticalAlignment="Center"/>
+            </Border>
         </Grid>
 
         <!-- 底部播放栏 -->
diff --git a/src/GUI/Views/ScanProgressView.axaml b/src/GUI/Views/ScanProgressView.axaml
index cd9796d..669034f 100644
--- a/src/GUI/Views/ScanProgressView.axaml
+++ b/src/GUI/Views/ScanProgressView.axaml
@@ -29,6 +29,8 @@
             </StackPanel>
             <TextBlock Text="{Binding CurrentFile}" FontSize="11"
                        TextTrimming="CharacterEllipsis" MaxWidth="368"/>
+            <Button Content="关闭" Command="{Binding DismissCommand}"
+                    IsVisible="{Binding HasError}" HorizontalAlignment="Right"/>
         </StackPanel>
     </Border>
 </UserControl>
diff --git a/src/Resonance.sln.DotSettings.user b/src/Resonance.sln.DotSettings.user
index 9c6f2d2..762a05c 100755
--- a/src/Resonance.sln.DotSettings.user
+++ b/src/Resonance.sln.DotSettings.user
@@ -26,6 +26,11 @@
     &lt;TestId&gt;xUnit::24F92458-FB39-44BE-A32F-41275183AF1B::net10.0::Core.Tests.IntegratedTest.ScanReadWritePipeline_ShouldGenerateDatabase&lt;/TestId&gt;
     &lt;TestId&gt;xUnit::24F92458-FB39-44BE-A32F-41275183AF1B::net10.0::Core.Tests.IntegratedTest&lt;/TestId&gt;
   &lt;/TestAncestor&gt;
+&lt;/SessionState&gt;</s:String>
+	<s:String x:Key="/Default/Environment/UnitTesting/UnitTestSessionStore/Sessions/=7a0de69d_002D085d_002D444a_002D9fbe_002D33683c7b6cab/@EntryIndexedValue">&lt;SessionState ContinuousTestingMode="0" IsActive="True" Name="DatabaseTests" xmlns="urn:schemas-jetbrains-com:jetbrains-ut-session"&gt;
+  &lt;TestAncestor&gt;
+    &lt;TestId&gt;xUnit::24F92458-FB39-44BE-A32F-41275183AF1B::net10.0::Core.Tests.DatabaseTests&lt;/TestId&gt;
+  &lt;/TestAncestor&gt;
 &lt;/SessionState&gt;</s:String>
 	<s:Boolean x:Key="/Default/ResxEditorPersonal/CheckedGroups/=GUI_002FAssets_002FLocale/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/ResxEditorPersonal/CheckedGroups/=GUI_002FLocale/@EntryIndexedValue">False</s:Boolean>