chore(release): 打包脚本默认版本改为 0.2.1

现象：
  ./deploy/.env: line 53: Miku.pmx: command not found
  [install] 第 53 行执行失败（退出码 127）

根因：deploy/.env.example 的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格
却没加引号，install.sh 用 `set -a; . deploy/.env` 载入时被切成
「赋值 + 命令」，Miku.pmx 被当成命令执行。

修复：
1. 模板改为 MODEL_CONVERT_PMX="Hatsune Miku.pmx"（占位符值同样加引号）；
2. 新增 deploy/env-lib.sh：.env 语法预检，install.sh / ctl.sh 在 source
   之前检查，报错给出「哪一行 / 原文 / 改法」， 与反引号建议单引号；
3. install.sh 的 ERR trap 补上出错文件名（lineno 属于被 source 的 .env，
   只报行号无法定位）；
4. 新增 test/env-file.spec.ts 12 项回归测试，锁住「模板可被 shell 原样载入」；
5. 版本升到 0.2.1，README(.md/.txt)/DSH.md 补 .env 写法约定、FAQ 与测试数量。

DSH.md

@@ -1,4 +1,4 @@
-# DSH.md -- opendance-web（OpenDance Studio 项目一：Web 管理服务端）
+# DSH.md -- opendance-web(OpenDance Studio 项目一：Web 管理服务端)
 
 ## 0. 本文件的作用
 
@@ -31,9 +31,9 @@ opendance-web  ←── 本仓库
 | 管理前端 | React 18 + Vite + TypeScript |
 | 3D 预览 | three.js + @pixiv/three-vrm |
 | 多格式解析 | BVH / VMD 内置纯 TS 解析器；FBX/glTF 走可选外部 Assimp |
-| 模型主力格式 | **GLB / VRM 为一等公民**：`.glb`/`.vrm`/`.gltf` 直接导入（不重编码），`.pmx`/`.fbx` 服务端转换（优先 GLB、其次 VRM） |
+| 模型主力格式 | **GLB / VRM 为一等公民**: `.glb`/`.vrm`/`.gltf` 直接导入（不重编码），`.pmx`/`.fbx` 服务端转换(优先 GLB、其次 VRM) |
 | 模型检查 / 缩略图 | `models/model-inspector.ts`（面数 / 顶点 / 贴图 / **骨骼树** / humanoid 覆盖 / 可驱动性）、`models/model-thumbnail.ts`（纯 TS 光栅化 PNG，零原生依赖） |
-| 模型压缩包 | 纯 TS ZIP 读取器（`common/zip-reader.ts`）+ 自动搜索包内模型 + 外部 Assimp 转换（`models/model-convert.ts`）；GLB 打包 `models/gltf-packer.ts`、贴图内嵌 `models/glb-textures.ts`、GLB->VRM 封装 `models/vrm-writer.ts` |
+| 模型压缩包 | 纯 TS ZIP 读取器(`common/zip-reader.ts`)+ 自动搜索包内模型 + 外部 Assimp 转换（`models/model-convert.ts`）；GLB 打包 `models/gltf-packer.ts`、贴图内嵌 `models/glb-textures.ts`、GLB->VRM 封装 `models/vrm-writer.ts` |
 | 默认模型种子 | `web-server/src/config/default-model.ts`（服务端/CLI 写入，运行期只读） |
 | 认证 | **本版本不含认证**（内网部署）；上线前须补 >= T-WEB-011 |
 
@@ -69,7 +69,7 @@ opendance-web  ←── 本仓库
 opendance-web/
 ├── project.yaml                 # 任务清单与状态
 ├── DSH.md                       # 本文件
-├── tasks/                       # 单任务说明书（001~010）
+├── tasks/                       # 单任务说明书(001~010)
 ├── contracts/                   # ★ 跨端契约（权威）
 │   ├── VERSION                  # 契约版本（唯一来源）
 │   ├── rest-api.yaml            # OpenAPI 3.0
@@ -80,11 +80,11 @@ opendance-web/
 │   ├── database.md              # 现有 MySQL 连接与迁移约定
 │   └── open-source-credits.md   # 开源声明锚点（三端共用）
 ├── web-server/                  # NestJS 服务端
-│   ├── src/                     # 源码（entities / models / preprocess）
+│   ├── src/                     # 源码(entities / models / preprocess)
 │   │   ├── common/zip-reader.ts # 纯 TS ZIP 读取器（STORE/DEFLATE、ZIP64、zip-slip 防护）
 │   │   ├── models/              # 模型上传 + 自动搜索/转换 + 分析 + 缩略图
 │   │   │   ├── model-convert.ts         # 选主模型 -> 直接导入或 Assimp 转换 -> 回读校验
-│   │   │   ├── gltf-packer.ts           # glTF（.gltf +.bin + 贴图）-> GLB 打包
+│   │   │   ├── gltf-packer.ts           # glTF(.gltf +.bin + 贴图)-> GLB 打包
 │   │   │   ├── glb-textures.ts          # 把外部贴图内嵌进 GLB 的 BIN chunk
 │   │   │   ├── vrm-writer.ts            # GLB -> VRM 1.0（写 VRMC_vrm 扩展）
 │   │   │   ├── model-inspector.ts       # 面数 / 顶点 / 骨骼树 / humanoid 覆盖 / 可驱动性
@@ -92,25 +92,26 @@ opendance-web/
 │   │   │   ├── default-model-source.ts  # 渲染 / 写入 src/config/default-model.ts
 │   │   │   └── vrm-inspector.ts
 │   │   ├── config/default-model.ts      # 默认模型种子（由审核 / CLI 写入，运行期只读）
-│   │   ├── migrations/          # TypeORM 迁移（AddModelConversionFields / AddModelStats）
+│   │   ├── migrations/          # TypeORM 迁移(AddModelConversionFields / AddModelStats)
 │   │   └── preprocess/          # BVH / VMD / FBX -> MediaPipe33
 │   │       ├── vmd-parser.ts    # VMD 二进制 + Shift-JIS + 贝塞尔插值
-│   │       ├── mmd-skeleton.ts  # 标准 MMD 骨架（静止比例实测自参考 PMX）
+│   │       ├── mmd-skeleton.ts  # 标准 MMD 骨架(静止比例实测自参考 PMX)
 │   │       ├── mmd-pose.ts      # MMD FK + 两骨骼腿部 IK + 左手系->右手系 Z 镜像
-│   │       └── retarget.ts      # worldFramesToKeypointFrames()：BVH / VMD 共用
+│   │       └── retarget.ts      # worldFramesToKeypointFrames():BVH / VMD 共用
 │   ├── admin/                   # React 管理端
 │   │   ├── src/components/ModelReviewPanel.tsx  # 模型审核面板 + 骨骼详细界面
 │   │   └── src/lib/bone-tree.ts                 # 骨骼树过滤（搜索保留祖先链）
-│   ├── test/                    # 单元测试 + 端到端冒烟（10 文件 / 168 项）
+│   ├── test/                    # 单元测试 + 端到端冒烟（11 文件 / 180 项）
 │   │                            #   mmd-vmd 31 / model-archive 24 / model-inspector 25
 │   │                            #   / model-thumbnail 8 / admin-bone-filter 8
 │   │                            #   / preprocess 25 / init-env 16 / admin-port 16
 │   │                            #   / access-log 9 / vrm-inspector 6
 │   └── scripts/                 # migrate.mjs / check-contracts.mjs / check-routes.mjs
-│                                #   / inspect-vmd.mjs（VMD 诊断）
+│                                #   / inspect-vmd.mjs(VMD 诊断)
 │                                #   / import-default-model.mjs（默认模型导入 / 补写源码）
 ├── deploy/                      # ★ 业务服务部署（不含 MySQL、不含反代）
 │   ├── init-env.sh              # ★ 首次启动的.env 交互引导（install.sh 缺.env 时调用）
+│   ├── env-lib.sh               # ★ deploy/.env 语法预检（被 install.sh / ctl.sh 引用）
 │   ├── install.sh               # 一键部署（systemd / OpenRC / SysVinit / 后台进程）
 │   ├── uninstall.sh
 │   ├── ctl.sh                   # 无 init 系统时的进程控制
@@ -126,15 +127,15 @@ opendance-web/
 ## 6. 硬性约束
 
 1. **不部署 MySQL**。数据库为部署方提供的现有实例，连接信息只经环境变量注入。
-   **也不使用 Docker**，**也不部署反向代理**：本端只提供业务服务
-   （API + 自带的管理端页面），反代由另外的服务负责，
+   **也不使用 Docker**, **也不部署反向代理**：本端只提供业务服务
+   (API + 自带的管理端页面)，反代由另外的服务负责，
    本项目只在 `deploy/proxy/` 下提供 IIS 与 nginx 的配置说明文档。
    业务服务监听**两个端口**（软件 API 端口 `PORT` + 管理端端口 `ADMIN_PORT`），
    约定见 9。
 2. **`DB_SYNCHRONIZE` 生产必须为 `false`**，所有表结构变更走 migration；每个
    migration 必须可逆。
 3. **绝不把凭证写入仓库**。`.env` 已在 `.gitignore` 中，只提交 `.env.example`。
-4. **来源五元组强制必填**：`source_type` / `source_name` / `source_url` / `license`
+4. **来源五元组强制必填**: `source_type` / `source_name` / `source_url` / `license`
    / `author`。任何资产入库缺一即 400。
 5. **契约先行**：改接口先改 `contracts/`，再提升 `contracts/VERSION`，同步
    `web-server/src/config/contract-versions.ts`，最后才改实现。
@@ -142,12 +143,12 @@ opendance-web/
 6. **不使用 SMPL** 及其衍生拓扑（许可风险），统一 MediaPipe 33 点。
 7. **上传文件永不使用原始文件名作为路径**，一律 `sha256` 去重后归档。
 8. **GLB / VRM 是模型主力格式**：服务端与客户端（Godot 内置 `GLTFDocument`）都把
-   这两种格式作为一等公民。`.glb` / `.vrm` / `.gltf` **直接导入、不重编码**；
+   这两种格式作为一等公民。`.glb` / `.vrm` / `.gltf` **直接导入、不重编码**;
    `.pmx` / `.fbx` 才由服务端转换，且**优先 GLB、其次 VRM**。
    humanoid 候选表必须与客户端 `opendance-windows/src/model/humanoid_map.gd` 逐字对齐，
    由 `test/model-inspector.spec.ts` 断言兜底。
 9. **模型上传一律 `pending`（待审核）**：上传不得自动发布、不得自动设为默认模型。
-   默认模型只在审核通过勾选 `setPrimary:true`（`POST /api/reviews/model/:id/approve`）
+   默认模型只在审核通过勾选 `setPrimary:true`(`POST /api/reviews/model/:id/approve`)
    或显式调用 `POST /api/models/:id/primary`（仅 `published`，否则 409）时设置。
 
 ## 7. 每任务的执行步骤
@@ -186,7 +187,7 @@ DB_HOST DB_PORT DB_USER DB_PASS DB_NAME
 DB_SYNCHRONIZE=false
 PORT=3000                   # 软件 API 端口（客户端调用，不含管理页面）
 ADMIN_PORT=3001             # 管理端端口（默认 PORT + 1；等于 PORT 为单端口兼容模式）
-HOST=0.0.0.0                # 软件 API 监听地址（未设置时默认即 0.0.0.0）
+HOST=0.0.0.0                # 软件 API 监听地址(未设置时默认即 0.0.0.0)
 ADMIN_HOST=0.0.0.0          # 可选，管理端监听地址，默认跟随 HOST
 STORAGE_DIR=/data/storage
 UPLOAD_MAX_BYTES=536870912
@@ -202,10 +203,10 @@ CONTRACTS_DIR=/contracts    # 可选，读取实时契约版本
 
 ## 9. 双端口约定（软件 API 端口 / 管理端端口）
 
-- **软件 API 端口**：`PORT`，默认 **3000**。给 Windows/Godot 客户端与 Android App
-  调用，只提供 `/api`、`/health`、`/static`、`/contracts`；**不提供管理页面**，
+- **软件 API 端口**: `PORT`，默认 **3000**。给 Windows/Godot 客户端与 Android App
+  调用，只提供 `/api`、`/health`、`/static`、`/contracts`; **不提供管理页面**,
   `/`、`/songs` 等一律 404（有意设计，避免管理页暴露在客户端调用的端口上）。
-- **管理端端口**：`ADMIN_PORT`，默认 `PORT + 1`（即 **3001**）。给浏览器访问，
+- **管理端端口**: `ADMIN_PORT`，默认 `PORT + 1`（即 **3001**）。给浏览器访问，
   提供管理页面（含 SPA 深链接回退）与上面全部接口。
 - `ADMIN_HOST` 可选，默认跟随 `HOST`；可用它把管理端限制在本机或内网。
 - `ADMIN_PORT === PORT` 为**单端口兼容模式**：管理页面回到 API 端口，日志提示
@@ -215,7 +216,7 @@ CONTRACTS_DIR=/contracts    # 可选，读取实时契约版本
 - 反向代理按用途分别转发两个端口；`/health` 两个端口都提供，可用于存活探测。
   细则见 `deploy/proxy/README.md` 与 `tasks/010-deploy.md`。
 
-## 10. VMD 动作通路（MikuMikuDance）
+## 10. VMD 动作通路(MikuMikuDance)
 
 ```
 .vmd ─▶ vmd-parser.ts ─▶ mmd-skeleton.ts ─▶ mmd-pose.ts ─▶ retarget.ts
@@ -227,16 +228,16 @@ CONTRACTS_DIR=/contracts    # 可选，读取实时契约版本
 - VMD 二进制：30 字节头 + 20 字节 Shift-JIS 模型名 + 111 字节/条的骨骼关键帧 + morph 段；
   只有旋转（少数骨骼带位移）、不含骨骼长度，因此必须靠 `mmd-skeleton.ts` 的标准骨架
   （静止比例从参考 PMX 实测）做 FK。
-- **腿部驱动自动判定**：`足ＩＫ` 有非零位移 -> 两骨骼解析 IK（膝盖朝角色正面弯，
+- **腿部驱动自动判定**: `足ＩＫ` 有非零位移 -> 两骨骼解析 IK（膝盖朝角色正面弯，
   不可达时收敛为伸直）；否则用 FK 旋转。部分动作数据把腿烘焙成 FK。
-- **手性**：MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) -> (-x,-y,z,w)`、位移 z 取反）
+- **手性**: MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) -> (-x,-y,z,w)`、位移 z 取反）
   后进入右手系通路。由真实数据对照实验确定：腿部烘焙为 FK 的样本中，`zMirrored`
   下「膝盖朝前」占 94.1%，不转换仅 5.9%。
 - `worldFramesToKeypointFrames()` 为 BVH / VMD 共用：骨盆归零 / 自适应缩放 /
   图像空间投影 / 9 个关节角完全一致。
 - 诊断工具：`node scripts/inspect-vmd.mjs 动作.vmd [--frames N] [--json out.json]`
   （打印头部/模型名/帧数/轨道数、未识别骨骼、IK 还是 FK、关键点序列异常统计、膝肘角分布）。
-- 契约 `contracts/model-formats.md` 2.3；测试 `test/mmd-vmd.spec.ts`（31 项）。
+- 契约 `contracts/model-formats.md` 2.3；测试 `test/mmd-vmd.spec.ts`(31 项)。
 
 ## 11. 模型格式策略、转换、分析与审核
 
@@ -252,7 +253,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
                                                   ├─ 2) 失败 ->.gltf -> gltf-packer.ts 打包回 GLB
                                                   ├─ 3) MODEL_CONVERT_FORMAT=vrm -> vrm-writer.ts 补 VRMC_vrm
                                                   └─ 每步 assimp info 回读校验
-                  ─▶ 入库（status=pending）
+                  ─▶ 入库(status=pending)
                   ─▶ model-inspector.ts 分析 -> models.stats
                   ─▶ model-thumbnail.ts 缩略图 -> models.thumbnail_asset_id
 ```
@@ -266,7 +267,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
     回读校验 -> 回退。
   - `models/gltf-packer.ts`：把 Assimp 导出的分离 `.gltf` + `.bin` + 贴图自行打包成 GLB。
   - `models/glb-textures.ts`：把 GLB 里 Assimp 写成外部 URI 的贴图内嵌进 BIN chunk。
-  - `models/vrm-writer.ts`：GLB -> VRM 1.0，只改 JSON chunk 写 `extensions.VRMC_vrm`，
+  - `models/vrm-writer.ts`: GLB -> VRM 1.0，只改 JSON chunk 写 `extensions.VRMC_vrm`,
     不做任何几何/材质损失。
   - `models/model-inspector.ts`：解析 GLB/VRM，算面数 / 顶点 / 贴图 / **骨骼树** /
     humanoid 覆盖 / 可驱动性（缺哪些必需骨骼）/ warnings。
@@ -274,20 +275,20 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
   - `models/default-model-source.ts`：渲染 / 写入 `src/config/default-model.ts`。
   - `config/default-model.ts`：默认模型种子（审核 / CLI 写入，运行期只读）。
 - **压缩包自动搜索**：优先级 `.vrm` -> `.glb` -> `.gltf` -> `.pmx` -> `.fbx`；同一优先级内
-  按 `MODEL_CONVERT_PMX` 指名字 -> 目录最浅 -> 文件最大。命中 glTF 系格式时**直接导入**，
+  按 `MODEL_CONVERT_PMX` 指名字 -> 目录最浅 -> 文件最大。命中 glTF 系格式时**直接导入**,
   只有 `.pmx`/`.fbx` 才转换。压缩包原件存为 `model-archive` 资产。
-- **转换与回退**：GLB 直出失败 -> glTF 再自行打包；`MODEL_CONVERT_FORMAT=vrm` 时在 GLB
-  之上补 `VRMC_vrm`（humanoid 不全则**回退交付 GLB**并把缺失骨骼写进 `conversion_note`）。
+- **转换与回退**: GLB 直出失败 -> glTF 再自行打包；`MODEL_CONVERT_FORMAT=vrm` 时在 GLB
+  之上补 `VRMC_vrm`(humanoid 不全则**回退交付 GLB**并把缺失骨骼写进 `conversion_note`)。
   **每一步产物都必须用 `assimp info` 回读校验**：实测 Assimp 会"写出损坏文件"
-  （FBX 导出退出码 11、回读报 `FBX-DOM no Objects dictionary found`），只看退出码
+  (FBX 导出退出码 11、回读报 `FBX-DOM no Objects dictionary found`)，只看退出码
   会把坏文件入库。
-- **入库后自动**：`inspectModelFile()` 分析写入 `models.stats`
+- **入库后自动**: `inspectModelFile()` 分析写入 `models.stats`
   （迁移 `AddModelStats1789460000000`，新增 `models.stats TEXT`）；
   `renderModelThumbnail()` 写入 `models.thumbnail_asset_id` / `thumbnailUrl`。
   **两者都是"尽力而为"**：失败只记 warning，不影响入库。
-- **状态与默认模型（硬性）**：上传**一律 `status=pending`**，`is_primary=false`，
+- **状态与默认模型（硬性）**：上传**一律 `status=pending`**, `is_primary=false`,
   不自动发布、不自动设为默认。默认模型只在
-  ① 审核通过带 `setPrimary:true`（`POST /api/reviews/model/:id/approve`）或
+  ① 审核通过带 `setPrimary:true`(`POST /api/reviews/model/:id/approve`)或
   ② `POST /api/models/:id/primary`（仅 `published`，否则 **409**）时设置，此时写库
   `is_primary` 并把身份写进源码种子。
   `GET /api/catalog/export` 的 `defaultModelId` 解析顺序为 `DEFAULT_MODEL_ID` -> 源码种子
@@ -295,17 +296,17 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
   -> 已发布且 is_primary 的 VRM -> 任意已发布 VRM -> id 最小的已发布模型。
 - **溯源**：压缩包原件记入 `models.source_asset_id`
   （迁移 `AddModelConversionFields1789450000000`）；`models.conversion_note` 记转换说明。
-- **失败**：包内没有可用模型、Assimp 不可用、两条路径都失败 -> **HTTP 422**，
+- **失败**：包内没有可用模型、Assimp 不可用、两条路径都失败 -> **HTTP 422**,
   不产生模型记录。
-- **文件名编码**：`common/upload.util.ts` 的 `decodeUploadName()` 修正 multipart
+- **文件名编码**: `common/upload.util.ts` 的 `decodeUploadName()` 修正 multipart
   文件名的 latin1/UTF-8 乱码（中文文件名原先存成 `模å_...`）。
-- 契约：`contracts/model-formats.md` 1.1、`contracts/data-models.md` 4.1；
+- 契约：`contracts/model-formats.md` 1.1、`contracts/data-models.md` 4.1;
   DTO 新增 `conversionNote` / `fileSha256` / `stats` / `thumbnailUrl`。
 
 ### 11.1 审核要求（模型）
 
 管理端「审核」页对 `pending` 模型展示 **模型审核面板**
-（`admin/src/components/ModelReviewPanel.tsx`）：
+(`admin/src/components/ModelReviewPanel.tsx`):
 
 - **指标**：体积 / 格式 / 容器 / VRM 版本 / 面数 / 顶点 / 网格 / 材质 / 贴图 /
   骨骼 / 节点 / 形变目标 / 动画。
@@ -317,28 +318,34 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
 - **通过**：可勾选「同时设为全局默认模型」-> 请求体 `setPrimary:true`。
 - **驳回**：必须填写审核意见（400）。
 - 实测：`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200、
-  `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...`；
+  `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...`;
   重建后 `defaultModelId` 由 VRM 变为 **22**。
 
-### 11.2 实测数据（v0.2.0）
+### 11.2 实测数据(v0.2.0)
 
 - 上传含 `Hatsune Miku.pmx` 的 MMD 压缩包 -> **HTTP 201 / 0.86s**、`format=glb`、
-  `status=pending`、`conversionNote=Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`；
+  `status=pending`、`conversionNote=Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`;
   分析 `vertices=7155 triangles=9071 materials=3 textures=2 images=2 nodes=240
   bones=238 skins=1 morphTargets=0 humanoidMapped=0/22 drivable=false
-  maxBoneDepth=23`，`missingRequiredBones` 为全部 16 根（日文 MMD 骨名无法映射）。
-- 直接上传 `.glb`：**HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`，
+  maxBoneDepth=23`, `missingRequiredBones` 为全部 16 根（日文 MMD 骨名无法映射）。
+- 直接上传 `.glb`: **HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`,
   入库文件 sha256 与源文件**一致**。
 - 缩略图：512x512 PNG / 15,043 字节，纯 TS 光栅化（含蒙皮），目视确认为居中的
-  T-pose 角色图；真实 10MB VRM（83 关节、5307 顶点）单张耗时 60-121ms（中位 79ms）。
-- 管理端 3D 预览放开到 `vrm/glb/gltf`（`fbx` 仍提示"仅归档，请先转换为 GLB/VRM"）；
+  T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。
+- 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档，请先转换为 GLB/VRM");
   列表页显示 40px 缩略图。
