如何用aide开发QQ机器人？

99ANYc3cd6 机器人 2025-12-08 10

第一部分：核心概念理解

在开始动手之前，先了解几个关键概念,这会让你事半功倍。

（图片来源网络，侵删）

nonebot 框架：这是机器人的“大脑”和“骨架”，它负责接收消息、调用插件、发送回复，并管理整个机器人的生命周期，你只需要专注于编写具体的功能（插件）,而不用关心底层的通信协议。
OneBot 协议：这是一个标准化的通信协议，用于机器人与客户端（如 QQ）之间的交互。nonebot 遵循 OneBot 协议，这意味着你可以使用不同的 Adapter（适配器） 来连接不同的平台，QQ、微信、Discord 等，我们这里主要使用 go-cqhttp 作为 QQ 的适配器。
Plugin（插件）：这是机器人的“功能模块”。nonebot 的核心思想就是“一切皆插件”，你可以把不同的功能（如天气查询、群管、游戏等）写成独立的插件，然后加载到机器人中,这种设计使得机器人非常易于扩展和维护。
Driver（驱动）：nonebot 的运行核心，负责启动和管理整个应用，包括加载配置、插件和适配器。
（图片来源网络，侵删）

第二部分：环境准备

在开始编码之前,请确保你的电脑上已安装以下软件：

Python 3.8+：推荐使用 Python 3.9 或更高版本，你可以从 Python 官网下载并安装，安装时请务必勾选 "Add Python to PATH"。
Git：用于从代码仓库下载项目，你可以从 Git 官网下载安装。
代码编辑器：强烈推荐使用 Visual Studio Code，它对 Python 开发有非常好的支持。
（图片来源网络，侵删）

第三部分：详细步骤（从零到一）

我们将按照以下步骤进行：

创建并配置 nonebot 项目
配置 go-cqhttp 连接 QQ
编写第一个插件
启动机器人并测试

步骤 1：创建并配置 `nonebot` 项目

打开你的终端（命令提示符、PowerShell 或终端）,执行以下命令：

# 创建一个新文件夹作为你的机器人项目目录
mkdir my-qq-bot
cd my-qq-bot
# 使用 nb 命令（nonebot 的官方命令行工具）来创建项目
nb create

在 nb create 的交互式界面中,进行如下选择：

选择项目模板: 选择 2 (Advanced)，即高级模板，这个模板包含了更多配置选项,适合深入学习。
选择适配器: 选择 1 (OneBot V11)，这是目前最主流的 QQ 机器人协议。
选择平台协议: 选择 1 (QQ)。
选择驱动: 选择 1 (FastAPI)。
选择包管理器: 选择 1 (pip)。

命令执行完毕后,你的项目目录结构会是这样：

my-qq-bot/
├── .env                  # 环境变量配置文件
├── .env.example         # 环境变量模板文件
├── .gitignore           # Git 忽略文件
├── bot.py               # 机器人主入口文件
├── pyproject.toml       # 项目依赖和配置文件
├── nb-cli.py            # nb 命令行工具
├── README.md            # 项目说明文档
└── src/                 # 源代码目录
    └── bot/
        ├── __init__.py
        └── plugins/     # 插件目录
            └── ...

步骤 2：配置 `go-cqhttp` 连接 QQ

nonebot 本身不直接连接 QQ，而是通过一个叫 go-cqhttp 的中间程序来连接。

下载 go-cqhttp：
- 访问 go-cqhttp 的 GitHub Releases 页面。
- 下载对应你操作系统的最新版本（如 go-cqhttp-windows-amd64.zip）。
- 解压到你喜欢的位置，D:\go-cqhttp。
首次运行获取 Uin：
- 进入解压后的文件夹，双击运行 go-cqhttp.exe。
- 首次运行会提示你选择协议，请选择 手机扫码登录。
- 它会弹出一个二维码，使用你想要绑定的 QQ 号的微信扫码登录。
- 登录成功后，程序会在同目录下生成一个 config.yml 文件。请妥善保管你的账号，避免风控。
修改 config.yml：
- 用文本编辑器打开 config.yml 文件。
- 找到 servers 部分，确保 ws_reverse 的配置如下，这样 go-cqhttp 才能把收到的消息转发给我们的 nonebot 程序。
```
servers:
  - ws_reverse:
      access-token: "" # 可以留空
      universal: ws://127.0.0.1:8080 # 这里是 nonebot 默认监听的地址和端口
      reverse-url: "" # 不需要
```
- 保存并关闭 config.yml。
配置 .env 文件：
- 回到你的 my-qq-bot 项目目录，打开 .env 文件。
- 确保以下配置正确，这与 go-cqhttp 的配置对应。
```
# .env
HOST=127.0.0.1
PORT=8080
```

