Architecture

架构概览

.NET Framework 4.8 · LabAPI 原生插件 · 单程序集 SLDataAPI.dll。

目录与命名空间

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

请求路径（简化）

GET /get_sl_data
  → HttpServer → ControlAuth(verify_token, 低权限表) → DataCollector 快照 JSON

POST /control/*
  → HttpServer → ApiKeyService（2.6）或 ControlAuth（2.5）
  → ControlController.Handle
  → MainThreadExecutor（游戏 API）→ JSON

WS /control
  → WsControlService 握手鉴权 → Session 读循环
  → call → 线程池 → 同上 Handle
  → subscribe_events → 事件广播

语音 :8082
  → VoiceService → 解码队列 → WS 客户端 / VoiceRecorder 写盘线程

线程模型

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

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

关键设计

快照（M-01）

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

录音开轨（S-01）

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

鉴权分表（M-02）

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

控制传输互斥

control_transport 在 HTTP 与 WS 入口各检查一次，返回 transport_mismatch 供客户端切换实现。

扩展阅读

加端点、SSS、测试：Development-Guide。