Refactor launcher startup, logging & host resolution

Improve launcher startup flow, logging, and host resolution. Key changes: add detailed startup logging and standardized preview messages; unify CLI vs GUI handling and error/result reporting (write result file when requested); refactor DeploymentLocator to a more robust host resolution (new HostResolutionResult, explicit/portable/published/debug resolution paths, legacy fallback); overhaul LauncherFlowCoordinator to better handle IPC stages, activation retries, window lifecycle, plugin/update flows and error reporting; add CommandContext helpers (IsGui/IsPreview/ExplicitAppRoot) and JSON context options; tighten async usage and ConfigureAwait calls; add better UI error handling and consistent exit codes. Several UX/debug conveniences and robustness fixes included.

LanMountainDesktop.Launcher/App.axaml.cs

@@ -13,10 +13,13 @@ public partial class App : Application
 {
     public override void Initialize()
     {
-        // 初始化日志记录器
         Logger.Initialize();
-        Logger.Info("Launcher starting...");
-        
+        var context = LauncherRuntimeContext.Current;
+        Logger.Info(
+            $"Launcher App initialize. Command='{context.Command}'; IsGuiMode={context.IsGuiCommand}; " +
+            $"IsPreview={context.IsPreviewCommand}; IsDebugMode={context.IsDebugMode}; " +
+            $"ExplicitAppRoot='{context.ExplicitAppRoot ?? "<none>"}'.");
+
         AvaloniaXamlLoader.Load(this);
     }
 
@@ -24,41 +27,29 @@ public partial class App : Application
     {
         if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
         {
+            desktop.ShutdownMode = ShutdownMode.OnExplicitShutdown;
+
             var context = LauncherRuntimeContext.Current;
+            Logger.Info(
+                $"Framework initialization completed. Command='{context.Command}'; IsPreview={context.IsPreviewCommand}; " +
+                $"IsDebugMode={context.IsDebugMode}.");
 
-            // 调试模式：显示开发调试窗口
-            if (context.IsDebugMode)
-            {
-                var devDebugWindow = new DevDebugWindow();
-                devDebugWindow.Show();
-                
-                // 调试模式下不自动启动正常流程，由开发者通过调试窗口控制
-                base.OnFrameworkInitializationCompleted();
-                return;
-            }
-
-            // 处理各界面的预览命令
             if (HandlePreviewCommand(context, desktop))
             {
                 base.OnFrameworkInitializationCompleted();
                 return;
             }
 
-            // apply-update 模式：显示 UpdateWindow，执行增量更新 + 插件升级
             if (string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
             {
-                // 先显示窗口，再启动后台任务
                 var updateWindow = new UpdateWindow();
                 updateWindow.Show();
                 _ = RunApplyUpdateWithWindowAsync(desktop, context, updateWindow);
             }
             else
             {
-                // 先显示 Splash 窗口，确保应用程序不会立即退出
                 var splashWindow = new SplashWindow();
                 splashWindow.Show();
-                
-                // 在 try-catch 块中实例化所有服务，确保任何异常都能被捕获
                 _ = RunCoordinatorWithSplashAsync(desktop, context, splashWindow);
             }
         }
@@ -66,156 +57,127 @@ public partial class App : Application
         base.OnFrameworkInitializationCompleted();
     }
 
-    /// <summary>
-    /// 处理界面预览命令
-    /// </summary>
     private bool HandlePreviewCommand(CommandContext context, IClassicDesktopStyleApplicationLifetime desktop)
     {
-        var command = context.Command.ToLowerInvariant();
-        
-        switch (command)
+        switch (context.Command.ToLowerInvariant())
         {
             case "preview-splash":
-                Console.WriteLine("[Launcher] Preview mode: SplashWindow");
+            {
+                Logger.Info("Preview command: splash.");
                 var splashWindow = new SplashWindow();
                 splashWindow.SetDebugMode(true);
                 splashWindow.Show();
                 _ = SimulateSplashPreviewAsync(desktop, splashWindow);
                 return true;
-                
+            }
             case "preview-error":
-                Console.WriteLine("[Launcher] Preview mode: ErrorWindow");
+            {
+                Logger.Info("Preview command: error.");
                 var errorWindow = new ErrorWindow();
-                errorWindow.SetErrorMessage("[预览模式] 这是一个错误页面预览。\n\n用于查看错误页面的样式和布局。");
+                errorWindow.SetErrorMessage("[Preview] This is the launcher error window preview.");
                 errorWindow.Show();
                 _ = WaitForWindowCloseAsync(desktop, errorWindow);
                 return true;
-                
+            }
             case "preview-update":
-                Console.WriteLine("[Launcher] Preview mode: UpdateWindow");
+            {
+                Logger.Info("Preview command: update.");
                 var updateWindow = new UpdateWindow();
                 updateWindow.SetDebugMode(true);
                 updateWindow.Show();
                 _ = SimulateUpdatePreviewAsync(desktop, updateWindow);
                 return true;
-                
+            }
             case "preview-oobe":
-                Console.WriteLine("[Launcher] Preview mode: OobeWindow");
+            {
+                Logger.Info("Preview command: oobe.");
                 var oobeWindow = new OobeWindow();
                 oobeWindow.Show();
                 _ = SimulateOobePreviewAsync(desktop, oobeWindow);
                 return true;
-                
+            }
             case "preview-debug":
-                Console.WriteLine("[Launcher] Preview mode: DevDebugWindow");
+            {
+                Logger.Info("Preview command: debug window.");
                 var devDebugWindow = new DevDebugWindow();
                 devDebugWindow.Show();
                 return true;
-                
+            }
             default:
                 return false;
         }
     }
 
-    /// <summary>
-    /// 模拟 Splash 窗口预览
-    /// </summary>
     private async Task SimulateSplashPreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, SplashWindow window)
     {
         var stages = new[] { "initializing", "update", "plugins", "launch", "ready" };
-        var messages = new[] { "初始化...", "检查更新...", "检查插件...", "正在启动...", "就绪" };
+        var messages = new[] { "Initializing...", "Checking updates...", "Checking plugins...", "Launching host...", "Ready" };
         var reporter = (ISplashStageReporter)window;
-        
-        for (int i = 0; i < stages.Length; i++)
+
+        for (var i = 0; i < stages.Length; i++)
         {
             reporter.Report(stages[i], messages[i]);
-            await Task.Delay(800);
+            await Task.Delay(800).ConfigureAwait(false);
         }
-        
-        // 等待5秒后自动关闭
-        await Task.Delay(5000);
+
+        await Task.Delay(5000).ConfigureAwait(false);
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
     }
 
-    /// <summary>
-    /// 模拟 Update 窗口预览
-    /// </summary>
     private async Task SimulateUpdatePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, UpdateWindow window)
     {
         var stages = new[] { "verify", "extract", "apply", "plugins", "cleanup" };
-        
-        for (int i = 0; i < stages.Length; i++)
+
+        for (var i = 0; i < stages.Length; i++)
         {
-            window.Report(stages[i], $"正在{GetStageName(stages[i])}...", (i + 1) * 20);
-            await Task.Delay(600);
+            window.Report(stages[i], $"Processing {stages[i]}...", (i + 1) * 20);
+            await Task.Delay(600).ConfigureAwait(false);
         }
-        
+
         window.ReportComplete(true, null);
-        
-        // 等待3秒后自动关闭
-        await Task.Delay(3000);
+        await Task.Delay(3000).ConfigureAwait(false);
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
-        
-        string GetStageName(string stage) => stage switch
-        {
-            "verify" => "验证",
-            "extract" => "解压",
-            "apply" => "应用",
-            "plugins" => "升级插件",
-            "cleanup" => "清理",
-            _ => stage
-        };
     }
 
