155 lines
5.4 KiB
Markdown
155 lines
5.4 KiB
Markdown
# MaiBot 插件编写指南 - 总览
|
||
|
||
## 📋 目录结构
|
||
|
||
本指南分为三个部分：
|
||
|
||
- **[总览](plugin_guide_overview.md)** - 插件系统架构和设计理念（当前文档）
|
||
- **[快速开始](plugin_quick_start.md)** - 5分钟创建你的第一个插件
|
||
- **[详细解析](plugin_detailed_guide.md)** - 深入理解各个组件和API
|
||
|
||
## 🎯 插件系统概述
|
||
|
||
MaiBot 采用组件化的插件系统，让开发者可以轻松扩展机器人功能。系统支持两种主要组件类型：
|
||
|
||
- **Action组件** - 智能动作，基于关键词、LLM判断等条件自动触发
|
||
- **Command组件** - 命令处理，基于正则表达式匹配用户输入的命令
|
||
|
||
## 🏗️ 系统架构
|
||
|
||
```
|
||
src/
|
||
├── plugin_system/ # 🔧 系统核心（框架代码）
|
||
│ ├── core/ # 插件管理和注册中心
|
||
│ ├── apis/ # 统一API接口（7大模块）
|
||
│ ├── base/ # 插件和组件基类
|
||
│ └── registry/ # 组件注册和查询
|
||
└── plugins/ # 🔌 插件内容（用户代码）
|
||
├── built_in/ # 内置插件
|
||
└── examples/ # 示例插件
|
||
```
|
||
|
||
### 核心设计理念
|
||
|
||
1. **分离关注点** - 系统框架与插件内容完全分离
|
||
2. **组件化设计** - 一个插件可包含多个Action和Command组件
|
||
3. **统一API访问** - 通过PluginAPI统一访问所有系统功能
|
||
4. **声明式配置** - 通过类属性声明组件行为，简化开发
|
||
5. **类型安全** - 完整的类型定义，IDE友好
|
||
|
||
## 🧩 组件类型详解
|
||
|
||
### Action组件 - 智能动作
|
||
|
||
Action用于实现智能交互逻辑，支持多种激活方式：
|
||
|
||
- **关键词激活** - 消息包含特定关键词时触发
|
||
- **LLM判断激活** - 使用大模型智能判断是否需要触发
|
||
- **随机激活** - 按概率随机触发
|
||
- **始终激活** - 每条消息都触发（谨慎使用）
|
||
|
||
**适用场景：**
|
||
- 智能问候、闲聊互动
|
||
- 情感分析和回应
|
||
- 内容审核和提醒
|
||
- 数据统计和分析
|
||
|
||
### Command组件 - 命令处理
|
||
|
||
Command用于处理结构化的用户命令，基于正则表达式匹配：
|
||
|
||
- **精确匹配** - 支持参数提取和验证
|
||
- **灵活模式** - 正则表达式的完整威力
|
||
- **帮助系统** - 自动生成命令帮助信息
|
||
|
||
**适用场景：**
|
||
- 功能性操作（查询、设置、管理）
|
||
- 工具类命令（计算、转换、搜索）
|
||
- 系统管理命令
|
||
- 游戏和娱乐功能
|
||
|
||
## 🔌 API系统概览
|
||
|
||
系统提供7大API模块，涵盖插件开发的所有需求：
|
||
|
||
| API模块 | 功能描述 | 主要用途 |
|
||
|---------|----------|----------|
|
||
| **MessageAPI** | 消息发送和交互 | 发送文本、图片、语音等消息 |
|
||
| **LLMAPI** | 大模型调用 | 文本生成、智能判断、创意创作 |
|
||
| **DatabaseAPI** | 数据库操作 | 存储用户数据、配置、历史记录 |
|
||
| **ConfigAPI** | 配置访问 | 读取全局配置和用户信息 |
|
||
| **UtilsAPI** | 工具函数 | 文件操作、时间处理、ID生成 |
|
||
| **StreamAPI** | 流管理 | 聊天流控制和状态管理 |
|
||
| **HearflowAPI** | 心流系统 | 与消息处理流程集成 |
|
||
|
||
## 🎨 开发体验
|
||
|
||
### 简化的导入接口
|
||
|
||
```python
|
||
from src.plugin_system import (
|
||
BasePlugin, register_plugin, BaseAction, BaseCommand,
|
||
ComponentInfo, ActionInfo, CommandInfo, ActionActivationType, ChatMode
|
||
)
|
||
```
|
||
|
||
### 声明式组件定义
|
||
|
||
```python
|
||
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访问
|
||
|
||
```python
|
||
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, "完成！"
|
||
```
|
||
|
||
## 🚀 开发流程
|
||
|
||
1. **创建插件目录** - 在 `src/plugins/` 下创建插件文件夹
|
||
2. **定义插件类** - 继承 `BasePlugin`，设置基本信息
|
||
3. **创建组件类** - 继承 `BaseAction` 或 `BaseCommand`
|
||
4. **注册组件** - 在插件的 `get_plugin_components()` 中返回组件列表
|
||
5. **测试验证** - 启动系统测试插件功能
|
||
|
||
## 📚 学习路径建议
|
||
|
||
1. **初学者** - 从[快速开始](plugin_quick_start.md)开始，5分钟体验插件开发
|
||
2. **进阶开发** - 阅读[详细解析](plugin_detailed_guide.md)，深入理解各个组件
|
||
3. **实战练习** - 参考 `simple_plugin` 示例，尝试开发自己的插件
|
||
4. **API探索** - 逐步尝试各个API模块的功能
|
||
|
||
## 💡 设计亮点
|
||
|
||
- **零配置启动** - 插件放入目录即可自动加载
|
||
- **热重载支持** - 开发过程中可动态重载插件（规划中）
|
||
- **依赖管理** - 支持插件间依赖关系声明
|
||
- **配置系统** - 支持TOML配置文件，灵活可定制
|
||
- **完整API** - 覆盖机器人开发的各个方面
|
||
- **类型安全** - 完整的类型注解，IDE智能提示
|
||
|
||
## 🎯 下一步
|
||
|
||
选择适合你的起点：
|
||
|
||
- 🚀 [立即开始 →](plugin_quick_start.md)
|
||
- 📖 [深入学习 →](plugin_detailed_guide.md)
|
||
- 🔍 [查看示例 →](../src/plugins/examples/simple_plugin/)
|
||
|
||
---
|
||
|
||
> 💡 **提示**: 插件系统仍在持续改进中，欢迎提出建议和反馈！ |