NoneBotPluginLogo

NoneBotPluginText

nonebot-plugin-osubot

✨ 面向 NoneBot2 的 osu! 查询与谱面工具插件 ✨

license pypi codecov python

📖 介绍

nonebot-plugin-osubot 提供 osu! 四种模式的玩家资料、成绩、BP 分析、群内排名、多人比赛分析、谱面信息与谱面预览等功能。查询结果以适合聊天场景的图片呈现，并通过 nonebot-plugin-uninfo 获取跨适配器的用户、群组与频道信息。

项目修改自 osuv2，并针对 NoneBot2 的命令交互、绘图和多平台使用进行了持续维护。

[!IMPORTANT] 谱面变速和完整视频预览依赖 FFmpeg。请先安装 FFmpeg 并确保可从 PATH 调用，或通过 OSU_PREVIEW_FFMPEG_PATH 指定可执行文件。

💿 安装

运行环境：Python 3.10–3.13、NoneBot2 2.3.0 及以上版本。

使用 nb-cli 安装（推荐）

在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装

nb plugin install nonebot-plugin-osubot
使用包管理器安装 在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令
pip 
pip install nonebot-plugin-osubot
pdm 
pdm add nonebot-plugin-osubot
poetry 
poetry add nonebot-plugin-osubot

打开 nonebot2 项目的 bot.py 文件, 在其中写入

nonebot.load_plugin("nonebot_plugin_osubot")

⚙️ 配置

前往 osu! 账号设置 创建 OAuth 应用，将客户端 ID 和客户端密钥写入 NoneBot 项目的 .env 文件：

OSU_CLIENT=你的客户端ID
OSU_KEY=你的客户端密钥

基础配置

配置项 必填 默认值 说明
OSU_CLIENT 是 无 osu! OAuth 客户端 ID
OSU_KEY 是 无 osu! OAuth 客户端密钥
SQLALCHEMY_DATABASE_URL 否 sqlite+aiosqlite:///db.sqlite3 数据库地址，详见 NoneBot ORM 配置
OSU_PROXY 否 无 请求 osu! API 时使用的代理地址或代理配置
OSUTRACK_ENABLED 否 true 是否启用玩家信息定时追踪
OSUTRACK_DEFAULT_DAYS 否 365 历史查询的默认追踪天数

完整预览配置

配置项 默认值 说明
OSU_PREVIEW_FFMPEG_PATH PATH 中的 FFmpeg FFmpeg 可执行文件路径
OSU_PREVIEW_TAIKO_SKIN_PATH 无 Taiko 皮肤目录，支持滚轮素材及其 @2x 版本；留空时使用内置样式
OSU_PREVIEW_FULL_SCALE 0.75 Mania 完整视频缩放倍率，范围 0.5–1.0
OSU_PREVIEW_FULL_FRAME_INTERVAL 30 Mania 完整视频帧间隔（毫秒），范围 20–50
OSU_PREVIEW_TAIKO_FULL_SCALE 0.5 Taiko 完整视频缩放倍率
OSU_PREVIEW_TAIKO_FULL_FRAME_INTERVAL 30 Taiko 完整视频帧间隔（毫秒）
OSU_PREVIEW_STD_CATCH_FULL_SCALE 0.5 osu!/Catch 完整视频缩放倍率
OSU_PREVIEW_STD_CATCH_FULL_FRAME_INTERVAL 30 osu!/Catch 完整视频帧间隔（毫秒）

⚠️ 从 v6 升级到 v7

v7 将底层 ORM 从 tortoise-orm 迁移至 nonebot-plugin-orm，数据库表名和结构发生了变化，升级前需手动执行迁移脚本，否则数据将丢失。

升级步骤：

  1. 停止 bot
  2. 在 bot 根目录下运行迁移脚本：
# 默认 SQLite（自动从 .env 读取数据库地址）
python migrate.py

# 或手动指定数据库地址
python migrate.py sqlite:///db.sqlite3
python migrate.py postgresql://user:pass@localhost/dbname
python migrate.py mysql+pymysql://user:pass@localhost/dbname
  1. 标记迁移版本：
nb orm stamp 68a04ea31d05
  1. 升级插件后重启 bot

🎉 使用

首次使用请发送 /bind <用户名、UID 或主页链接> 绑定账号。发送 /osuhelp 可查看交互式帮助，发送 /osuhelp 全部 可查看完整指令说明。

通用格式：

/命令 [玩家] [序号或范围]:[模式] [+Mods] [&sb]

模式简称：o/0 = osu!、t/1 = Taiko、c/2 = Catch、m/3 = Mania。未指定玩家或模式时，使用当前用户绑定账号的默认设置。官网成绩查询默认包含 lazer 与 stable 成绩，无需切换；成绩图会逐条标注来源。

常用指令

