FAQ

常见问题

插件项目引用哪个程序集？

引用目标启动器版本的 PCL.Core.dll，并设置 <Private>false</Private>。PCL.Mixin 命名空间直接包含在该程序集中。

Core 如何发现插件代码？

程序集通过 Mixin 配置列出 [Mixin] 类型，Core 扫描并应用这些类型中的操作。

如何在启动器创建完成后执行代码？

例如注入 PCL.FormMain 构造函数返回点：

[Mixin("PCL.FormMain")]
internal static class FormMainMixin
{
    [Inject(".ctor", At = MixinAt.Return)]
    private static void AfterCreated([This] object window)
    {
    }
}

真实插件还应考虑构造函数重载、调用次数和 UI 线程。

可以修改启动器任意代码吗？

可以声明主程序或其他已加载插件中的目标，但不是“任何位置都一定能注入”。目标类型必须已加载，方法和 IL 必须能解析，处理器签名必须兼容，开放泛型和部分特殊方法也有限制。

为什么我的 Mixin 匹配不到？

常见原因是重载歧义、Target 描述符不完整、Ordinal 变化、Slice 范围错误、目标 IL 被优化或依赖插件尚未加载。查看日志中的目标和匹配计数，并使用 Require/Expect/Allow。

required 和 Optional 有什么区别？

required 是 Mixin 配置级行为；MixinAttribute.Optional 是单个 Mixin 类型级行为。可选第三方集成应使用独立 Optional Mixin，不要把整个核心配置设为可选来隐藏错误。

如何访问私有字段或方法？

在实例 Mixin 中使用 [Shadow]，或定义 [Mixin] Accessor 接口并通过 MixinAccessors.Create<T>() 创建访问器。写入 readonly 成员需要 [Mutable]。

可以使用 Harmony API 吗？

PCL.Mixin 内部使用 Harmony/IL Patch 实现，但公共插件 API 不暴露 Prefix、Postfix、Finalizer 或 Transpiler。插件应使用 PCL.Mixin Attribute。

如何依赖另一个插件？

在 plugin.json 和市场 Manifest 中声明 dependencies。前置必须已安装、启用并满足 SemVer 约束，Core 会先加载前置并共享其公共主程序集。

为什么插件包不能带 PCL.Core.dll？

插件与启动器必须使用同一份 PCL.Core 类型身份。携带副本会导致类型冲突，并绕过 pclCoreVersion 兼容模型。

pclCoreVersion 是最低版本吗？

不是。它是插件构建时实际引用的 PCL.Core BaseVersion。最低支持版本由启动器内部维护。

未来 Core 版本和未知状态能安装吗？

可以在明确警告后由用户确认。低于内部最低支持版本的插件会被阻止。

如何进入插件市场？

最直接的方式是在可访问的 GitHub 仓库根目录放置 manifest.json，创建 Release，并添加 pclnexplugin Topic。仓库不要求开源。

也可以让用户添加第三方 JSON 市场源或直接 Manifest 源。

plugin-market.json 可以添加自定义 Topics 吗？

不可以。Topic pclnexplugin 硬编码在客户端，市场 JSON 中出现 topics 会被拒绝。

为什么没有 Logo？

在 plugin.json 或发布 Manifest 中声明 logo。它可以是包内/Manifest 相对路径或 HTTP/HTTPS URL。GitHub Topic 插件未声明时使用仓库 Owner 头像。

安装后为什么更新来源不对？

从 Manifest 安装会保存 Manifest 订阅；从 Git 安装会保存仓库地址。检查安装记录和本地 PluginManifestSubscriptions，不要在发布后直接更换 Manifest URL。

修改插件后为什么没有生效？

当前没有热重载。关闭启动器，替换插件目录或重新安装 PCLX，再重新启动。

插件导致启动器无法打开怎么办？

使用 PCL_NEX_SAFE_MODE=1 启动，跳过全部第三方 Mixin，然后禁用或移除问题插件并查看 PCL/Log/。