README_en.md
September 5, 2026 · View on GitHub
Introduction
phi-plugin is a plugin for querying Phigros information, including b30, score, userinfo, and more Phigros-related features. Suggestions and issues can be submitted via Issues. Pull request are welcome.
Use /phihelp after installation to view detailed commands.
Installation
Run the following commands in your Yunzai directory:
Using GitHub
# Install plugin core
git clone --depth=1 https://github.com/Catrong/phi-plugin.git ./plugins/phi-plugin/
# Enter plugin directory
cd ./plugins/phi-plugin/
# Install dependencies
pnpm install -P
Using Gitee
# Install plugin core
git clone --depth=1 https://gitee.com/catrong/phi-plugin.git ./plugins/phi-plugin/
# Enter plugin directory
cd ./plugins/phi-plugin/
# Install dependencies
pnpm install -P
Warning
Please use the master's permission to execute this command to download the song illustrations. Otherwise, the relevant song illustrations will not be displayed properly! (It can be standard input or other platforms.)
/phi downill
Todo
- Optimize UI design
- Add collection/avatar gallery
- Song selection via phi
- Optimize sessionToken QR scanning
- Modify settings via commands
- Query Song History Constants
- Score Map Tags
- Adapt to TapTap International Version
- ...
Features
Note: # can be replaced with /. Command headers are customizable.
User Features
| Command | Description |
|---|---|
#phi help | Show help |
#phi (gb|cn)?bind <token> | Bind sessionToken (supports CN/Global, default is CN) |
#phi unbind | Clear the current Bot's local sessionToken, API ID, save, and history only; API platform bindings are unchanged |
#phi clean | Delete all records |
#phi update | Update save data |
#phi (rks|pgr|b30) | Query Rks (provides b30 results) |
#phi x30 | Query 1Good b30 |
#phi fc30 | Query Full Combo b30 |
杠批比三零 | Same as above,but looks like Arcaea Online |
#phi info(1|2)? | View personal stats |
#phi lmtacc [0-100] | Calculate Rks with minimum ACC limit |
#phi (lvsco(re)|scolv) <rating range> <difficulty> | Get scores in range |
#phi chap <chapter name|help> | Get chapter scores |
#phi ahv <rating>[-v version] | Get rating score table |
#phi list <-dif difficultyRange> <-acc accRange> <EZ|HD|IN|AT> <NEW|C|B|A|S|V|FC|PHI> | List scores per song in range |
#phi hisb30 | Calculate B30 changes based on history |
#phi best1(+) | Text-based b30 (up to b99) |
#phi score xxx [-dif (EZ|HD|IN|AT)] [-or (acc|score|fc|time)] [-unrank] | Get single score & improvement tips (parameters for score ranking, API required) |
#phi suggest | Get songs that can increase Rks by +0.01 |
#phi ranklist [rank] | Rks leaderboard |
#phi rankfind <rks> | Find how many users have higher RKS than the queried RKS |
#phi data | Check user data count |
#phi guess | Guess song from illustration (reply directly) |
#phi (ltr|letter) | Guess song via letters (use #open/#ans) |
#phi tipgame | Guess song via hints (use #tip/#ans) |
#phi song xxx | Query song info (supports aliases) |
#phi chart <song> [difficulty=IN] | View chart details |
#phi tag <song name> [difficulty=IN] <tag> | View chart tags, available tags shown in response, default difficulty is IN |
#phi settag <song name> [difficulty=IN] <tag> | Tag a chart, recommended to use /tag to query tag list first, default difficulty is IN |
#phi (comment|cmt) <song> [difficulty=IN](newline)<text> | Comment on songs |
#phi mycmt | View own cloud comments |
#phi recmt <ID> | Delete comment (owner/admin) |
#phi (table|ratings) <rating> | Phigros rating table |
#phi (difHis|历史定数) | Query song rating history |
#phi new | Check new songs |
#phi tips | Random tips |
#phi jrrp | Daily luck |
#phi alias xxx | Query song aliases |
#phi (rand|random) [rating] [difficulty] | Random song by criteria |
#phi randclg [total] [difficulty] ([rating range]) | Random challenge (e.g., /rand 40 (IN 13-15)) |
#phi ill xxx | View song illustration |
#phi search <criteria> | Search songs by BPM/rating/notes |
#phi theme [number] | Switch themes; page styles are applied according to the theme package |
#phi myset <field> <value> | View/modify user settings, value supports selection by number (e.g., /myset theme 1) |
sign/sign | Daily check-in |
task/mytasks | View tasks |
retask/refresh | Refresh tasks (20 Notes) |
#phi (send|give) <target> <amount> | Send Notes |
Admin Features
| Command | Description |
|---|---|
#phi backup (back)? | Backup saves (+back to send) |
#phi restore | Restore from backup |
#phi(setnick) xxx ---> xxx | Set song alias |
#phi(delnick) xxx | Remove alias |
#phi(force)?(update) | Update plugin |
#phi repu | Restart puppeteer |
#download ill | Download illustration |
#phi get <rank> | Get sessionToken by rank |
#phi del <token> | Ban sessionToken |
#phi allow <token> | Unban sessionToken |
#phi (set|set)<feature><value> | Modify settings |
#phi ban <feature> | Disable features |
#phi botClaimLink | Owner command Get a Bot platform claim link that is valid for 15 minutes; private chat is recommended |
#phi resetApiBot | Owner command Issue a new API Bot identity; only use this if the credentials are lost or revoked, or when intentionally replacing the identity |
Ban Parameters
#phi ban Parameters
| Parameter | Feature | Affected Commands |
|---|---|---|
| all | All features | All |
| help | Help | /help /tkhelp |
| bind | Binding | /bind /unbind |
| b19 | Image queries | /pgr /update /info /list /pb30 /p30 /lmtacc /score /lvsco /chap /suggest |
| wb19 | Text queries | /data /best |
| song | Song info | /song /chart /ill /search /alias /rand /randclg /table /cmt /recmt /addtag /subtag /retag |
| ranklist | Leaderboards | /ranklist /godlist |
| fnc | Utilities | /com /tips /new |
| tipgame | Hint game | /tipgame |
| guessgame | Guess game | /guess |
| ltrgame | Letter game | /letter /ltr |
| sign | Social | /sign /send /task /retask /jrrp |
| setting | Settings | /theme |
| dan | Dan authentication | /dan /danupdate |
API Feature Testing Now Open
API features can be manually enabled/disabled in settings. When enabled, it automatically syncs user usage records and historical scores from Phi-Plugin applications (web, Yunzai, excluding Koishi for now) to the API server. Some features require API to be enabled.
| Command | Description |
|---|---|
#phi bind <userId> | Enable score query API, bind API account |
#phi setApiToken <token> | Set API Token |
#phi tokenList | Get list of currently bound platforms |
#phi auth <api Token> | Get sessionToken via API Token |
#phi clearApiData | Permanently delete the phi-api account and cloud data; requires Phigros SSTK permission and confirmation |
#phi updateHistory | Update historical scores from BOT to API server |
#phi updateUserToken | Owner command Upload current BOT user tokens to API server |
Claiming the Bot Platform Identity (Bot Owner)
Claiming associates this phi-plugin deployment with your signed-in web account so that you can view its status and binding statistics and manage it from the web dashboard. The Bot is already active after it successfully registers with the API; leaving it unclaimed does not disable the Bot or user score queries.
Claim procedure:
- Update phi-plugin to a version that supports Bot platform authentication and make sure
openPhiPluginApiis enabled. - Start or restart the Bot once. If the plugin has no API Bot identity, it automatically registers with the API and writes the credentials to the local configuration. Never disclose or manually send
apiBotClientSecret. - As the Bot owner, send
#phi botClaimLink(or#phi 获取Bot认领链接) in a private chat with the Bot. - Open the returned claim link within 15 minutes. If you are not signed in on the website, sign in first and then continue from the original claim page.
- Verify the Bot name and
clientIdshown on the page, then confirm the claim. You can then view and manage the Bot from the Bot management page in the web dashboard.
A claim link is single-use. If it expires or has already been used, send the command again to obtain a new one. When the command is sent in a group chat, the plugin does not post the link in the group; it writes the link to the Bot console instead. Using a private chat is recommended.
#phi resetApiBot (or #phi 重置API Bot身份) issues a completely new clientId and secret and replaces the current Bot identity. This is not part of the normal claim procedure. Only use it if the local credentials are lost, the identity has been revoked by the API, or you intentionally want to replace the Bot identity. The new identity must be claimed again. To prevent sensitive information from leaking, when this command is used in a group chat, the new identity details and claim link are written only to the Bot console.
Detailed Permission Explanation:
Binding and retrieving saves only requires a score query ID. When binding with sessionToken for the first time, the API Token will be set to the sessionToken, and if users provide a sessionToken during binding, the bot will save it locally.
Support Development
Your support is my greatest motivation!
Sponsors
Special thanks to these sponsors (list may not be fully updated):
 @Loser_X 🌸 20 🌸 |
 @Steve~ɘvɘɈƧ 🌸 40 🌸 |
 溯洌RIPPLE 🌸 35 🌸 |
 祈 🌸 15 🌸 |
 茗亿 🌸 30 🌸 |
 ... 🌸 50 🌸 |
 夏夏肃炎 🌸 5 🌸 |
 Bluerosion 🌸 52.0 🌸 |
 铃 🌸 5 🌸 |
Previews
| Best30 By @Steve~ɘvɘɈƧ | Single Score Legacy Version Song Info |
|---|---|
| Range Scores By @东城Eastown User Stats | Legacy Stats |
Contributors
Star History
Disclaimer
- This plugin is intended for non-commercial use only.
- All images/assets are from the internet and will be removed upon request.
- Cloud save system adapted from 7aGiven/PhigrosLibrary
Related Projects
| Yunzai-Bot Plugin Index | Yunzai-Bot | Miao-Yunzai | TRSS-Yunzai |