fix.开发者调试工具设置无法正常持久化的问题。修复了插件无法进行更新的问题。

2026-06-25 19:24:28 +08:00 · 2026-04-14 00:22:02 +08:00
parent 1b22e9df4a
commit b12dd68ba7
17 changed files with 1081 additions and 95 deletions
--- a/LanMountainDesktop/App.axaml.cs
+++ b/LanMountainDesktop/App.axaml.cs
@@ -404,10 +404,7 @@ public partial class App : Application
            _traySettingsMenuItem.Header = L("tray.menu.settings", "Settings");
        }

-        if (_trayComponentLibraryMenuItem is not null)
-        {
-            _trayComponentLibraryMenuItem.Header = L("tray.menu.component_library", "Component Library");
-        }
+        RefreshFusedDesktopMenuItemVisibility();

        if (_trayRestartMenuItem is not null)
        {
@@ -420,6 +417,30 @@ public partial class App : Application
        }
    }

+    private void RefreshFusedDesktopMenuItemVisibility()
+    {
+        if (_trayComponentLibraryMenuItem is null)
+        {
+            return;
+        }
+
+        // 仅在 Windows 上支持融合桌面功能
+        if (!OperatingSystem.IsWindows())
+        {
+            _trayComponentLibraryMenuItem.IsVisible = false;
+            return;
+        }
+
+        // 检查融合桌面功能是否启用
+        var appSnapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
+        _trayComponentLibraryMenuItem.IsVisible = appSnapshot.EnableFusedDesktop;
+
+        if (_trayComponentLibraryMenuItem.IsVisible)
+        {
+            _trayComponentLibraryMenuItem.Header = L("tray.menu.component_library", "Component Library");
+        }
+    }
+
    private void DisposeTrayIcon()
    {
        if (_trayIcon is null)
@@ -687,6 +708,16 @@ public partial class App : Application
                ApplyCurrentCultureFromSettings();
                RefreshTrayIconContent();
            }
+
+            // 检查融合桌面设置是否变更
+            var fusedDesktopChanged =
+                refreshAll ||
+                changedKeys.Contains(nameof(AppSettingsSnapshot.EnableFusedDesktop), StringComparer.OrdinalIgnoreCase);
+
+            if (fusedDesktopChanged)
+            {
+                RefreshFusedDesktopMenuItemVisibility();
+            }
        }, DispatcherPriority.Background);
    }

--- a/LanMountainDesktop/Models/AppSettingsSnapshot.cs
+++ b/LanMountainDesktop/Models/AppSettingsSnapshot.cs
@@ -152,6 +152,8 @@ public sealed class AppSettingsSnapshot

    public bool EnableThreeFingerSwipe { get; set; } = false;

+    public bool EnableFusedDesktop { get; set; } = false;
+
    public List<string> DisabledPluginIds { get; set; } = [];

    public bool IsDevModeEnabled { get; set; }
--- a/LanMountainDesktop/Services/FusedDesktopManagerService.cs
+++ b/LanMountainDesktop/Services/FusedDesktopManagerService.cs
@@ -58,6 +58,14 @@ internal sealed class FusedDesktopManagerService : IFusedDesktopManagerService
    {
        if (!OperatingSystem.IsWindows()) return;
        
+        // 检查融合桌面功能是否启用
+        var appSnapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
+        if (!appSnapshot.EnableFusedDesktop)
+        {
+            AppLogger.Info("FusedDesktop", "Fused desktop is disabled. Skipping initialization.");
+            return;
+        }
+        
        EnsureRegistries();
        ReloadWidgets();
    }
--- a/LanMountainDesktop/Services/HostApplicationLifecycleService.cs
+++ b/LanMountainDesktop/Services/HostApplicationLifecycleService.cs
@@ -1,5 +1,6 @@
 using System;
 using System.Diagnostics;
+using System.IO;
 using Avalonia;
 using Avalonia.Controls.ApplicationLifetimes;
 using Avalonia.Threading;
