基于 NoneBot2 + OneBot V11 的 QQ 机器人,集成 MCSManager 面板管理、Minecraft 服务器备份、QQ ↔ MC 聊天互通等功能。
孩子们我回来了 —— 2024.7.18 – 2026.5.12
# 1. 安装依赖并启动
bash start.shstart.sh 会自动创建 venv、安装依赖、安装 Playwright 的 Firefox 浏览器,然后启动 bot。
之后日常运行只需:
bash run.sh复制 config.example.toml 为 config.toml:
[database]
mongo_connection_string = "mongodb://user:password@ip:port/"
[nonebot]
# 这里填 NoneBot 配置,会被自动转发到 .env
[logging]
level = "debug" # debug / info / warn / error / crit
inject_nonebot = true # 是否接管 NoneBot 日志
[general]
superusers = [1111111111]
# 可选:MCSManager 面板配置
# [mcsm]
# base_url = "http://127.0.0.1:23333/"
# key = "YOUR_API_KEY"
# ignored = ["bot"] # 日志转发忽略的实例昵称.
├── main.py # 入口:解析配置 → 连接数据库 → 注册规则 → 启动 NoneBot
├── config.toml # 运行时配置(需自行创建)
├── run.sh / start.sh # 启动脚本
├── requirements.txt # Python 依赖
├── HTML_GUIDELINE.md # HTML 渲染设计规范(科幻终端 / HUD 风格)
│
├── message_source/ # 消息来源层
│ ├── qq.py # QQ 消息接入(OneBot V11)
│ ├── mc.py # Minecraft 日志轮询 + 消息解析
│ └── api.py # 事件分发:按优先级遍历注册的 Rule
│
├── lib/ # 核心库
│ ├── logger.py # 带 ANSI 颜色的自定义日志系统
│ ├── rule_registry.py # 规则扫描 + 类装饰器自动注册机制
│ ├── database/ # MongoDB 连接与配置/缓存管理
│ ├── chat/ # 聊天系统核心抽象
│ │ ├── rule.py # Rule 抽象基类(check → handle)
│ │ ├── rules.py # QqCommand / McCommand 基类
│ │ ├── context.py # 请求上下文(输入/输出适配器 + 会话 + 发送者)
│ │ ├── chat_session.py # 会话:权限、禁言、踢人、指令开关
│ │ ├── Input_adapters.py # 输入适配器(QQ 消息 → 富文本 / MC 纯文本)
│ │ ├── output_adapters.py # 输出适配器(QQ 回复 / MC tellraw)
│ │ └── html_renderer.py # Playwright HTML → PNG 渲染
│ ├── html_files/ # 各功能的 HTML 模板(帮助、骰子、实例列表等)
│ ├── mcsmanager/ # MCSManager API 封装(装饰器驱动的请求构建)
│ └── backup/ # 增量备份引擎(xxhash + zstd 去重)
│ └── auto.py # 自动备份调度(定时 + 在线检测)
│
└── rules/ # 事件处理规则(自动扫描注册)
├── common/ # QQ 与游戏内共用的规则
│ └── backup.py # /back + /aback 手动/自动备份管理
├── general/ # 通用 QQ 指令
│ ├── dice.py # /roll 骰子(支持 NdM,HTML 卡片结果)
│ ├── help.py # /help 帮助搜索(-n/-u/-d 按名称/用法/描述搜索)
│ ├── command.py # /cmd 指令启用/禁用,/cmds 查看状态
│ ├── permissions.py # /perm 权限设置,/tag 标签,/role 身份
│ └── profile.py # /profile 个人信息
├── in_game/ # 游戏内指令(通过 MC 聊天触发)
│ ├── general.py # !!help 游戏内帮助(支持搜索)
│ ├── calc.py # !!calc 计算器 + <!!calc> 行内计算
│ └── alarm.py # !!alarm 闹钟(支持 1h30m / 1:30:00 / 90s 格式)
└── mcsm/ # MCSManager 面板 QQ 指令
├── general.py # /mcsm 仪表盘, /mcsmrnd 节点信息, /mcsmdid Daemon ID
├── instance.py # /list 实例列表, /start /stop /restart /kill /send /log
└── chat_sync.py # /bind QQ 群 ↔ MC 聊天同步
通过 /bind <实例昵称> 将 QQ 群与 MC 服务器绑定,双向实时转发聊天消息。
| 指令 | 功能 |
|---|---|
/mcsm |
仪表盘概览 |
/list |
所有实例列表 |
/start <名称> |
启动实例 |
/stop <名称> |
安全停止 |
/restart <名称> |
重启 |
/kill <名称> |
强制终止 |
/send <名称> <命令> |
向终端发送命令 |
/log <名称> <行数> |
查看输出日志 |
基于 xxhash 摘要 + zstandard 压缩 + 内容寻址 blob 存储的增量备份引擎:
- 同名文件仅 mtime/size 未变时直接复用旧哈希,跳过读取
- 相同内容自动去重(多个实例共享同一 blob)
- 支持自动备份(在线玩家检测、间隔/保留数量可配)
| 上下文 | 指令 | 功能 |
|---|---|---|
| `/aback [实例] [status | on | |
| `/back <实例> [list | start | |
| 游戏内 | !!aback |
游戏内自动备份管理 |
| 游戏内 | !!back |
游戏内手动备份管理 |
| 指令 | 功能 |
|---|---|
!!calc <算式> |
计算器,输出组数/流体锭/tick 换算 |
<!!calc [-s/f/t/sec] 算式> |
行内计算器,聊天中直接替换结果 |
!!alarm 1h30m [事项] |
闹钟(支持 1h30m / 1:30:00 / 90 格式) |
!!help [-nud] <关键词> |
游戏内帮助(支持按名称/用法/描述搜索) |
| 指令 | 功能 | 需要身份 |
|---|---|---|
/perm <用户> <等级> |
设置群内权限 0-10 | 需高于目标等级 |
/tag -a/-d <用户> <标签> |
增删标签 | ADMIN |
/role <用户> user/admin |
设置全局身份 | SUPER_ADMIN |
各群/私聊可独立开关指令:
/cmd -e <id0> [id1] ...— 启用(多个 id 或all)/cmd -d <id0> [id1] ...— 禁用/cmds— 查看状态
所有 QQ 回复使用 Playwright (Firefox) 将 HTML 渲染为 PNG 图片发送,视觉风格遵循 HTML_GUIDELINE.md 定义的科幻终端 / HUD 硬核风格。
- 框架: NoneBot2 + OneBot V11
- 数据库: MongoDB (PyMongo)
- 渲染: Playwright + Firefox
- 备份: xxhash + zstandard
- 配置: TOML