本文最后更新于10 天前，其中的信息可能已经过时，如有错误请发送邮件到chengkun257@gmail.com

一、项目目标

本项目实现一个QQ群自动化管理机器人，主要功能：

✅ 新生常见问题自动回答（本地词库）
✅ 未命中问题记录（转人工）
✅ 广告检测（关键词 + 规则）
✅ 自动撤回违规消息
✅ 三次违规自动踢出群聊
✅ 数据本地持久化（JSON）

二、整体架构设计

QQ群 → QQ客户端 → NapCat → OneBot协议 → NoneBot → 插件系统 → 业务逻辑

🧩 各组件职责

组件	作用
QQ客户端	实际收发消息
NapCat	协议桥接（QQ → OneBot）
OneBot	标准化消息接口
NoneBot	Python机器人框架
插件系统	业务逻辑实现

🧠 为什么这样设计？

👉 QQ协议本身不可直接调用
👉 NapCat 充当“翻译官”
👉 NoneBot 负责“逻辑大脑”

三、环境准备

1️⃣ Python环境

2️⃣ 创建 NoneBot 项目

pip install nb-cli
nb create

选择：

适配器：OneBot V11
驱动：FastAPI

启动项目

nb run --reload

成功日志：

Uvicorn running on http://127.0.0.1:8080

四、NapCat 安装与配置

1️⃣ 下载 NapCat

GitHub：

👉 NapCat Releases

下载：

NapCat.Shell.Windows.OneKey.zip

2️⃣ 启动 NapCat

进入：

NapCat.xxx.Shell

运行：

napcat.bat

3️⃣ 登录 QQ

日志会出现：

二维码解码URL

扫码登录即可。

五、NapCat WebUI 登录问题（重要坑）

访问：

http://127.0.0.1:6099

会提示：

请输入 token

❗问题原因

部分版本：

👉 不输出 token
👉 但默认开启认证

✅ 解决方案

修改：

napcat/config/webui.json

加入：

{
  "enableAuth": false
}

重启 NapCat。

六、连接 NoneBot（核心步骤）

WebUI 操作

进入：

👉 网络配置 → 新建

❗必须选择：

Websocket客户端

填写：

ws://127.0.0.1:8080/onebot/v11/ws

❗不要填：

AccessToken（留空）

成功标志

NoneBot 输出：

Bot xxxx connected
connection open

七、插件系统（关键机制）

❗默认坑

plugin_dirs = []

👉 导致插件完全不加载

✅ 修改

[tool.nonebot]
plugin_dirs = ["plugins"]

插件目录结构

QQrobot/
├─ plugins/
│  └─ xxx.py

八、测试插件（打通链路）

from nonebot import on_message

test = on_message()

@test.handle()
async def _(event):
    if "测试机器人" in str(event.get_message()):
        await test.finish("我在线")

测试

群里发送：

测试机器人

回复：

我在线

👉 说明链路打通

九、系统设计（核心功能）

1️⃣ 本地词库答疑

设计思路

不是简单 equal 判断，而是：

👉 打分匹配系统

数据结构

[
  {
    "question": "报到时间",
    "aliases": ["什么时候报到"],
    "keywords": ["报到", "时间"],
    "answer": "请查看群公告"
  }
]

匹配策略

匹配类型	分值
question	+10
alias	+8
keyword	+3

优点

支持模糊匹配
抗表达差异
可扩展

2️⃣ 未命中转人工

设计目标

👉 所有没回答的问题记录下来

实现

save_handoff(user_id, group_id, message)

存储结构

[
  {
    "user_id": "...",
    "message": "...",
    "time": "..."
  }
]

3️⃣ 广告检测系统

核心思想

👉 关键词 + 权重评分

示例

[
  {"keyword": "兼职", "weight": 8},
  {"keyword": "加v", "weight": 15}
]

规则增强

手机号检测
URL检测
长数字检测
疑问句降权（防误杀）

判定逻辑

if score >= 40:
    判定为广告

4️⃣ 违规处理机制

策略

次数	行为
1	警告
2	禁言
3	踢出

实现

count = increase_violation_count()

if count == 1:
    警告
elif count == 2:
    禁言
elif count >= 3:
    踢人

十、项目结构设计（工程化）

D:\QQrobot\
├─ QQrobot\
│  ├─ plugins/
│  │  ├─ faq_bot.py
│  │  └─ moderator.py
│  ├─ services/
│  │  ├─ faq.py
│  │  ├─ ad_detect.py
│  │  └─ storage.py
│  ├─ data/
│  │  ├─ faq.json
│  │  ├─ violations.json
│  │  └─ ad_keywords.json
│  └─ pyproject.toml

十一、关键踩坑总结

❗1 插件不执行

原因：

plugin_dirs = []

❗2 WebUI登录不了

原因：

👉 没 token

解决：

enableAuth: false

❗3 WebSocket选错

错误：

Websocket服务器 ❌

正确：

Websocket客户端 ✅