feat.文档更新

2026-06-23 09:54:25 +08:00 · 2026-06-08 03:54:33 +08:00
parent 7db72fbcd0
commit 49af6601aa
247 changed files with 2939 additions and 0 deletions
--- a/docs/01-插件开发/01-快速开始/01-环境准备.md
+++ b/docs/01-插件开发/01-快速开始/01-环境准备.md
@@ -0,0 +1,345 @@
+# 插件开发 - 环境准备
+
+## 前置要求
+
+在开始开发插件之前，请确保你已经：
+
+- ✅ 安装了 .NET 10 SDK
+- ✅ 安装了支持 C# 的 IDE（Visual Studio 2022 / Rider / VS Code）
+- ✅ 了解 C# 基础语法
+- ✅ 了解 Avalonia UI 基础（或 WPF，两者相似）
+
+> 如果还没有配置开发环境，请先阅读 [开发环境配置](../../00-快速开始/03-开发环境配置.md)
+
+## 安装插件模板
+
+### 安装官方模板
+
+阑山桌面提供了官方的插件项目模板，可以快速创建插件项目骨架。
+
+```powershell
+# 安装插件模板包
+dotnet new install LanMountainDesktop.PluginTemplate
+
+# 验证安装成功
+dotnet new list | Select-String "lmd"
+```
+
+你应该看到类似输出：
+
+```
+lmd-plugin    LanMountainDesktop Plugin    C#    LanMountainDesktop/Plugin
+```
+
+### 模板版本管理
+
+```powershell
+# 查看已安装的模板
+dotnet new list lmd
+
+# 更新到最新版本
+dotnet new install LanMountainDesktop.PluginTemplate --force
+
+# 卸载模板
+dotnet new uninstall LanMountainDesktop.PluginTemplate
+```
+
+## 创建第一个插件项目
+
+### 使用模板创建项目
+
+```powershell
+# 创建新插件项目
+dotnet new lmd-plugin -n MyFirstPlugin
+
+# 进入项目目录
+cd MyFirstPlugin
+```
+
+### 项目结构
+
+创建后的项目结构如下：
+
+```
+MyFirstPlugin/
+├── MyFirstPlugin.csproj                # 项目文件
+├── Plugin.cs                           # 插件入口类
+├── plugin.json                         # 插件清单
+├── Components/                         # 组件目录
+│   └── SampleComponent.cs              # 示例组件
+├── Views/                              # 视图目录
+│   └── SampleComponentView.axaml       # 组件视图
+│   └── SampleComponentView.axaml.cs    # 视图代码后台
+├── ViewModels/                         # 视图模型
+│   └── SampleComponentViewModel.cs     # 组件视图模型
+├── Settings/                           # 设置页目录
+│   └── PluginSettingsPage.axaml        # 设置页视图
+│   └── PluginSettingsPage.axaml.cs     # 设置页代码
+├── Assets/                             # 资源目录
+│   └── icon.png                        # 插件图标
+└── Localization/                       # 本地化目录
+    └── Strings.resx                    # 字符串资源
+```
+
+## 理解插件清单
+
+### plugin.json 文件
+
+`plugin.json` 是插件的元数据文件，定义了插件的基本信息。
+
+```json
+{
+  "Id": "com.example.myfirstplugin",
+  "Name": "My First Plugin",
+  "Version": "1.0.0",
+  "Author": "Your Name",
+  "Description": "My first LanMountainDesktop plugin",
+  "MinHostVersion": "1.0.0",
+  "SdkVersion": "5.0.0",
+  "Dependencies": [],
+  "Permissions": [
+    "Network.Access"
+  ],
+  "Icon": "Assets/icon.png",
+  "Homepage": "https://github.com/yourusername/myfirstplugin",
+  "Repository": "https://github.com/yourusername/myfirstplugin.git"
+}
+```
+
+### 字段说明
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `Id` | ✅ | 插件唯一标识符，建议使用反向域名格式 |
+| `Name` | ✅ | 插件显示名称 |
+| `Version` | ✅ | 插件版本号，遵循语义化版本 |
+| `Author` | ✅ | 插件作者 |
+| `Description` | ✅ | 插件简介 |
+| `MinHostVersion` | ✅ | 最低宿主版本要求 |
+| `SdkVersion` | ✅ | 使用的 SDK 版本 |
+| `Dependencies` | ❌ | 依赖的其他插件 ID 列表 |
+| `Permissions` | ❌ | 插件所需权限列表 |
+| `Icon` | ❌ | 插件图标路径 |
+| `Homepage` | ❌ | 插件主页 URL |
+| `Repository` | ❌ | 源码仓库 URL |
+
+### 版本号规范
+
+插件版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)：
+
+```
+主版本号.次版本号.修订号
+
+例如: 1.2.3
+```
+
+- **主版本号**: 不兼容的 API 修改
+- **次版本号**: 向下兼容的功能性新增
+- **修订号**: 向下兼容的问题修正
+
+## 理解项目文件
+
+### MyFirstPlugin.csproj
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    
+    <!-- 插件元数据 -->
+    <PluginId>com.example.myfirstplugin</PluginId>
+    <PluginName>My First Plugin</PluginName>
+    <PluginVersion>1.0.0</PluginVersion>
+    
+    <!-- 禁用可执行文件生成，插件是类库 -->
+    <OutputType>Library</OutputType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Plugin SDK -->
+    <PackageReference Include="LanMountainDesktop.PluginSdk" Version="5.0.0" />
+    <PackageReference Include="LanMountainDesktop.Shared.Contracts" Version="5.0.0" />
+    
+    <!-- Avalonia UI -->
+    <PackageReference Include="Avalonia" Version="12.0.1" />
+    <PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.1" />
+    
+    <!-- MVVM Toolkit -->
+    <PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2" />
+  </ItemGroup>
+
+  <!-- 复制 plugin.json 到输出目录 -->
+  <ItemGroup>
+    <None Update="plugin.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+    <None Update="Assets\**">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+  
+  <!-- Avalonia 编译支持 -->
+  <ItemGroup>
+    <AvaloniaResource Include="**\*.axaml" />
+  </ItemGroup>
+</Project>
+```
+
+### 关键配置项
+
+- **TargetFramework**: 必须是 `net10.0`
+- **OutputType**: 必须是 `Library`（插件是类库，不是可执行文件）
+- **Nullable**: 建议启用，提高代码质量
+- **PluginId/PluginName/PluginVersion**: 应与 `plugin.json` 保持一致
+
+## 构建插件
+
+### 还原依赖
+
+```powershell
+dotnet restore
+```
+
+### 构建项目
+
+```powershell
+# Debug 模式
+dotnet build
+
+# Release 模式
+dotnet build -c Release
+```
+
+### 查看输出
+
+构建成功后，输出目录结构：
+
+```
+bin/Debug/net10.0/
+├── MyFirstPlugin.dll                   # 主程序集
+├── MyFirstPlugin.pdb                   # 调试符号
+├── plugin.json                         # 插件清单
+├── Assets/                             # 资源文件
+│   └── icon.png
+└── *.dll                               # 依赖程序集
+```
+
+## 调试插件
+
+### 方法一：复制到插件目录（推荐）
+
+```powershell
+# 构建插件
+dotnet build
+
+# 复制到宿主的插件目录
+$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstPlugin"
+New-Item -ItemType Directory -Path $pluginDir -Force
+Copy-Item -Path "bin\Debug\net10.0\*" -Destination $pluginDir -Recurse -Force
+
+# 启动宿主应用
+# （确保宿主在 Debug 模式下构建，这样可以附加调试器）
+```
+
+### 方法二：使用符号链接
+
+在开发模式下，可以创建符号链接避免每次复制：
+
+```powershell
+# 创建符号链接（需要管理员权限）
+$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstPlugin"
+$buildDir = "$(pwd)\bin\Debug\net10.0"
+
+New-Item -ItemType SymbolicLink -Path $pluginDir -Target $buildDir -Force
+```
+
+### 方法三：配置宿主调试路径
+
+如果你有宿主源码，可以修改宿主的插件搜索路径指向你的插件构建目录。
+
+在宿主项目的 `appsettings.Development.json` 中：
+
+```json
+{
+  "PluginPaths": [
+    "C:\\Dev\\MyFirstPlugin\\bin\\Debug\\net10.0"
+  ]
+}
+```
+
+### 附加调试器
+
+1. 启动宿主应用（LanMountainDesktop）
+2. 在 Visual Studio 中，选择"调试" → "附加到进程"
+3. 找到 `LanMountainDesktop.exe` 进程
+4. 点击"附加"
+5. 在插件代码中设置断点
+
+## 查看日志
+
+### 日志位置
+
+```
+%LOCALAPPDATA%\LanMountainDesktop\logs\latest.log
+```
+
+### 实时查看日志
+
+```powershell
+# PowerShell
+Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\latest.log" -Wait -Tail 50
+```
+
+### 日志级别
+
+- **Trace**: 最详细的信息，用于诊断
+- **Debug**: 调试信息
+- **Information**: 一般信息
+- **Warning**: 警告信息
+- **Error**: 错误信息
+- **Critical**: 严重错误
+
+## 常见问题
+
+### 插件没有被加载
+
+**检查清单**:
+1. 确认 `plugin.json` 存在且格式正确
+2. 确认插件 DLL 文件存在
+3. 查看日志文件中的错误信息
+4. 确认插件 ID 唯一，没有与其他插件冲突
+5. 确认 SDK 版本匹配
+
+### 编译错误：找不到类型
+
+**问题**: `error CS0246: The type or namespace name 'IPlugin' could not be found`
+
+**解决方案**:
+```powershell
+# 确认引用了 PluginSdk
+dotnet add package LanMountainDesktop.PluginSdk --version 5.0.0
+
+# 清理并重新构建
+dotnet clean
+dotnet build
+```
+
+### Avalonia 视图无法编译
+
+**问题**: AXAML 文件编译错误
+
+**解决方案**:
+1. 确认安装了 Avalonia NuGet 包
+2. 检查 AXAML 语法是否正确
+3. 确认 `AvaloniaResource` 项已配置在 csproj 中
+4. 清理并重新构建项目
+
+## 下一步
+
+现在你已经完成了环境准备，可以继续：
+
+- [创建第一个插件](02-创建第一个插件.md) - 实现插件功能
+- [插件生命周期](../02-核心概念/01-插件生命周期.md) - 理解插件运行机制
+- [组件系统](../02-核心概念/02-组件系统.md) - 创建桌面组件