步骤 3：编写第一个插件

让我们来创建一个简单的插件，让机器人能回应“你好”。

创建插件文件：在 src/bot/plugins/ 目录下，新建一个 Python 文件，比如叫 hello.py。

编写插件代码：将以下代码复制到 hello.py 文件中。

# src/bot/plugins/hello.py
from nonebot import on_command
from nonebot.adapters.onebot.v11 import Message, MessageSegment
from nonebot.params import CommandArg
# on_command 装饰器用于定义一个命令型触发器
# "你好" 是命令关键字
# aliases=["hi"] 定义了命令的别名
hello_matcher = on_command("你好", aliases={"hi"})
# @hello_matcher.handle() 装饰器定义了当命令被触发时执行的函数
async def handle_first_receive(bot, event, args: Message = CommandArg()):
    # args 是命令后面的参数，"你好 张三"，args "张三"
    # args.extract_plain_text() 提取纯文本内容
    name = args.extract_plain_text()
    if name:
        # 如果有名字，就个性化回复
        await hello_matcher.send(f"你好，{name}！欢迎使用 nonebot！")
    else:
        # 如果没有名字，就回复默认消息
        await hello_matcher.send("你好！欢迎使用 nonebot！")
# 也可以用 on_message 来监听所有消息
from nonebot import on_message
from nonebot.adapters.onebot.v11 import MessageEvent
simple_matcher = on_message()
@simple_matcher.handle()
async def handle_simple_message(event: MessageEvent):
    # 如果消息是 "在吗"
    if event.get_plaintext() == "在吗":
        await simple_matcher.send("在的，有什么事吗？")

代码解释：

on_command("你好")：创建一个命令匹配器，当用户在群里或私聊发送 /你好 或 /hi 时,这个函数就会被触发。
CommandArg：这是一个参数，它会捕获命令后面的所有内容，作为 Message 对象传递给 args。
await hello_matcher.send(...)：用于向触发事件的人（群或个人）发送回复。

步骤 4：启动机器人并测试

启动 go-cqhttp：双击运行 go-cqhttp.exe，你会看到终端窗口，它会显示正在连接，并等待 nonebot 的连接。
启动 nonebot： 打开一个新的终端窗口，进入你的 my-qq-bot 项目目录,运行以下命令：
```
# 使用 nb run 命令启动机器人
nb run
```
如果一切顺利，你会看到 nonebot 启动的日志，显示成功连接到 go-cqhttp。
测试：
- 在你的 QQ 群里（或者私聊机器人），发送 /你好 或 /hi。
- 机器人应该会回复你 "你好！欢迎使用 nonebot！"
- 再发送 /你好小明，机器人应该会回复 "你好，小明！欢迎使用 nonebot！"
- 发送 "在吗"，机器人应该会回复 "在的，有什么事吗？"

恭喜！你已经成功创建并运行了你的第一个 QQ 机器人！

第四部分：进阶与探索

管理插件

nonebot 提供了强大的插件管理功能。

自动发现：nonebot 会自动加载 src/bot/plugins/ 目录下的所有插件。

手动加载：你可以在 bot.py 文件中手动导入插件,这样可以控制加载顺序。

# bot.py
from nonebot import load_plugins
# ... 其他代码 ...
# 加载指定目录下的插件
load_plugins("src/bot/plugins")

使用现成的插件

nonebot 最大的优势之一就是其丰富的插件生态,你不需要重复造轮子。

官方插件库：访问 nonebot 插件市场。
安装插件：插件通常以 pip 包的形式提供，在你的项目根目录下，修改 pyproject.toml 文件，在 [tool.nonebot] 部分添加 plugins。

安装一个“定时任务”插件 nonebot-plugin-apscheduler：
```
# pyproject.toml
[tool.nonebot]
plugin_dirs = ["src/bot/plugins"]
plugins = [
    "nonebot_plugin_apscheduler"
]
```
然后在终端运行 pip install nonebot-plugin-apscheduler 安装依赖。