常见问题与故障排查

本页用于处理高频使用问题。插件正在更新、测试或分批部署时，Bot 当前返回和 Bot 内帮助菜单优先于文档。

• 查看模块依赖与维护边界：功能状态与数据来源
• 查看停机、迁移和维护安排：服务状态与公告
• 查看近期功能调整：Bot 更新日志
• 确认问题后提交材料：问题反馈

30 秒快速判断

先发送一个最基础的指令：

帮助

根据结果判断：

测试结果	更可能的问题	下一步
帮助 也完全没有回复	Bot 离线、群消息权限或 QQ 平台链路异常	检查群权限和服务公告
帮助 正常，只有某个模块失败	单个插件、数据源或参数问题	前往对应模块章节
文字正常，只有图片不显示	图片生成、上传或平台发送限制	查看“图片、菜单与按钮”章节
同一个指令偶尔成功	上游超时、排队、限流或网络波动	等待片刻后重试一次
私聊可用、群聊不可用	群消息权限、群配置或群作用域问题	检查机器人管理设置
管理功能提示无权限	群角色、超级用户或身份映射问题	由群主或维护人员检查

排查原则

不要在短时间内连续刷同一条指令。保留第一次出现的完整错误提示，比连续重试更有利于定位。

一、接入与群消息权限

如何将 Bot 加入群聊

当前流程是由群主或有相应权限的群管理员，直接将 Bot 拉入目标群聊。

• QQ 官方 Bot 号：3889004352
• 显示名称：Amia_晓山瑞希
• 不再使用“从群聊中选择联系人”等旧版邀请流程

详细步骤见如何使用。

Bot 入群后完全没有回复

依次检查：

1. 群主是否在机器人管理中开启“获取群内全部消息”；
2. Bot 是否仍在目标群中；
3. 发送的是否为纯文本 帮助；
4. 是否误加了 @、斜杠、空格或其他前缀；
5. 服务公告中是否有重启、维护或迁移；
6. 其他群是否也同时无法使用。

所有群都无响应时，更可能是 Bot 主进程或平台链路异常。只有一个群无响应时，更可能是该群权限或配置问题。

为什么 @机器人后反而无法触发

当前群聊环境支持直接发送指令文本。部分功能在消息包含 @机器人时可能无法正确识别。

推荐：

帮助

不推荐：

@Amia_晓山瑞希 帮助

群聊没有开启全部消息权限时，实际触发范围仍受 QQ 平台设置影响。

群里有人能用，有人不能用

可能原因：

• 指令存在用户绑定要求；
• 当前用户没有完成账号验证或数据上传；
• 功能要求群主、管理员或 Bot 超级用户权限；
• 用户处于功能冷却时间；
• 用户身份在 QQ 官方 Bot 环境中映射异常；
• 用户隐私设置禁止他人查询。

先让无法使用的用户发送 帮助、个人信息 或对应模块的绑定查询指令，以区分权限问题和数据问题。

Bot 被移出后重新加入，配置还在吗

不同模块的配置保存位置不同：

• 用户绑定、经济数据等通常按用户身份持久化；
• 群公告、欢迎、群分析等通常与群作用域相关；
• QQ 官方 Bot 的群 ID 和用户 ID 可能是平台虚拟标识；
• Bot 被移出、平台映射变化或重新部署后，部分群配置可能需要重新确认。

涉及群级配置时，由群主重新检查权限和模块启用状态。

二、指令与参数问题

提示“指令不存在”或没有匹配到功能

检查：

• 是否使用了正确的中文或英文指令名；
• 指令和参数之间是否保留空格；
• 是否把全角符号、中文括号或多余标点带入；
• 区服前缀、歌曲名、用户 ID 是否放在正确位置；
• 文档中的旧别名是否已经调整。

完整指令和别名以 Bot 内帮助菜单为准。文档主要说明高频入口，不保证列出每个别名。

提示参数错误，但看不出哪里错了

先把指令缩减为最基础形式。例如：

查歌 Garakuta

不要一开始就叠加多个筛选参数。基础形式成功后，再逐个增加区服、难度、角色或其他条件。

只有某一个插件完全不响应

先测试另一个模块：

