koishi-plugin-prism

v0.1.34

Published

3 days ago

PRiSM Next 计费与设备管理系统的 Koishi 机器人集成插件

0High
0Medium
0Low

akachandesu

koishi plugin prism prism-next billing device-management

koishi-plugin-prism

koishi-plugin-prism 是用于连接 PRiSM Next 计费与设备管理系统的 Koishi 机器人插件。它可以替代旧版 plugin-prism-neo-koishi，为玩家和店员提供便捷的群内与私聊机器人交互指令。

🌟 功能特性

🎮 玩家入场与结算：通过 /login 和 /logout 指令开启或结算计费场次，支持 /入场 别名；命令回复会引用触发消息，结账账单可私聊通知管理员与指定用户。
💳 账户钱包与资产管理：支持查询钱包余额（/wallet）和持有的道具资产（/items）。
🀄 麻将桌位集成：包含 /mahjong <tableId>、/上桌 <桌号>、自动识别当前桌位的 /下桌，以及用于查看桌名、别名和状态的 /麻将列表。上桌 仅允许已通过 login/入场 开启默认入场会话的玩家使用。支持在桌位未满但已开局时进行中途补位（直接开始计费上桌），且玩家下桌时会自动显示剩余游玩人数。list 按 session 标签分组：有非音乐游戏 session 的玩家归入最新的非音乐标签，纯音乐玩家归入音乐标签；麻将桌额外显示当前人数和容量。已开局桌位会从后端活跃 session 自动恢复，未满桌候座仍由机器人进程暂存，重启后不会保留。
🔌 硬件设备状态与电源管理：可直接在聊天中查看设备状态（/show）、远程开启/关闭电源（/on、/off）、远程投币（/coin）和模拟刷卡（/scan）。
🎟️ 礼物兑换码：使用 /redeem <code> 兑换系统发放的福利礼包。
🛠️ 管理员快捷指令：允许管理员为指定平台用户增加或扣除余额，并覆盖结账金额后立即结账。

⚙️ 配置说明

在 Koishi WebUI 的插件配置页面中，填入以下选项：

麻将桌配置

在 Koishi 配置页的 mahjongTableConfigs 中新增桌位，每一项填写：

displayName: "🀄️ M.LEAGUE联名比赛专用机"
aliases: [a, 四麻A, 比赛机]
pricingConfigIds: [pricing-mahjong-a]

displayName 是该桌的稳定锚点和 session 标签；玩家输入的桌号、简称等均写入 aliases（至少一个）。麻将桌只读取这个结构化列表。

管理员快捷指令必须同时配置 enableStaffCommands: true 与 staffUserIds。它们使用现有 integrationToken 调用受限的余额调整和立即结账接口；目标用户参数使用 Koishi 的 user 选择器，只有白名单内的管理员可以操作其他用户。

📝 机器人指令列表

玩家指令

register - 绑定或注册当前平台账号到 PRiSM 账户。
login / 入场 - 开启当前玩家的计费场次。
logout - 结算当前玩家的计费场次。玩家在未产生任何费用时退场，机器人会简洁显示“本次未产生费用”和当前余额；存在收费或优惠明细时仍显示完整结算账单。负单价 session 会在区间明细中保留真实的负数计费贡献，只有后端汇总全部 session 后的最终应付金额会限制为不低于 0。结账成功回执中的余额为后端已经完成扣款后的余额；只有 /billing 预览会显示当前余额与预计结账后余额。方案内区间封顶直接计入对应计时费用；全局封顶按后端返回的结构化日期和时段逐条列出，不合并、不截断，并直接形成计费总价，不作为优惠。只作用于整次结账的资产优惠直接列在计费总价下方，不显示额外标题或 emoji，也不会误归属到最后一个 session。在玩家退场或管理员覆盖结账成功后，机器人会向 staffUserIds 与 logoutNotifyUserIds 中的用户私聊同一份账单，账单会明确显示结账玩家身份。同一玩家在前一次退场结账尚未完成时重复发送 /logout 或 /退场，机器人会复用同一次结账请求与账单，避免重复扣款。账单和管理员代操作回执均使用“平台昵称（QQ：号码）”称呼玩家；平台暂时无法提供昵称时显示“未知昵称（QQ：号码）”，不会显示内部玩家 ID。管理员 /add 增加免费余额；/del 按结账相同的顺序从可用免费余额、再从付费余额扣除，余额不足时会返回余额不足提示。
billing - 预览当前玩家本场计费的消费费用。
wallet - 查看当前玩家的钱包余额。
items - 查看当前玩家持有的道具或资产。
list - 查看当前在线/在店游玩玩家的列表，按 session 标签分组并对同一玩家去重；存在非音乐游戏 session 时取最新的非音乐标签，麻将桌显示当前人数和容量。已开局桌位由后端 session 恢复；未满桌候座由机器人进程暂存，机器人重启后不会保留。
show [deviceId] - 查看设备电源与连接状态。
history - 查看自己的历史游玩记录。
lock - 发送开门指令。
on <deviceRef> - 使用后台设备名称、别名或 all 请求启动电源；不接受 Home Assistant entity ID，成功回复使用后端返回的设备名称。
off <deviceRef> - 使用后台设备名称、别名或 all 请求关闭电源；不接受 Home Assistant entity ID，all 显示为“所有设备”。
coin <deviceId> [count] - 请求向指定设备投币指定枚数。
scan <deviceId> <subject> - 请求向设备发送模拟刷卡。
redeem <code> - 兑换礼物码。
mahjong <tableId> / 上桌 [tableId] - 加入指定麻将桌；/上桌 未提供桌号时会引导查看 /麻将列表。仅允许已通过 login/入场 开启默认入场会话的玩家使用。支持在桌位未满但已开局时进行中途补位（即直接开始计费上桌）。
下桌 - 自动离开当前所在麻将桌，下桌后会停止计费，并显示该麻将桌的剩余游玩人数。
麻将列表 - 查看已配置机器的桌名、命令别名，以及空闲、等位或游玩中状态。
api测速 [次数] - 连续查询自己的钱包，显示 Bot 到 PRiSM API 的最小、平均与最大延迟（默认 3 次，最多 10 次）。
versions - 显示当前 Bot npm 包版本和后端发布版本；后端不可达时仍会显示 Bot 版本。

Bot 版本直接读取本 npm 包的 package.json，后端版本读取无需认证的 GET /version。插件发布遵循 SemVer；修复使用 patch、兼容新增功能使用 minor、不兼容改动使用 major，发布前通过 npm version <patch|minor|major> 自动更新包版本。

管理员快捷指令

启用 enableStaffCommands、配置 staffUserIds 白名单与 staffSessionToken 后可使用：

add <target:user> <amount:number> - 为目标用户增加余额。
del <target:user> <amount:number> - 从目标用户扣除余额。
overwrite <target:user> <amount:number> [reason:text] - 覆盖目标用户本次结账金额，并立即执行结账；未填写原因时使用默认管理员调价原因。

🛠️ 本地开发与构建

确保已安装 Node.js 和 bun。

克隆本仓库：

git clone https://github.com/nerimoe/koishi-plugin-prism.git
cd koishi-plugin-prism

安装依赖并执行编译：
```
bun install
bun run build
```
运行单元测试：
```
bun run test
```

📄 开源协议

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

koishi-plugin-prism

🌟 功能特性

⚙️ 配置说明

麻将桌配置

📝 机器人指令列表

玩家指令

管理员快捷指令

🛠️ 本地开发与构建

📄 开源协议