角色骨骼工坊 · 实现方案（rig-forge）

与《素材生成工具-实现方案.md》（asset-forge，:8788）并列的第四个服务（:8789）。 asset-forge 负责造模型，rig-forge 负责让模型能动。

〇、形态决策（三条，均已定）

决策	选择	为什么
绑骨方式	程序化白盒	不接 Hyper3D / 混元等外部绑骨 API。几何分析都在本地 Python 里跑，可复现、可调试、零成本、离线可用。
部署形态	独立工具 + 独立端口 :8789	与作品解耦，改绑骨不会碰作品服务；但直接读作品资源（`game/assets/models/*.glb`），不复制一份。
骨架规格	自有标准人形骨架（22 骨）	不套 Mixamo。命名用 `_L`/`_R` 后缀，日志与调试一眼可读；也不背上 `mixamorig:` 那套冗长前缀。

一、定位与边界

工具做四件事（对应用户需求 1a–1d）：

AI 预绑定：分析几何 → 生成骨架 → 距离场蒙皮 → 注入 glTF skin。
手动微调：3D 视图点选关节（彩色小球）后拖拽 gizmo，可勾选"联动子骨"整链平移。
AI 生成动作：中文描述词解析，或直接点选 13 种动作。
动作库：站立 / 行走 / 奔跑 / 打坐 / 攻击 / 受伤 / 被攻击 / 摔倒 / 高兴 / 生气 / 蓄力 / 挥手 / 倒地不起。

明确不做：

不做建模（那是 asset-forge 的事）。
不自动覆盖 game/ 下的在役资产 —— 产出落 rig-forge/data/，回灌作品是显式动作。
不训练任何网络模型。整套是确定性几何算法。

二、绑骨四步原理

GLB 输入
  │
  ├─ 1 bake_world_transforms()   把节点变换烘焙进 POSITION/NORMAL，清空变换
  ├─ 2 几何分析 analysis.py      → 身高 / 朝向 / 裆肩颈高度 / 手臂姿态 / 分区
  ├─ 3 骨架生成 skeleton.py      → 22 骨关节坐标（按比例落在解剖位置）
  ├─ 4 skinning.py               → 距离场权重 w = 1/(d+ε)^p，取 top-k 归一
  └─ 5 inject_skin()             写 bone 节点 + skin + JOINTS_0/WEIGHTS_0 + IBM

2.1 为什么要先烘焙世界变换

GLB 里节点可能带旋转/缩放。蒙皮要求顶点在绑定姿态的世界空间下与骨骼对齐，否则 IBM 算出来会在别的坐标系里，表现为"模型一动就炸开"。烘焙后整条节点链的变换清空 ⇒ 顶点与骨骼同处世界空间，后续全是干净的刚体运算。

2.2 蒙皮权重（核心算法）

每根骨是一条线段（自身关节 → 尾端锚点），不是点 —— 距离要算点到线段才有意义。
w = 1 / (d + ε)^p，p 由面数分流：低模 POWER_LOWPOLY=3.0，高模 POWER_HIGHPOLY=4.0。

低模褶皱少，幂次大反而僵硬。

取 top-k=4 后归一化（glTF 正好 4 个权重分量，天然对齐）。
左右侧约束：_L 骨不给右半身顶点，反之亦然（避免左手抢右手）。
细肢体折扣 THIN_LIMB_SCALE = 0.55：手臂骨（upper_arm / forearm / hand）权重打折。

这一步是必须的 —— A-Pose 时前臂下垂，离大腿根很近，不折的话前臂会抢走一大片胯部顶点。

2.3 IBM 的约定陷阱

glTF 里 inverseBindMatrices 存的是列主序；node.matrix 读进来也需转置。
本工程内部统一行主序（glbio.py 顶部明写）。跨这两套约定时要么全都转、要么全都不转，

混着来会得到一个看起来很吓人、其实完全正常的诊断结果（详见 §六）。

三、动作生成

动作是参数化原语：每套动作给若干关键帧 (t, {骨: 旋转})，再按 FPS 采样成完整轨道。
loop=True 的动作会在末尾补一帧首帧姿态，保证首尾无缝。
产出是轻量骨架动画 GLB：只含骨骼节点与动画通道，不带网格。作品侧把动画绑到

同一套骨架的模型上即可 —— 单文件 6–38KB，比把网格复制 13 份省得多。

amplitude / speed 可调，前端给了滑杆。
描述词解析 resolve_description() 带长词优先规则，返回 (action, confidence)；

置信度低时前端会提示"可能不是你要的"，而不是静默给个错动作。

四、独立工具 + 资源同步

人物清单从 game/assets/models/manifest.json 导入，只认 chr_ 前缀。
指纹三元组 = size + mtime_ns + sha1_16。三者任一变化 ⇒ 判"内容变了" ⇒ 标 stale。
台账 data/rig_manifest.json 记录每个角色的源指纹与绑定指纹。
自愈：台账为空时 list_characters() 自动 sync() 一次；