@@ -9,6 +10,8 @@ namespace LanMountainDesktop.Services;

 public sealed class HostApplicationLifecycleService : IHostApplicationLifecycle
 {
+    private const string UpgradeHelperExecutableName = "LanMountainDesktop.PluginUpgradeHelper.exe";
+
    public bool TryExit(HostApplicationLifecycleRequest? request = null)
    {
        App? app = null;
@@ -50,28 +53,14 @@ public sealed class HostApplicationLifecycleService : IHostApplicationLifecycle
        App? app = null;
        try
        {
-            var startInfo = AppRestartService.CreateRestartStartInfo();
-            if (startInfo is null)
+            app = Application.Current as App;
+
+            if (HasPendingPluginUpgrades())
            {
-                AppLogger.Warn(
-                    "HostLifecycle",
-                    $"Restart request rejected because restart start info could not be resolved. Source='{request?.Source ?? "Unknown"}'.");
-                return false;
+                return TryRestartWithUpgradeHelper(request);
            }

-            Process.Start(startInfo);
-            app = Application.Current as App;
-            app?.PrepareForShutdown(isRestart: true, request?.Source ?? "Unknown");
-            var exitRequest = request is null
-                ? new HostApplicationLifecycleRequest(Reason: "Restart accepted.")
-                : request with
-                {
-                    Reason = string.IsNullOrWhiteSpace(request.Reason)
-                        ? "Restart accepted."
-                        : request.Reason
-                };
-
-            return TryExit(exitRequest);
+            return TryRestartDirectly(request);
        }
        catch (Exception ex)
        {
@@ -80,4 +69,92 @@ public sealed class HostApplicationLifecycleService : IHostApplicationLifecycle
            return false;
        }
    }
+
+    private static bool HasPendingPluginUpgrades()
+    {
+        try
+        {
+            var pluginsDirectory = Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                "LanMountainDesktop",
+                "Extensions",
+                "Plugins");
+            var pendingUpgradesPath = Path.Combine(pluginsDirectory, ".pending-plugin-upgrades.json");
+            return File.Exists(pendingUpgradesPath);
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private bool TryRestartWithUpgradeHelper(HostApplicationLifecycleRequest? request)
+    {
+        AppLogger.Info("HostLifecycle", "Detected pending plugin upgrades. Using upgrade helper for restart.");
+
+        var helperPath = ResolveUpgradeHelperPath();
+        if (!File.Exists(helperPath))
+        {
+            AppLogger.Warn("HostLifecycle", $"Upgrade helper not found at '{helperPath}'. Falling back to direct restart.");
+            return TryRestartDirectly(request);
+        }
+
+        var pluginsDirectory = Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+            "LanMountainDesktop",
+            "Extensions",
+            "Plugins");
+
+        var startInfo = AppRestartService.CreateRestartStartInfo();
+        var launchCommand = startInfo?.FileName ?? Process.GetCurrentProcess().MainModule?.FileName ?? AppContext.BaseDirectory;
+        var launchArgs = startInfo?.Arguments ?? "";
+
+        var helperStartInfo = new ProcessStartInfo
+        {
+            FileName = helperPath,
+            Arguments = $"--plugins-dir \"{pluginsDirectory}\" --parent-pid {Environment.ProcessId} --launch \"{launchCommand}\" --launch-args \"{launchArgs}\" --working-dir \"{AppContext.BaseDirectory}\"",
+            UseShellExecute = true,
+            WorkingDirectory = AppContext.BaseDirectory
+        };
+
+        AppLogger.Info("HostLifecycle", $"Starting upgrade helper: {helperStartInfo.FileName} {helperStartInfo.Arguments}");
+
+        Process.Start(helperStartInfo);
+
+        var app = Application.Current as App;
+        app?.PrepareForShutdown(isRestart: true, request?.Source ?? "Unknown");
+
+        return TryExit(request);
+    }
+
+    private bool TryRestartDirectly(HostApplicationLifecycleRequest? request)
+    {
+        var startInfo = AppRestartService.CreateRestartStartInfo();
+        if (startInfo is null)
+        {
+            AppLogger.Warn(
+                "HostLifecycle",
+                $"Restart request rejected because restart start info could not be resolved. Source='{request?.Source ?? "Unknown"}'.");
+            return false;
+        }
+
+        Process.Start(startInfo);
+        var app = Application.Current as App;
+        app?.PrepareForShutdown(isRestart: true, request?.Source ?? "Unknown");
+        var exitRequest = request is null
+            ? new HostApplicationLifecycleRequest(Reason: "Restart accepted.")
+            : request with
+            {
+                Reason = string.IsNullOrWhiteSpace(request.Reason)
+                    ? "Restart accepted."
+                    : request.Reason
+            };
+
+        return TryExit(exitRequest);
+    }
+
+    private static string ResolveUpgradeHelperPath()
+    {
+        return Path.Combine(AppContext.BaseDirectory, "PluginUpgradeHelper", UpgradeHelperExecutableName);
+    }
 }
