docs: 跨平台架构文档、共享库审计报告与 Android CI 构建

docs/CROSS_PLATFORM.md

@@ -0,0 +1,92 @@
+# 跨平台架构说明
+
+> 本文档描述阑山桌面的跨平台（桌面 + 移动）架构方案与分层约束。
+> 当前目标平台：Windows（主力）、Linux/macOS（桌面构建）、Android（移动端）。iOS 暂不在范围内。
+
+## 1. 总体分层
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Heads（平台入口）                                    │
+│  LanMountainDesktop（WinExe 桌面宿主）                │
+│  LanMountainDesktop.Mobile.Android（Android head）    │
+├─────────────────────────────────────────────────────┤
+│  共享 UI 层                                          │
+│  LanMountainDesktop.Mobile（移动壳/组件面板）          │
+│  ComponentSystem / Controls / Theme（随桌面宿主）      │
+├─────────────────────────────────────────────────────┤
+│  平台差异层（Platform）                               │
+│  LanMountainDesktop.Platform.Abstractions（接口）     │
+│  LanMountainDesktop.Platform.Windows（Windows 实现）  │
+│  （后续按需增加 Platform.Android / Platform.MacOS）    │
+├─────────────────────────────────────────────────────┤
+│  共享核心层（必须无平台依赖）                          │
+│  Shared.Contracts / Shared.IPC / Settings.Core        │
+│  Appearance / DesktopComponents.Runtime / PluginSdk   │
+│  Host.Abstractions / PluginIsolation.Contracts        │
+└─────────────────────────────────────────────────────┘
+```
+
+## 1.1 当前落地状态
+
+- ✅ `Platform.Abstractions`：接口 + NoOp 实现 + `PlatformLog` 日志桥
+- ✅ `Platform.Windows`：电源管理、原生对话框、桌面层嵌入、窗口置底/区域穿透、
+  DWM 互操作、图标服务（WindowsIconService/UwpManifestIconResolver）、包标识查询
+- ✅ `Platform.MacOS`：MacIconService
+- ✅ `Platform.Android`：骨架（后续按需填充）
+- ✅ `Mobile` + `Mobile.Android`：单视图组件面板壳，APK 可构建
+- ✅ 主工程 `LanMountainDesktop` 已无任何 DllImport/LibraryImport
+- ✅ PluginIsolation.Ipc 新增 `InProcPluginIpcTransport`（进程内直通，含测试）
+
+主工程保留的平台相关内容（有意为之）：
+- `WindowsNotificationListener` / `WindowsSmtcMusicControlService` / `LocationService`
+  的 WinRT **反射**调用路径（无编译期平台依赖，运行时 `OperatingSystem.IsWindows()` 保护），
+  P/Invoke 部分已抽到 `Platform.Windows.WindowsPackageIdentity`。
+- `LinuxPowerManagementService`（纯命令行调用，无平台 API）。
+- 静态工厂门面（`*ServiceFactory`）留在 `LanMountainDesktop.Services` 命名空间，
+  保持既有调用点不变，内部委托平台实现。
+
+## 2. Platform 层规则
+
+- 所有 P/Invoke、`DllImport`/`LibraryImport`、Windows 注册表、COM/Office 互操作等平台专属代码，
+  一律放入 `LanMountainDesktop.Platform.<平台>` 项目，禁止出现在主工程与共享层。
+- `Platform.Abstractions` 只包含接口、跨平台 DTO 与 Null/NoOp 兜底实现。
+- Head 项目在启动时负责注册对应平台实现（桌面注册 Windows 实现，Android 注册移动实现或 NoOp）。
+
+## 3. 插件体系的平台策略
+
+| 能力 | 桌面 | Android |
+|---|---|---|
+| 插件契约（PluginSdk / PluginIsolation.Contracts） | 保留 | 保留（不变） |
+| 进程内加载（AssemblyLoadContext） | 保留 | 保留 |
+| 进程外隔离（命名管道 + AirAppHost 子进程） | 保留 | 不可用，降级为进程内 |
+| IPC 传输 | 命名管道（dotnetCampus.Ipc） | 进程内直通（InProc transport，同一契约） |
+| AirApp 运行时（独立进程） | 保留 | 第一版不提供 |
+
+插件代码不感知传输差异：同一套 `PluginIsolation` 契约在桌面走管道，在移动端走进程内直通。
+
+## 4. 移动端形态
+
+- 移动端不存在"桌面层自由摆放"的交互，组件以**组件面板**（可滚动卡片流/网格）呈现。
+- 复用同一批组件控件与 Appearance 主题资源，仅替换容器布局。
+- 单窗口生命周期（`ISingleViewApplicationLifetime`）。
+
+## 5. 明确舍弃（移动端不提供）
+
+- 电源管理（PowerManagementService）
+- 桌面层嵌入 / 点击穿透（MainWindowDesktopLayerService、WindowPassthroughService）
+- Office 互操作（MudTools.OfficeInterop.*）
+- Harmony 运行时补丁（Platform/Windows/Patches，仅随 Windows head 编译）
+- AirApp 独立进程运行时
+
+## 6. 构建与 CI
+
+- 桌面：`dotnet build LanMountainDesktop.slnx`（Windows/Linux/macOS 三平台 CI）。
+- Android：`dotnet build LanMountainDesktop.Mobile.Android/...csproj`（CI `build-android` job，
+  需要 `dotnet workload install android`）。
+- 共享层新增依赖时，必须确认该包支持 `net10.0-android`，否则放入 Platform 层。
+
+## 7. 相关文档
+
+- 共享库平台依赖审计报告：`docs/cross-platform-shared-audit.md`
+- 架构总览：`docs/ARCHITECTURE.md`

docs/cross-platform-shared-audit.md

@@ -0,0 +1,55 @@
+# 共享库跨平台依赖审计报告
+
+> 审计目标：确认以下共享库可被 Android head（net10.0-android）安全引用。
+> 审计方法：源码级扫描 `DllImport`/`LibraryImport`/`Microsoft.Win32`/`System.Drawing`/`WindowsRuntime`/`System.Management` + csproj 包引用检查。
+
+## 结论总览
+
+| 项目 | 状态 | 说明 |
+|---|---|---|
+| LanMountainDesktop.Shared.Contracts | ✅ 干净 | 仅引用 Avalonia，无平台 API |
+| LanMountainDesktop.Shared.IPC | ⚠️ 可编译，运行时受限 | 依赖 dotnetCampus.Ipc（命名管道）。Android 上可编译但命名管道不可用，移动端必须走进程内传输 |
+| LanMountainDesktop.Settings.Core | ✅ 干净 | 无包引用，纯托管 |
+| LanMountainDesktop.Appearance | ✅ 干净 | 无包引用，纯托管 |
+| LanMountainDesktop.DesktopComponents.Runtime | ✅ 干净 | 无包引用，纯托管 |
+| LanMountainDesktop.PluginSdk | ⚠️ 需验证 | 引用 FluentAvaloniaUI / FluentIcons.Avalonia（ExcludeAssets=runtime，仅编译期）与 dotnetCampus.Ipc；Android 引用时需实测还原 |
+| LanMountainDesktop.Host.Abstractions | ✅ 干净 | 无包引用 |
+
+## 详细发现
+
+### 1. 源码扫描
+
+7 个项目的 `.cs` 源码中均未发现：
+- `DllImport` / `LibraryImport`（P/Invoke）
+- `Microsoft.Win32`（注册表）
+- `System.Drawing`
+- `System.Runtime.WindowsRuntime`
+- `System.Management`
+
+平台专属代码全部集中在主工程 `LanMountainDesktop\`（9 个服务文件，正在迁往
+`LanMountainDesktop.Platform.Windows`）。
+
+### 2. dotnetCampus.Ipc（Shared.IPC、PluginSdk）
+
+- 编译期：跨平台 net 库，Android 目标可编译。
+- 运行期：传输基于命名管道，Android 不可用。
+- 处置：移动端一律使用 PluginIsolation 的进程内传输（InProc transport）；
+  Shared.IPC 在移动端应仅作为契约/类型来源，不建立管道连接。
+- 后续（可选）：若希望编译期硬隔离，可把"管道传输"从 Shared.IPC 拆到
+  Shared.IPC.Pipes 子项目，移动端不引用。当前不阻塞。
+
+### 3. FluentAvaloniaUI / FluentIcons.Avalonia（PluginSdk）
+
+- `ExcludeAssets="runtime"`，仅编译期类型引用。
+- 两者均为纯托管 Avalonia 库，预期可在 Android 还原；由 Mobile head 构建实测确认。
+
+### 4. 面向未来移动 AOT 的裁剪风险（仅报告，不修复）
+
+- 主工程使用 YamlDotNet、反射式配置读取——不在本次 7 个共享库范围内，
+  但如后续把相关逻辑下沉共享层，需加 `DynamicallyAccessedMembers` 注解或源生成序列化。
+- Settings.Core 若存在基于 `Activator.CreateInstance` 的设置实例化路径，
+  迁移到移动端 AOT（未来 iOS）前需要审计；Android（JIT/interp 可用）不阻塞。
+
+## 修复记录
+
+本次审计未发现需要修改共享库源码的问题，未做代码改动。