0.5.6

插件系统再进化

LanAirApp/README.md

@@ -0,0 +1,25 @@
+# LanAirApp
+
+`LanAirApp` 是阑山桌面插件生态的对外发布工作区。
+
+这里集中放置：
+- 插件开发标准
+- 插件打包与构建工具
+- 插件开发与打包文档
+- 示例插件
+
+目录结构：
+- `docs/`：插件开发文档、打包文档
+- `samples/`：示例插件，其中 `LanMountainDesktop.SamplePlugin` 是示例开发插件
+- `standards/`：插件标准文件与模板
+- `tools/`：插件打包与构建工具
+
+面向用户的安装流程：
+1. 将插件构建或打包为 `.laapp` 文件。
+2. 打开 `设置 -> 插件`。
+3. 点击 `打开 .laapp 插件包`。
+4. 选择插件包完成安装。
+
+宿主侧的插件加载、安装、发现、解析与设置页接入逻辑，保留在 `LanMountainDesktop/plugins/`。
+
+`LanMountainDesktop.PluginSdk` 仅作为插件开发 SDK 使用，提供 `IPlugin`、`IPluginContext`、清单模型与扩展注册接口。

LanAirApp/docs/PLUGIN_DEVELOPMENT.md

@@ -0,0 +1,41 @@
+# 插件开发文档
+
+LanMountainDesktop 插件基于 `LanMountainDesktop.PluginSdk` 开发。
+
+`LanAirApp/` 负责对外发布插件开发标准、示例插件和打包工具；宿主应用内部的插件加载与解析逻辑位于 `LanMountainDesktop/plugins/`。
+`LanMountainDesktop.PluginSdk` 只提供插件作者需要依赖的开发契约，不再承载宿主侧运行时加载实现。
+
+## 必需文件
+- `plugin.json`
+- `plugin.json` 中声明的入口程序集
+- 使用插件入口特性标记的入口类型
+
+## 推荐开发流程
+1. 以 `LanAirApp/samples/LanMountainDesktop.SamplePlugin` 为起点。
+2. 修改 `plugin.json`，填写你自己的插件 `id`、名称、作者、版本和入口程序集。
+3. 实现 `IPlugin` 或继承 `PluginBase`。
+4. 通过 `IPluginContext` 注册服务、设置页和桌面组件。
+5. 将输出内容打包为 `.laapp` 文件。
+
+## 运行时能力
+- 插件可以注册自己的设置页。
+- 插件可以注册自己的桌面组件。
+- 插件可以注册自己的服务，并通过插件消息总线进行通信。
+- 宿主优先加载 `.laapp` 包，其次才是散装清单。
+
+## 多语言建议
+- 插件应当内置 `Localization/zh-CN.json` 与 `Localization/en-US.json`。
+- 插件界面文案、组件文案、状态文案建议统一通过插件本地化层读取。
+- 建议优先读取宿主传入的语言代码，再回退到插件默认语言。
+
+## 目录建议
+一个标准插件项目建议至少包含：
+- `plugin.json`
+- `Localization/zh-CN.json`
+- `Localization/en-US.json`
+- 插件程序集与依赖文件
+
+## 示例项目与工具
+- 示例插件：`LanAirApp/samples/LanMountainDesktop.SamplePlugin`
+- 打包工具：`LanAirApp/tools/LanMountainDesktop.PluginPackager`
+- 标准模板：`LanAirApp/standards/plugin.template.json`

LanAirApp/docs/PLUGIN_PACKAGING.md

@@ -0,0 +1,34 @@
+# 插件打包文档
+
+LanMountainDesktop 插件的安装包格式固定为 `.laapp`。
+
+`LanAirApp/` 负责提供打包标准与打包工具；`.laapp` 的安装、发现和运行时加载由 `LanMountainDesktop/plugins/` 负责。
+
+## `.laapp` 格式说明
+- 本质上是一个标准 zip 压缩包
+- 包根目录必须包含 `plugin.json`
+- 包根目录还必须包含入口程序集及其依赖
+
+## 建议打包内容
+- `plugin.json`
+- `YourPlugin.dll`
+- 依赖程序集
+- `Localization/zh-CN.json`
+- `Localization/en-US.json`
+- 插件运行所需的其他资源文件
+
+## 使用打包工具
+```powershell
+dotnet run --project .\LanAirApp\tools\LanMountainDesktop.PluginPackager -- --input .\path\to\plugin-output --output .\artifacts\YourPlugin.laapp --overwrite
+```
+
+## 应用内安装流程
+1. 打开 `设置 -> 插件`
+2. 点击 `打开 .laapp 插件包`
+3. 选择要安装的插件包
+4. 如果插件注册了设置页或组件，安装后重启应用
+
+## 注意事项
+- `plugin.json` 中的 `entranceAssembly` 必须能在包内找到。
+- 包内应尽量避免无关开发产物。
+- `.laapp` 是标准安装格式，建议不要对外分发散装目录。

LanAirApp/samples/LanMountainDesktop.SamplePlugin/LanMountainDesktop.SamplePlugin.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <Version>1.0.0</Version>
+    <EnableDynamicLoading>true</EnableDynamicLoading>
+    <OutputPath>bin\$(Configuration)\$(TargetFramework)\content\</OutputPath>
+    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
+    <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
+    <PluginPackageOutputDirectory>..\..\..\LanMountainDesktop\bin\$(Configuration)\$(TargetFramework)\Extensions\Plugins\</PluginPackageOutputDirectory>
+    <PluginPackagePath>$(PluginPackageOutputDirectory)$(AssemblyName).laapp</PluginPackagePath>
+    <LegacyLoosePluginOutputDirectory>..\..\..\LanMountainDesktop\bin\$(Configuration)\$(TargetFramework)\Extensions\Plugins\SamplePlugin\</LegacyLoosePluginOutputDirectory>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\LanMountainDesktop.PluginSdk\LanMountainDesktop.PluginSdk.csproj" Private="false" />
+    <None Include="plugin.json" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+  <Target Name="CreateLaappPackage" AfterTargets="Build">
+    <MakeDir Directories="$(PluginPackageOutputDirectory)" />
+    <RemoveDir Directories="$(LegacyLoosePluginOutputDirectory)" />
+    <Delete Files="$(PluginPackagePath)" TreatErrorsAsWarnings="true" />
+    <ZipDirectory SourceDirectory="$(OutputPath)" DestinationFile="$(PluginPackagePath)" />
+  </Target>
+
+</Project>

LanAirApp/samples/LanMountainDesktop.SamplePlugin/README.md

@@ -0,0 +1,16 @@
+# LanMountainDesktop.SamplePlugin
+
+这是阑山桌面的**示例开发插件**。
+
+它用于演示以下能力：
+- 插件入口与 `plugin.json` 清单
+- 插件服务注册
+- 插件设置页注册
+- 插件桌面组件注册
+- 插件内通信与状态更新
+- `.laapp` 打包与安装流程
+- 插件多语言资源组织方式
+
+如果你要开发自己的插件，建议以这个目录为模板开始。
+
+这个目录仅用于示例开发与打包发布，不承载宿主应用内部的插件加载逻辑。

LanAirApp/samples/LanMountainDesktop.SamplePlugin/SamplePlugin.cs

@@ -0,0 +1,84 @@
+using LanMountainDesktop.PluginSdk;
+
+namespace LanMountainDesktop.SamplePlugin;
+
+[PluginEntrance]
+public sealed class SamplePlugin : PluginBase, IDisposable
+{
+    private SamplePluginRuntimeStateService? _stateService;
+    private SamplePluginClockService? _clockService;
+
+    public override void Initialize(IPluginContext context)
+    {
+        Directory.CreateDirectory(context.DataDirectory);
+
+        var hostName = GetHostProperty(context, "HostApplicationName", "UnknownHost");
+        var hostVersion = GetHostProperty(context, "HostVersion", "UnknownVersion");
+        var sdkApiVersion = GetHostProperty(context, "PluginSdkApiVersion", "UnknownApiVersion");
+        var messageBus = context.GetService<IPluginMessageBus>()
+            ?? throw new InvalidOperationException("Plugin message bus is not available.");
+
+        _stateService = new SamplePluginRuntimeStateService(
+            context.Manifest,
+            context.PluginDirectory,
+            context.DataDirectory,
+            hostName,
+            hostVersion,
+            sdkApiVersion,
+            messageBus);
+        context.RegisterService(_stateService);
+
+        _clockService = new SamplePluginClockService(context.DataDirectory, _stateService, messageBus);
+        context.RegisterService(_clockService);
+        _stateService.AttachClockService(_clockService);
+
+        var logPath = Path.Combine(context.DataDirectory, "sample-plugin.log");
+        var initMessage =
+            $"[{DateTimeOffset.UtcNow:O}] {context.Manifest.Name} initialized in {hostName} (plugin version {context.Manifest.Version ?? "dev"}).";
+
+        try
+        {
+            File.AppendAllText(logPath, initMessage + Environment.NewLine);
+            _stateService.MarkBackendReady($"Initialization log written to {logPath}.");
+        }
+        catch (Exception ex)
+        {
+            _stateService.MarkBackendFaulted($"Initialization log write failed: {ex.Message}");
+            throw;
+        }
+
+        _clockService.Start();
+
+        context.RegisterSettingsPage(new PluginSettingsPageRegistration(
+            "status",
+            "Plugin Status",
+            () => new SamplePluginSettingsView(context)));
+
+        context.RegisterDesktopComponent(new PluginDesktopComponentRegistration(
+            "LanMountainDesktop.SamplePlugin.StatusClock",
+            "Sample Plugin Status Clock",
+            widgetContext => new SamplePluginStatusClockWidget(widgetContext),
+            iconKey: "PuzzlePiece",
+            category: "Plugins",
+            minWidthCells: 4,
+            minHeightCells: 4,
+            allowDesktopPlacement: true,
+            allowStatusBarPlacement: false,
+            resizeMode: PluginDesktopComponentResizeMode.Proportional,
+            cornerRadiusResolver: cellSize => Math.Clamp(cellSize * 0.34, 18, 34)));
+    }
+
+    public void Dispose()
+    {
+        _clockService?.Dispose();
+        _clockService = null;
+        _stateService = null;
+    }
+
+    private static string GetHostProperty(IPluginContext context, string key, string fallback)
+    {
+        return context.TryGetProperty<string>(key, out var value) && !string.IsNullOrWhiteSpace(value)
+            ? value
+            : fallback;
+    }
+}

LanAirApp/samples/LanMountainDesktop.SamplePlugin/SamplePluginRuntimeStatus.cs

