HTTP API

HTTP 接口参考

所有接口基于裸 HTTP（默认端口 8081），无 TLS。鉴权见 Security-Model。

鉴权：数据接口用 verify_token（URL 参数 ?token=）；控制接口用 control_token（请求头 X-Control-Token）。下文示例中 YOUR_VERIFY_TOKEN / YOUR_CONTROL_TOKEN 为占位符，请替换为实际 token；<服务器IP> 替换为实际地址。

响应统一格式：{"success": true/false, "message": "...", "data": {...}}。success:false 时 data 为 null，错误原因在 message。

只读数据接口

`GET /get_sl_data?token=<verify_token>`

返回服务器实时状态快照：人数、回合、核弹、玩家列表（含坐标）、DNT_OF 系列插件状态。核弹字段仅在回合进行中实时读取，其余字段来自定时快照（每 push_interval_seconds 刷新）。

curl -s "http://<服务器IP>:8081/get_sl_data?token=YOUR_VERIFY_TOKEN"

{"success":true,"server_name":"我的服务器","online":true,"players_count":0,"max_players":32,
 "round_started":false,"round_duration":0,"current_phase":"等待开始",
 "nuke_status":"未激活","nuke_countdown":0,"voice_port":8082,
 "d_count":0,"foundation_count":0,"scp_count":0,"spectator_count":0,"ping":0,
 "players":[],
 "dntof_plugins":{"sl_player":{"present":true,"source_mode":"local","remote_url":null,"now_playing":null},
                  "omega_warhead":{"present":true,"phase":"none","coin_holders":[],"controller_holder":null,"countdown":null}}}

字段说明：

字段	说明
`server_name`	服务器名称（含颜色/大小标签原始文本）
`players_count` / `max_players`	当前人数 / 上限
`round_started`	回合是否已开始
`round_duration`	回合已进行秒数
`current_phase`	当前阶段（等待开始 / 进行中等）
`nuke_status`	`未激活` / `倒计时:XX秒` / `已爆炸`
`nuke_countdown`	核弹倒计时秒数（实时值，不受刷新间隔影响）
`voice_port`	语音转发端口
`d_count` / `foundation_count` / `scp_count` / `spectator_count`	各阵营人数（D 级含混沌分裂者）
`ping`	所有真实玩家平均延迟（ms）
`players[].steam_id`	玩家 SteamID（`p.UserId`）
`players[].x/y/z`	玩家世界坐标（地图追踪用，只取平面 x/z + 高度 y）
`players`	仅包含已分配职业的真实玩家，排除 NPC/Dummy
`dntof_plugins`	DNT_OF 系列插件（SLPlayer / OmegaWarhead）运行时信息；对应插件未加载时子字段为 `null`

数据刷新机制：

插件启用时立即采集一次数据（无需等待第一个刷新周期）
之后每隔 push_interval_seconds 秒刷新一次缓存（默认 8 秒）
回合开始 / 结束 / 等待玩家阶段切换时立即触发一次额外刷新
核弹倒计时在每次 HTTP 请求时实时读取，不受刷新间隔影响，始终与游戏内同步
地图布局在每回合开始时采集（LCZ/HCZ 每回合随机）；/control/map seed 返回的 seed 与布局一一对应

玩家过滤规则（不计入人数、不出现在玩家列表）：

通过 dummy 命令或插件创建的 NPC/Dummy 玩家（p.IsNpc == true）与服务器主机（p.IsHost == true）
RoleTypeId.None 的玩家（回合开始瞬间尚未完成职业分配，下一个刷新周期会正常出现）

控制接口

全部控制端点：仅 POST，请求体 JSON，鉴权 X-Control-Token 头。WS 长连接模式下 HTTP 调用返回 404（transport_mismatch 协商信号），同一 path+body 走 WS call 信封语义完全一致。

`POST /control/command`

执行服务器控制台命令。output 为命令直接返回值（点命令含完整回显），console 为 Harmony 捕获的控制台管线输出。

curl -s -X POST "http://<服务器IP>:8081/control/command" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"command":"help"}'

{"success":true,"message":"已执行",
 "data":{"output":"Command list:\r\nquery - Manages query client connections.\r\nbuffer - Returns TcpConsole buffers sizes.\r\n...","console":"..."}}

点命令（.m、.music 等）以主机玩家身份直连执行：

curl -s -X POST "http://<服务器IP>:8081/control/command" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"command":".m"}'

{"success":true,"message":"已执行",
 "data":{"output":"\n=== SLPlayer GUI 版 客户端指令 ===\n.music play [序号]     - 播放指定歌曲\n.music next            - 切换到下一首\n..."}}

`POST /control/player/kick`

踢出玩家。target 支持 PlayerId / UserId / IP / 昵称模糊匹配。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/kick" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","reason":"违规"}'

{"success":true,"message":"操作完成","data":null}

{"success":false,"message":"找不到玩家: PlayerName","data":null}

`POST /control/player/ban`

封禁玩家，duration 单位分钟（0=永久）。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/ban" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"76561198000000000","reason":"作弊","duration":1440}'

{"success":true,"message":"已封禁","data":null}

`POST /control/player/role`

设置玩家角色（RoleTypeId 枚举名）。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/role" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","role":"ClassD"}'

{"success":true,"message":"操作完成","data":null}

`POST /control/player/teleport`

传送玩家到指定坐标。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/teleport" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","x":90,"y":101,"z":42}'

{"success":true,"message":"操作完成","data":null}

`POST /control/player/mute`

语音禁言/解除。mute_scope: voice（全局，默认）| intercom（仅对讲机）；persistent: true=持久（写入本地静音存储，重连仍生效）/ false=临时（默认）。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/mute" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","mute":true,"mute_scope":"voice","persistent":true}'

{"success":true,"message":"操作完成","data":null}

`POST /control/player/msg`

向玩家发送私聊提示（hint），duration_seconds 显示时长。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/msg" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","message":"请文明发言","duration_seconds":5}'

{"success":true,"message":"操作完成","data":null}

`POST /control/player/effect`

施加状态效果（效果名兼容旧命名别名），effect_duration 秒。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/player/effect" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","effect":"Bleeding","effect_duration":30}'

{"success":true,"message":"操作完成","data":null}

`POST /control/player/state`

查询/设置玩家状态（godmode/bypass/health/intercom 均为可选，不填则查询）。

curl -s -X POST "http://<服务器IP>:8081/control/player/state" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"PlayerName"}'

{"success":true,"message":"ok",
 "data":{"godmode":false,"bypass":false,"health":100,"intercom":false}}

{"success":false,"message":"找不到玩家: NoSuchPlayer999","data":null}

`POST /control/round`

回合控制：restart（立即重启）/ end（立即结束）/ start（立即开始）。⚠️ 有副作用，会打断当前对局。

curl -s -X POST "http://<服务器IP>:8081/control/round" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

{"success":true,"message":"回合操作完成","data":null}

`POST /control/cassie`

CASSIE 播报。translation 非空时：语音播报 message 原文（含音效代码），游戏内字幕显示 translation（纯文本）——"英文播报 + 中文字幕"。⚠️ 会向全服播报。

curl -s -X POST "http://<服务器IP>:8081/control/cassie" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"Pitch_0_2 Attention all personnel","translation":"请全体人员注意"}'

{"success":true,"message":"CASSIE 播报已触发","data":null}

`POST /control/warhead`

核弹控制：start（启动）/ stop（停止）/ detonate（立即引爆）。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/warhead" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"start"}'

{"success":true,"message":"核弹操作完成","data":null}

`POST /control/wave`

重生波次控制（v2.5.4）。faction: mtf | chaos；action: instant（立即生成）/ set（设置剩余秒数与重生代币）/ status（查询）。instant/set ⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/wave" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"faction":"mtf","action":"status"}'

{"success":true,"message":"ok","data":{"faction":"mtf","time_left":330.0,"tokens":1}}

curl -s -X POST "http://<服务器IP>:8081/control/wave" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"faction":"mtf","action":"instant"}'

{"success":true,"message":"ok","data":{"faction":"mtf","time_left":0.0}}

`POST /control/map`

地图信息与控制。action:

seed：当前地图种子
layout：房间布局（含坐标/朝向/边界）
doors：门控制（door_type + scope: type/all/all_not_list + lock_door/open_door）⚠️
elevators：电梯控制（elevator_type + command: up/down/send + level）⚠️
lights：灯光控制（room_type + lights_off + duration）⚠️

curl -s -X POST "http://<服务器IP>:8081/control/map" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"layout"}'

{"success":true,"message":"ok",
 "data":{"seed":1302484298,"ready":true,"count":103,
         "bounds":{"min_x":-240.0,"max_x":255.0,"min_z":-240.0,"max_z":255.0},
         "rooms":[{"name":"LczToilets","zone":"LightContainment","shape":"Straight","ax":90.0,"az":30.0,"aw":15.0,"ad":15.0,"grid_scale":15.0,"x":90.0,"z":42.4,"y":101.6,"w":15.2,"d":10.0}, "..."]}}

curl -s -X POST "http://<服务器IP>:8081/control/map" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"elevators","elevator_type":"Nuke01","command":"send","level":0}'

{"success":true,"message":"已向 1/1 部电梯发送 直达 0 层 指令",
 "data":{"scope":"type","elevator_type":"Nuke01","command":"send","level":0,"moved":1,"invalid":0,"total":1}}

`POST /control/map/export`

导出地图原始数据（atlas RGBA base64、glyph_pairs、zone_candidates 等），供外部重建地图。

curl -s -X POST "http://<服务器IP>:8081/control/map/export" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{}'

{"success":true,"message":"ok",
 "data":{"grid_scale":15.0,"seed":1302484298,
         "atlases":[{"name":"HC_1_clark","width":32,"height":32,"rgba":"ZGRk/2RkZP9kZGT/..."}],
         "glyph_pairs":[],"zone_candidates":[]}}

`POST /control/reports`（v2.5.4 推出 · 代号 GIS,GNSS,RS!）

举报记录管理（需 report_enabled: true，玩家在 SSS 面板提交）。

curl -s -X POST "http://<服务器IP>:8081/control/reports" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"list"}'

{"success":true,"message":"ok",
 "data":[{"id":"85149ac2b9374245a845c557627cc3f5",
          "reporter_steam64":"76561198000000000","reporter_name":"举报人昵称",
          "reporter_ip":"1.2.3.4",
          "target_steam64":"76561198000000001","target_name":"被举报人昵称",
          "reason":"违规行为描述","reported_at":"2026-08-26T16:17:05.4402075Z",
          "status":"pending"}]}

curl -s -X POST "http://<服务器IP>:8081/control/reports" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"handle","id":"85149ac2b9374245a845c557627cc3f5"}'

{"success":true,"message":"已标记为已处理","data":null}

{"success":false,"message":"未找到该记录或该记录已处理","data":null}

`POST /control/slplayer`

SLPlayer 音乐控制（需服务器装有 SLPlayer）。action: status/list/play/next/stop/volume/shuffle/reload/fetch。播放类操作 ⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/slplayer" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"status"}'

{"success":true,"message":"ok",
 "data":{"playing":false,"index":-1,"song":null,"elapsed_seconds":0,"duration_seconds":0,
         "volume":50,"shuffle":false,"source":"local","remote_url":null,
         "playlist_count":1,"playlist":[{"index":0,"display":"歌名 - 歌手","duration":230}]}}

`POST /control/plugins`

插件管理。空 body 或 action 省略 = 列表；stage（暂存启停）/ clear（清空暂存）/ apply（写入生效，LabAPI 插件需重启）/ reload（热重载配置）。

curl -s -X POST "http://<服务器IP>:8081/control/plugins" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{}'

{"success":true,"message":"ok",
 "data":{"count":19,
         "plugins":[{"name":"SLDataAPI","author":"DNT_OF","version":"2.5.4.0",
                     "prefix":"","priority":"255","enabled":true,"self":true,"staged":null,"source":"labapi"},
                    {"name":"SomePlugin","author":"Author","version":"1.0.0.0",
                     "prefix":"","priority":"Medium","enabled":true,"self":false,"staged":null,"source":"labapi"}]}}

curl -s -X POST "http://<服务器IP>:8081/control/plugins" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"stage","name":"SomePlugin","enabled":false}'

{"success":true,"message":"已暂存","data":null}

`POST /control/ban_list`

游戏封禁列表（仅 IP/SteamID 封禁，不含操作日志）。

curl -s -X POST "http://<服务器IP>:8081/control/ban_list" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{}'

{"success":true,"message":"ok","data":{"count":0,"bans":[]}}

`POST /control/ban/add`

添加封禁（userId 为 Steam64 或 IP）。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/ban/add" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"76561198000000000","reason":"作弊","duration":1440}'

{"success":true,"message":"已封禁","data":null}

`POST /control/ban/revoke`

解除封禁。⚠️ 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/ban/revoke" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"76561198000000000"}'

{"success":true,"message":"已解除封禁","data":null}

`POST /control/logs`

读取服务器日志尾部。lines（默认 200）、filter、path、action=list（列出全部可用日志文件）。

curl -s -X POST "http://<服务器IP>:8081/control/logs" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"lines":5}'

{"success":true,"message":"ok",
 "data":{"file":"LocalAdmin Log 2026-08-28 21.53.00.txt",
         "path":"...\\AppData\\Roaming\\SCP Secret Laboratory\\LocalAdminLogs\\7777\\LocalAdmin Log 2026-08-28 21.53.00.txt",
         "total":5,
         "lines":["[2026-08-28 21:53:19.806 +08:00] [STDOUT] ...", "..."]}}

`POST /control/files/list | read | write`

文件管理（受 file_root 白名单限制，防路径穿越与 NTFS ADS）。⚠️ write 有副作用。

curl -s -X POST "http://<服务器IP>:8081/control/files/list" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"path":"."}'

{"success":true,"message":"ok",
 "data":{"path":".","entries":[{"name":"config.yml","size":2048,"is_dir":false,"modified":"2026-08-28T12:00:00Z"}]}}

curl -s -X POST "http://<服务器IP>:8081/control/files/write" \
  -H "X-Control-Token: YOUR_CONTROL_TOKEN" -H "Content-Type: application/json" \
  -d '{"path":"notes.txt","content":"hello"}'

{"success":true,"message":"ok","data":null}

{"success":false,"message":"文件端点未启用（服务器未配置 FileRoot）","data":null}

错误响应速查

HTTP 状态码	含义
`403`	token 错误/缺失，或该来源已被暴力破解锁定
`404`	控制接口未启用（`control_enabled: false`）、ws 模式互斥拒绝，或端点不存在
`405`	控制接口仅支持 POST
`413`	请求体超过 64KB
`400/500`	业务错误（响应 `message` 内附详情）

Uh oh!

HTTP API

HTTP 接口参考

只读数据接口

GET /get_sl_data?token=<verify_token>

控制接口

POST /control/command

POST /control/player/kick

POST /control/player/ban

POST /control/player/role

POST /control/player/teleport

POST /control/player/mute

POST /control/player/msg

POST /control/player/effect

POST /control/player/state

POST /control/round

POST /control/cassie

POST /control/warhead

POST /control/wave

POST /control/map

POST /control/map/export

POST /control/reports（v2.5.4 推出 · 代号 GIS,GNSS,RS!）

POST /control/slplayer

POST /control/plugins

POST /control/ban_list

POST /control/ban/add

POST /control/ban/revoke

POST /control/logs

POST /control/files/list | read | write

错误响应速查

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`GET /get_sl_data?token=<verify_token>`

`POST /control/command`

`POST /control/player/kick`

`POST /control/player/ban`

`POST /control/player/role`

`POST /control/player/teleport`

`POST /control/player/mute`

`POST /control/player/msg`

`POST /control/player/effect`

`POST /control/player/state`

`POST /control/round`

`POST /control/cassie`

`POST /control/warhead`

`POST /control/wave`

`POST /control/map`

`POST /control/map/export`

`POST /control/reports`（v2.5.4 推出 · 代号 GIS,GNSS,RS!）

`POST /control/slplayer`

`POST /control/plugins`

`POST /control/ban_list`

`POST /control/ban/add`

`POST /control/ban/revoke`

`POST /control/logs`

`POST /control/files/list | read | write`