MaiMBot工具系统开发指南：构建自定义功能插件

芮川琨Jack

于 2025-06-24 09:26:40 发布

阅读量748

点赞数 22

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/gitblog_00763/article/details/148863785

MaiMBot工具系统开发指南：构建自定义功能插件

MaiMBot 麦麦bot，一款专注于群组聊天的赛博网友（非常专注）QQ BOT 项目地址: https://gitcode.com/gh_mirrors/ma/MaiMBot

工具系统概述

MaiMBot的工具系统是一个高度模块化的插件架构，允许开发者通过编写简单的Python类来扩展机器人的功能。这个系统采用自动发现和加载机制，使得添加新工具变得异常简单，同时保持了良好的代码组织和可维护性。

核心设计理念

工具系统的设计遵循了几个关键原则：

松耦合：每个工具都是独立的模块，不直接依赖其他工具
标准化接口：所有工具都继承自BaseTool基类，确保统一的调用方式
自动发现：系统会自动扫描并加载符合规范的插件
LLM友好：工具的描述和参数定义采用JSONSchema格式，便于语言模型理解和使用

工具开发详解

基本结构

每个工具必须包含以下核心组件：

from src.tools.tool_can_use.base_tool import BaseTool, load_tool

class WeatherTool(BaseTool):
    # 工具标识符，必须全局唯一
    name = "weather_query"
    
    # 自然语言描述，供LLM理解工具用途
    description = "查询指定城市的天气情况"
    
    # 参数规范，定义工具需要的输入
    parameters = {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "要查询的城市名称"
            },
            "date": {
                "type": "string",
                "description": "查询日期，格式为YYYY-MM-DD",
                "default": "今天"
            }
        },
        "required": ["city"]
    }
    
    async def execute(self, function_args, message_txt=""):
        """工具执行逻辑
        
        参数:
            function_args: 解析后的参数字典
            message_txt: 原始用户消息文本
            
        返回:
            dict: 必须包含name和content字段的执行结果
        """
        city = function_args.get("city")
        date = function_args.get("date", "今天")
        
        # 这里实现实际的天气查询逻辑
        weather_data = await fetch_weather(city, date)
        
        return {
            "name": self.name,
            "content": f"{city}{date}的天气是{weather_data}"
        }

# 加载工具到系统
load_tool(WeatherTool)

关键组件解析

name属性：工具的唯一标识符，建议使用小写字母和下划线的组合
description：简明扼要地描述工具功能，这对LLM选择正确工具至关重要
parameters：采用JSONSchema格式定义，支持类型检查、默认值和必填项标记
execute方法：异步执行函数，包含核心业务逻辑

高级开发技巧

参数设计最佳实践

为常用参数设置合理的默认值
使用枚举类型限制参数取值范围
复杂的参数结构可以拆分为嵌套对象
为每个参数提供清晰的描述

示例：

parameters = {
    "type": "object",
    "properties": {
        "search_query": {
            "type": "string",
            "description": "搜索关键词"
        },
        "search_type": {
            "type": "string",
            "enum": ["web", "image", "news"],
            "default": "web",
            "description": "搜索类型"
        },
        "options": {
            "type": "object",
            "properties": {
                "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 10
                },
                "safe_search": {
                    "type": "boolean",
                    "default": True
                }
            }
        }
    },
    "required": ["search_query"]
}

执行方法优化

添加输入验证逻辑
实现适当的错误处理和回退机制
考虑添加缓存层提高性能
对于耗时操作，支持进度反馈

工具集成与调用

自动加载机制

系统启动时会自动执行以下流程：

扫描工具目录下的所有Python文件
识别所有继承自BaseTool的类
通过load_tool装饰器加载有效工具
构建全局工具注册表

调用流程示例

from src.tools.tool_use import ToolUser

async def handle_user_request(message):
    tool_user = ToolUser()
    
    # 工具调用
    result = await tool_user.use_tool(
        message_txt=message.text,
        sender_name=message.sender,
        chat_stream=message.stream
    )
    
    # 结果处理
    if result["used_tools"]:
        for tool_result in result["collected_info"]:
            print(f"工具{tool_result['name']}返回结果: {tool_result['content']}")
    else:
        print("本次请求未使用任何工具")