From e0ba4ea8331a240ebf3df551c4bfada9a1825ee9 Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Fri, 18 Sep 2026 02:47:00 +0800 Subject: [PATCH] =?UTF-8?q?fix(ws):=20config=20=E6=94=B9=E4=B8=BA=E5=8F=98?= =?UTF-8?q?=E6=9B=B4=E9=A9=B1=E5=8A=A8=EF=BC=88=E5=8E=9F=E6=AF=8F=202=20?= =?UTF-8?q?=E7=A7=92=E6=97=A0=E6=9D=A1=E4=BB=B6=E5=B9=BF=E6=92=AD=EF=BC=89?= =?UTF-8?q?+=20=E5=A5=91=E7=BA=A6=E3=80=8C=E5=8F=AF=E9=80=89/=E5=85=9C?= =?UTF-8?q?=E5=BA=95=E3=80=8D=E8=AF=AD=E4=B9=89=E5=AE=9A=E5=90=91=E9=AA=8C?= =?UTF-8?q?=E6=94=B6=EF=BC=88v0.2.5=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 一、缺陷：config 被当成心跳 _maybe_push_config() 原来每 CONFIG_PUSH_INTERVAL_MS（2 秒）无条件广播一次 config。 契约 §3.3 的语义是「运行中**调整**时下发」，不是心跳 —— 一次 30 分钟推流就是 900 条 没有任何信息量的消息；更糟的是它让「收到 config」无法被当作「配置变了」的信号。 实测 v0.2.4 产物：17 秒内收到 9 条。 修复： * 抽出 config_payload() 作为唯一载荷来源（同时用作「是否变化」的指纹）； * hello 应答顺序固定为「先 welcome、再 config」（若靠周期 tick 补发， 新对端第一条消息可能变成 config，只认握手应答的实现会困惑）； * _maybe_push_config() 仅在载荷真的变化时广播，并用 CONFIG_PUSH_INTERVAL_MS 去抖； * 显式 broadcast_config()（UI 改设置）同步更新指纹，避免下一 tick 重发。 实测 v0.2.5：17 秒内 1 条。 二、契约「可选/兜底」语义的定向验收（沿用 Android 侧的教训： 契约里可选的字段必须用**不提供**它的对端来测，否则等于没测） 新增 3 个场景（客户端断言 30 → 40 项）： * v0.1.0 风格对端：只发二进制帧（每 500ms）、从不 ping/stats、hello 不带 deviceId， 持续 17 秒（> 静默超时 15 秒）→ 连接必须保持（契约 §1.1 的向后兼容承诺）； * 两条都不带 deviceId 的连接同时在线 → 不做去重、按连接计数（§5）， device_replaced 只应有那一次真正重复 deviceId 的事件； * 完全不发 hello、只发 5 帧的对端 → 不断开、不崩、帧仍计入。 三、验收脚本自身修掉两处误判 * 「跨连接的 frame_id 回退」被当成缺陷：frame_id 是**每条连接各自从 0 递增**， 新连接重新开始完全合规 —— 指标用错了。已改名并标注「仅参考」， 真正相关的判据是逐连接的 frames_dropped == 3； * 「静默超时次数」被当成固定值：套件里本来就有"完全不发数据"的对端， 空闲的替换连接也会被正常超时。已改为**定向断言**：由 hello 记录建立 client_id → device 映射（探针新增 hellos[]），只检查 v0.1.0 风格对端没被误踢。 四、测试客户端改为顺序无关 固定「welcome 之后紧跟 config」后，"第一条消息就是 welcome"的假设立刻暴露。 契约没规定消息顺序，客户端必须顺序无关 —— 已加 nextOfType(type) 按类型取消息 并跳过其它类型（同时计入 counts）。 实测（v0.2.5 发布包，四条验收全绿）： * accept-release.sh：pck 无开发残留 / PE 版本资源 0.2.5 / pck 启动 180 帧 / 运行时探针 * accept-ws.sh：客户端 40 通过 / 0 失败 + 服务端侧全部事实 （10 次连接、111 帧、frames_dropped=3、malformed=1、device_replaced 仅 1 次、 v0.1.0 风格对端未被静默超时踢掉） * accept-frame-vectors.sh：解码 12/12、396 点 0 差异、编码器 0 差异 * verify.sh：785 通过 / 0 失败 --- README.md | 39 ++++++-- README.txt | 20 +++- build/accept-ws.sh | 29 +++++- build/integration/probe-ws.gd | 16 ++- build/integration/ws-client.mjs | 119 ++++++++++++++++++++--- export_presets.cfg | 4 +- project.godot | 2 +- project.yaml | 8 +- src/net/pose_server.gd | 52 +++++++--- tasks/024-config-push-and-legacy-peer.md | 67 +++++++++++++ 10 files changed, 306 insertions(+), 50 deletions(-) create mode 100644 tasks/024-config-push-and-legacy-peer.md diff --git a/README.md b/README.md index debafd3..2539442 100644 --- a/README.md +++ b/README.md @@ -22,10 +22,31 @@ OpenDance Studio **阶段二**: Windows 客户端（Godot 4）。 | 跨实现交叉校验 | OK 关节角与 Web 服务端 TypeScript 实现**逐帧一致** | | 场景选择与物理落地 | OK `scenes[]` 可选、重力/风/摩擦/碰撞体落地并可日志核对 | | 连接保活与设备去重 | OK welcome/config 声明静默超时与心跳；应用层 ping/pong；按 deviceId 去重 | -| 发布整包 | OK 单个 `opendance-windows-v0.2.4.zip` + `SHA256SUMS`(不拆分卷) | +| 发布整包 | OK 单个 `opendance-windows-v0.2.5.zip` + `SHA256SUMS`(不拆分卷) | | 版本号展示 | OK 「关于」清单显示 `v0.2.2`；`project.godot` / `project.yaml` / `export_presets.cfg` / exe 的 PE 版本资源 / 产物名 / tag 全部一致 | | 场景物理与保活 | OK 新增真实 GLB 端到端用例 + 17 秒保活对照用例（751 项断言全过） | +## v0.2.5 修订（config 改为变更驱动 + 契约「可选/兜底」语义定向验收） + +**缺陷**：`config` 被当成心跳 —— 每 2 秒**无条件**广播一次（契约 §3.3 的语义是 +"运行中**调整**时下发"）。一次 30 分钟推流 = 900 条无信息量的消息，而且让 +「收到 config」无法被当成「配置变了」的信号。实测 v0.2.4：17 秒内 9 条 → v0.2.5：**1 条**。 +修复：抽出 `config_payload()` 作为唯一载荷与指纹来源；`hello` 应答固定为 +**先 `welcome` 再 `config`**（避免新对端第一条消息变成 config）；之后仅当载荷变化才广播， +并用 `CONFIG_PUSH_INTERVAL_MS` 去抖。 + +**新增 3 个契约语义场景**（`accept-ws.sh` / `ws-client.mjs`，总 30 → **40 项断言**）： +* **v0.1.0 风格对端**：只发二进制帧（每 500ms 一帧）、**从不 ping**、`hello` 不带 `deviceId`， + 持续 17 秒（> 静默超时）→ 连接必须保持（契约 §1.1 的向后兼容承诺）； +* **两条都不带 `deviceId`** 的连接同时在线 → 不做去重，按连接计数（§5）； +* **完全不发 `hello`**、只发 5 帧的对端 → 不断开、不崩、帧仍计入。 + +顺带修掉验收脚本自身两处**误判**：把「跨连接的 frame_id 回退」当缺陷（`frame_id` 是 +每条连接各自从 0 递增，新连接重新开始是合规的）、把「静默超时次数」当固定值 +（空闲连接本来就会被正常超时）；现改为**定向断言**：由 hello 记录建立 +`client_id → device` 映射，只检查 v0.1.0 风格对端没有被误踢。 +测试客户端也改为**按类型取消息**（`nextOfType`）—— 契约没规定消息顺序，客户端必须顺序无关。 + ## v0.2.4 修订（编码取整对齐 + 产物不再夹带测试夹具） **缺陷 1（编码取整与参考实现不一致）**：`KeypointFrame.encode()` 用 GDScript 的 @@ -127,10 +148,10 @@ GODOT_BIN=/path/to/godot bash build/verify.sh GODOT_BIN=/path/to/godot bash build/export-windows.sh release # 打包发布产物（单个完整 zip + SHA256SUMS） -bash build/package-release.sh 0.2.4 +bash build/package-release.sh 0.2.5 # 发布包级验收（对**发布包**跑，而不是对源码；文档 §7.5） -GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.4.zip +GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.5.zip ``` `accept-release.sh` 校验 sha256 → 解压 → 文件清单（并检查没有 `.partN` 残留）→ @@ -149,7 +170,7 @@ Android 已用「金标准字节向量」与它对齐；而**本端的解码器 （自己编码、自己解码）。这条边由下列脚本补上： ```bash -GODOT_BIN=/path/to/godot bash build/accept-frame-vectors.sh dist-release/opendance-windows-v0.2.4.zip +GODOT_BIN=/path/to/godot bash build/accept-frame-vectors.sh dist-release/opendance-windows-v0.2.5.zip # 没有 web 仓 / 未装 node_modules 时：... --skip-regen ``` @@ -172,7 +193,7 @@ GODOT_BIN=/path/to/godot bash build/accept-frame-vectors.sh dist-release/opendan 文本/二进制边界、关闭语义、子协议协商）。因此另配一套**独立实现**的客户端： ```bash -GODOT_BIN=/path/to/godot bash build/accept-ws.sh dist-release/opendance-windows-v0.2.4.zip +GODOT_BIN=/path/to/godot bash build/accept-ws.sh dist-release/opendance-windows-v0.2.5.zip # 跳过耗时的两个场景（保活 19s / 静默超时 15s）： GODOT_BIN=... bash build/accept-ws.sh --skip-slow ``` @@ -190,7 +211,7 @@ GODOT_BIN=... bash build/accept-ws.sh --skip-slow 保活字段、不回 pong、不做去重）跑同一客户端 → 14 项 ✗、退出码 1，证明断言不是空转。 详见 [`tasks/020-ws-contract-conformance.md`](tasks/020-ws-contract-conformance.md)。 -当前版本：**v0.2.4**（`project.godot` 的 `application/config/version`， +当前版本：**v0.2.5**（`project.godot` 的 `application/config/version`， 与 `project.yaml`、`export_presets.cfg`、导出产物名、Git tag、「关于」清单展示、 以及 exe 的 PE 版本资源全部一致）。 @@ -273,7 +294,7 @@ GODOT_BIN=/path/to/godot bash build/export-windows.sh release powershell -ExecutionPolicy Bypass -File build\export-windows.ps1 # 打成可分发的 zip（单个完整包 + SHA256SUMS） -bash build/package-release.sh 0.2.4 +bash build/package-release.sh 0.2.5 ``` | 产物 | 位置 | 说明 | @@ -281,7 +302,7 @@ bash build/package-release.sh 0.2.4 | `OpenDance.exe` | `build/windows/` | 主程序，约 104 MB；脚本校验前 2 字节为 `MZ`(合法 PE) | | `OpenDance.pck` | `build/windows/` | 资源包，约 107 KB; **必须与 exe 同目录** | | `OpenDance.console.exe` | `build/windows/` | 控制台包装器，可能生成，非必需 | -| `opendance-windows-v0.2.4.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` | +| `opendance-windows-v0.2.5.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` | | `SHA256SUMS` | `dist-release/` | 裸文件名，与 zip 同目录时可 `sha256sum -c SHA256SUMS` 直接校验 | 导出前必须安装与编辑器同版本的 export templates，否则脚本会报「未找到导出模板」。 @@ -385,7 +406,7 @@ src/ 等格式，但本项目未在 Windows 上实测）。 若 IIS 上限已放开、或你能把包放到别处分发（例如 Web 服务端的 `/static`， 不受 IIS 那个限制约束），请改用资源管理器可直接双击解压的 deflate 包： - `ZIP_METHOD=deflate bash build/package-release.sh 0.2.4`（约 38 MB）。 + `ZIP_METHOD=deflate bash build/package-release.sh 0.2.5`（约 38 MB）。 7. **发布包 exe 的版本元数据**（T-WIN-017）：v0.2.1 之前在 Windows 「属性 → 详细信息」里显示的是 `0.1.0`，因为 `export_presets.cfg` 的 `application/file_version` / `application/product_version` 被硬编码且无人校验。 diff --git a/README.txt b/README.txt index ba71258..c5526cd 100644 --- a/README.txt +++ b/README.txt @@ -1,5 +1,5 @@ ================================================================ -OpenDance Studio -- Windows 客户端 v0.2.4 使用说明（zip 为 LZMA 压缩，需用 7-Zip/WinRAR 解压） +OpenDance Studio -- Windows 客户端 v0.2.5 使用说明（zip 为 LZMA 压缩，需用 7-Zip/WinRAR 解压） ================================================================ 摄像头跳舞评分系统的核心体验端：接收 Android 辅助 App 通过 WebSocket @@ -8,6 +8,16 @@ OpenDance Studio -- Windows 客户端 v0.2.4 使用说明（zip 为 LZMA 压缩 本客户端只接收关键点坐标，不接收、不存储任何视频画面。 +v0.2.5 修订 + 1. config 不再被当成心跳: 原来每 2 秒无条件广播一次（契约 §3.3 的语义是"运行中 + 调整时下发"），一次 30 分钟推流会产生 900 条无信息量的消息。现改为 + "hello 应答后先 welcome 再 config，之后仅当配置真的变化才广播（带去抖）"。 + 实测 17 秒内 config 由 9 条降到 1 条。 + 2. 新增 3 个契约语义场景（WebSocket 验收断言 30 → 40 项）: + v0.1.0 风格对端（只发帧、从不 ping、不带 deviceId）持续 17 秒不被踢； + 两条都不带 deviceId 的连接不做去重；完全不发 hello 的对端不崩不断。 + 3. 测试规模 785 项断言。 + v0.2.4 修订 1. 编码取整与契约参考实现对齐: 本端 encode() 原用 GDScript roundi（半数远离零）， 而参考实现与生产发送方（Android 的 Math.round）是「半数朝 +∞」—— -2.5 分别是 @@ -152,11 +162,11 @@ OpenDance.exe 的用户看第一节即可。 打成发布包： - bash build/package-release.sh 0.2.4 + bash build/package-release.sh 0.2.5 得到 dist-release/ 下两个资产： - opendance-windows-v0.2.4.zip <- 单个完整包，禁止 .partN 分卷 + opendance-windows-v0.2.5.zip <- 单个完整包，禁止 .partN 分卷 SHA256SUMS <- 裸文件名，可直接 sha256sum -c 包里含 OpenDance.exe、OpenDance.pck、THIRD_PARTY.md、README.txt、 @@ -175,14 +185,14 @@ OpenDance.exe 的用户看第一节即可。 如果你能把包放到别处分发（例如 Web 服务端的 /static，不受 IIS 那个 上限约束），建议改用资源管理器可直接双击解压的 deflate 包： - ZIP_METHOD=deflate bash build/package-release.sh 0.2.4 # 约 38 MB + ZIP_METHOD=deflate bash build/package-release.sh 0.2.5 # 约 38 MB 上限一旦放开，Release 资产也应换回 deflate 包。 7. 自检清单 0) 发布包级验收（对**发布包**而不是源码；文档 §7.5） - GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.4.zip + GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.5.zip 预期末行「发布包级验收全部通过」。它会校验 sha256、解压、核对文件清单、 读 exe 的 PE 版本资源、用 Godot 直接加载包内 pck 跑 180 帧、并跑包内运行时 探针（包内版本号 / 「关于」清单显示值 / 主场景 / autoload / 关键资源 / diff --git a/build/accept-ws.sh b/build/accept-ws.sh index 7806920..ba0bd32 100755 --- a/build/accept-ws.sh +++ b/build/accept-ws.sh @@ -136,10 +136,12 @@ const say = (ok, text) => { console.log(` ${ok ? "✓" : "✗"} ${text}`); if ( say(r.server.silent_timeout_ms === 15000 && r.server.heartbeat_interval_ms === 5000, `服务端声明 silentTimeoutMs=${r.server.silent_timeout_ms} / heartbeatIntervalMs=${r.server.heartbeat_interval_ms}`); -say(r.connected.length >= 6, `收到 ${r.connected.length} 次连接（握手完成）`); -say(r.framesReceived >= 72, `收到 ${r.framesReceived} 个关键点帧`); +say(r.connected.length >= 10, `收到 ${r.connected.length} 次连接（含 v0.1.0 风格、无 deviceId、无 hello 的对端）`); +say(r.framesReceived >= 100, `收到 ${r.framesReceived} 个关键点帧（基础 72 + v0.1.0 风格对端 34 + 无 hello 对端 5）`); say(r.lastFrameId >= 74, `最大 frame_id = ${r.lastFrameId}`); -say(r.frameIdRegressions === 0, `frame_id 无回退（回退 ${r.frameIdRegressions} 次）`); +// frame_id 是「每条连接各自从 0 递增」，新连接重新从 0 开始是合规的， +// 因此这里只打印跨连接计数作参考，不用它做判定（第一版误当成缺陷）。 +console.log(` · 跨连接 frame_id 回退计数 ${r.frameIdRegressionsAcrossConnections ?? "?"}（仅参考）`); // 客户端故意跳号 60→63，服务端应按 §8 计入丢帧 say(r.server.frames_dropped >= 3, `丢帧检测：frames_dropped=${r.server.frames_dropped}（期望 ≥3，来自故意的 60→63 跳号）`); // 客户端故意发 100 字节非法帧，服务端应计数且不崩 @@ -149,14 +151,31 @@ const c = r.controls; say((c.hello ?? 0) >= 6, `hello=${c.hello ?? 0}；ping=${c.ping ?? 0}；stats=${c.stats ?? 0}；bye=${c.bye ?? 0}`); say((c.ping ?? 0) >= (skipSlow ? 1 : 8), `应用层 ping 计数=${c.ping ?? 0}（保活场景）`); // 去重事件 -say(Array.isArray(r.deviceReplaced) && r.deviceReplaced.includes("aaaa000000000001"), - `device_replaced 事件：${JSON.stringify(r.deviceReplaced)}`); +say(Array.isArray(r.deviceReplaced) && r.deviceReplaced.length === 1 + && r.deviceReplaced[0] === "aaaa000000000001", + `device_replaced 只应发生一次且只针对重复的 deviceId（实际 ${JSON.stringify(r.deviceReplaced)}）：` + + "契约 §5 要求缺 deviceId 的连接**不做去重**、按连接计数"); // 断开原因：替换(1000) / 静默超时 / bye(1000) / 协议错误(1002) const reasons = r.disconnected.map((x) => x.reason).join(" | "); say(reasons.includes("被同一设备的新连接替换"), "服务端记录了「同设备替换」断开原因"); say(reasons.includes("user_stop"), "服务端记录了 bye 的 reason"); say(reasons.includes("code=1002"), "服务端记录了协议不匹配的 1002 关闭"); if (!skipSlow) { + // 只有"专门完全不发数据"的那条连接该被静默超时踢掉。 + // v0.1.0 风格的对端只发二进制帧、从不 ping —— 契约 §1.1 明确"每帧同样算活动"， + // 若它也被踢掉，静默超时计数就会 >1（这是"契约可选字段/兜底路径"最容易漏的一处）。 + // **定向**断言：契约 §1.1 承诺"只发帧、不发 ping 的 v0.1.0 风格对端也能正常互通"。 + // 报告里的断开原因没有设备名，因此靠 hello 记录建立 client_id → device 映射， + // 再检查该连接有没有被静默超时踢掉（全局计数会混入"空闲的连接"这类正常超时）。 + const legacyIds = (r.hellos ?? []).filter((h) => String(h.device).includes("Legacy")).map((h) => h.id); + say(legacyIds.length === 1, `报告里应能识别出 v0.1.0 风格对端（client_id=${JSON.stringify(legacyIds)}）`); + const legacyTimedOut = r.disconnected.some( + (x) => legacyIds.includes(x.id) && String(x.reason).includes("静默超时"), + ); + say(!legacyTimedOut, + "只发二进制帧、从不 ping 的对端**没有**被静默超时踢掉（契约 §1.1：每帧同样算活动）"); + const silentTimeouts = r.disconnected.filter((x) => String(x.reason).includes("静默超时")).length; + console.log(` · 静默超时共 ${silentTimeouts} 次（含专门"完全不发数据"的对端与空闲连接，属预期）`); say(reasons.includes("静默超时"), "服务端记录了静默超时踢人"); // 写这条时第一版写成了 !reasons.includes("静默超时 1") —— 恰好把「消息里带 15001 ms」 // 这件正确的事判成了失败。断言要写成**正向的模式匹配**，别用容易反转语义的否定式。 diff --git a/build/integration/probe-ws.gd b/build/integration/probe-ws.gd index a9ddb2e..7868c17 100644 --- a/build/integration/probe-ws.gd +++ b/build/integration/probe-ws.gd @@ -36,6 +36,10 @@ var _connected: Array = [] var _disconnected: Array = [] var _replaced: Array = [] var _controls := {} +## 每条连接的 hello 标识（client_id → {device, deviceId}）， +## 用来在报告核对阶段回答「某类对端有没有被误踢」——断开原因里没有设备名， +## 只有 client_id 可用，所以必须在这里建立映射。 +var _hellos: Array = [] var _frames := 0 var _last_frame_id := -1 var _frame_id_regressions := 0 @@ -141,6 +145,13 @@ func _on_control_received(client_id: int, message: Dictionary) -> void: var type := str(message.get("type", "(无 type)")) _controls[type] = int(_controls.get(type, 0)) + 1 _events.append({"atMs": _now_ms(), "kind": "control", "id": client_id, "type": type}) + if type == "hello": + _hellos.append({ + "id": client_id, + "device": str(message.get("device", "")), + "deviceId": str(message.get("deviceId", "")), + "atMs": _now_ms(), + }) func _finish(code: int = 0) -> void: @@ -155,9 +166,12 @@ func _finish(code: int = 0) -> void: "disconnected": _disconnected, "deviceReplaced": _replaced, "controls": _controls, + "hellos": _hellos, "framesReceived": _frames, "lastFrameId": _last_frame_id, - "frameIdRegressions": _frame_id_regressions, + # 注意：这是**跨连接**的全局计数。frame_id 是「每条连接各自从 0 单调递增」， + # 新连接重新从 0 开始完全合规，因此该字段只作参考，不能用来判定丢帧/回退。 + "frameIdRegressionsAcrossConnections": _frame_id_regressions, "firstFrameAtMs": _first_frame_ms, "lastFrameAtMs": _last_frame_ms, "events": _events, diff --git a/build/integration/ws-client.mjs b/build/integration/ws-client.mjs index 1b7b5a4..a6f42c8 100644 --- a/build/integration/ws-client.mjs +++ b/build/integration/ws-client.mjs @@ -83,16 +83,32 @@ function buildFrame({ frameId = 0, flags = 0, mirrored = false, lowConf = false, return new Uint8Array(buf); } -/** 打开一条连接，返回 { ws, next(type), closeInfo } */ -function connect({ deviceId = '', device = 'Node 契约客户端', protocol = SUBPROTOCOL, hello = true } = {}) { +/** + * 打开一条连接，返回 { ws, state, next(), closed(), counts } + * + * @param omitDeviceId 为 true 时 `hello` **不带 deviceId 字段**（契约 §3.1 标注为可选， + * §5 要求此时接收端"不做去重，按连接计数"） + * @param hello 为 false 时连 `hello` 都不发（测接收端对"只发二进制帧"的对端是否宽容） + */ +function connect({ + deviceId = '', + device = 'Node 契约客户端', + protocol = SUBPROTOCOL, + hello = true, + omitDeviceId = false, +} = {}) { return new Promise((resolve, reject) => { const ws = new WebSocket(URL_, [SUBPROTOCOL]); ws.binaryType = 'arraybuffer'; const inbox = []; const waiters = []; const state = { closeInfo: null, error: null }; + /** 收到的消息类型计数（用于断言"config 不是周期性刷屏"这类事实） */ + const counts = {}; const push = (msg) => { + const t = msg?.type ?? '(未知)'; + counts[t] = (counts[t] ?? 0) + 1; const w = waiters.shift(); if (w) w(msg); else inbox.push(msg); @@ -128,14 +144,18 @@ function connect({ deviceId = '', device = 'Node 契约客户端', protocol = SU opened .then(() => { if (hello) { - ws.send(JSON.stringify({ - type: 'hello', protocol, deviceId, device, + const payload = { + type: 'hello', protocol, device, appVersion: '0.2.0', cameraFacing: 'front', targetFps: 30, resolution: '640x480', - })); + }; + // 契约 §3.1：deviceId 可选 —— 这里刻意支持"整个字段都不出现"的合规对端 + if (!omitDeviceId) payload.deviceId = deviceId; + ws.send(JSON.stringify(payload)); } resolve({ ws, state, + counts, next: (timeoutMs = 3000) => new Promise((res) => { if (inbox.length) return res(inbox.shift()); const t = setTimeout(() => res({ type: '(超时)', timeoutMs }), timeoutMs); @@ -145,6 +165,22 @@ function connect({ deviceId = '', device = 'Node 契约客户端', protocol = SU res(m); }); }), + /** + * 按**类型**取消息，跳过其它类型（并把它们计入 counts）。 + * 契约没有规定消息顺序，客户端必须顺序无关 —— 尤其是接收端现在会在 + * `welcome` 之后立刻补一条 `config`，"第一条消息是 welcome" 不再是保证。 + */ + async nextOfType(type, timeoutMs = 3000) { + const skipped = []; + const deadline = Date.now() + timeoutMs; + while (Date.now() < deadline) { + const msg = await this.next(Math.max(50, deadline - Date.now())); + if (msg?.type === type) return msg; + skipped.push(msg?.type); + if (msg?.type === '(closed)') return msg; + } + return { type: '(超时)', expected: type, skipped }; + }, async closed(timeoutMs = 3000) { if (state.closeInfo) return state.closeInfo; const t0 = Date.now(); @@ -171,7 +207,7 @@ async function main() { // ---------- §1/§3.2 握手 ---------- console.log('[1] 子协议协商 + hello → welcome（§1 / §3.1 / §3.2）'); const a = await connect({ deviceId: 'aaaa000000000001', device: 'Pixel 8' }); - const welcome = await a.next(3000); + const welcome = await a.nextOfType('welcome'); check('收到 welcome', welcome?.type === 'welcome', JSON.stringify(welcome)); check('welcome.protocol 与契约一致', welcome?.protocol === SUBPROTOCOL, String(welcome?.protocol)); check('welcome.sessionId 非空', typeof welcome?.sessionId === 'string' && welcome.sessionId.length > 0); @@ -205,7 +241,7 @@ async function main() { a.ws.send(JSON.stringify({ type: 'stats', fps: 29.6, dropped: 3, latencyMs: 42, confidenceAvg: 0.93 })); const sentAt = 1730000000000; a.ws.send(JSON.stringify({ type: 'ping', sentAtMs: sentAt })); - const pong = await a.next(3000); + const pong = await a.nextOfType('pong'); check('收到 pong', pong?.type === 'pong', JSON.stringify(pong)); check('pong.sentAtMs 原样回传', pong?.sentAtMs === sentAt, String(pong?.sentAtMs)); check('pong.serverAtMs 已填写', Number.isFinite(Number(pong?.serverAtMs)) && Number(pong?.serverAtMs) > 0, @@ -214,7 +250,7 @@ async function main() { // ---------- §5 设备去重 ---------- console.log('\n[4] 同 deviceId 替换旧连接（§5）'); const a2 = await connect({ deviceId: 'aaaa000000000001', device: 'Pixel 8' }); - const a2welcome = await a2.next(3000); + const a2welcome = await a2.nextOfType('welcome'); check('新连接收到 welcome', a2welcome?.type === 'welcome', JSON.stringify(a2welcome)); const oldClose = await a.closed(4000); check('旧连接被服务端关闭', oldClose !== null, '旧连接仍在打开'); @@ -229,7 +265,7 @@ async function main() { console.log(' · --skip-slow：跳过 19 秒对照'); } else { const k = await connect({ deviceId: 'bbbb000000000002', device: 'Keepalive' }); - const kw = await k.next(3000); + const kw = await k.nextOfType('welcome'); check('保活连接已握手', kw?.type === 'welcome', JSON.stringify(kw)); const deadline = Date.now() + (silent + 4000); // 超过静默超时 4 秒 let pings = 0; @@ -252,7 +288,7 @@ async function main() { console.log(' · --skip-slow：跳过静默超时对照'); } else { const s = await connect({ deviceId: 'cccc000000000003', device: 'Silent' }); - const sw = await s.next(3000); + const sw = await s.nextOfType('welcome'); check('静默连接已握手', sw?.type === 'welcome', JSON.stringify(sw)); const t0 = Date.now(); const closeInfo = await s.closed(silent + 6000); @@ -267,7 +303,7 @@ async function main() { // ---------- §3.5 bye ---------- console.log('\n[7] bye → 服务端 close(1000)（§3.5）'); const b = await connect({ deviceId: 'dddd000000000004', device: 'Bye' }); - await b.next(3000); + await b.nextOfType('welcome'); b.ws.send(JSON.stringify({ type: 'bye', reason: 'user_stop' })); const byeClose = await b.closed(4000); check('服务端关闭了连接', byeClose !== null); @@ -276,14 +312,71 @@ async function main() { // ---------- §3.1 / §6 协议不匹配 ---------- console.log('\n[8] 协议版本不匹配 → bye + close(1002)（§3.1 / §6）'); const c = await connect({ deviceId: 'eeee000000000005', device: 'Old', protocol: 'opendance.pose.v0' }); - const byeMsg = await c.next(3000); + const byeMsg = await c.nextOfType('bye'); check('收到 bye', byeMsg?.type === 'bye', JSON.stringify(byeMsg)); check('bye.reason 说明协议不匹配', String(byeMsg?.reason ?? '').includes('protocol_mismatch'), String(byeMsg?.reason)); const mismatchClose = await c.closed(4000); check('关闭码为 1002（协议错误）', mismatchClose?.code === 1002, String(mismatchClose?.code)); + // ---------- §1.1 向后兼容：v0.1.0 风格对端（只发帧，从不 ping）---------- + console.log('\n[9] v0.1.0 风格对端：只发二进制帧、不发 ping / stats、hello 不带 deviceId（§1.1 / §3.1）'); + if (SKIP_SLOW) { + console.log(' · --skip-slow：跳过 17 秒帧保活对照'); + } else { + const legacy = await connect({ omitDeviceId: true, device: 'Legacy v0.1.0' }); + const lw = await legacy.nextOfType('welcome'); + check('v0.1.0 风格对端也收到 welcome', lw?.type === 'welcome', JSON.stringify(lw)); + const legacyFrames = Math.ceil((silent + 2000) / 500); // 每 500ms 一帧 + for (let i = 0; i < legacyFrames; i += 1) { + if (legacy.ws.readyState !== WebSocket.OPEN) break; + legacy.ws.send(buildFrame({ frameId: i })); + await sleep(500); + } + check(`只发帧（每 500ms 一帧、共 ${legacyFrames} 帧）持续 ${((silent + 2000) / 1000).toFixed(1)}s 后连接仍打开`, + legacy.ws.readyState === WebSocket.OPEN, + `readyState=${legacy.ws.readyState}（契约 §1.1：每帧都算活动，ping 只是兜底）`); + check('没有收到过 pong 也能正常推流（本场景从不发 ping）', + (legacy.counts.pong ?? 0) === 0, JSON.stringify(legacy.counts)); + // §3.3 的语义是"运行中调整时下发"，不是心跳：17 秒内不应出现周期性刷屏 + const cfgCount = legacy.counts.config ?? 0; + check(`17 秒内 config 条数应在合理范围（收到 ${cfgCount} 条；周期广播会是 ~8 条）`, + cfgCount <= 3, `实际 ${cfgCount} 条 —— config 应为变更驱动，而非心跳`); + legacy.ws.close(1000, 'done'); + await legacy.closed(2000); + } + + // ---------- §5 缺 deviceId → 不做去重 ---------- + console.log('\n[10] 两个都不带 deviceId 的连接不应互相顶掉（§5）'); + const n1 = await connect({ omitDeviceId: true, device: 'No-Id A' }); + const n1w = await n1.nextOfType('welcome'); + check('第一条无 deviceId 连接握手成功', n1w?.type === 'welcome', JSON.stringify(n1w)); + const n2 = await connect({ omitDeviceId: true, device: 'No-Id B' }); + const n2w = await n2.nextOfType('welcome'); + check('第二条无 deviceId 连接握手成功', n2w?.type === 'welcome', JSON.stringify(n2w)); + await sleep(500); + check('第一条仍在打开（未被去重顶掉）', n1.ws.readyState === WebSocket.OPEN, String(n1.ws.readyState)); + check('第二条仍在打开', n2.ws.readyState === WebSocket.OPEN, String(n2.ws.readyState)); + n1.ws.close(1000, 'done'); + n2.ws.close(1000, 'done'); + await n1.closed(2000); + await n2.closed(2000); + + // ---------- 不打招呼的对端（连 hello 都不发）---------- + console.log('\n[11] 完全不发 hello、只发二进制帧的对端应被宽容对待'); + const raw = await connect({ hello: false }); + const rawFrames = 5; + for (let i = 0; i < rawFrames; i += 1) { + raw.ws.send(buildFrame({ frameId: 1000 + i })); + await sleep(30); + } + await sleep(300); + check('接收端没有因此断开连接', raw.ws.readyState === WebSocket.OPEN, String(raw.ws.readyState)); + check('一个控制帧都没发过', Object.keys(raw.counts).length === 0, JSON.stringify(raw.counts)); + raw.ws.close(1000, 'done'); + await raw.closed(2000); + // ---------- 收尾 ---------- - console.log('\n[9] 收尾'); + console.log('\n[12] 收尾'); a2.ws.close(1000, 'done'); await a2.closed(2000); await sleep(300); diff --git a/export_presets.cfg b/export_presets.cfg index 0eb49bb..c024dcb 100644 --- a/export_presets.cfg +++ b/export_presets.cfg @@ -37,8 +37,8 @@ application/modify_resources=true application/icon="" application/console_wrapper_icon="" application/icon_interpolation=4 -application/file_version="0.2.4" -application/product_version="0.2.4" +application/file_version="0.2.5" +application/product_version="0.2.5" application/company_name="OpenDance Studio" application/product_name="OpenDance Studio" application/file_description="OpenDance Studio 摄像头跳舞评分客户端" diff --git a/project.godot b/project.godot index b827f3f..c16ca47 100644 --- a/project.godot +++ b/project.godot @@ -9,7 +9,7 @@ config_version=5 config/name="OpenDance Studio" config/description="摄像头跳舞评分系统 —— Windows 客户端。接收 Android 辅助 App 的 33 点骨骼关键点，驱动 VRM 角色并 DTW 实时评分。" -config/version="0.2.4" +config/version="0.2.5" run/main_scene="res://scenes/main.tscn" config/features=PackedStringArray("4.7", "GL Compatibility") config/icon="res://icon.svg" diff --git a/project.yaml b/project.yaml index 1867d15..f6a3409 100644 --- a/project.yaml +++ b/project.yaml @@ -1,5 +1,5 @@ project: opendance-windows-client -version: 0.2.4 +version: 0.2.5 repository: opendance-windows default_branch: main engine: Godot 4.7.2 @@ -118,9 +118,13 @@ tasks: file: tasks/023-pck-dev-leftovers.md scope: 发布包内不得混入开发/验收工具（export exclude build/*）+ 产物级残留检查 status: done + - id: T-WIN-024 + file: tasks/024-config-push-and-legacy-peer.md + scope: config 改为变更驱动（原每 2 秒无条件广播）+ v0.1.0 风格对端/缺 deviceId/无 hello 的契约语义验收 + status: done deliverable: - artifact: opendance-windows-v0.2.4.zip + artifact: opendance-windows-v0.2.5.zip packaging: Godot 导出脚本（Linux 直接导出 / Windows 兜底） release_rules: # 文档 §5.7 硬性要求 - 单个完整包，禁止 .partN 分卷 diff --git a/src/net/pose_server.gd b/src/net/pose_server.gd index d714fff..149e89f 100644 --- a/src/net/pose_server.gd +++ b/src/net/pose_server.gd @@ -76,6 +76,8 @@ var _next_client_id: int = 1 var _port: int = 0 var _running: bool = false var _last_config_push_ms: int = 0 +## 最近一次广播出去的配置指纹（用于「配置是否变化」判断） +var _last_config_signature: String = "" ## 见 DEGRADED_HOLD_MS；运行期可调（测试用） var degraded_hold_ms: int = DEGRADED_HOLD_MS @@ -372,7 +374,11 @@ func _handle_control(entry: Dictionary, text: String) -> void: if message.has("targetFps"): expected_fps = int(message["targetFps"]) entry["state"] = ClientState.STREAMING if int(entry["first_frame_at_ms"]) > 0 else ClientState.HANDSHAKING + # 顺序固定：先 welcome（对 hello 的应答），再 config（当前镜像/帧率/保活参数）。 + # 也可以等周期 tick 广播，但那样"新连接的第一条消息"可能变成 config， + # 让只认"握手应答"的实现困惑 —— 契约没规定顺序，但顺序自然更好排障。 _send_json(entry, welcome_payload()) + _send_json(entry, config_payload()) "ping": # 契约 §3.6：应用层心跳（协议层 ping 对应用层不可见，无法续命） _send_json(entry, { @@ -401,18 +407,9 @@ func welcome_payload() -> Dictionary: } -func _maybe_push_config() -> void: - if CONFIG_PUSH_INTERVAL_MS <= 0: - return - var now := Time.get_ticks_msec() - if now - _last_config_push_ms < CONFIG_PUSH_INTERVAL_MS: - return - _last_config_push_ms = now - broadcast_config() - - -func broadcast_config() -> void: - var payload := { +## 契约 §3.3 的 config 载荷（同时用作「配置是否变化」的指纹来源） +func config_payload() -> Dictionary: + return { "type": "config", "mirror": mirror, "targetFps": expected_fps, @@ -422,6 +419,37 @@ func broadcast_config() -> void: "silentTimeoutMs": CLIENT_TIMEOUT_MS, "heartbeatIntervalMs": HEARTBEAT_INTERVAL_MS, } + + +## 契约 §3.3 的语义是「**运行中调整**时下发」，不是心跳。 +## +## 原实现每 `CONFIG_PUSH_INTERVAL_MS`（2 秒）**无条件**广播一次 config —— +## 对一次 30 分钟的推流是 900 条没有任何信息量的消息，也让「收到 config」 +## 无法被当成「配置变了」的信号（发送端想据此做点什么就无从判断）。 +## 现在改为： +## 1. 有新客户端完成握手 → 立刻补发一次（它需要知道镜像/目标帧率）； +## 2. 之后仅当**载荷真的变化**才发，并用 `CONFIG_PUSH_INTERVAL_MS` 做去抖 +## （连续拖动滑块时不会每个中间值都发一条）。 +func _maybe_push_config() -> void: + if CONFIG_PUSH_INTERVAL_MS <= 0: + return + var now := Time.get_ticks_msec() + var signature := JSON.stringify(config_payload()) + + if signature == _last_config_signature: + return + if now - _last_config_push_ms < CONFIG_PUSH_INTERVAL_MS: + return + _last_config_signature = signature + _last_config_push_ms = now + broadcast_config() + + +func broadcast_config() -> void: + var payload := config_payload() + # 显式广播（UI 改了镜像/帧率等）也要更新指纹，否则下一个 tick 会再发一遍同样的内容 + _last_config_signature = JSON.stringify(payload) + _last_config_push_ms = Time.get_ticks_msec() for entry in _clients: if entry["handshaken"]: _send_json(entry, payload) diff --git a/tasks/024-config-push-and-legacy-peer.md b/tasks/024-config-push-and-legacy-peer.md new file mode 100644 index 0000000..f656d03 --- /dev/null +++ b/tasks/024-config-push-and-legacy-peer.md @@ -0,0 +1,67 @@ +# T-WIN-024：config 改为变更驱动 + 契约「可选/兜底」语义的定向验收 + +- **状态**: done +- **依赖**: T-WIN-020（WS 契约一致性验收） +- **文档**: v1.6 §6.5 / §7.6.1 +- **契约**: `websocket-keypoints 0.2.0` §1.1 / §3.1 / §3.3 / §5 + +## 一、缺陷：config 被当成心跳周期性广播 + +`_maybe_push_config()` 原来每 `CONFIG_PUSH_INTERVAL_MS`（2 秒）**无条件**广播一次 `config`： + +* 契约 §3.3 的语义是「**运行中调整**时下发」，不是心跳。一次 30 分钟推流 = **900 条** + 没有任何信息量的消息； +* 更糟的是它让「收到 config」无法被当作「配置变了」的信号 —— 发送端想据此做点什么 + 就无从判断。实测（v0.2.4 产物）：17 秒内收到 **9 条** config。 + +**修复**： +1. 抽出 `config_payload()` 作为唯一载荷来源（同时用作「是否变化」的指纹）； +2. `hello` 应答时**顺序固定**为「先 `welcome`、再 `config`」—— 契约没规定顺序， + 但若让周期 tick 补发，新对端的第一条消息可能变成 `config`，只认握手应答的实现会困惑； +3. `_maybe_push_config()` 只在**载荷真的变化**时广播，并用 `CONFIG_PUSH_INTERVAL_MS` + 做去抖（连续拖动滑块不会每个中间值都发一条）； +4. 显式 `broadcast_config()`（UI 改镜像/帧率时调用）也同步更新指纹，避免下一 tick 重发。 + +实测（v0.2.5 产物）：17 秒内 **1 条**。 + +## 二、契约「可选/兜底」语义的定向验收（新增 3 个场景） + +上一轮 Android 侧的教训是「契约里**可选**的字段必须用**不提供**它的对端来测， +否则等于没测」（自家两端总是互相迎合）。这轮把它用到接收端： + +| 场景 | 契约条款 | 断言 | +|--|--|--| +| **v0.1.0 风格对端**：只发二进制帧（每 500ms 一帧）、**从不发 `ping`/`stats`**、`hello` **不带 `deviceId`**，持续 17 秒（> 静默超时 15 秒） | §1.1「仅实现 v0.1.0 的一端仍可正常互通（它不发 ping、不读 silentTimeoutMs，但每帧与每秒 stats 已足够保活）」 | 连接**保持打开**；服务端**没有**把它静默超时踢掉（靠 hello 记录建立 `client_id → device` 映射后定向核对） | +| **两条都不带 `deviceId`** 的连接同时在线 | §5「`deviceId` 缺失或为空 → 不做去重，按连接计数」 | 两条都保持打开，`device_replaced` **只有**那次真正重复 `deviceId` 的事件 | +| **完全不发 `hello`**、只发 5 帧的对端 | 契约未规定（不该崩、不该断） | 服务端不断开、不崩，帧仍被计入 | + +## 三、验收脚本自身修掉的两处误判 + +1. **把"跨连接的 frame_id 回退"当成缺陷**：`frame_id` 是**每条连接各自从 0 递增**， + 新连接重新从 0 开始完全合规。探针原来做的是全局计数，属**指标用错**。 + 已改名为 `frameIdRegressionsAcrossConnections` 并标明「仅参考」， + 不再作为判定依据（真正相关的判据是逐连接的 `frames_dropped == 3`）。 +2. **把"静默超时次数"当成固定值**：套件里本来就有一条专门"完全不发数据"的对端， + 另外那条空闲的替换连接也会被正常超时 —— 全局计数会混入这些**预期**超时。 + 已改为**定向断言**：先由 hello 记录找出 v0.1.0 风格对端的 `client_id`， + 再检查它**没有**被静默超时踢掉。 + +## 四、测试客户端也要"顺序无关" + +固定「先 welcome 再 config」之后，`ws-client.mjs` 里"取到的第一条消息就是 welcome" +的假设暴露了：接收端在 `welcome` 之后紧跟 `config`，断言就会拿到 config。 +契约没有规定消息顺序，**客户端必须顺序无关** —— 已加 `nextOfType(type)`， +按类型取消息并跳过其它类型（同时计入 `counts`）。 + +## 五、实测 + +``` +== 结果：40 通过 / 0 失败 == # 原 30 项，新增 10 项 +✓ 只发帧（每 500ms 一帧、共 34 帧）持续 17.0s 后连接仍打开 +✓ 17 秒内 config 条数应在合理范围（收到 1 条；周期广播会是 ~8 条） +✓ 报告里应能识别出 v0.1.0 风格对端（client_id=[7]） +✓ 只发二进制帧、从不 ping 的对端没有被静默超时踢掉（契约 §1.1：每帧同样算活动） +✓ 第一条仍在打开（未被去重顶掉）／✓ 第二条仍在打开 +✓ 一个控制帧都没发过 +服务端侧：10 次连接 / 111 帧 / frames_dropped=3 / malformed_frames=1 / device_replaced 仅 1 次 +```