From aef5f8808312345beb0dcd9db455c751325dd749 Mon Sep 17 00:00:00 2001
From: zijunchiang <miyu@kasugano.cn>
Date: Mon, 14 Sep 2026 20:05:40 +0800
Subject: [PATCH] =?UTF-8?q?docs(win):=20=E7=94=A8=E5=AE=9E=E7=8E=B0?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=9B=BF=E6=8D=A2=E9=98=B6=E6=AE=B5=E4=BA=8C?=
 =?UTF-8?q?=E5=8D=A0=E4=BD=8D=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 108 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 80 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 4d6ea45..8077cbe 100644
--- a/README.md
+++ b/README.md
@@ -2,44 +2,96 @@
 
 OpenDance Studio **阶段二**：Windows 客户端（Godot 4）。
 
-> **状态：占位仓库**。按《DSH 开发文档：OpenDance Studio》的开发顺序
-> （Web 服务端 → Windows 客户端 → Android 辅助 App），本仓库将在阶段一
-> （`opendance-web`）契约冻结后开始开发。
+接收 Android 辅助 App 通过 WebSocket 推送的 33 点骨骼关键点，驱动 VRM 角色，
+并与 Web 管理服务端下发的参考动作做实时 DTW 评分。
 
-## 计划技术栈
+> 本客户端只接收关键点坐标，**不接收、不存储任何视频画面**。
+
+## 状态
+
+**阶段二已完成**：T-WIN-001 → T-WIN-011 全部落地。
+
+| 验收项 | 结果 |
+|---|---|
+| 脚本编译 | ✓ 全部通过（无 SCRIPT ERROR） |
+| 无头测试 | ✓ **580 项全部通过**（8 个测试套件） |
+| 应用启动 | ✓ 180 帧无运行时错误 |
+| Windows 导出 | ✓ 生成 `OpenDance.exe`（104 MB，PE 头校验通过）+ `OpenDance.pck` |
+| 真实 VRM 验证 | ✓ 154 骨骼 VRoid 模型，humanoid 覆盖率 **100%** |
+| 骨骼重定向 | ✓ 关键点方向与骨骼实际指向点积 **1.0000** |
+| 跨实现交叉校验 | ✓ 关节角与 Web 服务端 TypeScript 实现**逐帧一致** |
+
+## 快速开始
+
+```bash
+# 验证（编译 → 测试 → 启动）
+GODOT_BIN=/path/to/godot bash build/verify.sh
+
+# 导出 Windows 可执行文件
+GODOT_BIN=/path/to/godot bash build/export-windows.sh release
+
+# 打包发布产物
+bash build/package-release.sh 0.1.0
+```
+
+详细使用说明见 [`README.txt`](README.txt)，工程约束见 [`DSH.md`](DSH.md)。
+
+## 技术栈
 
 | 组件 | 选型 |
 |---|---|
-| 引擎 | Godot 4 (MIT) |
-| VRM 加载 | godot-vrm (MIT) |
-| 多格式导入 | Assimp (BSD-3-Clause) |
-| 通信 | WebSocket + HttpClient |
-| 评分 | DTW + 关节角度差异 |
+| 引擎 | Godot 4.7.x（MIT） |
+| VRM 加载 | Godot 内置 GLTFDocument |
+| 通信 | WebSocketPeer（服务端）+ HTTPRequest |
+| 评分 | DTW + 关节角度差异（纯 GDScript） |
 
-## 计划任务
+## 架构
 
-`T-WIN-001` 骨架 → `T-WIN-002` REST 客户端 → `T-WIN-003` WebSocket 接收 →
-`T-WIN-004` 239 字节帧反序列化 → `T-WIN-005` VRM 加载 → `T-WIN-006` 骨骼重定向 →
-`T-WIN-007` DTW 评分 → `T-WIN-008` 游戏 UI → `T-WIN-009` 来源信息展示 →
-`T-WIN-010` 关于页 → `T-WIN-011` Windows 打包脚本
+```
+Android 辅助 App ──239 字节关键点帧──▶ 本端 WebSocket 服务端 :8765
+                                            │
+Web 服务端 ──GET /api/catalog/export────────┤
+           ──GET /api/motions/:id/keypoints ┘
+                                            ▼
+                                      VRM 驱动 + DTW 评分
+```
 
-## 依赖的契约（已冻结于 opendance-web，v0.1.0）
+```
+src/
+├── autoload/   AppConfig / CatalogStore / PoseReceiver / ScoreService
+├── net/        239 字节编解码、WebSocket 服务、REST 客户端、NDJSON 解析
+├── model/      VRM 加载、humanoid 骨骼名映射
+├── anim/       关键点 → 骨骼重定向
+├── score/      特征提取、DTW、评分规则
+└── ui/         主界面 / 游戏界面 / 结算 / 关于 / 来源展示
+```
 
-- `contracts/websocket-keypoints.md` — **239 字节关键点帧**与文本控制消息（本端为接收方）
-- `contracts/skeleton-topology.md` — MediaPipe 33 点拓扑、父节点表、9 个关节角特征
-- `contracts/rest-api.yaml` — 曲目/动作/模型 API
-- `contracts/data-models.md` — 资源字段与 **VRM 优先**的默认模型选取规则（§4.1）
-- `contracts/model-formats.md` — 模型与动作格式、关键点序列结构
-- `contracts/open-source-credits.md` — 关于页必须展示的开源声明（三端共用）
+界面**全部用 GDScript 代码构建**（不手写 `.tscn`），因此可被无头导入与单元测试覆盖。
 
-契约地址：https://gitea.kasugano.cn/zijunchiang/opendance-web/src/branch/main/contracts
+## 依赖的契约（opendance-web v0.1.0 冻结）
 
-**任何跨端契约变更必须先回到 `opendance-web` 修改 `contracts/` 并提升版本**，
+- [`contracts/websocket-keypoints.md`](contracts/websocket-keypoints.md) — 239 字节关键点帧与文本控制消息（本端为**接收方**）
+- [`contracts/skeleton-topology.md`](contracts/skeleton-topology.md) — MediaPipe 33 点拓扑、父节点表、9 个关节角特征
+- [`contracts/rest-api.yaml`](contracts/rest-api.yaml) — 目录与关键点序列 API
+- [`contracts/data-models.md`](contracts/data-models.md) — 资源字段与 VRM 优先规则
+- [`contracts/model-formats.md`](contracts/model-formats.md) — 模型与动作格式、关键点序列结构
+
+`contracts/` 是**只读快照**。任何跨端契约变更必须先回到
+[`opendance-web`](https://gitea.kasugano.cn/zijunchiang/opendance-web) 修改并提升版本，
 再在本仓库创建适配任务。
 
-## 关键约束
+## 已知限制
 
-- 客户端消费的目录通过 `GET /api/catalog/export` 一次性拉取，仅含 `status = published` 的资源
-- 默认模型直接用服务端解析好的 `defaultModelId`，本端无需自行实现优先级
-- 不使用 SMPL 拓扑
-- 发布产物必须包含 `THIRD_PARTY.md` 与「关于」页开源声明
\ No newline at end of file
+1. Godot 的 `WebSocketPeer` 不暴露握手请求路径，因此**无法校验 path 是否为 `/pose`**，
+   实现接受任意 path，仅校验子协议 `opendance.pose.v1`。
+2. 文档原选型 `godot-vrm` GDExtension 不发布预编译产物，改用 Godot 内置 glTF 导入器
+   + 自实现骨骼名映射；理由见 `DSH.md` §6。
+3. `build/export-windows.ps1` 未在真实 Windows 上执行过（本环境无 Windows）。
+   两条路径共用同名导出预设与相同的 PE 头校验逻辑。
+4. 真实 VRM 样例仅放在 `_scratch/`（已 gitignore），版权原因不入库；
+   测试在找不到模型时显式跳过而非伪装通过。
+
+## 第三方开源声明
+
+见 [`THIRD_PARTY.md`](THIRD_PARTY.md)，或客户端「关于」页面。
+未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。