| name | teaching-doc |
| description | 本项目写文档（飞书 + docs/）的标准：面向要深入理解的学习者，每个概念都配标注图、真实数字和"改一个变量看结果"的动画。写任何实验记录、方法说明、消融结果前先读。 |
教学式文档标准
读者是项目负责人本人，目标是深入理解每个环节怎么算、为什么这样设计、参数变了会怎样，不是记流水账。
一句话检验：读者看完能不能自己改一个参数并预测结果？不能就没写完。
三件必配的东西
任何一个"概念 / 张量 / 方法 / 设计决策"出现在文档里，都要配齐：
- 标注图（在哪）：在仿真 / 可视化里截图，用工具（PIL / matplotlib）在图上画箭头和文字，标出这个东西对应画面里的哪个部位、在数组里的哪个下标。
- 写
poses (T,156) 不够；要一张骨架图，每个关节旁标 j=18 left_elbow → poses[t, 54:57]。
- 写"观测 196 维"不够；要一张 G1 截图，用颜色框出"这 29 维是关节角、这 3 维是重力方向（箭头画在骨盆上）、这 87 维是未来参考（画出未来 3 帧的虚影）"。
- 算例（怎么算）：挑一条最小的链路（左臂、一个关节、一帧）把数字真的算一遍列出来：输入数值 → 每一步的中间量 → 输出。公式旁边放真实数字，不放符号堆。
- FK：左臂 7 个关节的 rest 偏移、轴角、累计旋转、手腕世界坐标，一张表。
- IK：一帧的残差向量、雅可比的形状和几个数、阻尼前后 Δq 的差别。
- 奖励：一步里每一项的误差值、exp 之后的值、权重、加起来是多少。
- 动画（改了会怎样）：只改一个变量，其余固定，连续扫一遍，把结果录成 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 作附件。
- 每张图/视频下面一句话说"看什么"。
写作顺序（每一节）
- 先放图/视频（读者先看到现象）
- 再放数字算例（读者看到现象是怎么算出来的）
- 再放对比/扫参动画（读者看到参数怎么影响现象）
- 最后一段话讲设计决策和出处
- 末尾给复现命令
自检清单