--- a/LanMountainDesktop/Services/PendingPluginUpgradeService.cs
+++ b/LanMountainDesktop/Services/PendingPluginUpgradeService.cs
@@ -0,0 +1,160 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+
+namespace LanMountainDesktop.Services;
+
+public sealed class PendingPluginUpgradeService
+{
+    private const string PendingUpgradesFileName = ".pending-plugin-upgrades.json";
+    private static readonly Lock Gate = new();
+    private readonly string _pendingUpgradesFilePath;
+
+    public PendingPluginUpgradeService(string pluginsDirectory)
+    {
+        _pendingUpgradesFilePath = Path.Combine(pluginsDirectory, PendingUpgradesFileName);
+    }
+
+    public IReadOnlyList<PendingPluginUpgrade> GetPendingUpgrades()
+    {
+        lock (Gate)
+        {
+            return ReadPendingUpgradesCore();
+        }
+    }
+
+    public void AddPendingUpgrade(string pluginId, string sourcePackagePath, string targetVersion)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(pluginId);
+        ArgumentException.ThrowIfNullOrWhiteSpace(sourcePackagePath);
+        ArgumentException.ThrowIfNullOrWhiteSpace(targetVersion);
+
+        lock (Gate)
+        {
+            var upgrades = ReadPendingUpgradesCore().ToList();
+
+            upgrades.RemoveAll(u =>
+                string.Equals(u.PluginId, pluginId, StringComparison.OrdinalIgnoreCase));
+
+            upgrades.Add(new PendingPluginUpgrade(
+                pluginId,
+                Path.GetFullPath(sourcePackagePath),
+                targetVersion,
+                DateTimeOffset.UtcNow));
+
+            SavePendingUpgradesCore(upgrades);
+
+            AppLogger.Info(
+                "PendingPluginUpgrade",
+                $"Added pending upgrade. PluginId='{pluginId}'; TargetVersion='{targetVersion}'; SourcePath='{sourcePackagePath}'.");
+        }
+    }
+
+    public void RemovePendingUpgrade(string pluginId)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(pluginId);
+
+        lock (Gate)
+        {
+            var upgrades = ReadPendingUpgradesCore().ToList();
+            var removed = upgrades.RemoveAll(u =>
+                string.Equals(u.PluginId, pluginId, StringComparison.OrdinalIgnoreCase));
+
+            if (removed > 0)
+            {
+                SavePendingUpgradesCore(upgrades);
+                AppLogger.Info(
+                    "PendingPluginUpgrade",
+                    $"Removed pending upgrade. PluginId='{pluginId}'.");
+            }
+        }
+    }
+
+    public void ClearPendingUpgrades()
+    {
+        lock (Gate)
+        {
+            if (File.Exists(_pendingUpgradesFilePath))
+            {
+                File.Delete(_pendingUpgradesFilePath);
+                AppLogger.Info("PendingPluginUpgrade", "Cleared all pending upgrades.");
+            }
+        }
+    }
+
+    public bool HasPendingUpgrades()
+    {
+        lock (Gate)
+        {
+            return ReadPendingUpgradesCore().Count > 0;
+        }
+    }
+
+    private List<PendingPluginUpgrade> ReadPendingUpgradesCore()
+    {
+        if (!File.Exists(_pendingUpgradesFilePath))
+        {
+            return [];
+        }
+
+        try
+        {
+            var json = File.ReadAllText(_pendingUpgradesFilePath);
+            var upgrades = JsonSerializer.Deserialize<List<PendingPluginUpgrade>>(json);
+            return upgrades?.Where(u => u.IsValid()).ToList() ?? [];
+        }
+        catch (Exception ex)
+        {
+            AppLogger.Warn(
+                "PendingPluginUpgrade",
+                $"Failed to read pending upgrades from '{_pendingUpgradesFilePath}'.",
+                ex);
+            return [];
+        }
+    }
+
+    private void SavePendingUpgradesCore(List<PendingPluginUpgrade> upgrades)
+    {
+        try
+        {
+            var directory = Path.GetDirectoryName(_pendingUpgradesFilePath);
+            if (!string.IsNullOrWhiteSpace(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            var json = JsonSerializer.Serialize(upgrades, new JsonSerializerOptions
+            {
+                WriteIndented = true
+            });
+
+            File.WriteAllText(_pendingUpgradesFilePath, json);
+        }
+        catch (Exception ex)
+        {
+            AppLogger.Error(
+                "PendingPluginUpgrade",
+                $"Failed to save pending upgrades to '{_pendingUpgradesFilePath}'.",
+                ex);
+            throw;
+        }
+    }
+}
+
+public sealed record PendingPluginUpgrade(
+    string PluginId,
+    string SourcePackagePath,
+    string TargetVersion,
+    DateTimeOffset CreatedAt)
+{
+    public bool IsValid()
+    {
+        return !string.IsNullOrWhiteSpace(PluginId) &&
+               !string.IsNullOrWhiteSpace(SourcePackagePath) &&
+               !string.IsNullOrWhiteSpace(TargetVersion) &&
+               File.Exists(SourcePackagePath);
+    }
+}
--- a/LanMountainDesktop/ViewModels/SettingsViewModels.cs
+++ b/LanMountainDesktop/ViewModels/SettingsViewModels.cs
@@ -174,9 +174,6 @@ public sealed partial class GeneralSettingsPageViewModel : ViewModelBase, IDispo
        private bool _isInitializing;
        private bool _disposed;

-        [ObservableProperty]
-        private bool _enableThreeFingerSwipe;
-
    public GeneralSettingsPageViewModel(ISettingsFacadeService settingsFacade)
    {
        _settingsFacade = settingsFacade;
@@ -204,7 +201,6 @@ public sealed partial class GeneralSettingsPageViewModel : ViewModelBase, IDispo
        SelectedRenderMode = RenderModes.FirstOrDefault(option =>
            string.Equals(option.Value, normalizedRenderMode, StringComparison.OrdinalIgnoreCase))
            ?? RenderModes[0];
-        EnableThreeFingerSwipe = appSnapshot.EnableThreeFingerSwipe;
        _isInitializing = false;

        RefreshPreview();
@@ -236,33 +232,6 @@ public sealed partial class GeneralSettingsPageViewModel : ViewModelBase, IDispo
        {
            return;
        }
-        
-        // 如果是其他设置变更，重新加载我们的设置
-        _isInitializing = true;
-        try
-        {
-            var appSnapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
-            EnableThreeFingerSwipe = appSnapshot.EnableThreeFingerSwipe;
-        }
-        finally
-        {
-            _isInitializing = false;
-        }
-    }
-
-    partial void OnEnableThreeFingerSwipeChanged(bool value)
-    {
-        if (_isInitializing)
-        {
-            return;
-        }
-
-        var appSnapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
-        appSnapshot.EnableThreeFingerSwipe = value;
-        _settingsFacade.Settings.SaveSnapshot(
-            SettingsScope.App,
-            appSnapshot,
-            changedKeys: [nameof(AppSettingsSnapshot.EnableThreeFingerSwipe)]);
    }

    public event Action? RestartRequested;
@@ -3100,6 +3069,9 @@ public sealed partial class DevSettingsPageViewModel : ViewModelBase
        _isInitializing = true;
        LoadSettings();
        _isInitializing = false;
+
+        // 监听设置变更，防止被意外重置
+        _settingsFacade.Settings.Changed += OnSettingsChanged;
    }

    [ObservableProperty]
