koishi-plugin-arcade-queue-lite

一个面向 QQ 群的轻量 Koishi 机厅排队插件。数据按「平台 + 群号」隔离，支持机厅名称/别名、中英文更卡、加减运算、独立的总人数与分机人数、每台容量、平均/最长等待时间、自定义输出、过期提醒、定时清零、历史记录与撤销。

插件专注于群聊中的机厅人数维护与排队查询，不依赖外部联网服务，力求保持部署简单、操作直观、数据清晰。

运行要求

• Koishi 4.18+
• 一个已启用的 Koishi 数据库插件（推荐 database-sqlite）
• QQ/OneBot 不是硬性依赖，但本插件的权限识别已针对 QQ 群进行了兼容

主要设计

• 每个 QQ 群拥有独立的机厅和排卡数据。
• 普通成员默认可查询、可更卡；创建、改名、删除、清零等管理操作需要权限。
• 配置中的 adminUsers 是面向机器人维护者的全局管理员白名单，方便维护者跨群处理问题，无需在每个群申请 QQ 管理员。各群的群主和 QQ 群管理员可在自己的群内管理机厅，不需要加入此名单；是否识别他们由 allowGroupAdmins 控制。
• 总人数表示现场总量，通常由工作人员、刚到店的玩家或了解现场情况的人更新；这只是使用习惯，并非独立的 staff 权限。分机人数表示其中已经选择某台机器的人，更新分机不会改变总人数。
• 插件按“每人只计入一台机器”的口径统计，但不记录玩家名单，请由群内成员共同避免重复报卡。增加分机人数后若分机合计会超过总人数，操作会被拒绝；减少人数始终允许，便于修正旧数据。
• 把总人数改成正数且低于分机合计时，机器人会先询问：可按原比例缩减机台人数、仅修改总数或取消。把总人数改为 0 时会直接清空所有机台人数。
• 平均等待按 向上取整(总人数 ÷ 所有已记录机台容量之和) × 每轮分钟数 计算，采用总人数以给出偏保守的结果。
• 最长已知等待按排卡最多的已记录机台单独计算。两种时间都是估算，不是精准叫号承诺。

配置

| 配置项 | 默认值 | 说明 | |---|---:|---| | adminUsers | [] | 机器人维护者的全局管理员 QQ 号列表，建议维护者填写自己 | | allowGroupAdmins | true | 是否允许各群的群主和 QQ 群管理员管理本群机厅 | | allowMemberUpdate | true | 普通成员是否可更卡 | | enableShortcuts | true | 是否启用 dkq几、dkqj、dkq+1 等快捷输入 | | defaultMachineCount | 2 | 新机厅默认机台数 | | defaultAverageRoundMinutes | 12 | 每轮平均分钟数 | | defaultPlayersPerRound | 1 | 新建机台的默认每轮容量 | | maximumCount | 999 | 防止误输入的人数上限 | | historyLimit | 20 | 每个机厅保留的撤销历史数 | | compactUpdateReply | true | 更卡后只回一行摘要，减少刷屏 | | enableFuzzySuggestions | true | 别名输错一个字时给出建议 | | enableStaleWarning | true | 提醒久未更新的总人数/机台 | | totalStaleMinutes | 60 | 总人数过期阈值（分钟） | | machineStaleMinutes | 30 | 分机数据过期阈值（分钟） | | enableAutoClear | false | 是否启用统一时间的每日自动清零总开关 | | autoClearHour / autoClearMinute | 4 / 0 | 自动清零时间 | | autoClearTimezone | Asia/Shanghai | 自动清零使用的时区 | | autoClearMode | all | 清零全部，或只清机台 | | defaultOutputTemplate | 内置模板 | 新机厅的默认查询模板 | | arcades | [] | 在 Koishi 配置栏中直接建立和编辑机厅预设 |

在 Koishi 配置栏建立机厅

展开插件配置中的「机厅预设（控制台配置）」并点击「添加项目」。每一项可以填写：

