docs/protocol.md

协议规范

本文档定义了 InterConnect-Server 使用的 REST 和 WebSocket 协议格式。所有负载均为 JSON 格式。

认证 (Authentication)

• REST: 在请求头中发送 Authorization: Bearer <API_KEY>。
• WebSocket: 连接到 ws://<host>/ws?api_key=<API_KEY>（HTTPS 下使用 wss）。

事件对象 (Event Object)

事件通过 REST 发送到服务器，并广播给 WebSocket 客户端。 服务器仅验证必填字段和 event_type 值。 data 负载会原样传递。

必填字段：

• event_type (字符串)
• server_name (字符串)
• timestamp (字符串, ISO 8601)
• data (对象)

有效的 event_type 值：

• player_join - 玩家加入服务器
• player_quit - 玩家退出服务器
• player_death - 玩家死亡
• player_chat - 玩家与AI聊天消息
• player_message - 玩家公屏聊天消息
• remote_command - 远程命令执行
• server_start - 服务器启动
• server_stop - 服务器停止

事件数据字段

事件类型	监听器	数据字段
player_join	PlayerJoinEvent	player_name, uuid
player_quit	PlayerQuitEvent	player_name, uuid, playtime (在线时长秒数)
player_death	PlayerDeathEvent	player_name, uuid, death_message, killer (如果是被玩家杀死)
player_chat	AsyncChatEvent (1.19+) / AsyncPlayerChatEvent (1.8-1.18)	message, player_name, uuid
player_message	AsyncChatEvent (1.19+) / AsyncPlayerChatEvent (1.8-1.18)	message, player_name, uuid
remote_command	ServerCommandEvent	command, sender
server_start	PluginEnableEvent	server_id, max_players, version
server_stop	PluginDisableEvent	server_id

事件说明

• player_chat：监听玩家与AI的聊天事件。当配置了 auto_respond_chat: true 时，所有自动回复监听到的消息都归类为 player_chat。
• player_message：监听玩家与其他玩家的聊天事件（公屏聊天）。

事件示例：

{
  "event_type": "player_join",
  "server_name": "survival-01",
  "timestamp": "2024-01-21T12:34:56.789Z",
  "data": {
    "player": "Steve"
  }
}

REST 端点 (REST Endpoints)

POST /api/events

提交一个事件以进行存储和广播。

请求：

• 认证：任意有效密钥
• Content-Type: application/json
• Body: 事件对象

响应：

{
  "message": "Event received and broadcasted"
}

错误：

• 400 如果缺少必填字段或 event_type 无效
• 401 如果 API 密钥丢失/无效

POST /api/server/command

发送服务器命令。这也将广播一个 server_command 事件。

请求：

• 认证：Regular 或 Admin 密钥
• Content-Type: application/json
• Body:

{
  "command": "say Hello from API",
  "server_id": "survival-01"
}

注意：

• 当 Admin 密钥未绑定到服务器时，必须提供 server_id。
• 服务器对 Admin 命令强制执行允许/阻止列表。

响应：

{
  "message": "Command sent successfully",
  "command": "say Hello from API",
  "server_id": "survival-01"
}

WebSocket 消息 (WebSocket Messages)

客户端到服务器

Ping:

{ "type": "ping" }

Pong 响应:

{ "type": "pong" }

服务器到客户端

广播事件：

{
  "type": "minecraft_event",
  "event": {
    "event_type": "message",
    "server_name": "survival-01",
    "timestamp": "2024-01-21T12:34:56.789Z",
    "data": {
      "player": "Alex",
      "message": "Hello world"
    }
  },
  "source_key_id_prefix": "a1b2c3d4"
}

source_key_id_prefix 是提交事件或命令的 API 密钥 ID 的前 8 个字符。它不是 API 密钥本身。