@@ -3108,6 +3080,12 @@ public sealed partial class DevSettingsPageViewModel : ViewModelBase
    [ObservableProperty]
    private string _devPluginPath = string.Empty;

+    [ObservableProperty]
+    private bool _enableThreeFingerSwipe;
+
+    [ObservableProperty]
+    private bool _enableFusedDesktop;
+
    partial void OnIsDevModeEnabledChanged(bool value)
    {
        if (_isInitializing) return;
@@ -3120,11 +3098,52 @@ public sealed partial class DevSettingsPageViewModel : ViewModelBase
        SaveField(nameof(AppSettingsSnapshot.DevPluginPath), value);
    }

+    partial void OnEnableThreeFingerSwipeChanged(bool value)
+    {
+        if (_isInitializing) return;
+        SaveField(nameof(AppSettingsSnapshot.EnableThreeFingerSwipe), value);
+    }
+
+    partial void OnEnableFusedDesktopChanged(bool value)
+    {
+        if (_isInitializing) return;
+        SaveField(nameof(AppSettingsSnapshot.EnableFusedDesktop), value);
+    }
+
    private void LoadSettings()
    {
        var snapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
        IsDevModeEnabled = snapshot.IsDevModeEnabled;
        DevPluginPath = snapshot.DevPluginPath ?? string.Empty;
+        EnableThreeFingerSwipe = snapshot.EnableThreeFingerSwipe;
+        EnableFusedDesktop = snapshot.EnableFusedDesktop;
+    }
+
+    private void OnSettingsChanged(object? sender, SettingsChangedEvent e)
+    {
+        if (e.Scope != SettingsScope.App)
+        {
+            return;
+        }
+
+        var changedKeys = e.ChangedKeys?.ToArray();
+        if (changedKeys is null || changedKeys.Length == 0)
+        {
+            return;
+        }
+
+        // 如果是其他设置变更，重新加载我们的设置
+        _isInitializing = true;
+        try
+        {
+            var snapshot = _settingsFacade.Settings.LoadSnapshot<AppSettingsSnapshot>(SettingsScope.App);
+            EnableThreeFingerSwipe = snapshot.EnableThreeFingerSwipe;
+            EnableFusedDesktop = snapshot.EnableFusedDesktop;
+        }
+        finally
+        {
+            _isInitializing = false;
+        }
    }

    private void SaveField<T>(string key, T value)
