在已有的 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

包管理器优先按宿主唯一的锁文件识别，也可用 --manager npm、--manager yarn 或 --manager pnpm 指定。Yarn 需要 2+ 且使用 nodeLinker: node-modules。非默认 YAML 配置可用 --config 文件路径 指定。

安装前会将待修改的已有宿主文件和包装文件备份至宿主 .phi-plugin-install-backups/。安装失败时可据此恢复；脚本不会自动回滚已安装的依赖，也不会自动重启 Koishi。安装成功后请重启 Koishi 并刷新 WebUI。

请在控制台启用一个 database 服务。缺少 Puppeteer 时脚本会添加其依赖和配置，但保留已有服务的禁用状态。安装过程跳过浏览器下载，请通过 Koishi Puppeteer 服务配置可用的 Chrome / Chromium 路径。

若原先使用独立版本的同名koishi-plugin-phi-plugin插件，请先迁移，脚本不会覆盖它。

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。修改命令头时旧注册随重载清理；原来绑定旧指令标识的权限和别名设置需按新标识调整。游戏答题和会话确认仍作为普通消息处理。

顶层常用入口为 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 菜单中。命令头为空时省略根分组，例如 /b30、/songs alias。

Koishi 设置中的“Koishi 快捷指令”支持自定义以上默认菜单：使用一组树形勾选项：勾选分组即添加该分类菜单，展开后勾选子命令即将其添加到顶层快捷指令。父子独立勾选，不自动联动。单独勾选的功能不再在分类中重复显示，空分类自动省略；未选功能仍保留原聊天调用和权限检查，清空所有勾选可关闭快捷菜单。保存后由 Koishi 重载插件并自动同步。指令与非空分类合计最多 25 个顶层入口；默认已占满 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 调用。实际名称可在日志和指令管理中查看。

注册完成、命令头变更及插件卸载后，会以 500ms 防抖同步在线机器人，提交 Koishi 当前完整斜线指令树，保留其他插件的指令；同步中的后续变更会排队刷新，成功上传过的相同内容不重复提交。Discord 返回 429 时按 retry_after（秒）等待并增加 250ms 余量，随后自动上传最新指令树；等待期间重载插件也不会绕过冷却期限。无法解析限流等待时间时等待 30 秒，宿主关闭时取消重试。Discord 适配器须启用斜线指令；离线机器人仍由 Koishi 在上线时同步。其他更新失败会记录日志，可在连接恢复后重新加载插件重试。

注册前校验 Discord 限制：每层名称 1–32 字符、合法小写名称、最多三级、每层最多 25 个子项、全局最多 100 个根指令。超限会明确报错，不会截断名称或丢弃部分功能。上传前还会校验完整快照，校验失败则取消本次上传。Discord 中 /p help、/p b30 可直接执行，无需重复输入完整指令；曲名等参数填入可选的 args 字段，例如 /p score args:曲名，具体格式由业务功能校验。

聊天中继续使用原有写法，命令头 cmdhead 可以自定义、使用正则或留空：

Koishi 的全局前缀与 cmdhead 分别生效。例如 Koishi 前缀为 !、cmdhead 为空时，可发送 !b30；全局前缀也为空时可直接发送 b30。原有 /、# 写法仍兼容。保存命令头设置后由 Koishi 重载插件并重新匹配指令。

管理标识和 Koishi 别名也可直接调用，例如 pg.b30、pg.score 曲名；兼容在参数中传入完整原始指令。复杂正则命令头无法还原为字面量时，可通过 args 传入完整原始指令。所有调用都会经过 Koishi 的命令权限检查；原有业务权限检查仍保留。

插件启用并加载控制台扩展后，设置表单顶部提供“更新插件”和“更新曲绘库”两行按钮，点击即可执行，无需保存设置。仅控制台权限等级 4 及以上用户可以执行；页面显示更新进度和结果，并阻止重复启动。

已有仓库执行 git pull --ff-only，保留当前分支和远程配置；有未提交修改或无法快进时停止，不强制覆盖。曲绘库尚未下载时，按已保存的 downIllUrl 和 githubProxy 克隆。插件更新完成后请重载插件，若依赖发生变化则重新运行安装脚本。按钮不会自动重启 Koishi；接入此控制台扩展无需改动本体 package.json。