QQ 音乐听歌报告插件

适用于 AstrBot 的 QQ 音乐听歌报告插件，支持多账号绑定、本地持久化、扫码登录、密钥刷新、刷时长、账号信息查询，以及年 / 月 / 周 / 日听歌报告图片发送。

功能特性

使用 /qqyy 命令组统一管理功能入口。
支持扫码登录 QQ 音乐，无需手动获取 uin 和 qqmusic_key。
支持一键刷新登录密钥，保持账号长期有效。
支持刷 QQ 音乐听歌时长，每次 10 分钟。
支持自动刷时长：默认每 10 分钟一次；如果当天剩余时间不足，会按剩余时长自适应缩短间隔，达到 24 小时自动停止。
支持一键查询所有账号信息、一键为所有账号刷时长（多线程并行，不阻塞主线程）。
支持一键为所有账号自动刷时长直到各 24 小时（多线程并行，不阻塞主线程）。
支持多账号绑定、默认账号切换、账号删除和账户列表查看。
支持查询 QQ 音乐账号昵称、等级、成长值、好友排名和累计播放时长。
支持发送年报、月报、周报、日报图片。
支持群管理员通过”回复消息 + 执行命令”的方式代查群成员。
支持通过 AstrBot 插件配置限制可用用户和群组。
账号信息本地持久化保存，报告图片发送后自动清理，不保留长期图片缓存。

环境要求

已正确安装并可运行 AstrBot。
AstrBot 所在运行环境可访问 QQ 音乐相关接口。
Python 环境可用，并已安装 requests。

安装方式

将插件目录放到 AstrBot 的插件目录下，例如：AstrBot/data/plugins/astrbot_plugin_qqyy。
在 AstrBot 的 Python 环境中安装依赖：

pip install -r requirements.txt

启动或重载 AstrBot。
确认插件列表中已出现 qqyy。

插件配置

本插件通过 AstrBot 的 _conf_schema.json 提供配置。AstrBot 载入插件后，会自动生成配置文件：

data/config/astrbot_plugin_qqyy_config.json

运行时数据

账号存储文件： data/qqyy_accounts.json
临时图片目录： tmp/
插件配置文件： data/config/astrbot_plugin_qqyy_config.json

绑定参数说明

执行绑定命令时，需要提供以下参数：

alias：账号别名，用于区分多个 QQ 音乐账号。
uin：QQ 音乐账号对应的用户标识。
qqmusic_key：当前账号可用的 QQ 音乐访问凭据。

访问控制配置项

当前版本提供 access_control 配置对象，包含以下字段：

enabled：是否启用白名单控制。
allowed_user_ids：允许使用插件的用户 ID 列表。
allowed_group_ids：允许使用插件的群 ID 列表。
deny_message：未命中白名单时返回的提示语。

默认配置示例：

{
  "access_control": {
    "enabled": false,
    "allowed_user_ids": [],
    "allowed_group_ids": [],
    "deny_message": "当前用户或群组未被允许使用 QQ 音乐听歌报告插件"
  }
}

白名单判定规则

当 enabled = false 时，所有用户和群组都可以使用插件。
当 enabled = true 且两个白名单都为空时，插件会拒绝所有请求。
私聊中，只检查当前用户 ID 是否在 allowed_user_ids 中。
群聊中，只要 当前用户 ID 在用户白名单中，或 当前群 ID 在群白名单中，就允许使用。

如何填写用户 ID 和群 ID

用户 ID 可直接使用当前平台下的发送者 ID。
群 ID 可填写当前平台返回的群号 / 群组 ID。
如果你不确定当前会话的 ID，可在 AstrBot 中使用 /sid 查看会话信息。AstrBot 内置说明里也明确提到：群 ID 可用于整群白名单控制。

配置行为说明

第一次绑定的账号会自动成为默认账号。
如果删除的是默认账号，且还有其他账号，插件会自动将剩余账号中的第一个设为默认账号。
当一个用户绑定了多个账号，但没有有效默认账号时，插件会提示先执行 /qqyy 切换 <别名>。
报告图片会先写入 tmp/，发送完成后由发送后钩子自动删除。

注册行为

插件采用 AstrBot 的插件注册与命令组机制：