@@ -0,0 +1,465 @@
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using LanMountainDesktop.PluginSdk;
+
+namespace LanMountainDesktop.SamplePlugin;
+
+internal enum SamplePluginHealthState
+{
+    Healthy,
+    Pending,
+    Faulted
+}
+
+internal sealed record SamplePluginStatusEntry(
+    string Key,
+    string Title,
+    SamplePluginHealthState State,
+    string Summary,
+    string Detail,
+    DateTimeOffset UpdatedAt);
+
+internal sealed record SamplePluginCapabilityItem(
+    string Title,
+    string Detail);
+
+internal sealed record SamplePluginRuntimeSnapshot(
+    PluginManifest Manifest,
+    string PluginDirectory,
+    string DataDirectory,
+    string HostApplicationName,
+    string HostVersion,
+    string SdkApiVersion,
+    IReadOnlyList<SamplePluginStatusEntry> StatusEntries,
+    bool HasPlacedComponent,
+    int PlacedCount,
+    int PreviewCount,
+    IReadOnlyList<string> PlacementIds,
+    string? LastComponentId,
+    double LastCellSize,
+    DateTimeOffset? ServiceClockTime);
+
+internal sealed record SamplePluginClockTickMessage(DateTimeOffset CurrentTime);
+
+internal sealed record SamplePluginStateChangedMessage(string Reason);
+
+internal sealed record SamplePluginComponentInstance(
+    string ComponentId,
+    string? PlacementId,
+    double CellSize)
+{
+    public bool IsPlaced => !string.IsNullOrWhiteSpace(PlacementId);
+}
+
+internal sealed class SamplePluginRuntimeStateService
+{
+    private readonly object _gate = new();
+    private readonly IPluginMessageBus _messageBus;
+    private readonly Dictionary<string, SamplePluginComponentInstance> _componentInstances =
+        new(StringComparer.OrdinalIgnoreCase);
+
+    private readonly PluginManifest _manifest;
+    private readonly string _pluginDirectory;
+    private readonly string _dataDirectory;
+    private readonly string _hostApplicationName;
+    private readonly string _hostVersion;
+    private readonly string _sdkApiVersion;
+
+    private SamplePluginStatusEntry _frontend;
+    private SamplePluginStatusEntry _component;
+    private SamplePluginStatusEntry _backend;
+    private SamplePluginStatusEntry _service;
+    private string? _lastComponentId;
+    private double _lastCellSize;
+    private DateTimeOffset? _serviceClockTime;
+
+    public SamplePluginRuntimeStateService(
+        PluginManifest manifest,
+        string pluginDirectory,
+        string dataDirectory,
+        string hostApplicationName,
+        string hostVersion,
+        string sdkApiVersion,
+        IPluginMessageBus messageBus)
+    {
+        _manifest = manifest;
+        _pluginDirectory = pluginDirectory;
+        _dataDirectory = dataDirectory;
+        _hostApplicationName = hostApplicationName;
+        _hostVersion = hostVersion;
+        _sdkApiVersion = sdkApiVersion;
+        _messageBus = messageBus;
+
+        _frontend = CreateEntry(
+            "frontend",
+            "Frontend",
+            SamplePluginHealthState.Pending,
+            "Pending",
+            "Waiting for a plugin UI surface to connect.");
+
+        _component = CreateEntry(
+            "component",
+            "Component",
+            SamplePluginHealthState.Pending,
+            "Pending",
+            "No component instance has been created yet.");
+
+        _backend = CreateEntry(
+            "backend",
+            "Backend",
+            SamplePluginHealthState.Pending,
+            "Pending",
+            "Plugin initialization is in progress.");
+
+        _service = CreateEntry(
+            "service",
+            "Clock Service",
+            SamplePluginHealthState.Pending,
+            "Pending",
+            "Clock service is not attached yet.");
+    }
+
+    public void AttachClockService(SamplePluginClockService clockService)
+    {
+        ArgumentNullException.ThrowIfNull(clockService);
+
+        lock (_gate)
+        {
+            _serviceClockTime = clockService.CurrentTime;
+            _service = CreateEntry(
+                "service",
+                "Clock Service",
+                SamplePluginHealthState.Pending,
+                "Attached",
+                "Clock service was attached and is waiting for the first tick.");
+        }
+
+        PublishStateChanged("Clock service attached");
+    }
+
+    public void MarkFrontendReady(string detail)
+    {
+        lock (_gate)
+        {
+            _frontend = CreateEntry(
+                "frontend",
+                "Frontend",
+                SamplePluginHealthState.Healthy,
+                "Healthy",
+                detail);
+        }
+
+        PublishStateChanged("Frontend updated");
+    }
+
+    public void MarkBackendReady(string detail)
+    {
+        lock (_gate)
+        {
+            _backend = CreateEntry(
+                "backend",
+                "Backend",
+                SamplePluginHealthState.Healthy,
+                "Healthy",
+                detail);
+        }
+
+        PublishStateChanged("Backend updated");
+    }
+
+    public void MarkBackendFaulted(string detail)
+    {
+        lock (_gate)
+        {
+            _backend = CreateEntry(
+                "backend",
+                "Backend",
+                SamplePluginHealthState.Faulted,
+                "Faulted",
+                detail);
+        }
+
+        PublishStateChanged("Backend faulted");
+    }
+
+    public void MarkClockServiceTick(DateTimeOffset currentTime)
+    {
+        lock (_gate)
+        {
+            _serviceClockTime = currentTime;
+            _service = CreateEntry(
+                "service",
+                "Clock Service",
+                SamplePluginHealthState.Healthy,
+                "Healthy",
+                $"Clock service is running. Current service time: {currentTime.LocalDateTime:HH:mm:ss}");
+        }
+
+        PublishStateChanged("Clock service tick");
+    }
+
+    public void MarkClockServiceFaulted(string detail)
+    {
+        lock (_gate)
+        {
+            _service = CreateEntry(
+                "service",
+                "Clock Service",
+                SamplePluginHealthState.Faulted,
+                "Faulted",
+                detail);
+        }
+
+        PublishStateChanged("Clock service faulted");
+    }
+
+    public string RegisterComponentInstance(string componentId, string? placementId, double cellSize)
+    {
+        var instanceId = Guid.NewGuid().ToString("N");
+
+        lock (_gate)
+        {
+            _componentInstances[instanceId] = new SamplePluginComponentInstance(componentId, placementId, cellSize);
+            _lastComponentId = componentId;
+            _lastCellSize = cellSize;
+            UpdateComponentStatusNoLock();
+        }
+
+        PublishStateChanged("Component attached");
+        return instanceId;
+    }
+
+    public void UnregisterComponentInstance(string instanceId)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(instanceId);
+
+        var removed = false;
+        lock (_gate)
+        {
+            removed = _componentInstances.Remove(instanceId);
+            if (removed)
+            {
+                UpdateComponentStatusNoLock();
+            }
+        }
+
+        if (removed)
+        {
+            PublishStateChanged("Component detached");
+        }
+    }
+
+    public SamplePluginRuntimeSnapshot GetSnapshot()
+    {
+        lock (_gate)
+        {
+            var placementIds = _componentInstances.Values
+                .Where(instance => instance.IsPlaced)
+                .Select(instance => instance.PlacementId!)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(id => id, StringComparer.OrdinalIgnoreCase)
+                .ToArray();
+
+            var previewCount = _componentInstances.Values.Count(instance => !instance.IsPlaced);
+
+            return new SamplePluginRuntimeSnapshot(
+                _manifest,
+                _pluginDirectory,
+                _dataDirectory,
+                _hostApplicationName,
+                _hostVersion,
+                _sdkApiVersion,
+                [_frontend, _component, _backend, _service],
+                placementIds.Length > 0,
+                placementIds.Length,
+                previewCount,
+                placementIds,
+                _lastComponentId,
+                _lastCellSize,
+                _serviceClockTime);
+        }
+    }
+
+    public IReadOnlyList<SamplePluginCapabilityItem> GetCapabilities(
+        IPluginContext context,
+        bool hasStateService,
+        bool hasClockService,
+        bool hasMessageBus)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        var propertyNames = context.Properties.Count == 0
+            ? "(none)"
+            : string.Join(", ", context.Properties.Keys.OrderBy(key => key, StringComparer.OrdinalIgnoreCase));
+
+        return
+        [
+            new SamplePluginCapabilityItem(
+                "IPluginContext.Manifest",
+                $"Readable. Current plugin id: {context.Manifest.Id}; version: {context.Manifest.Version ?? "dev"}."),
+            new SamplePluginCapabilityItem(
+                "IPluginContext.PluginDirectory / DataDirectory",
+                $"Readable. Plugin directory: {context.PluginDirectory}; data directory: {context.DataDirectory}."),
+            new SamplePluginCapabilityItem(
+                "IPluginContext.Properties",
+                $"Readable. Host properties currently exposed: {propertyNames}."),
+            new SamplePluginCapabilityItem(
+                "IPluginContext.GetService<T>()",
+                $"Callable. State service resolved: {hasStateService}; clock service resolved: {hasClockService}; message bus resolved: {hasMessageBus}."),
+            new SamplePluginCapabilityItem(
+                "IPluginContext.RegisterService<TService>()",
+                "Callable during plugin initialization. This plugin registers SamplePluginRuntimeStateService and SamplePluginClockService into the plugin service container."),
+            new SamplePluginCapabilityItem(
+                "Plugin communication bus",
+                "This plugin uses IPluginMessageBus to push clock ticks and state change notifications into plugin UI surfaces."),
+            new SamplePluginCapabilityItem(
+                "PluginDesktopComponentContext",
+                "Widgets can read ComponentId, PlacementId, CellSize, and call GetService<T>() against the same plugin service container.")
+        ];
+    }
+
+    private void UpdateComponentStatusNoLock()
+    {
+        var placementIds = _componentInstances.Values
+            .Where(instance => instance.IsPlaced)
+            .Select(instance => instance.PlacementId!)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(id => id, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+
+        var previewCount = _componentInstances.Values.Count(instance => !instance.IsPlaced);
+
+        if (placementIds.Length > 0)
+        {
+            _component = CreateEntry(
+                "component",
+                "Component",
+                SamplePluginHealthState.Healthy,
+                "Placed",
+                $"Placed count: {placementIds.Length}; preview count: {previewCount}; placements: {string.Join(", ", placementIds)}");
+            return;
+        }
+
+        if (previewCount > 0)
+        {
+            _component = CreateEntry(
+                "component",
+                "Component",
+                SamplePluginHealthState.Healthy,
+                "Preview",
+                $"Preview instances: {previewCount}; no placed desktop instance is active yet.");
+            return;
+        }
+
+        _component = CreateEntry(
+            "component",
+            "Component",
+            SamplePluginHealthState.Pending,
+            "Pending",
+            "No component instance is active.");
+    }
+
+    private void PublishStateChanged(string reason)
+    {
+        _messageBus.Publish(new SamplePluginStateChangedMessage(reason));
+    }
+
+    private static SamplePluginStatusEntry CreateEntry(
+        string key,
+        string title,
+        SamplePluginHealthState state,
+        string summary,
+        string detail)
+    {
+        return new SamplePluginStatusEntry(
+            key,
+            title,
+            state,
+            summary,
+            detail,
+            DateTimeOffset.Now);
+    }
+}
+
+internal sealed class SamplePluginClockService : IDisposable
+{
+    private readonly object _gate = new();
+    private readonly string _clockStateFilePath;
+    private readonly SamplePluginRuntimeStateService _stateService;
+    private readonly IPluginMessageBus _messageBus;
+    private readonly Timer _timer;
+    private DateTimeOffset _currentTime = DateTimeOffset.Now;
+    private int _disposed;
+
+    public SamplePluginClockService(
+        string dataDirectory,
+        SamplePluginRuntimeStateService stateService,
+        IPluginMessageBus messageBus)
+    {
+        _clockStateFilePath = Path.Combine(dataDirectory, "clock-service.txt");
+        _stateService = stateService;
+        _messageBus = messageBus;
+        _timer = new Timer(OnTimerTick);
+    }
+
+    public DateTimeOffset CurrentTime
+    {
+        get
+        {
+            lock (_gate)
+            {
+                return _currentTime;
+            }
+        }
+    }
+
+    public void Start()
+    {
+        PublishTick();
+        _timer.Change(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(1));
+    }
+
+    public void Dispose()
+    {
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+        {
+            return;
+        }
+
+        _timer.Dispose();
+    }
+
+    private void OnTimerTick(object? state)
+    {
+        PublishTick();
+    }
+
+    private void PublishTick()
+    {
+        if (Volatile.Read(ref _disposed) != 0)
+        {
+            return;
+        }
+
+        var now = DateTimeOffset.Now;
+        lock (_gate)
+        {
+            _currentTime = now;
+        }
+
+        try
+        {
+            File.WriteAllText(
+                _clockStateFilePath,
+                now.ToString("O", CultureInfo.InvariantCulture));
+            _stateService.MarkClockServiceTick(now);
+            _messageBus.Publish(new SamplePluginClockTickMessage(now));
+        }
+        catch (Exception ex)
+        {
+            _stateService.MarkClockServiceFaulted($"Clock state write failed: {ex.Message}");
+        }
+    }
+}

