119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
# 插件加载路径说明
|
|
|
|
## 概述
|
|
|
|
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 命令
|
|
``` |