--- a/LanMountainDesktop/Views/SettingsPages/DevSettingsPage.axaml
+++ b/LanMountainDesktop/Views/SettingsPages/DevSettingsPage.axaml
@@ -25,6 +25,26 @@
                </ui:SettingsExpander.Footer>
            </ui:SettingsExpander>

+            <ui:SettingsExpander Header="启用三指滑动"
+                                 Description="使用三根手指或鼠标右键拖动自由滑动页面，在第一页向右滑动可回到 Windows 桌面（实验性功能）">
+                <ui:SettingsExpander.IconSource>
+                    <fi:SymbolIconSource Symbol="Gesture" />
+                </ui:SettingsExpander.IconSource>
+                <ui:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding EnableThreeFingerSwipe}" />
+                </ui:SettingsExpander.Footer>
+            </ui:SettingsExpander>
+
+            <ui:SettingsExpander Header="启用融合桌面"
+                                 Description="允许将组件放置在 Windows 系统桌面上（实验性功能，重启后生效）">
+                <ui:SettingsExpander.IconSource>
+                    <fi:SymbolIconSource Symbol="Apps" />
+                </ui:SettingsExpander.IconSource>
+                <ui:SettingsExpander.Footer>
+                    <ToggleSwitch IsChecked="{Binding EnableFusedDesktop}" />
+                </ui:SettingsExpander.Footer>
+            </ui:SettingsExpander>
+
            <Separator Classes="settings-separator" />

            <ui:SettingsExpander Header="开发者插件路径"
--- a/LanMountainDesktop/Views/SettingsPages/GeneralSettingsPage.axaml
+++ b/LanMountainDesktop/Views/SettingsPages/GeneralSettingsPage.axaml
@@ -14,13 +14,6 @@
                               Text="{Binding BasicHeader}"
                               Margin="0,0,0,4" />

-            <ui:SettingsExpander Header="启用三指滑动"
-                                 Description="使用三根手指或鼠标右键拖动自由滑动页面，在第一页向右滑动可回到 Windows 桌面">
-                <ui:SettingsExpander.Footer>
-                    <ToggleSwitch IsChecked="{Binding EnableThreeFingerSwipe}" />
-                </ui:SettingsExpander.Footer>
-            </ui:SettingsExpander>
-
            <ui:SettingsExpander Header="{Binding LanguageHeader}">
                <ui:SettingsExpander.IconSource>
                    <fi:SymbolIconSource Symbol="Settings" />
--- a/LanMountainDesktop/plugins/PluginMarketEmbeddedView.cs
+++ b/LanMountainDesktop/plugins/PluginMarketEmbeddedView.cs
@@ -784,12 +784,28 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable
            }

            RefreshInstalledSnapshot();
-            SetStatus(
-                F(
-                    "market.status.install_success_format",
-                    "Plugin '{0}' has been staged. Restart the app to apply it.",
-                    result.Manifest.Name),
-                SuccessBrush);
+
+            if (result.RestartRequired)
+            {
+                SetStatus(
+                    F(
+                        "market.status.upgrade_staged_format",
+                        "Plugin '{0}' v{1} has been downloaded. Restart to complete the upgrade.",
+                        result.Manifest.Name,
+                        result.Manifest.Version),
+                    WarningBrush);
+                PendingRestartStateService.SetPending(PendingRestartStateService.PluginCatalogReason, true);
+            }
+            else
+            {
+                SetStatus(
+                    F(
+                        "market.status.install_success_format",
+                        "Plugin '{0}' has been installed successfully.",
+                        result.Manifest.Name),
+                    SuccessBrush);
+            }
+
            RebuildSurface();
        }
        catch (OperationCanceledException) when (_lifetimeCts.IsCancellationRequested)
