414 lines
13 KiB
Markdown
414 lines
13 KiB
Markdown
# 📚 完整示例
|
||
|
||
## 📖 概述
|
||
|
||
这里收集了各种类型的完整插件示例，展示了MaiBot插件系统的最佳实践和高级用法。每个示例都包含完整的代码、配置和说明。
|
||
|
||
## 🎯 示例列表
|
||
|
||
### 🌟 基础示例
|
||
- [Hello World插件](#hello-world插件) - 快速入门示例
|
||
- [简单计算器](#简单计算器) - Command基础用法
|
||
- [智能问答](#智能问答) - Action基础用法
|
||
|
||
### 🔧 实用示例
|
||
- [用户管理系统](#用户管理系统) - 数据库操作示例
|
||
- [定时提醒插件](#定时提醒插件) - 定时任务示例
|
||
- [天气查询插件](#天气查询插件) - 外部API调用示例
|
||
|
||
### 🛠️ 工具系统示例
|
||
- [天气查询工具](#天气查询工具) - Focus模式信息获取工具
|
||
- [知识搜索工具](#知识搜索工具) - 百科知识查询工具
|
||
|
||
### 🚀 高级示例
|
||
- [多功能聊天助手](#多功能聊天助手) - 综合功能插件
|
||
- [游戏管理插件](#游戏管理插件) - 复杂状态管理
|
||
- [数据分析插件](#数据分析插件) - 数据处理和可视化
|
||
|
||
---
|
||
|
||
## Hello World插件
|
||
|
||
最基础的入门插件，展示Action和Command的基本用法。
|
||
|
||
### 功能说明
|
||
- **HelloAction**: 响应问候语，展示关键词激活
|
||
- **TimeCommand**: 查询当前时间，展示命令处理
|
||
|
||
### 完整代码
|
||
|
||
`plugins/hello_world_plugin/plugin.py`:
|
||
|
||
```python
|
||
from typing import List, Tuple, Type
|
||
from src.plugin_system import (
|
||
BasePlugin, register_plugin, BaseAction, BaseCommand,
|
||
ComponentInfo, ActionActivationType, ChatMode
|
||
)
|
||
|
||
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}风格的问候"
|
||
|
||
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插件"""
|
||
|
||
plugin_name = "hello_world_plugin"
|
||
plugin_description = "Hello World演示插件"
|
||
plugin_version = "1.0.0"
|
||
plugin_author = "MaiBot Team"
|
||
enable_plugin = True
|
||
|
||
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
|
||
return [
|
||
(HelloAction.get_action_info(), HelloAction),
|
||
(TimeCommand.get_command_info(
|
||
name="time_query",
|
||
description="查询当前系统时间"
|
||
), TimeCommand),
|
||
]
|
||
```
|
||
|
||
### 配置文件
|
||
|
||
`plugins/hello_world_plugin/config.toml`:
|
||
|
||
```toml
|
||
[plugin]
|
||
name = "hello_world_plugin"
|
||
version = "1.0.0"
|
||
enabled = true
|
||
|
||
[greeting]
|
||
default_style = "casual"
|
||
enable_emoji = true
|
||
|
||
[time]
|
||
timezone = "Asia/Shanghai"
|
||
format = "%Y-%m-%d %H:%M:%S"
|
||
```
|
||
|
||
---
|
||
|
||
## 天气查询工具
|
||
|
||
展示如何创建Focus模式下的信息获取工具，专门用于扩展麦麦的信息获取能力。
|
||
|
||
### 功能说明
|
||
- **Focus模式专用**：仅在专注聊天模式下工作
|
||
- **自动调用**：LLM根据用户查询自动判断是否使用
|
||
- **信息增强**：为麦麦提供实时天气数据
|
||
- **必须启用工具处理器**
|
||
|
||
### 完整代码
|
||
|
||
`src/tools/tool_can_use/weather_tool.py`:
|
||
|
||
```python
|
||
from src.tools.tool_can_use.base_tool import BaseTool, register_tool
|
||
import aiohttp
|
||
import json
|
||
|
||
class WeatherTool(BaseTool):
|
||
"""天气查询工具 - 获取指定城市的实时天气信息"""
|
||
|
||
# 工具名称，必须唯一
|
||
name = "weather_query"
|
||
|
||
# 工具描述，告诉LLM这个工具的用途
|
||
description = "查询指定城市的实时天气信息，包括温度、湿度、天气状况等"
|
||
|
||
# 参数定义，遵循JSONSchema格式
|
||
parameters = {
|
||
"type": "object",
|
||
"properties": {
|
||
"city": {
|
||
"type": "string",
|
||
"description": "要查询天气的城市名称，如：北京、上海、纽约"
|
||
},
|
||
"country": {
|
||
"type": "string",
|
||
"description": "国家代码，如：CN、US，可选参数"
|
||
}
|
||
},
|
||
"required": ["city"]
|
||
}
|
||
|
||
async def execute(self, function_args, message_txt=""):
|
||
"""执行天气查询"""
|
||
try:
|
||
city = function_args.get("city")
|
||
country = function_args.get("country", "")
|
||
|
||
# 构建查询参数
|
||
location = f"{city},{country}" if country else city
|
||
|
||
# 调用天气API
|
||
weather_data = await self._fetch_weather(location)
|
||
|
||
# 格式化结果
|
||
result = self._format_weather_data(weather_data)
|
||
|
||
return {
|
||
"name": self.name,
|
||
"content": result
|
||
}
|
||
|
||
except Exception as e:
|
||
return {
|
||
"name": self.name,
|
||
"content": f"天气查询失败: {str(e)}"
|
||
}
|
||
|
||
async def _fetch_weather(self, location: str) -> dict:
|
||
"""获取天气数据"""
|
||
# 这里是示例，实际需要接入真实的天气API
|
||
# 例如：OpenWeatherMap、和风天气等
|
||
api_url = f"http://api.weather.com/v1/current?q={location}"
|
||
|
||
async with aiohttp.ClientSession() as session:
|
||
async with session.get(api_url) as response:
|
||
return await response.json()
|
||
|
||
def _format_weather_data(self, data: dict) -> str:
|
||
"""格式化天气数据"""
|
||
if not data:
|
||
return "暂无天气数据"
|
||
|
||
# 提取关键信息
|
||
city = data.get("location", {}).get("name", "未知城市")
|
||
temp = data.get("current", {}).get("temp_c", "未知")
|
||
condition = data.get("current", {}).get("condition", {}).get("text", "未知")
|
||
humidity = data.get("current", {}).get("humidity", "未知")
|
||
|
||
# 格式化输出
|
||
return f"""
|
||
🌤️ {city} 实时天气
|
||
━━━━━━━━━━━━━━━━━━
|
||
🌡️ 温度: {temp}°C
|
||
☁️ 天气: {condition}
|
||
💧 湿度: {humidity}%
|
||
━━━━━━━━━━━━━━━━━━
|
||
""".strip()
|
||
|
||
# 注册工具（重要！必须调用）
|
||
register_tool(WeatherTool)
|
||
```
|
||
|
||
### 使用说明
|
||
|
||
1. **部署位置**：将文件放在 `src/tools/tool_can_use/` 目录下
|
||
2. **模式要求**：仅在Focus模式下可用
|
||
3. **配置要求**：必须开启工具处理器 `enable_tool_processor = True`
|
||
4. **自动调用**：用户发送"今天北京天气怎么样？"时，麦麦会自动调用此工具
|
||
|
||
---
|
||
|
||
## 知识搜索工具
|
||
|
||
展示如何创建知识查询工具，为麦麦提供百科知识和专业信息。
|
||
|
||
### 功能说明
|
||
- **知识增强**：扩展麦麦的知识获取能力
|
||
- **分类搜索**：支持科学、历史、技术等分类
|
||
- **多语言支持**：支持中英文结果
|
||
- **智能调用**：LLM自动判断何时需要知识查询
|
||
|
||
### 完整代码
|
||
|
||
`src/tools/tool_can_use/knowledge_search_tool.py`:
|
||
|
||
```python
|
||
from src.tools.tool_can_use.base_tool import BaseTool, register_tool
|
||
import aiohttp
|
||
import json
|
||
|
||
class KnowledgeSearchTool(BaseTool):
|
||
"""知识搜索工具 - 查询百科知识和专业信息"""
|
||
|
||
name = "knowledge_search"
|
||
description = "搜索百科知识、专业术语解释、历史事件等信息"
|
||
|
||
parameters = {
|
||
"type": "object",
|
||
"properties": {
|
||
"query": {
|
||
"type": "string",
|
||
"description": "要搜索的知识关键词或问题"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "知识分类：science(科学)、history(历史)、technology(技术)、general(通用)等",
|
||
"enum": ["science", "history", "technology", "general"]
|
||
},
|
||
"language": {
|
||
"type": "string",
|
||
"description": "结果语言：zh(中文)、en(英文)",
|
||
"enum": ["zh", "en"]
|
||
}
|
||
},
|
||
"required": ["query"]
|
||
}
|
||
|
||
async def execute(self, function_args, message_txt=""):
|
||
"""执行知识搜索"""
|
||
try:
|
||
query = function_args.get("query")
|
||
category = function_args.get("category", "general")
|
||
language = function_args.get("language", "zh")
|
||
|
||
# 执行搜索逻辑
|
||
search_results = await self._search_knowledge(query, category, language)
|
||
|
||
# 格式化结果
|
||
result = self._format_search_results(query, search_results)
|
||
|
||
return {
|
||
"name": self.name,
|
||
"content": result
|
||
}
|
||
|
||
except Exception as e:
|
||
return {
|
||
"name": self.name,
|
||
"content": f"知识搜索失败: {str(e)}"
|
||
}
|
||
|
||
async def _search_knowledge(self, query: str, category: str, language: str) -> list:
|
||
"""执行知识搜索"""
|
||
# 这里实现实际的搜索逻辑
|
||
# 可以对接维基百科API、百度百科API等
|
||
|
||
# 示例API调用
|
||
if language == "zh":
|
||
api_url = f"https://zh.wikipedia.org/api/rest_v1/page/summary/{query}"
|
||
else:
|
||
api_url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{query}"
|
||
|
||
async with aiohttp.ClientSession() as session:
|
||
async with session.get(api_url) as response:
|
||
if response.status == 200:
|
||
data = await response.json()
|
||
return [
|
||
{
|
||
"title": data.get("title", "无标题"),
|
||
"summary": data.get("extract", "无摘要"),
|
||
"source": "Wikipedia"
|
||
}
|
||
]
|
||
else:
|
||
return []
|
||
|
||
def _format_search_results(self, query: str, results: list) -> str:
|
||
"""格式化搜索结果"""
|
||
if not results:
|
||
return f"未找到关于 '{query}' 的相关信息"
|
||
|
||
formatted_text = f"📚 关于 '{query}' 的搜索结果:\n\n"
|
||
|
||
for i, result in enumerate(results[:3], 1): # 限制显示前3条
|
||
title = result.get("title", "无标题")
|
||
summary = result.get("summary", "无摘要")
|
||
source = result.get("source", "未知来源")
|
||
|
||
formatted_text += f"{i}. **{title}**\n"
|
||
formatted_text += f" {summary}\n"
|
||
formatted_text += f" 📖 来源: {source}\n\n"
|
||
|
||
return formatted_text.strip()
|
||
|
||
# 注册工具
|
||
register_tool(KnowledgeSearchTool)
|
||
```
|
||
|
||
### 配置示例
|
||
|
||
Focus模式配置文件示例：
|
||
|
||
```python
|
||
# 在Focus模式配置中
|
||
focus_config = {
|
||
"enable_tool_processor": True, # 必须启用工具处理器
|
||
"tool_timeout": 30, # 工具执行超时时间（秒）
|
||
"max_tools_per_message": 3 # 单次消息最大工具调用数
|
||
}
|
||
```
|
||
|
||
### 使用流程
|
||
|
||
1. **用户查询**：用户在Focus模式下发送"什么是量子计算？"
|
||
2. **LLM判断**：麦麦识别这是知识查询需求
|
||
3. **工具调用**：自动调用 `knowledge_search` 工具
|
||
4. **信息获取**：工具查询相关知识信息
|
||
5. **整合回复**：麦麦将获取的信息整合到回复中
|
||
|
||
### 工具系统特点
|
||
|
||
- **🎯 专用性**：仅在Focus模式下工作，专注信息获取
|
||
- **🔍 智能性**：LLM自动判断何时需要使用工具
|
||
- **📊 丰富性**：为麦麦提供外部数据和实时信息
|
||
- **⚡ 高效性**：系统自动发现和注册工具
|
||
- **🔧 独立性**：目前需要单独编写，未来将更好融入插件系统
|
||
|
||
---
|
||
|
||
🎉 **这些示例展示了MaiBot插件系统的强大功能！根据你的需求选择合适的示例作为起点。** |