teaching-doc

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

教学式文档标准

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

三件必配的东西

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

1. 标注图（在哪）：在仿真 / 可视化里截图，用工具（PIL / matplotlib）在图上画箭头和文字，标出这个东西对应画面里的哪个部位、在数组里的哪个下标。
   • 写 poses (T,156) 不够；要一张骨架图，每个关节旁标 j=18 left_elbow → poses[t, 54:57]。
   • 写"观测 196 维"不够；要一张 G1 截图，用颜色框出"这 29 维是关节角、这 3 维是重力方向（箭头画在骨盆上）、这 87 维是未来参考（画出未来 3 帧的虚影）"。
2. 算例（怎么算）：挑一条最小的链路（左臂、一个关节、一帧）把数字真的算一遍列出来：输入数值 → 每一步的中间量 → 输出。公式旁边放真实数字，不放符号堆。
   • FK：左臂 7 个关节的 rest 偏移、轴角、累计旋转、手腕世界坐标，一张表。
   • IK：一帧的残差向量、雅可比的形状和几个数、阻尼前后 Δq 的差别。
   • 奖励：一步里每一项的误差值、exp 之后的值、权重、加起来是多少。
3. 动画（改了会怎样）：只改一个变量，其余固定，连续扫一遍，把结果录成 GIF/mp4，标题里实时显示变量值和输出值。
   • FK：转一个肘关节 0→120°，看手腕轨迹；转肩关节，看肘和腕一起动；转脊柱，看整条臂都动。
   • IK：阻尼 λ 从 0.001 到 1，同一帧重建出的姿态怎么从"精确但抖"变成"平滑但偏"；权重 w_home 从 0 到 10，姿态怎么被拉回中立位。
   • RL：动作尺度 / 未来帧数 / RSI 开关，同一参考下策略行为和曲线的差异（消融就是这个的系统版）。

方法说明的写法

先说它在解什么优化问题（目标函数是什么、变量是什么、约束是什么），再说怎么解，最后给两个对比例子："这种情况 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 的影响图、三组参数下同一帧的三张重建对比。

RL 部分的写法

• 观测：标注图 + obs_layout() 的表 + 一步真实数值。
• 动作：画"策略输出 a → PD 目标 = home + 0.5a → 力矩 = kp(目标 − q) − kv·q̇ → 关节实际转到哪"的链，一个关节的数值 + 一段动画。
• 奖励：一段 rollout 里每一项随时间的曲线，和视频并排（同一时间轴）；标出摔倒 / 跟丢的时刻奖励怎么变。
• RSI / 早停 / 截断：用图说明 episode 从哪开始、在哪结束、为什么那一步不 bootstrap。
• 训练曲线：每条曲线旁写"健康的样子"和"不对劲时查什么"。
• 消融：表格（指标）+ 同屏视频（行为）+ 每组一句"为什么会这样"。

视频与图的规范

• 同屏对比用 scripts/video_grid.py，每格带中文标签，标签写清变量值（"λ=0.1"而不是"实验 2"）。
• 人体用 scripts/render_human.py，G1 用 rl.play --reference/--run。
• 标注图统一放 docs/figs/，生成脚本放 scripts/explain_*.py，可重跑。
• GIF 给飞书内嵌（< 5 MB，抽帧缩放），mp4 作附件。
• 每张图/视频下面一句话说"看什么"。

写作顺序（每一节）

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

自检清单

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