Nav2 调参：因果顺序比旋钮百科重要

1. 越调越怪的循环

窄门通过率从「偶发」变成「随机」——那一周我们同时改了 inflation_radius、max_vel_x、transform_tolerance 和 BT recovery 链。每次改动似乎有点用，合在一起却完全不可预测。回滚后按簇重做：先修 AMCL 在窄廊的跳变，再清 costmap 残影，路径质量起来后，控制器只动了 path_dist_scale 和 max_vel_theta 两项就稳住了。max_vel_x 反而比「调低很多」的版本更高——世界观诚实了，速度界限才敢放开。同时拧二十个参数，失去的不仅是时间，是可证伪性。

2. 四簇顺序（每次只动一簇）

1. 定位簇：AMCL/slam 的 update_min_d、transform_tolerance、粒子收敛；验收：协方差稳定、无跳变、窄廊不漂。
2. Costmap 簇：层配置、inflation_radius、footprint、clearing 范围；验收：分层截图、残影袋、窄门几何。
3. Planner 簇：tolerance、全局膨胀、未知空间策略 allow_unknown；验收：路径最小间隙、无解率。
4. Controller 簇：max_vel_x、critic 权重、progress/goal checker；验收：跟踪误差、振荡、到点精度。

恢复行为（BT XML）单独成第五簇，必须在场景袋上验证——不得与 controller 簇同 PR。

3. 参数簇内的联动

一簇内相关的两三个旋钮可一起动，跨簇禁止同一次实验。例如 costmap 簇：inflation_radius + cost_scaling_factor + footprint 同审；controller 簇：max_vel_x + max_vel_theta + acc_lim_x 同审。每簇实验固定路径集：同一组目标点、同一初始位姿分布——否则成功率对比无意义。

# 定位簇示例——只动这些
amcl:
  ros__parameters:
    update_min_d: 0.25
    transform_tolerance: 0.5
    max_particles: 2000

4. 受控实验记录模板

每次实验写四行：假设 → 改动项 → 观测 → 结论。

成功标准量化：10 次 ≥9 成功、碰撞 0、最大横向误差 < 0.15 m。没有记录的调参无法迁到下一台车。

5. 可交接的套件

最值钱的不是「最终 yaml」，而是套件：

• 地图 + 初始位姿集合 + 目标点列表
• 成功标准（量化）
• 禁止同时改动的参数簇声明
• 已知回归袋（窄门/残影/定位丢失）

新人只许在一簇内实验；参数 PR 必须带假设与套件结果。仿真验证顺序可照搬，绝对增益不可照搬——真机延迟与滑移不同。

6. 常见因果误判

表象在 controller 层，根因往往在 costmap 或 TF——顺序错了，会在错误层浪费时间。

7. 验收

• 参数 PR 标注所属簇；跨簇改动拒绝合并。
• 每簇改动附套件结果（成功率/误差/截图）。
• 启动摘要打印关键有效值（膨胀、速度界限、footprint），可 ros2 param get 核对。
• 「越调越怪」时强制回滚，从定位簇重跑——手感救不了失去的因果。

8. 与参数声明的交点

未声明参数让 yaml 键名静默失效（见参数声明文）。调参之前确认 ros2 param describe 能看见目标键——否则拧的是空气。Nav2 Composable 容器里覆盖更绕，以加载后的有效值为准。

9. 启动摘要与 param dump

每次实验前后 ros2 param dump /controller_server > before.yaml 留档。Nav2 Composable 容器里节点名带 namespace，dump 路径要对。对比 diff 比凭记忆可靠。启动脚本打印关键有效值：膨胀半径、max_vel、footprint 顶点数——现场一眼看出加载了哪套配置。

跨簇改动 PR 必须附套件前后对比表，否则 reviewer 无法判断因果。调参是因果实验，不是旋钮百科。先证明地图与定位诚实，控制器才是最后一公里。