Mofox-Core/docs/plugin_quick_start.md

MaiBot 插件快速开始指南

🚀 5分钟创建你的第一个插件

本指南将带你快速创建一个功能完整的插件，体验MaiBot插件开发的简单和强大。

📋 前置要求

• 已克隆MaiBot项目到本地
• Python 3.8+ 环境
• 基本的Python编程知识

🎯 我们要做什么

我们将创建一个名为 my_first_plugin 的插件，包含：

• 一个Action组件：自动回应"Hello"
• 一个Command组件：计算器功能

📁 第一步：创建插件目录

在 src/plugins/examples/ 下创建你的插件目录：

mkdir src/plugins/examples/my_first_plugin

📝 第二步：创建插件文件

在插件目录中创建 plugin.py 文件：

# src/plugins/examples/my_first_plugin/plugin.py

from typing import List, Tuple, Type, Optional
import re

# 导入插件系统核心
from src.plugin_system import (
    BasePlugin, register_plugin, BaseAction, BaseCommand,
    ComponentInfo, ActionInfo, CommandInfo, ActionActivationType, ChatMode
)
from src.common.logger import get_logger

logger = get_logger("my_first_plugin")


class HelloAction(BaseAction):
    """自动问候Action - 当用户说Hello时自动回应"""
    
    # 🎯 声明式配置：只需设置类属性
    focus_activation_type = ActionActivationType.KEYWORD
    normal_activation_type = ActionActivationType.KEYWORD
    activation_keywords = ["hello", "Hello", "HELLO"]
    keyword_case_sensitive = False
    mode_enable = ChatMode.ALL
    parallel_action = False
    
    async def execute(self) -> Tuple[bool, str]:
        """执行问候动作"""
        username = self.action_data.get("username", "朋友")
        response = f"Hello, {username}! 很高兴见到你！ 🎉"
        
        logger.info(f"向 {username} 发送问候")
        return True, response


class CalculatorCommand(BaseCommand):
    """计算器命令 - 执行简单数学运算"""
    
    # 🎯 声明式配置：定义命令模式
    command_pattern = r"^/calc\s+(?P<expression>[\d\+\-\*/\(\)\s\.]+)$"
    command_help = "计算器，用法：/calc <数学表达式>"
    command_examples = ["/calc 1+1", "/calc 2*3+4", "/calc (10-5)*2"]
    
    async def execute(self) -> Tuple[bool, Optional[str]]:
        """执行计算命令"""
        # 获取匹配的表达式
        expression = self.matched_groups.get("expression", "").strip()
        
        if not expression:
            await self.send_reply("❌ 请提供数学表达式！")
            return False, None
        
        try:
            # 安全计算（只允许基本数学运算）
            allowed_chars = set("0123456789+-*/.() ")
            if not all(c in allowed_chars for c in expression):
                await self.send_reply("❌ 表达式包含不允许的字符！")
                return False, None
            
            # 执行计算
            result = eval(expression)  # 在实际项目中应使用更安全的计算方法
            
            response = f"🧮 计算结果：\n`{expression} = {result}`"
            await self.send_reply(response)
            
            logger.info(f"计算: {expression} = {result}")
            return True, response
            
        except Exception as e:
            error_msg = f"❌ 计算错误: {str(e)}"
            await self.send_reply(error_msg)
            logger.error(f"计算失败: {expression}, 错误: {e}")
            return False, error_msg


@register_plugin
class MyFirstPlugin(BasePlugin):
    """我的第一个插件 - 展示基本功能"""
    
    # 🏷️ 插件基本信息
    plugin_name = "my_first_plugin"
    plugin_description = "我的第一个MaiBot插件，包含问候和计算功能"
    plugin_version = "1.0.0"
    plugin_author = "你的名字"
    enable_plugin = True
    
    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
        """返回插件包含的组件"""
        
        return [
            # Action组件：自动问候
            (HelloAction.get_action_info(
                name="hello_action", 
                description="自动回应Hello问候"
            ), HelloAction),
            
            # Command组件：计算器
            (CalculatorCommand.get_command_info(
                name="calculator_command",
                description="简单计算器，支持基础数学运算"
            ), CalculatorCommand)
        ]

📊 第三步：创建配置文件（可选）

创建 config.toml 文件来配置插件：

# src/plugins/examples/my_first_plugin/config.toml

[plugin]
name = "my_first_plugin"
description = "我的第一个插件"
enabled = true

[hello_action]
enable_emoji = true
greeting_message = "Hello, {username}! 很高兴见到你！"

[calculator]
max_expression_length = 100
allow_complex_math = false

如果你创建了配置文件，需要在插件类中指定：

@register_plugin
class MyFirstPlugin(BasePlugin):
    # ... 其他属性 ...
    config_file_name = "config.toml"  # 添加这一行

🔄 第四步：测试插件

1. 启动MaiBot：

   cd /path/to/MaiBot-Core
   python -m src.main
   

2. 测试Action组件：

   • 在聊天中发送 "Hello" 或 "hello"
   • 应该收到自动回复："Hello, [用户名]! 很高兴见到你！ 🎉"

3. 测试Command组件：

   • 发送 /calc 1+1
   • 应该收到回复："🧮 计算结果：\n1+1 = 2"

🎉 恭喜！

你已经成功创建了第一个MaiBot插件！插件包含：

✅ 一个Action组件 - 智能响应用户问候
✅ 一个Command组件 - 提供计算器功能
✅ 完整的配置 - 支持自定义行为
✅ 错误处理 - 优雅处理异常情况

🔍 代码解析

Action组件关键点

# 声明激活条件
focus_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["hello", "Hello", "HELLO"]

# 执行逻辑
async def execute(self) -> Tuple[bool, str]:
    # 处理逻辑
    return True, response  # (成功状态, 回复内容)

Command组件关键点

# 声明命令模式（正则表达式）
command_pattern = r"^/calc\s+(?P<expression>[\d\+\-\*/\(\)\s\.]+)$"

# 执行逻辑
async def execute(self) -> Tuple[bool, Optional[str]]:
    expression = self.matched_groups.get("expression")  # 获取匹配参数
    await self.send_reply(response)  # 发送回复
    return True, response

插件注册

@register_plugin  # 装饰器注册插件
class MyFirstPlugin(BasePlugin):
    # 基本信息
    plugin_name = "my_first_plugin"
    plugin_description = "插件描述"
    
    # 返回组件列表
    def get_plugin_components(self):
        return [(组件信息, 组件类), ...]

🎯 下一步学习

现在你已经掌握了基础，可以继续学习：

1. 深入API - 探索详细解析了解更多API功能
2. 参考示例 - 查看 simple_plugin 了解更复杂的功能
3. 自定义扩展 - 尝试添加更多组件和功能

🛠️ 常见问题

Q: 插件没有被加载？

A: 检查：

• 插件目录是否在 src/plugins/ 下
• 文件名是否为 plugin.py
• 类是否有 @register_plugin 装饰器
• 是否有语法错误

Q: Action组件没有触发？

A: 检查：

• activation_keywords 是否正确设置
• focus_activation_type 和 normal_activation_type 是否设置
• 消息内容是否包含关键词

Q: Command组件不响应？

A: 检查：

• command_pattern 正则表达式是否正确
• 用户输入是否完全匹配模式
• 是否有语法错误

📚 相关文档

• 系统总览 - 了解整体架构
• 详细解析 - 深入学习各个组件
• 示例插件 - 完整功能示例

---

🎉 恭喜完成快速开始！ 现在你已经是MaiBot插件开发者了！