@@ -1015,14 +1031,22 @@ internal sealed class PluginMarketEmbeddedView : UserControl, IDisposable

    private static int CompareVersions(string? left, string? right)
    {
-        if (!AirAppMarketIndexDocument.TryParseVersion(left, out var leftVersion))
+        var leftParsed = AirAppMarketIndexDocument.TryParseVersion(left, out var leftVersion);
+        var rightParsed = AirAppMarketIndexDocument.TryParseVersion(right, out var rightVersion);
+
+        if (!leftParsed && !rightParsed)
        {
-            leftVersion = new Version(0, 0, 0);
+            return 0;
        }

-        if (!AirAppMarketIndexDocument.TryParseVersion(right, out var rightVersion))
+        if (!leftParsed)
        {
-            rightVersion = new Version(0, 0, 0);
+            return -1;
+        }
+
+        if (!rightParsed)
+        {
+            return 1;
        }

        return (leftVersion ?? new Version(0, 0, 0)).CompareTo(rightVersion ?? new Version(0, 0, 0));
--- a/LanMountainDesktop/plugins/PluginMarketInstallService.cs
+++ b/LanMountainDesktop/plugins/PluginMarketInstallService.cs
@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Net.Http;
+using System.Reflection;
 using System.Threading;
 using System.Threading.Tasks;
 using System.Security.Cryptography;
@@ -20,7 +21,9 @@ internal sealed class AirAppMarketInstallService : IDisposable
    private readonly HttpClient _httpClient;
    private readonly ResumableDownloadService _downloadService;
    private readonly AirAppMarketReleaseResolverService _releaseResolverService;
+    private readonly PendingPluginUpgradeService _pendingUpgradeService;
    private readonly string _downloadsDirectory;
+    private readonly Version? _hostVersion;

    public AirAppMarketInstallService(PluginRuntimeService runtime, string dataDirectory)
    {
@@ -33,6 +36,8 @@ internal sealed class AirAppMarketInstallService : IDisposable
        _httpClient.DefaultRequestHeaders.UserAgent.ParseAdd("LanMountainDesktop-PluginMarketplace/1.0");
        _downloadService = new ResumableDownloadService(_httpClient);
        _releaseResolverService = new AirAppMarketReleaseResolverService(_httpClient);
+        _pendingUpgradeService = new PendingPluginUpgradeService(runtime.PluginsDirectory);
+        _hostVersion = typeof(App).Assembly.GetName().Version;
    }

    public async Task<AirAppMarketInstallResult> InstallAsync(
@@ -41,18 +46,6 @@ internal sealed class AirAppMarketInstallService : IDisposable
    {
        ArgumentNullException.ThrowIfNull(plugin);

-        if (OperatingSystem.IsWindows())
-        {
-            var helperPath = ResolveHelperPath();
-            if (!File.Exists(helperPath))
-            {
-                return new AirAppMarketInstallResult(
-                    false,
-                    null,
-                    $"Plugins install helper was not found at '{helperPath}'.");
-            }
-        }
-
        Directory.CreateDirectory(_downloadsDirectory);
        var sources = plugin.GetPackageSourcesInInstallOrder();
        if (sources.Count == 0)
@@ -67,6 +60,39 @@ internal sealed class AirAppMarketInstallService : IDisposable
            "PluginMarket",
            $"Starting install. PluginId='{plugin.Id}'; Version='{plugin.Version}'; Sources='{string.Join(", ", sources.Select(source => source.SourceKind.ToString()))}'.");

+        var compatibilityError = ValidateCompatibility(plugin);
+        if (!string.IsNullOrWhiteSpace(compatibilityError))
+        {
+            AppLogger.Warn("PluginMarket", $"Compatibility check failed. PluginId='{plugin.Id}'; Error='{compatibilityError}'.");
+            return new AirAppMarketInstallResult(false, null, compatibilityError);
+        }
+
+        var isUpgrade = IsPluginInstalled(plugin.Id);
+        if (isUpgrade)
+        {
+            return await InstallUpgradeAsync(plugin, sources, cancellationToken).ConfigureAwait(false);
+        }
+
+        return await InstallNewAsync(plugin, sources, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task<AirAppMarketInstallResult> InstallNewAsync(
+        AirAppMarketPluginEntry plugin,
+        IReadOnlyList<AirAppMarketPluginPackageSourceEntry> sources,
+        CancellationToken cancellationToken)
+    {
+        if (OperatingSystem.IsWindows())
+        {
+            var helperPath = ResolveHelperPath();
+            if (!File.Exists(helperPath))
+            {
+                return new AirAppMarketInstallResult(
+                    false,
+                    null,
+                    $"Plugins install helper was not found at '{helperPath}'.");
+            }
+        }
+
        var sourceErrors = new List<string>();
        foreach (var source in sources)
        {
@@ -93,6 +119,88 @@ internal sealed class AirAppMarketInstallService : IDisposable
        return new AirAppMarketInstallResult(false, null, combinedMessage);
    }

+    private async Task<AirAppMarketInstallResult> InstallUpgradeAsync(
+        AirAppMarketPluginEntry plugin,
+        IReadOnlyList<AirAppMarketPluginPackageSourceEntry> sources,
+        CancellationToken cancellationToken)
+    {
+        AppLogger.Info("PluginMarket", $"Detected upgrade scenario. Downloading package for deferred upgrade. PluginId='{plugin.Id}'.");
+
+        foreach (var source in sources)
+        {
+            var downloadResult = await DownloadPackageAsync(plugin, source, cancellationToken).ConfigureAwait(false);
+            if (downloadResult.Success && !string.IsNullOrWhiteSpace(downloadResult.PackagePath))
+            {
+                _pendingUpgradeService.AddPendingUpgrade(plugin.Id, downloadResult.PackagePath, plugin.Version);
+
+                AppLogger.Info(
+                    "PluginMarket",
+                    $"Upgrade staged for next restart. PluginId='{plugin.Id}'; Version='{plugin.Version}'; PackagePath='{downloadResult.PackagePath}'.");
+
+                var manifest = ReadManifestFromPackage(downloadResult.PackagePath);
+                return new AirAppMarketInstallResult(true, manifest, null, RestartRequired: true);
+            }
+        }
+
+        return new AirAppMarketInstallResult(
+            false,
+            null,
+            $"Failed to download upgrade package for plugin '{plugin.Id}' from all available sources.");
+    }
+
+    private bool IsPluginInstalled(string pluginId)
+    {
+        return _runtime.Catalog.Any(entry =>
+            string.Equals(entry.Manifest.Id, pluginId, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private string? ValidateCompatibility(AirAppMarketPluginEntry plugin)
+    {
+        if (_hostVersion is null)
+        {
+            return null;
+        }
+
+        if (!string.IsNullOrWhiteSpace(plugin.MinHostVersion))
+        {
+            if (!AirAppMarketIndexDocument.TryParseVersion(plugin.MinHostVersion, out var minHostVersion) ||
+                minHostVersion is null)
+            {
+                return $"Plugin '{plugin.Id}' declares invalid minimum host version '{plugin.MinHostVersion}'.";
+            }
+
+            if (_hostVersion < minHostVersion)
+            {
+                return $"Plugin '{plugin.Id}' requires host version {plugin.MinHostVersion} or newer. Current host version is {_hostVersion}.";
+            }
+        }
+
+        if (!string.IsNullOrWhiteSpace(plugin.ApiVersion))
+        {
+            if (!AirAppMarketIndexDocument.TryParseVersion(plugin.ApiVersion, out var pluginApiVersion) ||
+                pluginApiVersion is null)
+            {
+                return $"Plugin '{plugin.Id}' declares invalid API version '{plugin.ApiVersion}'.";
+            }
+
+            var hostApiVersion = PluginSdkInfo.ApiVersion;
+            if (hostApiVersion is not null)
+            {
+                if (!AirAppMarketIndexDocument.TryParseVersion(hostApiVersion, out var hostApiVersionParsed) ||
+                    hostApiVersionParsed is null)
+                {
+                    AppLogger.Warn("PluginMarket", $"Host API version '{hostApiVersion}' could not be parsed. Skipping API version check.");
+                }
+                else if (pluginApiVersion.Major != hostApiVersionParsed.Major)
+                {
+                    return $"Plugin '{plugin.Id}' uses incompatible API version {plugin.ApiVersion}. Host API version is {hostApiVersion}. Major version must match.";
+                }
+            }
+        }
+
+        return null;
+    }
+
    private async Task<AirAppMarketInstallAttemptResult> TryInstallFromSourceAsync(
        AirAppMarketPluginEntry plugin,
        AirAppMarketPluginPackageSourceEntry source,
@@ -275,6 +383,71 @@ internal sealed class AirAppMarketInstallService : IDisposable
        }
    }

+    private async Task<DownloadPackageResult> DownloadPackageAsync(
+        AirAppMarketPluginEntry plugin,
+        AirAppMarketPluginPackageSourceEntry source,
+        CancellationToken cancellationToken)
+    {
+        var packagePath = Path.Combine(
+            _downloadsDirectory,
+            $"{SanitizeFileName(plugin.Id)}-{SanitizeFileName(plugin.Version)}-{SanitizeFileName(source.SourceKind.ToString())}-{Guid.NewGuid():N}.laapp");
+
+        try
+        {
+            var resolvedDownloadUrl = await _releaseResolverService.ResolveDownloadUrlAsync(plugin, source, cancellationToken).ConfigureAwait(false);
+            AppLogger.Info(
+                "PluginMarket",
+                $"Downloading upgrade package for '{plugin.Id}' from '{resolvedDownloadUrl}'.");
+
+            var acquireResult = await AcquirePackageAsync(plugin, source, resolvedDownloadUrl, packagePath, cancellationToken).ConfigureAwait(false);
+            if (!acquireResult.Success)
+            {
+                TryDeleteFile(packagePath);
+                return new DownloadPackageResult(false, null, acquireResult.ErrorMessage);
+            }
+
+            var verificationResult = await VerifyPackageAsync(plugin, packagePath, cancellationToken).ConfigureAwait(false);
+            if (!verificationResult.Success)
+            {
+                TryDeleteFile(packagePath);
+                return new DownloadPackageResult(false, null, verificationResult.ErrorMessage);
+            }
+
+            return new DownloadPackageResult(true, packagePath, null);
+        }
+        catch (OperationCanceledException)
+        {
+            TryDeleteFile(packagePath);
+            throw;
+        }
+        catch (Exception ex)
+        {
+            TryDeleteFile(packagePath);
+            return new DownloadPackageResult(false, null, ex.Message);
+        }
+    }
+
+    private static PluginManifest ReadManifestFromPackage(string packagePath)
+    {
+        using var archive = System.IO.Compression.ZipFile.OpenRead(packagePath);
+        var entries = archive.Entries
+            .Where(entry => string.Equals(entry.Name, "plugin.json", StringComparison.OrdinalIgnoreCase))
+            .ToArray();
+
+        if (entries.Length == 0)
+        {
+            throw new InvalidOperationException($"Plugin package '{packagePath}' does not contain 'plugin.json'.");
+        }
+
+        if (entries.Length > 1)
+        {
+            throw new InvalidOperationException($"Plugin package '{packagePath}' contains multiple 'plugin.json' files.");
+        }
+
+        using var stream = entries[0].Open();
+        return PluginManifest.Load(stream, $"{packagePath}!/{entries[0].FullName}");
+    }
+
    public void Dispose()
    {
        _httpClient.Dispose();
@@ -299,4 +472,9 @@ internal sealed class AirAppMarketInstallService : IDisposable
    private sealed record AirAppMarketVerificationResult(
        bool Success,
        string? ErrorMessage);
+
+    private sealed record DownloadPackageResult(
+        bool Success,
+        string? PackagePath,
+        string? ErrorMessage);
 }
--- a/LanMountainDesktop/plugins/PluginMarketModels.cs
+++ b/LanMountainDesktop/plugins/PluginMarketModels.cs
@@ -305,7 +305,8 @@ internal sealed record AirAppMarketLoadResult(
 internal sealed record AirAppMarketInstallResult(
    bool Success,
    PluginManifest? Manifest,
-    string? ErrorMessage);
+    string? ErrorMessage,
+    bool RestartRequired = false);

 internal sealed class AirAppMarketIndexDocument
 {
--- a/LanMountainDesktop/plugins/PluginRuntimeService.cs
+++ b/LanMountainDesktop/plugins/PluginRuntimeService.cs
@@ -773,11 +773,6 @@ public sealed class PluginRuntimeService : IDisposable
    private void ApplyPendingPluginDeletions()
    {
        var pendingPaths = ReadPendingPluginDeletions();
-        if (pendingPaths.Count == 0)
-        {
-            return;
-        }
-
        var remainingPaths = new List<string>();
        foreach (var path in pendingPaths)
        {
@@ -788,6 +783,41 @@ public sealed class PluginRuntimeService : IDisposable
        }

        SavePendingPluginDeletions(remainingPaths);
+        CleanupPendingDeletionDirectory();
+    }
+
+    private void CleanupPendingDeletionDirectory()
+    {
+        var pendingDeletionDir = Path.Combine(PluginsDirectory, ".pending-deletions");
+        if (!Directory.Exists(pendingDeletionDir))
+        {
+            return;
+        }
+
+        foreach (var pendingFile in Directory.EnumerateFiles(pendingDeletionDir, "*.pending"))
+        {
+            try
+            {
+                File.Delete(pendingFile);
+            }
+            catch
+            {
+                // Ignore cleanup failures for pending deletions.
+            }
+        }
+
+        try
+        {
+            if (Directory.GetFiles(pendingDeletionDir).Length == 0 &&
+                Directory.GetDirectories(pendingDeletionDir).Length == 0)
+            {
+                Directory.Delete(pendingDeletionDir);
+            }
+        }
+        catch
+        {
+            // Ignore directory cleanup failures.
+        }
    }

    private string ResolvePluginRemovalTargetPath(PluginCatalogEntry entry)