---
url: https://wiki.awmc.team/guide/bot/phigros.md
---
# Phigros 查分（phi）

::: tip 一句话
除了舞萌 DX，AWMC Bot 也能查 **Phigros**：绑定 TapTap 账号后即可查 B30 成绩图、
资料卡、单曲信息、等效 rks，以及「两次存档之间长了多少」的进步报告喵～
:::

Phigros 的成绩来自 **TapTap 云存档**（协议还原自社区 phi-plugin）。绑定挂在**查分 QQ**
上：普通 QQ 直接用当前 QQ，官方 QQ 需先完成[查分 QQ 绑定（qbind）](/guide/bot/intro#八、论坛账号绑定-qbind)；
发送 `qbind 你的QQ号`，把 QQ 邮箱验证码发回 Bot 即可，无需先注册论坛；也可发送 `论坛绑定` 走 OAuth。未绑定时发 `phi绑定`，Bot 会提示先绑定查分 QQ。

指令一览：

| 指令 | 说明 |
|------|------|
| `phi绑定` | TapTap 扫码授权（链接 5 分钟内有效），或 `phi绑定 <sessionToken>` 直接绑定 |
| `phi查分` | B30 成绩图（默认入口） |
| `phi更新` | 立即重新拉取最新云存档 |
| `phi进步` | 与上一份存档对比：rks / 门槛 / 单曲精度 / 进出榜 |
| `phi资料` | 个人资料卡 |
| `phi查歌 <曲名>` | 单曲信息卡 |
| `phi随机 [筛选]` | 随机抽一首 |
| `phi计算 <定数> <acc>` | 等效 rks 计算器 |
| `phi解绑` | 解除绑定 |
| `phi帮助` | 指令列表 + 快捷按钮 |
| `开启phi` / `关闭phi` | **群主 / 管理员**：本群开关 |

常用的英文子命令写法都可用，例如 `phi bind` / `phi b30` / `phi song` / `phi rand` /
`phi com` / `phi update` / `phi progress` / `phi info` / `phi unbind` / `phi help`；
`φ` 前缀（如 `φ绑定`）同样识别。

## 一、群开关

* Phigros 功能在群内**默认开启**；`关闭phi` 后本群所有 phi 指令不再响应，`开启phi` 恢复。
* 开关与猜歌等群功能一样按群保存，群主 / 群管理员即可切换。
* 私聊不受群开关影响。
* 管理员还可以用数据库配置 `phi_module_enabled` 一次性停用整个模块（此时发指令会提示
  「Phigros 模块当前已停用」）。

## 二、绑定与解绑

```text
phi绑定
phi绑定 <sessionToken>
phi解绑
```

* **扫码绑定**：`phi绑定` 会返回 TapTap 授权二维码（附带文字链接兜底），用 TapTap App
  扫码并在 App 内点「确认」即可，链接 5 分钟内有效。
* **Token 直绑**：已有 sessionToken 时可以直接 `phi绑定 <sessionToken>`。
* **凭据安全**：sessionToken 只写入数据库（`phigros_bind` 表），任何回复、图片和日志的
  正常输出都**不会回显**它。
* 绑定成功后回复昵称与 rks，并发一条「发 `phi查分` 查看 B30」的提示。
* `phi解绑` 删除绑定，但**保留**历史快照，日后重新绑定仍可对比进步。
* 同一 QQ 同时只允许一个绑定流程；扫码后如果二维码失效，重新发一次 `phi绑定` 即可。

## 三、B30 查分

```text
phi查分
phi
pgr
phib30
phi查分 b40
phi查分 best19
```

* 默认输出 **B30 成绩图**：φ 满分曲 + 前 27 条成绩（名次、定数、acc、评级、推分建议），
  并在图上标注本局使用的定数数据版本。
* 榜单长度可调：`phi查分 b<N>` 把展示条数扩到 33～50（写小于 33 也按 33）；
  `phi查分 best<N>` 恰好显示 N 条（1～50）。
* 附带的快捷按钮面板共 10 个：B30 查分 / 我的资料 / 查歌 / 随机 / 等效计算 / 绑定 /
  更新存档 / 我的进步 / 解绑 / 帮助。
* 所有出图指令会先回一句「正在生成图片，请稍等一下哦！」，再发送图片。
* 曲绘按需从公共 CDN 下载并缓存；下载失败时降级为曲名首字占位块，不影响出图。
* 查分时会检查存档新鲜度：超过自动刷新窗口（默认 12 小时）会先重新拉取存档（见下节）。

## 四、存档更新与进步

```text
phi更新
phi进步
```

* **自动刷新**：`phi查分` 若发现存档超过 `phi_auto_update_hours`（默认 12 小时）就会
  先重拉一份，因此平时不必手动更新；`phi资料` / `phi进步` 直接读最近一次存档与快照。
* `phi更新` 适合刚打完机、想立刻看到新成绩的场合。
* 每次**成功**拉取存档都会写一份快照到 `phigros_snapshot` 表；
  `phi进步` 对比**最近两份**快照，输出 rks 变化、B30 计算值（门槛线）变化、单曲精度
  提升，以及新进榜 / 掉出榜清单；只有一份快照时会提示先积累两次。

## 五、资料、单曲与其他查询

```text
phi资料
phi查歌 <曲名>
phi随机 [EZ/HD/IN/AT | 15 | 15+]
phi计算 <定数> <acc>
```

* `phi资料`：个人资料卡，展示 rks、难度统计、课题段位与 data 货币，并用玩家背景曲绘
  模糊铺底；别名 `phi info` / `phi账号资料` / `phi个人信息`。
* `phi查歌 <曲名>`：单曲信息卡，给出定数、谱师、所属章节；**绑定后**还会附带自己
  在四个难度上的成绩与推分建议。支持中英文曲名与别名的模糊搜索（别名表随曲库更新）。
  别名 `phi song` / `查phi` / `phi搜索`。
* `phi随机 [筛选]`：随机抽一首，可按难度（`EZ` / `HD` / `IN` / `AT`）或定数
  （`15` / `15+`）筛选。别名 `phi rand` / `phi随机曲` / `随机phi`。
* `phi计算 <定数> <acc>`：等效 rks 计算器，公式为
  `rks = 定数 × ((acc − 55) / 45)²`；acc 取值 0～100，定数 0～20。
  例：`phi计算 16.7 98.5`。别名 `phi com` / `phi等效`。
* 以上四条查询**不额外计费**；只有 `phi查分` / `phi更新` 按下一节的规则计费。

## 六、计费

B30 查分按次计费，可从 `BREAK配置` 热修改（改完 60 秒内生效，无需重启）：

| 配置键 | 默认 | 说明 |
|---|---|---|
| `phi_b19_cost` | `2` | B30 查分单价（BREAK / 次）；`0` = 免费 |
| `phi_update_cost` | `0` | `phi更新` 单价；默认免费 |
| `phi_auto_update_hours` | `12` | 存档自动刷新窗口（小时） |
| `phi_module_enabled` | `1` | 模块总开关（`0` = 全模块停用） |

* 计费走与其它服务一致的路径：事先确认余额，**成功后才扣费**；余额不足会给出提示。
* 享有与账号指令相同的 FREEDOM 免单、免费窗口等优惠规则；返回文案会标明是否免单与余额。
* 存档里携带的 TapTap 昵称仅用于展示，绑定身份始终以**查分 QQ** 为准。

## 七、数据与曲库

* 曲库与定数跟随上游 phi-plugin 数据更新，当前收录 328 曲（含 Chapter 9「穹顶孤舟」），
  由管理员在需要时同步新版数据集；图上的角标会标明本次使用的定数数据版本。
* 曲绘缓存在 Bot 侧 `data/phigros/ill` 目录，命中缓存后不再重复下载。
* 渲染使用与 phi-plugin 相同的模板；截图进程偶发崩溃时会自动重试一次，仍失败则回落内置渲染。

## 八、常见问题

**发 `phi` 没反应？**
先看是不是在本群被关了：让群主 / 管理员发 `开启phi`；若提示「Phigros 模块当前已停用」，
则是管理员在配置里关闭了模块。

**提示先 qbind？**
官方 QQ 使用 Phigros 绑定前需要先绑定查分 QQ：发送 `qbind 你的QQ号` 并回复邮箱验证码，或发送 `论坛绑定` 完成 OAuth，之后再发 `phi绑定`。

**存档不是最新的？**
刚打完机可以直接 `phi更新`；平时查分超过 12 小时会自动重拉，若仍然看不到新成绩，
确认一下机器是否已联网上传 TapTap 云存档。

**`phi进步` 说没有可对比的存档？**
进步依赖快照：成功查分 / 更新两次之后（存档有变化时），对比才有内容。