v0.2.2 更新日志

发布日期：2026 年 2 月 27 日

v0.2.2 是 v0.2.x 的功能迭代版本，包含一处破坏性变更（插件目录重命名）和一项新功能（插件专属数据目录支持）。

破坏性变更

插件目录重命名：Plugins/ → plugins/

主程序扫描的插件目录已由 Plugins 重命名为 plugins（首字母改为小写），以符合跨平台目录命名规范。

环境	影响
Linux / macOS	⚠️ 受影响：需将现有 Plugins/ 目录手动重命名为 plugins/，否则升级后所有插件无法加载
Windows	✅ 不受影响：文件系统大小写不敏感，无需任何操作

详细迁移步骤请参阅 用户侧迁移指南。

新增内容

新增：插件专属数据目录（DataDirectory 与 GetDataPath）

插件现在可通过两个新的接口成员访问专属数据目录，适用于存储数据库文件、密钥对、缓存、导出文件等持久化数据。

DataDirectory 属性

返回插件专属数据目录的完整路径，默认为 {BaseDir}/data/{插件名}/。

// 默认实现
string DataDirectory => Path.Combine(AppContext.BaseDirectory, "data", Name);

TIP

DataDirectory 仅作为只读属性使用，不建议在插件中重写此属性。为了插件生态的标准化和规范化，插件的所有持久化文件应始终存放在专属数据目录内。

GetDataPath(string relativePath) 方法

DataDirectory 的路径拼接快捷方法，支持相对路径和绝对路径两种用法：

// 相对路径 → {DataDirectory}/keys/private.pem
var keyPath = GetDataPath("keys/private.pem");

// 绝对路径 → 直接返回该路径，DataDirectory 被忽略
var keyPath = GetDataPath("/mnt/hsm/private.pem");

绝对路径的穿透行为由 Path.Combine 的原生规则决定。这使得用户可以通过在配置文件中填写绝对路径，将文件存储到 data 目录以外的任意位置（例如 HSM 挂载路径）。

自动目录创建

主程序在注册插件服务时，会自动确保 DataDirectory 指向的目录已存在，插件无需手动调用 Directory.CreateDirectory。

启动后的目录结构示例：

{BaseDir}/
├── config/
│   └── my.plugin.json
└── data/
    └── my.plugin/          ← 主程序自动创建
        ├── plugin.db
        └── keys/
            └── private.pem

与配置文件配合使用

推荐在 DefaultConfig 中将路径字段设为相对路径字符串，Core 会在首次启动时将其写入配置文件。在 RegisterServices 中再通过 GetDataPath 解析为绝对路径后使用。插件的所有持久化文件应始终存放在专属数据目录内。

public object? DefaultConfig => new MySettings
{
    // ✅ 推荐：在 DefaultConfig 中存相对路径
    PrivateKeyPath = "keys/private.pem",
    DatabasePath   = "data.db"
};

public void RegisterServices(IServiceCollection services, IConfiguration configuration)
{
    var settings = configuration.Get<MySettings>()!;

    // GetDataPath 将相对路径解析为绝对路径：
    // "data.db"          → {DataDirectory}/data.db
    // "keys/private.pem" → {DataDirectory}/keys/private.pem
    var resolvedKeyPath = GetDataPath(settings.PrivateKeyPath);

    if (!File.Exists(resolvedKeyPath))
        GenerateKeyPair(resolvedKeyPath);

    services.Configure<MySettings>(configuration);
}

兼容性说明

• 两个新成员均提供了默认实现，现有插件无需任何代码修改即可编译通过
• 使用 Version="0.2.*" 的 NuGet 包引用会自动获取本版本
• 需将主程序更新至 v0.2.2 以启用自动数据目录创建能力；仅更新协议库不影响现有功能