Desktop Installation and Debugging

桌面端安装与调试

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

安装已签名插件

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

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

调试本机开发密钥签名包

PCL N 始终拒绝未签名包。PclNPluginSign=false 仍会由 SDK 自动创建本机开发密钥并签名，不应通过修改包内容绕过验证。

1. 在“启动器”分组打开“开发者模式”。
2. 按页面提示完成开发者授权。
3. 启用“开发者模式”。
4. 回到“插件 → 已安装”安装由本机开发密钥签名的开发构建。

正式提交插件中心前必须改用发布者正式 OpenPGP 密钥；SDK 本机开发密钥签名包不会通过市场审核。

从插件中心安装

从市场点击安装时，PCL 会自动安装 required 前置，并对每个下载包执行：最终 SHA-256、开发者签名、网站签名封套、插件身份和网站发布/吊销状态验证。在线验证失败采用 fail-closed 策略，不会把仅含开发者签名的候选包伪装成市场版本安装。

更新插件

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

<Version>0.2.0</Version>

"version": "0.2.0"

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

市场版本必须按 SemVer 严格递增。新市场版本发布后，网站只为旧版本保留 14 天回退下载窗口；到期删除远端制品。PCL 本机事务已经保存的旧版本不会被网站远程删除，但新设备或清理过本地缓存的设备在窗口结束后不能再从市场下载该旧版本。

前置依赖

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. 包内是否误带启动器私有程序集。

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