如何用Aide编写QQ机器人？

第一部分：核心概念与准备工作

QQ 机器人的工作原理

一个 QQ 机器人本质上是一个程序，它通过 QQ 官方提供的接口（协议）连接到 QQ 服务器，从而能够：

• 接收消息：监听用户发送给它的私聊消息或群聊消息。
• 发送消息：向指定用户或群聊回复消息。
• 执行操作：例如踢人、禁言、修改群资料等。

你的 Python 程序就是机器人的“大脑”，而“眼睛”和“嘴巴”就是负责连接 QQ 服务器的库。

技术选型

我们需要两个核心组件：

• QQ 协议库：用于与 QQ 服务器通信。

  • 推荐 nonebot2：这是目前 Python 生态中最流行、功能最强大、社区最活跃的 QQ 机器人框架，它基于 asyncio，性能高，且支持多种适配器（连接方式）。
  • 备选 go-cqhttp：它本身是一个独立的程序，可以作为 QQ 协议的“桥梁”，你的 Python 机器人通过 HTTP API 与 go-cqhttp 通信，这种方式更稳定，因为它不依赖 Python 库去解析复杂的 QQ 协议。
  • 对于新手和绝大多数场景,强烈推荐 nonebot2，它集成了适配器，开箱即用。

• AI 模型/服务：作为机器人的“大脑”。

  
  （图片来源网络，侵删）
  • OpenAI API (GPT-3.5/4)：效果最好，理解能力和生成能力最强，但有成本。
  • 国内大模型 API (如文心一言、讯飞星火、通义千问等)：对中文优化好，访问速度快，通常有免费额度。
  • 本地部署模型 (如 LLaMA, ChatGLM)：完全免费，数据私密，但对硬件要求高，配置复杂。
  • 从易用性和效果出发，推荐使用国内大模型 API，本教程将以调用 文心一言 API 为例，因为它与 QQ 生态结合紧密。

准备工作

1. Python 环境：确保你的电脑上安装了 Python 3.8 或更高版本。
2. 代码编辑器：如 VS Code。
3. 一个 QQ 号码：这个号码将作为你的机器人账号。
4. 获取 AI API Key：
   • 注册并登录 百度千帆大模型平台。
   • 创建一个新应用,获取 API Key 和 Secret Key，这两个密钥是调用文心一言服务的凭证。

第二部分：使用 nonebot2 搭建基础机器人

我们将分步进行,先让机器人能跑起来并回复消息，然后再接入 AI。

步骤 1：创建项目并安装 nonebot2

1. 创建一个新的文件夹作为你的机器人项目目录,my_qq_bot。
2. 在终端中进入该目录,并创建一个虚拟环境（推荐）：

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # macOS / Linux
   source venv/bin/activate

3. 安装 nonebot2：

   pip install nonebot2

步骤 2：编写基础代码

在你的项目根目录 my_qq_bot 下，创建一个名为 bot.py 的文件，并输入以下代码：

# bot.py
import nonebot
from nonebot import on_command
from nonebot.adapters.onebot.v11 import Message, MessageSegment
# 初始化 nonebot
bot = nonebot.get_bot()
# 定义一个简单的命令，当用户发送 "/echo hello" 时触发
echo = on_command("echo", aliases={"复读"})
@echo.handle()
async def handle_echo(bot, event: nonebot.Event):
    # 获取用户发送的命令内容（去掉 "/echo " 或 "/复读 "）
    args = str(event.get_message()).strip()
    # 回复用户
    await echo.send(Message(args))
# 定义一个简单的问候命令
hi = on_command("hi")
@hi.handle()
async def handle_hi(bot, event: nonebot.Event):
    await hi.send("你好！我是一个测试机器人。")
if __name__ == "__main__":
    # 运行机器人
    nonebot.run(app="bot.py")

步骤 3：配置并运行机器人

nonebot2 需要一个配置文件来指定连接方式，我们使用 fastapi 适配器，它可以通过 http 方式连接 go-cqhttp，也可以直接使用 mirai 协议，这里我们使用最简单的方式：让 nonebot2 启动一个内置的 HTTP 服务器，然后通过 http 协议连接。

