插件问题
插件已经启用，为什么仍然不能使用？
先阅读插件自己的 README 或使用说明，确认必填配置、依赖、权限和支持的 MaiBot 版本。然后检查插件加载日志、配置校验错误以及命令或事件是否成功注册。
只有在确认问题来自插件本身后，才需要向插件作者反馈。
升级 1.3.2 后头像不见了，怎么恢复？
1.3.2 起头像改由统一头像服务按当前平台路由去问适配器获取，不再有写死的 QQ 头像地址。看不到头像时按顺序查：
- 旧缓存不再读取 — 早期写在
data/avatar/qq/里的缓存文件 1.3.2 起直接被跳过，不会兜底显示，可以删掉该目录 - 适配器没实现头像接口 — 只有当前路由到的适配器实现了头像查询协议，对应平台才能出头像；没实现的平台和目标类型一律显示默认头像，这是预期行为，不是故障
- 被设置关掉了 — WebUI 设置里的「获取头像」开关关着时，前端根本不请求头像，打开即有
- 平台之前就不出头像 — 自定义平台、非数字 ID 在 1.3.2 之前一律没有头像；现在只要适配器实现了头像接口就能出头像
适配器是否支持头像，看它自己的 README 或更新说明；某个平台能不能出头像，取决于当前路由到的适配器作者是否跟进实现了头像协议。
日志提示「Host 版本不兼容」或「SDK 版本不兼容」怎么办？
说明插件的 _manifest.json 声明的兼容区间不含当前版本。分两种情况：
- Host 只高了一个补丁号（例如插件支持到
1.3.1、当前是1.3.2）— 麦麦会按兼容模式照样加载，只在日志里留一条 warning，不用处理 - 其他情况 — 插件被阻止加载。先找支持当前版本的插件版本；确实要试时，打开
[debug] force_plugin_compatibility（WebUI 调试配置里的「强制插件兼容」开关）并重启 MaiBot，让它跳过版本区间校验
强制兼容只是排查手段
该开关只跳过 Host / SDK 版本区间校验，不覆盖 manifest 协议版本、依赖解析和能力白名单；开启后接口变化导致的异常不会有任何前置提示，也不影响插件市场对版本的兼容性判断。定位完问题请关掉它。
插件命令为什么被当成普通聊天消息？
确认命令格式和前缀正确，并检查插件启动时是否成功注册命令。如果多个插件使用相同命令，或者某个插件提前拦截并修改了消息，命令可能继续进入普通聊天流程。
可以临时禁用近期安装的插件，逐个恢复来定位冲突。
怎样排查插件冲突？
记录冲突发生前最后安装或更新的插件，然后分批禁用插件进行二分排查。定位后比较命令名称、Hook、事件优先级和依赖版本，不要只根据网上某个旧版本案例直接认定插件有问题。
插件自带的自定义页面不显示怎么办？
1.3.2 起插件可以用自己目录里的 webui.json 向 WebUI 声明页面。装了这类插件却看不到入口，按顺序查：
- 看日志里有没有注册失败 — 声明写错时该插件本次注册整体失败，日志会打「插件 WebUI 声明无效」并附原因（字段越界、组件属性不适用、危险按钮没写确认文案等）
- 看日志里有没有「引用了未注册的静态 API」 — 页面绑定的 API 短名或
version和@API注册的不一致、或者绑定的是动态 API，都不挂得上 - 确认重载过插件 —
webui.json改动要重载插件才生效；没这个文件的插件完全不受影响 - 确认找对地方 —
sidebar页在工作区侧边栏「插件扩展」分组，workspace页在插件自己的顶部工作区里，别只盯着一边 - 等最多 30 秒 — 前端按轮询拿声明，卸载或禁用后入口同步下线，浏览器最多 30 秒反映，手动刷新立即生效
字段清单、组件类型与排错见 WebUI 页面。
插件下载失败怎么办？
检查仓库地址、网络、Git 是否可用，以及代理或镜像源配置。还要确认插件仓库的实际默认分支；分支可能叫 main、master 或其他名称，不能固定假设。
如果能访问仓库但安装仍失败，查看安装日志中的 Git 错误、权限错误和依赖安装错误。
插件更新后无法使用怎么办？
检查插件的更新说明和配置迁移要求，并对比 MaiBot 版本兼容范围。恢复前先备份插件目录和配置；如果需要回退，应按照插件仓库提供的版本说明操作。
为什么点「更新」提示已锁定版本？
你在安装该插件时勾选过「安装后锁定此版本，阻止自动更新」。锁定后它不再参与自动更新，市场里也不会提示有新版本。
恢复自动更新：打开插件详情页，在「安装版本」里选一次版本，并取消勾选「安装后锁定此版本，阻止自动更新」。
为什么不能自动降级到旧版本？
自动更新只会往新版本走，遇到比当前版本旧或相同的目标会直接提示「当前已是最新兼容版本，不会自动降级或重装」，避免误操作把你退回有问题的版本。
想降级：打开插件详情页，在「安装版本」下拉里手动选中目标版本并安装。切换版本前旧目录会备份到 plugins/.update_backups/，config.toml、config_back/、data/ 会保留，但插件数据不会回滚——降级前先备份插件目录。
版本下拉里有很多选项是灰色的，什么意思？
灰色且后缀带原因的版本与当前麦麦或 SDK 不兼容，装上去也会被拒绝，因此禁止选中。常见后缀有：
- 「需要麦麦 ≥ x.y.z」/「仅支持麦麦 ≤ x.y.z」 — 插件的
host_application区间不含当前版本 - 「需要 SDK ≥ x.y.z」/「仅支持 SDK ≤ x.y.z」 — 插件的
sdk区间不含当前 SDK 版本 - 「清单协议版本过旧」 — 该版本用的是不受支持的 manifest 协议
- 「· 已撤回」 — 作者撤回了这个发布版本
- 「· 预发布」 — 作者标记的测试版本，可用但不保证稳定
如果某个插件对所有版本都显示不兼容，说明它还没有适配你当前的麦麦版本，只能等作者更新。
提示「该插件按发布版本安装，请通过版本选择更新」怎么办？
这个插件是通过版本索引（Git Release）安装的，插件目录里有 .maibot-release.json 记录所选版本，不能再用 git pull 直接覆盖，否则会破坏版本记录。
正确做法：打开插件详情页，在「安装版本」里选目标版本安装。确实想改用分支版本时，先卸载该插件，再用「从 Git 安装」装一次。
插件版本安装失败有哪些常见原因？
- 依赖不满足 — 该版本要求的其他插件或 Python 包没装齐
- 被其他插件卡住 — 已安装的某个插件要求这个插件停在特定版本区间，提示「该版本不满足已安装插件 X 的依赖要求」
- 本地代码修改 — 你在插件目录里改过代码，提示「插件存在本地代码修改，请先处理」；先备份并还原再切换版本
- 索引与仓库不一致 — 提示「Tag 当前指向的 commit 与版本索引不一致」或「下载的 manifest 与版本索引不一致」，等版本索引同步后重试
- 版本同步失败 — 官方版本索引没拉下来，换镜像源或稍后重试
插件市场打不开或安装一直转圈？
使用 Clash、Surge 等 Fake-IP 代理时，插件市场域名可能被解析到 198.18.0.0/15 段，被判定为不安全地址而无法访问。1.3.0 起插件市场的 HTTPS 域名已允许落在该网段，正常代理环境下不会再因此失败。
仍然失败时：换一个镜像源、临时关掉代理的 Fake-IP 模式，或查看错误信息末尾——所有镜像源都失败时会列出每个源的具体原因。