better：优化文档

2025-06-15 23:30:53 +08:00
parent 517f0c29e1
commit 2879b5dba0
14 changed files with 3680 additions and 1048 deletions
--- a/docs/plugins/examples/complete-examples.md
+++ b/docs/plugins/examples/complete-examples.md
@@ -0,0 +1,414 @@
+# 📚 完整示例
+
+## 📖 概述
+
+这里收集了各种类型的完整插件示例，展示了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插件系统的强大功能！根据你的需求选择合适的示例作为起点。**