Skip to content

UniQQ 机器人框架 ​

UniQQ 是一款 QQ 机器人框架,作为插件运行底座,承载综合插件等各类插件完成消息收发与业务处理;本页介绍框架定位、基本使用方式、SDK 开发进展与插件生态。

✨ 简介 ​

UniQQ 是 QQ 机器人生态中的框架层。它本身不实现具体业务,而是提供插件运行环境:插件在框架中加载后,即可完成收消息、发消息与执行动作。生态中的各类插件(如综合插件、售卡系统、资料卡、关键词统计、自定义报时、ZL-超级宠物等)均运行于 UniQQ 框架之上。

在涉及「QQ 官方机器人协作」的语境中,运行于 UniQQ 框架的机器人实例通常被称为插件机器人,与 QQ 官方机器人相互配合,各司其职。

🧩 框架定位与职责 ​

角色职责
官方机器人前台交互:收消息、回复消息、发送菜单与提示
综合插件(业务层)业务判断:指令匹配、问答、入群验证、违禁词、定时任务等
插件机器人(UniQQ 框架)后台执行:落地强执行动作,官方机器人异常时补发消息

UniQQ 框架侧机器人具备以下特点:

  • 真实身份可见:插件机器人看到的是真实 QQ 群号、真实用户 QQ 号与框架 Bot QQ,可直接对接以 QQ 号为键的业务逻辑。
  • 强执行能力:支持禁言 / 解除禁言、踢人、撤回消息、修改群名片、群黑名单与白名单管理等动作(机器人需具备相应群管理员权限)。
  • 事件齐全:可监听群消息、私聊消息,以及新人进群、成员退群、管理员变化等框架事件。
  • 容灾补发:在官方机器人协作模式中,官方机器人断线或发送失败时,插件机器人可临时接管消息收发并补发;官方恢复后自动切回官方优先。

🚀 基本使用 ​

UniQQ 框架以插件为核心组织功能,典型使用流程如下:

  1. 安装插件:将插件安装到机器人框架中并启用。
  2. 进入插件控制台:打开 UniQQ 的插件设置,进入对应插件的控制台进行配置。
  3. 群内启用:多数插件支持群内首次发送指令后自动登记群列表,群主可在控制台调整群开关、指令前缀等配置。
  4. 发送指令使用:在群聊或私聊中按插件文档发送指令即可使用对应功能。

TIP

各插件的具体安装步骤、指令列表与配置项不尽相同,请以对应插件的详细使用教程为准(见下方「插件生态」)。

🛠️ SDK 开发进展 ​

面向开发者的多语言 SDK 正在推进中,当前状态如下:

语言状态
易语言开发中
Python开发中
C++开发中

WARNING

以上 SDK 尚在开发过程中,接口设计与可用范围以后续正式发布为准。在 SDK 正式发布前,请勿基于未定稿的接口进行开发。

🔌 插件生态 ​

UniQQ 框架上已有覆盖多种场景的插件,主要包括:

插件主要能力
综合插件菜单、问答、API 指令、AI 聊天、入群验证、违禁词、黑白名单、定时任务等群管能力,并支持「QQ 官方机器人协作」模式
售卡系统面向卡密销售场景的业务插件
资料卡资料卡相关功能插件
关键词统计群内关键词统计插件
自定义报时定时报时插件
ZL-超级宠物群聊宠物养成游戏插件,含领养、照料、战斗、副本、交易等玩法

各插件的详细使用教程收录于对应插件分类,通常涵盖以下内容,使用前建议先行阅读:

教程内容说明
安装与启用在机器人框架中安装插件并启用
插件控制台打开 UniQQ → 插件设置,进入对应插件控制台进行功能配置与管理
群配置群开关、群指令前缀等按群粒度的设置
数据备份数据库热备份与导出,建议定期保存
检查更新控制台内检查新版本并一键升级

❓ 常见问题 ​

插件启用后群内没有反应? 确认插件已在框架中启用、对应群的群开关已打开,且指令拼写符合该插件文档约定;再结合框架日志与插件控制台的管理日志排查。

插件机器人执行禁言、踢人失败? 确认机器人已在目标群具备管理员权限,且目标 QQ 号填写正确;部分动作对权限与群规模有限制,详见综合插件文档。

如何与 QQ 官方机器人配合使用? 参见《QQ 官方机器人协作》文档(见平台总览页导航),其中介绍了协作模式、身份映射与部署要点。

现在能用 SDK 做二次开发吗? 易语言、Python、C++ 三种语言的 SDK 尚在开发中,接口以后续正式发布为准,当前请勿基于未定稿接口开发。

如何备份插件数据? 多数插件的控制台提供备份功能,支持一键热备份数据库,建议定期导出保存;具体操作以各插件文档为准。

🆘 获取帮助 ​

  • 插件使用问题:查阅对应插件的详细教程与文档。
  • 官方机器人协作问题:参见平台总览页中「QQ 官方机器人协作」文档。
  • 反馈问题时,建议附上框架运行日志、插件版本与复现步骤,以便定位。

薇薇官机平台 · ZL 系列插件