381 lines
9.6 KiB
Markdown
381 lines
9.6 KiB
Markdown
# 🚀 快速开始指南
|
||
|
||
## 📖 概述
|
||
|
||
这个指南将带你在5分钟内创建你的第一个MaiBot插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。
|
||
|
||
## 🎯 学习目标
|
||
|
||
- 理解插件的基本结构
|
||
- 创建你的第一个Action组件
|
||
- 创建你的第一个Command组件
|
||
- 学会配置插件
|
||
|
||
## 📂 准备工作
|
||
|
||
确保你已经：
|
||
1. 克隆了MaiBot项目
|
||
2. 安装了Python依赖
|
||
3. 了解基本的Python语法
|
||
|
||
## 🏗️ 创建插件
|
||
|
||
### 1. 创建插件目录
|
||
|
||
在项目根目录的 `plugins/` 文件夹下创建你的插件目录：
|
||
|
||
```bash
|
||
mkdir plugins/hello_world_plugin
|
||
cd plugins/hello_world_plugin
|
||
```
|
||
|
||
### 2. 创建插件主文件
|
||
|
||
创建 `plugin.py` 文件：
|
||
|
||
```python
|
||
from typing import List, Tuple, Type
|
||
from src.plugin_system import (
|
||
BasePlugin, register_plugin, BaseAction, BaseCommand,
|
||
ComponentInfo, ActionActivationType, ChatMode
|
||
)
|
||
|
||
# ===== Action组件 =====
|
||
|
||
class HelloAction(BaseAction):
|
||
"""问候Action - 展示智能动作的基本用法"""
|
||
|
||
# ===== 激活控制必须项 =====
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
|
||
# ===== 基本信息必须项 =====
|
||
action_name = "hello_greeting"
|
||
action_description = "向用户发送友好的问候消息"
|
||
|
||
# 关键词配置
|
||
activation_keywords = ["你好", "hello", "hi"]
|
||
keyword_case_sensitive = False
|
||
|
||
# ===== 功能定义必须项 =====
|
||
action_parameters = {
|
||
"greeting_style": "问候风格：casual(随意) 或 formal(正式)"
|
||
}
|
||
|
||
action_require = [
|
||
"用户发送问候语时使用",
|
||
"营造友好的聊天氛围"
|
||
]
|
||
|
||
associated_types = ["text", "emoji"]
|
||
|
||
async def execute(self) -> Tuple[bool, str]:
|
||
"""执行问候动作"""
|
||
# 获取参数
|
||
style = self.action_data.get("greeting_style", "casual")
|
||
|
||
# 根据风格生成问候语
|
||
if style == "formal":
|
||
message = "您好！很高兴为您服务！"
|
||
emoji = "🙏"
|
||
else:
|
||
message = "嗨！很开心见到你！"
|
||
emoji = "😊"
|
||
|
||
# 发送消息
|
||
await self.send_text(message)
|
||
await self.send_type("emoji", emoji)
|
||
|
||
return True, f"发送了{style}风格的问候"
|
||
|
||
# ===== Command组件 =====
|
||
|
||
class TimeCommand(BaseCommand):
|
||
"""时间查询Command - 展示命令的基本用法"""
|
||
|
||
command_pattern = r"^/time$"
|
||
command_help = "查询当前时间"
|
||
command_examples = ["/time"]
|
||
intercept_message = True # 拦截消息处理
|
||
|
||
async def execute(self) -> Tuple[bool, str]:
|
||
"""执行时间查询"""
|
||
import datetime
|
||
|
||
now = datetime.datetime.now()
|
||
time_str = now.strftime("%Y-%m-%d %H:%M:%S")
|
||
|
||
await self.send_text(f"⏰ 当前时间：{time_str}")
|
||
|
||
return True, f"显示了当前时间: {time_str}"
|
||
|
||
# ===== 插件注册 =====
|
||
|
||
@register_plugin
|
||
class HelloWorldPlugin(BasePlugin):
|
||
"""Hello World插件 - 你的第一个MaiBot插件"""
|
||
|
||
# 插件基本信息
|
||
plugin_name = "hello_world_plugin"
|
||
plugin_description = "Hello World演示插件，展示基本的Action和Command用法"
|
||
plugin_version = "1.0.0"
|
||
plugin_author = "你的名字"
|
||
enable_plugin = True # 默认启用插件
|
||
config_file_name = "config.toml"
|
||
|
||
# Python依赖声明（可选）
|
||
python_dependencies = [
|
||
# 如果你的插件需要额外的Python包，在这里声明
|
||
# PythonDependency(
|
||
# package_name="requests",
|
||
# version=">=2.25.0",
|
||
# description="HTTP请求库"
|
||
# ),
|
||
]
|
||
|
||
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
|
||
"""返回插件包含的组件列表"""
|
||
return [
|
||
# Action组件 - 使用类中定义的所有属性
|
||
(HelloAction.get_action_info(), HelloAction),
|
||
|
||
# Command组件 - 需要指定name和description
|
||
(TimeCommand.get_command_info(
|
||
name="time_query",
|
||
description="查询当前系统时间"
|
||
), TimeCommand),
|
||
]
|
||
```
|
||
|
||
### 3. 创建配置文件
|
||
|
||
创建 `config.toml` 文件：
|
||
|
||
```toml
|
||
[plugin]
|
||
name = "hello_world_plugin"
|
||
version = "1.0.0"
|
||
enabled = true
|
||
description = "Hello World演示插件"
|
||
|
||
[greeting]
|
||
default_style = "casual"
|
||
enable_emoji = true
|
||
|
||
[time]
|
||
timezone = "Asia/Shanghai"
|
||
format = "%Y-%m-%d %H:%M:%S"
|
||
|
||
[logging]
|
||
level = "INFO"
|
||
```
|
||
|
||
### 4. 创建说明文档
|
||
|
||
创建 `README.md` 文件：
|
||
|
||
```markdown
|
||
# Hello World 插件
|
||
|
||
## 概述
|
||
|
||
这是一个简单的Hello World插件，演示了MaiBot插件系统的基本用法。
|
||
|
||
## 功能
|
||
|
||
- **HelloAction**: 智能问候动作，响应用户的问候语
|
||
- **TimeCommand**: 时间查询命令，显示当前时间
|
||
|
||
## 使用方法
|
||
|
||
### Action使用
|
||
当用户发送包含"你好"、"hello"或"hi"的消息时，插件会自动触发问候动作。
|
||
|
||
### Command使用
|
||
发送 `/time` 查询当前时间。
|
||
|
||
## 配置
|
||
|
||
可以通过 `config.toml` 调整插件行为。
|
||
```
|
||
|
||
## 🎮 测试插件
|
||
|
||
### 1. 启动MaiBot
|
||
|
||
将插件放入 `plugins/` 目录后，启动MaiBot：
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
### 2. 测试Action
|
||
|
||
发送消息：
|
||
```
|
||
你好
|
||
```
|
||
|
||
期望输出：
|
||
```
|
||
嗨！很开心见到你！😊
|
||
```
|
||
|
||
### 3. 测试Command
|
||
|
||
发送命令：
|
||
```
|
||
/time
|
||
```
|
||
|
||
期望输出：
|
||
```
|
||
⏰ 当前时间：2024-01-01 12:00:00
|
||
```
|
||
|
||
## 🔍 解析代码
|
||
|
||
### Action组件重点
|
||
|
||
1. **激活控制**: 使用 `KEYWORD` 激活类型，当检测到指定关键词时触发
|
||
2. **必须项完整**: 包含所有必须的类属性
|
||
3. **智能决策**: 麦麦会根据情境决定是否使用这个Action
|
||
|
||
### Command组件重点
|
||
|
||
1. **正则匹配**: 使用 `^/time$` 精确匹配 `/time` 命令
|
||
2. **消息拦截**: 设置 `intercept_message = True` 防止命令继续处理
|
||
3. **即时响应**: 匹配到命令立即执行
|
||
|
||
### 插件注册重点
|
||
|
||
1. **@register_plugin**: 装饰器自动注册插件
|
||
2. **组件列表**: `get_plugin_components()` 返回所有组件
|
||
3. **配置加载**: 自动加载 `config.toml` 文件
|
||
|
||
## 📦 添加依赖包（可选）
|
||
|
||
如果你的插件需要额外的Python包，可以声明依赖：
|
||
|
||
```python
|
||
from src.plugin_system import PythonDependency
|
||
|
||
@register_plugin
|
||
class HelloWorldPlugin(BasePlugin):
|
||
# ... 其他配置 ...
|
||
|
||
# 声明Python依赖
|
||
python_dependencies = [
|
||
PythonDependency(
|
||
package_name="requests",
|
||
version=">=2.25.0",
|
||
description="HTTP请求库，用于网络功能"
|
||
),
|
||
PythonDependency(
|
||
package_name="numpy",
|
||
version=">=1.20.0",
|
||
optional=True,
|
||
description="数值计算库（可选功能）"
|
||
),
|
||
]
|
||
```
|
||
|
||
### 依赖检查
|
||
|
||
系统会自动检查依赖，你也可以手动检查：
|
||
|
||
```python
|
||
from src.plugin_system import plugin_manager
|
||
|
||
# 检查所有插件依赖
|
||
result = plugin_manager.check_all_dependencies()
|
||
print(f"缺少依赖的插件: {result['plugins_with_missing_required']}个")
|
||
|
||
# 生成requirements文件
|
||
plugin_manager.generate_plugin_requirements("plugin_deps.txt")
|
||
```
|
||
|
||
📚 **详细了解**: [依赖管理系统](dependency-management.md)
|
||
|
||
## 🎯 下一步
|
||
|
||
恭喜！你已经创建了第一个MaiBot插件。接下来可以：
|
||
|
||
1. 学习 [Action组件详解](action-components.md) 掌握更复杂的Action开发
|
||
2. 学习 [Command组件详解](command-components.md) 创建更强大的命令
|
||
3. 了解 [依赖管理系统](dependency-management.md) 管理Python包依赖
|
||
4. 查看 [API参考](api/) 了解所有可用的接口
|
||
5. 参考 [完整示例](examples/complete-examples.md) 学习最佳实践
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q: 插件没有加载怎么办？
|
||
A: 检查：
|
||
1. 插件是否放在 `plugins/` 目录下
|
||
2. `plugin.py` 文件语法是否正确
|
||
3. 查看启动日志中的错误信息
|
||
|
||
### Q: Action没有触发怎么办？
|
||
A: 检查：
|
||
1. 关键词是否正确配置
|
||
2. 消息是否包含激活关键词
|
||
3. 聊天模式是否匹配
|
||
|
||
### Q: Command无响应怎么办？
|
||
A: 检查：
|
||
1. 正则表达式是否正确
|
||
2. 命令格式是否精确匹配
|
||
3. 是否有其他插件拦截了消息
|
||
|
||
## 🔧 插件启用状态管理
|
||
|
||
### 启用状态控制方式
|
||
|
||
插件可以通过以下两种方式控制启用状态：
|
||
|
||
1. **类属性控制**
|
||
```python
|
||
class MyPlugin(BasePlugin):
|
||
enable_plugin = True # 在类中设置启用状态
|
||
```
|
||
|
||
2. **配置文件控制**
|
||
```toml
|
||
[plugin]
|
||
enabled = true # 在配置文件中设置启用状态
|
||
```
|
||
|
||
### 启用状态优先级
|
||
|
||
1. 配置文件中的设置优先级高于类属性
|
||
2. 如果配置文件中没有 `[plugin] enabled` 设置，则使用类属性中的值
|
||
3. 如果类属性也没有设置，则使用 `BasePlugin` 的默认值 `False`
|
||
|
||
### 最佳实践
|
||
|
||
1. 在开发插件时，建议在类中设置 `enable_plugin = True`
|
||
2. 在部署插件时，通过配置文件控制启用状态
|
||
3. 在文档中明确说明插件的默认启用状态
|
||
4. 提供配置示例，说明如何启用/禁用插件
|
||
|
||
### 常见问题
|
||
|
||
1. **插件未加载**
|
||
- 检查类属性 `enable_plugin` 是否设置为 `True`
|
||
- 检查配置文件中的 `[plugin] enabled` 设置
|
||
- 查看日志中是否有插件加载相关的错误信息
|
||
|
||
2. **配置文件不生效**
|
||
- 确保配置文件名称正确（默认为 `config.toml`）
|
||
- 确保配置文件格式正确（TOML格式）
|
||
- 确保配置文件中的 `[plugin]` 部分存在
|
||
|
||
3. **动态启用/禁用**
|
||
- 修改配置文件后需要重启MaiBot才能生效
|
||
- 目前不支持运行时动态启用/禁用插件
|
||
|
||
---
|
||
|
||
🎉 **成功！你已经掌握了MaiBot插件开发的基础！** |