介绍
phi-plugin 为查询Phigros信息的插件，包括b30、score、userinfo以及更多Phigros相关功能，有相关的建议和问题可以在Issues中提出，欢迎PR。
具体功能可在安装插件后 通过 /phihelp 查看详细指令
安装
Yunzai 安装
在Yunzai目录下运行
使用Github
#安装插件本体
git clone --depth=1 https://github.com/Catrong/phi-plugin.git ./plugins/phi-plugin/
#进入插件目录
cd ./plugins/phi-plugin/
#安装插件所需依赖
pnpm install -P
使用Gitee
#安装插件本体
git clone --depth=1 https://gitee.com/catrong/phi-plugin.git ./plugins/phi-plugin/
#进入插件目录
cd ./plugins/phi-plugin/
#安装插件所需依赖
pnpm install -P
[!WARNING]
请使用主人权限执行该指令以下载曲绘，否则相关曲绘将无法正常展示！（可以是标准输入或者其他平台）
/phi downill
[!TIP]
如果安装依赖时速度过慢，运行：
pnpm config set registry https://registry.npmmirror.com
渲染器 SDK 现为按需提供的可选依赖。默认 Puppeteer 通常直接使用 Yunzai 宿主安装的 puppeteer（兼容 24.x）；若提示缺少该包，请在宿主根目录执行 pnpm add puppeteer@^24.16.2。选择 Shotium 时复用宿主服务，无需在本插件另装 Shotium SDK。
模板维护者可参考 Shotium 文字适配规则：在 .art 开头声明 pvis，正文保留 name="pvis"，由渲染入口统一补上字号。
Koishi 安装
在已有的 Koishi 4 项目根目录执行（需要 Node.js，克隆或更新时需要 Git）：
node ./external/phi-plugin/scripts/install-koishi.cjs
首次安装时，也可以从包含此脚本的插件版本中单独取得 scripts/install-koishi.cjs，在 Koishi 根目录运行 node install-koishi.cjs。脚本会自动克隆缺失的插件本体；已有本体默认直接复用，不会自动更新。
脚本会生成独立的 koishi-plugin-phi-plugin 包装包、安装依赖，并在 koishi.yml 登记插件，让 WebUI 能识别插件并显示配置表单。不会修改本体 phi-plugin/package.json，但会修改 Koishi 宿主的 package.json 和锁文件。已有插件配置、凭据、禁用状态及 Puppeteer 设置会保留；旧的相对路径入口会迁移为标准插件名。
# 预览安装计划，不修改文件
node ./external/phi-plugin/scripts/install-koishi.cjs --dry-run
# 从其他目录执行时指定 Koishi 根目录
node /path/to/install-koishi.cjs --root /path/to/koishi-app
# 更新本体并重新安装（仅允许干净 Git 工作区，快进更新）
node ./external/phi-plugin/scripts/install-koishi.cjs --update
# 只安装 Shotium 后端，首次安装也可使用此参数
node ./external/phi-plugin/scripts/install-koishi.cjs --renderer shotium
# 准备两种后端，自动跟随宿主使用 Shotium，否则使用 Puppeteer
node ./external/phi-plugin/scripts/install-koishi.cjs --renderer auto
# 准备并切换到 Koishi Puppeteer 服务
node ./external/phi-plugin/scripts/install-koishi.cjs --renderer puppeteer
包管理器优先按宿主唯一的锁文件识别，也可用 --manager npm、--manager yarn 或 --manager pnpm 指定。Yarn 需要 2+ 且使用 nodeLinker: node-modules。pnpm 的本地链接不安装本体公共依赖，安装器会先用随 Node.js 提供的 npm 7+ 补齐本体公共运行依赖，跳过渲染器 peers、安装脚本和 npm 锁文件；宿主继续使用 pnpm，本体 package.json 和原锁文件均不修改。非默认 YAML 配置可用 --config 文件路径 指定。
安装前会将待修改的已有宿主文件和包装文件备份至宿主 .phi-plugin-install-backups/。安装失败时可据此恢复；脚本不会自动回滚已安装的依赖，也不会自动重启 Koishi。安装成功后请重启 Koishi 并刷新 WebUI。
请在控制台启用一个 database 服务。--renderer 省略时保留已有 phi-plugin 实例的 renderer，首次安装默认 puppeteer。选择 shotium 只安装 @pixel.js/shotium SDK，使用本插件管理的原生渲染器，无需 Puppeteer 服务或 Chrome。SDK 需要 Node.js 18+，由包管理器按系统与架构安装原生包，请保留 optionalDependencies。
选择 puppeteer 会按需补齐 Puppeteer SDK、Koishi Puppeteer 服务依赖与配置；选择 auto 会准备两种后端，并补齐 Puppeteer 作为未检测到宿主 Shotium 时的后备。两者均保留已有服务、浏览器路径和禁用状态。安装过程跳过浏览器下载，请通过 Koishi Puppeteer 服务配置可用的 Chrome / Chromium 路径。Shotium 为可选 SDK，Puppeteer 服务为可选注入，未安装或启用所选后端时会明确提示缺少依赖。
以后在 Koishi 设置的“渲染设置”中选择渲染器，也可修改 koishi.yml 对应 phi-plugin 实例的 renderer。保存后原位切换渲染器及并发、超时、质量设置，无需重载插件或重启宿主；旧请求继续完成，后续请求使用新后端。缺少所选服务或 SDK 时拒绝此次切换并保留当前后端。切换到尚未安装的后端前，可重新执行安装器选择该后端；安装器会保留之前已安装的另一后端，方便后续切换。
若原先使用独立版本的同名koishi-plugin-phi-plugin插件，请先迁移，脚本不会覆盖它。
Koishi 指令管理
Koishi 加载插件后还会每分钟执行“phi-Bot状态与正式别名同步”：上报 Bot 状态并处理 API 下发事项；正式别名距上次成功同步满 6 小时才重新下载。任务遵循 API 总开关和版本检查，不重叠执行，插件卸载或重载时自动清理旧定时器。启动时的首次同步仍由原有 API 初始化流程负责。
插件通过 Koishi 的 ctx.command() 注册功能，可在指令管理中查看、调整权限或设置别名。常用功能直接注册在命令头下，例如 /p help、/p b30、/p score（管理标识为 p.help、p.b30、p.score）；不常用功能按分类展开，例如 /p songs alias、/p account unbind。修改命令头时旧注册随重载清理；原来绑定旧指令标识的权限和别名设置需按新标识调整。游戏答题和会话确认仍作为普通消息处理。
Koishi 端的主人判定沿用 Koishi 的权限等级：等级 ≥ 4（控制台里的管理员）视为主人，其余一律为 false；Yunzai 端继续使用框架提供的 isMaster。repu、gx、backup、tkls、botclaimlink、myset 等主人功能按该标记放行或拒绝。指令注册本身使用最低等级（authority: 1，所有人都能触发），需要更细的限制可在控制台的指令管理中为具体指令叠加权限。群组管理员判定（e.isAdmin、e.member）暂未在 Koishi 端映射，相关功能在 Koishi 端仍按无权限处理。
顶层常用入口为 help、b30、bind、update、score、suggest、info、song、sign。其他功能放入成绩 scores、账号 account、曲目 songs、帮助 guides、API api、别名提案 proposals、Bot bot、谱面 charts、游戏 games、管理 admin、市场 market、日常 daily、排行 ranking、设置 settings、更新 maintenance、用户 user 分类。当前共 9 个常用入口和 16 个分类。默认不向 Discord 下发任何斜线指令，打开总开关并按需勾选后，这些入口与分类才会出现在 Discord 菜单中。命令头为空时省略根分组，例如 /b30、/songs alias。
Koishi 设置中的“Koishi 快捷指令”由一个 Discord 指令总开关和一组树形勾选项组成，两者初始都未启用/未勾选，因此新装或未配置的插件不会向 Discord 注册任何斜线指令，只保留原聊天调用。打开总开关后：勾选分组即添加该分类菜单，展开后勾选子命令即将其添加到顶层快捷指令。父子独立勾选，不自动联动。单独勾选的功能不再在分类中重复显示，空分类自动省略；未选功能仍保留原聊天调用和权限检查，清空所有勾选可关闭快捷菜单。保存后由 Koishi 重载插件并自动同步。指令与非空分类合计最多 25 个顶层入口，超限只记录日志警告、注册照常完成。调整顶层/分类位置会改变管理标识，原权限与别名配置需按新标识调整。总开关与树形设置仅提供给 Koishi，不出现在 Guoba 设置中；已有两组配置会继续读取，首次编辑树形选择后使用新配置。
正则命令头仍用于匹配聊天内容。对于 phi|pg、(?:phi|pg) 这类命令头，使用首个字面量分支 phi 作为管理分组；无法提取字面量的复杂正则使用 phi-plugin 分组，不将正则符号作为指令名。
注册命名冲突时，整棵指令树按“空头 → p → phi → phigros → phi-plugin”回退；用户显式设置的非空命令头优先尝试。空头模式只要有一个顶层名称被已有指令或别名占用，就为整棵树选择下一个可用根分组。例如已有系统 help 时使用 /p help、/p b30，不向系统帮助添加子命令。所有候选均占用时明确报错，可设置其他命令头。聊天匹配规则不随注册回退改变；系统 /help 优先，Phi 帮助可通过 #help（宿主未占用该写法时）或 /p help 调用。实际名称可在日志和指令管理中查看。
插件只把指令注册到 Koishi：斜线指令树由 Koishi 的指令管理器按 slash 标记生成，上传则交给平台适配器统一管理。Koishi 在启动就绪与机器人上线时自行提交，插件在注册、改命令头或换勾选后也只调用同一入口，不再自行计算快照、去重、重试或清空。重复请求、限流退避与远端清理由适配器负责（Discord 适配器须启用其自身的斜线指令开关，否则适配器会直接忽略提交）；离线机器人由 Koishi 在其上线时同步。总开关关闭或没有任何勾选时指令树为空，插件不会主动清空 Discord 上已上传的菜单，需要时可关闭适配器的斜线指令或手动清理。
注册前仍会校验 Discord 的名称与层级约定：每层名称 1–32 字符、合法小写名称、最多三级，非法名称会明确报错并中止注册。每层 25 个子项与全局 100 个根指令的约定降级为日志警告，超限不再阻止注册，真正的约束由适配器与 Discord 在提交时给出。Discord 中 /p help、/p b30 可直接执行，无需重复输入完整指令；曲名等参数填入可选的 args 字段，例如 /p score args:曲名，具体格式由业务功能校验。
聊天中继续使用原有写法，命令头 cmdhead 可以自定义、使用正则或留空：
| cmdhead | 示例 |
|---|
phi | /phihelp、#phi help、/phi b30 |
pg | /pghelp、/pg b30 |
| 空字符串 | /help、/b30 |
phi|pg | /phihelp、/pghelp |
Koishi 的全局前缀与 cmdhead 分别生效。例如 Koishi 前缀为 !、cmdhead 为空时，可发送 !b30；全局前缀也为空时可直接发送 b30。原有 /、# 写法仍兼容。保存命令头设置后由 Koishi 重载插件并重新匹配指令。
管理标识和 Koishi 别名也可直接调用，例如 pg.b30、pg.score 曲名；兼容在参数中传入完整原始指令。复杂正则命令头无法还原为字面量时，可通过 args 传入完整原始指令。所有调用都会经过 Koishi 的命令权限检查；原有业务权限检查仍保留。
Koishi 设置页更新按钮
插件启用并加载控制台扩展后，设置表单顶部提供“更新插件”和“更新曲绘库”两行按钮，点击即可执行，无需保存设置。仅控制台权限等级 4 及以上用户可以执行；页面显示更新进度和结果，并阻止重复启动。
已有仓库执行 git pull --ff-only，保留当前分支和远程配置；有未提交修改或无法快进时停止，不强制覆盖。曲绘库尚未下载时，按已保存的 downIllUrl 和 githubProxy 克隆。插件更新完成后请重载插件，若依赖发生变化则重新运行安装脚本。按钮不会自动重启 Koishi；接入此控制台扩展无需改动本体 package.json。
Todo
功能
以下#均可用/代替，命令头可自定义
以下为用户功能
| 功能名称 | 功能说明 |
|---|
#phi帮助 | 获取帮助 |
#phi (cn|gb)?(bind|绑定)xxx | 绑定sessionToken，支持国服/国际服，默认为国服 |
#phi (unbind|解绑) | 仅清除当前 Bot 本地保存的 sessionToken、API ID、存档和历史，不修改 API 平台绑定 |
#phi clean | 删除所有记录 |
#phi (update|更新存档) | 更新存档 |
#phi (rks|pgr|b30) | 查询rks，会提供得出的b30结果 |
#phi x30 | 查询1Good b30 |
#phi fc30 | 查询Full Combo b30 |
杠批比三零 | 同上 |
#phi info(1|2)? | 查询个人统计信息 |
#phi lmtacc [0-100] | 计算限制最低 ACC 后的 RKS |
#phi (lvsco(re)|scolv) <定数范围> <难度> | 获取区间成绩 |
#phi chap <章节名称|help> | 获取章节成绩 |
#phi ahv <定数>[-v 版本] | 获取定数成绩表 |
#phi 理论分表 [-v 版本] | 查看指定版本的理论RKS分表（模拟数据，不依赖存档） |
#phi list <-dif 定数范围> <-acc ACC范围> <EZ|HD|IN|AT> <NEW|C|B|A|S|V|FC|PHI> | 获取区间每首曲目的成绩 |
#phi hisb30 | 根据历史记录计算B30变化情况 |
#phi best1(+) | 查询文字版b30（或更多），最高b99 |
#phi (score|单曲成绩)xxx [-dif 难度] [-or acc|score|fc|time] [-unrank] | 获取单曲成绩及这首歌的推分建议，参数为对分数排行的参数，目前仅开启API后有效 |
#phi (suggest|推分) |
以下为管理功能
| 功能名称 | 功能说明 |
|---|
#phi backup (back)? | 备份存档文件，+ back 发送该备份文件，自动保存在 /phi-plugin/backup/ 目录下 |
#phi restore | 从备份中还原，不会丢失已有数据，需要将文件放在 /phi-plugin/backup/ 目录下 |
#phi(设置别名|setnick) xxx ---> xxx | 设置某一歌曲的别名，格式为 原名(或已有别名) ---> 别名（会自动过滤--->两边的空格） |
#phi(删除别名|delnick) xxx | 删除某一歌曲的别名 |
#phi(强制|qz)?(更新|gx) | 更新本插件 |
#phi repu | 重启puppeteer |
#下载曲绘|down ill | 下载曲绘到本地 |
#phi get <名次> | 获取排行榜上某一名次的sessionToken |
#phi del <sessionToken> | 禁用某一sessionToken |
#phi allow <sessionToken> | 恢复某一sessionToken |
#phi (set|设置)<功能><值> | 修改设置，建议先/phi set查看功能名称，没有空格 |
#phi ban <功能> | 禁用某一类功能，详见 功能参数说明 |
#phi 获取Bot认领链接 | 主人命令 获取 15 分钟内有效的 Bot 平台认领链接，建议私聊发送 |
#phi 重置API Bot身份 | 主人命令 重新申请一套 API Bot 身份，仅用于凭据丢失、被撤销或主动更换身份 |
#phi ban 功能参数说明
| 参数 | 功能 | 影响指令 |
|---|
| 全部 | 全部功能 | 所有 |
| help | 帮助功能 | /help /tkhelp /myset |
| bind | 绑定功能 | /bind /unbind |
| b19 | 图片查分功能 | /pgr /update /info /list /pb30 /p30 /lmtacc /score /lvsco /chap /suggest |
| wb19 | 文字查分功能 | /data /best |
| song | 图鉴功能 | /song /chart /ill /search /alias /rand /randclg /table /cmt /recmt /addtag /subtag /retag |
| ranklist | 排行榜功能，不会禁用用户排名 | /ranklist /godlist |
| fnc | 小功能 | /com /tips /new |
| tipgame | tip猜歌 | /tipgame |
| guessgame | 猜歌 | /guess |
| ltrgame | 猜字母 | /letter /ltr |
| fribgame | 弗一把 | /friberg /fib /fri |
| sign | 娱乐功能 | /sign /send /task /retask /jrrp |
| setting | 系统设置 | /theme |
| dan | 段位认证相关 | /dan /danupdate |
API功能正式开启测试
可在设置项手动设置打开与关闭，开启后，将自动同步用户在Phi-Plugin系列应用（网页、云崽，暂不含koishi）使用记录与历史成绩到API端，且部分功能需要开启API后才能使用
| 功能名称 | 功能说明 |
|---|
#phi (bind|绑定) <userId> | 开启查分API可用，绑定API账号 |
#phi setApiToken <token> | 设置API Token |
#phi tokenList | 获取当前绑定的平台列表 |
#phi auth <api Token> | 通过API Token 获取 sessionToken |
#phi alias submit 曲目 | 别名 | 备注 | 私聊提交曲目别名提案 |
#phi alias mine | 查询自己的别名提案 |
#phi alias appeal 提案ID | 理由 | 私聊申请公开评审 |
#phi alias public | 查询正在公开投票的提案 |
#phi alias vote 提案ID 赞成/反对 | 参与公开投票或改票 |
#phi alias unvote 提案ID | 撤回公开投票 |
#phi clearApiData | 永久注销 phi-api 账号并清除云端数据，需要 Phigros SSTK 权限及二次确认 |
#phi updateHistory | 将BOT端的历史成绩更新到API端 |
#phi updateUserToken | 主人命令 上传当前BOT端的用户Token到API端 |
Bot 平台认领（Bot 主人）
认领用于把当前 phi-plugin 部署关联到已登录的网页账号，以便在网页控制台查看 Bot 状态、绑定统计和进行管理。Bot 在 API 注册成功后已经可以正常工作，未认领不会影响 Bot 激活或用户查分。
认领步骤：
- 将 phi-plugin 更新到支持 Bot 平台认证的版本，并确认配置项
openPhiPluginApi 已开启。
- 启动或重启一次 Bot。插件缺少 API Bot 身份时会自动向 API 注册，并将凭据写入本地配置；请勿公开或手工发送
apiBotClientSecret。
- Bot 主人在私聊中发送
#phi 获取Bot认领链接（也可使用 #phi botClaimLink）。
- 在 15 分钟内打开 Bot 返回的认领链接。若网页尚未登录，请先完成登录，随后继续原认领页面。
- 核对页面显示的 Bot 名称和
clientId，确认认领。完成后可在网页控制台的 Bot 管理页面查看和管理该 Bot。
认领链接为一次性链接，过期或使用后需重新发送命令获取。在群聊中执行时，插件不会把链接发到群内，而会将链接输出到 Bot 控制台；建议改为私聊执行。
#phi 重置API Bot身份（别名 #phi resetApiBot）会申请全新的 clientId 和 secret，并替换当前 Bot 身份。该命令不是正常认领步骤，只应在本地凭据丢失、身份被 API 撤销或确定要更换 Bot 身份时使用；重置后需要重新认领。为避免敏感信息泄露，在群聊中执行时，新的身份信息和认领链接只会输出到 Bot 控制台。
关于权限的详细说明：
仅通过查分ID即可绑定与获取存档，首次使用sessionToken绑定时会将API Token设置为sessionToken，且用户绑定时若提供sessionToken，bot端本地会保存。
支持我的创作
感谢您的支持，您的支持就是我创作的最大动力！
赞助者
感谢以下赞助者对本项目的支持，鸣谢名单可能更新不及时，欢迎来QQ催我！
部分功能预览
贡献者
感谢以下贡献者对本项目做出的贡献
Star History
免责声明
- 功能仅限内部交流与小范围使用，请勿将
Yunzai-Bot及phi-Plugin用于任何以盈利为目的的场景.
- 图片与其他素材均来自于网络，仅供交流学习使用，如有侵权请联系，会立即删除.
- 云存档由 7aGiven/PhigrosLibrary 改写而来
- 谱面标签采用 B 站 UP 主 空游呀 的分类方式，可前往 空游的小站 了解更多音游相关内容和分类资料。
- 谱师数据来源于 DP-Tool
写的不好，轻喷……
友情链接
