📖 中文文档 📖 English Documentation

📦 构建工作流文档 — 版本发布流程与构建配置

mcdr_listener_ws_server

~~💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入QQ群：259248174 🎉（这个群G了~~

💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入QQ群：1085190201 🎉

💡 在群里直接艾特我，回复的更快哦~ ✨

🚀 3 分钟快速上手

Step 1: 配置 WebSocket 服务

将插件放入 MCDR 插件目录，安装依赖: uv pip install -r requirements.txt
加载插件，编辑生成的 config/mcdr_listener_ws_server/config.yml
修改 ws_token 为你自己的密码
确认 host（默认 0.0.0.0）和 port（默认 60601）可被客户端访问

Step 2: 配置 Koishi 客户端

在 Koishi 端安装 mclistener-ws-client，配置:

wsServerUrl: 指向本插件的 WebSocket 地址
wsToken: 与服务端 ws_token 一致
sourcePlatformList / targetPlatformChannelList: 你的群/频道

Step 3: 验证

群里发消息 → 游戏内应显示 [群名] (群号) 昵称: 消息
游戏内说话 → 群里应收到玩家聊天消息

💡 图片渲染和远程命令需额外配置 RCON，见下方说明。

📡 互通架构

聊天平台一侧

聊天平台 图文消息 ⇄ Minecraft Java服务器 文字消息与进出服事件 的群服互通插件。

支持 Koishi Bot 接入，理论上 Koishi 支持的大部分聊天平台均可使用。

已有现成的 Koishi 插件: https://github.com/VincentZyuApps/koishi-plugin-mclistener-ws-client

QQ 接入（OneBot v11 协议端）：Koishi 通过 @koishijs/plugin-adapter-onebot 适配器，对接 OneBot v11 协议的实现端（如 LLOneBot、NapCat、Lagrange.OneBot 等），由协议端连接 QQ 服务器，实现 QQ 群消息的双向互通。
Discord 接入（Discord Bot API）：Koishi 通过 @koishijs/plugin-adapter-discord 适配器，在 Discord Developer Portal 创建 Bot 应用并获取 Token，直连 Discord Gateway API，实现 Discord 频道消息的双向互通。
更多平台：Kook、Telegram 等 Koishi 支持的平台均可

我自己的测试环境和生产环境: QQ（OneBot v11 / LLOneBot）/ Discord

当然你也可以自己编写插件把他接入到其他的Bot框架，比如Koishi，Nonebot2，Astrbot等等，或者其他任何形式的Web应用的 WebSocket客户端接入。

Minecraft Java服务器一侧

支持 MCDReforged 兼容的部分 Minecraft Java 服务端发行版。

我自己的测试环境和生产环境: Spigot / Paper 1.21.8

如果你运行的是 基岩版 (BDS + LeviLamina)，请使用 levilamina-plugin-mclistener-ws-server（与本插件使用同一 WebSocket 协议，可共用 Koishi 客户端）。

👀 它能做什么

→ 聊天平台 → MC 服务器

文字消息转发到游戏内
图片消息以 tellraw 可点击文本广播给所有在线玩家，点击后触发 !!view_image 渲染为 text_display 实体

QQ（OneBot v11）:

Discord:

→ MC 服务器 → 聊天平台

玩家聊天消息转发到平台
玩家加入/退出服务器通知转发到平台

QQ（OneBot v11）:

→ MC 服务器内

玩家可用 !!view_image <url> 命令手动查看远程图片

→ 聊天平台 → MC 服务器（远程命令执行）

通过聊天平台远程执行 MC 服务器 RCON 命令，结果回传至聊天平台

QQ（OneBot v11）:

⚠️ 前置条件：启用 RCON

以下核心功能必须启用 RCON 才能使用：

🖼️ 游戏内展示外部图片（!!view_image 命令 + 图片消息渲染）
🖥️ 远程命令执行（从聊天平台执行 MC 服务器命令并返回结果）

如果你只需要基础的文字消息转发和进出服通知，可以跳过此步骤。

配置步骤

1. Minecraft 服务器 — 在 server.properties 中启用 RCON：

enable-rcon=true
rcon.port=25575
rcon.password=你的RCON密码

2. MCDR 主配置文件 — 在 MCDR 的 config.yml 中配置 RCON（插件通过 MCDR 的 RCON 接口执行命令）：

rcon:
  enable: true
  address: 127.0.0.1
  port: 25575
  password: 你的RCON密码

安装

将插件放入 MCDR 插件目录，确保依赖已安装：

mcdreforged >= 2.13.0
websockets >= 15.0.0
Pillow >= 10.0.0
requests >= 2.32.0

git clone https://github.com/VincentZyuApps/mcdr_listener_ws_server ./plugins/mcdr_listener_ws_server
# 或国内镜像
git clone https://gitee.com/vincent-zyu/mcdr_listener_ws_server.git ./plugins/mcdr_listener_ws_server

uv pip install mcdreforged
uv pip install -r requirements.txt

若在 Windows 下运行，建议MCDR的config.yml的encoding和coding都改成GBK，避免 emoji 等字符问题。Linux可以都用utf-8

