Majsoul-Plugin

✨ 基于TRSS-Yunzai的雀魂麻将多功能插件✨

说明文档 · 指令列表 · 常见问题

丨前言&插件简介

一个雀魂麻将多功能插件，插件不包括TRSS-Yunzai，应该配合TRSS-Yunzai使用：

项目地址：https://github.com/Xcheng-dada/Majsoul-Plugin

Tip

本插件在功能方向上受 Majsoul_bot 和 MajsoulUID 启发，核心逻辑由本团队使用 JavaScript 独立实现，并针对 TRSS-Yunzai 框架进行了适配。

Important

与上游项目差异

修复段位分显示负数、三麻走势图（修正为 3 条线）
雀士图鉴保持与官方同步更新，移除无效抽卡礼物

体验优化亮点

查询图表支持房间筛选，柱状图百分比显示
对局记录与订阅推送纯文字 → Canvas 重绘图片
搜索配图、帮助图重做，立绘随机展示
图表圆点与线条精确对齐，视觉效果更整洁

丨安装方法

在 TRSS-Yunzai 根目录下使用以下命令拉取本项目（建议加 --depth 1 仅克隆最新提交，减少下载体积）
```
git clone --depth 1 https://github.com/Xcheng-dada/Majsoul-Plugin.git ./plugins/Majsoul-Plugin
```
安装依赖（请确保当前位于 TRSS-Yunzai 根目录，pnpm install 会自动识别并安装本插件的依赖）
```
pnpm install
```
获取本地 API 程序（牌谱分析功能必需，否则无法使用 #牌谱Review / #雀魂场况）。该程序随本仓库 Release 一同发布，不在插件源码目录内。请前往本仓库的 Release 页面下载并解压，将对应平台的程序文件放置到插件目录下的 api/ 文件夹（详细步骤见下方「本地 API 程序从哪里获取？」）。
重启 TRSS-Yunzai，进入机器人在的群聊，即可正常使用本插件。

丨已实现的功能

丨雀魂抽卡模块

十连抽卡：模拟雀魂抽卡，自动合成并发送十连结果图片。
多卡池系统：支持多个UP卡池（包括经典卡池与新增卡池），可随时切换。
每日限制：每个用户每日默认可进行 5 次十连抽卡。
群组独立配置：每个QQ群可以独立设置和切换卡池，互不影响。
管理工具：机器人主人可为特定用户设定抽卡机会、重置抽卡次数，群成员可查询抽卡状态。

丨雀魂用户管理模块

玩家搜索：搜索玩家信息（昵称、UID、段位），支持多节点自动切换，也支持好友码搜索。
UID绑定：将雀魂玩家UID与QQ号绑定，便于后续查询。
多账号管理：支持绑定多个雀魂UID，并可设置主账号。
绑定切换：可随时切换已绑定的主账号。
账号解绑：支持解绑指定UID或全部解绑。

丨雀魂对局订阅模块

对局订阅：订阅指定玩家的四麻/三麻对局，自动推送到群聊。
定时检查：四麻每 3 分钟检查一次，三麻每 5 分钟检查一次（默认间隔，如需调整可在插件代码中修改 index.js 的 SCHEDULES 配置）。
播报内容：包含对局场次、牌谱链接、玩家信息（含分数和段位分变化）及时间。
灵活管理：支持查看订阅状态、临时开启/关闭播报、删除订阅。
注意：订阅依赖牌谱屋（amae-koromo）数据，受其 API 限制，仅 金之间及以上 有对局记录的玩家可订阅。

丨雀魂对局查询模块