-- 测试：`npx vitest run` -> **10 个文件 / 168 项通过**
-  （`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、
+- 测试：`npx vitest run` -> **11 个文件 / 180 项通过**
+  (`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）。
 
-## 12. 首次启动的.env 引导（deploy/init-env.sh）与监听地址
+## 12. 首次启动的.env 引导（deploy/init-env.sh）、.env 预检与监听地址
+
+- `deploy/env-lib.sh`: `.env` 语法预检。`install.sh` / `ctl.sh` 用
+  `set -a; . deploy/.env` 载入配置时 shell 会真的执行该文件，值含空格却未加引号
+  会被切成「赋值 + 命令」（实测报 `line 53: Miku.pmx: command not found`，退出码 127）。
+  两个脚本在 source 之前调用预检，输出「哪一行、原文、改法」；
+  模板中带空格的值统一写成 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`。
 
 - `deploy/init-env.sh`：交互式逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS /
   DB_NAME / PORT / ADMIN_PORT / HOST`，回车保留默认；口令 `read -rs` 不回显、
@@ -346,22 +353,22 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
   （口令只经环境变量传递、失败仅告警）；只替换/追加这 8 个键、保留模板注释，
   写完 `chmod 600` 并回读校验；结尾打印摘要（口令 `***`）与变更列表。
 - 开关：`--force` / `--check` / `-y|--yes|--non-interactive` / `-i|--interactive` /
-  `--skip-db-check` / `--dir` / `--env-file` / `--example` / `--timeout` / `-h`；
+  `--skip-db-check` / `--dir` / `--env-file` / `--example` / `--timeout` / `-h`;
   环境变量 `OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` /
   `OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` /
   `OPENDANCE_PROMPT_TIMEOUT`。
-- **非交互绝不挂住**：stdin 非 TTY 且是 `</dev/null`/关闭，或带 `-y` 等开关 ->
+- **非交互绝不挂住**: stdin 非 TTY 且是 `</dev/null`/关闭，或带 `-y` 等开关 ->
   只校验不提问；所有 read 带超时，EOF/超时立即 `exit 1`。
 - 接入点：`deploy/install.sh` 缺 `deploy/.env` 时先调用 `init-env.sh` 引导，
   失败才 die（若 `$APP_DIR/deploy/.env` 已存在则复用，保持原语义）。
-- **监听地址默认 `0.0.0.0`**：`configuration.ts` 的
-  `bindHost = process.env.HOST?? '0.0.0.0'`，`adminHost` 默认跟随 `HOST`
+- **监听地址默认 `0.0.0.0`**: `configuration.ts` 的
+  `bindHost = process.env.HOST?? '0.0.0.0'`, `adminHost` 默认跟随 `HOST`
   （同样回落 `0.0.0.0`）；`deploy/.env.example` 与 `web-server/.env.example`
