v0.2.5 e0ba4ea833

OpenDance Studio Windows 客户端 v0.2.5 Stable

zijunchiang released this 2026-09-18 02:47:05 +08:00 | 3 commits to main since this release

OpenDance Studio -- Windows 客户端 v0.2.5

修复：config 被当成心跳周期性广播（每 2 秒一条）；
新增：契约「可选/兜底」语义的定向验收（v0.1.0 风格对端 / 缺 deviceId / 不发 hello）。

契约快照不变：rest-api 0.5.0 / websocket-keypoints 0.2.0 / data-models 0.7.0 /
skeleton-topology 0.2.0 / model-formats 0.5.0 / database 0.4.0
（与 opendance-web / opendance-android 逐字节一致）。

一、缺陷：config 被当成心跳

_maybe_push_config() 原来每 CONFIG_PUSH_INTERVAL_MS（2 秒）无条件广播一次 config。
契约 §3.3 的语义是「运行中调整时下发」，不是心跳：

一次 30 分钟推流 = 900 条没有任何信息量的消息；
更糟的是它让「收到 config」无法被当作「配置变了」的信号 —— 发送端想据此做点什么
就无从判断。

修复：抽出 config_payload() 作为唯一载荷与指纹来源；hello 应答顺序固定为
先 welcome、再 config（若靠周期 tick 补发，新对端第一条消息可能变成 config，
只认握手应答的实现会困惑）；之后仅当载荷真的变化才广播，并用同一常量做去抖
（连续拖动滑块不会每个中间值都发一条）；显式 broadcast_config()（UI 改设置）也同步
更新指纹，避免下一 tick 重发。

实测：17 秒内 config 9 条 → 1 条。

二、新增：契约「可选/兜底」语义的定向验收

上一轮 Android 侧的教训是「契约里可选的字段必须用不提供它的对端来测，
否则等于没测」（自家两端总是互相迎合）。本版把它用到接收端：

场景	契约	断言
v0.1.0 风格对端：只发二进制帧（每 500 ms 一帧）、从不发 `ping`/`stats`、`hello` 不带 `deviceId`，持续 17 秒（> 静默超时 15 秒）	§1.1 明确「仅实现 v0.1.0 的一端仍可正常互通（它不发 ping，但每帧已足够保活）」	连接保持打开；服务端没有把它静默超时踢掉
两条都不带 `deviceId` 的连接同时在线	§5「`deviceId` 缺失或为空 → 不做去重，按连接计数」	两条都保持打开；`device_replaced` 只应有那次真正重复 `deviceId` 的事件
完全不发 `hello`、只发 5 帧的对端	契约未规定（不该崩、不该断）	不断开、不崩、帧仍计入

WebSocket 验收断言：30 → 40 项，40 通过 / 0 失败。

三、顺带修掉验收脚本自身两处误判

把「跨连接的 frame_id 回退」当缺陷：frame_id 是每条连接各自从 0 递增，
新连接重新从 0 开始完全合规 —— 指标用错了。已改名并标注「仅参考」；
真正相关的判据是逐连接的 frames_dropped == 3。
把「静默超时次数」当固定值：套件里本来就有"完全不发数据"的对端，空闲的连接也会
被正常超时。已改为定向断言：由 hello 记录建立 client_id → device 映射
（探针新增 hellos[]），只检查 v0.1.0 风格对端没被误踢。

测试客户端也改为顺序无关（nextOfType(type)）—— 契约没规定消息顺序，
"第一条消息就是 welcome" 的假设在 welcome 后紧跟 config 时立刻暴露。

四、附件与解压（重要）

资产	说明
`opendance-windows-v0.2.5.zip`	单个完整包，不分卷：`OpenDance.exe` + `OpenDance.pck`（必须同目录）+ `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/`
`SHA256SUMS`	裸文件名，`sha256sum -c SHA256SUMS` 直接校验

解压需要 7-Zip / WinRAR / PeaZip：本包用 LZMA 压缩（26,634,144 B）以绕过本站
前置 IIS 的 maxAllowedContentLength = 30,000,000 字节上限
（同内容 deflate 包约 38 MB，会 HTTP 413）。Windows 10 资源管理器不支持
LZMA(method 14) 的 zip，双击会报错。

五、发布前自检（本版实测，四条全绿）

$ bash build/accept-release.sh <zip>
  ✓ PE 版本资源 0.2.5 ／ pck 启动 180 帧无错 ／ pck 无开发残留 ／ 运行时探针全过
$ bash build/accept-ws.sh <zip>
  == 结果：40 通过 / 0 失败 ==（客户端）+ 服务端侧全部事实
$ bash build/accept-frame-vectors.sh <zip>
  ✓ 解码 12/12、396 点 0 差异 ／ ✓ 编码器字节与参考实现完全一致（0 项差异）
$ bash build/verify.sh
  == 结果：785 通过 / 0 失败，6 跳过 ==

六、未在本环境验证（诚实声明）

本仓库在 Linux 上导出 Windows 产物，没有 Windows 机器与真机 30 分钟联调；
跨端集成验收（accept-integration.sh）需要已部署的 Web 服务端。

Downloads

opendance-windows-v0.2.5.zip
25 MiB
2026-09-18 02:48:40 +08:00
SHA256SUMS
95 B
2026-09-18 02:48:41 +08:00
Source Code (ZIP)
Source Code (TAR.GZ)

7 Releases 7 Tags