• enabled：是否启用
• key：稳定的内部标识，例如 dkq，建立后不要随便修改
• groupIds：允许使用的 QQ 群号；可填多个，留空表示所有群
• name：机厅完整名称
• aliases：别名和缩写
• machineNames：机台名称
• initialTotalCount / initialMachineCounts：首次创建时的初始人数
• avgRoundMinutes：每轮平均时长
• machineCapacities：每台机每轮容量，与机台名称逐项对应；目前一人一机时全部填 1
• notice：醒目公告
• remark：自由备注
• queryTemplate：这家机厅独立的查卡输出格式
• autoClearEnabled：全局自动清零开启时，这家机厅是否参与；全天营业的机厅可以关闭

保存插件配置后，名称、别名、机台、参数、公告、备注和模板会同步到数据库。正在使用的实时总人数、分机台人数和历史记录不会被覆盖。初始人数只在第一次创建该机厅时使用。

如果同一家机厅需要在多个群里共用设置，只需在 groupIds 中加入多个群号；每个群的实时人数仍然独立。

第一次使用

先在插件配置的 adminUsers 中填写自己的 QQ 号，然后在目标群发送：

机厅添加 迪卡丘嘉年华（佳和店） -a dkq,迪卡丘,佳和 -m 2

随后即可查询：

机厅查询 dkq
查卡 迪卡丘
dkq几
dkqj

查询效果示例

🎮 迪卡丘嘉年华
👥 当前共 8 人｜已分机 5 人｜未分配 3 人
• 舞萌1：3 人｜约 36 分钟｜容量 1｜刚刚（玩家甲）
• 舞萌2：2 人｜约 24 分钟｜容量 1｜2 分钟前（玩家乙）
• 未分配到已记录机台：3 人
⏱ 全场平均等待：约 48 分钟
⏳ 最长已知等待：约 36 分钟（舞萌1）
🕒 总人数：刚刚（值班员）

其中“当前共”表示现场总人数，“已分机”表示已经写入各个已记录机台的人数合计，“未分配”也可能包含正在休息、围观或使用未记录机台的人。机台人数包含正在游玩的玩家。等待时间仅供参考；有人离开、轮次长短变化或数据较久未更新时，请以现场情况为准。

更卡

更新总体人数

更卡 dkq 10
更卡 dkq +2
更卡 dkq -1
更卡 迪卡丘 加3
更卡 迪卡丘 减2
queue dkq set 8
queue dkq add 2
queue dkq sub 1

启用快捷输入后，也可以直接发送：

dkq10
dkq+2
迪卡丘-1

支持的表达式：

• 绝对值：10、设为10、=10、set 10
• 增加：+2、加2、增加2、add 2、plus 2
• 减少：-2、减2、减少2、sub 2、minus 2
• 清零：清零、清空、clear、reset

如果新的总人数大于 0、但小于当前机台人数合计，机器人不会立即写入，而会要求在 60 秒内回复：

• 确认调整：总人数生效，并按各机台原有占比缩减机台人数
• 仅改总数：只改总人数，保留机台数据并显示不一致警告
• 取消：本次不作修改

把总人数更新为 0 时无需确认，总人数和所有机台人数会一起归零。

更新单台机器

更卡 dkq 1号机 +1
更卡 dkq #2 减1
更卡 dkq 2 +1
dkq1号机+1
dkq#2-1

更新某台机器不会改变总人数。例如总人数是 10，1 号机从 2 人改成 4 人后，总人数仍是 10，已分机人数增加 2。若分机合计将超过 10，插件会要求先更新总人数。

命令速查

机厅列表 和 机厅记录 可由普通成员查看；添加、改名、参数调整、清零、撤销和删除等修改操作需要管理员权限。修改记录只提供查看，不支持手动编辑。

