6.3 调试方法论与常见故障对照
6.3 调试方法论与常见故障对照
本节摘要：性能有画像、接触有处方，剩下的异常——训练曲线诡异、能量凭空消失、两台机器结果不同——需要一套通用的排错思维：先复现、再收缩、后归因，每一步只动一个变量。本节给出「最小复现」方法论的完整操作，附一份覆盖九类高频故障的对照表，以及故障笔记的记录格式。方法论的价值不在第一次用，在第一百次用时依然稳定省时。
6.1 治慢、6.2 治抖，本节兜底其余一切。它不新增引擎知识，而是把前五章的所有原理组织成一套排错时不会乱的工作流程。
一、故障对照表先亮出来
方法论之前，先把「急救手册」放桌上。九类高频故障，现象、首查、病根三层结构，按出镜率排序：
| 现象 | 首查 | 常见病根 |
|---|---|---|
| 接触高频抖动 | solref 与步长关系 | 欠阻尼加薄件惯量（6.2 实录） |
| 仿真慢 | 分段性能画像 | condim 与碰撞配对浪费（6.1） |
| 能量凭空膨胀 | 积分器与步长失配 | 显式注能、系统最高频越界（3.3） |
| 物体缓慢下沉或漂移 | 接触软垫剖面 | solimp 软、地面摩擦过低 |
| 两台机器结果不同 | 版本与种子 | 绑定版本差异、随机源未固定 |
| 训练曲线诡异 | 环境四件套 | 观测含未来、奖励不同源（5.1） |
| 约束行为怪异 | equality 参数 | solref 冲突、约束互相打架 |
| 穿透 | 稳态还是间歇 | solimp 深层刚度、高速隧穿 |
| 模型加载失败 | 报错行号 | 单位制、惯量缺失、引用悬空 |
表的用法是「首查命中即入节」：现象对上第一列，按第二列的动作执行，多数故障两步内入港。首查不中再进方法论——那张网兜住剩下的疑难杂症。
二、最小复现：把大问题压缩到十行
疑难故障的标准开局不是盯着大模型发呆，而是收缩：把出问题的场景逐步裁剪到最小的、仍然复现故障的模型。收缩的威力来自组合数学——大模型的参数空间上千维，最小复现往往十行以内、参数一只手数得过来，归因从大海捞针变成逐个排查。
标准流程四步：
第一步：钉死复现。 固定随机种子、固定初始状态、固定版本，「有时出现」的故障先变成「每次出现」。引擎的确定性（第一章的老朋友）是钉死复现的底气：同输入必同输出，问题跑一遍在、跑十遍都在。
第二步：分层剥离。 依次关掉与现象最可能无关的部分：执行器换零控制、接触对象逐个移走、传感器断开、柔性件换刚体。每剥一层跑一次——故障消失的那一次剥离，就是定位。某「机械臂抓取时随机抖飞」的故障，剥离到「只剩夹爪与物块」仍在，五分钟锁定是夹爪闭合速度过快导致接触穿透，与机械臂整体无关。
第三步：二分参数。 怀疑参数组内多个参数时，二分而非逐个：先把怀疑组参数全部回默认（故障应在），再一半恢复嫌疑值（故障在与不在，锁定一半），两三轮收敛到单参数。比逐个快一个数量级。
第四步：对照实验留证。 病因假设提出后，做一次「唯一变量」实验：同一个模型，只切这个参数，现象应随之切换。切得动，归因成立；切不动，假设作废重来。这一步防的是「巧合修复」——改了五处、坏了的地方好了，你谢错了人。
图 6-3 最小复现四步：从「有时出现」到「唯一变量归因」
三、故障笔记：让排错成为团队资产
最小复现的终点不是修好，是写下来。故障笔记的格式越简单越能坚持，四个字段足矣：
现象：静止站立三十秒后足底高频抖动，振幅缓增 最小复现：十行场景——脚掌 box 加地面，solref 时间常数等于步长 病因：软垫时间常数与步长相等叠加欠阻尼，回弹过冲成环 处方与验证：时间常数提到五倍步长、阻尼比回一，唯一变量验证通过
这份四行记录的价值兑现在两种时刻：三个月后同款故障出现，检索「抖动 加步长」直接命中；新成员接手项目，故障笔记是他能继承的最贵的资产。一个团队的排错能力，不看最强大脑的水平，看笔记库的厚度。
四、几个「疑似引擎 bug」的真相
排错路上有个高频心理陷阱：查了两小时毫无头绪，结论滑向「引擎有 bug」。以试车场多年的接单经验，这个结论的命中率极低，而下面四个「疑似 bug」各有常见真相：
真相一：版本差异。 「同一份模型两个同事跑出不同结果」，十有八九是绑定版本不同（1.2 讲过新旧两代绑定）或 option 默认值随版本演进。核对版本号是跨人排错的第一句话，不是最后一句话。
真相二：默认值在替你做主。 引擎有大量「不写就用默认」的参数——solref、solimp、摩擦组合规则、求解器算法。「我没设过这个参数」不等于「它没有值」；诊断时把关键默认值显式打印出来看，常能终结悬案。
真相三：环境层的锅。 训练类故障的相当比例最后查到 5.1 的环境四件套：观测含未来、奖励不同源、重置泄漏。引擎只是忠实执行，异常是环境层喂给它的。排错顺序永远是：环境四件套自检、再进引擎参数。
真相四：数值病伪装成逻辑病。 「策略学会了一只手虚抓空气」这类看似算法层的行为问题，追下去常是接触参数让触觉观测带噪声，策略在拟合噪声。3.3 的能量账本与 6.2 的体检单是分辨数值病的两件仪器——仪器先上，再怀疑逻辑。
本节要点回顾
- 对照表开路：九类高频故障按「现象—首查—病根」对号入座，两步内入港；
- 最小复现四步：钉死复现、分层剥离、二分参数、唯一变量归因，大问题压缩到十行；
- 巧合修复是债：没有唯一变量验证的修复，只是把问题推迟到下个版本；
- 故障笔记四字段：现象、最小复现、病因、处方与验证——团队最贵的资产；
- 「引擎 bug」四真相：版本差异、默认值做主、环境层的锅、数值病伪装，结论前先过这四关。
到此，排错的方法与工具全部交齐。下一章走出失速区，看看这座试车场的未来：当模型健康、方法论在手，GPU 并行、可微分与人形浪潮会把 MuJoCo 的边界推到哪。