• 帮助、个人信息 正常：Bot 主进程大概率正常；
• PJSK 正常、舞萌失败：优先检查舞萌数据源或插件；
• 舞萌正常、PJSK 失败：优先检查 PJSK 后端、区服和绑定；
• 所有图片类功能失败：优先检查图片生成和发送链路。

为什么同一指令结果会变化

可能由以下原因造成：

• 游戏或活动数据更新；
• 第三方数据源刷新；
• 用户重新上传成绩；
• 插件算法或定数调整；
• 缓存过期；
• 当前默认绑定或默认数据源发生变化。

三、PJSK 常见问题

PJSK 绑定失败

检查：

• 游戏 ID 是否完整；
• 区服前缀是否正确；
• 当前 QQ 是否已经绑定同一账号；
• 是否把昵称、房间号或活动排名误当作游戏 ID；
• 对应区服的绑定服务是否可用。

常用区服前缀：

• cn：国服
• tw：台服
• en：国际服
• kr：韩服

不加前缀时通常按默认区服处理，但不同功能的默认规则可能不同。

已经绑定，查询的却不是目标账号

使用绑定列表和默认账号相关指令检查：

• 当前是否存在多个绑定；
• 默认绑定是否指向旧账号；
• 区服默认绑定和全局默认绑定是否冲突；
• 指令是否带了其他区服前缀；
• 查询他人时是否误用了自己的默认账号。

可以使用 绑定列表、切绑定、设置主账号、设置默认绑定 或清除默认绑定相关指令。

他人无法查询我的账号

绑定后默认可能处于不公开状态。检查是否启用了允许他人查询的设置。

常用入口：

• 给看：允许他人查询；
• 不给看：禁止他人查询；
• 隐藏ID / 显示ID：控制结果中的 UID 展示。

公开查询权限和 UID 显示是两类设置，不要混淆。

基础资料能查，Rating、组卡或详细数据不能用

进阶功能可能依赖额外数据：

• suite 数据未上传；
• suite 数据已经过期；
• 账号尚未完成验证；
• 当前区服不支持该项能力；
• 默认绑定不是已上传数据的账号；
• 上游后端没有返回完整数据。

可以先检查：

• pjsk验证列表
• 抓包数据 / sud
• 对应绑定账号和区服

上传入口与具体要求见PJSK 专项功能。

MySekai / 烤森功能没有数据

MySekai 功能依赖单独的数据上传。suite 数据存在，不代表 MySekai 数据也存在。

检查：

• 是否上传 MySekai 数据；
• 烤森抓包数据 / msd 是否显示有效；
• 当前查询账号是否为上传数据的账号；
• 当前区服是否支持该项内容；
• 数据是否在游戏更新后失效。

当前 JP 支持范围通常更完整，TW / CN 的具体范围以 Bot 返回为准。

榜线、时速或预测结果没有更新

可能原因：

• 活动尚未开始或已经结束；
• 查询的是错误区服；
• 对应档线暂时没有数据；
• 上游采集存在延迟；
• World Link 角色参数不正确；
• 预测模型暂未覆盖该档位。

榜线、时速和预测不是同一种数据。不要把预测值当作最终排名保证。

组卡结果不符合预期

检查输入条件：

• 团名、颜色、活动 ID 是否正确；
• 是否指定了歌曲和难度；
• 协力、单人、Auto 等模式是否正确；
• 是否要求指定队长或排除卡牌；
• suite 数据是否包含最新卡牌和养成状态；
• 参数之间是否保留空格。

先使用最少条件运行一次，再逐项增加限制，可以更快定位是哪一个参数导致无结果。

个人信息背景没有生效

个人信息背景通常要求账号已验证。检查：

• 是否完成验证；
• 上传的是支持的图片格式；
• 图片是否过大或无法下载；
• 调整命令是否作用于正确绑定；
• 是否使用了 u序号 操作其他绑定账号。

账号安全需要注意什么

必须注意

不要在群聊、截图或反馈表单中公开引继码、密码、Token、OAuth 授权码、登录二维码和完整抓包凭证。

Bot 无法找回丢失的游戏账号。绑定、验证或上传前，请自行保存引继码与密码。

四、舞萌 DX 常见问题

b50、ap50 或单曲查询失败

先检查：

1. 是否已经绑定有效的数据源；
2. 默认数据源是落雪还是水鱼；
3. 数据源授权是否失效；
4. 查询目标是否确实存在成绩；
5. 歌曲 ID、名称或别名是否正确；
6. 上游查分服务是否异常。

