如何写麦麦v0.1插件
如何编写MaiBot插件
Section titled “如何编写MaiBot插件”目前插件系统为v0.1版本,仅试行并实现简单功能,且只能在focus下使用。 目前插件的形式为给focus模型的决策增加新动作action。 原有focus的planner有reply和no_reply两种动作。 在麦麦plugin文件夹中的示例插件新增了mute_action动作和pic_action动作,你可以参考其中的代码。 在之后的更新中,会兼容normal_chat aciton,更多的自定义组件,tool,和/help式指令。
- 在src/plugins/你的插件名/actions/目录下创建插件文件。
- 继承PluginAction基类。
- 实现process方法。
- 在src/plugins/你的插件名/init.py中导入你的插件类,确保插件能被正确加载。
# src/plugins/你的插件名/__init__.pyfrom .actions.your_action import YourAction__all__ = ["YourAction"]
插件结构示例
Section titled “插件结构示例”from src.common.logger_manager import get_loggerfrom src.chat.focus_chat.planners.actions.plugin_action import PluginAction, register_actionfrom typing import Tuple
logger = get_logger("your_action_name")
@register_actionclass YourAction(PluginAction): """你的动作描述"""
action_name = "your_action_name" # 动作名称,必须唯一 action_description = "这个动作的详细描述,会展示给用户" action_parameters = { "param1": "参数1的说明(可选)", "param2": "参数2的说明(可选)" } action_require = [ "使用场景1", "使用场景2" ] default = False # 是否默认启用
associated_types = ["command", "text"] #该插件会发送的消息类型
async def process(self) -> Tuple[bool, str]: """插件核心逻辑""" # 你的代码逻辑... return True, "执行结果"
可用的API方法
Section titled “可用的API方法”插件可以使用PluginAction基类提供的以下API:
1. 直接发送消息
Section titled “1. 直接发送消息”# 发送文本await self.send_message(type="text", data="你好")
# 发送图片await self.send_message(type="image", data=base64_image_string)
# 发送命令(需要adapter支持)await self.send_message( type="command", data={"name": "GROUP_BAN", "args": {"qq_id": str(user_id), "duration": duration_str}}, display_message=f"我禁言了 {target} {duration_str}秒",)
会将消息直接以原始文本发送,type指定消息类型,data为发送内容。
2. 使用表达器发送消息
Section titled “2. 使用表达器发送消息”await self.send_message_by_expressor("你好")
await self.send_message_by_expressor(f"禁言{target} {duration}秒,因为{reason}")
将消息通过表达器发送,使用LLM组织成符合bot语言风格的内容并发送,只能发送文本。
3. 获取聊天类型
Section titled “3. 获取聊天类型”chat_type = self.get_chat_type() # 返回 "group" 或 "private" 或 "unknown"
4. 获取最近消息
Section titled “4. 获取最近消息”messages = self.get_recent_messages(count=5) # 获取最近5条消息# 返回格式: [{"sender": "发送者", "content": "内容", "timestamp": 时间戳}, ...]
5. 获取动作参数
Section titled “5. 获取动作参数”param_value = self.action_data.get("param_name", "默认值")
6. 获取可用模型
Section titled “6. 获取可用模型”models = self.get_available_models() # 返回所有可用的模型配置# 返回格式: {"model_name": {"config": "value", ...}, ...}
7. 使用模型生成内容
Section titled “7. 使用模型生成内容”success, response, reasoning, model_name = await self.generate_with_model( prompt="你的提示词", model_config=models["model_name"], # 从get_available_models获取的模型配置 max_tokens=2000, # 可选,最大生成token数 request_type="plugin.generate", # 可选,请求类型标识 temperature=0.7, # 可选,温度参数 # 其他模型特定参数...)
8. 获取用户ID
Section titled “8. 获取用户ID”platform, user_id = await self.get_user_id_by_person_name("用户名")
logger.info(f"{self.log_prefix} 你的日志信息")logger.warning("警告信息")logger.error("错误信息")
process方法必须返回一个元组,包含两个元素:
- 第一个元素(bool): 表示动作是否执行成功
- 第二个元素(str): 执行结果的文本描述(可以为空"")
return True, "执行成功的消息"# 或return False, "执行失败的原因"
- 使用action_parameters清晰定义你的动作需要的参数。
- 使用action_require描述何时应该使用你的动作。
- 使用action_description准确描述你的动作功能。
- 使用logger记录重要信息,方便调试。
- 避免操作底层系统,尽量使用PluginAction提供的API。
插件会在系统启动时自动加载,只要放在正确的目录并添加了@register_action装饰器。 若设置default = True,插件会自动添加到默认动作集并启用,否则默认只加载不启用。