koishi-plugin-minecraft-adapter

Koishi 的 Minecraft 适配器插件，基于 鹊桥 (QueQiao) V2 协议，通过 WebSocket 与 Minecraft 服务器交互。

功能特性

• 鹊桥 V2 协议: 完整支持鹊桥 V2 WebSocket 协议
• WebSocket 连接: 通过鹊桥 WebSocket Server 实时接收/发送事件和消息
• RCON 命令执行: 通过鹊桥 WebSocket API send_rcon_command 执行服务器命令
• 多服务器支持: 通过 servers 数组配置多个 Minecraft 服务器，每个服务器独立运行
• 完整事件支持:
  • 玩家聊天 (PlayerChatEvent)
  • 玩家命令 (PlayerCommandEvent)
  • 玩家加入 (PlayerJoinEvent)
  • 玩家离开 (PlayerQuitEvent)
  • 玩家死亡 (PlayerDeathEvent)
  • 玩家成就 (PlayerAchievementEvent)
• 完整 API 支持:
  • 广播消息 (broadcast)
  • 私聊消息 (send_private_msg)
  • RCON 命令 (send_rcon_command)
  • 标题显示 (title)
  • 动画栏 (action_bar)
• 自动重连: WebSocket 断开后指数退避自动重连
• ChatImage 支持: 按服务器独立配置 ChatImage CICode 图片显示

前置需求

• Koishi v4.17.9+
• 鹊桥 (QueQiao) v0.3.0+ 服务端插件/Mod

安装

npm install koishi-plugin-minecraft-adapter

配置

全局配置

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | debug | boolean | false | 启用调试模式，输出详细日志 | | detailedLogging | boolean | false | 启用详细日志（入站解析和 dispatch 快照） | | tokenizeMode | 'split' \| 'none' | 'split' | 入站消息分词模式 | | reconnectInterval | number | 5000 | 重连间隔时间(ms) | | maxReconnectAttempts | number | 10 | 最大重连尝试次数 | | useMessagePrefix | boolean | false | 是否使用消息前缀 | | servers | array | [] | 服务器配置列表 |

服务器配置 (servers[])

每个服务器对应一个独立的 bot 实例。

| 配置项 | 类型 | 必填 | 说明 | |--------|------|------|------| | selfId | string | ✅ | 机器人唯一标识 | | serverName | string | ❌ | 服务器名称，需与鹊桥 config.yml 中的 server_name 一致 | | websocket | object | ✅ | WebSocket 配置（用于事件接收和消息发送） | | chatImage | object | ❌ | ChatImage 图片显示配置（仅对此服务器生效） |

WebSocket 配置 (servers[].websocket)

| 配置项 | 类型 | 必填 | 说明 | |--------|------|------|------| | url | string | ✅ | 鹊桥 WebSocket Server 地址（如 ws://127.0.0.1:8080） | | accessToken | string | ❌ | 访问令牌（与鹊桥 config.yml 中的 access_token 一致） | | extraHeaders | object | ❌ | 额外请求头 |

RCON（通过鹊桥 WebSocket）

插件侧不再直连 TCP RCON。执行命令时会通过鹊桥 V2 WebSocket API send_rcon_command 发送。

RCON 的启用与密码/端口等配置请在鹊桥端 config.yml 中完成。

ChatImage 配置 (servers[].chatImage)

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | enabled | boolean | false | 启用 CICode 图片发送（需客户端安装 ChatImage Mod） | | defaultImageName | string | '图片' | 图片在聊天栏中的默认显示名称 |

完整配置示例

单服务器

plugins:
  minecraft-adapter:
    debug: false
    tokenizeMode: split
    servers:
      - selfId: 'mc-server-1'
        serverName: 'TestServer'
        websocket:
          url: 'ws://127.0.0.1:8080'
          accessToken: 'your_token'
        chatImage:
          enabled: true
          defaultImageName: '图片'

多服务器

plugins:
  minecraft-adapter:
    debug: false
    servers:
      - selfId: 'survival'
        serverName: 'SurvivalServer'
        websocket:
          url: 'ws://192.168.1.10:8080'
          accessToken: 'token_survival'
        chatImage:
          enabled: true
      - selfId: 'creative'
        serverName: 'CreativeServer'
        websocket:
          url: 'ws://192.168.1.11:8080'
          accessToken: 'token_creative'

从旧版配置迁移

如果你使用的是旧版配置格式（bots + 全局 chatImage），插件会自动迁移并在日志中提示。建议尽快手动迁移到新格式：

旧格式（已弃用）：

plugins:
  minecraft-adapter:
    chatImage:
      enabled: true
    bots:
      - selfId: 'mc-1'
        websocket:
          url: 'ws://127.0.0.1:8080'

新格式：

plugins:
  minecraft-adapter:
    servers:
      - selfId: 'mc-1'
        websocket:
          url: 'ws://127.0.0.1:8080'
        chatImage:
          enabled: true

主要变更：

• bots → servers
• 全局 chatImage → 每服务器 chatImage
• websocket 现在是必填项

使用方法

监听事件

ctx.on('message', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`[${session.event.guild?.name}] ${session.event.user?.name}: ${session.content}`)
  }
})

ctx.on('guild-member-added', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`${session.event.user?.name} 加入了服务器`)
  }
})

ctx.on('guild-member-removed', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`${session.event.user?.name} 离开了服务器`)
  }
})

发送消息

// 广播消息（通过 bot 实例自动定位到对应服务器）
await bot.sendMessage('server-channel', '服务器即将重启')

// 向指定玩家发送私聊消息
await bot.sendPrivateMessage('Steve', '你好')

// 执行 RCON 命令（通过鹊桥 WebSocket API 执行）
const result = await bot.executeCommand('list')

鹊桥 V2 事件映射

| 鹊桥事件 | Koishi 事件类型 | |----------|----------------| | PlayerChatEvent | message | | PlayerCommandEvent | message (subtype: command) | | PlayerJoinEvent | guild-member-added | | PlayerQuitEvent | guild-member-removed | | PlayerDeathEvent | notice (subtype: player-death) | | PlayerAchievementEvent | notice (subtype: player-achievement) |

鹊桥 V2 API 映射

| 功能 | 鹊桥 API | 说明 | |------|----------|------| | 广播消息 | broadcast | 向所有在线玩家广播 | | 私聊消息 | send_private_msg | 向指定玩家发送消息 | | RCON 命令 | send_rcon_command | 执行服务器命令 | | 标题显示 | title | 显示标题和副标题 | | 动画栏 | action_bar | 显示动画栏消息 |

调试

启用 debug: true 后会输出详细日志，包括：

• 适配器初始化过程
• WebSocket 连接状态
• 接收到的原始消息数据
• 事件解析和会话创建过程
• API 请求和响应
• 断线重连过程
• 错误详情和堆栈跟踪

注意: 调试模式会产生大量日志，请仅在排查问题时启用。

协议参考

• 鹊桥文档
• 鹊桥 API 文档
• 鹊桥 GitHub

许可证

MIT