用 Koishi 做一个群聊机厅排队插件

它解决什么问题

arcade-queue-lite 是一个面向 QQ 群的轻量 Koishi 插件，用来维护机厅当前总人数、各机台人数和等待时间估算。群成员可以直接在聊天中查卡或更新人数，管理员则可以维护机厅、机台、公告和清零规则。

数据按“平台 + 群号”隔离。即使多个群配置了同一家机厅，每个群的实时人数也彼此独立。

安装

运行环境需要 Koishi 4.18 或更高版本，以及一个已经启用的数据库插件，推荐使用 database-sqlite。

在 Koishi 控制台的插件市场搜索 arcade-queue-lite，安装并启用插件。也可以在 npm 包页面 查看公开包信息。

截至 2026 年 9 月 9 日，Koishi 官方索引与 npm 的公开最新版是 0.3.2。本文同时介绍本地后续开发版 0.3.5 中的功能；商店尚未更新时，部分新功能可能不可用。

基础配置

第一次使用前建议检查这些配置：

• adminUsers：机器人维护者的管理员账号列表。
• allowGroupAdmins：是否允许群主和群管理员管理本群机厅，默认开启。
• allowMemberUpdate：是否允许普通成员更卡，默认开启。
• enableShortcuts：是否启用“别名几”“别名j”“别名+1”等快捷输入，默认开启。
• enableStandaloneJShortcut：是否允许只发送 j 查卡，默认关闭。
• arcades：通过控制台配置机厅名称、别名、机台和可用群。

在“机厅预设”中可以设置稳定的内部标识、可用群、名称、别名、机台名称、每轮时长、机台容量、公告、备注和查询模板。保存静态配置不会覆盖群内正在使用的实时人数和历史记录。

查询与汇总

配置好机厅后，群成员可以这样查询：

机厅查询 星光机厅
查卡 星光
星光几
星光j
jtj

jtj 会列出当前群全部已启用机厅的名称和总人数。

在 0.3.5 中，如果开启 enableStandaloneJShortcut，并且当前群恰好只有一家已启用机厅，也可以直接发送：

j

这个判断按群独立进行。有多家机厅时仍需使用“别名j”，避免查错。

更新人数

总体人数支持绝对值和加减运算：

更卡 星光 10
更卡 星光 +2
更卡 星光 -1
星光+1

也可以更新指定机台：

更卡 星光 1号机 +1
星光#2-1

总人数与分机人数是两个不同的统计口径。更新某台机器通常不会改变总人数；如果分机合计将超过总人数，插件会拒绝写入并提示先修正总数。只有一台机器的机厅可直接更新机厅人数，此时总人数和唯一机台人数同步。

管理与安全边界

普通成员默认可以查询和更卡。创建、改名、删除、清零、撤销及参数调整等管理操作需要机器人维护者、群主或群管理员权限，具体取决于插件配置。

插件还支持过期提醒、每日自动清零、修改历史与撤销、自定义查询模板。等待时间根据人数、机台容量和每轮时长估算，只适合作为现场参考，不是叫号承诺。

机厅配置、人数、更新时间、更新者标识和撤销历史保存在 Koishi 使用的数据库中。插件本身不请求外部接口，也不会主动上传排卡数据；机器人维护者仍需保护数据库、配置和备份，并按群的实际情况设置管理权限。

当前版本状态

公开商店版 0.3.2 可通过 Koishi 插件市场安装。本地 0.3.5 已继续加入按群判断的单独 j、jtj 汇总、预设群过滤和单机厅快捷更新等能力。待新版发布到 npm 并被 Koishi 官方索引收录后，商店用户才能直接获取这些后续改进。