插件安装失败与依赖报错处理

插件故障按「卡在哪一步」分流：下载不动、装完报错、能用但行为异常。对号入座。

一、下载就失败

国内访问插件仓库网络不稳，官方文档给的原话级原因：「插件通过 GitHub 安装，在国内访问 GitHub 确实有时候连不上」。三层解法：

1. 代理：「设置 → 网络 → 代理与依赖源 → HTTP 代理」配置并保存；Docker 部署注意代理地址是容器视角（host.docker.internal 等，见 Docker 部署）
2. GitHub 加速地址：同一页面的专门设置项，填加速镜像前缀
3. 彻底绕开：本机下载插件 ZIP，插件页右下角 + 从文件安装，完整流程见手动装插件

二、加载报 No module named xxx

含义：插件依赖的 Python 库没装上。官方文档列的成因有三：网络问题导致依赖下载失败；插件作者没写 requirements.txt；Python 版本不兼容。

解法：手动补装依赖

1. 看清报错里缺的库叫什么名字
2. 到「数据与日志 → 日志」页，点「安装 pip 库」
3. 弹窗里填库名，按需填 PyPI 镜像链接（国内网络建议填镜像源），点安装
4. 装完点插件卡片上的「尝试一键重载修复」，不重启框架直接重新加载
5. 还不行重启整个程序

配套动作：若确认是插件作者漏写 requirements.txt，去插件仓库提 Issue 提醒作者补上，这是社区惯例。Python 版本不兼容的，换符合插件要求的解释器环境（框架本身要求 Python 3.10+）。

三、装上了但行为不对

• 功能没出现：插件提供的工具/技能要在人格设定里勾选才生效，指令要在指令管理里确认启用
• 参数不生效：配置文件里改完要保存，个别插件还要重载
• 版本不匹配：插件要求更高的框架版本，升级框架或换插件版本
• 与其他插件冲突：同名指令冲突，在指令管理里重命名一个

四、怀疑插件有毒

官方责任边界明确：无法完全保证市场插件安全性，因插件造成的损失不予负责。发现异常（莫名的外发请求、越权指令）立即停用并删除插件，到项目仓库或社区反馈；日志页留好证据。

万能兜底

以上全试过不行：删插件重装一遍（排除安装时文件损坏）；仍不行去插件仓库提 Issue，附上日志页的相关报错——发之前把 Token、IP、用户 ID 打码。