🚀
极简优先
5 行代码即可启动机器人，无需理解复杂的协议细节。SDK 内部封装 Intent 计算、Token 管理、消息去重、签名验证等所有底层逻辑。
Skip to content
快速开始
环境要求
- Python 3.10+
- aiohttp >= 3.9.0
- pyyaml >= 6.0
安装
pip
pip install easybot-qq源码安装
git clone https://github.com/SaucePlum/easybot.git
cd easybot
pip install -r requirements.txt代码示例
点击查看完整示例
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()提示
公域机器人只会收到频道内 @它 的消息；请在频道中 @机器人进行测试。
推荐：加入最小错误处理
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()异步启动（自行管理事件循环）
import asyncio
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!")
asyncio.run(bot.start_async())注意
运行前请确保已在 QQ 开放平台 创建机器人应用并获取 AppID 和 AppSecret。
核心功能
🎯 多场景消息收发
支持 QQ 平台全场景消息交互，一套代码适配多种场景：
| 场景 | 说明 | 适用范围 |
|---|---|---|
| 频道消息 | 公域 @机器人消息、私域全量消息 | 频道社区 |
| 群聊消息 | 群内 @机器人消息 | QQ 群聊 |
| 单聊消息 | QQ 私聊消息 | 一对一聊天 |
| 频道私信 | 频道内私信对话 | 频道私信 |
🔌 完整 API 封装
全面覆盖 QQ 开放平台的 OpenAPI，提供类型安全的 Python 接口：
- 频道管理 - 创建、查询、修改子频道信息
- 成员管理 - 查询成员、踢出成员、设置禁言
- 身份组管理 - CRUD 操作、成员分配、权限配置
- 权限管理 - 用户权限、身份组权限的查询与修改
- 论坛系统 - 帖子、评论、回复事件监听
- 音频控制 - 播放、暂停、切歌等音频操作
- 消息管理 - 撤回消息、设置精华、获取引用
💬 会话管理系统
基于作用域的会话状态管理，轻松实现多轮对话：
- 五种作用域 -
USERGUILDCHANNELGROUPGLOBAL - 会话超时 - 自动回收过期会话，释放资源
- WaitFor 等待 - 实现多轮对话交互，等待用户输入
- 状态持久化 - 支持会话数据的持久化存储
查看 WaitFor 示例代码
from easybot import Bot, Model, Scope, WaitTimeoutError
bot = Bot(app_id="你的AppID", app_secret="你的AppSecret")
@bot.on_guild_message
async def on_message(msg: Model.GuildMessage) -> None:
with bot.session.bind(msg) as s:
await msg.reply("请输入你的名字：")
try:
# 等待用户回复（任意输入）
name_msg = await s.wait_for(
scopes=Scope.USER,
command=None, # None 表示接受任意输入
timeout=60 # 60秒超时
)
name = name_msg.treated_msg or name_msg.content
await msg.reply(f"你好，{name}！")
except WaitTimeoutError:
await msg.reply("等待超时，请重新开始。")
bot.start()🛡️ 生产级特性
- 自动重连 - WebSocket 断线自动重连，保证连接稳定
- 消息去重 - 内置消息去重机制，避免重复处理
- 签名验证 - Webhook 消息签名验证，确保安全
- Token 管理 - 自动刷新 Token，无需手动维护
- 错误处理 - 完善的异常体系，精准定位问题
- 日志系统 - 分级日志输出，便于调试和监控