【python】nonebot--QQ接口库

Nonebot框架开发酷Q机器人插件

nonebot官方文档：https://none.rclab.tk/guide/
cqhttp官方文档：https://cqhttp.cc/docs/4.10/#/

装饰器

—命令识别

@on_command()

• name 定义命令名称 字符串类型

• aliases=(cmd1,cmd2,…)元组类型的命令别名

• permission= perm.权限
  权限可选值:
  PRIVATE_FRIEND 私人好友
  PRIVATE_GROUP 私人群
  PRIVATE_DISCUSS 私人讨论组
  PRIVATE_OTHER 私人其他
  PRIVATE 私人
  DISCUSS 讨论组
  GROUP_MEMBER 群成员
  GROUP_ADMIN 群管理
  GROUP_OWNER 群主
  GROUP 群
  SUPERUSER 超级管理员
  EVERYBODY 任何人

• only_to_me = True 为True在群里唤醒机器人需要@，False则时不需要

• privileged = False 默认值为False 是否开启特权，在存在会话的情况下也运行该装饰器下的函数

• shell_like= False 默认值False 是否用类shell语法来分割命令后面的参数

—事件监听

@on_notice()
可选参数：

• group_upload 事件名：群文件上传
• group_admin 事件名：
  group_admin.set、group_admin.unset 事件子类型，分别表示设置和取消管理员
• group_decrease 事件名：群成员减少
  group_decrease.leave、group_decrease.kick、group_decrease.kick_me 事件子类型，分别表示主动退群、成员被踢、登录号被踢
• group_increase 事件名：群成员增加
  group_increase.approve、group_increase.invite 事件子类型，分别表示管理员已同意入群、管理员邀请入群
• friend_add 事件名：好友添加

—消息控制

@on_message()

—请求处理

@on_request()
可选参数：

• friend 好友添加请求
• group 群添加请求(自身是群主或管理员)

消息处理

—发送回复消息

session.send()
参数：

• message 要发送的消息内容
• at_sender 回复时是否@消息发送者 默认为False
• ensure_private 确定消息来源是否为私聊 默认为False
• ignore_failure 是否忽略可能发送的错误 默认为True
• **kargs 默认为None

—发送私聊消息

send_private_msg()
参数：

• user_id number - 对方 QQ 号
• message message - 要发送的内容
• auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message字段是字符串时有效

—发送群消息

send_group_msg()
参数：

• group_id number - 群号
• message message - 要发送的内容
• auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message
  字段是字符串时有效

—发送讨论组消息

send_discuss_msg()
参数：

• discuss_id number - 讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）
• message message - 要发送的内容
• auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message
  字段是字符串时有效

—发送消息

send_msg()
参数：

• message_type string - 消息类型，支持
  private、group、discuss，分别对应私聊、群组、讨论组，如不传入，则根据传入的 *_id 参数判断
• user_id number - 对方 QQ 号（消息类型为 private 时需要）
• group_id number - 群号（消息类型为 group 时需要）
• discuss_id number - 讨论组 ID（消息类型为 discuss 时需要）
• message message - 要发送的内容
• auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message
  字段是字符串时有效

—撤回消息

ps：需要安装酷Q pro版才能实现该功能
delete_msg()
参数：

• message_id number (int32)

—发送好友赞

ps：需要安装酷Q pro版才能实现该功能
send_like()
参数：

• user_id number - 对方 QQ 号
• times number 赞的次数默认值为1，每个好友每天最多 10 次

—处理加好友请求

set_friend_add_request()
参数：

• flag string - 加好友请求的 flag（需从上报的数据中获得）
• approve boolean true 是否同意请求
• remark string 空 添加后的好友备注（仅在同意时有效）

—处理加群请求／邀请

set_group_add_request()
参数：

• flag string - 加群请求的 flag（需从上报的数据中获得）
• sub_type 或 type string - add 或 invite，请求类型（需要和上报消息中的 sub_type 字段相符）
• approve boolean true 是否同意请求／邀请
• reason string 空 拒绝理由（仅在拒绝时有效）

—发送文字

