mirror of
https://github.com/snowy-yang/qqbotsdk.git
synced 2026-10-21 11:29:07 +00:00
snowy-yang
bcd69099b6
GUIDE/API 拆为 docs/guide/ 五页与 docs/api/ 七页，侧边栏分组折叠， 旧链接 alias 映射；安装改为 pip install qqbotsdk-py，README 加徽章； 删除 docs 分支同步工作流，pages.yml 直部署（自定义域名 CNAME 随产物带上）。
2.6 KiB
2.6 KiB
快速开始
从零开始接入 QQ 官方机器人：装包、配置、跑起第一个回声机器人。 事件处理细节见事件处理，收发消息的规则见收发消息。
接入准备
- 到 QQ 开放平台 注册开发者账号并创建机器人，拿到
AppID与AppSecret（即.env里的APPID/APPSECRET）。 - 确认机器人的可用场景，这决定了你能收哪些事件、发哪些消息：
- 群 / 单聊（v2 接口）：需要在开放平台开通对应能力，事件与消息接口均用 openid（
group_openid/user_openid），与用户的 QQ 号互不可见。 - 频道公域机器人：只能收
AT_MESSAGE_CREATE（@机器人才触发），发消息必须带msg_id被动回复。 - 频道私域机器人：可订阅
GUILD_MESSAGES（全量消息）与论坛事件，可主动发消息、撤回消息。
- 群 / 单聊（v2 接口）：需要在开放平台开通对应能力，事件与消息接口均用 openid（
安装
pip install qqbotsdk-py # 或
uv add qqbotsdk-py
导入名是 qqbotsdk（发行包名带 -py 后缀是因为 PyPI 上 qqbotsdk 与已有项目撞名）。要求 Python ≥ 3.12。
最小可跑示例
项目根目录放两个文件。
.env（SDK 启动时自动加载，缺失 APPID/APPSECRET 启动即报错）：
APPID=你的AppID
APPSECRET=你的AppSecret
intents.toml（事件订阅按分组开关，详见配置与订阅）：
GROUP_AND_C2C_EVENT = true
main.py：
from qqbotsdk import Bot
from qqbotsdk.api import BotApi
from qqbotsdk.payloads import GroupAtMessage
bot = Bot()
# handler 形参按标注注入：payload dataclass 与 BotApi 等组件可任意组合
@bot.on("GROUP_AT_MESSAGE_CREATE")
async def on_group_message(msg: GroupAtMessage, api: BotApi):
# 被动回复带 msg_id（5 分钟内有效，多次回复递增 msg_seq）；失败抛 ApiError
await api.post_group_message(
msg.group_openid,
content=f"你说：{msg.content}",
msg_id=msg.id,
)
if __name__ == "__main__":
bot.run()
运行：
uv run python main.py
把机器人拉进测试群，@它说句话，就会收到回声。