WS Control Protocol

WS 控制通道协议

UTF-8 JSON 文本帧（非二进制）。call 与 HTTP POST 同 path、同 body；另支持事件订阅。

前提： control_enabled: true 且 control_transport: ws。

对齐 main 上的当前稳定版。

握手鉴权

版本	方式
现行	Authorization: Bearer <api_key> 或 X-SLDataAPI-Key（不要把 Key 放进 URL）
旧版（control_token，已废弃）	?key=<control_token> 或 X-Control-Token（见 Old-HTTP-API）

路径：ws://<host>:8081/control（别名 /ws/control），与数据口共用 http_port。tls_mode 为 optional 时也可用 wss://，为 required 时只能用 wss://（明文升级返回 HTTP 426）；自签证书请固定指纹，见 Security-Model「传输（TLS）」。改 control_transport 后须重启服务器。

control_transport: http 时握手 404 + {"code":"transport_mismatch","use":"http"}。

---

连接示例

const ws = new WebSocket("ws://127.0.0.1:8081/control", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
// 浏览器无法自定义握手头时，请用 Node / wscat 等客户端

---

消息类型

hello（S→C）

{"type":"hello","server":"SLDataAPI","version":"<插件版本>","endpoints":"/control/*","beta":[],
 "tls":true,"cert_fingerprint":"AB:CD:…:EF"}

version 为插件版本（Plugin.Version）。beta列出已开启的内测能力：adapted_actions（beta_adapted_plugin_actions）、file_chunks（beta_file_root_ws）；都没开时为 []。旧版本没有该字段，客户端应按「缺失 = 无内测能力」处理。详见 Beta-Features。

tls表示本连接是否走 TLS；cert_fingerprint 为证书 SHA-256 指纹（tls_mode: off 或证书不可用时为 null）。指纹由服务端自报，首次固定时请对照启动横幅或 sldataapi cert show。

ping / pong

建议每 25s 发 {"type":"ping"}；90s 无入站消息断连。

call / result

{"type":"call","reqId":"c1","path":"/control/console/command","body":{"command":"help"}}

现行 path 见 HTTP-API（勿再使用旧版扁平路径如 /control/command）。内测端点（/control/adapted/...、files/stat|read_chunk|write_chunk）同样走 call，见 Beta-Features；分块读写时单块请控制在 160KB 原始字节以内，保证 base64 后不超过 256KB 单消息上限。

成功：

{"type":"result","reqId":"c1","ok":true,"status":200,
 "data":{"success":true,"message":"已执行","data":{...}}}

业务失败：ok:false，status 为 HTTP 语义（400/403/404…）。并发超限：status:429。

reqId 连接内唯一；结果可乱序。

协议错误：

{"type":"error","message":"未知消息类型: xxx（支持 ping / subscribe_events / call）"}

subscribe_events / unsubscribe_events

{"type":"subscribe_events"}

确认：events_subscribed / events_unsubscribed。
需 Key 含 ws:subscribe_events 权限。

event（S→C）

{"type":"event","event":"round_started","utc":"...","data":{...}}

event	data 要点
round_started / round_ended	started_at / leading_team 等
player_joined / player_left	nickname, userid
player_died	old_role, 可选攻击者
elevator_used	elevator_group
door_opened	door, can_open

扩展的低频事件，数据均不含 IP。玩家块 = nickname / userid / player_id，带前缀时如 issuer_nickname：

event	data 要点
player_banned	玩家块、issuer_*、reason、duration_seconds（离线封禁时仅回传账号 ID）
player_kicked	玩家块、issuer_*、reason
player_escaped	玩家块、old_role、new_role、scenario
player_role_changed	玩家块、old_role、new_role、reason（RemoteAdmin / Respawn / Died / RoundStart …）
player_reported	kind（player / cheater）、source（game = 游戏内举报，plugin = 插件举报面板，带 id）、reporter_*、target_*、reason
wave_respawned	faction（游戏原名：FoundationStaff / FoundationEnemy …）、team（短名：mtf / chaos，其他阵营为 faction 小写）、count、players
decontamination_started	{}
generator_activated	room、engaged、total
scp_terminated	玩家块、role、announcement（CASSIE 播报词）
warhead_started	automatic、触发者玩家块（控制面 / 控制台触发时为 Dedicated Server）
warhead_stopped / warhead_detonated	触发者玩家块

不推送移动、开火、语音等高频事件。

断开期间事件不补发；重连后需重新订阅。

---

限制

项	值
全局连接	8
单连接并发 call	4
单消息	256KB
空闲	90s
分片组装	30s

握手 / 关闭码

码	含义
HTTP 401	鉴权失败 / 锁定
HTTP 403	Key 无 WS 权限等
HTTP 404	未启用 / HTTP 模式互斥
HTTP 426	tls_mode: required 下的明文升级
HTTP 503	连接满
WS 1008	分片超时
WS 1009	消息过大