nonebot-plugin-kuwo

✨ 基于 NoneBot2 的酷我音乐插件 ✨

基于 NoneBot2 的酷我音乐插件，面向 NapCat / OneBot V11 使用场景，提供搜索、直链、音乐卡片、语音和文件发送能力。

功能

• kwsearch <关键词>
  • 返回搜索结果列表
  • 支持 text / image
• kw搜索 <关键词>
  • kwsearch 中文别名
• kw <关键词> [-q/--quality <quality>]
  • 搜索后直接取第一首歌
  • 支持 text / card / record / file
• kwid <rid> [-q/--quality <quality>]
  • 直接通过 rid 获取歌曲
  • 支持 text / card / record / file

安装

nb-cli

nb plugin install nonebot-plugin-kuwo --upgrade

使用 PyPI 源：

nb plugin install nonebot-plugin-kuwo --upgrade -i https://pypi.org/simple

uv add nonebot-plugin-kuwo

uv add git+https://github.com/006lp/nonebot-plugin-kuwo@main

pdm add nonebot-plugin-kuwo

poetry add nonebot-plugin-kuwo

plugins = ["nonebot_plugin_kuwo"]

配置

COMMAND_START=["/"]
LOG_LEVEL=INFO
RENDER_BACKEND=playwright

KUWO_SEARCH_LIMIT=5
KUWO_LIST_RENDER_MODE=text
KUWO_TRACK_RENDER_MODE=text
KUWO_DEFAULT_QUALITY=standard
# KUWO_TRACK_PROXY_URL=http://127.0.0.1:7890
KUWO_TRACK_CACHE_RETENTION_DAYS=1
KUWO_TRACK_CACHE_MAX_SIZE_MB=1024

配置项说明：

RENDER_BACKEND 是 nonebot-plugin-htmlrender 的配置项。使用 KUWO_LIST_RENDER_MODE=image 时需要设置为 playwright；未配置时图片渲染会失败并自动回退到文本列表。当前项目依赖限定为 nonebot-plugin-htmlrender>=0.7.1,<0.8，暂时避开 0.8 系列的破坏性更新。默认 RENDER_STARTUP_MODE=off 时不会在 NoneBot 启动阶段预热浏览器，首次图片渲染会按需启动，详情见 nonebot-plugin-htmlrender 文档。

音质枚举：

• standard
• exhigh
• lossless
• hires
• hifi
• sur
• jymaster

特殊规则：

• KUWO_TRACK_RENDER_MODE=card 且未显式设置 KUWO_LIST_RENDER_MODE 时，搜索列表默认切到 image
• record 模式强制回落到 standard
• card 模式音质上限固定为 lossless
• KUWO_TRACK_CACHE_MAX_SIZE_MB 小于 600 时仅记录警告，不阻止启动
• KUWO_TRACK_PROXY_URL 只代理歌曲直链接口，不代理搜索、封面、详情和文件下载

使用

搜索列表

kwsearch / kw搜索 当前支持两种输出：

• text
  • 每行格式：序号. 音乐id 歌曲名-歌手
• image
  • 使用 nonebot-plugin-htmlrender 生成图片列表
  • 直接复用搜索接口返回的 web_albumpic_short
  • 渲染失败时自动回退到文本

单曲输出

kw / kwid 当前支持四种输出：

• text
  • 有封面时发送 图片 + 文本
  • 文本包含：歌曲名、歌手、专辑、时长、码率、直链
  • 若接口返回 ekey，文本中会额外带上 ekey
• card
  • 发送自定义音乐卡片
  • url 和 audio 都使用真实直链
• record
  • 发送语音段
  • 始终使用 standard
• file
  • 下载到本地缓存后发送文件段
  • .mflac 会先解密成可播放的 .flac
  • 上传文件名使用 [quality]歌曲名 - 歌手.扩展名，quality 为最终生效音质，例如 [lossless]Summer - rionos.flac

音质参数

kw 和 kwid 都支持：

-q
--quality

示例：

/kw Summer Pockets -q lossless
/kwid 553152678 --quality exhigh

文件缓存与 .mflac

file 模式使用 nonebot-plugin-localstore 的插件缓存目录，并在其下维护 tracks/ 子目录。

普通可直接发送的格式：

• mp3
• flac
• aac
• ogg
• wav

缓存策略：

• 相同 rid + bitrate 优先复用缓存
• 缓存命中会刷新文件时间
• 默认按 1 天和 1024MB 双重策略清理
• 两个值都设为 0 时，不做自动清理

.mflac 流程：

1. 下载原始 .mflac
2. 使用 Kuwo 返回的 ekey
3. 提取 QMC 原始密钥
4. 推导最终 QMCv2 密钥
5. 本地解密为 .flac
6. 发送解密后的文件
7. 删除中间 .mflac

反馈问题

提交 Issue 前请先搜索已有反馈，并按模板提供插件版本、NoneBot / 适配器 / 协议端版本、相关配置、触发命令和脱敏后的 DEBUG 日志。

开发

项目强制使用 uv。

当前版本 0.2.7 的本地验证环境为 Python 3.13.16 / Rust 1.99.0，插件支持 Python >=3.10，原生扩展使用 abi3-py310。 构建工具使用 maturin>=1.15.0,<2.0，Rust 绑定使用 pyo3 0.29.3；Release 工作流固定使用 maturin 1.15.0。

uv sync --dev --locked
uv run maturin develop --release --locked

更新依赖后需要重新构建原生扩展：

uv lock --upgrade
cargo update
uv sync --dev --locked
uv run maturin develop --release --locked

常用命令：

uv run ruff check .
uv run pytest tests -q -p no:cacheprovider
cargo fmt --all --check

说明：

• 发布版 wheel 会自带原生扩展 _qmc_rs
• 源码开发或本地调试需要先执行 maturin develop

项目结构

nonebot_plugin_kuwo/
├── __init__.py
├── config.py
├── data_source.py
├── models.py
├── qmc.py
├── render.py
└── utils.py
src/
└── qmc.rs
tests/

鸣谢

• LiuLang 提供 DES 解密算法思路
• UnblockNeteaseMusic/server 提供音乐直链接口

许可证

本项目使用 AGPL-3.0 许可证。