通过 @register("qqyy", "27chcn", "QQ 音乐听歌报告插件", "5.8.0") 注册插件。
通过 @filter.command_group("qqyy") 注册命令组。
所有命令都以 /qqyy 作为统一入口。
插件构造函数支持接收 AstrBot 注入的 config，用于读取 _conf_schema.json 生成的配置。

查询目标解析规则

普通成员： 即使回复了其他人的消息，也只能查询自己绑定的账号。
群管理员 / 群主： 当消息是“回复某个成员的消息”且平台原始消息中能解析出目标发送者时，可以代查该成员。
兼容回退： 如果平台没有提供可解析的回复目标，插件会自动回退为查询命令发送者本人，不会直接报平台兼容性异常。
访问控制优先： 若当前用户 / 群组未通过白名单检查，命令会在业务逻辑执行前直接拒绝。

命令说明

子指令	说明	用法
`登录`	扫码登录 QQ 音乐；默认别名为"大号"，已存在时需指定别名。	`/qqyy 登录 [别名]`
`刷新`	刷新当前账号的登录密钥；不传别名时刷新默认账号。	`/qqyy 刷新 [别名]`
`全部刷新`	一键刷新所有绑定账号的登录密钥（多线程并行）。	`/qqyy 全部刷新`
`刷时长`	刷 QQ 音乐听歌时长，每次 10 分钟；不传别名时使用默认账号。	`/qqyy 刷时长 [别名]`
`自动刷时长`	后台自动刷时长直到累计 24 小时，默认 10 分钟一次；当天时间不足时自适应缩短间隔。	`/qqyy 自动刷时长 [别名]`
`全部信息`	一键查询所有绑定账号的信息（多线程并行）。	`/qqyy 全部信息`
`全部刷时长`	为所有绑定账号各刷一次时长（10 分钟，账号之间默认间隔 3 秒错峰提交）。	`/qqyy 全部刷时长`
`全部自动刷时长`	为所有账号错峰提交后台自动刷时长任务直到各 24 小时。	`/qqyy 全部自动刷时长`
`绑定`	手动绑定一个 QQ 音乐账号；首次绑定会自动设为默认账号。	`/qqyy 绑定 <别名> <uin> <qqmusic_key>`
`切换`	将指定别名切换为默认账号。	`/qqyy 切换 <别名>`
`删除`	删除指定别名的账号。	`/qqyy 删除 <别名>`
`账户列表`	查看当前已绑定的全部账号及默认账号标记。	`/qqyy 账户列表`
`信息`	查询账号信息；不传别名时查询默认账号。	`/qqyy 信息 [别名]`
`年报`	发送年度听歌报告图片。	`/qqyy 年报 [别名]`
`月报`	发送月度听歌报告图片。	`/qqyy 月报 [别名]`
`周报`	发送周度听歌报告图片。	`/qqyy 周报 [别名]`
`日报`	发送日度听歌报告图片。	`/qqyy 日报 [别名]`

使用示例

扫码登录

/qqyy 登录

发送后会收到一张二维码图片，用 QQ 音乐 App 扫码即可完成登录。登录成功后自动绑定为"大号"。

扫码登录并指定别名

/qqyy 登录 小号

刷新密钥

/qqyy 刷新
/qqyy 刷新 小号

密钥过期时使用，无需重新扫码。

全部刷新

/qqyy 全部刷新

一键刷新当前用户绑定的所有账号密钥。没有扫码登录缓存凭证的账号会在结果中标记失败，需要重新扫码登录。

刷时长

/qqyy 刷时长
/qqyy 刷时长 小号

每次刷 10 分钟听歌时长。

自动刷时长

/qqyy 自动刷时长
/qqyy 自动刷时长 小号

命令会先执行一次与 /qqyy 刷时长 相同的首刷；首刷成功后再返回“后台任务已启动”，回复中会显示当前预计上报间隔。后台任务会在每次上报后延迟检测已播放时长，并按“距离当天结束剩余时间 / 距离 24 小时所需上报次数”自适应安排下一次上报，计算时会扣除上报后的查询延迟：时间充足时保持 10 分钟一次；时间不足时自动缩短，最低 60 秒一次。进度查询失败不会立即停止，会按已上报次数继续执行；连续 3 次检测时长未增长会先放慢到 10 分钟一次，连续 6 次仍未增长才会停止；达到 24 小时或累计上报满 24 小时自动停止。重复执行同一账号会提示任务已在运行。

全部信息

/qqyy 全部信息