#文件位置:插件py文件中 发送其他类型消息同理
from nonebot import CommandSession,on_command
@on_command('你好')
async def auto_reply(session:CommandSession):
    await session.send('[转账] 0.01元转账需收款，请使用手机QQ查看。',at_sender=True)

—发送表情

QQ表情

[CQ:face,id=表情id]

emoji表情

[CQ:emoji,id=表情id]

原创表情

[CQ:bface,id=表情id]

小表情

[CQ:sface,id=表情id]

酷Q [CQ:face,*] 表情代码对应表：https://cqp.cc/t/36910
酷Q [CQ:emoji,*] emoji表情代码对应表：https://cqp.cc/t/15827

—发送图片

ps：需要安装酷Q pro版才能实现该功能

[CQ:image,file=文件名]

—发送语音

ps：需要安装酷Q pro版才能实现该功能

[CQ:record,file=文件名]

—分享音乐

[CQ:music,id=209249583,type=qq]

—发送窗口抖动

戳一戳

session.send('[CQ:shake,id=1]')

— @某人

{1}为被@的群成员帐号。若该参数为all，则@全体成员（次数用尽或权限不足则会转换为文本）。
举例：[CQ:at,qq=123456]

— 发送猜拳魔法表情

[CQ:rps,type={1}] 
{1}为猜拳结果的类型，暂不支持发送时自定义。该参数可被忽略。
1 - 猜拳结果为石头
2 - 猜拳结果为剪刀
3 - 猜拳结果为布

— 发送掷骰子魔法表情

[CQ:dice,type={1}] 
{1}对应掷出的点数，暂不支持发送时自定义。该参数可被忽略。

— 匿名发消息（仅支持群消息使用）

[CQ:anonymous,ignore={1}]
本CQ码需加在消息的开头。
当{1}为true时，代表不强制使用匿名，如果匿名失败将转为普通消息发送。
当{1}为false或ignore参数被忽略时，代表强制使用匿名，如果匿名失败将取消该消息的发送。
举例：
[CQ:anonymous,ignore=true]
[CQ:anonymous]

— 发送音乐

[CQ:music,type={1},id={2}]
{1}为音乐平台类型，目前支持qq、163、xiami
{2}为对应音乐平台的数字音乐id
注意：音乐只能作为单独的一条消息发送
举例：
[CQ:music,type=qq,id=422594]（发送一首QQ音乐的“Time after time”歌曲到群内）
[CQ:music,type=163,id=28406557]（发送一首网易云音乐的“桜咲く”歌曲到群内）

— 发送音乐自定义分享

[CQ:music,type=custom,url={1},audio={2},title={3},content={4},image={5}]
{1}为分享链接，即点击分享后进入的音乐页面（如歌曲介绍页）。
{2}为音频链接（如mp3链接）。
{3}为音乐的标题，建议12字以内。
{4}为音乐的简介，建议30字以内。该参数可被忽略。
{5}为音乐的封面图片链接。若参数为空或被忽略，则显示默认图片。
注意：音乐自定义分享只能作为单独的一条消息发送

— 发送链接分享

[CQ:share,url={1},title={2},content={3},image={4}]
{1}为分享链接。
{2}为分享的标题，建议12字以内。
{3}为分享的简介，建议30字以内。该参数可被忽略。
{4}为分享的图片链接。若参数为空或被忽略，则显示默认图片。
注意：链接分享只能作为单独的一条消息发送

群组管理

—群组踢人

set_group_kick()

—群组单人禁言

set_group_ban()

—群组匿名用户禁言

set_group_anonymous_ban()

—群组全员禁言

set_group_whole_ban()

—群组设置管理员

set_group_admin()

—群组匿名

set_group_anonymous()

—设置群名片

set_group_card()

—退出群组

set_group_leave()

—设置群组专属头衔

set_group_special_title()

—退出讨论组

set_discuss_leave()

—获取群列表

get_group_list()获取群成员信息 get_group_member_info()

—获取群成员列表

get_group_member_list()

—获取群信息

_get_group_info()

—获取会员信息

_get_vip_info()

—获取群公告

_get_group_notice()

–发布群公告

_send_group_notice()

数据获取

—获取登录号信息

get_login_info()
返回数据：

• user_id number (int64) QQ 号
• nickname string

—获取陌生人信息

get_stranger_info()
参数：