sync() 末尾会补登记 —— 扫描 data/bound/*_rigged.glb，认领台账里没有的既有产物（否则手工/探针产出的绑定会在台账重建后"消失"）。

sync(force=True) 只重读文件，不再无脑把所有角色标 stale（那会把全站吓红）。

五、部署

作品         :8000
资源生成器   :8788   → /forge/
角色骨骼工坊 :8789   → /rig/
单入口反代   :8080   （本地 Python；生产用 nginx-menpai.conf）

前端 Vite 用相对 base（'./'），因此直连 :8789 与反代 /rig/ 两种形态都能用，

不需要为子路径单独设 VITE_APP_BASE（asset-forge 则需要）。

服务统一由 tools/services.py 托管，支持 -p/--port 只重启某一个：

  python tools/services.py restart -p 8789     # 只动骨骼工坊，不惊动作品

5.1 子路径的两个必踩坑（已在 `serve_single_entry.py` 与 nginx 模板里堵住）

无尾斜杠 → 白屏。前端用相对 base，页面停在 /rig 时浏览器把 ./assets/...

解析到站点根 ⇒ 静态资源整片 404。必须 301 到 /rig/。（本地代理由 _dispatch 通用处理；nginx 用 location = /rig { return 301 /rig/; }。）

.glb 请求被静态正则抢走。nginx 里 location ~* \.glb$ 的 正则优先级高于普通前缀匹配，

会把 /rig/api/file/anim/*.glb 转发到作品后端 ⇒ 404，症状只是"动画预览不出来"。 ⇒ 子路径 location 必须写 ^~（前缀里优先级最高，可压过正则）。

六、踩坑清单

#	现象	真因	处置
1	整个界面点不动，但无任何报错	`.modal { display:flex }` 作者样式压过 UA 的 `[hidden]{display:none}`，hidden 的浮层铺满全屏吃掉所有点击	补 `.modal[hidden] { display:none }`
2	体检永久飘红（误差 2.06~2.85），但模型与动作肉眼正常	诊断函数把列主序 IBM 当行主序用，`(M @ bg).T` ≠ `bg.T @ IBM`	改成 `ibm.reshape(4,4).T @ bg`；实测 5e-8
3	页面一加载就一堆 404	无 favicon，浏览器自动探查 `/favicon.ico`	内联 data-URI SVG 图标
4	语义报表"全绿"却是错的	白名单里含了 forearm，把"前臂抢走胯部顶点"一起掩盖成 ✔	收紧白名单 + 新增中轴分区探测器
5	12 个角色被误判 T-Pose	用横向倍数判手臂张开，宽袍把倍数顶高	改用高度信号：极值层是否贴肩
6	服务刚重启连不上	uvicorn 日志已打印 running，但端口还没 bind	重启后等 ~4s 再请求；判据只信端口 + HTTP

七、验证方法（三层，缺一不可）

结构校验：_probe_anim.py —— 动画数/通道数/帧数/骨数/体积。

只能证明"数据在"，证明不了"对不对"。

语义 + 视觉双判据：

_probe_all.py：12 角色批量体检（身高/朝向/姿态/分区偏低）。
_viz_char.py + _tools/rigviz.py：把骨架按 2D 叠加渲染到模型上

（复用 tools/render_glb.py 的等距投影 + Z-Buffer，骨骼不做深度测试，穿模也可见）。

⚠️ 只跑语义会掉进自证陷阱 —— 阈值一松就"全绿"。必须用骨架叠加图独立复核。

端到端（无头浏览器）：

_tools/anim_e2e.cjs：选角色 → 点动作 → 播放 → 连拍 4 帧 → 比帧间像素差。
_tools/rig_edit_e2e.cjs：选角色 → 点选关节 → 平移 → 保存并重新蒙皮 → 还原。
判据是帧间必须有差异 + 页面无 pageerror；两者都过才算动作真的在动。

为什么必须连拍：结构校验只能证明"有动画数据"，证明不了"模型真的在动、动得像不像"。而 TransformControls 的 gizmo 手柄在屏幕上的位置依赖视角，脚本里硬编码坐标必然脆断 —— 所以微调验证走 window.__rig 钩子（与作品侧 window.__game 同惯例），验的是链路（选中 → 改动 → 落库 → 重蒙皮），不是像素级手感。

附：目录结构

rig-forge/
├── backend/
│   ├── app/
│   │   ├── config.py           目录/端口/幂次常量
│   │   ├── main.py             FastAPI 路由 + 诊断
│   │   └── services/
│   │       ├── glbio.py        GLB 读写、accessor、矩阵（行主序）
│   │       ├── analysis.py     几何分析
│   │       ├── skeleton.py     22 骨规格与线段
│   │       ├── skinning.py     距离场权重
│   │       ├── autobind.py     主流程 + 注入 skin
│   │       ├── assets.py       资源同步 + 台账
│   │       ├── anim.py         动作生成
│   │       └── anim_lib.py     13 种动作原语 + 描述词解析
│   └── _probe_*.py             体检探针（可删）
├── frontend/                   Vite + three.js（相对 base）
├── _tools/
│   ├── rigviz.py               骨架叠加渲染
│   ├── anim_e2e.cjs            动作端到端
│   └── rig_edit_e2e.cjs        微调端到端
└── data/
    ├── bound/                  绑定产物 *_rigged.glb
    ├── anim/                   动作 GLB
    └── rig_manifest.json       台账