koishi-plugin-image-selector

感谢原作者 995837081/koishi-plugin-image-selecter

简介

一个图片库管理插件。将图片按文件夹分类存放，用户只需发送对应关键词即可随机获取该分类下的图片或视频；也可通过指令将图片存入指定分类。支持多别名、权限管控、精确/模糊两种触发模式。

功能特性

📤 关键词发图（消息中间件，无需指令前缀）

直接发送关键词触发，语法：<关键词> [数量]

配置项：

• maxout（默认 5）：单次最大发图数量上限
• matchMode（默认 fuzzy）：触发模式
  • fuzzy 模糊匹配：消息以关键词开头即触发，后缀非数字时发 1 张
  • exact 精确匹配：仅 关键词 或 关键词 数字 这两种格式触发，其余忽略
  • none 禁用模式：关键词不直接触发，仅限通过指令（如发图）调用

示例（以"猫图"为关键词，上限 5 张）：

• 通用情况（模糊模式）：

猫图          → 发 1 张
猫图 3        → 发 3 张
猫图 100      → 发 5 张 (超出上限取配置值)

• 精确模式下 (matchMode: 'exact')：

猫图真可爱    → 无反应 ❌
猫图abc       → 无反应 ❌

• 禁用模式下 (matchMode: 'none')：

猫图          → 无反应 ❌ (关键词不触发，仅限指令)

📤 发图指令 默认: 发图 · 可自定义（sendCommandName）

与关键词触发逻辑完全相同，区别是使用显式指令前缀。

语法：发图 <关键词> [数量]

发图 猫图      → 发 1 张
发图 猫图 3    → 发 3 张

📥 存图指令 默认: 存图 · 可自定义（saveCommandName）

语法：存图 [关键词] [图片...]，支持三种方式：

存图 猫图 [图片]       → 直接带图，存入"猫图"分类
[回复一张图] 存图      → 引用消息存图
存图                   → 交互式：机器人提示后再发图和关键词

配置项：

• tempPath（必填）：临时存储目录路径
• saveFailFallback（默认 true）：关键词匹配失败时的行为，true 存入临时目录，false 直接取消
• promptTimeout（默认 30）：交互式存图的等待超时，单位秒
• filenameTemplate：存图文件名模板，详见"文件名模板"

权限控制（userLimits / groupLimits）：

设置用户/群组的上传尺寸上限（MB），0 表示禁止上传。

优先级：用户独立设置 > 群组独立设置 > 群组默认 > 全局默认

示例配置：
default: 0          → 默认所有人禁止上传
管理员ID: 100       → 管理员可上传 100MB
某群ID: 5           → 该群成员默认 5MB
某恶意用户ID: 0     → 即使在允许的群中也被禁止

📋 图库列表指令 默认: 图库列表 · 可自定义（listCommandName）

列出所有可用分类及其别名。

图库列表
→ 猫咪 别名：猫图, 喵星人
→ 风景
→ 狗狗 别名：狗图

🔄 刷新图库指令 默认: 刷新图库 · 可自定义（refreshCommandName）

手动刷新文件夹缓存。添加、删除或重命名文件夹后执行，立即生效无需重启。

刷新图库
→ 图库缓存已刷新，当前共有 15 个文件夹

进阶说明与机制

文件夹命名与别名系统

文件夹名采用 主名-别名1-别名2 的格式。发送消息时，匹配其中任意一个词均可触发功能。

示例： 若文件夹名为 猫咪-猫图-喵星人

• 匹配成功：

  • 猫咪 ✅
  • 猫图 ✅
  • 喵星人 ✅

• 匹配失败：

  • 小猫 ❌ (不属于文件夹名中的任何一段)
  • 狗狗 ❌

多个文件夹包含相同别名时，系统会随机选择其中一个文件夹，并向控制台输出警告日志。

文件名模板

默认：${date}-${time}-${index}-${guildId}-${userId}${ext}

支持变量：${userId} ${username} ${timestamp} ${date} ${time} ${index} ${ext} ${guildId} ${channelId}

支持格式

• 图片：JPEG / PNG / GIF / WebP / BMP / TIFF
• 视频：MP4 / MOV / AVI

缓存机制

文件夹列表自动缓存 5 分钟，修改文件夹结构后使用 刷新图库 立即生效。

目录结构

images/                  ← imagePath（图片库）
├── 猫咪-猫图-喵星人/
│   ├── 1.jpg
│   └── 2.gif
└── 风景-自然/
    └── sunset.mp4

temp/                    ← tempPath（临时存储）

注意事项

1. imagePath 和 tempPath 必须存在且有读写权限
2. userLimits 必须包含 userId 为 default 的项作为全局默认值
3. 文件夹名避免使用特殊字符，别名之间用 - 分割
4. 定期清理临时文件夹，避免占用过多空间

许可证

MIT License