zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
50 Commits 2 Branches 7 Tags
main
Commit Graph
5 Commits
Author SHA1 Message Date
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
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
zijunchiang a78a536476 feat(integration): 跨端集成验收（包内客户端 × 真实 Web 服务端）+ 修两个真实缺陷（v0.2.3） 
单测打的是假 HTTP 夹具，Web 端测试只验自己那一侧 —— 两端各自绿灯不代表契约字段
真的对得上。本版加了跨端集成验收，并在首次运行就抓到两个真实缺陷。

一、跨端集成验收（T-WIN-019）
  * build/integration/probe-integration.gd：只加载**包内**代码
    （`godot --main-pack <pck> --script <探针>` + res://），打真实服务端并逐项断言：
    /health 六个契约版本、catalog/version 指纹、catalog/export 解析出的四类资源与
    defaultModelId；**场景物理参数逐项比对**（重力/基础风/阵风/风坐标系/地面摩擦坡度/
    碰撞体/出生点/相机/环境）+ Wind.sample(0) + 场景 GLB 可下载；
    动作 NDJSON → 客户端解析帧数 == 服务端帧数、33 点、每帧服务端关节角、
    推导帧率 30 fps、时长 96.67 s；缩略图 PNG；模型 VRM 可下载。
  * build/integration/seed-catalog.mjs：用**真实素材**播种目录
    （示例文件/ 下的真 VMD → 内部标准 33 点；真 PMX → VRM；场景 GLB + 物理参数），
    并把期望值（含从 /health 取的契约版本）写成 JSON。
  * build/accept-integration.sh：编排「服务端可达 → 播种 → 包内探针 → 汇报」。
  实测（v0.2.3 包内 pck × 真实 Web v0.7.4 + 真实 MySQL）：全部通过。

二、探针抓到的两个真实缺陷
  1. `CatalogTypes.Motion` 缺 `thumbnail_url`：服务端 catalog/export 从
     data-models 0.6.0 起一直在发 thumbnailUrl（Model/Scene 都有），客户端默默丢掉。
     已补字段与解析（缺失为 ""），新增 tests/test_catalog_types.gd（4 项 20 断言）
     用**服务端真实报文形状**锁住三个资源类型的覆盖，并显式记录一处刻意不消费的差异
     （Model.usable/unusableReason —— 目录只下发可用模型，恒为 true）。
  2. `ApiClient._request()` 对**所有**响应无条件 `raw.get_string_from_utf8()`：
     数据本身没错（二进制路径返回原始字节），但每下载一个文件都会打印
     「Unicode parsing error … Invalid UTF-8 leading byte (N)」噪声，并把整个文件
     （模型可达数十 MB）解码成 String 拷贝后丢弃。改为只在需要文本时解码。

三、顺带修掉测试里的写死契约版本
  tests/test_api_integration.gd 断言 rest-api/websocket-keypoints/skeleton-topology
  均为 "0.1.0"。该用例只在服务端可达时才跑，平时一直 skip，所以契约升到 0.5.0 后
  没有任何地方发现它。改为从仓库 contracts/VERSION 读期望值并与 /health 比对
  （顺带成为「客户端契约快照 vs 服务端」的跨端校验）。

证据：verify.sh 全绿（820 通过 / 0 失败，比上版 +46，因为服务端在线时 API 集成组
真的跑了）；包内 pck 跨端集成探针全部通过；check-version/PE 版本资源 = 0.2.3。
 2026-09-17 05:18:03 +08:00
zijunchiang ba988f6ca6 fix(packaging): 发布包 exe 的 PE 版本资源必须等于发布版本（v0.2.2） 
缺陷（v0.2.1 实测）：把 opendance-windows-v0.2.1.zip 解开、在 Windows 上
「右键 → 属性 → 详细信息」，显示的是

    文件版本    0.1.0
    产品版本    0.1.0

而产物名、Git tag、README 全是 v0.2.1 —— 正是文档 §11.2 要禁止的
「不可核对的发布」。

根因：export_presets.cfg 的 application/file_version /
application/product_version 被硬编码在 0.1.0，而它们**不会**跟随
project.godot 的 application/config/version 自动更新；check-version.sh 当时
只比 project.godot ↔ project.yaml（两处一致），所以静态校验全绿、产物却是错的。
漂移发生在没人看的第三个位置 —— 校验位置少一个，等于没校验。

证据：
  strings -a -el OpenDance.exe  ->  FileVersion 0.1.0 / ProductVersion 0.1.0
  VS_FIXEDFILEINFO @0x67b976c   ->  FileVersion 0.1.0.0 / ProductVersion 0.0.0.0
对照组：官方模板 windows_release_x86_64.exe 的 FileVersion = 4.7.2，
说明本机 rcedit 改写是生效的，问题纯粹在预设的值本身。

修复：
  * build/sync-export-version.sh（新增）：导出前把版本号写进导出预设，
    幂等、拒绝非 X.Y.Z；
  * build/check-pe-version.sh（新增）：直接读 exe 的 PE 版本资源 ——
    VS_FIXEDFILEINFO（签名 0xFEEF04BD 后 16 字节，grep -abo 取偏移约 40 ms）
    与 StringFileInfo（strings -el，资源管理器属性页显示的就是它）。
    两处都查：实测固定信息里的 ProductVersion 恒为 0.0.0.0；
  * build/check-version.sh：新增导出预设两个键的校验；
  * build/export-windows.sh：导出前同步、导出后直接复核产物；
  * build/package-release.sh：打包前校验源 exe、解包后再校验包内 exe；
  * build/verify.sh：新增步骤 1/5「产物 PE 版本资源」（未导出则跳过）；
  * tests/test_about.gd：新增 test_export_preset_version_matches_project_version。

反向验证：把预设 file_version 改回 0.1.0 →
  check-version.sh 退出码 1（报出两处不一致）；
  无头测试 753 通过 / 1 失败，失败项正是
  「导出预设的 file_version 与版本号唯一来源一致」。

实测 v0.2.2 产物：PE FileVersion 0.2.2.0 / StringFileInfo 0.2.2，
版本号在 project.godot / project.yaml / export_presets.cfg / exe 元数据 /
产物名 / tag 六处一致。verify.sh 全绿（754 通过 / 0 失败 / 5 跳过）。

同时把 LZMA 压缩的取舍写清楚：deflate 包 38,248,818 B 仍超 IIS
30,000,000 B 上限，故 Release 资产仍是 LZMA 整包（26,628,529 B，不拆分卷）；
若上限放开或改由 Web /static 分发，用 ZIP_METHOD=deflate 重打包即可得到
资源管理器可直接双击解压的包。
 2026-09-17 04:22:57 +08:00
zijunchiang 315cf79708 feat(win): T-WIN-011 Windows 打包与一键验证脚本 2026-09-14 20:04:54 +08:00