WS Control Protocol

WS 控制通道协议

连接

ws://<host>:8081/control?key=<control_token>
ws://<host>:8081/ws/control?key=<control_token>    （旧别名）

也可用 X-Control-Token 头传递 token。传输格式为 UTF-8 JSON 文本帧。

消息类型

hello（S→C）

建连后立即推送：

{"type":"hello","server":"SLDataAPI","version":"...","endpoints":"/control/*"}

ping / pong（C↔S）

{"type":"ping"}
{"type":"pong"}

建议每 25 秒发送一次 ping 保活。90 秒无入站消息判定空闲超时断连。

call（C→S）+ result（S→C）

// C→S
{"type":"call","reqId":"c1","path":"/control/command","body":{"command":"help"}}

// S→C（可乱序返回，按 reqId 关联）
{"type":"result","reqId":"c1","ok":true,"status":200,"data":{"success":true,"data":{"output":"...", "console":"..."}}}

path 必须是 /control/* 端点，body 为该端点的 POST body。语义与 HTTP POST 完全一致。 单连接并发上限 4 个（超出回 429），全局连接上限 8 个，单消息上限 256KB。

subscribe_events / unsubscribe_events（C→S）

{"type":"subscribe_events"}

订阅后开始接收事件推送。取消订阅发 unsubscribe_events。

event（S→C）

{"type":"event","event":"round_started","utc":"2026-08-20T14:00:00.000Z","data":{}}

当前支持的事件类型：

• round_started / round_ended — 回合生命周期（开始时间 / 胜利阵营）
• player_joined / player_left — 玩家进出（昵称/UserId）
• player_died — 玩家死亡（昵称/攻击者/死亡前角色）
• door_opened — 门交互（含权限门；can_open 指示该玩家是否有权打开）
• elevator_used — 使用电梯（电梯组，如 Nuke01）

事件推送与 call 调用同连接复用、互不阻塞；尽力而为投递，断线期间事件不补发，重连后需重新 subscribe_events。

限制

参数	值
全局连接数	8
单连接并发 call	4（超出回 429）
单消息上限	256KB
空闲超时	90s（需定期 ping）
分片组装超时	30s