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`：监听玩家与其他玩家的聊天事件（公屏聊天）。

事件示例：
```json
{
  "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: 事件对象

响应：
```json
{
  "message": "Event received and broadcasted"
}
```

错误：
- `400` 如果缺少必填字段或 `event_type` 无效
- `401` 如果 API 密钥丢失/无效

### POST /api/server/command

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

请求：
- 认证：Regular 或 Admin 密钥
- `Content-Type: application/json`
- Body:
```json
{
  "command": "say Hello from API",
  "server_id": "survival-01"
}
```

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

响应：
```json
{
  "message": "Command sent successfully",
  "command": "say Hello from API",
  "server_id": "survival-01"
}
```

## WebSocket 消息 (WebSocket Messages)

### 客户端到服务器

Ping:
```json
{ "type": "ping" }
```

Pong 响应:
```json
{ "type": "pong" }
```

### 服务器到客户端

广播事件：
```json
{
  "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 密钥本身。