docs: 新增「初次部署(从零跑起来)」;去混淆字符与真实内网信息
- README.md / README.txt 新增初次部署章节:前置条件、获取代码、首次运行、 配置服务端地址(API 3000 / 管理端 3001 分离)、与 Android 的 WebSocket 联通、 打包导出、自检清单、常见问题 - 三库同源契约:':=' 写法修回、去掉真实 MariaDB 版本串 - 全文去除易被 Gitea 判为「模棱两可 Unicode」的字符(- - ... -> 取代 — – … § →) - 真实内网地址与库名改占位符
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# DSH.md —— opendance-windows(OpenDance Studio 项目二:Windows 客户端)
|
||||
# DSH.md -- opendance-windows(OpenDance Studio 项目二:Windows 客户端)
|
||||
|
||||
## 0. 本文件的作用
|
||||
|
||||
@@ -11,7 +11,7 @@ Windows 客户端是核心体验载体:接收 Android 辅助 App 推送的 33
|
||||
驱动 VRM 角色,并与 Web 服务端下发的参考动作做实时 DTW 评分。
|
||||
|
||||
```
|
||||
Android 辅助 App ──239 字节关键点帧──▶ 本端(WebSocket 服务端 :8765)
|
||||
Android 辅助 App ──239 字节关键点帧──▶ 本端(WebSocket 服务端:8765)
|
||||
│
|
||||
Web 服务端 ──GET /api/catalog/export──────┤
|
||||
──GET /api/motions/:id/keypoints┘
|
||||
@@ -19,14 +19,14 @@ Web 服务端 ──GET /api/catalog/export──────┤
|
||||
VRM 驱动 + DTW 评分
|
||||
```
|
||||
|
||||
**本端是 WebSocket 的「服务端」,Android 主动连入**(契约 websocket-keypoints.md §1)。
|
||||
**本端是 WebSocket 的「服务端」,Android 主动连入**(契约 websocket-keypoints.md 1)。
|
||||
|
||||
## 2. 技术栈
|
||||
|
||||
| 组件 | 选型 | 说明 |
|
||||
|---|---|---|
|
||||
|--|--|--|
|
||||
| 引擎 | Godot 4.7.2(MIT) | 可在 Linux 上导出 Windows exe |
|
||||
| VRM 加载 | **Godot 内置 GLTFDocument** | 见 §6 的选型变更说明 |
|
||||
| VRM 加载 | **Godot 内置 GLTFDocument** | 见 6 的选型变更说明 |
|
||||
| 多格式导入 | Godot 内置 glTF 导入器 | FBX 由管理端转 BVH 后下发 |
|
||||
| 通信 | WebSocketPeer + HTTPRequest | 无第三方依赖 |
|
||||
| 评分 | DTW + 关节角度差异 | 纯 GDScript 实现 |
|
||||
@@ -52,7 +52,7 @@ Web 服务端 ──GET /api/catalog/export──────┤
|
||||
## 4. 上下文预算
|
||||
|
||||
| 项 | 建议值 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| 单任务文件数 | ≤ 6 |
|
||||
| 单任务代码行数 | ≤ 1500 |
|
||||
| 单任务 Token | ≤ 12K |
|
||||
@@ -72,7 +72,7 @@ opendance-windows/
|
||||
│ ├── autoload/ # AppConfig / CatalogStore / PoseReceiver / ScoreService
|
||||
│ ├── net/ # 239 字节编解码、WebSocket 服务、REST 客户端、NDJSON 解析
|
||||
│ ├── model/ # VRM 加载、humanoid 骨骼名映射
|
||||
│ ├── anim/ # 关键点 → 骨骼重定向
|
||||
│ ├── anim/ # 关键点 -> 骨骼重定向
|
||||
│ ├── score/ # 特征提取、DTW、评分规则
|
||||
│ └── ui/ # 主界面 / 游戏界面 / 结算 / 关于 / 来源展示
|
||||
├── tests/ # 无头测试框架 + 用例
|
||||
@@ -85,7 +85,7 @@ opendance-windows/
|
||||
`.tscn` 是带 uid 与节点路径的手写格式,在没有编辑器的情况下极易出错且难以验证;
|
||||
用代码构建可随脚本一起被无头导入和单元测试覆盖。`scenes/main.tscn` 因此只保留一个根节点。
|
||||
|
||||
**VRM 加载改用 Godot 内置 glTF 导入器**(文档 §5.1 原选型为 godot-vrm GDExtension):
|
||||
**VRM 加载改用 Godot 内置 glTF 导入器**(文档 5.1 原选型为 godot-vrm GDExtension):
|
||||
|
||||
- `V-Sekai/godot-vrm` **不发布任何预编译产物**(无 GitHub Release,仅源码,
|
||||
需用 godot-cpp 本地编译原生库),这会同时破坏「Linux 上导出 Windows exe」的验收路径。
|
||||
@@ -99,7 +99,7 @@ opendance-windows/
|
||||
|
||||
1. **绝不让视频帧离开设备**:本端只接收 33 个关键点的坐标,不接收也不存储图像。
|
||||
2. **契约先行**:改交互先改 `opendance-web` 的 `contracts/`,再回本仓库同步快照。
|
||||
3. **不假设骨骼轴向约定**:重定向基于「静止朝向 → 目标朝向」的最小旋转,
|
||||
3. **不假设骨骼轴向约定**:重定向基于「静止朝向 -> 目标朝向」的最小旋转,
|
||||
`pose = parent_global_basis⁻¹ × desired` 这一合成公式由真实 VRM 实测标定,
|
||||
有回归测试守护,不得凭记忆改写。
|
||||
4. **上传/下载的模型不入库**:真实 VRM 样例仅放在 `_scratch/`(已 gitignore),
|
||||
@@ -113,13 +113,13 @@ opendance-windows/
|
||||
GODOT=/path/to/godot # Godot 4.7.x
|
||||
|
||||
# 1. 全部脚本编译通过(无输出即通过)
|
||||
$GODOT --headless --path . --import 2>&1 | grep -E "SCRIPT ERROR|Parse Error"
|
||||
$GODOT --headless --path. --import 2>&1 | grep -E "SCRIPT ERROR|Parse Error"
|
||||
|
||||
# 2. 无头单元测试 + 真实 API 集成(API 不可达时相关用例显式跳过)
|
||||
$GODOT --headless --path . --script res://tests/run_tests.gd
|
||||
$GODOT --headless --path. --script res://tests/run_tests.gd
|
||||
|
||||
# 3. 应用可启动(autoload + UI 构建无报错)
|
||||
$GODOT --headless --path . --quit-after 180
|
||||
$GODOT --headless --path. --quit-after 180
|
||||
|
||||
# 4. Windows 导出(需先安装 export templates)
|
||||
bash build/export-windows.sh release
|
||||
@@ -128,7 +128,7 @@ bash build/export-windows.sh release
|
||||
## 9. 上下文超标时的拆分策略
|
||||
|
||||
| 超标原因 | 拆分方式 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| 单任务涉及多个界面 | 按界面拆(主/游戏/结算/关于) |
|
||||
| 单文件过大 | 按类拆,先生成接口再分实现 |
|
||||
| 契约全文加载 | 改用锚点引用 |
|
||||
|
||||
Reference in New Issue
Block a user