Plugin Package

插件包结构

PCL Nex 插件以目录为单位安装。每个插件目录必须包含 plugin.json，并包含入口 DLL 或入口脚本。加载器会扫描 PCL/Plugins/*/plugin.json，同时兼容旧的 PCL/Plugins/*.dll 平铺 DLL 布局。

C# DLL 插件目录

Plugins/
  com.example.hello/
    plugin.json
    HelloPlugin.dll
    DependencyA.dll
    Resources/
      icon.png

plugin.json 示例：

{
  "id": "com.example.hello",
  "name": "Hello Plugin",
  "version": "1.0.0.0",
  "author": "Example",
  "description": "A minimal C# plugin.",
  "runtime": "dotnet",
  "entryAssembly": "HelloPlugin.dll",
  "minApiVersion": "1.2.1.0",
  "capabilities": ["ContributeTools"]
}

JavaScript 插件目录

Plugins/
  com.example.script/
    plugin.json
    main.js
    lib/
      helper.js

plugin.json 示例：

{
  "id": "com.example.script",
  "name": "Script Plugin",
  "version": "1.0.0.0",
  "author": "Example",
  "description": "A JavaScript plugin.",
  "runtime": "javascript-v8",
  "entryScript": "main.js",
  "minApiVersion": "1.2.1.0",
  "capabilities": []
}

关键字段

字段	运行时	必填	说明
id	全部	是	插件唯一 ID，建议反向域名格式，如 com.example.myplugin
name	全部	是	插件显示名称
version	全部	是	插件版本号，需能解析为 System.Version
author	全部	建议	作者
description	全部	建议	简短描述
runtime	全部	否	dotnet 或 javascript-v8，省略时默认为 dotnet
entryAssembly	C#	是	入口 DLL 相对路径，如 HelloPlugin.dll 或 lib/HelloPlugin.dll
entryScript	JS	是	入口脚本相对路径，如 main.js
minApiVersion	全部	是	插件需要的最低 SDK API 版本
maxApiVersion	全部	否	最高兼容 SDK API 版本
minHostVersion	全部	否	最低启动器版本
maxHostVersion	全部	否	最高兼容启动器版本
capabilities	全部	否	能力声明数组
homepageUrl	全部	否	主页或项目地址
license	全部	否	许可证标识
icon	全部	否	图标相对路径
screenshots	全部	否	截图相对路径数组

plugin.json 使用大小写不敏感的字段名，支持字符串形式的能力枚举和版本号字符串。推荐仍按上表的 camelCase 字段书写。

ID 命名建议

插件 ID 应稳定、唯一、全小写，推荐：

com.example.myplugin
org.example.tools.backup
net.example.launcher.quicktools

避免使用：

My Plugin
hello plugin
plugin#1

插件 ID 会影响用户识别、启用状态、数据目录和自保禁用记录，发布后不要随意更改。

入口文件规则

C# 插件：

• runtime 为 dotnet 或省略。
• entryAssembly 指向插件主 DLL。
• DLL 内应有一个 public 入口类实现 IPclPlugin。
• 入口类通常使用 [Plugin(...)] 标注。
• plugin.json 用于包校验和定位 DLL，运行时入口信息来自 DLL 内的 [Plugin]。
• 不要把 PCL.Plugin.Abstractions.dll 放进插件包。

JavaScript 插件：

• runtime 必须为 javascript-v8。
• entryScript 指向入口脚本。
• 入口脚本定义全局 load(ctx)。
• 可选定义全局 unload()。
• JS 插件运行在 Jint 中，不是 Node.js，也不是浏览器环境。

依赖文件

插件可以携带自己的依赖 DLL、资源文件、配置模板、说明文档等。C# 插件的第三方 DLL 会由插件自己的加载上下文解析；共享的 PCL.Plugin.Abstractions、PCL.Core、System.*、Microsoft.* 程序集会交给宿主默认上下文。

插件运行时产生的持久化数据应写入 context.DataDirectory。配置 API 会在该目录下维护 config.ini。

不要修改启动器程序目录中的文件，也不要把运行数据写回插件安装目录。