-  均为 `HOST=0.0.0.0`；`install.sh` 的 `BIND_HOST="${HOST:-0.0.0.0}"`，
+  均为 `HOST=0.0.0.0`; `install.sh` 的 `BIND_HOST="${HOST:-0.0.0.0}"`,
   `init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
-  （`install.sh` 的 `HEALTH_HOST`/`API_HOST` 是**本机健康检查**用的回环地址，
+  (`install.sh` 的 `HEALTH_HOST`/`API_HOST` 是**本机健康检查**用的回环地址，
   与对外监听的默认值无关。）
-- 测试 `test/init-env.spec.ts`（16 项）。
+- 测试 `test/init-env.spec.ts`(16 项)。
 
 ## 13. 上下文超标时的拆分策略
 

README.md

@@ -0,0 +1,539 @@
+# opendance-web
+
+OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 MySQL 实例)。
+
+管理歌曲、VRM 模型与动作来源,是 Windows 客户端与 Android 辅助 App 的唯一数据源与**契约权威**。
+
+> **本服务端不部署、不管理 MySQL。** 数据库为部署方提供的现有实例,连接信息通过 `.env` 注入。
+>
+> **本服务端也不部署反向代理。** 只提供业务服务(API + 自带管理端页面),反代由另外的服务/团队负责,本仓库仅在 `deploy/proxy/` 下提供配置说明文档。
+
+## 状态
+
+**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.1**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+
+v0.2.1 修订:
+
+1. **修复部署失败**:`deploy/.env.example` 里 `MODEL_CONVERT_PMX=Hatsune Miku.pmx` 的值含空格却没加引号,`install.sh` 用 `set -a; . deploy/.env` 载入时把 `Miku.pmx` 当命令执行,报 `command not found`(退出码 127);模板改为带引号写法;
+2. **新增 `.env` 语法预检**(`deploy/env-lib.sh`):`install.sh` 与 `ctl.sh` 在 source 之前先检查,直接给出哪一行、原文、改法,不再出现看不懂的 127 报错;
+3. 安装失败提示带上出错文件名(`.env` 被 source 时行号属于 `.env`,只报行号无法定位);
+4. 新增 12 项回归测试(`test/env-file.spec.ts`),锁住「模板可被 shell 原样载入」这条线。
+
+v0.2.0 主要变更:
+
+1. **GLB / VRM 确定为模型主力格式**,服务端与客户端分别落实支持库;
+2. **模型管理**:`.glb/.vrm` 直接导入;`.pmx/.fbx` 服务端**优先转 GLB、其次 VRM**;压缩包**自动搜索**包内可用模型;入库自动生成**缩略图**与**模型分析**;
+3. **模型审核**:上传一律 `pending`,审核界面含**骨骼详细预览**(后期评分依据);
+4. 新增**历史模型回填**(`POST /api/models/:id/reanalyze` + `scripts/reanalyze-models.mjs`);
+5. **管理端口与软件 API 端口分开**(`PORT` / `ADMIN_PORT`),动作数据支持 **VMD**,模型支持压缩包**转换导入**。
+
+## 部署到 Linux 服务器(业务服务,不含反向代理)
+
+### 1. 初次部署(从零跑起来)
+
+按顺序做,每步都有验证方法:
+
+1. 准备一台 Linux 服务器,**以 root 登录**(不需要 sudo),装好 Node.js 22+
+
+   ```bash
+   node -v                      # 期望 v22 或更高
+   ```
+
+2. 准备一个现有的 MySQL / MariaDB 实例,并建好库与账号(见下方[前置要求](#前置要求))
+   本项目**不会创建数据库本身**
+
+3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
+
+   ```bash
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/opendance-web-v0.2.1.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/SHA256SUMS
+   sha256sum -c SHA256SUMS      # 期望输出 "OK"
+   ```
+
+4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
+
+   ```bash
+   tar -xzf opendance-web-v0.2.1.tar.gz && cd opendance-web-v0.2.1
+   bash deploy/init-env.sh
+   ```
+
+5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
+
+   ```bash
+   bash deploy/install.sh
+   ```
+
+6. 验证(把 `<服务器地址>` 换成实际地址)
+
+   ```bash
+   curl -fsS http://<服务器地址>:3000/health          # 期望 {"status":"ok",...}
+   curl -sI  http://<服务器地址>:3001/ | head -1      # 期望 200,管理端页面
+   curl -sI  http://<服务器地址>:3000/ | head -1      # 期望 404,API 端口不提供管理页
+   ```
+
+7. 可选:回填历史模型的分析与缩略图(新装可跳过)
+
+   ```bash
+   cd /opt/opendance/web-server
+   node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000
+   ```
+
+8. 浏览器打开 `http://<服务器地址>:3001/` 进入管理端,上传曲目/动作/模型并审核
+   模型上传后状态为**待审核**,审核通过才会被客户端拉取
+
+**安全约定**:`deploy/.env` 已被 `.gitignore` 忽略,不要提交;文档、截图、工单里也不要贴真实的数据库口令、内网地址或域名,需要时用 `<占位符>` 代替。
+
+### 2. 职责边界
+
+本端只提供业务服务:NestJS API + 管理端页面。反向代理由另外的服务/团队负责,本项目不安装、不配置任何反代软件,只在 `deploy/proxy/` 下提供 IIS 与 nginx 的配置说明文档。
+
+### 3. 部署形态
+
+Node 业务服务由系统服务托管,**同时监听两个端口**,职责分开:
+
+| 端口 | 默认 | 提供内容 |
+| --- | --- | --- |
+| 软件 API 端口(给 Windows/Godot 客户端与 Android App) | 3000 | `/api/` REST API、`/health` 健康检查、`/static/` 上传文件、`/contracts/` 契约快照;该端口**不提供管理页面**,`/` 与 `/songs` 等一律返回 404(有意设计) |
+| 管理端端口(给浏览器) | 3001 | 管理页面(本服务自带,含 SPA 深链接回退)+ 上面全部接口 |
+
+反向代理按用途分别转发两个端口,每个端口各一条全匹配转发规则即可。
+
+### 4. 前置要求
+
+- Linux 服务器,有 **root** 权限(不需要 sudo,直接以 root 执行即可)
+- **Node.js 22** 或更高版本
+- 进程管理:`systemd` / `OpenRC` / `SysVinit` 均可;三者都没有也能装(自动降级为 `nohup` 后台进程 + PID 文件 + crontab `@reboot` 开机自启)
+- 反向代理:由另外的服务提供,本项目不要求、也不安装
+- 一个可连通的现有 MySQL / MariaDB 实例,并已创建数据库与账号:
+
+```sql
+CREATE DATABASE IF NOT EXISTS opendance
+  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER IF NOT EXISTS 'opendance_app'@'%' IDENTIFIED BY '<数据库口令>';
+GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
+  ON opendance.* TO 'opendance_app'@'%';
+FLUSH PRIVILEGES;
+```
+
+本项目不会创建数据库本身,也不需要 `GRANT OPTION` / `FILE` / `SUPER` 等管理权限。
+
+### 5. 部署步骤
+
+```bash
+tar -xzf opendance-web-v0.2.1.tar.gz
+cd opendance-web-v0.2.1
+bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
+bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
+```
+
+也可跳过引导手工填写:
+
+```bash
+cp deploy/.env.example deploy/.env
+vi deploy/.env          # 填写 DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME
+```
+
+脚本会依次:校验环境与 `.env` -> 创建服务用户与目录 -> 复制程序文件 -> 安装运行期依赖 -> 执行 TypeORM 迁移 -> 注册并启动系统服务(systemd / OpenRC / SysVinit / 后台进程)-> 等待健康检查。
+
+### 6. `deploy/.env` 初始化引导(deploy/init-env.sh)
+
+缺 `deploy/.env` 时,`install.sh` 会先调用本脚本引导填写;引导失败才中止安装(若安装目录里已有上次安装留下的 `.env`,则直接复用,不会重复提问)。也可以单独运行:逐项询问数据库与端口,回车保留默认值,写盘前做必填项与端口范围校验,并可用项目自带的 `mysql2` 做一次数据库连通性自检 —— 口令只经环境变量传给子进程,出错信息与摘要一律显示 `*`。
+
+```bash
+bash deploy/init-env.sh              # 交互引导(终端里逐项询问)
+bash deploy/init-env.sh --force      # 已有 .env 也重新逐项询问
+bash deploy/init-env.sh --check      # 只校验, 不改动、不提问(适合复核)
+```
+
+逐项询问的字段(共 8 个):`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_NAME` / `PORT` / `ADMIN_PORT` / `HOST`。
+
+`DB_PASS` 用 `read -s` 不回显;所有字段按约定写成 `键=值`(不加引号),因此口令请勿含会破坏 shell 语法的字符(`& $ ` \ 空格 ; | < > () !`),脚本检测到会告警。写回只替换或追加这 8 个键、保留模板注释,写完 `chmod 600` 并回读校验;结尾打印摘要(口令 `*`)与本次变更列表。
+
+开关:
+
+| 开关 | 说明 |
+| --- | --- |
+| `--force` | 已有 `.env` 也重新逐项询问 |
+| `--check` | 只校验,不修改文件、不提问 |
+| `-y`, `--yes`, `--non-interactive` | 非交互:只校验缺字段与端口,绝不提问 |
+| `-i`, `--interactive` | 即使 stdin 不是 TTY 也强制提问(读取超时仍生效) |
+| `--skip-db-check` | 跳过数据库连通性自检 |
+| `--dir DIR` | 等价于 `--env-file DIR/.env --example DIR/.env.example` |
+| `--env-file PATH` | 指定 `.env` 路径(默认脚本目录下的 `.env`) |
+| `--example PATH` | 指定模板路径(默认 `.env` 同目录的 `.env.example`) |
+| `--timeout SECONDS` | 非 TTY 下每次读取的超时秒数(默认 10) |
+| `-h`, `--help` | 显示帮助 |
+
+环境变量:`OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` / `OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` / `OPENDANCE_PROMPT_TIMEOUT`。
+
+非交互绝不挂住:stdin 非 TTY 且是 `</dev/null` 或已关闭,或带 `-y/--yes/--non-interactive` 时只校验不提问;所有 `read` 都带超时,EOF 或超时立即 `exit 1`,不会卡在 CI 或自动化里。
+
+### 7. 部署完成后(直接访问后端端口,`<host>` 为服务器 IP)
+
+| 入口 | 地址 |
+| --- | --- |
+| 客户端接口 | `http://<host>:3000/api` |
+| 健康检查 | `http://<host>:3000/health` |
+| 契约快照 | `http://<host>:3000/contracts/` |
+| 管理端首页 | `http://<host>:3001/` |
+
+软件 API 端口上没有管理页面:`http://<host>:3000/` 返回 **404**,属正常。
+
+### 8. 对外访问
+
+由反向代理按用途分别转发两个端口:
+
+```text
+浏览器管理界面                     -> http://<后端地址>:3001
+Windows/Godot 客户端与 Android App -> http://<后端地址>:3000
+```
+
+配置样例与说明(含两个端口的转发写法):
+
+| 文件 | 用途 |
+| --- | --- |
+| `deploy/proxy/nginx.conf.example` | nginx 站点配置 |
+| `deploy/proxy/web.config.example` | IIS(ARR + URL Rewrite)配置 |
+| `deploy/proxy/README.md` | 完整说明、自检清单与常见故障 |
+
+直连后端时,防火墙需**同时放行两个端口**(默认 3000 与 3001)。
+
+外部访问不了?安装脚本结尾会直接给出结论(监听地址、对外可达性、防火墙提示);也可以在服务器上跑一次自检脚本(只读,不改配置):
+
+```bash
+bash deploy/check-access.sh            # 或 bash deploy/check-access.sh /opt/opendance
+```
+
+它会打印 `.env` 里的 `HOST`/`PORT`、实际监听地址、回环与对外 IP 自测结果、80/443 是否有反代、防火墙放行情况,并直接给出修复命令。
+
+### 9. 可覆盖的安装参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `APP_DIR` | `/opt/opendance` | 程序目录 |
+| `SERVICE_USER` | `opendance` | 运行服务的系统用户 |
+| `STORAGE_DIR` | `/var/lib/opendance/storage` | 上传文件目录 |
+| `PORT` | `3000` | 软件 API 端口 |
+| `ADMIN_PORT` | `3001` | 管理端端口(默认 `PORT + 1`) |
+
+例:`APP_DIR=/srv/opendance bash deploy/install.sh`。
+
+### 10. 升级
+
+解压新版本后重新执行 `bash deploy/install.sh` 即可(会覆盖程序文件,保留 `deploy/.env` 与上传数据)。
+
+### 11. 卸载
+
+```bash
+sudo bash deploy/uninstall.sh           # 停服务、禁用站点, 保留数据
+sudo bash deploy/uninstall.sh --purge   # 一并删除程序目录与上传文件
+```
+
+数据库始终由部署方自行管理,卸载脚本不做任何改动。
+
+### 12. 常用命令(按安装时自动检测到的初始化系统而定)
+
+```bash
+# systemd
+systemctl status opendance-api      # 服务状态
+journalctl -u opendance-api -f      # 实时日志
+systemctl restart opendance-api     # 重启
+
+# OpenRC
+rc-service opendance-api status / restart
+tail -f /var/log/opendance-api.log
+
+# SysVinit
+/etc/init.d/opendance-api status / restart
+
+# 无 init 系统(降级模式)
+bash /opt/opendance/deploy/ctl.sh status | restart | logs
+```
+
+反代配置不在本机,无需在此维护。
+
+### 13. 常见问题(初次部署)
+
+| 现象 | 处理 |
+| --- | --- |
+| 安装脚本报"未找到 node"或 Node 版本过低 | 装 Node.js 22+ 后重跑;脚本会打印检测到的版本号 |
+| 安装脚本报"`deploy/.env` 中 `DB_*` 未设置" | 先跑 `bash deploy/init-env.sh` 生成配置,或手工 `cp deploy/.env.example deploy/.env` 后填写 |
+| 健康检查返回 503 | 服务起来了但连不上数据库:核对 `deploy/.env` 的 `DB_HOST/DB_PORT/DB_USER/DB_PASS/DB_NAME`,以及数据库账号是否允许从本机 IP 连接(`GRANT ... TO 'user'@'%'` 或具体主机) |
+| 服务本机 curl 通、外部访问不了 | `bash deploy/check-access.sh` 一次定位:打印 `HOST`/`PORT`、实际监听地址、对外 IP 自测、80/443 有无反代、防火墙放行情况,并给出修复命令 |
+| 管理页面打开是 404 | 说明访问的是软件 API 端口(默认 3000);管理页面在管理端端口(默认 3001) |
+| 上传 `.zip` 模型包报 422 且提示 Assimp 不可用 | PMX/FBX 转换依赖 Assimp:`apt-get install -y assimp-utils libassimp6`;只上传 `.glb` / `.vrm` 则不需要它 |
+| 安装时报 `command not found` / 退出码 127,且提示指向 `deploy/.env` 某一行 | 该行的值含空格或 shell 元字符却没加引号,被 shell 当成命令执行了。按预检提示给这个值加引号(如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`)后重跑;`deploy/env-lib.sh` 会提前拦住并给出行号 |
+| 模型审核界面显示"未分析 / 无预览图" | 该模型是升级前入库的:调 `POST /api/models/<id>/reanalyze`,或批量跑 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000` |
+
+## 本地开发
+
+后端:
+
+```bash
+cd web-server
+cp .env.example .env    # 填写 DB_*
+npm install
+npm run migration:run   # 首次需要
+npm run start:dev       # API http://localhost:3000; 管理端 http://localhost:3001
+```
+
+管理前端:
+
+```bash
+cd web-server/admin
+npm install
+npm run dev             # http://localhost:5173(/api 与 /health 代理到 3000)
+```
+
+## 验证
+
+```bash
+cd web-server
+npm run contracts:check   # 契约版本一致性
+npm run typecheck         # TypeScript 严格检查
+npm run test              # 180 项单元测试 / 11 个文件(VMD 31、模型压缩包 24、
+                          #   模型检查器 25、缩略图 8、骨骼过滤 8、
+                          #   预处理 25、init-env 16、admin-port 16、
+                          #   access-log 9、VRM 检查器 6、.env 预检 12)
+npm run build             # 生产构建
+npm run start:prod &      # 启动
+npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
+
+cd ../admin && npm run build   # 管理端构建
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_NAME` | - | 现有 MySQL 实例连接信息(**必填**) |
+| `DB_SYNCHRONIZE` | `false` | 必须为 `false`。生产环境启动时若检测到 `true` 会直接中止启动;所有表结构变更通过 TypeORM migration 执行 |
+| `DB_LOGGING` | `false` | 是否打印 SQL |
+| `PORT` | `3000` | 软件 API 监听端口。给 Windows/Godot 客户端与 Android App 调用,只提供 `/api`、`/health`、`/static`、`/contracts`,不提供管理页面 |
+| `ADMIN_PORT` | `PORT + 1`(3001) | 管理端端口。浏览器访问管理界面(管理页面 + 上面全部接口);设为与 `PORT` 相同即为单端口兼容模式,日志会提示「未分端口」 |
+| `HOST` | `0.0.0.0` | 监听地址(软件 API 端口),因此装好即可被客户端访问(此时请用防火墙限制来源)。反代与后端同机时建议改为 `127.0.0.1`,让后端不直接对外暴露 |
+| `ADMIN_HOST` | 跟随 `HOST` | 管理端监听地址(可选;`HOST` 未设置时同样回落 `0.0.0.0`)。需要接口对外、管理端只对本机时设为 `127.0.0.1` |
+| `ADMIN_DIR` | `../admin`(即 `/opt/opendance/admin`) | 管理端静态站点目录 |
+| `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 可执行文件。FBX/glTF 动作预处理需要;上传 `.zip` 模型包、或 `.pmx/.fbx` 单文件模型时必须能调用到,否则转换失败(422) |
+| `MODEL_CONVERT_FORMAT` | `glb` | 需要转换的模型(PMX/FBX)的交付格式:`glb`(两个客户端都原生加载)或 `vrm`。`vrm` = 在 GLB 之上补 `VRMC_vrm` 扩展(humanoid 骨骼 / 表情语义),humanoid 骨骼映射不全时自动回退交付 GLB 并写进 `conversion_note`。产物一律用 `assimp info` 回读校验 |
+| `MODEL_CONVERT_PMX` | `"Hatsune Miku.pmx"` | 压缩包内优先选用的 PMX 文件名(大小写不敏感);找不到时按「格式优先级 -> 目录最浅 -> 文件最大」挑选 |
+| `MODEL_CONVERT_TIMEOUT_MS` | `180000` | 单次转换超时(毫秒) |
+| `DEFAULT_MODEL_ID` | - | 可选:显式指定默认模型 id;不设置时按源码种子 `src/config/default-model.ts` 匹配,再回落到 VRM 优先规则 |
+| `CONTRACTS_DIR` | - | 可选:契约目录,设置后 `/health` 反映实时契约版本(原生部署默认指向 `/opt/opendance/contracts`) |
+
+端口配置非法(非 1..65535 整数)时,生产环境启动会直接中止;`ADMIN_PORT` 设为与 `PORT` 相同只打印提示,不中止。
+
+**`.env` 写法约定**:`install.sh` / `ctl.sh` 用 `set -a; . deploy/.env` 载入配置,shell 会**真的执行**这个文件,因此
+
+- 普通值不加引号:`PORT=3000`、`DB_HOST=127.0.0.1`;
+- 值里含**空格或 shell 元字符**(`& | ; $ \` < > ( )` 等)时**必须加引号**,例如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`;
+- 双引号内不要用 `$(...)` 或反引号(会被真的执行),需要字面量时用单引号:`KEY='a b'`。
+
+两个脚本在 source 之前都会先跑 `deploy/env-lib.sh` 的语法预检,不安全写法会直接指出行号、原文与改法。
+
+## 主要 API
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/health` | 健康检查(含数据库连通性) |
+| `GET` | `/api/songs` | 曲目列表(分页 / 检索) |
+| `POST` | `/api/songs` | 新建曲目 |
+| `GET` | `/api/songs/:id` | 曲目详情 |
+| `PATCH` | `/api/songs/:id` | 更新曲目 |
+| `DELETE` | `/api/songs/:id` | 删除曲目(软删除) |
+| `POST` | `/api/songs/:id/audio` | 上传音频 |
+| `GET` | `/api/motions` | 动作列表 |
+| `POST` | `/api/motions` | 上传动作 + 来源信息 |
+| `POST` | `/api/motions/:id/preprocess` | BVH/VMD/FBX -> MediaPipe33 关键点 |
+| `GET` | `/api/motions/:id/keypoints` | 下载关键点序列(NDJSON) |
+| `GET` | `/api/models` | 模型列表 |
+| `POST` | `/api/models` | 上传模型 + 来源信息(`.glb/.vrm/.gltf` 直接导入;`.pmx/.fbx` 服务端转换;`.zip` 自动搜索包内模型) |
+| `POST` | `/api/models/:id/primary` | 设为全局默认模型(仅 `published` 允许,否则 409) |
+| `GET` | `/api/reviews` | 审核流水 / 待审列表 |
+| `POST` | `/api/reviews/:type/:id/approve` | 审核通过(模型可带 `setPrimary:true`) |
+| `POST` | `/api/reviews/:type/:id/reject` | 审核驳回(必须填意见) |
+| `GET` | `/api/catalog/export` | 客户端一次性拉取已发布目录 |
+| `GET` | `/api/catalog/version` | 契约版本 + 目录指纹 |
+
+完整契约(OpenAPI 3.0)见 `contracts/rest-api.yaml`。
+
+上传文件通过 `/static/<kind>/<yyyy>/<mm>/<sha256>.ext` 访问,相同内容只落盘一次(sha256 去重)。
+
+### 支持的模型格式(`POST /api/models` 上传)
+
+系统以 **GLB / VRM 为主力格式**:服务端与客户端都把这两种格式作为一等公民(Godot 客户端用内置 `GLTFDocument` 加载 glTF/GLB/VRM,见 `opendance-windows/src/model/vrm_loader.gd`,本次无需改动)。
+
+| 格式 | 扩展名 | 优先级 | 处理方式 |
+| --- | --- | --- | --- |
+| glTF Binary | `.glb` | 主力(P0) | **直接导入,不重编码** |
+| VRM | `.vrm` | 主力(P0) | **直接导入**;GLB + VRM 扩展(humanoid / 表情 / springBone / meta) |
+| glTF | `.gltf` | P1 | **直接导入**(分离的 `.bin` / 贴图需随 `.zip` 一起上传) |
+| MMD 压缩包 | `.zip` | P1 | **自动搜索**包内可用模型(见下) |
+| MMD 模型 | `.pmx` | P2(输入) | 服务端转换,优先 GLB、其次 VRM |
+| FBX | `.fbx` | P2(输入) | 服务端转换,优先 GLB、其次 VRM |
+
+入库后一律 `status=pending`(待审核):上传不再自动发布、不再自动设为默认,必须经审核通过(模型审核面板可勾选「同时设为全局默认模型」)才对客户端可见。
+
+### 升级后回填已有模型(面数 / 骨骼 / 缩略图)
+
+升级到带 `models.stats` 的版本后,旧模型还没有分析与预览图。服务启动后执行一次:
+
+```bash
+cd /opt/opendance/web-server
+node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000
+# 只处理一个: --model-id 14    只列清单: --dry-run    全部重算: --force
+```
+
+也可对单个模型调 `POST /api/models/:id/reanalyze`(只改 `stats` 与缩略图两个字段)。若模型文件在存储中已丢失,接口返回 **409** 并提示先恢复文件,不会用空结果覆盖已有数据。
+
+### 模型压缩包(`.zip`)自动搜索与转换
+
+上传的 `.zip` 不再"只找 `.pmx`",而是自动搜索包内可用模型,走"解压 -> 选主模型 -> 直接导入或转换 -> 回读校验 -> 入库",而不是把压缩包当模型存下来。
+
+| 环节 | 行为 |
+| --- | --- |
+| 选主模型 | 优先级 `.vrm` -> `.glb` -> `.gltf` -> `.pmx` -> `.fbx`;同一优先级内按"`MODEL_CONVERT_PMX` 指名字 -> 目录最浅 -> 文件最大"。命中 `.vrm/.glb/.gltf` 时直接导入(不重编码) |
+| 转换 | 只有 `.pmx/.fbx` 需要转换。链路:`assimp export -> .glb`(首选);失败则 `assimp export -> .gltf`,再由 `gltf-packer.ts` 自行打包回 GLB;`MODEL_CONVERT_FORMAT=vrm` 时在 GLB 之上补 `VRMC_vrm` 扩展封装成 **VRM 1.0**(humanoid 骨骼不全则回退交付 GLB,缺失骨骼写进说明) |
+| 校验 | 每一步产物必须用 `assimp info` **回读校验**。Assimp 会"写出损坏文件"(实测 PMX 导出 FBX 退出码 11、回读报 FBX-DOM 错误),只看退出码会把坏文件入库 |
+| 贴图 | GLB 产物里 Assimp 会把贴图写成外部 URI(还带反斜杠),服务端把压缩包内 / `.gltf` 同目录的贴图**内嵌**进 GLB 的二进制块,保证单文件可加载 |
+| 说明 | 每次尝试写入 `models.conversion_note`,例如 `Hatsune Miku.pmx -> GLB, 已内嵌 2 张贴图` |
+| 溯源 | 压缩包原件以 `model-archive` 资产留存,写入 `models.source_asset_id`;迁移 `AddModelConversionFields1789450000000` |
+| 失败 | 包内没有可用模型、Assimp 不可用、两条路径都失败 -> HTTP **422**,不产生模型记录 |
+| 文件名编码 | `upload.util.ts` 的 `decodeUploadName()` 修正 multipart 文件名的 latin1/UTF-8 乱码(中文文件名原先会存成乱码) |
+| 管理端 | 上传框 `accept` 为 `.vrm,.glb,.gltf,.fbx,.zip`;预览面板显示「转换来源」、「文件 sha256」与面数 / 顶点 / 骨骼分析摘要 |
+| 新增字段 | DTO/契约新增 `conversionNote`、`fileSha256`、`stats`、`thumbnailUrl` |
+
+实测(Assimp 6.0.4):
+
+- 上传含 `Hatsune Miku.pmx` 的 MMD 压缩包 -> HTTP 201 / 0.86s、`format=glb`、`status=pending`、`conversionNote=Hatsune Miku.pmx -> GLB, 已内嵌 2 张贴图`。分析结果:`vertices=7155 triangles=9071 materials=3 textures=2 images=2 nodes=240 bones=238 skins=1 morphTargets=0 humanoidMapped=0/22 drivable=false maxBoneDepth=23`;`missingRequiredBones` 为全部 16 根(日文 MMD 骨名无法映射到 humanoid,审核界面会直接标红)。
+- 直接上传 `.glb` -> HTTP 201 / 0.36s、`conversionNote=直接导入(GLB, 未做重编码)`,入库文件 sha256 与源文件一致(不重编码,字节级保留)。
+
+### 模型分析、缩略图与 3D 预览(入库后自动执行,失败不影响入库)
+
+| 能力 | 实现 |
+| --- | --- |
+| 分析 | `model-inspector.ts` 解析 GLB/VRM:面数 / 顶点 / 网格 / 材质 / 贴图 / 节点 / 形变目标 / 动画 / 蒙皮骨骼数 / 骨骼树 / humanoid 覆盖 / 可驱动性(缺哪些必需骨骼)/ warnings,写入 `models.stats`(迁移 `AddModelStats1789460000000`,新增 `models.stats TEXT`) |
+| 缩略图 | `model-thumbnail.ts` 用**纯 TS 软件光栅化**生成 PNG(读 GLB/glTF -> 应用节点层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer 逐三角形平面着色 -> 手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer)。默认 512x512,写入 `models.thumbnail_asset_id` / `thumbnailUrl`;失败或非 glTF 容器时留空,列表页退化为格式占位图 |
+| 预览 | 管理端 3D 预览放开到 `vrm/glb/gltf`(`.fbx` 仍提示「仅归档,请先转换为 GLB/VRM」);列表页显示 40px 小缩略图,审核面板显示 116px 缩略图 |
+
+实测:512x512 PNG / 15,043 字节,目视确认为居中的 T-pose 角色图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms)。
+
+### 审核流程(模型)
+
+模型上传后为 `pending`,在管理端「审核」页的模型审核面板里查看并决定:
+
+| 项 | 内容 |
+| --- | --- |
+| 面板内容 | 体积 / 格式 / 容器 / VRM 版本 / 面数 / 顶点 / 网格 / 材质 / 贴图 / 骨骼 / 节点 / 形变目标 / 动画 / humanoid 覆盖(已映射/总数 + 明细)/ 可驱动性结论(缺哪些必需骨骼)/ warnings |
+| 骨骼预览 | 骨骼详细界面:扁平骨骼树按 depth 缩进、显示骨骼名、是否参与蒙皮、humanoid 映射徽章、子节点数;支持按名搜索(保留祖先链)、「仅显示蒙皮骨骼」开关、限高滚动 + 只渲染前 400 行(千根骨骼不卡) |
+| 通过 | 勾选「同时设为全局默认模型」-> 请求体带 `setPrimary:true`(`POST /api/reviews/model/:id/approve`);此时才写库 `is_primary` 并把默认模型身份写进源码 `src/config/default-model.ts` |
+| 单独设置 | `POST /api/models/:id/primary`(仅 `published` 允许,否则 409) |
+| 驳回 | 必须填写审核意见,否则 400 |
+
+### 默认模型是怎么定的
+
+`GET /api/catalog/export` 的 `defaultModelId` 按以下顺序解析:
+
+0. 环境变量 `DEFAULT_MODEL_ID`(且模型存在且已发布)
+1. 源码种子 `src/config/default-model.ts` 的 `DEFAULT_MODEL_SEED` —— 按**上传压缩包的 sha256** 匹配已发布模型(用户文件永远稳定;不能用转换产物的 sha256,Assimp 每次导出的字节都略有不同),换库 / 重建库后仍有效
+2. `format='vrm'` 且 `published` 且 `is_primary=1`
+3. 任意 `published` 的 VRM(id 升序取第一个)
+4. id 最小的已发布模型
+5. 无可用模型 -> 客户端用内置占位模型
+
+源码种子 `src/config/default-model.ts` 当前为**空种子**(占位:`id=null`、sha256 空串),此时 `defaultModelId` 直接从第 2 步的 VRM 优先规则开始解析;按下面的方式设定默认模型后,服务端会把种子写成真实内容。
+
+实测(v0.2.0):`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200,模型 `status=published`、`isPrimary=true`,源码种子写入 `sourceSha256=72eb6882...`;重建后 `GET /api/catalog/export` 的 `defaultModelId` 由 VRM 变为 22(库中另有 2 个已发布 VRM)。也可手工指定:`POST /api/models/:id/primary`。
+
+第 1 步的源码写入由服务端在审核通过并勾选 `setPrimary`(或调用 primary 接口)时完成;生产 systemd 加固(`ProtectSystem=strict`)下服务进程写不了程序目录,可改用下面的 CLI 补写。
+
+### 导入 / 补写默认模型(`web-server/scripts/import-default-model.mjs`)
+
+需先 `npm run build`(脚本复用编译产物 `dist/models/default-model-source.js`)。
+
+```bash
+cd web-server
+node scripts/import-default-model.mjs 模型.zip \
+  --url http://127.0.0.1:3000 \
+  --name "初音未来 Hatsune Miku" --author "Boku Wa Luka" \
+  --license "MMD 模型使用条款(见压缩包内说明)" \
+  --source-name "模型_初音未来Hatsune Miku_by_Boku_Wa_Luka.zip" \
+  --source-url "本地文件: 模型_初音未来Hatsune Miku_by_Boku_Wa_Luka.zip" \
+  --source-type other
+# 上传 -> 服务端转换入库(pending)-> 把身份写进 src/config/default-model.ts
+
+node scripts/import-default-model.mjs --write-source-only --model-id 22
+# 只根据已入库模型补写源码, 不调上传 API
+
+node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-run
+# 只打印将写入的内容, 不落盘
+```
+
+说明:`--url` 默认 `http://127.0.0.1:3000`,`--source-type` 默认 `other`。v0.2.0 起上传一律 `pending`,因此 CLI 上传路径只负责转换入库与写源码种子;要让它在 `defaultModelId` 中生效,仍需在管理端审核通过(勾选「同时设为全局默认模型」)或调用 `POST /api/models/:id/primary`。
+
+### 支持的动作格式(`POST /api/motions` 上传 -> `POST /api/motions/:id/preprocess` 预处理)
+
+| 格式 | 扩展名 | 处理方式 |
+| --- | --- | --- |
+| BVH | `.bvh` | 内置纯 TS 解析器,保留源帧率 |
+| VMD | `.vmd` | 内置解析(MikuMikuDance),固定 30fps;腿部按「足ＩＫ是否带位移」自动选 IK 或 FK |
+| FBX | `.fbx` | 需可选的 Assimp 先转 BVH |
+| glTF / GLB | `.gltf` / `.glb` | 同上 |
+| 关键点 JSON | `.json` | 已是 MediaPipe33 结构,只做校验与规范化 |
+
+### VMD 动作上传前后自查
+
+服务端对 `.vmd` 是内置解析,不依赖 Assimp。上传前可先在 `web-server` 目录下跑诊断工具(只读:不写数据库、不访问网络),确认骨骼名能识别、腿走 IK 还是 FK、关键点序列无异常:
+
+```bash
+cd web-server
+npm run build
+node scripts/inspect-vmd.mjs 动作.vmd
+node scripts/inspect-vmd.mjs 动作.vmd --frames 300      # 只采样前 300 帧
+node scripts/inspect-vmd.mjs 动作.vmd --json out.json   # 导出关键点序列
+```
+
+它会打印头部 / 模型名 / 帧数 / 轨道数、未识别骨骼、走 IK 还是 FK、关键点序列异常统计与膝肘角分布。上传后再调用 `/preprocess` 走正式通路。
+
+## 目录结构
+
+```text
+project.yaml            任务清单与状态
+DSH.md                  本项目 DSH 执行约束
+tasks/                  单任务说明书(T-WEB-001 ~ 010)
+contracts/              跨端契约(权威, 改接口先改这里)
+web-server/             NestJS 服务端源码
+web-server/admin/       React 管理端
+web-server/src/common/zip-reader.ts            纯 TS ZIP 读取器
+web-server/src/models/model-convert.ts         .zip/.pmx/.fbx -> GLB/VRM 转换
+web-server/src/models/gltf-packer.ts           glTF(分离文件)-> GLB 打包
+web-server/src/models/glb-textures.ts          GLB 贴图内嵌
+web-server/src/models/vrm-writer.ts            GLB -> VRM 1.0 封装(写 VRMC_vrm 扩展)
+web-server/src/models/model-inspector.ts       模型检查器(面数/骨骼树/humanoid 覆盖)
+web-server/src/models/model-thumbnail.ts       纯 TS 光栅化缩略图(零原生依赖)
+web-server/src/config/default-model.ts         默认模型种子(服务端/CLI 写入)
+web-server/src/migrations/1789460000000-AddModelStats.ts
+                                                models.stats 迁移(审核分析结果)
+web-server/admin/src/components/ModelReviewPanel.tsx
+                                                模型审核面板(含骨骼详细界面)
+web-server/admin/src/lib/bone-tree.ts          骨骼树过滤(搜索保留祖先链)
+web-server/scripts/import-default-model.mjs    默认模型导入 / 补写 CLI
+deploy/                 业务服务部署(系统服务, 不含 MySQL、不含反向代理)
+deploy/init-env.sh      首次启动的 .env 交互引导(install.sh 会调用)
+deploy/proxy/           反向代理配置说明(nginx / IIS, 仅供参考不部署)
+THIRD_PARTY.md          第三方开源项目声明
+```
+
+## 安全提示
+
+1. `.env` 已被 `.gitignore` 忽略,禁止提交;仓库中只保留 `.env.example`。
+2. 数据库账号使用最小权限,不授予 `GRANT OPTION` / `FILE` / `SUPER`。
+3. 本版本未内置管理端登录认证,请部署在内网,或在反向代理层加 Basic Auth / SSO。
+4. 上传的模型与动作默认需填写来源五元组并通过审核后才对客户端可见。模型上传后一律 `pending`:不再自动发布、不再自动设为默认;默认模型只在审核通过时勾选「同时设为全局默认模型」(`setPrimary:true`)或调用 `POST /api/models/:id/primary`(仅 `published`)时才设置(见[审核流程](#审核流程模型))。
+5. 未使用 SMPL 拓扑,统一 MediaPipe 33 点,规避非商用许可限制。
+
+## 第三方开源声明
+
+见 `THIRD_PARTY.md`,或访问站点 `http://<host>/` 的「关于」页面。

README.txt

@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
+OpenDance Studio -- Web 管理服务端 v0.2.1  使用说明
 ================================================================
 
 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,16 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。
 
+v0.2.1 修订
+  1. 修复部署失败: 模板里的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格却
+     没加引号, install.sh 用 `set -a; . deploy/.env` 载入时把 Miku.pmx 当命令
+     执行, 报 command not found(退出码 127); 模板已改为带引号写法。
+  2. 新增 .env 语法预检(deploy/env-lib.sh): install.sh 与 ctl.sh 在 source 之前
+     先检查, 直接给出哪一行、原文与改法, 不再出现看不懂的 127。
+  3. 失败提示带上出错文件名(.env 被 source 时行号属于 .env)。
+  4. 新增 12 项回归测试(web-server/test/env-file.spec.ts)。
+  约定: 值里含空格或 shell 元字符时必须加引号(双引号内不要用 $( ) 或反引号)。
+
 --
 一、部署到 Linux 服务器(业务服务, 不含反向代理)
 --
@@ -20,11 +30,11 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
    2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
         本项目不会创建数据库本身
    3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.2.0.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.2.1.tar.gz
         curl -LO https://<制品库地址>/SHA256SUMS
         sha256sum -c SHA256SUMS      # 期望输出 "OK"
    4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
-        tar -xzf opendance-web-v0.2.0.tar.gz && cd opendance-web-v0.2.0
+        tar -xzf opendance-web-v0.2.1.tar.gz && cd opendance-web-v0.2.1
         bash deploy/init-env.sh
    5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
         bash deploy/install.sh
@@ -79,8 +89,8 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
   (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
 
 部署步骤
-  tar -xzf opendance-web-v0.2.0.tar.gz
-  cd opendance-web-v0.2.0
+  tar -xzf opendance-web-v0.2.1.tar.gz
+  cd opendance-web-v0.2.1
   bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
   bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 
@@ -209,7 +219,10 @@ deploy/.env 初始化引导(deploy/init-env.sh)
  - 上传 .zip 模型包报 422 且提示 Assimp 不可用
      PMX/FBX 转换依赖 Assimp: apt-get install -y assimp-utils libassimp6;
      只上传 .glb / .vrm 则不需要它。
- - 模型审核界面显示"未分析 / 无预览图"
+ - 安装时报 command not found / 退出码 127, 且提示指向 deploy/.env 某一行
+      该行的值含空格或 shell 元字符却没加引号, 被 shell 当成命令执行了。按预检
+      提示给这个值加引号(如 MODEL_CONVERT_PMX="Hatsune Miku.pmx")后重跑。
+  - 模型审核界面显示"未分析 / 无预览图"
      该模型是升级前入库的: 调 POST /api/models/<id>/reanalyze, 或批量跑
      node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000。
 
@@ -236,10 +249,10 @@ deploy/.env 初始化引导(deploy/init-env.sh)
   cd web-server
   npm run contracts:check   # 契约版本一致性
   npm run typecheck         # TypeScript 严格检查
-  npm run test              # 168 项单元测试 / 10 个文件(VMD 31、模型压缩包 24、
+  npm run test              # 180 项单元测试 / 11 个文件(VMD 31、模型压缩包 24、
                             #   模型检查器 25、缩略图 8、骨骼过滤 8、
                             #   预处理 25、init-env 16、admin-port 16、
-                            #   access-log 9、VRM 检查器 6)
+                            #   access-log 9、VRM 检查器 6、.env 预检 12)
   npm run build             # 生产构建
   npm run start:prod &      # 启动
   npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -270,6 +283,13 @@ deploy/.env 初始化引导(deploy/init-env.sh)
   ADMIN_HOST            管理端监听地址(可选, 默认跟随 HOST;HOST 未设置时同样
                         回落 0.0.0.0)。需要接口对外、管理端只对本机时设为
                         127.0.0.1
+  .env 写法约定: install.sh / ctl.sh 用 `set -a; . deploy/.env` 载入配置, shell 会
+  真的执行这个文件, 因此普通值不加引号(PORT=3000), 值里含空格或 shell 元字符
+  (& | ; $ ` < > ( ) 等)时必须加引号, 例如 MODEL_CONVERT_PMX="Hatsune Miku.pmx";
+  双引号内不要用 $( ) 或反引号(会被真的执行), 需要字面量时用单引号 KEY='a b'。
+  两个脚本在 source 之前都会先跑 deploy/env-lib.sh 的语法预检, 不安全写法会直接
+  指出行号、原文与改法。
+
   端口配置非法(非 1..65535 整数)时, 生产环境启动会直接中止;
   ADMIN_PORT 设为与 PORT 相同只打印提示, 不中止。
   ADMIN_DIR             管理端静态站点目录(默认 ../admin, 即 /opt/opendance/admin)
@@ -286,7 +306,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
                         vrm = 在 GLB 之上补 VRMC_vrm 扩展(humanoid 骨骼 / 表情语义),
                         humanoid 骨骼映射不全时自动回退交付 GLB 并写进 conversion_note。
                         产物一律用 `assimp info` 回读校验
-  MODEL_CONVERT_PMX     压缩包内优先选用的 PMX 文件名(默认 Hatsune Miku.pmx,
+  MODEL_CONVERT_PMX     压缩包内优先选用的 PMX 文件名(默认 "Hatsune Miku.pmx",
                         大小写不敏感); 找不到时按「格式优先级 -> 目录最浅 ->
                         文件最大」挑选
   MODEL_CONVERT_TIMEOUT_MS

THIRD_PARTY.md

@@ -95,7 +95,7 @@
 ## 14. class-validator / class-transformer
 
 - 许可证：MIT
-- 源链接：https://github.com/typestack/class-validator ，
+- 源链接：https://github.com/typestack/class-validator ,
   https://github.com/typestack/class-transformer
 - 使用端：Web 服务端（请求校验与转换）
 

contracts/data-models.md

@@ -5,7 +5,7 @@ Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视
 
 ## 1. 通用约定
 
-- 所有资源返回 `id: number`（BIGINT，超出 2^53 前不会发生）。
+- 所有资源返回 `id: number`(BIGINT，超出 2^53 前不会发生)。
 - 所有时间为 ISO 8601 UTC 字符串，例：`2026-09-14T10:00:00.000Z`。
 - 列表接口统一分页响应：
 
@@ -117,7 +117,7 @@ rejected   已驳回
 ```
 0. 环境变量 DEFAULT_MODEL_ID 指定，且该模型存在且已发布
 1. 源码内写死的默认模型种子（web-server/src/config/default-model.ts 的
-   DEFAULT_MODEL_SEED）：按 **sourceSha256（上传压缩包的 sha256）** 匹配已发布模型，
+   DEFAULT_MODEL_SEED）：按 **sourceSha256(上传压缩包的 sha256)** 匹配已发布模型，
    换库/重建库后仍然有效；没有压缩包时退回按产物 sha256，最后按名称兜底。
    ⚠ 不能用产物 sha256 当主键：实测 Assimp 的 GLB 导出不是字节级确定的，
    同一份 zip 每次转换得到的文件 sha256 都不同（BIN chunk 有十几字节浮动）
@@ -145,7 +145,7 @@ rejected   已驳回
 | `comment` | string\|null | 审核意见 |
 | `createdAt` | string | |
 
-## 6. `CatalogBundle`（客户端一次性拉取，`GET /api/catalog/export`）
+## 6. `CatalogBundle`(客户端一次性拉取，`GET /api/catalog/export`)
 
 ```json
 {

contracts/database.md

@@ -3,11 +3,11 @@
 ## 环境
 
 - 类型：MySQL 兼容实例（外部提供，含 MariaDB 10.5+），TypeORM
-  使用 `mysql` driver（`mysql2`）连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+
+  使用 `mysql` driver(`mysql2`)连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+
   共同子集内，不使用 MySQL 8 专有语法（窗口函数 CTE 递归除外）。
-- 数据库名：由部署方提供，通过 `DB_NAME` 注入（本文档示例统一用 `opendance`）
+- 数据库名：由部署方提供，通过 `DB_NAME` 注入(本文档示例统一用 `opendance`)
 - 字符集：`utf8mb4` / `utf8mb4_general_ci`（沿用现有实例默认排序规则）
-- 迁移工具：TypeORM migration，**不使用 `DB_SYNCHRONIZE`**
+- 迁移工具：TypeORM migration, **不使用 `DB_SYNCHRONIZE`**
 
 ## 连接信息（由部署方提供）
 
@@ -25,10 +25,10 @@ DB_LOGGING=false
 
 ## 约定
 
-- 所有表名使用 `snake_case`，复数形式（`songs` / `motions` / `models`）
+- 所有表名使用 `snake_case`，复数形式(`songs` / `motions` / `models`)
 - 主键统一为 `BIGINT AUTO_INCREMENT`，字段名 `id`
-- 时间字段统一 `DATETIME`，`created_at` / `updated_at`，`updated_at` 由应用层维护
-- 软删除统一使用 `deleted_at DATETIME NULL`（`@DeleteDateColumn`）
+- 时间字段统一 `DATETIME`, `created_at` / `updated_at`, `updated_at` 由应用层维护
+- 软删除统一使用 `deleted_at DATETIME NULL`(`@DeleteDateColumn`)
 - 布尔字段使用 `TINYINT(1)`
 - 来源（出处）字段为 5 元组，任何资产入库必须齐备：
   `source_type` / `source_name` / `source_url` / `license` / `author`
@@ -36,24 +36,24 @@ DB_LOGGING=false
 - 每个 migration 必须可逆（提供 `down` 方法）
 - 迁移文件名格式：`<timestamp>-<kebab-name>.ts`
 
-## 增量迁移（v0.2.0 / v0.3.0）
+## 增量迁移(v0.2.0 / v0.3.0)
 
 | 迁移 | 变更 |
 |--|--|
-| `AddModelConversionFields` | `models` 增加 `source_asset_id BIGINT NULL`（上传的压缩包，用于溯源）与 `conversion_note VARCHAR(500) NULL`（转换说明，见 model-formats.md 1.1） |
+| `AddModelConversionFields` | `models` 增加 `source_asset_id BIGINT NULL`（上传的压缩包，用于溯源）与 `conversion_note VARCHAR(500) NULL`(转换说明，见 model-formats.md 1.1) |
 | `AddModelStats` | `models` 增加 `stats TEXT NULL`（模型分析结果：面数、骨骼树、humanoid 覆盖、可驱动性），供审核界面展示 |
 
-## 表清单（v0.1.0）
+## 表清单(v0.1.0)
 
 | 表 | 用途 | 任务 |
 |--|--|--|
 | `songs` | 曲目元数据 | T-WEB-003 |
 | `assets` | 上传文件元数据（去重、sha256、物理路径） | T-WEB-004 |
-| `motions` | 动作数据（BVH/FBX...）+ 来源 + 预处理产物 | T-WEB-004 / 006 |
+| `motions` | 动作数据(BVH/FBX...)+ 来源 + 预处理产物 | T-WEB-004 / 006 |
 | `models` | 角色模型（VRM 优先）+ 来源 + 压缩包转换溯源 | T-WEB-005 |
 | `review_records` | 上传审核流水 | T-WEB-007 |
 
-## 状态机（`status` 列，v0.1.0）
+## 状态机(`status` 列，v0.1.0)
 
 ```
 draft ──submit──▶ pending ──approve──▶ published

contracts/model-formats.md

@@ -1,21 +1,21 @@
 # contracts/model-formats.md - 模型与动作格式契约 v0.4.0
 
-## 1. 角色模型（models）
+## 1. 角色模型(models)
 
 **系统以 GLB / VRM 为主力格式**（两个客户端都原生加载），其余格式一律在服务端转换。
 
 | 格式 | 扩展名 | 支持级别 | 服务端行为 |
 |--|--|--|--|
-| glTF Binary | `.glb` | **主力（P0）** | **直接导入**，不重编码 |
-| VRM | `.vrm` | **主力（P0）** | **直接导入**；= GLB + VRM 扩展（humanoid / 表情 / springBone / meta） |
-| glTF | `.gltf` (+ `.bin`, 贴图) | P1 | 直接导入（分离文件在 zip 内可用；单文件上传会缺.bin） |
+| glTF Binary | `.glb` | **主力(P0)** | **直接导入**，不重编码 |
+| VRM | `.vrm` | **主力(P0)** | **直接导入**; = GLB + VRM 扩展(humanoid / 表情 / springBone / meta) |
+| 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） |
+| FBX | `.fbx` | P2（输入） | 服务端转换(优先 GLB、其次 VRM) |
 
 ### 1.1 上传与转换策略
 
-**`.glb` / `.vrm` / `.gltf` 直接导入**（不重编码，零损失）；**`.pmx` / `.fbx` 由服务端转换**：
+**`.glb` / `.vrm` / `.gltf` 直接导入**（不重编码，零损失）；**`.pmx` / `.fbx` 由服务端转换**:
 **优先 GLB，其次 VRM**。
 
 #### 单文件上传
@@ -28,7 +28,7 @@
 
 #### 压缩包上传（自动搜索）
 
-不再"只找 `.pmx`"，而是**按格式优先级自动搜索包内可用模型**：
+不再"只找 `.pmx`"，而是**按格式优先级自动搜索包内可用模型**:
 
 ```
 .vrm  ->.glb  ->.gltf        （直接导入，优先）
@@ -38,7 +38,7 @@
 同一优先级内：`MODEL_CONVERT_PMX` 指定的文件名优先，其次目录最浅，最后文件最大。
 压缩包原件以 `model-archive` 资产留存并写入 `models.source_asset_id`。
 
-#### 转换与校验（PMX / FBX）
+#### 转换与校验(PMX / FBX)
 
 | 步骤 | 规则 |
 |--|--|
@@ -46,7 +46,7 @@
 | 2. glTF 打包 | 上一步失败时 `assimp export ->.gltf`，由 `gltf-packer.ts` 把 `.gltf` + `.bin` + 贴图自行合成 GLB |
 | 3. VRM 封装 | `MODEL_CONVERT_FORMAT=vrm` 时，在 GLB 之上补 `VRMC_vrm` 扩展（humanoid 骨骼来自骨骼名映射，见 `model-inspector.ts` 的候选表，与 Godot 客户端一致）；**humanoid 不全则回退交付 GLB**，缺失骨骼写进 `conversion_note` |
 | 回读校验 | 每一步产物都要 `assimp info` 回读。Assimp 会"写出损坏文件"（实测 FBX 导出退出码 11、产物回读报 `FBX-DOM no Objects dictionary found`），只看退出码会把坏文件入库 |
-| 说明 | 每次尝试都写进 `models.conversion_note`（例如 `Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`） |
+| 说明 | 每次尝试都写进 `models.conversion_note`(例如 `Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`) |
 | 失败 | 包内没有可用模型、Assimp 不可用、两条路径都失败 -> **HTTP 422**，不产生模型记录 |
 
 #### 入库后（自动）
@@ -63,14 +63,14 @@
 | 项 | 规则 |
 |--|--|
 | 确定性 | **转换产物不是字节级确定的**：同一份 zip 连续转换 3 次得到 3 个不同 sha256（大小相同，BIN chunk 有十几字节浮动）。因此默认模型种子以**上传压缩包的 sha256** 为匹配键，产物 sha256 只作记录 |
-| 安全 | 解压前逐条校验路径，拒绝绝对路径与 `..`（zip-slip）；拒绝加密条目；只支持 STORE / DEFLATE |
+| 安全 | 解压前逐条校验路径，拒绝绝对路径与 `..`(zip-slip)；拒绝加密条目；只支持 STORE / DEFLATE |
 
 **VRM 优先**的选取顺序见 `data-models.md` 4.1。
 
-VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）或
-`extensions.VRMC_vrm`（1.0），写入 `models.vrm_version`。
+VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`(0.x)或
+`extensions.VRMC_vrm`(1.0)，写入 `models.vrm_version`。
 
-## 2. 动作数据（motions）
+## 2. 动作数据(motions)
 
 | 格式 | 扩展名 | 预处理支持 | 说明 |
 |--|--|--|--|
@@ -82,7 +82,7 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 
 ### 2.1 预处理产物（冻结）
 
-- 格式：NDJSON（`application/x-ndjson`），每行一帧，UTF-8 无 BOM
+- 格式：NDJSON(`application/x-ndjson`)，每行一帧，UTF-8 无 BOM
 - 一行结构：
 
 ```json
@@ -93,9 +93,9 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 - `angles` 为 `skeleton-topology.md` 5 定义的 9 个关节角余弦，顺序固定：
   `[shoulder_L, shoulder_R, elbow_L, elbow_R, hip_L, hip_R, knee_L, knee_R, spine]`
 - 帧率：保留源帧率；`fps` 写入 `motions.fps`，缺省 30
-- 坐标系换算：所有 3D 动作数据统一转到 **Y 轴向上、右手系、骨盆为原点**，
+- 坐标系换算：所有 3D 动作数据统一转到 **Y 轴向上、右手系、骨盆为原点**,
   再投影到 MediaPipe 归一化图像空间：
-  `x_img = 0.5 + x_world * scale`，`y_img = 0.5 - y_world * scale`，`z_img = -z_world * scale`，
+  `x_img = 0.5 + x_world * scale`, `y_img = 0.5 - y_world * scale`, `z_img = -z_world * scale`,
   `scale = 0.35 / max(|x|,|y|,|z|)`（按整段动作的最大范围自适应，保证不出画）
 - 缺失关节（BVH 中不存在对应骨骼）：`confidence = 0.0`，坐标沿用最近可用父节点
 
@@ -122,18 +122,18 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 未映射到的点按 `skeleton-topology.md` 5 的层级由父节点推算，
 并置 `confidence` 降低（`0.5`），表示估算而非实测。
 
-### 2.3 VMD（MikuMikuDance）解析约定
+### 2.3 VMD(MikuMikuDance)解析约定
 
-VMD 是二进制格式：文件头 `Vocaloid Motion Data 0002`（30 字节）+ 模型名（20 字节，
-Shift-JIS）+ 骨骼关键帧数组（每条 **111 字节**：15 字节骨骼名、uint32 帧号、
+VMD 是二进制格式：文件头 `Vocaloid Motion Data 0002`(30 字节)+ 模型名（20 字节，
+Shift-JIS)+ 骨骼关键帧数组（每条 **111 字节**: 15 字节骨骼名、uint32 帧号、
 float32x3 位移、float32x4 旋转四元数、64 字节贝塞尔插值参数）+ morph / 相机 /
 灯光 / 自阴影 / IK / 可见性段落。**VMD 不含骨骼长度**，只有旋转（少数骨骼带位移），
 因此服务端必须自带一套标准 MMD 骨架才能做 FK。
 
 处理链路：`vmd-parser.ts`（二进制 + Shift-JIS + 贝塞尔插值）-> `mmd-skeleton.ts`
-（标准骨架）-> `mmd-pose.ts`（FK + 腿部 IK）-> `retarget.ts` 的
+（标准骨架）-> `mmd-pose.ts`(FK + 腿部 IK)-> `retarget.ts` 的
 `worldFramesToKeypointFrames()`（与 BVH 完全共用骨盆归零 / 自适应缩放 / 图像空间投影 /
-9 个关节角）。固定 **30 fps**（MMD 帧率恒定，上传时填写的 `fps` 被忽略）。
+9 个关节角）。固定 **30 fps**(MMD 帧率恒定，上传时填写的 `fps` 被忽略)。
 
 | MediaPipe 点 | MMD 标准骨骼 | 说明 |
 |--|--|--|
@@ -149,11 +149,11 @@ float32x3 位移、float32x4 旋转四元数、64 字节贝塞尔插值参数）
 骨骼名按 `mmd-skeleton.ts` 的别名表归一（含全角 `ＩＫ` / 半角 `IK` 两种写法）；
 未纳入标准骨架的骨骼（裙摆、物理、表情等）被忽略但会计数并写入预处理日志。
 
-**腿部驱动判定**：`足ＩＫ` 轨道存在非零位移 -> 走 IK（用两骨骼解析 IK 把踝拉到 IK
+**腿部驱动判定**: `足ＩＫ` 轨道存在非零位移 -> 走 IK（用两骨骼解析 IK 把踝拉到 IK
 目标点，膝盖朝角色正面弯，不可达时收敛为伸直）；否则走 FK（部分动作数据把腿烘焙成
 FK 旋转）。两份示例文件分别命中两种路径。
 
-**坐标系**：MMD 原生是左手系（正面为 -Z），本项目通路是右手系（正面为 +Z、+X 为角色
+**坐标系**: MMD 原生是左手系（正面为 -Z），本项目通路是右手系（正面为 +Z、+X 为角色
 左侧）。VMD 的四元数与位移统一做 Z 镜像（`(x,y,z,w) -> (-x,-y,z,w)`、位移 z 取反）后
 送入标准骨架。该选择由真实数据对照实验确定：腿部烘焙为 FK 的样本中，`zMirrored` 下
 膝盖朝前占比 94.1%，不转换时仅 5.9%（见 `test/mmd-vmd.spec.ts`）。
@@ -167,15 +167,15 @@ FK 旋转）。两份示例文件分别命中两种路径。
 
 | 项 | 值 |
 |--|--|
-| 单文件上限 | 512 MiB（`UPLOAD_MAX_BYTES` 可覆盖） |
+| 单文件上限 | 512 MiB(`UPLOAD_MAX_BYTES` 可覆盖) |
 | 允许扩展名 | 上表全部；其他一律 422 |
 | 存储路径 | `${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}` |
 | 去重 | 相同 sha256 复用同一 `assets` 记录，不重复落盘 |
 | 文件名 | 服务端不使用原始文件名做路径，只存 `assets.original_name` |
 
-## 4. 开源依赖与许可证（引用 `open-source-credits.md`）
+## 4. 开源依赖与许可证(引用 `open-source-credits.md`)
 
-- `bvh`（MIT）- BVH 解析参考实现
-- `Assimp`（BSD-3-Clause）- FBX/glTF 转换，**可选外部依赖**
-- `@pixiv/three-vrm`（MIT）- 管理端 VRM 预览
-- `three`（MIT）- 管理端 3D 预览
+- `bvh`(MIT)- BVH 解析参考实现
+- `Assimp`(BSD-3-Clause)- FBX/glTF 转换，**可选外部依赖**
+- `@pixiv/three-vrm`(MIT)- 管理端 VRM 预览
+- `three`(MIT)- 管理端 3D 预览

contracts/skeleton-topology.md

@@ -47,7 +47,7 @@
 | 33 | neck | `midpoint(left_shoulder(11), right_shoulder(12))` |
 | 34 | pelvis | `midpoint(left_hip(23), right_hip(24))` |
 
-## 3. 父节点表（`parent[i]`，-1 表示世界根）
+## 3. 父节点表（`parent[i]`, -1 表示世界根）
 
 对称树，便于骨骼重定向与关节角计算：
 
@@ -91,16 +91,16 @@
 
 ## 4. 坐标系
 
-- **归一化图像坐标**：`x, y ∈ [0, 1]`，原点左上角，`y` 向下；`x` 相对图像宽，`y` 相对图像高。
-- **深度**：`z` 与 `x` 同尺度，原点位于髋中心，**负值朝向相机**。
-- **镜像**：Android 前置摄像头默认输出镜像画面；是否镜像由帧头 `flags.bit0` 声明，
-  接收端据此决定是否翻转 `x`（`x' = 1 - x`）。
-- **置信度**：`visibility ∈ [0, 1]`，落盘/传输为 `uint8`（`round(v * 255)`）。
+- **归一化图像坐标**: `x, y ∈ [0, 1]`，原点左上角，`y` 向下；`x` 相对图像宽，`y` 相对图像高。
+- **深度**: `z` 与 `x` 同尺度，原点位于髋中心，**负值朝向相机**。
+- **镜像**: Android 前置摄像头默认输出镜像画面；是否镜像由帧头 `flags.bit0` 声明，
+  接收端据此决定是否翻转 `x`(`x' = 1 - x`)。
+- **置信度**: `visibility ∈ [0, 1]`，落盘/传输为 `uint8`(`round(v * 255)`)。
   归一化比例统一使用 `32767`（见 `websocket-keypoints.md`）。
 
 ## 5. 派生特征（DTW 输入，Windows 端实现，服务端预处理产物同构）
 
-服务端 T-WEB-006 预处理产出的关键点序列与 Android 端输出的帧**结构完全一致**，
+服务端 T-WEB-006 预处理产出的关键点序列与 Android 端输出的帧**结构完全一致**,
 因此 Windows 端 DTW 引擎只有一条输入通路。
 
 关节角特征（弧度，余弦值便于插值）：

contracts/websocket-keypoints.md

@@ -10,17 +10,17 @@ ws://<windows-host>:8765/pose
 ```
 
 - Windows 客户端监听，Android App 主动连接。
-- 子协议：`opendance.pose.v1`（`Sec-WebSocket-Protocol`）
+- 子协议：`opendance.pose.v1`(`Sec-WebSocket-Protocol`)
 - 二进制帧传输关键点，文本帧传输控制消息（JSON）。
 - 默认 30 FPS；发送端允许丢帧，接收端必须按 `frame_id` 检测丢包并插值补齐。
 
 ## 2. 二进制帧：239 字节（冻结）
 
-**小端序（little-endian）**。
+**小端序(little-endian)**。
 
 ```
 偏移  长度  字段          类型      说明
-0     2     magic         u16 LE    固定 0x4F44（ASCII "OD"）
+0     2     magic         u16 LE    固定 0x4F44(ASCII "OD")
 2     1     version       u8        固定 0x01
 3     1     flags         u8        bit0 = 镜像画面(mirrored)
                                     bit1 = 本帧含低置信度点(<0.5)
@@ -32,7 +32,7 @@ ws://<windows-host>:8765/pose
 合计  239
 ```
 
-### 单个关键点（7 字节，`i` 为 0..32）
+### 单个关键点(7 字节，`i` 为 0..32)
 
 ```
 偏移  长度  字段   类型     换算
@@ -43,7 +43,7 @@ ws://<windows-host>:8765/pose
 ```
 
 - 点索引与坐标语义见 `skeleton-topology.md`。
-- 编码：`x = clamp(round(x_norm * 32767), -32768, 32767)`，`y`、`z` 同理。
+- 编码：`x = clamp(round(x_norm * 32767), -32768, 32767)`, `y`、`z` 同理。
 - 低置信度点（`conf < 128`）坐标无意义，接收端必须插值，不得直接使用。
 - `i16` 为有符号数：`0x8000` 表示 `-32768`。
 
@@ -68,7 +68,7 @@ func decode(buf: PackedByteArray) -> Dictionary:
     return {"flags": flags, "frame_id": frame_id, "points": pts}
 ```
 
-## 3. 文本控制帧（JSON，UTF-8）
+## 3. 文本控制帧(JSON, UTF-8)
 
 ### 3.1 `hello` - Android -> Windows，连接后立即发送
 

deploy/.env.example

@@ -24,10 +24,10 @@ HOST=0.0.0.0
 ADMIN_DIR=/opt/opendance/admin
 
 # ---- 现有 MySQL / MariaDB 实例（本项目不安装、不管理数据库）----
-DB_HOST=<existing-mysql-host>
+DB_HOST='<existing-mysql-host>'
 DB_PORT=3306
 DB_USER=opendance_app
-DB_PASS=<数据库口令>
+DB_PASS='<数据库口令>'
 DB_NAME=opendance
 # 生产环境必须为 false，表结构一律走 TypeORM migration
 DB_SYNCHRONIZE=false
@@ -50,7 +50,9 @@ ASSIMP_BIN=assimp
 #        humanoid 骨骼名映射不全时会自动回退交付 GLB 并写进 conversion_note
 MODEL_CONVERT_FORMAT=glb
 # 压缩包里优先选用的 PMX 文件名（大小写不敏感）；找不到时按"格式优先级 -> 目录最浅 -> 文件最大"挑
-MODEL_CONVERT_PMX=Hatsune Miku.pmx
+# 值里含空格或 shell 元字符时必须用引号包起来（install.sh 会用
+# `set -a; . deploy/.env` 真的执行本文件；不加引号会把 "Miku.pmx" 当命令）
+MODEL_CONVERT_PMX="Hatsune Miku.pmx"
 # 单次转换超时（毫秒）
 MODEL_CONVERT_TIMEOUT_MS=180000
 

deploy/ctl.sh

@@ -13,6 +13,7 @@
 # ============================================================
 set -uo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
 APP_DIR="${APP_DIR:-/opt/opendance}"
 SERVICE_USER="${SERVICE_USER:-opendance}"
 LOG_FILE="${LOG_FILE:-/var/log/opendance-api.log}"
@@ -95,8 +96,14 @@ start() {
     return 0
   fi
 
-  # 载入部署环境变量
+  # 载入部署环境变量（先做语法预检：.env 会被 shell 真的执行）
   if [ -f "$APP_DIR/deploy/.env" ]; then
+    if [ -f "$SCRIPT_DIR/env-lib.sh" ]; then
+      # shellcheck source=deploy/env-lib.sh
+      . "$SCRIPT_DIR/env-lib.sh"
+      opendance_validate_env_file "$APP_DIR/deploy/.env" \
+        || die "$APP_DIR/deploy/.env 语法预检未通过（见上）：给对应行的值加上引号后重试。"
+    fi
     set -a; . "$APP_DIR/deploy/.env"; set +a
   else
     die "缺少 $APP_DIR/deploy/.env"

deploy/env-lib.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# ============================================================
+# OpenDance Studio Web API —— deploy/.env 语法预检
+#
+# 本文件被 install.sh 与 ctl.sh 引用（不要单独执行）。
+#
+# 为什么需要：
+#   两个脚本都用 `set -a; . deploy/.env` 载入配置，shell 会**真的执行**
+#   这个文件。若某个值含空格或 shell 元字符却没加引号，这一行会被切成
+#   「赋值 + 命令」，报错形如：
+#       ./deploy/.env: line 53: Miku.pmx: command not found
+#   退出码 127，而且提示里看不出是哪个文件、哪一行、该怎么改。
+#   载入前先做一次静态检查，给出带行号与修复建议的中文提示。
+#
+# 约定（与 init-env.sh 一致）：
+#   普通值不加引号（如 PORT=3000）；值里含空格或 shell 元字符时用引号包起来，
+#   例如 MODEL_CONVERT_PMX="Hatsune Miku.pmx"。双引号内不要用 $(...) 或反引号
+#   —— 它们在载入时会被真正执行。单引号是字面量，最安全。
+# ============================================================
+
+# 裸值（未加引号）是否可以被 `set -a; . file` 安全载入
+#   赋值语句里的裸值不会做通配展开，所以 * ? [ ] { } ! % + , - . : / @ = 都安全；
+#   真正会破坏解析的是：空白、& | ; $ ` < > ( ) \ 以及引号本身、行首的 ~
+opendance_env_value_is_safe_unquoted() {
+  local v="${1:-}"
+  [ -z "$v" ] && return 0
+  case "$v" in
+    *[[:space:]]*|*'&'*|*'|'*|*';'*|*'$'*|*'`'*|*'<'*|*'>'*|*'('*|*')'*|*'\'*|*'"'*|*"'"*) return 1 ;;
+    '~'*) return 1 ;;
+  esac
+  return 0
+}
+
+# 值本身是否是安全的写法（空值 / 加引号 / 裸值但字符安全）
+# 允许「引号 + 行尾注释」的写法，例如 DB_HOST="127.0.0.1"   # 本机
+opendance_env_value_is_safe() {
+  local v="${1:-}" inner="" rest=""
+  case "$v" in
+    '') return 0 ;;
+    \"*)
+      case "$v" in *\"*) ;; *) return 1 ;; esac          # 结束引号必须在
+      inner="${v#\"}"; inner="${inner%%\"*}"             # 引号内的内容
+      case "$inner" in *'$('*|*'`'*) return 1 ;; esac     # 双引号内会真的执行
+      rest="${v#\"}"; rest="${rest#*\"}"                 # 结束引号之后的内容
+      case "$rest" in
+        ''|[[:space:]]|[[:space:]]*|[[:space:]]*'#'*) return 0 ;;
+        *) return 1 ;;
+      esac ;;
+    \'*)
+      case "$v" in *\'*) ;; *) return 1 ;; esac
+      rest="${v#\'}"; rest="${rest#*\'}"
+      case "$rest" in
+        ''|[[:space:]]|[[:space:]]*|[[:space:]]*'#'*) return 0 ;;
+        *) return 1 ;;
+      esac ;;
+    *) opendance_env_value_is_safe_unquoted "$v" ;;
+  esac
+}
+
+# 校验一个 .env 文件：opendance_validate_env_file <文件路径>
+#   通过返回 0；发现不安全写法返回 1（问题行与其改法已打印到 stderr)
+opendance_validate_env_file() {
+  local file="${1:-}" lineno=0 bad=0 line key value reason inner
+  if [ ! -f "$file" ]; then
+    printf '[env] 找不到配置文件：%s\n' "$file" >&2
+    return 1
+  fi
+  while IFS= read -r line || [ -n "$line" ]; do
+    lineno=$((lineno + 1))
+    line="${line%$'\r'}"                     # 兼容 CRLF
+    case "$line" in ''|'#'*) continue ;; esac
+    reason=""
+    case "$line" in
+      [A-Za-z_]*=*) ;;
+      *) reason="不是「键=值」形式（载入时会被当成命令执行）" ;;
+    esac
+    if [ -z "$reason" ]; then
+      key="${line%%=*}"
+      value="${line#*=}"
+      case "$key" in
+        *[!A-Za-z0-9_]*) reason="键名含非法字符" ;;
+      esac
+    fi
+    if [ -z "$reason" ] && ! opendance_env_value_is_safe "$value"; then
+      case "$value" in
+        \"*)
+          inner="${value#\"}"
+          case "$inner" in
+            *\"*) reason="引号写法不安全：引号后有其它内容，或引号内用了 \$( ) / 反引号（载入时会真的执行）" ;;
+            *)    reason="双引号未闭合" ;;
+          esac ;;
+        \'*)
+          inner="${value#\'}"
+          case "$inner" in
+            *\'*) reason="单引号后还有其它内容，请把整个值放进引号" ;;
+            *)    reason="单引号未闭合" ;;
+          esac ;;
+        *)   reason="值含空格或 shell 元字符，却未加引号" ;;
+      esac
+    fi
+    if [ -n "$reason" ]; then
+      bad=$((bad + 1))
+      printf '\033[1;31m[env]\033[0m %s 第 %d 行写法不安全：%s\n' "$file" "$lineno" "$reason" >&2
+      printf '      %d | %s\n' "$lineno" "$line" >&2
+      case "$line" in
+        *'='*)
+          key="${line%%=*}"; value="${line#*=}"
+          case "$value" in
+            \"*|\'*)
+              printf '      提示: 引号请成对、且把整个值包住; 单引号是字面量, 最安全。\n' >&2 ;;
+            *"'"*)
+              printf '      提示: 值里同时有单引号与特殊字符, 请手工调整 - 单引号内不能再出现单引号。\n' >&2 ;;
+            *'$'*|*'`'*)
+              printf "      改法: %s='%s'  注意: 双引号里的 \$( ) 与反引号会被真的执行, 单引号才是字面量。\n" "$key" "$value" >&2 ;;
+            *)
+              printf '      改法: %s="%s"\n' "$key" "$value" >&2 ;;
+          esac ;;
+      esac
+    fi
+  done < "$file"
+  if [ "$bad" -gt 0 ]; then
+    printf '\033[1;31m[env]\033[0m %s 语法预检未通过：%d 行需要加引号（见上）。\n' "$file" "$bad" >&2
+    return 1
+  fi
+  return 0
+}