可以尝试：

• 查看绑定
• 切换数据源 落雪
• 切换数据源 水鱼
• mai状态

为什么查分能用，但上传成绩不能用

舞萌查询插件和成绩同步组件是两个独立模块：

• 查分与分析模块读取已经存在的成绩数据；
• 同步组件负责授权、排队、登录、上传和会话清理。

因此，同步服务维护时，已有成绩的 b50 仍可能正常；查分器异常时，同步流程也可能完成但暂时看不到新结果。

成绩同步为什么一直排队

当前同步队列：

• 最多容纳 10 人；
• 同时只处理 1 名用户；
• 前一用户没有结束时，后续用户需要等待。

使用 队列状态 查看人数。不要重复发送 上传成绩，重复操作可能产生多个无效会话。

为什么每天凌晨到上午无法同步

成绩同步服务当前维护窗口为：

每日 00:00—11:00

维护窗口内暂停同步是预期行为，不代表账号、Token 或二维码损坏。

落雪 OAuth 授权失败

检查：

• 是否使用最新生成的授权链接；
• 授权码是否完整；
• 授权码是否已经使用或过期；
• 是否在正确 QQ 账号下完成绑定；
• 浏览器授权完成后是否及时发送确认指令。

旧版落雪 Token 绑定方式已经失效时，应按 Bot 提示使用 OAuth 链接授权。

水鱼 Token 无效

可能原因：

• Token 复制不完整；
• Token 已经失效；
• 账号或数据源状态异常；
• 将其他服务的凭证误当作水鱼 Token；
• 在公开群中发送后出于安全原因需要立即更换。

不要把 Token 发送到公开反馈表单。

上传流程卡住，无法重新开始

依次尝试：

1. 取消：取消当前操作；
2. 登出：清理异常登录状态；
3. 查看绑定：确认当前绑定和同步类型；
4. 等待队列释放；
5. 在维护窗口外重新发送 上传成绩。

上传完成后 B50 没变化

可能原因：

• 本次游戏没有产生更高成绩；
• 同步完成，但查分器仍在处理；
• 查询使用了另一数据源；
• 默认绑定或默认路由不是刚同步的账号；
• 游戏成绩尚未在上游显示；
• B50 计算规则变化后，单曲提升未进入当前列表。

先等待短时间，再确认默认数据源和账号。

mai状态 与实际机台情况不一致

服务器状态模块可能包含用户上报和群聊自动识别，反映的是社区观测，不等同于华立、SEGA 或场地方的官方公告。

错误上报、地区差异和状态恢复延迟都可能造成短时间不一致。

五、经济系统常见问题

签到、打工或任务提示冷却

经济系统可能对签到、打工、问答、互动和部分经营操作设置次数或冷却限制。等待 Bot 返回的冷却时间结束后再操作。

连续刷指令不会缩短冷却时间。

积分、道具或卡牌和预期不一致

先检查：

• 当前使用的是否为同一个 QQ 身份；
• 是否在正确群聊或作用域中查询；
• 订单、奖励或合成是否已经完成结算；
• 道具是否已经被使用；
• 插件是否刚完成数据迁移或更新；
• Bot 是否返回了失败或回滚提示。

不要仅凭排行榜截图判断个人账本错误。反馈时应提供完整操作顺序和每一步返回。

经济系统数据能兑换现实货币吗

不能。PC、道具、卡牌、商城和市场数据均为 Bot 内部虚拟互动内容：

• 不与人民币挂钩；
• 不提供反向兑换；
• 不承诺现实收益；
• 不应在线下或其他平台交易。

排行榜和个人信息为什么不同步

可能原因：

• 排行榜使用缓存或聚合数据；
• 当前群排行与全局个人信息口径不同；
• 刚完成的操作尚未进入统计；
• 查询的是不同身份或群作用域；
• 数据更新期间存在短暂延迟。

六、群聊工具、统计与管理

群活统计数字为什么不一致

以下功能可能来自不同统计口径：

• 今日发言
• 本月发言
• 全群统计
• 今日DAU
• 群聊活跃分析

差异通常来自：

• 时间范围不同；
• 去重方式不同；
• 模块启用时间不同；
• Bot 未收到部分历史消息；
• 群聊分析不会补算启用前数据。