配置

首次加载后自动从 resources/ 释放默认配置模板到 config/mcdr_listener_ws_server/config.yml，主要选项：

插件支持国际化（i18n），玩家可见消息文本可在 lang/ 目录下按需修改（zh_cn.yml / en_us.yml）。

配置项	说明	默认值
`host`	🌐 监听地址	`0.0.0.0`
`port`	🔌 监听端口	`60601`
`ws_token`	🔑 WebSocket 连接 Token（空字符串=不校验）⚠️ 默认值仅用于测试	`"test12345"`
`enable_remote_exec_command`	⚡ 启用远程命令执行	`false`
`remote_exec_command_whitelist`	🛡️ 远程命令前缀白名单（空列表=不限制）	`[]`
`remote_exec_command_timeout_sec`	⏱️ 命令执行超时（秒）	`10`
`remote_exec_result_max_length`	📏 返回结果最大字符数，超长截断	`4000`
`strip_message_whitespace`	🧹 清理消息中的换行和制表符（`\n` `\r` `\t` → 空格，避免游戏内消息断裂）	`true`
`cache_dir`	📂 图片缓存目录	`./cache/mcdr_listener_ws_server/images/`
`image_max_side_length`	📐 图片最大边长	`64`
`image_duration_sec`	⏱️ 图片展示时长（秒）	`10`
`image_cache_ttl_sec`	🧹 图片缓存保留时长（秒）	`180`
`image_host_whitelist`	🛡️ 图片域名白名单，每个域名可单独配置代理（空=直连，填代理地址=走代理）	`multimedia.nt.qq.com.cn`(直连), `gxh.vip.qq.com`(直连), `cdn.discordapp.com`(走代理), `media.discordapp.net`(走代理)
`view_image_permission`	🎮 !!view_image 所需权限等级（`0`=不限制）	`0`
`view_image_player_whitelist`	🎮 !!view_image 玩家白名单（`[]`=不限制）	`[]`

如需本地测试（本地起一个 WS 客户端模拟聊天平台接入），可在生成的配置文件 config/mcdr_listener_ws_server/config.yml 中将 127.0.0.1 加入 image_host_whitelist：
image_host_whitelist:
  - host: multimedia.nt.qq.com.cn
  - host: gxh.vip.qq.com
  - host: cdn.discordapp.com
    proxy: http://127.0.0.1:7890
  - host: media.discordapp.net
    proxy: http://127.0.0.1:7890
  - host: 127.0.0.1
!!view_image 权限判定逻辑（四种组合）：

条件行为
仅 view_image_player_whitelist 不为空检查玩家是否在白名单中，不在则拒绝
仅 view_image_permission > 0 检查玩家 MCDR 权限等级是否达标，不达标则拒绝
两者都配置 满足任一条件即可（白名单或权限等级达标）
两者都为空/默认 所有玩家可用（默认行为）

条件	行为
仅 `view_image_player_whitelist` 不为空	检查玩家是否在白名单中，不在则拒绝
仅 `view_image_permission > 0`	检查玩家 MCDR 权限等级是否达标，不达标则拒绝
两者都配置	满足任一条件即可（白名单或权限等级达标）
两者都为空/默认	所有玩家可用（默认行为）

命令

`!!view_image <url>`

玩家执行后在面前以 text_display 展示远程图片。
需满足：由玩家执行 + 图片域名在白名单内。
命令反馈文本从 lang/ 语言文件读取，支持自定义。

WebSocket 事件格式

服务端广播事件

玩家进入 🎉

{
    "type": "player_join",
    "player_name": "some_name"
}

玩家离开 😢

{
    "type": "player_leave",
    "player_name": "some_name"
}

玩家聊天 💬

{
    "type": "player_chat",
    "player_name": "some_name",
    "content": "some_content"
}

客户端入站事件

客户端向服务端发送以下 JSON 消息。

平台消息转发 📨

{
    "type": "chat_platform_to_server",
    "nickname": "用户名",
    "message": "消息内容",
    "group_id": "123456",
    "group_name": "群名称",
    "images": [
        {
            "url": "https://example.com/image.png",
            "name": "image.png"
        }
    ]
}

images 字段可选，携带时会在游戏内以 text_display 实体渲染展示图片。

远程命令执行 🖥️

{
    "type": "external_command_to_server",
    "command": "list"
}

服务端执行后将返回结果：

{
    "type": "command_result",
    "command": "list",
    "result": "..."
}

⚠️ 一些已知限制

图片域名需在白名单: 图片 URL 的域名必须在 image_host_whitelist 中，否则不会下载/渲染
!!view_image 全服冷却: 该命令有全服共享冷却（默认 5.5 秒），冷却期间其他玩家无法使用
远程命令需双边配置: 需要同时开启插件 enable_remote_exec_command 和客户端相应配置
Windows 编码: Windows Powershell下运行 MCDR 的 config.yml 建议将 encoding和decoding 设为 GBK，避免一些字符的编码问题比如emoji，Linux可以都用utf-8