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 输入的行为其实完全一致。断言必须基于实际存储精度，或改用有效判别用例。
This commit is contained in:
@@ -22,10 +22,28 @@ OpenDance Studio **阶段二**: Windows 客户端（Godot 4）。
|
||||
| 跨实现交叉校验 | OK 关节角与 Web 服务端 TypeScript 实现**逐帧一致** |
|
||||
| 场景选择与物理落地 | OK `scenes[]` 可选、重力/风/摩擦/碰撞体落地并可日志核对 |
|
||||
| 连接保活与设备去重 | OK welcome/config 声明静默超时与心跳；应用层 ping/pong；按 deviceId 去重 |
|
||||
| 发布整包 | OK 单个 `opendance-windows-v0.2.3.zip` + `SHA256SUMS`(不拆分卷) |
|
||||
| 发布整包 | OK 单个 `opendance-windows-v0.2.4.zip` + `SHA256SUMS`(不拆分卷) |
|
||||
| 版本号展示 | OK 「关于」清单显示 `v0.2.2`；`project.godot` / `project.yaml` / `export_presets.cfg` / exe 的 PE 版本资源 / 产物名 / tag 全部一致 |
|
||||
| 场景物理与保活 | OK 新增真实 GLB 端到端用例 + 17 秒保活对照用例（751 项断言全过） |
|
||||
|
||||
## v0.2.4 修订（编码取整对齐 + 产物不再夹带测试夹具）
|
||||
|
||||
**缺陷 1（编码取整与参考实现不一致）**：`KeypointFrame.encode()` 用 GDScript 的
|
||||
`roundi`（半数远离零），而契约参考实现（Web 的 `Math.round`）与**生产发送方 Android**
|
||||
（Kotlin `Math.round`）都是「半数朝 +∞」—— `-2.5` 分别是 `-3` 与 `-2`。
|
||||
实测在 12 个跨实现向量里有 1 例 **33 字节不同**。本端是接收方、`encode()` 只用于自测，
|
||||
对产品无影响；但它让「跨实现一致性」只能停留在宽松口径（"差异仅限取整边界"），
|
||||
而宽松口径会退化成永远没人看的已知差异。**修复**：新增 `_round_like_js(v) = floor(v + 0.5)`
|
||||
并用于 4 处取整；`accept-frame-vectors.sh` 的口径**收紧为「编码差异必须为 0」**。
|
||||
|
||||
**缺陷 2（产物里夹带开发/验收工具）**：`export_filter="all_resources"` +
|
||||
`exclude_filter` 没有 `build/*`，于是每次新增构建/验收脚本都会被编译进 pck ——
|
||||
包括**故意不合规**的坏服务端夹具 `probe-ws-bad.gd` 与向量文件。
|
||||
`OpenDance.pck` 因此从 145,400 B 涨到 **315,464 B（54% 是测试夹具）**。
|
||||
**修复**：`exclude_filter` 增加 `build/*`；并新增**产物级防线**
|
||||
`build/integration/list-pck.gd`（遍历包内条目、标出开发残留）+ `accept-release.sh`
|
||||
断言「无残留」，避免下次加个新工具目录又重演。
|
||||
|
||||
## v0.2.3 修订（跨端集成验收 + 两处真实缺陷）
|
||||
|
||||
**缺陷 1（契约字段缺失）**：`CatalogTypes.Motion` 没有 `thumbnail_url` 字段，
|
||||
@@ -109,10 +127,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.3
|
||||
bash build/package-release.sh 0.2.4
|
||||
|
||||
# 发布包级验收（对**发布包**跑，而不是对源码；文档 §7.5）
|
||||
GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.3.zip
|
||||
GODOT_BIN=/path/to/godot bash build/accept-release.sh dist-release/opendance-windows-v0.2.4.zip
|
||||
```
|
||||
|
||||
`accept-release.sh` 校验 sha256 → 解压 → 文件清单（并检查没有 `.partN` 残留）→
|
||||
@@ -131,7 +149,7 @@ Android 已用「金标准字节向量」与它对齐；而**本端的解码器
|
||||
（自己编码、自己解码）。这条边由下列脚本补上：
|
||||
|
||||
```bash
|
||||
GODOT_BIN=/path/to/godot bash build/accept-frame-vectors.sh dist-release/opendance-windows-v0.2.3.zip
|
||||
GODOT_BIN=/path/to/godot bash build/accept-frame-vectors.sh dist-release/opendance-windows-v0.2.4.zip
|
||||
# 没有 web 仓 / 未装 node_modules 时：... --skip-regen
|
||||
```
|
||||
|
||||
@@ -154,7 +172,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.3.zip
|
||||
GODOT_BIN=/path/to/godot bash build/accept-ws.sh dist-release/opendance-windows-v0.2.4.zip
|
||||
# 跳过耗时的两个场景（保活 19s / 静默超时 15s）：
|
||||
GODOT_BIN=... bash build/accept-ws.sh <zip> --skip-slow
|
||||
```
|
||||
@@ -172,7 +190,7 @@ GODOT_BIN=... bash build/accept-ws.sh <zip> --skip-slow
|
||||
保活字段、不回 pong、不做去重）跑同一客户端 → 14 项 ✗、退出码 1，证明断言不是空转。
|
||||
详见 [`tasks/020-ws-contract-conformance.md`](tasks/020-ws-contract-conformance.md)。
|
||||
|
||||
当前版本：**v0.2.3**（`project.godot` 的 `application/config/version`，
|
||||
当前版本：**v0.2.4**（`project.godot` 的 `application/config/version`，
|
||||
与 `project.yaml`、`export_presets.cfg`、导出产物名、Git tag、「关于」清单展示、
|
||||
以及 exe 的 PE 版本资源全部一致）。
|
||||
|
||||
@@ -255,7 +273,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.3
|
||||
bash build/package-release.sh 0.2.4
|
||||
```
|
||||
|
||||
| 产物 | 位置 | 说明 |
|
||||
@@ -263,7 +281,7 @@ bash build/package-release.sh 0.2.3
|
||||
| `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.3.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` |
|
||||
| `opendance-windows-v0.2.4.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` |
|
||||
| `SHA256SUMS` | `dist-release/` | 裸文件名，与 zip 同目录时可 `sha256sum -c SHA256SUMS` 直接校验 |
|
||||
|
||||
导出前必须安装与编辑器同版本的 export templates，否则脚本会报「未找到导出模板」。
|
||||
@@ -367,7 +385,7 @@ src/
|
||||
等格式，但本项目未在 Windows 上实测）。
|
||||
若 IIS 上限已放开、或你能把包放到别处分发（例如 Web 服务端的 `/static`，
|
||||
不受 IIS 那个限制约束），请改用资源管理器可直接双击解压的 deflate 包：
|
||||
`ZIP_METHOD=deflate bash build/package-release.sh 0.2.3`（约 38 MB）。
|
||||
`ZIP_METHOD=deflate bash build/package-release.sh 0.2.4`（约 38 MB）。
|
||||
7. **发布包 exe 的版本元数据**（T-WIN-017）：v0.2.1 之前在 Windows
|
||||
「属性 → 详细信息」里显示的是 `0.1.0`，因为 `export_presets.cfg` 的
|
||||
`application/file_version` / `application/product_version` 被硬编码且无人校验。
|
||||
|
||||
Reference in New Issue
Block a user