插件安装与版本回退

← 插件与自动化 · 所有分区

新导入的 JSON 规则插件默认停用；插件 ID、规则格式和接口版本必须先通过校验。内置 keyword_replies 与 scheduled_tasks 不可用外部 JSON 替换、更新或移除。

加载、升级与移除

• 启用 / 停用：立即应用并持久保存，重启时恢复选择。
• 设置：单独保存插件设置；多个页面使用版本校验，旧页面不会覆盖新设置，冲突时关闭设置弹窗、重新载入后再编辑。
• 重新载入：更新面板中的状态和设置，不读取磁盘上的新定义。
• 重新加载：重新读取这一插件的 JSON，适用于修改命令、模板或规则。
• 扫描目录：重新发现目录中的 JSON 文件，保留当前已保存的配置与启用选择。
• 移除：仅停用后可移除，原文件移至 data/plugin-archive/，配置保留。重新导入相同 ID 总是停用，并重新使用默认设置。

升级时在面板导入同 ID、不同版本的 JSON，确认版本与更新说明后更新，检查设置和权限再启用。面板保留兼容设置，新字段使用默认值，并保存旧版本供回退；不自动下载升级。直接替换磁盘文件再「重新加载」不会生成版本历史，建议使用面板更新流程。详见下方「插件版本更新与回退」。

单个插件格式错误不会阻止其他插件或主程序启动。状态文件损坏时所有插件停用且禁止写入，以免覆盖已有设置；修复或备份该文件后重启。通知发送失败记录错误，不重放，以免重复发送。

插件版本更新与回退

可在插件 JSON 顶层添加 changelog（最多 2000 字），作为纯文字更新说明。导入同 ID、不同版本的文件时，面板显示旧/新版本及说明，确认后更新；无需先移除旧插件。相同版本号拒绝覆盖，请为新版本填写不同的 version。

更新保留兼容的设置及权限，新字段采用默认值、已不兼容的字段恢复新默认值；更新后保持停用，请检查后手动启用。每个插件最多保存 5 个旧版本，全局最多 150 个。列表「版本与回退」可查看历史并回退定义、设置和权限，回退后同样保持停用。更新写入失败会恢复原定义和状态；历史记录在全部写入成功后保存。

管理 API：POST /api/extensions/upgrade 接受 {plugin, revision}；GET /api/extensions/{id}/versions 返回历史元信息；POST /api/extensions/{id}/rollback 接受 {version_id, revision}。只支持原有声明式 JSON，不运行插件脚本、不自动从第三方仓库下载，也不会把修改的权限直接放开。

管理权限

管理 API 使用服主管理令牌或具有 plugins.manage 的团队会话令牌，不接受网站后端密钥、玩家会话或游戏桥接令牌。写操作提供当前 revision；返回 409 后重新读取，核对新旧内容再提交。完整端点见插件开发文档。

业务记录使用 Bot 主数据库：新安装默认 SQLite，也可按MySQL 存储指南配置 MySQL。不要把‘默认 SQLite’理解为仅支持 SQLite。配置目录下的插件状态和网站设置仍为各自 JSON 文件；具体备份范围见备份与恢复。