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.pyemoji_action.py→src/plugins/built_in/actions/emoji_action.pyno_reply_action.py→src/plugins/built_in/actions/no_reply_action.py
Command迁移
- 现有命令系统将封装为内置Command组件
- 保持现有的命令模式和功能
兼容性
新插件系统保持与现有系统的兼容性：
- 现有的Action和Command继续工作
- 提供兼容层和适配器
- 逐步迁移到新架构
扩展性
系统设计支持未来扩展：
- 新的组件类型（Scheduler、Listener等）
- 插件间依赖和通信
- 插件热重载
- 插件市场和分发
最佳实践
- 单一职责：每个组件专注于特定功能
- 配置驱动：通过配置文件控制行为
- 错误处理：妥善处理异常情况
- 日志记录：记录关键操作和错误
- 测试覆盖：为插件编写单元测试