QQBot 快速上手5分钟跑通你的第一个QQ自动回复机器人【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot如果你管理着几个QQ群一定经历过这样的时刻同样的怎么进群今天打卡了吗被问了一百遍你复制粘贴到手酸说好每晚十点发提醒结果一忙就忘半夜想看服务器状态还得爬起来开电脑。QQBot 就是来解决这类问题的——它是一款基于腾讯 SmartQQ 协议的 Python 开源框架用最直白的话说让你用几行代码把 QQ 里的自动回复、定时提醒、消息监控全部包办。这个项目跨平台Linux / Windows / macOS支持插件化扩展对新手友好到写一个函数就能上岗。一、QQBot 是什么把 QQ 变成你的代码遥控器你可以把 QQBot 想象成一位24 小时不喊累的在线接线员它替你登录一个 QQ 号帮你盯着每一条进来的消息然后按你写好的规则决定该回什么、该发给谁、什么时候发。它和普通脚本最大的区别在于可交互——不是一次性跑完就结束而是持续在线、持续监听、持续响应。核心能力可以用一张表看清能力模块具体做什么典型场景消息收/发监听好友、群、讨论组消息并自动回复客服机器人、群聊管理定时任务通过qqbotsched按 cron 语法触发动作打卡提醒、每日汇报联系人管理查询/搜索好友、群、成员获取资料成员统计、群管理插件扩展热加载/卸载功能模块互不干扰个性化功能开发外部接口命令行工具 本地 HTTP APIWeb 前端联动、远程操作值得说明的是QQBot 官方并未提供现成聊天 AI它是一个框架——你提供逻辑它负责跑腿。也正因如此它的能力边界由你的想象力决定。二、理解 QQBot 的核心思想一切皆回调上手前先花 30 秒理解这个框架最关键的机制后面会事半功倍。QQBot 把程序运行时发生的各种事件统一抽象成了9 种回调函数你只要在插件文件里写好这些函数框架就会在对应时机自动调用它们onInit插件初始化onQrcode拿到登录二维码onStartupComplete启动完成onQQMessage收到新消息最常用onInterval每 5 分钟触发一次onUpdate联系人列表更新onPlug/onUnplug插件被加载/卸载onExit程序退出其中onQQMessage是你最常用的入口。函数名和参数必须原样保留框架靠签名识别它们——这是新手最容易踩的坑。所有回调的完整示例在qqbot/plugins/sampleslots.py里建议先通读一遍。三、5分钟快速上手从空目录到第一个机器人第 1 步获取代码并安装依赖项目要求 Python 2.7 或 3.4用 pip 安装依赖即可git clone https://gitcode.com/gh_mirrors/qq/qqbot cd qqbot pip install . 想装在隔离环境避免污染系统 Python项目仓库里提供了qqbot-venv.sh脚本可直接创建独立虚拟环境。第 2 步启动主程序并扫码登录qqbot程序启动后会自动弹出二维码Linux 需要系统装有 gvfs-open 或 shotwell用手机 QQ 扫码授权即可。登录信息会保存在本地下次用qqbot -q qq号码启动可免扫码快速登录注意保存的凭证约 2 天后过期。第 3 步写你的第一个插件新建文件sample.py内容如下def onQQMessage(bot, contact, member, content): if content -hello: bot.SendTo(contact, 你好我是QQ机器人) elif content -stop: bot.SendTo(contact, QQ机器人已关闭) bot.Stop()这段代码让机器人遇到-hello就打招呼收到-stop就自动下线。把文件放到~/.qqbot-tmp/plugins/目录然后在另一个终端窗口执行qq plug sample至此你的第一个 QQ 自动回复机器人已经上线 。想卸载就执行qq unplug sample整个过程无需重启主程序——这就是插件热插拔。四、3个拿来即用的实战模板掌握了入口函数剩下的就是写业务逻辑。下面三个模板都摘自项目官方文档与示例可以直接改改套用。模板一群内被友好应答QQBot 会智能识别有人你消息中带ME标记就说明本机器人被点名了这时候才回应避免骚扰群友def onQQMessage(bot, contact, member, content): if ME in content: bot.SendTo(contact, member.name 艾特我干嘛呢)模板二定时群发提醒11:55 和 17:55 自动开饭广播定时任务用qqbotsched装饰器参数沿用 Unix crontab 语法支持hour、minute、day_of_week等 11 个字段from qqbot import qqbotsched qqbotsched(hour11,17, minute55) def mytask(bot): gl bot.List(group, 456班) if gl is not None: for group in gl: bot.SendTo(group, 同志们开饭啦啦啦啦啦啦)⏰ 这是它内部对 apscheduler 的轻量封装——想每 5 分钟跑一次写minute*/5想工作日跑写day_of_weekmon-fri。模板三用命令行远程指挥qq命令工具可以让你在另一个终端直接操控机器人连代码都不用写qq send buddy jack 你好 # 给好友 jack 发消息 qq list group 机器人测试 # 搜索名含机器人测试的群 qq list group-member 456班 # 查看群成员 qq send group 198班 大家好 # 给群发消息配套的 HTTP 接口默认监听127.0.0.1:8188让 Web 前端也能调用同样的能力比如通过send/buddy/jack/hello这类 URL 发送消息。五、它内部是怎么跑的一张图看懂运行机制QQBot 的架构是典型的主线程管生命周期子线程干杂活设计清晰值得借鉴程序的生命周期可以拆成四个阶段登录阶段读取配置 → 加载插件触发onInit→ 获取二维码触发onQrcode→ 等待扫码授权。启动阶段登录成功后可选拉取联系人列表触发onStartupComplete随后同时拉起 4 个子线程——消息轮询线程、每 5 分钟的 interval 线程、本地 term-server 线程8188 端口、定时调度线程。运行阶段主循环持续运转消息一到就触发onQQMessage定时到点就执行qqbotsched任务所有插件回调都在主线程依次串行执行——所以不用担心全局变量线程安全但回调里也千万别做耗时操作否则会阻塞整个程序。退出阶段手动停止、重启或登录过期时触发onExit父进程再根据退出码决定是否自动重启。值得一提的是框架内置了掉线自动重启restartOnOffline和定时重启插件qqbot/plugins/schedrestart.py配合邮箱接收二维码能让机器人长期稳定在线。六、新手避坑清单都是血泪经验回调签名不能改onQQMessage(bot, contact, member, content)四个参数一个都不能少、名字不能换否则函数不会被识别。不是所有联系人能发消息bot.SendTo只能发给好友/群/讨论组不能发给群成员对象member。判断消息类型看contact.ctype取值为buddy/group/discuss分别对应好友消息、群消息、讨论组消息。别在回调里调外部命令绝对不要用os.system(qq send ...)去操作自己这个 QQ会和主程序形成死锁请直接用bot.SendTo等内置接口。配置按层级覆盖根配置 → 默认配置 → 用户配置 → 命令行参数优先级依次递增。改了配置不生效多半是你没按qqbot -u 你的用户名启动。文件名避开关键字别把自己的脚本命名为qqbot.py、sys.py也别在代码里用qqbot/sys/time做变量名很容易和库冲突。重复发消息的处理SendTo有个resendOn1202参数默认True设成False可避免偶发重复发送代价是可能漏发按需取舍。七、常见问题速查Q1二维码弹不出来怎么办AQQBot 一共提供 4 种二维码显示模式GUI 弹窗默认、邮箱模式配置mailAccount和mailAuthCode推荐 QQ 邮箱、服务器模式需公网 IP、文本模式cmdQrcode设为true需装 pillow 和 wcwidth。远程服务器上用邮箱模式最省心。Q2如何稳定长期在线ASmartQQ 协议限制下登录凭证 1~2 天必失效需重新扫码。实操方案是开启邮箱模式 restartOnOffline自动重启 加载schedrestart插件每天固定时间重启一次比如每天 8:00用手机顺手扫一下即可。Q3怎么拿到消息发送者的 QQ 号A用onQQMessage的第 2、3 个参数contact.qq/contact.name/contact.mark等属性都在联系人对象上各字段含义详见qcontact-attr.md。注意member在好友消息时为None。Q4能发图片、文件、语音吗A不能。SmartQQ 协议本身不支持发送图片、文件、音频及 XML 卡片消息群内也无法真正 其他成员对方只会收到纯文本。这是协议层面的硬限制不是配置能解决的。八、给新手的 3 阶段学习路线入门通读根目录README.MD弄懂基本概念 → 跑通qqbot/plugins/sample.py示例 → 把qqbot/plugins/sampleslots.py里的 9 种回调都打印一遍日志感受触发时机。进阶精读README.MD中bot.List / Update / SendTo三个核心接口的返回值语义 → 用qqbotsched写出你的第一个定时任务 → 研究qqbot/plugins/schedrestart.py的插件写法。实战在plugins-in-dev/目录看社区插件如patchfetch.py如何覆写联系人获取逻辑→ 参考配置文件写多用户配置 → 尝试用 HTTP API 给你的机器人做一个 Web 控制台。写在最后关于项目现状的诚实说明需要向读者说明一个事实QQBot 基于腾讯 SmartQQ 协议构建而该官方接口已于 2019 年停止服务因此本项目目前已无法实际登录使用项目也早已停止维护项目作者在 README 顶部明确标注了这一点。文章中的示例代码与运行机制描述均来自项目真实源码与官方文档。尽管如此QQBot 依然是学习 Python 机器人框架设计的一流教材它的插件热加载机制、回调事件模型、定时任务封装、多线程生命周期管理至今仍有很高的参考价值。如果你正在设计自己的消息机器人或自动化框架读它的源码会收获颇多。核心资源导航官方文档README.MD最完整的接口说明务必先读最简单示例qqbot/plugins/sample.py一个文件学会自动回复全部回调示例qqbot/plugins/sampleslots.py9 种回调逐个演示定时重启插件qqbot/plugins/schedrestart.py开发中插件plugins-in-dev/含patchfetch.py等高阶玩法表情关键词表qqbot/facemap.py消息里可嵌入/可爱等表情联系人属性说明qcontact-attr.md常见问题汇总faq.md看懂架构、跑通示例、再动手写一个属于自己的回调——自动化带来的爽感只有试过才知道。开始吧 【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
QQBot 快速上手：5分钟跑通你的第一个QQ自动回复机器人
QQBot 快速上手5分钟跑通你的第一个QQ自动回复机器人【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot如果你管理着几个QQ群一定经历过这样的时刻同样的怎么进群今天打卡了吗被问了一百遍你复制粘贴到手酸说好每晚十点发提醒结果一忙就忘半夜想看服务器状态还得爬起来开电脑。QQBot 就是来解决这类问题的——它是一款基于腾讯 SmartQQ 协议的 Python 开源框架用最直白的话说让你用几行代码把 QQ 里的自动回复、定时提醒、消息监控全部包办。这个项目跨平台Linux / Windows / macOS支持插件化扩展对新手友好到写一个函数就能上岗。一、QQBot 是什么把 QQ 变成你的代码遥控器你可以把 QQBot 想象成一位24 小时不喊累的在线接线员它替你登录一个 QQ 号帮你盯着每一条进来的消息然后按你写好的规则决定该回什么、该发给谁、什么时候发。它和普通脚本最大的区别在于可交互——不是一次性跑完就结束而是持续在线、持续监听、持续响应。核心能力可以用一张表看清能力模块具体做什么典型场景消息收/发监听好友、群、讨论组消息并自动回复客服机器人、群聊管理定时任务通过qqbotsched按 cron 语法触发动作打卡提醒、每日汇报联系人管理查询/搜索好友、群、成员获取资料成员统计、群管理插件扩展热加载/卸载功能模块互不干扰个性化功能开发外部接口命令行工具 本地 HTTP APIWeb 前端联动、远程操作值得说明的是QQBot 官方并未提供现成聊天 AI它是一个框架——你提供逻辑它负责跑腿。也正因如此它的能力边界由你的想象力决定。二、理解 QQBot 的核心思想一切皆回调上手前先花 30 秒理解这个框架最关键的机制后面会事半功倍。QQBot 把程序运行时发生的各种事件统一抽象成了9 种回调函数你只要在插件文件里写好这些函数框架就会在对应时机自动调用它们onInit插件初始化onQrcode拿到登录二维码onStartupComplete启动完成onQQMessage收到新消息最常用onInterval每 5 分钟触发一次onUpdate联系人列表更新onPlug/onUnplug插件被加载/卸载onExit程序退出其中onQQMessage是你最常用的入口。函数名和参数必须原样保留框架靠签名识别它们——这是新手最容易踩的坑。所有回调的完整示例在qqbot/plugins/sampleslots.py里建议先通读一遍。三、5分钟快速上手从空目录到第一个机器人第 1 步获取代码并安装依赖项目要求 Python 2.7 或 3.4用 pip 安装依赖即可git clone https://gitcode.com/gh_mirrors/qq/qqbot cd qqbot pip install . 想装在隔离环境避免污染系统 Python项目仓库里提供了qqbot-venv.sh脚本可直接创建独立虚拟环境。第 2 步启动主程序并扫码登录qqbot程序启动后会自动弹出二维码Linux 需要系统装有 gvfs-open 或 shotwell用手机 QQ 扫码授权即可。登录信息会保存在本地下次用qqbot -q qq号码启动可免扫码快速登录注意保存的凭证约 2 天后过期。第 3 步写你的第一个插件新建文件sample.py内容如下def onQQMessage(bot, contact, member, content): if content -hello: bot.SendTo(contact, 你好我是QQ机器人) elif content -stop: bot.SendTo(contact, QQ机器人已关闭) bot.Stop()这段代码让机器人遇到-hello就打招呼收到-stop就自动下线。把文件放到~/.qqbot-tmp/plugins/目录然后在另一个终端窗口执行qq plug sample至此你的第一个 QQ 自动回复机器人已经上线 。想卸载就执行qq unplug sample整个过程无需重启主程序——这就是插件热插拔。四、3个拿来即用的实战模板掌握了入口函数剩下的就是写业务逻辑。下面三个模板都摘自项目官方文档与示例可以直接改改套用。模板一群内被友好应答QQBot 会智能识别有人你消息中带ME标记就说明本机器人被点名了这时候才回应避免骚扰群友def onQQMessage(bot, contact, member, content): if ME in content: bot.SendTo(contact, member.name 艾特我干嘛呢)模板二定时群发提醒11:55 和 17:55 自动开饭广播定时任务用qqbotsched装饰器参数沿用 Unix crontab 语法支持hour、minute、day_of_week等 11 个字段from qqbot import qqbotsched qqbotsched(hour11,17, minute55) def mytask(bot): gl bot.List(group, 456班) if gl is not None: for group in gl: bot.SendTo(group, 同志们开饭啦啦啦啦啦啦)⏰ 这是它内部对 apscheduler 的轻量封装——想每 5 分钟跑一次写minute*/5想工作日跑写day_of_weekmon-fri。模板三用命令行远程指挥qq命令工具可以让你在另一个终端直接操控机器人连代码都不用写qq send buddy jack 你好 # 给好友 jack 发消息 qq list group 机器人测试 # 搜索名含机器人测试的群 qq list group-member 456班 # 查看群成员 qq send group 198班 大家好 # 给群发消息配套的 HTTP 接口默认监听127.0.0.1:8188让 Web 前端也能调用同样的能力比如通过send/buddy/jack/hello这类 URL 发送消息。五、它内部是怎么跑的一张图看懂运行机制QQBot 的架构是典型的主线程管生命周期子线程干杂活设计清晰值得借鉴程序的生命周期可以拆成四个阶段登录阶段读取配置 → 加载插件触发onInit→ 获取二维码触发onQrcode→ 等待扫码授权。启动阶段登录成功后可选拉取联系人列表触发onStartupComplete随后同时拉起 4 个子线程——消息轮询线程、每 5 分钟的 interval 线程、本地 term-server 线程8188 端口、定时调度线程。运行阶段主循环持续运转消息一到就触发onQQMessage定时到点就执行qqbotsched任务所有插件回调都在主线程依次串行执行——所以不用担心全局变量线程安全但回调里也千万别做耗时操作否则会阻塞整个程序。退出阶段手动停止、重启或登录过期时触发onExit父进程再根据退出码决定是否自动重启。值得一提的是框架内置了掉线自动重启restartOnOffline和定时重启插件qqbot/plugins/schedrestart.py配合邮箱接收二维码能让机器人长期稳定在线。六、新手避坑清单都是血泪经验回调签名不能改onQQMessage(bot, contact, member, content)四个参数一个都不能少、名字不能换否则函数不会被识别。不是所有联系人能发消息bot.SendTo只能发给好友/群/讨论组不能发给群成员对象member。判断消息类型看contact.ctype取值为buddy/group/discuss分别对应好友消息、群消息、讨论组消息。别在回调里调外部命令绝对不要用os.system(qq send ...)去操作自己这个 QQ会和主程序形成死锁请直接用bot.SendTo等内置接口。配置按层级覆盖根配置 → 默认配置 → 用户配置 → 命令行参数优先级依次递增。改了配置不生效多半是你没按qqbot -u 你的用户名启动。文件名避开关键字别把自己的脚本命名为qqbot.py、sys.py也别在代码里用qqbot/sys/time做变量名很容易和库冲突。重复发消息的处理SendTo有个resendOn1202参数默认True设成False可避免偶发重复发送代价是可能漏发按需取舍。七、常见问题速查Q1二维码弹不出来怎么办AQQBot 一共提供 4 种二维码显示模式GUI 弹窗默认、邮箱模式配置mailAccount和mailAuthCode推荐 QQ 邮箱、服务器模式需公网 IP、文本模式cmdQrcode设为true需装 pillow 和 wcwidth。远程服务器上用邮箱模式最省心。Q2如何稳定长期在线ASmartQQ 协议限制下登录凭证 1~2 天必失效需重新扫码。实操方案是开启邮箱模式 restartOnOffline自动重启 加载schedrestart插件每天固定时间重启一次比如每天 8:00用手机顺手扫一下即可。Q3怎么拿到消息发送者的 QQ 号A用onQQMessage的第 2、3 个参数contact.qq/contact.name/contact.mark等属性都在联系人对象上各字段含义详见qcontact-attr.md。注意member在好友消息时为None。Q4能发图片、文件、语音吗A不能。SmartQQ 协议本身不支持发送图片、文件、音频及 XML 卡片消息群内也无法真正 其他成员对方只会收到纯文本。这是协议层面的硬限制不是配置能解决的。八、给新手的 3 阶段学习路线入门通读根目录README.MD弄懂基本概念 → 跑通qqbot/plugins/sample.py示例 → 把qqbot/plugins/sampleslots.py里的 9 种回调都打印一遍日志感受触发时机。进阶精读README.MD中bot.List / Update / SendTo三个核心接口的返回值语义 → 用qqbotsched写出你的第一个定时任务 → 研究qqbot/plugins/schedrestart.py的插件写法。实战在plugins-in-dev/目录看社区插件如patchfetch.py如何覆写联系人获取逻辑→ 参考配置文件写多用户配置 → 尝试用 HTTP API 给你的机器人做一个 Web 控制台。写在最后关于项目现状的诚实说明需要向读者说明一个事实QQBot 基于腾讯 SmartQQ 协议构建而该官方接口已于 2019 年停止服务因此本项目目前已无法实际登录使用项目也早已停止维护项目作者在 README 顶部明确标注了这一点。文章中的示例代码与运行机制描述均来自项目真实源码与官方文档。尽管如此QQBot 依然是学习 Python 机器人框架设计的一流教材它的插件热加载机制、回调事件模型、定时任务封装、多线程生命周期管理至今仍有很高的参考价值。如果你正在设计自己的消息机器人或自动化框架读它的源码会收获颇多。核心资源导航官方文档README.MD最完整的接口说明务必先读最简单示例qqbot/plugins/sample.py一个文件学会自动回复全部回调示例qqbot/plugins/sampleslots.py9 种回调逐个演示定时重启插件qqbot/plugins/schedrestart.py开发中插件plugins-in-dev/含patchfetch.py等高阶玩法表情关键词表qqbot/facemap.py消息里可嵌入/可爱等表情联系人属性说明qcontact-attr.md常见问题汇总faq.md看懂架构、跑通示例、再动手写一个属于自己的回调——自动化带来的爽感只有试过才知道。开始吧 【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考