deploy/install.sh

@@ -21,11 +21,18 @@
 # ============================================================
 set -euo pipefail
 # 失败时打印出错行号，避免只看到半截输出
-trap 'printf "\033[1;31m[install]\033[0m 第 %d 行执行失败（退出码 %d）\n" "$LINENO" "$?" >&2' ERR
+trap 'printf "\033[1;31m[install]\033[0m %s 第 %d 行执行失败（退出码 %d）\n" "${BASH_SOURCE[0]}" "$LINENO" "$?" >&2' ERR
 
 SRC_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$SRC_DIR"
 
+# .env 语法预检（deploy/env-lib.sh）：.env 是被 shell 真正 source 的文件，
+# 未加引号且含空格的值会被当成命令执行，报错形如
+#   ./deploy/.env: line 53: Miku.pmx: command not found
+# 载入前先查一遍，给出带行号与改法的中文提示。
+# shellcheck source=deploy/env-lib.sh
+. "$SRC_DIR/deploy/env-lib.sh"
+
 APP_DIR="${APP_DIR:-/opt/opendance}"
 SERVICE_USER="${SERVICE_USER:-opendance}"
 STORAGE_DIR="${STORAGE_DIR:-/var/lib/opendance/storage}"
@@ -125,6 +132,8 @@ if [ ! -f deploy/.env ]; then
   fi
 fi
 
+opendance_validate_env_file "./deploy/.env" || die "deploy/.env 语法预检未通过（见上）：按提示给对应行的值加上引号后重新执行。"
+
 set -a
 # shellcheck disable=SC1091
 . ./deploy/.env
@@ -320,6 +329,7 @@ fi
 
 # ---------- 3. 数据库迁移 ----------
 log "执行 TypeORM 迁移（不使用 DB_SYNCHRONIZE）"
+opendance_validate_env_file "$APP_DIR/deploy/.env" || die "$APP_DIR/deploy/.env 语法预检未通过（见上）"
 set -a; . "$APP_DIR/deploy/.env"; set +a
 cd "$APP_DIR/web-server"
 as_service_user env \

deploy/proxy/README.md

@@ -1,6 +1,6 @@
-# 反向代理说明（nginx / IIS）
+# 反向代理说明(nginx / IIS)
 
-> **职责边界**：本 Web 端**只提供业务服务**（NestJS API + 管理端页面），
+> **职责边界**：本 Web 端**只提供业务服务**(NestJS API + 管理端页面),
 > **不部署、不配置反向代理**。反向代理由另外的服务或团队负责，本文档只提供配置说明。
 >
 > 安装脚本 `deploy/install.sh` 不会安装或修改任何反代软件。
@@ -11,16 +11,16 @@
 
 | 端口 | 环境变量 | 默认 | 给谁用 | 提供什么 |
 |--|--|--|--|--|
-| 软件 API 端口 | `PORT` | `3000` | Windows/Godot 客户端、Android App | `/api`、`/health`、`/static`、`/contracts`；**不含管理页面**（未知路径 404） |
+| 软件 API 端口 | `PORT` | `3000` | Windows/Godot 客户端、Android App | `/api`、`/health`、`/static`、`/contracts`; **不含管理页面**(未知路径 404) |
 | 管理端端口 | `ADMIN_PORT` | `3001` | 浏览器（管理员） | 管理页面 + 上面全部接口 |
 
 ```
-软件 API：  http://<后端地址>:3000
+软件 API:  http://<后端地址>:3000
 管理端：    http://<后端地址>:3001
 ```
 
 两者都不需要在代理层托管静态文件，也不需要配置 SPA 回退（服务端已处理）；
-各用一条 `location /`（nginx）或全匹配规则（IIS）即可。
+各用一条 `location /`(nginx)或全匹配规则（IIS）即可。
 
 **推荐做法**：把两个端口挂在两个不同的站点/域名上，便于分别做访问控制，例如
 
@@ -33,12 +33,12 @@
 | 路径 | 内容 | 哪个端口提供 |
 |--|--|--|
 | `/`、`/assets/*` | 管理端页面与静态资源 | **仅管理端**；前端路由深链接（如 `/songs`）由服务端回退到 `index.html` |
-| `/api/*` | REST API | 两个端口都提供（契约见 `contracts/rest-api.yaml`） |
+| `/api/*` | REST API | 两个端口都提供(契约见 `contracts/rest-api.yaml`) |
 | `/health` | 健康检查 | 两个端口都提供；可用作反代的存活探测，数据库不可用时返回 **503** |
 | `/static/*` | 上传文件 | 两个端口都提供（模型 / 音频 / 关键点序列） |
 | `/contracts/*` | 契约快照 | 两个端口都提供，只读 |
 
-> Windows 客户端与 Android 之间的**关键点 WebSocket 链路不经过本服务**，
+> Windows 客户端与 Android 之间的**关键点 WebSocket 链路不经过本服务**,
 > 反代无需配置 WebSocket 转发。
 >
 > `ADMIN_PORT` 设为与 `PORT` 相同时是**单端口兼容模式**：两个端口合一，
@@ -58,7 +58,7 @@
 
 ## 三、必须同步调整的两项
 
-1. **上传上限**：本服务默认允许 512 MiB（`UPLOAD_MAX_BYTES`）。
+1. **上传上限**：本服务默认允许 512 MiB(`UPLOAD_MAX_BYTES`)。
    代理层默认值通常远小于此（nginx 1 MB、IIS 约 28.6 MB），不改会导致大模型上传失败。
 2. **超时**：上传大文件与下载关键点序列可能较慢，代理的读写超时必须放大。
 
@@ -138,7 +138,7 @@ IIS 管理器 -> 选中服务器节点 -> Application Request Routing Cache
     </rewrite>
     <security>
       <requestFiltering>
-        <!-- 512 MiB：IIS 默认约 28.6 MB，不改大文件上传必失败 -->
+        <!-- 512 MiB:IIS 默认约 28.6 MB，不改大文件上传必失败 -->
         <requestLimits maxAllowedContentLength="536870912" />
       </requestFiltering>
     </security>
@@ -181,10 +181,10 @@ curl -i http://127.0.0.1:3001/health
 # 2. 经反代可访问
 curl -i http://<反代地址>/health
 
-# 3. 管理端页面可打开（应返回 HTML）
+# 3. 管理端页面可打开(应返回 HTML)
 curl -i http://<反代地址>/ | head -5
 
-# 4. 前端深链接可用（应返回同一份 HTML，而不是 404）
+# 4. 前端深链接可用(应返回同一份 HTML，而不是 404)
 curl -i http://<反代地址>/songs | head -5
 
 # 5. API 可用
@@ -196,7 +196,7 @@ curl -i http://<反代地址>/api/catalog/version
 
 | 现象 | 原因 |
 |--|--|
-| 反代 502 / 504 | 后端未启动，或 `HOST` 绑定地址不对（同机应为 `127.0.0.1`，异机应为 `0.0.0.0`） |
+| 反代 502 / 504 | 后端未启动，或 `HOST` 绑定地址不对(同机应为 `127.0.0.1`，异机应为 `0.0.0.0`) |
 | 页面能开、接口 404 | 只转发了 `/`，需要把 `/api/`、`/health`、`/static/` 一并转发（最简单是全匹配） |
 | 上传大文件 413 | 代理层上传上限没放开（见第三、四、五节） |
 | 上传中途断开 | 代理超时太短 |
@@ -210,7 +210,7 @@ curl -i http://<反代地址>/api/catalog/version
 在运维侧配好反代之前，可以直接访问后端业务服务（本项目开箱即用，不依赖反代）：
 
 1. `deploy/.env` 中 `HOST=0.0.0.0`（若只想让某个网段访问，也可填具体网卡地址）
-2. 防火墙放行后端端口（默认 `3000/tcp`）
+2. 防火墙放行后端端口(默认 `3000/tcp`)
 3. 浏览器访问 `http://<服务器IP>:3000`
 
 > 注意：服务默认在 **3000** 端口，不在 80/443。直接访问 `http://<服务器IP>/`

project.yaml

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

scripts/package-release.sh

@@ -1,15 +1,17 @@
 #!/bin/bash
 # ============================================================
-# 打包发布产物：opendance-web-v0.1.0.tar.gz
+# 打包发布产物：opendance-web-v0.2.1.tar.gz
 #
 # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
 #   web-server/      NestJS 源码 + 构建产物
 #   admin/           React 管理端构建产物
 #   deploy/          install.sh / ctl.sh / uninstall.sh / .env.example
+#                    env-lib.sh (.env 语法预检) / init-env.sh (.env 引导)
 #                    systemd|openrc|initd / proxy（反代说明文档，仅文档不部署）
 #   contracts/       当前版本契约快照
 #   THIRD_PARTY.md   开源项目声明
-#   README.txt       使用说明
+#   README.md        使用说明(Markdown, 仓库首页展示的就是它)
+#   README.txt       使用说明(纯文本同内容版本)
 #
 # 用法：./scripts/package-release.sh [版本号]
 # ============================================================
@@ -18,7 +20,7 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"
 
-VERSION="${1:-0.2.0}"
+VERSION="${1:-0.2.1}"
 NAME="opendance-web-v${VERSION}"
 OUT_DIR="$REPO_ROOT/dist-release"
 STAGE="$OUT_DIR/$NAME"
@@ -76,7 +78,7 @@ cp -r deploy "$STAGE/deploy"
 rm -f "$STAGE/deploy/.env"
 rm -rf "$STAGE/deploy"/systemd/*.bak "$STAGE/deploy"/openrc/*.bak "$STAGE/deploy"/initd/*.bak
 cp -r contracts "$STAGE/contracts"
-cp THIRD_PARTY.md README.txt project.yaml DSH.md "$STAGE/"
+cp THIRD_PARTY.md README.txt README.md project.yaml DSH.md "$STAGE/"
 cp -r tasks "$STAGE/tasks"
 
 # ---------- 5. 打包 ----------
@@ -129,13 +131,15 @@ for required in \
   "opendance-web-v${VERSION}/web-server/dist/models/vrm-writer.js" \
   "opendance-web-v${VERSION}/web-server/dist/models/gltf-packer.js" \
   "opendance-web-v${VERSION}/deploy/init-env.sh" \
+  "opendance-web-v${VERSION}/deploy/env-lib.sh" \
   "opendance-web-v${VERSION}/deploy/proxy/README.md" \
   "opendance-web-v${VERSION}/deploy/proxy/nginx.conf.example" \
   "opendance-web-v${VERSION}/deploy/proxy/web.config.example" \
   "opendance-web-v${VERSION}/deploy/systemd/opendance-api.service" \
   "opendance-web-v${VERSION}/contracts/VERSION" \
   "opendance-web-v${VERSION}/THIRD_PARTY.md" \
-  "opendance-web-v${VERSION}/README.txt" ; do
+  "opendance-web-v${VERSION}/README.txt" \
+  "opendance-web-v${VERSION}/README.md" ; do
   if ! grep -qx "$required" <<< "$MANIFEST_TMP"; then
     echo "  ✗ 缺少关键文件：$required" >&2
     fail=1

tasks/001-scaffold.md

@@ -1,6 +1,6 @@
 # T-WEB-001 骨架 + 连接现有 MySQL
 
-- **状态**：done
+- **状态**: done
 - **依赖**：无
 
 ## 目标
@@ -29,7 +29,7 @@ web-server/src/db/data-source.ts
 | `web-server/src/app.module.ts` | 根模块，`TypeOrmModule.forRootAsync` 由 `AppConfig` 注入连接信息 |
 | `web-server/src/config/configuration.ts` | 类型化配置层，唯一读取 `process.env` 的位置 |
 | `web-server/src/config/config.module.ts` | 全局配置模块 |
-| `web-server/src/db/data-source.ts` | TypeORM DataSource（CLI + 运行期共用），`synchronize: false` |
+| `web-server/src/db/data-source.ts` | TypeORM DataSource(CLI + 运行期共用), `synchronize: false` |
 | `web-server/src/health/health.controller.ts` | `GET /health`，真实探测数据库连通性 |
 | `web-server/.env.example` | 环境变量样例 |
 
@@ -61,4 +61,4 @@ curl -s http://localhost:3000/health
 
 ## 结果
 
-- 已连通 `<数据库主机>:3306/opendance`，`/health` 返回 200 且 `connected=true`。
+- 已连通 `<数据库主机>:3306/opendance`, `/health` 返回 200 且 `connected=true`。

tasks/002-db-migration.md

@@ -1,7 +1,7 @@
 # T-WEB-002 TypeORM 迁移生成表结构
 
-- **状态**：done
-- **依赖**：T-WEB-001
+- **状态**: done
+- **依赖**: T-WEB-001
 
 ## 目标
 
@@ -25,7 +25,7 @@ web-server/src/db/data-source.ts
 |---|---|---|
 | `assets` | 上传文件元数据 | `sha256` 唯一索引（去重）、`stored_path`、`size` |
 | `songs` | 曲目 | 来源五元组、`status`、`deleted_at` |
-| `motions` | 动作数据 | `song_id` FK（ON DELETE SET NULL）、预处理产物列 |
+| `motions` | 动作数据 | `song_id` FK(ON DELETE SET NULL)、预处理产物列 |
 | `models` | 角色模型 | `format`、`vrm_version`、`is_primary` |
 | `review_records` | 审核流水 | `(target_type, target_id)` 复合索引 |
 
@@ -33,7 +33,7 @@ web-server/src/db/data-source.ts
 
 - 表名 `snake_case` 复数；主键 `BIGINT AUTO_INCREMENT`
 - 时间列 `DATETIME`；软删除 `deleted_at`
-- Tags 使用 `simple-json`（MariaDB 下落 LONGTEXT，规避 JSON 类型差异）
+- Tags 使用 `simple-json`(MariaDB 下落 LONGTEXT，规避 JSON 类型差异)
 
 ## 交付物
 

tasks/003-song-crud.md

@@ -1,7 +1,7 @@
 # T-WEB-003 /api/songs CRUD
 
-- **状态**：done
-- **依赖**：T-WEB-002
+- **状态**: done
+- **依赖**: T-WEB-002
 
 ## 目标
 
@@ -27,7 +27,7 @@ web-server/src/common/pagination.ts
 | GET | `/api/songs/:id` | 详情 |
 | PATCH | `/api/songs/:id` | 更新（来源需五元组同时提交） |
 | DELETE | `/api/songs/:id` | **软删除** |
-| POST | `/api/songs/:id/audio` | 上传音频（multipart，字段名 `file`） |
+| POST | `/api/songs/:id/audio` | 上传音频(multipart，字段名 `file`) |
 | POST | `/api/songs/:id/cover` | 上传封面 |
 
 ## 关键实现

tasks/004-motion-upload.md

@@ -1,7 +1,7 @@
 # T-WEB-004 动作数据上传 + 来源字段
 
-- **状态**：done
-- **依赖**：T-WEB-002
+- **状态**: done
+- **依赖**: T-WEB-002
 
 ## 目标
 
@@ -29,17 +29,17 @@ web-server/src/preprocess/retarget.ts     # worldFramesToKeypointFrames()
 | GET | `/api/motions` | 分页 + `q`/`songId`/`format`/`status` 过滤 |
 | POST | `/api/motions` | multipart 上传 |
 | GET | `/api/motions/:id` | 详情 |
-| PATCH | `/api/motions/:id` | 更新元数据（含 `detachSong`） |
+| PATCH | `/api/motions/:id` | 更新元数据(含 `detachSong`) |
 | DELETE | `/api/motions/:id` | 软删除 |
 
-## 存储策略（`contracts/model-formats.md` 3）
+## 存储策略(`contracts/model-formats.md` 3)
 
 ```
 ${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}
 ```
 
-- 上传先落 `${STORAGE_DIR}/tmp`（multer diskStorage），避免大文件占用内存
-- `StorageService` 流式计算 sha256；**相同内容只落盘一次**，复用 `assets` 记录
+- 上传先落 `${STORAGE_DIR}/tmp`(multer diskStorage)，避免大文件占用内存
+- `StorageService` 流式计算 sha256; **相同内容只落盘一次**，复用 `assets` 记录
 - 并发同文件上传靠 `assets.sha256` 唯一索引兜底，冲突后回退到已存在记录
 - 路径永不使用原始文件名；`absolutePath()` 拒绝逃逸存储根目录
 
@@ -48,14 +48,14 @@ ${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}
 - 扩展名白名单：`.bvh.vmd.fbx.gltf.glb.json`，其他 -> 400
 - 来源五元组缺任一项 -> 400
 - `songId` 指向不存在的曲目 -> 400
-- 单文件上限 `UPLOAD_MAX_BYTES`（默认 512 MiB）
+- 单文件上限 `UPLOAD_MAX_BYTES`(默认 512 MiB)
 
-## VMD 支持（`.vmd`）
+## VMD 支持(`.vmd`)
 
-- 管理端上传控件已支持 `.vmd`（accept、格式筛选、中文标签「VMD（MMD）」）
-- 入库后 `format=vmd`；预处理走内置链路，不依赖 Assimp：
+- 管理端上传控件已支持 `.vmd`(accept、格式筛选、中文标签「VMD(MMD)」)
+- 入库后 `format=vmd`；预处理走内置链路，不依赖 Assimp:
   `vmd-parser.ts`（二进制 + Shift-JIS + 贝塞尔插值）-> `mmd-skeleton.ts`（标准骨架）
-  -> `mmd-pose.ts`（FK + 腿部 IK + Z 镜像）-> `retarget.ts` 的
+  -> `mmd-pose.ts`(FK + 腿部 IK + Z 镜像)-> `retarget.ts` 的
   `worldFramesToKeypointFrames()`（与 BVH 共用骨盆归零 / 自适应缩放 / 投影 / 关节角）
 - 固定 30 fps；腿部按 `足ＩＫ` 是否带位移自动选 IK 或 FK
 - 上传后处理失败与 BVH 一致：写入 `preprocessState=failed` 与可读错误
@@ -73,8 +73,8 @@ VMD 实测（用 `../示例文件/` 下的两个样本）：
 
 | 样本 | 帧数 | 腿部驱动 | 结果 |
 |--|--|--|--|
-| `【动作】霜雪千年.vmd`（0.79 MiB） | 2901 | `足ＩＫ` 驱动（IK） | 0 NaN / 0 越界，预处理约 0.4s |
-| `恋爱循环.vmd`（20.24 MiB） | 4604 | 烘焙 FK | 0 NaN / 0 越界，预处理约 2.5s |
+| `【动作】霜雪千年.vmd`(0.79 MiB) | 2901 | `足ＩＫ` 驱动(IK) | 0 NaN / 0 越界，预处理约 0.4s |
+| `恋爱循环.vmd`(20.24 MiB) | 4604 | 烘焙 FK | 0 NaN / 0 越界，预处理约 2.5s |
 
 上传前可先用诊断工具自查（只读）：
 

tasks/005-model-upload.md

@@ -1,12 +1,12 @@
 # T-WEB-005 模型上传（GLB/VRM 直接导入 + PMX/FBX 转换 + zip 自动搜索 + 分析/缩略图 + 上传即待审）
 
-- **状态**：done（v0.2.0 重构：GLB/VRM 主力、上传即待审）
-- **依赖**：T-WEB-002
+- **状态**: done(v0.2.0 重构：GLB/VRM 主力、上传即待审)
+- **依赖**: T-WEB-002
 
 ## 目标
 
 系统以 **GLB / VRM 为主力格式**（服务端与客户端都一等公民）：`.glb`/`.vrm`/`.gltf`
-**直接导入、不重编码**，`.pmx`/`.fbx` 服务端转换（**优先 GLB、其次 VRM**），`.zip`
+**直接导入、不重编码**, `.pmx`/`.fbx` 服务端转换（**优先 GLB、其次 VRM**），`.zip`
 **自动搜索包内可用模型**。入库后自动**分析**（面数 / 骨骼树 / humanoid 覆盖 / 可驱动性）
 与生成**缩略图**；状态**一律 `pending`**，经审核后才可能成为默认模型。
 
@@ -38,11 +38,11 @@ web-server/scripts/import-default-model.mjs
 | 方法 | 路径 | 说明 |
 |--|--|--|
 | GET | `/api/models` | 分页 + `q`/`format`/`status`/`primaryOnly` |
-| POST | `/api/models` | multipart 上传（`file` + 名称 + 来源五元组）；`file` 接受 `.glb`/`.vrm`/`.gltf`/`.pmx`/`.fbx`/`.zip`；**入库一律 pending** |
-| GET | `/api/models/:id` | 详情（含 `stats`、`thumbnailUrl`、`conversionNote`、`fileSha256`、`sourceSha256`） |
+| POST | `/api/models` | multipart 上传（`file` + 名称 + 来源五元组）；`file` 接受 `.glb`/`.vrm`/`.gltf`/`.pmx`/`.fbx`/`.zip`; **入库一律 pending** |
+| GET | `/api/models/:id` | 详情(含 `stats`、`thumbnailUrl`、`conversionNote`、`fileSha256`、`sourceSha256`) |
 | PATCH | `/api/models/:id` | 更新 |
 | DELETE | `/api/models/:id` | 软删除 |
-| POST | `/api/models/:id/primary` | 设为全局默认模型（**仅 `published` 允许，否则 409**） |
+| POST | `/api/models/:id/primary` | 设为全局默认模型(**仅 `published` 允许，否则 409**) |
 
 ## 格式策略（服务端与客户端一致）
 
@@ -54,7 +54,7 @@ web-server/scripts/import-default-model.mjs
 | `.zip` | **自动搜索包内可用模型**（见下） |
 
 客户端（Godot）本来就用内置 `GLTFDocument` 加载 glTF/GLB/VRM
-（`opendance-windows/src/model/vrm_loader.gd`），**无需改动**。服务端 humanoid 候选表
+(`opendance-windows/src/model/vrm_loader.gd`), **无需改动**。服务端 humanoid 候选表
 与客户端 `humanoid_map.gd` **逐字对齐**，由 `test/model-inspector.spec.ts` 断言两边一致。
 
 ## 压缩包自动搜索与转换
@@ -74,14 +74,14 @@ web-server/scripts/import-default-model.mjs
 | ZIP 读取 | `common/zip-reader.ts` | 中央目录/EOCD、STORE(0)+DEFLATE(8)、ZIP64 大小字段、Shift-JIS/GBK 文件名回退；拒绝 zip-slip 与加密条目；不支持的压缩方式报错 |
 | 选主模型 | `model-convert.ts` | 格式优先级 `.vrm` -> `.glb` -> `.gltf` -> `.pmx` -> `.fbx`；同一优先级内"`MODEL_CONVERT_PMX` 指名字（默认 `Hatsune Miku.pmx`，大小写不敏感）-> 目录最浅 -> 文件最大" |
 | 直接导入 | `importModelFile()` | `.vrm`/`.glb`/`.gltf` 原样入库；`.glb` 若含 `VRMC_vrm`/`VRM` 扩展会被识别为 VRM |
-| 转换 | `convertModelFile()` / `convertModelArchive()` | `MODEL_CONVERT_FORMAT=glb`（默认）|`vrm`；超时 `MODEL_CONVERT_TIMEOUT_MS`（默认 180000） |
+| 转换 | `convertModelFile()` / `convertModelArchive()` | `MODEL_CONVERT_FORMAT=glb`（默认）|`vrm`；超时 `MODEL_CONVERT_TIMEOUT_MS`(默认 180000) |
 | 回读校验 | `exportAndValidate()` | 每步产物**必须** `assimp info` 回读；退出码 0 但产物损坏也判失败 |
 | GLB 打包 | `gltf-packer.ts` | GLB 直出失败时导出 `.gltf`，把 `.bin` 与外部贴图自行合成单文件 GLB |
-| VRM 封装 | `vrm-writer.ts` | `MODEL_CONVERT_FORMAT=vrm` 时只改 JSON chunk 补 `extensions.VRMC_vrm`；humanoid 骨骼不全 -> **回退交付 GLB**，缺失骨骼写进说明 |
-| 贴图内嵌 | `glb-textures.ts` | 把 GLB 中外部 URI 贴图追加 bufferView 并内嵌进 BIN chunk（4 字节对齐） |
+| VRM 封装 | `vrm-writer.ts` | `MODEL_CONVERT_FORMAT=vrm` 时只改 JSON chunk 补 `extensions.VRMC_vrm`; humanoid 骨骼不全 -> **回退交付 GLB**，缺失骨骼写进说明 |
+| 贴图内嵌 | `glb-textures.ts` | 把 GLB 中外部 URI 贴图追加 bufferView 并内嵌进 BIN chunk(4 字节对齐) |
 | 溯源 | 迁移 `AddModelConversionFields1789450000000` | 压缩包原件存为 `model-archive` 资产 -> `models.source_asset_id`；说明 -> `models.conversion_note` |
 | 失败 | `models.service.ts` | 无可用模型 / Assimp 不可用 / 两条路径都失败 -> **HTTP 422**，不产生模型记录 |
-| 文件名编码 | `common/upload.util.ts` `decodeUploadName()` | 修正 multipart 文件名的 latin1/UTF-8 乱码（中文文件名原先存成 `模å_...`） |
+| 文件名编码 | `common/upload.util.ts` `decodeUploadName()` | 修正 multipart 文件名的 latin1/UTF-8 乱码(中文文件名原先存成 `模å_...`) |
 | DTO | `conversionNote` / `fileSha256` / `sourceSha256` / `stats` / `thumbnailUrl` | 契约 `data-models.md` 4、`rest-api.yaml` |
 
 ## 入库后自动：分析 + 缩略图（尽力而为，失败不影响入库）
@@ -93,11 +93,11 @@ web-server/scripts/import-default-model.mjs
 
 ## 状态与默认模型（硬性）
 
-- **上传一律 `status=pending`**（`models.service.ts` 固定 `PublishStatus.Pending`），
-  `is_primary=false`：**不再自动发布、不再自动设为默认**；服务端不再识别 `autoDefault`。
-- 默认模型只在下列时机设置，并把身份写进源码 `src/config/default-model.ts`：
-  1. 审核通过带 `setPrimary:true`：`POST /api/reviews/model/:id/approve`；
-  2. 显式设置：`POST /api/models/:id/primary`（**仅 `published` 允许，否则 409**）。
+- **上传一律 `status=pending`**(`models.service.ts` 固定 `PublishStatus.Pending`),
+  `is_primary=false`: **不再自动发布、不再自动设为默认**；服务端不再识别 `autoDefault`。
+- 默认模型只在下列时机设置，并把身份写进源码 `src/config/default-model.ts`:
+  1. 审核通过带 `setPrimary:true`: `POST /api/reviews/model/:id/approve`;
+  2. 显式设置：`POST /api/models/:id/primary`(**仅 `published` 允许，否则 409**)。
 - `GET /api/catalog/export` 的 `defaultModelId` 解析顺序（`resolveDefaultModelId()`）：
 
 ```
@@ -116,27 +116,27 @@ web-server/scripts/import-default-model.mjs
 
 `vrm-inspector.ts` 直接读取 GLB 头部 JSON chunk，不依赖完整 3D 库：
 
-- `extensions.VRMC_vrm` -> VRM **1.0**（取 `specVersion`）
+- `extensions.VRMC_vrm` -> VRM **1.0**(取 `specVersion`)
 - `extensions.VRM` -> VRM **0.x**
-- 两者皆无 -> `null`（普通 GLB）
+- 两者皆无 -> `null`(普通 GLB)
 
-## 实测（v0.2.0）
+## 实测(v0.2.0)
 
 - 上传含 `Hatsune Miku.pmx` 的 MMD 压缩包 -> **HTTP 201 / 0.86s**、`format=glb`、
   `status=pending`、`conversionNote=Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`。
   分析结果：`vertices=7155 triangles=9071 materials=3 textures=2 images=2 nodes=240
-  bones=238 skins=1 morphTargets=0 humanoidMapped=0/22 drivable=false maxBoneDepth=23`；
+  bones=238 skins=1 morphTargets=0 humanoidMapped=0/22 drivable=false maxBoneDepth=23`;
   `missingRequiredBones` 为**全部 16 根**（日文 MMD 骨名无法映射到 humanoid）。
-- 直接上传 `.glb` -> **HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`，
+- 直接上传 `.glb` -> **HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`,
   入库文件 sha256 与源文件**一致**（不重编码）。
 - 缩略图：512x512 PNG / 15,043 字节，服务端纯 TS 光栅化（含蒙皮），目视确认为居中的
-  T-pose 角色图；真实 10MB VRM（83 关节、5307 顶点）单张耗时 60-121ms（中位 79ms）。
-- 审核：`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200，
-  模型 `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...`；
+  T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。
+- 审核：`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200,
+  模型 `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...`;
   重建后 `GET /api/catalog/export` 的 `defaultModelId` 由 VRM 变为 **22**
   （库中另有 2 个已发布 VRM）。
 
-### 运维 CLI：`web-server/scripts/import-default-model.mjs`
+### 运维 CLI: `web-server/scripts/import-default-model.mjs`
 
 服务进程在 systemd 加固（`ProtectSystem=strict`）下写不了程序目录，源码种子
 通常由本脚本在沙箱外补写。需先 `npm run build`（复用 `dist/models/default-model-source.js`）。
@@ -146,21 +146,21 @@ cd web-server
 node scripts/import-default-model.mjs 模型.zip --url http://127.0.0.1:3000 \
   --name "初音未来 Hatsune Miku" --author "Boku Wa Luka" \
   --license "MMD 模型使用条款（见压缩包内说明）" --source-type other
-# 上传 -> 服务端转换入库（pending）-> 把身份写进 src/config/default-model.ts
+# 上传 -> 服务端转换入库(pending)-> 把身份写进 src/config/default-model.ts
 
 node scripts/import-default-model.mjs --write-source-only --model-id 22   # 只补写源码
 node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-run
 ```
 
 上传一律 pending，因此要让 CLI 写出的种子在 `defaultModelId` 中生效，仍需审核通过
-（勾选「同时设为全局默认模型」）或调用 `POST /api/models/:id/primary`；
-`--url` 默认 `http://127.0.0.1:3000`，`--source-type` 默认 `other`。
+（勾选「同时设为全局默认模型」）或调用 `POST /api/models/:id/primary`;
+`--url` 默认 `http://127.0.0.1:3000`, `--source-type` 默认 `other`。
 
 ## 验收
 
 ```bash
 cd web-server
-npx vitest run        # 10 个文件 / 168 项通过
+npx vitest run        # 11 个文件 / 180 项通过
 npm run test:smoke    # 冒烟 [4] 段落
 ```
 
@@ -170,7 +170,7 @@ npm run test:smoke    # 冒烟 [4] 段落
 | `.zip` 自动搜索包内模型 | ✅ 优先级 `.vrm`>`glb`>`.gltf`>`.pmx`>`.fbx`；同优先级按指名字->目录最浅->文件最大 |
 | `.pmx` 转换优先 GLB | ✅ 实测 201 / 0.86s、`format=glb`、2 张贴图内嵌 |
 | GLB 失败回退 glTF->GLB 打包 | ✅ GLB 直出失败时 `gltf-packer.ts` 自行打包；每步 `assimp info` 回读校验 |
-| `MODEL_CONVERT_FORMAT=vrm` 封装 | ✅ `vrm-writer.ts` 补 `VRMC_vrm`；humanoid 不全回退 GLB |
+| `MODEL_CONVERT_FORMAT=vrm` 封装 | ✅ `vrm-writer.ts` 补 `VRMC_vrm`; humanoid 不全回退 GLB |
 | 自动分析写入 `models.stats` | ✅ 实测 `triangles=9071 bones=238 humanoidMapped=0/22 drivable=false` |
 | 缩略图生成且不影响入库 | ✅ 512x512 / 15,043 B；失败只告警 |
 | 上传一律 pending、不自动设默认 | ✅ `create()` 固定 `PublishStatus.Pending` + `isPrimary=false` |
@@ -179,15 +179,15 @@ npm run test:smoke    # 冒烟 [4] 段落
 | 失败语义 | ✅ 无可用模型 / Assimp 不可用 / 两条路径均失败 -> HTTP 422，不产生模型记录 |
 | ZIP 安全 | ✅ 拒绝 zip-slip、加密条目、未知压缩方式（`model-archive.spec.ts` 24 项） |
 | humanoid 与客户端一致 | ✅ `model-inspector.spec.ts` 抽 `humanoid_map.gd` 逐键比对（25 项） |
-| VRM 版本识别 | ✅ `test/vrm-inspector.spec.ts`（6 例） |
+| VRM 版本识别 | ✅ `test/vrm-inspector.spec.ts`(6 例) |
 
-`test/model-archive.spec.ts`（**24 项**）覆盖 ZIP 解析 / zip-slip / 加密 / 未知压缩方式、
+`test/model-archive.spec.ts`(**24 项**)覆盖 ZIP 解析 / zip-slip / 加密 / 未知压缩方式、
 主模型挑选优先级、GLB 贴图内嵌、用**假 Assimp** 对照多种回退路径、源码渲染 + `tsc` 校验。
-`test/model-inspector.spec.ts`（**25 项**）覆盖 GLB 统计与骨骼树、VRM 识别、必需 16 根
+`test/model-inspector.spec.ts`(**25 项**)覆盖 GLB 统计与骨骼树、VRM 识别、必需 16 根
 humanoid 骨、非 glTF 容器降级、截断与健壮性、与客户端映射表逐字一致。
-`test/model-thumbnail.spec.ts`（**8 项**）覆盖缩略图 PNG 结构、蒙皮与降级路径。
+`test/model-thumbnail.spec.ts`(**8 项**)覆盖缩略图 PNG 结构、蒙皮与降级路径。
 
-## 追加：历史模型回填（`POST /api/models/:id/reanalyze`）
+## 追加：历史模型回填(`POST /api/models/:id/reanalyze`)
 
 升级到带 `models.stats` 的版本后，已有模型还没有分析与缩略图。重新分析接口只改
 `stats` 与 `thumbnailAssetId` 两个字段，用于回填 / 文件替换后刷新 / 缩略图渲染器升级后重出图。
@@ -198,8 +198,8 @@ node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000          # 回填
 node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000 --dry-run # 只列清单
 ```
 
-实测（真实 21MB VRM，290 骨骼）：回填出面数 53552 / 顶点 44662 / 骨骼 290 /
+实测（真实 21MB VRM, 290 骨骼）：回填出面数 53552 / 顶点 44662 / 骨骼 290 /
 humanoid 7/22，并重建 512x512 缩略图。
 文件在存储中丢失时返回 **409** 并说明原因，不会用全 0 结果覆盖既有分析数据。
-另外 `StorageService.persistBuffer` 在 sha256 去重命中但文件不存在时会**自愈补写**，
+另外 `StorageService.persistBuffer` 在 sha256 去重命中但文件不存在时会**自愈补写**,
 避免换过 `STORAGE_DIR` 或只恢复数据库后出现"静默全 0 分析"。

tasks/006-keypoint-preprocess.md

@@ -1,7 +1,7 @@
 # T-WEB-006 BVH/VMD/FBX -> 关键点序列预处理
 
-- **状态**：done
-- **依赖**：T-WEB-004
+- **状态**: done
+- **依赖**: T-WEB-004
 
 ## 目标
 
@@ -28,7 +28,7 @@ web-server/src/preprocess/*
 
 | 文件 | 职责 |
 |--|--|
-| `bvh-parser.ts` | 纯 TS BVH 词法/语法解析 + 逐帧前向运动学（FK） |
+| `bvh-parser.ts` | 纯 TS BVH 词法/语法解析 + 逐帧前向运动学(FK) |
 | `vmd-parser.ts` | VMD 二进制解析：30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼关键帧 + morph 段；MMD 贝塞尔插值，固定 30fps |
 | `mmd-skeleton.ts` | 标准 MMD 骨架（含全角/半角 `ＩＫ`/`IK` 别名归一）；静止比例从参考 PMX 实测 |
 | `mmd-pose.ts` | MMD FK + 两骨骼解析腿部 IK + 左手系->右手系 Z 镜像，输出逐帧世界坐标 |
@@ -36,14 +36,14 @@ web-server/src/preprocess/*
 | `joint-map.ts` | 关节名 -> MediaPipe 点索引的默认映射表 |
 | `retarget.ts` | 导出的 `worldFramesToKeypointFrames()`：任意骨架世界坐标 -> 骨盆归零 -> 自适应缩放 -> 投影 -> 9 个关节角；BVH 与 VMD 共用 |
 | `keypoint-codec.ts` | 239 字节二进制帧编解码、NDJSON 序列化/解析、关键点 JSON 校验 |
-| `assimp.ts` | 可选外部 Assimp 调用（FBX/glTF -> BVH） |
+| `assimp.ts` | 可选外部 Assimp 调用(FBX/glTF -> BVH) |
 | `preprocess.service.ts` | 编排、落盘、状态与错误记录 |
 
 ## 拓扑与缩放（契约冻结）
 
 - 33 点顺序与父节点表来自 `contracts/skeleton-topology.md`，虚拟关节
   `neck=33`、`pelvis=34` 只参与关节角计算，**不进入输出序列**。
-- 投影：`x_img = 0.5 + x s`，`y_img = 0.5 - y s`，`z_img = -z s`，
+- 投影：`x_img = 0.5 + x s`, `y_img = 0.5 - y s`, `z_img = -z s`,
   `s = 0.35 / max(|x|,|y|,|z|)`（按整段动作自适应，保证不出画）。
 - 置信度分层：直接映射 **1.0**、按层级推算 **0.5**、无法推算 **0.0**。
 
@@ -53,7 +53,7 @@ web-server/src/preprocess/*
 |--|--|
 | `.bvh` | 内置解析器，无外部依赖 |
 | `.vmd` | 内置解析器，无外部依赖；固定 30fps，见「VMD 通路」 |
-| `.json` | 直通校验与规范化（须符合 `mediapipe33@0.1.0`） |
+| `.json` | 直通校验与规范化(须符合 `mediapipe33@0.1.0`) |
 | `.fbx` `.gltf` `.glb` | 调用可选 Assimp 转 BVH；未安装 Assimp 时写入可读错误并置 `preprocessState=failed` |
 
 ## VMD 通路
@@ -67,13 +67,13 @@ web-server/src/preprocess/*
 - VMD 不含骨骼长度、只有旋转（少数骨骼带位移），必须靠 `mmd-skeleton.ts` 的
   标准骨架做 FK；骨骼名按别名表归一（全角 `ＩＫ` / 半角 `IK`），未纳入标准骨架的
   骨骼（裙摆 / 物理 / 表情等）被忽略但计数。
-- **腿部驱动自动判定**：`足ＩＫ` 轨道存在非零位移 -> 两骨骼解析 IK（膝盖朝角色
+- **腿部驱动自动判定**: `足ＩＫ` 轨道存在非零位移 -> 两骨骼解析 IK（膝盖朝角色
   正面弯，目标不可达时收敛为伸直，不产生 NaN）；否则走 FK 旋转（部分动作数据把
   腿烘焙成 FK）。
-- **手性**：MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) -> (-x,-y,z,w)`、位移 z
+- **手性**: MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) -> (-x,-y,z,w)`、位移 z
   取反）后进入右手系通路。由真实数据对照实验确定：腿部烘焙为 FK 的样本中，
   `zMirrored` 下「膝盖朝前」占 94.1%，不转换仅 5.9%（见 `test/mmd-vmd.spec.ts`）。
-- 重定向**完全复用 BVH 通路**：`worldFramesToKeypointFrames()` 负责骨盆归零 /
+- 重定向**完全复用 BVH 通路**: `worldFramesToKeypointFrames()` 负责骨盆归零 /
   自适应缩放 / 图像空间投影 / 9 个关节角，因此两种来源的产物结构一致。
 - 固定 **30 fps**，上传时填写的 `fps` 被忽略。
 
@@ -91,7 +91,7 @@ NDJSON 往返、解码器拒绝错误长度与 magic。
 VMD 侧另测：二进制解析与截断报错、贝塞尔/四元数插值、标准骨架比例与镜像、
 FK 与腿部 IK（可达/不可达/退化）、手性对照、合成 VMD 端到端 0 NaN / 0 越界。
 
-两个真实样本实测（`../示例文件/`）：`【动作】霜雪千年.vmd` 2901 帧（腿部 IK）
+两个真实样本实测（`../示例文件/`）：`【动作】霜雪千年.vmd` 2901 帧(腿部 IK)
 约 0.4s、`恋爱循环.vmd` 4604 帧（烘焙 FK）约 2.5s，均 0 NaN / 0 越界。
 
 样例数据由 `test/fixtures/generate-sample-bvh.mjs` 生成（60 帧挥手 + 深蹲，

tasks/007-upload-review.md

@@ -1,7 +1,7 @@
 # T-WEB-007 上传审核流程
 
-- **状态**：done（v0.2.0 追加：模型审核面板 / 骨骼详细界面 / `setPrimary`）
-- **依赖**：T-WEB-003 / 004 / 005
+- **状态**: done(v0.2.0 追加：模型审核面板 / 骨骼详细界面 / `setPrimary`)
+- **依赖**: T-WEB-003 / 004 / 005
 
 ## 目标
 
@@ -34,45 +34,45 @@ draft ──submit──▶ pending ──approve──▶ published
 | GET | `/api/reviews` | 不传 `status` -> 审核流水；传 `status` -> 该状态待审资产（三类合并） |
 | GET | `/api/reviews/:targetType/:id/history` | 单个资产的审核历史 |
 | POST | `/api/reviews/:targetType/:id/submit` | -> `pending` |
-| POST | `/api/reviews/:targetType/:id/approve` | -> `published`；**模型**可带 `setPrimary:true` |
-| POST | `/api/reviews/:targetType/:id/reject` | -> `rejected`，**必须填写意见** |
+| POST | `/api/reviews/:targetType/:id/approve` | -> `published`; **模型**可带 `setPrimary:true` |
+| POST | `/api/reviews/:targetType/:id/reject` | -> `rejected`, **必须填写意见** |
 | POST | `/api/reviews/:targetType/:id/withdraw` | -> `draft` |
 
 ## 关键实现
 
-- `STATUS_TRANSITIONS` 是状态机的唯一来源；非法流转一律 **409**，
+- `STATUS_TRANSITIONS` 是状态机的唯一来源；非法流转一律 **409**,
   重复审核同一状态同样 409。
 - 驳回未填 `comment` -> **400**（合规要求：拒绝侵权内容需留痕）。
 - 每次成功流转都写一条 `review_records`，记录 `fromStatus` / `toStatus` /
   `reviewer` / `comment`。
 - 三类资产的直连 PATCH 也会校验状态机，避免绕过审核流程。
 - `/api/catalog/export` 与 `/api/catalog/version` 只导出 `published`。
-- **模型上传只能 pending**：`ModelsService.create()` 固定
+- **模型上传只能 pending**: `ModelsService.create()` 固定
   `status=PublishStatus.Pending` + `isPrimary=false`，请求体里的 `autoDefault`
   等旁路一律不生效（硬性约束，见 DSH.md 6.9）。
 
-## 模型审核面板（v0.2.0）
+## 模型审核面板(v0.2.0)
 
 待审列表只有 `PendingItem`（不含模型详情），面板用 `item.targetId` 现拉
-`GET /api/models/:id`（`admin/src/components/ModelReviewPanel.tsx`）：
+`GET /api/models/:id`(`admin/src/components/ModelReviewPanel.tsx`):
 
 | 区域 | 内容 |
 |--|--|
 | 基本 | 缩略图、格式、状态、文件地址、转换说明 |
-| 指标 | 体积（`fileSize`）/ 格式 / 容器 / VRM 版本 / 面数 / 顶点 / 网格 / 材质 / 贴图 / 骨骼 / 节点 / 形变目标 / 动画 / 图元 / 蒙皮 / 骨骼最大层级 |
+| 指标 | 体积(`fileSize`)/ 格式 / 容器 / VRM 版本 / 面数 / 顶点 / 网格 / 材质 / 贴图 / 骨骼 / 节点 / 形变目标 / 动画 / 图元 / 蒙皮 / 骨骼最大层级 |
 | 可驱动性 | 结论横幅：16 根必需 humanoid 骨齐全 -> 可驱动；不全 -> 列出缺哪些（直接标红）；非 glTF 容器 -> 只能审核来源与体积 |
-| humanoid 覆盖 | 已映射 / 总数（22）+ 进度条 + 已命中规范名徽章明细 |
+| humanoid 覆盖 | 已映射 / 总数(22)+ 进度条 + 已命中规范名徽章明细 |
 | warnings | `ModelStats.warnings` 逐条列出 |
 | 骨骼详细界面 | 扁平骨骼树按 `depth` 缩进（14px/层），显示骨骼名、是否蒙皮徽章、humanoid 映射徽章、子节点数；支持按名搜索（保留祖先链）、「仅显示蒙皮骨骼」开关、限高滚动 + **只渲染前 400 行**（超出提示还有多少根），千根骨骼不卡 |
 | stats 为空 | 提示"暂无分析数据（旧数据或后端尚未完成分析）"，只能按格式/体积/来源判断 |
 
 ### 通过 / 驳回 / 设为默认
 
-- 面板底部勾选「同时设为全局默认模型」-> 点「通过」时请求体带 `setPrimary:true`：
+- 面板底部勾选「同时设为全局默认模型」-> 点「通过」时请求体带 `setPrimary:true`:
   `ReviewsService.transition()` 保存模型为 `published` 后调用
   `ModelsService.setPrimary(id)`（同一事务清其余 `is_primary`），并把身份写进源码
   `src/config/default-model.ts`。
-- 单独设置走 `POST /api/models/:id/primary`：**仅 `published` 允许，否则 409**。
+- 单独设置走 `POST /api/models/:id/primary`: **仅 `published` 允许，否则 409**。
 - 驳回必须填意见（400）。
 
 ### 骨骼树过滤（`admin/src/lib/bone-tree.ts`，纯函数、可单测）
@@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published
 
 ```bash
 cd web-server
-npx vitest run        # 10 个文件 / 168 项通过（含 admin-bone-filter 8 项）
+npx vitest run        # 11 个文件 / 180 项通过（含 admin-bone-filter 8 项、.env 预检 12 项）
 npm run test:smoke
 ```
 
@@ -101,4 +101,4 @@ npm run test:smoke
 | `setPrimary` 随审核通过生效 | ✅ `POST /api/reviews/model/22/approve` + `setPrimary:true` -> 200、`status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...` |
 | 单独设默认仅 published | ✅ `POST /api/models/:id/primary` 非 published -> 409 |
 | 驳回必须填意见 | ✅ 无 `comment` -> 400 |
-| 目录重建后默认模型 | ✅ `GET /api/catalog/export` 的 `defaultModelId` 由 VRM 变为 **22**（库中另有 2 个已发布 VRM） |
+| 目录重建后默认模型 | ✅ `GET /api/catalog/export` 的 `defaultModelId` 由 VRM 变为 **22**(库中另有 2 个已发布 VRM) |

tasks/008-admin-ui-songs.md

@@ -1,7 +1,7 @@
 # T-WEB-008 歌曲管理界面
 
-- **状态**：done
-- **依赖**：T-WEB-003
+- **状态**: done
+- **依赖**: T-WEB-003
 
 ## 目标
 
@@ -19,11 +19,11 @@ web-server/admin/package.json
 
 ## 交付物
 
-`web-server/admin/`（React 18 + Vite + TypeScript）：
+`web-server/admin/`(React 18 + Vite + TypeScript):
 
 | 路径 | 说明 |
 |--|--|
-| `src/pages/SongsPage.tsx` | 歌曲列表 + 分页 + 检索（`q` / `status` / `artist`） |
+| `src/pages/SongsPage.tsx` | 歌曲列表 + 分页 + 检索(`q` / `status` / `artist`) |
 | `src/components/SongForm*` | 新建/编辑表单，含来源五元组 |
 | `src/api/client.ts` | fetch 封装；非 2xx 抛 `ApiError`，兼容 Nest 的 `message: string[]` |
 | `src/api/types.ts` | 与契约对齐的 TypeScript 类型 |
@@ -48,6 +48,6 @@ npm run build     # tsc -b && vite build 必须成功
 
 ## 构建与运行
 
-- 开发：`npm run dev`（5173，`/api` 与 `/health` 代理到 `localhost:3000`）
-- 生产：`npm run build` 产物由**后端服务自身**托管（`ADMIN_DIR`，含 SPA 回退），反向代理只需整体转发到后端端口（见 `deploy/proxy/README.md`）
+- 开发：`npm run dev`(5173, `/api` 与 `/health` 代理到 `localhost:3000`)
+- 生产：`npm run build` 产物由**后端服务自身**托管（`ADMIN_DIR`，含 SPA 回退），反向代理只需整体转发到后端端口(见 `deploy/proxy/README.md`)
 - `VITE_API_BASE` 可覆盖 API 基地址；留空表示同源

tasks/009-admin-ui-models.md

@@ -1,7 +1,7 @@
 # T-WEB-009 模型管理界面 + 来源展示
 
-- **状态**：done
-- **依赖**：T-WEB-005
+- **状态**: done
+- **依赖**: T-WEB-005
 
 ## 目标
 
@@ -30,11 +30,11 @@ web-server/admin/src/components/VrmPreview.tsx
 - 表格列：预览缩略图、名称、格式（VRM 高亮徽章）、VRM 版本、是否默认、
   **来源五元组**、许可、状态、操作
 - **来源展示（本任务验收重点）**：整行展示 `sourceType` + `sourceName` + `author`
-  + `license`，`sourceUrl` 可点击外链跳转
-- 上传：`POST /api/models`（multipart `file` + 名称 + `isPrimary` + 来源五元组 +
+  + `license`, `sourceUrl` 可点击外链跳转
+- 上传：`POST /api/models`(multipart `file` + 名称 + `isPrimary` + 来源五元组 +
   状态），客户端校验与歌曲页一致
 - 「设为默认」-> `POST /api/models/:id/primary`，成功后刷新列表以反映互斥结果
-- 3D 预览：`GLTFLoader` + `VRMLoaderPlugin` 加载 `fileUrl`，
+- 3D 预览：`GLTFLoader` + `VRMLoaderPlugin` 加载 `fileUrl`,
   支持鼠标拖拽旋转与滚轮缩放，正确处理 VRM 0.x / 1.0 元数据差异、
   未选择模型、加载失败三种状态，卸载时释放资源
 
@@ -45,5 +45,5 @@ cd web-server/admin
 npm run build     # 必须成功
 ```
 
-另由 `npm run test:smoke`（[4] 段落）验证后端确实在列表接口返回完整来源字段，
+另由 `npm run test:smoke`([4] 段落)验证后端确实在列表接口返回完整来源字段，
 供本页面展示。

tasks/010-deploy.md

@@ -1,17 +1,17 @@
 # T-WEB-010 部署（Linux 业务服务，不使用 Docker，不部署反代）
 
-- **状态**：done（两次需求变更后重做）
-- **依赖**：T-WEB-001 ~ 009
+- **状态**: done（两次需求变更后重做）
+- **依赖**: T-WEB-001 ~ 009
 
 ## 目标
 
 Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程由系统服务
-（systemd / OpenRC / SysVinit / 后台进程）托管，**同时提供 REST API 与管理端页面**。
-**不使用 Docker**，**不部署 MySQL**（数据库为部署方提供的现有实例），
+(systemd / OpenRC / SysVinit / 后台进程)托管，**同时提供 REST API 与管理端页面**。
+**不使用 Docker**, **不部署 MySQL**（数据库为部署方提供的现有实例），
 **也不部署反向代理**（由另外的服务/团队负责）。
 
 > **需求变更记录**
-> 1. 初版按文档 4.4 实现为 Docker Compose；用户要求改为"运行在 Linux 的网站"，
+> 1. 初版按文档 4.4 实现为 Docker Compose；用户要求改为"运行在 Linux 的网站",
 >    于是替换为 nginx + systemd 原生站点部署，并删除 `deploy/docker-compose.yml`、
 >    `web-server/Dockerfile`、`web-server/admin/Dockerfile`。
 > 2. 随后用户明确："web 端仅需要业务需求，反代等工作交由另外的服务处理。
@@ -20,7 +20,7 @@ Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程
 >    托管（`ADMIN_DIR` + SPA 深链接回退），并新增 `deploy/proxy/` 只交付说明文档。
 > 3. 再随后用户要求**管理端口与软件 API 端口分离**：新增 `ADMIN_PORT`
 >    （默认 `PORT + 1`）与可选的 `ADMIN_HOST`（默认跟随 `HOST`）。软件 API 端口
->    只给客户端调接口（`/api`、`/health`、`/static`、`/contracts`，`/` 等返回 404），
+>    只给客户端调接口（`/api`、`/health`、`/static`、`/contracts`, `/` 等返回 404），
 >    管理端端口给浏览器（管理页面 + 全部接口）。`ADMIN_PORT === PORT` 保留为
 >    单端口兼容模式，只 warn 不中止。install.sh 的汇总与反代说明改为两个端口。
 > 4. 本次追加两项：
@@ -29,7 +29,7 @@ Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程
 >       `install.sh` 在缺 `deploy/.env` 时先调用它，失败才 die（安装目录已有上次
 >       安装留下的.env 则直接复用，保持原语义）。
 >    b) **默认监听 0.0.0.0 固化**：确认 `configuration.ts` 的
->       `bindHost = process.env.HOST?? '0.0.0.0'`、`adminHost` 默认跟随 HOST，
+>       `bindHost = process.env.HOST?? '0.0.0.0'`、`adminHost` 默认跟随 HOST,
 >       两个 `.env.example` 与 `init-env.sh` 的 HOST 默认值均为 `0.0.0.0`。
 
 ## load
@@ -52,10 +52,10 @@ deploy/proxy/README.md
 ```
 Windows/Godot 客户端、Android App ─▶ 软件 API 端口:3000（只提供接口，无管理页面）
                                         ├── /api/        REST API
-                                        ├── /health      健康检查（数据库不可用返回 503）
+                                        ├── /health      健康检查(数据库不可用返回 503)
                                         ├── /static/     上传文件
                                         └── /contracts/  契约快照
-                                        （/、/songs 等返回 404，有意设计）
+                                        (/、/songs 等返回 404，有意设计)
 
 浏览器 ─▶ 反向代理（外部提供，IIS / nginx / 网关...）──▶ 管理端端口:3001
               │  整端口转发，不需要托管静态文件      ├── /            管理端页面（含 SPA 深链接回退）
@@ -81,15 +81,15 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口:3000（只提供
 | `deploy/.env.example` | 部署环境变量样例（`PORT` / `ADMIN_PORT` / `ADMIN_HOST` / `HOST` 说明与上传上限告警） |
 | `deploy/systemd/opendance-api.service` | systemd 单元，含 `ProtectSystem=strict` 等安全加固 |
 | `deploy/openrc/opendance-api` | OpenRC 服务脚本 |
-| `deploy/initd/opendance-api` | SysVinit / LSB 启动脚本（转调 ctl.sh） |
+| `deploy/initd/opendance-api` | SysVinit / LSB 启动脚本(转调 ctl.sh) |
 | `deploy/ctl.sh` | 无 init 系统时的进程控制（后台进程 + PID 文件），start/stop/restart/status/logs |
 | `deploy/proxy/README.md` | **反代说明文档**：转发目标、绑定地址、自检清单、故障对照 |
-| `deploy/proxy/nginx.conf.example` | nginx 配置样例（上传上限、超时、keepalive、可选 HTTPS） |
+| `deploy/proxy/nginx.conf.example` | nginx 配置样例(上传上限、超时、keepalive、可选 HTTPS) |
 | `deploy/proxy/web.config.example` | IIS 配置样例（需 ARR + URL Rewrite 模块） |
 
-## deploy/.env 初始化引导（init-env.sh）
+## deploy/.env 初始化引导(init-env.sh)
 
-首次部署不再要求手工 `cp deploy/.env.example deploy/.env && vi deploy/.env`：
+首次部署不再要求手工 `cp deploy/.env.example deploy/.env && vi deploy/.env`:
 
 ```
 install.sh 检测到缺 deploy/.env
@@ -97,11 +97,11 @@ install.sh 检测到缺 deploy/.env
    └── 否则调用 deploy/init-env.sh
          ├── 缺.env -> 从.env.example 复制，chmod 600
          ├── 交互（TTY / 管道）-> 逐项询问并写回
-         └── 非交互（CI、</dev/null、-y）-> 只校验，绝不阻塞；失败则 install.sh die
+         └── 非交互(CI、</dev/null、-y)-> 只校验，绝不阻塞；失败则 install.sh die
 ```
 
 逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME / PORT / ADMIN_PORT / HOST`
-共 8 个键，回车保留默认；`DB_PASS` 用 `read -rs` 不回显、按约定写盘**不加引号**；
+共 8 个键，回车保留默认；`DB_PASS` 用 `read -rs` 不回显、按约定写盘**不加引号**;
 校验必填项与端口范围；可用 Node + mysql2 做连通性自检（口令只经环境变量传给子进程，
 失败仅告警）；只替换/追加这 8 个键、保留模板注释，写完 `chmod 600` 并回读校验；
 结尾打印摘要（口令 `***`）与本次变更列表。
@@ -116,21 +116,21 @@ install.sh 检测到缺 deploy/.env
 | `--skip-db-check` | 跳过数据库连通性自检 |
 | `--dir DIR` | 等价于 `--env-file DIR/.env --example DIR/.env.example` |
 | `--env-file PATH` / `--example PATH` | 指定 `.env` / 模板路径 |
-| `--timeout SECONDS` | 非 TTY 下每次读取超时秒数（默认 10） |
+| `--timeout SECONDS` | 非 TTY 下每次读取超时秒数(默认 10) |
 | `-h` / `--help` | 显示帮助 |
 
 环境变量：`OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` /
 `OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` /
 `OPENDANCE_PROMPT_TIMEOUT`。
 
-**非交互绝不挂住**：stdin 非 TTY 且是 `</dev/null` 或已关闭，或带 `-y` 等开关 ->
+**非交互绝不挂住**: stdin 非 TTY 且是 `</dev/null` 或已关闭，或带 `-y` 等开关 ->
 只校验不提问；所有 read 带超时，EOF/超时立即 `exit 1`。
 
-**默认监听 0.0.0.0**：`configuration.ts` 的
-`bindHost = process.env.HOST?? '0.0.0.0'`，`adminHost` 默认跟随 `HOST`
-（HOST 未设置时同样回落 `0.0.0.0`）；`deploy/.env.example` 与
-`web-server/.env.example` 均写 `HOST=0.0.0.0`；`install.sh` 的
-`BIND_HOST="${HOST:-0.0.0.0}"`；`init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
+**默认监听 0.0.0.0**: `configuration.ts` 的
+`bindHost = process.env.HOST?? '0.0.0.0'`, `adminHost` 默认跟随 `HOST`
+(HOST 未设置时同样回落 `0.0.0.0`); `deploy/.env.example` 与
+`web-server/.env.example` 均写 `HOST=0.0.0.0`; `install.sh` 的
+`BIND_HOST="${HOST:-0.0.0.0}"`; `init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
 注意 `install.sh` 里的 `HEALTH_HOST` / `API_HOST` 用的是**回环地址**做本机健康检查，
 与对外监听的默认值无关。
 
@@ -142,7 +142,7 @@ install.sh 检测到缺 deploy/.env
 1. systemd    /run/systemd/system 存在且 systemctl 可用
 2. OpenRC     rc-service + rc-update 可用
 3. SysVinit   /etc/init.d 存在且 update-rc.d 或 chkconfig 可用
-4. 都没有     nohup 后台进程 + PID 文件（deploy/ctl.sh）
+4. 都没有     nohup 后台进程 + PID 文件(deploy/ctl.sh)
               并写 crontab @reboot 实现开机自启
 ```
 
@@ -156,45 +156,45 @@ install.sh 检测到缺 deploy/.env
 
 ## 关键实现
 
-- **双端口**：一个 Node 进程创建两个 HTTP server--软件 API 端口（`PORT`，默认 3000）
+- **双端口**：一个 Node 进程创建两个 HTTP server--软件 API 端口(`PORT`，默认 3000)
   与管理端端口（`ADMIN_PORT`，默认 3001），复用同一个 express 实例；用
   `req.socket.localPort` 判断请求来自哪个端口，决定是否提供管理页面。
-  `ADMIN_PORT === PORT` 时只建一个 server（单端口兼容模式，避免 EADDRINUSE）
-- **服务自身托管管理端**：`app.useStaticAssets(adminDir,...)` + SPA 回退中间件
+  `ADMIN_PORT === PORT` 时只建一个 server(单端口兼容模式，避免 EADDRINUSE)
+- **服务自身托管管理端**: `app.useStaticAssets(adminDir,...)` + SPA 回退中间件
   （仅管理端口生效）；回退会跳过 `/api/`、`/health`、`/static/`、`/contracts/`
   以及带扩展名的路径，保证未知 API 仍返回 404 而不是 HTML
-- **软件 API 端口不提供管理页面**：`/`、`/songs` 等在该端口一律 404（有意设计）
+- **软件 API 端口不提供管理页面**: `/`、`/songs` 等在该端口一律 404（有意设计）
 - **`HOST` / `ADMIN_HOST` 绑定地址**：同机反代建议 `127.0.0.1`，异机反代用
   `0.0.0.0` + 防火墙；`ADMIN_HOST` 可选（默认跟随 `HOST`），可单独把管理端限制在
   本机或内网；`HOST` 默认取 `0.0.0.0` 以保证开箱可用
-- **首次部署的.env 由引导生成**：`install.sh` 缺 `deploy/.env` 时先调用
+- **首次部署的.env 由引导生成**: `install.sh` 缺 `deploy/.env` 时先调用
   `deploy/init-env.sh`（安装目录已有上次安装的 `.env` 则直接复用）；引导脚本在
   非交互环境下只校验、绝不阻塞，校验失败时 install.sh 才 die
-- **端口校验**：`PORT` / `ADMIN_PORT` 必须是 1..65535 的整数；非法值在生产环境
+- **端口校验**: `PORT` / `ADMIN_PORT` 必须是 1..65535 的整数；非法值在生产环境
   启动时快速失败（`validateEnv` 的 errors），`ADMIN_PORT === PORT` 只 warn
 - **install.sh 汇总与反代说明**：结尾分别打印两个端口的访问地址、监听配置与
   防火墙放行命令（`firewall-cmd` / `ufw` 同时放行两个端口）
-- **systemd 加固**：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、
+- **systemd 加固**: `NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、
   `ReadWritePaths=/var/lib/opendance`，进程只能写自己的存储目录
-- **上传上限两侧一致**：后端 `UPLOAD_MAX_BYTES=536870912`（512 MiB），
+- **上传上限两侧一致**：后端 `UPLOAD_MAX_BYTES=536870912`(512 MiB),
   反代侧 `client_max_body_size` / `maxAllowedContentLength` 必须不小于此值
-- **模型转换配置**（`deploy/.env.example` 已写入）：
+- **模型转换配置**(`deploy/.env.example` 已写入):
   - `ASSIMP_BIN=assimp`：上传 `.zip` 模型包或 `.pmx`/`.fbx` 单文件时**必须**能调用到，
     否则转换失败 **422**
   - `MODEL_CONVERT_FORMAT=glb`（默认）|`vrm`：只影响需要转换的 PMX/FBX 的交付格式。
     `glb` 通用，两个客户端都原生加载；`vrm` 在 GLB 之上补 `VRMC_vrm` 扩展
-    （humanoid 骨骼 / 表情语义），**humanoid 骨骼名映射不全时自动回退交付 GLB**
+    (humanoid 骨骼 / 表情语义), **humanoid 骨骼名映射不全时自动回退交付 GLB**
     并写进 `models.conversion_note`。产物一律 `assimp info` 回读校验
   - `MODEL_CONVERT_PMX` / `MODEL_CONVERT_TIMEOUT_MS` 语义见 README 四
-- **迁移用编译产物**：`web-server/scripts/migrate.mjs` 检测到 `dist/` 时走
-  `typeorm -d dist/db/data-source.js`，无需在服务器上装 devDependencies；
+- **迁移用编译产物**: `web-server/scripts/migrate.mjs` 检测到 `dist/` 时走
+  `typeorm -d dist/db/data-source.js`，无需在服务器上装 devDependencies;
   本版本迁移共 3 个：`InitSchema1789382903060`、
   `AddModelConversionFields1789450000000`、**`AddModelStats1789460000000`**
   （新增 `models.stats TEXT`，存模型分析结果，已在真实库执行）
 - **依赖安装显式带 dev**：安装脚本先 `set -a;. deploy/.env` 导出了
-  `NODE_ENV=production`，会让 npm 跳过 devDependencies 导致 `tsc: not found`；
+  `NODE_ENV=production`，会让 npm 跳过 devDependencies 导致 `tsc: not found`;
   故用 `env -u NODE_ENV npm ci --include=dev`
-- **复制文件时锚定排除**：`storage/` 这类模式会误伤 `src/storage/` 与 `dist/storage/`
+- **复制文件时锚定排除**: `storage/` 这类模式会误伤 `src/storage/` 与 `dist/storage/`
   （曾导致 `MODULE_NOT_FOUND...storage.module`），排除规则一律用 `/storage/` 锚定
 - **`/contracts/` 静态暴露**：另两端可直接从站点取契约快照
 
@@ -202,7 +202,7 @@ install.sh 检测到缺 deploy/.env
 
 ```bash
 bash deploy/init-env.sh              # 或手工 cp deploy/.env.example deploy/.env 后填写 DB_*
-bash deploy/install.sh               # 需 root（不需要 sudo）
+bash deploy/install.sh               # 需 root(不需要 sudo)
 curl -fsS http://localhost:3000/health
 curl -fsS http://localhost:3001/health
 curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/   # 期望 404（软件 API 端口无管理页面）
@@ -212,12 +212,12 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 | 验收项 | 状态 |
 |--|--|
 | `deploy/install.sh` 脚本语法与幂等性 | ✅ `bash -n` 通过；重复执行会覆盖程序文件、保留 `.env` |
-| 连接现有 MySQL 成功 | ✅ 已用真实实例验证（`/health` 200，`database.connected=true`） |
-| TypeORM migration 执行成功 | ✅ 5 张业务表已创建并验证；v0.2.0 的 `AddModelStats1789460000000`（`models.stats TEXT`）已在真实库执行 |
+| 连接现有 MySQL 成功 | ✅ 已用真实实例验证(`/health` 200, `database.connected=true`) |
+| TypeORM migration 执行成功 | ✅ 5 张业务表已创建并验证；v0.2.0 的 `AddModelStats1789460000000`(`models.stats TEXT`)已在真实库执行 |
 | 模型转换配置 | ✅ `deploy/.env.example` 写入 `ASSIMP_BIN` / `MODEL_CONVERT_FORMAT=glb|vrm` / `MODEL_CONVERT_PMX` / `MODEL_CONVERT_TIMEOUT_MS`；不合规输入转换失败 422 |
 | `curl http://<host>:3000/health` 通过 | ✅ 直连后端端口已验证 |
 | 软件 API 端口 `/` 返回 404 | ✅ `PORT=3000` 上 `/`、`/songs` 均 404（有意设计，无管理页面） |
-| 管理端端口 `/` 返回 200 | ✅ `ADMIN_PORT=3001` 上 `/`、`/songs`、`/models` 均返回同一份 HTML（200） |
+| 管理端端口 `/` 返回 200 | ✅ `ADMIN_PORT=3001` 上 `/`、`/songs`、`/models` 均返回同一份 HTML(200) |
 | 前端深链接回退 | ✅ 未知静态路径回退到 `index.html`，未知 API 仍 404 |
 | `ADMIN_PORT === PORT` 单端口兼容模式 | ✅ 只建一个 server，管理页面回到 API 端口，日志提示「未分端口」 |
 | 端口非法在生产环境中止启动 | ✅ `validateEnv` 对非 1..65535 整数端口报 error |
@@ -225,11 +225,11 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 | 不使用 Docker | ✅ 仓库内已无 Dockerfile / docker-compose / Docker 引用 |
 | 不部署反向代理 | ✅ 仅交付 `deploy/proxy/` 文档，install.sh 中无任何反代安装动作 |
 | 缺 `deploy/.env` 时由 `init-env.sh` 引导 | ✅ 交互逐项询问 8 个键；只改这 8 个键、保留模板注释、`chmod 600`、回读校验；安装目录已有 `.env` 时直接复用 |
-| `init-env.sh --check` / 非交互不阻塞 | ✅ `test/init-env.spec.ts`（16 项）覆盖 `--check`、`-y`、EOF/超时立即退出、口令不加引号写盘 |
+| `init-env.sh --check` / 非交互不阻塞 | ✅ `test/init-env.spec.ts`(16 项)覆盖 `--check`、`-y`、EOF/超时立即退出、口令不加引号写盘 |
 | `HOST` 默认 `0.0.0.0` | ✅ `configuration.ts`、`deploy/.env.example`、`web-server/.env.example`、`install.sh`、`init-env.sh` 五处一致 |
 
 > **环境限制说明**：本次执行环境**无 root 权限**，且**未安装 nginx**（按需求也不应安装）。
-> 因此 `deploy/install.sh` 的服务注册链路（systemd / OpenRC / SysVinit / crontab）
+> 因此 `deploy/install.sh` 的服务注册链路(systemd / OpenRC / SysVinit / crontab)
 > 未能在本机实机跑通。已完成的等价验证：
 > - 后端以 `node dist/main.js` 直连真实数据库启动，两个端口 `/health` 均 200
 > - 管理端托管与 SPA 回退逐路径实测（`/`、`/songs`、`/models`、`/api/*`、未知路径），
@@ -238,7 +238,7 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 > - `npm run migration:run` 走编译产物成功
 > - 端到端冒烟 57 项全通过
 > - `install.sh` / `uninstall.sh` / `ctl.sh` 通过 `bash -n` 语法校验
-> - `init-env.sh` 通过 `bash -n`，并由 `test/init-env.spec.ts`（16 项）覆盖
+> - `init-env.sh` 通过 `bash -n`，并由 `test/init-env.spec.ts`(16 项)覆盖
 >   交互写回 / `--check` / 非交互 / 超时 / 幂等 / 口令不加引号
 > - 反代文档中的占位符与后端实际行为逐条对照（两个端口、路径、上传上限、健康检查）
 >
@@ -253,13 +253,13 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 
 内容：`web-server/`（源码 + dist）、`admin/`（构建产物）、`deploy/`
 （含 `proxy/` 反代文档）、`contracts/` 快照、`THIRD_PARTY.md`、`README.txt`。
-打包脚本会对产物做硬校验：`src/**/*.ts` 必须都有对应 `dist/*.js`，
+打包脚本会对产物做硬校验：`src/**/*.ts` 必须都有对应 `dist/*.js`,
 关键文件（`dist/main.js`、`dist/storage/storage.module.js`、`admin/index.html`、
 `deploy/proxy/*`）必须齐全，且不得含真实 `.env` 与 Docker/nginx 安装配置。
 v0.2.0 起校验清单追加模型新模块：`dist/models/model-inspector.js`、
 `dist/models/model-thumbnail.js`、`dist/models/vrm-writer.js`、
 `dist/models/gltf-packer.js`、`dist/migrations/1789460000000-AddModelStats.js`。
 
-> **发布包名变更**：`opendance-web-v0.1.0.tar.gz` -> **`opendance-web-v0.2.0.tar.gz`**
-> （`scripts/package-release.sh` 的 `VERSION` 默认值已改为 `0.2.0`，
+> **发布包名变更**: `opendance-web-v0.1.0.tar.gz` -> **`opendance-web-v0.2.0.tar.gz`**
+> (`scripts/package-release.sh` 的 `VERSION` 默认值已改为 `0.2.0`,
 > 与 `project.yaml` 的 `version: 0.2.0`、`web-server/package.json` 一致）。

web-server/admin/README.md

@@ -1,7 +1,7 @@
-# OpenDance Studio 管理端（opendance-admin）
+# OpenDance Studio 管理端(opendance-admin)
 
 基于 **React 18 + TypeScript + Vite** 的管理后台，对接 `web-server` 的 NestJS API。
-接口契约以 [`../contracts/rest-api.yaml`](../contracts/rest-api.yaml)（rest-api 0.1.0）为准，
+接口契约以 [`../contracts/rest-api.yaml`](../contracts/rest-api.yaml)(rest-api 0.1.0)为准，
 字段语义见 [`../contracts/data-models.md`](../contracts/data-models.md)。
 
 界面语言为简体中文；无任何 UI 组件框架，全部样式集中在 `src/styles.css`。
@@ -11,16 +11,16 @@
 ```bash
 npm install      # 或 pnpm install
 npm run dev      # 开发服务器 http://localhost:5173
-npm run build    # 生产构建（tsc -b && vite build）-> dist/
+npm run build    # 生产构建(tsc -b && vite build)-> dist/
 npm run preview  # 本地预览 dist/
-npm run typecheck # 只做类型检查（tsc --noEmit）
+npm run typecheck # 只做类型检查(tsc --noEmit)
 ```
 
 > 管理端请求的是**同源**的 `/api/**` 与 `/health`，不含任何硬编码域名。
 
-## 开发代理（dev proxy）
+## 开发代理(dev proxy)
 
-`vite.config.ts` 已把 `/api` 与 `/health` 代理到 `http://localhost:3000`：
+`vite.config.ts` 已把 `/api` 与 `/health` 代理到 `http://localhost:3000`:
 
 ```ts
 server: {
@@ -73,24 +73,24 @@ bash deploy/install.sh
 ```
 
 - 后端通过 `ADMIN_DIR` 定位管理端产物，默认 `../admin`
-- 反代配置样例：`deploy/proxy/nginx.conf.example`（nginx）、
-  `deploy/proxy/web.config.example`（IIS）
+- 反代配置样例：`deploy/proxy/nginx.conf.example`(nginx)、
+  `deploy/proxy/web.config.example`(IIS)
 - 完整说明：`deploy/proxy/README.md`
 
 ## 目录结构
 
 ```
 src/
-  main.tsx                 入口（BrowserRouter）
+  main.tsx                 入口(BrowserRouter)
   App.tsx                  路由表
   styles.css               全部样式
   api/
-    client.ts              fetch 封装（ApiError / 分页 / multipart）
+    client.ts              fetch 封装(ApiError / 分页 / multipart)
     types.ts               契约类型（与 rest-api.yaml 一一对应）
     endpoints.ts           契约端点封装
   components/
     Layout.tsx             左侧导航骨架
-    ui.tsx                 通用组件（表格/弹窗/分页/来源五元组展示与表单...）
+    ui.tsx                 通用组件(表格/弹窗/分页/来源五元组展示与表单...)
     VrmPreview.tsx         three + @pixiv/three-vrm 的 3D 预览（懒加载分包）
   lib/
     labels.ts              枚举中文文案
@@ -119,12 +119,12 @@ src/
 
 ## 3D 预览说明
 
-`src/components/VrmPreview.tsx`：`GLTFLoader` + `VRMLoaderPlugin`（来自 `@pixiv/three-vrm`），
+`src/components/VrmPreview.tsx`: `GLTFLoader` + `VRMLoaderPlugin`（来自 `@pixiv/three-vrm`），
 
-- 依据 `vrm.meta.metaVersion` 区分 VRM 0.x / 1.0，0.x 自动执行 `VRMUtils.rotateVRM0`；
+- 依据 `vrm.meta.metaVersion` 区分 VRM 0.x / 1.0, 0.x 自动执行 `VRMUtils.rotateVRM0`;
 - 自实现鼠标拖拽旋转与滚轮缩放（未引入 OrbitControls）；
 - `requestAnimationFrame` 循环内调用 `vrm.update(delta)`，并按包围盒自动取景；
-- 卸载时取消 RAF、断开 ResizeObserver、释放 renderer / geometry / material / texture；
+- 卸载时取消 RAF、断开 ResizeObserver、释放 renderer / geometry / material / texture;
 - 无 WebGL 上下文时降级为错误提示，不会让页面崩溃。
 
 `three` + `@pixiv/three-vrm`（约 750 kB）通过 `React.lazy` 单独分包，仅进入模型页时加载。

web-server/admin/package.json

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

web-server/package.json

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

web-server/test/env-file.spec.ts

@@ -0,0 +1,189 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+/**
+ * deploy/.env 的「可被 shell 安全载入」保证。
+ *
+ * 背景（真实故障）：install.sh 用 `set -a; . deploy/.env` 载入配置，而模板里
+ *   MODEL_CONVERT_PMX=Hatsune Miku.pmx
+ * 的值含空格却没加引号，这一行被切成「赋值 + 命令」，安装直接失败：
+ *   ./deploy/.env: line 53: Miku.pmx: command not found
+ *   [install] 第 53 行执行失败(退出码 127)
+ *
+ * 因此这里锁两条线：
+ *   1. deploy/.env.example 必须能被 `set -a; .` 原样载入（回归用例）；
+ *   2. deploy/env-lib.sh 的预检能在载入前拦住不安全写法，并给出行号与改法。
+ */
+
+function findDeployFile(name: string): string {
+  const candidates = [
+    resolve(process.cwd(), '..', 'deploy', name), // 从 web-server/ 运行（vitest 默认）
+    resolve(process.cwd(), 'deploy', name), // 从仓库根运行
+    resolve(process.cwd(), '..', '..', 'deploy', name),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`找不到 deploy/${name}，候选路径：\n${candidates.join('\n')}`);
+}
+
+const EXAMPLE = findDeployFile('.env.example');
+const ENV_LIB = findDeployFile('env-lib.sh');
+const INSTALL_SH = findDeployFile('install.sh');
+const CTL_SH = findDeployFile('ctl.sh');
+
+const dirs: string[] = [];
+function makeDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'opendance-env-'));
+  dirs.push(dir);
+  return dir;
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true });
+});
+
+/** 用真实 shell 载入一个 .env（与 install.sh 的做法一致） */
+function sourceEnv(file: string) {
+  return spawnSync(
+    'bash',
+    [
+      '-c',
+      'set -a; . "$1"; set +a; printf "%s\\n" "${MODEL_CONVERT_PMX:-}" "${DB_HOST:-}" "${DB_PASS:-}" "${UPLOAD_MAX_BYTES:-}"',
+      '_',
+      file,
+    ],
+    { encoding: 'utf8', timeout: 15000 },
+  );
+}
+
+/** 调用 deploy/env-lib.sh 的预检函数 */
+function validate(file: string) {
+  return spawnSync('bash', ['-c', '. "$1"; opendance_validate_env_file "$2"', '_', ENV_LIB, file], {
+    encoding: 'utf8',
+    timeout: 15000,
+  });
+}
+
+function writeEnv(content: string): string {
+  const file = join(makeDir(), '.env');
+  writeFileSync(file, content);
+  return file;
+}
+
+describe('deploy/.env.example：必须能被 shell 原样载入', () => {
+  it('`set -a; . .env.example` 成功, 且带空格的值读回完整 (回归: 修复前此处退出码 127)', () => {
+    const result = sourceEnv(EXAMPLE);
+
+    expect(result.stderr).not.toContain('command not found');
+    expect(result.status).toBe(0);
+    const [pmx, host, pass, uploadMax] = result.stdout.trimEnd().split('\n');
+    expect(pmx).toBe('Hatsune Miku.pmx');
+    expect(host).toBe('<existing-mysql-host>');
+    expect(pass).toBe('<数据库口令>');
+    expect(uploadMax).toBe('536870912');
+  });
+
+  it('模板整体通过语法预检', () => {
+    const result = validate(EXAMPLE);
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  it('模板里每个赋值行都通过预检（逐行定位，便于以后加字段时发现问题）', () => {
+    const lines = readFileSync(EXAMPLE, 'utf8').split('\n');
+    const assigns = lines.filter((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l));
+    expect(assigns.length).toBeGreaterThan(10); // 模板字段数量下限，防止误删
+    for (const line of assigns) {
+      expect(validate(writeEnv(`${line}\n`)).status, `模板行应通过预检：${line}`).toBe(0);
+    }
+  });
+});
+
+describe('deploy/env-lib.sh：载入前的语法预检', () => {
+  it('拦住「值含空格却未加引号」，并给出行号、原文与改法（本次故障的原始写法）', () => {
+    const result = validate(writeEnv('NODE_ENV=production\nMODEL_CONVERT_PMX=Hatsune Miku.pmx\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain('MODEL_CONVERT_PMX=Hatsune Miku.pmx');
+    expect(result.stderr).toContain('MODEL_CONVERT_PMX="Hatsune Miku.pmx"');
+  });
+
+  it('拦住 shell 元字符，且对 $( ) 建议单引号（双引号仍会执行）', () => {
+    const result = validate(writeEnv('A=x&y\nB=$(id)\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 1 行');
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain("B='$(id)'");
+  });
+
+  it('拦住未闭合引号', () => {
+    const result = validate(writeEnv('A="unclosed\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('双引号未闭合');
+  });
+
+  it('不误伤合法写法：* % 口令、IPv4、路径、空值、单引号、引号 + 行尾注释', () => {
+    const result = validate(
+      writeEnv(
+        [
+          'DB_PASS=S3cr3t*Pwd%1',
+          'DB_HOST=127.0.0.1',
+          'DB_PORT=3306',
+          'STORAGE_DIR=/var/lib/opendance/storage',
+          'EMPTY=',
+          "WITH_SPACE='a b c'",
+          'QUOTED_COMMENT="x y"  # 行尾注释',
+          'MODEL_CONVERT_PMX="Hatsune Miku.pmx"',
+          '# 注释与空行也必须放过',
+          '',
+        ].join('\n'),
+      ),
+    );
+    expect(result.stderr).toBe('');
+    expect(result.status).toBe(0);
+  });
+
+  it('拦住非「键=值」的行号并指出原因', () => {
+    const result = validate(writeEnv('A=1\n这一行不是赋值\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain('不是「键=值」形式');
+  });
+
+  it('文件不存在时返回 1（而不是静默通过）', () => {
+    const result = validate(join(makeDir(), 'missing.env'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('找不到配置文件');
+  });
+});
+
+describe('载入顺序：install.sh / ctl.sh 必须先预检再 source', () => {
+  it('install.sh 在 `. ./deploy/.env` 之前调用预检', () => {
+    const text = readFileSync(INSTALL_SH, 'utf8');
+    const check = text.indexOf('opendance_validate_env_file "./deploy/.env"');
+    const source = text.indexOf('. ./deploy/.env');
+    expect(check).toBeGreaterThan(-1);
+    expect(source).toBeGreaterThan(-1);
+    expect(check).toBeLessThan(source);
+    // .env 被 source 时 LINENO 指向 .env 的行号，报错必须带上文件名才定位得到
+    expect(text).toContain('${BASH_SOURCE[0]}');
+  });
+
+  it('install.sh 在迁移前再次预检安装目录里的 .env', () => {
+    const text = readFileSync(INSTALL_SH, 'utf8');
+    expect(text).toContain('opendance_validate_env_file "$APP_DIR/deploy/.env"');
+  });
+
+  it('ctl.sh 载入 .env 前调用预检，且引用同目录的 env-lib.sh', () => {
+    const text = readFileSync(CTL_SH, 'utf8');
+    expect(text).toContain('"$SCRIPT_DIR/env-lib.sh"');
+    const check = text.indexOf('opendance_validate_env_file "$APP_DIR/deploy/.env"');
+    const source = text.indexOf('. "$APP_DIR/deploy/.env"');
+    expect(check).toBeGreaterThan(-1);
+    expect(source).toBeGreaterThan(-1);
+    expect(check).toBeLessThan(source);
+  });
+});