SecRandom 示例插件

这是 SecRandom 的示例插件仓库，演示当前版本插件 API 的推荐用法。

这是一个最小示例：只注册一个设置页，用来展示插件信息。

当前目标插件 API 版本：3.1.5（对应 SecRandom 主程序 v3.1.5）。

插件能做什么

能力	对应 API	示例位置
插件入口与生命周期	PluginBase.Initialize / OnAppStarted / OnAppStopping / DisposeAsync	ExamplePlugin/Plugin.cs
注册设置页	services.AddSettingsPage<T>("名称") + [PageInfo]	ExamplePlugin/Views/SettingsPages/ExampleSettingsPage.axaml.cs
读取宿主服务	IAppHost.Host.Services / IAppHost.TryGetService<T>()	同上
读取清单与加载状态	IPluginManager.Plugins → PluginInfo.Manifest / LoadStatus	同上
插件私有数据目录	PluginBase.PluginConfigFolder	ExamplePlugin/PluginStateStore.cs

目录结构

ExamplePlugin/
├── manifest.yml                     # 插件清单（宿主只认这个文件）
├── icon.png                         # 插件图标
├── README.md                        # 插件说明（随包发布）
├── Plugin.cs                        # 插件入口：PluginBase 实现
├── PluginStateStore.cs              # 在插件配置目录里读写自己的数据
├── SecRandom.ExamplePlugin.csproj   # 项目文件（引用 SecRandom.PluginSdk）
└── Views/SettingsPages/
    ├── ExampleSettingsPage.axaml
    └── ExampleSettingsPage.axaml.cs
scripts/
├── build.ps1                        # 构建 + 打包
└── validate-package.ps1             # 校验 .srpx 包结构

构建

需要 .NET SDK 10 与网络（首次还原 SecRandom.PluginSdk）。

powershell -ExecutionPolicy Bypass -File scripts\build.ps1

构建 + 打包 + 校验一把梭，产物在 ExamplePlugin\srpx\SecRandom.ExamplePlugin.srpx。

只想构建、不校验：

powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -NoValidate

引用本地的客户端源码

当 SecRandom.PluginSdk 还没有对应版本的 NuGet 包，或者想直接对着本地客户端代码调试时：

powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -UseLocalSdk -SecRandomClientRoot D:\code\SecRandom-C

这会把 NuGet 包引用换成对 SecRandom.PluginSdk.csproj 的项目引用。

安装到客户端

主程序支持两种加载方式。

1. 安装 .srpx 包（推荐，和真实用户一致）

把构建出来的包放进主程序数据目录的 cache\plugin-packages\ 下，然后重启主程序：

# 主程序数据目录：<主程序目录>\data
# 把包复制进去即可，重启后主程序会自行校验、解压到 data\plugins\<插件id>\ 并删除包
Copy-Item ExamplePlugin\srpx\SecRandom.ExamplePlugin.srpx `
    D:\code\SecRandom-C\SecRandom.Desktop\bin\Release\net10.0-windows10.0.19041.0\data\cache\plugin-packages\

主程序启动时会扫描该目录下的 *.srpx：先校验包体积/清单，再解压到暂存目录， 确认包根有 manifest.yml 后移动到 data\plugins\<manifest id>\，最后删除包文件。 校验不通过时会在包旁边留下 <包名>.rejected 文件，里面写着原因。

2. 用外部插件目录启动（开发调试）

启动参数 --epp（等价写法 --externalPluginPath）可以额外指定一个插件目录：

# 1) 构建插件
powershell -ExecutionPolicy Bypass -File scripts\build.ps1

# 2) 把插件输出整理成 <父目录>\<插件id>\ 的形态
$stage = 'D:\code\SecRandom-ExamplePlugins\artifacts\epp-test\com.example.plugin'
New-Item -ItemType Directory -Force $stage | Out-Null
Copy-Item ExamplePlugin\bin\Release\net10.0\* $stage -Exclude *.pdb -Force

# 3) 启动主程序：--epp 指向“包含插件子目录的父目录”，不是插件目录本身
D:\code\SecRandom-C\SecRandom.Desktop\bin\Release\net10.0-windows10.0.19041.0\SecRandom.Desktop.exe `
    --epp D:\code\SecRandom-ExamplePlugins\artifacts\epp-test

--epp 传进去的目录，主程序只会枚举它的子目录，并且每个子目录都必须是一个插件目录 （直接带 manifest.yml）。把 --epp 指向 ...\ExamplePlugin\bin\Release\net10.0 这种 “插件文件就摊在这一层”的目录是发现不到插件的。

启动后：

1. 打开 设置，左侧应该出现 SecRandom 示例插件（PluginBase.Initialize 里注册的设置页）；
2. 设置页会显示清单信息、加载状态、配置目录与状态文件路径。

插件自己的日志会写进主程序日志（data\logs\log-*.log），搜索 SecRandom.ExamplePlugin 即可确认加载情况。

插件清单（manifest.yml）

id: com.example.plugin
name: SecRandom 示例插件
version: 1.0.0
apiVersion: 3.1.5
entranceAssembly: SecRandom.ExamplePlugin.dll
author: SECTL

• apiVersion 的主版本必须与宿主主版本一致（当前为 3），否则宿主会拒绝加载；
• entranceAssembly 必须是包内的相对路径，不能是绝对路径、也不能包含 ..；
• 仓库里已经删掉了旧版的 plugin.json / metadata.yml，宿主不再读取它们。

发布

srpx/SecRandom.ExamplePlugin.srpx 就是可以直接分发的插件包。发布到插件市场时， 需要把包上传到可下载地址，并把 SHA-256、版本、apiVersion 等信息登记到插件索引仓库 （SECTL/SecRandom-PluginIndex）。