桌面端安装与调试

适用于 SDK 0.1.0-alpha.4，并描述 PCL.Plugin v0.10.0 的现行桌面流程。

安装已签名插件

1. 启动 PCL N，打开“设置”。
2. 在“插件”分组选择“已安装”。
3. 点击“安装 .pnp”。
4. 选择插件包，等待签名、文件表、哈希、Manifest 和兼容范围验证完成。
5. 安装成功后点击“启用”。

页面会显示运行时目录、插件 ID、活动版本、启用状态和前置依赖状态。插件更新会安装到独立版本目录并原子切换活动版本；失败时运行时会保留或恢复旧版本。

调试未签名开发包

未签名包默认拒绝加载。这是安全边界，不应通过修改包内容绕过。

1. 在“启动器”分组打开“开发者模式”。
2. 按页面提示完成开发者授权。
3. 启用“开发者模式”。
4. 启用“允许强制加载未签名插件”。
5. 回到“插件 → 已安装”安装开发构建。

开发者模式到期或关闭后，允许未签名插件的开关会自动关闭。正式交付给其他用户的包必须使用 OpenPGP 签名。

更新插件

保持插件 ID 不变，提高 Version 与 plugin.json.version，重新构建并安装新 .pnp：

<Version>0.2.0</Version>

"version": "0.2.0"

发布过的版本不可覆盖。即使只修复一个拼写，也应发布新版本。

前置依赖

Manifest 中 kind: "required" 的依赖必须已安装、版本匹配并处于启用状态。运行时会按拓扑顺序先加载前置；缺失前置时插件不会加载，“已安装”页面会列出缺少项。

本地 .pnp 安装不会凭空获得依赖包。调试多个相关插件时，请先安装前置插件，再安装主插件。依赖写法见 依赖与兼容声明。

查看状态和日志

• “插件 → 已安装”：查看安装、启用、版本和前置状态。
• “启动器 → 开发者模式”：开启开发者诊断。
• “插件 → 安全”：切换 Plugin Safe Mode 或 UI Safe Mode（需要在开发者模式中显示高级页面）。
• “插件 → UI Patch”：查看应用统计和冲突。
• “插件 → 兼容性”：查看本地插件组合观测。

插件运行目录位于平台应用数据目录下的 PCL-N/plugin-runtime。实际绝对路径会显示在“已安装”页面；不要在文档或代码中假设 Windows 固定盘符。

每个插件通过 context.Directories 获取自己的目录：

context.Directories.Data;  // 持久数据
context.Directories.Cache; // 可重建缓存
context.Directories.Logs;  // 插件日志
context.Directories.Temp;  // 临时文件

优先使用 IPluginSettingsStore 保存简单配置，不要自行拼接其他插件或启动器的目录。

常用调试循环

修改代码
  → dotnet build -c Release
  → 安装新的 SemVer 版本
  → 启用并复现
  → 查看页面状态与日志
  → 禁用插件验证注册项是否被正确释放

不要反复覆盖同一个版本号。运行时使用独立版本目录，清晰的版本递增能让回滚和日志定位更可靠。

安装失败时先检查

1. .pnp 是否来自 Release 构建。
2. PclNPluginId、Manifest id 是否相同。
3. Version、Manifest version 是否相同。
4. entryPoint.assembly 和 entryPoint.type 是否正确。
5. API/Host 范围是否包含当前启动器。
6. 所有 required 服务和前置插件是否可用。
7. 正式包的签名指纹是否与公钥一致。
8. 包内是否误带启动器私有程序集。

仍无法定位时参见 故障排查。