基于 早柚核心 (gsuid_core) 的「今日 <类型>」本地图库插件
把图片按类型放进文件夹,插件就为每个文件夹提供一条 今日<类型> 命令 —— 今日黑丝、今日白丝、今日制服。
新建文件夹即刻可用,不需要重启核心,也不需要重载。
群聊里行为对齐 TodayWaifu 的「今日萝莉」:同一个人在同一个群里、同一天内重复发送,返回的是同一张图, 北京时间 0 点才重新抽。私聊不限次数,每次都重新随机。
| 动态类型 | 一级文件夹名即类型名,收到消息时才解析,加文件夹无需重启无需重载 |
| 群聊每日固定 | 群里每人 / 每群 / 每类型每天固定一张,北京时间 0 点重置(不跟随服务器时区) |
| 私聊不限次数 | 私聊每次都重新随机,不定桩、不写每日记录 |
| 同群不撞图 | 同一天同一个群里,不同的人不会抽到同一张(图不够分时才退回允许重复) |
| 分群授权 | 群里每个类型需群管理员先授权,可为不同群设置不同尺度;私聊不受限制 |
| 不暴露图库 | 未知 / 被屏蔽 / 未授权 / 空文件夹一律静默且互不可区分,无法靠试探枚举服务器上有哪些类型 |
| 与 TodayWaifu 共存 | 默认屏蔽 今日老婆、今日萝莉 等命令;动态触发器非阻断,不会吃掉其它插件的 今日X |
| 零额外依赖 | 除 GsCore 本身外不引入任何第三方库 |
必须先部署好 GsCore。把仓库放进核心的插件目录:
cd <gsuid_core>/gsuid_core/plugins
git clone https://github.com/e0kt/TodayImage.git然后重启一次 GsCore。只有首次安装需要重启。
mkdir -p <gsuid_core>/data/TodayImage/黑丝
cp /some/pics/*.jpg <gsuid_core>/data/TodayImage/黑丝/私聊机器人发送 今日黑丝 即可出图,私聊可以一直发一直出新图。
群里还需要群管理员先发送 TodayImage允许黑丝(见下方分群授权),且群里每天每类型只给一张。
图片根目录默认就是 <gsuid_core>/data/TodayImage/,可在网页控制台改。
根目录下的每个一级文件夹就是一个类型,文件夹名即命令后缀:
data/TodayImage/
├── 黑丝/ → 今日黑丝
│ ├── a.jpg
│ └── 画师A/ 子目录会被递归扫描
│ └── b.png
├── 白丝/ → 今日白丝
│ └── c.jpeg
├── 制服/ ← 新建这个文件夹,就多了「今日制服」
│
├── config.json 这几个是插件自己的数据文件,
├── categories.json 是文件不是文件夹,不会被当成图片类型
├── daily_records.json
└── group_permissions.json
支持 .jpg .jpeg .png .webp .gif .bmp,其余文件和以 . 开头的(如 .DS_Store)都会被忽略。
不确定路径?主人发送
查看图片或今日图片帮助,机器人会打印当前的图片根目录与类型清单。
| 命令 | 说明 |
|---|---|
今日<类型> |
抽取当天该类型的图片,全天固定 |
Today<类型> |
同一张图,以聊天记录形式发送并附上图片ID |
今日图片帮助 |
查看用法;类型清单与管理命令仅主人可见 |
Today<类型> 的形式照搬 GsCore core更新 的通知 —— 聊天里只占一个气泡,点开每行一条:
群友: Today黑丝
机器人: [聊天记录]
你今天的黑丝来啦!
[图片]
类型:黑丝
图片ID:3f9a0c1e
抽取人:群友甲
- 与
今日<类型>是同一次抽取:群里先发哪个都一样,拿到的是同一张,不多给机会 Today后紧跟类型名,中间不能有空格(Today 黑丝不触发);大小写不限(today黑丝也行)- 授权、屏蔽、静默规则与
今日<类型>完全相同 - 记录里只有图片ID,不含文件名或路径;群聊里用昵称标明是谁的,不 @ 人
- 用途之一是删图:对这条记录回复
删除<类型>就按图片ID 精确删除(见下方回复删图)
| 命令 | 说明 |
|---|---|
TodayImage允许<类型> |
允许本群使用该类型 |
TodayImage禁止<类型> |
撤销,下一条消息即生效 |
TodayImage列表 |
查看本群已允许的类型 |
| 命令 | 说明 |
|---|---|
TodayImage重置<类型> |
清掉本群该类型当天的绑定,让群里所有人重新抽一张新图 |
主人: TodayImage重置黑丝
机器人: 已重置本群的【黑丝】,清除 3 条绑定,大家可以重新抽了。
- 只影响发送所在的群 + 指定的那一个类型 + 当天;其它类型、其它群、私聊不受影响
- 重置放开的是一次重抽,不是取消当日固定 —— 重新抽到的那张当天依然固定
- 同一天可以反复重置,每次都能拿到新图;次日随当天记录一并失效
- 权限比
TodayImage允许(群管理员可用)更严:重置会改变全群所有人当天已经拿到的结果
| 命令 | 说明 |
|---|---|
回复图片 + 删除<类型> |
把这张图从图库删掉,并让当天抽到它的人重新抽 |
用途是纠正 wd14 打标错误 —— 一张图被分到了错的类型里。
(对机器人发出的那张图回复)
管理员: 删除黑丝
机器人: 已删除【黑丝】的这张图,2 人可以重新抽了。
- 必须是回复,直接发命令不生效
- 图库是全局的,所以删除影响所有群;抽到过它的人(跨群跨用户)都能重抽
- 认不出是哪一张时不会删任何东西,而是提示改用
删除图片 <类型> <图片ID> - 标签写错(图在
白丝却写删除黑丝)会被拒绝,不做任何改动 - 默认群管理员即可使用:错标本身就是全局的,能发现的人修掉它对所有群都是净收益。 控制台的「删图仅限主人」可收紧为仅主人,适用于图库即原始数据的部署
它怎么认出是哪一张(逐级退让,越靠前越精确):
R. 被回复的是 Today<类型> 发出的聊天记录 —— 直接按记录里的图片ID 定位。
ID 是文字,不受 QQ 重新编码(吞图)、图片链接过期、核心重启影响;最推荐的删图方式
0. 直接拿被回复的那张图比对图库 —— 回复的是 今日<类型> 的裸图时走这条
- 消息 ID 命中发送回执 —— 精确
- 该群该类型当天只有一条抽图记录 —— 精确
- 时间窗内该群该类型最近发出的那张 —— 兜底,回复里会注明
- 仍不确定 —— 拒绝并提示改用
删除图片 <类型> <图片ID>
第 0 级先在该类型内做字节级比对(实测 7900 张里 8ms); 平台若重新编码,退到感知哈希,但只在当天该群的少数候选里找。
它不依赖发送回执(实测本项目在用的 OneBot 适配器不返回消息 ID), 也不怕核心重启 —— 后面几级用的内存表一重启就空了。 第 3 级兜底有「删图兜底时间窗」限制(默认 1 小时),设为 0 可禁用。
回复 Today 记录时的额外规则:
- 仍须写类型名:只发「删除」不会删,类型名就是对这次删除的确认;写错类型同样拒绝
- 记录里的图片ID 在该类型下对应多个同名文件(不同子目录)时拒绝,请在图库目录中手动处理
- 不校验记录来源(别的群转发来的、隔天的都按 ID 处理)—— 能删的只有有删图权限的人
- 若平台没把被回复记录的内容交给插件,自动退回上面第 0~4 级,与回复裸图时完全一样
| 命令 | 权限 | 说明 |
|---|---|---|
上传图片 <类型> |
主人 / 白名单 | 把消息附带的图片存进该类型文件夹 |
查看图片 [<类型>] |
主人 | 列出全部类型,或某类型下的图片与图片ID |
删除图片 <类型> [图片ID] |
主人 | 按ID删除单张,不带ID删除该类型全部 |
重载图片类型 |
主人 | 立即刷新缓存(可选,新文件夹本来就会自动生效) |
| 群聊 | 私聊 | |
|---|---|---|
| 需要授权 | 需群管理员 TodayImage允许<类型> |
不需要 |
| 抽图次数 | 每人每天每类型固定一张 | 不限次数,每次重抽 |
| 同群不撞图 | 是 | 不适用 |
| 写入每日记录 | 是 | 否 |
群聊里每个类型都需要群管理员先授权,这样一个机器人可以在不同群里用不同尺度。私聊完全不受限制。
管理员: TodayImage允许黑丝
机器人: 已允许本群使用【黑丝】。
群友: 今日黑丝
机器人: [图片]
群友: 今日白丝
机器人: (没有反应 —— 本群没开这个类型)
- 「群管理员及以上」= 群管理员 / 群主 / superuser / 主人(GsCore 的
user_pm <= 3) - 类型名两侧的括号和空格会自动去掉,
TodayImage允许【黑丝】和TodayImage允许 黑丝等价 - 授权与文件夹是否存在互不相干:可以先授权再建文件夹
- 黑名单优先于授权:就算建了个叫「老婆」的文件夹并授权,
今日老婆也仍然不会被本插件回复
Warning
群聊默认什么都不允许。 首次安装或升级到 v0.3 后,所有群都要由管理员逐个授权才能出图。
建议顺序:先想好每个群开哪些类型 → 重启 → 逐群 TodayImage允许<类型> → 用 TodayImage列表 核对。
想让新群默认带上一些类型,可在控制台设置「新群默认允许的类型」——
它只对还没有任何授权记录的群生效,不会把管理员撤销过的类型放回去。
插件不直接对接任何平台,消息由 GsCore 的适配器送进来,所以理论上适配器支持什么平台就能用什么平台。 为接入 Discord 这类频道型平台,插件侧做了这些准备:
GsCore 的 user_type 有四个取值:group / direct / channel / sub_channel。
Discord、KOOK、QQ 频道用的是 channel(服务器频道)和 sub_channel(线程),不是 group。
插件统一用 tdi/chat_context.py 判定,规则与核心自身一致(核心判私聊一律看 user_type != "direct"):
| 场景 | user_type |
group_id |
判定 | 授权键 |
|---|---|---|---|---|
| QQ 群 | group |
465… |
群聊 | 465… |
| QQ / Discord 私聊 | direct |
— | 私聊 | — |
| Discord 服务器频道(实测) | group |
9150…(snowflake) |
群聊 | 9150… |
频道型 user_type |
channel / sub_channel |
任意 | 群聊 | group_id |
频道但适配器没填 group_id |
channel |
None |
仍算群聊 | 空键 → 拒绝 |
适配器忘了给私聊设 direct |
group |
None |
私聊 | — |
| 适配器自造的新取值 | guild_forum |
任意 | 仍算群聊 | fail closed |
实测说明:本项目在用的 Discord 适配器发的是 user_type='group' + snowflake 形式的 group_id,
并不会用到 channel / sub_channel。表里那几行是为其它适配器准备的防御 ——
核心确实定义了这四种取值,换一个适配器就可能用上。
「频道但没填 group_id」那行是重点:若按 group_id is None 判私聊,这种事件会被当成私聊,
分群授权会被整个绕过。目前在用的适配器不会产生这种事件,但核心允许,所以插件有测试专门钉住这一条,
并禁止任何模块再用 group_id 做会话分类。
授权键就是 group_id。实测中 Discord 适配器对一个服务器只给一个 snowflake,
因此授权是按该 ID 生效,而不是按每个频道。若换成会逐频道下发不同 group_id 的适配器,
则每个频道都要单独授权;线程也不会继承父频道 —— 事件里拿不到父频道 ID,与其猜,不如 fail closed。
记录键含 bot_id,所以 Discord 的 DM 是 direct:discord:<uid>、QQ 的是 direct:onebot:<uid>,
同一个人在两个平台上互不干扰。
Important
Discord 适配器不映射服务器权限。 实测统计(本项目的生产日志):
user_pm |
Discord | QQ (OneBot) |
|---|---|---|
0 主人 |
19 | 923 |
2 群主 |
0 | 49 |
3 群管理员 |
0 | 308 |
6 普通用户 |
15 | 1554 |
Discord 侧只出现 0 和 6,且那些 0 全部来自 masters 配置里的账号。
QQ 侧有大量 2 / 3,对比鲜明。
后果:Discord 频道里 TodayImage允许 / TodayImage禁止 / TodayImage列表
只有机器人主人能用,服务器管理员会被当成普通用户拒绝。频道照常能发图,
只是授权得由主人代劳。
换别的 Discord 适配器前建议重测:让一个非主人的服务器管理员发条消息,
在 data/logs/ 里查该事件的 user_pm。
桥接端只在 QQ(OneBot)上把消息打包成聊天记录;其它平台会把记录的每一条拆成单独一条消息。
为免一次 Today黑丝 刷出 4~5 条,非 OneBot 平台上插件改发一条普通消息,内容相同
(文案、图片、类型:、图片ID:、抽取人:)。回复这条消息删图同样按其中的图片ID 定位。
Discord 对普通服务器有单文件上限(约 10MB)。插件的「单张图片大小上限」默认也是 10MB, 但那只限制上传;已在图库里的大图发送失败与否取决于适配器与平台,必要时自行压缩图库。
发送一个不存在的类型(例如 今日不存在),机器人不会有任何回复。
未知、被屏蔽、未授权、空文件夹这四种情况在外部完全无法区分 —— 这是刻意设计:
只要它们的回复有差别,任何人都能靠逐个试探把服务器上有哪些类型问出来。
排查请看 <gsuid_core>/data/logs/,每次静默都有 debug 日志说明原因(unknown / blocked / unauthorised / empty)。
管理员也可以用 TodayImage列表 查看本群的授权情况。
全部配置都在 GsCore 网页控制台,存放于 data/TodayImage/config.json,插件升级不会丢失。
| 配置项 | 默认 | 说明 |
|---|---|---|
| 启用今日图片 | 开 | 总开关 |
| 图片根目录 | 空 | 留空即 data/TodayImage 本身。改后需重启 |
| 命令前缀 | 今日 |
留空会退回 今日。改后需重启 |
| 抽图文案模板 | 你今天的{类型}来啦! |
可用 {类型} 变量 |
| 群聊中艾特发送者 | 开 | 私聊始终不艾特 |
| 删图兜底时间窗(秒) | 3600 |
认不出是哪一张时,删除该群该类型最近发出的那张;0 表示禁用兜底 |
| 删图仅限主人 | 关 | 开启后回复删图收紧为仅主人;普通群友在任何配置下都不能删 |
| 私聊不限次数 | 开 | 私聊每次重抽、不写每日记录;关闭则私聊也变成每天一张。群聊始终固定,不受此项影响 |
| 同群同类型不重复 | 开 | 图不够分时自动退回允许重复 |
| 每日重置时区(UTC偏移小时) | 8 |
按北京时间 0 点重置,不跟随服务器时区 |
| 新群默认允许的类型 | 空 | 只对没有授权记录的群生效 |
| 放行的命令 | 空 | 把某条命令从屏蔽名单里摘掉,用于「该类型已迁移过来、上游功能已关闭」的情况 |
| 不回复的命令 | 已含 TodayWaifu 今日系列 | 按前缀匹配,填写内容与默认名单合并 |
| 图片列表转发阈值 | 10 |
超过则用合并转发 |
| 图片上传白名单 | 空 | 主人无需加入 |
| 单张图片大小上限(MB) | 10 |
超限的上传计入失败 |
| 目录扫描缓存时间(秒) | 300 |
也决定新文件夹多久自动生效;0 表示每次都扫 |
每个类型的单独设置(启用 / 别名 / 文案)在 data/TodayImage/categories.json:
{
"version": 1,
"categories": {
"黑丝": { "enabled": true, "aliases": ["丝袜"], "caption": "今天的黑丝,请收好~" },
"白丝": { "enabled": false, "aliases": [], "caption": null }
}
}改完发送 重载图片类型 立即生效。
两个插件可以同时安装。TodayWaifu 的 今日老婆、今日萝莉、今日战双老婆 等命令都在默认屏蔽名单里,
本插件一律不回复 —— 即使真的建了一个叫 老婆 的文件夹也不会抢答。
反过来,本插件的动态触发器是非阻断的,不会吃掉任何其它插件的 今日X 命令。
测试里有一条会实际枚举 TodayWaifu 注册的所有 今日* 触发器并逐个断言在屏蔽名单内,
所以上游新增命令而这边忘了屏蔽时,测试会先红。
插件在仓库内开发,测试不需要安装 GsCore:
git clone https://github.com/e0kt/TodayImage.git
cd TodayImage
python -m unittest discover -s tests -v核心逻辑(图库扫描、类型解析、每日记录、分群授权、黑名单、图片解码、缓存)全是只依赖标准库的纯模块,
测试通过 importlib 直接加载文件,因此无核心、无机器人也能跑。
装进 GsCore 后再跑一次,会额外执行框架契约测试(sv.TL 形状、pm=3 权限闸门、TodayWaifu 命令屏蔽覆盖率):
PYTHONPATH=<gsuid_core>:<gsuid_core>/gsuid_core \
<gsuid_core>/.venv/bin/python -m unittest discover -s tests设计文档在 specs/,用 spec-kit 分三轮迭代写成,
每一轮都有 spec / research / plan / tasks,记录了做过的取舍和被否决的方案。
插件本身不附带任何图片内容。图片由部署者自行准备,请自行评估内容合规与平台风控风险。
本项目采用 GNU General Public License v3.0。
上游 gsuid_core 与 TodayWaifu 均为 GPL-3.0; 本插件的图片解码、文件缓存、目录扫描、私聊 at 剥离与原子写入等部分改编自 TodayWaifu, 相关模块头部均已注明出处。