Important
本项目是 tencent-connect/botpy 的非官方维护分支，不代表腾讯官方发行版。PyPI 上的 qq-botpy 仍是上游项目发布的包，不包含本 fork 的后续修改。
上游仓库长期未更新后，本项目依据机器人开放平台 API v2 文档，对 SDK 的协议实现进行了补充和修正。当前维护内容主要包括：
| 范围 | 本 fork 的补充 |
|---|---|
| OpenAPI | 默认使用 api.bot.qq.com，兼容 201/202 响应，并在异常中保留更完整的业务错误上下文 |
| WebSocket 网关 | 使用服务端下发的心跳周期，响应服务端主动心跳请求，并补充会话与网关字段 |
| 群与好友事件 | 支持全量群消息、群成员变化、机器人进出群、好友关系及主动消息授权状态等事件 |
| 群/C2C 消息 | 补充消息撤回、好友单聊流式消息、输入中状态、互动召回等 API v2 能力 |
| 文件能力 | 补充群与好友单聊的大文件分片上传接口及相关数据类型 |
| 数据模型与测试 | 补齐消息、互动、卡片、引用消息、授权状态等字段，并增加网关协议测试 |
部分接口属于平台内邀或需要单独申请权限，能否调用仍以机器人开放平台为准。本项目会尽量保持既有 botpy 使用方式，但新增字段和接口以当前 API v2 定义为准。
本 fork 暂未单独发布到 PyPI，请直接从 GitHub 安装。建议先创建虚拟环境：
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade "git+https://github.com/TbYangZ/botpy.git@master"Windows PowerShell 激活虚拟环境时使用：
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --upgrade "git+https://github.com/TbYangZ/botpy.git@master"如果需要参与开发，或希望项目立即使用本地修改，可以使用可编辑安装：
git clone https://github.com/TbYangZ/botpy.git
cd botpy
python -m pip install -e .更新本 fork 时，在源码目录执行：
git pull
python -m pip install --upgrade -e .兼容 Python 3.8 及以上版本。如果环境中已经安装过 PyPI 版 qq-botpy，上述命令会以相同的 Python 包名 botpy 安装本项目；建议在独立虚拟环境中使用，避免版本混用。
安装后仍然使用原项目的导入名称：
import botpy原机器人的老版本
qq-bot仍然可以使用，但新接口的支持会逐渐停止。本项目延续qq-botpy的接口设计，并针对 API v2 进行维护。
- OpenAPI 默认域名更新为
api.bot.qq.com，并完善201/202响应和业务错误上下文。 - WebSocket 使用服务端下发的心跳周期，并响应服务端主动心跳请求。
- 新增全量群消息、群成员变化和订阅消息授权状态事件。
- 新增群/单聊撤回、单聊流式消息、互动召回和大文件分片上传等 API v2 能力。
- 补齐消息场景、卡片、引用消息、互动反馈和授权等事件字段。
- 更新鉴权方式。 新版本通过AppID + AppSecret进行鉴权，需要使用者进行适配。AppSecret见QQ机器人开发设置页中的AppSecret字段。具体适配方式见示例 鉴权配置示例 鉴权传参接口变更示例
- 增加群和好友内发消息能力。可参考群内发消息示例 好友内发消息示例
- 增加群和好友内发送富媒体消息能力，目前支持图片、视频、语音类型。可参考 群内发富媒体消息示例 好友内发富媒体消息示例
Important
本维护版需要使用 asyncio.run() 启动机器人，并在异步入口中创建 Client。请不要再把 client.run() 作为新代码的启动方式；这种旧式写法依赖隐式事件循环，在较新的 Python 版本中可能无法正常创建客户端。
通过继承实现bot.Client, 实现自己的机器人Client
实现机器人相关事件的处理方法,如 on_at_message_create， 详细的事件监听列表，请参考 事件监听.md
如下，是定义机器人被@的后自动回复:
import botpy
from botpy.message import Message
class MyClient(botpy.Client):
async def on_at_message_create(self, message: Message):
await message.reply(content=f"机器人{self.robot.name}收到你的@消息了: {message.content}")注意:每个事件会下发具体的数据对象，如`message`相关事件是`message.Message`的对象 (部分事件透传了后台数据，暂未实现对象缓存)
设置机器人需要监听的事件通道，在异步入口中创建 Client，并通过 asyncio.run() 启动：
import asyncio
import os
import botpy
from botpy.message import Message
class MyClient(botpy.Client):
async def on_at_message_create(self, message: Message):
await self.api.post_message(channel_id=message.channel_id, content="content")
async def main():
intents = botpy.Intents(public_guild_messages=True)
client = MyClient(intents=intents)
async with client:
await client.start(
appid=os.environ["QQ_BOT_APP_ID"],
secret=os.environ["QQ_BOT_APP_SECRET"],
)
if __name__ == "__main__":
asyncio.run(main())请通过环境变量或其他安全配置方式提供 AppID 和 AppSecret，不要将凭据直接提交到代码仓库。
也可以通过预设置的类型，设置需要监听的事件通道
import botpy
intents = botpy.Intents.none()
intents.public_guild_messages=True如果要使用api方法，可以参考如下方式:
import botpy
from botpy.message import Message
class MyClient(botpy.Client):
async def on_at_message_create(self, message: Message):
await self.api.post_message(channel_id=message.channel_id, content="content")examples 目录下存放示例机器人，具体使用可参考Readme.md
Warning
examples/ 目录继承自上游项目，本次未对其中的示例代码进行改写。多数示例仍在同步上下文中创建 Client 并调用旧式 client.run()，主要用于展示事件回调和 API 调用，未体现本维护版要求的 asyncio.run() 启动方式；在较新的 Python 版本中直接照搬其启动部分可能失败。此外，这些示例尚未覆盖本 fork 新增的全部 API v2 事件和接口。新项目请以本 README 的“快速入门”为准。
examples/
.
├── README.md
├── config.example.yaml # 示例配置文件（需要修改为config.yaml）
├── demo_announce.py # 机器人公告API使用示例
├── demo_api_permission.py # 机器人授权查询API使用示例
├── demo_at_reply.py # 机器人at被动回复async示例
├── demo_at_reply_ark.py # 机器人at被动回复ark消息示例
├── demo_at_reply_embed.py # 机器人at被动回复embed消息示例
├── demo_at_reply_command.py # 机器人at被动使用Command指令装饰器回复消息示例
├── demo_at_reply_file_data.py # 机器人at被动回复本地图片消息示例
├── demo_at_reply_keyboard.py # 机器人at被动回复md带内嵌键盘的示例
├── demo_at_reply_markdown.py # 机器人at被动回复md消息示例
├── demo_at_reply_reference.py # 机器人at被动回复消息引用示例
├── demo_dms_reply.py # 机器人私信被动回复示例
├── demo_get_reaction_users.py # 机器人获取表情表态成员列表示例
├── demo_guild_member_event.py # 机器人频道成员变化事件示例
├── demo_interaction.py # 机器人互动事件示例（未启用）
├── demo_pins_message.py # 机器人消息置顶示例
├── demo_recall.py # 机器人消息撤回示例
├── demo_schedule.py # 机器人日程相关示例
pip install -r requirements.txt # 安装依赖的pip包
pre-commit install # 安装格式化代码的钩子代码库提供API接口测试和 websocket 的单测用例，位于 tests 目录中。如果需要自己运行，可以在 tests 目录重命名 .test.yaml 文件后添加自己的测试参数启动测试：
先确保已安装 pytest ：
pip install pytest然后在项目根目录下执行单测：
pytest感谢以下开发者对原版 botpy 作出的贡献：
本项目 fork 自腾讯维护的 tencent-connect/botpy。原项目版权信息继续保留：
Copyright (c) 2021 Tencent
原项目及本 fork 均依据 MIT License 使用、修改与分发。完整版权声明和许可条款请参阅仓库根目录的 LICENSE 文件。本 fork 的维护不改变原项目的版权归属，也不表示获得腾讯官方背书。
以下为原项目提供的QQ 频道开发者社区入口：
