LanMountainDesktop/docs/04-架构与实现/01-整体架构.md

整体架构

本文档描述阑山桌面的整体技术架构、各模块职责和交互方式。

架构概览

核心模块

┌─────────────────────────────────────────────────────────────┐
│                     用户交互层                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │桌面组件   │  │主窗口     │  │托盘图标   │  │设置窗口   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              LanMountainDesktop（桌面宿主）                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   组件系统                             │  │
│  │   组件注册 | 组件渲染 | 布局管理 | 编辑模式            │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   插件运行时                           │  │
│  │   插件加载 | 生命周期 | SDK 接入 | 契约装配            │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   核心服务层                           │  │
│  │   设置 | 主题 | 本地化 | 日志 | 遥测 | IPC             │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
              ↓                           ↓
┌──────────────────────┐    ┌──────────────────────────────┐
│ LanMountainDesktop   │    │ LanMountainDesktop          │
│   .AirAppRuntime     │←IPC→│   .AirAppHost (多实例)       │
│  Air APP 运行时容器   │    │  Air APP 渲染进程            │
└──────────────────────┘    └──────────────────────────────┘
              ↑
┌──────────────────────┐
│ LanMountainDesktop   │
│   .Launcher          │
│  启动器 (唯一入口)     │
└──────────────────────┘

项目结构

核心项目

项目	职责	类型
LanMountainDesktop	桌面宿主主程序	WPF 应用
LanMountainDesktop.Launcher	启动器（OOBE、Splash、版本管理）	独立可执行
LanMountainDesktop.AirAppRuntime	Air APP 运行时容器	独立服务
LanMountainDesktop.AirAppHost	Air APP 渲染进程	框架依赖应用

SDK 和基础设施

项目	职责	类型
LanMountainDesktop.PluginSdk	插件 SDK	NuGet 包
LanMountainDesktop.AirAppSdk	Air APP SDK	NuGet 包
LanMountainDesktop.Shared.Contracts	共享契约类型	类库
LanMountainDesktop.Shared.IPC	IPC 基础设施	类库

功能模块

项目	职责	类型
LanMountainDesktop.Settings.Core	设置系统	类库
LanMountainDesktop.Appearance	主题和外观	类库
LanMountainDesktop.DesktopComponents.Runtime	组件运行时	类库
LanMountainDesktop.DesktopHost	桌面宿主生命周期	类库

未来扩展（计划中）

项目	职责	状态
LanMountainDesktop.PluginIsolation.Contracts	插件隔离契约	已创建
LanMountainDesktop.PluginIsolation.Ipc	插件隔离 IPC	已创建

启动流程

生产环境启动

1. 用户启动 Launcher.exe
         ↓
2. 首次启动？ → 是 → 显示 OOBE 欢迎页
         ↓ 否
3. 显示 Splash 启动动画
         ↓
4. 扫描 app-* 目录，选择最佳版本
   - 优先选择有 .current 标记的
   - 其次选择版本号最高的
   - 跳过有 .partial 或 .destroy 标记的
         ↓
5. 预启动 AirAppRuntime.exe
   - JIT 框架依赖进程
   - 等待 IPC 管道就绪
         ↓
6. 启动 app-{version}/LanMountainDesktop.exe
         ↓
7. Host 初始化
   - 日志系统
   - 遥测系统
   - 设置加载
   - 主题应用
         ↓
8. 初始化桌面环境
   - 创建桌面窗口
   - 加载插件
   - 注册组件
   - 显示托盘图标
         ↓
9. 将 Host PID 附加给 AirAppRuntime
         ↓
10. 清理标记为 .destroy 的旧版本
         ↓
11. 桌面就绪

开发环境启动

开发者直接启动 LanMountainDesktop.exe
         ↓
检测到没有通过 Launcher 启动
         ↓
跳过 OOBE 和版本管理
         ↓
如果 AirAppRuntime 未运行，自动启动
         ↓
正常初始化桌面环境

核心系统

1. 组件系统

职责: 管理桌面组件的注册、创建、渲染和布局

架构:

ComponentRegistry (组件注册表)
    ↓ 注册
ComponentDefinition (组件定义)
    ↓ 创建实例
ComponentInstance (组件实例)
    ↓ 渲染
ComponentView (Avalonia UI)
    ↓ 显示
DesktopWidgetWindow (桌面窗口)

关键类:

• ComponentRegistry - 组件注册和查找
• ComponentBase - 组件基类
• ComponentInstanceManager - 组件实例管理
• DesktopLayoutService - 布局管理

