Skip to content

v2.6.1 RIDGE

Pre-release
Pre-release

Choose a tag to compare

View all tags
@DNTOF DNTOF released this 04 Oct 01:25
v2.6.1_RIDGE
cb0e6d5

v2.6.1 RIDGE

预发布：SLDataAPI 2.6.1，开发代号 RIDGE（相对 2.6.0 PEAK）。源码已在 main。

重要提示（请先读）

这是一个预发布（Pre-release）版本：在 2.6.0 PEAK 之上加入两项内测功能，默认全部关闭。不打开开关时，行为与 2.6.0 PEAK 一致（文件沙箱加固除外，见下文）。

  • 内测功能只在维护者本机做过加载冒烟和无鉴权探测，带鉴权的端到端流程还没有完整测试。请只在测试服打开开关。
  • 自动更新只认稳定版：本版本标记为 Pre-release，2.6.0 PEAK 的更新检查不会推送它，需要手动下载。
  • 发现问题请积极开 Issue（附版本号 v2.6.1 RIDGE、LabAPI/游戏版本、相关日志与复现步骤）：https://github.com/DNTOF/SLDataAPI/issues
  • 安全/权限类问题请按模板脱敏，不要贴明文 API Key / verify_token / WebDAV 密码。

新增内测功能（默认关闭）

1. 适配插件写操作：beta_adapted_plugin_actions: true

  • 第三方插件在 TryRegister 之后，可以调用 PluginEndpointRegistry.TryRegisterActions(id, actions, out error) 注册写 / 动作路由（每个插件最多 16 个，请求体 ≤64KB）。TryRegister 签名不变，只读插件无需改动。
  • 调用：POST /control/adapted/<plugin_id>/<action>（HTTP 与 WS call 同一路由）。处理器在主线程执行，超时 3s；插件抛 AdaptedActionException 返回 4xx。
  • 一律按写操作计，每次调用都写入 control_log。
  • 开关打开时，/plugins/adapted 与 get_sl_data.adapted_plugins[*] 额外列出 actions。内置探测包装（SLPlayer / OmegaWarhead）不能追加动作。
  • 示例插件 AdaptedPluginSample 1.1.0 新增 echo / bump 动作；在旧版 SLDataAPI 上会自动退回只读。

2. FileRoot 的 WS 适配：beta_file_root_ws: true

  • 原有 files/list|read|write 本来就能走 WS call，但受单条消息上限（WS 256KB / HTTP 64KB）限制，大文件读写不可行。
  • 新增端点：
    • /control/files/stat：文件 / 目录元信息（读）
    • /control/files/read_chunk：按 offset / length 分块读，base64，单块 ≤160KB；offset 为 0 时附整文件 sha256（读）
    • /control/files/write_chunk：分块上传会话。offset 须连续，总计 ≤512KB，120s 过期，每把 Key 最多 2 个会话；final 时可校验 sha256 并原子替换写入；action: "abort" 取消自己的会话（写）
  • 仍需配置 file_root，沿用原有沙箱与写入防线；write_chunk 的块数据在审计里只记录长度。

WS hello 新增 beta 数组

控制 WS 握手后的 hello 消息新增 beta 字段，列出已开启的内测能力：adapted_actions / file_chunks，平台可以据此决定是否展示相关 UI。

权限（ACL）

  • 新键 /control/adapted/：默认拒绝，admin、duty 和 all_control_true 都不会自动授予。
  • 分块文件端点归已有的 /control/files/ 管，同样默认拒绝（含 admin）。
  • 需要在 apikey.config 对应 Key 的 endpoints_override 中显式放开，例如：
    • 全部适配插件动作："/control/adapted/": true
    • 仅某个插件："/control/adapted/dntof.sample_adapted/": true
    • 文件读写："/control/files/": true（或 { "read": true, "write": false } 只读）

安全加固（不受开关影响）

  • FileRoot 沙箱现在拒绝路径中经过**符号链接 / 目录联接（junction）**的情况，防止借链接逃出 file_root。对全部文件端点（含原有 files/list|read|write）生效。如果你的 file_root 里有意放了链接，升级后相关路径会被拒绝。

其他变化

  • 修复：适配插件动作注册日志不再附带依赖加载顺序的「未开启」提示（原提示会误导）
  • 许可证：全部源码加 SPDX 头（GPL-3.0-only，Copyright (C) 2026 DNT_OF），新增双语 NOTICE，README 增加许可证说明
  • README 按 2.6.0 PEAK 重写，恢复 Harmony / Newtonsoft 依赖下载链接

安装 / 更新

  1. 备份现有 config.yml / apikey.config
  2. 将 SLDataAPI.dll 放入 LabAPI/plugins/global/（示例插件 AdaptedPluginSample.dll 可选）
  3. 确认依赖：0Harmony.dll、Newtonsoft.Json.dll
  4. 重启服务器（插件只在进程启动时加载）
  5. 首次加载后，config.yml 会自动补上 beta_adapted_plugin_actions: false 与 beta_file_root_ws: false。需要内测时改为 true 再重启，并按上文给测试 Key 显式授权。

DevKit

附件 SLDataAPI-DevKit-v2.6.1_RIDGE.zip 含开发 skill（已补充内测端点清单）与：

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

仅对自有服务器冒烟；勿把真实密钥写进脚本。冒烟脚本尚未覆盖内测端点。

文档

已知问题

  • 内测功能带鉴权的端到端流程尚未由维护者完整测试（已测：构建、单元测试、本机加载冒烟、无鉴权探测）
  • 语音端口（默认 8082）被其他程序占用时语音服务启动失败，暂无自动回退；请在 voice_port 换一个空闲端口
  • /control/plugins 在 admin 默认 ACL 下仍为拒绝（catalog 默认 false），需要 endpoints_override 显式放开
  • /control/player/inventory、/control/dummies 仍为 501

遇到异常请开 Issue，反馈越具体修得越快。

Assets 5
Loading