• user_id number - QQ 号
• no_cache boolean false 是否不使用缓存（使用缓存可能更新不及时，但响应更快）

返回数据：

• user_id number (int64) QQ 号
• nickname string 昵称
• sex string 性别，male 或 female 或 unknown
• age number (int32) 年龄

—获取 Cookies

get_cookies()
返回数据：

• cookies string

—获取 CSRF Token

get_csrf_token()
返回数据：

• token number (int32) CSRF Token

—获取 QQ 相关接口凭证

get_credentials()
返回数据：

• cookies string Cookies值
• csrf_token number(int32) CSRF Token

—获取语音

get_record()
参数：

• file string - 收到的语音文件名（CQ 码的 file 参数），如
  0B38145AA44505000B38145AA4450500.silk
• out_format string - 要转换到的格式，目前支持 mp3、amr、wma、m4a、spx、ogg、wav、flac
• full_path boolean false 是否返回文件的绝对路径（Windows 环境下建议使用，Docker 中不建议）

返回数据：

• file string 转换后的语音文件名或路径，如 0B38145AA44505000B38145AA4450500.mp3，如果开启了
  full_path，则如
  C:\Apps\CoolQ\data\record\0B38145AA44505000B38145AA4450500.mp3

—获取图片

get_image()
参数：

• file string - 收到的图片文件名（CQ 码的 file 参数），如
  6B4DE3DFD1BD271E3297859D41C530F5.jpg

返回数据：

• file string 下载后的图片文件路径，如
  C:\Apps\CoolQ\data\image\6B4DE3DFD1BD271E3297859D41C530F5.jpg

—获取插件运行状态

get_status()

—获取 酷Q 及 HTTP API 插件的版本信息

get_version_info()
返回数据：

• app_initialized boolean HTTP API 插件已初始化
• app_enabled boolean HTTP API 插件已启用
• plugins_good object HTTP API 的各内部插件是否正常运行
• app_good boolean HTTP API 插件正常运行（已初始化、已启用、各内部插件正常运行）
• online boolean 当前 QQ 在线，null 表示无法查询到在线状态
• good boolean HTTP API 插件状态符合预期，意味着插件已初始化，内部插件都在正常运行，且 QQ 在线

—检查是否可以发送图片

can_send_image()
返回数据：

• yes boolean 是或否

—检查是否可以发送语音

can_send_record()
返回数据：

• yes boolean 是或否

—重启 HTTP API 插件

set_restart_plugin()
参数：

• delay number 0 要延迟的毫秒数，如果默认情况下无法重启，可以尝试设置延迟为 2000 左右

—清理数据目录

clean_data_dir()

• 参数： data_dir string - 收到清理的目录名，支持 image、record、show、bface

—清理插件日志

clean_plugin_log()

—重启 酷Q，并以当前登录号自动登录（需勾选快速登录）

_set_restart()
参数：
字段名 数据类型 默认值 说明

• clean_log boolean false 是否在重启时清空 酷Q 的日志数据库（log*.db）
• clean_cache boolean false 是否在重启时清空 酷Q 的缓存数据库（cache.db）
• clean_event boolean false 是否在重启时清空 酷Q 的事件数据库（eventv2.db）

— 检查更新

.check_update()

—对事件执行快速操作

.handle_quick_operation()

—获取 data 目录中的文件的接口

除了上面的 API，插件还提供一个简单的静态文件获取服务，请求方式只支持 HTTP 的 GET，URL 路径为 /data/
加上要请求的文件相对于 酷Q data 目录的路径。例如，假设 酷Q 主目录在 C:\Apps\CQA，则要获取
C:\Apps\CQA\data\image\ABCD.jpg.cqimg 的话，只需请求
/data/image/ABCD.jpg.cqimg，响应内容即为要请求的文件。 和上面的其它请求一样，如果配置文件中指定了 access
token，则每次请求需要在请求头中加入验证头 Authorization: Bearer your-token。
另外，请求的路径中不允许出现 …，即上级目录的标记，以防止恶意或错误的请求到系统中的其它文件。 本功能默认情况下不开启，在配置文件中将
serve_data_files 设置为 yes 或 true 即可开启，见 配置文件说明。