# Teaching Doc

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

- Skill: `ryf1123/teaching-doc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ryf1123/teaching-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryf1123/teaching-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ryf1123 (https://skillmd.com/u/ryf1123)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryf1123/teaching-doc

---


# 教学式文档标准

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

## 三件必配的东西

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

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. 末尾给复现命令

## 自检清单

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