前言¶
在 QQ 开放平台做机器人时，频道 @、C2C 私聊和群 @ 三类入口的 Intent、事件名和回复 API 并不一致；频道消息还带 <@!botid> 前缀，需要单独解析。若只靠零散文档拼代码，很容易漏开 Intent，或在 Python 3.10+ 上踩到「没有当前 event loop」的启动问题。下面介绍 SkillHub 上的 QQBot开发指南（@user_e7c8a23d/qqbot-messaging）：把 qq-botpy 的三种场景、定时推送和可运行模板整理成 Agent 可遵循的 SKILL.md，便于在对话里直接生成或改机器人项目。
这是什么¶
QQBot开发指南 是社区来源（community）的编程类 Skill，坐标 @user_e7c8a23d/qqbot-messaging，当前版本 1.0.0，由发布者 user_e7c8a23d 维护。SkillHub 分类为 dev-programming，标签标明 requires_api_key=true（需配置 QQ 机器人 appid / secret）。
它定位为 QQ 机器人消息收发框架说明：底层基于腾讯 qq-botpy SDK，覆盖频道 @、C2C 私聊、群 @ 的收发模式，并提供定时推送循环、启动片段，以及 scripts/bot_template.py 完整示例。
核心功能¶
以下能力均来自 Skill 自带的 SKILL.md 与脚本，安装后 Agent 会按其中约定协助开发。
三种消息场景¶
| 场景 | Intent | 事件 | 消息类型 |
|---|---|---|---|
| 频道 @ | public_guild_messages=True |
on_at_message_create |
Message |
| C2C 私聊 | public_messages=True |
on_c2c_message_create |
C2CMessage |
| 群 @ | public_messages=True |
on_group_at_message_create |
GroupMessage |
要点：
- C2C 与群消息共用
public_messages=True，可在同一 Bot 上同时监听。 - 频道回复常用
await message.reply(content="...")；C2C / 群需走对应post_c2c_message/post_group_message，并带上msg_id等参数（详见 Skill 内表格）。 - 频道指令解析需去掉 @ 前缀；Skill 提供
scripts/bot_utils.py中的parse_cmd()，模板里也有同名实现。
定时推送¶
用 asyncio.create_task() 挂后台协程，循环内 await asyncio.sleep(seconds)；取消任务时 task.cancel()，循环内捕获 asyncio.CancelledError 退出。bot_template.py 中为三类场景分别维护订阅字典与 PUSH_INTERVAL（默认 3600 秒），可作为「开始订阅 / 取消订阅」类业务的起点。
启动与运行环境¶
Skill 明确要求 Python 3.10+ 在 client.run() 前显式创建事件循环：
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
intents = botpy.Intents(public_guild_messages=True, public_messages=True)
client = MyBot(intents=intents)
client.run(appid=config["appid"], secret=config["secret"])
业务依赖安装：
pip install qq-botpy
项目侧配置 config.yaml：
appid: "YOUR_APPID"
secret: "YOUR_SECRET"
附带脚本¶
scripts/bot_template.py：三种处理器 + 定时推送的可运行模板；复制到项目后实现handle_command()/get_push_content()即可扩展业务。scripts/bot_utils.py：parse_cmd()与通用SubscriptionManager。
Skill 内 FAQ 还整理了收不到消息（Intent）、发消息失败（被动 msg_id 过期、主动消息权限）等常见原因，便于 Agent 对照排查。
安装与启用¶
Skill 遵循通用 SKILL.md 格式。在 SkillHub 页面给出的方式是：让 AI 按 SkillHub 安装说明 安装坐标 @user_e7c8a23d/qqbot-messaging。
若本机已安装 skillhub CLI，可将 Skill 装到当前 Agent 的 skills 目录（必须使用 --dir，否则默认 ./skills/ 可能不会被识别）：
command -v skillhub && skillhub --version
未安装 CLI 时，可按官方文档执行完整安装（节选）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装本 Skill 示例（将 <skills 目录> 换成你使用的客户端路径）：
skillhub install @user_e7c8a23d/qqbot-messaging --dir <skills 目录>
常见客户端 skills 目录（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
安装完成后重启或刷新 Agent，使其加载新 Skill。对话中描述「开发 QQ 机器人」「处理频道/群/私聊消息」「定时推送」等需求时，Agent 应优先引用该 Skill 中的场景表与模板。
典型用法¶
经过上面的安装，可以按 Skill 文档从模板落地一个最小可运行 Bot。
1. 准备配置与依赖
在项目目录创建 config.yaml 并填入开放平台申请的 appid、secret，执行 pip install qq-botpy。
2. 以模板为起点
将 Skill 内的 scripts/bot_template.py 复制到项目（或让 Agent 按该文件结构生成代码），保留三类 on_* 处理器与订阅逻辑，在 handle_command() 中实现指令分支，例如 Skill 自带的示例语义：
def handle_command(cmd: str) -> str | None:
if "查询" in cmd or "行情" in cmd:
return "这里返回你的业务数据"
return None
3. 启动
在文件末尾按 Skill 要求设置 loop 与 Intents，再 python bot_template.py 运行。
频道场景下，入站内容需经 parse_cmd() 再交给 handle_command()；C2C / 群可直接使用原文本。需要定时推送时，沿用模板中的 asyncio.create_task 与 get_push_content()，并注意 Skill FAQ：被动回复依赖的 msg_id 有效期短，长周期推送可能需要主动消息权限或及时更新 msg_id。
适用场景与注意¶
适合谁
- 已在 QQ 开放平台创建机器人，需要用 qq-botpy 统一处理频道、私聊、群 @ 的开发者。
- 希望由 Cursor / Claude Code 等 Agent 按固定模式生成 Bot 骨架、改 Intent 或补定时推送逻辑的团队。
限制与注意
- 必须配置有效的
appid/secret（requires_api_key=true）；密钥不要提交到仓库。 - Skill 聚焦消息收发与推送模式，不包含开放平台审核、沙箱开通等运营流程；权限与能力以 QQ 开放平台当前规则为准。
- Python 3.10+ 务必按 Skill 写法创建 event loop；三类场景 Intent 漏配会导致「收不到消息」。
- SkillHub 统计（截至页面信息）：评分 100000，下载约 1101 次，安装 15 次；社区 Skill，升级前可在 SkillHub 核对版本号。
结尾¶
QQBot开发指南 把 qq-botpy 的三类消息场景、配置字段、启动片段和可运行模板收敛进一份 SKILL.md，适合作为 Agent 侧开发 QQ 机器人的参照。需要安装或查看说明时，可打开 SkillHub 页面：
- https://www.skillhub.cn/skills/user_e7c8a23d/qqbot-messaging
- https://api.skillhub.cn/user_e7c8a23d/qqbot-messaging