LanAirApp/samples/LanMountainDesktop.SamplePlugin/SamplePluginSettingsView.cs

@@ -0,0 +1,339 @@
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Layout;
+using Avalonia.Media;
+using Avalonia.Threading;
+using LanMountainDesktop.PluginSdk;
+
+namespace LanMountainDesktop.SamplePlugin;
+
+internal sealed class SamplePluginSettingsView : UserControl
+{
+    private readonly IPluginContext _context;
+    private readonly SamplePluginRuntimeStateService _stateService;
+    private readonly SamplePluginClockService _clockService;
+    private readonly IPluginMessageBus _messageBus;
+    private readonly StackPanel _pluginInfoPanel = new() { Spacing = 8 };
+    private readonly StackPanel _capabilityPanel = new() { Spacing = 8 };
+    private readonly StackPanel _statusPanel = new() { Spacing = 10 };
+    private readonly List<IDisposable> _subscriptions = [];
+
+    public SamplePluginSettingsView(IPluginContext context)
+    {
+        _context = context;
+        _stateService = context.GetService<SamplePluginRuntimeStateService>()
+            ?? throw new InvalidOperationException("SamplePluginRuntimeStateService is not available.");
+        _clockService = context.GetService<SamplePluginClockService>()
+            ?? throw new InvalidOperationException("SamplePluginClockService is not available.");
+        _messageBus = context.GetService<IPluginMessageBus>()
+            ?? throw new InvalidOperationException("IPluginMessageBus is not available.");
+
+        _stateService.MarkFrontendReady("Settings page is connected to plugin services and communication.");
+
+        AttachedToVisualTree += OnAttachedToVisualTree;
+        DetachedFromVisualTree += OnDetachedFromVisualTree;
+
+        Content = new Border
+        {
+            Background = new LinearGradientBrush
+            {
+                StartPoint = new RelativePoint(0, 0, RelativeUnit.Relative),
+                EndPoint = new RelativePoint(1, 1, RelativeUnit.Relative),
+                GradientStops =
+                [
+                    new GradientStop(Color.Parse("#1F0B1120"), 0),
+                    new GradientStop(Color.Parse("#260C4A6E"), 1)
+                ]
+            },
+            BorderBrush = new SolidColorBrush(Color.Parse("#6628B2FF")),
+            BorderThickness = new Thickness(1),
+            CornerRadius = new CornerRadius(18),
+            Padding = new Thickness(18),
+            Child = new StackPanel
+            {
+                Spacing = 14,
+                Children =
+                {
+                    new TextBlock
+                    {
+                        Text = "Sample Plugin Capability Inspector",
+                        FontSize = 22,
+                        FontWeight = FontWeight.SemiBold,
+                        Foreground = Brushes.White
+                    },
+                    CreateSection("Plugin Info", _pluginInfoPanel),
+                    CreateSection("Accessible Capabilities", _capabilityPanel),
+                    CreateSection("Live Runtime Status", _statusPanel)
+                }
+            }
+        };
+
+        RefreshView();
+    }
+
+    private void OnAttachedToVisualTree(object? sender, VisualTreeAttachmentEventArgs e)
+    {
+        SubscribeToPluginBus();
+        RefreshView();
+    }
+
+    private void OnDetachedFromVisualTree(object? sender, VisualTreeAttachmentEventArgs e)
+    {
+        foreach (var subscription in _subscriptions)
+        {
+            subscription.Dispose();
+        }
+
+        _subscriptions.Clear();
+    }
+
+    private void SubscribeToPluginBus()
+    {
+        if (_subscriptions.Count > 0)
+        {
+            return;
+        }
+
+        _subscriptions.Add(_messageBus.Subscribe<SamplePluginClockTickMessage>(_ =>
+            Dispatcher.UIThread.Post(RefreshView)));
+
+        _subscriptions.Add(_messageBus.Subscribe<SamplePluginStateChangedMessage>(_ =>
+            Dispatcher.UIThread.Post(RefreshView)));
+    }
+
+    private void RefreshView()
+    {
+        var snapshot = _stateService.GetSnapshot();
+        RefreshPluginInfo(snapshot);
+        RefreshCapabilities();
+        RefreshStatuses(snapshot);
+    }
+
+    private void RefreshPluginInfo(SamplePluginRuntimeSnapshot snapshot)
+    {
+        _pluginInfoPanel.Children.Clear();
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Plugin Name", snapshot.Manifest.Name));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Plugin Id", snapshot.Manifest.Id));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Version", snapshot.Manifest.Version ?? "dev"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Author", snapshot.Manifest.Author ?? "(none)"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Description", snapshot.Manifest.Description ?? "(none)"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Plugin Directory", snapshot.PluginDirectory));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Data Directory", snapshot.DataDirectory));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Host Application", snapshot.HostApplicationName));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Host Version", snapshot.HostVersion));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("SDK API Version", snapshot.SdkApiVersion));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("State Service Resolved", (_context.GetService<SamplePluginRuntimeStateService>() is not null).ToString()));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Clock Service Resolved", (_context.GetService<SamplePluginClockService>() is not null).ToString()));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Message Bus Resolved", (_context.GetService<IPluginMessageBus>() is not null).ToString()));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Component Placed", snapshot.HasPlacedComponent ? "Yes" : "No"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Placed Count", snapshot.PlacedCount.ToString()));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Preview Count", snapshot.PreviewCount.ToString()));
+        _pluginInfoPanel.Children.Add(CreateInfoLine(
+            "Placement Ids",
+            snapshot.PlacementIds.Count == 0 ? "(none)" : string.Join(", ", snapshot.PlacementIds)));
+        _pluginInfoPanel.Children.Add(CreateInfoLine("Last Component Id", snapshot.LastComponentId ?? "(none)"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine(
+            "Last Cell Size",
+            snapshot.LastCellSize > 0 ? $"{snapshot.LastCellSize:F0}px" : "(unknown)"));
+        _pluginInfoPanel.Children.Add(CreateInfoLine(
+            "Clock Service Time",
+            _clockService.CurrentTime.LocalDateTime.ToString("HH:mm:ss")));
+    }
+
+    private void RefreshCapabilities()
+    {
+        var capabilities = _stateService.GetCapabilities(
+            _context,
+            _context.GetService<SamplePluginRuntimeStateService>() is not null,
+            _context.GetService<SamplePluginClockService>() is not null,
+            _context.GetService<IPluginMessageBus>() is not null);
+
+        _capabilityPanel.Children.Clear();
+        foreach (var capability in capabilities)
+        {
+            _capabilityPanel.Children.Add(CreateCapabilityCard(capability));
+        }
+    }
+
+    private void RefreshStatuses(SamplePluginRuntimeSnapshot snapshot)
+    {
+        _statusPanel.Children.Clear();
+
+        foreach (var entry in snapshot.StatusEntries)
+        {
+            var palette = GetPalette(entry.State);
+            _statusPanel.Children.Add(new Border
+            {
+                Background = new SolidColorBrush(palette.Background),
+                BorderBrush = new SolidColorBrush(palette.Border),
+                BorderThickness = new Thickness(1),
+                CornerRadius = new CornerRadius(12),
+                Padding = new Thickness(12, 10),
+                Child = new StackPanel
+                {
+                    Spacing = 4,
+                    Children =
+                    {
+                        CreateStatusHeader(entry, palette),
+                        new TextBlock
+                        {
+                            Text = entry.Detail,
+                            Foreground = new SolidColorBrush(Color.Parse("#FFE0F2FE")),
+                            TextWrapping = TextWrapping.Wrap
+                        },
+                        new TextBlock
+                        {
+                            Text = $"Updated: {entry.UpdatedAt.LocalDateTime:HH:mm:ss}",
+                            Foreground = new SolidColorBrush(Color.Parse("#FF93C5FD"))
+                        }
+                    }
+                }
+            });
+        }
+    }
+
+    private Border CreateSection(string title, Control content)
+    {
+        return new Border
+        {
+            Background = new SolidColorBrush(Color.Parse("#14000000")),
+            BorderBrush = new SolidColorBrush(Color.Parse("#3328B2FF")),
+            BorderThickness = new Thickness(1),
+            CornerRadius = new CornerRadius(14),
+            Padding = new Thickness(14),
+            Child = new StackPanel
+            {
+                Spacing = 12,
+                Children =
+                {
+                    new TextBlock
+                    {
+                        Text = title,
+                        FontSize = 16,
+                        FontWeight = FontWeight.SemiBold,
+                        Foreground = Brushes.White
+                    },
+                    content
+                }
+            }
+        };
+    }
+
+    private Control CreateInfoLine(string label, string value)
+    {
+        var grid = new Grid
+        {
+            ColumnDefinitions = new ColumnDefinitions("180,*"),
+            ColumnSpacing = 10
+        };
+
+        var labelText = new TextBlock
+        {
+            Text = label,
+            Foreground = new SolidColorBrush(Color.Parse("#FFBAE6FD")),
+            FontWeight = FontWeight.SemiBold,
+            TextWrapping = TextWrapping.Wrap
+        };
+        var valueText = new TextBlock
+        {
+            Text = value,
+            Foreground = Brushes.White,
+            TextWrapping = TextWrapping.Wrap
+        };
+
+        grid.Children.Add(labelText);
+        grid.Children.Add(valueText);
+        Grid.SetColumn(valueText, 1);
+        return grid;
+    }
+
+    private Control CreateCapabilityCard(SamplePluginCapabilityItem item)
+    {
+        return new Border
+        {
+            Background = new SolidColorBrush(Color.Parse("#0F082F49")),
+            BorderBrush = new SolidColorBrush(Color.Parse("#3338BDF8")),
+            BorderThickness = new Thickness(1),
+            CornerRadius = new CornerRadius(12),
+            Padding = new Thickness(12, 10),
+            Child = new StackPanel
+            {
+                Spacing = 4,
+                Children =
+                {
+                    new TextBlock
+                    {
+                        Text = item.Title,
+                        Foreground = Brushes.White,
+                        FontWeight = FontWeight.SemiBold
+                    },
+                    new TextBlock
+                    {
+                        Text = item.Detail,
+                        Foreground = new SolidColorBrush(Color.Parse("#FFE0F2FE")),
+                        TextWrapping = TextWrapping.Wrap
+                    }
+                }
+            }
+        };
+    }
+
+    private static Control CreateStatusHeader(
+        SamplePluginStatusEntry entry,
+        (Color Background, Color Border, Color Dot) palette)
+    {
+        var grid = new Grid
+        {
+            ColumnDefinitions = new ColumnDefinitions("Auto,*,Auto"),
+            ColumnSpacing = 8
+        };
+
+        var dot = new Border
+        {
+            Width = 10,
+            Height = 10,
+            CornerRadius = new CornerRadius(999),
+            Background = new SolidColorBrush(palette.Dot),
+            VerticalAlignment = VerticalAlignment.Center
+        };
+        var title = new TextBlock
+        {
+            Text = entry.Title,
+            FontSize = 15,
+            FontWeight = FontWeight.SemiBold,
+            Foreground = Brushes.White
+        };
+        var summary = new TextBlock
+        {
+            Text = entry.Summary,
+            Foreground = new SolidColorBrush(Color.Parse("#FFD7F2FF")),
+            HorizontalAlignment = HorizontalAlignment.Right
+        };
+
+        grid.Children.Add(dot);
+        grid.Children.Add(title);
+        grid.Children.Add(summary);
+        Grid.SetColumn(title, 1);
+        Grid.SetColumn(summary, 2);
+        return grid;
+    }
+
+    private static (Color Background, Color Border, Color Dot) GetPalette(SamplePluginHealthState state)
+    {
+        return state switch
+        {
+            SamplePluginHealthState.Healthy => (
+                Color.Parse("#1F115E59"),
+                Color.Parse("#665EEAD4"),
+                Color.Parse("#5EEAD4")),
+            SamplePluginHealthState.Faulted => (
+                Color.Parse("#291B1B"),
+                Color.Parse("#66F87171"),
+                Color.Parse("#F87171")),
+            _ => (
+                Color.Parse("#2B3A2A0D"),
+                Color.Parse("#66FBBF24"),
+                Color.Parse("#FBBF24"))
+        };
+    }
+}