机厅列表
机厅添加 <名称> -a <别名1,别名2> -m <机台数>
机厅别名 <名称/别名> <新别名1,新别名2>
机厅改名 <名称/别名> <新名称>
机厅机台 <名称/别名> <机台数>
机厅机台命名 <名称/别名> <名称1,名称2,...>
机厅参数 <名称/别名> <每轮分钟> [全部机台容量]
机厅容量 <名称/别名> <机台名或序号> <容量>
机厅自动清零 <名称/别名> [开启/关闭]
机厅公告 <名称/别名> [公告内容]
机厅备注 <名称/别名> [备注内容]
机厅模板 <名称/别名> [模板内容]
机厅记录 <名称/别名>
机厅撤销 <名称/别名>
机厅清零 <名称/别名>
机台清零 <名称/别名>
机厅删除 <名称/别名> --confirm

机厅机台命名 示例：

机厅机台命名 dkq 舞萌1,舞萌2,中二
更卡 dkq 中二 +2
机厅容量 dkq 中二 1

自动清零

自动清零使用插件配置中的统一时间、时区和清零模式。开启全局 enableAutoClear 后，只有自身 autoClearEnabled 同时开启的机厅才会参与；关闭该项的全天营业机厅不会被自动清零。

管理员可以在群内查看或修改单个机厅的状态：

机厅自动清零 dkq
机厅自动清零 dkq 开启
机厅自动清零 dkq 关闭

通过 Koishi 配置栏预设建立的机厅，也可以直接编辑该预设的 autoClearEnabled。保存或重载预设配置后，配置栏中的值会同步到数据库。

自定义输出

发送 机厅模板 dkq 可以查看当前模板及变量。可用变量：

• {name}：机厅名称
• {aliases}：全部别名
• {total}：总体人数
• {machines}：分机台明细
• {machineTotal}：分机台合计
• {assigned}：已分机人数（同 {machineTotal}）
• {unassigned}：尚未分到已记录机台的人数
• {difference}：总体人数减分机合计
• {capacity}：已记录机台的总容量
• {wait} / {averageWait}：按总人数估算的全场平均等待
• {longestWait}：最长已知等待
• {longestMachine}：最长等待对应的机台
• {notice}：带 📢 前缀的公告
• {noticeRaw}：不带前缀的公告原文
• {remark}：带 📝 前缀的自由备注
• {remarkRaw}：不带前缀的备注原文
• {updatedAt}：更新时间
• {updatedBy}：更新者
• {totalAge} / {totalUpdater}：总人数距今多久、由谁更新
• {stale}：过期或数据不一致提醒

例如：

机厅模板 dkq 🎮 {name}\n现在 {total} 人，预计等待 {wait}\n{machines}\n{notice}\n{remark}

更推荐在 Koishi 配置栏的 queryTemplate 中编辑模板，那里可以直接输入多行内容。模板中也可以写任意固定文字，例如交通提醒、营业时间、价格、群规或店内活动；只有花括号变量会被自动替换。

数据与隐私

• 机厅配置、排卡人数、更新时间、更新者显示名称或用户 ID，以及用于撤销的历史记录，保存在机器人使用的 Koishi 数据库中。
• 数据按「平台 + 群号」隔离，不同群聊拥有各自独立的实时人数。
• 插件本身不请求外部接口，也不会主动向外部服务上传排卡数据。
• 机器人维护者应自行保护数据库、插件配置和备份文件，并根据所在群的实际情况设置管理权限。

安装

在 Koishi 控制台的插件市场中搜索 arcade-queue-lite，安装后进入插件配置并启用。使用前请确认数据库插件（例如 database-sqlite）已经启用。

如需通过本地安装包部署，可以把 .tgz 上传到 VPS，然后执行：

docker cp koishi-plugin-arcade-queue-lite-0.3.2.tgz koishi:/koishi/
docker exec -it koishi sh
cd /koishi
yarn add koishi-plugin-arcade-queue-lite@file:./koishi-plugin-arcade-queue-lite-0.3.2.tgz
exit
docker restart koishi

重启后进入 Koishi 控制台：

1. 确保 database-sqlite 已启用。
2. 停用其他使用相同命令名的排队插件，避免命令冲突。
3. 添加并启用 arcade-queue-lite。
4. 在 adminUsers 中添加自己的 QQ 号。
5. 在测试群执行 机厅帮助。

开发

npm install
npm test
npm pack

License

MIT