| name | teaching-doc |
| description | 本项目写文档（飞书 + docs/）的标准：面向要深入理解的学习者，每个概念都配标注图、真实数字和"改一个变量看结果"的动画。写任何实验记录、方法说明、消融结果前先读。 |
教学式文档标准
读者是项目负责人本人，目标是深入理解每个环节怎么算、为什么这样设计、参数变了会怎样，不是记流水账。
一句话检验：读者看完能不能自己改一个参数并预测结果？不能就没写完。
三件必配的东西
任何一个"概念 / 张量 / 方法 / 设计决策"出现在文档里，都要配齐：
- 标注图（在哪）：在仿真 / 可视化里截图，用工具（PIL / matplotlib）在图上画箭头和文字，标出这个东西对应画面里的哪个部位、在数组里的哪个下标。
- 写
body (T,258) 不够；要一张骨架图，每个关节旁标
j=18 left_elbow → feat[:, 54:60]（si.skeleton.body_slot 就是干这个的）。
- 写"条件 128 维"不够；要一张图把音频那一路和文本那一路分开画出来，
标出「这一段是第 t 帧的 Mel、这一段是第 t 帧正在说的词的嵌入」。
- 算例（怎么算）：挑一条最小的链路（左臂、一个关节、一帧）把数字真的算一遍列出来：输入数值 → 每一步的中间量 → 输出。公式旁边放真实数字，不放符号堆。
- 控制层：一个控制量（比如
R_el_flex）的静息值、三路偏移、合成值、
对应的旋转矩阵、6D 的 6 个数、FK 出来的手腕坐标，一张表走完。
- flow matching：一条真实样本的 x、ε、某个 t 下的 x_t、目标速度 v、模型预测 v̂，
以及从 v̂ 反推出的 x̂₀，全部给数字。
- 指标：一个语义事件的峰值帧姿态到 13 个类别原型的 13 个距离，指出最小的那个是谁。
- 动画（改了会怎样）：只改一个变量，其余固定，连续扫一遍，把结果录成 GIF/mp4，标题里实时显示变量值和输出值。
- 控制层：单个自由度 0→最大值扫一遍，看火柴人怎么动（
scripts/explain_*.py 里有模板）。
- 采样：ODE 步数 5/10/25/50、CFG 权重 1.0/1.5/3.0，同一条件下生成结果的差异。
- FOPPAS：overlap = 0/4/8/16，接缝处速度突变的对比曲线 + 同屏视频。
- 条件：同一条语音、只改文本条件，人物做出不同手势 —— 这是本项目最该有的一张图。
方法说明的写法
先说它在解什么优化问题（目标函数是什么、变量是什么、约束是什么），再说怎么解，最后给两个对比例子："这种情况 loss 更大因为…"、"把参数改成…之后同一个动作会被重建成…"。
阻尼最小二乘 IK 的例子：目标 min ‖W(目标位置 − FK(q))‖² + λ‖Δq‖² + w_smooth‖q − q_prev‖² + w_home‖q − q_home‖²；
变量是 29 个关节角；每次迭代解 (JᵀWJ + λI)Δq = JᵀW r。要给：一帧真实的 r 和 J 的数字、λ 大小对 Δq 的影响图、三组参数下同一帧的三张重建对比。
生成模型部分的写法
- 条件：标注图（音频那一路 / 文本那一路分开画）+ 一帧真实数值 + 四种文本模式的对照图。
- 目标函数：flow matching 的 x_t、v、x̂₀ 三者的关系画成一条线，配一组真实数字；
和 DDPM 的 ε 预测放在一起对比。
- 采样：ODE 每一步 x 的轨迹（挑几个维度画），标出 CFG 在哪一步起作用。
- 指标：每个指标都要写清它什么时候会骗人。
BeatAlign 和 Diversity 在动作抖动时会双双刷高（论文原文提醒过），
MPJPE 对多对多任务天然不利 —— 这两条必须配一张"指标好但视频差"的反例图。
- 消融：表格（指标）+ 同屏视频（行为）+ 混淆矩阵 + 每组一句"为什么会这样"。
视频与图的规范
- 同屏对比用
scripts/video_grid.py，每格带中文标签，标签写清变量值
（"text_mode=shuffle"而不是"实验 2"）。
- 骨架用
si.render.render，传 overlay= 可以把生成叠在真值上（蓝=真值、红=生成）。
- 视频要带音轨（
si.render.mux），否则看不出手势和语音对不对得上。
- 标注图统一放
docs/figs/，生成脚本放 scripts/explain_*.py，可重跑。
- GIF 给飞书内嵌（< 5 MB，抽帧缩放），mp4 作附件。
- 每张图/视频下面一句话说"看什么"。
写作顺序（每一节）
- 先放图/视频（读者先看到现象）
- 再放数字算例（读者看到现象是怎么算出来的）
- 再放对比/扫参动画（读者看到参数怎么影响现象）
- 最后一段话讲设计决策和出处
- 末尾给复现命令
自检清单
