# 🔧 插件开发故障排除指南

本指南帮助你快速解决 MoFox-Bot 插件开发中的常见问题。

---

## 📋 快速诊断清单

遇到问题时，首先按照以下步骤检查：

1. ✅ 检查日志文件 `logs/app_*.jsonl`
2. ✅ 确认插件已在 `_manifest.json` 中正确配置
3. ✅ 验证你使用的是 `PlusCommand` 而不是 `BaseCommand`
4. ✅ 检查 `execute()` 方法签名是否正确
5. ✅ 确认返回值格式正确

---

## 🔴 严重问题：插件无法加载

### 错误 #1: "未检测到插件"

**症状**：
- 插件目录存在，但日志中没有加载信息
- `get_plugin_components()` 返回空列表

**可能原因与解决方案**：

#### ❌ 缺少 `@register_plugin` 装饰器

```python
# 错误 - 缺少装饰器
class MyPlugin(BasePlugin):  # 不会被检测到
    pass

# 正确 - 添加装饰器
@register_plugin  # 必须添加！
class MyPlugin(BasePlugin):
    pass
```

#### ❌ `plugin.py` 文件不存在或位置错误

```
plugins/
  └── my_plugin/
      ├── _manifest.json     ✅
      └── plugin.py           ✅ 必须在这里
```

#### ❌ `_manifest.json` 格式错误

```json
{
  "manifest_version": 1,
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "插件描述",
  "author": {
    "name": "Your Name"
  }
}
```

---

### 错误 #2: "ActionInfo.__init__() missing required argument: 'component_type'"

**症状**：
```
TypeError: ActionInfo.__init__() missing 1 required positional argument: 'component_type'
```

**原因**：手动创建 `ActionInfo` 时未指定 `component_type` 参数

**解决方案**：

```python
from src.plugin_system import ActionInfo, ComponentType

# ❌ 错误 - 缺少 component_type
action_info = ActionInfo(
    name="my_action",
    description="我的动作"
)

# ✅ 正确方法 1 - 使用自动生成（推荐）
class MyAction(BaseAction):
    action_name = "my_action"
    action_description = "我的动作"

def get_plugin_components(self):
    return [
        (MyAction.get_action_info(), MyAction)  # 自动生成，推荐！
    ]

# ✅ 正确方法 2 - 手动指定 component_type
action_info = ActionInfo(
    name="my_action",
    description="我的动作",
    component_type=ComponentType.ACTION  # 必须指定！
)
```

---

## 🟡 命令问题：命令无响应

### 错误 #3: 命令被识别但不执行

**症状**：
- 输入 `/mycommand` 后没有任何反应
- 日志显示命令已匹配但未执行

**可能原因与解决方案**：

#### ❌ 使用了 `BaseCommand` 而不是 `PlusCommand`

```python
# ❌ 错误 - 使用 BaseCommand
from src.plugin_system import BaseCommand

class MyCommand(BaseCommand):  # 不推荐！
    command_name = "mycommand"
    command_pattern = r"^/mycommand$"  # 需要手动写正则
    
    async def execute(self):  # 签名错误！
        pass

# ✅ 正确 - 使用 PlusCommand
from src.plugin_system import PlusCommand, CommandArgs

class MyCommand(PlusCommand):  # 推荐！
    command_name = "mycommand"
    # 不需要 command_pattern，会自动生成！
    
    async def execute(self, args: CommandArgs):  # 正确签名
        await self.send_text("命令执行成功")
        return True, "执行了mycommand", True
```

#### ❌ `execute()` 方法签名错误

```python
# ❌ 错误的签名（缺少 args 参数）
async def execute(self) -> Tuple[bool, Optional[str], bool]:
    pass

# ❌ 错误的签名（参数类型错误）
async def execute(self, args: list[str]) -> Tuple[bool, Optional[str], bool]:
    pass

# ✅ 正确的签名
async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
    await self.send_text("响应用户")
    return True, "日志描述", True
```

---

### 错误 #4: 命令发送了消息但用户没收到

**症状**：
- 日志显示命令执行成功
- 但用户没有收到任何消息

**原因**：在返回值中返回消息，而不是使用 `self.send_text()`

**解决方案**：

```python
# ❌ 错误 - 在返回值中返回消息
async def execute(self, args: CommandArgs):
    message = "这是给用户的消息"
    return True, message, True  # 这不会发送给用户！

# ✅ 正确 - 使用 self.send_text()
async def execute(self, args: CommandArgs):
    # 发送消息给用户
    await self.send_text("这是给用户的消息")
    
    # 返回日志描述（不是用户消息）
    return True, "执行了某个操作", True
```

---

### 错误 #5: "notice处理失败" 或重复消息

**症状**：
- 日志中出现 "notice处理失败"
- 用户收到重复的消息

**原因**：同时使用了 `send_api.send_text()` 和返回消息

**解决方案**：

```python
# ❌ 错误 - 混用不同的发送方式
from src.plugin_system.apis.chat_api import send_api

async def execute(self, args: CommandArgs):
    await send_api.send_text(self.stream_id, "消息1")  # 不要这样做
    return True, "消息2", True  # 也不要返回消息

# ✅ 正确 - 只使用 self.send_text()
async def execute(self, args: CommandArgs):
    await self.send_text("这是唯一的消息")  # 推荐方式
    return True, "日志：执行成功", True  # 仅用于日志
```