分类 指令 说明
账号 /bind、/unbind、/mode 绑定账号与设置默认模式
资料 /info、/mu、/rank、/update 玩家资料、主页、群内 PP 排名和资料刷新
最佳成绩 /bp、/bl、/nb、/bpa 单条 BP、BP 列表、新增 BP 与 BP 分析
最近成绩 /re、/rl、/pr、/pl 最近游玩、最近通过成绩及其列表
谱面成绩 /sc [mapid]、/sl [mapid] 查询单条成绩，或列出该谱面各 Mod 组合的最佳成绩
历史 /hs [#天数] 查询 PP 与排名历史
谱面 /m、/bm、/bg、/dl 难度信息、谱面集、背景与谱面下载
预览 /预览、/完整预览、/vp 普通预览、全谱预览和完整预览视频
多人 /mp <matchid>、/rt <matchid> 多人比赛详情与多人房评分
其他 /推荐、/md、猜歌指令 谱面推荐、成就查询与猜歌游戏

示例：

/bind peppy
/bp 5:o +HDHR
/bl 31-60:m
/sc 3783810
/sl 3783810
/bpa
/预览 3783810 +gif
/完整预览 3783810
/mp 123456789

查询过一张谱面后，/m、/bm、/sc、/bg、/预览、/dl 等指令可以省略 ID，复用最近查询的谱面。

ppysb 查询

使用 /sbbind <玩家> 绑定 ppysb 账号，然后在普通查询末尾添加 &sb，例如 /info &sb、/bl:4 &sb。SB 模式 0–3 对应四种常规模式，4–6 对应 Relax，8 对应 Autopilot。

AI 自然语言调用（可选）

如果同一个 NoneBot 项目中安装并加载了 nonebot-plugin-ai-groupmate，本插件会自动向 ai-groupmate 注册 osu 查询工具。用户可以通过自然语言让 AI 调用 osubot 的查询能力，而不是直接输入固定命令。

没有安装或没有加载 nonebot-plugin-ai-groupmate 时，本功能会自动跳过，不影响 osubot 原有指令使用。

示例：

@bot 查我的 bp1
@bot 查我的 info
@bot 查 peppy 的 bp1
@bot 查 WhiteCat 的 bp 1-20
@bot 查 @群友 的 bp1
@bot 查我在 3783810 这张图上的成绩
@bot 查我的 pp 历史
@bot 分析我的 bp 构成
@bot 给我推荐谱面
@bot 发一下我的 osu 主页
@bot 查 match 123456789
@bot 查 match 123456789 的 rating
@bot 预览谱面 3783810
@bot 提取谱面 3783810 的背景
@bot 查成就 Non-stop Dancer

账号与模式规则：

  • 用户说“我/我的/自己”或未指定玩家时，使用当前发言用户通过 /bind 绑定的 osu 账号。
  • 消息里 @群友 时，优先使用被 @ 群友绑定的 osu 账号。
  • 查询绑定用户时会使用绑定记录中的默认模式，官网成绩默认包含 lazer 与 stable 成绩。
  • 明确指定 osu 用户名时会查询该 osu 用户名；如果需要非 std 模式，请在自然语言里说明 taiko、ctb 或 mania。

如果用户只是要求查询，AI 会调用工具发出图片后结束；如果用户同时要求评价，例如：

@bot 查我的 bp1，我打得怎么样
@bot 分析一下 @群友 的 bp1
@bot 看看我 recent 发挥如何

工具会把生成的图片回传给支持多模态的主模型，AI 可以基于图片内容给出简短评价。该分析能力依赖 ai-groupmate 当前配置的主聊天模型支持多模态输入。

💡 贡献

如果遇到任何问题，欢迎提各种issue来反馈bug 你也可以加群(228986744)来进行反馈！ 1665504476458_temp_qrcode_share_9993

Project links

Data verified by PyPI on Aug 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (7.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yaowan233 from gravatar.com yaowan233

Credits

Author: yaowan233

GitHub Statistics

Data verified by PyPI on Aug 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

AGPL-3.0

Requires

Python <3.14, >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nonebot_plugin_osubot-7.2.8.tar.gz (15.7 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nonebot_plugin_osubot-7.2.8-py3-none-any.whl (15.8 MB view details)

Uploaded Python 3

File details

Details for the file nonebot_plugin_osubot-7.2.8.tar.gz.

File metadata

  • Download URL: nonebot_plugin_osubot-7.2.8.tar.gz
  • Upload date:
  • Size: 15.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nonebot_plugin_osubot-7.2.8.tar.gz
Algorithm Hash digest
SHA256 5acd61e823a6781796a8ba9f004d40cc61beed9652a203a4c191a024d0e0876e
MD5 d3ee2bad37bd8a01e5faa55371f61e48
BLAKE2b-256 9443e6489faa8c8d073271ed49908ee03040805c5314a6a0cf8b594f2dfecc4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for nonebot_plugin_osubot-7.2.8.tar.gz:

Publisher: pypi-publish.yml on yaowan233/nonebot-plugin-osubot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nonebot_plugin_osubot-7.2.8-py3-none-any.whl.

File metadata

File hashes

Hashes for nonebot_plugin_osubot-7.2.8-py3-none-any.whl
Algorithm Hash digest
SHA256 79955ab97d060d3c4718279907cc95107fff51edf9554acdc98aebb9a25be599
MD5 cac09fbdd706a8cf43671c48c5a10631
BLAKE2b-256 a432a95c9e3c7fa395cd39905211c3ab1177733ebe1fca4aba072d78791ab520

See more details on using hashes here.

Provenance

The following attestation bundles were made for nonebot_plugin_osubot-7.2.8-py3-none-any.whl:

Publisher: pypi-publish.yml on yaowan233/nonebot-plugin-osubot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

7.4.0

2 files

7.3.0

2 files

This release

7.2.8 This release

2 files

7.2.7.1

2 files

7.2.6

2 files

7.2.5

2 files

7.2.4

2 files

7.2.3

2 files

7.2.2

2 files

7.2.1

2 files

7.2.0

2 files

7.1.3

2 files

7.1.2

2 files

7.1.1

2 files

7.1.0

2 files

7.0.4

2 files

7.0.3

2 files

7.0.2

2 files

7.0.1

2 files

7.0.0

2 files

6.28.0

2 files

6.27.4

2 files

6.27.3

2 files

6.26.8

2 files

6.26.7

2 files

6.26.6

2 files

6.26.5

2 files

6.26.4

2 files

6.26.2

1 file

6.26.1

1 file

6.25.0

2 files

6.24.2

2 files

6.24.1

2 files

6.24.0

2 files

6.23.1

2 files

6.23.0

2 files

6.22.3

2 files

6.22.1

2 files

6.22.0

2 files

6.21.0

2 files

6.20.1

2 files

6.20.0

2 files

6.19.0

2 files

6.18.1

2 files

6.18.0

2 files

6.17.1

2 files

6.17.0

2 files

6.16.0

2 files

6.15.1

2 files

6.15.0

2 files

6.14.0

2 files

6.13.2

2 files

6.13.1

2 files

6.13.0

2 files

6.12.7

2 files

6.12.6

2 files

6.12.5

2 files

6.12.4

2 files

6.12.3

2 files

6.12.2

2 files

6.12.1

2 files

6.12.0

2 files

6.11.1

2 files

6.11.0

2 files

6.10.0

2 files

6.9.3

2 files

6.9.2

2 files

6.9.1

2 files

6.9.0

2 files

6.8.1

2 files

6.8.0

2 files

6.7.12

2 files

6.7.11

2 files

6.7.10

2 files

6.7.9

2 files

6.7.8

2 files

6.7.7

2 files

6.7.6

2 files

6.7.5

2 files

6.7.4

2 files

6.7.3

2 files

6.7.2

2 files

6.7.1

2 files

6.7.0

2 files

6.6.1

2 files

6.5.6

2 files

6.5.5

2 files

6.5.4

2 files

6.5.3

2 files

6.5.2

2 files

6.5.1

2 files

6.5.0

2 files

6.4.7

2 files

6.4.6

2 files

6.4.5

2 files

6.4.4

2 files

6.4.3

2 files

6.4.2

2 files

6.4.1

2 files

6.4.0

2 files

6.3.2

2 files

6.3.1

2 files

6.3.0

2 files

6.2.3

2 files

6.2.2

2 files

6.2.1

2 files

6.1.2

2 files

6.1.1

2 files

6.1.0

2 files

6.0.7

2 files

6.0.6

2 files

6.0.5

2 files

6.0.4

2 files

6.0.3

2 files

6.0.2

2 files

6.0.1

2 files

6.0.0

2 files

5.8.5

2 files

5.8.4

2 files

5.8.3

2 files

5.8.2

2 files

5.8.1

2 files

5.8.0

2 files

5.7.3

2 files

5.7.2

2 files

5.7.1

2 files

5.7.0

2 files

5.6.0

2 files

5.5.3

2 files

5.5.2

2 files

5.5.1

2 files

5.5.0

2 files

5.4.1

2 files

5.4.0

2 files

5.3.0

2 files

5.2.4

2 files

5.2.3

2 files

5.2.2

2 files

5.2.1

2 files

5.2.0

2 files

5.1.0

2 files

5.0.1

2 files

5.0.0

2 files

4.2.4

2 files

4.2.3

2 files

4.2.2

2 files

4.2.1

2 files

4.2.0

2 files

4.1.0

2 files

4.0.19

2 files

4.0.18

2 files

4.0.17

2 files

4.0.16

2 files

4.0.15

2 files

4.0.14

2 files

4.0.13

2 files

4.0.12

2 files

4.0.11

2 files

4.0.9

2 files

4.0.8

2 files

4.0.7

2 files

4.0.6

2 files

4.0.5

2 files

4.0.4

2 files

4.0.3

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

3.5.2

2 files

3.5.1

2 files

3.0.0

2 files

2.0.0.post2

2 files

2.0.0.post1

2 files

2.0.0

2 files

1.8.0

2 files

1.0.0

2 files

0.13.2

2 files

0.1.5

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page