teaching-doc

name	teaching-doc
description	本项目写文档（飞书 + docs/）的标准：面向要深入理解的学习者，每个概念都配标注图、真实数字和"改一个变量看结果"的动画。写任何实验记录、方法说明、消融结果前先读。

教学式文档标准

读者是项目负责人本人，目标是深入理解每个环节怎么算、为什么这样设计、参数变了会怎样，不是记流水账。 一句话检验：读者看完能不能自己改一个参数并预测结果？不能就没写完。

三件必配的东西

任何一个"概念 / 张量 / 方法 / 设计决策"出现在文档里，都要配齐：

1. 标注图（在哪）：在仿真 / 可视化里截图，用工具（PIL / matplotlib）在图上画箭头和文字，标出这个东西对应画面里的哪个部位、在数组里的哪个下标。
   • 写 body (T,258) 不够；要一张骨架图，每个关节旁标 j=18 left_elbow → feat[:, 54:60]（si.skeleton.body_slot 就是干这个的）。
   • 写"条件 128 维"不够；要一张图把音频那一路和文本那一路分开画出来， 标出「这一段是第 t 帧的 Mel、这一段是第 t 帧正在说的词的嵌入」。
2. 算例（怎么算）：挑一条最小的链路（左臂、一个关节、一帧）把数字真的算一遍列出来：输入数值 → 每一步的中间量 → 输出。公式旁边放真实数字，不放符号堆。
   • 控制层：一个控制量（比如 R_el_flex）的静息值、三路偏移、合成值、 对应的旋转矩阵、6D 的 6 个数、FK 出来的手腕坐标，一张表走完。
   • flow matching：一条真实样本的 x、ε、某个 t 下的 x_t、目标速度 v、模型预测 v̂， 以及从 v̂ 反推出的 x̂₀，全部给数字。
   • 指标：一个语义事件的峰值帧姿态到 13 个类别原型的 13 个距离，指出最小的那个是谁。
3. 动画（改了会怎样）：只改一个变量，其余固定，连续扫一遍，把结果录成 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 作附件。
• 每张图/视频下面一句话说"看什么"。

写作顺序（每一节）

1. 先放图/视频（读者先看到现象）
2. 再放数字算例（读者看到现象是怎么算出来的）
3. 再放对比/扫参动画（读者看到参数怎么影响现象）
4. 最后一段话讲设计决策和出处
5. 末尾给复现命令

自检清单

• 每个出现的张量形状，图上能指出它在哪
• 每个公式旁边有真实数字
• 每个"为什么这样设计"有一个反例（不这样会怎样）的图或视频
• 每个参数有一张扫参图或一组对比
• 踩的坑有"修复前 / 修复后"并排
• 每节结尾有复现命令