安全模式与恢复

插件、安装包、更新或迁移出错时会发生什么，以及用户如何始终保有对插件管理与数据的控制。

失败处理的设计目标很简单：坏插件、坏安装包、失败的更新或损坏的迁移，绝不能剥夺用户管理插件和恢复数据的能力。

启动安全模式

GhostBoard 在发布第三方插件代码之前写入启动标记，只有在所有已启用插件完成首次激活后才清除它。若上一次启动没有到达该点，下一次启动会跳过全部第三方代码，并在设置 → 插件显示 插件安全模式已启用 及原因：

• 上一次插件启动没有完成；
• 保存的启动状态不可信（损坏文件被保留，GhostBoard 失败关闭）；
• 通过 --safe-mode 或 GHOSTBOARD_SAFE_MODE=1 显式请求了安全模式。

安全模式下可以停用或移除插件、回退代码、恢复数据。下次启动尝试启用插件 让下一次启动退出安全模式；当前会话保持安全。

开发期重载失败

已连接的开发目录在变更时重载。若新代码 import 失败或 setup 抛错，候选被丢弃：上一个激活继续运行，命令、已打开的面板与状态不变，插件菜单显示指向你的文件的错误。成功的重载在发布新代际前，按逆注册顺序清理旧代际且只清理一次。

面板错误

面板组件或挂载函数中的异常只影响该面板的 root。宿主 UI 与插件的其他贡献继续工作；面板显示诊断信息并可重新打开。

损坏或被篡改的安装包

• 归档在审阅步骤之前校验（路径、限制、manifest、入口、签名），安装期间从不执行。
• 已安装的文件树在每次激活前按规范摘要重新校验；被修改或损坏的树会以“插件包文件未能继续通过验证”停用，直到重新安装。
• 未签名的原地升级、签名不匹配、密钥变更、更新 URL 变更、摘要不匹配与版本不前进都会被拒绝，已安装版本保持不变。

失败或不想要的更新

安装更新会保留上一版本经过校验的文件。将代码回退到 … 重新校验并重新激活它们；插件保持停用直到用户再次审阅并启用。更新版本的日志不能在重启时覆盖回退后的状态。

数据迁移恢复

自定义画布类型把卡片状态迁移到更高 dataVersion 之前，GhostBoard 保存旧状态的 preimage。备份失败则迁移不运行。设置 → 插件中的 恢复迁移前备份 在保存当前数据的保护副本后，用最近的备份替换已迁移的卡片数据，并停用插件。恢复数据与回退代码是分开的步骤，用户可以任选其一。

无法自动恢复的

SDK 之外的副作用——挂载点外的 DOM 编辑、直接网络调用、写入用户选定目录的文件——不是事务性的。插件键值存储没有版本迁移，插件必须容忍自己的旧值。有疑问时，GhostBoard 宁愿停用插件并保留数据，而不是猜测。