1. 在项目根目录创建 .env 文件（注意文件名以点开头）：

   
   （图片来源网络，侵删）

   # .env
   # 这里先不填，我们使用命令行参数启动

2. 获取一个登录器：nonebot2 本身不处理登录，你需要一个工具来获取一个 QQ号 的 session key，最简单的方式是使用 nb-cli 自带的登录功能。

3. 使用 nb-cli 初始化项目并运行：

   # 在项目根目录执行
   nb run

   首次运行时,它会提示你进行配置，并引导你使用一个 QQ 号扫码登录，登录成功后，它会自动生成一个 .env 文件，里面包含了 session_key。

4. 再次运行 nb run，你的机器人就启动了！现在你可以用这个 QQ 号给机器人发 /echo hello 或 /hi，它应该会回复你。

至此,一个基础的、可以处理命令的 QQ 机器人已经搭建完成。

第三部分：接入 AI 大模型（文心一言）

我们让机器人变得“聪明”起来。

步骤 1：安装 AI 相关依赖

我们需要一个库来调用文心一言的 API。nonebot-plugin-ai 是一个现成的插件，但为了让你更好地理解原理，我们手动实现一个简单的 AI 对话功能。

安装 requests 库：

pip install requests

步骤 2：编写 AI 对话逻辑

在项目根目录创建一个 ai_utils.py 文件，用于封装调用文心一言 API 的函数。

# ai_utils.py
import requests
import json
# 替换成你自己的 API Key 和 Secret Key
API_KEY = "你的API_Key"
SECRET_KEY = "你的Secret_Key"
def get_wenxin_access_token():
    """
    获取文心一言的 Access Token
    """
    url = f"https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id={API_KEY}&client_secret={SECRET_KEY}"
    payload = ""
    headers = {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    return response.json().get("access_token")
def get_wenxin_response(prompt):
    """
    调用文心一言 API 获取回复
    """
    access_token = get_wenxin_access_token()
    if not access_token:
        return "无法获取访问令牌，请检查 API Key 和 Secret Key。"
    url = f"https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions?access_token={access_token}"
    payload = json.dumps({
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    })
    headers = {
        'Content-Type': 'application/json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    result = response.json()
    # 处理可能的错误
    if "error_code" in result:
        return f"AI 出错了: {result.get('error_msg', '未知错误')}"
    return result.get("result", "我没有得到有效回复。")

步骤 3：将 AI 功能集成到机器人中

修改你的 bot.py 文件，添加一个用于闲聊的命令。

# bot.py (修改后的完整代码)
import nonebot
from nonebot import on_command
from nonebot.adapters.onebot.v11 import Message
from nonebot import logger
# 导入我们刚刚编写的 AI 工具
from ai_utils import get_wenxin_response
# --- 之前的命令 ---
echo = on_command("echo", aliases={"复读"})
@echo.handle()
async def handle_echo(bot, event):
    args = str(event.get_message()).strip()
    await echo.send(Message(args))
hi = on_command("hi")
@hi.handle()
async def handle_hi(bot, event):
    await hi.send("你好！我是一个测试机器人。")
# --- 新增的 AI 对话命令 ---
# 使用 on_message 来监听所有消息，而不是特定命令
# 但更好的方式是添加一个前缀，避免误触发
chat = on_command("ai", aliases={"ai", "AI", "人工智能"})
@chat.handle()
async def handle_chat(bot, event):
    # 获取用户发送的消息，并去掉命令部分（如 "/ai "）
    user_input = str(event.get_message()).strip(chat.command[0] + " ")
    if not user_input:
        await chat.send("请输入你想问的问题哦~")
        return
    logger.info(f"收到用户问题: {user_input}")
    # 调用 AI 获取回复
    ai_response = get_wenxin_response(user_input)
    logger.info(f"AI 回复: {ai_response}")
    # 发送回复
    await chat.send(ai_response)
if __name__ == "__main__":
    nonebot.run(app="bot.py")

步骤 4：重启并测试

1. 在终端按 Ctrl+C 停止机器人。
2. 再次运行 nb run。
3. 你可以给机器人发送 /ai 你好，请介绍一下你自己，机器人应该会调用文心一言 API 并返回一个介绍性的回答。

第四部分：进阶与优化

基础的 AI 机器人已经完成，但离一个优秀的机器人还有距离。

使用插件（推荐）

nonebot2 强大的生态系统在于其丰富的插件，你不需要重复造轮子。

• nonebot-plugin-ai：集成了多个 AI 模型（包括文心一言、讯飞等）的插件，使用起来更方便、更稳定。
• nonebot-plugin-admin：管理员插件，可以方便地管理群，如踢人、禁言等。
• nonebot-plugin-mystool：米游社插件，可以帮你自动完成每日任务。

安装插件通常很简单：

nb plugin install nonebot-plugin-ai

然后在 bot.py 中加载它即可。

添加上下文记忆

上面的例子每次调用 AI 都是独立的，机器人无法记住之前的对话，要实现上下文记忆，我们需要在调用 API 时，把之前的对话历史也一并传过去。

修改 ai_utils.py 中的 get_wenxin_response 函数，让它接收一个消息历史列表。

# ai_utils.py (修改版)
# ... (get_wenxin_access_token 函数不变)
def get_wenxin_response(messages_history): # 参数改为消息历史列表
    access_token = get_wenxin_access_token()
    if not access_token:
        return "无法获取访问令牌。"
    url = f"https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions?access_token={access_token}"
    payload = json.dumps({
        "messages": messages_history # 直接传入整个历史
    })
    headers = {'Content-Type': 'application/json'}
    response = requests.request("POST", url, headers=headers, data=payload)
    result = response.json()
    if "error_code" in result:
        return f"AI 出错了: {result.get('error_msg', '未知错误')}"
    return result.get("result", "我没有得到有效回复。")

然后修改 bot.py，维护一个简单的会话字典。

# bot.py (修改版)
# ... (导入部分)
# 在全局创建一个字典来存储每个用户的对话历史
# key: user_id, value: list of messages
conversation_history = {}
chat = on_command("ai")
@chat.handle()
async def handle_chat(bot, event):
    user_id = event.user_id
    user_input = str(event.get_message()).strip(chat.command[0] + " ")
    if not user_input:
        await chat.send("请输入你想问的问题哦~")
        return
    # 初始化或获取该用户的对话历史
    if user_id not in conversation_history:
        conversation_history[user_id] = []
    # 将用户的新消息加入历史
    conversation_history[user_id].append({"role": "user", "content": user_input})
    # 调用 AI
    ai_response = get_wenxin_response(conversation_history[user_id])
    # 将 AI 的回复也加入历史，以便下次对话
    conversation_history[user_id].append({"role": "assistant", "content": ai_response})
    await chat.send(ai_response)
# ... (其他部分)

这样,机器人就能记住和你聊天的上下文了。

部署上线

开发完成后,你需要让机器人 24/7 在线运行。

• 个人电脑：简单，但电脑关机或断网机器人就会下线。
• 云服务器：推荐，购买一台便宜的云服务器（如阿里云、腾讯云、UCloud），在上面完成上述所有步骤，然后使用 screen 或 tmux 等工具保持程序运行，或者使用 PM2、systemd 等工具将其作为守护进程运行。

总结与注意事项

• 教程路线：nonebot2 基础 -> 调用 AI API -> 上下文记忆 -> 使用插件 -> 部署上线。
• 协议限制：QQ 官方对机器人协议有限制，例如频率限制、功能限制。nonebot2 和 go-cqhttp 会尽力处理，但也要注意规范使用，避免被封号。
• API 成本：调用 AI API 是有成本的，虽然免费额度够用，但如果机器人使用频繁，会产生费用，注意监控 API 调用情况。
• 安全：保护好你的 API Key 和 Secret Key，不要泄露。

这个教程为你提供了一个坚实的基础,你可以基于此进行扩展，例如添加图片识别、联网搜索、游戏娱乐等功能，打造一个独一无二的专属 QQ 机器人，祝你编码愉快！

标签： Aide QQ机器人编写教程 Aide框架开发QQ机器人指南 用Aide制作QQ机器人步骤