群聊活跃分析如何开始记录

该模块默认不开启。只有管理员在目标群主动开启分析后，才记录之后产生的匿名活动元数据。

群作用域按平台 Bot 实例和群标识区分，不强制还原成真实 QQ 群号。

群聊分析会保存聊天正文吗

不会。公开边界包括：

• 不保存消息正文；
• 不保存昵称；
• 不保存真实 QQ 号；
• 不保存平台虚拟用户 ID 或群 ID 明文；
• 不采集图片、语音和文件内容；
• 不采集私聊内容。

入群欢迎或离群提示没有触发

可能原因：

• 欢迎模块未在该群启用；
• QQ 平台没有推送对应事件；
• Bot 在事件发生时离线；
• 群作用域配置发生变化；
• 主动退群、被移出等事件类型无法被平台准确区分；
• 图片或主动消息发送失败。

管理员指令提示无权限

检查：

• 当前用户是否真的是群主或管理员；
• 指令是否只允许 Bot 超级用户；
• QQ 官方 Bot 返回的身份是否为平台虚拟身份；
• 身份绑定是否完成；
• 权限服务是否可用；
• 当前群是否启用了对应模块。

权限检查采用默认拒绝时，权限服务异常不会自动放行。不要通过重复尝试绕过权限。

七、图片、Markdown、菜单与按钮

文字正常，但图片没有显示

可能原因：

• 图片生成失败；
• 本地文件不存在；
• 图床或上传服务异常；
• QQ 平台拒绝图片；
• 图片尺寸或体积超限；
• 网络超时；
• 生成成功但发送阶段失败。

反馈时应说明是“没有任何回复”“返回文字但没图”，还是“图片加载失败”。这三种情况对应不同链路。

Markdown 菜单或按钮缺失

不同 QQ 客户端、官方 Bot 能力和消息适配层可能显示不同：

• 支持时返回 Markdown 和按钮；
• 不支持时可能降级为文本或图片；
• 按钮不可点击时可以直接发送对应文字指令；
• 客户端版本过旧时可能无法完整显示。

喜报、悲报或表情包生成失败

检查输入文本是否为空、过长或包含无法渲染的字符。文字功能正常但所有生成器都失败时，更可能是图片渲染或发送链路异常。

八、功能状态页面在哪里

功能状态页面地址：

https://help.mizuki.top/status

网站顶部导航会提供独立的“功能状态”入口，首页“支持与维护”区域也会提供卡片。

该页面说明：

• 哪些模块已上线；
• 哪些模块依赖上游；
• 哪些模块需要管理员启用；
• 数据来自哪里；
• 更新是实时、按请求、上传后还是随部署生效；
• 插件更新期间如何理解文档与现网差异。

它不是实时监控面板。具体停机和维护仍以服务状态与公告为准。

九、文档与 Bot 实际行为不一致

插件更新、兼容调整、仓库提交和生产部署之间可能存在时间差。

判断顺序：

1. 以 Bot 当前返回为准；
2. 查看 Bot 内帮助菜单；
3. 查看功能状态与数据来源；
4. 查看Bot 更新日志；
5. 查看服务状态与公告；
6. 确认长期不一致后再反馈。

你正在使用的可能仍是上一版生产插件，而仓库中已经出现下一版文档；反过来也可能发生。

十、提交反馈前准备什么

最低必要信息

• 问题发生日期和大致时间；
• 群聊或私聊环境；
• 是否为 QQ 官方 Bot；
• 完整指令和参数；
• Bot 的完整返回；
• 从开始到失败的操作步骤；
• 是否可以稳定复现；
• 已遮挡敏感信息的截图。

推荐反馈模板

问题模块：
发生时间：
使用环境：群聊 / 私聊
完整指令：
实际结果：
预期结果：
复现步骤：
是否稳定复现：
已完成的排查：
截图或错误原文：

不要提交的内容

• 游戏引继码和密码；
• 水鱼 Token；
• OAuth 授权码；
• 登录二维码；
• 完整抓包凭证；
• 未遮挡的个人账号信息；
• 与问题无关的大量聊天记录。

整理完成后前往问题反馈。只写“坏了”“没反应”或只发一张裁剪后的截图，通常无法定位问题。