即时查询：查询玩家最近对局记录，支持四麻和三麻。
详细信息：包含玩家排名、段位、分数、PT变化、房间类型、时间和牌谱链接。
多模式支持：支持通过昵称查询（省略昵称时使用已绑定UID），四麻用 #(雀魂/四麻)对局、三麻用 #三麻对局 分别查询。
段位场筛选：可在指令后追加段位场关键词，仅统计该场次的对局。支持 金之间/玉之间/王座之间，并支持模糊别名（如 金/金间、玉/玉间、王座/王座间），例如 #雀魂对局玩家名金。
注意：受牌谱屋（amae-koromo）API 限制，仅 金之间及以上 有对局记录的玩家可查询。

丨雀魂玩家数据查询模块

玩家数据查询：查询玩家详细战绩数据，分为四麻（#雀魂查询/#查询四麻）与三麻（#查询三麻）分别查询。
战绩统计：包含自摸率、和牌率、首位率、放铳率等详细数据。
对局走势：展示最近16场对局的分数走势图表（带房间筛选时仅展示该房间对局，走势标题显示房间名）。
段位场筛选：指令后追加段位场关键词（含上述模糊别名）后，仅展示对应房间的战绩与走势，顶部标题显示「昵称 · 房间名」。某模式无对局记录时该模式显示暂无数据。
友人场数据查询：#雀魂查询友/友人/友人场 <玩家名> 查看玩家友人场战绩（四麻）；三麻用 #查询三麻友 <玩家名>。
比赛场数据查询：#雀魂查询赛/赛事/比赛/比赛场 <玩家名> 查看玩家比赛场战绩（四麻）；三麻用 #查询三麻赛 <玩家名>。
好友码查询：#雀魂查询 <好友码> 通过好友码获取玩家战绩（需本地 API 已登录，自动转换好友码为 UID 后查询）。

丨雀魂AI牌谱分析模块

AI牌谱分析：通过 #牌谱Review <URL> 提交牌谱至 Mortal 进行 AI 分析，逐局生成牌谱分析图（含手牌、副露、吃碰杠过程与 AI 点评）。Mortal 引擎仅支持四麻牌谱（含四人东、四人半庄），三麻牌谱暂不支持 AI 分析（提交时直接提示不支持，详见下方常见问题）。
牌谱场况查看：通过 #雀魂场况 <URL> <局> [巡] 查看指定局/巡的牌谱过程图（局数、巡数均从 1 开始，巡数省略则展示整局），支持 #场况 / #牌谱详情 等价指令。需先对该牌谱执行过 #牌谱Review 后方可查看。
雀魂账号登录（必须）：牌谱分析依赖本地 API 登录态以获取牌谱原始数据及真实昵称/头像，未登录无法进行牌谱分析。通过 #雀魂登录 <账号> <密码> 登录，登录态由本地 API 持久保存。建议使用小号登录（详见下方常见问题）。

丨指令列表

Tip

所有指令均支持不加井号触发（如 雀魂十连 和 #雀魂十连 都有效）

抽卡相关

指令	说明	示例
`#雀魂十连`	进行十连抽卡。	`#雀魂十连`
`#查看雀魂卡池`	查看本群当前使用的卡池。	`#查看雀魂卡池`
`#查询抽卡次数 [QQ号]`	查询自己或他人的今日抽卡情况。	`#查询抽卡次数 123456`

用户管理

指令	说明	示例
`#雀魂搜索 <玩家名>`	搜索雀魂玩家信息（昵称、UID、段位）；也支持通过好友码搜索（`#雀魂搜索 <好友码>`，需本地 API 已登录）。	`#雀魂搜索玩家名`
`#雀魂绑定 <UID>`	绑定雀魂玩家UID（5-10位数字）。	`#雀魂绑定 12345678`
`#雀魂切换 <UID>`	切换已绑定的主账号。	`#雀魂切换 12345678`
`#雀魂解绑 [UID]`	解绑指定UID（不填则解绑全部）。	`#雀魂解绑` / `#雀魂解绑 12345678`
`#雀魂我的绑定`	查看自己绑定的所有雀魂UID。	`#雀魂我的绑定`

对局查询