LanAirApp/samples/LanMountainDesktop.SamplePlugin/SamplePluginStatusClockWidget.cs

@@ -0,0 +1,284 @@
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Layout;
+using Avalonia.Media;
+using Avalonia.Threading;
+using LanMountainDesktop.PluginSdk;
+
+namespace LanMountainDesktop.SamplePlugin;
+
+internal sealed class SamplePluginStatusClockWidget : Border
+{
+    private readonly PluginDesktopComponentContext _context;
+    private readonly SamplePluginRuntimeStateService _stateService;
+    private readonly SamplePluginClockService _clockService;
+    private readonly IPluginMessageBus _messageBus;
+    private readonly TextBlock _timeTextBlock;
+    private readonly TextBlock _subtitleTextBlock;
+    private readonly StackPanel _statusPanel;
+    private readonly Border _statusHost;
+    private readonly List<IDisposable> _subscriptions = [];
+    private string? _instanceId;
+
+    public SamplePluginStatusClockWidget(PluginDesktopComponentContext context)
+    {
+        _context = context;
+        _stateService = context.GetService<SamplePluginRuntimeStateService>()
+            ?? throw new InvalidOperationException("SamplePluginRuntimeStateService is not available.");
+        _clockService = context.GetService<SamplePluginClockService>()
+            ?? throw new InvalidOperationException("SamplePluginClockService is not available.");
+        _messageBus = context.GetService<IPluginMessageBus>()
+            ?? throw new InvalidOperationException("IPluginMessageBus is not available.");
+
+        _timeTextBlock = new TextBlock
+        {
+            Foreground = Brushes.White,
+            FontWeight = FontWeight.Bold,
+            HorizontalAlignment = HorizontalAlignment.Left
+        };
+        _subtitleTextBlock = new TextBlock
+        {
+            Foreground = new SolidColorBrush(Color.Parse("#FFBFE9FF")),
+            HorizontalAlignment = HorizontalAlignment.Left,
+            TextWrapping = TextWrapping.Wrap
+        };
+        _statusPanel = new StackPanel
+        {
+            Spacing = 8
+        };
+        _statusHost = new Border
+        {
+            Background = new SolidColorBrush(Color.Parse("#1F082F49")),
+            BorderBrush = new SolidColorBrush(Color.Parse("#5538BDF8")),
+            BorderThickness = new Thickness(1),
+            Child = _statusPanel
+        };
+
+        Background = new LinearGradientBrush
+        {
+            StartPoint = new RelativePoint(0, 0, RelativeUnit.Relative),
+            EndPoint = new RelativePoint(1, 1, RelativeUnit.Relative),
+            GradientStops =
+            [
+                new GradientStop(Color.Parse("#FF07111F"), 0),
+                new GradientStop(Color.Parse("#FF0C4A6E"), 0.55),
+                new GradientStop(Color.Parse("#FF0EA5E9"), 1)
+            ]
+        };
+        BorderBrush = new SolidColorBrush(Color.Parse("#6648C7FF"));
+        BorderThickness = new Thickness(1);
+        HorizontalAlignment = HorizontalAlignment.Stretch;
+        VerticalAlignment = VerticalAlignment.Stretch;
+        Child = new Grid
+        {
+            RowDefinitions = new RowDefinitions("Auto,*"),
+            RowSpacing = 14,
+            Children =
+            {
+                new StackPanel
+                {
+                    Spacing = 4,
+                    HorizontalAlignment = HorizontalAlignment.Left,
+                    Children =
+                    {
+                        _timeTextBlock,
+                        _subtitleTextBlock
+                    }
+                },
+                _statusHost
+            }
+        };
+
+        Grid.SetRow(((Grid)Child).Children[1], 1);
+
+        AttachedToVisualTree += OnAttachedToVisualTree;
+        DetachedFromVisualTree += OnDetachedFromVisualTree;
+        SizeChanged += OnSizeChanged;
+
+        RefreshClock(_clockService.CurrentTime);
+        UpdateSubtitle();
+        RefreshStatusPanel();
+        ApplyScale();
+    }
+
+    private void OnAttachedToVisualTree(object? sender, VisualTreeAttachmentEventArgs e)
+    {
+        if (string.IsNullOrWhiteSpace(_instanceId))
+        {
+            _instanceId = _stateService.RegisterComponentInstance(
+                _context.ComponentId,
+                _context.PlacementId,
+                _context.CellSize);
+        }
+
+        _stateService.MarkFrontendReady("Widget surface is connected to plugin services and communication.");
+        SubscribeToPluginBus();
+
+        RefreshClock(_clockService.CurrentTime);
+        UpdateSubtitle();
+        RefreshStatusPanel();
+    }
+
+    private void OnDetachedFromVisualTree(object? sender, VisualTreeAttachmentEventArgs e)
+    {
+        foreach (var subscription in _subscriptions)
+        {
+            subscription.Dispose();
+        }
+
+        _subscriptions.Clear();
+
+        if (string.IsNullOrWhiteSpace(_instanceId))
+        {
+            return;
+        }
+
+        _stateService.UnregisterComponentInstance(_instanceId);
+        _instanceId = null;
+    }
+
+    private void OnSizeChanged(object? sender, SizeChangedEventArgs e)
+    {
+        ApplyScale();
+        RefreshStatusPanel();
+    }
+
+    private void SubscribeToPluginBus()
+    {
+        if (_subscriptions.Count > 0)
+        {
+            return;
+        }
+
+        _subscriptions.Add(_messageBus.Subscribe<SamplePluginClockTickMessage>(message =>
+            Dispatcher.UIThread.Post(() => RefreshClock(message.CurrentTime))));
+
+        _subscriptions.Add(_messageBus.Subscribe<SamplePluginStateChangedMessage>(_ =>
+            Dispatcher.UIThread.Post(() =>
+            {
+                UpdateSubtitle();
+                RefreshStatusPanel();
+            })));
+    }
+
+    private void RefreshClock(DateTimeOffset currentTime)
+    {
+        _timeTextBlock.Text = currentTime.LocalDateTime.ToString("HH:mm:ss");
+    }
+
+    private void UpdateSubtitle()
+    {
+        var snapshot = _stateService.GetSnapshot();
+        _subtitleTextBlock.Text = string.IsNullOrWhiteSpace(_context.PlacementId)
+            ? $"Preview surface | placed: {snapshot.PlacedCount}"
+            : $"Placement {_context.PlacementId} | placed: {snapshot.PlacedCount}";
+    }
+
+    private void RefreshStatusPanel()
+    {
+        _statusPanel.Children.Clear();
+
+        var snapshot = _stateService.GetSnapshot();
+        var basis = GetLayoutBasis();
+        var titleSize = Math.Clamp(basis * 0.068, 11, 16);
+        var detailSize = Math.Clamp(basis * 0.052, 9, 13);
+
+        foreach (var entry in snapshot.StatusEntries)
+        {
+            var palette = GetPalette(entry.State);
+            _statusPanel.Children.Add(new Border
+            {
+                Background = new SolidColorBrush(palette.Background),
+                BorderBrush = new SolidColorBrush(palette.Border),
+                BorderThickness = new Thickness(1),
+                CornerRadius = new CornerRadius(12),
+                Padding = new Thickness(10, 8),
+                Child = new Grid
+                {
+                    RowDefinitions = new RowDefinitions("Auto,Auto"),
+                    ColumnDefinitions = new ColumnDefinitions("Auto,*,Auto"),
+                    ColumnSpacing = 8,
+                    Children =
+                    {
+                        new Border
+                        {
+                            Width = Math.Clamp(basis * 0.038, 8, 11),
+                            Height = Math.Clamp(basis * 0.038, 8, 11),
+                            CornerRadius = new CornerRadius(999),
+                            Background = new SolidColorBrush(palette.Dot),
+                            VerticalAlignment = VerticalAlignment.Center
+                        },
+                        new TextBlock
+                        {
+                            Text = entry.Title,
+                            FontSize = titleSize,
+                            FontWeight = FontWeight.SemiBold,
+                            Foreground = Brushes.White,
+                            TextWrapping = TextWrapping.Wrap
+                        },
+                        new TextBlock
+                        {
+                            Text = entry.Summary,
+                            FontSize = detailSize,
+                            Foreground = new SolidColorBrush(Color.Parse("#FFD7F2FF")),
+                            HorizontalAlignment = HorizontalAlignment.Right,
+                            TextAlignment = TextAlignment.Right,
+                            VerticalAlignment = VerticalAlignment.Center
+                        },
+                        new TextBlock
+                        {
+                            Text = entry.Detail,
+                            FontSize = detailSize,
+                            Foreground = new SolidColorBrush(Color.Parse("#FFD7F2FF")),
+                            TextWrapping = TextWrapping.Wrap
+                        }
+                    }
+                }
+            });
+
+            var row = (Grid)((Border)_statusPanel.Children[^1]).Child!;
+            Grid.SetColumn(row.Children[1], 1);
+            Grid.SetColumn(row.Children[2], 2);
+            Grid.SetColumnSpan(row.Children[3], 3);
+            Grid.SetRow(row.Children[3], 1);
+        }
+    }
+
+    private void ApplyScale()
+    {
+        var basis = GetLayoutBasis();
+        Padding = new Thickness(Math.Clamp(basis * 0.09, 16, 26));
+        CornerRadius = new CornerRadius(Math.Clamp(basis * 0.14, 20, 34));
+        _timeTextBlock.FontSize = Math.Clamp(basis * 0.22, 30, 58);
+        _subtitleTextBlock.FontSize = Math.Clamp(basis * 0.062, 11, 17);
+        _statusHost.Padding = new Thickness(Math.Clamp(basis * 0.045, 10, 18));
+        _statusHost.CornerRadius = new CornerRadius(Math.Clamp(basis * 0.09, 14, 22));
+        _statusPanel.Spacing = Math.Clamp(basis * 0.024, 6, 10);
+    }
+
+    private double GetLayoutBasis()
+    {
+        var width = Bounds.Width > 1 ? Bounds.Width : _context.CellSize * 4;
+        var height = Bounds.Height > 1 ? Bounds.Height : _context.CellSize * 4;
+        return Math.Max(_context.CellSize * 4, Math.Min(width, height));
+    }
+
+    private static (Color Background, Color Border, Color Dot) GetPalette(SamplePluginHealthState state)
+    {
+        return state switch
+        {
+            SamplePluginHealthState.Healthy => (
+                Color.Parse("#1F0F766E"),
+                Color.Parse("#4D5EEAD4"),
+                Color.Parse("#5EEAD4")),
+            SamplePluginHealthState.Faulted => (
+                Color.Parse("#29B91C1C"),
+                Color.Parse("#66F87171"),
+                Color.Parse("#F87171")),
+            _ => (
+                Color.Parse("#1F7C2D12"),
+                Color.Parse("#66FDBA74"),
+                Color.Parse("#FDBA74"))
+        };
+    }
+}