一键查询所有绑定账号的等级、成长值、播放时长等信息，多个账号通过线程池并行请求。

全部刷时长

/qqyy 全部刷时长

为所有绑定账号各刷一次 10 分钟时长。账号之间默认间隔 3 秒提交请求，用于降低批量同时请求带来的风控风险；等待间隔使用异步 sleep，不会阻塞主线程。

全部自动刷时长

/qqyy 全部自动刷时长

为所有绑定账号错峰提交后台自动刷时长任务，账号之间默认间隔 3 秒；命令回复中会列出本次新启动账号的当前预计上报间隔。每个后台任务启动后会按当前已播放时长和当天剩余时间自适应安排下一次上报，计算时会扣除上报后的查询延迟：时间充足时保持 10 分钟一次；时间不足时最低可缩短到 60 秒一次。每次上报后都会延迟检测进度：进度查询失败不会立即停止，会按已上报次数继续执行；连续 3 次检测时长未增长会先放慢到 10 分钟一次，连续 6 次仍未增长才会停止；各自达到 24 小时或累计上报满 24 小时自动停止。命令只等待错峰提交完成，不会阻塞到所有账号刷满 24 小时。

绑定并查看默认账号信息

/qqyy 绑定 main 123456789 your_qqmusic_key
/qqyy 信息

绑定第二个账号并切换默认账号

/qqyy 绑定 alt 987654321 another_qqmusic_key
/qqyy 切换 alt
/qqyy 账户列表

查询报告图片

/qqyy 年报
/qqyy 月报 alt

配置白名单后仅允许指定对象使用

{
  "access_control": {
    "enabled": true,
    "allowed_user_ids": ["10001"],
    "allowed_group_ids": ["20001"],
    "deny_message": "当前用户或群组未被允许使用 QQ 音乐听歌报告插件"
  }
}

上面的配置表示：

私聊中，仅用户 10001 可用。
群聊中，只要发送者是 10001，或当前群是 20001，就允许使用。

群管理员代查

在群聊中：

先让目标成员发送一条消息。
群管理员或群主回复这条消息。
回复后发送 /qqyy 信息、/qqyy 周报 等查询命令。

如果回复目标可被平台原始消息正确识别，插件会查询被回复成员；否则会自动回退为查询管理员自己。

数据与缓存说明

插件只持久化保存账号配置，不缓存接口结果。
生成的报告图片属于临时文件，仅用于当前这次消息发送。
图片发送完成后会自动删除，避免长期占用磁盘空间。

常见问题

1. 提示”你还没有绑定 QQ 音乐账号”

说明当前身份下还没有可用绑定记录，请先执行：

/qqyy 登录

或手动绑定：

/qqyy 绑定 <别名> <uin> <qqmusic_key>

2. 提示”QQ 音乐接口请求失败，请检查 uin 或 qqmusic_key 是否有效”

通常表示 uin 或 qqmusic_key 无效、已过期，或当前运行环境无法正常访问 QQ 音乐接口。可尝试：

/qqyy 刷新

若刷新仍失败，请重新扫码登录：

/qqyy 登录

3. 扫码登录时提示"二维码已过期或未被扫码"

二维码有效期约 60 秒，请在收到二维码图片后尽快使用 QQ 音乐 App 扫码。过期后重新发送 /qqyy 登录 即可。

4. 为什么我回复了别人的消息，结果查到的还是我自己？

只有群管理员或群主才支持回复代查；普通成员始终只能查询自己。另外，如果当前平台没有在原始消息里提供可解析的回复目标，插件也会自动回退为查询自己。

5. 为什么命令直接被拒绝了？

如果启用了白名单控制，而当前用户和当前群都没有命中允许列表，插件会直接返回拒绝提示。尤其是在你开启白名单但没有填写任何用户或群组时，插件会拒绝所有请求。

开发说明

当前实现拆分为 3 个主要部分：

main.py：AstrBot 插件入口、命令注册、访问控制、权限与回复目标解析、消息发送后清理。
account_store.py：本地账号持久化与默认账号管理。
qqyy.py：QQ 音乐接口请求、账号信息聚合与报告图片下载。

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
_conf_schema.json		_conf_schema.json
account_store.py		account_store.py
auto_play.py		auto_play.py
batch_utils.py		batch_utils.py
credential_utils.py		credential_utils.py
main.py		main.py
metadata.yaml		metadata.yaml
qqyy.py		qqyy.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation