EasyBot SDK 帮助文档

外观

快速入门

约 1935 字大约 6 分钟

本指南将帮助你在 5 分钟内完成 EasyBot SDK 的安装、配置并运行第一个 QQ 机器人。

一、环境准备

1.1 系统要求

项目要求
Python3.10 或更高版本
操作系统Windows / Linux / macOS
网络可访问 QQ 开放平台 API（api.sgroup.qq.com）

1.2 验证 Python 版本

python --version
# 输出应 >= Python 3.10.0

二、安装 SDK

2.1 从 PyPI 安装（推荐）

pip install easybot-qq

2.2 从源码安装

适用于需要修改源码或参与开发的场景：

# 克隆或下载项目到本地
git clone https://github.com/SaucePlum/easybot.git
cd easybot

# 安装依赖
pip install -r requirements.txt

2.3 验证安装

import easybot
print(easybot.__version__)  # 应输出: 1.0.0

三、获取机器人凭证

在使用 SDK 之前，你需要先在 QQ 开放平台创建机器人应用。

3.1 创建机器人应用

  1. 访问 QQ 开放平台 并登录
  2. 创建一个 机器人应用
  3. 在应用详情页获取：
    • AppID: 应用的唯一标识
    • AppSecret: 应用密钥（请妥善保管，勿泄露）

3.2 选择机器人类型

根据你的需求选择机器人类型：

类型说明适用场景
公域机器人只能接收频道内 @它的消息通用场景，可被任意频道添加
私域机器人可以接收频道全量消息、成员变更等更多事件需要监控所有消息的场景

注意：私域机器人需要手动授权添加到指定频道。

四、第一个机器人

4.1 最简示例

创建文件 bot.py，写入以下代码：

from easybot import Bot, Model

bot = Bot(app_id="你的AppID", app_secret="你的AppSecret")

@bot.on_guild_message
async def on_message(msg: Model.GuildMessage) -> None:
    await msg.reply("Hello World!")

bot.start()

公域机器人只会收到频道内 @它 的消息；请在频道中 @机器人进行测试。

4.1.1 最小错误处理（推荐）

在生产环境中，建议对消息发送失败做最小兜底，避免单次失败影响后续事件处理：

from easybot import Bot, Model, APIError, NetworkError, RateLimitError

bot = Bot(app_id="你的AppID", app_secret="你的AppSecret")

@bot.on_guild_message
async def on_message(msg: Model.GuildMessage) -> None:
    try:
        await msg.reply(f"你说：{msg.treated_msg}")
    except RateLimitError as e:
        bot.logger.warning(f"触发频率限制：{e}")
    except (APIError, NetworkError) as e:
        bot.logger.error(f"回复失败：{e}")

bot.start()

4.2 运行机器人

python bot.py

4.3 测试机器人

在 QQ 频道中 @你的机器人并发送任意消息，它将回复 "Hello World!"。

五、核心概念

5.1 Bot 实例

Bot 是机器人的核心类，负责连接管理和事件分发：

from easybot import Bot

bot = Bot(
    app_id="your_app_id",        # 机器人 AppID
    app_secret="your_app_secret", # 机器人密钥
    is_private=False,             # 是否私域机器人（默认 False）
    is_sandbox=False,             # 是否沙箱环境（默认 False）
    is_debug=False,               # 是否调试模式（默认 False）
)

5.2 事件处理器

使用装饰器注册事件处理器，务必为每个处理器指定正确的类型提示：

from easybot import Bot, Model

bot = Bot(app_id="...", app_secret="...")

# 频道@机器人消息
@bot.on_guild_message
async def on_guild(msg: Model.GuildMessage):
    await msg.reply("收到频道消息")

# 群聊@机器人消息
@bot.on_at_group_message
async def on_at_group(msg: Model.GroupMessage):
    await msg.reply("收到群聊@消息")

# 全量群聊消息
@bot.on_group_message
async def on_group(msg: Model.GroupMessage):
    await msg.reply("收到群聊消息")

# 单聊消息
@bot.on_c2c_message
async def on_c2c(msg: Model.C2CMessage):
    await msg.reply("收到私信")

# 频道私信
@bot.on_direct_message
async def on_dm(msg: Model.DirectMessage):
    await msg.reply("收到频道私信")

bot.start()

5.3 消息模型

所有消息模型继承自 MessageBase，提供统一的 reply() 方法：

@bot.on_guild_message
async def handle(msg: Model.GuildMessage):
    # 基本属性
    msg.id           # 消息 ID
    msg.content      # 原始内容
    msg.treated_msg  # 处理后的内容（去除@等）
    msg.author       # 发送者信息
    msg.timestamp    # 时间戳
    
    # 推荐：使用 reply() 快速回复
    await msg.reply("回复内容")
    await msg.reply("引用回复", reference=True)

5.4 命令系统

使用 @bot.on_command 注册命令处理器：

from easybot import Bot, CommandValidScenes, Model

bot = Bot(app_id="...", app_secret="...")

# 简单命令
@bot.on_command(command="ping", valid_scenes=CommandValidScenes.ALL)
async def ping(msg: Model.GuildMessage | Model.GroupMessage | Model.C2CMessage | Model.DirectMessage):
    await msg.reply("pong!")

# 多别名命令
@bot.on_command(command=["hello", "你好"], valid_scenes=CommandValidScenes.ALL)
async def hello(msg: Model.GuildMessage | Model.GroupMessage | Model.C2CMessage | Model.DirectMessage):
    await msg.reply("你好！")

bot.start()

5.5 生命周期事件