LanAirApp/samples/LanMountainDesktop.SamplePlugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "LanMountainDesktop.SamplePlugin",
+  "name": "LanMountain Sample Plugin",
+  "description": "Example plugin used to validate PluginSdk loading and isolation.",
+  "author": "LanMountainDesktop",
+  "version": "1.0.0",
+  "apiVersion": "1.0.0",
+  "entranceAssembly": "LanMountainDesktop.SamplePlugin.dll"
+}

LanAirApp/samples/README.md

@@ -0,0 +1,11 @@
+# 示例插件
+
+本目录用于存放阑山桌面的示例开发插件。
+
+当前示例：
+- `LanMountainDesktop.SamplePlugin`
+
+说明：
+- 这个插件是**示例开发插件**，用于演示插件项目结构、服务注册、设置页注册、桌面组件注册、`.laapp` 打包与安装流程。
+- 开发新插件时，建议直接从这个示例插件复制一份再修改。
+- 示例插件属于 `LanAirApp/` 对外开发工作区；宿主应用里的插件运行时与解析实现位于 `LanMountainDesktop/plugins/`。

LanAirApp/standards/README.md

@@ -0,0 +1,11 @@
+# 插件标准文件
+
+这里存放 LanMountainDesktop 插件开发所使用的标准模板与约定文件。
+
+当前标准：
+- 安装包扩展名：`.laapp`
+- 插件清单文件名：`plugin.json`
+- 多语言资源目录：`Localization/`
+- 建议内置语言文件：`zh-CN.json`、`en-US.json`
+
+创建新插件时，建议优先参考本目录中的模板文件。

LanAirApp/standards/plugin.template.json

@@ -0,0 +1,9 @@
+{
+  "id": "LanMountainDesktop.YourPlugin",
+  "name": "Your Plugin",
+  "description": "Describe what your plugin adds to LanMountainDesktop.",
+  "author": "Your Name",
+  "version": "1.0.0",
+  "apiVersion": "1.0.0",
+  "entranceAssembly": "LanMountainDesktop.YourPlugin.dll"
+}

LanAirApp/tools/LanMountainDesktop.PluginPackager/LanMountainDesktop.PluginPackager.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <Version>1.0.0</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\LanMountainDesktop.PluginSdk\LanMountainDesktop.PluginSdk.csproj" />
+  </ItemGroup>
+
+</Project>

LanAirApp/tools/LanMountainDesktop.PluginPackager/Program.cs

@@ -0,0 +1,136 @@
+using System.IO.Compression;
+using LanMountainDesktop.PluginSdk;
+
+return await RunAsync(args);
+
+static async Task<int> RunAsync(string[] args)
+{
+    if (args.Length == 0 || args.Any(arg => string.Equals(arg, "--help", StringComparison.OrdinalIgnoreCase)))
+    {
+        PrintUsage();
+        return 0;
+    }
+
+    string? inputDirectory = null;
+    string? outputPath = null;
+    var overwrite = false;
+
+    for (var i = 0; i < args.Length; i++)
+    {
+        switch (args[i])
+        {
+            case "--input":
+                inputDirectory = ReadValue(args, ref i, "--input");
+                break;
+            case "--output":
+                outputPath = ReadValue(args, ref i, "--output");
+                break;
+            case "--overwrite":
+                overwrite = true;
+                break;
+            default:
+                throw new InvalidOperationException($"Unknown argument '{args[i]}'.");
+        }
+    }
+
+    if (string.IsNullOrWhiteSpace(inputDirectory))
+    {
+        throw new InvalidOperationException("Missing required argument '--input'.");
+    }
+
+    var fullInputDirectory = Path.GetFullPath(inputDirectory);
+    if (!Directory.Exists(fullInputDirectory))
+    {
+        throw new DirectoryNotFoundException($"Plugin build directory '{fullInputDirectory}' was not found.");
+    }
+
+    var manifestPath = Path.Combine(fullInputDirectory, PluginSdkInfo.ManifestFileName);
+    if (!File.Exists(manifestPath))
+    {
+        throw new FileNotFoundException(
+            $"Plugin build directory '{fullInputDirectory}' does not contain '{PluginSdkInfo.ManifestFileName}'.",
+            manifestPath);
+    }
+
+    var manifest = PluginManifest.Load(manifestPath);
+    var entranceAssemblyPath = manifest.ResolveEntranceAssemblyPath(manifestPath);
+    if (!File.Exists(entranceAssemblyPath))
+    {
+        throw new FileNotFoundException(
+            $"The entrance assembly declared by '{PluginSdkInfo.ManifestFileName}' was not found.",
+            entranceAssemblyPath);
+    }
+
+    outputPath ??= Path.Combine(
+        Path.GetDirectoryName(fullInputDirectory) ?? fullInputDirectory,
+        BuildPackageFileName(manifest.Id));
+
+    var fullOutputPath = Path.GetFullPath(outputPath);
+    var inputDirectoryWithSeparator = EnsureTrailingSeparator(fullInputDirectory);
+    if (fullOutputPath.StartsWith(inputDirectoryWithSeparator, StringComparison.OrdinalIgnoreCase))
+    {
+        throw new InvalidOperationException("The output .laapp path cannot be placed inside the source directory.");
+    }
+
+    var destinationDirectory = Path.GetDirectoryName(fullOutputPath);
+    if (string.IsNullOrWhiteSpace(destinationDirectory))
+    {
+        throw new InvalidOperationException("Failed to determine the output directory for the .laapp package.");
+    }
+
+    Directory.CreateDirectory(destinationDirectory);
+    if (File.Exists(fullOutputPath))
+    {
+        if (!overwrite)
+        {
+            throw new InvalidOperationException(
+                $"The output package '{fullOutputPath}' already exists. Pass '--overwrite' to replace it.");
+        }
+
+        File.Delete(fullOutputPath);
+    }
+
+    await Task.Run(() => ZipFile.CreateFromDirectory(
+        fullInputDirectory,
+        fullOutputPath,
+        CompressionLevel.Optimal,
+        includeBaseDirectory: false));
+
+    Console.WriteLine($"Packaged '{manifest.Name}' to '{fullOutputPath}'.");
+    return 0;
+}
+
+static string ReadValue(IReadOnlyList<string> args, ref int index, string optionName)
+{
+    var nextIndex = index + 1;
+    if (nextIndex >= args.Count)
+    {
+        throw new InvalidOperationException($"Missing value for '{optionName}'.");
+    }
+
+    index = nextIndex;
+    return args[nextIndex];
+}
+
+static string BuildPackageFileName(string pluginId)
+{
+    var invalidChars = Path.GetInvalidFileNameChars();
+    var safeName = new string(pluginId.Select(ch => invalidChars.Contains(ch) ? '_' : ch).ToArray());
+    return safeName + PluginSdkInfo.PackageFileExtension;
+}
+
+static string EnsureTrailingSeparator(string path)
+{
+    return path.EndsWith(Path.DirectorySeparatorChar.ToString(), StringComparison.Ordinal)
+        ? path
+        : path + Path.DirectorySeparatorChar;
+}
+
+static void PrintUsage()
+{
+    Console.WriteLine("LanMountainDesktop.PluginPackager");
+    Console.WriteLine("Usage:");
+    Console.WriteLine("  --input <plugin build directory>   Required");
+    Console.WriteLine("  --output <path to .laapp>          Optional");
+    Console.WriteLine("  --overwrite                        Optional");
+}