2. 插件系统

职责: 加载、初始化和管理插件生命周期

运行时模式:

模式	状态	说明
in-proc	✅ 当前默认	插件运行在宿主进程内
isolated-background	🚧 规划中	后台逻辑隔离进程
isolated-window	🚧 规划中	UI 渲染隔离进程

加载流程:

1. 扫描插件目录
   %LOCALAPPDATA%\LanMountainDesktop\plugins\
         ↓
2. 读取 plugin.json 清单
         ↓
3. 验证依赖关系
         ↓
4. 创建 PluginLoadContext
         ↓
5. 加载插件程序集
         ↓
6. 创建 IPlugin 实例
         ↓
7. 调用 InitializeAsync()
         ↓
8. 注册组件和服务

3. 设置系统

职责: 管理应用和插件的配置数据

设置域:

Settings Root
├── General (通用设置)
├── Appearance (外观设置)
├── Components (组件设置)
├── Plugins (插件设置)
│   ├── Plugin A
│   └── Plugin B
└── Advanced (高级设置)

持久化:

• 位置: %LOCALAPPDATA%\LanMountainDesktop\settings\
• 格式: JSON
• 实时保存，延迟写入

4. 主题系统

职责: 管理亮色/暗色主题、圆角系统

圆角规范:

级别	Token	值	用途
基础	DesignCornerRadiusBasic	4	按钮、输入框
组件	DesignCornerRadiusComponent	8	卡片、面板
窗口	DesignCornerRadiusWindow	12	窗口、对话框

主题切换:

1. 用户选择主题
2. AppearanceService 切换资源字典
3. 广播主题变更事件
4. 各组件响应并更新 UI
5. 通过 IPC 通知 Air APP

5. IPC 系统

职责: 进程间通信

通信拓扑:

┌────────────────┐
│     Host       │ ← 外部 IPC 入口点
│  (主程序)       │
└────────┬───────┘
         │ IPC
    ┌────┴────┐
    ↓         ↓
┌────────┐ ┌────────────┐
│Launcher│ │AirAppRuntime│
└────────┘ └──────┬──────┘
                  │ IPC
            ┌─────┴─────┐
            ↓           ↓
      ┌─────────┐ ┌─────────┐
      │AirAppHost│ │AirAppHost│
      └─────────┘ └─────────┘

IPC 管道:

• LanMountainDesktop.Host.v1 - 宿主公共服务
• LanMountainDesktop.AirAppRuntime.v1 - Air APP 生命周期
• LanMountainDesktop.AirAppRuntimeControl.v1 - Runtime 控制

数据流

设置变更流程

用户修改设置
    ↓
SettingsService.SetValue()
    ↓
触发 SettingChanged 事件
    ↓
相关组件监听并响应
    ↓
延迟写入磁盘（防抖 500ms）

组件更新流程

定时器触发 (默认 1 秒)
    ↓
ComponentUpdateService.UpdateAsync()
    ↓
遍历所有组件实例
    ↓
调用 Component.UpdateAsync()
    ↓
组件更新数据
    ↓
UI 自动刷新（数据绑定）

插件通信流程

Plugin A 发送消息
    ↓
PluginMessenger.Send()
    ↓
消息总线分发
    ↓
Plugin B 接收消息
    ↓
处理并可选回复

安全性

权限系统

插件需要声明所需权限：

{
  "Permissions": [
    "FileSystem.Read",      // 读取文件
    "FileSystem.Write",     // 写入文件
    "Network.Access",       // 网络访问
    "System.Info"           // 系统信息
  ]
}

沙箱隔离（未来）

进程隔离模式下：

• 插件运行在独立进程
• 通过 IPC 访问宿主服务
• 限制文件系统访问
• 限制网络访问

性能优化

启动优化

• ✅ 延迟加载插件
• ✅ 异步初始化
• ✅ 组件按需创建
• ✅ 资源延迟加载

运行时优化

• ✅ 虚拟化列表
• ✅ 图片缓存
• ✅ 布局缓存
• ✅ 事件防抖/节流

内存优化

• ✅ 弱事件模式
• ✅ 及时释放资源
• ✅ 图片降采样
• ✅ 组件卸载清理

相关文档

• 启动器系统 - 启动器详细设计
• 插件运行时 - 插件加载和管理
• 组件系统 - 组件架构和渲染
• IPC 通信 - 进程间通信设计