from easybot import Bot, Model

bot = Bot(app_id="...", app_secret="...")

@bot.on_startup
async def on_startup(event: Model.StartupEvent):
    bot.logger.info("机器人启动成功")

@bot.on_shutdown
async def on_shutdown(event: Model.ShutdownEvent):
    bot.logger.info("机器人正在关闭")

@bot.on_timer(interval=60)
async def on_timer(event: Model.TimerEvent):
    bot.logger.info("定时任务执行")

bot.start()

六、完整示例

以下是一个展示多种常用功能的完整示例：

from easybot import (
    Bot,
    Model,
    MessagesModel,
    CommandValidScenes,
)

# 初始化机器人
bot = Bot(
    app_id="你的AppID",
    app_secret="你的AppSecret",
    is_private=False,
    is_sandbox=True,
    is_debug=True,
)

# 预处理器：记录所有消息
@bot.before_command(valid_scenes=CommandValidScenes.ALL)
async def log_message(msg: Model.GuildMessage | Model.GroupMessage | Model.C2CMessage | Model.DirectMessage):
    bot.logger.info(f"收到消息: {msg.treated_msg}")

# 频道消息处理
@bot.on_guild_message
async def handle_guild_message(msg: Model.GuildMessage):
    content = msg.treated_msg.strip()

    if content == "ping":
        await msg.reply("Pong! 🏓")

    elif content.startswith("echo "):
        text = content[5:]
        await msg.reply(text)

    elif content == "embed":
        embed = MessagesModel.MessageEmbed(
            title="🎉 Embed 卡片",
            content=["第一行", "第二行"],
            prompt="点击查看",
        )
        await msg.reply(embed)

    elif content == "markdown":
        md = MessagesModel.MessageMarkdown(
            content="# 标题\n\n**粗体文字**"
        )
        await msg.reply(md)

# 命令处理
@bot.on_command(command="help", valid_scenes=CommandValidScenes.ALL)
async def help_cmd(msg: Model.GuildMessage | Model.GroupMessage | Model.C2CMessage | Model.DirectMessage):
    await msg.reply("可用命令：\n- ping\n- echo <文本>\n- embed\n- markdown\n- help")

# 生命周期事件
@bot.on_startup
async def on_startup(event: Model.StartupEvent):
    bot.logger.info("机器人已启动！")

@bot.on_timer(interval=300)
async def heartbeat(event: Model.TimerEvent):
    bot.logger.info(f"心跳检查 - 第 {event.tick_count} 次")

if __name__ == "__main__":
    bot.start()

七、连接协议选择

SDK 支持三种连接模式，根据你的部署场景选择：

7.1 WebSocket 模式（默认）

最常用的方式，SDK 主动连接 QQ 平台的 WebSocket Gateway：

from easybot import Bot, Proto

bot = Bot(
    app_id="xxx",
    app_secret="xxx",
    protocol=Proto.websocket(),  # 默认模式
)

适用场景：本地开发、服务器直连部署

7.2 Webhook 模式

SDK 启动 HTTP 服务端，QQ 平台主动推送事件：

from easybot import Bot, Proto

bot = Bot(
    app_id="xxx",
    app_secret="xxx",
    protocol=Proto.webhook(port=8080),
)

适用场景：有公网 IP、使用 nginx 反向代理、云函数部署

7.3 Remote Webhook 模式

通过远程中转服务器连接：

from easybot import Bot, Proto

bot = Bot(
    app_id="xxx",
    app_secret="xxx",
    protocol=Proto.remote_webhook(url="wss://your-server.com"),
)

适用场景：内网环境、需要通过中转服务器连接

八、运行与调试

8.1 启动方式

同步启动（阻塞主线程）：

bot.start()  # 阻塞运行，直到 Ctrl+C 停止

异步启动（自行管理事件循环）：

import asyncio

async def main():
    await bot.start_async()

asyncio.run(main())

8.2 日志查看

开启调试模式以查看更多信息：

bot = Bot(..., is_debug=True)

日志输出位置：

  • 控制台：彩色格式化输出
  • 文件：logs/{bot_id}/{日期}.log（按天轮转）

8.3 停止机器人

  • Ctrl+C：发送中断信号，优雅停止
  • 程序调用：bot.stop() 设置停止标志

九、常见问题

Q1: 提示 "Intent 计算错误"

确保你的机器人类型与注册的事件处理器匹配：

  • 公域机器人只能使用 @bot.on_guild_message
  • 私域机器人可以使用 @bot.on_guild_full_message 等更多事件

Q2: 消息发送失败

检查以下几点：

  1. AppID 和 AppSecret 是否正确
  2. 机器人是否已添加到频道/群聊
  3. 是否有发送消息的权限
  4. 网络是否能访问 QQ 开放平台 API

Q3: 如何测试机器人

推荐使用沙箱环境进行测试：

bot = Bot(
    app_id="...",
    app_secret="...",
    is_sandbox=True,  # 开启沙箱环境
)

十、下一步

恭喜你已经完成了 EasyBot 的快速入门！接下来可以：

深入学习

高级功能

获取帮助

更新日志

2026/5/22 13:02
查看所有更新日志
  • fcf88-feat: 添加全量群聊消息事件支持于
  • 30b8c-feat: 提升代码质量并优化文档示例于
  • a8177-feat(plugins): 支持插件热重载功能并优化命令查找逻辑于
  • v1.0.0于

📢 加入交流

QQ 官方机器人 Python SDK

👉 点击加入 EasyBotSDK 官方频道

一起交流讨论，获取最新更新