TodayWaifu 完整使用指南与配置手册
TodayWaifu 是一款专为 GsCore(早柚核心)机器人框架开发的多游戏角色抽取与互动娱乐插件。插件支持鸣潮、战双帕弥什、异环等多个游戏角色的抽取,并提供群友抽取、抢夺、赠送、离婚等丰富的社群互动机制,同时支持本地图库与远程统一鉴权图库两种数据加载方案。
本文档作为插件的详细配置与使用指南,覆盖全部功能指令、控制台配置项说明及图库接入规范。
目录
- 一、系统要求与安装方式
- 二、功能指令手册
- 1. 每日角色抽取
- 老婆列表与汇总
- 老婆互动与社交玩法
- 今日萝莉与今日正太
- 自定义老婆角色库
- 三、控制台详细配置说明
- 1. 图片数据源设置
- 缓存与性能优化
- 游戏专项与面板路径
- 群友互动配置
- 基础回复与图片压缩
- 抢夺与赠送机制
- 权限与白名单设置
- 帮助图与外观定制
- 四、远程图库与令牌鉴权
- 五、社区图库共建(WaifuHub)
- 六、常见问题与故障排查
一、系统要求与安装方式
1. 运行前提
- 已正确安装并成功运行 GsCore(早柚核心) 框架;
- Python 运行环境建议 3.10 及以上;
- 机器人适配端正常连接(OneBot V11、QQ 官方机器人平台、KOOK、Telegram 等平台均可)。
2. 安装方式
方式一:机器人指令一键安装
在任意已连接 GsCore 的管理群或私聊窗口向机器人发送:
CodeBlock Loading...
方式二:Git 手动克隆
进入 GsCore 部署目录下的插件目录执行克隆:
CodeBlock Loading...
安装完成后,请在终端重启 GsCore 服务,或在控制台重载插件以完成全部初始化。
二、功能指令手册
在群聊或私聊中直接发送以下指令即可触发相应功能。
1. 每日角色抽取
每位用户每天固定只能抽取一次,抽取结果当天有效。
| 指令名称 | 触发示例 | 权限要求 | 说明 |
|---|---|---|---|
| 今日老婆 | 今日老婆 | 无 | 抽取今天的老婆角色,默认抽取鸣潮女角色。 |
| 今日老公 | 今日老公 | 无 | 抽取男神角色,默认抽取鸣潮男角色,需在控制台开启。 |
| 今日异环老婆 | 今日异环老婆 | 无 | 抽取异环角色,需在控制台开启相应功能。 |
| 今日战双老婆 | 今日战双老婆 | 无 | 抽取战双帕弥什角色,主人或白名单用户可在命令后附加角色名指定抽取。 |
| 上传战双老婆图片 | 上传战双老婆图片 露西亚 | 主人或上传白名单 | 为已存在的战双角色文件夹上传补充图片。 |
| 今日普通老婆 | 今日普通老婆 | 无 | 从全网经典动漫角色库中抽取,支持附加作品或角色名。 |
2. 老婆列表与汇总
| 指令名称 | 触发示例 | 权限要求 | 说明 |
|---|---|---|---|
| 老婆列表 | 老婆列表 | 无 | 查看本群内今天所有已抽取老婆的群友汇总名单。 |
| 老公列表 | 老公列表 | 无 | 查看本群内今天所有已抽取老公的群友汇总名单。 |
| 普通老婆列表 | 普通老婆列表 | 无 | 查看本群内今天所有已抽取普通动漫老婆的汇总名单。 |
3. 老婆互动与社交玩法
| 指令名称 | 触发示例 | 权限要求 | 说明 |
|---|---|---|---|
| 抢老婆 | 抢老婆 @某人 | 无 | 按概率抢夺对方今日抽到的老婆,成功后归自己所有。 |
| 抢老公 | 抢老公 @某人 | 无 | 按概率抢夺对方今日抽到的老公。 |
| 送老婆 | 送老婆 @某人 | 无 | 将自己今日的老婆赠送给对方,对方同意后转让。 |
| 接受老婆赠送 | 接受老婆赠送 | 无 | 收到赠送提醒后,发送此命令确认接受赠送。 |
| 拒绝老婆赠送 | 拒绝老婆赠送 | 无 | 拒绝对方的送老婆请求。 |
| 送老公 | 送老公 @某人 | 无 | 将自己今日的老公赠送给对方。 |
| 接受老公赠送 | 接受老公赠送 | 无 | 确认接收送来的老公。 |
| 拒绝老公赠送 | 拒绝老公赠送 | 无 | 拒绝对方的送老公请求。 |
| 离婚 | 离婚 | 无 | 主动放弃今天的老婆,放弃后不可再抽。 |
| 老公离婚 | 老公离婚 | 无 | 主动放弃今天的老公。 |
| 娶群友 | 娶群友 | 无 | 从当前群聊成员缓存中随机迎娶一位群友作为今日老婆。 |
4. 今日萝莉与今日正太
| 指令名称 | 触发示例 | 权限要求 | 说明 |
|---|---|---|---|
| 今日萝莉 | 今日萝莉 | 无 | 抽取今天的萝莉图片,抽取后支持抢夺、赠送。 |
| 抢萝莉 | 抢萝莉 @某人 | 无 | 按照配置概率抢夺对方今天的萝莉。 |
| 送萝莉 | 送萝莉 @某人 | 无 | 将今日萝莉赠送给指定群友。 |
| 接受萝莉赠送 | 接受萝莉赠送 | 无 | 同意接受赠送的萝莉。 |
| 拒绝萝莉赠送 | 拒绝萝莉赠送 | 无 | 拒绝对方赠送的萝莉。 |
| 萝莉离婚 | 萝莉离婚 | 无 | 放弃今日萝莉。 |
| 上传萝莉图片 | 上传萝莉图片 [附带图片] | 主人或上传白名单 | 上传萝莉图片到本地图库中。 |
| 查看萝莉图片 | 查看萝莉图片 | 主人或上传白名单 | 查看本地萝莉图库中的全部图片及对应图片编号。 |
| 删除萝莉图片 | 删除萝莉图片 8位ID | 主人或上传白名单 | 删除指定图片编号的图片;不带ID会清空本地库。 |
| 今日正太 | 今日正太 | 无 | 抽取今天的正太图片。 |
| 抢正太 / 送正太 | 抢正太 @某人 / 送正太 @某人 | 无 | 正太的抢夺与赠送交互。 |
| 正太离婚 | 正太离婚 | 无 | 放弃今日正太。 |
5. 自定义老婆角色库
服主可完全脱离游戏限制,自行创建任意自定义二次元角色。
| 指令名称 | 触发示例 | 权限要求 | 说明 |
|---|---|---|---|
| 创建老婆 | 创建老婆 达妮娅 | 机器人主人 | 创建一个新的自定义角色目录。 |
| 上传老婆图片 | 上传老婆图片 达妮娅 [图片] | 主人或上传白名单 | 为该自定义角色上传绑定的展示插画。 |
| 查看老婆图片 | 查看老婆图片 达妮娅 | 主人或上传白名单 | 查看该角色名下所有已上传的图片列表。 |
| 删除老婆 | 删除老婆 达妮娅 | 机器人主人 | 删除该自定义角色及其所有本地图片。 |
| 分配老婆 | 分配老婆 @某人 达妮娅 | 主人或分配白名单 | 强制为指定群友分配今日老婆,覆盖其当天记录。 |
三、控制台详细配置说明
打开 GsCore 网页控制台,进入「插件配置」并定位到 TodayWaifu,即可看到以下所有配置项。
以下所有配置项均采用控制台实际展示的中文名称进行逐项说明。
1. 图片数据源设置
- 图片数据源
- 可选项:
local(本地模式)/gallery(远程图库模式) - 说明:控制「今日老婆」和「今日老公」的基础图片获取途径。选
local时只读取服务器本地角色图片目录,适合服务器本地存有大量壁纸立绘的服主;选gallery时自动通过远程图库接口拉取在线精选图。
- 可选项:
- 异环老婆图片数据源
- 可选项:
local/gallery - 说明:选
local时仅使用本地异环目录图片;选gallery时在本地缺图时自动从 NTEUID 官方资源库兜底加载。
- 可选项:
- 战双老婆图片数据源
- 可选项:
local/gallery - 说明:选
local时仅使用本地战双图库目录;选gallery时优先通过远程图库拉取战双高清插画,接口不可用时自动回落本地。
- 可选项:
- 萝莉图片数据源
- 可选项:
local/gallery - 说明:控制今日萝莉的图片来源。
- 可选项:
- 本地角色图片目录
- 默认值:留空
- 说明:数据源为
local时生效。留空时系统会自动寻找gsuid_core/data/XutheringWavesUID/custom_role_pile目录。
- 图库接口统一地址
- 默认值:
https://twfapi.xlinxc.cn - 说明:所有远程图库模式的数据分发接口,集中服务于鸣潮、战双、普通老婆、萝莉、正太等所有远端接口。
- 默认值:
- 图库访问令牌
- 默认值:留空
- 说明:远程图库接口开启鉴权后必填。可前往
https://twf.xlinxc.cn申请,或加入交流群获取。填入后插件在拉取列表及下载图片时会自动带上签名鉴权。
- 启用普通老婆
- 默认值:关闭
- 说明:开启后可使用「今日普通老婆」抽取全网经典动漫角色。
- 今日普通老婆文字模板
- 默认值:
你今天的老婆是来自{role_id}的{name}! - 变量支持:
{name}代表角色名称,{role_id}代表所属作品名称。
- 默认值:
2. 缓存与性能优化
- 零点前预热图库图片
- 默认值:开启
- 说明:每天 23:20 自动开始以低速率对次日候选角色的图片进行提前本地下载,避免次日凌晨全群群友集中抽取时发生瞬时下载拥堵或失败。
- 每个角色预热图片数
- 默认值:
2(范围 0 ~ 20) - 说明:预热扫描时为每位候选角色预先下载的图片张数。数值越大首抽命中本地缓存率越高,但会消耗更多带宽与磁盘空间。
- 默认值:
- 图库缓存容量上限(MB)
- 默认值:
512 - 说明:本地缓存图片的总存储上限。当缓存总体积超出设定值时,系统会自动删除最旧的缓存文件;设为
0代表不限制容量。
- 默认值:
- 每日记录保留天数
- 默认值:
30 - 说明:数据库中抽取记录的历史保存天数。超出天数的记录会在每日维护时自动清理,防止数据库长期运行后体积膨胀。
- 默认值:
3. 游戏专项与面板路径
- 启用今日异环老婆
- 默认值:关闭
- 说明:开启后群内方可使用「今日异环老婆」系列指令。
- 异环角色 ID 对照表路径
- 默认值:留空(自动读取插件内置对照表)
- 异环自定义面板图目录
- 默认值:留空(自动查找
gsuid_core/data/NTEUID/custom/panel)
- 默认值:留空(自动查找
- 异环默认角色立绘目录
- 默认值:留空(自动查找
gsuid_core/data/NTEUID/role/detail)
- 默认值:留空(自动查找
- 今日异环老婆文字模板
- 默认值:
你今天的异环老婆是{name}。 - 变量支持:
{name}代表角色名,{role_id}代表角色编号。
- 默认值:
- 启用今日战双老婆
- 默认值:开启
- 说明:开启后可使用「今日战双老婆」或别名「jrzslp」从本地战双图库抽取。
- 战双老婆图库目录
- 默认值:留空(默认使用
data/TodayWaifu/pgr_wife) - 说明:在目录下为每个战双角色建立同名子文件夹,角色图片放入其中即可自动识别。
- 默认值:留空(默认使用
- 今日战双老婆文字模板
- 默认值:
你今天的战双老婆是{name}。
- 默认值:
4. 群友互动配置
- 今日老婆概率抽群友
- 默认值:关闭
- 说明:开启后,群友使用「今日老婆」时有概率直接抽中当前群内的真实群友,未命中时回退抽取常规角色。
- 今日老婆抽群友概率
- 默认值:
0.1(即 10%) - 说明:0 到 1 之间的小数。
- 默认值:
- 今日老婆抽群友文字模板
- 默认值:
你今天的老婆是{name} - 变量支持:
{name}群友昵称,{user_id}群友账号。
- 默认值:
- 启用娶群友
- 默认值:关闭
- 说明:开启后允许使用独立的「娶群友」命令。
- 娶群友文字模板
- 默认值:
你娶到的群友是{name}
- 默认值:
5. 基础回复与图片压缩
- 发送文字说明
- 默认值:开启
- 说明:关闭后只发送角色图片,不再附加文字模板内容。
- 发送时艾特触发者
- 默认值:开启
- 说明:回复时是否艾特使用指令的用户。
- 显示角色 ID
- 默认值:关闭
- 说明:开启后在文字说明下方额外附加一行「角色ID:xxx」,便于排查角色配置。
- 显示触发者 ID
- 默认值:关闭
- 说明:开启后在文字底部显示当前用户的账号 ID,方便在 QQ 官方机器人等平台上群友互相复制识别码进行互动。
- 发送角色剧情与对话台词
- 默认值:关闭
- 说明:开启后在老婆抽取回复中自动随机附带一条角色的专属好感台词或游戏内剧情语录。
- 角色图片最大体积(MB)
- 默认值:
2(范围 0 ~ 50) - 说明:为适应官方机器人或严格风控平台的上传限制,当发送图片超出该阈值时,插件会自动将图片转为高质量 WebP 格式压缩至该限制以内;设为
0代表不进行任何压缩。
- 默认值:
- 主人 Debug 模式
- 默认值:关闭
- 说明:开启后机器人主人每次抽取都强制重新随机生成结果,不读取也不保存当天的每日记录,方便管理测试。
6. 抢夺与赠送机制
- 启用抢老婆 / 启用抢老公 / 启用抢萝莉 / 启用抢正太
- 默认值:开启
- 说明:控制各模式抢夺指令的开放状态。
- 抢老婆/老公成功率
- 默认值:
0.5(即 50% 概率)
- 默认值:
- 抢萝莉成功率 / 抢正太成功率
- 默认值:
0.5
- 默认值:
- 启用送老婆 / 启用送老公 / 启用送萝莉 / 启用送正太
- 默认值:开启
- 说明:控制赠送指令的开关。赠送流程需要接收方在群内回复确认才可正式完成过户。
- 各类成功文案模板
- 支持分别自定义抢夺成功、赠送成功的通知文案,可用变量包括
{name}(角色名)、{role_id}(角色编号)、{target}(目标用户)。
- 支持分别自定义抢夺成功、赠送成功的通知文案,可用变量包括
7. 权限与白名单设置
- 图片上传白名单
- 说明:允许使用「上传老婆图片」、「上传萝莉图片」、「上传战双老婆图片」的用户 ID 列表。机器人主人默认拥有所有权限,无需重复填入。
- 指定老婆白名单
- 说明:允许在抽取指令后直接附加角色名称进行指定抽取的特权用户名单。
- 分配老婆白名单
- 说明:允许使用「分配老婆 @某人 角色名」强制为他人指派角色的用户名单。
8. 帮助图与外观定制
- 帮助横幅图:自定义「今日老婆帮助」顶部横幅图像。
- 帮助背景图:自定义帮助长图的底层背景图片。
- 帮助头像:自定义帮助图左上角展示的机器人头像。
- 帮助展示行数:默认
4行,控制每组指令在卡片中的排列高度。
四、远程图库与令牌鉴权
为确保图片分发速度与内容质量,TodayWaifu 提供了云端统一图库。
- 图库模式特点:
- 自动聚合多部作品的高清壁纸与插画,随版本自动更新;
- 包含故障自动熔断降级机制,当远端网络发生抖动时,系统会自动平滑降级到本地缓存或本地资源,避免机器人报错超时。
- 鉴权令牌获取:
- 访问自助申请平台:https://twf.xlinxc.cn 申请授权;
- 或加入官方交流 Q 群 798949533 向管理员申请;
- 获取后在 GsCore 控制台将令牌填入「图库访问令牌」配置项即可生效。
五、社区图库共建(WaifuHub)
为了让更多二次元爱好者能够参与到图库建设中,项目设立了完全开源的公共图片提交仓库:
- 仓库地址:https://github.com/MimoKit/WaifuHub
- 目录规范:
- 游戏角色按
游戏名/女角色/角色名/或游戏名/男角色/角色名/归类; - 萝莉与正太分别设有顶层独立目录
萝莉/与正太/,无子文件夹;
- 游戏角色按
- 零门槛提交:
- 网页端直接进入对应目录点击「Upload files」上传高清插画(建议 1080P 以上全年龄向内容);
- 提交 Pull Request,管理员审核合并后将定期自动同步至图库接口分发给所有部署 Bot。
六、常见问题与故障排查
- 发送图片报 403 权限错误:
- 检查控制台中「图库访问令牌」是否已填写且有效;如已过期请前往官网重新获取。
- 抽取结果图片发送超时或报 send_msg timeout:
- 检查「角色图片最大体积(MB)」配置项,建议设置为 2MB 到 3MB 之间,避免因原始插画体积过大(如 20MB 以上原图)导致上传超时。
- 本地模式找不到图片:
- 确认「本地角色图片目录」路径配置正确,并检查服务器文件系统读取权限是否已赋予机器人进程。
- 更换角色对照表后未更新:
- 重启 GsCore 服务即可刷新内置的角色对照缓存。