QQ Bot 群聊小助手

官网：codehyq.github.io/qq-bot-page

基于 NoneBot2 + OneBot v11 的 QQ 群聊机器人，支持网易云/QQ 音乐点歌、歌词查询、猜歌游戏、成语接龙、天气查询等多种功能。

所有命令需要 @机器人 才能触发，避免群聊刷屏。

功能一览

音乐

命令	说明
@我 点歌 <歌名>	网易云音乐搜索，选序号发卡片
@我 QQ点歌 <歌名>	QQ 音乐搜索，选序号发链接
@我 歌词	查看上一首歌的歌词（网易云）
@我 每日一歌	随机推荐一首热门歌曲
@我 猜歌	根据歌词猜歌名，60 秒限时
@我 点歌排行	本群点歌次数排行
@我 点歌记录	你的点歌足迹

互动

命令	说明
@我 成语接龙	开始成语接龙游戏，接不上淘汰
@我 抽签 / @我 运势	今日运势，每天限一次
@我 选择 A B C	随机帮你做选择
@我 一言	随机语录（支持分类：一言 动漫）

工具

命令	说明
@我 天气 <城市>	查询城市天气（默认北京）
@我 每日英语	一句英文 + 中文翻译
@我 每日日语	一句日文 + 中文翻译
@我 美图 / @我 二次元	随机动漫图片

通用

命令	说明
@我	显示引导信息
@我 帮助	显示完整功能菜单

快速开始

环境要求

• Docker Desktop（Windows 需开启 WSL2）
• LLBot Desktop（QQ 机器人客户端）
• 一个 QQ 小号（已加入目标群）

1. 启动后端

git clone https://github.com/codehyq/qq-bot.git
cd qq-bot

# 配置网易云 Cookie（可选，提升搜索准确度）
# 从浏览器登录 music.163.com 提取 Cookie，写入 bot/.env：
# echo "NETEASE_COOKIE=你的cookie" >> bot/.env

# 启动 Docker 服务
docker compose up -d

三个容器启动后：

• qq-bot-musicapi-1 — 网易云音乐 API（端口 13000）
• qq-bot-qqmusicapi-1 — QQ 音乐 API（端口 13300）
• qq-bot-nonebot-1 — 机器人核心（端口 8080）

2. 配置 LLBot Desktop

1. 下载 LLBot Desktop，解压到固定目录
2. 运行 llbot.exe，点击"启动"后用 QQ 小号扫码登录
3. 打开 http://localhost:3080，在反向 WebSocket 配置中添加：
   • 地址：ws://localhost:8080/onebot/v11/ws
   • Token：留空

3. 测试

在群里发送 @机器人 帮助 查看所有功能。

架构

QQ群消息 → LLBot Desktop (QQ NT 宿主)
              │ 反向 WebSocket (OneBot v11)
              ▼
         NoneBot2 (Python, :8080)
         ├── at_bot.py       # @机器人拦截器
         ├── music.py        # 点歌
         ├── music_extra.py  # 歌词/每日一歌/猜歌
         ├── idiom_chain.py  # 成语接龙
         ├── weather.py      # 天气
         ├── quote.py        # 一言
         ├── fortune.py      # 抽签
         ├── choose.py       # 选择困难症
         ├── daily_lang.py   # 每日英语/日语
         ├── image.py        # 美图
         ├── help.py         # 帮助菜单
         └── db.py           # SQLite 数据库
              │
         ┌────┴────┐
         ▼         ▼
    musicapi    qqmusicapi
   (Netease)   (QQ Music)
    :13000      :13300

项目结构

qq-bot/
├── docker-compose.yml
├── bot/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── .env                      # NoneBot 配置 + NETEASE_COOKIE
│   ├── bot.py                    # NoneBot 入口
│   └── plugins/
│       ├── at_bot.py             # @机器人交互拦截（优先级 1）
│       ├── help_registry.py      # 帮助信息注册表
│       ├── help.py               # 统一帮助插件
│       ├── music.py              # 点歌（网易云 + QQ 音乐）
│       ├── music_extra.py        # 歌词/每日一歌/猜歌
│       ├── idiom_chain.py        # 成语接龙（内置 300+ 成语）
│       ├── weather.py            # 天气查询（wttr.in）
│       ├── quote.py              # 一言（hitokoto.cn）
│       ├── fortune.py            # 抽签（内置签文）
│       ├── choose.py             # 选择困难症
│       ├── daily_lang.py         # 每日英语/日语（内置语料）
│       ├── image.py              # 美图（多数据源自动切换）
│       └── db.py                 # SQLite 数据库
└── qqmusicapi/
    ├── Dockerfile
    ├── package.json
    └── server.js                 # QQ 音乐 API 服务

技术栈

• Docker Compose — 服务编排
• NoneBot2 — Python 机器人框架（FastAPI + 事件驱动）
• nonebot-adapter-onebot — OneBot v11 协议适配
• httpx — 异步 HTTP 客户端
• aiosqlite — 异步 SQLite（排行/记录持久化）
• LLBot Desktop — QQ NT 宿主，无需签名服务器

License

MIT