NoneBotPluginText

算法比赛助手

基于 NoneBot2 的算法比赛查询、订阅提醒与 OJ 用户信息卡片插件

简介

nonebot-plugin-algo 是一个面向算法竞赛群和个人机器人的 NoneBot2 插件，支持通过 clist.by 查询比赛与题目，订阅比赛开始提醒，并生成洛谷、Codeforces 用户信息卡片。

比赛查询功能依赖 clist.by API，使用前需要准备 clist_username 和 clist_api_key。用户卡片截图依赖 Playwright 浏览器运行环境。

功能

查询今日、近期比赛，支持按 OJ 平台 ID 和天数筛选
查询指定比赛的题目信息
订阅比赛提醒，支持群聊和私聊场景
查询、绑定洛谷用户，支持简略卡片和详细卡片
查询、绑定 Codeforces 用户，展示 rating、提交热力图、近期比赛等信息
使用本地存储保存订阅数据、用户绑定数据和卡片缓存

安装

使用 nb-cli

nb plugin install nonebot-plugin-algo

使用 uv

uv add nonebot-plugin-algo

使用 pip

pip install nonebot-plugin-algo

然后在 NoneBot 项目的 pyproject.toml 中启用插件：

[tool.nonebot]
plugins = ["nonebot_plugin_algo"]

如果需要生成洛谷或 Codeforces 信息卡片，还需要安装 Playwright Chromium：

uv run playwright install chromium

非 uv 环境可以使用：

python -m playwright install chromium

配置

在 NoneBot 项目的 .env 或 .env.* 中添加配置：

# clist.by API 凭据，使用比赛查询和题目查询时必需
clist_username=your_username
clist_api_key=your_api_key

# 可选配置
algo_days=7
algo_limit=20
algo_remind_pre=30
algo_order_by=start
oj_include=[1,93,163,166,102]

配置项说明：

配置项	默认值	说明
`clist_username`	空	clist.by 用户名
`clist_api_key`	空	clist.by API Key
`oj_include`	`[1,93,163,166,102]`	默认查询的平台 ID 列表
`algo_days`	`7`	近期比赛默认查询天数
`algo_limit`	`20`	clist.by API 返回数量上限
`algo_remind_pre`	`30`	比赛开始前多少分钟提醒
`algo_order_by`	`start`	clist.by 排序字段

常用 clist.by 平台 ID：

平台	ID
Codeforces	`1`
AtCoder	`93`
洛谷	`162`
牛客	`166`

命令

比赛查询

命令	功能	示例
`今日比赛`	查询今天未开始的比赛	`今日比赛`
`近期比赛 [平台ID] [天数]`	查询近期比赛，可选平台和天数	`近期比赛 162 10`
`比赛题目 [比赛ID]`	查询指定比赛题目	`比赛题目 123456`

订阅提醒

命令	功能	示例
`订阅 [比赛ID]` / `订阅比赛 [比赛ID]`	订阅比赛提醒	`订阅 123456`
`取消订阅 [比赛ID]`	取消指定比赛订阅	`取消订阅 123456`
`订阅列表` / `我的订阅`	查看当前会话的订阅列表	`订阅列表`
`清空订阅`	清空当前会话的订阅	`清空订阅`

洛谷

命令	功能	示例
`绑定洛谷 [用户名或ID]`	绑定洛谷账号	`绑定洛谷 123456`
`我的洛谷`	查询已绑定洛谷账号的简略卡片	`我的洛谷`
`我的洛谷 -f`	查询已绑定洛谷账号的详细卡片	`我的洛谷 -f`
`/洛谷 [用户名或ID]` / `/lg [用户名或ID]`	查询指定洛谷用户简略卡片	`/lg 123456`
`/洛谷 -f [用户名或ID]` / `/lg -f [用户名或ID]`	查询指定洛谷用户详细卡片	`/lg -f 123456`

别名：洛谷绑定、绑定lg、lg绑定 等同于 绑定洛谷。

Codeforces

命令	功能	示例
`绑定cf [handle]`	绑定 Codeforces 账号	`绑定cf tourist`
`我的cf`	查询已绑定 CF 账号的简略卡片	`我的cf`
`我的cf -f`	查询已绑定 CF 账号的详细卡片	`我的cf -f`
`/cf [handle]`	查询指定 CF 用户简略卡片	`/cf tourist`
`/cf -f [handle]`	查询指定 CF 用户详细卡片	`/cf -f tourist`

别名：cf绑定 等同于 绑定cf。

缓存

命令	功能
`清空卡片` / `清理卡片`	清空洛谷和 Codeforces 卡片缓存

卡片缓存会在每天 02:00、10:00、18:00 自动清理。

开发

本项目使用 uv 管理依赖和锁文件。

# 安装项目依赖和开发依赖
uv sync --all-groups

# 安装 Playwright Chromium
uv run playwright install chromium

# 运行代码检查
uv run ruff check .

# 格式化
uv run black .
uv run isort .

# 构建发行包
uv build

如果只想安装运行依赖：

uv sync

项目结构

nonebot_plugin_algo/
  command.py          # NoneBot 命令入口
  config.py           # 插件配置和本地存储路径
  query.py            # 比赛与题目查询响应
  subscribe.py        # 比赛订阅、提醒和恢复任务
  scheduler.py        # 卡片缓存清理任务
  util.py             # clist.by API 请求工具
  oj/
    luogu/            # 洛谷 API 与卡片生成
    cf/               # Codeforces API 与卡片生成
  assets/             # 卡片模板、样式和图片资源

路线图

比赛查询系统
条件检索比赛
比赛题目查询
订阅提醒系统
洛谷用户绑定与信息卡片
Codeforces 用户绑定与信息卡片
AtCoder 用户信息查询
个性题单
题目链接解析

开源协议

本项目基于 AGPL-3.0 License 开源。

Metadata

Release files for nonebot-plugin-algo 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nonebot-plugin-algo 0.3.2
File	Size	Uploaded
nonebot_plugin_algo-0.3.2.tar.gz	29.7 MB	Jul 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nonebot-plugin-algo 0.3.2
File	Interpreter	ABI	Platform	Reset
nonebot_plugin_algo-0.3.2-py3-none-any.whl 29.7 MB Jul 11, 2026	Python 3	none	any	Details

Total release size: 59.4 MB

Release files / nonebot_plugin_algo-0.3.2.tar.gz

Download URL	nonebot_plugin_algo-0.3.2.tar.gz
Size	29.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`b4c17e75ef2d2ececce6ed904f5569e489e2da6bc7bd2b298fdf7e0fbfb85233`
BLAKE2b-256 checksum How to use checksums	`4eb6a9f245570f586e1884e92fa5c1f09ee5c35b7099ec02685c07312cd859d9`
Upload date	Jul 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / nonebot_plugin_algo-0.3.2-py3-none-any.whl

Download URL	nonebot_plugin_algo-0.3.2-py3-none-any.whl
Size	29.7 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`a81620488c42265541dd65652075269a0cf274f2f14765300fc31c0c1231d09f`
BLAKE2b-256 checksum How to use checksums	`27637d51e380cc719698c95ebfe638bd7c7460260b10a1784d58f42786097193`
Upload date	Jul 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`