Architecture

架构概览

.NET Framework 4.8 · LabAPI 原生插件 · 单程序集 SLDataAPI.dll。
对齐 main 上的当前稳定版。主要组件包括 TLS（Services/TlsCertificateService.cs、Services/TlsPolicy.cs、Commands/Cert*）、Services/FileSandbox.cs、Services/FileUploadSessions.cs 与 Beta-Features 的内测端点。

目录与命名空间

SLDataAPI/
├── Plugin.cs              # 生命周期、LabAPI 事件、服务编排
├── Config.cs              # config.yml 映射
├── Log.cs
├── Data/                  # Models.cs · ControlModels.cs（DTO）
├── Control/               # ControlController · WsControlService · ControlAuth
├── Auth/                  # ApiKeyService · EndpointAcl · RemoteCommandGuard
├── Commands/              # sldataapi apikey * / cert *（仅本地控制台）
├── Services/              # HttpServer · DataCollector · MainThreadExecutor · TlsCertificateService · …
├── Voice/                 # VoiceService · VoiceRecorder
├── Map/                   # 布局采集 / 导出
├── Integrations/          # EXILED 反射桥 · 第三方插件探测
└── Capture/               # Harmony：控制台输出捕获

请求路径（简化）

:8081 / :8082 新连接
  → 首字节嗅探（tls_mode: optional）：0x16 → TLS（自签证书）；其他 → 明文
  → required 下明文直接 426

GET /get_sl_data  ·  GET /plugins/adapted
  → HttpServer → verify_token（头优先）→ DataCollector 快照 / 适配插件发现

POST /control/*
  → HttpServer → ApiKeyService + EndpointAcl
  → ControlController.Handle
  → MainThreadExecutor（游戏 API）→ {success,message,data}

WS /control
  → WsControlService 握手（API Key）→ Session
  → call → 线程池 → 同上 Handle
  → subscribe_events → 事件广播

语音 :8082
  → VoiceService（API Key）→ 解码队列 → WS 客户端 / VoiceRecorder

旧版曾用 control_token + 扁平 /control/* 路径，见 Old-HTTP-API。

线程模型

线程	职责
Unity 主线程	游戏状态、MEC、语音解码入队、录音入队
HTTP 线程池	连接、控制逻辑、JSON 序列化
WS 读线程	每连接阻塞读帧
WS 工作池	执行 ControlController.Handle
录音写盘	单线程追加 WAV

约束： 除纯 IO/序列化外，触碰 Unity/Mirror 必须 MainThreadExecutor.RunOnMainThread（默认 5s 超时；超时后取消标志，防「报超时仍执行」的双重执行）。

关键设计

快照

DataCollector 在主线程构建完整 ServerData，原子替换缓存；HTTP 只读 volatile 引用。

录音开轨

开轨控制消息与 PCM 同队列串行，避免字典竞态导致静音轨。

鉴权分表

verify_token 失败计数与 API Key 失败计数分离，避免低权限接口刷锁高权限通道。

控制传输互斥

control_transport 为 http 或 ws 硬互斥；错模式返回 transport_mismatch。

扩展阅读

加端点、SSS、测试：Development-Guide。安全边界：Security-Model。