Mofox-Core/src/plugins/README.md

MaiBot 插件系统架构

概述

MaiBot 插件系统采用组件化设计，支持插件包含多种组件类型：

• Action组件：处理聊天中的动作逻辑
• Command组件：处理命令请求
• 未来扩展：Scheduler（定时任务）、Listener（事件监听）等

目录结构

src/plugins/
├── core/                          # 插件核心管理
│   ├── plugin_manager.py          # 插件管理器
│   ├── plugin_loader.py           # 插件加载器（预留）
│   └── component_registry.py      # 组件注册中心
├── apis/                          # API模块
│   ├── plugin_api.py              # 统一API聚合
│   ├── message_api.py             # 消息API
│   ├── llm_api.py                 # LLM API
│   ├── database_api.py            # 数据库API
│   ├── config_api.py              # 配置API
│   ├── utils_api.py               # 工具API
│   ├── stream_api.py              # 流API
│   └── hearflow_api.py            # 心流API
├── base/                          # 基础类
│   ├── base_plugin.py             # 插件基类
│   ├── base_action.py             # Action组件基类
│   ├── base_command.py            # Command组件基类
│   └── component_types.py         # 组件类型定义
├── built_in/                      # 内置组件
│   ├── actions/                   # 内置Action
│   └── commands/                  # 内置Command
└── examples/                      # 示例插件
    └── simple_plugin/             # 简单插件示例
        ├── plugin.py
        └── config.toml

核心特性

1. 组件化设计

• 插件可以包含多种组件类型
• 每种组件有明确的职责和接口
• 支持组件的独立启用/禁用

2. 统一的API访问

• 所有插件组件通过 PluginAPI 访问系统功能
• 包含消息发送、数据库操作、LLM调用等
• 提供统一的错误处理和日志记录

3. 灵活的配置系统

• 支持 TOML 格式的配置文件
• 插件可以读取自定义配置
• 支持全局配置和插件特定配置

4. 统一的注册管理

• 组件注册中心管理所有组件
• 支持组件的动态启用/禁用
• 提供丰富的查询和统计接口

插件开发指南

创建基本插件

from src.plugins.base.base_plugin import BasePlugin, register_plugin
from src.plugins.base.base_action import BaseAction
from src.plugins.base.component_types import ActionInfo, ActionActivationType

class MyAction(BaseAction):
    async def execute(self) -> tuple[bool, str]:
        # 使用API发送消息
        response = "Hello from my plugin!"
        return True, response

@register_plugin
class MyPlugin(BasePlugin):
    plugin_name = "my_plugin"
    plugin_description = "我的第一个插件"
    
    def get_plugin_components(self):
        action_info = ActionInfo(
            name="my_action",
            description="我的动作",
            activation_keywords=["hello"]
        )
        return [(action_info, MyAction)]

创建命令组件

from src.plugins.base.base_command import BaseCommand
from src.plugins.base.component_types import CommandInfo

class MyCommand(BaseCommand):
    async def execute(self) -> tuple[bool, str]:
        # 获取命令参数
        param = self.matched_groups.get("param", "")
        
        # 发送回复
        await self.send_reply(f"收到参数: {param}")
        return True, f"处理完成: {param}"

# 在插件中注册
def get_plugin_components(self):
    command_info = CommandInfo(
        name="my_command",
        description="我的命令",
        command_pattern=r"^/mycmd\s+(?P<param>\w+)$",
        command_help="用法：/mycmd <参数>"
    )
    return [(command_info, MyCommand)]

使用配置文件

# config.toml
[plugin]
name = "my_plugin"
enabled = true

[my_settings]
max_items = 10
default_message = "Hello World"

class MyPlugin(BasePlugin):
    config_file_name = "config.toml"
    
    def get_plugin_components(self):
        # 读取配置
        max_items = self.get_config("my_settings.max_items", 5)
        message = self.get_config("my_settings.default_message", "Hi")
        
        # 使用配置创建组件...

API使用示例

消息操作

# 发送文本消息
await self.api.send_text_to_group(chat_stream, "Hello!")

# 发送图片
await self.api.send_image_to_group(chat_stream, image_path)

数据库操作

# 查询数据
data = await self.api.db_get("table_name", "key")

# 保存数据
await self.api.db_set("table_name", "key", "value")

LLM调用

# 生成文本
response = await self.api.llm_text_request("你好，请介绍一下自己")

# 生成图片
image_url = await self.api.llm_image_request("一只可爱的猫咪")

内置组件迁移

现有的内置Action和Command将迁移到新架构：

Action迁移

• reply_action.py → src/plugins/built_in/actions/reply_action.py
• emoji_action.py → src/plugins/built_in/actions/emoji_action.py
• no_reply_action.py → src/plugins/built_in/actions/no_reply_action.py

Command迁移

• 现有命令系统将封装为内置Command组件
• 保持现有的命令模式和功能

兼容性

新插件系统保持与现有系统的兼容性：

• 现有的Action和Command继续工作
• 提供兼容层和适配器
• 逐步迁移到新架构

扩展性

系统设计支持未来扩展：

• 新的组件类型（Scheduler、Listener等）
• 插件间依赖和通信
• 插件热重载
• 插件市场和分发

最佳实践

1. 单一职责：每个组件专注于特定功能
2. 配置驱动：通过配置文件控制行为
3. 错误处理：妥善处理异常情况
4. 日志记录：记录关键操作和错误
5. 测试覆盖：为插件编写单元测试