zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
20c6682202f04be344f8f73bd9e007d6c5e63a16
opendance-windows/project.yaml
T
zijunchiang e0ba4ea833 fix(ws): config 改为变更驱动（原每 2 秒无条件广播）+ 契约「可选/兜底」语义定向验收（v0.2.5） 
一、缺陷：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 失败
2026-09-18 02:47:00 +08:00

139 lines
4.7 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
project: opendance-windows-client
version: 0.2.5
repository: opendance-windows
default_branch: main
engine: Godot 4.7.2
contracts_version:
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
# 契约变更流程（文档 7.2）：
# 任何跨端契约变更必须先在 opendance-web 修改 contracts/ 并提升版本，
# 再在本项目创建适配任务。本项目内的 contracts/ 只是只读快照。
dependencies:
- name: opendance-web
kind: rest-api
contract: contracts/rest-api.yaml
usage: 曲目/动作/模型目录与关键点序列
- name: opendance-android
kind: websocket-consumer
contract: contracts/websocket-keypoints.md
usage: 本端为服务端，Android 主动连入推流
tasks:
- id: T-WIN-001
file: tasks/001-scaffold.md
scope: Godot 项目骨架
status: done
- id: T-WIN-002
file: tasks/002-rest-client.md
scope: 调用 Web 服务端 API
status: done
- id: T-WIN-003
file: tasks/003-websocket-receiver.md
scope: 接收 Android 关键点帧
status: done
- id: T-WIN-004
file: tasks/004-keypoint-deserialize.md
scope: 239 字节帧反序列化
status: done
- id: T-WIN-005
file: tasks/005-vrm-loader.md
scope: VRM 模型加载
status: done
- id: T-WIN-006
file: tasks/006-skeleton-retarget.md
scope: 关键点 -> VRM 骨骼重定向
status: done
- id: T-WIN-007
file: tasks/007-scoring-dtw.md
scope: DTW 评分引擎
status: done
- id: T-WIN-008
file: tasks/008-game-ui.md
scope: 主界面 + 游戏界面 + 结算
status: done
- id: T-WIN-009
file: tasks/009-source-display.md
scope: 模型/动作来源信息展示
status: done
- id: T-WIN-010
file: tasks/010-about-page.md
scope: 关于页面 + 开源声明
status: done
- id: T-WIN-011
file: tasks/011-build-script.md
scope: Windows 打包脚本
status: done
- id: T-WIN-012
file: tasks/012-about-version.md
scope: 「关于」清单展示当前版本号
status: done
- id: T-WIN-013
file: tasks/013-scene-selection.md
scope: API 升级 rest-api 0.5.0 + 场景选择 + 物理落地
status: done
- id: T-WIN-014
file: tasks/014-full-package.md
scope: 发布整包（单个 zip + SHA256SUMS，不拆分卷）
status: done
- id: T-WIN-016
file: tasks/016-aabb-transforms.md
scope: 场景包围盒沿树累乘变换（修复入树前用 global_transform 导致的 ERROR 与范围偏位）
status: done
- id: T-WIN-015
file: tasks/015-keepalive-dedup.md
scope: 连接保活 / 设备去重 / 状态机（契约 websocket-keypoints 0.2.0，与 T-AND-011 对齐）
status: done
- id: T-WIN-017
file: tasks/017-pe-version.md
scope: 发布包 exe 的 PE 版本资源（Windows 属性页显示的文件/产品版本）必须等于发布版本
status: done
- id: T-WIN-018
file: tasks/018-release-acceptance.md
scope: 发布包级端到端验收（读包内 pck：版本号 / 界面显示值 / 契约表 / 资源可加载）
status: done
- id: T-WIN-019
file: tasks/019-cross-end-integration.md
scope: 跨端集成验收（包内客户端 × 真实 Web 服务端）+ 补 Motion.thumbnailUrl 契约字段
status: done
- id: T-WIN-020
file: tasks/020-ws-contract-conformance.md
scope: WebSocket 契约一致性验收（Node 独立客户端 × 发布包内 PoseServer）+ 故意不合规的负例服务端
status: done
- id: T-WIN-021
file: tasks/021-frame-vector-conformance.md
scope: 关键点帧跨实现一致性（Web 参考实现 × 包内 GDScript 解码器，12 用例 / 396 点逐值比对）
status: done
- id: T-WIN-022
file: tasks/022-encode-rounding.md
scope: 编码取整与契约参考实现（JS Math.round）对齐，编码差异收紧为 0
status: done
- id: T-WIN-023
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.5.zip
packaging: Godot 导出脚本（Linux 直接导出 / Windows 兜底）
release_rules: # 文档 §5.7 硬性要求
- 单个完整包，禁止 .partN 分卷
- 同时上传 SHA256SUMS（裸文件名，可直接 sha256sum -c）
includes:
- OpenDance.exe
- OpenDance.pck
- THIRD_PARTY.md
- README.txt
- README.md
- contracts/ # 当前版本契约快照
Reference in New Issue View Git Blame Copy Permalink