gardel/Mofox-Core

Fork 0

Files

SengokuCola de0bdd3766 feat：继续重构插件api

2025-06-10 19:16:58 +08:00

5.4 KiB

Raw Blame History

MaiBot 插件编写指南 - 总览

📋 目录结构

本指南分为三个部分：

总览 - 插件系统架构和设计理念（当前文档）
快速开始 - 5分钟创建你的第一个插件
详细解析 - 深入理解各个组件和API

🎯 插件系统概述

MaiBot 采用组件化的插件系统，让开发者可以轻松扩展机器人功能。系统支持两种主要组件类型：

Action组件 - 智能动作，基于关键词、LLM判断等条件自动触发
Command组件 - 命令处理，基于正则表达式匹配用户输入的命令

🏗️ 系统架构

src/
├── plugin_system/          # 🔧 系统核心（框架代码）
│   ├── core/               # 插件管理和注册中心
│   ├── apis/               # 统一API接口（7大模块）
│   ├── base/               # 插件和组件基类
│   └── registry/           # 组件注册和查询
└── plugins/                # 🔌 插件内容（用户代码）
    ├── built_in/           # 内置插件
    └── examples/           # 示例插件

核心设计理念

分离关注点 - 系统框架与插件内容完全分离
组件化设计 - 一个插件可包含多个Action和Command组件
统一API访问 - 通过PluginAPI统一访问所有系统功能
声明式配置 - 通过类属性声明组件行为，简化开发
类型安全 - 完整的类型定义，IDE友好

🧩 组件类型详解

Action组件 - 智能动作

Action用于实现智能交互逻辑，支持多种激活方式：

关键词激活 - 消息包含特定关键词时触发
LLM判断激活 - 使用大模型智能判断是否需要触发
随机激活 - 按概率随机触发
始终激活 - 每条消息都触发（谨慎使用）

适用场景：

智能问候、闲聊互动
情感分析和回应
内容审核和提醒
数据统计和分析

Command组件 - 命令处理

Command用于处理结构化的用户命令，基于正则表达式匹配：

精确匹配 - 支持参数提取和验证
灵活模式 - 正则表达式的完整威力
帮助系统 - 自动生成命令帮助信息

适用场景：

功能性操作（查询、设置、管理）
工具类命令（计算、转换、搜索）
系统管理命令
游戏和娱乐功能

🔌 API系统概览

系统提供7大API模块，涵盖插件开发的所有需求：

API模块	功能描述	主要用途
MessageAPI	消息发送和交互	发送文本、图片、语音等消息
LLMAPI	大模型调用	文本生成、智能判断、创意创作
DatabaseAPI	数据库操作	存储用户数据、配置、历史记录
ConfigAPI	配置访问	读取全局配置和用户信息
UtilsAPI	工具函数	文件操作、时间处理、ID生成
StreamAPI	流管理	聊天流控制和状态管理
HearflowAPI	心流系统	与消息处理流程集成

🎨 开发体验

简化的导入接口

from src.plugin_system import (
    BasePlugin, register_plugin, BaseAction, BaseCommand,
    ComponentInfo, ActionInfo, CommandInfo, ActionActivationType, ChatMode
)

声明式组件定义

class HelloAction(BaseAction):
    # 🎯 直接通过类属性定义行为
    focus_activation_type = ActionActivationType.KEYWORD
    activation_keywords = ["你好", "hello", "hi"]
    mode_enable = ChatMode.ALL
    
    async def execute(self) -> Tuple[bool, str]:
        return True, "你好！我是MaiBot 😊"

统一的API访问

class MyCommand(BaseCommand):
    async def execute(self) -> Tuple[bool, Optional[str]]:
        # 💡 通过self.api访问所有系统功能
        await self.api.send_message("text", "处理中...")
        models = self.api.get_available_models()
        await self.api.store_user_data("key", "value")
        return True, "完成！"

🚀 开发流程

创建插件目录 - 在 src/plugins/ 下创建插件文件夹
定义插件类 - 继承 BasePlugin，设置基本信息
创建组件类 - 继承 BaseAction 或 BaseCommand
注册组件 - 在插件的 get_plugin_components() 中返回组件列表
测试验证 - 启动系统测试插件功能

📚 学习路径建议

初学者 - 从快速开始开始，5分钟体验插件开发
进阶开发 - 阅读详细解析，深入理解各个组件
实战练习 - 参考 simple_plugin 示例，尝试开发自己的插件
API探索 - 逐步尝试各个API模块的功能

💡 设计亮点

零配置启动 - 插件放入目录即可自动加载
热重载支持 - 开发过程中可动态重载插件（规划中）
依赖管理 - 支持插件间依赖关系声明
配置系统 - 支持TOML配置文件，灵活可定制
完整API - 覆盖机器人开发的各个方面
类型安全 - 完整的类型注解，IDE智能提示

🎯 下一步

选择适合你的起点：

💡 提示: 插件系统仍在持续改进中，欢迎提出建议和反馈！

5.4 KiB Raw Blame History Unescape Escape