-    /// <summary>
-    /// 模拟 OOBE 窗口预览
-    /// </summary>
     private async Task SimulateOobePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, OobeWindow window)
     {
         try
         {
-            // 等待用户点击开始按钮
-            await window.WaitForEnterAsync();
-            Console.WriteLine("[Launcher] OOBE preview completed by user");
+            await window.WaitForEnterAsync().ConfigureAwait(false);
+            Logger.Info("OOBE preview completed by user.");
         }
         catch (Exception ex)
         {
-            Console.Error.WriteLine($"[Launcher] OOBE preview error: {ex.Message}");
+            Logger.Error("OOBE preview failed.", ex);
         }
-        
-        // 用户点击后关闭应用程序
+
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
     }
 
-    /// <summary>
-    /// 等待窗口关闭
-    /// </summary>
     private async Task WaitForWindowCloseAsync(IClassicDesktopStyleApplicationLifetime desktop, Window window)
     {
-        var tcs = new TaskCompletionSource();
-        window.Closed += (s, e) => tcs.TrySetResult();
-        await tcs.Task;
+        var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+        window.Closed += (_, _) => tcs.TrySetResult();
+        await tcs.Task.ConfigureAwait(false);
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
     }
-    
+
     private static async Task RunCoordinatorWithSplashAsync(
         IClassicDesktopStyleApplicationLifetime desktop,
         CommandContext context,
         SplashWindow splashWindow)
     {
         LauncherResult result;
-        ErrorWindow? errorWindow = null;
-        LauncherFlowCoordinator? coordinator = null;
-        
+
         try
         {
-            // 在 try-catch 块中实例化所有服务，确保异常被捕获
             var appRoot = Commands.ResolveAppRoot(context);
+            Logger.Info(
+                $"Coordinator start. Command='{context.Command}'; AppRoot='{appRoot}'; " +
+                $"IsDebugMode={context.IsDebugMode}; ResultPath='{context.GetOption("result") ?? "<none>"}'.");
+
             var deploymentLocator = new DeploymentLocator(appRoot);
-            
-            // TODO: 从配置读取 GitHub 仓库信息
-            
-            coordinator = new LauncherFlowCoordinator(
+            var coordinator = new LauncherFlowCoordinator(
                 context,
                 deploymentLocator,
                 new OobeStateService(appRoot),
@@ -226,88 +188,85 @@ public partial class App : Application
         }
         catch (Exception ex)
         {
-            // 捕获异常并显示错误窗口
+            Logger.Error("Coordinator threw an unhandled exception.", ex);
             result = new LauncherResult
             {
                 Success = false,
                 Stage = "launch",
                 Code = "exception",
-                Message = $"启动器发生错误: {ex.Message}",
+                Message = $"Launcher failed: {ex.Message}",
                 ErrorMessage = ex.ToString()
             };
-            
-            Console.Error.WriteLine($"[Launcher] Exception caught: {ex}");
-            
-            // 在 UI 线程显示错误窗口 - 使用更健壮的方式
-            try
-            {
-                await Dispatcher.UIThread.InvokeAsync(() =>
-                {
-                    try
-                    {
-                        // 安全关闭 Splash 窗口
-                        if (splashWindow.IsVisible && splashWindow.IsLoaded)
-                        {
-                            splashWindow.Close();
-                        }
-                    }
-                    catch (Exception closeEx)
-                    {
-                        Console.Error.WriteLine($"[Launcher] Error closing splash window: {closeEx.Message}");
-                    }
-                    
-                    // 创建并显示错误窗口
-                    try
-                    {
-                        errorWindow = new ErrorWindow();
-                        errorWindow.SetErrorMessage($"启动器发生错误:\n{ex.Message}\n\n请检查应用安装是否完整，或尝试重新安装。");
-                        errorWindow.Show();
-                        Console.WriteLine("[Launcher] ErrorWindow shown successfully");
-                    }
-                    catch (Exception windowEx)
-                    {
-                        Console.Error.WriteLine($"[Launcher] Failed to show ErrorWindow: {windowEx.Message}");
-                    }
-                });
-                
-                // 如果错误窗口成功显示，等待它关闭
-                if (errorWindow != null)
-                {
-                    try
-                    {
-                        // 等待用户选择或窗口关闭
-                        var errorResult = await errorWindow.WaitForChoiceAsync();
-                        Console.WriteLine($"[Launcher] ErrorWindow result: {errorResult}");
-                    }
-                    catch (Exception waitEx)
-                    {
-                        Console.Error.WriteLine($"[Launcher] Error waiting for ErrorWindow: {waitEx.Message}");
-                        // 如果等待失败，至少给用户5秒时间看到错误信息
-                        await Task.Delay(5000);
-                    }
-                }
-                else
-                {
-                    // 错误窗口未能显示，等待5秒让用户看到控制台输出
-                    await Task.Delay(5000);
-                }
-            }
-            catch (Exception uiEx)
-            {
-                // 最后的兜底：记录到控制台
-                Console.Error.WriteLine($"[Launcher] Critical error in UI thread: {uiEx.Message}");
-                await Task.Delay(3000);
-            }
         }
-        
-        await Commands.WriteResultIfNeededAsync(LauncherRuntimeContext.Current.GetOption("result"), result).ConfigureAwait(false);
+
+        Logger.Info($"Coordinator completed. Success={result.Success}; Stage='{result.Stage}'; Code='{result.Code}'.");
+        await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
+
+        if (!result.Success &&
+            result.Code is not "host_not_found" &&
+            (string.Equals(result.Stage, "launch", StringComparison.OrdinalIgnoreCase) ||
+             string.Equals(result.Stage, "launchHost", StringComparison.OrdinalIgnoreCase)))
+        {
+            await ShowFailureWindowAsync(result).ConfigureAwait(false);
+        }
+
         Environment.ExitCode = result.Success ? 0 : 1;
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
     }
 
-    /// <summary>
-    /// apply-update 模式：执行增量更新和插件升级，完成后自动退出
-    /// </summary>
+    private static async Task WriteLauncherResultAsync(CommandContext context, LauncherResult result)
+    {
+        var resultPath = context.GetOption("result");
+        if (string.IsNullOrWhiteSpace(resultPath))
+        {
+            return;
+        }
+
+        try
+        {
+            await Commands.WriteResultIfNeededAsync(resultPath, result).ConfigureAwait(false);
+            Logger.Info($"Launcher result written to '{Path.GetFullPath(resultPath)}'.");
+        }
+        catch (Exception ex)
+        {
+            Logger.Error($"Failed to write launcher result to '{resultPath}'.", ex);
+        }
+    }
+
+    private static async Task ShowFailureWindowAsync(LauncherResult result)
+    {
+        ErrorWindow? errorWindow = null;
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                errorWindow = new ErrorWindow();
+                errorWindow.SetErrorMessage(
+                    $"Failed to start LanMountainDesktop.\n\nStage: {result.Stage}\nCode: {result.Code}\n\n{result.Message}");
+                errorWindow.Show();
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to show launcher failure window.", ex);
+            }
+        });
+
+        if (errorWindow is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await errorWindow.WaitForChoiceAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failure window closed unexpectedly.", ex);
+        }
+    }
+
     private static async Task RunApplyUpdateWithWindowAsync(
         IClassicDesktopStyleApplicationLifetime desktop,
         CommandContext context,
@@ -324,8 +283,7 @@ public partial class App : Application
 
         try
         {
-            // 1. 应用增量更新
-            await Dispatcher.UIThread.InvokeAsync(() => window.Report("verify", "正在验证更新...", 10));
+            await Dispatcher.UIThread.InvokeAsync(() => window.Report("verify", "Verifying update...", 10));
             var updateResult = await updateEngine.ApplyPendingUpdateAsync().ConfigureAwait(false);
             if (!updateResult.Success)
             {
@@ -333,24 +291,20 @@ public partial class App : Application
                 errorMessage = updateResult.Message;
             }
 
-            // 2. 应用待处理的插件升级
             if (success)
             {
-                await Dispatcher.UIThread.InvokeAsync(() => window.Report("plugins", "正在升级插件...", 60));
-                var pluginsDir = context.GetOption("plugins-dir")
-                                 ?? Path.Combine(appRoot, "plugins");
+                await Dispatcher.UIThread.InvokeAsync(() => window.Report("plugins", "Applying plugin upgrades...", 60));
+                var pluginsDir = context.GetOption("plugins-dir") ?? Path.Combine(appRoot, "plugins");
                 var queueResult = pluginUpgrades.ApplyPendingUpgrades(pluginsDir);
                 if (!queueResult.Success && queueResult.Code != "noop")
                 {
-                    // 插件升级失败不阻断整体流程，仅记录到控制台
-                    Console.Error.WriteLine($"Plugin upgrade had failures: {queueResult.Message}");
+                    Logger.Error($"Plugin upgrade failed during apply-update: {queueResult.Message}");
                 }
             }
 
-            // 3. 清理旧版本，保留至少3个版本以支持回滚
             if (success)
             {
-                await Dispatcher.UIThread.InvokeAsync(() => window.Report("cleanup", "正在清理...", 90));
+                await Dispatcher.UIThread.InvokeAsync(() => window.Report("cleanup", "Cleaning up old deployments...", 90));
                 deploymentLocator.CleanupOldDeployments(minVersionsToKeep: 3);
             }
         }
@@ -358,21 +312,11 @@ public partial class App : Application
         {
             success = false;
             errorMessage = ex.Message;
+            Logger.Error("Apply-update flow failed.", ex);
         }
 
-        // 显示完成状态，短暂停留后关闭
         await Dispatcher.UIThread.InvokeAsync(() => window.ReportComplete(success, errorMessage));
-
-        if (success)
-        {
-            // 成功：停留 1.5 秒让用户看到"更新完成"
-            await Task.Delay(1500);
-        }
-        else
-        {
-            // 失败：停留 5 秒让用户看到错误信息
-            await Task.Delay(5000);
-        }
+        await Task.Delay(success ? 1500 : 5000).ConfigureAwait(false);
 
         await Commands.WriteResultIfNeededAsync(context.GetOption("result"), new LauncherResult
         {
@@ -385,6 +329,4 @@ public partial class App : Application
         Environment.ExitCode = success ? 0 : 1;
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
     }
-
-
 }

LanMountainDesktop.Launcher/AppJsonContext.cs

@@ -6,7 +6,10 @@ using LanMountainDesktop.Shared.Contracts.Launcher;
 
 namespace LanMountainDesktop.Launcher;
 
-[JsonSourceGenerationOptions(WriteIndented = true, PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
+[JsonSourceGenerationOptions(
+    WriteIndented = true,
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
+    PropertyNameCaseInsensitive = true)]
 [JsonSerializable(typeof(SignedFileMap))]
 [JsonSerializable(typeof(UpdateFileEntry))]
 [JsonSerializable(typeof(PlondsUpdateMetadata))]

LanMountainDesktop.Launcher/CommandContext.cs

@@ -4,6 +4,17 @@ namespace LanMountainDesktop.Launcher;
 
 internal sealed class CommandContext
 {
+    private static readonly string[] GuiCommands =
+    [
+        "launch",
+        "apply-update",
+        "preview-splash",
+        "preview-error",
+        "preview-update",
+        "preview-oobe",
+        "preview-debug"
+    ];
+
     public string Command { get; }
 
     public string SubCommand { get; }
@@ -28,6 +39,14 @@ internal sealed class CommandContext
         Options.ContainsKey("debug") ||
         System.Diagnostics.Debugger.IsAttached;
 
+    public bool IsPreviewCommand =>
+        Command.StartsWith("preview-", StringComparison.OrdinalIgnoreCase);
+
+    public bool IsGuiCommand =>
+        GuiCommands.Contains(Command, StringComparer.OrdinalIgnoreCase);
+
+    public string? ExplicitAppRoot => GetOption("app-root");
+
     private CommandContext(string command, string subCommand, Dictionary<string, string> options, string[] rawArgs)
     {
         Command = command;

LanMountainDesktop.Launcher/Program.cs

@@ -10,32 +10,54 @@ internal static class Program
     private static async Task<int> Main(string[] args)
     {
         var commandContext = CommandContext.FromArgs(args);
+        Logger.Initialize();
+        Logger.Info(
+            $"Program entry. Command='{commandContext.Command}'; SubCommand='{commandContext.SubCommand}'; " +
+            $"IsGuiMode={commandContext.IsGuiCommand}; IsDebugMode={commandContext.IsDebugMode}; " +
+            $"HasResultPath={!string.IsNullOrWhiteSpace(commandContext.GetOption("result"))}; " +
+            $"ExplicitAppRoot='{commandContext.ExplicitAppRoot ?? "<none>"}'.");
 
-        // 处理遗留插件安装命令
-        if (commandContext.IsLegacyPluginInstall)
+        try
         {
-            var installer = new PluginInstallerService();
-            return await Commands.RunLegacyPluginInstallAsync(commandContext, installer).ConfigureAwait(false);
-        }
+            if (commandContext.IsLegacyPluginInstall)
+            {
+                var installer = new PluginInstallerService();
+                return await Commands.RunLegacyPluginInstallAsync(commandContext, installer).ConfigureAwait(false);
+            }
+
+            if (!commandContext.IsGuiCommand)
+            {
+                return await Commands.RunCliCommandAsync(commandContext).ConfigureAwait(false);
+            }
 
-        // apply-update 命令：启动 Avalonia GUI 显示更新进度窗口
-        if (string.Equals(commandContext.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
-        {
             LauncherRuntimeContext.Current = commandContext;
             BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
             return Environment.ExitCode;
         }
-
-        // 处理其他 CLI 命令 (update, plugin, rollback 等)
-        if (!string.Equals(commandContext.Command, "launch", StringComparison.OrdinalIgnoreCase))
+        catch (Exception ex)
         {
-            return await Commands.RunCliCommandAsync(commandContext).ConfigureAwait(false);
-        }
+            Logger.Error("Launcher failed before GUI flow completed.", ex);
 
-        // 主启动流程: OOBE -> Splash -> 版本选择 -> 启动主程序
-        LauncherRuntimeContext.Current = commandContext;
-        BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
-        return Environment.ExitCode;
+            var result = new LauncherResult
+            {
+                Success = false,
+                Stage = "launcher",
+                Code = "launcher_bootstrap_failed",
+                Message = ex.Message,
+                ErrorMessage = ex.ToString(),
+                Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+                {
+                    ["command"] = commandContext.Command,
+                    ["subCommand"] = commandContext.SubCommand,
+                    ["isGuiMode"] = commandContext.IsGuiCommand.ToString(),
+                    ["isDebugMode"] = commandContext.IsDebugMode.ToString(),
+                    ["explicitAppRoot"] = commandContext.ExplicitAppRoot ?? string.Empty
+                }
+            };
+
+            await Commands.WriteResultIfNeededAsync(commandContext.GetOption("result"), result).ConfigureAwait(false);
+            return 1;
+        }
     }
 
     private static AppBuilder BuildAvaloniaApp()

LanMountainDesktop.Launcher/Services/DeploymentLocator.cs

@@ -33,7 +33,6 @@ internal sealed class DeploymentLocator
             var candidates = Directory.GetDirectories(_appRoot, "app-*", SearchOption.TopDirectoryOnly);
             Console.WriteLine($"[DeploymentLocator] Found {candidates.Length} app-* directories");
 
-            // ClassIsland 风格的查询：先筛选，后排序
             var validInstallations = candidates
                 .Where(path =>
                 {
@@ -79,38 +78,199 @@ internal sealed class DeploymentLocator
         }
     }
 
-    public string? ResolveHostExecutablePath()
+    public HostResolutionResult ResolveHostExecutable(CommandContext context)
     {
-        // 使用新的灵活定位器
-        var options = new HostDiscoveryOptions
-        {
-            ExecutableName = "LanMountainDesktop",
-            PreferDevModeConfig = true,
-            RecursiveSearch = false, // 默认不启用递归搜索以提高性能
-            AdditionalSearchPaths = new List<string>
-            {
-                // 可以通过配置文件或环境变量添加更多路径
-                "${AppRoot}",
-                "${AppRoot}/..",
-                "${BaseDirectory}/../..",
-            }
-        };
+        ArgumentNullException.ThrowIfNull(context);
 
-        var locator = new FlexibleHostLocator(_appRoot, options);
-        var result = locator.ResolveHostExecutablePath();
-        
-        if (result != null)
+        var executable = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
+        var searchedPaths = new List<string>();
+        var explicitAppRoot = context.ExplicitAppRoot;
+        var devModeConfigIgnored = !context.IsDebugMode && Views.ErrorWindow.CheckDevModeEnabled();
+
+        string? resolvedPath;
+        string? source;
+
+        if (!string.IsNullOrWhiteSpace(explicitAppRoot))
         {
-            return result;
+            var explicitRoot = Path.GetFullPath(explicitAppRoot);
+            resolvedPath = TryResolveExplicitAppRoot(explicitRoot, executable, searchedPaths, out source);
+        }
+        else
+        {
+            resolvedPath = TryResolvePublishedOrPortableHost(executable, searchedPaths, out source);
         }
 
-        // 回退到旧逻辑（作为备选）
+        if (resolvedPath is null && context.IsDebugMode)
+        {
+            resolvedPath = TryResolveDebugHost(executable, searchedPaths, out source);
+        }
+
+        if (resolvedPath is null)
+        {
+            resolvedPath = ResolveHostExecutablePathLegacy();
+            if (!string.IsNullOrWhiteSpace(resolvedPath))
+            {
+                searchedPaths.Add(Path.GetFullPath(resolvedPath));
+                source = "legacy_fallback";
+            }
+        }
+
+        return new HostResolutionResult
+        {
+            Success = !string.IsNullOrWhiteSpace(resolvedPath),
+            ResolvedHostPath = resolvedPath,
+            ResolutionSource = source,
+            AppRoot = _appRoot,
+            ExplicitAppRoot = explicitAppRoot,
+            DevModeConfigIgnored = devModeConfigIgnored,
+            SearchedPaths = searchedPaths
+                .Where(path => !string.IsNullOrWhiteSpace(path))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList()
+        };
+    }
+
+    public string? ResolveHostExecutablePath()
+    {
         return ResolveHostExecutablePathLegacy();
     }
 
-    /// <summary>
-    /// 传统的主程序路径解析（作为备选）
-    /// </summary>
+    private string? TryResolveExplicitAppRoot(
+        string explicitRoot,
+        string executable,
+        List<string> searchedPaths,
+        out string? source)
+    {
+        var directPath = Path.Combine(explicitRoot, executable);
+        searchedPaths.Add(directPath);
+        if (File.Exists(directPath))
+        {
+            source = "explicit_app_root_direct";
+            return directPath;
+        }
+
+        var deployment = FindBestDeploymentHost(explicitRoot, executable, searchedPaths);
+        if (deployment is not null)
+        {
+            source = "explicit_app_root_deployment";
+            return deployment;
+        }
+
+        source = null;
+        return null;
+    }
+
+    private string? TryResolvePublishedOrPortableHost(
+        string executable,
+        List<string> searchedPaths,
+        out string? source)
+    {
+        var deployment = FindBestDeploymentHost(_appRoot, executable, searchedPaths);
+        if (deployment is not null)
+        {
+            source = "published_deployment";
+            return deployment;
+        }
+
+        var portableCandidates = new[]
+        {
+            Path.Combine(_appRoot, executable),
+            Path.Combine(AppContext.BaseDirectory, executable)
+        };
+
+        foreach (var candidate in portableCandidates
+                     .Select(Path.GetFullPath)
+                     .Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            searchedPaths.Add(candidate);
+            if (File.Exists(candidate))
+            {
+                source = "portable_host";
+                return candidate;
+            }
+        }
+
+        source = null;
+        return null;
+    }
+
+    private string? TryResolveDebugHost(
+        string executable,
+        List<string> searchedPaths,
+        out string? source)
+    {
+        if (Views.ErrorWindow.CheckDevModeEnabled())
+        {
+            var savedCustomPath = Views.ErrorWindow.GetSavedCustomHostPath();
+            if (!string.IsNullOrWhiteSpace(savedCustomPath))
+            {
+                var fullSavedPath = Path.GetFullPath(savedCustomPath);
+                searchedPaths.Add(fullSavedPath);
+                if (File.Exists(fullSavedPath))
+                {
+                    source = "debug_saved_custom_path";
+                    return fullSavedPath;
+                }
+            }
+        }
+
+        foreach (var devPath in GetDevelopmentPaths(executable))
+        {
+            var fullPath = Path.GetFullPath(devPath);
+            searchedPaths.Add(fullPath);
+            if (File.Exists(fullPath))
+            {
+                source = "debug_build_output";
+                return fullPath;
+            }
+        }
+
+        source = null;
+        return null;
+    }
+
+    private static string? FindBestDeploymentHost(
+        string root,
+        string executable,
+        List<string> searchedPaths)
+    {
+        if (!Directory.Exists(root))
+        {
+            searchedPaths.Add(Path.Combine(root, "app-*", executable));
+            return null;
+        }
+
+        var appDirs = Directory.GetDirectories(root, "app-*", SearchOption.TopDirectoryOnly)
+            .Where(path => !File.Exists(Path.Combine(path, ".destroy")))
+            .Where(path => !File.Exists(Path.Combine(path, ".partial")))
+            .Select(path => new
+            {
+                Path = path,
+                HostPath = Path.Combine(path, executable),
+                HasCurrent = File.Exists(Path.Combine(path, ".current")),
+                Version = ParseVersionFromDirectory(path)
+            })
+            .OrderByDescending(item => item.HasCurrent)
+            .ThenByDescending(item => item.Version)
+            .ToList();
+
+        foreach (var candidate in appDirs)
+        {
+            searchedPaths.Add(candidate.HostPath);
+            if (File.Exists(candidate.HostPath))
+            {
+                return candidate.HostPath;
+            }
+        }
+
+        if (appDirs.Count == 0)
+        {
+            searchedPaths.Add(Path.Combine(root, "app-*", executable));
+        }
+
+        return null;
+    }
+
     private string? ResolveHostExecutablePathLegacy()
     {
         var executable = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
@@ -126,14 +286,12 @@ internal sealed class DeploymentLocator
             }
         }
 
-        // 2. 查找 Launcher 所在目录（开发环境 - 直接运行）
         var inRoot = Path.Combine(_appRoot, executable);
         if (File.Exists(inRoot))
         {
             return inRoot;
         }
 
-        // 3. 查找父目录（开发环境 - 从 Launcher 项目运行）
         var parent = Path.GetFullPath(Path.Combine(_appRoot, ".."));
         var inParent = Path.Combine(parent, executable);
         if (File.Exists(inParent))
@@ -144,14 +302,12 @@ internal sealed class DeploymentLocator
         // 4. å¼€å<E282AC>‘模å¼<C3A5>：如果å<C593>¯ç”¨äº†å¼€å<E282AC>‘模å¼<C3A5>，优先使用ä¿<C3A4>存的自定义路径
         if (Views.ErrorWindow.CheckDevModeEnabled())
         {
-            // 4.1 首先检查保存的自定义路径
             var savedCustomPath = Views.ErrorWindow.GetSavedCustomHostPath();
             if (!string.IsNullOrWhiteSpace(savedCustomPath) && File.Exists(savedCustomPath))
             {
                 return savedCustomPath;
             }
 
-            // 4.2 扫描开发路径
             var devPath = ScanDevelopmentPaths(executable);
             if (!string.IsNullOrWhiteSpace(devPath))
             {
@@ -179,7 +335,7 @@ internal sealed class DeploymentLocator
     {
         var possiblePaths = new[]
         {
-            // 从 Launcher 项目运行
+            // ä»?Launcher 项目è¿<EFBFBD>è¡Œ
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
@@ -203,17 +359,14 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 获取开发环境可能的主程序路径
-    /// </summary>
+    /// 获å<EFBFBD>–å¼€å<EFBFBD>‘环境å<EFBFBD>¯èƒ½çš„主程åº<EFBFBD>è·¯å¾?    /// </summary>
     private static IEnumerable<string> GetDevelopmentPaths(string executable)
     {
-        // 获取 Launcher 所在目录
         var launcherDir = AppContext.BaseDirectory;
         
-        // 可能的开发目录结构
         var possiblePaths = new[]
         {
-            // 从 Launcher 项目运行：..\LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
+            // ä»?Launcher 项目è¿<EFBFBD>è¡Œï¼?.\LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
@@ -221,7 +374,7 @@ internal sealed class DeploymentLocator
             Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // 从 dev-test 目录运行
+            // ä»?dev-test 目录è¿<EFBFBD>è¡Œ
             Path.Combine(launcherDir, "..", "dev-test", "app-1.0.0-dev", executable),
         };
 
@@ -256,9 +409,8 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 清理旧版本部署，保留最近的N个版本
-    /// </summary>
-    /// <param name="minVersionsToKeep">最少保留版本数，默认3个</param>
+    /// 清ç<EFBFBD>†æ—§ç‰ˆæœ¬éƒ¨ç½²ï¼Œä¿<EFBFBD>留最近的N个版æœ?    /// </summary>
+    /// <param name="minVersionsToKeep">最少ä¿<C3A4>留版本数，默è®?ä¸?/param>
     public void CleanupOldDeployments(int minVersionsToKeep = 3)
     {
         try
@@ -272,7 +424,6 @@ internal sealed class DeploymentLocator
 
             var candidates = Directory.GetDirectories(_appRoot, "app-*", SearchOption.TopDirectoryOnly);
 
-            // 过滤掉无效部署目录（排除partial），按版本排序
             var validDeployments = candidates
                 .Where(path => !File.Exists(Path.Combine(path, ".partial")))
                 .Select(path => new
@@ -349,7 +500,6 @@ internal sealed class DeploymentLocator
             {
                 if (versionsToKeep.Contains(deployment.Path))
                 {
-                    // 保留此版本，如果之前标记了destroy则取消标记
                     if (deployment.IsDestroyed)
                     {
                         try
@@ -365,7 +515,6 @@ internal sealed class DeploymentLocator
                     continue;
                 }
 
-                // 如果还没标记destroy的，先标记
                 if (!deployment.IsDestroyed)
                 {
                     try
@@ -387,7 +536,7 @@ internal sealed class DeploymentLocator
                 }
                 catch
                 {
-                    // 忽略删除失败(可能文件被占用),下次启动再试
+                    // 忽略删除失败(å<>¯èƒ½æ–‡ä»¶è¢«å<C2AB> ç”?,下次å<C2A1>¯åŠ¨å†<C3A5>试
                     Console.WriteLine($"[DeploymentLocator] Failed to delete (will retry later): {deployment.Path}");
                 }
             }
@@ -400,7 +549,7 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 仅清理已标记为.destroy的部署（兼容旧方法）
+    /// 仅清ç<EFBFBD>†å·²æ ‡è®°ä¸?destroy的部署（兼容旧方法）
     /// </summary>
     [Obsolete("Use CleanupOldDeployments instead")]
     public void CleanupDestroyedDeployments()
@@ -432,8 +581,7 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 从部署目录读取版本信息
-    /// </summary>
+    /// 从部署目录读å<EFBFBD>–版本信æ<EFBFBD>?    /// </summary>
     public AppVersionInfo GetVersionInfo()
     {
         var deploymentDir = FindCurrentDeploymentDirectory();
@@ -453,16 +601,16 @@ internal sealed class DeploymentLocator
                 }
                 catch
                 {
-                    // 忽略读取失败，回退到默认值
                 }
             }
         }
 
-        // 回退：从目录名解析版本，使用默认开发代号
         return new AppVersionInfo
         {
             Version = GetCurrentVersion(),
-            Codename = "Administrate" // 默认开发代号
+            Codename = "Administrate"
         };
-    }
+}
+
+
 }

LanMountainDesktop.Launcher/Services/HostResolutionResult.cs

@@ -0,0 +1,18 @@
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class HostResolutionResult
+{
+    public bool Success { get; init; }
+
+    public string? ResolvedHostPath { get; init; }
+
+    public string? ResolutionSource { get; init; }
+
+    public string AppRoot { get; init; } = string.Empty;
+
+    public string? ExplicitAppRoot { get; init; }
+
+    public bool DevModeConfigIgnored { get; init; }
+
+    public List<string> SearchedPaths { get; init; } = [];
+}

LanMountainDesktop.Launcher/Services/WelcomeOobeStep.cs

@@ -0,0 +1,42 @@
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class WelcomeOobeStep : IOobeStep
+{
+    private readonly OobeStateService _oobeStateService;
+
+    public WelcomeOobeStep(OobeStateService oobeStateService)
+    {
+        _oobeStateService = oobeStateService;
+    }
+
+    public async Task RunAsync(CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        OobeWindow? window = null;
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            window = new OobeWindow();
+            window.Show();
+        });
+
+        if (window is null)
+        {
+            return;
+        }
+
+        await window.WaitForEnterAsync().ConfigureAwait(false);
+        _oobeStateService.MarkCompleted();
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            if (window.IsVisible)
+            {
+                window.Close();
+            }
+        });
+    }
+}

LanMountainDesktop.Launcher/Views/LoadingDetailsWindow.axaml.cs

@@ -23,14 +23,12 @@ public partial class LoadingDetailsWindow : Window
     {
         AvaloniaXamlLoader.Load(this);
 
-        // 初始化列表
         var itemsList = this.FindControl<ItemsControl>("LoadingItemsList");
         if (itemsList != null)
         {
             itemsList.ItemsSource = _items;
         }
 
-        // 创建更新定时器
         _updateTimer = new DispatcherTimer
         {
             Interval = TimeSpan.FromMilliseconds(100)
@@ -59,8 +57,7 @@ public partial class LoadingDetailsWindow : Window
     }
 
     /// <summary>
-    /// 更新加载状态
-    /// </summary>
+    /// 鏇存柊鍔犺浇鐘舵€?    /// </summary>
     public void UpdateLoadingState(LoadingStateMessage state)
     {
         Dispatcher.UIThread.Post(() =>
@@ -73,7 +70,6 @@ public partial class LoadingDetailsWindow : Window
                 // 鏇存柊鏁翠綋杩涘害
                 UpdateOverallProgress(state);
 
-                // 更新当前活动项
                 UpdateCurrentItem(state);
 
                 // 鏇存柊鍒楄〃
@@ -124,8 +120,7 @@ public partial class LoadingDetailsWindow : Window
     }
 
     /// <summary>
-    /// 更新当前活动项
-    /// </summary>
+    /// 鏇存柊褰撳墠娲诲姩椤?    /// </summary>
     private void UpdateCurrentItem(LoadingStateMessage state)
     {
         var currentItem = state.ActiveItems.FirstOrDefault();
@@ -162,7 +157,6 @@ public partial class LoadingDetailsWindow : Window
     /// </summary>
     private void UpdateItemsList(LoadingStateMessage state)
     {
-        // 同步列表项
         foreach (var item in state.ActiveItems)
         {
             var existing = _items.FirstOrDefault(i => i.Id == item.Id);
@@ -187,7 +181,7 @@ public partial class LoadingDetailsWindow : Window
             }
         }
 
-        // 按状态排序：进行中 -> 等待中 -> 已完成 -> 失败
+        // 鎸夌姸鎬佹帓搴忥細杩涜<EFBFBD>涓?-> 绛夊緟涓?-> 宸插畬鎴?-> 澶辫触
         var sortedItems = _items.OrderBy(i => GetStatePriority(i.State)).ToList();
         _items.Clear();
         foreach (var item in sortedItems)
@@ -240,17 +234,20 @@ public partial class LoadingDetailsWindow : Window
     /// </summary>
     private static string GetStageDescription(StartupStage stage) => stage switch
     {
-        StartupStage.Initializing => "正在初始化系统...",
-        StartupStage.LoadingSettings => "正在加载设置...",
-        StartupStage.LoadingPlugins => "正在加载插件...",
-        StartupStage.InitializingUI => "正在初始化界面...",
-        StartupStage.Ready => "加载完成",
-        _ => "正在加载..."
+        StartupStage.Initializing => "正在初始化系统...",
+        StartupStage.LoadingSettings => "正在加载设置...",
+        StartupStage.LoadingPlugins => "正在加载插件...",
+        StartupStage.InitializingUI => "正在初始化界面...",
+        StartupStage.ShellInitialized => "桌面外壳已初始化",
+        StartupStage.DesktopVisible => "桌面已经可见",
+        StartupStage.ActivationRedirected => "已激活现有实例",
+        StartupStage.ActivationFailed => "现有实例激活失败",
+        StartupStage.Ready => "加载完成",
+        _ => "正在加载..."
     };
 
     /// <summary>
-    /// 获取项描述
-    /// </summary>
+    /// 鑾峰彇椤规弿杩?    /// </summary>
     private static string GetItemDescription(LoadingItem item)
     {
         if (!string.IsNullOrEmpty(item.Description))
@@ -268,8 +265,7 @@ public partial class LoadingDetailsWindow : Window
     }
 
     /// <summary>
-    /// 获取项图标
-    /// </summary>
+    /// 鑾峰彇椤瑰浘鏍?    /// </summary>
     private static string GetItemIcon(LoadingItemType type) => type switch
     {
         LoadingItemType.Plugin => "\uE768",
@@ -298,8 +294,7 @@ public partial class LoadingDetailsWindow : Window
 }
 
 /// <summary>
-/// 加载项视图模型
-/// </summary>
+/// 鍔犺浇椤硅<EFBFBD>鍥炬ā鍨?/// </summary>
 public class LoadingItemViewModel : INotifyPropertyChanged
 {
     public string Id { get; }
@@ -394,3 +389,4 @@ public class LoadingItemViewModel : INotifyPropertyChanged
         _ => new SolidColorBrush(Color.Parse("#616161"))
     };
 }
+