指令	说明	示例
`#(雀魂/四麻)对局 [玩家名] [房间]`	查询玩家最近5场四麻对局记录，省略玩家名时使用已绑定UID；可追加房间筛选（金之间/玉之间/王座之间等，支持模糊别名）。	`#雀魂对局玩家名 [金]`
`#三麻对局 [玩家名] [房间]`	查询玩家最近5场三麻对局记录，省略玩家名时使用已绑定UID；可追加房间筛选。	`#三麻对局玩家名 [玉间]`

对局订阅

指令	说明	示例
`#(雀魂/四麻)订阅 <玩家名>`	订阅玩家四麻对局播报（自动推送到本群）。	`#雀魂订阅玩家名`
`#三麻订阅 <玩家名>`	订阅玩家三麻对局播报（自动推送到本群）。	`#三麻订阅玩家名`

玩家数据查询

指令	说明	示例
`#雀魂查询 [玩家名] [房间]`	查询玩家四麻详细数据（图片形式），省略玩家名时使用已绑定UID；可追加房间筛选（金/金间/金之间、玉/玉间/玉之间、王座/王座间/王座之间等）。`#查询四麻` 与其等价。	`#雀魂查询玩家名 [玉]`
`#查询三麻 [玩家名] [房间]`	查询玩家三麻详细数据（图片形式），省略玩家名时使用已绑定UID；可追加房间筛选。	`#查询三麻玩家名 [王座]`
`#雀魂查询友/友人/友人场 <玩家名>`	查询玩家友人场数据（`#查询四麻`/`#查询三麻` 前缀同理）。	`#雀魂查询友玩家名`
`#雀魂查询赛/赛事/比赛/比赛场 <玩家名>`	查询玩家比赛场数据（`#查询四麻`/`#查询三麻` 前缀同理）。	`#雀魂查询比赛玩家名`
`#雀魂查询 <好友码>`	通过好友码查询玩家战绩（需本地 API 已登录）。	`#雀魂查询 12345678`

AI牌谱分析

指令	说明	示例
`#牌谱Review <URL> [座位]`	提交牌谱至 Mortal 进行 AI 分析，逐局生成牌谱分析图（须先登录，未登录时直接提示无法分析）。`[座位]` 可选，支持 `东/南/西/北` 或 `1/2/3/4`（1=东，2=南，3=西，4=北），指定后分析该座位玩家；省略时按牌谱主视角分析。	`#牌谱Review https://game.maj-soul.com/1/?paipu=xxx 北`
`#雀魂场况 <URL> <局> [巡]`	查看指定牌谱某局某巡的场况图（局数、巡数均从1开始，巡数可省略；亦支持 `#场况` / `#牌谱详情`）。需先对该牌谱执行过 `#牌谱Review` 后方可查看。	`#雀魂场况 https://game.maj-soul.com/1/?paipu=xxx 1 1`
`#雀魂登录 <账号> <密码>`	登录雀魂账号以获取牌谱原始数据及真实昵称/头像（必须，取谱依赖本地 API 登录态）；登录态由本地 API 持久保存。建议使用小号。	`#雀魂登录 12345678 mypassword`

管理员专用 (`permission: 'admin'`)

指令	说明	示例
`#(开启/关闭)雀魂抽卡`	开启或关闭本群的抽卡功能。	`#开启雀魂抽卡` / `#关闭雀魂抽卡`
`#切换雀魂卡池 <卡池名称>`	切换本群的抽卡卡池。	`#切换雀魂卡池辉夜大小姐想让我告白`
`#(雀魂/四麻/三麻)订阅状态`	查看本群的订阅列表。	`#雀魂订阅状态` / `#三麻订阅状态`
`#开启(雀魂/四麻/三麻)订阅 <玩家名>`	开启订阅（若已存在则恢复播报，仅管理员可操作）。	`#开启雀魂订阅玩家名`
`#关闭(雀魂/四麻/三麻)订阅 <玩家名>`	关闭订阅（暂停播报，保留订阅记录，仅管理员可操作）。	`#关闭雀魂订阅玩家名`
`#删除(雀魂/四麻/三麻)订阅 <玩家名>`	删除订阅（彻底移除该订阅，仅管理员可操作）。	`#删除三麻订阅玩家名`

