Skip to content

Development Guide

Jump to bottom
DNTOF edited this page Sep 24, 2026 · 8 revisions

开发者指南

面向在 SLDataAPI 仓库贡献功能的开发者。

当前正式版本：2.6.0 PEAK（main / tag v2.6.0_PEAK）。

DevKit：Release 附件 SLDataAPI-DevKit-v2.6.0_PEAK.zip（sl-dataapi-dev skill + 冒烟脚本）。

项目结构

目录 命名空间 职责
Plugin.cs SLDataAPI Enable/Disable、事件订阅、服务启动顺序
Config.cs SLDataAPI config.yml 属性（snake_case）
Data/ SLDataAPI.Data HTTP/WS JSON DTO
Control/ SLDataAPI.Control 路由 ControlController、WS WsControlService、ControlAuth
Auth/ SLDataAPI.Auth ApiKeyService、EndpointAcl、RemoteCommandGuard
Commands/ SLDataAPI.Commands sldataapi / apikey（本地 only）
Services/ SLDataAPI.Services HttpServer、DataCollector、MainThreadExecutor、ReportService、ControlLogService、WebDavUploader、UpdateChecker…
Voice/ SLDataAPI.Voice SPY 转发 + 录音
Map/ SLDataAPI.Map seed/layout/export
Integrations/ SLDataAPI.Integrations EXILED 反射、第三方插件探测
Capture/ SLDataAPI.Capture 控制台输出 Harmony 补丁
examples/AdaptedPluginSample/ — 适配插件注册示例

架构：Architecture。编译发布：Building。

强制约定

1. 事件链保护

LabAPI 事件 handler 必须整体 try/catch，异常 Log.Error 后吞掉，不得抛回游戏。参考 Plugin.OnRoundStarted。

2. 主线程派发

var result = MainThreadExecutor.RunOnMainThread(() =>
{
    // Unity / Mirror API
    return (200, Json(true, "ok", data));
}, out Exception err);
if (err != null)
    return (400, Json(false, err.Message));

纯文件、鉴权校验、序列化可不派发。超时后设置取消标志，迟到的 action 不得再执行。

3. 错误对外表述

ControlController.Handle 顶层 catch → 500 "内部错误"。不向客户端返回堆栈、绝对路径。

4. 配置 snake_case

C# ReportMaxRecords → YAML report_max_records。单字段错误可能导致整文件回退默认。

5. 版本注释

功能块用注释标版本，例如：

// ===== 举报（v2.5.4 推出）=====

Plugin.Version 为单一真相（2.6.0 · PEAK）；README / Wiki / Release tag 对齐。

添加控制端点

  1. Data/ControlModels.cs：新增请求类（JSON 属性 snake_case）。
  2. ControlController.Handle：switch 注册 path（RA 对齐路径）。
  3. 实现 XxxAction(string body)：Parse<T> → 校验 → MainThreadExecutor → (status, Json(...))。
  4. 鉴权：ApiKeyService.TryAuthenticate（Bearer / X-SLDataAPI-Key）+ EndpointAcl。
  5. 审计：侵入性写操作经 ControlLogService（若启用）。
  6. 文档：更新 HTTP-API；历史对照仍见 Old-HTTP-API。
  7. WS：无需 duplicate——call.path 与 HTTP 相同即自动兼容。

参考：ReportsAction、MapFacilityAction、broadcast / staffchat。

501 占位

未实现：Stub501("name")。当前仍为 501：/control/player/inventory、/control/dummies。
已实现：/control/broadcast、/control/staffchat。

远程命令护栏

RemoteCommandGuard 拦截经控制通道执行的 sldataapi/slda。新增本地管理命令应注册在 Commands/ 并默认拒绝远程。

SSS 游戏内 UI

模式见 Services/ReportService.cs（UserSettings.ServerSpecific）：

控件 用途
SSGroupHeader 分组标题
SSDropdownSetting 下拉
SSPlaintextSetting 文本
SSButton + holdTimeSeconds 长按提交

流程：DefinedSettings → SendToAll()；ServerOnSettingValueReceived 在主线程按 SettingId 处理。
注意：DefinedSettings 全局单例，与其他插件可能冲突。

本地测试

先本地执行 sldataapi apikey create <id> admin，再：

curl -s -X POST "http://127.0.0.1:8081/control/broadcast" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"message":"ping","duration_seconds":5}'

curl -s "http://127.0.0.1:8081/get_sl_data" \
  -H "Authorization: Bearer <verify_token>"

DevKit 冒烟：

.\scripts\Test-ControlEndpoints.ps1 -BaseUrl http://127.0.0.1:8081 `
  -VerifyToken "<verify_token>" -ApiKey "<admin_key>"

仅对自有服务器；勿把真实密钥写进脚本。

dotnet test tests/SLDataAPI.Auth.Tests
dotnet test tests/SLDataAPI.Update.Tests
dotnet test tests/SLDataAPI.WebDav.Tests

WS：握手带 Bearer。见 WS-Control-Protocol。

文档分工

内容 页面
现行 HTTP / 控制 HTTP-API
安全 / 配置 / 构建 Security-Model · Configuration · Building
历史 2.5 对照 Old-HTTP-API

发布

见 Building。正式 Release 请用带 key.snk 的本机构建并核对公钥令牌后再上传附件。DevKit zip 与 DLL 一并挂到对应 tag。

Clone this wiki locally