Skip to content

Plugin Package

Jump to bottom
Ling edited this page Jul 22, 2026 · 3 revisions

插件包结构

PCL Nex 插件以 PCLX 包发布，以独立目录安装。包根目录必须存在 plugin.json，并至少包含一个主程序集和一个 Mixin 配置。

推荐目录

example.plugin.pclx
  plugin.json
  README.md
  lib/
    Example.Plugin.dll
    Example.Plugin.pdb
    ThirdParty.Dependency.dll
  mixins/
    example.plugin.mixins.json
  assets/
    logo.png
    screenshot-1.png

安装后大致对应：

PCL/Plugins/example.plugin/
  plugin.json
  lib/...
  mixins/...
  assets/...

加载器扫描已安装插件目录中的 plugin.json。

最小 plugin.json

{
  "id": "example.plugin",
  "name": "Example Plugin",
  "version": "1.0.0",
  "author": "Example",
  "description": "Example plugin.",
  "pclCoreVersion": "2026.07.1",
  "entryAssembly": "lib/Example.Plugin.dll",
  "mixinConfig": "mixins/example.plugin.mixins.json"
}

可以用 mixinConfigs 声明多个配置：

{
  "mixinConfigs": [
    "mixins/core.mixins.json",
    "mixins/ui.mixins.json"
  ]
}

mixinConfig 和 mixinConfigs 可以同时存在，重复路径会按大小写不敏感去重。

路径规则

  • entryAssembly、Mixin 配置和包内 Logo 使用相对于包根目录的路径。
  • 这些路径不能逃出插件目录。
  • 不要使用绝对路径、驱动器路径或包含 .. 的路径。
  • logo 也可以是 HTTP/HTTPS URL；包内资源优先使用正斜杠。
  • plugin.json 必须在包根目录，不能只放在更深的子目录中作为正式发布布局。

主程序集与依赖程序集

entryAssembly 指向插件的主程序集。插件自己的第三方 DLL 可以放在同目录或其子目录中，由插件加载上下文解析。

不要把下列程序集打进包中：

  • PCL.Core.dll
  • 启动器自带的框架程序集

前置插件的主程序集会共享给依赖插件。需要复用 Python、JavaScript 或公共服务时，应由前置 Bridge 插件公开稳定 API，再通过 dependencies 声明顺序和版本。

PCLX 安全处理

安装器会：

  • 在临时目录下载或导入包。
  • 对市场或 Manifest 安装校验完整 64 位十六进制 SHA-256。
  • 检查 ZIP 路径穿越和解压后的路径边界。
  • 校验插件 ID、入口程序集、Mixin 配置和依赖声明。
  • 先写 staging 目录，再切换正式安装目录。
  • 更新时保留原安装目录备份，失败后恢复已安装版本、安装记录和启用状态。

不要依赖安装器接受不完整的包。缺少入口程序集或任一声明的 Mixin 配置都会使安装失败。

插件 ID

ID 最长 128 个字符，必须至少包含两个非空点分段。每段只允许 ASCII 字母、数字、下划线和连字符。

example.plugin
com.example.download-tools
pcl.bridge.python

ID 用于安装目录、启用状态、依赖关系和更新记录。发布后不要更改。

安装来源记录

安装器会记录插件来源：

  • 从 Git 仓库安装时保存 Git 仓库地址。
  • 从单插件 manifest.json 安装时保存 Manifest 地址，并加入本地 PluginManifestSubscriptions，后续更新继续读取同一地址。
  • 从商店安装时沿用商店条目的 Manifest 或仓库来源。

配置最终持久化到启动器本地配置系统，包括 PCL/config.v1.yaml 中的插件配置项。

Clone this wiki locally