feat(models): 骨骼重绑定——修复 MMD 模型 humanoid 恒为 0/22（契约 skeleton-topology 0.2.0）

根因：normalizeBoneName() 只保留 a-z0-9，**中日文字符被整个丢掉**：
'上半身'/'左ひじ'/'首' 归一化后都是空串，MMD 模型的骨名必然失配，
humanoid 覆盖率恒为 0/22 -> 不可驱动 -> 只能回退交付 GLB 并标记不可用。

修复：
1. 归一化保留 CJK/平假名/片假名/长音符/々，并把全角 ASCII（足ＩＫ）折成半角；
2. 候选表补齐四类命名（22 根 x 8-13 个候选）：VRoid / Mixamo /
   MMD 标准骨架（下半身/上半身/上半身2/首/頭/左肩/左腕/左ひじ/左手首/
   左足/左ひざ/左足首/左つま先）/ 常见中文名（臀部/头/脖子/左大臂/左大腿…）；
   精确匹配保证「左足ＩＫ」不会抢占「左足」；
3. Windows 客户端 humanoid_map.gd 的 CANDIDATES 由服务端表**生成写入**，
   normalize() 同步改造，parity 测试断言键/候选顺序完全一致；
4. 契约 skeleton-topology -> 0.2.0：新增 §6「内部动作标准与模型骨骼重绑定」
   （三层标准、22/16 根骨、归一化与匹配规则、实测记录）；
5. 新增 4 项测试；规模 17 文件 / 229 项。

实测：奥黛塔 PMX 0/22 -> 21/22、初音未来 PMX 0/22 -> 19/22，均 drivable=true 且产出 VRM。
版本 0.4.0。

DSH.md

@@ -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）。

README.md

@@ -10,7 +10,15 @@ 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.3.0**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+
+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 +85,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.4.0/opendance-web-v0.4.0.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.4.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.4.0.tar.gz && cd opendance-web-v0.4.0
    bash deploy/init-env.sh
    ```
 
@@ -155,8 +163,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.4.0.tar.gz
+cd opendance-web-v0.4.0
 bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
 bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 ```
@@ -329,12 +337,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              # 229 项单元测试 / 17 个文件(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)
 npm run build             # 生产构建
 npm run start:prod &      # 启动
 npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -357,7 +365,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` | 单次转换超时(毫秒) |

README.txt

@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.2.5  使用说明
+OpenDance Studio -- Web 管理服务端 v0.4.0  使用说明
 ================================================================
 
 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,31 @@ OpenDance Studio -- Web 管理服务端 v0.2.5  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。
 
+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 +115,11 @@ v0.2.1 修订
    2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
         本项目不会创建数据库本身
    3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.2.5.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.4.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.4.0.tar.gz && cd opendance-web-v0.4.0
         bash deploy/init-env.sh
    5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
         bash deploy/install.sh
@@ -152,8 +177,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.4.0.tar.gz
+  cd opendance-web-v0.4.0
   bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
   bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 
@@ -328,12 +353,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              # 229 项单元测试 / 17 个文件(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)
   npm run build             # 生产构建
   npm run start:prod &      # 启动
   npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)

contracts/VERSION

@@ -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.5.0
+skeleton-topology: 0.2.0
+model-formats: 0.5.0
 database: 0.3.0

contracts/data-models.md

@@ -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`）。
@@ -96,8 +96,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 | 读 | |

contracts/model-formats.md

@@ -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**。
 

contracts/skeleton-topology.md

@@ -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`），不影响驱动与评分。

deploy/.env.example

@@ -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" 当命令）

project.yaml

@@ -1,5 +1,5 @@
 project: opendance-web-server
-version: 0.2.5
+version: 0.4.0
 repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0
@@ -60,7 +60,7 @@ tasks:
     status: done
 
 deliverable:
-  artifact: opendance-web-v0.2.5.tar.gz
+  artifact: opendance-web-v0.4.0.tar.gz
   packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
   includes:
     - web-server/          # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）

scripts/package-release.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # ============================================================
-# 打包发布产物：opendance-web-v0.2.5.tar.gz
+# 打包发布产物：opendance-web-v0.4.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.4.0}"
 NAME="opendance-web-v${VERSION}"
 OUT_DIR="$REPO_ROOT/dist-release"
 STAGE="$OUT_DIR/$NAME"

tasks/005-model-upload.md

@@ -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] 段落
 ```
 

tasks/007-upload-review.md

@@ -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
 ```
 

web-server/admin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opendance-admin",
   "private": true,
-  "version": "0.2.5",
+  "version": "0.4.0",
   "type": "module",
   "description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
   "scripts": {

web-server/admin/src/api/types.ts

@@ -160,6 +160,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;

web-server/admin/src/components/Layout.tsx

@@ -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">

web-server/admin/src/components/ModelReviewPanel.tsx

@@ -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>

web-server/admin/src/lib/version.ts

@@ -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}`;

web-server/admin/src/pages/Models.tsx

@@ -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>

web-server/admin/src/styles.css

@@ -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;

web-server/admin/src/vite-env.d.ts

@@ -7,3 +7,6 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv;
 }
+
+/** 构建期注入的应用版本号（来自 web-server/package.json） */
+declare const __APP_VERSION__: string;

web-server/admin/vite.config.ts

@@ -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,

web-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendance-web-server",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
   "license": "MIT",
   "private": true,

web-server/src/catalog/catalog.service.ts

@@ -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({

web-server/src/config/configuration.ts

@@ -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),

web-server/src/config/contract-versions.ts

@@ -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.5.0',
+  'skeleton-topology': '0.2.0',
+  'model-formats': '0.5.0',
   database: '0.3.0',
 });
 

web-server/src/models/model-inspector.ts

@@ -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;
 }

web-server/src/models/model.serializer.ts

@@ -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,

web-server/src/models/models.service.ts

@@ -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;

web-server/test/model-inspector.spec.ts

@@ -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 运行」为主，同时兼容从仓库根运行 */

web-server/test/model-usability.spec.ts

@@ -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 });
+  });
+});