Avalonia12 (#7)

* ava12升级

* Enable centralized package versioning

Add <Project> and <PropertyGroup> with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to Directory.Packages.props to enable centralized package version management across the repository. This allows package versions to be controlled from this single file instead of individual project files.

* Migrate codebase to Avalonia 12 APIs

Apply Avalonia 12 migration changes: replace SystemDecorations with WindowDecorations and remove ExtendClientAreaChromeHints/ExtendClientAreaTitleBarHeightHint usages; update BindingPlugins removal logic (no-op); switch clipboard usage to ClipboardExtensions.SetTextAsync; update Bitmap.CopyPixels calls to the new signature. Replace TextBox.Watermark with PlaceholderText, convert NumberBox styles to FANumberBox and adjust templates, change Checked/Unchecked handlers to IsCheckedChanged, and adapt FluentIcons usages (SymbolIconSource -> FASymbol/FAFont/FluentIcon equivalents). Fix MainWindow partial classes to inherit Window and correct missing variables/fields/usings. Add migration docs/specs/tasks under .trae and include a small TestFluentIcons project for icon testing.

* Migrate to Avalonia 12 and Plugin SDK v5

Upgrade project to the Avalonia 12 baseline and Plugin SDK v5: centralize Avalonia packages, remove legacy WebView.Avalonia usage (use NativeWebView/WebView2 EnvironmentRequested), and update Fluent/Material icon/package usages. Bump multiple package/project versions to 5.0.0 and Avalonia 12.0.1, update plugin template and README/docs to SDK v5, and add PLUGIN_SDK_V5_MIGRATION.md.

Also fix runtime/behavior bugs: make DataLocationResolver use a fixed bootstrap launcher data path and avoid recursive ResolveDataRoot; add legacy-state handling and extraction in OobeStateService; and update component settings tests to reflect migrated storage (DB/backup) and reset cache for test reloads. Various csproj, tests, and docs updated to reflect the migration and ensure build/test compatibility.

* Update icon glyphs and symbol mappings

Replace and refine icon sources across settings pages and controls: many FAFontIconSource glyphs were updated to specific Seagull Fluent Icons codepoints, some FASymbolIconSource usages were replaced with FAFontIconSource, and a number of symbol-to-Symbol enum mappings were adjusted (e.g. "Bell" -> AlertOn, "Shield" -> ShieldLock). Also clarified a comment in SettingsWindow and fixed a trailing newline in StudySettingsPage. Changes standardize icon visuals and bridge FluentIcons glyphs into FluentAvalonia icon sources.

* fix.修复合并产生的问题。

.github/VERSION_SYNC_INFO.md

@@ -1,127 +1,65 @@
-# 版本号自动同步说明
+# 版本同步说明
 
-## 📋 概述
+## 目标
 
-从本次更新开始，Release 工作流已配置为**自动同步版本号**，确保应用的每个版本号来源都保持一致。
+发布版的用户可见版本必须统一指向“应用版本”，不能再出现：
 
-## 🔄 版本号流转链路
+- Launcher UI 显示 `1.0.0`
+- 应用设置页显示 `0.8.x`
+- `version.json`、安装包、Release 资产名称各写各的
 
-```
-Git Tag (v1.0.1)
-    ↓
-[Release 工作流 prepare 任务]
-    ↓
-提取版本号: 1.0.1
-    ↓
-[Update version in .csproj] ✨ 新增步骤
-    ↓
-自动更新 .csproj 文件版本号
-    ↓
-dotnet restore/build
-    ↓
-构建时读取更新后的版本号
-    ↓
-应用内显示版本号 (MainWindow.Localization.cs 动态读取)
-```
+## 默认仓库状态
 
-## 🎯 工作原理
+仓库内的静态版本现在故意保留为开发占位值：
 
-### 1. 版本号提取
-当推送 Git Tag 时（如 `git tag v1.0.1`），Release 工作流的 `prepare` 任务自动提取版本号：
-- TAG: `v1.0.1` → VERSION: `1.0.1`
+- `Directory.Build.props`
+- `LanMountainDesktop/LanMountainDesktop.csproj`
+- `LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj`
+- `LanMountainDesktop.Shared.Contracts/LanMountainDesktop.Shared.Contracts.csproj`
+- `LanMountainDesktop/app.manifest`
+- `LanMountainDesktop.Launcher/app.manifest`
 
-### 2. 自动更新 .csproj
-在三个平台的构建任务中，新增了 **"Update version in .csproj"** 步骤：
+这些值只是提醒“当前不是正式注入构建”，不能代表发布版本。
 
-**Windows (PowerShell)**:
-```powershell
-$VERSION = "1.0.1"
-(Get-Content file.csproj) -replace '<Version>.*?</Version>', "<Version>$VERSION</Version>" | Set-Content file.csproj
-```
+## Release 工作流怎么做
 
-**Linux/macOS (Bash)**:
-```bash
-VERSION="1.0.1"
-sed -i "s/<Version>.*<\/Version>/<Version>$VERSION<\/Version>/" file.csproj
-```
+Release 工作流会先从 tag 提取版本：
 
-### 3. 构建和发布
-更新后的版本号被用于：
-- 程序集版本 (`AssemblyVersion`)
-- 包文件名 (`LanMountainDesktop-1.0.1-win-x64.zip`)
-- 应用内显示 (About 页面)
-- GitHub Release 标题
+- `v0.8.5.2` -> `0.8.5.2`
+- 程序集四段版本 -> `0.8.5.2`
 
-## 📍 涉及的文件
+随后显式执行：
 
-自动更新的文件：
-1. `LanMountainDesktop/LanMountainDesktop.csproj`
+- `scripts/Set-ReleaseVersion.ps1`
 
-## ✅ 使用流程
+这个步骤会同步更新：
 
-### 发布新版本
+- 主程序 `.csproj` 的 `Version`
+- Launcher `.csproj` 的 `Version`
+- Shared.Contracts `.csproj` 的 `Version`
+- `Directory.Build.props`
+- 主程序 `app.manifest`
+- Launcher `app.manifest`
 
-```bash
-# 1. 更新代码（可选：代码中的版本号现在会自动更新）
-git add .
-git commit -m "feat: Add new features"
+之后构建和发布阶段继续通过 MSBuild 属性注入：
 
-# 2. 创建版本标签
-git tag v1.0.1
-# 或带注释的标签
-git tag -a v1.0.1 -m "Release v1.0.1"
+- `Version`
+- `AssemblyVersion`
+- `FileVersion`
+- `InformationalVersion`
 
-# 3. 推送标签到 GitHub
-git push origin v1.0.1
+因此最终会统一落到：
 
-# 4. Release 工作流自动运行：
-#    - 自动更新 .csproj 文件
-#    - 构建所有平台
-#    - 创建 GitHub Release
-#    - 附带所有平台的发布包
-```
+- Launcher UI 读取到的应用版本
+- 应用设置页显示的版本
+- `version.json`
+- 程序集文件版本
+- Windows manifest
+- 安装包版本
+- GitHub Release 资产名称
 
-## 🔒 版本号一致性保证
+## 维护规则
 
-现在应用的三个版本号来源完全同步：
-
-| 来源 | 说明 | 自动更新 |
-|------|------|--------|
-| `.csproj` <Version> | 项目文件版本 | ✅ 是 |
-| 程序集版本 | 编译时读取 | ✅ 是 |
-| 应用内显示 | About 页面 | ✅ 是 |
-| 发布包文件名 | Release 工作流 | ✅ 是 |
-| GitHub Release | Release 工作流 | ✅ 是 |
-
-## ⚠️ 注意事项
-
-### 不需要手动更新
-- ❌ 不需要在 `.csproj` 中手动修改 Version
-- ❌ 不需要修改多个地方的版本号
-
-### 只需执行
-- ✅ 创建 Git Tag: `git tag v1.0.1`
-- ✅ 推送 Tag: `git push origin v1.0.1`
-- ✅ 其他由工作流自动处理
-
-## 📊 版本号格式
-
-支持的格式：
-- ✅ `v1.0.0` (builds -> 1.0.0)
-- ✅ `v1.2.3` (builds -> 1.2.3)
-- ✅ `v2.0.0-rc1` (builds -> 2.0.0-rc1, 如果需要)
-
-## 🛠️ 工作流文件
-
-更新的工作流文件：
-- `.github/workflows/release.yml` - Release 工作流
-
-## 📝 相关文件
-
-- [MULTIPLATFORM_RELEASE_GUIDE.md](./MULTIPLATFORM_RELEASE_GUIDE.md) - 多平台发布指南
-- [WORKFLOWS_GUIDE.md](./WORKFLOWS_GUIDE.md) - 工作流使用指南
-
----
-
-**最后更新**: 2026-03-04  
-**工作流版本**: 2.0 (自动版本同步)
+- 日常开发不要手动把仓库默认版本改成正式版本号。
+- 正式发版只需要打 tag，版本同步交给工作流。
+- 如果新增新的版本承载点，必须同时补到 `Set-ReleaseVersion.ps1` 和 Release 工作流里。

.github/workflows/release.yml

@@ -119,6 +119,13 @@ jobs:
           dotnet-version: ${{ env.DOTNET_VERSION }}
           dotnet-quality: 'preview'
 
+      - name: Stamp release version metadata
+        shell: pwsh
+        run: |
+          ./scripts/Set-ReleaseVersion.ps1 `
+            -Version "${{ needs.prepare.outputs.version }}" `
+            -AssemblyVersion "${{ needs.prepare.outputs.assembly_version }}"
+
       - name: Restore
         run: dotnet restore ${{ env.Solution_Name }}
 
@@ -364,6 +371,13 @@ jobs:
           dotnet-version: ${{ env.DOTNET_VERSION }}
           dotnet-quality: 'preview'
 
+      - name: Stamp release version metadata
+        shell: pwsh
+        run: |
+          ./scripts/Set-ReleaseVersion.ps1 `
+            -Version "${{ needs.prepare.outputs.version }}" `
+            -AssemblyVersion "${{ needs.prepare.outputs.assembly_version }}"
+
       - name: Restore
         run: dotnet restore ${{ env.Solution_Name }}
 
@@ -545,6 +559,13 @@ jobs:
           dotnet-version: ${{ env.DOTNET_VERSION }}
           dotnet-quality: 'preview'
 
+      - name: Stamp release version metadata
+        shell: pwsh
+        run: |
+          ./scripts/Set-ReleaseVersion.ps1 `
+            -Version "${{ needs.prepare.outputs.version }}" `
+            -AssemblyVersion "${{ needs.prepare.outputs.assembly_version }}"
+
       - name: Restore
         run: dotnet restore ${{ env.Solution_Name }}
 

.gitignore

@@ -514,3 +514,4 @@ nul
 /*.AppImage
 /velopack-output-local-verify
 /velopack-output-local
+/test-aot-publish

.kilo/package-lock.json

@@ -0,0 +1,376 @@
+{
+  "name": ".kilo",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "@kilocode/plugin": "7.2.20"
+      }
+    },
+    "node_modules/@kilocode/plugin": {
+      "version": "7.2.20",
+      "resolved": "https://registry.npmjs.org/@kilocode/plugin/-/plugin-7.2.20.tgz",
+      "integrity": "sha512-M5lMc58Mu9j1zveH+E3ZUKRHefzh+acNAqHGSG3TuF6K2l16KrZlCl38CZlgj2R5Qgaig6Jec/F2p9Rbn3BhCQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@kilocode/sdk": "7.2.20",
+        "effect": "4.0.0-beta.48",
+        "zod": "4.1.8"
+      },
+      "peerDependencies": {
+        "@opentui/core": ">=0.1.99",
+        "@opentui/solid": ">=0.1.99"
+      },
+      "peerDependenciesMeta": {
+        "@opentui/core": {
+          "optional": true
+        },
+        "@opentui/solid": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@kilocode/sdk": {
+      "version": "7.2.20",
+      "resolved": "https://registry.npmjs.org/@kilocode/sdk/-/sdk-7.2.20.tgz",
+      "integrity": "sha512-KUpu1fyzcAyZWpiv//834zGLN+PYzIH65crs15VTtUJ9CDvGqcj08EM0XlkF9jMuGQAjHjfRbvCfml3+YO31+Q==",
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "7.0.6"
+      }
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-darwin-arm64": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-arm64/-/msgpackr-extract-darwin-arm64-3.0.3.tgz",
+      "integrity": "sha512-QZHtlVgbAdy2zAqNA9Gu1UpIuI8Xvsd1v8ic6B2pZmeFnFcMWiPLfWXh7TVw4eGEZ/C9TH281KwhVoeQUKbyjw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-darwin-x64": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-x64/-/msgpackr-extract-darwin-x64-3.0.3.tgz",
+      "integrity": "sha512-mdzd3AVzYKuUmiWOQ8GNhl64/IoFGol569zNRdkLReh6LRLHOXxU4U8eq0JwaD8iFHdVGqSy4IjFL4reoWCDFw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm/-/msgpackr-extract-linux-arm-3.0.3.tgz",
+      "integrity": "sha512-fg0uy/dG/nZEXfYilKoRe7yALaNmHoYeIoJuJ7KJ+YyU2bvY8vPv27f7UKhGRpY6euFYqEVhxCFZgAUNQBM3nw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm64": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm64/-/msgpackr-extract-linux-arm64-3.0.3.tgz",
+      "integrity": "sha512-YxQL+ax0XqBJDZiKimS2XQaf+2wDGVa1enVRGzEvLLVFeqa5kx2bWbtcSXgsxjQB7nRqqIGFIcLteF/sHeVtQg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-x64": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-x64/-/msgpackr-extract-linux-x64-3.0.3.tgz",
+      "integrity": "sha512-cvwNfbP07pKUfq1uH+S6KJ7dT9K8WOE4ZiAcsrSes+UY55E/0jLYc+vq+DO7jlmqRb5zAggExKm0H7O/CBaesg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-win32-x64": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-win32-x64/-/msgpackr-extract-win32-x64-3.0.3.tgz",
+      "integrity": "sha512-x0fWaQtYp4E6sktbsdAqnehxDgEc/VwM7uLsRCYWaiGu0ykYdZPiS8zCWdnjHwyiumousxfBm4SO31eXqwEZhQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "license": "MIT"
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/effect": {
+      "version": "4.0.0-beta.48",
+      "resolved": "https://registry.npmjs.org/effect/-/effect-4.0.0-beta.48.tgz",
+      "integrity": "sha512-MMAM/ZabuNdNmgXiin+BAanQXK7qM8mlt7nfXDoJ/Gn9V8i89JlCq+2N0AiWmqFLXjGLA0u3FjiOjSOYQk5uMw==",
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "fast-check": "^4.6.0",
+        "find-my-way-ts": "^0.1.6",
+        "ini": "^6.0.0",
+        "kubernetes-types": "^1.30.0",
+        "msgpackr": "^1.11.9",
+        "multipasta": "^0.2.7",
+        "toml": "^4.1.1",
+        "uuid": "^13.0.0",
+        "yaml": "^2.8.3"
+      }
+    },
+    "node_modules/fast-check": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-4.7.0.tgz",
+      "integrity": "sha512-NsZRtqvSSoCP0HbNjUD+r1JH8zqZalyp6gLY9e7OYs7NK9b6AHOs2baBFeBG7bVNsuoukh89x2Yg3rPsul8ziQ==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/dubzzz"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fast-check"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "pure-rand": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=12.17.0"
+      }
+    },
+    "node_modules/find-my-way-ts": {
+      "version": "0.1.6",
+      "resolved": "https://registry.npmjs.org/find-my-way-ts/-/find-my-way-ts-0.1.6.tgz",
+      "integrity": "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA==",
+      "license": "MIT"
+    },
+    "node_modules/ini": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-6.0.0.tgz",
+      "integrity": "sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ==",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.17.0 || >=22.9.0"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
+    "node_modules/kubernetes-types": {
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/kubernetes-types/-/kubernetes-types-1.30.0.tgz",
+      "integrity": "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/msgpackr": {
+      "version": "1.11.10",
+      "resolved": "https://registry.npmjs.org/msgpackr/-/msgpackr-1.11.10.tgz",
+      "integrity": "sha512-iCZNq+HszvF+fC3anCm4nBmWEnbeIAfpDs6IStAEKhQ2YSgkjzVG2FF9XJqwwQh5bH3N9OUTUt4QwVN6MLMLtA==",
+      "license": "MIT",
+      "optionalDependencies": {
+        "msgpackr-extract": "^3.0.2"
+      }
+    },
+    "node_modules/msgpackr-extract": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/msgpackr-extract/-/msgpackr-extract-3.0.3.tgz",
+      "integrity": "sha512-P0efT1C9jIdVRefqjzOQ9Xml57zpOXnIuS+csaB4MdZbTdmGDLo8XhzBG1N7aO11gKDDkJvBLULeFTo46wwreA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "node-gyp-build-optional-packages": "5.2.2"
+      },
+      "bin": {
+        "download-msgpackr-prebuilds": "bin/download-prebuilds.js"
+      },
+      "optionalDependencies": {
+        "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.3",
+        "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.3",
+        "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.3",
+        "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.3",
+        "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.3",
+        "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.3"
+      }
+    },
+    "node_modules/multipasta": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/multipasta/-/multipasta-0.2.7.tgz",
+      "integrity": "sha512-KPA58d68KgGil15oDqXjkUBEBYc00XvbPj5/X+dyzeo/lWm9Nc25pQRlf1D+gv4OpK7NM0J1odrbu9JNNGvynA==",
+      "license": "MIT"
+    },
+    "node_modules/node-gyp-build-optional-packages": {
+      "version": "5.2.2",
+      "resolved": "https://registry.npmjs.org/node-gyp-build-optional-packages/-/node-gyp-build-optional-packages-5.2.2.tgz",
+      "integrity": "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "detect-libc": "^2.0.1"
+      },
+      "bin": {
+        "node-gyp-build-optional-packages": "bin.js",
+        "node-gyp-build-optional-packages-optional": "optional.js",
+        "node-gyp-build-optional-packages-test": "build-test.js"
+      }
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/pure-rand": {
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.0.tgz",
+      "integrity": "sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/dubzzz"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fast-check"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/toml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/toml/-/toml-4.1.1.tgz",
+      "integrity": "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/uuid": {
+      "version": "13.0.0",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-13.0.0.tgz",
+      "integrity": "sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==",
+      "funding": [
+        "https://github.com/sponsors/broofa",
+        "https://github.com/sponsors/ctavan"
+      ],
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist-node/bin/uuid"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.8.3",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
+      "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.1.8",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

.kilo/plans/1776989126427-witty-island.md

@@ -0,0 +1,171 @@
+# LanMountainDesktop 启动器无法启动应用 - 问题分析与修复计划
+
+## 1. 项目架构概述
+
+LanMountainDesktop 采用**双进程架构**：
+- **Launcher** (`LanMountainDesktop.Launcher`) - 启动器，负责版本管理、更新、启动主程序
+- **Host** (`LanMountainDesktop`) - 主应用宿主
+
+### 启动流程
+1. 用户启动 `LanMountainDesktop.Launcher.exe`
+2. Launcher 扫描 `app-*` 目录，选择最佳版本
+3. 检查并应用待处理的更新
+4. 处理插件升级队列
+5. 启动主程序 `app-{version}/LanMountainDesktop.exe`
+6. 通过 IPC 监控主程序启动进度
+
+## 2. 问题分析
+
+### 2.1 核心问题：主机可执行文件找不到
+
+根据代码分析（`DeploymentLocator.cs`），启动器通过以下顺序查找主机可执行文件：
+
+1. **显式 app-root**（如果通过命令行指定）
+2. **已发布部署**（查找 `app-*` 目录）
+3. **可移植主机**（直接在应用根目录）
+4. **调试主机**（开发模式，查找构建输出路径）
+5. **旧版回退路径**
+
+**当前状态检查**：
+- ❌ 未找到 `app-*` 目录（生产部署结构不存在）
+- ❌ 未找到 `bin/Debug/**/*.exe`（项目未构建或构建输出不存在）
+
+### 2.2 可能的启动失败原因
+
+| 问题 | 描述 | 优先级 |
+|------|------|--------|
+| **项目未构建** | LanMountainDesktop 主程序未编译，没有可执行文件 | P0 |
+| **部署结构缺失** | 生产模式下缺少 `app-*` 目录结构 | P0 |
+| **开发模式路径问题** | 调试模式下路径计算错误或构建输出不在预期位置 | P1 |
+| **.NET 版本问题** | 项目使用 .NET 10.0，运行环境可能缺少对应运行时 | P1 |
+| **更新应用失败** | `ApplyPendingUpdateAsync` 失败导致无法完成部署 | P2 |
+| **IPC 连接超时** | 主程序启动后未及时建立 IPC 连接，导致启动器超时 | P2 |
+
+### 2.3 关键代码位置
+
+- **主机查找逻辑**: `LanMountainDesktop.Launcher/Services/DeploymentLocator.cs`
+  - `FindCurrentDeploymentDirectory()` - 查找 app-* 目录
+  - `ResolveHostExecutable()` - 解析主机路径
+  
+- **启动协调逻辑**: `LanMountainDesktop.Launcher/Services/LauncherFlowCoordinator.cs`
+  - `RunAsync()` - 主启动流程
+  - `LaunchHostWithIpcAsync()` - 启动主机进程
+  
+- **更新引擎**: `LanMountainDesktop.Launcher/Services/UpdateEngineService.cs`
+  - `ApplyPendingUpdateAsync()` - 应用待处理的更新
+
+## 3. 诊断步骤
+
+### 步骤 1：检查构建状态
+```bash
+dotnet --info
+dotnet build LanMountainDesktop.slnx -c Debug
+```
+
+### 步骤 2：验证主机可执行文件是否存在
+检查以下路径是否存在 `LanMountainDesktop.exe`：
+- `LanMountainDesktop/bin/Debug/net10.0/`
+- `LanMountainDesktop/bin/Release/net10.0/`
+
+### 步骤 3：测试直接运行主程序（跳过 Launcher）
+```bash
+dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj
+```
+
+### 步骤 4：检查 Launcher 启动日志
+在开发模式下运行 Launcher 并查看控制台输出：
+```bash
+dotnet run --project LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj -- launch
+```
+
+## 4. 修复计划
+
+### 方案 A：构建并配置开发环境（推荐）
+
+**适用场景**：开发或调试环境
+
+1. **构建整个解决方案**
+   ```bash
+   dotnet restore
+   dotnet build LanMountainDesktop.slnx -c Debug
+   ```
+
+2. **验证构建输出**
+   - 确认 `LanMountainDesktop/bin/Debug/net10.0/LanMountainDesktop.exe` 存在
+   - 确认 `LanMountainDesktop.Launcher/bin/Debug/net10.0/LanMountainDesktop.Launcher.exe` 存在
+
+3. **测试 Launcher 启动**
+   ```bash
+   dotnet run --project LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj -- launch
+   ```
+
+4. **如果路径查找失败，检查 `DeploymentLocator.cs` 中的开发路径**
+   - 当前逻辑（第 366-375 行）查找：
+     - `../LanMountainDesktop/bin/Debug/net10.0/LanMountainDesktop.exe`
+     - `../LanMountainDesktop/bin/Release/net10.0/LanMountainDesktop.exe`
+   - 确认这些路径与实际的构建输出路径匹配
+
+### 方案 B：创建生产部署结构
+
+**适用场景**：生产环境或模拟生产环境
+
+1. **发布主程序**
+   ```bash
+   dotnet publish LanMountainDesktop/LanMountainDesktop.csproj -c Release -o app-1.0.0
+   ```
+
+2. **创建 .current 标记文件**
+   ```bash
+   echo. > app-1.0.0/.current
+   ```
+
+3. **从 Launcher 启动**
+   - Launcher 应该能找到 `app-1.0.0/LanMountainDesktop.exe`
+
+### 方案 C：修复潜在的代码问题
+
+如果上述方案无法解决问题，可能需要修复代码：
+
+#### C1. 增强错误处理和日志
+在 `DeploymentLocator.cs` 中添加更详细的日志输出，帮助诊断路径查找失败的原因。
+
+#### C2. 检查更新逻辑
+如果 `ApplyPendingUpdateAsync` 失败，可能导致启动中止。检查 `.launcher/update/incoming/` 目录是否有残留的更新文件。
+
+#### C3. 调整超时设置
+如果主程序启动较慢，可以适当增加 `LauncherFlowCoordinator.cs` 中的超时时间：
+- `StartupSoftTimeout` (当前 10 秒)
+- `StartupHardTimeout` (当前 30 秒)
+
+## 5. 建议执行顺序
+
+1. ✅ **首先执行方案 A 的步骤 1-2**（构建项目）
+2. ✅ **执行诊断步骤 3**（测试直接运行主程序）
+3. ✅ **执行诊断步骤 4**（查看 Launcher 启动日志）
+4. 根据日志输出决定后续操作：
+   - 如果显示 "host executable was not found" → 检查路径配置
+   - 如果显示 "update apply failed" → 清理更新缓存
+   - 如果主程序启动后超时 → 检查 IPC 连接或增加超时
+
+## 6. 验证方法
+
+修复后，通过以下方式验证：
+
+```bash
+# 开发模式启动
+dotnet run --project LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj -- launch
+
+# 或直接运行 Launcher 可执行文件
+# (需要先构建 Launcher)
+```
+
+启动后应该看到：
+1. Splash 窗口显示
+2. 主程序桌面窗口出现
+3. Launcher 自动退出（或最小化到托盘）
+
+## 7. 注意事项
+
+- 项目使用 .NET 10.0（`global.json` 指定版本 10.0.103）
+- 确保开发环境已安装对应的 .NET SDK
+- 如果修改了 `DeploymentLocator.cs` 的路径查找逻辑，需要同步更新文档 `docs/DEVELOPMENT.md`

.trae/documents/avalonia12-migration-plan.md

@@ -0,0 +1,106 @@
+# Avalonia 12 迁移计划
+
+## 当前状态
+
+项目已完成以下迁移准备：
+
+* `Directory.Packages.props` 中 Avalonia 包已升级到 `12.0.1`
+
+* `FluentAvaloniaUI` 已升级到 `3.0.0-preview1`
+
+* `Avalonia.Diagnostics` 已替换为 `AvaloniaUI.DiagnosticsSupport`
+
+* `Avalonia.Controls.WebView` 已升级到 `12.0.0`
+
+* `ClassIsland.Markdown.Avalonia` 已升级到 `12.0.0`
+
+## 构建错误清单（26 errors）
+
+### 1. 窗口装饰 API 移除（8 errors）
+
+**文件**：`LanMountainDesktop/Views/SettingsWindow.axaml.cs`（4 errors）
+
+* `ExtendClientAreaChromeHints` 不存在（line 166, 179）
+
+* `SystemDecorations` 已过时，需改用 `WindowDecorations`（line 168, 177）
+
+**文件**：`LanMountainDesktop/Views/ComponentEditorWindow.axaml.cs`（4 errors）
+
+* `ExtendClientAreaChromeHints` 不存在（line 63, 72）
+
+* `SystemDecorations` 已过时，需改用 `WindowDecorations`（line 65, 70）
+
+**AXAML 文件**：13 个文件使用 `SystemDecorations` 属性（编译警告）
+
+### 2. 变量/字段未找到（8 errors）
+
+**文件**：`LanMountainDesktop/Views/MainWindow.ComponentSystem.cs`
+
+* `centerLeft` 不存在（line 759, 766, 778）
+
+* `positions` 不存在（line 1266）
+
+**文件**：`LanMountainDesktop/Views/MainWindow.DesktopPaging.cs`
+
+* `child` 不存在（line 312）
+
+* `_isThreeFingerOrRightDragSwipeActive` 不存在（line 517, 828, 847, 850）
+
+### 3. API 变更（3 errors）
+
+**文件**：`LanMountainDesktop/App.axaml.cs`
+
+* `BindingPlugins` 不可访问（line 532, 537）
+
+**文件**：`LanMountainDesktop/Views/Components/DesktopComponentFailureView.cs`
+
+* `IClipboard.SetTextAsync` 不存在（line 187）
+
+**文件**：`LanMountainDesktop/Services/MonetColorService.cs`
+
+* `Bitmap.CopyPixels` 参数不匹配（line 91）
+
+### 4. 第三方库变更（1 error）
+
+**文件**：`LanMountainDesktop/Views/SettingsWindow.axaml.cs`
+
+* `FluentIcons.Avalonia.SymbolIconSource` 不存在（line 215）
+
+### 5. 过时属性警告（需同步修复）
+
+* `TextBox.Watermark` → `PlaceholderText`（7 处 .cs + 7 处 .axaml）
+
+## 迁移步骤
+
+### Phase 1: 修复窗口装饰 API（高优先级）
+
+1. 重写 `SettingsWindow.ApplyChromeMode()` 使用 Avalonia 12 新 API
+2. 重写 `ComponentEditorWindow.ApplyChromeMode()` 使用 Avalonia 12 新 API
+3. 批量替换所有 `.axaml` 中的 `SystemDecorations` → `WindowDecorations`
+
+### Phase 2: 修复 MainWindow 编译错误（高优先级）
+
+1. 检查 `MainWindow.ComponentSystem.cs` 中 `centerLeft` 和 `positions` 的作用域问题
+2. 检查 `MainWindow.DesktopPaging.cs` 中 `child` 和 `_isThreeFingerOrRightDragSwipeActive` 的作用域问题
+3. 确认这些变量是否被意外删除或重命名
+
+### Phase 3: 修复 Avalonia 12 API 变更（中优先级）
+
+1. `App.axaml.cs`: 替换 `BindingPlugins.DataValidators` 的访问方式
+2. `DesktopComponentFailureView.cs`: 使用新的剪贴板 API
+3. `MonetColorService.cs`: 更新 `Bitmap.CopyPixels` 调用签名
+
+### Phase 4: 修复第三方库变更（中优先级）
+
+1. `SettingsWindow.axaml.cs`: 替换 `FluentIcons.Avalonia.SymbolIconSource` 为 v3 等效 API
+
+### Phase 5: 清理过时属性（低优先级）
+
+1. 批量替换 `Watermark` → `PlaceholderText`（所有 .cs 和 .axaml）
+
+## 验证步骤
+
+* 每阶段修复后运行 `dotnet build LanMountainDesktop.slnx -c Debug`
+
+* 最终运行 `dotnet test LanMountainDesktop.slnx -c Debug`
+

.trae/specs/avalonia-12-migration/checklist.md

@@ -0,0 +1,21 @@
+# Checklist
+
+- [x] `Directory.Packages.props` contains the Avalonia 12 dependency baseline.
+- [x] Main host references `Avalonia.Controls.WebView`.
+- [x] Source no longer references `WebView.Avalonia`, `AvaloniaWebView`, or `.UseDesktopWebView()`.
+- [x] `BrowserWidget` uses `NativeWebView.Source`, `Navigate`, `Refresh()`, `NavigationStarted`, and `EnvironmentRequested`.
+- [x] WebView blanking navigates to `about:blank`.
+- [x] Plugin SDK package version is `5.0.0`.
+- [x] `PluginSdkInfo.ApiVersion` is `5.0.0`.
+- [x] Plugin template package version default is `5.0.0`.
+- [x] Plugin template manifest `apiVersion` is `5.0.0`.
+- [x] Launcher data location config resolution cannot recurse through `ResolveDataRoot()`.
+- [x] `OobeStateServiceTests` pass.
+- [x] `dotnet build LanMountainDesktop.slnx -c Debug` has 0 errors.
+- [x] `dotnet test LanMountainDesktop.slnx -c Debug` completes without a test host stack overflow.
+- [ ] Windows host smoke test completed.
+- [ ] Windows Launcher smoke test completed.
+- [ ] Settings window FluentAvalonia 3 smoke test completed.
+- [ ] Component editor Material smoke test completed.
+- [ ] BrowserWidget navigation/refresh/page activation smoke test completed.
+- [ ] WebView2 missing-runtime diagnostic smoke test completed.

.trae/specs/avalonia-12-migration/spec.md

@@ -0,0 +1,49 @@
+# Avalonia 12 Full Stack Migration
+
+## Summary
+
+LanMountainDesktop has moved its desktop stack to the Avalonia 12 baseline. The migration covers the main host, Launcher, Plugin SDK, plugin runtime loading policy, official WebView usage, ClassIsland Markdown, FluentAvalonia, FluentIcons, and Material-related dependencies.
+
+## Requirements
+
+### Requirement: Centralized Avalonia 12 dependency baseline
+
+The solution SHALL use central package management for direct Avalonia-facing projects and keep the core UI dependency baseline on Avalonia `12.0.1`.
+
+Required package baseline:
+
+- `Avalonia*` `12.0.1`
+- `Avalonia.Controls.WebView` `12.0.0`
+- `ClassIsland.Markdown.Avalonia` `12.0.0`
+- `FluentAvaloniaUI` `3.0.0-preview1`
+- `FluentIcons.Avalonia` `2.1.325`
+- `Material.Avalonia` `3.16.0`
+- `Material.Icons.Avalonia` `3.0.2`
+
+### Requirement: Official WebView
+
+The host SHALL use `Avalonia.Controls.NativeWebView` for the browser widget and SHALL NOT reference `WebView.Avalonia`, `AvaloniaWebView`, or `.UseDesktopWebView()`.
+
+Windows WebView2 user data configuration SHALL be supplied through `EnvironmentRequested` using `WindowsWebView2EnvironmentRequestedEventArgs.UserDataFolder`.
+
+### Requirement: Plugin SDK v5
+
+The Plugin SDK API baseline SHALL be `5.0.0`. SDK v4 plugins are treated as incompatible until rebuilt.
+
+The SDK SHALL keep the existing public UI extension shape, including `SettingsPageBase` and Avalonia `Control` based desktop components.
+
+### Requirement: Launcher data location stability
+
+Launcher data location configuration SHALL be read from a fixed bootstrap Launcher data directory so resolving the selected data root cannot recursively require resolving itself.
+
+### Requirement: OOBE state compatibility
+
+The Launcher SHALL read current OOBE state from the resolved `Launcher/state` directory and SHALL continue to migrate the legacy `.launcher/state/first_run_completed` marker.
+
+## Acceptance
+
+- `dotnet build LanMountainDesktop.slnx -c Debug` completes with 0 errors.
+- `OobeStateServiceTests` pass.
+- Full `dotnet test LanMountainDesktop.slnx -c Debug` no longer aborts from `DataLocationResolver` recursion.
+- Plugin template defaults to SDK package version `5.0.0` and manifest `apiVersion` `5.0.0`.
+- Current developer documentation points to SDK v5 and Avalonia 12.

.trae/specs/avalonia-12-migration/tasks.md

@@ -0,0 +1,18 @@
+# Tasks
+
+- [x] Centralize Avalonia 12 package versions in `Directory.Packages.props`.
+- [x] Move the host, Launcher, Plugin SDK, DesktopHost, Shared.Contracts, and Avalonia-facing projects onto central package versions.
+- [x] Replace third-party `WebView.Avalonia` usage with official `NativeWebView`.
+- [x] Configure WebView2 user data through `EnvironmentRequested`.
+- [x] Move FluentAvalonia usages to the FA3 control names and package baseline.
+- [x] Move FluentIcons usage to `FluentIcons.Avalonia` and remove the old `.Fluent` package.
+- [x] Update Plugin SDK package version and API baseline to `5.0.0`.
+- [x] Update plugin runtime shared assembly policy for Avalonia 12 / FluentAvalonia / FluentIcons / Material.
+- [x] Fix Avalonia 12 compile breaks in window chrome, binding plugin access, clipboard, bitmap copy, and icon source usage.
+- [x] Fix Launcher data location recursion by using a fixed bootstrap config path.
+- [x] Fix OOBE state tests and legacy marker compatibility.
+- [x] Update PluginTemplate defaults to SDK v5.
+- [x] Add SDK v5 migration documentation.
+- [x] Update current docs from SDK v4 / Avalonia 11 examples to SDK v5 / Avalonia 12.
+- [x] Run full solution tests and record any remaining non-upgrade failures.
+- [ ] Perform Windows manual smoke test for host, Launcher, settings, component editor, BrowserWidget, and WebView2 missing-runtime handling.

.trae/specs/external-ipc-public-api/checklist.md

@@ -0,0 +1,11 @@
+# External IPC Public API Checklist
+
+- [x] Host can expose strong-typed public IPC services.
+- [x] External .NET client can connect and call built-in services.
+- [x] Host publishes launcher startup and loading-state notifications through routed notify.
+- [x] Launcher consumes routed notify instead of the old primary custom named-pipe path.
+- [x] Plugin SDK exposes public IPC contribution primitives.
+- [x] Plugin runtime can discover and register plugin public IPC services.
+- [x] Public catalog includes built-in and plugin-contributed services.
+- [x] `catalog.changed` is emitted when new services are added after startup.
+- [ ] Add example external client sample.

.trae/specs/external-ipc-public-api/spec.md

@@ -0,0 +1,24 @@
+# External IPC Public API Spec
+
+## Goal
+
+Provide a single `dotnetCampus.Ipc` based external integration layer for:
+
+- Host public APIs
+- Launcher/OOBE startup progress and loading-state notifications
+- plugin-contributed public services and live event push
+
+## Delivered
+
+- `LanMountainDesktop.Shared.IPC` project
+- `[IpcPublic]` based built-in public contracts
+- `PublicIpcHostService` and `LanMountainDesktopIpcClient`
+- Launcher migrated to Host public IPC notifications
+- Plugin SDK public IPC contribution API
+- Host runtime integration for plugin public IPC services
+
+## Out of Scope
+
+- plugin process isolation
+- non-.NET strong-typed public IPC clients
+- live plugin public service removal without restart

.trae/specs/external-ipc-public-api/tasks.md

@@ -0,0 +1,12 @@
+# External IPC Public API Tasks
+
+- [x] Add `LanMountainDesktop.Shared.IPC`
+- [x] Expose built-in `[IpcPublic]` services
+- [x] Add routed notify constants and public IPC client/host wrappers
+- [x] Start Host public IPC during app startup
+- [x] Move Launcher startup progress consumption to the new IPC base
+- [x] Add plugin public IPC registration/contributor SDK
+- [x] Register plugin-contributed public services into Host catalog
+- [x] Add integration tests for strong-typed public service access and plugin registration descriptors
+- [ ] Expand built-in public service surface beyond the first minimal set
+- [ ] Add non-.NET bridge guidance and samples

.trae/specs/independent-settings-window/checklist.md

@@ -0,0 +1,6 @@
+- [x] 从桌面、托盘、IPC、组件库进入设置时，都会落到同一个设置窗口
+- [x] 设置已打开时再次触发设置入口，只会聚焦已有窗口，不会切换成关闭
+- [x] 设置窗口始终拥有独立任务栏图标，不受“桌面主窗口在任务栏显示图标”开关影响
+- [x] 点击“回到 Windows”后，只隐藏或最小化桌面主窗口，设置窗口保持可见
+- [x] 启用滑入滑出动画后，只有主窗口参与动画，设置窗口不参与
+- [x] 点击设置窗口关闭按钮后会真实关闭；再次打开时创建新的居中窗口

.trae/specs/independent-settings-window/spec.md

@@ -0,0 +1,78 @@
+# 独立设置窗口 Spec
+
+## Why
+
+- 当前设置窗口仍然带有桌面壳的 owner / anchor 语义，点击“回到 Windows”或触发桌面动画时，容易被一起隐藏或重新定位。
+- 产品新增了“在任务栏显示图标”和“启用滑入滑出动画”设置，需要明确边界：它们只影响桌面主窗口，不影响设置窗口。
+- 桌面底栏、托盘菜单、IPC、组件库等入口应当始终打开同一个独立设置窗口，而不是切换成附属浮窗或开关行为。
+
+## What Changes
+
+- 将设置窗口改为独立顶层窗口，始终使用自己的任务栏按钮和图标。
+- `SettingsWindowService.Open` 改为幂等的 open-or-focus；重复打开只聚焦已有窗口，并在提供目标页时切换到对应页面。
+- 移除 `Owner`、锚点定位和 `Toggle` 语义；首次打开按参考屏幕居中，关闭为真实关闭。
+- 桌面壳的“回到 Windows”、最小化到托盘/任务栏、滑入滑出动画，只影响 `MainWindow`，不会影响设置窗口。
+- 统一桌面、托盘、IPC、组件库等设置入口，全部走 `OpenIndependentSettingsModule`。
+- 设置页文案明确“在任务栏显示图标”只控制桌面主窗口；设置窗口始终保留独立任务栏图标。
+
+## Impact
+
+- Affected code:
+  - `LanMountainDesktop/Services/Settings/SettingsWindowService.cs`
+  - `LanMountainDesktop/App.axaml.cs`
+  - `LanMountainDesktop/Views/MainWindow.axaml.cs`
+  - `LanMountainDesktop/Views/MainWindow.ComponentSystem.cs`
+  - `LanMountainDesktop/Views/FusedDesktopComponentLibraryControl.axaml.cs`
+  - `LanMountainDesktop/Views/SettingsPages/GeneralSettingsPage.axaml`
+- Affected behavior:
+  - 设置窗口生命周期
+  - 设置入口一致性
+  - 任务栏图标与桌面壳显示边界
+
+---
+
+## ADDED Requirements
+
+### Requirement: 设置窗口为独立顶层窗口
+
+系统 SHALL 将设置窗口作为独立顶层窗口显示，而不是作为桌面主窗口的附属子窗。
+
+#### Scenario: 设置窗口拥有独立任务栏图标
+- **WHEN** 用户打开设置窗口
+- **THEN** 设置窗口使用独立顶层窗口方式显示
+- **AND THEN** 设置窗口在任务栏中保留自己的独立按钮和图标
+- **AND THEN** “在任务栏显示图标”开关不会影响设置窗口的任务栏按钮
+
+### Requirement: 设置入口统一为 open-or-focus
+
+系统 SHALL 让所有设置入口打开或聚焦同一个设置窗口实例。
+
+#### Scenario: 已打开时重复触发设置入口
+- **WHEN** 设置窗口已经打开，用户再次从桌面、托盘或 IPC 触发打开设置
+- **THEN** 系统只聚焦现有设置窗口
+- **AND THEN** 如果请求包含目标页，则导航到目标页
+- **AND THEN** 不会把已打开的设置窗口当作开关关闭
+
+### Requirement: 设置窗口不参与桌面壳可见性切换
+
+系统 SHALL 让桌面壳的隐藏、最小化和进出场动画只作用于主窗口。
+
+#### Scenario: 回到 Windows 时设置窗口保持可见
+- **WHEN** 主窗口执行“回到 Windows”并隐藏到托盘或最小化到任务栏
+- **THEN** 设置窗口保持当前可见状态
+- **AND THEN** 设置窗口不会跟随主窗口一起隐藏、最小化或重定位
+
+#### Scenario: 桌面滑入滑出动画不作用于设置窗口
+- **WHEN** 启用了滑入滑出动画并触发主窗口退场或入场
+- **THEN** 只有主窗口参与动画
+- **AND THEN** 设置窗口不会消失，也不会跟随主窗口做进出场动画
+
+### Requirement: 关闭设置窗口时真实销毁实例
+
+系统 SHALL 在用户关闭设置窗口时真实关闭该窗口实例。
+
+#### Scenario: 关闭后再次打开
+- **WHEN** 用户点击设置窗口右上角关闭按钮
+- **THEN** 当前设置窗口实例被关闭并销毁
+- **AND THEN** 下次再次打开设置时创建新的设置窗口实例
+- **AND THEN** 新窗口按参考屏幕居中显示

.trae/specs/independent-settings-window/tasks.md

@@ -0,0 +1,25 @@
+# Tasks
+
+- [x] Task 1: 简化设置窗口打开契约
+  - [x] 将 `SettingsWindowOpenRequest` 从 owner / anchor 语义改为目标页 + 参考屏幕语义
+  - [x] 移除 `ISettingsWindowService.Toggle`
+
+- [x] Task 2: 重做设置窗口服务行为
+  - [x] 设置窗口始终使用 `Show()` 打开
+  - [x] 设置窗口始终 `ShowInTaskbar = true`
+  - [x] 已打开时只聚焦并在需要时切页
+  - [x] 关闭后销毁实例，下次打开重新创建并居中
+
+- [x] Task 3: 统一设置入口并解耦桌面壳
+  - [x] 桌面底栏设置按钮改为 open-or-focus
+  - [x] 组件库入口改为复用 `OpenIndependentSettingsModule`
+  - [x] 移除 `MainWindow` 上的设置窗口锚点逻辑
+
+- [x] Task 4: 明确产品边界
+  - [x] 调整“在任务栏显示图标”文案，限定为桌面主窗口
+  - [x] 新增独立设置窗口 feature spec
+  - [x] 在窗口过渡动画 spec 中补充“设置窗口不参与动画”
+
+- [x] Task 5: 验证
+  - [x] 运行 `dotnet build LanMountainDesktop.slnx -c Debug`
+  - [x] 运行与新 helper 相关的测试

.trae/specs/launcher-oobe-elevation-hardening/checklist.md

@@ -0,0 +1,8 @@
+# Launcher OOBE and Elevation Hardening Checklist
+
+- [ ] New install shows OOBE once.
+- [ ] Same-user reinstall does not show OOBE again.
+- [ ] `postinstall` launch path is handled without misclassifying the user state.
+- [ ] `apply-update` and `plugin-install` do not auto-enter OOBE.
+- [ ] Default plugin install does not request UAC.
+- [ ] Logs include OOBE status, suppression reason, and launch source.

.trae/specs/launcher-oobe-elevation-hardening/spec.md

@@ -0,0 +1,43 @@
+# Launcher OOBE and Elevation Hardening Spec
+
+## Goal
+
+Stabilize the launcher startup path so that:
+
+- OOBE does not reappear for the same Windows user after reinstall/upgrade.
+- Normal startup, OOBE, update checks, incremental downloads, and default plugin installs do not trigger unexpected UAC prompts.
+- Only the approved elevation paths remain allowed.
+
+## Scope
+
+- Launcher OOBE state handling
+- launch source classification
+- elevation boundary cleanup
+- plugin install default behavior
+- diagnostic logging and troubleshooting guidance
+
+## Behavior
+
+- OOBE state is stored as a per-user truth source at `%LOCALAPPDATA%\LanMountainDesktop\.launcher\state\oobe-state.json`.
+- `first_run_completed` is treated as a legacy compatibility marker only.
+- `launchSource` values are treated as:
+  - `normal`
+  - `postinstall`
+  - `apply-update`
+  - `plugin-install`
+  - `debug-preview`
+- Automatic OOBE is allowed only for normal user-mode startup.
+- `postinstall` may show OOBE only when the launcher is not elevated and user state is available.
+- `apply-update`, `plugin-install`, and `debug-preview` must not auto-enter OOBE.
+- Allowed elevation paths are limited to:
+  - the installer itself
+  - full installer update application
+  - user-confirmed legacy uninstall
+- Default plugin installation targets the current user's LocalAppData scope and must not request elevation by default.
+
+## Acceptance
+
+- Same-user reinstall does not re-enter OOBE.
+- Missing or damaged OOBE state does not silently bounce the user back into OOBE loops.
+- Default plugin installation path never triggers surprise UAC.
+- Logs can explain why OOBE was shown or suppressed and why elevation was or was not requested.

.trae/specs/launcher-oobe-elevation-hardening/tasks.md

@@ -0,0 +1,9 @@
+# Launcher OOBE and Elevation Hardening Tasks
+
+- [ ] Move OOBE state to a single per-user JSON source.
+- [ ] Treat `first_run_completed` as legacy migration-only state.
+- [ ] Add explicit `launchSource` handling for startup and maintenance flows.
+- [ ] Suppress auto-OOBE for maintenance and elevated launch contexts.
+- [ ] Remove default elevation from plugin installation into the user data scope.
+- [ ] Add structured diagnostics for OOBE decisions and elevation reasons.
+- [ ] Update launcher docs and troubleshooting guidance.

.trae/specs/launcher-shell-hardening/checklist.md

@@ -0,0 +1,10 @@
+# 验收清单
+
+- [ ] 设置页重启后，Launcher 能重新接管并恢复到正确展示形态。
+- [ ] 插件升级辅助程序完成后，回拉的是 Launcher 而不是宿主 exe。
+- [ ] 已在托盘中的实例再次启动时，不会出现第二个主进程。
+- [ ] 托盘初始化失败时，应用不会进入无入口的 `TrayOnly`。
+- [ ] 托盘运行中丢失时，watchdog 能重建或自动恢复前台。
+- [ ] Launcher UI 版本与应用设置页版本一致。
+- [ ] 发布 tag `vX.Y.Z.W` 时，manifest、程序集、`version.json`、安装包和资产命名一致。
+- [ ] 100% / 150% / 200% / 250% 缩放下，Launcher OOBE、主窗口、通知动画正常。

.trae/specs/launcher-shell-hardening/launcher-coordinator-addendum.md

@@ -0,0 +1,29 @@
+# Launcher Coordinator And Always-On Tray Addendum
+
+## Launcher-to-launcher coordination
+
+- Launcher reserves startup ownership in `%LocalAppData%\LanMountainDesktop\.launcher\state\startup-attempt.json` before it starts the host process.
+- The reserved record includes `CoordinatorPid`, `CoordinatorPipeName`, `HeartbeatAtUtc`, `PublicIpcConnected`, `ShellStatus`, and `ReservedBeforeHostStart`.
+- Only the active coordinator may call `Process.Start()` for the host. Secondary Launchers attach to the coordinator pipe and request desktop activation or status.
+- If the coordinator heartbeat is newer than `10s` and the coordinator pid is alive, a new Launcher must not take over.
+- If the coordinator is stale, the next Launcher may take over the same pending attempt instead of creating a second host attempt.
+- Normal launches probe Host Public IPC first. If a host is already running, Launcher activates that instance and exits without starting another host.
+
+## Finer shell status
+
+- Public shell IPC exposes `GetShellStatusAsync()`, `ActivateMainWindowWithStatusAsync()`, `EnsureTrayReadyAsync()`, and `EnsureTaskbarEntryAsync()`.
+- `PublicShellStatus` separates process, shell state, main-window visibility, tray health, taskbar-entry health, and Public IPC readiness.
+- Launcher success/failure details must include coordinator pid, attempt id, host pid, Public IPC status, tray state, and taskbar usability when available.
+
+## Always-on tray and taskbar repair
+
+- The tray icon and menu are mandatory application-liveness indicators and are not controlled by user settings.
+- Tray watchdog starts during shell initialization and keeps running until application exit.
+- `ShowInTaskbar=true` means hidden/background states prefer `MinimizedToTaskbar`; it never disables the tray.
+- `ShowInTaskbar=false` is the only mode that may enter pure `TrayOnly`, and only after `TrayReady`.
+- When taskbar entry is requested but missing, shell repair recreates or shows the main window minimized with `ShowInTaskbar=true` while keeping the tray visible.
+
+## Regression coverage
+
+- Unit tests cover active coordinator rejection, stale heartbeat takeover, and host-pid assignment after a reserved attempt.
+- Manual QA still needs multi-process Launcher concurrency and real tray loss simulation on Windows.

.trae/specs/launcher-shell-hardening/spec.md

@@ -0,0 +1,67 @@
+# Launcher 外壳托管、托盘兜底与高分屏动画修复
+
+## 背景
+
+当前桌面应用在以下场景存在明显不稳定性：
+
+- 设置页或升级后的“重启”没有统一回到 Launcher。
+- 已有实例处于托盘时，再次启动容易误报“窗口未显示”，甚至重复拉起。
+- 托盘初始化失败或运行中丢失时，应用可能进入无恢复入口状态。
+- Launcher 和宿主的版本来源不一致，发布后容易出现 UI 版本错乱。
+- 高分屏和混合缩放环境下，Launcher OOBE、主窗口入场和通知动画存在像素/DIP 混用问题。
+
+## 目标
+
+- Launcher 成为正式环境唯一的启动与重启入口。
+- 进入 `TrayOnly` 前必须先确认托盘可恢复。
+- Launcher UI 显示的版本号等于应用版本号。
+- 发布工作流显式同步主程序、Launcher、manifest 和产物版本。
+- 动画和定位统一按 DIP 与缩放计算。
+
+## 行为要求
+
+### 1. 重启接管
+
+- 应用内重启、插件升级后的重启都必须优先回到 Launcher。
+- Launcher 对 `SecondaryActivationSucceeded` 只认定为一次成功重定向，不允许再做 fallback 二次拉起。
+- Launcher 启动成功判定区分三类场景：
+  - 前台启动：`DesktopVisible` 或 `ActivationRedirected`
+  - 重启到最小化：`BackgroundReady`
+  - 重启到托盘：`TrayReady + BackgroundReady`
+
+### 2. 托盘硬约束
+
+- 托盘状态机必须至少覆盖：
+  - `Unavailable`
+  - `Initializing`
+  - `Ready`
+  - `Recovering`
+  - `Failed`
+- `HideMainWindowToTray`、关闭到托盘、重启恢复到托盘前都必须先执行托盘就绪检查。
+- 如果托盘不可用：
+  - 优先回退到任务栏最小化
+  - 若任务栏入口也不可用，则强制恢复前台可见
+- 托盘处于隐藏态期间必须运行 watchdog；连续恢复失败时自动恢复主窗口。
+
+### 3. 版本来源
+
+- Launcher 只能显示应用版本，不能显示 Launcher 自身硬编码版本。
+- 版本解析优先顺序：
+  - `version.json`
+  - 主程序文件版本 / 信息版本
+  - `app-<version>` 部署目录
+- Release 工作流必须显式打版本补丁，避免仓库默认占位值被误当成正式版本。
+
+### 4. 高分屏动画
+
+- 主窗口、通知、Launcher OOBE 的动画位移必须使用 DIP 或基于缩放换算后的尺寸。
+- 不允许直接把 `PixelRect` 宽高当作 `TranslateTransform` 或 `DesiredSize` 的输入。
+- 淡入和位移动画应并行执行，避免先淡入后滑动造成观感异常。
+
+## 验收
+
+- 已在托盘中的实例再次通过 Launcher 启动时，只激活已有实例。
+- 设置页重启和插件升级重启后，不再出现“窗口未显示但后台已有多个进程”。
+- 托盘失败时应用仍保持可恢复。
+- Launcher 与应用设置页显示相同版本。
+- 100% / 150% / 200% / 250% 缩放下，Launcher OOBE、主窗口入场、通知位置与动画正常。

.trae/specs/launcher-shell-hardening/startup-visuals-addendum.md

@@ -0,0 +1,37 @@
+# Launcher Slow-Startup And Startup Visual Addendum
+
+## New startup timing contract
+
+- `30s` is a soft timeout, not a failure threshold.
+- After `30s`, if the desktop process is still alive or Public IPC is connected, Launcher must stay in a waiting state and must not start another host process.
+- `120s` is the hard timeout.
+- Before returning `desktop_not_visible`, Launcher must attempt one foreground recovery through `ActivateMainWindowAsync()`.
+
+## Startup attempt de-duplication
+
+- Launcher persists the current startup attempt in `%LocalAppData%\LanMountainDesktop\.launcher\state\startup-attempt.json`.
+- A second Launcher process must attach to a live pending attempt instead of calling `Process.Start()` again.
+- Closing the splash window does not cancel startup; it transitions the attempt into detached waiting and preserves recovery state for the next Launcher run.
+
+## Startup visual modes
+
+- `EnableSlideTransition = true` forces `StartupVisualMode.SlideSplash` and automatically disables fade.
+- `EnableSlideTransition = false && EnableFadeTransition = false` resolves to `StartupVisualMode.StaticSplash`.
+- `EnableSlideTransition = false && EnableFadeTransition = true` resolves to `StartupVisualMode.Fade`.
+
+## UX safeguards
+
+- If the host process is still alive at failure time, the failure dialog must prefer:
+  - `Activate`
+  - `Wait`
+  - `Open Logs`
+  - `Exit`
+- Retry is only valid when Launcher is not about to create a duplicate desktop process.
+
+## Launcher coordinator guard
+
+- Startup attempts are now reserved before host launch, so concurrent Launchers cannot all reach `Process.Start()`.
+- A live coordinator is identified by `CoordinatorPid`, `CoordinatorPipeName`, and a heartbeat newer than `10s`.
+- Secondary Launchers send `activate-desktop` or `attach` to the coordinator pipe and then exit with the coordinator status.
+- If Host Public IPC is already available during a normal launch, Launcher activates the existing desktop and does not start a new host process.
+- Public shell status now reports tray readiness and taskbar-entry usability separately, allowing Launcher to distinguish "running but hidden" from "not recoverable".

.trae/specs/launcher-shell-hardening/tasks.md

@@ -0,0 +1,14 @@
+# 任务拆解
+
+- [x] 为 Launcher/宿主共享新增重启来源、父进程和展示模式参数。
+- [x] 修复 Launcher 对 `SecondaryActivationSucceeded` 的重复 fallback 拉起。
+- [x] 让 Launcher 成功判定支持 `TrayReady` 与 `BackgroundReady`。
+- [x] 应用重启默认优先回到 Launcher，而不是直接回拉宿主 exe。
+- [x] 抽出独立托盘服务，集中处理创建、刷新、watchdog 与状态流转。
+- [x] 在进入 `TrayOnly` 前增加托盘就绪校验与回退策略。
+- [x] 为运行中托盘丢失增加 watchdog 和自动恢复逻辑。
+- [x] 统一公共 IPC、设置页与 Launcher 的版本读取入口。
+- [x] 将仓库默认版本改为开发占位值，并在 Release 工作流中加入显式打版本步骤。
+- [x] 修复主窗口入场、通知定位和 Launcher OOBE 的高分屏动画/定位问题。
+- [x] 补充规格与版本同步说明文档。
+- [ ] 追加针对托盘恢复和启动判定的自动化回归测试。

.trae/specs/launcher-shell-hardening/tray-menu-shutdown-addendum.md

@@ -0,0 +1,17 @@
+# Tray Menu Shutdown Addendum
+
+## Requirements
+
+- Tray menu `Exit App` must commit an irreversible host shutdown request.
+- Once shutdown is committed, tray menu actions must not reopen the desktop, settings window, or component library.
+- Shutdown cleanup must release Public IPC, plugin runtime, tray icon, fused desktop edit UI, telemetry resources, and the single-instance lock before the forced-exit deadline.
+- Forced process termination must be scheduled when the shutdown request is accepted, not only after Avalonia lifetime exit.
+- Restart must preserve `RestartRequested` intent and must not route through an exit path that overwrites it.
+- Fused desktop component library menu activation must reuse the existing library window and must exit edit mode if opening fails.
+
+## Acceptance
+
+- Selecting `Exit App` from the tray leaves no background host process and allows a later Launcher start to acquire the single-instance lock.
+- Selecting `Restart App` starts the Launcher or upgrade helper once, then shuts down the old host as a restart.
+- Repeated tray clicks during shutdown are ignored and logged.
+- Repeated component-library clicks focus the existing window instead of opening duplicates.

.trae/specs/launcher-upgrade/checklist.md

@@ -6,3 +6,6 @@
 - [x] Legacy plugin install arguments still execute.
 - [x] OOBE and splash are implemented as separate windows.
 - [x] Update and rollback logic use version directory markers.
+
+- [ ] Treat `first_run_completed` as legacy-only compatibility data.
+- [ ] Keep the authoritative OOBE state in `%LOCALAPPDATA%\LanMountainDesktop\.launcher\state\oobe-state.json`.

.trae/specs/launcher-upgrade/spec.md

@@ -52,3 +52,9 @@ Upgrade `LanMountainDesktop.Launcher` into the unified Launcher for:
 
 - `IOobeStep` for future multi-step OOBE
 - `ISplashStageReporter` for future startup progress visualization
+
+## Compatibility Addendum
+
+- The current production OOBE state format is a per-user JSON file at `%LOCALAPPDATA%\LanMountainDesktop\.launcher\state\oobe-state.json`.
+- `first_run_completed` remains legacy compatibility data only.
+- Same-user reinstall or upgrade should not re-enter OOBE.

.trae/specs/plugin-process-isolation/checklist.md

@@ -0,0 +1,12 @@
+# Checklist
+
+- [x] `plugin.json` 缺省时仍默认为 `in-proc`
+- [x] 非法 `runtime.mode` 会给出清晰错误
+- [x] SDK 中已有 Worker 入口和隔离运行模式的公共接口
+- [x] IPC 契约已拆到独立工程，且不引用 Avalonia
+- [x] IPC 封装层已集中环境变量、启动参数和通知路由常量
+- [x] 架构文档已写明一期 `isolated-background`、二期 `isolated-window`
+- [x] 架构文档已写明 `IPluginExportRegistry` / `IPluginMessageBus` 不再作为隔离插件主边界
+- [x] 文档已写明 ClassIsland 的借鉴点与取舍
+- [ ] Host 在 Worker 崩溃时仅降级插件且不中断主程序
+- [ ] `isolated-background` 的组件、编辑器、设置页完成真实 IPC 回路

.trae/specs/plugin-process-isolation/spec.md

@@ -0,0 +1,41 @@
+# Plugin Process Isolation
+
+## Why
+
+现有插件体系仍是“同进程 + AssemblyLoadContext 隔离”，无法阻止插件 fatal crash 拖垮 Host，也无法阻止插件直接访问 Host 进程内对象和内存。
+
+## What Changes
+
+- 增加插件运行模式概念：`in-proc`、`isolated-background`、`isolated-window`
+- 一期落地 `isolated-background`
+- 新建独立 IPC 契约包和 IPC 封装包
+- 在 `PluginSdk` 中新增 Worker 入口与 `runtime.mode`
+- 明确隔离模式下不再兼容对象实例共享型 API
+- 新增正式架构文档说明 UI 方案、迁移策略、残余风险和 ClassIsland 借鉴
+
+## Impact
+
+- `LanMountainDesktop.PluginSdk/`
+- `LanMountainDesktop.PluginTemplate/`
+- 新增 `LanMountainDesktop.PluginIsolation.Contracts/`
+- 新增 `LanMountainDesktop.PluginIsolation.Ipc/`
+- `docs/ARCHITECTURE.md`
+- `docs/PLUGIN_PROCESS_ISOLATION_ARCHITECTURE.md`
+
+## Requirements
+
+### Requirement 1
+
+宿主必须同时支持存量 `in-proc` 插件与未来的隔离插件，不得以本次改造打断旧插件加载。
+
+### Requirement 2
+
+隔离插件的 Host/Worker 通信必须基于显式 IPC 路由和 DTO，而不是 Host 服务对象实例共享。
+
+### Requirement 3
+
+一期必须把后台逻辑隔离为独立 Worker 进程，并显式记录 Host UI 壳层的残余风险。
+
+### Requirement 4
+
+仓库文档必须把 ClassIsland IPC 的借鉴点和不照搬的部分写清楚，避免后续实现阶段误把插件协议做成远程对象模型。

.trae/specs/plugin-process-isolation/tasks.md

@@ -0,0 +1,12 @@
+# Tasks
+
+- [x] 梳理现有插件运行时、组件注册、设置页和共享对象边界
+- [x] 形成插件进程隔离架构文档
+- [x] 在 `.trae/specs/plugin-process-isolation/` 下补齐 spec、tasks、checklist
+- [x] 在 `PluginSdk` 中增加 `runtime.mode`、Worker 入口接口和运行模式枚举
+- [x] 新建 `LanMountainDesktop.PluginIsolation.Contracts`，沉淀纯 DTO、路由常量、错误码与 JSON context
+- [x] 新建 `LanMountainDesktop.PluginIsolation.Ipc`，沉淀 ClassIsland 风格的 IPC 包装外壳
+- [x] 更新插件模板 `plugin.json`，让新插件默认显式声明 `in-proc`
+- [ ] 在 Host 侧接入真实 Worker 进程拉起与 dotnetCampus.Ipc 传输绑定
+- [ ] 为 `isolated-background` 构建 Host UI 壳层适配器
+- [ ] 为故障、心跳、降级与恢复补齐端到端测试

.trae/specs/window-slide-transition/spec.md

@@ -113,6 +113,15 @@
 - **AND THEN** 过渡时长使用 `FluttermotionToken.Duration.Page`（320ms）和 `FluttermotionToken.Duration.Intro`（400ms）
 - **AND THEN** 缓动函数使用 `0.05,0.75,0.10,1.00`（DecelerateBezier）
 
+### Requirement: 设置窗口不参与桌面壳过渡动画
+
+系统 SHALL 将桌面壳进出场动画限制在主窗口范围内，不影响独立设置窗口。
+
+#### Scenario: 设置窗口在桌面动画期间保持独立
+- **WHEN** 主窗口执行滑入、滑出、最小化或恢复动画
+- **THEN** 设置窗口不参与该动画
+- **AND THEN** 设置窗口不会跟随主窗口一起隐藏、最小化或重定位
+
 ## MODIFIED Requirements
 
 ### Requirement: OnMinimizeClick 行为

AGENTS.md

@@ -74,7 +74,7 @@ dotnet test LanMountainDesktop.slnx -c Debug
 - SDK 公共 API 以 `LanMountainDesktop.PluginSdk/` 为准
 - 共享契约以 `LanMountainDesktop.Shared.Contracts/` 为准
 - market 数据来源默认是兄弟仓库 `..\\LanAirApp`
-- 迁移或 breaking change 优先同步 `docs/PLUGIN_SDK_V4_MIGRATION.md`
+- 迁移或 breaking change 优先同步 `docs/PLUGIN_SDK_V5_MIGRATION.md`
 
 ### 设置与主题
 
@@ -91,6 +91,6 @@ dotnet test LanMountainDesktop.slnx -c Debug
 - 视觉规范：`docs/VISUAL_SPEC.md`
 - 圆角规范：`docs/CORNER_RADIUS_SPEC.md`
 - 生态边界：`docs/ECOSYSTEM_BOUNDARIES.md`
-- SDK v4 迁移：`docs/PLUGIN_SDK_V4_MIGRATION.md`
+- SDK v5 迁移：`docs/PLUGIN_SDK_V5_MIGRATION.md`
 
 如果多个文档都提到同一件事，以 `docs/ai/DOC_SOURCES.md` 列出的权威来源为准。

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
   <PropertyGroup>
-    <Version>1.0.0</Version>
+    <Version>0.0.0-dev</Version>
     <TargetFramework Condition="'$(TargetFramework)' == ''">net10.0</TargetFramework>
     <Nullable Condition="'$(Nullable)' == ''">enable</Nullable>
     <ImplicitUsings Condition="'$(ImplicitUsings)' == ''">enable</ImplicitUsings>

Directory.Packages.props

@@ -0,0 +1,42 @@
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="Avalonia" Version="12.0.1" />
+    <PackageVersion Include="Avalonia.Controls.WebView" Version="12.0.0" />
+    <PackageVersion Include="Avalonia.Desktop" Version="12.0.1" />
+    <PackageVersion Include="Avalonia.Fonts.Inter" Version="12.0.1" />
+    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.0.1" />
+    <PackageVersion Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1" />
+    <PackageVersion Include="ClassIsland.Markdown.Avalonia" Version="12.0.0" />
+    <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.2.1" />
+    <PackageVersion Include="dotnetCampus.Ipc" Version="2.0.0-alpha434" />
+    <PackageVersion Include="DotNetCampus.AvaloniaInkCanvas" Version="1.0.1" />
+    <PackageVersion Include="Downloader" Version="4.1.1" />
+    <PackageVersion Include="FluentAvaloniaUI" Version="3.0.0-preview1" />
+    <PackageVersion Include="FluentIcons.Avalonia" Version="2.1.325" />
+    <PackageVersion Include="Material.Avalonia" Version="3.16.0" />
+    <PackageVersion Include="MaterialColorUtilities" Version="0.3.0" />
+    <PackageVersion Include="Material.Icons.Avalonia" Version="3.0.2" />
+    <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="MudTools.OfficeInterop" Version="2.0.8" />
+    <PackageVersion Include="MudTools.OfficeInterop.Excel" Version="2.0.8" />
+    <PackageVersion Include="MudTools.OfficeInterop.PowerPoint" Version="2.0.8" />
+    <PackageVersion Include="MudTools.OfficeInterop.Word" Version="2.0.8" />
+    <PackageVersion Include="PortAudioSharp2" Version="1.0.6" />
+    <PackageVersion Include="PostHog" Version="2.4.0" />
+    <PackageVersion Include="Sentry" Version="4.0.0" />
+    <PackageVersion Include="System.Drawing.Common" Version="10.0.0" />
+    <PackageVersion Include="System.Runtime.WindowsRuntime" Version="4.7.0" />
+    <PackageVersion Include="Tmds.DBus.Protocol" Version="0.92.0" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="YamlDotNet" Version="16.3.0" />
+    <PackageVersion Include="log4net" Version="3.3.0" />
+  </ItemGroup>
+</Project>

LanMountainDesktop.DesktopHost/DesktopShellHost.cs

@@ -46,8 +46,8 @@ public sealed class DesktopShellHost : IDesktopShellHost
         if (application.ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
         {
             desktop.Exit += (_, _) => _performExitCleanup();
-            _createAndAssignMainWindow(desktop);
             _startActivationListener();
+            _createAndAssignMainWindow(desktop);
         }
 
         _startWeatherRefresh();

LanMountainDesktop.DesktopHost/LanMountainDesktop.DesktopHost.csproj

@@ -5,7 +5,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="Avalonia" Version="11.3.12" />
+    <PackageReference Include="Avalonia" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\LanMountainDesktop.PluginSdk\LanMountainDesktop.PluginSdk.csproj" />

LanMountainDesktop.Launcher/App.axaml.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using Avalonia;
 using Avalonia.Controls;
 using Avalonia.Controls.ApplicationLifetimes;
@@ -5,7 +6,11 @@ using Avalonia.Markup.Xaml;
 using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Services.Ipc;
 using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
 namespace LanMountainDesktop.Launcher;
 
@@ -13,52 +18,71 @@ public partial class App : Application
 {
     public override void Initialize()
     {
-        // 初始化日志记录器
+        if (Design.IsDesignMode)
+        {
+            AvaloniaXamlLoader.Load(this);
+            return;
+        }
+
         Logger.Initialize();
-        Logger.Info("Launcher starting...");
-        
+        var context = LauncherRuntimeContext.Current;
+        var execution = LauncherExecutionContext.Capture();
+        Logger.Info(
+            $"Launcher App initialize. Command='{context.Command}'; IsGuiMode={context.IsGuiCommand}; " +
+            $"IsPreview={context.IsPreviewCommand}; IsDebugMode={context.IsDebugMode}; " +
+            $"LaunchSource='{context.LaunchSource}'; IsElevated={execution.IsElevated}; " +
+            $"UserSid='{execution.UserSid ?? string.Empty}'; ExplicitAppRoot='{context.ExplicitAppRoot ?? "<none>"}'.");
+
         AvaloniaXamlLoader.Load(this);
     }
 
     public override void OnFrameworkInitializationCompleted()
     {
+        if (Design.IsDesignMode)
+        {
+            base.OnFrameworkInitializationCompleted();
+            return;
+        }
+
         if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
         {
+            desktop.ShutdownMode = ShutdownMode.OnExplicitShutdown;
+
             var context = LauncherRuntimeContext.Current;
+            var execution = LauncherExecutionContext.Capture();
+            Logger.Info(
+                $"Framework initialization completed. Command='{context.Command}'; IsPreview={context.IsPreviewCommand}; " +
+                $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
+                $"IsElevated={execution.IsElevated}; UserSid='{execution.UserSid ?? string.Empty}'.");
 
-            // 调试模式：显示开发调试窗口
-            if (context.IsDebugMode)
-            {
-                var devDebugWindow = new DevDebugWindow();
-                devDebugWindow.Show();
-                
-                // 调试模式下不自动启动正常流程，由开发者通过调试窗口控制
-                base.OnFrameworkInitializationCompleted();
-                return;
-            }
-
-            // 处理各界面的预览命令
             if (HandlePreviewCommand(context, desktop))
             {
                 base.OnFrameworkInitializationCompleted();
                 return;
             }
 
-            // apply-update 模式：显示 UpdateWindow，执行增量更新 + 插件升级
+            // 调试模式：只显示 DevDebugWindow，不走正常启动流程
+            // 避免启动主程序后 Launcher 自动退出，导致开发者无法预览 UI
+            if (context.IsDebugMode && !context.IsPreviewCommand &&
+                !string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
+            {
+                Logger.Info("Debug mode active — showing DevDebugWindow instead of normal launch flow.");
+                var devDebugWindow = new DevDebugWindow();
+                devDebugWindow.Show();
+                base.OnFrameworkInitializationCompleted();
+                return;
+            }
+
             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();
+                var splashWindow = CreateSplashWindow();
                 splashWindow.Show();
-                
-                // 在 try-catch 块中实例化所有服务，确保任何异常都能被捕获
                 _ = RunCoordinatorWithSplashAsync(desktop, context, splashWindow);
             }
         }
@@ -66,248 +90,591 @@ 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");
-                var splashWindow = new SplashWindow();
+            {
+                Logger.Info("Preview command: splash.");
+                var splashWindow = CreateSplashWindow();
                 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 static SplashWindow CreateSplashWindow()
+    {
+        var window = new SplashWindow();
+        TrySetSplashVersionInfo(window, LauncherRuntimeContext.Current);
+        return window;
+    }
+
+    private static void TrySetSplashVersionInfo(SplashWindow window, CommandContext context)
+    {
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(context);
+            var versionInfo = new DeploymentLocator(appRoot).GetVersionInfo();
+            window.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to set splash version info before coordinator start: {ex.Message}");
+        }
+    }
+
     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);
-            var deploymentLocator = new DeploymentLocator(appRoot);
-            
-            // TODO: 从配置读取 GitHub 仓库信息
-            
-            coordinator = new LauncherFlowCoordinator(
-                context,
-                deploymentLocator,
-                new OobeStateService(appRoot),
-                new UpdateEngineService(deploymentLocator),
-                new PluginInstallerService());
+        SplashWindow? currentSplashWindow = splashWindow;
+        var appRoot = Commands.ResolveAppRoot(context);
+        var startupAttemptRegistry = new StartupAttemptRegistry();
+        var coordinatorPipeName = LauncherCoordinatorIpcServer.CreatePipeName();
+        var successPolicy = LauncherFlowCoordinator.ResolveSuccessPolicyKey(context);
 
-            result = await coordinator.RunAsync(splashWindow).ConfigureAwait(false);
-        }
-        catch (Exception ex)
+        if (!startupAttemptRegistry.TryReserveCoordinator(
+                context.LaunchSource,
+                successPolicy,
+                coordinatorPipeName,
+                out var reservedAttempt,
+                out var activeCoordinatorAttempt))
+        {
+            result = await AttachToExistingCoordinatorAsync(
+                context,
+                currentSplashWindow,
+                activeCoordinatorAttempt).ConfigureAwait(false);
+
+            Logger.Info($"Secondary launcher completed. Success={result.Success}; Code='{result.Code}'.");
+            await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
+
+            Environment.ExitCode = result.Success ? 0 : 1;
+            await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
+            return;
+        }
+
+        using var coordinatorServer = new LauncherCoordinatorIpcServer(
+            coordinatorPipeName,
+            BuildCoordinatorStatusFromAttempt(reservedAttempt),
+            HandleCoordinatorRequestAsync,
+            startupAttemptRegistry.UpdateOwnedCoordinatorHeartbeat);
+        coordinatorServer.Start();
+
+        while (true)
         {
-            // 捕获异常并显示错误窗口
-            result = new LauncherResult
-            {
-                Success = false,
-                Stage = "launch",
-                Code = "exception",
-                Message = $"启动器发生错误: {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);
-                }
+                Logger.Info(
+                    $"Coordinator start. Command='{context.Command}'; AppRoot='{appRoot}'; " +
+                    $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
+                    $"ResultPath='{context.GetOption("result") ?? "<none>"}'.");
+
+                var deploymentLocator = new DeploymentLocator(appRoot);
+                var coordinator = new LauncherFlowCoordinator(
+                    context,
+                    deploymentLocator,
+                    new OobeStateService(appRoot),
+                    new UpdateEngineService(deploymentLocator),
+                    new PluginInstallerService(),
+                    startupAttemptRegistry,
+                    coordinatorServer);
+
+                result = await coordinator.RunAsync(currentSplashWindow).ConfigureAwait(false);
             }
-            catch (Exception uiEx)
+            catch (Exception ex)
             {
-                // 最后的兜底：记录到控制台
-                Console.Error.WriteLine($"[Launcher] Critical error in UI thread: {uiEx.Message}");
-                await Task.Delay(3000);
+                Logger.Error("Coordinator threw an unhandled exception.", ex);
+                result = new LauncherResult
+                {
+                    Success = false,
+                    Stage = "launch",
+                    Code = "exception",
+                    Message = $"Launcher failed: {ex.Message}",
+                    ErrorMessage = ex.ToString()
+                };
             }
+
+            if (result.Success ||
+                result.Code == "host_not_found" ||
+                (!string.Equals(result.Stage, "launch", StringComparison.OrdinalIgnoreCase) &&
+                 !string.Equals(result.Stage, "launchHost", StringComparison.OrdinalIgnoreCase)))
+            {
+                break;
+            }
+
+            var failureAction = await ShowFailureWindowAsync(result).ConfigureAwait(false);
+            if (failureAction == ErrorWindowResult.Exit)
+            {
+                break;
+            }
+
+            if (failureAction == ErrorWindowResult.ActivateExisting &&
+                await TryActivateExistingInstanceAsync().ConfigureAwait(false))
+            {
+                result = new LauncherResult
+                {
+                    Success = true,
+                    Stage = "launch",
+                    Code = "activation_requested",
+                    Message = "Launcher activated the existing desktop instance.",
+                    Details = result.Details
+                };
+                break;
+            }
+
+            currentSplashWindow = CreateSplashWindow();
+            currentSplashWindow.Show();
         }
-        
-        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);
+
         Environment.ExitCode = result.Success ? 0 : 1;
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
     }
 
-    /// <summary>
-    /// apply-update 模式：执行增量更新和插件升级，完成后自动退出
-    /// </summary>
+    private static async Task<LauncherResult> AttachToExistingCoordinatorAsync(
+        CommandContext context,
+        SplashWindow? splashWindow,
+        StartupAttemptRecord? activeCoordinatorAttempt)
+    {
+        var reporter = splashWindow as ISplashStageReporter;
+        reporter?.Report("activation", "Connecting to the active launcher...");
+
+        if (activeCoordinatorAttempt is not null &&
+            !string.IsNullOrWhiteSpace(activeCoordinatorAttempt.CoordinatorPipeName))
+        {
+            var command = string.Equals(context.LaunchSource, "restart", StringComparison.OrdinalIgnoreCase)
+                ? LauncherCoordinatorCommands.Attach
+                : LauncherCoordinatorCommands.ActivateDesktop;
+            var request = new LauncherCoordinatorRequest
+            {
+                Command = command,
+                LaunchSource = context.LaunchSource,
+                SuccessPolicy = LauncherFlowCoordinator.ResolveSuccessPolicyKey(context)
+            };
+
+            var response = await new LauncherCoordinatorIpcClient()
+                .SendAsync(activeCoordinatorAttempt.CoordinatorPipeName, request, TimeSpan.FromSeconds(2))
+                .ConfigureAwait(false);
+
+            if (response is not null)
+            {
+                reporter?.Report("activation", response.Message);
+                await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+                var success = response.Accepted ||
+                              IsRecoverableActivationFailure(response.ActivationResult, response.Status);
+                return new LauncherResult
+                {
+                    Success = success,
+                    Stage = "launch",
+                    Code = success && !response.Accepted ? "attached_to_launcher_coordinator" : response.Code,
+                    Message = success && !response.Accepted
+                        ? "Attached to the active Launcher coordinator; desktop startup is still in progress."
+                        : response.Message,
+                    Details = BuildCoordinatorResultDetails(response.Status, response.ActivationResult)
+                };
+            }
+        }
+
+        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+        if (activation is not null)
+        {
+            reporter?.Report("activation", activation.Message);
+            await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+            var success = activation.Accepted || IsRecoverableActivationFailure(activation, null);
+            return new LauncherResult
+            {
+                Success = success,
+                Stage = "launch",
+                Code = activation.Accepted
+                    ? "existing_host_activated"
+                    : success
+                        ? "existing_host_startup_pending"
+                        : "existing_host_activation_failed",
+                Message = success && !activation.Accepted
+                    ? "Existing desktop process is still starting; Launcher attached without starting another process."
+                    : activation.Message,
+                Details = BuildCoordinatorResultDetails(null, activation)
+            };
+        }
+
+        await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+        return new LauncherResult
+        {
+            Success = false,
+            Stage = "launch",
+            Code = "launcher_coordinator_unavailable",
+            Message = "Another Launcher is coordinating startup, but it did not respond in time.",
+            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["activeCoordinatorPid"] = activeCoordinatorAttempt?.CoordinatorPid.ToString() ?? string.Empty,
+                ["activeCoordinatorPipeName"] = activeCoordinatorAttempt?.CoordinatorPipeName ?? string.Empty,
+                ["activeAttemptId"] = activeCoordinatorAttempt?.AttemptId ?? string.Empty,
+                ["activeHostPid"] = activeCoordinatorAttempt?.HostPid.ToString() ?? string.Empty
+            }
+        };
+    }
+
+    private static async Task<LauncherCoordinatorResponse> HandleCoordinatorRequestAsync(
+        LauncherCoordinatorRequest request,
+        LauncherCoordinatorStatus status)
+    {
+        if (string.Equals(request.Command, LauncherCoordinatorCommands.ActivateDesktop, StringComparison.OrdinalIgnoreCase))
+        {
+            var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+            if (activation is not null)
+            {
+                if (!activation.Accepted && IsRecoverableActivationFailure(activation, status))
+                {
+                    return new LauncherCoordinatorResponse
+                    {
+                        Accepted = true,
+                        Code = "attached_to_launcher_coordinator",
+                        Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
+                        Status = status,
+                        ActivationResult = activation
+                    };
+                }
+
+                return new LauncherCoordinatorResponse
+                {
+                    Accepted = activation.Accepted,
+                    Code = activation.Accepted ? "existing_host_activated" : "existing_host_activation_failed",
+                    Message = activation.Message,
+                    Status = status,
+                    ActivationResult = activation
+                };
+            }
+
+            return new LauncherCoordinatorResponse
+            {
+                Accepted = true,
+                Code = "attached_to_launcher_coordinator",
+                Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
+                Status = status
+            };
+        }
+
+        return new LauncherCoordinatorResponse
+        {
+            Accepted = true,
+            Code = "attached_to_launcher_coordinator",
+            Message = "Attached to the active Launcher coordinator.",
+            Status = status
+        };
+    }
+
+    private static LauncherCoordinatorStatus BuildCoordinatorStatusFromAttempt(StartupAttemptRecord attempt)
+    {
+        return new LauncherCoordinatorStatus
+        {
+            AttemptId = attempt.AttemptId,
+            CoordinatorPid = Environment.ProcessId,
+            HostPid = attempt.HostPid,
+            HostProcessAlive = TryGetLiveProcess(attempt.HostPid),
+            LaunchSource = attempt.LaunchSource,
+            SuccessPolicy = attempt.SuccessPolicy,
+            LastObservedStage = attempt.LastObservedStage,
+            LastObservedMessage = attempt.LastObservedMessage,
+            PublicIpcConnected = attempt.PublicIpcConnected || attempt.IpcConnected,
+            State = attempt.State.ToString(),
+            SoftTimeoutShown = attempt.State is StartupAttemptState.SoftTimeout or StartupAttemptState.DetachedWaiting,
+            Completed = attempt.State is StartupAttemptState.Succeeded or StartupAttemptState.Failed,
+            Succeeded = attempt.State == StartupAttemptState.Succeeded,
+            UpdatedAtUtc = attempt.UpdatedAtUtc
+        };
+    }
+
+    private static bool IsRecoverableActivationFailure(
+        PublicShellActivationResult? activation,
+        LauncherCoordinatorStatus? status)
+    {
+        if (activation is { Accepted: true })
+        {
+            return false;
+        }
+
+        if (status is { Completed: false, HostProcessAlive: true })
+        {
+            return true;
+        }
+
+        var shellStatus = activation?.Status;
+        if (shellStatus is null || !shellStatus.PublicIpcReady)
+        {
+            return false;
+        }
+
+        return !shellStatus.MainWindowOpened ||
+               !shellStatus.DesktopVisible ||
+               string.Equals(activation?.Code, "shell_not_ready", StringComparison.OrdinalIgnoreCase) ||
+               string.Equals(activation?.Code, "startup_pending", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static Dictionary<string, string> BuildCoordinatorResultDetails(
+        LauncherCoordinatorStatus? status,
+        PublicShellActivationResult? activation)
+    {
+        var details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["coordinatorPid"] = status?.CoordinatorPid.ToString() ?? string.Empty,
+            ["coordinatorAttemptId"] = status?.AttemptId ?? string.Empty,
+            ["hostPid"] = status?.HostPid.ToString() ?? activation?.Status.ProcessId.ToString() ?? string.Empty,
+            ["hostProcessAlive"] = status?.HostProcessAlive.ToString() ?? string.Empty,
+            ["publicIpcConnected"] = (status?.PublicIpcConnected ?? activation is not null).ToString(),
+            ["startupStage"] = status?.LastObservedStage.ToString() ?? string.Empty,
+            ["startupState"] = status?.State ?? string.Empty,
+            ["activationAccepted"] = activation?.Accepted.ToString() ?? string.Empty,
+            ["shellState"] = activation?.Status.ShellState ?? status?.ShellStatus?.ShellState ?? string.Empty,
+            ["trayState"] = activation?.Status.Tray.State ?? status?.ShellStatus?.Tray.State ?? string.Empty,
+            ["taskbarUsable"] = activation?.Status.Taskbar.IsUsable.ToString() ?? status?.ShellStatus?.Taskbar.IsUsable.ToString() ?? string.Empty
+        };
+
+        return details;
+    }
+
+    private static async Task DismissSplashIfNeededAsync(SplashWindow? splashWindow)
+    {
+        if (splashWindow is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await splashWindow.DismissAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to dismiss splash after coordinator attach: {ex.Message}");
+        }
+    }
+
+    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<ErrorWindowResult> ShowFailureWindowAsync(LauncherResult result)
+    {
+        ErrorWindow? errorWindow = null;
+        var hostProcessAlive = result.Details.TryGetValue("hostProcessAlive", out var hostProcessAliveText) &&
+                               bool.TryParse(hostProcessAliveText, out var hostProcessAliveValue) &&
+                               hostProcessAliveValue;
+        var hostPid = result.Details.TryGetValue("hostPid", out var hostPidText) &&
+                      int.TryParse(hostPidText, out var parsedPid)
+            ? parsedPid
+            : (int?)null;
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                errorWindow = new ErrorWindow();
+                if (hostProcessAlive)
+                {
+                    errorWindow.ConfigureForRunningHostFailure(hostPid);
+                }
+                else
+                {
+                    errorWindow.ConfigureForGenericFailure(allowRetry: true);
+                }
+
+                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 ErrorWindowResult.Exit;
+        }
+
+        try
+        {
+            return await errorWindow.WaitForChoiceAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failure window closed unexpectedly.", ex);
+            return ErrorWindowResult.Exit;
+        }
+    }
+
+    private static async Task<bool> TryActivateExistingInstanceAsync()
+    {
+        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
+        return activation?.Accepted == true;
+    }
+
+    private static async Task<PublicShellActivationResult?> TryActivateExistingInstanceWithStatusAsync(TimeSpan timeout)
+    {
+        try
+        {
+            using var ipcClient = new LanMountainDesktopIpcClient();
+            var connectTask = ipcClient.ConnectAsync();
+            var completedTask = await Task.WhenAny(connectTask, Task.Delay(timeout)).ConfigureAwait(false);
+            if (completedTask != connectTask)
+            {
+                return null;
+            }
+
+            await connectTask.ConfigureAwait(false);
+            if (!ipcClient.IsConnected)
+            {
+                return null;
+            }
+
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            var activationTask = shellProxy.ActivateMainWindowWithStatusAsync();
+            completedTask = await Task.WhenAny(activationTask, Task.Delay(timeout)).ConfigureAwait(false);
+            if (completedTask != activationTask)
+            {
+                return null;
+            }
+
+            return await activationTask.ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to activate the existing desktop instance: {ex.Message}");
+            return null;
+        }
+    }
+
+    private static bool TryGetLiveProcess(int processId)
+    {
+        if (processId <= 0)
+        {
+            return false;
+        }
+
+        try
+        {
+            using var process = Process.GetProcessById(processId);
+            return !process.HasExited;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
     private static async Task RunApplyUpdateWithWindowAsync(
         IClassicDesktopStyleApplicationLifetime desktop,
         CommandContext context,
@@ -324,8 +691,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 +699,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,33 +720,26 @@ 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
         {
             Success = success,
             Stage = "apply-update",
             Code = success ? "ok" : "failed",
-            Message = success ? "Update applied successfully." : (errorMessage ?? "Unknown error")
+            Message = success ? "Update applied successfully." : (errorMessage ?? "Unknown error"),
+            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["command"] = context.Command,
+                ["launchSource"] = context.LaunchSource
+            }
         }).ConfigureAwait(false);
 
         Environment.ExitCode = success ? 0 : 1;
         await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
     }
-
-
 }

LanMountainDesktop.Launcher/AppJsonContext.cs

@@ -3,10 +3,14 @@ using System.Text.Json.Serialization;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Launcher.Services;
 using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
 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))]
@@ -17,12 +21,24 @@ namespace LanMountainDesktop.Launcher;
 [JsonSerializable(typeof(SnapshotMetadata))]
 [JsonSerializable(typeof(AppVersionInfo))]
 [JsonSerializable(typeof(StartupProgressMessage))]
+[JsonSerializable(typeof(LauncherCoordinatorRequest))]
+[JsonSerializable(typeof(LauncherCoordinatorResponse))]
+[JsonSerializable(typeof(LauncherCoordinatorStatus))]
+[JsonSerializable(typeof(PublicShellStatus))]
+[JsonSerializable(typeof(PublicTrayStatus))]
+[JsonSerializable(typeof(PublicTaskbarStatus))]
+[JsonSerializable(typeof(PublicShellActivationResult))]
 [JsonSerializable(typeof(LauncherResult))]
 [JsonSerializable(typeof(HostDiscoveryConfig))]
 [JsonSerializable(typeof(PluginManifest))]
 [JsonSerializable(typeof(PendingUpgrade))]
 [JsonSerializable(typeof(List<PendingUpgrade>))]
+[JsonSerializable(typeof(OobeStateFile))]
+[JsonSerializable(typeof(DataLocationConfig))]
 [JsonSerializable(typeof(GitHubRelease))]
 [JsonSerializable(typeof(GitHubAsset))]
 [JsonSerializable(typeof(List<GitHubRelease>))]
+[JsonSerializable(typeof(StartupAttemptRecord))]
+[JsonSerializable(typeof(PrivacyConfig))]
+[JsonSerializable(typeof(PrivacyAgreementState))]
 internal sealed partial class AppJsonContext : JsonSerializerContext;

LanMountainDesktop.Launcher/CommandContext.cs

@@ -4,6 +4,19 @@ namespace LanMountainDesktop.Launcher;
 
 internal sealed class CommandContext
 {
+    private const string LaunchSourceOptionName = "launch-source";
+
+    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; }
@@ -20,13 +33,43 @@ internal sealed class CommandContext
         Options.ContainsKey("plugins-dir") &&
         Options.ContainsKey("result");
 
+    public string LaunchSource => NormalizeLaunchSource(GetOption(LaunchSourceOptionName)) ?? InferLaunchSource();
+
     /// <summary>
     /// 是否处于调试模式（从 Rider/VS 等 IDE 启动）
-    /// 仅当明确指定 --debug 参数或调试器附加时才启用
+    /// 当满足以下任一条件时启用：
+    /// 1. 明确指定 --debug 参数
+    /// 2. 调试器附加（Debugger.IsAttached）
+    /// 3. DOTNET_ENVIRONMENT 环境变量为 Development（IDE 调试启动时自动设置）
     /// </summary>
     public bool IsDebugMode =>
         Options.ContainsKey("debug") ||
-        System.Diagnostics.Debugger.IsAttached;
+        System.Diagnostics.Debugger.IsAttached ||
+        IsDevelopmentEnvironment;
+
+    /// <summary>
+    /// 是否为 Development 环境（DOTNET_ENVIRONMENT=Development）
+    /// Rider/VS 调试启动时会自动设置此环境变量
+    /// </summary>
+    public bool IsDevelopmentEnvironment =>
+        string.Equals(
+            System.Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT"),
+            "Development",
+            StringComparison.OrdinalIgnoreCase);
+
+    public bool IsPreviewCommand =>
+        Command.StartsWith("preview-", StringComparison.OrdinalIgnoreCase);
+
+    public bool IsGuiCommand =>
+        GuiCommands.Contains(Command, StringComparer.OrdinalIgnoreCase);
+
+    public bool IsMaintenanceCommand =>
+        string.Equals(LaunchSource, "apply-update", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(LaunchSource, "plugin-install", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(Command, "update", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(Command, "plugin", StringComparison.OrdinalIgnoreCase);
+
+    public string? ExplicitAppRoot => GetOption("app-root");
 
     private CommandContext(string command, string subCommand, Dictionary<string, string> options, string[] rawArgs)
     {
@@ -62,6 +105,45 @@ internal sealed class CommandContext
             : fallback;
     }
 
+    private string InferLaunchSource()
+    {
+        if (IsPreviewCommand)
+        {
+            return "debug-preview";
+        }
+
+        if (string.Equals(Command, "apply-update", StringComparison.OrdinalIgnoreCase))
+        {
+            return "apply-update";
+        }
+
+        if (IsLegacyPluginInstall || string.Equals(Command, "plugin", StringComparison.OrdinalIgnoreCase))
+        {
+            return "plugin-install";
+        }
+
+        return "normal";
+    }
+
+    private static string? NormalizeLaunchSource(string? raw)
+    {
+        if (string.IsNullOrWhiteSpace(raw))
+        {
+            return null;
+        }
+
+        return raw.Trim().ToLowerInvariant() switch
+        {
+            "normal" => "normal",
+            "restart" => "restart",
+            "postinstall" => "postinstall",
+            "apply-update" => "apply-update",
+            "plugin-install" => "plugin-install",
+            "debug-preview" => "debug-preview",
+            _ => null
+        };
+    }
+
     private static Dictionary<string, string> ParseOptions(string[] args)
     {
         var values = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
@@ -79,6 +161,13 @@ internal sealed class CommandContext
                 continue;
             }
 
+            var equalsIndex = key.IndexOf('=');
+            if (equalsIndex >= 0)
+            {
+                values[key[..equalsIndex]] = key[(equalsIndex + 1)..];
+                continue;
+            }
+
             if (i + 1 < args.Length && !args[i + 1].StartsWith("--", StringComparison.Ordinal))
             {
                 values[key] = args[++i];

LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj

@@ -8,7 +8,7 @@
     <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
-    <Version>1.0.0</Version>
+    <Version>0.0.0-dev</Version>
     <PackageVersion>$(Version)</PackageVersion>
     <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
     <!-- 应用程序图标 -->
@@ -18,14 +18,18 @@
   <ItemGroup>
     <!-- 只引用 Shared.Contracts（IPC 协议） -->
     <ProjectReference Include="..\LanMountainDesktop.Shared.Contracts\LanMountainDesktop.Shared.Contracts.csproj" />
+    <ProjectReference Include="..\LanMountainDesktop.Shared.IPC\LanMountainDesktop.Shared.IPC.csproj" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Avalonia" Version="11.3.12" />
-    <PackageReference Include="Avalonia.Desktop" Version="11.3.12" />
-    <PackageReference Include="FluentAvaloniaUI" Version="2.5.0" />
-    <PackageReference Include="Avalonia.Fonts.Inter" Version="11.3.12" />
-    <PackageReference Include="Tmds.DBus.Protocol" Version="0.92.0" />
+    <PackageReference Include="Avalonia" />
+    <PackageReference Include="Avalonia.Desktop" />
+    <PackageReference Include="FluentAvaloniaUI" />
+    <PackageReference Include="FluentIcons.Avalonia" />
+    <PackageReference Include="Avalonia.Fonts.Inter" />
+    <PackageReference Include="ClassIsland.Markdown.Avalonia" />
+    <PackageReference Include="CommunityToolkit.Mvvm" />
+    <PackageReference Include="Tmds.DBus.Protocol" />
   </ItemGroup>
 
   <!-- 资源文件 -->
@@ -34,6 +38,7 @@
     <None Include="Assets\public-key.pem" CopyToOutputDirectory="PreserveNewest" />
     <!-- Avalonia 资源文件 -->
     <AvaloniaResource Include="Assets\logo.ico" />
+    <AvaloniaResource Include="..\LanMountainDesktop\Assets\logo_nightly.png" Link="Assets\logo_nightly.png" />
   </ItemGroup>
 
   <Target Name="CopyPublicKeyToLauncherDir" AfterTargets="Build">

LanMountainDesktop.Launcher/Models/DataLocationModels.cs

@@ -0,0 +1,23 @@
+namespace LanMountainDesktop.Launcher.Models;
+
+internal enum DataLocationMode
+{
+    System,
+    Portable
+}
+
+internal sealed class DataLocationConfig
+{
+    public string DataLocationMode { get; set; } = "System";
+
+    public string? SystemDataPath { get; set; }
+
+    public string? PortableDataPath { get; set; }
+}
+
+internal sealed class DataLocationPromptResult
+{
+    public DataLocationMode SelectedMode { get; init; }
+
+    public bool MigrateExistingData { get; init; }
+}

LanMountainDesktop.Launcher/Models/LauncherCoordinatorMessages.cs

@@ -0,0 +1,96 @@
+using System.Text.Json.Serialization;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Models;
+
+internal static class LauncherCoordinatorCommands
+{
+    public const string Attach = "attach";
+    public const string ActivateDesktop = "activate-desktop";
+    public const string GetStatus = "get-status";
+}
+
+internal sealed class LauncherCoordinatorRequest
+{
+    [JsonPropertyName("requestId")]
+    public string RequestId { get; init; } = Guid.NewGuid().ToString("N");
+
+    [JsonPropertyName("command")]
+    public string Command { get; init; } = LauncherCoordinatorCommands.Attach;
+
+    [JsonPropertyName("launcherPid")]
+    public int LauncherPid { get; init; } = Environment.ProcessId;
+
+    [JsonPropertyName("launchSource")]
+    public string LaunchSource { get; init; } = string.Empty;
+
+    [JsonPropertyName("successPolicy")]
+    public string SuccessPolicy { get; init; } = string.Empty;
+}
+
+internal sealed class LauncherCoordinatorResponse
+{
+    [JsonPropertyName("accepted")]
+    public bool Accepted { get; init; }
+
+    [JsonPropertyName("code")]
+    public string Code { get; init; } = string.Empty;
+
+    [JsonPropertyName("message")]
+    public string Message { get; init; } = string.Empty;
+
+    [JsonPropertyName("status")]
+    public LauncherCoordinatorStatus? Status { get; init; }
+
+    [JsonPropertyName("activationResult")]
+    public PublicShellActivationResult? ActivationResult { get; init; }
+}
+
+internal sealed class LauncherCoordinatorStatus
+{
+    [JsonPropertyName("attemptId")]
+    public string AttemptId { get; init; } = string.Empty;
+
+    [JsonPropertyName("coordinatorPid")]
+    public int CoordinatorPid { get; init; } = Environment.ProcessId;
+
+    [JsonPropertyName("hostPid")]
+    public int HostPid { get; init; }
+
+    [JsonPropertyName("hostProcessAlive")]
+    public bool HostProcessAlive { get; init; }
+
+    [JsonPropertyName("launchSource")]
+    public string LaunchSource { get; init; } = string.Empty;
+
+    [JsonPropertyName("successPolicy")]
+    public string SuccessPolicy { get; init; } = string.Empty;
+
+    [JsonPropertyName("lastObservedStage")]
+    public StartupStage LastObservedStage { get; init; } = StartupStage.Initializing;
+
+    [JsonPropertyName("lastObservedMessage")]
+    public string LastObservedMessage { get; init; } = string.Empty;
+
+    [JsonPropertyName("publicIpcConnected")]
+    public bool PublicIpcConnected { get; init; }
+
+    [JsonPropertyName("state")]
+    public string State { get; init; } = string.Empty;
+
+    [JsonPropertyName("softTimeoutShown")]
+    public bool SoftTimeoutShown { get; init; }
+
+    [JsonPropertyName("completed")]
+    public bool Completed { get; init; }
+
+    [JsonPropertyName("succeeded")]
+    public bool Succeeded { get; init; }
+
+    [JsonPropertyName("shellStatus")]
+    public PublicShellStatus? ShellStatus { get; init; }
+
+    [JsonPropertyName("updatedAtUtc")]
+    public DateTimeOffset UpdatedAtUtc { get; init; } = DateTimeOffset.UtcNow;
+}

LanMountainDesktop.Launcher/Models/OobeStateModels.cs

@@ -0,0 +1,63 @@
+namespace LanMountainDesktop.Launcher.Models;
+
+internal enum OobeStateStatus
+{
+    FirstRun,
+    Completed,
+    Unavailable,
+    Suppressed
+}
+
+internal sealed class OobeStateFile
+{
+    public int SchemaVersion { get; init; } = 1;
+
+    public string CompletedAtUtc { get; init; } = string.Empty;
+
+    public string UserName { get; init; } = string.Empty;
+
+    public string? UserSid { get; init; }
+
+    public string LaunchSource { get; init; } = string.Empty;
+}
+
+internal sealed class OobeLaunchDecision
+{
+    public OobeStateStatus Status { get; init; }
+
+    public bool ShouldShowOobe { get; init; }
+
+    public string StatePath { get; init; } = string.Empty;
+
+    public string LaunchSource { get; init; } = "normal";
+
+    public bool IsElevated { get; init; }
+
+    public string UserName { get; init; } = string.Empty;
+
+    public string? UserSid { get; init; }
+
+    public string ResultCode { get; init; } = "ok";
+
+    public string SuppressionReason { get; init; } = string.Empty;
+
+    public string ErrorMessage { get; init; } = string.Empty;
+
+    public bool UsedLegacyMarker { get; init; }
+
+    public bool MigratedLegacyMarker { get; init; }
+}
+
+internal sealed class OobeCompletionResult
+{
+    public bool Success { get; init; }
+
+    public string ResultCode { get; init; } = "ok";
+
+    public string ErrorMessage { get; init; } = string.Empty;
+}
+
+internal sealed record LauncherExecutionSnapshot(
+    bool IsElevated,
+    string UserName,
+    string? UserSid);

LanMountainDesktop.Launcher/Models/PrivacyAgreementState.cs

@@ -0,0 +1,42 @@
+namespace LanMountainDesktop.Launcher.Models;
+
+/// <summary>
+/// 隐私协议同意状态模型（带防篡改保护）
+/// </summary>
+public class PrivacyAgreementState
+{
+    /// <summary>
+    /// 用户是否同意隐私协议
+    /// </summary>
+    public bool IsAgreed { get; set; } = false;
+
+    /// <summary>
+    /// 同意时间（UTC）
+    /// </summary>
+    public DateTime AgreedAtUtc { get; set; }
+
+    /// <summary>
+    /// 同意的协议版本
+    /// </summary>
+    public string AgreementVersion { get; set; } = "1.0";
+
+    /// <summary>
+    /// 用户标识（匿名）
+    /// </summary>
+    public string UserId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 设备标识
+    /// </summary>
+    public string DeviceId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 数据完整性校验哈希（HMAC-SHA256）
+    /// </summary>
+    public string IntegrityHash { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 用于生成哈希的随机盐值
+    /// </summary>
+    public string Salt { get; set; } = string.Empty;
+}

LanMountainDesktop.Launcher/Models/PrivacyConfig.cs

@@ -0,0 +1,22 @@
+namespace LanMountainDesktop.Launcher.Models;
+
+/// <summary>
+/// 隐私配置模型
+/// </summary>
+public class PrivacyConfig
+{
+    /// <summary>
+    /// 是否启用崩溃报告遥测
+    /// </summary>
+    public bool CrashTelemetryEnabled { get; set; } = true;
+
+    /// <summary>
+    /// 是否启用使用统计遥测
+    /// </summary>
+    public bool UsageTelemetryEnabled { get; set; } = true;
+
+    /// <summary>
+    /// 隐私追踪 ID
+    /// </summary>
+    public string TelemetryId { get; set; } = string.Empty;
+}

LanMountainDesktop.Launcher/Models/StartupAttemptRecord.cs

@@ -0,0 +1,65 @@
+using System.Text.Json.Serialization;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Models;
+
+internal enum StartupAttemptState
+{
+    Pending,
+    SoftTimeout,
+    DetachedWaiting,
+    Succeeded,
+    Failed,
+    WaitingForShell
+}
+
+internal sealed class StartupAttemptRecord
+{
+    [JsonPropertyName("attemptId")]
+    public string AttemptId { get; set; } = Guid.NewGuid().ToString("N");
+
+    [JsonPropertyName("hostPid")]
+    public int HostPid { get; set; }
+
+    [JsonPropertyName("coordinatorPid")]
+    public int CoordinatorPid { get; set; }
+
+    [JsonPropertyName("coordinatorPipeName")]
+    public string CoordinatorPipeName { get; set; } = string.Empty;
+
+    [JsonPropertyName("startedAtUtc")]
+    public DateTimeOffset StartedAtUtc { get; set; } = DateTimeOffset.UtcNow;
+
+    [JsonPropertyName("updatedAtUtc")]
+    public DateTimeOffset UpdatedAtUtc { get; set; } = DateTimeOffset.UtcNow;
+
+    [JsonPropertyName("heartbeatAtUtc")]
+    public DateTimeOffset HeartbeatAtUtc { get; set; } = DateTimeOffset.UtcNow;
+
+    [JsonPropertyName("launchSource")]
+    public string LaunchSource { get; set; } = string.Empty;
+
+    [JsonPropertyName("successPolicy")]
+    public string SuccessPolicy { get; set; } = string.Empty;
+
+    [JsonPropertyName("lastObservedStage")]
+    public StartupStage LastObservedStage { get; set; } = StartupStage.Initializing;
+
+    [JsonPropertyName("lastObservedMessage")]
+    public string LastObservedMessage { get; set; } = string.Empty;
+
+    [JsonPropertyName("ipcConnected")]
+    public bool IpcConnected { get; set; }
+
+    [JsonPropertyName("publicIpcConnected")]
+    public bool PublicIpcConnected { get; set; }
+
+    [JsonPropertyName("shellStatus")]
+    public string ShellStatus { get; set; } = string.Empty;
+
+    [JsonPropertyName("reservedBeforeHostStart")]
+    public bool ReservedBeforeHostStart { get; set; }
+
+    [JsonPropertyName("state")]
+    public StartupAttemptState State { get; set; } = StartupAttemptState.Pending;
+}

LanMountainDesktop.Launcher/Program.cs

@@ -4,41 +4,69 @@ using LanMountainDesktop.Launcher.Services;
 
 namespace LanMountainDesktop.Launcher;
 
-internal static class Program
+public static class Program
 {
     [STAThread]
-    private static async Task<int> Main(string[] args)
+    public static async Task<int> Main(string[] args)
     {
         var commandContext = CommandContext.FromArgs(args);
+        var execution = LauncherExecutionContext.Capture();
+        Logger.Initialize();
+        Logger.Info(
+            $"Program entry. Command='{commandContext.Command}'; SubCommand='{commandContext.SubCommand}'; " +
+            $"IsGuiMode={commandContext.IsGuiCommand}; IsDebugMode={commandContext.IsDebugMode}; " +
+            $"LaunchSource='{commandContext.LaunchSource}'; IsElevated={execution.IsElevated}; " +
+            $"UserSid='{execution.UserSid ?? string.Empty}'; " +
+            $"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,
+                    ["launchSource"] = commandContext.LaunchSource,
+                    ["isGuiMode"] = commandContext.IsGuiCommand.ToString(),
+                    ["isDebugMode"] = commandContext.IsDebugMode.ToString(),
+                    ["isElevated"] = execution.IsElevated.ToString(),
+                    ["userSid"] = execution.UserSid ?? string.Empty,
+                    ["explicitAppRoot"] = commandContext.ExplicitAppRoot ?? string.Empty
+                }
+            };
+
+            await Commands.WriteResultIfNeededAsync(commandContext.GetOption("result"), result).ConfigureAwait(false);
+            return 1;
+        }
     }
 
-    private static AppBuilder BuildAvaloniaApp()
+    public static AppBuilder BuildAvaloniaApp()
     {
         return AppBuilder.Configure<App>()
             .UsePlatformDetect()

LanMountainDesktop.Launcher/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("LanMountainDesktop.Tests")]

LanMountainDesktop.Launcher/Properties/launchSettings.json

@@ -1,6 +1,14 @@
 {
   "$schema": "http://json.schemastore.org/launchsettings.json",
   "profiles": {
+    "Launcher (Debug Mode)": {
+      "commandName": "Project",
+      "commandLineArgs": "launch --debug",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
     "Launcher (Launch Mode)": {
       "commandName": "Project",
       "commandLineArgs": "launch",
@@ -9,6 +17,46 @@
         "DOTNET_ENVIRONMENT": "Development"
       }
     },
+    "Launcher (Preview Debug Window)": {
+      "commandName": "Project",
+      "commandLineArgs": "preview-debug",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
+    "Launcher (Preview Splash)": {
+      "commandName": "Project",
+      "commandLineArgs": "preview-splash",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
+    "Launcher (Preview Error)": {
+      "commandName": "Project",
+      "commandLineArgs": "preview-error",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
+    "Launcher (Preview Update)": {
+      "commandName": "Project",
+      "commandLineArgs": "preview-update",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
+    "Launcher (Preview OOBE)": {
+      "commandName": "Project",
+      "commandLineArgs": "preview-oobe",
+      "workingDirectory": "$(SolutionDir)",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
     "Launcher (Update Check)": {
       "commandName": "Project",
       "commandLineArgs": "update check",

LanMountainDesktop.Launcher/Services/Commands.cs

@@ -166,7 +166,10 @@ internal static class Commands
             return Path.GetFullPath(configured);
         }
 
-        var baseDir = AppContext.BaseDirectory;
+        var launcherDir = Path.GetDirectoryName(Environment.ProcessPath);
+        var baseDir = Path.GetFullPath(!string.IsNullOrWhiteSpace(launcherDir)
+            ? launcherDir
+            : AppContext.BaseDirectory);
         
         // 发布版结构：Launcher 和 app-* 目录在同一目录
         // 检查当前目录是否有 app-* 子目录（发布版）

LanMountainDesktop.Launcher/Services/DataLocationOobeStep.cs

@@ -0,0 +1,67 @@
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class DataLocationOobeStep : IOobeStep
+{
+    private readonly DataLocationResolver _resolver;
+
+    public DataLocationOobeStep(DataLocationResolver resolver)
+    {
+        _resolver = resolver;
+    }
+
+    public async Task RunAsync(CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var existingConfig = _resolver.LoadConfig();
+        if (existingConfig is not null)
+        {
+            Logger.Info("DataLocation OOBE step skipped: config already exists.");
+            return;
+        }
+
+        DataLocationPromptWindow? window = null;
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            window = new DataLocationPromptWindow(_resolver);
+            window.Show();
+        });
+
+        if (window is null)
+        {
+            Logger.Warn("DataLocation OOBE step failed: window could not be created.");
+            return;
+        }
+
+        try
+        {
+            var result = await window.WaitForChoiceAsync().ConfigureAwait(false);
+            if (result is null)
+            {
+                Logger.Info("DataLocation OOBE step: user cancelled or closed window. Using default system location.");
+                _resolver.ApplyLocationChoice(DataLocationMode.System, null, false);
+            }
+            else
+            {
+                var success = _resolver.ApplyLocationChoice(result.SelectedMode, null, result.MigrateExistingData);
+                Logger.Info(
+                    $"DataLocation OOBE step: user selected '{result.SelectedMode}'. " +
+                    $"Migrate={result.MigrateExistingData}; Success={success}.");
+            }
+        }
+        finally
+        {
+            await Dispatcher.UIThread.InvokeAsync(() =>
+            {
+                if (window.IsVisible)
+                {
+                    window.Close();
+                }
+            });
+        }
+    }
+}

LanMountainDesktop.Launcher/Services/DataLocationResolver.cs

@@ -0,0 +1,283 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class DataLocationResolver
+{
+    private const string ConfigFileName = "data-location.config.json";
+    private const string LauncherFolderName = "Launcher";
+    private const string DesktopFolderName = "Desktop";
+
+    private readonly string _appRoot;
+    private readonly string _defaultSystemDataPath;
+
+    public DataLocationResolver(string appRoot)
+    {
+        _appRoot = Path.GetFullPath(appRoot);
+        _defaultSystemDataPath = Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+            "LanMountainDesktop");
+    }
+
+    public string AppRoot => _appRoot;
+
+    /// <summary>
+    /// 默认系统数据路径（用户目录）
+    /// </summary>
+    public string DefaultSystemDataPath => _defaultSystemDataPath;
+
+    /// <summary>
+    /// 默认便携模式数据路径（应用目录下的 AppData）
+    /// </summary>
+    public string DefaultPortableDataPath => Path.Combine(_appRoot, "AppData");
+
+    private string ResolveBootstrapLauncherDataPath()
+    {
+        return Path.Combine(_defaultSystemDataPath, LauncherFolderName);
+    }
+
+    /// <summary>
+    /// 检查是否允许便携模式（应用目录是否可写）
+    /// </summary>
+    public bool IsPortableModeAllowed()
+    {
+        try
+        {
+            var testFile = Path.Combine(_appRoot, $".write-test-{Guid.NewGuid():N}.tmp");
+            File.WriteAllText(testFile, string.Empty);
+            File.Delete(testFile);
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// 解析数据根目录（用户选择的位置）
+    /// </summary>
+    public string ResolveDataRoot()
+    {
+        var config = LoadConfig();
+        return ResolveDataRoot(config);
+    }
+
+    private string ResolveDataRoot(DataLocationConfig? config)
+    {
+        if (config is null)
+        {
+            return _defaultSystemDataPath;
+        }
+
+        if (string.Equals(config.DataLocationMode, "Portable", StringComparison.OrdinalIgnoreCase))
+        {
+            var portablePath = !string.IsNullOrWhiteSpace(config.PortableDataPath)
+                ? config.PortableDataPath
+                : DefaultPortableDataPath;
+            return Path.GetFullPath(portablePath);
+        }
+
+        return !string.IsNullOrWhiteSpace(config.SystemDataPath)
+            ? Path.GetFullPath(config.SystemDataPath)
+            : _defaultSystemDataPath;
+    }
+
+    /// <summary>
+    /// 启动器数据目录（日志、配置、状态等）
+    /// </summary>
+    public string ResolveLauncherDataPath()
+    {
+        return Path.Combine(ResolveDataRoot(), LauncherFolderName);
+    }
+
+    /// <summary>
+    /// 桌面应用数据目录（组件、设置、插件等）
+    /// </summary>
+    public string ResolveDesktopDataPath()
+    {
+        return Path.Combine(ResolveDataRoot(), DesktopFolderName);
+    }
+
+    /// <summary>
+    /// 数据位置配置文件路径（保存在 Launcher 目录下）
+    /// </summary>
+    public string ResolveConfigPath()
+    {
+        return Path.Combine(ResolveBootstrapLauncherDataPath(), ConfigFileName);
+    }
+
+    /// <summary>
+    /// 启动器日志目录
+    /// </summary>
+    public string ResolveLauncherLogsPath()
+    {
+        return Path.Combine(ResolveLauncherDataPath(), "logs");
+    }
+
+    /// <summary>
+    /// 启动器状态目录
+    /// </summary>
+    public string ResolveLauncherStatePath()
+    {
+        return Path.Combine(ResolveLauncherDataPath(), "state");
+    }
+
+    public DataLocationMode ResolveMode()
+    {
+        var config = LoadConfig();
+        if (config is null)
+        {
+            return DataLocationMode.System;
+        }
+
+        return string.Equals(config.DataLocationMode, "Portable", StringComparison.OrdinalIgnoreCase)
+            ? DataLocationMode.Portable
+            : DataLocationMode.System;
+    }
+
+    public DataLocationConfig? LoadConfig()
+    {
+        try
+        {
+            // 配置文件必须位于默认系统数据路径下的 Launcher 目录中
+            // 避免循环依赖：不能调用 ResolveConfigPath() -> ResolveLauncherDataPath() -> ResolveDataRoot() -> LoadConfig()
+            var configPath = Path.Combine(_defaultSystemDataPath, LauncherFolderName, ConfigFileName);
+            if (!File.Exists(configPath))
+            {
+                return null;
+            }
+
+            var json = File.ReadAllText(configPath);
+            return JsonSerializer.Deserialize(json, AppJsonContext.Default.DataLocationConfig);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to load data location config. Error='{ex.Message}'.");
+            return null;
+        }
+    }
+
+    public bool SaveConfig(DataLocationConfig config)
+    {
+        try
+        {
+            var launcherPath = ResolveBootstrapLauncherDataPath();
+            Directory.CreateDirectory(launcherPath);
+
+            var configPath = ResolveConfigPath();
+            var json = JsonSerializer.Serialize(config, AppJsonContext.Default.DataLocationConfig);
+            File.WriteAllText(configPath, json);
+            return true;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to save data location config. Error='{ex.Message}'.");
+            return false;
+        }
+    }
+
+    public bool ApplyLocationChoice(DataLocationMode mode, string? customPath = null, bool migrateExistingData = false)
+    {
+        var targetDataRoot = mode == DataLocationMode.Portable && !string.IsNullOrWhiteSpace(customPath)
+            ? Path.GetFullPath(customPath)
+            : _defaultSystemDataPath;
+
+        var config = new DataLocationConfig
+        {
+            DataLocationMode = mode.ToString(),
+            SystemDataPath = _defaultSystemDataPath,
+            PortableDataPath = mode == DataLocationMode.Portable ? targetDataRoot : null
+        };
+
+        // 先创建目录结构
+        try
+        {
+            var resolvedDataRoot = ResolveDataRoot(config);
+            Directory.CreateDirectory(Path.Combine(resolvedDataRoot, LauncherFolderName));
+            Directory.CreateDirectory(Path.Combine(resolvedDataRoot, DesktopFolderName));
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to create data directories. Error='{ex.Message}'.");
+            return false;
+        }
+
+        // 保存配置
+        if (!SaveConfig(config))
+        {
+            return false;
+        }
+
+        if (migrateExistingData && mode == DataLocationMode.Portable)
+        {
+            MigrateSystemDataToPortable(targetDataRoot);
+        }
+
+        return true;
+    }
+
+    public bool HasExistingSystemData()
+    {
+        var desktopPath = Path.Combine(_defaultSystemDataPath, DesktopFolderName);
+        if (!Directory.Exists(desktopPath))
+        {
+            return false;
+        }
+
+        var markerFiles = new[]
+        {
+            Path.Combine(desktopPath, "settings.json"),
+            Path.Combine(desktopPath, "component-state.db"),
+            Path.Combine(desktopPath, "app.db")
+        };
+
+        return markerFiles.Any(File.Exists);
+    }
+
+    private void MigrateSystemDataToPortable(string targetDataRoot)
+    {
+        if (!HasExistingSystemData())
+        {
+            return;
+        }
+
+        var sourceDesktopPath = Path.Combine(_defaultSystemDataPath, DesktopFolderName);
+        var targetDesktopPath = Path.Combine(targetDataRoot, DesktopFolderName);
+
+        try
+        {
+            Directory.CreateDirectory(targetDesktopPath);
+
+            // 迁移桌面数据
+            if (Directory.Exists(sourceDesktopPath))
+            {
+                CopyDirectory(sourceDesktopPath, targetDesktopPath);
+            }
+
+            Logger.Info($"Data migration completed. Target='{targetDataRoot}'.");
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Data migration failed. Target='{targetDataRoot}'. Error='{ex.Message}'.");
+        }
+    }
+
+    private static void CopyDirectory(string sourceDir, string destDir)
+    {
+        Directory.CreateDirectory(destDir);
+
+        foreach (var file in Directory.GetFiles(sourceDir))
+        {
+            var destFile = Path.Combine(destDir, Path.GetFileName(file));
+            File.Copy(file, destFile, overwrite: true);
+        }
+
+        foreach (var subDir in Directory.GetDirectories(sourceDir))
+        {
+            var destSubDir = Path.Combine(destDir, Path.GetFileName(subDir));
+            CopyDirectory(subDir, destSubDir);
+        }
+    }
+}

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 =>
                 {
@@ -58,8 +57,8 @@ internal sealed class DeploymentLocator
                     Version = ParseVersionFromDirectory(path),
                     HasCurrentMarker = File.Exists(Path.Combine(path, ".current"))
                 })
-                .OrderBy(x => x.HasCurrentMarker ? 0 : 1)  // .current 标记的排前面
-                .ThenByDescending(x => x.Version)  // 然后按版本号降序
+                .OrderBy(x => x.HasCurrentMarker ? 0 : 1)  // .current 鏍囪鐨勬帓鍓嶉潰
+                .ThenByDescending(x => x.Version)  // 鐒跺悗鎸夌増鏈彿闄嶅簭
                 .ToList();
 
             if (validInstallations.Count == 0)
@@ -79,43 +78,223 @@ 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))
+            {
+                if (TryNormalizeSavedDebugPath(savedCustomPath, out var fullSavedPath))
+                {
+                    searchedPaths.Add(fullSavedPath);
+                    if (File.Exists(fullSavedPath))
+                    {
+                        source = "debug_saved_custom_path";
+                        return fullSavedPath;
+                    }
+
+                    Logger.Warn($"Saved launcher debug host path is invalid; falling back to development paths. Path='{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 bool TryNormalizeSavedDebugPath(string savedPath, out string fullSavedPath)
+    {
+        try
+        {
+            fullSavedPath = Path.GetFullPath(savedPath);
+            return true;
+        }
+        catch (Exception ex)
+        {
+            fullSavedPath = string.Empty;
+            Logger.Warn($"Saved launcher debug host path is invalid and cannot be normalized; falling back to development paths. Path='{savedPath}'; Error='{ex.Message}'.");
+            return false;
+        }
+    }
+
+    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";
         
-        // 1. 首先查找 app-{version} 目录（生产环境）
+        // 1. 棣栧厛鏌ユ壘 app-{version} 鐩綍锛堢敓浜х幆澧冿級
         var currentDeployment = FindCurrentDeploymentDirectory();
         if (!string.IsNullOrWhiteSpace(currentDeployment))
         {
@@ -126,14 +305,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))
@@ -141,17 +318,23 @@ internal sealed class DeploymentLocator
             return inParent;
         }
 
-        // 4. 开发模式：如果启用了开发模式，优先使用保存的自定义路径
+        // 4. 寮€鍙戞ā寮忥細濡傛灉鍚敤浜嗗紑鍙戞ā寮忥紝浼樺厛浣跨敤淇濆瓨鐨勮嚜瀹氫箟璺緞
         if (Views.ErrorWindow.CheckDevModeEnabled())
         {
-            // 4.1 首先检查保存的自定义路径
             var savedCustomPath = Views.ErrorWindow.GetSavedCustomHostPath();
-            if (!string.IsNullOrWhiteSpace(savedCustomPath) && File.Exists(savedCustomPath))
+            if (!string.IsNullOrWhiteSpace(savedCustomPath))
             {
-                return savedCustomPath;
+                if (TryNormalizeSavedDebugPath(savedCustomPath, out var fullSavedPath) &&
+                    File.Exists(fullSavedPath))
+                {
+                    return fullSavedPath;
+                }
+                else if (!string.IsNullOrWhiteSpace(fullSavedPath))
+                {
+                    Logger.Warn($"Saved launcher debug host path is invalid; falling back to development paths. Path='{fullSavedPath}'.");
+                }
             }
 
-            // 4.2 扫描开发路径
             var devPath = ScanDevelopmentPaths(executable);
             if (!string.IsNullOrWhiteSpace(devPath))
             {
@@ -159,7 +342,7 @@ internal sealed class DeploymentLocator
             }
         }
 
-        // 5. 开发模式：查找主程序项目的输出目录
+        // 5. 寮€鍙戞ā寮忥細鏌ユ壘涓荤▼搴忛」鐩殑杈撳嚭鐩綍
         var devPaths = GetDevelopmentPaths(executable);
         foreach (var devPath in devPaths)
         {
@@ -173,58 +356,63 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 扫描开发路径（开发模式）
+    /// 鎵弿寮€鍙戣矾寰勶紙寮€鍙戞ā寮忥級
     /// </summary>
     private static string? ScanDevelopmentPaths(string executable)
     {
+        var solutionRoot = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", ".."));
+        
         var possiblePaths = new[]
         {
-            // 从 Launcher 项目运行
+            // 标准开发路径：解决方案根目录下的 LanMountainDesktop 项目
+            Path.Combine(solutionRoot, "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
+            Path.Combine(solutionRoot, "LanMountainDesktop", "bin", "Release", "net10.0", executable),
+            
+            // 向后兼容
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // 从解决方案根目录运行
-            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
-            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
-            
             // dev-test 目录
-            Path.Combine(AppContext.BaseDirectory, "..", "dev-test", "app-1.0.0-dev", executable),
+            Path.Combine(solutionRoot, "dev-test", "app-1.0.0-dev", executable),
         };
 
         foreach (var path in possiblePaths.Select(Path.GetFullPath).Distinct())
         {
+            Logger.Info($"Scanning development path: {path}");
             if (File.Exists(path))
             {
+                Logger.Info($"Found host at: {path}");
                 return path;
             }
         }
 
         return null;
-    }
-
+     }
+    
     /// <summary>
-    /// 获取开发环境可能的主程序路径
+    /// 鑾峰彇寮€鍙戞ā寮忥細鏌ユ壘涓荤▼搴忚経
     /// </summary>
     private static IEnumerable<string> GetDevelopmentPaths(string executable)
     {
-        // 获取 Launcher 所在目录
         var launcherDir = AppContext.BaseDirectory;
         
-        // 可能的开发目录结构
+        // 计算解决方案根目录：从 LanMountainDesktop.Launcher\bin\Debug\net10.0\ 向上4级
+        var solutionRoot = Path.GetFullPath(Path.Combine(launcherDir, "..", "..", "..", ".."));
+        
         var possiblePaths = new[]
         {
-            // 从 Launcher 项目运行：..\LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
+            // 标准开发路径：解决方案根目录下的 LanMountainDesktop 项目
+            Path.Combine(solutionRoot, "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
+            Path.Combine(solutionRoot, "LanMountainDesktop", "bin", "Release", "net10.0", executable),
+            
+            // 向后兼容：如果 Launcher 在特殊目录结构中
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // 从解决方案根目录运行：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),
-            
-            // 从 dev-test 目录运行
-            Path.Combine(launcherDir, "..", "dev-test", "app-1.0.0-dev", executable),
+            // dev-test 目录
+            Path.Combine(solutionRoot, "dev-test", "app-1.0.0-dev", executable),
         };
-
+        
         return possiblePaths.Select(Path.GetFullPath).Distinct();
     }
 
@@ -256,9 +444,8 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 清理旧版本部署，保留最近的N个版本
-    /// </summary>
-    /// <param name="minVersionsToKeep">最少保留版本数，默认3个</param>
+    /// 娓呯悊鏃х増鏈儴缃诧紝淇濈暀鏈€杩戠殑N涓増鏈?    /// </summary>
+    /// <param name="minVersionsToKeep">鏈€灏戜繚鐣欑増鏈暟锛岄粯璁?涓?/param>
     public void CleanupOldDeployments(int minVersionsToKeep = 3)
     {
         try
@@ -272,7 +459,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
@@ -287,10 +473,10 @@ internal sealed class DeploymentLocator
 
             Console.WriteLine($"[DeploymentLocator] Found {validDeployments.Count} valid deployments");
 
-            // 确定要保留的版本
+            // 纭畾瑕佷繚鐣欑殑鐗堟湰
             var versionsToKeep = new HashSet<string>();
 
-            // 1. 总是保留当前版本
+            // 1. 鎬绘槸淇濈暀褰撳墠鐗堟湰
             var currentVersion = validDeployments.FirstOrDefault(d => d.IsCurrent);
             if (currentVersion != null)
             {
@@ -298,7 +484,7 @@ internal sealed class DeploymentLocator
                 Console.WriteLine($"[DeploymentLocator] Keep current version: {currentVersion.Path}");
             }
 
-            // 2. 保留最近的N个有效版本（不包括已标记destroy的）
+            // 2. 淇濈暀鏈€杩戠殑N涓湁鏁堢増鏈紙涓嶅寘鎷凡鏍囪destroy鐨勶級
             var activeVersions = validDeployments
                 .Where(d => !d.IsDestroyed)
                 .Take(minVersionsToKeep)
@@ -310,8 +496,9 @@ internal sealed class DeploymentLocator
                 Console.WriteLine($"[DeploymentLocator] Keep recent version: {ver.Path}");
             }
 
-            // 3. 保留有快照的版本（用于回滚）
-            var snapshotDir = Path.Combine(_appRoot, ".launcher", "snapshots");
+            // 3. 淇濈暀鏈夊揩鐓х殑鐗堟湰锛堢敤浜庡洖婊氾級
+            var resolver = new DataLocationResolver(_appRoot);
+            var snapshotDir = Path.Combine(resolver.ResolveLauncherDataPath(), "snapshots");
             if (Directory.Exists(snapshotDir))
             {
                 try
@@ -334,22 +521,21 @@ internal sealed class DeploymentLocator
                         }
                         catch
                         {
-                            // 忽略快照解析错误
+                            // 蹇界暐蹇収瑙ｆ瀽閿欒
                         }
                     }
                 }
                 catch
                 {
-                    // 忽略快照目录访问错误
+                    // 蹇界暐蹇収鐩綍璁块棶閿欒
                 }
             }
 
-            // 清理不需要的版本
+            // 娓呯悊涓嶉渶瑕佺殑鐗堟湰
             foreach (var deployment in validDeployments)
             {
                 if (versionsToKeep.Contains(deployment.Path))
                 {
-                    // 保留此版本，如果之前标记了destroy则取消标记
                     if (deployment.IsDestroyed)
                     {
                         try
@@ -359,13 +545,12 @@ internal sealed class DeploymentLocator
                         }
                         catch
                         {
-                            // 忽略取消标记失败
+                            // 蹇界暐鍙栨秷鏍囪澶辫触
                         }
                     }
                     continue;
                 }
 
-                // 如果还没标记destroy的，先标记
                 if (!deployment.IsDestroyed)
                 {
                     try
@@ -375,11 +560,11 @@ internal sealed class DeploymentLocator
                     }
                     catch
                     {
-                        // 忽略标记失败
+                        // 蹇界暐鏍囪澶辫触
                     }
                 }
 
-                // 尝试删除
+                // 灏濊瘯鍒犻櫎
                 try
                 {
                     Directory.Delete(deployment.Path, recursive: true);
@@ -387,7 +572,7 @@ internal sealed class DeploymentLocator
                 }
                 catch
                 {
-                    // 忽略删除失败(可能文件被占用),下次启动再试
+                    // 蹇界暐鍒犻櫎澶辫触(鍙兘鏂囦欢琚崰鐢?,涓嬫鍚姩鍐嶈瘯
                     Console.WriteLine($"[DeploymentLocator] Failed to delete (will retry later): {deployment.Path}");
                 }
             }
@@ -395,12 +580,12 @@ internal sealed class DeploymentLocator
         catch (Exception ex)
         {
             Console.Error.WriteLine($"[DeploymentLocator] Cleanup failed: {ex.Message}");
-            // 忽略清理失败
+            // 蹇界暐娓呯悊澶辫触
         }
     }
 
     /// <summary>
-    /// 仅清理已标记为.destroy的部署（兼容旧方法）
+    /// 浠呮竻鐞嗗凡鏍囪涓?destroy鐨勯儴缃诧紙鍏煎鏃ф柟娉曪級
     /// </summary>
     [Obsolete("Use CleanupOldDeployments instead")]
     public void CleanupDestroyedDeployments()
@@ -432,37 +617,17 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 从部署目录读取版本信息
-    /// </summary>
+    /// 浠庨儴缃茬洰褰曡鍙栫増鏈俊鎭?    /// </summary>
     public AppVersionInfo GetVersionInfo()
     {
-        var deploymentDir = FindCurrentDeploymentDirectory();
-        if (!string.IsNullOrWhiteSpace(deploymentDir))
-        {
-            var versionFile = Path.Combine(deploymentDir, "version.json");
-            if (File.Exists(versionFile))
+        var executableName = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
+        var resolved = AppVersionProvider.ResolveFromPackageRoot(_appRoot, executableName);
+        return string.IsNullOrWhiteSpace(resolved.Version)
+            ? new AppVersionInfo
             {
-                try
-                {
-                    var json = File.ReadAllText(versionFile);
-                    var info = JsonSerializer.Deserialize(json, AppJsonContext.Default.AppVersionInfo);
-                    if (info is not null)
-                    {
-                        return info;
-                    }
-                }
-                catch
-                {
-                    // 忽略读取失败，回退到默认值
-                }
+                Version = GetCurrentVersion(),
+                Codename = "Administrate"
             }
-        }
-
-        // 回退：从目录名解析版本，使用默认开发代号
-        return new AppVersionInfo
-        {
-            Version = GetCurrentVersion(),
-            Codename = "Administrate" // 默认开发代号
-        };
+            : resolved;
     }
 }

LanMountainDesktop.Launcher/Services/FlexibleHostLocator.cs

@@ -560,6 +560,11 @@ namespace LanMountainDesktop.Launcher.Services;
             }
         }
 
+        if (string.Equals(source, "saved dev mode path", StringComparison.OrdinalIgnoreCase))
+        {
+            Logger.Warn($"Saved launcher debug host path is invalid; continuing host discovery. Path='{path}'.");
+        }
+
         return null;
     }
 

LanMountainDesktop.Launcher/Services/HostLaunchPlan.cs

@@ -0,0 +1,213 @@
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed record HostLaunchPlan(
+    string HostPath,
+    string PackageRoot,
+    string WorkingDirectory,
+    IReadOnlyList<string> Arguments,
+    IReadOnlyDictionary<string, string> EnvironmentVariables,
+    AppVersionInfo VersionInfo);
+
+internal static class HostLaunchPlanBuilder
+{
+    public const string DataRootOptionName = "data-root";
+
+    private static readonly string[] LauncherOnlyOptions =
+    [
+        "debug", "show-loading-details", "plugins-dir", "source", "result",
+        "app-root", DataRootOptionName,
+        LauncherIpcConstants.LauncherPidEnvVar,
+        LauncherIpcConstants.PackageRootEnvVar,
+        LauncherIpcConstants.VersionEnvVar,
+        LauncherIpcConstants.CodenameEnvVar
+    ];
+
+    public static HostLaunchPlan Build(
+        CommandContext context,
+        DeploymentLocator deploymentLocator,
+        HostResolutionResult resolution,
+        string? dataRoot = null)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        ArgumentNullException.ThrowIfNull(deploymentLocator);
+        ArgumentNullException.ThrowIfNull(resolution);
+
+        if (string.IsNullOrWhiteSpace(resolution.ResolvedHostPath))
+        {
+            throw new InvalidOperationException("Host path must be resolved before building a launch plan.");
+        }
+
+        var hostPath = Path.GetFullPath(resolution.ResolvedHostPath);
+        var packageRoot = ResolvePackageRoot(hostPath, resolution.AppRoot, resolution.ResolutionSource);
+        var versionInfo = deploymentLocator.GetVersionInfo();
+        var arguments = BuildForwardedArguments(context, packageRoot, versionInfo, dataRoot);
+        var environment = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            [LauncherIpcConstants.LauncherPidEnvVar] = Environment.ProcessId.ToString(),
+            [LauncherIpcConstants.PackageRootEnvVar] = packageRoot,
+            [LauncherIpcConstants.VersionEnvVar] = versionInfo.Version,
+            [LauncherIpcConstants.CodenameEnvVar] = versionInfo.Codename
+        };
+
+        if (!string.IsNullOrWhiteSpace(dataRoot))
+        {
+            environment["LMD_DATA_ROOT"] = dataRoot;
+        }
+
+        return new HostLaunchPlan(
+            hostPath,
+            packageRoot,
+            Directory.Exists(packageRoot)
+                ? packageRoot
+                : Path.GetDirectoryName(hostPath) ?? AppContext.BaseDirectory,
+            arguments,
+            environment,
+            versionInfo);
+    }
+
+    public static string FormatArgumentsForLog(IReadOnlyList<string> arguments)
+    {
+        return string.Join(" ", arguments.Select(QuoteArgument));
+    }
+
+    private static string ResolvePackageRoot(string hostPath, string appRoot, string? resolutionSource)
+    {
+        var fullAppRoot = string.IsNullOrWhiteSpace(appRoot)
+            ? AppContext.BaseDirectory
+            : Path.GetFullPath(appRoot);
+
+        var hostDirectory = Path.GetDirectoryName(hostPath);
+        if (hostDirectory is not null &&
+            Directory.Exists(fullAppRoot) &&
+            IsAppDeploymentDirectory(hostDirectory) &&
+            IsParentOf(fullAppRoot, hostDirectory))
+        {
+            return fullAppRoot;
+        }
+
+        if (string.Equals(resolutionSource, "published_deployment", StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(resolutionSource, "explicit_app_root_deployment", StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(resolutionSource, "legacy_fallback", StringComparison.OrdinalIgnoreCase))
+        {
+            return fullAppRoot;
+        }
+
+        return hostDirectory ?? fullAppRoot;
+    }
+
+    private static IReadOnlyList<string> BuildForwardedArguments(
+        CommandContext context,
+        string packageRoot,
+        AppVersionInfo versionInfo,
+        string? dataRoot = null)
+    {
+        var arguments = new List<string>();
+
+        for (var index = 0; index < context.RawArgs.Count; index++)
+        {
+            var arg = context.RawArgs[index];
+
+            if (index == 0 &&
+                !arg.StartsWith("--", StringComparison.Ordinal) &&
+                string.Equals(arg, context.Command, StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (index == 1 &&
+                !arg.StartsWith("--", StringComparison.Ordinal) &&
+                string.Equals(arg, context.SubCommand, StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (arg.StartsWith("--", StringComparison.Ordinal))
+            {
+                var key = arg[2..];
+                var equalsIndex = key.IndexOf('=');
+                if (equalsIndex >= 0)
+                {
+                    key = key[..equalsIndex];
+                }
+
+                if (LauncherOnlyOptions.Contains(key, StringComparer.OrdinalIgnoreCase))
+                {
+                    if (equalsIndex < 0 &&
+                        index + 1 < context.RawArgs.Count &&
+                        !context.RawArgs[index + 1].StartsWith("--", StringComparison.Ordinal))
+                    {
+                        index++;
+                    }
+
+                    continue;
+                }
+            }
+
+            arguments.Add(arg);
+        }
+
+        arguments.Add($"--{LauncherIpcConstants.LauncherPidEnvVar}={Environment.ProcessId}");
+        arguments.Add($"--{LauncherIpcConstants.PackageRootEnvVar}={packageRoot}");
+        arguments.Add($"--{LauncherIpcConstants.VersionEnvVar}={versionInfo.Version}");
+        arguments.Add($"--{LauncherIpcConstants.CodenameEnvVar}={versionInfo.Codename}");
+
+        if (!string.IsNullOrWhiteSpace(dataRoot))
+        {
+            arguments.Add($"--{DataRootOptionName}={dataRoot}");
+        }
+
+        return arguments;
+    }
+
+    private static bool IsAppDeploymentDirectory(string path)
+    {
+        var fileName = Path.GetFileName(Path.TrimEndingDirectorySeparator(path));
+        return fileName.StartsWith("app-", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static bool IsParentOf(string parent, string child)
+    {
+        var parentPath = Path.GetFullPath(parent).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        var childPath = Path.GetFullPath(child).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        if (string.Equals(parentPath, childPath, StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        return childPath.StartsWith(
+            parentPath + Path.DirectorySeparatorChar,
+            OperatingSystem.IsWindows() ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal);
+    }
+
+    private static string QuoteArgument(string value)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            return "\"\"";
+        }
+
+        if (!value.Contains('"') && !value.Contains(' ') && !value.Contains('\t'))
+        {
+            return value;
+        }
+
+        var builder = new System.Text.StringBuilder();
+        builder.Append('"');
+        foreach (var ch in value)
+        {
+            if (ch == '"')
+            {
+                builder.Append("\\\"");
+            }
+            else
+            {
+                builder.Append(ch);
+            }
+        }
+
+        builder.Append('"');
+        return builder.ToString();
+    }
+}

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/Ipc/LauncherCoordinatorIpcClient.cs

@@ -0,0 +1,111 @@
+using System.IO.Pipes;
+using System.Text;
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Services.Ipc;
+
+internal sealed class LauncherCoordinatorIpcClient
+{
+    private const int LengthPrefixSize = 4;
+    private const int MaxPayloadLength = 1024 * 1024;
+
+    public async Task<LauncherCoordinatorResponse?> SendAsync(
+        string pipeName,
+        LauncherCoordinatorRequest request,
+        TimeSpan timeout)
+    {
+        if (string.IsNullOrWhiteSpace(pipeName))
+        {
+            return null;
+        }
+
+        using var timeoutCts = new CancellationTokenSource(timeout);
+        try
+        {
+            await using var client = new NamedPipeClientStream(
+                ".",
+                pipeName,
+                PipeDirection.InOut,
+                PipeOptions.Asynchronous);
+
+            await client.ConnectAsync(timeoutCts.Token).ConfigureAwait(false);
+            await WriteRequestAsync(client, request, timeoutCts.Token).ConfigureAwait(false);
+            return await ReadResponseAsync(client, timeoutCts.Token).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            return null;
+        }
+        catch (TimeoutException)
+        {
+            return null;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to send launcher coordinator IPC request: {ex.Message}");
+            return null;
+        }
+    }
+
+    private static async Task WriteRequestAsync(
+        Stream stream,
+        LauncherCoordinatorRequest request,
+        CancellationToken cancellationToken)
+    {
+        var json = JsonSerializer.Serialize(request, AppJsonContext.Default.LauncherCoordinatorRequest);
+        var payload = Encoding.UTF8.GetBytes(json);
+        await stream.WriteAsync(BitConverter.GetBytes(payload.Length), cancellationToken).ConfigureAwait(false);
+        await stream.WriteAsync(payload, cancellationToken).ConfigureAwait(false);
+        await stream.FlushAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task<LauncherCoordinatorResponse?> ReadResponseAsync(
+        Stream stream,
+        CancellationToken cancellationToken)
+    {
+        var lengthBuffer = new byte[LengthPrefixSize];
+        if (!await ReadExactAsync(stream, lengthBuffer, cancellationToken).ConfigureAwait(false))
+        {
+            return null;
+        }
+
+        var payloadLength = BitConverter.ToInt32(lengthBuffer, 0);
+        if (payloadLength <= 0 || payloadLength > MaxPayloadLength)
+        {
+            return null;
+        }
+
+        var payload = new byte[payloadLength];
+        if (!await ReadExactAsync(stream, payload, cancellationToken).ConfigureAwait(false))
+        {
+            return null;
+        }
+
+        return JsonSerializer.Deserialize(
+            Encoding.UTF8.GetString(payload),
+            AppJsonContext.Default.LauncherCoordinatorResponse);
+    }
+
+    private static async Task<bool> ReadExactAsync(
+        Stream stream,
+        byte[] buffer,
+        CancellationToken cancellationToken)
+    {
+        var totalRead = 0;
+        while (totalRead < buffer.Length)
+        {
+            var read = await stream
+                .ReadAsync(buffer.AsMemory(totalRead, buffer.Length - totalRead), cancellationToken)
+                .ConfigureAwait(false);
+            if (read == 0)
+            {
+                return false;
+            }
+
+            totalRead += read;
+        }
+
+        return true;
+    }
+}

LanMountainDesktop.Launcher/Services/Ipc/LauncherCoordinatorIpcServer.cs

@@ -0,0 +1,235 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.IO.Pipes;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Services.Ipc;
+
+internal sealed class LauncherCoordinatorIpcServer : IDisposable
+{
+    private const int LengthPrefixSize = 4;
+    private const int MaxPayloadLength = 1024 * 1024;
+    private readonly string _pipeName;
+    private readonly Func<LauncherCoordinatorRequest, LauncherCoordinatorStatus, Task<LauncherCoordinatorResponse>> _requestHandler;
+    private readonly Action<LauncherCoordinatorStatus> _heartbeatHandler;
+    private readonly CancellationTokenSource _cts = new();
+    private readonly object _statusGate = new();
+    private LauncherCoordinatorStatus _status;
+    private Task? _listenTask;
+    private Task? _heartbeatTask;
+
+    public LauncherCoordinatorIpcServer(
+        string pipeName,
+        LauncherCoordinatorStatus initialStatus,
+        Func<LauncherCoordinatorRequest, LauncherCoordinatorStatus, Task<LauncherCoordinatorResponse>> requestHandler,
+        Action<LauncherCoordinatorStatus> heartbeatHandler)
+    {
+        _pipeName = pipeName;
+        _status = initialStatus;
+        _requestHandler = requestHandler;
+        _heartbeatHandler = heartbeatHandler;
+    }
+
+    public static string CreatePipeName()
+    {
+        var seed = $"{Environment.UserName}:{Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)}";
+        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(seed.ToLowerInvariant()));
+        return $"LanMountainDesktop_Launcher_Coordinator_{Convert.ToHexString(bytes[..8])}";
+    }
+
+    public void Start()
+    {
+        _listenTask ??= Task.Run(ListenLoopAsync);
+        _heartbeatTask ??= Task.Run(HeartbeatLoopAsync);
+    }
+
+    public LauncherCoordinatorStatus GetStatus()
+    {
+        lock (_statusGate)
+        {
+            return _status;
+        }
+    }
+
+    public void UpdateStatus(LauncherCoordinatorStatus status)
+    {
+        lock (_statusGate)
+        {
+            _status = status;
+        }
+    }
+
+    public void Dispose()
+    {
+        _cts.Cancel();
+
+        try
+        {
+            _listenTask?.Wait(TimeSpan.FromSeconds(1));
+            _heartbeatTask?.Wait(TimeSpan.FromSeconds(1));
+        }
+        catch
+        {
+        }
+
+        _cts.Dispose();
+    }
+
+    private async Task ListenLoopAsync()
+    {
+        while (!_cts.IsCancellationRequested)
+        {
+            NamedPipeServerStream? server = null;
+            try
+            {
+                server = new NamedPipeServerStream(
+                    _pipeName,
+                    PipeDirection.InOut,
+                    8,
+                    PipeTransmissionMode.Byte,
+                    PipeOptions.Asynchronous);
+
+                await server.WaitForConnectionAsync(_cts.Token).ConfigureAwait(false);
+                var connectedServer = server;
+                _ = Task.Run(() => HandleConnectionAsync(connectedServer, _cts.Token), _cts.Token);
+                server = null;
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+            catch (Exception ex)
+            {
+                Logger.Warn($"Launcher coordinator IPC listener failed: {ex.Message}");
+                try
+                {
+                    await Task.Delay(250, _cts.Token).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException)
+                {
+                    break;
+                }
+            }
+            finally
+            {
+                server?.Dispose();
+            }
+        }
+    }
+
+    private async Task HeartbeatLoopAsync()
+    {
+        while (!_cts.IsCancellationRequested)
+        {
+            try
+            {
+                _heartbeatHandler(GetStatus());
+                await Task.Delay(TimeSpan.FromSeconds(2), _cts.Token).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+            catch (Exception ex)
+            {
+                Logger.Warn($"Launcher coordinator heartbeat failed: {ex.Message}");
+            }
+        }
+    }
+
+    private async Task HandleConnectionAsync(NamedPipeServerStream server, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var request = await ReadRequestAsync(server, cancellationToken).ConfigureAwait(false);
+            var status = GetStatus();
+            var response = request is null
+                ? new LauncherCoordinatorResponse
+                {
+                    Accepted = false,
+                    Code = "invalid_request",
+                    Message = "Launcher coordinator request was invalid.",
+                    Status = status
+                }
+                : await _requestHandler(request, status).ConfigureAwait(false);
+
+            await WriteResponseAsync(server, response, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Launcher coordinator IPC request failed: {ex.Message}");
+        }
+        finally
+        {
+            try
+            {
+                server.Dispose();
+            }
+            catch
+            {
+            }
+        }
+    }
+
+    private static async Task<LauncherCoordinatorRequest?> ReadRequestAsync(
+        Stream stream,
+        CancellationToken cancellationToken)
+    {
+        var lengthBuffer = new byte[LengthPrefixSize];
+        if (!await ReadExactAsync(stream, lengthBuffer, cancellationToken).ConfigureAwait(false))
+        {
+            return null;
+        }
+
+        var payloadLength = BitConverter.ToInt32(lengthBuffer, 0);
+        if (payloadLength <= 0 || payloadLength > MaxPayloadLength)
+        {
+            return null;
+        }
+
+        var payload = new byte[payloadLength];
+        if (!await ReadExactAsync(stream, payload, cancellationToken).ConfigureAwait(false))
+        {
+            return null;
+        }
+
+        return JsonSerializer.Deserialize(
+            Encoding.UTF8.GetString(payload),
+            AppJsonContext.Default.LauncherCoordinatorRequest);
+    }
+
+    private static async Task WriteResponseAsync(
+        Stream stream,
+        LauncherCoordinatorResponse response,
+        CancellationToken cancellationToken)
+    {
+        var json = JsonSerializer.Serialize(response, AppJsonContext.Default.LauncherCoordinatorResponse);
+        var payload = Encoding.UTF8.GetBytes(json);
+        await stream.WriteAsync(BitConverter.GetBytes(payload.Length), cancellationToken).ConfigureAwait(false);
+        await stream.WriteAsync(payload, cancellationToken).ConfigureAwait(false);
+        await stream.FlushAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task<bool> ReadExactAsync(
+        Stream stream,
+        byte[] buffer,
+        CancellationToken cancellationToken)
+    {
+        var totalRead = 0;
+        while (totalRead < buffer.Length)
+        {
+            var read = await stream
+                .ReadAsync(buffer.AsMemory(totalRead, buffer.Length - totalRead), cancellationToken)
+                .ConfigureAwait(false);
+            if (read == 0)
+            {
+                return false;
+            }
+
+            totalRead += read;
+        }
+
+        return true;
+    }
+}

LanMountainDesktop.Launcher/Services/LauncherBackgroundService.cs

@@ -0,0 +1,174 @@
+using Avalonia.Media.Imaging;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+/// <summary>
+/// 启动器背景图片服务
+/// </summary>
+internal static class LauncherBackgroundService
+{
+    private const string PictureFileName = "Launcher Picture";
+    private const long MaxFileSize = 10 * 1024 * 1024; // 10MB
+    private const double WindowAspectRatio = 7.0 / 5.0; // 700:500
+    private const double AspectRatioTolerance = 0.15; // 15% 误差
+
+    private static Bitmap? _cachedBitmap;
+    private static string? _cachedPath;
+
+    /// <summary>
+    /// 背景图片信息
+    /// </summary>
+    public record BackgroundImageInfo
+    {
+        public required bool Exists { get; init; }
+        public required bool IsValid { get; init; }
+        public string? FilePath { get; init; }
+        public Bitmap? Bitmap { get; init; }
+        public int Width { get; init; }
+        public int Height { get; init; }
+        public double AspectRatio { get; init; }
+        public string? ErrorMessage { get; init; }
+    }
+
+    /// <summary>
+    /// 加载背景图片
+    /// </summary>
+    public static BackgroundImageInfo LoadBackgroundImage()
+    {
+        try
+        {
+            var resolver = new DataLocationResolver(AppContext.BaseDirectory);
+            var launcherPath = resolver.ResolveLauncherDataPath();
+
+            // 查找图片文件
+            var imagePath = FindImageFile(launcherPath);
+            if (imagePath == null)
+            {
+                return new BackgroundImageInfo
+                {
+                    Exists = false,
+                    IsValid = false,
+                    ErrorMessage = "未找到背景图片文件"
+                };
+            }
+
+            // 检查文件大小
+            var fileInfo = new FileInfo(imagePath);
+            if (fileInfo.Length > MaxFileSize)
+            {
+                return new BackgroundImageInfo
+                {
+                    Exists = true,
+                    IsValid = false,
+                    FilePath = imagePath,
+                    ErrorMessage = $"图片文件过大 ({fileInfo.Length / 1024 / 1024}MB > 10MB)"
+                };
+            }
+
+            // 使用缓存
+            if (_cachedBitmap != null && _cachedPath == imagePath)
+            {
+                return new BackgroundImageInfo
+                {
+                    Exists = true,
+                    IsValid = true,
+                    FilePath = imagePath,
+                    Bitmap = _cachedBitmap,
+                    Width = _cachedBitmap.PixelSize.Width,
+                    Height = _cachedBitmap.PixelSize.Height,
+                    AspectRatio = (double)_cachedBitmap.PixelSize.Width / _cachedBitmap.PixelSize.Height
+                };
+            }
+
+            // 加载图片
+            var bitmap = new Bitmap(imagePath);
+            var width = bitmap.PixelSize.Width;
+            var height = bitmap.PixelSize.Height;
+            var aspectRatio = (double)width / height;
+
+            // 校验比例
+            var ratioDiff = Math.Abs(aspectRatio - WindowAspectRatio) / WindowAspectRatio;
+            if (ratioDiff > AspectRatioTolerance)
+            {
+                bitmap.Dispose();
+                return new BackgroundImageInfo
+                {
+                    Exists = true,
+                    IsValid = false,
+                    FilePath = imagePath,
+                    Width = width,
+                    Height = height,
+                    AspectRatio = aspectRatio,
+                    ErrorMessage = $"图片比例不符合要求 ({aspectRatio:F2}，需要接近 {WindowAspectRatio:F2})"
+                };
+            }
+
+            // 缓存图片
+            _cachedBitmap = bitmap;
+            _cachedPath = imagePath;
+
+            Logger.Info($"[LauncherBackground] 背景图片加载成功: {imagePath} ({width}x{height}, 比例: {aspectRatio:F2})");
+
+            return new BackgroundImageInfo
+            {
+                Exists = true,
+                IsValid = true,
+                FilePath = imagePath,
+                Bitmap = bitmap,
+                Width = width,
+                Height = height,
+                AspectRatio = aspectRatio
+            };
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[LauncherBackground] 加载背景图片失败: {ex.Message}");
+            return new BackgroundImageInfo
+            {
+                Exists = false,
+                IsValid = false,
+                ErrorMessage = $"加载失败: {ex.Message}"
+            };
+        }
+    }
+
+    /// <summary>
+    /// 查找图片文件
+    /// </summary>
+    private static string? FindImageFile(string directory)
+    {
+        var extensions = new[] { ".png", ".jpg", ".jpeg", ".bmp", ".gif", ".webp" };
+
+        foreach (var ext in extensions)
+        {
+            var path = Path.Combine(directory, PictureFileName + ext);
+            if (File.Exists(path))
+            {
+                return path;
+            }
+        }
+
+        // 也尝试不带扩展名的匹配（如果文件本身就有扩展名）
+        var files = Directory.GetFiles(directory, PictureFileName + ".*");
+        foreach (var file in files)
+        {
+            var ext = Path.GetExtension(file).ToLowerInvariant();
+            if (extensions.Contains(ext))
+            {
+                return file;
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// 清除缓存
+    /// </summary>
+    public static void ClearCache()
+    {
+        _cachedBitmap?.Dispose();
+        _cachedBitmap = null;
+        _cachedPath = null;
+    }
+}

LanMountainDesktop.Launcher/Services/LauncherDebugSettingsStore.cs

@@ -0,0 +1,134 @@
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed record LauncherDebugSettings(bool DevModeEnabled, string? CustomHostPath);
+
+internal static class LauncherDebugSettingsStore
+{
+    private const string DevModeFileName = "dev-mode.flag";
+    private const string CustomHostPathFileName = "custom-host-path.txt";
+    private const string LegacyDevModeFileName = "devmode.config";
+    private const string LegacyCustomHostPathFileName = "custom-host-path.config";
+
+    internal static string? ConfigBaseDirectoryOverride { get; set; }
+
+    public static string ConfigBaseDirectory => ConfigBaseDirectoryOverride ?? ResolveConfigBaseDirectory();
+
+    public static LauncherDebugSettings Load()
+    {
+        return new LauncherDebugSettings(
+            LoadDevModeState(),
+            LoadCustomHostPath());
+    }
+
+    public static bool IsDevModeEnabled() => Load().DevModeEnabled;
+
+    public static string? GetSavedCustomHostPath() => Load().CustomHostPath;
+
+    public static void Save(LauncherDebugSettings settings)
+    {
+        try
+        {
+            Directory.CreateDirectory(ConfigBaseDirectory);
+            File.WriteAllText(GetPath(DevModeFileName), settings.DevModeEnabled.ToString());
+            File.WriteAllText(GetPath(CustomHostPathFileName), settings.CustomHostPath ?? string.Empty);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to save launcher debug settings: {ex.Message}");
+        }
+    }
+
+    public static void SaveDevModeState(bool enabled)
+    {
+        var current = Load();
+        Save(current with { DevModeEnabled = enabled });
+    }
+
+    public static void SaveCustomHostPath(string? customHostPath)
+    {
+        var current = Load();
+        Save(current with { CustomHostPath = customHostPath });
+    }
+
+    private static bool LoadDevModeState()
+    {
+        var newValue = TryReadText(GetPath(DevModeFileName));
+        if (!string.IsNullOrWhiteSpace(newValue))
+        {
+            return TryParseDevMode(newValue);
+        }
+
+        var legacyValue = TryReadText(GetPath(LegacyDevModeFileName));
+        return !string.IsNullOrWhiteSpace(legacyValue) && TryParseDevMode(legacyValue);
+    }
+
+    private static string? LoadCustomHostPath()
+    {
+        var newValue = TryReadText(GetPath(CustomHostPathFileName));
+        if (!string.IsNullOrWhiteSpace(newValue))
+        {
+            return newValue.Trim();
+        }
+
+        var legacyValue = TryReadText(GetPath(LegacyCustomHostPathFileName));
+        return string.IsNullOrWhiteSpace(legacyValue) ? null : legacyValue.Trim();
+    }
+
+    private static bool TryParseDevMode(string value)
+    {
+        var normalized = value.Trim();
+        return normalized == "1" ||
+               normalized.Equals("true", StringComparison.OrdinalIgnoreCase) ||
+               normalized.Equals("yes", StringComparison.OrdinalIgnoreCase) ||
+               normalized.Equals("on", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static string? TryReadText(string path)
+    {
+        try
+        {
+            return File.Exists(path) ? File.ReadAllText(path) : null;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to read launcher debug setting '{path}': {ex.Message}");
+            return null;
+        }
+    }
+
+    private static string GetPath(string fileName) => Path.Combine(ConfigBaseDirectory, fileName);
+
+    private static string ResolveConfigBaseDirectory()
+    {
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(CommandContext.FromArgs([]));
+            var resolver = new DataLocationResolver(appRoot);
+            return resolver.ResolveLauncherDataPath();
+        }
+        catch
+        {
+        }
+
+        try
+        {
+            var appData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+            if (!string.IsNullOrWhiteSpace(appData))
+            {
+                return Path.Combine(appData, "LanMountainDesktop", "Launcher");
+            }
+        }
+        catch
+        {
+        }
+
+        try
+        {
+            return Path.Combine(AppContext.BaseDirectory, "Launcher");
+        }
+        catch
+        {
+            return Path.Combine(Directory.GetCurrentDirectory(), "Launcher");
+        }
+    }
+}

LanMountainDesktop.Launcher/Services/LauncherExecutionContext.cs

@@ -0,0 +1,30 @@
+using System.Security.Principal;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal static class LauncherExecutionContext
+{
+    public static LauncherExecutionSnapshot Capture()
+    {
+        var userName = Environment.UserName ?? string.Empty;
+        if (!OperatingSystem.IsWindows())
+        {
+            return new LauncherExecutionSnapshot(false, userName, null);
+        }
+
+        try
+        {
+            using var identity = WindowsIdentity.GetCurrent();
+            var principal = new WindowsPrincipal(identity);
+            return new LauncherExecutionSnapshot(
+                principal.IsInRole(WindowsBuiltInRole.Administrator),
+                userName,
+                identity.User?.Value);
+        }
+        catch
+        {
+            return new LauncherExecutionSnapshot(false, userName, null);
+        }
+    }
+}

LanMountainDesktop.Launcher/Services/LegacyVersionDetector.cs

@@ -262,6 +262,9 @@ internal sealed class LegacyVersionDetector
                 var parts = info.UninstallCommand.Split(new[] { ' ' }, 2);
                 var fileName = parts[0].Trim('"');
                 var arguments = parts.Length > 1 ? parts[1] : "";
+                Logger.Info(
+                    $"Opening legacy uninstall interface with elevation reason 'legacy_uninstall'. " +
+                    $"InstallPath='{info.InstallPath}'; Version='{info.Version}'.");
 
                 Process.Start(new ProcessStartInfo
                 {

LanMountainDesktop.Launcher/Services/Logger.cs

@@ -53,12 +53,22 @@ internal static class Logger
     /// </summary>
     private static string? GetLogDirectory()
     {
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(CommandContext.FromArgs([]));
+            var resolver = new DataLocationResolver(appRoot);
+            return resolver.ResolveLauncherLogsPath();
+        }
+        catch
+        {
+        }
+
         try
         {
             var appData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
             if (!string.IsNullOrEmpty(appData))
             {
-                return Path.Combine(appData, "LanMountainDesktop", ".launcher", "logs");
+                return Path.Combine(appData, "LanMountainDesktop", "Launcher", "logs");
             }
         }
         catch
@@ -68,7 +78,7 @@ internal static class Logger
         try
         {
             var launcherDir = AppContext.BaseDirectory;
-            return Path.Combine(launcherDir, ".launcher", "logs");
+            return Path.Combine(launcherDir, "Launcher", "logs");
         }
         catch
         {

LanMountainDesktop.Launcher/Services/OobeStateService.cs

@@ -1,104 +1,246 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
 namespace LanMountainDesktop.Launcher.Services;
 
 internal sealed class OobeStateService
 {
-    private readonly string _markerPath;
+    private const int CurrentSchemaVersion = 1;
 
-    public OobeStateService(string appRoot)
+    private readonly string _stateDirectory;
+    private readonly string _statePath;
+    private readonly string _legacyStatePath;
+    private readonly string _legacyMarkerPath;
+    private readonly LauncherExecutionSnapshot _executionSnapshot;
+
+    public OobeStateService(
+        string appRoot,
+        string? stateRootOverride = null,
+        LauncherExecutionSnapshot? executionSnapshot = null)
     {
-        // 优先使用 LocalApplicationData（用户目录，普通用户一定有权限）
-        string? stateDir = null;
-        Exception? lastException = null;
+        _ = Path.GetFullPath(appRoot);
+        _executionSnapshot = executionSnapshot ?? LauncherExecutionContext.Capture();
 
-        // 策略1: LocalApplicationData（首选，用户目录，普通用户一定有写权限）
-        try
-        {
-            var appDataDir = Path.Combine(
-                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
-                "LanMountainDesktop");
-            stateDir = Path.Combine(appDataDir, ".launcher", "state");
-            Directory.CreateDirectory(stateDir);
-            Console.WriteLine($"[OobeStateService] Using LocalApplicationData: {stateDir}");
-        }
-        catch (Exception ex)
-        {
-            lastException = ex;
-            Console.Error.WriteLine($"[OobeStateService] LocalApplicationData failed: {ex.Message}");
-            stateDir = null;
-        }
+        var stateRoot = string.IsNullOrWhiteSpace(stateRootOverride)
+            ? ResolveStateRoot(appRoot)
+            : Path.GetFullPath(stateRootOverride);
+        _stateDirectory = Path.Combine(stateRoot, "Launcher", "state");
+        _statePath = Path.Combine(_stateDirectory, "oobe-state.json");
 
-        // 策略2: 如果LocalApplicationData不行，使用用户的临时目录
-        if (stateDir == null)
-        {
-            try
-            {
-                var tempDir = Path.Combine(Path.GetTempPath(), "LanMountainDesktop", ".launcher", "state");
-                Directory.CreateDirectory(tempDir);
-                stateDir = tempDir;
-                Console.WriteLine($"[OobeStateService] Using TempPath: {stateDir}");
-            }
-            catch (Exception ex)
-            {
-                lastException = ex;
-                Console.Error.WriteLine($"[OobeStateService] TempPath failed: {ex.Message}");
-                stateDir = null;
-            }
-        }
-
-        // 策略3: 最后的兜底：使用当前用户的应用程序数据目录（和Launcher同目录
-        if (stateDir == null)
-        {
-            try
-            {
-                var launcherDir = AppContext.BaseDirectory;
-                stateDir = Path.Combine(launcherDir, ".launcher", "state");
-                Directory.CreateDirectory(stateDir);
-                Console.WriteLine($"[OobeStateService] Using Launcher directory: {stateDir}");
-            }
-            catch (Exception ex)
-            {
-                lastException = ex;
-                Console.Error.WriteLine($"[OobeStateService] All strategies failed! Last error: {ex.Message}");
-                // 如果所有策略都失败，抛出异常让上层处理
-                throw new InvalidOperationException("无法创建 OOBE 状态存储目录失败", lastException);
-            }
-        }
-
-        _markerPath = Path.Combine(stateDir, "first_run_completed");
-        Console.WriteLine($"[OobeStateService] Initialized successfully, marker path: {_markerPath}");
+        var legacyRoot = string.IsNullOrWhiteSpace(stateRootOverride)
+            ? Path.GetFullPath(appRoot)
+            : Path.GetFullPath(stateRootOverride);
+        var legacyStateDirectory = Path.Combine(legacyRoot, ".launcher", "state");
+        _legacyStatePath = Path.Combine(legacyStateDirectory, "oobe-state.json");
+        _legacyMarkerPath = Path.Combine(legacyStateDirectory, "first_run_completed");
     }
 
-    public bool IsFirstRun()
+    public OobeLaunchDecision Evaluate(CommandContext context)
+    {
+        var decision = EvaluateCore(context);
+        Logger.Info(
+            $"OOBE decision evaluated. LaunchSource='{decision.LaunchSource}'; Status='{decision.Status}'; " +
+            $"ShouldShow={decision.ShouldShowOobe}; IsElevated={decision.IsElevated}; " +
+            $"StatePath='{decision.StatePath}'; SuppressionReason='{decision.SuppressionReason}'; " +
+            $"ResultCode='{decision.ResultCode}'; UserSid='{decision.UserSid ?? string.Empty}'.");
+        return decision;
+    }
+
+    public OobeCompletionResult MarkCompleted(CommandContext context)
     {
         try
         {
-            return !File.Exists(_markerPath);
+            Directory.CreateDirectory(_stateDirectory);
+            var payload = new OobeStateFile
+            {
+                SchemaVersion = CurrentSchemaVersion,
+                CompletedAtUtc = DateTimeOffset.UtcNow.ToString("O"),
+                UserName = _executionSnapshot.UserName,
+                UserSid = _executionSnapshot.UserSid,
+                LaunchSource = context.LaunchSource
+            };
+
+            var tempPath = Path.Combine(_stateDirectory, $"oobe-state.{Guid.NewGuid():N}.tmp");
+            var json = JsonSerializer.Serialize(payload, AppJsonContext.Default.OobeStateFile);
+            File.WriteAllText(tempPath, json);
+            File.Move(tempPath, _statePath, overwrite: true);
+            TryDeleteLegacyMarker();
+
+            Logger.Info(
+                $"OOBE completion persisted. LaunchSource='{context.LaunchSource}'; StatePath='{_statePath}'; " +
+                $"UserSid='{_executionSnapshot.UserSid ?? string.Empty}'.");
+
+            return new OobeCompletionResult
+            {
+                Success = true,
+                ResultCode = "ok"
+            };
         }
         catch (Exception ex)
         {
-            Console.Error.WriteLine($"[OobeStateService] Failed to check first run: {ex.Message}");
-            // 如果无法检查，默认视为首次运行，确保OOBE能显示
-            return true;
+            Logger.Warn(
+                $"Failed to persist OOBE state. LaunchSource='{context.LaunchSource}'; StatePath='{_statePath}'; " +
+                $"Error='{ex.Message}'.");
+            return new OobeCompletionResult
+            {
+                Success = false,
+                ResultCode = "oobe_state_unavailable",
+                ErrorMessage = ex.Message
+            };
         }
     }
 
-    public void MarkCompleted()
+    private OobeLaunchDecision EvaluateCore(CommandContext context)
     {
+        if (string.Equals(context.LaunchSource, "debug-preview", StringComparison.OrdinalIgnoreCase))
+        {
+            return BuildSuppressedDecision(context, "debug_preview", "oobe_suppressed_debug_preview");
+        }
+
+        if (context.IsMaintenanceCommand)
+        {
+            return BuildSuppressedDecision(context, "maintenance", "oobe_suppressed_maintenance");
+        }
+
         try
         {
-            var dir = Path.GetDirectoryName(_markerPath);
-            if (!string.IsNullOrWhiteSpace(dir))
+            var migratedLegacyMarker = false;
+            if (File.Exists(_statePath))
             {
-                Directory.CreateDirectory(dir);
+                return EvaluateStateFile(context, _statePath, migratedLegacyState: false);
             }
 
-            File.WriteAllText(_markerPath, DateTimeOffset.UtcNow.ToString("O"));
-            Console.WriteLine("[OobeStateService] Marked first run as completed");
+            if (File.Exists(_legacyStatePath))
+            {
+                return EvaluateStateFile(context, _legacyStatePath, migratedLegacyState: false);
+            }
+
+            if (File.Exists(_legacyMarkerPath))
+            {
+                migratedLegacyMarker = TryMigrateLegacyMarker(context);
+                return BuildDecision(context, OobeStateStatus.Completed, shouldShowOobe: false, usedLegacyMarker: true, migratedLegacyMarker: migratedLegacyMarker);
+            }
+
+            if (_executionSnapshot.IsElevated)
+            {
+                return BuildSuppressedDecision(context, "elevated", "oobe_suppressed_elevated");
+            }
+
+            if (string.Equals(context.LaunchSource, "postinstall", StringComparison.OrdinalIgnoreCase))
+            {
+                return BuildDecision(context, OobeStateStatus.FirstRun, shouldShowOobe: true);
+            }
+
+            return BuildDecision(context, OobeStateStatus.FirstRun, shouldShowOobe: true);
         }
         catch (Exception ex)
         {
-            Console.Error.WriteLine($"[OobeStateService] Failed to mark completed: {ex.Message}");
-            // 如果无法写入也没关系，下次启动还会显示OOBE
+            return BuildUnavailableDecision(context, ex.Message);
+        }
+    }
+
+    private bool TryMigrateLegacyMarker(CommandContext context)
+    {
+        var result = MarkCompleted(context);
+        return result.Success;
+    }
+
+    private OobeLaunchDecision EvaluateStateFile(CommandContext context, string statePath, bool migratedLegacyState)
+    {
+        using var stream = File.OpenRead(statePath);
+        var state = JsonSerializer.Deserialize(stream, AppJsonContext.Default.OobeStateFile);
+        if (state is null || state.SchemaVersion <= 0 || string.IsNullOrWhiteSpace(state.CompletedAtUtc))
+        {
+            return BuildUnavailableDecision(context, "OOBE state file is invalid.");
+        }
+
+        return BuildDecision(context, OobeStateStatus.Completed, shouldShowOobe: false, migratedLegacyMarker: migratedLegacyState);
+    }
+
+    private void TryDeleteLegacyMarker()
+    {
+        try
+        {
+            if (File.Exists(_legacyMarkerPath))
+            {
+                File.Delete(_legacyMarkerPath);
+            }
+        }
+        catch
+        {
+        }
+    }
+
+    private OobeLaunchDecision BuildDecision(
+        CommandContext context,
+        OobeStateStatus status,
+        bool shouldShowOobe,
+        bool usedLegacyMarker = false,
+        bool migratedLegacyMarker = false)
+    {
+        return new OobeLaunchDecision
+        {
+            Status = status,
+            ShouldShowOobe = shouldShowOobe,
+            StatePath = _statePath,
+            LaunchSource = context.LaunchSource,
+            IsElevated = _executionSnapshot.IsElevated,
+            UserName = _executionSnapshot.UserName,
+            UserSid = _executionSnapshot.UserSid,
+            UsedLegacyMarker = usedLegacyMarker,
+            MigratedLegacyMarker = migratedLegacyMarker,
+            ResultCode = "ok"
+        };
+    }
+
+    private OobeLaunchDecision BuildSuppressedDecision(CommandContext context, string reason, string resultCode)
+    {
+        return new OobeLaunchDecision
+        {
+            Status = OobeStateStatus.Suppressed,
+            ShouldShowOobe = false,
+            StatePath = _statePath,
+            LaunchSource = context.LaunchSource,
+            IsElevated = _executionSnapshot.IsElevated,
+            UserName = _executionSnapshot.UserName,
+            UserSid = _executionSnapshot.UserSid,
+            SuppressionReason = reason,
+            ResultCode = resultCode
+        };
+    }
+
+    private OobeLaunchDecision BuildUnavailableDecision(CommandContext context, string errorMessage)
+    {
+        return new OobeLaunchDecision
+        {
+            Status = OobeStateStatus.Unavailable,
+            ShouldShowOobe = false,
+            StatePath = _statePath,
+            LaunchSource = context.LaunchSource,
+            IsElevated = _executionSnapshot.IsElevated,
+            UserName = _executionSnapshot.UserName,
+            UserSid = _executionSnapshot.UserSid,
+            ResultCode = "oobe_state_unavailable",
+            ErrorMessage = errorMessage
+        };
+    }
+
+    private static string ResolveStateRoot(string appRoot)
+    {
+        try
+        {
+            var resolver = new DataLocationResolver(appRoot);
+            return resolver.ResolveDataRoot();
+        }
+        catch
+        {
+            var appData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+            if (string.IsNullOrWhiteSpace(appData))
+            {
+                throw new InvalidOperationException("LocalApplicationData is unavailable.");
+            }
+
+            return Path.Combine(appData, "LanMountainDesktop");
         }
     }
 }

LanMountainDesktop.Launcher/Services/PluginInstallerService.cs

@@ -30,6 +30,11 @@ internal sealed class PluginInstallerService
             throw new FileNotFoundException($"Plugin package '{fullSourcePath}' was not found.", fullSourcePath);
         }
 
+        if (TryBuildElevationRequiredResult(fullPluginsDirectory) is { } elevationRequiredResult)
+        {
+            return elevationRequiredResult;
+        }
+
         var manifest = ReadManifestFromPackage(fullSourcePath);
         Directory.CreateDirectory(fullPluginsDirectory);
         var destinationPath = Path.Combine(fullPluginsDirectory, BuildInstalledPackageFileName(manifest.Id));
@@ -51,6 +56,61 @@ internal sealed class PluginInstallerService
         };
     }
 
+    private static LauncherResult? TryBuildElevationRequiredResult(string pluginsDirectory)
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return null;
+        }
+
+        string? allowedRoot = null;
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(CommandContext.FromArgs([]));
+            var resolver = new DataLocationResolver(appRoot);
+            allowedRoot = EnsureTrailingSeparator(resolver.ResolveDataRoot());
+        }
+        catch
+        {
+        }
+
+        if (string.IsNullOrWhiteSpace(allowedRoot))
+        {
+            var localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+            if (string.IsNullOrWhiteSpace(localAppData))
+            {
+                return null;
+            }
+
+            allowedRoot = EnsureTrailingSeparator(Path.Combine(Path.GetFullPath(localAppData), "LanMountainDesktop"));
+        }
+
+        var normalizedPluginsDirectory = EnsureTrailingSeparator(Path.GetFullPath(pluginsDirectory));
+        if (normalizedPluginsDirectory.StartsWith(allowedRoot, StringComparison.OrdinalIgnoreCase))
+        {
+            return null;
+        }
+
+        Logger.Warn(
+            $"Plugin installation requires explicit elevation. Reason='plugin_requires_elevation'; " +
+            $"PluginsDirectory='{pluginsDirectory}'; AllowedRoot='{allowedRoot}'.");
+
+        return new LauncherResult
+        {
+            Success = false,
+            Stage = "plugin.install",
+            Code = "plugin_elevation_required",
+            Message = "Plugin installation outside the current user's LanMountainDesktop data directory requires explicit elevation.",
+            ErrorMessage = "Plugin installation target is outside the current user's LanMountainDesktop data directory.",
+            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["pluginsDirectory"] = pluginsDirectory,
+                ["allowedRoot"] = allowedRoot,
+                ["elevationReason"] = "outside_user_scope"
+            }
+        };
+    }
+
     public PluginManifest ReadManifestFromPackage(string packagePath)
     {
         using var archive = ZipFile.OpenRead(packagePath);

LanMountainDesktop.Launcher/Services/PrivacyAgreementService.cs

@@ -0,0 +1,245 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+/// <summary>
+/// 隐私协议同意状态管理服务（带防篡改保护）
+/// </summary>
+internal sealed class PrivacyAgreementService
+{
+    private readonly string _storagePath;
+    private readonly string _secretKey;
+    private const string ConfigFileName = "privacy-agreement.state.json";
+    private const string CurrentAgreementVersion = "1.0";
+
+    public PrivacyAgreementService(string launcherDataPath)
+    {
+        _storagePath = Path.Combine(launcherDataPath, ConfigFileName);
+        // 使用机器特定信息生成密钥，增加篡改难度
+        _secretKey = GenerateMachineSpecificKey();
+    }
+
+    /// <summary>
+    /// 检查用户是否已同意隐私协议
+    /// </summary>
+    public bool HasUserAgreed()
+    {
+        try
+        {
+            if (!File.Exists(_storagePath))
+            {
+                Logger.Info("[PrivacyAgreementService] 未找到隐私协议同意状态文件");
+                return false;
+            }
+
+            var json = File.ReadAllText(_storagePath);
+            var state = JsonSerializer.Deserialize(json, AppJsonContext.Default.PrivacyAgreementState);
+
+            if (state == null)
+            {
+                Logger.Warn("[PrivacyAgreementService] 无法解析隐私协议状态文件");
+                return false;
+            }
+
+            // 验证数据完整性
+            if (!VerifyIntegrity(state))
+            {
+                Logger.Warn("[PrivacyAgreementService] 隐私协议状态文件已被篡改！");
+                // 删除被篡改的文件
+                try
+                {
+                    File.Delete(_storagePath);
+                }
+                catch (Exception ex)
+                {
+                    Logger.Warn($"[PrivacyAgreementService] 删除被篡改文件失败: {ex.Message}");
+                }
+                return false;
+            }
+
+            // 检查协议版本是否匹配
+            if (state.AgreementVersion != CurrentAgreementVersion)
+            {
+                Logger.Info($"[PrivacyAgreementService] 隐私协议版本已更新: {state.AgreementVersion} -> {CurrentAgreementVersion}");
+                return false;
+            }
+
+            Logger.Info($"[PrivacyAgreementService] 用户已于 {state.AgreedAtUtc:yyyy-MM-dd HH:mm:ss} UTC 同意隐私协议");
+            return state.IsAgreed;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[PrivacyAgreementService] 检查同意状态时出错: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// 保存用户同意隐私协议的状态
+    /// </summary>
+    public bool SaveAgreement(bool isAgreed, string userId, string deviceId)
+    {
+        try
+        {
+            // 确保目录存在
+            var directory = Path.GetDirectoryName(_storagePath);
+            if (!string.IsNullOrEmpty(directory) && !Directory.Exists(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            // 生成随机盐值
+            var salt = GenerateRandomSalt();
+
+            var state = new PrivacyAgreementState
+            {
+                IsAgreed = isAgreed,
+                AgreedAtUtc = DateTime.UtcNow,
+                AgreementVersion = CurrentAgreementVersion,
+                UserId = userId,
+                DeviceId = deviceId,
+                Salt = salt
+            };
+
+            // 计算完整性哈希
+            state.IntegrityHash = CalculateIntegrityHash(state);
+
+            // 保存到文件
+            var json = JsonSerializer.Serialize(state, AppJsonContext.Default.PrivacyAgreementState);
+            File.WriteAllText(_storagePath, json);
+
+            Logger.Info($"[PrivacyAgreementService] 隐私协议同意状态已保存: IsAgreed={isAgreed}");
+            return true;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[PrivacyAgreementService] 保存同意状态失败: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// 获取当前的协议版本
+    /// </summary>
+    public string GetCurrentAgreementVersion() => CurrentAgreementVersion;
+
+    /// <summary>
+    /// 清除同意状态（用于测试或重置）
+    /// </summary>
+    public bool ClearAgreement()
+    {
+        try
+        {
+            if (File.Exists(_storagePath))
+            {
+                File.Delete(_storagePath);
+                Logger.Info("[PrivacyAgreementService] 隐私协议同意状态已清除");
+            }
+            return true;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[PrivacyAgreementService] 清除同意状态失败: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// 生成机器特定的密钥
+    /// </summary>
+    private string GenerateMachineSpecificKey()
+    {
+        try
+        {
+            // 组合多个机器特定信息生成密钥
+            var machineName = Environment.MachineName;
+            var userName = Environment.UserName;
+            var osVersion = Environment.OSVersion.Version.ToString();
+            var processorCount = Environment.ProcessorCount.ToString();
+
+            // 使用硬件信息（如果可用）
+            var hardwareId = GetHardwareIdentifier();
+
+            var keyData = $"{machineName}:{userName}:{osVersion}:{processorCount}:{hardwareId}:LanMountainDesktop";
+
+            // 使用 SHA-256 生成固定长度的密钥
+            using var sha256 = SHA256.Create();
+            var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(keyData));
+            return Convert.ToHexString(hash);
+        }
+        catch
+        {
+            // 如果无法获取机器信息，使用备用密钥
+            return "LanMountainDesktop-Privacy-Agreement-Fallback-Key-2026";
+        }
+    }
+
+    /// <summary>
+    /// 获取硬件标识符
+    /// </summary>
+    private string GetHardwareIdentifier()
+    {
+        try
+        {
+            // 尝试使用系统目录创建时间作为硬件标识的一部分
+            var systemDir = Environment.SystemDirectory;
+            var dirInfo = new DirectoryInfo(systemDir);
+            return dirInfo.CreationTimeUtc.ToString("yyyyMMddHHmmss");
+        }
+        catch
+        {
+            return "Unknown";
+        }
+    }
+
+    /// <summary>
+    /// 生成随机盐值
+    /// </summary>
+    private string GenerateRandomSalt()
+    {
+        var saltBytes = new byte[32];
+        using var rng = RandomNumberGenerator.Create();
+        rng.GetBytes(saltBytes);
+        return Convert.ToHexString(saltBytes);
+    }
+
+    /// <summary>
+    /// 计算完整性哈希（HMAC-SHA256）
+    /// </summary>
+    private string CalculateIntegrityHash(PrivacyAgreementState state)
+    {
+        // 构建需要哈希的数据字符串
+        var dataToHash = $"{state.IsAgreed}:{state.AgreedAtUtc:o}:{state.AgreementVersion}:{state.UserId}:{state.DeviceId}:{state.Salt}";
+
+        // 使用 HMAC-SHA256 计算哈希
+        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(_secretKey));
+        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(dataToHash));
+        return Convert.ToHexString(hash);
+    }
+
+    /// <summary>
+    /// 验证数据完整性
+    /// </summary>
+    private bool VerifyIntegrity(PrivacyAgreementState state)
+    {
+        try
+        {
+            if (string.IsNullOrEmpty(state.IntegrityHash) || string.IsNullOrEmpty(state.Salt))
+            {
+                return false;
+            }
+
+            var expectedHash = CalculateIntegrityHash(state);
+            return CryptographicOperations.FixedTimeEquals(
+                Encoding.UTF8.GetBytes(state.IntegrityHash),
+                Encoding.UTF8.GetBytes(expectedHash));
+        }
+        catch
+        {
+            return false;
+        }
+    }
+}

LanMountainDesktop.Launcher/Services/StartupAttemptRegistry.cs

@@ -0,0 +1,550 @@
+using System.Diagnostics;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class StartupAttemptRegistry
+{
+    private static readonly TimeSpan CoordinatorHeartbeatTimeout = TimeSpan.FromSeconds(10);
+
+    private readonly string _statePath;
+    private readonly string _mutexName;
+    private string? _ownedAttemptId;
+
+    public StartupAttemptRegistry()
+        : this(ResolveDefaultStatePath())
+    {
+    }
+
+    private static string ResolveDefaultStatePath()
+    {
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(CommandContext.FromArgs([]));
+            var resolver = new DataLocationResolver(appRoot);
+            return Path.Combine(resolver.ResolveLauncherStatePath(), "startup-attempt.json");
+        }
+        catch
+        {
+            return Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                "LanMountainDesktop",
+                "Launcher",
+                "state",
+                "startup-attempt.json");
+        }
+    }
+
+    internal StartupAttemptRegistry(string statePath)
+    {
+        _statePath = statePath;
+        _mutexName = $"LanMountainDesktop.Launcher.StartupAttempt.{ComputePathHash(statePath)}";
+    }
+
+    public StartupAttemptRecord StartOwnedAttempt(
+        int hostPid,
+        string launchSource,
+        string successPolicy,
+        StartupStage stage,
+        string? message)
+    {
+        var record = new StartupAttemptRecord
+        {
+            AttemptId = Guid.NewGuid().ToString("N"),
+            HostPid = hostPid,
+            CoordinatorPid = Environment.ProcessId,
+            LaunchSource = launchSource,
+            SuccessPolicy = successPolicy,
+            LastObservedStage = stage,
+            LastObservedMessage = message ?? string.Empty,
+            StartedAtUtc = DateTimeOffset.UtcNow,
+            UpdatedAtUtc = DateTimeOffset.UtcNow,
+            HeartbeatAtUtc = DateTimeOffset.UtcNow,
+            State = StartupAttemptState.Pending
+        };
+
+        ExecuteWithLock(() =>
+        {
+            SaveUnsafe(record);
+            _ownedAttemptId = record.AttemptId;
+        });
+
+        return Clone(record);
+    }
+
+    public bool TryReserveCoordinator(
+        string launchSource,
+        string successPolicy,
+        string coordinatorPipeName,
+        out StartupAttemptRecord reservedAttempt,
+        out StartupAttemptRecord? activeCoordinatorAttempt)
+    {
+        StartupAttemptRecord? reserved = null;
+        StartupAttemptRecord? active = null;
+
+        ExecuteWithLock(() =>
+        {
+            var existing = LoadUnsafe();
+            if (existing is not null && IsCoordinatorLive(existing))
+            {
+                active = Clone(existing);
+                return;
+            }
+
+            if (existing is not null && IsRecoverableCoordinatorAttempt(existing))
+            {
+                existing.CoordinatorPid = Environment.ProcessId;
+                existing.CoordinatorPipeName = coordinatorPipeName;
+                existing.HeartbeatAtUtc = DateTimeOffset.UtcNow;
+                existing.UpdatedAtUtc = DateTimeOffset.UtcNow;
+                if (existing.HostPid <= 0)
+                {
+                    existing.ReservedBeforeHostStart = true;
+                }
+
+                if (existing.State == StartupAttemptState.DetachedWaiting)
+                {
+                    existing.State = StartupAttemptState.SoftTimeout;
+                }
+
+                _ownedAttemptId = existing.AttemptId;
+                SaveUnsafe(existing);
+                reserved = Clone(existing);
+                return;
+            }
+
+            var now = DateTimeOffset.UtcNow;
+            var record = new StartupAttemptRecord
+            {
+                AttemptId = Guid.NewGuid().ToString("N"),
+                HostPid = 0,
+                CoordinatorPid = Environment.ProcessId,
+                CoordinatorPipeName = coordinatorPipeName,
+                LaunchSource = launchSource,
+                SuccessPolicy = successPolicy,
+                LastObservedStage = StartupStage.Initializing,
+                LastObservedMessage = "Launcher coordinator reserved startup ownership.",
+                StartedAtUtc = now,
+                UpdatedAtUtc = now,
+                HeartbeatAtUtc = now,
+                ReservedBeforeHostStart = true,
+                State = StartupAttemptState.Pending
+            };
+
+            _ownedAttemptId = record.AttemptId;
+            SaveUnsafe(record);
+            reserved = Clone(record);
+        });
+
+        reservedAttempt = reserved ?? new StartupAttemptRecord();
+        activeCoordinatorAttempt = active;
+        return reserved is not null;
+    }
+
+    public StartupAttemptRecord? GetOwnedAttempt()
+    {
+        StartupAttemptRecord? result = null;
+        if (string.IsNullOrWhiteSpace(_ownedAttemptId))
+        {
+            return null;
+        }
+
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is not null && string.Equals(record.AttemptId, _ownedAttemptId, StringComparison.Ordinal))
+            {
+                result = Clone(record);
+            }
+        });
+
+        return result;
+    }
+
+    public StartupAttemptRecord? TryGetLiveCoordinatorAttempt()
+    {
+        StartupAttemptRecord? result = null;
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is not null && IsCoordinatorLive(record))
+            {
+                result = Clone(record);
+            }
+        });
+
+        return result;
+    }
+
+    public StartupAttemptRecord? TryGetLatestAttempt()
+    {
+        StartupAttemptRecord? result = null;
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is not null)
+            {
+                result = Clone(record);
+            }
+        });
+
+        return result;
+    }
+
+    public StartupAttemptRecord AssignOwnedHostProcess(
+        int hostPid,
+        StartupStage stage,
+        string? message)
+    {
+        StartupAttemptRecord? result = null;
+        UpdateOwned(record =>
+        {
+            record.HostPid = hostPid;
+            record.LastObservedStage = stage;
+            record.LastObservedMessage = message ?? record.LastObservedMessage;
+            record.ReservedBeforeHostStart = false;
+            result = Clone(record);
+        });
+
+        return result ?? StartOwnedAttempt(
+            hostPid,
+            string.Empty,
+            string.Empty,
+            stage,
+            message);
+    }
+
+    public bool AdoptAttempt(string attemptId)
+    {
+        if (string.IsNullOrWhiteSpace(attemptId))
+        {
+            return false;
+        }
+
+        var adopted = false;
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is null || !string.Equals(record.AttemptId, attemptId, StringComparison.Ordinal))
+            {
+                return;
+            }
+
+            if (!IsAttachable(record))
+            {
+                return;
+            }
+
+            _ownedAttemptId = record.AttemptId;
+            if (record.State == StartupAttemptState.DetachedWaiting)
+            {
+                record.State = StartupAttemptState.SoftTimeout;
+            }
+
+            record.UpdatedAtUtc = DateTimeOffset.UtcNow;
+            SaveUnsafe(record);
+            adopted = true;
+        });
+
+        return adopted;
+    }
+
+    public StartupAttemptRecord? TryGetAttachableAttempt(string launchSource, string successPolicy)
+    {
+        StartupAttemptRecord? result = null;
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is null ||
+                !IsAttachable(record) ||
+                !string.Equals(record.LaunchSource, launchSource, StringComparison.OrdinalIgnoreCase) ||
+                !string.Equals(record.SuccessPolicy, successPolicy, StringComparison.OrdinalIgnoreCase))
+            {
+                return;
+            }
+
+            result = Clone(record);
+        });
+
+        return result;
+    }
+
+    public void MarkOwnedIpcConnected()
+    {
+        UpdateOwned(record =>
+        {
+            record.IpcConnected = true;
+            record.PublicIpcConnected = true;
+        });
+    }
+
+    public void UpdateOwnedStage(StartupStage stage, string? message, bool ipcConnected)
+    {
+        UpdateOwned(record =>
+        {
+            record.LastObservedStage = stage;
+            record.LastObservedMessage = message ?? string.Empty;
+            if (ipcConnected)
+            {
+                record.IpcConnected = true;
+                record.PublicIpcConnected = true;
+            }
+        });
+    }
+
+    public void UpdateOwnedCoordinatorHeartbeat(LauncherCoordinatorStatus status)
+    {
+        UpdateOwned(record =>
+        {
+            record.CoordinatorPid = Environment.ProcessId;
+            record.HeartbeatAtUtc = DateTimeOffset.UtcNow;
+            record.LastObservedStage = status.LastObservedStage;
+            record.LastObservedMessage = status.LastObservedMessage;
+            record.IpcConnected = status.PublicIpcConnected;
+            record.PublicIpcConnected = status.PublicIpcConnected;
+            record.ShellStatus = status.ShellStatus?.ShellState ?? status.State;
+        });
+    }
+
+    public void MarkOwnedSoftTimeout(string? message)
+    {
+        UpdateOwned(record =>
+        {
+            record.State = StartupAttemptState.SoftTimeout;
+            record.LastObservedMessage = message ?? record.LastObservedMessage;
+        });
+    }
+
+    public void MarkOwnedWaitingForShell(string? message)
+    {
+        UpdateOwned(record =>
+        {
+            if (record.State is StartupAttemptState.Pending or StartupAttemptState.SoftTimeout or StartupAttemptState.DetachedWaiting)
+            {
+                record.State = StartupAttemptState.WaitingForShell;
+            }
+
+            record.LastObservedMessage = message ?? record.LastObservedMessage;
+        });
+    }
+
+    public void MarkOwnedDetachedWaiting()
+    {
+        UpdateOwned(record =>
+        {
+            if (record.State is StartupAttemptState.Pending or StartupAttemptState.SoftTimeout)
+            {
+                record.State = StartupAttemptState.DetachedWaiting;
+            }
+        });
+    }
+
+    public void MarkOwnedSucceeded(StartupStage stage, string? message)
+    {
+        UpdateOwned(record =>
+        {
+            record.State = StartupAttemptState.Succeeded;
+            record.LastObservedStage = stage;
+            record.LastObservedMessage = message ?? record.LastObservedMessage;
+        });
+    }
+
+    public void MarkOwnedFailed(StartupStage stage, string? message)
+    {
+        UpdateOwned(record =>
+        {
+            record.State = StartupAttemptState.Failed;
+            record.LastObservedStage = stage;
+            record.LastObservedMessage = message ?? record.LastObservedMessage;
+        });
+    }
+
+    private void UpdateOwned(Action<StartupAttemptRecord> update)
+    {
+        if (string.IsNullOrWhiteSpace(_ownedAttemptId))
+        {
+            return;
+        }
+
+        ExecuteWithLock(() =>
+        {
+            var record = LoadUnsafe();
+            if (record is null || !string.Equals(record.AttemptId, _ownedAttemptId, StringComparison.Ordinal))
+            {
+                return;
+            }
+
+            update(record);
+            record.UpdatedAtUtc = DateTimeOffset.UtcNow;
+            SaveUnsafe(record);
+        });
+    }
+
+    private void ExecuteWithLock(Action action)
+    {
+        using var mutex = new Mutex(false, _mutexName);
+        var hasHandle = false;
+        try
+        {
+            try
+            {
+                hasHandle = mutex.WaitOne(TimeSpan.FromSeconds(2));
+            }
+            catch (AbandonedMutexException)
+            {
+                hasHandle = true;
+            }
+
+            if (!hasHandle)
+            {
+                return;
+            }
+
+            action();
+        }
+        finally
+        {
+            if (hasHandle)
+            {
+                mutex.ReleaseMutex();
+            }
+        }
+    }
+
+    private StartupAttemptRecord? LoadUnsafe()
+    {
+        if (!File.Exists(_statePath))
+        {
+            return null;
+        }
+
+        try
+        {
+            var json = File.ReadAllText(_statePath);
+            return JsonSerializer.Deserialize(json, AppJsonContext.Default.StartupAttemptRecord);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private void SaveUnsafe(StartupAttemptRecord record)
+    {
+        var directory = Path.GetDirectoryName(_statePath);
+        if (!string.IsNullOrWhiteSpace(directory))
+        {
+            Directory.CreateDirectory(directory);
+        }
+
+        File.WriteAllText(_statePath, JsonSerializer.Serialize(record, AppJsonContext.Default.StartupAttemptRecord));
+    }
+
+    private static bool IsAttachable(StartupAttemptRecord record)
+    {
+        if (record.State is not (
+            StartupAttemptState.Pending or
+            StartupAttemptState.SoftTimeout or
+            StartupAttemptState.DetachedWaiting or
+            StartupAttemptState.WaitingForShell))
+        {
+            return false;
+        }
+
+        return TryGetLiveProcess(record.HostPid, out _);
+    }
+
+    private static bool IsRecoverableCoordinatorAttempt(StartupAttemptRecord record)
+    {
+        if (record.State is not (
+            StartupAttemptState.Pending or
+            StartupAttemptState.SoftTimeout or
+            StartupAttemptState.DetachedWaiting or
+            StartupAttemptState.WaitingForShell))
+        {
+            return false;
+        }
+
+        if (record.HostPid <= 0)
+        {
+            return true;
+        }
+
+        return TryGetLiveProcess(record.HostPid, out _);
+    }
+
+    private static bool IsCoordinatorLive(StartupAttemptRecord record)
+    {
+        if (record.State is not (
+            StartupAttemptState.Pending or
+            StartupAttemptState.SoftTimeout or
+            StartupAttemptState.DetachedWaiting or
+            StartupAttemptState.WaitingForShell))
+        {
+            return false;
+        }
+
+        if (record.CoordinatorPid <= 0 ||
+            string.IsNullOrWhiteSpace(record.CoordinatorPipeName) ||
+            DateTimeOffset.UtcNow - record.HeartbeatAtUtc > CoordinatorHeartbeatTimeout)
+        {
+            return false;
+        }
+
+        return TryGetLiveProcess(record.CoordinatorPid, out _);
+    }
+
+    private static bool TryGetLiveProcess(int processId, out Process? process)
+    {
+        process = null;
+        if (processId <= 0)
+        {
+            return false;
+        }
+
+        try
+        {
+            process = Process.GetProcessById(processId);
+            return !process.HasExited;
+        }
+        catch
+        {
+            process?.Dispose();
+            process = null;
+            return false;
+        }
+    }
+
+    private static string ComputePathHash(string statePath)
+    {
+        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(statePath.ToLowerInvariant()));
+        return Convert.ToHexString(bytes[..8]);
+    }
+
+    private static StartupAttemptRecord Clone(StartupAttemptRecord record)
+    {
+        return new StartupAttemptRecord
+        {
+            AttemptId = record.AttemptId,
+            HostPid = record.HostPid,
+            CoordinatorPid = record.CoordinatorPid,
+            CoordinatorPipeName = record.CoordinatorPipeName,
+            StartedAtUtc = record.StartedAtUtc,
+            UpdatedAtUtc = record.UpdatedAtUtc,
+            HeartbeatAtUtc = record.HeartbeatAtUtc,
+            LaunchSource = record.LaunchSource,
+            SuccessPolicy = record.SuccessPolicy,
+            LastObservedStage = record.LastObservedStage,
+            LastObservedMessage = record.LastObservedMessage,
+            IpcConnected = record.IpcConnected,
+            PublicIpcConnected = record.PublicIpcConnected,
+            ShellStatus = record.ShellStatus,
+            ReservedBeforeHostStart = record.ReservedBeforeHostStart,
+            State = record.State
+        };
+    }
+}

LanMountainDesktop.Launcher/Services/ThemeService.cs

@@ -0,0 +1,68 @@
+using Avalonia;
+using Avalonia.Styling;
+using FluentAvalonia.Styling;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+/// <summary>
+/// 主题服务，管理启动器的主题设置
+/// </summary>
+public static class ThemeService
+{
+    private static ThemeVariant _currentTheme = ThemeVariant.Light;
+    private static string _accentColor = "#0078D4";
+
+    /// <summary>
+    /// 获取当前主题
+    /// </summary>
+    public static ThemeVariant CurrentTheme => _currentTheme;
+
+    /// <summary>
+    /// 获取当前主题色
+    /// </summary>
+    public static string AccentColor => _accentColor;
+
+    /// <summary>
+    /// 应用主题设置
+    /// </summary>
+    public static void ApplyTheme(ThemeMode mode, string accentColor)
+    {
+        _currentTheme = mode switch
+        {
+            ThemeMode.Dark => ThemeVariant.Dark,
+            _ => ThemeVariant.Light
+        };
+        _accentColor = accentColor;
+
+        // 应用到当前应用程序
+        if (Application.Current is { } app)
+        {
+            app.RequestedThemeVariant = _currentTheme;
+        }
+    }
+
+    /// <summary>
+    /// 应用浅色主题
+    /// </summary>
+    public static void ApplyLightTheme(string accentColor)
+    {
+        ApplyTheme(ThemeMode.Light, accentColor);
+    }
+
+    /// <summary>
+    /// 应用深色主题
+    /// </summary>
+    public static void ApplyDarkTheme(string accentColor)
+    {
+        ApplyTheme(ThemeMode.Dark, accentColor);
+    }
+}
+
+/// <summary>
+/// 主题模式
+/// </summary>
+public enum ThemeMode
+{
+    Light,
+    Dark
+}

LanMountainDesktop.Launcher/Services/UpdateEngineService.cs

@@ -7,7 +7,6 @@ namespace LanMountainDesktop.Launcher.Services;
 
 internal sealed class UpdateEngineService
 {
-    private const string LauncherDirectoryName = ".launcher";
     private const string UpdateDirectoryName = "update";
     private const string IncomingDirectoryName = "incoming";
     private const string SnapshotsDirectoryName = "snapshots";
@@ -30,7 +29,8 @@ internal sealed class UpdateEngineService
     {
         _deploymentLocator = deploymentLocator;
         _appRoot = deploymentLocator.GetAppRoot();
-        _launcherRoot = Path.Combine(_appRoot, LauncherDirectoryName);
+        var resolver = new DataLocationResolver(_appRoot);
+        _launcherRoot = resolver.ResolveLauncherDataPath();
         _incomingRoot = Path.Combine(_launcherRoot, UpdateDirectoryName, IncomingDirectoryName);
         _snapshotsRoot = Path.Combine(_launcherRoot, SnapshotsDirectoryName);
     }
@@ -1458,7 +1458,7 @@ internal sealed class UpdateEngineService
         }
     }
 
-    private void CleanupIncomingArtifacts()
+    internal void CleanupIncomingArtifacts()
     {
         foreach (var path in new[]
                  {

LanMountainDesktop.Launcher/Services/WelcomeOobeStep.cs

@@ -0,0 +1,50 @@
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Services;
+
+internal sealed class WelcomeOobeStep : IOobeStep
+{
+    private readonly CommandContext _context;
+    private readonly OobeStateService _oobeStateService;
+
+    public WelcomeOobeStep(OobeStateService oobeStateService, CommandContext context)
+    {
+        _oobeStateService = oobeStateService;
+        _context = context;
+    }
+
+    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);
+        var completion = _oobeStateService.MarkCompleted(_context);
+        if (!completion.Success)
+        {
+            Logger.Warn(
+                $"OOBE completion state was not persisted. ResultCode='{completion.ResultCode}'; " +
+                $"Error='{completion.ErrorMessage}'.");
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            if (window.IsVisible)
+            {
+                window.Close();
+            }
+        });
+    }
+}

LanMountainDesktop.Launcher/ViewModels/DevDebugWindowViewModel.cs

@@ -13,6 +13,7 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
     private bool _isErrorEnabled = true;
     private bool _isUpdateEnabled = true;
     private bool _isOobeEnabled = true;
+    private bool _isDataLocationEnabled = true;
     private string _statusMessage = "就绪";
 
     public event PropertyChangedEventHandler? PropertyChanged;
@@ -87,6 +88,23 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
         }
     }
 
+    /// <summary>
+    /// 数据位置选择页面是否启用实际功能
+    /// </summary>
+    public bool IsDataLocationEnabled
+    {
+        get => _isDataLocationEnabled;
+        set
+        {
+            if (_isDataLocationEnabled != value)
+            {
+                _isDataLocationEnabled = value;
+                OnPropertyChanged();
+                UpdateStatus($"数据位置选择: {(value ? "功能模式" : "仅查看")}");
+            }
+        }
+    }
+
     #endregion
 
     #region 状态信息
@@ -131,6 +149,11 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
     /// </summary>
     public ICommand OpenOobeCommand { get; }
 
+    /// <summary>
+    /// 打开数据位置选择页面命令
+    /// </summary>
+    public ICommand OpenDataLocationCommand { get; }
+
     /// <summary>
     /// 全部切换到查看模式命令
     /// </summary>
@@ -170,6 +193,11 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
     /// </summary>
     public event EventHandler<OobeOpenEventArgs>? OpenOobeRequested;
 
+    /// <summary>
+    /// 请求打开数据位置选择页面
+    /// </summary>
+    public event EventHandler<DataLocationOpenEventArgs>? OpenDataLocationRequested;
+
     /// <summary>
     /// 请求关闭窗口
     /// </summary>
@@ -199,12 +227,18 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
             OpenOobeRequested?.Invoke(this, new OobeOpenEventArgs(IsOobeEnabled));
         });
 
+        OpenDataLocationCommand = new RelayCommand(() =>
+        {
+            OpenDataLocationRequested?.Invoke(this, new DataLocationOpenEventArgs(IsDataLocationEnabled));
+        });
+
         SetAllViewOnlyCommand = new RelayCommand(() =>
         {
             IsSplashEnabled = false;
             IsErrorEnabled = false;
             IsUpdateEnabled = false;
             IsOobeEnabled = false;
+            IsDataLocationEnabled = false;
             UpdateStatus("全部页面已切换到查看模式");
         });
 
@@ -214,6 +248,7 @@ public sealed class DevDebugWindowViewModel : INotifyPropertyChanged
             IsErrorEnabled = true;
             IsUpdateEnabled = true;
             IsOobeEnabled = true;
+            IsDataLocationEnabled = true;
             UpdateStatus("全部页面已切换到功能模式");
         });
 
@@ -260,4 +295,10 @@ public class OobeOpenEventArgs : EventArgs
     public OobeOpenEventArgs(bool isFunctional) => IsFunctional = isFunctional;
 }
 
+public class DataLocationOpenEventArgs : EventArgs
+{
+    public bool IsFunctional { get; }
+    public DataLocationOpenEventArgs(bool isFunctional) => IsFunctional = isFunctional;
+}
+
 #endregion

LanMountainDesktop.Launcher/Views/DataLocationPromptWindow.axaml

@@ -0,0 +1,154 @@
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+        xmlns:views="clr-namespace:LanMountainDesktop.Launcher.Views"
+        xmlns:fi="using:FluentIcons.Avalonia"
+        mc:Ignorable="d"
+        d:DesignWidth="520"
+        d:DesignHeight="480"
+        x:Class="LanMountainDesktop.Launcher.Views.DataLocationPromptWindow"
+        x:DataType="views:DataLocationPromptWindow"
+        Title="Choose Data Location"
+        Width="520"
+        Height="480"
+        CanResize="False"
+        WindowStartupLocation="CenterScreen"
+        Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
+        TransparencyLevelHint="None"
+        Icon="/Assets/logo.ico">
+  <Grid x:Name="ContentGrid"
+        Opacity="0">
+    <Grid.RenderTransform>
+      <TranslateTransform Y="24" />
+    </Grid.RenderTransform>
+    <Grid Margin="36" RowDefinitions="Auto,*,Auto">
+      <StackPanel Grid.Row="0" Spacing="8" Margin="0,0,0,20">
+        <TextBlock Text="Choose Data Location"
+                   FontSize="22"
+                   FontWeight="SemiBold"
+                   Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        <TextBlock Text="Choose where launcher and desktop data should be stored. You can change this later in settings."
+                   FontSize="13"
+                   TextWrapping="Wrap"
+                   Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+      </StackPanel>
+
+      <StackPanel Grid.Row="1" Spacing="12">
+        <Border x:Name="AdminWarningBanner"
+                Background="{DynamicResource SystemFillColorCriticalBackgroundBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="12,10"
+                IsVisible="False">
+          <StackPanel Spacing="4">
+            <StackPanel Orientation="Horizontal" Spacing="6">
+              <fi:SymbolIcon Symbol="Important"
+                             FontSize="16"
+                             Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+              <TextBlock Text="App folder is not writable"
+                         FontWeight="SemiBold"
+                         FontSize="13"
+                         Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+            </StackPanel>
+            <TextBlock Text="The current install directory requires elevated permissions. Data will be stored in the system user profile instead."
+                       FontSize="12"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+          </StackPanel>
+        </Border>
+
+        <Border x:Name="SystemOptionBorder"
+                Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                BorderThickness="2"
+                BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                Padding="16,14">
+          <Grid ColumnDefinitions="Auto,*">
+            <RadioButton x:Name="SystemRadio"
+                         Grid.Column="0"
+                         VerticalAlignment="Top"
+                         Margin="0,2,12,0"
+                         GroupName="DataLocation"
+                         IsChecked="True" />
+            <StackPanel Grid.Column="1" Spacing="4">
+              <TextBlock Text="Store in the system user profile (Recommended)"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <TextBlock Text="Data stays tied to the current Windows user and remains intact across app reinstalls and updates."
+                         FontSize="12"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+              <TextBlock x:Name="SystemPathText"
+                         FontSize="11"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorTertiaryBrush}"
+                         Margin="0,4,0,0" />
+            </StackPanel>
+          </Grid>
+        </Border>
+
+        <Border x:Name="PortableOptionBorder"
+                Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                BorderThickness="1"
+                BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                Padding="16,14">
+          <Grid ColumnDefinitions="Auto,*">
+            <RadioButton x:Name="PortableRadio"
+                         Grid.Column="0"
+                         VerticalAlignment="Top"
+                         Margin="0,2,12,0"
+                         GroupName="DataLocation"
+                         IsEnabled="False" />
+            <StackPanel Grid.Column="1" Spacing="4">
+              <TextBlock Text="Store next to the app"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <TextBlock Text="Useful for portable installs. The whole app folder can be moved to another machine together with its data."
+                         FontSize="12"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+              <TextBlock x:Name="PortablePathText"
+                         FontSize="11"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorTertiaryBrush}"
+                         Margin="0,4,0,0" />
+            </StackPanel>
+          </Grid>
+        </Border>
+
+        <Border x:Name="MigrationInfoBorder"
+                Background="{DynamicResource SystemFillColorSuccessBackgroundBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="12,10"
+                IsVisible="False">
+          <StackPanel Orientation="Horizontal" Spacing="6">
+            <fi:SymbolIcon Symbol="Info"
+                           FontSize="16"
+                           Foreground="{DynamicResource SystemFillColorSuccessBrush}" />
+            <TextBlock x:Name="MigrationInfoText"
+                       FontSize="12"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource SystemFillColorSuccessBrush}" />
+          </StackPanel>
+        </Border>
+      </StackPanel>
+
+      <StackPanel Grid.Row="2"
+                  Orientation="Horizontal"
+                  HorizontalAlignment="Right"
+                  Spacing="10"
+                  Margin="0,20,0,0">
+        <Button x:Name="CancelButton"
+                Content="Cancel"
+                Theme="{DynamicResource ButtonTheme}"
+                IsVisible="False" />
+        <Button x:Name="ConfirmButton"
+                Content="Confirm"
+                Theme="{DynamicResource AccentButtonTheme}" />
+      </StackPanel>
+    </Grid>
+  </Grid>
+</Window>

LanMountainDesktop.Launcher/Views/DataLocationPromptWindow.axaml.cs

@@ -0,0 +1,308 @@
+using Avalonia;
+using Avalonia.Animation;
+using Avalonia.Animation.Easings;
+using Avalonia.Controls;
+using Avalonia.Interactivity;
+using Avalonia.Markup.Xaml;
+using Avalonia.Media;
+using Avalonia.Styling;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Services;
+
+namespace LanMountainDesktop.Launcher.Views;
+
+internal partial class DataLocationPromptWindow : Window
+{
+    private readonly TaskCompletionSource<DataLocationPromptResult?> _completionSource = new();
+    private readonly DataLocationResolver _resolver;
+    private bool _isTransitioning;
+
+    public DataLocationPromptWindow()
+    {
+        AvaloniaXamlLoader.Load(this);
+        Loaded += OnWindowLoaded;
+        Opened += OnWindowOpened;
+        _resolver = new DataLocationResolver(AppContext.BaseDirectory);
+    }
+
+    internal DataLocationPromptWindow(DataLocationResolver resolver)
+    {
+        AvaloniaXamlLoader.Load(this);
+        Loaded += OnWindowLoaded;
+        Opened += OnWindowOpened;
+        _resolver = resolver;
+    }
+
+    private void OnWindowLoaded(object? sender, RoutedEventArgs e)
+    {
+        BindControls();
+        UpdateUiState();
+    }
+
+    private void BindControls()
+    {
+        var systemRadio = this.FindControl<RadioButton>("SystemRadio");
+        var portableRadio = this.FindControl<RadioButton>("PortableRadio");
+        var confirmButton = this.FindControl<Button>("ConfirmButton");
+        var cancelButton = this.FindControl<Button>("CancelButton");
+
+        if (systemRadio is not null)
+        {
+            systemRadio.IsCheckedChanged += OnSelectionChanged;
+        }
+
+        if (portableRadio is not null)
+        {
+            portableRadio.IsCheckedChanged += OnSelectionChanged;
+        }
+
+        if (confirmButton is not null)
+        {
+            confirmButton.Click += OnConfirmClick;
+        }
+
+        if (cancelButton is not null)
+        {
+            cancelButton.Click += OnCancelClick;
+        }
+    }
+
+    private void UpdateUiState()
+    {
+        var systemPathText = this.FindControl<TextBlock>("SystemPathText");
+        var portablePathText = this.FindControl<TextBlock>("PortablePathText");
+        var adminWarningBanner = this.FindControl<Border>("AdminWarningBanner");
+        var portableRadio = this.FindControl<RadioButton>("PortableRadio");
+        var migrationInfoBorder = this.FindControl<Border>("MigrationInfoBorder");
+        var migrationInfoText = this.FindControl<TextBlock>("MigrationInfoText");
+
+        if (systemPathText is not null)
+        {
+            systemPathText.Text = _resolver.DefaultSystemDataPath;
+        }
+
+        if (portablePathText is not null)
+        {
+            portablePathText.Text = _resolver.DefaultPortableDataPath;
+        }
+
+        var portableAllowed = _resolver.IsPortableModeAllowed();
+
+        if (adminWarningBanner is not null)
+        {
+            adminWarningBanner.IsVisible = !portableAllowed;
+        }
+
+        if (portableRadio is not null)
+        {
+            portableRadio.IsEnabled = portableAllowed;
+        }
+
+        var hasExistingData = _resolver.HasExistingSystemData();
+        if (migrationInfoBorder is not null)
+        {
+            migrationInfoBorder.IsVisible = hasExistingData;
+        }
+
+        if (migrationInfoText is not null && hasExistingData)
+        {
+            migrationInfoText.Text = "Existing system data was detected. Choosing portable mode will migrate the current data automatically.";
+        }
+    }
+
+    private void OnSelectionChanged(object? sender, RoutedEventArgs e)
+    {
+        var systemRadio = this.FindControl<RadioButton>("SystemRadio");
+        var portableRadio = this.FindControl<RadioButton>("PortableRadio");
+        var systemBorder = this.FindControl<Border>("SystemOptionBorder");
+        var portableBorder = this.FindControl<Border>("PortableOptionBorder");
+
+        var isSystem = systemRadio?.IsChecked == true;
+        var isPortable = portableRadio?.IsChecked == true;
+
+        if (systemBorder is not null)
+        {
+            systemBorder.BorderBrush = isSystem
+                ? Application.Current?.FindResource("AccentFillColorDefaultBrush") as IBrush
+                : Application.Current?.FindResource("CardStrokeColorDefaultBrush") as IBrush;
+            systemBorder.BorderThickness = isSystem ? new Thickness(2) : new Thickness(1);
+        }
+
+        if (portableBorder is not null)
+        {
+            portableBorder.BorderBrush = isPortable
+                ? Application.Current?.FindResource("AccentFillColorDefaultBrush") as IBrush
+                : Application.Current?.FindResource("CardStrokeColorDefaultBrush") as IBrush;
+            portableBorder.BorderThickness = isPortable ? new Thickness(2) : new Thickness(1);
+        }
+    }
+
+    private async void OnConfirmClick(object? sender, RoutedEventArgs e)
+    {
+        if (_isTransitioning)
+        {
+            return;
+        }
+
+        _isTransitioning = true;
+
+        var portableRadio = this.FindControl<RadioButton>("PortableRadio");
+        var selectedMode = portableRadio?.IsChecked == true
+            ? DataLocationMode.Portable
+            : DataLocationMode.System;
+
+        var migrateExistingData = selectedMode == DataLocationMode.Portable && _resolver.HasExistingSystemData();
+
+        try
+        {
+            await PlayExitAnimationAsync();
+            _completionSource.TrySetResult(new DataLocationPromptResult
+            {
+                SelectedMode = selectedMode,
+                MigrateExistingData = migrateExistingData
+            });
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Error during data location prompt exit animation: {ex.Message}");
+            _completionSource.TrySetResult(new DataLocationPromptResult
+            {
+                SelectedMode = selectedMode,
+                MigrateExistingData = migrateExistingData
+            });
+        }
+    }
+
+    private async void OnCancelClick(object? sender, RoutedEventArgs e)
+    {
+        if (_isTransitioning)
+        {
+            return;
+        }
+
+        _isTransitioning = true;
+
+        try
+        {
+            await PlayExitAnimationAsync();
+            _completionSource.TrySetResult(null);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Error during data location prompt cancel: {ex.Message}");
+            _completionSource.TrySetResult(null);
+        }
+    }
+
+    private async void OnWindowOpened(object? sender, EventArgs e)
+    {
+        await PlayEntranceAnimationAsync();
+    }
+
+    private async Task PlayEntranceAnimationAsync()
+    {
+        try
+        {
+            var contentGrid = this.FindControl<Grid>("ContentGrid");
+            if (contentGrid is null)
+            {
+                return;
+            }
+
+            var translateTransform = contentGrid.RenderTransform as TranslateTransform ?? new TranslateTransform();
+            contentGrid.RenderTransform = translateTransform;
+
+            contentGrid.Opacity = 0;
+            translateTransform.Y = 24;
+
+            var fadeInAnimation = new Animation
+            {
+                Duration = TimeSpan.FromMilliseconds(500),
+                Easing = new CubicEaseOut(),
+                FillMode = FillMode.Forward,
+                Children =
+                {
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(OpacityProperty, 0.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(0)
+                    },
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(OpacityProperty, 1.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(500)
+                    }
+                }
+            };
+
+            var slideUpAnimation = new Animation
+            {
+                Duration = TimeSpan.FromMilliseconds(500),
+                Easing = new CubicEaseOut(),
+                FillMode = FillMode.Forward,
+                Children =
+                {
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(TranslateTransform.YProperty, 24.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(0)
+                    },
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(TranslateTransform.YProperty, 0.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(500)
+                    }
+                }
+            };
+
+            await Task.WhenAll(
+                fadeInAnimation.RunAsync(contentGrid),
+                slideUpAnimation.RunAsync(translateTransform));
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Error playing data location prompt entrance animation: {ex.Message}");
+        }
+    }
+
+    private async Task PlayExitAnimationAsync()
+    {
+        try
+        {
+            var contentGrid = this.FindControl<Grid>("ContentGrid");
+            if (contentGrid is null)
+            {
+                await Task.Delay(150);
+                return;
+            }
+
+            var fadeOutAnimation = new Animation
+            {
+                Duration = TimeSpan.FromMilliseconds(200),
+                Easing = new CubicEaseIn(),
+                FillMode = FillMode.Forward,
+                Children =
+                {
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(OpacityProperty, 1.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(0)
+                    },
+                    new KeyFrame
+                    {
+                        Setters = { new Setter(OpacityProperty, 0.0) },
+                        KeyTime = TimeSpan.FromMilliseconds(200)
+                    }
+                }
+            };
+
+            await fadeOutAnimation.RunAsync(contentGrid);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Error playing data location prompt exit animation: {ex.Message}");
+        }
+    }
+
+    internal Task<DataLocationPromptResult?> WaitForChoiceAsync() => _completionSource.Task;
+}

LanMountainDesktop.Launcher/Views/DevDebugWindow.axaml

@@ -141,6 +141,32 @@
             </Grid>
           </Border>
 
+          <!-- 数据位置选择页面 -->
+          <Border Background="{DynamicResource SystemControlBackgroundAltMediumBrush}"
+                  CornerRadius="8"
+                  Padding="15">
+            <Grid ColumnDefinitions="*,Auto">
+              <StackPanel Grid.Column="0">
+                <TextBlock Text="📁 数据位置选择 (DataLocationPromptWindow)"
+                           FontWeight="SemiBold"
+                           FontSize="14" />
+                <TextBlock Text="选择数据保存位置"
+                           FontSize="11"
+                           Opacity="0.6"
+                           Margin="0,3,0,0" />
+              </StackPanel>
+              <StackPanel Grid.Column="1" Spacing="8">
+                <ToggleSwitch Content="启用功能"
+                              IsChecked="{Binding IsDataLocationEnabled}"
+                              OnContent="功能"
+                              OffContent="查看" />
+                <Button Content="打开"
+                        Command="{Binding OpenDataLocationCommand}"
+                        HorizontalAlignment="Right" />
+              </StackPanel>
+            </Grid>
+          </Border>
+
         </StackPanel>
       </ScrollViewer>
 

LanMountainDesktop.Launcher/Views/DevDebugWindow.axaml.cs

@@ -25,6 +25,7 @@ public partial class DevDebugWindow : Window
         _viewModel.OpenErrorRequested += OnOpenErrorRequested;
         _viewModel.OpenUpdateRequested += OnOpenUpdateRequested;
         _viewModel.OpenOobeRequested += OnOpenOobeRequested;
+        _viewModel.OpenDataLocationRequested += OnOpenDataLocationRequested;
         _viewModel.CloseRequested += OnCloseRequested;
     }
 
@@ -135,6 +136,17 @@ public partial class DevDebugWindow : Window
         }
     }
 
+    /// <summary>
+    /// 打开数据位置选择页面
+    /// </summary>
+    private void OnOpenDataLocationRequested(object? sender, DataLocationOpenEventArgs e)
+    {
+        var appRoot = AppDomain.CurrentDomain.BaseDirectory;
+        var resolver = new DataLocationResolver(appRoot);
+        var window = new DataLocationPromptWindow(resolver);
+        window.Show();
+    }
+
     /// <summary>
     /// 关闭窗口
     /// </summary>

LanMountainDesktop.Launcher/Views/ErrorDebugWindow.axaml.cs

@@ -5,52 +5,41 @@ using Avalonia.Platform.Storage;
 
 namespace LanMountainDesktop.Launcher.Views;
 
-/// <summary>
-/// 错误调试窗口 - 开发人员专用调试设置
-/// </summary>
 public partial class ErrorDebugWindow : Window
 {
     private string? _selectedHostPath;
-    private bool _isInitialized = false;
+    private bool _isInitialized;
 
-    /// <summary>
-    /// 是否启用了开发模式
-    /// </summary>
     public bool IsDevModeEnabled { get; private set; }
 
-    /// <summary>
-    /// 选择的主程序路径
-    /// </summary>
+    public bool WasAccepted { get; private set; }
+
     public string? SelectedHostPath => _selectedHostPath;
 
     public ErrorDebugWindow()
     {
         AvaloniaXamlLoader.Load(this);
-        
-        // 延迟到窗口加载完成后再初始化组件
-        this.Loaded += OnWindowLoaded;
+        Loaded += OnWindowLoaded;
     }
 
-    public ErrorDebugWindow(bool devModeEnabled, string? initialPath) : this()
+    public ErrorDebugWindow(bool devModeEnabled, string? initialPath)
+        : this()
     {
         IsDevModeEnabled = devModeEnabled;
         _selectedHostPath = initialPath;
     }
 
-    /// <summary>
-    /// 窗口加载完成事件
-    /// </summary>
     private void OnWindowLoaded(object? sender, RoutedEventArgs e)
     {
-        if (_isInitialized) return;
+        if (_isInitialized)
+        {
+            return;
+        }
+
         _isInitialized = true;
-        
-        Console.WriteLine("[ErrorDebugWindow] Window loaded, initializing components...");
         InitializeComponents();
-        
-        // 设置初始值（在视觉树准备好后）
-        var devModeToggle = this.FindControl<ToggleSwitch>("DevModeToggle");
-        if (devModeToggle is not null)
+
+        if (this.FindControl<ToggleSwitch>("DevModeToggle") is { } devModeToggle)
         {
             devModeToggle.IsChecked = IsDevModeEnabled;
         }
@@ -60,113 +49,72 @@ public partial class ErrorDebugWindow : Window
 
     private void InitializeComponents()
     {
-        // 开发模式开关
-        var devModeToggle = this.FindControl<ToggleSwitch>("DevModeToggle");
-        if (devModeToggle is not null)
+        if (this.FindControl<ToggleSwitch>("DevModeToggle") is { } devModeToggle)
         {
-            devModeToggle.IsCheckedChanged += (s, e) =>
+            devModeToggle.IsCheckedChanged += (_, _) =>
             {
                 IsDevModeEnabled = devModeToggle.IsChecked ?? false;
-                Console.WriteLine($"[ErrorDebugWindow] DevMode changed to: {IsDevModeEnabled}");
             };
-            Console.WriteLine("[ErrorDebugWindow] DevModeToggle event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorDebugWindow] Failed to find DevModeToggle!");
         }
 
-        // 浏览按钮
-        var browseButton = this.FindControl<Button>("BrowseButton");
-        if (browseButton is not null)
+        if (this.FindControl<Button>("BrowseButton") is { } browseButton)
         {
             browseButton.Click += OnBrowseClick;
-            Console.WriteLine("[ErrorDebugWindow] BrowseButton event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorDebugWindow] Failed to find BrowseButton!");
         }
 
-        // 确定按钮
-        var okButton = this.FindControl<Button>("OkButton");
-        if (okButton is not null)
+        if (this.FindControl<Button>("OkButton") is { } okButton)
         {
-            okButton.Click += (s, e) => Close();
-            Console.WriteLine("[ErrorDebugWindow] OkButton event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorDebugWindow] Failed to find OkButton!");
-        }
-
-        // 取消按钮
-        var cancelButton = this.FindControl<Button>("CancelButton");
-        if (cancelButton is not null)
-        {
-            cancelButton.Click += (s, e) =>
+            okButton.Click += (_, _) =>
             {
-                // 取消时恢复原始状态
-                IsDevModeEnabled = false;
-                _selectedHostPath = null;
-                Console.WriteLine("[ErrorDebugWindow] Cancel clicked, resetting state");
+                WasAccepted = true;
                 Close();
             };
-            Console.WriteLine("[ErrorDebugWindow] CancelButton event bound");
         }
-        else
+
+        if (this.FindControl<Button>("CancelButton") is { } cancelButton)
         {
-            Console.Error.WriteLine("[ErrorDebugWindow] Failed to find CancelButton!");
+            cancelButton.Click += (_, _) => Close();
         }
-        
-        Console.WriteLine("[ErrorDebugWindow] Components initialization completed");
     }
 
-    /// <summary>
-    /// 浏览按钮点击
-    /// </summary>
     private async void OnBrowseClick(object? sender, RoutedEventArgs e)
     {
         var storageProvider = StorageProvider;
-        if (storageProvider is null) return;
+        if (storageProvider is null)
+        {
+            return;
+        }
 
         var options = new FilePickerOpenOptions
         {
-            Title = "选择阑山桌面主程序",
+            Title = "Select LanMountainDesktop host executable",
             AllowMultiple = false,
-            FileTypeFilter = new[]
-            {
-                new FilePickerFileType("可执行文件")
+            FileTypeFilter =
+            [
+                new FilePickerFileType("Executable")
                 {
                     Patterns = OperatingSystem.IsWindows()
-                        ? new[] { "*.exe" }
-                        : new[] { "*" }
+                        ? ["*.exe"]
+                        : ["*"]
                 }
-            }
+            ]
         };
 
         var result = await storageProvider.OpenFilePickerAsync(options);
-        if (result.Count > 0)
+        if (result.Count <= 0)
         {
-            _selectedHostPath = result[0].Path.LocalPath;
-            Console.WriteLine($"[ErrorDebugWindow] Selected host path: {_selectedHostPath}");
-            UpdatePathDisplay(_selectedHostPath);
+            return;
         }
+
+        _selectedHostPath = result[0].Path.LocalPath;
+        UpdatePathDisplay(_selectedHostPath);
     }
 
-    /// <summary>
-    /// 更新路径显示
-    /// </summary>
     private void UpdatePathDisplay(string? path)
     {
-        var pathTextBlock = this.FindControl<TextBlock>("PathTextBlock");
-        if (pathTextBlock is not null)
+        if (this.FindControl<TextBlock>("PathTextBlock") is { } pathTextBlock)
         {
-            pathTextBlock.Text = string.IsNullOrEmpty(path) ? "未选择" : path;
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorDebugWindow] Failed to find PathTextBlock!");
+            pathTextBlock.Text = string.IsNullOrEmpty(path) ? "Not selected" : path;
         }
     }
 }

LanMountainDesktop.Launcher/Views/ErrorWindow.axaml

@@ -3,102 +3,96 @@
         xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
         xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
         xmlns:views="clr-namespace:LanMountainDesktop.Launcher.Views"
-        xmlns:ui="using:FluentAvalonia.UI.Controls"
         mc:Ignorable="d"
-        d:DesignWidth="520"
-        d:DesignHeight="280"
         x:Class="LanMountainDesktop.Launcher.Views.ErrorWindow"
         x:DataType="views:ErrorWindow"
-        Title="阑山桌面"
-        Width="520"
-        Height="280"
+        Title="LanMountain Desktop"
+        Width="560"
+        Height="320"
         CanResize="False"
         WindowStartupLocation="CenterScreen"
-        Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
+        Background="#111318"
         TransparencyLevelHint="None"
         Icon="/Assets/logo.ico">
   <Design.DataContext>
     <views:ErrorWindow />
   </Design.DataContext>
 
-  <!-- Fluent Design 风格对话框布局 -->
   <Grid RowDefinitions="*,Auto">
-    <!-- 主内容区域：左侧图标 + 右侧文字 -->
-    <Grid Grid.Row="0" Margin="24,24,24,16" ColumnDefinitions="Auto,*">
-      
-      <!-- 左侧：错误图标（可点击进入调试模式） -->
+    <Grid Grid.Row="0"
+          Margin="24"
+          ColumnDefinitions="Auto,*">
       <Border x:Name="ErrorIconBorder"
               Grid.Column="0"
-              Width="48"
-              Height="48"
-              Margin="0,4,16,0"
-              Background="{DynamicResource SystemFillColorCriticalBackgroundBrush}"
-              CornerRadius="24"
+              Width="52"
+              Height="52"
+              Margin="0,4,18,0"
+              Background="#2B161A"
+              CornerRadius="26"
               VerticalAlignment="Top">
-        <TextBlock Text="&#xEA39;"
+        <TextBlock Text="!"
                    FontSize="24"
-                   FontFamily="{DynamicResource SymbolThemeFontFamily}"
-                   Foreground="{DynamicResource SystemFillColorCriticalBrush}"
+                   FontWeight="Bold"
+                   Foreground="#FFB4AB"
                    HorizontalAlignment="Center"
-                   VerticalAlignment="Center"/>
+                   VerticalAlignment="Center" />
       </Border>
-      
-      <!-- 右侧：标题 + 内容 -->
-      <StackPanel Grid.Column="1" Spacing="8">
-        <!-- 标题 -->
+
+      <StackPanel Grid.Column="1"
+                  Spacing="10">
         <TextBlock x:Name="TitleText"
-                   Text="启动失败"
-                   FontSize="18"
+                   Text="Launcher could not confirm startup"
+                   FontSize="20"
                    FontWeight="SemiBold"
-                   Foreground="{DynamicResource TextFillColorPrimaryBrush}"
-                   TextWrapping="Wrap"/>
-        
-        <!-- 错误信息 -->
+                   Foreground="#F6F7FB"
+                   TextWrapping="Wrap" />
+
         <TextBlock x:Name="ErrorMessageText"
-                   Text="找不到阑山桌面应用程序。"
+                   Text="LanMountain Desktop did not reach the expected startup state."
                    FontSize="14"
-                   Foreground="{DynamicResource TextFillColorSecondaryBrush}"
+                   Foreground="#D2D7E1"
                    TextWrapping="Wrap"
-                   LineHeight="20"/>
-        
-        <!-- 建议信息 -->
+                   LineHeight="22" />
+
         <TextBlock x:Name="SuggestionText"
-                   Text="请确保应用程序已正确安装，或尝试重新安装。"
+                   Text="You can inspect logs, retry when the old process is gone, or reactivate the current instance."
                    FontSize="13"
-                   Foreground="{DynamicResource TextFillColorTertiaryBrush}"
+                   Foreground="#9BA5B7"
                    TextWrapping="Wrap"
-                   LineHeight="18"
-                   Margin="0,4,0,0"/>
+                   LineHeight="20" />
       </StackPanel>
     </Grid>
 
-    <!-- 底部：按钮区域 -->
     <Border Grid.Row="1"
-            Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
-            Padding="24,16">
-      <Grid ColumnDefinitions="*,Auto">
+            Padding="24,16"
+            Background="#171A21">
+      <Grid ColumnDefinitions="*,Auto,Auto,Auto"
+            ColumnSpacing="8">
         <Button x:Name="OpenLogButton"
                 Grid.Column="0"
-                Content="打开日志"
-                Width="100"
-                Height="32"
-                FontSize="13"
-                HorizontalAlignment="Left"/>
-        <StackPanel Grid.Column="1"
-                    Orientation="Horizontal" 
-                    Spacing="8">
-          <Button x:Name="ExitButton"
-                  Content="退出"
-                  Width="80"
-                  Height="32"
-                  FontSize="13"/>
-          <Button x:Name="RetryButton"
-                  Content="重试"
-                  Width="80"
-                  Height="32"
-                  FontSize="13"
-                  Theme="{DynamicResource AccentButtonTheme}"/>
-        </StackPanel>
+                Content="Open Logs"
+                MinWidth="108"
+                Height="34"
+                HorizontalAlignment="Left" />
+
+        <Button x:Name="SecondaryActionButton"
+                Grid.Column="1"
+                Content="Wait"
+                MinWidth="108"
+                Height="34"
+                IsVisible="False" />
+
+        <Button x:Name="ExitButton"
+                Grid.Column="2"
+                Content="Exit"
+                MinWidth="90"
+                Height="34" />
+
+        <Button x:Name="PrimaryActionButton"
+                Grid.Column="3"
+                Content="Retry"
+                MinWidth="108"
+                Height="34" />
       </Grid>
     </Border>
   </Grid>

LanMountainDesktop.Launcher/Views/ErrorWindow.axaml.cs

@@ -1,542 +1,314 @@
+using System.Diagnostics;
 using Avalonia.Controls;
+using Avalonia.Input;
 using Avalonia.Interactivity;
 using Avalonia.Markup.Xaml;
-using Avalonia.Platform.Storage;
 using LanMountainDesktop.Launcher.Services;
-using System.Diagnostics;
 
 namespace LanMountainDesktop.Launcher.Views;
 
-/// <summary>
-/// 错误窗口 - 显示启动失败信息，支持调试模式（隐藏入口）
-/// </summary>
 public partial class ErrorWindow : Window
 {
-    private readonly TaskCompletionSource<ErrorWindowResult> _completionSource = new();
-    private int _iconClickCount = 0;
     private const int DebugModeClickThreshold = 5;
-    private bool _isDebugMode = false;
-    private string? _customHostPath;
+
+    private readonly TaskCompletionSource<ErrorWindowResult> _completionSource = new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private int _iconClickCount;
+    private bool _isDebugMode;
     private bool _devModeEnabled;
+    private string? _customHostPath;
+    private ErrorWindowResult _primaryAction = ErrorWindowResult.Retry;
+    private ErrorWindowResult? _secondaryAction;
 
     public ErrorWindow()
     {
         AvaloniaXamlLoader.Load(this);
 
-        // 先加载保存的状态
         _devModeEnabled = LoadDevModeStateInternal();
         _customHostPath = LoadCustomHostPathInternal();
 
-        // 延迟到窗口加载完成后再初始化组件，确保视觉树已准备好
-        this.Loaded += OnWindowLoaded;
-        this.Opened += OnWindowOpened;
+        Loaded += OnWindowLoaded;
+        Closed += (_, _) => _completionSource.TrySetResult(ErrorWindowResult.Exit);
+        ConfigureForGenericFailure(allowRetry: true);
     }
 
-    /// <summary>
-    /// 窗口加载完成事件 - 视觉树已准备好
-    /// </summary>
-    private void OnWindowLoaded(object? sender, RoutedEventArgs e)
-    {
-        Console.WriteLine("[ErrorWindow] Window loaded, initializing components...");
-        InitializeComponents();
-    }
-
-    /// <summary>
-    /// 窗口打开事件
-    /// </summary>
-    private void OnWindowOpened(object? sender, EventArgs e)
-    {
-        Console.WriteLine("[ErrorWindow] Window opened and visible");
-    }
-
-    private void InitializeComponents()
-    {
-        Console.WriteLine("[ErrorWindow] Initializing components...");
-        
-        // 错误图标点击事件（进入调试模式 - 隐藏功能）
-        var errorIconBorder = this.FindControl<Border>("ErrorIconBorder");
-        if (errorIconBorder is not null)
-        {
-            errorIconBorder.PointerPressed += OnErrorIconClick;
-            Console.WriteLine("[ErrorWindow] ErrorIconBorder event bound successfully");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorWindow] Failed to find ErrorIconBorder!");
-        }
-
-        // 按钮事件
-        var retryButton = this.FindControl<Button>("RetryButton");
-        var exitButton = this.FindControl<Button>("ExitButton");
-        var openLogButton = this.FindControl<Button>("OpenLogButton");
-
-        if (retryButton is not null)
-        {
-            retryButton.Click += OnRetryClick;
-            Console.WriteLine("[ErrorWindow] RetryButton event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorWindow] Failed to find RetryButton!");
-        }
-
-        if (exitButton is not null)
-        {
-            exitButton.Click += OnExitClick;
-            Console.WriteLine("[ErrorWindow] ExitButton event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorWindow] Failed to find ExitButton!");
-        }
-
-        if (openLogButton is not null)
-        {
-            openLogButton.Click += OnOpenLogClick;
-            Console.WriteLine("[ErrorWindow] OpenLogButton event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[ErrorWindow] Failed to find OpenLogButton!");
-        }
-        
-        Console.WriteLine("[ErrorWindow] Components initialization completed");
-    }
-
-    /// <summary>
-    /// 设置错误消息
-    /// </summary>
     public void SetErrorMessage(string message)
     {
-        var errorText = this.FindControl<TextBlock>("ErrorMessageText");
-        if (errorText is not null)
+        if (this.FindControl<TextBlock>("ErrorMessageText") is { } errorText)
         {
             errorText.Text = message;
         }
     }
 
-    /// <summary>
-    /// 设置调试模式
-    /// </summary>
     public void SetDebugMode(bool isDebugMode)
     {
         _isDebugMode = isDebugMode;
-        var titleText = this.FindControl<TextBlock>("TitleText");
-        if (titleText is not null && isDebugMode)
+        if (isDebugMode && this.FindControl<TextBlock>("TitleText") is { } titleText)
         {
-            titleText.Text = "[调试模式] 错误页面";
+            titleText.Text = "[Debug] Launcher error";
         }
     }
 
-    /// <summary>
-    /// 获取用户选择的主程序路径
-    /// </summary>
-    public string? GetCustomHostPath() => _customHostPath;
-
-    /// <summary>
-    /// 是否启用了开发模式
-    /// </summary>
-    public bool IsDevModeEnabled() => _devModeEnabled;
-
-    /// <summary>
-    /// 等待用户选择
-    /// </summary>
-    public Task<ErrorWindowResult> WaitForChoiceAsync()
+    public void ConfigureForHostNotFound()
     {
-        return _completionSource.Task;
+        ApplyActionLayout(
+            title: "Launcher could not find the desktop executable",
+            suggestion: "Pick another executable in debug mode, inspect logs, or retry after fixing the deployment path.",
+            primaryLabel: "Retry",
+            primaryAction: ErrorWindowResult.Retry,
+            secondaryLabel: null,
+            secondaryAction: null);
     }
 
-    /// <summary>
-    /// 错误图标点击事件 - 连续点击 5 次进入调试模式（隐藏功能）
-    /// </summary>
-    private void OnErrorIconClick(object? sender, Avalonia.Input.PointerPressedEventArgs e)
+    public void ConfigureForGenericFailure(bool allowRetry)
+    {
+        ApplyActionLayout(
+            title: "Launcher could not confirm startup",
+            suggestion: allowRetry
+                ? "Inspect logs, then retry once the previous startup attempt has fully finished."
+                : "Inspect logs or exit. Launcher will avoid creating another desktop process while the old one is still running.",
+            primaryLabel: allowRetry ? "Retry" : "Activate",
+            primaryAction: allowRetry ? ErrorWindowResult.Retry : ErrorWindowResult.ActivateExisting,
+            secondaryLabel: allowRetry ? null : "Wait",
+            secondaryAction: allowRetry ? null : ErrorWindowResult.ContinueWaiting);
+    }
+
+    public void ConfigureForRunningHostFailure(int? hostPid)
+    {
+        var pidHint = hostPid is > 0 ? $" Current host PID: {hostPid}." : string.Empty;
+        ApplyActionLayout(
+            title: "Startup is still pending",
+            suggestion: $"The desktop process is still running, so Launcher will not start a second instance.{pidHint}",
+            primaryLabel: "Activate",
+            primaryAction: ErrorWindowResult.ActivateExisting,
+            secondaryLabel: "Wait",
+            secondaryAction: ErrorWindowResult.ContinueWaiting);
+    }
+
+    public string? GetCustomHostPath() => _customHostPath;
+
+    public bool IsDevModeEnabled() => _devModeEnabled;
+
+    public Task<ErrorWindowResult> WaitForChoiceAsync() => _completionSource.Task;
+
+    public static bool CheckDevModeEnabled() => LoadDevModeStateInternal();
+
+    public static string? GetSavedCustomHostPath() => LoadCustomHostPathInternal();
+
+    private void OnWindowLoaded(object? sender, RoutedEventArgs e)
+    {
+        if (this.FindControl<Border>("ErrorIconBorder") is { } errorIconBorder)
+        {
+            errorIconBorder.PointerPressed += OnErrorIconClick;
+        }
+
+        if (this.FindControl<Button>("PrimaryActionButton") is { } primaryActionButton)
+        {
+            primaryActionButton.Click += OnPrimaryActionClick;
+        }
+
+        if (this.FindControl<Button>("SecondaryActionButton") is { } secondaryActionButton)
+        {
+            secondaryActionButton.Click += OnSecondaryActionClick;
+        }
+
+        if (this.FindControl<Button>("ExitButton") is { } exitButton)
+        {
+            exitButton.Click += (_, _) => _completionSource.TrySetResult(ErrorWindowResult.Exit);
+        }
+
+        if (this.FindControl<Button>("OpenLogButton") is { } openLogButton)
+        {
+            openLogButton.Click += OnOpenLogClick;
+        }
+    }
+
+    private void ApplyActionLayout(
+        string title,
+        string suggestion,
+        string primaryLabel,
+        ErrorWindowResult primaryAction,
+        string? secondaryLabel,
+        ErrorWindowResult? secondaryAction)
+    {
+        _primaryAction = primaryAction;
+        _secondaryAction = secondaryAction;
+
+        if (this.FindControl<TextBlock>("TitleText") is { } titleText && !_isDebugMode)
+        {
+            titleText.Text = title;
+        }
+
+        if (this.FindControl<TextBlock>("SuggestionText") is { } suggestionText)
+        {
+            suggestionText.Text = suggestion;
+        }
+
+        if (this.FindControl<Button>("PrimaryActionButton") is { } primaryButton)
+        {
+            primaryButton.Content = primaryLabel;
+        }
+
+        if (this.FindControl<Button>("SecondaryActionButton") is { } secondaryButton)
+        {
+            secondaryButton.IsVisible = !string.IsNullOrWhiteSpace(secondaryLabel);
+            secondaryButton.Content = secondaryLabel ?? string.Empty;
+        }
+    }
+
+    private void OnPrimaryActionClick(object? sender, RoutedEventArgs e)
+    {
+        _completionSource.TrySetResult(_primaryAction);
+    }
+
+    private void OnSecondaryActionClick(object? sender, RoutedEventArgs e)
+    {
+        _completionSource.TrySetResult(_secondaryAction ?? ErrorWindowResult.Exit);
+    }
+
+    private void OnErrorIconClick(object? sender, PointerPressedEventArgs e)
     {
         _iconClickCount++;
-
         if (_iconClickCount >= DebugModeClickThreshold && !_isDebugMode)
         {
             EnterDebugMode();
         }
     }
 
-    /// <summary>
-    /// 进入调试模式 - 显示调试窗口
-    /// </summary>
     private async void EnterDebugMode()
     {
         _isDebugMode = true;
 
-        // 创建并显示调试窗口
         var debugWindow = new ErrorDebugWindow(_devModeEnabled, _customHostPath)
         {
             WindowStartupLocation = WindowStartupLocation.CenterOwner
         };
 
-        // 订阅调试窗口关闭事件
-        debugWindow.Closed += (s, e) =>
+        debugWindow.Closed += (_, _) =>
         {
-            // 更新状态
+            if (!debugWindow.WasAccepted)
+            {
+                _isDebugMode = false;
+                _iconClickCount = 0;
+                return;
+            }
+
             _devModeEnabled = debugWindow.IsDevModeEnabled;
             _customHostPath = debugWindow.SelectedHostPath;
 
-            // 保存开发模式状态和自定义路径
-            SaveDevModeStateInternal(_devModeEnabled);
-            SaveCustomHostPathInternal(_customHostPath);
-
-            // 如果启用了开发模式且没有选择路径，自动扫描
-            if (_devModeEnabled && string.IsNullOrEmpty(_customHostPath))
+            if (_devModeEnabled && string.IsNullOrWhiteSpace(_customHostPath))
             {
                 ScanDevPaths();
-                // 扫描到路径后也保存
-                if (!string.IsNullOrEmpty(_customHostPath))
-                {
-                    SaveCustomHostPathInternal(_customHostPath);
-                }
             }
+
+            LauncherDebugSettingsStore.Save(new LauncherDebugSettings(_devModeEnabled, _customHostPath));
+
+            _isDebugMode = false;
+            _iconClickCount = 0;
         };
 
         await debugWindow.ShowDialog(this);
     }
 
-    /// <summary>
-    /// 扫描开发路径
-    /// </summary>
-    private void ScanDevPaths()
-    {
-        var executable = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
-        var possiblePaths = new[]
-        {
-            Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
-            Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
-            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
-            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
-            Path.Combine(AppContext.BaseDirectory, "..", "dev-test", "app-1.0.0-dev", executable),
-        };
-
-        foreach (var path in possiblePaths.Select(Path.GetFullPath).Distinct())
-        {
-            if (File.Exists(path))
-            {
-                _customHostPath = path;
-                break;
-            }
-        }
-    }
-
-    /// <summary>
-    /// 获取配置存储的基础目录
-    /// </summary>
-    private static string GetConfigBaseDirectory()
-    {
-        try
-        {
-            // 优先使用 LocalApplicationData（用户状态）
-            var appData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
-            if (!string.IsNullOrEmpty(appData))
-            {
-                var configDir = Path.Combine(appData, "LanMountainDesktop", ".launcher");
-                return configDir;
-            }
-        }
-        catch
-        {
-            // LocalApplicationData 不可用，回退到 Launcher 所在目录
-        }
-
-        // 回退方案：使用 Launcher 所在目录
-        try
-        {
-            var launcherDir = AppContext.BaseDirectory;
-            var configDir = Path.Combine(launcherDir, ".launcher");
-            return configDir;
-        }
-        catch
-        {
-            // 最后的兜底：使用当前目录
-            return Path.Combine(Directory.GetCurrentDirectory(), ".launcher");
-        }
-    }
-
-    /// <summary>
-    /// 确保配置目录存在
-    /// </summary>
-    private static bool EnsureConfigDirectory(string dirPath)
-    {
-        try
-        {
-            if (!Directory.Exists(dirPath))
-            {
-                Directory.CreateDirectory(dirPath);
-                Console.WriteLine($"[ErrorWindow] Created config directory: {dirPath}");
-            }
-            return true;
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to create config directory: {ex.Message}");
-            return false;
-        }
-    }
-
-    /// <summary>
-    /// 保存开发模式状态（内部方法）
-    /// </summary>
-    private static void SaveDevModeStateInternal(bool enabled)
-    {
-        try
-        {
-            var configDir = GetConfigBaseDirectory();
-            if (!EnsureConfigDirectory(configDir))
-            {
-                Console.Error.WriteLine("[ErrorWindow] Cannot save dev mode: config directory unavailable");
-                return;
-            }
-
-            var devModeFile = Path.Combine(configDir, "devmode.config");
-            File.WriteAllText(devModeFile, enabled ? "1" : "0");
-            Console.WriteLine($"[ErrorWindow] Dev mode state saved: {enabled}");
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to save dev mode state: {ex.Message}");
-        }
-    }
-
-    /// <summary>
-    /// 加载开发模式状态（内部方法）
-    /// </summary>
-    private static bool LoadDevModeStateInternal()
-    {
-        try
-        {
-            var configDir = GetConfigBaseDirectory();
-            var devModeFile = Path.Combine(configDir, "devmode.config");
-
-            if (File.Exists(devModeFile))
-            {
-                var content = File.ReadAllText(devModeFile).Trim();
-                var enabled = content == "1";
-                Console.WriteLine($"[ErrorWindow] Dev mode state loaded: {enabled}");
-                return enabled;
-            }
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to load dev mode state: {ex.Message}");
-        }
-        return false;
-    }
-
-    /// <summary>
-    /// 保存自定义主程序路径（内部方法）
-    /// </summary>
-    private static void SaveCustomHostPathInternal(string? path)
-    {
-        try
-        {
-            var configDir = GetConfigBaseDirectory();
-            if (!EnsureConfigDirectory(configDir))
-            {
-                Console.Error.WriteLine("[ErrorWindow] Cannot save custom path: config directory unavailable");
-                return;
-            }
-
-            var hostPathFile = Path.Combine(configDir, "custom-host-path.config");
-            File.WriteAllText(hostPathFile, path ?? string.Empty);
-            Console.WriteLine($"[ErrorWindow] Custom host path saved: {path}");
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to save custom host path: {ex.Message}");
-        }
-    }
-
-    /// <summary>
-    /// 加载自定义主程序路径（内部方法）
-    /// </summary>
-    private static string? LoadCustomHostPathInternal()
-    {
-        try
-        {
-            var configDir = GetConfigBaseDirectory();
-            var hostPathFile = Path.Combine(configDir, "custom-host-path.config");
-
-            if (File.Exists(hostPathFile))
-            {
-                var content = File.ReadAllText(hostPathFile).Trim();
-                // 验证路径是否仍然有效
-                if (!string.IsNullOrEmpty(content) && File.Exists(content))
-                {
-                    Console.WriteLine($"[ErrorWindow] Custom host path loaded: {content}");
-                    return content;
-                }
-
-                // 路径已失效，清理配置文件
-                if (!string.IsNullOrEmpty(content))
-                {
-                    Console.WriteLine($"[ErrorWindow] Custom host path is no longer valid: {content}");
-                    try
-                    {
-                        File.Delete(hostPathFile);
-                        Console.WriteLine("[ErrorWindow] Cleared invalid custom host path");
-                    }
-                    catch (Exception clearEx)
-                    {
-                        Console.Error.WriteLine($"[ErrorWindow] Failed to clear invalid host path: {clearEx.Message}");
-                    }
-                }
-            }
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to load custom host path: {ex.Message}");
-        }
-        return null;
-    }
-
-    /// <summary>
-    /// 检查是否启用了开发模式（静态方法，启动时调用）
-    /// </summary>
-    public static bool CheckDevModeEnabled()
-    {
-        return LoadDevModeStateInternal();
-    }
-
-    /// <summary>
-    /// 获取保存的自定义主程序路径（静态方法，启动时调用）
-    /// </summary>
-    public static string? GetSavedCustomHostPath()
-    {
-        return LoadCustomHostPathInternal();
-    }
-
-    private void OnRetryClick(object? sender, RoutedEventArgs e)
-    {
-        _completionSource.TrySetResult(ErrorWindowResult.Retry);
-    }
-
-    private void OnExitClick(object? sender, RoutedEventArgs e)
-    {
-        _completionSource.TrySetResult(ErrorWindowResult.Exit);
-    }
-
-    /// <summary>
-    /// 打开日志文件
-    /// </summary>
     private async void OnOpenLogClick(object? sender, RoutedEventArgs e)
     {
         try
         {
             var logFilePath = Logger.GetLogFilePath();
-
-            if (string.IsNullOrEmpty(logFilePath) || !File.Exists(logFilePath))
+            if (!string.IsNullOrWhiteSpace(logFilePath) && File.Exists(logFilePath))
             {
-                // 如果没有日志文件，打开日志目录
-                var logDir = Path.GetDirectoryName(logFilePath);
-                if (!string.IsNullOrEmpty(logDir) && Directory.Exists(logDir))
-                {
-                    OpenFolder(logDir);
-                }
-                else
-                {
-                    // 尝试打开配置目录
-                    var configDir = GetConfigBaseDirectory();
-                    if (Directory.Exists(configDir))
-                    {
-                        OpenFolder(configDir);
-                    }
-                    else
-                    {
-                        Console.WriteLine("[ErrorWindow] No log file or directory available");
-                    }
-                }
+                OpenPath(logFilePath);
                 return;
             }
 
-            Console.WriteLine($"[ErrorWindow] Opening log file: {logFilePath}");
-            OpenFile(logFilePath);
+            var logDirectory = !string.IsNullOrWhiteSpace(logFilePath)
+                ? Path.GetDirectoryName(logFilePath)
+                : null;
+            if (!string.IsNullOrWhiteSpace(logDirectory) && Directory.Exists(logDirectory))
+            {
+                OpenPath(logDirectory);
+                return;
+            }
+
+            var configDirectory = GetConfigBaseDirectory();
+            if (Directory.Exists(configDirectory))
+            {
+                OpenPath(configDirectory);
+            }
         }
         catch (Exception ex)
         {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to open log: {ex.Message}");
+            Debug.WriteLine($"[ErrorWindow] Failed to open log path: {ex}");
+        }
+
+        await Task.CompletedTask;
+    }
+
+    private void ScanDevPaths()
+    {
+        var executable = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
+        var candidatePaths = new[]
+        {
+            Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
+            Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
+            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
+            Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable)
+        };
+
+        foreach (var candidate in candidatePaths.Select(Path.GetFullPath).Distinct())
+        {
+            if (File.Exists(candidate))
+            {
+                _customHostPath = candidate;
+                break;
+            }
         }
     }
 
-    /// <summary>
-    /// 打开文件
-    /// </summary>
-    private static void OpenFile(string filePath)
+    private static void OpenPath(string path)
     {
-        try
+        if (OperatingSystem.IsWindows())
         {
-            if (OperatingSystem.IsWindows())
+            Process.Start(new ProcessStartInfo
             {
-                Process.Start(new ProcessStartInfo
-                {
-                    FileName = "explorer.exe",
-                    Arguments = $"\"{filePath}\"",
-                    UseShellExecute = true
-                });
-            }
-            else if (OperatingSystem.IsMacOS())
-            {
-                Process.Start("open", filePath);
-            }
-            else if (OperatingSystem.IsLinux())
-            {
-                Process.Start("xdg-open", filePath);
-            }
+                FileName = "explorer.exe",
+                Arguments = $"\"{path}\"",
+                UseShellExecute = true
+            });
+            return;
         }
-        catch (Exception ex)
+
+        if (OperatingSystem.IsMacOS())
         {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to open file: {ex.Message}");
+            Process.Start("open", path);
+            return;
+        }
+
+        if (OperatingSystem.IsLinux())
+        {
+            Process.Start("xdg-open", path);
         }
     }
 
-    /// <summary>
-    /// 打开文件夹
-    /// </summary>
-    private static void OpenFolder(string folderPath)
+    private static string GetConfigBaseDirectory()
     {
-        try
-        {
-            if (OperatingSystem.IsWindows())
-            {
-                Process.Start(new ProcessStartInfo
-                {
-                    FileName = "explorer.exe",
-                    Arguments = $"\"{folderPath}\"",
-                    UseShellExecute = true
-                });
-            }
-            else if (OperatingSystem.IsMacOS())
-            {
-                Process.Start("open", folderPath);
-            }
-            else if (OperatingSystem.IsLinux())
-            {
-                Process.Start("xdg-open", folderPath);
-            }
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"[ErrorWindow] Failed to open folder: {ex.Message}");
-        }
+        return LauncherDebugSettingsStore.ConfigBaseDirectory;
+    }
+
+    private static bool LoadDevModeStateInternal()
+    {
+        return LauncherDebugSettingsStore.IsDevModeEnabled();
+    }
+
+    private static string? LoadCustomHostPathInternal()
+    {
+        return LauncherDebugSettingsStore.GetSavedCustomHostPath();
     }
 }
 
-/// <summary>
-/// 错误窗口用户选择结果
-/// </summary>
 public enum ErrorWindowResult
 {
-    /// <summary>
-    /// 重试
-    /// </summary>
     Retry,
-
-    /// <summary>
-    /// 退出
-    /// </summary>
-    Exit
+    Exit,
+    ActivateExisting,
+    ContinueWaiting
 }

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"))
     };
 }
+

LanMountainDesktop.Launcher/Views/OobeWindow.axaml

@@ -4,14 +4,15 @@
         xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
         xmlns:views="clr-namespace:LanMountainDesktop.Launcher.Views"
         xmlns:ui="using:FluentAvalonia.UI.Controls"
+        xmlns:fi="using:FluentIcons.Avalonia"
         mc:Ignorable="d"
-        d:DesignWidth="600"
-        d:DesignHeight="500"
+        d:DesignWidth="850"
+        d:DesignHeight="650"
         x:Class="LanMountainDesktop.Launcher.Views.OobeWindow"
         x:DataType="views:OobeWindow"
         Title="欢迎使用阑山桌面"
-        Width="600"
-        Height="500"
+        Width="850"
+        Height="650"
         CanResize="False"
         WindowStartupLocation="CenterScreen"
         Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
@@ -22,54 +23,758 @@
   </Design.DataContext>
 
   <Grid x:Name="ContentGrid">
-    <!-- 主内容区域 -->
-    <Grid Margin="48" RowDefinitions="*,Auto">
-      <!-- 中央内容区域 -->
-      <StackPanel Grid.Row="0" 
-                  VerticalAlignment="Center" 
-                  HorizontalAlignment="Center"
-                  Spacing="24">
-        
-        <!-- 顶部：完成状态勾号图标 -->
-        <Border Width="80"
-                Height="80"
-                Background="{DynamicResource SystemFillColorSuccessBackgroundBrush}"
-                CornerRadius="40"
-                HorizontalAlignment="Center">
-          <ui:SymbolIcon Symbol="Accept"
-                         FontSize="40"
-                         Foreground="{DynamicResource SystemFillColorSuccessBrush}"
-                         HorizontalAlignment="Center"
-                         VerticalAlignment="Center"/>
-        </Border>
-        
-        <!-- 中央：欢迎文字 -->
-        <StackPanel Spacing="8" HorizontalAlignment="Center">
-          <TextBlock Text="欢迎使用阑山桌面"
+    <!-- 步骤 1: 打字机动画开场 -->
+    <Grid x:Name="TypingStep" Margin="60,80,60,60">
+      <!-- 主标题区域（左上角） -->
+      <StackPanel HorizontalAlignment="Left" VerticalAlignment="Top" Spacing="16">
+        <!-- 打字机文本区域 -->
+        <StackPanel Orientation="Horizontal">
+          <TextBlock x:Name="TypingTextBlock"
                      FontSize="28"
                      FontWeight="SemiBold"
                      Foreground="{DynamicResource TextFillColorPrimaryBrush}"
+                     FontFamily="Consolas, Monaco, 'Courier New', monospace" />
+          <Border x:Name="CursorBorder"
+                  Width="3"
+                  Height="28"
+                  Background="{DynamicResource TextFillColorPrimaryBrush}"
+                  VerticalAlignment="Bottom"
+                  Margin="4,0,0,4">
+            <Border.Styles>
+              <Style Selector="Border">
+                <Style.Animations>
+                  <Animation Duration="0:0:0.8" IterationCount="INFINITE">
+                    <KeyFrame Cue="0%">
+                      <Setter Property="Opacity" Value="1" />
+                    </KeyFrame>
+                    <KeyFrame Cue="50%">
+                      <Setter Property="Opacity" Value="1" />
+                    </KeyFrame>
+                    <KeyFrame Cue="51%">
+                      <Setter Property="Opacity" Value="0" />
+                    </KeyFrame>
+                    <KeyFrame Cue="100%">
+                      <Setter Property="Opacity" Value="0" />
+                    </KeyFrame>
+                  </Animation>
+                </Style.Animations>
+              </Style>
+            </Border.Styles>
+          </Border>
+        </StackPanel>
+
+        <!-- 副标题区域（流光渐变动画 + 打字机效果） -->
+        <StackPanel x:Name="SubtitlePanel" Opacity="0" IsVisible="False" Spacing="4">
+          <StackPanel Orientation="Horizontal">
+            <TextBlock x:Name="NextGenTextBlock"
+                       FontSize="48"
+                       FontWeight="Bold"
+                       FontFamily="Consolas, Monaco, 'Courier New', monospace">
+              <TextBlock.Foreground>
+                 <LinearGradientBrush StartPoint="0%,0%" EndPoint="100%,100%">
+                   <GradientStop Offset="0.0" Color="#0078D4" />
+                   <GradientStop Offset="0.33" Color="#7B68EE" />
+                   <GradientStop Offset="0.66" Color="#FF8C00" />
+                   <GradientStop Offset="1.0" Color="#107C10" />
+                 </LinearGradientBrush>
+               </TextBlock.Foreground>
+            </TextBlock>            <Border x:Name="SubtitleCursorBorder"
+                    Width="4"
+                    Height="48"
+                    Background="{DynamicResource TextFillColorPrimaryBrush}"
+                    VerticalAlignment="Bottom"
+                    Margin="4,0,0,4"
+                    IsVisible="False">
+              <Border.Styles>
+                <Style Selector="Border">
+                  <Style.Animations>
+                    <Animation Duration="0:0:0.8" IterationCount="INFINITE">
+                      <KeyFrame Cue="0%">
+                        <Setter Property="Opacity" Value="1" />
+                      </KeyFrame>
+                      <KeyFrame Cue="50%">
+                        <Setter Property="Opacity" Value="1" />
+                      </KeyFrame>
+                      <KeyFrame Cue="51%">
+                        <Setter Property="Opacity" Value="0" />
+                      </KeyFrame>
+                      <KeyFrame Cue="100%">
+                        <Setter Property="Opacity" Value="0" />
+                      </KeyFrame>
+                    </Animation>
+                  </Style.Animations>
+                </Style>
+              </Border.Styles>
+            </Border>
+          </StackPanel>
+          <TextBlock x:Name="DashboardTextBlock"
+                     FontSize="48"
+                     FontWeight="Bold"
+                     FontFamily="Consolas, Monaco, 'Courier New', monospace"
+                     Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        </StackPanel>
+      </StackPanel>
+
+      <!-- 按钮动画区域（左下角） -->
+      <Grid x:Name="ButtonAnimationArea"
+            Width="280"
+            Height="80"
+            HorizontalAlignment="Left"
+            VerticalAlignment="Bottom"
+            Margin="0,0,0,40"
+            IsVisible="False">
+
+        <!-- 方框边框（由鼠标画出） -->
+        <Border x:Name="DrawnBorder"
+                Width="160"
+                Height="56"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Background="Transparent"
+                BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                BorderThickness="0"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}">
+        </Border>
+
+        <!-- 开始按钮（从方框中弹出） -->
+        <Button x:Name="StartButton"
+                Width="160"
+                Height="56"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Theme="{DynamicResource AccentButtonTheme}"
+                Opacity="0"
+                IsVisible="False"
+                RenderTransformOrigin="0.5,0.5">
+          <Button.RenderTransform>
+            <ScaleTransform ScaleX="0.1" ScaleY="0.1" />
+          </Button.RenderTransform>
+          <TextBlock Text="开始使用"
+                     FontSize="16"
+                     FontWeight="SemiBold" />
+        </Button>
+
+        <!-- 鼠标光标 -->
+        <Canvas x:Name="MouseCursor"
+                Width="24"
+                Height="24"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Margin="-50,-50,0,0"
+                IsVisible="False">
+          <Path Data="M0,0 L0,18 L4,14 L7,20 L10,19 L7,13 L12,13 Z"
+                Fill="{DynamicResource TextFillColorPrimaryBrush}"
+                Stroke="{DynamicResource SolidBackgroundFillColorBaseBrush}"
+                StrokeThickness="1" />
+        </Canvas>
+      </Grid>
+    </Grid>
+
+    <!-- 步骤 2: 主题选择页面 -->
+    <Grid x:Name="ThemeStep" Margin="48" RowDefinitions="Auto,*,Auto" IsVisible="False">
+      <StackPanel Grid.Row="0" Spacing="8" Margin="0,0,0,24">
+        <TextBlock Text="个性化你的桌面"
+                   FontSize="24"
+                   FontWeight="SemiBold"
+                   Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        <TextBlock Text="选择你喜欢的主题样式，可随时在设置中更改"
+                   FontSize="13"
+                   Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+      </StackPanel>
+
+      <ScrollViewer Grid.Row="1" VerticalScrollBarVisibility="Auto">
+        <StackPanel Spacing="20">
+          <!-- 浅色/深色模式选择 -->
+          <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                  CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                  Padding="16">
+            <StackPanel Spacing="12">
+              <TextBlock Text="外观模式"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <Grid ColumnDefinitions="*,*" ColumnSpacing="12">
+                <Border x:Name="LightModeOption"
+                        Grid.Column="0"
+                        Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                        CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                        BorderThickness="2"
+                        BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                        Padding="16"
+                        Cursor="Hand">
+                  <StackPanel Spacing="8" HorizontalAlignment="Center">
+                    <Border Width="48"
+                            Height="48"
+                            Background="#F3F3F3"
+                            CornerRadius="8"
+                            BorderBrush="#E0E0E0"
+                            BorderThickness="1">
+                      <fi:SymbolIcon Symbol="WeatherSunny"
+                                     FontSize="24"
+                                     Foreground="#5F5F5F"
+                                     HorizontalAlignment="Center"
+                                     VerticalAlignment="Center"/>
+                    </Border>
+                    <TextBlock Text="浅色模式"
+                               FontSize="13"
+                               HorizontalAlignment="Center"
+                               Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                    <RadioButton x:Name="LightModeRadio"
+                                 GroupName="ThemeMode"
+                                 IsChecked="True"
+                                 HorizontalAlignment="Center" />
+                  </StackPanel>
+                </Border>
+
+                <Border x:Name="DarkModeOption"
+                        Grid.Column="1"
+                        Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                        CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                        BorderThickness="1"
+                        BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                        Padding="16"
+                        Cursor="Hand">
+                  <StackPanel Spacing="8" HorizontalAlignment="Center">
+                    <Border Width="48"
+                            Height="48"
+                            Background="#1E1E1E"
+                            CornerRadius="8"
+                            BorderBrush="#333333"
+                            BorderThickness="1">
+                      <fi:SymbolIcon Symbol="WeatherMoon"
+                                     FontSize="24"
+                                     Foreground="#E0E0E0"
+                                     HorizontalAlignment="Center"
+                                     VerticalAlignment="Center"/>
+                    </Border>
+                    <TextBlock Text="深色模式"
+                               FontSize="13"
+                               HorizontalAlignment="Center"
+                               Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                    <RadioButton x:Name="DarkModeRadio"
+                                 GroupName="ThemeMode"
+                                 HorizontalAlignment="Center" />
+                  </StackPanel>
+                </Border>
+              </Grid>
+            </StackPanel>
+          </Border>
+
+          <!-- 主题色选择 -->
+          <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                  CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                  Padding="16">
+            <StackPanel Spacing="12">
+              <TextBlock Text="主题色"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <WrapPanel x:Name="AccentColorPanel" HorizontalAlignment="Left">
+                <!-- 预设颜色 -->
+                <Border x:Name="BlueColor"
+                        Width="40"
+                        Height="40"
+                        Background="#0078D4"
+                        CornerRadius="20"
+                        BorderThickness="3"
+                        BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                        Margin="0,0,12,12"
+                        Cursor="Hand">
+                  <Border.Styles>
+                    <Style Selector="Border:pointerover">
+                      <Setter Property="RenderTransform" Value="scale(1.1)" />
+                    </Style>
+                  </Border.Styles>
+                </Border>
+                <Border x:Name="PurpleColor"
+                        Width="40"
+                        Height="40"
+                        Background="#7B68EE"
+                        CornerRadius="20"
+                        BorderThickness="0"
+                        Margin="0,0,12,12"
+                        Cursor="Hand" />
+                <Border x:Name="GreenColor"
+                        Width="40"
+                        Height="40"
+                        Background="#107C10"
+                        CornerRadius="20"
+                        BorderThickness="0"
+                        Margin="0,0,12,12"
+                        Cursor="Hand" />
+                <Border x:Name="OrangeColor"
+                        Width="40"
+                        Height="40"
+                        Background="#D83B01"
+                        CornerRadius="20"
+                        BorderThickness="0"
+                        Margin="0,0,12,12"
+                        Cursor="Hand" />
+                <Border x:Name="PinkColor"
+                        Width="40"
+                        Height="40"
+                        Background="#E3008C"
+                        CornerRadius="20"
+                        BorderThickness="0"
+                        Margin="0,0,12,12"
+                        Cursor="Hand" />
+                <Border x:Name="TealColor"
+                        Width="40"
+                        Height="40"
+                        Background="#008080"
+                        CornerRadius="20"
+                        BorderThickness="0"
+                        Margin="0,0,12,12"
+                        Cursor="Hand" />
+              </WrapPanel>
+            </StackPanel>
+          </Border>
+
+          <!-- 莫奈取色来源 -->
+          <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                  CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                  Padding="16">
+            <StackPanel Spacing="12">
+              <TextBlock Text="莫奈取色来源"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <TextBlock Text="从壁纸自动提取主题色，让界面与桌面完美融合"
+                         FontSize="12"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+
+              <StackPanel Spacing="8">
+                <Border x:Name="MonetFromWallpaperOption"
+                        Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                        CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                        BorderThickness="2"
+                        BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                        Padding="12"
+                        Cursor="Hand">
+                  <Grid ColumnDefinitions="Auto,*">
+                    <RadioButton x:Name="MonetFromWallpaperRadio"
+                                 Grid.Column="0"
+                                 GroupName="MonetSource"
+                                 IsChecked="True"
+                                 VerticalAlignment="Center"
+                                 Margin="0,0,12,0" />
+                    <StackPanel Grid.Column="1" Spacing="4">
+                      <TextBlock Text="从桌面壁纸取色"
+                                 FontSize="13"
+                                 FontWeight="SemiBold"
+                                 Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                      <TextBlock Text="自动分析当前壁纸颜色生成主题"
+                                 FontSize="11"
+                                 Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+                    </StackPanel>
+                  </Grid>
+                </Border>
+
+                <Border x:Name="MonetFromCustomOption"
+                        Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                        CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                        BorderThickness="1"
+                        BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                        Padding="12"
+                        Cursor="Hand">
+                  <Grid ColumnDefinitions="Auto,*">
+                    <RadioButton x:Name="MonetFromCustomRadio"
+                                 Grid.Column="0"
+                                 GroupName="MonetSource"
+                                 VerticalAlignment="Center"
+                                 Margin="0,0,12,0" />
+                    <StackPanel Grid.Column="1" Spacing="4">
+                      <TextBlock Text="自定义图片取色"
+                                 FontSize="13"
+                                 FontWeight="SemiBold"
+                                 Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                      <TextBlock Text="选择一张图片作为取色来源"
+                                 FontSize="11"
+                                 Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+                    </StackPanel>
+                  </Grid>
+                </Border>
+
+                <Border x:Name="MonetDisabledOption"
+                        Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                        CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                        BorderThickness="1"
+                        BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                        Padding="12"
+                        Cursor="Hand">
+                  <Grid ColumnDefinitions="Auto,*">
+                    <RadioButton x:Name="MonetDisabledRadio"
+                                 Grid.Column="0"
+                                 GroupName="MonetSource"
+                                 VerticalAlignment="Center"
+                                 Margin="0,0,12,0" />
+                    <StackPanel Grid.Column="1" Spacing="4">
+                      <TextBlock Text="不使用莫奈取色"
+                                 FontSize="13"
+                                 FontWeight="SemiBold"
+                                 Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                      <TextBlock Text="使用固定的预设主题色"
+                                 FontSize="11"
+                                 Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+                    </StackPanel>
+                  </Grid>
+                </Border>
+              </StackPanel>
+            </StackPanel>
+          </Border>
+        </StackPanel>
+      </ScrollViewer>
+
+      <StackPanel Grid.Row="2"
+                  Orientation="Horizontal"
+                  HorizontalAlignment="Right"
+                  Spacing="12"
+                  Margin="0,24,0,0">
+        <Button x:Name="ThemeBackButton"
+                Content="返回"
+                Theme="{DynamicResource ButtonTheme}" />
+        <Button x:Name="ThemeNextButton"
+                Content="下一步"
+                Theme="{DynamicResource AccentButtonTheme}" />
+      </StackPanel>
+    </Grid>
+
+    <!-- 步骤 3: 数据位置选择页面 -->
+    <Grid x:Name="DataLocationStep" Margin="48" RowDefinitions="Auto,*,Auto" IsVisible="False">
+      <StackPanel Grid.Row="0" Spacing="8" Margin="0,0,0,32">
+        <TextBlock Text="选择数据保存位置"
+                   FontSize="28"
+                   FontWeight="SemiBold"
+                   Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        <TextBlock Text="决定将应用数据保存在哪里，可随时在设置中更改"
+                   FontSize="14"
+                   Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+      </StackPanel>
+
+      <StackPanel Grid.Row="1" Spacing="20">
+        <Border x:Name="AdminWarningBanner"
+                Background="{DynamicResource SystemFillColorCriticalBackgroundBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16,12"
+                IsVisible="False">
+          <StackPanel Spacing="6">
+            <StackPanel Orientation="Horizontal" Spacing="8">
+              <fi:SymbolIcon Symbol="ShieldError"
+                             FontSize="20"
+                             Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+              <TextBlock Text="无法保存到应用目录"
+                         FontWeight="SemiBold"
+                         FontSize="14"
+                         Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+            </StackPanel>
+            <TextBlock Text="当前安装目录需要管理员权限才能写入，数据将自动保存到系统用户目录。"
+                       FontSize="13"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource SystemFillColorCriticalBrush}" />
+          </StackPanel>
+        </Border>
+
+        <!-- 系统用户目录选项 -->
+        <Border x:Name="SystemOptionBorder"
+                Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                BorderThickness="2"
+                BorderBrush="{DynamicResource AccentFillColorDefaultBrush}"
+                Padding="20,18"
+                Cursor="Hand">
+          <Grid ColumnDefinitions="Auto,*">
+            <RadioButton x:Name="SystemRadio"
+                         Grid.Column="0"
+                         VerticalAlignment="Center"
+                         Margin="0,0,16,0"
+                         GroupName="DataLocation"
+                         IsChecked="True" />
+            <StackPanel Grid.Column="1" Spacing="8">
+               <StackPanel Orientation="Horizontal" Spacing="8">
+                 <fi:SymbolIcon Symbol="Folder"
+                                FontSize="24"
+                                Foreground="{DynamicResource AccentFillColorDefaultBrush}" />
+                 <TextBlock Text="保存在系统用户目录（推荐）"
+                            FontSize="16"
+                            FontWeight="SemiBold"
+                            Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+               </StackPanel>
+              <TextBlock Text="数据与当前 Windows 用户绑定，重装应用或更新后数据不会丢失。适合大多数用户。"
+                         FontSize="13"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+              <Border Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                      CornerRadius="{DynamicResource DesignCornerRadiusSm}"
+                      Padding="12,8"
+                      Margin="0,4,0,0">
+                <TextBlock x:Name="SystemPathText"
+                           FontSize="12"
+                           TextWrapping="Wrap"
+                           Foreground="{DynamicResource TextFillColorTertiaryBrush}"
+                           FontFamily="Consolas, Monaco, monospace" />
+              </Border>
+            </StackPanel>
+          </Grid>
+        </Border>
+
+        <!-- 便携模式选项 -->
+        <Border x:Name="PortableOptionBorder"
+                Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                BorderThickness="1"
+                BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                Padding="20,18"
+                Cursor="Hand">
+          <Grid ColumnDefinitions="Auto,*">
+            <RadioButton x:Name="PortableRadio"
+                         Grid.Column="0"
+                         VerticalAlignment="Center"
+                         Margin="0,0,16,0"
+                         GroupName="DataLocation"
+                         IsEnabled="False" />
+            <StackPanel Grid.Column="1" Spacing="8">
+               <StackPanel Orientation="Horizontal" Spacing="8">
+                 <fi:SymbolIcon Symbol="Save"
+                                FontSize="24"
+                                Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+                 <TextBlock Text="保存在应用安装目录（便携模式）"
+                            FontSize="16"
+                            FontWeight="SemiBold"
+                            Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+               </StackPanel>
+              <TextBlock Text="便于携带，可随应用文件夹整体移动到其他电脑。适合在多台电脑间使用或需要便携运行的场景。"
+                         FontSize="13"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+              <Border Background="{DynamicResource SolidBackgroundFillColorQuarternaryBrush}"
+                      CornerRadius="{DynamicResource DesignCornerRadiusSm}"
+                      Padding="12,8"
+                      Margin="0,4,0,0">
+                <TextBlock x:Name="PortablePathText"
+                           FontSize="12"
+                           TextWrapping="Wrap"
+                           Foreground="{DynamicResource TextFillColorTertiaryBrush}"
+                           FontFamily="Consolas, Monaco, monospace" />
+              </Border>
+            </StackPanel>
+          </Grid>
+        </Border>
+
+        <!-- 数据迁移提示 -->
+        <Border x:Name="MigrationInfoBorder"
+                Background="{DynamicResource SystemFillColorSuccessBackgroundBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16,12"
+                IsVisible="False">
+          <StackPanel Orientation="Horizontal" Spacing="8">
+            <fi:SymbolIcon Symbol="Checkmark"
+                            FontSize="20"
+                            Foreground="{DynamicResource SystemFillColorSuccessBrush}" />
+            <TextBlock x:Name="MigrationInfoText"
+                       FontSize="13"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource SystemFillColorSuccessBrush}" />
+          </StackPanel>
+        </Border>
+      </StackPanel>
+
+      <StackPanel Grid.Row="2"
+                  Orientation="Horizontal"
+                  HorizontalAlignment="Right"
+                  Spacing="12"
+                  Margin="0,32,0,0">
+        <Button x:Name="DataLocationBackButton"
+                Content="返回"
+                Theme="{DynamicResource ButtonTheme}"
+                Width="100"
+                Height="36" />
+        <Button x:Name="DataLocationNextButton"
+                Content="下一步"
+                Theme="{DynamicResource AccentButtonTheme}"
+                Width="100"
+                Height="36" />
+      </StackPanel>
+    </Grid>
+
+    <!-- 步骤 4: 信息与隐私页面 -->
+    <Grid x:Name="PrivacyStep" Margin="48" RowDefinitions="Auto,*,Auto" IsVisible="False">
+      <StackPanel Grid.Row="0" Spacing="8" Margin="0,0,0,24">
+        <TextBlock Text="信息与隐私"
+                   FontSize="24"
+                   FontWeight="SemiBold"
+                   Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        <TextBlock Text="选择是否参与遥测计划，查看隐私政策"
+                   FontSize="13"
+                   Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+      </StackPanel>
+
+      <StackPanel Grid.Row="1" Spacing="16">
+        <!-- 崩溃报告 -->
+        <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16">
+          <Grid ColumnDefinitions="*,Auto">
+            <StackPanel Grid.Column="0" Spacing="4">
+              <TextBlock Text="发送匿名崩溃报告"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <TextBlock Text="帮助改进应用稳定性，不包含个人身份信息"
+                         FontSize="12"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+            </StackPanel>
+            <ToggleSwitch x:Name="CrashTelemetryToggle"
+                          Grid.Column="1"
+                          IsChecked="False"
+                          IsEnabled="False"
+                          VerticalAlignment="Center" />
+          </Grid>
+        </Border>
+
+        <!-- 使用统计 -->
+        <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16">
+          <Grid ColumnDefinitions="*,Auto">
+            <StackPanel Grid.Column="0" Spacing="4">
+              <TextBlock Text="发送匿名使用统计"
+                         FontSize="14"
+                         FontWeight="SemiBold"
+                         Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+              <TextBlock Text="帮助了解功能使用情况，优化产品体验"
+                         FontSize="12"
+                         TextWrapping="Wrap"
+                         Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+            </StackPanel>
+            <ToggleSwitch x:Name="UsageTelemetryToggle"
+                          Grid.Column="1"
+                          IsChecked="False"
+                          IsEnabled="False"
+                          VerticalAlignment="Center" />
+          </Grid>
+        </Border>
+
+        <!-- 隐私追踪 ID -->
+        <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16">
+          <StackPanel Spacing="8">
+            <TextBlock Text="隐私追踪 ID"
+                       FontSize="14"
+                       FontWeight="SemiBold"
+                       Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+            <TextBlock Text="此 ID 用于匿名标识您的设备，不包含任何个人信息"
+                       FontSize="12"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+            <TextBox x:Name="TelemetryIdTextBox"
+                     Text=""
+                     IsReadOnly="True"
+                     FontFamily="Consolas, Monaco, monospace"
+                     FontSize="12"
+                     HorizontalAlignment="Stretch" />
+          </StackPanel>
+        </Border>
+
+        <!-- 隐私协议同意区域 -->
+        <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                CornerRadius="{DynamicResource DesignCornerRadiusMd}"
+                Padding="16"
+                Margin="0,8,0,0">
+          <StackPanel Spacing="12">
+            <!-- 复选框和协议文本 -->
+            <StackPanel Orientation="Horizontal" Spacing="8">
+              <CheckBox x:Name="PrivacyAgreementCheckBox"
+                        VerticalAlignment="Center" />
+              <StackPanel Orientation="Horizontal" Spacing="4" VerticalAlignment="Center">
+                <TextBlock Text="同意"
+                           FontSize="13"
+                           VerticalAlignment="Center"
+                           Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+                <Button x:Name="ViewPrivacyPolicyButton"
+                        Content="《阑山桌面遥测隐私数据收集协议》"
+                        Background="Transparent"
+                        BorderThickness="0"
+                        Padding="0"
+                        FontSize="13"
+                        Foreground="{DynamicResource SystemAccentColor}">
+                  <Button.Styles>
+                    <Style Selector="Button:pointerover /template/ ContentPresenter">
+                      <Setter Property="TextBlock.Foreground" Value="{DynamicResource SystemAccentColorDark1}" />
+                    </Style>
+                  </Button.Styles>
+                </Button>
+              </StackPanel>
+            </StackPanel>
+
+            <!-- 提示文本 -->
+            <TextBlock Text="您必须阅读并同意隐私协议后，才能开启遥测功能。遥测数据仅用于改进应用稳定性和优化产品体验，不包含任何个人身份信息。"
+                       FontSize="12"
+                       TextWrapping="Wrap"
+                       Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+          </StackPanel>
+        </Border>
+      </StackPanel>
+
+      <StackPanel Grid.Row="2"
+                  Orientation="Horizontal"
+                  HorizontalAlignment="Right"
+                  Spacing="12"
+                  Margin="0,24,0,0">
+        <Button x:Name="PrivacyBackButton"
+                Content="返回"
+                Theme="{DynamicResource ButtonTheme}" />
+        <Button x:Name="PrivacyNextButton"
+                Content="下一步"
+                Theme="{DynamicResource AccentButtonTheme}" />
+      </StackPanel>
+    </Grid>
+
+    <!-- 步骤 5: 欢迎完成页面 -->
+    <Grid x:Name="WelcomeStep" Margin="48" RowDefinitions="*,Auto" IsVisible="False">
+      <StackPanel Grid.Row="0"
+                  VerticalAlignment="Center"
+                  HorizontalAlignment="Center"
+                  Spacing="32">
+
+        <Border Width="96"
+                Height="96"
+                Background="{DynamicResource SystemFillColorSuccessBackgroundBrush}"
+                CornerRadius="48"
+                HorizontalAlignment="Center">
+          <PathIcon Data="M9,16.17 L4.83,12 L3.41,13.41 L9,19 L21,7 L19.59,5.59 Z"
+                    Width="48"
+                    Height="48"
+                    Foreground="{DynamicResource SystemFillColorSuccessBrush}"
+                    HorizontalAlignment="Center"
+                    VerticalAlignment="Center"/>
+        </Border>
+
+        <StackPanel Spacing="12" HorizontalAlignment="Center">
+          <TextBlock Text="欢迎使用阑山桌面"
+                     FontSize="32"
+                     FontWeight="SemiBold"
+                     Foreground="{DynamicResource TextFillColorPrimaryBrush}"
                      HorizontalAlignment="Center" />
           <TextBlock Text="你的桌面，不止一面"
-                     FontSize="14"
+                     FontSize="16"
                      Foreground="{DynamicResource TextFillColorSecondaryBrush}"
                      HorizontalAlignment="Center" />
         </StackPanel>
-        
       </StackPanel>
 
-      <!-- 底部：圆形开始按钮 -->
       <Button Grid.Row="1"
               x:Name="EnterButton"
               HorizontalAlignment="Center"
               Width="56"
               Height="56"
-              Margin="0,0,0,16"
+              Margin="0,0,0,24"
               Theme="{DynamicResource AccentButtonTheme}"
               CornerRadius="28">
-        <ui:SymbolIcon Symbol="Forward"
+        <fi:SymbolIcon Symbol="ArrowRight"
                        FontSize="24"
-                       Foreground="{DynamicResource TextOnAccentFillColorPrimaryBrush}"/>
+                       Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>
       </Button>
     </Grid>
   </Grid>

LanMountainDesktop.Launcher/Views/PrivacyPolicyWindow.axaml

@@ -0,0 +1,63 @@
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+        xmlns:md="clr-namespace:Markdown.Avalonia;assembly=Markdown.Avalonia"
+        xmlns:views="clr-namespace:LanMountainDesktop.Launcher.Views"
+        mc:Ignorable="d"
+        x:Class="LanMountainDesktop.Launcher.Views.PrivacyPolicyWindow"
+        x:DataType="views:PrivacyPolicyViewModel"
+        Title="阑山桌面遥测隐私数据收集协议"
+        Width="800"
+        Height="600"
+        MinWidth="600"
+        MinHeight="400"
+        WindowStartupLocation="CenterOwner"
+        Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
+        TransparencyLevelHint="None"
+        Icon="/Assets/logo.ico">
+
+  <Grid RowDefinitions="Auto,*,Auto">
+    <!-- 标题栏 -->
+    <Border Grid.Row="0"
+            Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+            BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+            BorderThickness="0,0,0,1"
+            Padding="24,16">
+      <StackPanel Spacing="4">
+        <TextBlock Text="阑山桌面遥测隐私数据收集协议"
+                   FontSize="20"
+                   FontWeight="SemiBold"
+                   Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+        <TextBlock Text="请仔细阅读以下协议内容，了解我们如何收集、使用和保护您的数据"
+                   FontSize="13"
+                   Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
+      </StackPanel>
+    </Border>
+
+    <!-- Markdown 内容区域 -->
+    <Border Grid.Row="1"
+            Margin="24,16"
+            Background="{DynamicResource SolidBackgroundFillColorBaseBrush}">
+      <md:MarkdownScrollViewer x:Name="MarkdownViewer"
+                               Markdown="{Binding PrivacyPolicyMarkdown}"
+                               HorizontalAlignment="Stretch" />
+    </Border>
+
+    <!-- 底部按钮 -->
+    <Border Grid.Row="2"
+            Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+            BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+            BorderThickness="0,1,0,0"
+            Padding="24,16">
+      <StackPanel Orientation="Horizontal"
+                  HorizontalAlignment="Right"
+                  Spacing="12">
+        <Button x:Name="CloseButton"
+                Content="关闭"
+                Theme="{DynamicResource AccentButtonTheme}"
+                Width="100" />
+      </StackPanel>
+    </Border>
+  </Grid>
+</Window>

LanMountainDesktop.Launcher/Views/PrivacyPolicyWindow.axaml.cs

@@ -0,0 +1,121 @@
+using Avalonia.Controls;
+using Avalonia.Interactivity;
+using CommunityToolkit.Mvvm.ComponentModel;
+
+namespace LanMountainDesktop.Launcher.Views;
+
+public partial class PrivacyPolicyWindow : Window
+{
+    private readonly PrivacyPolicyViewModel _viewModel;
+
+    public PrivacyPolicyWindow()
+    {
+        InitializeComponent();
+        _viewModel = new PrivacyPolicyViewModel();
+        DataContext = _viewModel;
+
+        // 加载隐私政策内容
+        LoadPrivacyPolicy();
+
+        // 绑定关闭按钮事件
+        if (this.FindControl<Button>("CloseButton") is { } closeButton)
+        {
+            closeButton.Click += OnCloseClick;
+        }
+    }
+
+    private void OnCloseClick(object? sender, RoutedEventArgs e)
+    {
+        Close();
+    }
+
+    private void LoadPrivacyPolicy()
+    {
+        // 默认隐私政策内容（Markdown 格式）
+        _viewModel.PrivacyPolicyMarkdown = @"# 阑山桌面遥测隐私数据收集协议
+
+## 1. 概述
+
+欢迎使用阑山桌面！本协议旨在向您说明我们在应用运行过程中收集哪些数据、如何使用这些数据以及如何保护您的隐私。
+
+## 2. 我们收集的数据
+
+### 2.1 崩溃报告（可选）
+
+当应用发生崩溃时，我们可能会收集以下信息：
+
+- **崩溃类型**：应用程序崩溃、无响应等异常情况的类型
+- **错误堆栈**：导致崩溃的代码路径（不包含文件内容或个人数据）
+- **设备信息**：操作系统版本、应用版本、.NET 运行时版本
+- **匿名设备标识符**：一个随机生成的唯一标识符，用于统计崩溃频率
+
+**注意**：崩溃报告不包含您的个人文件、桌面组件内容、浏览历史或任何可识别个人身份的信息。
+
+### 2.2 使用统计（可选）
+
+如果您启用了使用统计，我们可能会收集：
+
+- **功能使用频率**：各功能模块的使用次数（如设置打开次数、组件添加次数）
+- **性能指标**：应用启动时间、内存占用范围等性能数据
+- **匿名设备标识符**：用于统计独立用户数量
+
+**注意**：使用统计不包含您的组件配置、个人设置或任何敏感信息。
+
+## 3. 我们不收集的数据
+
+我们明确**不会**收集以下信息：
+
+- ❌ 您的姓名、邮箱、电话号码等个人身份信息
+- ❌ 您的桌面截图或壁纸内容
+- ❌ 您添加的组件的具体内容或配置详情
+- ❌ 您的文件系统浏览记录
+- ❌ 您的网络活动或浏览历史
+- ❌ 您的精确地理位置信息
+
+## 4. 数据用途
+
+我们收集的数据仅用于以下目的：
+
+1. **改进应用稳定性**：通过分析崩溃报告，修复程序缺陷
+2. **优化产品体验**：了解功能使用情况，优先改进常用功能
+3. **性能优化**：识别性能瓶颈，提升应用运行效率
+
+## 5. 数据存储与保护
+
+- 所有数据通过**加密传输**（HTTPS）发送到我们的服务器
+- 数据存储在安全的服务器环境中，访问受到严格控制
+- 匿名设备标识符仅用于统计目的，无法关联到您的真实身份
+- 我们**不会**将数据出售或共享给任何第三方用于商业目的
+
+## 6. 您的控制权
+
+您拥有以下权利：
+
+- **随时开启或关闭**：您可以在 OOBE 向导或设置中随时更改遥测选项
+- **数据删除**：如果您希望删除已收集的数据，请联系我们的支持团队
+- **知情权**：您有权了解我们收集了哪些数据（通过本协议）
+
+## 7. 协议更新
+
+我们可能会不时更新本协议。重大变更时，我们会在应用内通知您。继续使用本应用即表示您同意修订后的协议。
+
+## 8. 联系我们
+
+如果您对本协议有任何疑问，请通过以下方式联系我们：
+
+- 项目主页：https://github.com/LanMountain/LanMountainDesktop
+- 问题反馈：在 GitHub 仓库提交 Issue
+
+---
+
+**最后更新日期**：2026年4月26日
+
+感谢您信任并使用阑山桌面！";
+    }
+}
+
+public partial class PrivacyPolicyViewModel : ObservableObject
+{
+    [ObservableProperty]
+    private string _privacyPolicyMarkdown = string.Empty;
+}

LanMountainDesktop.Launcher/Views/SplashWindow.axaml

@@ -3,85 +3,82 @@
         xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
         xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
         xmlns:views="clr-namespace:LanMountainDesktop.Launcher.Views"
-        xmlns:ui="using:FluentAvalonia.UI.Controls"
         mc:Ignorable="d"
-        d:DesignWidth="480"
-        d:DesignHeight="320"
         x:Class="LanMountainDesktop.Launcher.Views.SplashWindow"
         x:DataType="views:SplashWindow"
         Title="LanMountain Desktop"
         Width="480"
         Height="320"
         CanResize="False"
+        ShowInTaskbar="False"
         WindowStartupLocation="CenterScreen"
-        SystemDecorations="None"
-        Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
+        WindowDecorations="None"
+        Background="#0B0B0B"
         TransparencyLevelHint="None"
         Icon="/Assets/logo.ico">
   <Design.DataContext>
     <views:SplashWindow />
   </Design.DataContext>
 
-  <Grid>
-    <!-- 左上角：应用名称 -->
-    <TextBlock x:Name="AppNameText"
-               Text="LanMountain Desktop"
-               FontSize="24"
-               FontWeight="SemiBold"
-               VerticalAlignment="Top"
-               HorizontalAlignment="Left"
-               Margin="24,24,0,0"
-               Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
+  <Grid RowDefinitions="*,Auto">
+    <!-- 背景图片 -->
+    <Image x:Name="BackgroundImage"
+           Grid.RowSpan="2"
+           Stretch="UniformToFill"
+           IsVisible="False"
+           Opacity="0"/>
 
-    <!-- 底部区域：进度条和状态 -->
-    <Grid VerticalAlignment="Bottom" Margin="24,0,24,24">
-      <Grid.RowDefinitions>
-        <RowDefinition Height="Auto"/>
-        <RowDefinition Height="Auto"/>
-      </Grid.RowDefinitions>
-      
-      <!-- 第一行：左下角版本信息，右下角阶段文字 -->
-      <Grid Grid.Row="0" Margin="0,0,0,8">
-        <Grid.ColumnDefinitions>
-          <ColumnDefinition Width="*"/>
-          <ColumnDefinition Width="Auto"/>
-        </Grid.ColumnDefinitions>
-        
-        <!-- 左下角：版本和开发代号 - 可点击打开开发者界面（隐藏功能） -->
-        <Border x:Name="VersionTextBorder"
-                Grid.Column="0"
-                Background="Transparent"
-                Cursor="Hand"
-                HorizontalAlignment="Left"
-                VerticalAlignment="Bottom">
-          <TextBlock x:Name="VersionText"
-                     FontSize="11"
-                     Foreground="{DynamicResource TextFillColorSecondaryBrush}"
-                     Opacity="0.8"
-                     Text="1.0.0 (Administrate)" />
-        </Border>
-        
-        <!-- 右下角：阶段文字 -->
-        <TextBlock x:Name="StatusText"
-                   Grid.Column="1"
-                   FontSize="11"
-                   Foreground="{DynamicResource TextFillColorSecondaryBrush}"
-                   HorizontalAlignment="Right"
-                   VerticalAlignment="Bottom"
-                   Opacity="0.8"
-                   Text="Initializing..." />
-      </Grid>
-      
-      <!-- 底部：进度条 -->
-      <ProgressBar x:Name="ProgressIndicator"
-                   Grid.Row="1"
-                   Minimum="0"
-                   Maximum="100"
-                   Value="0"
-                   Height="4"
-                   IsIndeterminate="False"
-                   Foreground="{DynamicResource AccentFillColorDefaultBrush}"
-                   Background="{DynamicResource ControlStrokeColorDefaultBrush}" />
+    <!-- 半透明遮罩层 -->
+    <Border x:Name="BackgroundOverlay"
+            Grid.RowSpan="2"
+            Background="#0B0B0B"
+            Opacity="0.85"/>
+
+    <Grid Grid.Row="0"
+          Margin="24">
+      <TextBlock x:Name="AppNameText"
+                 Text="LanMountain Desktop"
+                 FontSize="24"
+                 FontWeight="SemiBold"
+                 VerticalAlignment="Top"
+                 HorizontalAlignment="Left"
+                 Foreground="#F6F7FB" />
     </Grid>
+
+    <Border Grid.Row="1"
+            Padding="24,18,24,24"
+            Background="Transparent">
+      <Grid RowDefinitions="Auto,Auto"
+            RowSpacing="10">
+        <Grid ColumnDefinitions="*,Auto">
+          <Border x:Name="VersionTextBorder"
+                  Background="Transparent"
+                  Cursor="Hand"
+                  HorizontalAlignment="Left">
+            <TextBlock x:Name="VersionText"
+                       FontSize="11"
+                       Foreground="#B9C0CC"
+                       Text="0.0.0-dev (Administrate)" />
+          </Border>
+
+          <TextBlock x:Name="StatusText"
+                     Grid.Column="1"
+                     FontSize="11"
+                     Foreground="#B9C0CC"
+                     HorizontalAlignment="Right"
+                     Text="Initializing..." />
+        </Grid>
+
+        <ProgressBar x:Name="ProgressIndicator"
+                     Grid.Row="1"
+                     Minimum="0"
+                     Maximum="100"
+                     Value="0"
+                     Height="4"
+                     IsIndeterminate="False"
+                     Foreground="#F6F7FB"
+                     Background="#2C313D" />
+      </Grid>
+    </Border>
   </Grid>
 </Window>

LanMountainDesktop.Launcher/Views/SplashWindow.axaml.cs

@@ -1,88 +1,228 @@
+using System.Diagnostics;
+using Avalonia;
 using Avalonia.Controls;
 using Avalonia.Input;
 using Avalonia.Interactivity;
 using Avalonia.Markup.Xaml;
+using Avalonia.Media;
 using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Services;
 
 namespace LanMountainDesktop.Launcher.Views;
 
-/// <summary>
-/// 启动画面窗口 - 简洁设计
-/// </summary>
 public partial class SplashWindow : Window, ISplashStageReporter
 {
-    private int _versionTextClickCount = 0;
     private const int DebugModeClickThreshold = 5;
-    private bool _isDebugModeOpened = false;
+    private static readonly TimeSpan FadeAnimationDuration = TimeSpan.FromMilliseconds(160);
+
+    private int _versionTextClickCount;
+    private bool _isDebugModeOpened;
+    private bool _isOpened;
+    private bool _dismissed;
 
     public SplashWindow()
     {
         AvaloniaXamlLoader.Load(this);
-        
-        // 延迟到窗口加载完成后再绑定事件
-        this.Loaded += OnWindowLoaded;
+        Loaded += OnWindowLoaded;
+        Opened += OnWindowOpened;
     }
 
-    /// <summary>
-    /// 窗口加载完成事件
-    /// </summary>
     private void OnWindowLoaded(object? sender, RoutedEventArgs e)
     {
-        Console.WriteLine("[SplashWindow] Window loaded, binding events...");
-        
-        // 绑定版本文本点击事件（隐藏功能：点击5次打开开发者界面）
-        var versionTextBorder = this.FindControl<Border>("VersionTextBorder");
-        if (versionTextBorder is not null)
+        InitializeBackgroundImage();
+
+        if (this.FindControl<Border>("VersionTextBorder") is { } versionBorder)
         {
-            versionTextBorder.PointerPressed += OnVersionTextClick;
-            Console.WriteLine("[SplashWindow] VersionTextBorder click event bound");
-        }
-        else
-        {
-            Console.Error.WriteLine("[SplashWindow] Failed to find VersionTextBorder!");
+            versionBorder.PointerPressed += OnVersionTextClick;
         }
     }
 
-    /// <summary>
-    /// 版本文本点击事件 - 连续点击5次打开开发者界面（隐藏功能）
-    /// </summary>
+    private void InitializeBackgroundImage()
+    {
+        try
+        {
+            var imageInfo = LauncherBackgroundService.LoadBackgroundImage();
+            if (imageInfo is { IsValid: true, Bitmap: not null })
+            {
+                if (this.FindControl<Image>("BackgroundImage") is { } backgroundImage)
+                {
+                    backgroundImage.Source = imageInfo.Bitmap;
+                    backgroundImage.IsVisible = true;
+                    backgroundImage.Opacity = 1;
+                }
+                Logger.Info("[SplashWindow] 背景图片加载成功");
+            }
+            else if (imageInfo is { Exists: true, IsValid: false })
+            {
+                Logger.Warn($"[SplashWindow] 背景图片校验失败: {imageInfo.ErrorMessage}");
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[SplashWindow] 加载背景图片失败: {ex.Message}");
+        }
+    }
+
+    private async void OnWindowOpened(object? sender, EventArgs e)
+    {
+        if (_isOpened)
+        {
+            return;
+        }
+
+        _isOpened = true;
+
+        Opacity = 0d;
+        await AnimateOpacityAsync(0d, 1d, FadeAnimationDuration).ConfigureAwait(false);
+    }
+
+    public async Task DismissAsync()
+    {
+        if (_dismissed)
+        {
+            return;
+        }
+
+        _dismissed = true;
+
+        if (!Dispatcher.UIThread.CheckAccess())
+        {
+            await Dispatcher.UIThread.InvokeAsync(async () => await DismissAsync());
+            return;
+        }
+
+        await AnimateOpacityAsync(Opacity, 0d, FadeAnimationDuration).ConfigureAwait(false);
+        Close();
+    }
+
+    public void Report(string stage, string message)
+    {
+        Dispatcher.UIThread.Post(() =>
+        {
+            if (this.FindControl<TextBlock>("StatusText") is { } statusText)
+            {
+                statusText.Text = message;
+            }
+
+            if (this.FindControl<ProgressBar>("ProgressIndicator") is { } progressIndicator)
+            {
+                var progress = ResolveProgress(stage);
+                if (progress > 0)
+                {
+                    progressIndicator.IsIndeterminate = false;
+                    progressIndicator.Value = progress;
+                }
+                else
+                {
+                    progressIndicator.IsIndeterminate = true;
+                }
+            }
+        });
+    }
+
+    public void ReportStage(string stage, int progress)
+    {
+        Dispatcher.UIThread.Post(() =>
+        {
+            if (this.FindControl<TextBlock>("StatusText") is { } statusText)
+            {
+                statusText.Text = stage;
+            }
+
+            if (this.FindControl<ProgressBar>("ProgressIndicator") is { } progressIndicator)
+            {
+                progressIndicator.IsIndeterminate = false;
+                progressIndicator.Value = Math.Clamp(progress, 0, 100);
+            }
+        });
+    }
+
+    public void UpdateProgress(int percent, string? message = null)
+    {
+        Dispatcher.UIThread.Post(() =>
+        {
+            if (!string.IsNullOrWhiteSpace(message) &&
+                this.FindControl<TextBlock>("StatusText") is { } statusText)
+            {
+                statusText.Text = message;
+            }
+
+            if (this.FindControl<ProgressBar>("ProgressIndicator") is { } progressIndicator)
+            {
+                progressIndicator.IsIndeterminate = false;
+                progressIndicator.Value = Math.Clamp(percent, 0, 100);
+            }
+        });
+    }
+
+    public void UpdateStatus(string message)
+    {
+        Dispatcher.UIThread.Post(() =>
+        {
+            if (this.FindControl<TextBlock>("StatusText") is { } statusText)
+            {
+                statusText.Text = message;
+            }
+        });
+    }
+
+    public void SetVersionInfo(string version, string codename)
+    {
+        Dispatcher.UIThread.Post(() =>
+        {
+            if (this.FindControl<TextBlock>("VersionText") is { } versionText)
+            {
+                versionText.Text = $"{version} ({codename})";
+            }
+        });
+    }
+
+    public void SetDebugMode(bool isDebugMode)
+    {
+        if (!isDebugMode)
+        {
+            return;
+        }
+
+        UpdateStatus("[Debug Mode] Splash Preview");
+    }
+
     private void OnVersionTextClick(object? sender, PointerPressedEventArgs e)
     {
-        if (_isDebugModeOpened) return;
-        
-        _versionTextClickCount++;
-        Console.WriteLine($"[SplashWindow] Version text clicked {_versionTextClickCount}/{DebugModeClickThreshold}");
+        if (_isDebugModeOpened)
+        {
+            return;
+        }
 
+        _versionTextClickCount++;
         if (_versionTextClickCount >= DebugModeClickThreshold)
         {
             OpenDebugWindow();
         }
     }
 
-    /// <summary>
-    /// 打开开发者调试窗口
-    /// </summary>
     private async void OpenDebugWindow()
     {
         _isDebugModeOpened = true;
-        Console.WriteLine("[SplashWindow] Opening debug window...");
 
         try
         {
-            // 加载保存的状态
-            var devModeEnabled = ErrorWindow.CheckDevModeEnabled();
-            var customHostPath = ErrorWindow.GetSavedCustomHostPath();
-
-            var debugWindow = new ErrorDebugWindow(devModeEnabled, customHostPath)
+            var debugWindow = new ErrorDebugWindow(
+                ErrorWindow.CheckDevModeEnabled(),
+                ErrorWindow.GetSavedCustomHostPath())
             {
-                WindowStartupLocation = WindowStartupLocation.CenterScreen
+                WindowStartupLocation = WindowStartupLocation.CenterOwner
             };
 
-            // 订阅窗口关闭事件以保存状态
-            debugWindow.Closed += (s, e) =>
+            debugWindow.Closed += (_, _) =>
             {
-                Console.WriteLine("[SplashWindow] Debug window closed");
+                if (debugWindow.WasAccepted)
+                {
+                    LauncherDebugSettingsStore.Save(new LauncherDebugSettings(
+                        debugWindow.IsDevModeEnabled,
+                        debugWindow.SelectedHostPath));
+                }
+
                 _isDebugModeOpened = false;
                 _versionTextClickCount = 0;
             };
@@ -91,160 +231,59 @@ public partial class SplashWindow : Window, ISplashStageReporter
         }
         catch (Exception ex)
         {
-            Console.Error.WriteLine($"[SplashWindow] Error opening debug window: {ex.Message}");
+            Debug.WriteLine($"[SplashWindow] Failed to open debug window: {ex}");
             _isDebugModeOpened = false;
             _versionTextClickCount = 0;
         }
     }
 
-    /// <summary>
-    /// 更新进度和状态
-    /// </summary>
-    public void Report(string stage, string message)
+    private async Task AnimateOpacityAsync(double from, double to, TimeSpan duration)
     {
-        Dispatcher.UIThread.Post(() =>
+        await AnimateAsync(progress =>
         {
-            var statusText = this.FindControl<TextBlock>("StatusText");
-            var progressIndicator = this.FindControl<ProgressBar>("ProgressIndicator");
-            
-            if (statusText is null || progressIndicator is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] Controls not found: StatusText={statusText != null}, ProgressIndicator={progressIndicator != null}");
-                return;
-            }
-
-            // 更新状态文本
-            statusText.Text = message;
-
-            // 根据阶段更新进度
-            var progress = ResolveProgress(stage);
-            if (progress > 0)
-            {
-                progressIndicator.IsIndeterminate = false;
-                progressIndicator.Value = progress;
-            }
-            else
-            {
-                progressIndicator.IsIndeterminate = true;
-            }
-        });
+            Opacity = from + ((to - from) * progress);
+        }, duration, EaseOutCubic).ConfigureAwait(false);
     }
 
-    /// <summary>
-    /// 更新进度（0-100）
-    /// </summary>
-    public void UpdateProgress(int percent, string? message = null)
+    private async Task AnimateAsync(Action<double> update, TimeSpan duration, Func<double, double> easing)
     {
-        Dispatcher.UIThread.Post(() =>
+        if (duration <= TimeSpan.Zero)
         {
-            var statusText = this.FindControl<TextBlock>("StatusText");
-            var progressIndicator = this.FindControl<ProgressBar>("ProgressIndicator");
-            
-            if (statusText is null || progressIndicator is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] Controls not found in UpdateProgress");
-                return;
-            }
+            await Dispatcher.UIThread.InvokeAsync(() => update(1d));
+            return;
+        }
 
-            if (!string.IsNullOrEmpty(message))
-            {
-                statusText.Text = message;
-            }
+        var stopwatch = Stopwatch.StartNew();
+        while (stopwatch.Elapsed < duration)
+        {
+            var raw = stopwatch.Elapsed.TotalMilliseconds / duration.TotalMilliseconds;
+            var progress = easing(Math.Clamp(raw, 0d, 1d));
+            await Dispatcher.UIThread.InvokeAsync(() => update(progress));
+            await Task.Delay(16).ConfigureAwait(false);
+        }
 
-            progressIndicator.IsIndeterminate = false;
-            progressIndicator.Value = Math.Clamp(percent, 0, 100);
-        });
+        await Dispatcher.UIThread.InvokeAsync(() => update(1d));
     }
 
-    /// <summary>
-    /// 更新状态文本
-    /// </summary>
-    public void UpdateStatus(string message)
-    {
-        Dispatcher.UIThread.Post(() =>
-        {
-            var statusText = this.FindControl<TextBlock>("StatusText");
-            if (statusText is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] StatusText not found in UpdateStatus");
-                return;
-            }
-            statusText.Text = message;
-        });
-    }
-
-    /// <summary>
-    /// 报告阶段和进度（0-100）
-    /// </summary>
-    public void ReportStage(string stage, int progress)
-    {
-        Dispatcher.UIThread.Post(() =>
-        {
-            var statusText = this.FindControl<TextBlock>("StatusText");
-            var progressIndicator = this.FindControl<ProgressBar>("ProgressIndicator");
-            
-            if (statusText is null || progressIndicator is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] Controls not found in ReportStage");
-                return;
-            }
-
-            statusText.Text = stage;
-            progressIndicator.IsIndeterminate = false;
-            progressIndicator.Value = Math.Clamp(progress, 0, 100);
-        });
-    }
-
-    /// <summary>
-    /// 设置版本和开发代号
-    /// </summary>
-    public void SetVersionInfo(string version, string codename)
-    {
-        Dispatcher.UIThread.Post(() =>
-        {
-            var versionText = this.FindControl<TextBlock>("VersionText");
-            if (versionText is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] VersionText not found in SetVersionInfo");
-                return;
-            }
-            versionText.Text = $"{version} ({codename})";
-        });
-    }
-
-    /// <summary>
-    /// 设置调试模式
-    /// </summary>
-    public void SetDebugMode(bool isDebugMode)
-    {
-        Dispatcher.UIThread.Post(() =>
-        {
-            var statusText = this.FindControl<TextBlock>("StatusText");
-            if (statusText is null)
-            {
-                Console.Error.WriteLine($"[SplashWindow] StatusText not found in SetDebugMode");
-                return;
-            }
-            if (isDebugMode)
-            {
-                statusText.Text = "[Debug Mode] Splash Preview";
-            }
-        });
-    }
-
-    /// <summary>
-    /// 根据阶段名称解析进度值
-    /// </summary>
     private static int ResolveProgress(string stage)
     {
         return stage.ToLowerInvariant() switch
         {
             "initializing" => 10,
+            "settings" => 25,
             "update" => 30,
             "plugins" => 50,
-            "launch" => 70,
+            "ui" => 65,
+            "shell" => 80,
+            "activation" => 90,
             "ready" => 100,
             _ => 0
         };
     }
+
+    private static double EaseOutCubic(double value)
+    {
+        var inverse = 1d - value;
+        return 1d - (inverse * inverse * inverse);
+    }
 }

LanMountainDesktop.Launcher/Views/UpdateWindow.axaml

@@ -13,7 +13,7 @@
         Height="320"
         CanResize="False"
         WindowStartupLocation="CenterScreen"
-        SystemDecorations="None"
+        WindowDecorations="None"
         Background="{DynamicResource SolidBackgroundFillColorBaseBrush}"
         TransparencyLevelHint="None"
         Icon="/Assets/logo.ico">

LanMountainDesktop.Launcher/app.manifest

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
-  <assemblyIdentity version="1.0.0.0" name="LanMountainDesktop.Launcher"/>
+  <assemblyIdentity version="0.0.0.0" name="LanMountainDesktop.Launcher"/>
   <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
     <security>
       <requestedPrivileges xmlns="urn:schemas-microsoft-com:asm.v3">

LanMountainDesktop.PluginIsolation.Contracts/AppearanceContracts.cs

@@ -0,0 +1,12 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginAppearanceSnapshotRequest(string SessionId);
+
+public sealed record PluginAppearanceSnapshot(
+    string ThemeVariant,
+    string? AccentColor = null,
+    double CornerRadiusScale = 1.0,
+    IReadOnlyDictionary<string, double>? CornerRadiusTokens = null,
+    IReadOnlyDictionary<string, string>? ResourceAliases = null);
+
+public sealed record PluginAppearanceChangedNotification(PluginAppearanceSnapshot Snapshot);

LanMountainDesktop.PluginIsolation.Contracts/DiagnosticsContracts.cs

@@ -0,0 +1,45 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginHeartbeatPing(
+    string SessionId,
+    DateTimeOffset SentAtUtc);
+
+public sealed record PluginHeartbeatPong(
+    string SessionId,
+    DateTimeOffset ReceivedAtUtc);
+
+public sealed record PluginLogEntry(
+    string Level,
+    string Category,
+    string Message,
+    DateTimeOffset TimestampUtc,
+    string? Exception = null);
+
+public static class PluginLogLevels
+{
+    public const string Trace = "trace";
+    public const string Debug = "debug";
+    public const string Information = "information";
+    public const string Warning = "warning";
+    public const string Error = "error";
+    public const string Critical = "critical";
+}
+
+public sealed record PluginFaultReport(
+    string SessionId,
+    string FaultKind,
+    bool IsFatal,
+    string Message,
+    string? StackTrace = null,
+    int? WorkerProcessId = null,
+    int? ExitCode = null,
+    DateTimeOffset? OccurredAtUtc = null);
+
+public static class PluginFaultKinds
+{
+    public const string ManagedException = "managed-exception";
+    public const string NativeCrash = "native-crash";
+    public const string WatchdogTimeout = "watchdog-timeout";
+    public const string StartupFailure = "startup-failure";
+    public const string ForcedTermination = "forced-termination";
+}

LanMountainDesktop.PluginIsolation.Contracts/LanMountainDesktop.PluginIsolation.Contracts.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Version>5.0.0</Version>
+    <PackageId>LanMountainDesktop.PluginIsolation.Contracts</PackageId>
+    <IsPackable>true</IsPackable>
+    <Authors>LanMountainDesktop</Authors>
+    <Description>Transport-neutral IPC contracts for the LanMountainDesktop plugin isolation architecture.</Description>
+    <PackageTags>LanMountainDesktop;Plugin;IPC;Isolation;Contracts</PackageTags>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <RepositoryUrl>https://github.com/wwiinnddyy/LanMountainDesktop</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageLicenseExpression>LGPL-3.0-or-later</PackageLicenseExpression>
+    <Copyright>Copyright (c) LanMountainDesktop Contributors</Copyright>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+</Project>

LanMountainDesktop.PluginIsolation.Contracts/LifecycleContracts.cs

@@ -0,0 +1,33 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginInitializeRequest(
+    string PluginId,
+    string SessionId,
+    string HostPipeName,
+    string DataDirectory,
+    IReadOnlyDictionary<string, string>? StartupProperties = null);
+
+public sealed record PluginInitializeResponse(
+    bool Succeeded,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginStopRequest(
+    string Reason,
+    bool RestartRequested = false);
+
+public sealed record PluginRestartRequest(string Reason);
+
+public sealed record PluginLifecycleStateChanged(
+    string State,
+    string? Detail = null);
+
+public static class PluginLifecycleStates
+{
+    public const string Starting = "starting";
+    public const string Ready = "ready";
+    public const string Degraded = "degraded";
+    public const string Stopping = "stopping";
+    public const string Stopped = "stopped";
+    public const string Faulted = "faulted";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginCapabilityDeclaration.cs

@@ -0,0 +1,17 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginCapabilityDeclaration(
+    string Name,
+    string Version,
+    string? Description = null);
+
+public static class PluginCapabilityNames
+{
+    public const string Settings = "settings";
+    public const string Appearance = "appearance";
+    public const string DesktopComponentUi = "ui.desktop-component";
+    public const string ComponentEditorUi = "ui.component-editor";
+    public const string SettingsPageUi = "ui.settings-page";
+    public const string Logging = "diagnostics.log";
+    public const string FaultReporting = "diagnostics.fault";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIpcErrorCodes.cs

@@ -0,0 +1,15 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIpcErrorCodes
+{
+    public const string ProtocolMismatch = "protocol_mismatch";
+    public const string SessionRejected = "session_rejected";
+    public const string CapabilityDenied = "capability_denied";
+    public const string InvalidRequest = "invalid_request";
+    public const string UnsupportedRoute = "unsupported_route";
+    public const string SettingsConflict = "settings_conflict";
+    public const string UiAttachRejected = "ui_attach_rejected";
+    public const string WorkerFaulted = "worker_faulted";
+    public const string WorkerExited = "worker_exited";
+    public const string HeartbeatTimeout = "heartbeat_timeout";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIpcRoutes.cs

@@ -0,0 +1,56 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIpcRoutes
+{
+    public static class Session
+    {
+        public const string Handshake = "session/handshake";
+        public const string Capabilities = "session/capabilities";
+        public const string Ready = "session/ready";
+    }
+
+    public static class Lifecycle
+    {
+        public const string Initialize = "lifecycle/initialize";
+        public const string Stop = "lifecycle/stop";
+        public const string RestartRequest = "lifecycle/restart-request";
+        public const string StateChanged = "lifecycle/state-changed";
+    }
+
+    public static class Settings
+    {
+        public const string GetSnapshot = "settings/get-snapshot";
+        public const string Write = "settings/write";
+        public const string Changed = "settings/changed";
+    }
+
+    public static class Appearance
+    {
+        public const string GetSnapshot = "appearance/get-snapshot";
+        public const string Changed = "appearance/changed";
+    }
+
+    public static class Ui
+    {
+        public const string Attach = "ui/attach";
+        public const string Detach = "ui/detach";
+        public const string Command = "ui/command";
+        public const string StateChanged = "ui/state-changed";
+    }
+
+    public static class Heartbeat
+    {
+        public const string Ping = "heartbeat/ping";
+        public const string Pong = "heartbeat/pong";
+    }
+
+    public static class Log
+    {
+        public const string Write = "log/write";
+    }
+
+    public static class Fault
+    {
+        public const string Report = "fault/report";
+    }
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIsolationJsonContext.cs

@@ -0,0 +1,39 @@
+using System.Text.Json.Serialization;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+[JsonSourceGenerationOptions(
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
+    PropertyNameCaseInsensitive = true,
+    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
+[JsonSerializable(typeof(PluginCapabilityDeclaration))]
+[JsonSerializable(typeof(List<PluginCapabilityDeclaration>))]
+[JsonSerializable(typeof(PluginSessionHandshakeRequest))]
+[JsonSerializable(typeof(PluginSessionHandshakeResponse))]
+[JsonSerializable(typeof(PluginReadyNotification))]
+[JsonSerializable(typeof(PluginInitializeRequest))]
+[JsonSerializable(typeof(PluginInitializeResponse))]
+[JsonSerializable(typeof(PluginStopRequest))]
+[JsonSerializable(typeof(PluginRestartRequest))]
+[JsonSerializable(typeof(PluginLifecycleStateChanged))]
+[JsonSerializable(typeof(PluginSettingsSnapshotRequest))]
+[JsonSerializable(typeof(PluginSettingsSnapshotResponse))]
+[JsonSerializable(typeof(PluginSettingsWriteRequest))]
+[JsonSerializable(typeof(PluginSettingsWriteResponse))]
+[JsonSerializable(typeof(PluginSettingsChangedNotification))]
+[JsonSerializable(typeof(PluginAppearanceSnapshotRequest))]
+[JsonSerializable(typeof(PluginAppearanceSnapshot))]
+[JsonSerializable(typeof(PluginAppearanceChangedNotification))]
+[JsonSerializable(typeof(PluginUiSurfaceDescriptor))]
+[JsonSerializable(typeof(List<PluginUiSurfaceDescriptor>))]
+[JsonSerializable(typeof(PluginUiAttachRequest))]
+[JsonSerializable(typeof(PluginUiAttachResponse))]
+[JsonSerializable(typeof(PluginUiDetachNotification))]
+[JsonSerializable(typeof(PluginUiCommandRequest))]
+[JsonSerializable(typeof(PluginUiCommandResponse))]
+[JsonSerializable(typeof(PluginUiStateChangedNotification))]
+[JsonSerializable(typeof(PluginHeartbeatPing))]
+[JsonSerializable(typeof(PluginHeartbeatPong))]
+[JsonSerializable(typeof(PluginLogEntry))]
+[JsonSerializable(typeof(PluginFaultReport))]
+public partial class PluginIsolationJsonContext : JsonSerializerContext;

LanMountainDesktop.PluginIsolation.Contracts/PluginIsolationProtocolVersion.cs

@@ -0,0 +1,6 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIsolationProtocolVersion
+{
+    public const string Current = "1.0";
+}

LanMountainDesktop.PluginIsolation.Contracts/README.md

@@ -0,0 +1,9 @@
+# LanMountainDesktop.PluginIsolation.Contracts
+
+Transport-neutral DTOs, route constants, protocol versioning, and JSON serialization context for plugin process isolation.
+
+## Includes
+
+- route groups for session, lifecycle, settings, appearance, UI, heartbeat, log, and fault
+- explicit DTOs for routed request and notification payloads
+- source-generated `System.Text.Json` context for the IPC protocol

LanMountainDesktop.PluginIsolation.Contracts/SessionContracts.cs

@@ -0,0 +1,21 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginSessionHandshakeRequest(
+    string PluginId,
+    string SessionId,
+    string RuntimeMode,
+    string ProtocolVersion,
+    IReadOnlyList<PluginCapabilityDeclaration>? RequestedCapabilities = null,
+    IReadOnlyDictionary<string, string>? Metadata = null);
+
+public sealed record PluginSessionHandshakeResponse(
+    bool Accepted,
+    string ProtocolVersion,
+    IReadOnlyList<PluginCapabilityDeclaration>? GrantedCapabilities = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginReadyNotification(
+    string PluginId,
+    string SessionId,
+    IReadOnlyList<PluginUiSurfaceDescriptor>? UiSurfaces = null);

LanMountainDesktop.PluginIsolation.Contracts/SettingsContracts.cs

@@ -0,0 +1,33 @@
+using System.Text.Json;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginSettingsSnapshotRequest(
+    string Scope,
+    string? SectionId = null,
+    string? ComponentInstanceId = null);
+
+public sealed record PluginSettingsSnapshotResponse(
+    string Scope,
+    JsonElement Snapshot,
+    string? ETag = null);
+
+public sealed record PluginSettingsWriteRequest(
+    string Scope,
+    JsonElement Value,
+    string? SectionId = null,
+    string? ComponentInstanceId = null,
+    string? ETag = null);
+
+public sealed record PluginSettingsWriteResponse(
+    bool Accepted,
+    string? ETag = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginSettingsChangedNotification(
+    string Scope,
+    JsonElement Value,
+    string? SectionId = null,
+    string? ComponentInstanceId = null,
+    string? ETag = null);

LanMountainDesktop.PluginIsolation.Contracts/UiContracts.cs

@@ -0,0 +1,52 @@
+using System.Text.Json;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginUiSurfaceDescriptor(
+    string SurfaceId,
+    string SurfaceKind,
+    string Title,
+    string? ComponentId = null);
+
+public static class PluginUiSurfaceKinds
+{
+    public const string DesktopComponent = "desktop-component";
+    public const string ComponentEditor = "component-editor";
+    public const string SettingsPage = "settings-page";
+    public const string Window = "window";
+}
+
+public sealed record PluginUiAttachRequest(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null,
+    JsonElement? InitialState = null);
+
+public sealed record PluginUiAttachResponse(
+    bool Accepted,
+    JsonElement? InitialState = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginUiDetachNotification(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null);
+
+public sealed record PluginUiCommandRequest(
+    string SurfaceId,
+    string CommandName,
+    string? InstanceId = null,
+    JsonElement? Payload = null);
+
+public sealed record PluginUiCommandResponse(
+    bool Accepted,
+    JsonElement? Payload = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginUiStateChangedNotification(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null,
+    JsonElement? State = null);