Mofox-Core/docs/plugin_loading_paths.md

插件加载路径说明

概述

MaiBot-Core 现在支持从多个路径加载插件，为插件开发者提供更大的灵活性。

支持的插件路径

系统会按以下优先级顺序搜索和加载插件：

1. 项目根目录插件路径：/plugins

• 路径: 项目根目录下的 plugins/ 文件夹
• 优先级: 最高
• 用途: 用户自定义插件、第三方插件
• 特点:
  • 与项目源码分离
  • 便于版本控制管理
  • 适合用户添加个人插件

2. 源码目录插件路径：/src/plugins

• 路径: src目录下的 plugins/ 文件夹
• 优先级: 次高
• 用途: 系统内置插件、官方插件
• 特点:
  • 与项目源码集成
  • 适合系统级功能插件

插件结构支持

两个路径都支持相同的插件结构：

传统结构（推荐用于复杂插件）

plugins/my_plugin/
├── __init__.py
├── actions/
│   ├── __init__.py
│   └── my_action.py
├── commands/
│   ├── __init__.py
│   └── my_command.py
└── config.toml

简化结构（推荐用于简单插件）

plugins/my_plugin/
├── __init__.py
├── my_action.py
├── my_command.py
└── config.toml

文件命名约定

动作文件

• *_action.py
• *_actions.py
• 包含 action 字样的文件名

命令文件

• *_command.py
• *_commands.py
• 包含 command 字样的文件名

加载行为

1. 顺序加载: 先加载 /plugins，再加载 /src/plugins
2. 重名处理: 如果两个路径中有同名插件，优先加载 /plugins 中的版本
3. 错误隔离: 单个插件加载失败不会影响其他插件的加载
4. 详细日志: 系统会记录每个插件的来源路径和加载状态

最佳实践

用户插件开发

• 将自定义插件放在 /plugins 目录
• 使用清晰的插件命名
• 包含必要的 __init__.py 文件

系统插件开发

• 将系统集成插件放在 /src/plugins 目录
• 遵循项目代码规范
• 完善的错误处理

版本控制

• 将 /plugins 目录添加到 .gitignore（如果是用户自定义插件）
• 或者为插件创建独立的git仓库

示例插件

参考 /plugins/example_root_plugin/ 中的示例插件，了解如何在根目录创建插件。

故障排除

常见问题

1. 插件未被加载

   • 检查插件目录是否有 __init__.py 文件
   • 确认文件命名符合约定
   • 查看启动日志中的加载信息

2. 导入错误

   • 确保插件依赖的模块已安装
   • 检查导入路径是否正确

3. 重复注册

   • 检查是否有同名的动作或命令
   • 避免在不同路径放置相同功能的插件

调试日志

启动时查看日志输出：

[INFO] 正在从 plugins 加载插件...
[INFO] 正在从 src/plugins 加载插件...
[SUCCESS] 插件加载完成: 总计 X 个动作, Y 个命令
[INFO] 插件加载详情:
[INFO]   example_plugin (来源: plugins): 1 动作, 1 命令