# 插件加载路径说明

## 概述

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 命令
```