murainbot 0.3.1

一个基于python适配onebot11协议的轻量级Onebot框架/QQ机器人框架/QQBot框架

🤔 概述

MuRainBot2 (MRB2) 是一个基于 Python、适配 OneBot v11 协议的轻量级开发框架。

它专注于提供稳定高效的核心事件处理与 API 调用能力，所有具体功能（如关键词回复、群管理等）均通过插件实现，赋予开发者高度的灵活性。

对于具体的操作（如监听消息、发送消息、批准加群请求等）请先明确：

• 什么是OneBot11协议；
• 什么是Onebot实现端，什么是Onebot开发框架；
• Onebot实现端具有哪些功能

✨ 核心特性

• 🪶 轻量高效： 没有太多冗杂的功能，使用简单，内存占用较低。
• 🧩 轻松扩展： 灵活的插件系统，让您能够轻松、快速地添加、移除或定制所需功能。
• 🔁 基于线程池： 基于内置线程池实现并发处理，没有异步的较为复杂的语法，直接编写同步代码，且如果你使用nogil版本的python解释器可以获得更高的性能。
• 🤖 命令解析： 命令系统吸收了像 FastAPI 一样现代 Web 框架的优点，为开发者带来简洁、高效的插件编写体验。

🚨 重要提醒：关于重构与兼容性

[!CAUTION] 请注意： 本项目在 2025/6/29 进行了一次巨大修改&更新，修改了目录结构和包名，如果您是旧版本用户或拥有旧插件，请修改插件以进行适配。

[!CAUTION] 请注意： 本项目在 2024 年底至 2025 年初进行了一次 彻底的重构（主要涉及 dev 分支并在 2025年1月29日 合并至 master）。

当前的 MRB2 版本与重构前的旧版本插件完全不兼容。 如果您是旧版本用户或拥有旧插件，请参考 最新文档 进行适配迁移。

📖 背景与术语

• MRB2： MuRainBot2 的缩写。
• OneBot v11 协议： 一个广泛应用于即时通讯软件中的聊天机器人的应用层协议标准，本项目基于此标准开发。详情请见 OneBot v11。
• 框架： MRB2 作为一个 OneBot 开发框架，负责处理与 OneBot 实现端的通信、事件分发、API 调用封装等底层工作，以及提供插件系统，让开发者可以专注于插件功能的实现。更多通用术语可参考 OneBot v12 术语表 (v11 与 v12 大体相通)。
• 插件： MRB2 的所有功能都由插件提供。插件通常是放置在 plugins 目录下的 Python 文件或包含 __init__.py 的 Python 包。

什么？你问我为什么要叫MRB2，因为这个框架最初是给我的一个叫做沐雨的bot写的，然后之前还有一个写的很垃圾的版本，所以就叫做MRB2

🐛 问题反馈

如果使用时遇到问题，请按以下步骤操作：

1. 将框架版本更新到 dev 分支（可选，但推荐）
2. 将 config.yml 中的 debug.enable 设置为 true。
3. 复现您遇到的 Bug。
4. 检查 Onebot 实现端的日志，确认问题是否源于实现端本身。如果是，请向您使用的实现端反馈。
5. 如果问题确认在 MRB2 框架：
   • 请准备完整的 MRB2 日志文件 (logs 目录下)。您可以自行遮挡日志中的 QQ 号、群号等敏感信息。
   • 提供清晰的错误描述、复现步骤。
   • 如果开启了 save_dump 且生成了 dump 文件，可以一并提供。（不强制，但是推荐提供，不过需要注意可以检查一下是否包含apikey等敏感信息）
   • 将当前使用的MRB2版本、日志、错误描述、复现步骤，以及dump文件（可选），提交到项目的 Issues 页面。

如果不遵守以上要求，您的问题可能会被关闭或无视。

📁 目录结构

查看基本目录结构

├─ data                MRB2及插件的临时/缓存文件
│   ├─ ...
├─ murainbot                 MRB2的Lib库，插件和MRB2均需要依赖此Lib
│   ├─ __init__.py     MRB2Lib的初始化文件
│   ├─ core            核心模块，负责配置文件读取、与实现端通信、插件加载等
│   |   ├─ ...
│   ├─ utils           工具模块，实现一些偏工具类的功能，例如QQ信息缓存、日志记录、事件分类等
│   |   ├─ ...
│   ...
├─ logs
│   ├─ latest.log      当日的日志
│   ├─ xxxx-xx-xx.log  以往的日志
│   ...
├─ plugins
│   ├─ xxx.py           xxx插件代码
│   ├─ yyy.py           yyy插件代码
│   ...
├─ plugin_configs
│   ├─ xxx.yml          xxx插件的配置文件
│   ├─ yyy.yml          yyy插件的配置文件
│   ...
├─ config.yml           MRB2配置文件
├─ main.py              MRB2的入口文件
└─ README.md            这个文件就不用解释了吧（？）

💻 如何部署？

本项目使用 Python 3.12+ 开发，并利用了其部分新特性 (如 PEP 701)。推荐使用 Python 3.12 或更高版本运行，如果使用 Python 3.12 以下版本，由于未经测试，可能会导致部分代码出现问题。

详细的部署步骤、配置说明和插件开发指南，请查阅：

➡️ MRB2 官方文档

快速部署指南

• 安装murainbot2

  pip install murainbot
  

• 创建项目

  murainbot init
  

• 启动项目

  murainbot run
  

📕 关于版本

• 目前项目仍在开发中，属于测试版，未来还可能会有一些不兼容更改和新功能添加，也欢迎各位提供宝贵的建设性的意见。

❤️ 鸣谢 ❤️

贡献指南： 我们欢迎各种形式的贡献！包括 Issues 和 Pull Request，您可以向我们反馈 bug 提供建议，请求一些新功能，也可以通过 PR 直接帮我们编写代码来实现功能或者修复bug。请将您的 Pull Request 提交到 dev 分支。我们会定期将 dev 分支的稳定更新合并到 master 分支。

感谢所有为 MRB2 付出努力的贡献者！

特别感谢 HarcicYang、kaokao221 和 BigCookie233 在项目开发过程中提供的宝贵帮助！

⭐ Star History ⭐

🚀 关于性能

本项目在正常使用，默认配置，多群聊，6-8个中等复杂度（如签到、图片绘制（如视频信息展示等）、AI聊天（基于API接口调用的））的插件情况下内存占用稳定在 100-160MB 左右 （具体取决于插件和群聊数量以及配置文件，也可能超过这个范围）

仅安装默认插件，默认配置，情况下内存占用稳定在 40MB-60MB 左右

如果实在内存不够用可调小缓存（配置文件中的 qq_data_cache.max_cache_size）（尽管这个也占不了多少内存）