nonebot-plugin-longtu

✨一个随机发送龙图的nonebot2插件✨

💬 前言

2024年是龙年...我都准备好了.jpg

📖 介绍

一个非常简单的nonebot2插件，输入指令后会从神秘的龙图仓库（内含1500张精选龙图）中随机发送一张或多张（可爱）的龙图.

ps：攻击性较强，请酌情使用。

神秘的龙图仓库：https://github.com/Whiked/Dragonimg

💿 安装

pip install nonebot-plugin-longtu

pdm add nonebot-plugin-longtu

poetry add nonebot-plugin-longtu

conda install nonebot-plugin-longtu

[tool.nonebot]
plugins = [
    # ...
    "nonebot_plugin_longtu"
]

⚙️ 配置

在 nonebot2 项目的 .env 文件中添加下表中的配置

默认本地模式

不添加配置即可使用。首次没有图片时可以远程取图，后台分批并行补库；已经有本地图时，只从现有图片中随机抽取，无需等整个仓库下载完成。一次命令在图片数量足够时不会重复抽取。

“空闲”指没有龙图请求正在处理，且距离最近一次龙图请求结束超过指定时间，不是检测整机 CPU 或整个群是否安静。已经发起的一批下载会完成，后续批次等待前台请求结束。默认 3 张并行、批次间隔 0.1 秒，1516 张图片的批次间隔合计约 51 秒，不再固定等待两小时。实际完成时间还取决于网络、使用频率和失败重试，不能将间隔之和当作总耗时。HTTP 连接池另为前台预留容量。

内置 index.json 固定记录 1516 张图片的真实文件名、大小和 Git blob 校验值。随机取图与后台下载共用这份索引，不查询 GitHub API，不需要 token，也不会猜测文件后缀。失败批次按 5、10、20、40、60 秒退避，成功批次恢复正常速度；后续轮次只重试失败项，重启后跳过已完整保存的图片。全部下载完成后后台任务退出，不持续轮询。下载使用临时文件并校验后替换，不自动删除本地图。图片只在使用时读入内存，不把整个图库常驻内存。

希望更快补库时可将 LONGTU_DOWNLOAD_CONCURRENCY=5、LONGTU_DOWNLOAD_INTERVAL=0；带宽较小时可设并发为 1 并增加批次间隔。旧配置中的显式等待值会继续生效，升级后需移除或调整才能使用新默认值。

自定义目录示例：

LONGTU_MODE=local
LONGTU_LOCAL_DIR="./data/longtu"

也可以下载 Dragonimg 的 ZIP，将 drimg 内图片放入该目录，保持文件名不变。启动时仅收录本层索引内的图片；运行期间手动补入图片后重启 bot。默认插件目录不可写时，请设置可写目录，尤其是容器或系统级安装环境；容器建议挂载该目录，升级插件前也建议备份本地图片。图库若将来变化，需要维护者同步更新并发布索引。

完全离线使用已有图片：

LONGTU_MODE=local
LONGTU_LOCAL_DIR="./data/longtu"
LONGTU_AUTO_DOWNLOAD=false
LONGTU_REMOTE_FALLBACK=false

纯远程模式

LONGTU_MODE=remote

此模式使用插件内置清单，每次下载图片字节发送，不创建本地图片目录，不运行后台补库；更新内置清单随插件升级。它仍依赖 GitHub 网络，网络较差时建议使用默认本地模式。

两种模式都发送图片字节，适用于 NoneBot 与 OneBot 协议端位于不同机器的环境，不要求协议端能访问 NoneBot 的本地路径。

🎉 使用

现有指令列表：

dragon，龙龙，龙图：发送一张可爱的龙龙图片

龙图 3：发送三张可爱的龙龙图片

示例：

📞 制作者

黑纸折扇 [Perseus037] (https://github.com/Perseus037)

• QQ: 1209228678

Whike [Whiked] (https://github.com/Whiked)

• QQ: 274752001

🙏 感谢

student_2333 (https://github.com/lgc2333) 的无私帮助。

📝 更新日志

0.2.1

• 默认后台 3 张并行，启动等待 5 秒、请求后空闲 3 秒、每批间隔 0.1 秒。
• 前台请求优先，失败批次指数退避，仅重试失败图片，保留校验与重启续传。

0.2.0

• 支持本地、远程两种模式，默认本地优先，目录可配置。
• 空闲时单文件渐进下载，已有图片可立即使用，支持重启续传，补齐后自动结束。
• 内置真实图片清单，校验下载内容，限制请求等待，复用 HTTP 连接。

0.1.2

• 龙库换源：将图片资源迁移到 GitHub Raw（Whiked/Dragonimg/drimg/），提升可用性与稳定性

0.1.1.post1

• 实现多张龙图发送
• 增加新配置项

0.1.0.post4

• 增加了更多类型的httpx错误处理
• 修改FinishedException位置

0.1.0.post1-0.1.0.post3

• 仓库内由测试的50张龙图扩展到了1500张精选龙图，随机范围更广（攻击性更强）。
• 常规修正