---

## 🟢 配置问题

### 错误 #6: 配置警告 "配置中不存在字空间或键"

**症状**：
```
获取全局配置 plugins.my_plugin 失败: "配置中不存在字空间或键 'plugins'"
```

**这是正常的吗？**

✅ **是的，这是正常行为！** 不需要修复。

**说明**：
- 系统首先尝试从全局配置加载：`config/plugins/my_plugin/config.toml`
- 如果不存在，会自动回退到插件本地配置：`plugins/my_plugin/config.toml`
- 这个警告可以安全忽略

**如果你想消除警告**：
1. 在 `config/plugins/` 目录创建你的插件配置目录
2. 或者直接忽略 - 使用本地配置完全正常

---

## 🔧 返回值问题

### 错误 #7: 返回值格式错误

**Action 返回值** (2个元素)：
```python
async def execute(self) -> Tuple[bool, str]:
    await self.send_text("消息")
    return True, "日志描述"  # 2个元素
```

**Command 返回值** (3个元素)：
```python
async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
    await self.send_text("消息")
    return True, "日志描述", True  # 3个元素（增加了拦截标志）
```

**对比表格**：

| 组件类型 | 返回值 | 元素说明 |
|----------|--------|----------|
| **Action** | `(bool, str)` | (成功标志, 日志描述) |
| **Command** | `(bool, str, bool)` | (成功标志, 日志描述, 拦截标志) |

---

## 🎯 参数解析问题

### 错误 #8: 无法获取命令参数

**症状**：
- `args` 为空或不包含预期的参数

**解决方案**：

```python
async def execute(self, args: CommandArgs):
    # 检查是否有参数
    if args.is_empty():
        await self.send_text("❌ 缺少参数\n用法: /command <参数>")
        return True, "缺少参数", True
    
    # 获取原始参数字符串
    raw_input = args.get_raw()
    
    # 获取解析后的参数列表
    arg_list = args.get_args()
    
    # 获取第一个参数
    first_arg = args.get_first("默认值")
    
    # 获取指定索引的参数
    second_arg = args.get_arg(1, "默认值")
    
    # 检查标志
    if args.has_flag("--verbose"):
        # 处理 --verbose 模式
        pass
    
    # 获取标志的值
    output = args.get_flag_value("--output", "default.txt")
```

---

## 📝 类型注解问题

### 错误 #9: IDE 报类型错误

**解决方案**：确保使用正确的类型导入

```python
from typing import Tuple, Optional, List, Type
from src.plugin_system import (
    BasePlugin,
    PlusCommand,
    BaseAction,
    CommandArgs,
    ComponentInfo,
    CommandInfo,
    ActionInfo,
    ComponentType
)

# 正确的类型注解
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
    return [
        (MyCommand.get_command_info(), MyCommand),
        (MyAction.get_action_info(), MyAction)
    ]
```

---

## 🚀 性能问题

### 错误 #10: 插件响应缓慢

**可能原因**：

1. **阻塞操作**：在 `execute()` 中使用了同步 I/O
2. **大量数据处理**：在主线程处理大文件或复杂计算
3. **频繁的数据库查询**：每次都查询数据库

**解决方案**：

```python
import asyncio

async def execute(self, args: CommandArgs):
    # ✅ 使用异步操作
    result = await some_async_function()
    
    # ✅ 对于同步操作，使用 asyncio.to_thread
    result = await asyncio.to_thread(blocking_function)
    
    # ✅ 批量数据库操作
    from src.common.database.optimization.batch_scheduler import get_batch_scheduler
    scheduler = get_batch_scheduler()
    await scheduler.schedule_batch_insert(Model, data_list)
    
    return True, "执行成功", True
```

---

## 📞 获取帮助

如果以上方案都无法解决你的问题：

1. **查看日志**：检查 `logs/app_*.jsonl` 获取详细错误信息
2. **查阅文档**：
   - [快速开始指南](./quick-start.md)
   - [增强命令指南](./PLUS_COMMAND_GUIDE.md)
   - [Action组件指南](./action-components.md)
3. **在线文档**：https://mofox-studio.github.io/MoFox-Bot-Docs/
4. **提交 Issue**：在 GitHub 仓库提交详细的问题报告

---

## 🎓 最佳实践速查

| 场景 | 推荐做法 | 避免 |
|------|----------|------|
| 创建命令 | 使用 `PlusCommand` | ❌ 使用 `BaseCommand` |
| 发送消息 | `await self.send_text()` | ❌ 在返回值中返回消息 |
| 注册组件 | 使用 `get_action_info()` | ❌ 手动创建不带 `component_type` 的 Info |
| 参数处理 | 使用 `CommandArgs` 方法 | ❌ 手动解析字符串 |
| 异步操作 | 使用 `async/await` | ❌ 使用同步阻塞操作 |
| 配置读取 | `self.get_config()` | ❌ 硬编码配置值 |

---

**最后更新**：2024-12-17  
**版本**：v1.0.0

有问题欢迎反馈，帮助我们改进这份指南！