UniQQ 机器人框架
UniQQ 是一款 QQ 机器人框架,作为插件运行底座,承载综合插件等各类插件完成消息收发与业务处理;本页介绍框架定位、基本使用方式、SDK 开发进展与插件生态。
✨ 简介
UniQQ 是 QQ 机器人生态中的框架层。它本身不实现具体业务,而是提供插件运行环境:插件在框架中加载后,即可完成收消息、发消息与执行动作。生态中的各类插件(如综合插件、售卡系统、资料卡、关键词统计、自定义报时、ZL-超级宠物等)均运行于 UniQQ 框架之上。
在涉及「QQ 官方机器人协作」的语境中,运行于 UniQQ 框架的机器人实例通常被称为插件机器人,与 QQ 官方机器人相互配合,各司其职。
🧩 框架定位与职责
| 角色 | 职责 |
|---|---|
| 官方机器人 | 前台交互:收消息、回复消息、发送菜单与提示 |
| 综合插件(业务层) | 业务判断:指令匹配、问答、入群验证、违禁词、定时任务等 |
| 插件机器人(UniQQ 框架) | 后台执行:落地强执行动作,官方机器人异常时补发消息 |
UniQQ 框架侧机器人具备以下特点:
- 真实身份可见:插件机器人看到的是真实 QQ 群号、真实用户 QQ 号与框架 Bot QQ,可直接对接以 QQ 号为键的业务逻辑。
- 强执行能力:支持禁言 / 解除禁言、踢人、撤回消息、修改群名片、群黑名单与白名单管理等动作(机器人需具备相应群管理员权限)。
- 事件齐全:可监听群消息、私聊消息,以及新人进群、成员退群、管理员变化等框架事件。
- 容灾补发:在官方机器人协作模式中,官方机器人断线或发送失败时,插件机器人可临时接管消息收发并补发;官方恢复后自动切回官方优先。
🚀 基本使用
UniQQ 框架以插件为核心组织功能,典型使用流程如下:
- 安装插件:将插件安装到机器人框架中并启用。
- 进入插件控制台:打开 UniQQ 的插件设置,进入对应插件的控制台进行配置。
- 群内启用:多数插件支持群内首次发送指令后自动登记群列表,群主可在控制台调整群开关、指令前缀等配置。
- 发送指令使用:在群聊或私聊中按插件文档发送指令即可使用对应功能。
TIP
各插件的具体安装步骤、指令列表与配置项不尽相同,请以对应插件的详细使用教程为准(见下方「插件生态」)。
🛠️ SDK 开发进展
面向开发者的多语言 SDK 正在推进中,当前状态如下:
| 语言 | 状态 |
|---|---|
| 易语言 | 开发中 |
| Python | 开发中 |
| C++ | 开发中 |
WARNING
以上 SDK 尚在开发过程中,接口设计与可用范围以后续正式发布为准。在 SDK 正式发布前,请勿基于未定稿的接口进行开发。
🔌 插件生态
UniQQ 框架上已有覆盖多种场景的插件,主要包括:
| 插件 | 主要能力 |
|---|---|
| 综合插件 | 菜单、问答、API 指令、AI 聊天、入群验证、违禁词、黑白名单、定时任务等群管能力,并支持「QQ 官方机器人协作」模式 |
| 售卡系统 | 面向卡密销售场景的业务插件 |
| 资料卡 | 资料卡相关功能插件 |
| 关键词统计 | 群内关键词统计插件 |
| 自定义报时 | 定时报时插件 |
| ZL-超级宠物 | 群聊宠物养成游戏插件,含领养、照料、战斗、副本、交易等玩法 |
各插件的详细使用教程收录于对应插件分类,通常涵盖以下内容,使用前建议先行阅读:
| 教程内容 | 说明 |
|---|---|
| 安装与启用 | 在机器人框架中安装插件并启用 |
| 插件控制台 | 打开 UniQQ → 插件设置,进入对应插件控制台进行功能配置与管理 |
| 群配置 | 群开关、群指令前缀等按群粒度的设置 |
| 数据备份 | 数据库热备份与导出,建议定期保存 |
| 检查更新 | 控制台内检查新版本并一键升级 |
❓ 常见问题
插件启用后群内没有反应? 确认插件已在框架中启用、对应群的群开关已打开,且指令拼写符合该插件文档约定;再结合框架日志与插件控制台的管理日志排查。
插件机器人执行禁言、踢人失败? 确认机器人已在目标群具备管理员权限,且目标 QQ 号填写正确;部分动作对权限与群规模有限制,详见综合插件文档。
如何与 QQ 官方机器人配合使用? 参见《QQ 官方机器人协作》文档(见平台总览页导航),其中介绍了协作模式、身份映射与部署要点。
现在能用 SDK 做二次开发吗? 易语言、Python、C++ 三种语言的 SDK 尚在开发中,接口以后续正式发布为准,当前请勿基于未定稿接口开发。
如何备份插件数据? 多数插件的控制台提供备份功能,支持一键热备份数据库,建议定期导出保存;具体操作以各插件文档为准。
🆘 获取帮助
- 插件使用问题:查阅对应插件的详细教程与文档。
- 官方机器人协作问题:参见平台总览页中「QQ 官方机器人协作」文档。
- 反馈问题时,建议附上框架运行日志、插件版本与复现步骤,以便定位。
