搜索官方目录
.maiarc.search 上海关键词至少两个字；结果较多时用 n / p 翻页，用 q 退出。
文档 / Maimai 排卡指南版本 2026.10
A LITTLE GUIDE FOR YOUR NEXT PLAY
出发前，
先看看有几卡。
从群聊里的一次查卡，到跨群共享的机厅人数。
这份指南整理了常用指令、管理操作与 HTTP API 的接入方式。
.maiarc机器人命令前缀
04:00 UTC+8每日排卡维护时间
79 ENDPOINTS独立 HTTP 业务接口
01 /
三步开始使用
以下用「家」作为机厅别名，ID 仅为示例，请替换成真实搜索结果。
取一个顺手的名字
.maiarc.add 12345 家由群主、群管理员或超级用户执行。别名只在本群生效。
查卡，也顺手报卡
家几 / 家+1 / 家=5同一个机厅ID的数据跨群共享。到店或离店时及时更新。
先绑定，再查卡机器人只识别本群已绑定的别名。不同群可以用不同名称指向同一个机厅，删除群别名不会删除共享机厅数据。
02 /
日常查卡与设卡
查询机厅卡数群成员
查询本群别名对应的当前人数。想看全部机厅时，发送 jtj 或 .maiarc.lookup。
家几 家有多少人 jtj .maiarc.lookup
返回卡数、最近更新、查询次数及补充说明。卡数由用户上报，不代表机器实时检测。
增加、减少或直接设定卡数群成员
家+1 家-1 家=5
分别表示增加1人、减少1人、设为5人。普通更新单次变化最多30人，减少到负数时按0处理。只读机厅不允许普通更新。
给本次人数补充说明更新本人
在QQ中回复机器人针对你这次人数更新的消息，写入不超过50字的说明。
包括旁边休息的两人，未计算围观
仅该次更新本人可用。下一次人数更新会清除旧说明；HTTP接口另需最新 operation_id。
搜索官方机厅与翻页可用群成员
.maiarc.search 上海 天空 n p q
多个关键词同时匹配，可用数字跳页。搜索使用官方目录缓存，自定义机厅不出现在官方目录中。退出搜索后再发送其他指令。
积分、排行榜与年度报告群成员
.maiarc.mypoints .maiarc.leaderboard 我的年度报告 群年度报告
也可用「我的积分」「积分榜」。年度报告查询上一年度已生成的报告，不会在发送指令时自动生成；没有数据时可能没有报告。
查看帮助、封禁状态或退出会话群成员
.maiarc.help .maiarc.banlookup 取消
banlookup 默认查看本人，也可加QQ号。交互会话默认120秒过期，发送「取消」可结束。
03 /
群管理员操作
以下命令由群主、群管理员或配置的超级用户执行。
绑定或删除本群机厅别名管理员
.maiarc.add 12345 家 .maiarc.del 家
ID来自机厅搜索；别名不能带空格。同名绑定会覆盖本群旧映射。删除别名只解除本群绑定，不影响其他群和机厅数据。
添加官方目录里没有的机厅管理员
.maiarc.addcustom 自定义机厅 上海某路 上海 2 .maiarc.add 返回的自定义ID 家
参数依次为名称、地址、可选省份、可选机台数，字段自身不要包含空格。创建后还需要另行绑定别名。也可只发送 .maiarc.addcustom 按提示输入。
回滚最近一次人数修改管理员
.maiarc.rollback 家 家回滚
两种写法任选其一。同一笔历史只能回滚一次；只读机厅不能回滚。操作者获3分，被回滚的其他更新者扣20分，最低0分。
封禁与解封人数更新管理员
.maiarc.banuser 123456 1 反复误报卡数 .maiarc.unbanuser 123456 .maiarc.banlookup 123456
时长以小时为单位，支持小数。普通管理员只管理当前群；全局封禁和指定其他群范围由超级用户管理。
刷新官方机厅目录管理员
.maiarc.refreshwahlap
当搜索缺少机厅或目录过旧时使用。刷新目录不会替代群成员上报当前卡数；网络异常时保留缓存。
04 /
积分与使用规则
| 操作 | 积分变化 | 说明 |
|---|---|---|
| 成功更新人数 | +5 | 增加、减少或设置人数 |
| 查询单个机厅 | +1 | 通过常规单厅查询 |
| 批量查询本群机厅 | +2 | jtj / .maiarc.lookup |
| 添加别名 | +10 | 绑定本群机厅 |
| 执行回滚 | +3 | 管理员完成一次回滚 |
| 更新被他人回滚 | −20 | 最低扣至0分 |
| 触发更新频率熔断 | 清零 | 当前群封禁15分钟 |
报卡不是刷分60秒内允许15次人数更新，继续操作会触发当前群15分钟封禁并清零积分。请按实际情况报卡。HTTP关键词批量搜索接口本身不计积分。
北京时间每日04:00维护清空可写机厅人数、查询次数、回滚状态和补充说明；只读机厅保留人数，仅重置查询次数。独立API调度默认关闭，部署时指定一方负责维护。
05 /
超级用户管理
清空、强制更新与只读状态超级用户
.maiarc.clearone 家 .maiarc.clearall .maiarc.forceupdate 12345 10 set 现场校准 .maiarc.setreadonly 家 true
强制更新参数顺序为「ID 人数 操作类型 [说明]」，操作类型为 set / add / subtract。允许绕过只读限制。清空全部机厅影响范围较大，请核对使用场景。
任务与群公告超级用户
.maiarc.tasks list .maiarc.tasks pause clear_arc_person .maiarc.tasks resume clear_arc_person .maiarc.tasks enable_api .maiarc.sendannounce 请按现场人数及时报卡
enable_api 开启每10分钟刷新官方目录。bot公告直接发送到已绑定机厅的群；独立HTTP API的公告只创建待投递队列，需客户端领取和确认。
06 /
HTTP API 接入
适合网站、工具和其他客户端。使用服务管理员签发的 API Key，按角色和群范围授权。
GET
/v1/arcades/counts?keyword=上海关键词查卡在名称、地址、省份和ID中做字面包含匹配，一次返回全部可见机厅。普通凭据查询授权群绑定机厅，superadmin查询全库；0卡正常返回。
curl -G 'https://mai-api.blingwang.cn/v1/arcades/counts' \ -H "Authorization: Bearer $API_KEY" \ --data-urlencode 'keyword=上海'
{
"data": {
"keyword": "上海",
"total": 1,
"items": [{
"id": "12345", "name": "上海示例机厅",
"address": "上海市某路", "province": "上海",
"person_count": 7, "readonly": false
}]
}
}keyword必填、1~80字，不分页。仅查实际排卡集合，官方目录中尚未纳管的机厅不会被当作0卡返回。
打开 Swagger UI 文档 ↗bot与API的数据源要分别配置bot当前默认SQLite，独立API使用MongoDB，两者不会自动同步。API写操作需MongoDB副本集和 Idempotency-Key。在线调试请在API服务自身的 /docs/ 打开Swagger UI；普通静态预览页仅供阅读。
07 /
常见问题
为什么发送「家几」没有回复？
先确认插件在该群启用、机器人在线、别名已绑定，并检查别名是否完全一致。未识别的普通消息会被忽略，避免干扰聊天。
机厅不在搜索结果里怎么办？
请管理员先刷新官方目录，再搜索更具体的关键词。官方未收录的机厅可使用 addcustom 创建，之后绑定返回的自定义ID。
为什么两个群的卡数会一起变？
两个群绑定同一机厅ID时共享人数，这是正常行为。群别名相互独立，人数按ID共享。
为什么提示只读、封禁或无法回滚？
只读机厅禁止普通更新与回滚；封禁在对应范围内限制人数更新。回滚要求存在尚未使用的一笔历史，日常维护会清除旧历史。
API搜索为什么没有某个机厅？
检查凭据授权群、群别名绑定，以及机厅是否已进入实际排卡集合。关键词查卡不同于官方目录搜索；superadmin可查询全库已纳管机厅。
Swagger UI如何鉴权和重试写操作？
在Authorize中填写完整API Key，不要再加Bearer前缀。新写操作使用新Idempotency-Key；同一操作网络超时重试，必须复用原键、原方法、原路径和完全相同的正文。
未找到相关指令，请换个关键词。
网站账户与群同步
网站首页公开查询青岛机厅。注册只需 QQ 和至少8位密码，取得五分钟有效的六位码后，用该QQ本人在群聊或私聊向机器人发送 验证 123456，回原浏览器完成。再次登录只需QQ和密码。
加入至少一个包含指定QQ的群即可获得报数资格；无需成为管理员，也不要求群内绑定该机厅。网站与群通过API共用同一份卡数。个人中心可按需生成API凭据，或私聊机器人发送 申请API 用途名称 30。密钥只通过个人页面或私聊交付。
Logto与QQ本地登录分别认证，绑定后共享UID。本地密码、验证码及API密钥不进入Logto。管理员需本人QQ二次验证，群管理员仅管理本群，超级管理员由显式白名单指定。找回密码撤销旧会话，并可选择撤销全部个人密钥。
旧排卡库结构保持，新增账户和安全功能均使用独立新库。当前机器人默认SQLite，部署须明确选择API模式，不能假定已自动同步或迁移。