zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
6ea2c93d66234ecca1d59348895819179064809a
opendance-windows/project.yaml
T
zijunchiang 6ea2c93d66 fix(pack): 编码取整与参考实现对齐 + 产物不再夹带测试夹具（v0.2.4） 
两个缺陷，都由上一轮的验收机制暴露：

1) 编码取整与契约参考实现不一致（T-WIN-022）
   KeypointFrame.encode() 用 GDScript 的 roundi（半数远离零），而契约参考实现
   （Web 的 keypoint-codec.ts）与**生产发送方 Android**（Kotlin Math.round）都是
   「半数朝 +∞」：-2.5 分别是 -3 与 -2。实测在 12 个跨实现向量里 1 例 33 字节不同。
   本端是接收方、encode() 只用于自测与协议回归，对产品无影响；但它让「跨实现一致性」
   只能停留在宽松口径（"差异仅限 .5 取整边界"），而宽松口径会退化成没人看的已知差异。
   修复：新增 _round_like_js(v) = floor(v + 0.5)，用于 4 处取整（坐标 ×3 + 置信度）；
   夹紧顺序对任意实数与参考实现等价。
   收紧：accept-frame-vectors.sh 的编码口径改为「必须为 0 项差异」。
   新增单测（+11 断言）：_round_like_js 的 5 个取值、端到端 -0.5/32767 → 0（roundi
   会给 -1，是有效判别用例），以及 test_reference_vectors_decode_and_encode_exactly
   —— 直接读锁定的参考向量逐值解码 + 用 f32InputPoints 重编码与 f32Hex 逐字节比对，
   让 verify.sh（只跑源码、无需 pck）也覆盖「Web ↔ Windows」这条边。

2) 产物里夹带开发/验收工具（T-WIN-023）
   export_filter="all_resources" 且 exclude_filter 没有 build/*，于是每次新增
   构建/验收脚本都被编译进 pck —— 包括**故意不合规**的坏服务端夹具 probe-ws-bad.gd
   与 frame-vectors.json。实测 OpenDance.pck 315,464 B →（排除后）145,400 B，
   即 54% 的 pck 是测试夹具。已发布的 v0.2.3 同样带着这些残留。
   修复：exclude_filter 增加 build/*；
   新增产物级防线 build/integration/list-pck.gd（遍历包内条目、标出
   res://build/ tests/ _scratch/ dist-release/ 与 *.md 残留，有残留即退出码 1），
   并接进 accept-release.sh（打印条目总数并断言「无开发残留」）——否则下次加个新
   工具目录又会重演。顺带确认 pck 没有把上一次导出的 pck 自嵌套进去。

实测（v0.2.4 发布包，三条产物级验收全绿）：
  * accept-release.sh：pck 58 项无开发残留 / PE 版本资源 0.2.4 / pck 启动 180 帧无错 /
    运行时探针（包内版本号 0.2.4、AboutScreen 显示值、15 项关键资源、契约表比对）
  * accept-ws.sh：客户端 30 通过 / 0 失败 + 服务端侧 16 项事实
  * accept-frame-vectors.sh：解码 12/12、396 点 0 差异，
    **编码器字节与参考实现完全一致（0 项差异）**
  * verify.sh：785 通过 / 0 失败（原 774）

踩坑：给 -0.5/32767 这类值写断言时，第一版按"理想有理数"期望（2.5/32767 → 3）而
失败 —— PackedVector3Array 存的是 float32，乘回 32767 后略小于半整数，与 JS 对同一
float32 输入的行为其实完全一致。断言必须基于实际存储精度，或改用有效判别用例。
2026-09-17 05:59:54 +08:00

135 lines
4.5 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.4
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
deliverable:
artifact: opendance-windows-v0.2.4.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