nonebot-plugin-random

✨ Nonebot2 通用抽图/语音插件 ✨

📖 介绍

nonebot-plugin-random 是面向 NoneBot2 和 OneBot V11 的通用随机素材插件。只需在 data/random 中建立资源池并放入素材，即可提供文本、图片、语音或视频随机抽取功能。

0.1.0 新增动态资源池管理、网页截图面板、群级与全局开关、群级冷却、跨群管理、资源池归档恢复和严格配置校验。资源池 Matcher 可以在运行期间创建、重建或注销，无需每次修改后重启机器人。

💿 安装

插件要求 Python 3.9.5 或更高版本。

使用 nb-cli：

nb plugin install nonebot-plugin-random

使用 pip：

pip install nonebot-plugin-random

然后在 NoneBot2 配置中加载插件，或在入口文件中调用：

nonebot.load_plugin("nonebot-plugin-random")

管理面板由 nonebot-plugin-htmlrender 渲染。首次部署时请按照该插件的说明准备 Playwright 浏览器运行环境；浏览器不可用时，随机池列表会回退为文本消息。

🎉 快速开始

机器人启动时会创建并扫描运行目录下的 data/random/。每个不以 . 或 _ 开头的子目录都是一个资源池，例如：

data/
├─ random/
│  ├─ capoo/
│  │  ├─ config.json
│  │  ├─ happy.png
│  │  └─ nested/
│  │     └─ sleepy.webp
│  └─ quote/
│     ├─ config.json
│     └─ hello.txt
└─ random_archive/

若 capoo 没有 config.json，插件会使用默认配置并注册 随机capoo 命令。已有的 data/random/<资源池> 目录可以继续使用，但新版配置采用严格校验；包含未知字段、错误类型或非法值的资源池会记录错误并跳过。

⚙️ 资源池配置

config.json 必须是 UTF-8 编码的 JSON 对象。

{
    "display_name": "Capoo",
    "draw_output": "image",
    "draw_mode": "direct",
    "cooldown_seconds": 10,
    "message_type": "command",
    "message": ["随机capoo"],
    "insert_message": ["添加随机capoo"],
    "delete_message": ["删除随机capoo"],
    "modify_admin_only": true,
    "is_tome": false,
    "output_prefix": "",
    "output_suffix": "",
    "is_at_sender": false
}

output_prefix 和 output_suffix 支持以下占位符：

资源池 ID 来自目录名，只允许小写字母、数字、下划线和连字符，长度为 1～32 个字符，并且必须以字母或数字开头。

📦 支持的素材

命令模式下可以在抽取命令后附加文件名前缀，插件会从文件名以该前缀开头的候选素材中随机选择。

图片资源池支持在群聊中发送或回复图片进行添加、删除。添加时会验证图片内容，只接受 PNG、JPEG、GIF 和 WebP；删除会移除内容哈希相同的所有图片。

🎛️ 管理命令

查看与群内开关

跨群与全局管理

群级和全局开关保存在 data/random/group_switches.json，写入过程使用临时文件替换，避免部分写入。

动态资源池管理

删除操作不会直接销毁素材，而是将整个资源池移动到 data/random_archive/<时间戳>--<资源池ID>。

🔐 权限与状态优先级

资源池状态按以下顺序解析：

1. 群显式开启；
2. 群显式关闭；
3. 全局默认禁用；
4. 默认开启。

群级冷却按“群号 + 资源池 ID”分别计算，不同群互不影响。抽取发送失败时会释放本次冷却占用。

📝 更新日志

0.1.0

• 重构为动态资源池注册与管理架构。
• 新增网页截图管理面板及文本降级响应。
• 新增群级开关、全局默认状态和超级管理员跨群管理。
• 新增群级冷却、文本抽取、直接/分层抽取模式。
• 新增运行时创建、编辑、归档与恢复资源池。
• 使用 Pydantic v2 严格校验配置，并增强图片内容与文件名安全校验。
• 将图片增删权限默认值调整为仅管理员。

💡 特别感谢

• noneplugin/nonebot-plugin-petpet Nonebot2 插件，用于制作摸头等头像相关表情包

📄 开源许可

本项目使用 MIT License 开源。