MioKit.Plugin.Templates 1.2.0

MioKit 插件 dotnet 模板

这个包提供两套 dotnet new 项目模板，用来统一创建 MioKit 插件项目。

安装模板

本地安装

开发或测试模板包时，可以直接从模板包项目目录安装：

dotnet new install .\templates\MioKit.Plugin.Templates --force

也可以从本地 .nupkg 安装：

dotnet new install .\PublishNuget\nupkgs\MioKit.Plugin.Templates.1.0.0.nupkg --force

在线安装（NuGet 发布后）

模板包发布到 NuGet 后，使用包 ID 在线安装：

dotnet new install MioKit.Plugin.Templates

安装指定版本：

dotnet new install MioKit.Plugin.Templates::1.0.0

更新模板：

dotnet new update

卸载模板：

dotnet new uninstall MioKit.Plugin.Templates

查看模板

dotnet new list miokit

查看标准插件模板参数：

dotnet new miokit-plugin -h

查看 WebView2 插件模板参数：

dotnet new miokit-plugin-webview2 -h

创建标准插件

# -n 含 '.' 时，plugin.json 的 name 默认取最后一段（如 MioKit.Clipboard → Clipboard）
dotnet new miokit-plugin -n MioKit.Clipboard `
  --pluginId com.example.plugin.clipboard `
  --description "剪贴板插件" `
  --pluginAuthor "your-name"

# 也可显式指定显示名称
dotnet new miokit-plugin -n MioKit.Clipboard --displayName "剪贴板"

创建 WebView2 插件

dotnet new miokit-plugin-webview2 -n MyWebPlugin `
  --pluginId com.example.plugin.my-web-plugin `
  --displayName "我的 Web 插件" `
  --description "使用 WebView2 UI 的 MioKit 插件" `
  --pluginAuthor "your-name"

WebView2 模板已内置 vue-ui/（内容来自 miokit-ui-template），dotnet new 后即可开发，无需额外克隆或初始化脚本。

前置步骤：安装 Agent skills

插件开发相关 Agent skills 不随模板生成到项目内，而是由同级项目 MioKit.CodeAgent 通过 skills.sh 提供。

npx skills add tiny-isle/MioKit.CodeAgent

安装后可使用 miokit-plugin-new、miokit-plugin-core、miokit-plugin-avalonia-ui 和 miokit-plugin-webview2。WebView2 模板不再生成项目内 .agents/skills。

首次开发前安装依赖：

cd plugin/vue-ui
pnpm install

前端开发：

cd plugin/vue-ui
pnpm dev

前端发布构建：

cd plugin/vue-ui
pnpm build

共享 JavaScript runtime

宿主将用户数据目录中的共享 runtime 映射为 https://jsruntime.local/。插件需要追加大型前端运行时资源时， 通过 MioAppContext.Current.Environment.JavaScriptRuntimeDirectory 取得物理目录，并写入插件自己的唯一子目录； 不要修改宿主管理的 monaco0.54.0。Monaco 可直接从 https://jsruntime.local/monaco0.54.0/vs 加载。

模板参数

两套模板支持相同的业务参数。

模板会自动生成插件根类型 Guid：

搜索组、节点类型与示例数据不在模板中生成；请按 miokit-plugin-core skill 添加。

生成后的目录结构

两套模板都会生成解决方案、插件项目与预览宿主：

MyPlugin/
├── MyPlugin.slnx
├── pack.ps1
├── publish.ps1
├── plugin/
│   ├── docs/
│   │   ├── requirements.md
│   │   ├── lifecycle.md
│   │   └── features-and-properties.md
│   ├── Properties/
│   │   ├── _global.cs
│   │   └── AssemblyInfo.cs
│   ├── MyPlugin.csproj
│   ├── MyPluginConst.cs
│   ├── MyPluginPlugin.cs
│   ├── MyPluginRegister.cs
│   └── plugin.json
├── preview/
└── Publish/

模板不再用 README.md 强行占位空目录。业务代码按需创建以下常用目录：

plugin/
├── Assets/       # icon、图片、静态资源
├── Features/     # IMyFeature.cs + IMyFeature.Extensions.cs
├── Models/       # DTO、配置、缓存记录
├── Nodes/        # MioObject 搜索组、可执行节点、树结构
├── Services/     # 扫描、同步、缓存、桥接等服务
└── Views/        # Avalonia/WebView2 视图

WebView2 模板额外包含：

MyWebPlugin/
└── plugin/
    ├── vue-ui/              # Vue 3 前端源码，随模板发布
    ├── ui/dist/             # pnpm build 输出，构建后生成
    ├── docs/webview2-ui.md
    ├── Services/TimerJsService.cs
    ├── Services/HotKeyCaptureJsService.cs
    └── Views/PluginWebView.axaml

关键文件

Properties/_global.cs

集中放置全局 using，包括：

global using MioKit.Sdk;
global using Autofac;
global using Microsoft.Extensions.DependencyInjection;

WebView2 模板还会额外包含：

global using Avalonia.Controls;
global using CommunityToolkit.Mvvm.ComponentModel;
global using MioKit.Webview2.Core;

Properties/AssemblyInfo.cs

配置 Avalonia XAML 命名空间：

using Avalonia.Metadata;

[assembly: XmlnsDefinition("https://github.com/tiny-isle/MioKit", "MioKit.Framework.Controls")]
[assembly: XmlnsDefinition("https://github.com/tiny-isle/MioKit", "MioKit.Framework.UserControls")]
[assembly: XmlnsPrefix("https://github.com/tiny-isle/MioKit", "mio")]

plugin.json

模板会根据参数生成插件元数据：

{
  "metadataVersion": "1.0",
  "id": "com.example.plugin.my-plugin",
  "name": "我的插件",
  "description": "# 我的插件\n\n这里可填写 **Markdown** 使用说明。",
  "assembly": "MyPlugin.dll",
  "minSdkVersion": "2.0.0",
  "nugetDependents": []
}

pluginVersion、releaseState、releaseDate 禁止写入清单。NuGet PackageVersion 是唯一版本来源，其 SemVer 后缀决定正式/预发布状态。

配置 plugin.json.icon 时，模板会同步生成 NuGet PackageIcon 元数据；图标文件仍需按同一路径复制并 Pack。只有文件存在但 nuspec 没有 icon 时，NuGet 目录不会生成可供商店使用的 iconUrl。

pack.ps1 / publish.ps1

模板提供可继续定制的初始脚本：

.\pack.ps1 -PackageId Example.MioKit.MyPlugin -PackageVersion 1.2.0
.\publish.ps1 -PackageId Example.MioKit.MyPlugin -PackageVersion 1.3.0-beta.1 -PackFirst

打包脚本会检查入口 DLL、plugin.json、声明资源、宿主 DLL、nuspec JSON 信封，以及 nuspec icon 与清单图标路径的一致性。发布脚本按 Process → User → Machine 读取 miokit-nuget-apikey、miokit-nuget-name、miokit-nuget-url，且不修改全局 NuGet 配置。

打包模板

# 仅打包模板包
.\PublishNuget\scripts\pack.ps1 -Projects MioKit.Plugin.Templates

# 打包全部
.\PublishNuget\scripts\pack.ps1

版本号在 PublishNuget/versions.json 中维护；输出默认在 PublishNuget/nupkgs/。

发布到 NuGet：

.\PublishNuget\scripts\publish.ps1 -Projects MioKit.Plugin.Templates

生成的包示例：

PublishNuget/nupkgs/MioKit.Plugin.Templates.1.0.0.nupkg

发布到 NuGet 前检查

发布前建议确认：

• 已用 PublishNuget 打包
• dotnet new install <nupkg> --force 可以安装成功
• dotnet new list miokit 能看到两个模板
• dotnet new miokit-plugin ... 能生成标准插件
• dotnet new miokit-plugin-webview2 ... 能生成 WebView2 插件
• 两种生成项目都可以 dotnet build
• plugin.json 中的 id、name、assembly 替换正确
• NuGet PackageVersion 与 PackageId 是唯一包身份来源；不要在 plugin.json 重复维护它们
• 稳定/预发布状态只由发布者传入的 NuGet SemVer 决定
• 生成项目根目录含可用的 pack.ps1 与 publish.ps1
• Properties/_global.cs 和 Properties/AssemblyInfo.cs 存在
• 文档中的推荐目录结构与模板实际输出一致
• npx skills add tiny-isle/MioKit.CodeAgent 可以安装插件开发 skill

版本约定

包版本以各模板生成项目中的 *.csproj 的 PackageReference 为准，与 MioKit.Plugin.Templates 一同发布；skill 文档（nuget.md 等）不单独维护版本号表。