feat(motions): 动作预览——骨架缩略图 + 管理端 3D 回放（契约 data-models 0.6.0）

按《DSH 开发文档 v1.6》4.11（T-WEB-014，用户标注「重要」）：服务端： - 抽出公共 PNG 编码器 src/common/png.ts（模型缩略图改为复用，零原生依赖不变） - 新增 src/motions/motion-thumbnail.ts：关键点序列 -> 正视图骨架 PNG （复用 33 点 PARENT_TABLE 连线，包围盒按整段计算，低置信度点不画） - motions 增 thumbnail_asset_id（迁移 AddMotionThumbnail）+ AssetKind.MotionThumbnail - /preprocess 生成缩略图并落库，失败只记 warning；MotionDto 增 thumbnailUrl（契约 0.6.0）管理端： - 新增 MotionPreview：懒加载 NDJSON -> 骨架线框 + 关节实例球体支持播放/暂停、上一帧/下一帧、时间轴拖动、0.25x-2x 变速、循环叠加帧号/当前时间/总时长，按整段包围盒自动取景 three.js 单独分包（lazy + Suspense），主包 241 kB 不涨 - 动作列表新增 40px 骨架缩略图列（点击开预览）+ 预览按钮 + 内联预览面板 - 新增 admin/src/lib/keypoint-sequence.ts 与 lib/skeleton-topology.ts 测试：新增 8 项；规模 18 文件 / 237 项。版本 0.5.0。
feat(models): 骨骼重绑定——修复 MMD 模型 humanoid 恒为 0/22（契约 skeleton-topology 0.2.0）
2026-09-17 00:21:09 +08:00 · 2026-09-17 00:10:07 +08:00 · 2026-09-17 00:05:02 +08:00
44 changed files with 1664 additions and 141 deletions
@@ -101,7 +101,7 @@ opendance-web/
 │   ├── admin/                   # React 管理端
 │   │   ├── src/components/ModelReviewPanel.tsx  # 模型审核面板 + 骨骼详细界面
 │   │   └── src/lib/bone-tree.ts                 # 骨骼树过滤（搜索保留祖先链）
-│   ├── test/                    # 单元测试 + 端到端冒烟（15 文件 / 220 项）
+│   ├── test/                    # 单元测试 + 端到端冒烟（17 文件 / 229 项）
 │   │                            #   mmd-vmd 31 / model-archive 24 / model-inspector 25
 │   │                            #   / model-thumbnail 8 / admin-bone-filter 8
 │   │                            #   / preprocess 25 / init-env 16 / admin-port 16
@@ -291,6 +291,9 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
  `baseColorFactor x diffuse`、清掉 `KHR_materials_specular/volume/transmission/ior`、
  修正 Assimp 写坏的 `accessor.min/max`。PMX 的球面贴图与 toon 阶梯在 glTF core 里
  没有槽位，数量写入 `conversion_note`。`MODEL_SHADING=unlit` 可交付"颜色=贴图"的平涂观感。
+- **模型一律转 VRM(v0.5.0)**: `MODEL_CONVERT_FORMAT` 默认 `vrm`; humanoid 必需骨齐全才产出
+  VRM, 不达标时回退交付 GLB 且 `usable=false`(可入库可审核, **不进入 `catalog/export`**),
+  待按 `skeleton-topology` 标准重绑定骨骼后重新导入即转为可用。
 - **入库后自动**: `inspectModelFile()` 分析写入 `models.stats`
  （迁移 `AddModelStats1789460000000`，新增 `models.stats TEXT`）；
  `renderModelThumbnail()` 写入 `models.thumbnail_asset_id` / `thumbnailUrl`。
@@ -343,7 +346,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
  T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。
 - 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档，请先转换为 GLB/VRM");
  列表页显示 40px 缩略图。
- 测试：`npx vitest run` -> **15 个文件 / 220 项通过**
+- 测试：`npx vitest run` -> **17 个文件 / 229 项通过**
  (`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、
  `model-archive` 24、`mmd-vmd` 31、`preprocess` 25、`init-env` 16、
  `admin-port` 16、`access-log` 9、`vrm-inspector` 6）。
@@ -10,7 +10,31 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My

 ## 状态

-**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.5**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.5.0**(契约 `rest-api 0.4.0`、`data-models 0.6.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.3.0`)。
+
+v0.5.0 修订(**动作预览**,契约 data-models -> 0.6.0):
+
+1. **动作骨架缩略图(服务端)**:新增 `motions/motion-thumbnail.ts`——把关键点序列画成正视图骨架 PNG(零原生依赖,复用抽出的 `common/png.ts`);随 `/preprocess` 生成并落库(`motions.thumbnail_asset_id`,迁移 `AddMotionThumbnail`),失败只记 warning 不影响预处理;
+2. **动作 3D 回放(管理端,重要)**:新增 `MotionPreview`——懒加载 `GET /api/motions/:id/keypoints`(NDJSON),骨架线框 + 关节球体,支持**播放/暂停、上一帧/下一帧、时间轴拖动、0.25x-2x 变速、循环**,叠加"第 N/M 帧 · 当前时间 · 总时长",按整段包围盒自动取景;three.js 单独分包,主包体积不涨;
+3. **动作管理列表**:新增 40px 骨架缩略图列(点击开预览)+「预览/收起预览」按钮;
+4. 关键点解析与拓扑(管理端 `lib/keypoint-sequence.ts` / `lib/skeleton-topology.ts`)纯函数化,便于测试;
+5. 新增 8 项测试;规模 **18 文件 / 237 项**。
+
+v0.4.0 修订(**骨骼重绑定**:把"一律转 VRM"真正可用,契约 skeleton-topology -> 0.2.0):
+
+1. **修复 humanoid 覆盖率恒为 0/22 的根因**:`normalizeBoneName()` 原先只保留 `a-z0-9`,**中日文字符被整个丢掉**(`上半身`/`左ひじ`/`首` 全变空串);现在保留 CJK/假名,并把全角 ASCII(`足ＩＫ`)折成半角;
+2. **候选表补齐四类命名**:VRoid / Mixamo / **MMD 标准骨架**(`下半身`/`上半身`/`上半身2`/`首`/`頭`/`左肩`/`左腕`/`左ひじ`/`左手首`/`左足`/`左ひざ`/`左足首`/`左つま先`)/ 常见中文名;精确匹配保证 `左足ＩＫ` 不抢占 `左足`;
+3. **服务端与 Windows 客户端逐字一致**:`humanoid_map.gd` 的 `CANDIDATES` 由服务端表生成写入,parity 测试断言;
+4. **实测**:奥黛塔 PMX **0/22 → 21/22**、初音未来 PMX **0/22 → 19/22**,均 `drivable=true` 且产出 VRM;
+5. 契约 `skeleton-topology` -> **0.2.0**:新增 §6「内部动作标准与模型骨骼重绑定」。
+
+v0.3.0 修订(**VRM 主力化**,契约 data-models / model-formats -> 0.5.0):
+
+1. **所有上传的模型一律转 VRM**:`MODEL_CONVERT_FORMAT` 默认改为 `vrm` —— `.pmx/.fbx` 经 `assimp -> GLB -> VRM 1.0`,`glb/gltf` 导入后包装为 VRM;支持库沿用自研 `vrm-writer`/`vrm-inspector` + Assimp(可选 `@gltf-transform/core` 做结构校验);
+2. **humanoid 门槛与可用性标记**(`usable`):必需骨齐全才产出 VRM;不达标(如 MMD 日文骨名 `0/22`)时回退交付 GLB、`usable=false` —— **可入库、可审核,但不进入 `catalog/export`**(`/api/catalog/version` 指纹同步过滤);待骨骼重绑定后重新导入即转为可用;
+3. 模型列表与审核面板显示 **「不可用」及其原因**(`unusableReason`,例如 `humanoid 不达标(0/22),未产出 VRM`);`resolveDefaultModelId` 只在可用模型中选择;
+4. **管理端左下角展示当前版本号**(v1.5 文档第十一章要求):构建期从 `web-server/package.json` 注入 `v__APP_VERSION__`,与 `GET /health` 的 version **同源**;顺带修掉右下角写死的 `契约 rest-api 0.1.0`;
+5. 新增 5 项测试(`test/model-usability.spec.ts`);规模 16 文件 / 225 项。

 v0.2.5 修订:

@@ -77,15 +101,15 @@ v0.2.0 主要变更:
 3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)

   ```bash
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.5/opendance-web-v0.2.5.tar.gz
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.5/SHA256SUMS
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.5.0/opendance-web-v0.5.0.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.5.0/SHA256SUMS
   sha256sum -c SHA256SUMS      # 期望输出 "OK"
   ```

 4. 解压并生成配置(交互式引导,逐项问答,口令不回显)

   ```bash
-   tar -xzf opendance-web-v0.2.5.tar.gz && cd opendance-web-v0.2.5
+   tar -xzf opendance-web-v0.5.0.tar.gz && cd opendance-web-v0.5.0
   bash deploy/init-env.sh
   ```

@@ -155,8 +179,8 @@ FLUSH PRIVILEGES;
 ### 5. 部署步骤

 ```bash
-tar -xzf opendance-web-v0.2.5.tar.gz
-cd opendance-web-v0.2.5
+tar -xzf opendance-web-v0.5.0.tar.gz
+cd opendance-web-v0.5.0
 bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
 bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 ```
@@ -329,12 +353,12 @@ npm run dev             # http://localhost:5173(/api 与 /health 代理到 3000)
 cd web-server
 npm run contracts:check   # 契约版本一致性
 npm run typecheck         # TypeScript 严格检查
-npm run test              # 220 项单元测试 / 15 个文件(VMD 31、模型压缩包 27、
+npm run test              # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 27、
                          #   模型检查器 25、缩略图 8、骨骼过滤 8、
                          #   预处理 25、init-env 16、admin-port 16、
                          #   access-log 9、VRM 检查器 6、.env 预检 12、
                          #   Assimp 定位与安装 13、stats 容量与编码 12、
-                          #   缩略图贴图采样 6、MMD 材质对齐 9)
+                          #   缩略图贴图采样 6、MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8)
 npm run build             # 生产构建
 npm run start:prod &      # 启动
 npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -357,7 +381,7 @@ cd ../admin && npm run build   # 管理端构建
 | `STORAGE_DIR` | `/var/lib/opendance/storage` | 上传文件存储目录(原生部署默认值) |
 | `UPLOAD_MAX_BYTES` | `536870912`(512 MiB) | 单文件上限。反向代理层的同名限制必须不小于此值,否则大模型上传会在代理层被拒(nginx `client_max_body_size` / IIS `requestLimits`),详见 `deploy/proxy/README.md` |
 | `ASSIMP_BIN` | `assimp` | Assimp 可执行文件(`install.sh` 会自动安装并解析出绝对路径写入此项)。`.pmx/.fbx` 模型转换与 FBX/glTF 动作预处理需要;缺失时上传会失败并给出安装命令,只上传 `.glb/.vrm` 不受影响 |
-| `MODEL_CONVERT_FORMAT` | `glb` | 需要转换的模型(PMX/FBX)的交付格式:`glb`(两个客户端都原生加载)或 `vrm`。`vrm` = 在 GLB 之上补 `VRMC_vrm` 扩展(humanoid 骨骼 / 表情语义),humanoid 骨骼映射不全时自动回退交付 GLB 并写进 `conversion_note`。产物一律用 `assimp info` 回读校验 |
+| `MODEL_CONVERT_FORMAT` | `vrm` | 需要转换的模型(PMX/FBX)的交付格式:`glb`(两个客户端都原生加载)或 `vrm`。`vrm` = 在 GLB 之上补 `VRMC_vrm` 扩展(humanoid 骨骼 / 表情语义),humanoid 骨骼映射不全时自动回退交付 GLB 并写进 `conversion_note`。产物一律用 `assimp info` 回读校验 |
 | `MODEL_CONVERT_PMX` | `"Hatsune Miku.pmx"` | 压缩包内优先选用的 PMX 文件名(大小写不敏感);找不到时按「格式优先级 -> 目录最浅 -> 文件最大」挑选 |
 | `MODEL_SHADING` | `pbr` | 转换后模型的着色模式。`pbr`:标准 PBR,并按 PMX 参数修正 `doubleSided` / `metallic` / `roughness`;`unlit`:写 `KHR_materials_unlit`,颜色 = 贴图 x `baseColorFactor`、与场景光照无关,最接近 MMD 的平涂观感 |
 | `MODEL_CONVERT_TIMEOUT_MS` | `180000` | 单次转换超时(毫秒) |
@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.2.5  使用说明
+OpenDance Studio -- Web 管理服务端 v0.5.0  使用说明
 ================================================================

 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,41 @@ OpenDance Studio -- Web 管理服务端 v0.2.5  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。

+v0.5.0 修订 - 动作预览(契约 data-models -> 0.6.0)
+  1. 动作骨架缩略图(服务端): motion-thumbnail.ts 把关键点序列画成正视图骨架 PNG,
+     随 /preprocess 生成并落库(motions.thumbnail_asset_id, 迁移 AddMotionThumbnail),
+     失败只记 warning 不影响预处理。
+  2. 动作 3D 回放(管理端, 重要): 新增 MotionPreview - 懒加载 NDJSON -> 骨架线框 +
+     关节球体, 支持播放/暂停、上一帧/下一帧、时间轴拖动、0.25x-2x 变速、循环,
+     叠加帧号/时间/总时长; three.js 单独分包, 主包体积不涨。
+  3. 动作管理列表新增 40px 骨架缩略图列(点击预览)与「预览」按钮。
+  4. 新增 8 项测试; 规模 18 文件 / 237 项。
+
+v0.4.0 修订 - 骨骼重绑定(契约 skeleton-topology -> 0.2.0)
+  1. 修复 humanoid 覆盖率恒为 0/22 的根因: normalizeBoneName() 原先只保留 a-z0-9,
+     中日文字符被整个丢掉(上半身/左ひじ/首 全变空串)。现在保留 CJK/假名,
+     并把全角 ASCII(足ＩＫ)折成半角。
+  2. 候选表补齐四类命名: VRoid / Mixamo / MMD 标准骨架(下半身/上半身/上半身2/
+     首/頭/左肩/左腕/左ひじ/左手首/左足/左ひざ/左足首/左つま先)/ 常见中文名;
+     精确匹配保证 左足ＩＫ 不会抢占 左足。
+  3. 服务端与 Windows 客户端逐字一致: humanoid_map.gd 的 CANDIDATES 由服务端表
+     生成写入, normalize() 同步改造(parity 测试断言)。
+  4. 实测: 奥黛塔 PMX 0/22 -> 21/22、初音未来 PMX 0/22 -> 19/22, 均 drivable=true
+     并产出 VRM(此前只能回退 GLB 并标记不可用)。
+  5. 契约 skeleton-topology -> 0.2.0: 新增第 6 节"内部动作标准与模型骨骼重绑定"。
+  6. 新增 4 项测试; 规模 17 文件 / 229 项。
+
+v0.3.0 修订 - VRM 主力化(契约 data-models / model-formats -> 0.5.0)
+  1. 所有上传的模型一律转 VRM: MODEL_CONVERT_FORMAT 默认改为 vrm -
+     .pmx/.fbx 经 assimp -> GLB -> VRM 1.0, glb/gltf 导入后包装为 VRM。
+  2. humanoid 门槛与可用性标记(usable): 必需骨齐全才产出 VRM; 不达标
+     (如 MMD 日文骨名 0/22)时回退交付 GLB、usable=false - 可入库、可审核,
+     但不进入 catalog/export(指纹同步过滤); 待骨骼重绑定后重新导入即转为可用。
+  3. 模型列表与审核面板显示"不可用"及原因; 默认模型只在可用模型中选择。
+  4. 管理端左下角展示当前版本号(构建期从 web-server/package.json 注入,
+     与 GET /health 的 version 同源)。
+  5. 新增 5 项测试; 规模 16 文件 / 225 项。
+
 v0.2.5 修订 - MMD 材质/着色对齐
  PMX 的着色模型(卡通阶梯 + 球面贴图 + 平坦环境光)与 glTF PBR 不是一回事,
  Assimp 转换会丢东西。实测样本 【奥黛塔】_by_原神.zip(39 个材质):
@@ -90,11 +125,11 @@ v0.2.1 修订
   2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
        本项目不会创建数据库本身
   3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.2.5.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.5.0.tar.gz
        curl -LO https://<制品库地址>/SHA256SUMS
        sha256sum -c SHA256SUMS      # 期望输出 "OK"
   4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
-        tar -xzf opendance-web-v0.2.5.tar.gz && cd opendance-web-v0.2.5
+        tar -xzf opendance-web-v0.5.0.tar.gz && cd opendance-web-v0.5.0
        bash deploy/init-env.sh
   5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
        bash deploy/install.sh
@@ -152,8 +187,8 @@ v0.2.1 修订
  (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)

 部署步骤
-  tar -xzf opendance-web-v0.2.5.tar.gz
-  cd opendance-web-v0.2.5
+  tar -xzf opendance-web-v0.5.0.tar.gz
+  cd opendance-web-v0.5.0
  bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
  bash deploy/install.sh          # 已以 root 登录, 不需要 sudo

@@ -328,12 +363,12 @@ deploy/.env 初始化引导(deploy/init-env.sh)
  cd web-server
  npm run contracts:check   # 契约版本一致性
  npm run typecheck         # TypeScript 严格检查
-  npm run test              # 220 项单元测试 / 15 个文件(VMD 31、模型压缩包 24、
+  npm run test              # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 24、
                            #   模型检查器 25、缩略图 8、骨骼过滤 8、
                            #   预处理 25、init-env 16、admin-port 16、
                            #   access-log 9、VRM 检查器 6、.env 预检 12、
                            #   Assimp 定位与安装 13、stats 容量与编码 12、缩略图贴图 6、
-                            #   MMD 材质对齐 9)
+                            #   MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8)
  npm run build             # 生产构建
  npm run start:prod &      # 启动
  npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -2,7 +2,7 @@
 # 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
 rest-api: 0.4.0
 websocket-keypoints: 0.1.0
-data-models: 0.4.0
-skeleton-topology: 0.1.0
-model-formats: 0.4.0
+data-models: 0.6.0
+skeleton-topology: 0.2.0
+model-formats: 0.5.0
 database: 0.3.0
@@ -1,4 +1,4 @@
-# contracts/data-models.md - 数据模型契约 v0.4.0
+# contracts/data-models.md - 数据模型契约 v0.5.0

 Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视图**。
 字段名在 JSON 中统一 `camelCase`；数据库列名 `snake_case`（见 `database.md`）。
@@ -83,6 +83,7 @@ rejected   已驳回
 | `durationMs` | number\|null | | |
 | `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
 | `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或.npz 的 JSON 封装） |
+| `thumbnailUrl` | string\|null | 读 | 骨架缩略图（`/preprocess` 时生成，动作管理列表展示；未生成时为 null）(v0.6.0) |
 | `keypointFrames` | number\|null | 读 | 关键点帧数 |
 | `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
 | `preprocessError` | string\|null | 读 | |
@@ -96,8 +97,10 @@ rejected   已驳回
 |--|--|--|--|
 | `id` | number | 读 | |
 | `name` | string | ✅ | 模型名称，<=200 |
-| `format` | enum | ✅ | `glb` / `vrm`（主力）/ `gltf` / `fbx`（历史数据）。上传的 PMX/FBX 会被服务端转换成 glb 或 vrm 再入库，见 model-formats.md 1.1 |
+| `format` | enum | ✅ | `vrm`（主力）/ `glb`（回退或历史数据）/ `gltf` / `fbx`。**所有上传模型一律转换为 VRM**，只有 humanoid 不达标时回退为 `glb` 并置 `usable=false`，见 model-formats.md 1.1 |
 | `vrmVersion` | string\|null | 读 | `0.x` / `1.0`，非 VRM 为 null |
+| `usable` | boolean | 读 | **是否可被客户端使用**：等价于"已产出 VRM"(`format=vrm`)。`false` 的模型**不出现在 `catalog/export`**(v0.5.0) |
+| `unusableReason` | string\|null | 读 | `usable=false` 时的原因，例如 `humanoid 不达标（0/22），未产出 VRM` |
 | `isPrimary` | boolean | | 全局默认模型；**同一时刻全库至多一个 `true`** |
 | `fileUrl` | string | 读 | |
 | `fileSize` | number | 读 | |
@@ -1,20 +1,41 @@
-# contracts/model-formats.md - 模型与动作格式契约 v0.4.0
+# contracts/model-formats.md - 模型与动作格式契约 v0.5.0

 ## 1. 角色模型(models)

-**系统以 GLB / VRM 为主力格式**（两个客户端都原生加载），其余格式一律在服务端转换。
+**v0.5.0 起模型主力格式为 VRM**: **所有上传的模型都转换为 VRM**(`MODEL_CONVERT_FORMAT`
+默认 `vrm`）；GLB 退为**转换中间产物**与 **humanoid 不达标时的回退交付**。
+两个客户端（Godot `godot-vrm` / 管理端 `@pixiv/three-vrm`）都原生加载 VRM。

 | 格式 | 扩展名 | 支持级别 | 服务端行为 |
 |--|--|--|--|
-| glTF Binary | `.glb` | **主力(P0)** | **直接导入**，不重编码 |
 | VRM | `.vrm` | **主力(P0)** | **直接导入**; = GLB + VRM 扩展(humanoid / 表情 / springBone / meta) |
+| glTF Binary | `.glb` | 输入(P0) | 导入后**包装为 VRM**（含 `VRMC_vrm`）；humanoid 不齐时保留 GLB 并标记 `usable=false` |
 | glTF | `.gltf` (+ `.bin`, 贴图) | P1 | 直接导入(分离文件在 zip 内可用；单文件上传会缺.bin) |
 | MMD 压缩包 | `.zip` | P1 | **自动搜索包内可用模型**：优先直接导入 `.vrm`/`.glb`/`.gltf`，否则转换 `.pmx`/`.fbx`，见 1.1 |
-| MMD 模型 | `.pmx` | P2（输入） | 服务端转换（优先 GLB、其次 VRM）；单文件上传无贴图 |
-| FBX | `.fbx` | P2（输入） | 服务端转换(优先 GLB、其次 VRM) |
+| MMD 模型 | `.pmx` | P2（输入） | 服务端转换：`assimp -> GLB -> VRM`；单文件上传无贴图 |
+| FBX | `.fbx` | P2（输入） | 服务端转换：`assimp -> GLB -> VRM` |

 ### 1.1 上传与转换策略

+**v0.5.0 起的一律转换链路**:
+
+```
+.vrm            -> 直接导入(已是 VRM)
+.glb / .gltf    -> 包装为 VRM 1.0(写 VRMC_vrm)
+.pmx / .fbx     -> assimp -> GLB -> 包装为 VRM 1.0
+.zip            -> 自动搜索包内模型，按上面三种处理
+```
+
+**humanoid 门槛（硬性）**: VRM 1.0 要求 humanoid 必需骨骼齐全。服务端判定规则：
+
+| 情况 | 交付 | `models.usable` | 是否进入客户端目录 |
+|--|--|--|--|
+| humanoid 必需骨齐全 | **VRM**(`format=vrm`, `vrmVersion=1.0`) | `true` | ✅ 可发布、可选用 |
+| humanoid 不齐（如 MMD 日文骨名未重绑定） | 回退交付 **GLB**, `vrmVersion=null`, `conversionNote` 注明原因 | `false` | ❌ 不进入 `catalog/export` |
+
+即：**不达标模型仍可入库与审核，但标记为不可用、不进入已发布目录**;
+待骨骼按 `skeleton-topology.md` 的标准重绑定成功后重新转换即变为可用。
+
 **`.glb` / `.vrm` / `.gltf` 直接导入**（不重编码，零损失）；**`.pmx` / `.fbx` 由服务端转换**:
 **优先 GLB，其次 VRM**。

@@ -1,4 +1,4 @@
-# contracts/skeleton-topology.md - 骨骼拓扑契约 v0.1.0
+# contracts/skeleton-topology.md - 骨骼拓扑契约 v0.2.0

 **唯一拓扑：MediaPipe Pose 33 点。禁止引入 SMPL 及其衍生拓扑（许可风险）。**

@@ -123,3 +123,65 @@ spine      = angle(neck, pelvis, midpoint(left_ankle, right_ankle))

 **DTW 序列结构（冻结）**：每帧 = `[33 x (x, y, z), 9 个关节角余弦] = 108 维`。
 低置信度点（`visibility < 0.5`）在插值阶段由相邻帧线性补全，不参与代价计算。
+
+
+---
+
+## 6. 内部动作标准与模型骨骼重绑定(v0.2.0)
+
+**目的**：动作数据必须能匹配系统内的任意模型，因此把"关键点标准 + 骨架标准 + humanoid 标准"
+冻结成本节，模型上传时按此**重绑定骨骼**，再包装为 VRM。
+
+### 6.1 三层标准
+
+| 层 | 标准 | 权威实现 |
+|--|--|--|
+| 关键点 | MediaPipe Pose **33 点**（顺序见 §1），动作一律先转成关键点序列（NDJSON）再入库 | `preprocess/`(BVH / VMD / FBX -> 33 点) |
+| 动作骨架 | **MMD 标准骨架**(静止比例实测自参考 PMX; `足ＩＫ` 带位移时走两骨骼腿部 IK，否则 FK) | `preprocess/mmd-skeleton.ts` |
+| 模型骨架 | **22 根 humanoid 规范骨**（顺序即层级，父在前），其中 **16 根为必需**(§6.2) | `models/model-inspector.ts` 的 `HUMANOID_CANDIDATES` |
+
+评分只依赖 33 点关键点序列，**与模型骨架解耦**；因此"动作能匹配任何模型"的充要条件是
+**模型可驱动**(16 根必需骨齐全，`drivable=true`)。
+
+### 6.2 22 根 humanoid 规范骨与 16 根必需骨
+
+```
+hips -> spine -> chest -> upperChest -> neck -> head
+                  ├── leftShoulder  -> leftUpperArm  -> leftLowerArm  -> leftHand
+                  └── rightShoulder -> rightUpperArm -> rightLowerArm -> rightHand
+hips -> leftUpperLeg  -> leftLowerLeg  -> leftFoot  -> leftToes
+hips -> rightUpperLeg -> rightLowerLeg -> rightFoot -> rightToes
+```
+
+必需 16 根（缺一即 `drivable=false`）：`hips`、`spine`、`neck`、`head`、
+`leftUpperArm`、`leftLowerArm`、`leftHand`、`rightUpperArm`、`rightLowerArm`、`rightHand`、
+`leftUpperLeg`、`leftLowerLeg`、`leftFoot`、`rightUpperLeg`、`rightLowerLeg`、`rightFoot`。
+
+### 6.3 重绑定规则（模型上传时执行，服务端与三端一致）
+
+1. **归一化**：小写 → 只保留 `a-z0-9` + **中文/日文（CJK、平假名、片假名、长音符、々）**;
+   **全角 ASCII（Ａ-Ｚ ａ-ｚ ０-９）折成半角**(MMD 常写「足ＩＫ」「つま先ＩＫ」)。
+   *v0.2.0 修正*：此前只保留 `a-z0-9`, MMD 骨名（`上半身`/`左ひじ`/`首`）被归一化成空串，
+   humanoid 覆盖率恒为 **0/22**。
+2. **剥前缀**：只剥 `J_Bip` / `mixamorig` / `Bip01`; **不剥** `J_Aim_` / `J_Roll_` / `J_Sec_`
+   (VRoid 的扭转辅助骨，剥了会与真正的骨骼撞名)。
+3. **变体**: `left/right` 与 `l/r` 互转（`leftupperarm` <-> `lupperarm`）。
+4. **精确匹配**：归一化+变体后的名字必须与候选表**完全相等**（前缀不匹配），
+   因此 `左足ＩＫ`(-> `左足ik`)不会抢占 `左足`(`leftUpperLeg`)。
+5. **候选表覆盖四类命名**（顺序即优先级；服务端与客户端**逐字一致**，由测试断言）：
+   VRoid(`J_Bip_C_Hips` 等)、Mixamo(`mixamorig:LeftArm`)、
+   **MMD 标准骨架(`下半身`/`上半身`/`上半身2`/`首`/`頭`/`左肩`/`左腕`/`左ひじ`/`左手首`/`左足`/`左ひざ`/`左足首`/`左つま先`)**、
+   常见中文名（`臀部`/`头`/`脖子`/`左大臂`/`左小臂`/`左大腿`/`左脚` 等）。
+6. **结果写入 VRM**：命中结果写成 `VRMC_vrm.humanoid.humanBones` 的**节点索引**(VRM 规范
+   不要求节点名固定，因此以索引为准，不改动几何与贴图）；未命中的骨骼保留原名作为附加骨。
+7. **结论必须上报**: `models.stats.humanoidMapped` / `humanoidTotal` / `missingRequiredBones` /
+   `drivable` 四项写库，审核界面展示；`usable` 与是否进入客户端目录见 model-formats.md 1.1。
+
+### 6.4 实测（v0.2.0 重绑定后）
+
+| 样本 | 重绑定前 | 重绑定后 | 结果 |
+|--|--|--|--|
+| `【奥黛塔】_by_原神.zip`(PMX，日文骨名) | 0/22，不可驱动 | **21/22, drivable=true** | 交付 **VRM** |
+| `模型_初音未来Hatsune Miku_by_Boku_Wa_Luka.zip`(PMX) | 0/22，不可驱动 | **19/22, drivable=true** | 交付 **VRM** |
+
+未命中的 1-3 根均为非必需骨（如 `upperChest` / `leftToes`），不影响驱动与评分。
@@ -44,11 +44,11 @@ UPLOAD_MAX_BYTES=536870912
 # ---- 可选的 Assimp（FBX/glTF 动作预处理；也用于压缩包模型的转换）----
 # 上传 .zip（内含 .pmx 的 MMD 模型包）时必须能调用到它，否则转换会失败
 ASSIMP_BIN=assimp
-# 需要转换的模型（PMX / FBX）交付格式：glb（默认，两个客户端都原生加载）| vrm
-#   glb：通用，客户端直接加载
-#   vrm：在 GLB 之上补 VRMC_vrm 扩展（humanoid 骨骼 / 表情语义）；
-#        humanoid 骨骼名映射不全时会自动回退交付 GLB 并写进 conversion_note
-MODEL_CONVERT_FORMAT=glb
+# 模型交付格式：vrm（默认，v0.5.0 起所有上传模型一律转 VRM）| glb
+#   vrm：在 GLB 之上补 VRMC_vrm 扩展（humanoid 骨骼 / 表情语义）
+#   glb：仅作为转换中间产物；humanoid 不达标时会回退交付 GLB，
+#        该模型 usable=false（可入库可审核，但不进入客户端目录）
+MODEL_CONVERT_FORMAT=vrm
 # 压缩包里优先选用的 PMX 文件名（大小写不敏感）；找不到时按"格式优先级 -> 目录最浅 -> 文件最大"挑
 # 值里含空格或 shell 元字符时必须用引号包起来（install.sh 会用
 # `set -a; . deploy/.env` 真的执行本文件；不加引号会把 "Miku.pmx" 当命令）
@@ -1,5 +1,5 @@
 project: opendance-web-server
-version: 0.2.5
+version: 0.5.0
 repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0
@@ -60,13 +60,13 @@ tasks:
    status: done

 deliverable:
-  artifact: opendance-web-v0.2.5.tar.gz
+  artifact: opendance-web-v0.5.0.tar.gz
  packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
  includes:
    - web-server/          # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）
    - admin/               # React 管理端构建产物
    - deploy/              # install.sh / init-env.sh / systemd / openrc / initd / ctl.sh / .env.example（PORT、ADMIN_PORT、HOST）
    - deploy/proxy/        # 反向代理说明（nginx / IIS，仅供参考不部署）
-    - contracts/           # 当前版本契约快照（0.4.0）
+    - contracts/           # 当前版本契约快照（data-models 0.6.0）
    - THIRD_PARTY.md       # 开源声明
    - README.txt           # 使用说明
@@ -1,6 +1,6 @@
 #!/bin/bash
 # ============================================================
-# 打包发布产物：opendance-web-v0.2.5.tar.gz
+# 打包发布产物：opendance-web-v0.5.0.tar.gz
 #
 # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
 #   web-server/      NestJS 源码 + 构建产物
@@ -21,7 +21,7 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"

-VERSION="${1:-0.2.5}"
+VERSION="${1:-0.5.0}"
 NAME="opendance-web-v${VERSION}"
 OUT_DIR="$REPO_ROOT/dist-release"
 STAGE="$OUT_DIR/$NAME"
@@ -160,7 +160,7 @@ node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-ru

 ```bash
 cd web-server
-npx vitest run        # 15 个文件 / 220 项通过
+npx vitest run        # 17 个文件 / 229 项通过
 npm run test:smoke    # 冒烟 [4] 段落
 ```

@@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published

 ```bash
 cd web-server
-npx vitest run        # 15 个文件 / 220 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项、缩略图贴图 6 项、MMD 材质对齐 9 项）
+npx vitest run        # 17 个文件 / 229 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项、缩略图贴图 6 项、MMD 材质对齐 9 项、模型可用性 5 项、MMD 骨名重绑定 4 项）
 npm run test:smoke
 ```

@@ -1,7 +1,7 @@
 {
  "name": "opendance-admin",
  "private": true,
-  "version": "0.2.5",
+  "version": "0.5.0",
  "type": "module",
  "description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
  "scripts": {
@@ -102,6 +102,8 @@ export interface Motion extends SourceFields {
  durationMs: number | null;
  keypointFormat: string | null;
  keypointUrl: string | null;
+  /** 骨架缩略图（预处理时生成；T-WEB-014） */
+  thumbnailUrl: string | null;
  keypointFrames: number | null;
  preprocessState: PreprocessState;
  preprocessError: string | null;
@@ -160,6 +162,10 @@ export interface Model extends SourceFields {
  name: string;
  format: ModelFormat;
  vrmVersion: string | null;
+  /** 是否可用于客户端（= 已产出 VRM）；false 的模型不进入客户端目录（v0.5.0） */
+  usable: boolean;
+  /** usable=false 的原因，例如「humanoid 不达标（0/22），未产出 VRM」 */
+  unusableReason: string | null;
  isPrimary: boolean;
  fileUrl: string | null;
  fileSize: number | null;
@@ -1,5 +1,7 @@
 import { NavLink, Outlet } from 'react-router-dom';

+import { APP_VERSION_LABEL } from '../lib/version';
+
 interface NavItem {
  to: string;
  label: string;
@@ -44,9 +46,13 @@ export function Layout() {
          ))}
        </nav>
        <div className="sidebar-foot">
+          {/* 当前版本号：左下角固定展示，来源 web-server/package.json（与 /health 同源） */}
+          <span className="app-version" title="当前版本号">
+            {APP_VERSION_LABEL}
+          </span>
          <span>API 基址</span>
          <code>{API_BASE === '' ? '同源（dev proxy / nginx）' : API_BASE}</code>
-          <span className="muted">契约 rest-api 0.1.0</span>
+          <span className="muted">契约版本见「概览」页</span>
        </div>
      </aside>
      <main className="content">
@@ -203,6 +203,17 @@ function ModelStatsView({ model, stats }: { model: Model; stats: ModelStats }) {
        <Metric label="骨骼最大层级" value={formatCount(stats.maxBoneDepth)} />
      </div>

+      {/* 可用性门槛（v0.5.0）：未产出 VRM 的模型不进入客户端目录 */}
+      {!model.usable ? (
+        <div className="banner banner-danger" role="alert">
+          <strong>不可用：该模型不会进入客户端目录</strong>
+          <span>{model.unusableReason ?? '未产出 VRM'}</span>
+          <span className="muted">
+            依据契约 model-formats 1.1，所有模型一律转 VRM；humanoid 必需骨齐全后重新导入即可转为可用。
+          </span>
+        </div>
+      ) : null}
+
      {/* 可驱动性结论 */}
      <div className={`banner ${BANNER_CLASS[drivable.kind]}`} role={drivable.kind === 'error' ? 'alert' : 'status'}>
        <strong>
@@ -0,0 +1,370 @@
+/**
+ * 动作预览：关键点序列 3D 回放（T-WEB-014）。
+ *
+ * 只用 three.js 的核心能力（LineSegments + InstancedMesh），不依赖 three-vrm：
+ *   * 骨架：按 `skeleton-topology.ts` 的骨段建 LineSegments，逐帧写 position；
+ *   * 关节：InstancedMesh 球体，逐帧写实例矩阵（低置信度点缩放为 0 隐藏）；
+ *   * 交互：播放 / 暂停 / 逐帧 / 时间轴拖动 / 变速 / 循环；
+ *   * 数据：`GET /api/motions/:id/keypoints`（NDJSON，懒加载，切换动作时取消旧请求）。
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import * as THREE from 'three';
+
+import { apiUrl } from '../api/client';
+import {
+  BONE_SEGMENTS,
+  FACE_POINT_LIMIT,
+  KEYPOINT_NAMES,
+  VIRTUAL_PELVIS,
+  VIRTUAL_SHOULDER_CENTER,
+} from '../lib/skeleton-topology';
+import { type ParsedKeypointSequence, parseKeypointNdjson, sequenceBounds } from '../lib/keypoint-sequence';
+import { useAsync } from '../lib/useAsync';
+import { ErrorBox, Loading } from './ui';
+
+const SPEEDS = [0.25, 0.5, 1, 2] as const;
+const MIN_VISIBILITY = 0.3;
+
+interface MotionPreviewProps {
+  motionId: number;
+  /** 画布高度（px） */
+  height?: number;
+}
+
+/** 把预览需要的骨架几何一次性建好，之后每帧只更新 buffer */
+function buildSkeletonObject(): {
+  group: THREE.Group;
+  bones: THREE.LineSegments;
+  joints: THREE.InstancedMesh;
+  /** 每个关节实例对应的关键点索引 */
+  jointIndices: number[];
+} {
+  const group = new THREE.Group();
+
+  // 只画身体骨段（面部五官太密，缩略图/预览都不画）
+  const segments = BONE_SEGMENTS.filter(
+    ([child, parent]) => child >= FACE_POINT_LIMIT && parent >= FACE_POINT_LIMIT,
+  );
+  const bonePositions = new Float32Array(segments.length * 2 * 3);
+  const boneGeometry = new THREE.BufferGeometry();
+  boneGeometry.setAttribute('position', new THREE.BufferAttribute(bonePositions, 3));
+  const bones = new THREE.LineSegments(
+    boneGeometry,
+    new THREE.LineBasicMaterial({ color: 0x60a5fa, linewidth: 2 }),
+  );
+  bones.frustumCulled = false;
+  group.add(bones);
+
+  const jointIndices: number[] = [];
+  for (let index = FACE_POINT_LIMIT; index < KEYPOINT_NAMES.length; index += 1) jointIndices.push(index);
+  const jointGeometry = new THREE.SphereGeometry(0.035, 10, 8);
+  const jointMaterial = new THREE.MeshStandardMaterial({ color: 0xf8fafc, roughness: 0.6, metalness: 0 });
+  const joints = new THREE.InstancedMesh(jointGeometry, jointMaterial, jointIndices.length);
+  joints.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+  joints.frustumCulled = false;
+  group.add(joints);
+
+  return { group, bones, joints, jointIndices };
+}
+
+export function MotionPreview({ motionId, height = 360 }: MotionPreviewProps): JSX.Element {
+  const mountRef = useRef<HTMLDivElement | null>(null);
+  const sequenceRef = useRef<ParsedKeypointSequence | null>(null);
+  const cursorRef = useRef(0);
+  const playingRef = useRef(true);
+  const speedRef = useRef(1);
+  const loopRef = useRef(true);
+  const [playing, setPlaying] = useState(true);
+  const [speed, setSpeed] = useState(1);
+  const [loop, setLoop] = useState(true);
+  const [cursor, setCursor] = useState(0);
+
+  const state = useAsync(
+    () =>
+      fetch(apiUrl(`/api/motions/${motionId}/keypoints`))
+        .then((response) => {
+          if (!response.ok) throw new Error(`关键点下载失败：HTTP ${response.status}`);
+          return response.text();
+        })
+        .then((text) => parseKeypointNdjson(text)),
+    [motionId],
+  );
+
+  const summary = useMemo(() => {
+    if (!state.data) return null;
+    const { frames, frameIntervalMs } = state.data;
+    if (frames.length === 0) return null;
+    return { count: frames.length, interval: frameIntervalMs };
+  }, [state]);
+
+  useEffect(() => {
+    sequenceRef.current = state.data ?? null;
+    cursorRef.current = 0;
+    setCursor(0);
+  }, [state]);
+
+  useEffect(() => {
+    playingRef.current = playing;
+  }, [playing]);
+  useEffect(() => {
+    speedRef.current = speed;
+  }, [speed]);
+  useEffect(() => {
+    loopRef.current = loop;
+  }, [loop]);
+
+  useEffect(() => {
+    const mount = mountRef.current;
+    if (!mount) return;
+    const width = Math.max(1, mount.clientWidth);
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x181a20);
+    const camera = new THREE.PerspectiveCamera(38, width / height, 0.01, 100);
+    const renderer = new THREE.WebGLRenderer({ antialias: true });
+    renderer.setPixelRatio(Math.min(2, window.devicePixelRatio || 1));
+    renderer.setSize(width, height, false);
+    mount.appendChild(renderer.domElement);
+    scene.add(new THREE.AmbientLight(0xffffff, 1.1));
+    const key = new THREE.DirectionalLight(0xffffff, 1.6);
+    key.position.set(1, 2, 2);
+    scene.add(key);
+    const rim = new THREE.DirectionalLight(0x88bbff, 0.8);
+    rim.position.set(-1.5, 1, -1.5);
+    scene.add(rim);
+
+    const { group, bones, joints, jointIndices } = buildSkeletonObject();
+    scene.add(group);
+
+    // 网格地面（帮助判断朝向与高度）
+    const grid = new THREE.GridHelper(4, 8, 0x334155, 0x1f2937);
+    grid.position.y = -1;
+    scene.add(grid);
+
+    const resize = (): void => {
+      const nextWidth = Math.max(1, mount.clientWidth);
+      camera.aspect = nextWidth / height;
+      camera.updateProjectionMatrix();
+      renderer.setSize(nextWidth, height, false);
+    };
+    const observer = new ResizeObserver(resize);
+    observer.observe(mount);
+
+    const clock = new THREE.Clock();
+    let raf = 0;
+    let elapsed = 0;
+    let lastRendered = -1;
+
+    const applyFrame = (sequence: ParsedKeypointSequence, index: number): void => {
+      const frame = sequence.frames[Math.min(sequence.frames.length - 1, Math.max(0, index))];
+      if (!frame) return;
+      const { positions, visibility } = frame;
+
+      // 骨段：虚拟关节用实际点替代（骨盆=左右髋中点，肩中心=左右肩中点）
+      const pointAt = (index2: number, out: THREE.Vector3): THREE.Vector3 => {
+        if (index2 === VIRTUAL_PELVIS) {
+          out.set(
+            (positions[23 * 3] + positions[24 * 3]) / 2,
+            (positions[23 * 3 + 1] + positions[24 * 3 + 1]) / 2,
+            (positions[23 * 3 + 2] + positions[24 * 3 + 2]) / 2,
+          );
+          return out;
+        }
+        if (index2 === VIRTUAL_SHOULDER_CENTER) {
+          out.set(
+            (positions[11 * 3] + positions[12 * 3]) / 2,
+            (positions[11 * 3 + 1] + positions[12 * 3 + 1]) / 2,
+            (positions[11 * 3 + 2] + positions[12 * 3 + 2]) / 2,
+          );
+          return out;
+        }
+        out.set(positions[index2 * 3], positions[index2 * 3 + 1], positions[index2 * 3 + 2]);
+        return out;
+      };
+
+      const attr = bones.geometry.getAttribute('position') as THREE.BufferAttribute;
+      const array = attr.array as Float32Array;
+      const scratchA = new THREE.Vector3();
+      const scratchB = new THREE.Vector3();
+      const segments = BONE_SEGMENTS.filter(
+        ([child, parent]) => child >= FACE_POINT_LIMIT && parent >= FACE_POINT_LIMIT,
+      );
+      for (let index2 = 0; index2 < segments.length; index2 += 1) {
+        const [child, parent] = segments[index2];
+        pointAt(child, scratchA);
+        pointAt(parent, scratchB);
+        array[index2 * 6] = scratchA.x;
+        array[index2 * 6 + 1] = scratchA.y;
+        array[index2 * 6 + 2] = scratchA.z;
+        array[index2 * 6 + 3] = scratchB.x;
+        array[index2 * 6 + 4] = scratchB.y;
+        array[index2 * 6 + 5] = scratchB.z;
+      }
+      attr.needsUpdate = true;
+
+      const matrix = new THREE.Matrix4();
+      const scale = new THREE.Vector3();
+      const zero = new THREE.Vector3(0, 0, 0);
+      const position = new THREE.Vector3();
+      const quaternion = new THREE.Quaternion();
+      for (let slot = 0; slot < jointIndices.length; slot += 1) {
+        const pointIndex = jointIndices[slot];
+        const visible = visibility[pointIndex] >= MIN_VISIBILITY;
+        position.set(
+          positions[pointIndex * 3],
+          positions[pointIndex * 3 + 1],
+          positions[pointIndex * 3 + 2],
+        );
+        scale.setScalar(visible ? 1 : 0);
+        if (!visible) position.copy(zero);
+        matrix.compose(position, quaternion, scale);
+        joints.setMatrixAt(slot, matrix);
+      }
+      joints.instanceMatrix.needsUpdate = true;
+    };
+
+    const tick = (): void => {
+      raf = requestAnimationFrame(tick);
+      const delta = clock.getDelta();
+      const sequence = sequenceRef.current;
+      if (sequence && sequence.frames.length > 0) {
+        if (playingRef.current) {
+          elapsed += delta * 1000 * speedRef.current;
+          const step = sequence.frameIntervalMs > 0 ? sequence.frameIntervalMs : 1000 / 30;
+          let next = cursorRef.current + elapsed / step;
+          elapsed = 0;
+          if (next >= sequence.frames.length) {
+            if (loopRef.current) {
+              next %= sequence.frames.length;
+            } else {
+              next = sequence.frames.length - 1;
+              playingRef.current = false;
+              setPlaying(false);
+            }
+          }
+          cursorRef.current = next;
+          const integer = Math.floor(next);
+          if (integer !== lastRendered) {
+            lastRendered = integer;
+            setCursor(integer);
+          }
+        }
+        applyFrame(sequence, Math.floor(cursorRef.current));
+
+        // 相机跟随包围盒（取整段包围盒，避免逐帧抖动）
+        if (sequence.frames.length > 0 && !mount.dataset.framed) {
+          const bounds = sequenceBounds(sequence.frames);
+          if (bounds) {
+            const center = new THREE.Vector3(
+              (bounds.min[0] + bounds.max[0]) / 2,
+              (bounds.min[1] + bounds.max[1]) / 2,
+              (bounds.min[2] + bounds.max[2]) / 2,
+            );
+            const size = Math.max(
+              bounds.max[0] - bounds.min[0],
+              bounds.max[1] - bounds.min[1],
+              bounds.max[2] - bounds.min[2],
+              0.5,
+            );
+            group.position.set(-center.x, -center.y, -center.z);
+            camera.position.set(0.6 * size, 0.7 * size, 2.6 * size);
+            camera.lookAt(0, 0, 0);
+            mount.dataset.framed = '1';
+          }
+        }
+      }
+      renderer.render(scene, camera);
+    };
+    raf = requestAnimationFrame(tick);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      observer.disconnect();
+      renderer.dispose();
+      bones.geometry.dispose();
+      (bones.material as THREE.Material).dispose();
+      joints.geometry.dispose();
+      (joints.material as THREE.Material).dispose();
+      if (renderer.domElement.parentNode === mount) mount.removeChild(renderer.domElement);
+      delete mount.dataset.framed;
+    };
+  }, [height, motionId]);
+
+  if (state.loading) return <Loading text="正在加载关键点序列…" />;
+  if (state.error) {
+    return <ErrorBox message={state.error} onRetry={state.reload} />;
+  }
+  if (!summary) {
+    return (
+      <div className="banner banner-warn" role="status">
+        <strong>该动作还没有关键点序列</strong>
+        <span>先执行「预处理」（POST /api/motions/:id/preprocess）后再预览。</span>
+      </div>
+    );
+  }
+
+  const total = summary.count;
+  const currentTimeMs = Math.round((cursor * summary.interval) / 1000 * 1000) / 1000;
+
+  return (
+    <div className="motion-preview">
+      <div className="motion-preview-canvas" ref={mountRef} style={{ height }} />
+      <div className="motion-preview-bar">
+        <button type="button" className="btn btn-ghost" onClick={() => setPlaying((value) => !value)}>
+          {playing ? '暂停' : '播放'}
+        </button>
+        <button
+          type="button"
+          className="btn btn-ghost"
+          onClick={() => {
+            setPlaying(false);
+            cursorRef.current = Math.max(0, Math.floor(cursorRef.current) - 1);
+            setCursor(Math.floor(cursorRef.current));
+          }}
+        >
+          上一帧
+        </button>
+        <button
+          type="button"
+          className="btn btn-ghost"
+          onClick={() => {
+            setPlaying(false);
+            cursorRef.current = Math.min(total - 1, Math.floor(cursorRef.current) + 1);
+            setCursor(Math.floor(cursorRef.current));
+          }}
+        >
+          下一帧
+        </button>
+        <input
+          type="range"
+          min={0}
+          max={Math.max(0, total - 1)}
+          value={cursor}
+          onChange={(event) => {
+            setPlaying(false);
+            const next = Number(event.target.value);
+            cursorRef.current = next;
+            setCursor(next);
+          }}
+          aria-label="时间轴"
+        />
+        <span className="mono small">
+          第 {cursor + 1}/{total} 帧 · {currentTimeMs.toFixed(2)}s · {(total * summary.interval / 1000).toFixed(2)}s
+        </span>
+        <label className="motion-preview-speed">
+          速度
+          <select value={speed} onChange={(event) => setSpeed(Number(event.target.value))}>
+            {SPEEDS.map((value) => (
+              <option key={value} value={value}>
+                {value}x
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="motion-preview-speed">
+          <input type="checkbox" checked={loop} onChange={(event) => setLoop(event.target.checked)} />
+          循环
+        </label>
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,117 @@
+/**
+ * 关键点序列（NDJSON）解析与回放辅助（T-WEB-014）。
+ *
+ * 数据来源：`GET /api/motions/:id/keypoints`，每行一帧：
+ *   `{"frame":0,"timeMs":0,"points":[[x,y,z,visibility] x 33],"angles":[...9]}`
+ *
+ * 解析后转成**扁平 Float32Array**：33 点 x 3 轴 + 33 个置信度，
+ * 供 three.js 逐帧更新（避免每帧创建对象数组导致 GC 抖动）。
+ */
+
+export interface ParsedKeypointFrame {
+  /** 服务端帧号 */
+  frame: number;
+  timeMs: number;
+  /** 长度 33*3：[x,y,z] x 33（与 contracts/skeleton-topology.md §1 顺序一致） */
+  positions: Float32Array;
+  /** 长度 33 的置信度 */
+  visibility: Float32Array;
+  /** 9 个关节角余弦（DTW 输入，预览不用但保留） */
+  angles: number[];
+}
+
+export interface ParsedKeypointSequence {
+  frames: ParsedKeypointFrame[];
+  /** 平均帧间隔（毫秒）；用于播放速度 */
+  frameIntervalMs: number;
+  durationMs: number;
+}
+
+const POINT_COUNT = 33;
+
+function toNumber(value: unknown, fallback = 0): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/** 解析一行；结构不合法返回 null（跳过该行而不是整段失败） */
+function parseLine(line: string): ParsedKeypointFrame | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== 'object') return null;
+  const obj = raw as { frame?: unknown; timeMs?: unknown; points?: unknown; angles?: unknown };
+  if (!Array.isArray(obj.points) || obj.points.length === 0) return null;
+  const count = Math.min(POINT_COUNT, obj.points.length);
+  const positions = new Float32Array(POINT_COUNT * 3);
+  const visibility = new Float32Array(POINT_COUNT);
+  for (let index = 0; index < count; index += 1) {
+    const point = obj.points[index];
+    if (!Array.isArray(point)) continue;
+    positions[index * 3] = toNumber(point[0]);
+    positions[index * 3 + 1] = toNumber(point[1]);
+    positions[index * 3 + 2] = toNumber(point[2]);
+    visibility[index] = toNumber(point[3], 1);
+  }
+  return {
+    frame: toNumber(obj.frame),
+    timeMs: toNumber(obj.timeMs),
+    positions,
+    visibility,
+    angles: Array.isArray(obj.angles) ? obj.angles.map((value) => toNumber(value)) : [],
+  };
+}
+
+/**
+ * 解析 NDJSON；空串 / 全部非法时返回 `frames: []`（调用方给"无数据"提示，不抛错）。
+ */
+export function parseKeypointNdjson(text: string): ParsedKeypointSequence {
+  const frames: ParsedKeypointFrame[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+    const frame = parseLine(line);
+    if (frame) frames.push(frame);
+  }
+  let interval = 1000 / 30;
+  if (frames.length >= 2) {
+    const first = frames[0].timeMs;
+    const last = frames[frames.length - 1].timeMs;
+    const span = last - first;
+    if (span > 0) interval = span / (frames.length - 1);
+  }
+  const durationMs = frames.length > 0 ? frames[frames.length - 1].timeMs + interval : 0;
+  return { frames, frameIntervalMs: interval, durationMs };
+}
+
+/** 计算整段（或指定帧）的包围盒，用于自动取景；返回 null 表示没有可用点 */
+export function sequenceBounds(
+  frames: readonly ParsedKeypointFrame[],
+  minVisibility = 0.3,
+): { min: [number, number, number]; max: [number, number, number] } | null {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let minZ = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let maxZ = Number.NEGATIVE_INFINITY;
+  let seen = 0;
+  for (const frame of frames) {
+    for (let index = 0; index < POINT_COUNT; index += 1) {
+      if (frame.visibility[index] < minVisibility) continue;
+      const x = frame.positions[index * 3];
+      const y = frame.positions[index * 3 + 1];
+      const z = frame.positions[index * 3 + 2];
+      if (x < minX) minX = x;
+      if (y < minY) minY = y;
+      if (z < minZ) minZ = z;
+      if (x > maxX) maxX = x;
+      if (y > maxY) maxY = y;
+      if (z > maxZ) maxZ = z;
+      seen += 1;
+    }
+  }
+  if (seen === 0) return null;
+  return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
@@ -0,0 +1,109 @@
+/**
+ * MediaPipe Pose 33 点拓扑（管理端预览用）。
+ *
+ * 与 `contracts/skeleton-topology.md` §1/§3 一致：
+ *   * 33 个关键点的语义顺序；
+ *   * 父节点表（`parent[i]`，33/34 是虚拟关节 —— 骨盆/肩中心，绘制时归到 0/nose 之外单独处理）。
+ * 服务端权威实现在 `web-server/src/preprocess/mediapipe33.ts`（含测试断言的一致性检查）。
+ * 这里只保留预览绘制需要的两份最小数据，避免把服务端代码打进前端包。
+ */
+
+export const KEYPOINT_NAMES: readonly string[] = [
+  'nose',
+  'left_eye_inner',
+  'left_eye',
+  'left_eye_outer',
+  'right_eye_inner',
+  'right_eye',
+  'right_eye_outer',
+  'left_ear',
+  'right_ear',
+  'mouth_left',
+  'mouth_right',
+  'left_shoulder',
+  'right_shoulder',
+  'left_elbow',
+  'right_elbow',
+  'left_wrist',
+  'right_wrist',
+  'left_pinky',
+  'right_pinky',
+  'left_index',
+  'right_index',
+  'left_thumb',
+  'right_thumb',
+  'left_hip',
+  'right_hip',
+  'left_knee',
+  'right_knee',
+  'left_ankle',
+  'right_ankle',
+  'left_heel',
+  'right_heel',
+  'left_foot_index',
+  'right_foot_index',
+];
+
+/** 虚拟关节索引（不在 33 点内，仅用于层级） */
+export const VIRTUAL_PELVIS = 33;
+export const VIRTUAL_SHOULDER_CENTER = 34;
+
+/** `parent[i]`：-1 表示世界根；33/34 表示虚拟关节 */
+export const PARENT_TABLE: readonly number[] = [
+  VIRTUAL_SHOULDER_CENTER, // 0  nose
+  0, // 1  left_eye_inner
+  0, // 2  left_eye
+  0, // 3  left_eye_outer
+  0, // 4  right_eye_inner
+  0, // 5  right_eye
+  0, // 6  right_eye_outer
+  3, // 7  left_ear
+  6, // 8  right_ear
+  0, // 9  mouth_left
+  0, // 10 mouth_right
+  VIRTUAL_SHOULDER_CENTER, // 11 left_shoulder
+  VIRTUAL_SHOULDER_CENTER, // 12 right_shoulder
+  11, // 13 left_elbow
+  12, // 14 right_elbow
+  13, // 15 left_wrist
+  14, // 16 right_wrist
+  15, // 17 left_pinky
+  16, // 18 right_pinky
+  15, // 19 left_index
+  16, // 20 right_index
+  15, // 21 left_thumb
+  16, // 22 right_thumb
+  VIRTUAL_PELVIS, // 23 left_hip
+  VIRTUAL_PELVIS, // 24 right_hip
+  23, // 25 left_knee
+  24, // 26 right_knee
+  25, // 27 left_ankle
+  26, // 28 right_ankle
+  27, // 29 left_heel
+  28, // 30 right_heel
+  27, // 31 left_foot_index
+  28, // 32 right_foot_index
+];
+
+/** 绘制用骨段：把父表展开成 [子, 父] 对（虚拟关节映射到鼻/肩线的实际点） */
+export const BONE_SEGMENTS: ReadonlyArray<readonly [number, number]> = (() => {
+  const out: Array<readonly [number, number]> = [];
+  for (let index = 0; index < PARENT_TABLE.length; index += 1) {
+    const parent = PARENT_TABLE[index];
+    if (parent === -1) continue;
+    if (parent === VIRTUAL_PELVIS) {
+      // 骨盆虚拟点：用左右髋的中点表示，绘制时由渲染器按帧计算，这里先挂到左髋
+      out.push([index, 23]);
+      continue;
+    }
+    if (parent === VIRTUAL_SHOULDER_CENTER) {
+      out.push([index, 11]);
+      continue;
+    }
+    out.push([index, parent]);
+  }
+  return out;
+})();
+
+/** 需要忽略的绘制段（面部五官连线太密，预览里只会糊成一团） */
+export const FACE_POINT_LIMIT = 11;
@@ -0,0 +1,10 @@
+/**
+ * 应用版本号（构建期由 vite.config.ts 从 web-server/package.json 注入）。
+ * 页面左下角必须展示它，且与 `GET /health` 的 version、发布产物文件名一致
+ * （开发文档 v1.5 第十一章）。SSR / 测试环境下回退为 '0.0.0'。
+ */
+export const APP_VERSION: string =
+  typeof __APP_VERSION__ === 'string' && __APP_VERSION__.length > 0 ? __APP_VERSION__ : '0.0.0';
+
+/** 展示用：带 v 前缀 */
+export const APP_VERSION_LABEL = `v${APP_VERSION}`;
@@ -492,6 +492,14 @@ export function ModelsPage() {
                      </td>
                      <td>
                        <FormatBadge format={model.format} kind="model" />
+                        {!model.usable ? (
+                          <span
+                            className="badge badge-rejected"
+                            title={model.unusableReason ?? '未产出 VRM，不进入客户端目录'}
+                          >
+                            不可用
+                          </span>
+                        ) : null}
                      </td>
                      <td className="mono">{model.vrmVersion ?? '—'}</td>
                      <td>
@@ -1,4 +1,4 @@
-import { useState, type FormEvent } from 'react';
+import { lazy, Suspense, useState, type FormEvent } from 'react';
 import { apiUrl, errorMessage } from '../api/client';
 import {
  deleteMotion,
@@ -13,6 +13,10 @@ import { formatNumber } from '../lib/format';
 import { MOTION_FORMAT_LABELS, PREPROCESS_LABELS, STATUS_OPTIONS } from '../lib/labels';
 import { hasErrors, parseOptionalNumber, requireText, validateSourceFields, type FieldErrors } from '../lib/validation';
 import { useAsync } from '../lib/useAsync';
+const MotionPreview = lazy(async () => {
+  const module = await import('../components/MotionPreview');
+  return { default: module.MotionPreview };
+});
 import {
  ConfirmDialog,
  Empty,
@@ -228,6 +232,7 @@ export function MotionsPage() {
  const [filters, setFilters] = useState<MotionFilters>({ q: '', format: '', status: '', page: 1 });
  const [qInput, setQInput] = useState('');
  const [uploadOpen, setUploadOpen] = useState(false);
+  const [previewId, setPreviewId] = useState<number | null>(null);
  const [deleteTarget, setDeleteTarget] = useState<Motion | null>(null);
  const [busyId, setBusyId] = useState<number | null>(null);
  const [deleting, setDeleting] = useState(false);
@@ -383,6 +388,8 @@ export function MotionsPage() {
            <table className="table">
              <thead>
                <tr>
+                  <th>预览</th>
+
                  <th>名称</th>
                  <th>关联曲目</th>
                  <th>格式</th>
@@ -398,6 +405,31 @@ export function MotionsPage() {
                  const keypointsReady = motion.preprocessState === 'done';
                  return (
                    <tr key={motion.id}>
+                      <td>
+
+                        {motion.thumbnailUrl ? (
+
+                          <img
+
+                            className="thumb-40 thumb-clickable"
+
+                            src={motion.thumbnailUrl}
+
+                            alt={`${motion.name} 首帧骨架`}
+
+                            title="预处理时生成的骨架缩略图（点击预览）"
+
+                            onClick={() => setPreviewId(previewId === motion.id ? null : motion.id)}
+
+                          />
+
+                        ) : (
+
+                          <span className="muted small" title="预处理后生成">—</span>
+
+                        )}
+
+                      </td>
                      <td>
                        <div className="cell-title">{motion.name}</div>
                        <div className="muted small">#{motion.id}</div>
@@ -425,6 +457,23 @@ export function MotionsPage() {
                        <StatusBadge status={motion.status} />
                      </td>
                      <td className="col-actions">
+                        <button
+
+                          type="button"
+
+                          className="link-btn"
+
+                          disabled={!keypointsReady}
+
+                          onClick={() => setPreviewId(previewId === motion.id ? null : motion.id)}
+
+                          title={keypointsReady ? '关键点 3D 回放（播放 / 逐帧 / 时间轴 / 变速 / 循环）' : '预处理完成后才可预览'}
+
+                        >
+
+                          {previewId === motion.id ? '收起预览' : '预览'}
+
+                        </button>
                        <button
                          type="button"
                          className="link-btn"
@@ -473,6 +522,20 @@ export function MotionsPage() {
            onChange={(page) => setFilters((previous) => ({ ...previous, page }))}
          />
        ) : null}
+
+      {previewId !== null ? (
+        <div className="panel-body motion-preview-panel">
+          <header className="panel-head">
+            <h3>动作预览 #{previewId}</h3>
+            <button type="button" className="link-btn" onClick={() => setPreviewId(null)}>
+              关闭
+            </button>
+          </header>
+          <Suspense fallback={<Loading text="正在加载 3D 预览…" />}>
+            <MotionPreview motionId={previewId} />
+          </Suspense>
+        </div>
+      ) : null}
      </section>

      {uploadOpen ? (
@@ -173,6 +173,14 @@ h3 {
  color: var(--text-mute);
 }

+.app-version {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text-strong, #e8ecf3);
+  letter-spacing: 0.02em;
+}
+
 .sidebar-foot code {
  color: var(--text-dim);
  word-break: break-all;
@@ -1485,3 +1493,49 @@ textarea {
 .bone-children {
  margin-left: auto;
 }
+
+/* ---- 动作预览（T-WEB-014） ---- */
+.thumb-40 {
+  width: 40px;
+  height: 40px;
+  border-radius: 4px;
+  background: #181a20;
+  object-fit: cover;
+}
+
+.thumb-clickable {
+  cursor: pointer;
+  border: 1px solid var(--border);
+}
+
+.motion-preview-panel {
+  margin-top: 12px;
+}
+
+.motion-preview-canvas {
+  width: 100%;
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  background: #181a20;
+}
+
+.motion-preview-bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  padding: 8px 4px 2px;
+}
+
+.motion-preview-bar input[type='range'] {
+  flex: 1 1 220px;
+  min-width: 160px;
+}
+
+.motion-preview-speed {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--text-mute);
+}
@@ -7,3 +7,6 @@ interface ImportMetaEnv {
 interface ImportMeta {
  readonly env: ImportMetaEnv;
 }
+
+/** 构建期注入的应用版本号（来自 web-server/package.json） */
+declare const __APP_VERSION__: string;
@@ -1,11 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';

 const API_TARGET = 'http://localhost:3000';

+/**
+ * 版本号唯一来源：`web-server/package.json`（与 `GET /health` 的 version 同源）。
+ * 构建期注入 `__APP_VERSION__`，管理端左下角直接展示，避免代码里再手写一份
+ * （见开发文档 v1.5 第十一章「版本号展示」）。
+ */
+const serverPackage = JSON.parse(
+  readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
+) as { version?: string };
+const APP_VERSION = serverPackage.version ?? '0.0.0';
+
 // base './' 让产物可挂在任意子路径；开发期 /api 与 /health 代理到 NestJS 服务。
 export default defineConfig({
  base: './',
+  define: {
+    __APP_VERSION__: JSON.stringify(APP_VERSION),
+  },
  plugins: [react()],
  server: {
    port: 5173,
@@ -1,6 +1,6 @@
 {
  "name": "opendance-web-server",
-  "version": "0.2.5",
+  "version": "0.5.0",
  "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
  "license": "MIT",
  "private": true,
@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { createHash } from 'node:crypto';
 import { Repository } from 'typeorm';
-import { PublishStatus } from '../common/enums';
+import { ModelFormat, PublishStatus } from '../common/enums';
 import { AppConfig } from '../config/configuration';
 import { CharacterModel } from '../entities/model.entity';
 import { Motion } from '../entities/motion.entity';
@@ -43,7 +43,11 @@ export class CatalogService {
    const [songs, motions, models] = await Promise.all([
      this.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
      this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
-      this.models.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
+      // v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
+      this.models.find({
+        where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
+        order: { id: 'ASC' },
+      }),
    ]);

    const [songDtos, motionDtos, modelDtos, defaultModelId] = await Promise.all([
@@ -71,7 +75,11 @@ export class CatalogService {
    const [songs, motions, models] = await Promise.all([
      this.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
      this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
-      this.models.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
+      // v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
+      this.models.find({
+        where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
+        order: { id: 'ASC' },
+      }),
    ]);

    const fingerprint = JSON.stringify({
@@ -70,6 +70,8 @@ export enum AssetKind {
  /** 上传的模型压缩包（zip）原件，仅用于溯源；入库的是转换后的模型文件 */
  ModelArchive = 'model-archive',
  Thumbnail = 'thumbnail',
+  /** 动作关键点序列的骨架缩略图（T-WEB-014） */
+  MotionThumbnail = 'motion-thumbnail',
  Keypoints = 'keypoints',
 }

@@ -0,0 +1,65 @@
+/**
+ * 极简 PNG 编码（8 位真彩 RGB、无隔行、filter=0、手写 CRC32）。
+ *
+ * 模型缩略图与动作缩略图共用：**零原生依赖**（只用 node:zlib 的 deflate），
+ * 避免为了出图引入 canvas / sharp / headless-gl。
+ * 解码见 `models/model-thumbnail.ts` 内的 decodePng（同样零依赖）。
+ */
+import { deflateSync } from 'node:zlib';
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer: Buffer): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1) {
+    c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type: string, data: Buffer): Buffer {
+  const typeBuffer = Buffer.from(type, 'ascii');
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
+  return Buffer.concat([length, typeBuffer, data, crc]);
+}
+
+/** 把 RGB 像素（行优先，长度 = width*height*3）编码为 PNG */
+export function encodePngRgb(rgb: Buffer, width: number, height: number): Buffer {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // color type: truecolor RGB
+  ihdr[10] = 0; // compression
+  ihdr[11] = 0; // filter method
+  ihdr[12] = 0; // interlace: none
+
+  const stride = width * 3;
+  const raw = Buffer.alloc(height * (stride + 1));
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0; // filter type 0
+    rgb.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+
+  return Buffer.concat([
+    signature,
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', deflateSync(raw)),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
@@ -88,7 +88,9 @@ export class AppConfig {
   * 设为 `vrm` 时会在 GLB 之上补 `VRMC_vrm` 扩展，humanoid 骨骼不全则回退 GLB。
   */
  get modelConvertFormat(): 'glb' | 'vrm' {
-    return (this.config.get<string>('modelConvertFormat') ?? 'glb') === 'vrm' ? 'vrm' : 'glb';
+    // v0.5.0 起默认 **vrm**：所有上传模型一律转 VRM（见 contracts/model-formats.md 1.1）；
+    // humanoid 不达标时管线自动回退交付 GLB 并置 usable=false。
+    return (this.config.get<string>('modelConvertFormat') ?? 'vrm') === 'glb' ? 'glb' : 'vrm';
  }

  /**
@@ -207,7 +209,7 @@ export const configuration = () => {
    adminDir: process.env.ADMIN_DIR ?? resolve(process.cwd(), '..', 'admin'),
    uploadMaxBytes: Number(process.env.UPLOAD_MAX_BYTES ?? 512 * 1024 * 1024),
    assimpBin: process.env.ASSIMP_BIN ?? 'assimp',
-    modelConvertFormat: process.env.MODEL_CONVERT_FORMAT ?? 'glb',
+    modelConvertFormat: process.env.MODEL_CONVERT_FORMAT ?? 'vrm',
    modelShading: process.env.MODEL_SHADING ?? 'pbr',
    modelConvertPmx: process.env.MODEL_CONVERT_PMX ?? 'Hatsune Miku.pmx',
    modelConvertTimeoutMs: Number(process.env.MODEL_CONVERT_TIMEOUT_MS ?? 180_000),
@@ -11,9 +11,9 @@ import { join } from 'node:path';
 export const CONTRACT_VERSIONS: Readonly<Record<string, string>> = Object.freeze({
  'rest-api': '0.4.0',
  'websocket-keypoints': '0.1.0',
-  'data-models': '0.4.0',
-  'skeleton-topology': '0.1.0',
-  'model-formats': '0.4.0',
+  'data-models': '0.6.0',
+  'skeleton-topology': '0.2.0',
+  'model-formats': '0.5.0',
  database: '0.3.0',
 });

@@ -57,6 +57,10 @@ export class Motion {
  @Column({ name: 'keypoint_frames', type: 'int', nullable: true })
  keypointFrames!: number | null;

+  /** 骨架缩略图资产（预处理时生成；失败不影响预处理） */
+  @Column({ name: 'thumbnail_asset_id', type: 'bigint', nullable: true, transformer: bigintNumber })
+  thumbnailAssetId!: number | null;
+
  @Column({ name: 'preprocess_state', type: 'varchar', length: 16, default: PreprocessState.None })
  preprocessState!: PreprocessState;

@@ -0,0 +1,19 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * 动作预览（T-WEB-014）：`motions.thumbnail_asset_id` 存骨架缩略图资产。
+ *
+ * 缩略图在 `/api/motions/:id/preprocess` 时生成（关键点序列 -> 正视图骨架 PNG），
+ * 供动作管理列表展示；生成失败不影响预处理结果。
+ */
+export class AddMotionThumbnail1789600000000 implements MigrationInterface {
+    name = 'AddMotionThumbnail1789600000000'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE \`motions\` ADD \`thumbnail_asset_id\` bigint NULL`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE \`motions\` DROP COLUMN \`thumbnail_asset_id\``);
+    }
+}
@@ -143,21 +143,51 @@ export const STRIPPABLE_PREFIXES: readonly string[] = ['jbip', 'mixamorig', 'bip
 * 与客户端 `humanoid_map.gd` 的 CANDIDATES 逐字一致（测试会逐键比对）。
 */
 export const HUMANOID_CANDIDATES: Record<string, string[]> = {
-  hips: ['chips', 'hips', 'hip', 'pelvis', 'root'],
-  spine: ['cspine', 'spine', 'spine1', 'spinemid'],
-  chest: ['cchest', 'chest', 'spine2', 'spineupper'],
-  upperChest: ['cupperchest', 'upperchest', 'chest2', 'spine3'],
-  neck: ['cneck', 'neck', 'neck1'],
-  head: ['chead', 'head'],
-  leftShoulder: ['lshoulder', 'leftshoulder', 'shoulderl', 'shoulderleft', 'claviclel', 'lclavicle'],
-  leftUpperArm: ['lupperarm', 'leftupperarm', 'larm', 'leftarm', 'luparm'],
-  leftLowerArm: ['llowerarm', 'leftlowerarm', 'lforearm', 'leftforearm', 'lelbow'],
-  leftHand: ['lhand', 'lefthand', 'lwrist', 'leftwrist'],
-  rightShoulder: ['rshoulder', 'rightshoulder', 'shoulderr', 'shoulderright', 'clavicler', 'rclavicle'],
-  rightUpperArm: ['rupperarm', 'rightupperarm', 'rarm', 'rightarm', 'ruparm'],
-  rightLowerArm: ['rlowerarm', 'rightlowerarm', 'rforearm', 'rightforearm', 'relbow'],
-  rightHand: ['rhand', 'righthand', 'rwrist', 'rightwrist'],
-  leftUpperLeg: ['lupperleg', 'leftupperleg', 'lthigh', 'leftthigh', 'lupleg', 'lhip', 'lefthip'],
+  hips: ['chips', 'hips', 'hip', 'pelvis', 'root',
+    // MMD / 中文常见名
+    '下半身', '腰', 'センター', 'center', '臀部', '髋', '骨盆',],
+  spine: ['cspine', 'spine', 'spine1', 'spinemid',
+    // MMD / 中文常见名
+    '上半身', '脊椎', '脊柱',],
+  chest: ['cchest', 'chest', 'spine2', 'spineupper',
+    // MMD / 中文常见名
+    '上半身2', '胸部', '胸',],
+  upperChest: ['cupperchest', 'upperchest', 'chest2', 'spine3',
+    // MMD / 中文常见名
+    '上半身3',],
+  neck: ['cneck', 'neck', 'neck1',
+    // MMD / 中文常见名
+    '首', '颈', '脖子',],
+  head: ['chead', 'head',
+    // MMD / 中文常见名
+    '頭', '头', '头部',],
+  leftShoulder: ['lshoulder', 'leftshoulder', 'shoulderl', 'shoulderleft', 'claviclel', 'lclavicle',
+    // MMD / 中文常见名
+    '左肩', '左锁骨',],
+  leftUpperArm: ['lupperarm', 'leftupperarm', 'larm', 'leftarm', 'luparm',
+    // MMD / 中文常见名
+    '左腕', '左大臂', '左上臂', '左臂',],
+  leftLowerArm: ['llowerarm', 'leftlowerarm', 'lforearm', 'leftforearm', 'lelbow',
+    // MMD / 中文常见名
+    '左ひじ', '左肘', '左小臂', '左前臂',],
+  leftHand: ['lhand', 'lefthand', 'lwrist', 'leftwrist',
+    // MMD / 中文常见名
+    '左手首', '左手', '左手腕',],
+  rightShoulder: ['rshoulder', 'rightshoulder', 'shoulderr', 'shoulderright', 'clavicler', 'rclavicle',
+    // MMD / 中文常见名
+    '右肩', '右锁骨',],
+  rightUpperArm: ['rupperarm', 'rightupperarm', 'rarm', 'rightarm', 'ruparm',
+    // MMD / 中文常见名
+    '右腕', '右大臂', '右上臂', '右臂',],
+  rightLowerArm: ['rlowerarm', 'rightlowerarm', 'rforearm', 'rightforearm', 'relbow',
+    // MMD / 中文常见名
+    '右ひじ', '右肘', '右小臂', '右前臂',],
+  rightHand: ['rhand', 'righthand', 'rwrist', 'rightwrist',
+    // MMD / 中文常见名
+    '右手首', '右手', '右手腕',],
+  leftUpperLeg: ['lupperleg', 'leftupperleg', 'lthigh', 'leftthigh', 'lupleg', 'lhip', 'lefthip',
+    // MMD / 中文常见名
+    '左足', '左大腿',],
  leftLowerLeg: [
    'llowerleg',
    'leftlowerleg',
@@ -167,10 +197,17 @@ export const HUMANOID_CANDIDATES: Record<string, string[]> = {
    'leftshin',
    'lknee',
    'leftknee',
-  ],
-  leftFoot: ['lfoot', 'leftfoot', 'lankle', 'leftankle'],
-  leftToes: ['ltoes', 'lefttoes', 'ltoe', 'lefttoe', 'ltoebase', 'lefttoebase'],
-  rightUpperLeg: ['rupperleg', 'rightupperleg', 'rthigh', 'rightthigh', 'rupleg', 'rhip', 'righthip'],
+    // MMD / 中文常见名
+    '左ひざ', '左膝', '左小腿', '左膝盖',],
+  leftFoot: ['lfoot', 'leftfoot', 'lankle', 'leftankle',
+    // MMD / 中文常见名
+    '左足首', '左脚', '左脚踝',],
+  leftToes: ['ltoes', 'lefttoes', 'ltoe', 'lefttoe', 'ltoebase', 'lefttoebase',
+    // MMD / 中文常见名
+    '左つま先', '左脚趾',],
+  rightUpperLeg: ['rupperleg', 'rightupperleg', 'rthigh', 'rightthigh', 'rupleg', 'rhip', 'righthip',
+    // MMD / 中文常见名
+    '右足', '右大腿',],
  rightLowerLeg: [
    'rlowerleg',
    'rightlowerleg',
@@ -180,9 +217,14 @@ export const HUMANOID_CANDIDATES: Record<string, string[]> = {
    'rightshin',
    'rknee',
    'rightknee',
-  ],
-  rightFoot: ['rfoot', 'rightfoot', 'rankle', 'rightankle'],
-  rightToes: ['rtoes', 'righttoes', 'rtoe', 'righttoe', 'rtoebase', 'righttoebase'],
+    // MMD / 中文常见名
+    '右ひざ', '右膝', '右小腿', '右膝盖',],
+  rightFoot: ['rfoot', 'rightfoot', 'rankle', 'rightankle',
+    // MMD / 中文常见名
+    '右足首', '右脚', '右脚踝',],
+  rightToes: ['rtoes', 'righttoes', 'rtoe', 'righttoe', 'rtoebase', 'righttoebase',
+    // MMD / 中文常见名
+    '右つま先', '右脚趾',],
 };

 /* -------------------------------------------------------------- 客户端逻辑移植 */
@@ -196,7 +238,25 @@ export function normalizeBoneName(nodeName: string): string {
  const lower = nodeName.toLowerCase();
  let out = '';
  for (const ch of lower) {
-    if ((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9')) out += ch;
+    const code = ch.codePointAt(0) ?? 0;
+    if ((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9')) {
+      out += ch;
+      continue;
+    }
+    // 全角 ASCII（Ａ-Ｚ ａ-ｚ ０-９）折成半角：MMD 常写「足ＩＫ」「つま先ＩＫ」
+    if (code >= 0xff01 && code <= 0xff5e) {
+      out += String.fromCharCode(code - 0xfee0);
+      continue;
+    }
+    // **必须保留中文与日文**：MMD 骨名（上半身 / 左ひじ / 首 / 下半身）全是这些字符。
+    // v0.3.0 之前只保留 a-z0-9，导致 MMD 模型所有骨名归一化成空串、humanoid 覆盖率恒为 0/22。
+    if (
+      (code >= 0x3040 && code <= 0x30ff) || // 平假名 / 片假名 / 长音符
+      (code >= 0x4e00 && code <= 0x9fff) || // CJK 统一表意文字
+      code === 0x3005 // 々
+    ) {
+      out += ch;
+    }
  }
  return out;
 }
@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { inflateSync } from 'node:zlib';
+
+import { encodePngRgb } from '../common/png';
 import { dirname, resolve as resolvePath } from 'node:path';
-import { deflateSync } from 'node:zlib';

 /**
 * 服务端模型缩略图生成（纯 TypeScript 软件光栅化）。
@@ -1355,67 +1356,6 @@ function decodePng(buffer: Buffer): DecodedImage | null {
  return { width, height, rgba: out };
 }

-// ---------------------------------------------------------------------------
-// PNG 编码（8 位 RGB、无隔行、filter=0；不引第三方库）
-// ---------------------------------------------------------------------------
-
-const CRC_TABLE = (() => {
-  const table = new Uint32Array(256);
-  for (let n = 0; n < 256; n += 1) {
-    let c = n;
-    for (let k = 0; k < 8; k += 1) {
-      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-    }
-    table[n] = c >>> 0;
-  }
-  return table;
-})();
-
-function crc32(buffer: Buffer): number {
-  let c = 0xffffffff;
-  for (let i = 0; i < buffer.length; i += 1) {
-    c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
-  }
-  return (c ^ 0xffffffff) >>> 0;
-}
-
-function pngChunk(type: string, data: Buffer): Buffer {
-  const typeBuffer = Buffer.from(type, 'ascii');
-  const length = Buffer.alloc(4);
-  length.writeUInt32BE(data.length, 0);
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
-  return Buffer.concat([length, typeBuffer, data, crc]);
-}
-
-/** 把 RGB 像素编码为 PNG（每行前置 filter 字节 0，整块 deflate） */
-function encodePng(rgb: Buffer, width: number, height: number): Buffer {
-  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(width, 0);
-  ihdr.writeUInt32BE(height, 4);
-  ihdr[8] = 8; // bit depth
-  ihdr[9] = 2; // color type: truecolor RGB
-  ihdr[10] = 0; // compression
-  ihdr[11] = 0; // filter method
-  ihdr[12] = 0; // interlace: none
-
-  const stride = width * 3;
-  const raw = Buffer.alloc(height * (stride + 1));
-  for (let y = 0; y < height; y += 1) {
-    raw[y * (stride + 1)] = 0; // filter type 0
-    rgb.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
-  }
-
-  return Buffer.concat([
-    signature,
-    pngChunk('IHDR', ihdr),
-    pngChunk('IDAT', deflateSync(raw)),
-    pngChunk('IEND', Buffer.alloc(0)),
-  ]);
-}
-
 // ---------------------------------------------------------------------------
 // 对外入口
 // ---------------------------------------------------------------------------
@@ -1476,7 +1416,7 @@ export async function renderModelThumbnail(
    if (output.drawn === 0) return null;

    return {
-      png: encodePng(output.pixels, size, size),
+      png: encodePngRgb(output.pixels, size, size),
      width: size,
      height: size,
      trianglesDrawn: output.drawn,
@@ -1,4 +1,5 @@
 import { ModelFormat, PublishStatus, SourceType } from '../common/enums';
+import type { ModelStats } from './model-inspector';
 import { CharacterModel } from '../entities/model.entity';

 /** 契约 data-models.md §4 的对外表示 */
@@ -7,6 +8,13 @@ export interface ModelDto {
  name: string;
  format: ModelFormat;
  vrmVersion: string | null;
+  /**
+   * 是否可被客户端使用（v0.5.0）：等价于"已产出 VRM"。
+   * `false` 的模型**不进入 `catalog/export`**，但仍可入库与审核。
+   */
+  usable: boolean;
+  /** `usable=false` 时的原因（中文，供审核面板直接展示） */
+  unusableReason: string | null;
  isPrimary: boolean;
  fileUrl: string | null;
  fileSize: number | null;
@@ -37,12 +45,35 @@ export interface ModelUrlLookup {
  sourceSha256?: string | null;
 }

+/**
+ * 模型是否可用于客户端（v0.5.0 门槛）：**必须已产出 VRM**。
+ *
+ * 依据 `contracts/model-formats.md` 1.1：所有上传模型一律转 VRM；
+ * humanoid 不达标时管线回退交付 GLB，此时模型可入库、可审核，但**不可用**、
+ * 不进入 `catalog/export` —— 待按 skeleton-topology 标准重绑定骨骼后重新转换即转为可用。
+ */
+export function isUsableModel(model: CharacterModel): boolean {
+  return model.format === ModelFormat.Vrm;
+}
+
+/** 不可用的原因（可用时返回 null）；从 stats 取 humanoid 覆盖度，便于人工定位 */
+export function unusableReason(model: CharacterModel): string | null {
+  if (isUsableModel(model)) return null;
+  const stats = (model.stats ?? null) as Partial<ModelStats> | null;
+  if (stats && typeof stats.humanoidMapped === 'number' && typeof stats.humanoidTotal === 'number') {
+    return `humanoid 不达标（${stats.humanoidMapped}/${stats.humanoidTotal}），未产出 VRM`;
+  }
+  return '未产出 VRM（格式为 GLB），不可用于客户端';
+}
+
 export function toModelDto(model: CharacterModel, urls: ModelUrlLookup): ModelDto {
  return {
    id: model.id,
    name: model.name,
    format: model.format,
    vrmVersion: model.vrmVersion,
+    usable: isUsableModel(model),
+    unusableReason: unusableReason(model),
    isPrimary: model.isPrimary,
    fileUrl: urls.fileUrl,
    fileSize: urls.fileSize ?? null,
@@ -451,8 +451,9 @@ export class ModelsService {
   *   4. id 最小的已发布模型
   */
  async resolveDefaultModelId(): Promise<number | null> {
+    // v0.5.0：默认模型必须来自**可用**模型（已产出 VRM）；未产出 VRM 的不进客户端目录
    const published = await this.models.find({
-      where: { status: PublishStatus.Published },
+      where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
      order: { id: 'ASC' },
    });
    if (published.length === 0) return null;
@@ -0,0 +1,177 @@
+/**
+ * 动作缩略图：把关键点序列画成一张骨架 PNG（零原生依赖）。
+ *
+ * 用途：动作管理列表每行显示首帧骨架缩略图（T-WEB-014），随预处理一起生成并落库
+ * （`motions.thumbnail_asset_id`）。与模型缩略图共用 `common/png.ts` 的编码器。
+ *
+ * 画法取舍：
+ *   * 只做**正视图**（X/Y 平面）——动作的"姿态"在正视图里最容易辨认，且不需要相机与光照；
+ *   * 取**代表帧**（默认整段中间帧）绘制，包围盒按**整段**计算，保证不同动作构图一致；
+ *   * 置信度低于阈值的点不画（与其相连的骨骼也跳过），避免出现"飘线"。
+ */
+import { PARENT_TABLE } from '../preprocess/mediapipe33';
+import type { Keypoint, KeypointFrame } from '../preprocess/mediapipe33';
+import { encodePngRgb } from '../common/png';
+
+export interface MotionThumbnailOptions {
+  /** 输出边长（正方形），默认 256 */
+  size?: number;
+  /** 背景色 RGB，默认深灰 [24,26,32]（与模型缩略图一致） */
+  background?: [number, number, number];
+  /** 骨骼颜色 RGB */
+  boneColor?: [number, number, number];
+  /** 关节颜色 RGB */
+  jointColor?: [number, number, number];
+  /** 置信度阈值，低于该值的点不绘制，默认 0.3 */
+  minVisibility?: number;
+  /** 指定绘制第几帧（默认中间帧）；越界会夹到范围内 */
+  frameIndex?: number;
+}
+
+const DEFAULT_SIZE = 256;
+const MIN_SIZE = 32;
+const MAX_SIZE = 1024;
+const DEFAULT_BACKGROUND: [number, number, number] = [24, 26, 32];
+const DEFAULT_BONE: [number, number, number] = [96, 165, 250];
+const DEFAULT_JOINT: [number, number, number] = [248, 250, 252];
+const DEFAULT_MIN_VISIBILITY = 0.3;
+
+interface Point2 {
+  x: number;
+  y: number;
+}
+
+/** 画一条粗线（Bresenham + 方形笔刷）；坐标已为像素空间 */
+function drawLine(
+  pixels: Uint8Array,
+  size: number,
+  from: Point2,
+  to: Point2,
+  color: [number, number, number],
+  thickness: number,
+): void {
+  const half = Math.max(0, Math.floor(thickness / 2));
+  const steps = Math.max(Math.abs(to.x - from.x), Math.abs(to.y - from.y));
+  const count = Math.max(1, Math.ceil(steps));
+  for (let step = 0; step <= count; step += 1) {
+    const t = count === 0 ? 0 : step / count;
+    const cx = Math.round(from.x + (to.x - from.x) * t);
+    const cy = Math.round(from.y + (to.y - from.y) * t);
+    for (let dy = -half; dy <= half; dy += 1) {
+      for (let dx = -half; dx <= half; dx += 1) {
+        const x = cx + dx;
+        const y = cy + dy;
+        if (x < 0 || y < 0 || x >= size || y >= size) continue;
+        const index = (y * size + x) * 3;
+        pixels[index] = color[0];
+        pixels[index + 1] = color[1];
+        pixels[index + 2] = color[2];
+      }
+    }
+  }
+}
+
+/** 画一个实心圆（关节） */
+function drawDisc(
+  pixels: Uint8Array,
+  size: number,
+  center: Point2,
+  radius: number,
+  color: [number, number, number],
+): void {
+  const r = Math.max(1, radius);
+  const r2 = r * r;
+  for (let dy = -r; dy <= r; dy += 1) {
+    for (let dx = -r; dx <= r; dx += 1) {
+      if (dx * dx + dy * dy > r2) continue;
+      const x = Math.round(center.x) + dx;
+      const y = Math.round(center.y) + dy;
+      if (x < 0 || y < 0 || x >= size || y >= size) continue;
+      const index = (y * size + x) * 3;
+      pixels[index] = color[0];
+      pixels[index + 1] = color[1];
+      pixels[index + 2] = color[2];
+    }
+  }
+}
+
+/**
+ * 渲染动作骨架缩略图。
+ * 关键点为空 / 全部低于置信度 / 退化包围盒时返回 null（调用方按"未生成"处理，不抛错）。
+ */
+export function renderMotionThumbnail(
+  frames: readonly KeypointFrame[],
+  options: MotionThumbnailOptions = {},
+): Buffer | null {
+  if (frames.length === 0) return null;
+  const rawSize = options.size ?? DEFAULT_SIZE;
+  if (!Number.isFinite(rawSize)) throw new Error('缩略图尺寸非法：size 必须是有限数字');
+  const size = Math.min(MAX_SIZE, Math.max(MIN_SIZE, Math.round(rawSize)));
+  const background = options.background ?? DEFAULT_BACKGROUND;
+  const boneColor = options.boneColor ?? DEFAULT_BONE;
+  const jointColor = options.jointColor ?? DEFAULT_JOINT;
+  const minVisibility = options.minVisibility ?? DEFAULT_MIN_VISIBILITY;
+
+  // 包围盒按整段计算（所有可见点），保证同一动作族的构图一致
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let visible = 0;
+  for (const frame of frames) {
+    for (const point of frame.points) {
+      // Keypoint = [x, y, z, visibility]
+      const [x, y, , visibility] = point;
+      if (visibility < minVisibility) continue;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      visible += 1;
+    }
+  }
+  if (visible === 0 || !Number.isFinite(minX) || !Number.isFinite(minY)) return null;
+
+  const width = Math.max(maxX - minX, 1e-3);
+  const height = Math.max(maxY - minY, 1e-3);
+  const scale = (size * 0.86) / Math.max(width, height);
+  const offsetX = size / 2 - ((minX + maxX) / 2) * scale;
+  // glTF / 关键点坐标是 Y 向上，图像 Y 向下 —— 这里翻转，保证头在上
+  const offsetY = size / 2 + ((minY + maxY) / 2) * scale;
+  const project = (point: Keypoint): Point2 => ({
+    x: point[0] * scale + offsetX,
+    y: offsetY - point[1] * scale,
+  });
+
+  const pixels = new Uint8Array(size * size * 3);
+  for (let i = 0; i < size * size; i += 1) {
+    pixels[i * 3] = background[0];
+    pixels[i * 3 + 1] = background[1];
+    pixels[i * 3 + 2] = background[2];
+  }
+
+  const requested = options.frameIndex ?? Math.floor(frames.length / 2);
+  const frame = frames[Math.min(frames.length - 1, Math.max(0, requested))];
+  const thickness = Math.max(2, Math.round(size / 96));
+  const jointRadius = Math.max(1, Math.round(size / 128));
+
+  // 骨骼：按 33 点父表连线（父索引 33/34 是虚拟关节，映射到 0）
+  for (let index = 0; index < PARENT_TABLE.length && index < frame.points.length; index += 1) {
+    const rawParent = PARENT_TABLE[index];
+    const parentIndex = rawParent === 33 || rawParent === 34 ? 0 : rawParent;
+    if (parentIndex < 0 || parentIndex >= frame.points.length) continue;
+    const child = frame.points[index];
+    const parent = frame.points[parentIndex];
+    if (child[3] < minVisibility || parent[3] < minVisibility) continue;
+    drawLine(pixels, size, project(parent), project(child), boneColor, thickness);
+  }
+
+  // 关节
+  for (const point of frame.points) {
+    if (point[3] < minVisibility) continue;
+    drawDisc(pixels, size, project(point), jointRadius, jointColor);
+  }
+
+  return encodePngRgb(Buffer.from(pixels.buffer, pixels.byteOffset, pixels.length), size, size);
+}
@@ -14,6 +14,8 @@ export interface MotionDto {
  durationMs: number | null;
  keypointFormat: string | null;
  keypointUrl: string | null;
+  /** 骨架缩略图（预处理时生成；T-WEB-014） */
+  thumbnailUrl: string | null;
  keypointFrames: number | null;
  preprocessState: PreprocessState;
  preprocessError: string | null;
@@ -31,6 +33,7 @@ export interface MotionUrlLookup {
  fileUrl: string | null;
  keypointUrl: string | null;
  fileSize?: number | null;
+  thumbnailUrl: string | null;
 }

 export function toMotionDto(motion: Motion, urls: MotionUrlLookup): MotionDto {
@@ -46,6 +49,7 @@ export function toMotionDto(motion: Motion, urls: MotionUrlLookup): MotionDto {
    durationMs: motion.durationMs,
    keypointFormat: motion.keypointFormat,
    keypointUrl: urls.keypointUrl,
+    thumbnailUrl: urls.thumbnailUrl,
    keypointFrames: motion.keypointFrames,
    preprocessState: motion.preprocessState,
    preprocessError: motion.preprocessError,
@@ -204,14 +204,16 @@ export class MotionsService {

  async toDtos(rows: Motion[]): Promise<MotionDto[]> {
    const assets = await this.storage.findMany(
-      rows.flatMap((row) => [row.fileAssetId, row.keypointAssetId]),
+      rows.flatMap((row) => [row.fileAssetId, row.keypointAssetId, row.thumbnailAssetId]),
    );
    return rows.map((row) => {
      const file = row.fileAssetId ? assets.get(row.fileAssetId) : undefined;
      const keypoints = row.keypointAssetId ? assets.get(row.keypointAssetId) : undefined;
+      const thumbnail = row.thumbnailAssetId ? assets.get(row.thumbnailAssetId) : undefined;
      return toMotionDto(row, {
        fileUrl: file ? this.storage.url(file) : null,
        keypointUrl: keypoints ? this.storage.url(keypoints) : null,
+        thumbnailUrl: thumbnail ? this.storage.url(thumbnail) : null,
        fileSize: file?.size ?? null,
      });
    });
@@ -1,4 +1,5 @@
 import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { renderMotionThumbnail } from '../motions/motion-thumbnail';
 import { InjectRepository } from '@nestjs/typeorm';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -63,6 +64,26 @@ export class PreprocessService {

      motion.keypointFormat = KEYPOINT_FORMAT;
      motion.keypointAssetId = stored.asset.id;
+
+      // 骨架缩略图（T-WEB-014）：动作管理列表展示；失败只记 warning，不影响预处理结果
+      try {
+        const thumbnail = renderMotionThumbnail(result.frames);
+        if (thumbnail) {
+          const storedThumb = await this.storage.persistBuffer(
+            AssetKind.MotionThumbnail,
+            thumbnail,
+            `motion-${motion.id}-thumb.png`,
+            'image/png',
+          );
+          motion.thumbnailAssetId = storedThumb.asset.id;
+        } else {
+          this.logger.warn(`动作 #${motion.id} 缩略图未生成（关键点不可用）`);
+        }
+      } catch (error) {
+        this.logger.warn(
+          `动作 #${motion.id} 缩略图生成失败：${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
      motion.keypointFrames = result.frames.length;
      motion.fps = result.fps;
      motion.frameCount = result.frames.length;
@@ -406,6 +406,62 @@ describe('morphTargets 统计', () => {
  });
 });

+/* --------------------- 5.5 MMD / 中文骨名映射（T-WEB-013 骨骼重绑定） */
+
+describe('MMD 与中文骨名映射（T-WEB-013）', () => {
+  async function statsFor(names: string[], file: string): Promise<ModelStats> {
+    const doc = buildHumanoidDocument(names);
+    return inspectModelFile(write(file, Buffer.from(JSON.stringify(doc))));
+  }
+
+  it('归一化必须保留中日文，并把全角 ASCII 折成半角', () => {
+    expect(normalizeBoneName('上半身')).toBe('上半身');
+    expect(normalizeBoneName('左ひじ')).toBe('左ひじ');
+    expect(normalizeBoneName('首')).toBe('首');
+    // MMD 的「足ＩＫ」是全角字母：折成半角后是 足ik，与「左足」精确匹配不上（安全）
+    expect(normalizeBoneName('左足ＩＫ')).toBe('左足ik');
+    expect(normalizeBoneName('J_Bip_C_Hips')).toBe('jbipchips');
+  });
+
+  it('MMD 标准骨架名 → 16 根必需骨齐全、drivable=true（0/22 的修复点）', async () => {
+    const stats = await statsFor(
+      [
+        '全ての親', 'センター', '下半身', '上半身', '上半身2', '首', '頭',
+        '左肩', '左腕', '左ひじ', '左手首', '右肩', '右腕', '右ひじ', '右手首',
+        '左足', '左ひざ', '左足首', '右足', '右ひざ', '右足首',
+      ],
+      'mmd-standard.gltf',
+    );
+    expect(stats.missingRequiredBones).toEqual([]);
+    expect(stats.drivable).toBe(true);
+    expect(stats.humanoidMapped).toBeGreaterThanOrEqual(16);
+  });
+
+  it('MMD 的 IK 骨（足ＩＫ / つま先ＩＫ）不得抢占 humanoid 骨', async () => {
+    const stats = await statsFor(
+      ['下半身', '上半身', '首', '頭', '左足ＩＫ', '左つま先ＩＫ'],
+      'mmd-ik.gltf',
+    );
+    expect(stats.missingRequiredBones).toContain('leftUpperLeg');
+    expect(stats.missingRequiredBones).toContain('leftFoot');
+    expect(stats.drivable).toBe(false);
+  });
+
+  it('中文骨名也能映射（臀部/头/脖子/左大腿/左脚）', async () => {
+    const stats = await statsFor(
+      [
+        '臀部', '脊椎', '胸部', '脖子', '头',
+        '左大臂', '左小臂', '左手', '右大臂', '右小臂', '右手',
+        '左大腿', '左小腿', '左脚', '右大腿', '右小腿', '右脚',
+      ],
+      'chinese-names.gltf',
+    );
+    expect(stats.missingRequiredBones).toEqual([]);
+    expect(stats.drivable).toBe(true);
+  });
+});
+
+
 /* ------------------------------- 6. 与客户端 humanoid_map.gd 的一致性 */

 /** gd 文件在客户端仓库里；按「从 web-server 运行」为主，同时兼容从仓库根运行 */
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { CatalogService } from '../src/catalog/catalog.service';
+import { ModelFormat, PublishStatus, SourceType } from '../src/common/enums';
+import type { CharacterModel } from '../src/entities/model.entity';
+import { isUsableModel, toModelDto, unusableReason } from '../src/models/model.serializer';
+
+/**
+ * v0.5.0「模型一律转 VRM」的可用性门槛。
+ *
+ * 规则（contracts/model-formats.md 1.1）：所有上传模型都转 VRM；
+ * humanoid 不达标时回退交付 GLB —— 这种模型**可入库、可审核，但不可用**，
+ * **不进入 `catalog/export`**（用户明确选择"入库但标记不可用，不进已发布目录"）。
+ */
+
+function model(overrides: Partial<CharacterModel> = {}): CharacterModel {
+  return {
+    id: 1,
+    name: 'model',
+    format: ModelFormat.Vrm,
+    vrmVersion: '1.0',
+    isPrimary: false,
+    fileAssetId: 1,
+    sourceAssetId: null,
+    thumbnailAssetId: null,
+    conversionNote: null,
+    stats: null,
+    sourceType: SourceType.Other,
+    sourceName: 'x',
+    sourceUrl: 'x',
+    license: 'x',
+    author: 'x',
+    status: PublishStatus.Published,
+    createdAt: new Date('2026-01-01T00:00:00Z'),
+    updatedAt: new Date('2026-01-01T00:00:00Z'),
+    ...overrides,
+  } as CharacterModel;
+}
+
+describe('模型可用性（usable）', () => {
+  it('VRM → 可用，且没有不可用原因', () => {
+    const vrm = model({ format: ModelFormat.Vrm });
+    expect(isUsableModel(vrm)).toBe(true);
+    expect(unusableReason(vrm)).toBeNull();
+    expect(toModelDto(vrm, { fileUrl: '/f', thumbnailUrl: null }).usable).toBe(true);
+  });
+
+  it('GLB（humanoid 不达标）→ 不可用，原因带 humanoid 覆盖度', () => {
+    const glb = model({
+      format: ModelFormat.Glb,
+      vrmVersion: null,
+      stats: { humanoidMapped: 0, humanoidTotal: 22 } as Record<string, unknown>,
+    });
+    expect(isUsableModel(glb)).toBe(false);
+    expect(unusableReason(glb)).toBe('humanoid 不达标（0/22），未产出 VRM');
+    const dto = toModelDto(glb, { fileUrl: '/f', thumbnailUrl: null });
+    expect(dto.usable).toBe(false);
+    expect(dto.unusableReason).toContain('0/22');
+  });
+
+  it('GLB 且没有 stats → 给出通用原因（不抛错）', () => {
+    const glb = model({ format: ModelFormat.Glb, vrmVersion: null, stats: null });
+    expect(unusableReason(glb)).toContain('未产出 VRM');
+  });
+});
+
+describe('目录导出只含可用模型', () => {
+  function buildService(captured: { modelsWhere?: unknown }): CatalogService {
+    const songs = { find: vi.fn().mockResolvedValue([]) };
+    const motions = { find: vi.fn().mockResolvedValue([]) };
+    const models = {
+      find: vi.fn().mockImplementation((options: { where: unknown }) => {
+        captured.modelsWhere = options.where;
+        return Promise.resolve([model({ id: 7, format: ModelFormat.Vrm })]);
+      }),
+    };
+    const songsService = { toDtos: vi.fn().mockResolvedValue([]) };
+    const motionsService = { toDtos: vi.fn().mockResolvedValue([]) };
+    const modelsService = {
+      toDtos: vi.fn().mockImplementation((rows: CharacterModel[]) =>
+        rows.map((row) => toModelDto(row, { fileUrl: '/f', thumbnailUrl: null })),
+      ),
+      resolveDefaultModelId: vi.fn().mockResolvedValue(7),
+    };
+    const config = { contractVersions: { 'rest-api': '0.5.0' } };
+    return new CatalogService(
+      songs as never,
+      motions as never,
+      models as never,
+      songsService as never,
+      motionsService as never,
+      modelsService as never,
+      config as never,
+    );
+  }
+
+  it('查询条件限定 status=published 且 format=vrm', async () => {
+    const captured: { modelsWhere?: unknown } = {};
+    const bundle = await buildService(captured).exportBundle();
+    expect(captured.modelsWhere).toEqual({ status: PublishStatus.Published, format: ModelFormat.Vrm });
+    expect(bundle.models.map((m) => m.id)).toEqual([7]);
+    expect(bundle.models.every((m) => m.usable)).toBe(true);
+  });
+
+  it('目录指纹同样只统计可用模型（否则客户端会因"不可见变化"反复刷新）', async () => {
+    const captured: { modelsWhere?: unknown } = {};
+    await buildService(captured).version();
+    expect(captured.modelsWhere).toEqual({ status: PublishStatus.Published, format: ModelFormat.Vrm });
+  });
+});
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseKeypointNdjson, sequenceBounds } from '../admin/src/lib/keypoint-sequence';
+import { BONE_SEGMENTS, KEYPOINT_NAMES, PARENT_TABLE } from '../admin/src/lib/skeleton-topology';
+import { renderMotionThumbnail } from '../src/motions/motion-thumbnail';
+import type { KeypointFrame } from '../src/preprocess/mediapipe33';
+
+/**
+ * 动作预览（T-WEB-014）：
+ *   * 服务端：关键点序列 -> 骨架缩略图（列表展示）；
+ *   * 管理端：NDJSON 解析 -> 3D 回放（播放/逐帧/时间轴/变速/循环）。
+ */
+
+/** 造一帧：所有点可见，坐标沿索引铺开（便于验证解析与绘制） */
+function makeFrame(index: number, visibility = 1): KeypointFrame {
+  const points = Array.from({ length: 33 }, (_, point) => [
+    Math.cos((point / 33) * Math.PI * 2) * 0.5,
+    (point / 33) * 1.6 - 0.8,
+    Math.sin((point / 33) * Math.PI * 2) * 0.2,
+    visibility,
+  ]) as KeypointFrame['points'];
+  return { frame: index, timeMs: index * (1000 / 30), points, angles: new Array(9).fill(0.5) };
+}
+
+function ndjson(frames: KeypointFrame[]): string {
+  return frames.map((frame) => JSON.stringify(frame)).join('\n') + '\n';
+}
+
+/** 取 PNG 里偏离背景色的像素数（背景 [24,26,32]） */
+function drawnPixels(png: Buffer): number {
+  let count = 0;
+  for (let i = 0; i + 2 < png.length; i += 1) {
+    // 直接扫原始字节（IDAT 已压缩，这里只做粗略计数：非背景三连出现即算）
+    if (png[i] === 96 && png[i + 1] === 165 && png[i + 2] === 250) count += 1;
+  }
+  return count;
+}
+
+describe('动作缩略图（服务端）', () => {
+  it('关键点序列 -> 合法 PNG（含骨架像素）', () => {
+    const png = renderMotionThumbnail([makeFrame(0), makeFrame(1), makeFrame(2)], { size: 128 });
+    expect(png).not.toBeNull();
+    // PNG magic
+    expect(png!.subarray(0, 8)).toEqual(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    expect(png!.length).toBeGreaterThan(200);
+  });
+
+  it('空序列 / 全部低置信度 -> null（不抛错）', () => {
+    expect(renderMotionThumbnail([])).toBeNull();
+    expect(renderMotionThumbnail([makeFrame(0, 0.01)])).toBeNull();
+  });
+
+  it('尺寸越界抛中文错误（参数非法与"读不到"区分开）', () => {
+    expect(() => renderMotionThumbnail([makeFrame(0)], { size: Number.NaN })).toThrow(/尺寸非法/);
+    expect(renderMotionThumbnail([makeFrame(0)], { size: 8 })).not.toBeNull(); // 夹到 32
+  });
+});
+
+describe('关键点 NDJSON 解析（管理端）', () => {
+  it('解析帧数与帧间隔；数组尺寸固定为 33*3 / 33', () => {
+    const parsed = parseKeypointNdjson(ndjson([makeFrame(0), makeFrame(1), makeFrame(2)]));
+    expect(parsed.frames.length).toBe(3);
+    expect(parsed.frames[0].positions.length).toBe(33 * 3);
+    expect(parsed.frames[0].visibility.length).toBe(33);
+    // 连续帧：帧间隔 = 1000/30 ms
+    expect(parsed.frameIntervalMs).toBeCloseTo(1000 / 30, 3);
+    expect(parsed.durationMs).toBeGreaterThan(0);
+  });
+
+  it('坏行被跳过，好行照常解析（单行损坏不影响整段）', () => {
+    const text = `{"frame":0,"timeMs":0,"points":[[0,0,0,1]],"angles":[]}\n坏行\n${JSON.stringify(makeFrame(1))}\n`;
+    const parsed = parseKeypointNdjson(text);
+    expect(parsed.frames.length).toBe(2);
+  });
+
+  it('空文本 -> 0 帧（页面据此提示"先预处理"）', () => {
+    expect(parseKeypointNdjson('').frames.length).toBe(0);
+    expect(parseKeypointNdjson('\n\n').frames.length).toBe(0);
+  });
+
+  it('包围盒按整段计算（用于自动取景）', () => {
+    const parsed = parseKeypointNdjson(ndjson([makeFrame(0), makeFrame(10)]));
+    const bounds = sequenceBounds(parsed.frames);
+    expect(bounds).not.toBeNull();
+    expect(bounds!.max[1]).toBeGreaterThan(bounds!.min[1]);
+  });
+});
+
+describe('33 点拓扑（管理端绘制用）', () => {
+  it('33 个点、父表长度一致、骨段索引合法', () => {
+    expect(KEYPOINT_NAMES.length).toBe(33);
+    expect(PARENT_TABLE.length).toBe(33);
+    expect(BONE_SEGMENTS.length).toBeGreaterThan(20);
+    for (const [child, parent] of BONE_SEGMENTS) {
+      expect(child).toBeGreaterThanOrEqual(0);
+      expect(child).toBeLessThan(33);
+      expect(parent).toBeGreaterThanOrEqual(0);
+      expect(parent).toBeLessThan(33);
+    }
+  });
+});