主人专用 (`permission: 'master'`)

指令	说明	示例
`#设置用户次数 <QQ号> <次数>`	设置指定用户的今日剩余抽卡次数。	`#设置用户次数 123456 5`
`#重置用户次数 <QQ号>`	重置指定用户的今日抽卡记录。	`#重置用户次数 123456`
`#设置token <token>`	配置牌谱屋 Bearer token（仅支持私聊机器人且需为主人）。配置后玩家搜索 / 对局订阅 / 对局查询 / 玩家数据查询等依赖牌谱屋 API 的功能方可使用。	`#设置token xxxxx`

支持的卡池（持续更新中）

经典卡池

常驻池
辉夜大小姐想让我告白
咲-Saki-1
咲-Saki-2
斗牌传说
狂赌之渊
限定池
反叛的鲁路修
Fate系列
银魂
魔法少女伊莉雅
蔚蓝档案
偶像大师闪耀色彩
刀剑神域

Note

关于限定装扮的说明：由于限定装扮数量庞大、复刻时间不固定，且部分限定装扮为活动获取而非抽卡获取，因此目前不考虑单独增加限定装扮卡池。限定池仅包含可通过抽卡获取的限定雀士。

丨常见问题 Q&A

丨抽卡时提示"插件加载错误"或类似错误？

确保依赖已安装：在TRSS-Yunzai根目录内执行 pnpm install。
检查Node.js版本：确保版本为 18 或以上。
重启Yunzai：修改配置或安装依赖后，请重启机器人。
查看详细日志：错误信息通常会在控制台输出，根据日志排查问题。

丨管理员指令没有反应？

请确认发送指令的QQ号已在TRSS-Yunzai的 config.yaml（或类似配置）中设置为管理员 (admin) 或主人 (master)。

丨搜索玩家时提示"暂未搜索到该玩家"？

可使用好友码查询：若提示暂未搜索到该玩家，可使用好友码查询——#雀魂查询 <好友码> 或 #雀魂搜索 <好友码>（需本地 API 已配置并登录）。
检查昵称是否正确：请确保输入完整的玩家昵称。
尝试英文名搜索：部分玩家可能使用英文名或特殊字符。

丨绑定UID时提示"UID格式不正确"？

雀魂UID为5-10位数字，请检查输入是否正确。
确保输入的是纯数字UID，不包含其他字符。

丨切换UID时提示"尚未绑定该UID"？

请先使用#雀魂我的绑定查看已绑定的UID列表，然后使用列表中的UID进行切换。

丨为什么抽不到某些限定装扮？

限定装扮大部分通过活动获取或限时复刻，由于复刻时间不确定且获取方式多样，目前插件未收录所有限定装扮。

丨魂天段位图标为什么没有等级区分？

目前魂天 1~20 级统一使用魂天图标（暂无分级素材）。
如您有官方分级图标资源，欢迎提交 PR 补充。
雀魂官方目前只开放魂天最高 20 级，所以 20 级只显示当前魂珠数量，达到 20 魂珠后不再升级。

丨玩家数据查询图片中的雀士服饰是怎么决定的？

查询图片会依照玩家当前使用的服饰输出对应立绘；仅当该服饰未被收录时，才会从 person_full 文件夹随机选择立绘代替。

丨使用牌谱分析功能时提示"当前未登录"？

原因：未登录是因为本地 API 没有登录态，无法获取牌谱原始数据，因此无法进行分析。
解决：请先执行 #雀魂登录 <账号> <密码> 完成登录。
说明：登录态由本地 API 持久保存，登录一次后无需重复登录。
⚠️ 账号安全提示：登录由本地 API（Majsoul.ProtocolLogin.Api 对应平台程序）保存账号密码并持有登录态，操作真实账号，建议使用小号登录，切勿使用重要主账号，本插件不保证账号的绝对安全。

丨本地 API 程序从哪里获取？

本地 API 程序（Windows 为 Majsoul.ProtocolLogin.Api-win-x64.exe，Linux 为 Majsoul.ProtocolLogin.Api-linux-x64）随本仓库的 Release 一同发布，不在插件源码目录内。
若要使用牌谱分析功能，请前往本仓库的 Release 页面，下载对应平台（Windows / Linux）的压缩包并解压，将解压得到的程序文件放置到插件目录下的 api/ 文件夹：
```
Majsoul-Plugin/api/Majsoul.ProtocolLogin.Api-win-x64.exe   # Windows
Majsoul-Plugin/api/Majsoul.ProtocolLogin.Api-linux-x64    # Linux
```
放置完成后启动 Yunzai，插件会根据配置自动拉起该程序（监听 127.0.0.1:5088，Windows 与 Linux 均支持自动拉起），拉起后直接用 #雀魂登录 <账号> <密码> 完成登录即可。
该程序自带以下本地页面，可供查看与调试：
- WebUI：http://127.0.0.1:5088
⚠️ 该程序与 5088 端口一一绑定，同一时间只能有一个实例运行。若手动再开一个会因端口被占用而闪退。请勿重复启动。

丨AI牌谱分析支持哪些规则/模式？

当前引擎（Mortal）：支持四麻牌谱，含四人东与四人南，且需为**一般规则（标准规则）**牌谱。
三麻暂不支持：当前 Mortal 引擎不支持三人麻将，三麻牌谱目前无法使用 AI 分析功能。

丨为什么玩家搜索 / 对局订阅 / 对局查询提示需要 token？

雀魂牌谱屋（amae-koromo）的 API 现在需要 Bearer token 才能访问数据，未配置 token 时以下功能将不可用：
- 玩家搜索（#雀魂搜索）
- 对局订阅（#雀魂订阅 等播报）
- 对局查询（#雀魂对局 / #三麻对局）
- 玩家数据查询（#雀魂查询 / #查询三麻）
如何获取 token：需自行联系牌谱屋（amae-koromo）作者获取专属 Bearer token。
如何配置：获取到 token 后，【私聊机器人】 发送（仅私聊支持，且需为机器人主人）：
```
设置token <你的token>
```
配置成功后立即生效并保存至 data/token.json，无需手动编辑文件；也可直接写入 data/token.json 的 {"token":"你的token"}。

丨感谢

DaiShengSheng / Majsoul_bot ：本项目抽卡、对局记录、对局订阅等功能的设计思路参考来源。核心逻辑由本团队使用 JavaScript 独立实现，非原项目移植。
SAPikachu / amae-koromo ：雀魂牌谱屋项目，提供玩家数据查询API。
KimigaiiWuyi / MajsoulUID ：本项目玩家数据查询、AI牌谱分析功能的设计思路参考来源。基础逻辑由协作者 QingFeng 完成 Python → JavaScript 初始实现，后续由本项目作者进行了深度 Bug 修复、视觉重构与功能增强。
QingFeng ：玩家数据查询、AI牌谱分析功能的基础逻辑初始实现者（Python → JavaScript），对本项目的早期版本有重要贡献。
homura / majsoul.wget.es ：远程 AI 评审接口（本插件牌谱分析的数据来源），其 Review 服务支持以下引擎：
- Equim-chan / Mortal ：本插件实际使用的 AI 引擎。
Ayu ：本地 API（协议登录雀魂）作者。

Name		Name	Last commit message	Last commit date
api		api
apps		apps
components		components
config		config
resources		resources
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
guoba.support.js		guoba.support.js
index.js		index.js
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation