三类失败：ENG / ALG / SCN

为什么需要失败分类

闭环评测一个 case 失败了，第一件事不是”改模型”，而是搞清楚失败的根因归属。verify_batch 这个验收脚本把每个失败 case 自动归到三类身份，每类的修法完全不同：

类别	含义	根因层	修法
ENG	工程问题	参数 / 控制管道	改配置、改参数、改控制逻辑
ALG	算法局限	模型本身	重训、微调、改架构
SCN	场景几何	Bench2Drive 场景设计	修场景（行为树、路线、NPC 编排）

混淆这三类会导致修错地方：把 SCN 当 ALG 去改模型，怎么改都没用（场景没真的发生交互）；把 ALG 当 ENG 去调参数，掩盖了模型的真问题。

三类的判定逻辑

ENG：控制管道能改的

ENG 类的标志是”模型输出是对的，但执行环节出了问题”。典型表现：

• 起跑速度配不上可用距离（warmup 把车推太快）。
• 控制器参数（Pure Pursuit 的 lookahead、PID 增益）和场景不匹配。
• 帧率/超时配置错。

判定线索：模型的规划轨迹是合理的（减速、避让），但 Ego 实际行为不符合规划。修法在控制管道，不动模型权重。

ALG：模型本身的局限

ALG 类的标志是”模型在分布外场景上系统性输出错误”。典型表现（EP06 的弯道案例）：

• 输入是弯道场景，模型输出直线轨迹。
• 在训练集没见过的几何/天气上整体崩溃。
• 检测模块漏检关键目标导致规划错。

判定线索：模型输出的轨迹本身就不合理（ steer 全程为 0、81% tick off-road）。修法是重训或微调模型，工程管道无能为力。

SCN：场景设计的缺陷

SCN 类的标志是”场景本该发生的交互没发生”。典型表现（cut_in_right 案例）：

• 行为树里的 ChangeLane 节点在该路段返回 FAILURE。
• NPC 走了平行路径，从未真正切入。
• 路线定义的触发位置和实际路网拓扑不匹配。

判定线索：模型表现”看起来差”，但仔细看 NPC 行为发现场景根本没执行设计的交互。修法是改场景编排（行为树、路线、子类化），既不动模型也不动控制管道。

自动判定的关键指标

verify_batch 用几个客观指标辅助分类：

指标	含义	用途
npc_in_lane_ticks	NPC 真正在 Ego 车道内的帧数	0 → SCN（切入没发生）
min_lateral_distance	NPC 和 Ego 的最小横向距离	持续 >3m → SCN
steer 序列	控制层转向指令	全程 0 → ALG（模型没转弯意图）
off_road_ratio	off-road 帧数占比	>50% → ALG
brake 峰值时刻	全力刹车出现的时机	刹车太晚 → ENG（速度配不上距离）

这些指标让分类客观可复现，不靠人眼判断。

诚实归因的工程价值

EP07 反复强调”诚实展示边界，比掩盖问题更重要”。归因错位的代价：

• 虚低：把 SCN 当 ALG，模型的实际能力被低估，误导后续优化方向。
• 虚高：把 ALG 当 ENG 用参数 patch 掉，掩盖模型真问题，部署时爆雷。
• 不可复现：没有客观指标，靠人判断，换个人分类结果就变。

正确归因是工程迭代的基础——只有知道失败真正属于哪一层，才能在那一层对症下药。EP07 的 T1（SCN）和 T2（ENG）就是两个典型范例。

参考

• Bench2Drive 论文（失败分析）
• 根因分析（Root Cause Analysis, 维基百科）

T1 根因：cut_in_right 永远不切入

现象与诊断

cut_in_right 这条 case 在 epic_v2 跑出来是 WARN，自动诊断指标：

• npc_in_lane_ticks = 0：NPC 从来没进入过 Ego 车道。
• 横向距离从 2.9 m 单调增大到 12 m：NPC 离 Ego 越来越远。

这两个指标共同指向：“切入”这个动作根本没发生。verify_batch 据此判 SCN。

根因链：从行为树到 OpenDRIVE

NPC 没切入不是随机故障，是确定性的拓扑失败，根因链有三层：

第一层：行为树的 ChangeLane 节点

Bench2Drive 的 cut_in_right 由 ScenarioRunner 行为树编排，核心节点 ChangeLane(target_lane=ego_lane) 要求 NPC 切到 Ego 车道。这个节点不是直接发”横向位移”指令，而是请求 CARLA 生成一条变道路径。

第二层：CARLA 的 waypoint 生成

ChangeLane 内部调 waypoint.get_left_lane() / get_right_lane() 查询：当前位置能否合法换到相邻车道。这个查询依赖 OpenDRIVE 里两个车道之间的 LaneChange 拓扑——不是任意相邻车道都能换，要 OpenDRIVE 明确允许才行。

第三层：OpenDRIVE 的 LaneChange 属性

OpenDRIVE 里每条车道有 <lane> 元素，相邻车道之间的变道权限由车道类型、虚实线类型、<rule> 属性共同决定。Town04 弯道段的 OpenDRIVE 没有定义合法的 LaneChange 拓扑——可能是弯道曲率太大（变道不安全）、或车道类型限制（如应急车道）。

结果：get_right_lane() 返回 None 或非法，ChangeLane 节点永远 FAILURE。

为什么 NPC 走了平行路径

行为树的回退逻辑：当 ChangeLane 失败，NPC 不能停下（会阻塞交通），退而求其次沿当前车道继续走。在弯道上，NPC 车道和 Ego 车道的曲率不同，沿各自车道前进时横向距离被动拉开：

$\Delta y(s) = \int_0^s \left(\kappa_{\text{npc}}(s') - \kappa_{\text{ego}}(s')\right) ds'$

其中 $\kappa$ 是车道曲率。弯道越深，$\Delta y$ 越大——这就是横向距离从 2.9 m 涨到 12 m 的几何原因。这不是 NPC 主动远离 Ego，是弯道几何的必然。

为什么 Ego 还是刹了车

诊断显示 Ego 确实有减速，但这不是”真切入触发的避让”，而是二次反应：

• NPC 在右后方接近，进入 Ego 的感知范围。
• SparseDriveV2 检测到右侧有车，谨慎减速（合理行为）。
• 但这种减速不是场景设计的考点——考点是”NPC 切入 Ego 正前方时 Ego 该怎么让”。

场景设计的交互没发生，Ego 的减速只是对旁边有车的本能反应。所以这条 case 的 WARN 分数不反映模型的真实 cut-in 处理能力——它根本没被考到。

为什么这是 SCN 而不是 ALG/ENG

三类归因的核心问题：模型和控制管道有没有错？

• 模型：检测到右侧有车并减速，是合理反应——没错。
• 控制管道：把减速意图正确执行——没错。
• 错的是场景：行为树假设的”NPC 能在弯道变道”这个前提不成立。

把这种 case 当 ALG 去改模型，会冤枉模型（模型已经做了它能做的合理决策）。把这种 case 当 ENG 去调参数，也修不好（参数再怎么调，NPC 还是不会切入）。唯一正确的修法是让场景真的发生切入——这就是 T1 解法（B05）的内容。

这类问题的普遍性

LaneChange 拓扑缺失不是 Town04 弯道独有的问题。任何 OpenDRIVE 路网拓扑和行为树假设不匹配的地方都会出现：

• 环岛（多车交织，变道拓扑复杂）。
• 匝道汇入（车道类型变化）。
• 施工段（临时车道限制）。

这是仿真评测协议的固有挑战——场景设计依赖底层 API，底层 API 依赖路网拓扑，多层依赖任一环失效场景就空转。诚实面对这类 SCN 问题，是评测可信度的前提。

参考

• CARLA — OpenDRIVE 与 LaneChange
• ASAM OpenDRIVE 标准
• ScenarioRunner 行为树

T1 解法：自写 Python 子类

底层原则：不动上游

修 SCN 类问题的工程纪律是不动上游仓库：

• 不 fork Bench2Drive、不改它的源码——否则后续 upstream 升级要处理合并冲突。
• 不改 CARLA 本身——动 UE 源码成本极高。
• 只在外部加一层，用 Python 的继承/路由机制替换行为。

这样修法是最小侵入的：Bench2Drive 仓库一行没改，只在自己的 loader 里加 30 行路由代码。

子类化：把 LaneChange 参数改激进

新建一个 Python 子类 AutoSimCutInRight，继承 Bench2Drive 的 CutIn 父类，只重写四个 LaneChange 相关参数，让 NPC 在弯道前的直线段就完成切入：

class AutoSimCutInRight(CutIn):
    """cut_in_right 在 Town04 弯道段的修复子类。
    
    父类 CutIn 依赖 CARLA 在触发位置生成 LaneChange waypoint，
    但弯道段没有合法拓扑，ChangeLane 永远 FAILURE。
    解法：把触发条件提前到还允许变道的直线段。
    """
    # 四个 LaneChange 参数全部改激进
    CATCHUP_TRIGGER_DISTANCE = 15.0   # 父类 5m → 15m，更早开始追
    LATERAL_START_DISTANCE = 2.0      # 父类 5m → 2m，更早开始横切
    LANE_CHANGE_ARC_LENGTH = 15.0     # 父类 25m → 15m，横切更快
    # （第四个参数类似，压缩变道时间窗）

四个参数的作用机制：

参数	父类值	子类值	物理意义
CATCHUP_TRIGGER_DISTANCE	5 m	15 m	NPC 距 Ego 多远开始追击
LATERAL_START_DISTANCE	5 m	2 m	横切起点距 Ego 多远
LANE_CHANGE_ARC_LENGTH	25 m	15 m	完成变道走过的弧长

核心思想：让 NPC 在弯道前的直线段（OpenDRIVE 允许变道）就把切入做完，而不是等到弯道段（拓扑不允许）才尝试。

为什么提前到直线段就行

直线段的 OpenDRIVE 拓扑是完整的——相邻车道之间有合法 LaneChange 权限。所以：

• 在直线段，ChangeLane 节点能成功生成变道路径。
• NPC 在弯道前完成切入，进入弯道时已经在 Ego 车道内。
• 弯道段的拓扑限制不再相关（不需要再变道）。

这是个绕过而非修复的方案——它没改弯道段的 OpenDRIVE，只是把交互时机提前到拓扑允许的地方。对于”测 Ego 对 cut-in 的反应”这个考题来说，提前到直线段发生 cut-in 完全等价。

Loader 层路由：30 行代码

在加载场景的 loader 里加一层路由：

# loader.py（自己维护，不改 Bench2Drive）
from bench2drive.scenarios import CutIn
from myfixes import AutoSimCutInRight

SCENARIO_OVERRIDES = {
    'cut_in_right_osc2': AutoSimCutInRight,   # 只路由这一个 case
    # cut_in_left 不路由（见 B06）
}

def load_scenario(case_id, world, tm):
    cls = SCENARIO_OVERRIDES.get(case_id, DEFAULT_REGISTRY[case_id])
    return cls(world, tm)

当 case_id == 'cut_in_right_osc2' 时，loader 用 AutoSimCutInRight 替换上游的 CutIn。其他 case 走默认注册表，完全不受影响。

这种”按 case_id 路由”的设计让修复精准定向——只改有问题的那一个 case，不波及其他。30 行 loader 代码换来一个 SCN 修复，性价比极高。

修复后的效果（B08 详述）

epic_v3 跑这个 case：

• NPC 在直线段完成真正切入（npc_in_lane_ticks 从 0 跳到 18）。
• Ego 检测到切入，输出减速轨迹。
• 最近距离 2.06 m（合理的安全余量）。
• case 从 WARN 变 PASS。

易错点

• 子类参数不要改过头：太激进会让 NPC 行为不真实（如瞬间切入），虽然能触发交互但偏离真实交通。
• 路由要精准：只路由确认有问题的 case_id，盲目扩大路由范围会引入新问题（B06 的 cut_in_left 反例）。
• 保留可追溯性：子类和路由都要有注释说明为什么这么改，否则后续维护者不知道意图。

参考

• Python 继承与方法重写
• ScenarioRunner 自定义场景
• CARLA — OpenDRIVE LaneChange

T1 反直觉决策：cut_in_left 不路由

一个反直觉的工程决策

既然 AutoSimCutInRight 子类修好了 cut_in_right，“顺手”也把它路由给 cut_in_left 看起来很合理——左右对称嘛。但这样做反而让 cut_in_left 回归 WARN。正确的决策是：子类只路由右侧，左侧保持原样。

这是个典型的”想当然扩大修复范围反而引入回归”的例子。

为什么 cut_in_left 不能用激进参数

把激进子类路由到 cut_in_left 后的现象：

• NPC 切完车道后，贴在 Ego 后方 4 米持续 300 个 tick（约 15 秒）。
• 触发 Pure Pursuit 控制器的 proximity yield（近距离让行）逻辑。
• Ego 平均速度从 31 km/h 砸到 10 km/h。
• 速度太低，路线完成率下降，case 回归到 WARN。

根因是左右场景几何不对称：

• cut_in_right：NPC 从右切入，切完后在 Ego 右前方，自然加速离开。
• cut_in_left：NPC 从左切入，切完后如果参数激进，会”贴”在 Ego 左后方（因为左侧车流的几何和右侧不同），长时间保持近距离。

同样的激进参数在右边是”快速切入然后离开”，在左边变成”快速切入然后黏住”。对称的参数不对称的效果——这是仿真场景的常见陷阱。

Pure Pursuit 的 proximity yield 机制

为什么 Ego 会减速到 10 km/h？因为轨迹跟踪控制器里有 proximity yield（近距离让行）逻辑：

def proximity_yield(npc_distance, model_target_speed):
    """近距离时主动让行，覆盖模型的目标速度。
    
    返回 max(2.0, 0.35 * npc_distance)：保证最低 2.0 的下限。
    """
    return max(2.0, 0.35 * npc_distance)

当 NPC 在 4 m 内持续存在时：

$v_{\text{target}} = \max(2.0,\ 0.35 \times 4) = \max(2.0,\ 1.4) = 2.0\ \text{m/s} \approx 7.2\ \text{km/h}$

这个 yield 逻辑覆盖了模型原本的目标速度——模型想让车保持 31 km/h，但 proximity_yield 强制压到 7.2 km/h。结果 Ego 龟速，路线跑不完。

注意这里用的是 max 而不是 min——这是 B10 反复出现的关键细节。max 保证”至少开多快”（防卡死），但在需要停车的场景反而会阻止减速。

为什么 cut_in_left 在 epic_v2 本来就 PASS

cut_in_left 在 epic_v2（未修复版）用的是 Bench2Drive 原版的 CutIn 父类，参数温和（catchup 5m、lateral 5m、arc 25m）。温和参数下：

• NPC 切入后不会贴住 Ego，而是按正常车流速度离开。
• 不触发 proximity_yield 的持续近距离。
• Ego 能保持正常速度，case PASS。

所以 cut_in_left 本来就没问题——不需要修。强行套用激进子类反而破坏了原本正常的行为。

用单元测试守护决策

视频强调的关键工程实践：把”cut_in_left 不路由”这个决策写成一条永久单元测试：

def test_cut_in_left_not_overridden():
    """守护：cut_in_left 必须用原版 CutIn，不能路由到 AutoSimCutInRight。
    
    历史教训：曾尝试对称路由，导致 NPC 贴在 Ego 后方触发 proximity_yield，
    平均速度从 31 km/h 降到 10 km/h，case 回归 WARN。
    """
    assert 'cut_in_left' not in SCENARIO_OVERRIDES, \
        "cut_in_left 不应被路由到激进子类（见历史回归）"

这条测试的意义：

1. 防止重蹈覆辙：以后任何人想”扩大路由范围”都会被这条测试挡住。
2. 记录决策理由：测试的 docstring 解释了为什么——未来的维护者不需要重新踩坑。
3. 可执行的设计文档：测试本身就是文档，且每次 CI 都跑，比注释更可靠。

通用启示：不对称场景要小心

这个案例的普遍教训：

• 对称假设常出错：左右、前后、不同地图的”看起来一样”的场景，底层几何可能完全不同。
• 修复要定向：修一个 case 不要”顺手”扩到其他 case，每个 case 都要独立验证。
• 保留反例：发现某个修复对某个 case 有害，要记录下来并测试守护，否则未来会有人再试。

参考

• Pure Pursuit 算法
• 回归测试（Regression Testing）
• CARLA — Vehicle control

T2 根因：1.93 米是怎么来的

现象：static_cross 近撞

static_cross 场景里，Ego 接近一个静止障碍物，最近距离只有 1.93 米——视觉上几乎是擦边撞上。verify_batch 判 ENG（工程问题）。

根因：纯运动学不足

诊断显示这不是模型差，也不是控制器软，而是起跑速度配不上可用距离。两个数字摆出来就清楚了：

• 起跑速度：warmup 阶段把 Ego 加速到 36 km/h。
• 可用距离：障碍物在 Ego 正前方 6 米。

36 km/h 全力刹车，理论最小停车距离是 12.5 米——而可用距离只有 6 米。物理上就停不下来。

停车距离公式

匀减速运动的最小停车距离（brake 一开始就拉满 1.0）：

$d_{\text{stop}} = \frac{v^2}{2a}$

其中 $v$ 是初速度，$a$ 是最大减速度。

代入 36 km/h = 10 m/s：

$d_{\text{stop}} = \frac{10^2}{2a}$

视频说 $d_{\text{stop}} = 12.5$ m，反推减速度：

$a = \frac{v^2}{2 d_{\text{stop}}} = \frac{100}{25} = 4\ \text{m/s}^2$

$a = 4\ \text{m/s}^2$ 是 CARLA 在 brake=1.0 时的等效减速度。

这个减速度合理吗

对比真实车辆：

场景	减速度
真实车紧急制动（ABS，干燥路面）	8–9 m/s²
真实车舒适制动	3–4 m/s²
CARLA brake=1.0（推导值）	4 m/s²

CARLA 的 4 m/s² 比真实紧急制动低（约一半）。这是 CARLA 物理引擎的简化——它不是高保真车辆动力学模拟器，刹车模型偏保守。这个差异在大多数场景不明显，但在”极限刹车”场景（static_cross 就是）会成为瓶颈。

为什么 1.93 米不是模型的错

把数字摆开：

$\underbrace{d_{\text{stop}} = 12.5\ \text{m}}_{\text{物理极限}} \;>\; \underbrace{d_{\text{avail}} = 6\ \text{m}}_{\text{可用距离}}$

物理极限（12.5 m）远大于可用距离（6 m）。就算 brake 从第一帧就拉满 1.0、就算模型从看到障碍物那一帧就决策减速，车也停不下来——会以约 $(10^2 - 2 \times 4 \times 6)^{1/2} = \sqrt{100-48} = \sqrt{52} \approx 7.2$ m/s 的残速撞上。

实测撞到 1.93 米（残速更低，因为模型其实更早开始减速），说明模型已经尽力了——它从看到障碍就开始刹车，只是物理上没足够距离。

所以这是 ENG（工程问题）：warmup 把起跑速度定太高，让任何模型都面对一个物理上不可解的刹车任务。

为什么诊断是 ENG 不是 ALG

判 ENG 的逻辑：

• 模型行为合理：看到静止障碍，输出减速轨迹，brake 拉满。
• 控制器行为合理：忠实地把减速意图执行。
• 错的是起跑速度配置：warmup 不该把车推到 36 km/h，因为可用距离只有 6 m。

这是工程管道的参数错（warmup 速度），不是模型能力不足。修法在控制管道（B11），不动模型。

运动学视角的修复方向

要安全停下，需要：

$d_{\text{stop}} = \frac{v^2}{2a} \le d_{\text{avail}} = 6\ \text{m}$

反推最大允许起跑速度：

$v_{\max} = \sqrt{2 a d_{\text{avail}}} = \sqrt{2 \times 4 \times 6} = \sqrt{48} \approx 6.93\ \text{m/s} \approx 25\ \text{km/h}$

所以起跑速度必须降到 25 km/h 以下，才有物理可能在 6 m 内停下。视频的修法把巡航速度从 36 降到 22 km/h（B11），正好留出余量——22 km/h 下 $d_{\text{stop}} = (6.11^2)/(2 \times 4) = 4.67$ m，比 6 m 可用距离小 1.33 m，模型有时间在 3.88 m 处停住。

参考

• 制动距离（Braking distance，维基百科）
• 匀变速运动公式
• CARLA — Vehicle physics

T2 方案 A 反作用：YIELD 反而加速

第一反应：加进 YIELD_CASES

面对 static_cross 的近撞问题，最直觉的修法是”让控制器在靠近障碍物时主动减速”。视频作者第一反应是把 static_cross 加进 YIELD_CASES（让行场景集合），期望 proximity_yield 函数帮 Ego 减速。

但单元测试立刻挂了——YIELD 不但没减速，反而加速了。

根因：max vs min 的语义错位

proximity_yield 函数的实现：

def proximity_yield(npc_distance, model_target_speed):
    """近距离时让行。
    
    返回 max(2.0, 0.35 * npc_distance)：保证目标速度有下限。
    """
    return max(2.0, 0.35 * npc_distance)

问题在 max。当 NPC（这里把 static_cross 的障碍物也当 NPC 处理）在 5 m 内时：

$v_{\text{yield}} = \max(2.0,\ 0.35 \times 5) = \max(2.0,\ 1.75) = 2.0\ \text{m/s} = 7.2\ \text{km/h}$

这个 yield 返回的目标速度（7.2 km/h）覆盖了模型原本的目标速度。而模型在 static_cross 场景里想减速到 1.9 km/h（接近停下）：

速度	数值
模型想要的目标速度	1.9 km/h
yield 返回的目标速度	7.2 km/h
实际采用（yield 覆盖）	7.2 km/h

yield 把模型的刹车意图覆盖了——模型想停，yield 说”至少开 7.2 km/h”，结果车没停住，撞了。

max 和 min 的语义

这是函数语义设计的核心陷阱：

操作	语义	适用场景
max(floor, x)	“至少 floor”	防止车完全卡死（保证最低速度）
min(ceil, x)	“至多 ceil”	防止车开太快（速度上限）

proximity_yield 用 max(2.0, ...) 是为了防止 cut-in 场景下 Ego 完全停车导致后车追尾——保证 Ego 至少蠕行。这个设计对 cut-in 是合理的（让 Ego 缓慢移动避让）。

但对 static_cross 是灾难——static_cross 需要 Ego 完全停下（障碍物在前方），yield 的”最低速度”反而阻止停车。

正确做法应该是 min（取模型速度和 yield 速度的较小者），但改 max→min 会破坏 cut-in 场景的防追尾逻辑——一个函数服务两种语义冲突的场景。

方案 A 撤回：撤回必须留痕

既然 YIELD_CASES 这条路走不通，方案 A 撤回。但视频强调：撤回这件事必须留痕，写成一条 regression 测试：

def test_static_cross_not_in_yield_cases():
    """守护：static_cross 不能加进 YIELD_CASES。
    
    历史教训：曾把 static_cross 加进 YIELD_CASES 期望 proximity_yield 帮减速，
    但 proximity_yield 用 max(2.0, 0.35*d) 保证最低速度 7.2 km/h，
    覆盖了模型想停到 1.9 km/h 的意图，反而导致近撞。
    static_cross 需要完全停车，和 YIELD 的防卡死语义冲突。
    正确修法见 B11：降巡航速度 + 改 warmup throttle。
    """
    assert 'static_cross' not in YIELD_CASES, \
        "static_cross 不应进 YIELD_CASES（见历史回归）"

这条测试的意义：

1. 防止 future me 重蹈覆辙——几个月后可能忘了为什么，又想试 YIELD。
2. 记录根因——docstring 解释了 max/min 的语义陷阱。
3. 指引正确方向——明确指向 B11 的真修法。

通用启示：复用逻辑要检查语义兼容

这个失败的普遍教训：

• 一个工具函数服务多个场景时，要检查每个场景的语义需求是否一致。
• proximity_yield 对 cut-in（需要蠕行）和 static_cross（需要停车）的语义是冲突的——同一个 max 操作对前者合理、对后者有害。
• 盲目复用（“既然 cut-in 用了 yield，static_cross 也加上”）会引入这种语义错位。
• 遇到语义冲突，不要硬改共享函数（会影响其他场景），要么分开实现，要么换思路（B11 的降速方案绕开了 yield）。

参考

• CARLA — Vehicle control 与速度控制
• Regression Testing（维基百科）

T2 真修法 B + C：双管齐下

为什么单一修法不够

T2 的最终修法是 B 和 C 叠加，两个改动缺一不可。理解为什么需要两个，要回到运动学根因（B09）：

$d_{\text{stop}} = \frac{v^2}{2a} \le d_{\text{avail}} = 6\ \text{m} \implies v \le 25\ \text{km/h}$

要让 Ego 在 6 m 内停下，起跑速度必须 ≤ 25 km/h。问题分两步：配置里写的目标速度和实际达到的速度——这两个不是一回事。

修法 B：降低巡航速度

# static_cross 场景的巡航速度
CRUISE_SPEED = {
    # 'static_cross': 36,   # 旧值，物理上停不下来
    'static_cross': 22,      # 新值，配得上 6m 可用距离
}

把 static_cross 的巡航速度从 36 降到 22 km/h。22 km/h 下的最小停车距离：

$d_{\text{stop}} = \frac{(22/3.6)^2}{2 \times 4} = \frac{6.11^2}{8} = \frac{37.3}{8} \approx 4.67\ \text{m}$

4.67 m < 6 m，物理上能停下，留出 1.33 m 余量。

为什么单 B 不够：warmup 越速

只改 B（巡航速度配置）不够，因为 warmup 阶段会越速。warmup 是场景启动前的加速段，它的实现：

def warmup(ego, cruise_speed):
    """场景启动前加速到巡航速度。"""
    while ego.speed < cruise_speed:
        ego.apply_control(carla.VehicleControl(throttle=0.7))  # 持续给油 0.7
        world.tick()

问题在 throttle=0.7 是持续给油，没有反馈控制：

• 速度达到 22 km/h 那一帧，throttle 还是 0.7。
• 车有惯性，throttle 0.7 会让车冲过巡航速度。
• 实测越速 +13 km/h——配置 22 km/h，实际跑到 35 km/h。

35 km/h 接近原来的 36 km/h，B 的调整基本失效。这就是为什么需要 C。

修法 C：warmup throttle 反馈控制

def warmup(ego, cruise_speed):
    """场景启动前加速到巡航速度（带反馈）。"""
    while True:
        current = ego.speed
        if current >= cruise_speed:
            break                    # 到了就停加速
        ego.apply_control(carla.VehicleControl(throttle=0.7))
        world.tick()
    # 速度到了巡航就停止加速，不让 warmup 把车推过头

C 的核心：速度达到巡航就停止加速，加一个 break 条件。这样车不会冲过巡航速度，warmup 结束时实际速度 ≈ 配置的 22 km/h。

B + C 叠加的效果

两个修法叠加：

项	修前	修后
巡航速度配置	36 km/h	22 km/h
warmup 实际速度	~49 km/h（36 + 越速 13）	~22 km/h
最小停车距离	~12.5+ m	4.67 m
可用距离	6 m	6 m
最近距离（实测）	1.93 m（近撞）	3.88 m

安全余量翻倍：从 1.93 m（几乎擦撞）到 3.88 m（从容停下）。注意 3.88 m 比物理极限 4.67 m 还要好——因为模型从看到障碍就提前减速，比”全力刹车从第一帧”更优。

为什么不能只靠 C

反过来，只改 C（warmup 反馈）不改 B（巡航配置）也不行：

• B 不改：巡航还是 36 km/h。
• C 改了：warmup 准确停在 36 km/h（不越速）。
• 但 36 km/h 的最小停车距离 12.5 m > 6 m 可用距离——物理上还是停不下。

所以 B 和 C 都必须改：

• B 把目标速度降到物理可行范围（≤25 km/h）。
• C 保证实际速度真的达到目标（不越速）。

两者解决的是不同环节的问题：B 解决”目标值不对”，C 解决”实际值偏离目标”。

单元测试守护

这个修法也写成测试，防止回退：

def test_static_cross_cruise_speed():
    assert SCENARIO_CONFIG['static_cross'].cruise_speed <= 25, \
        "static_cross 巡航速度必须 ≤25 km/h（6m 可用距离的物理上限）"

def test_warmup_has_speed_break():
    """warmup 必须有速度达成的 break，否则越速。"""
    assert 'break' in inspect.getsource(warmup), \
        "warmup 缺少速度达成 break（历史越速 +13 km/h）"

这两条测试把”物理约束”和”实现细节”都固化下来。

通用启示：根因要拆到每一层

T2 的修法过程展示了调试的层次：

1. 现象：1.93 m 近撞。
2. 根因层 1：起跑速度太快（36 km/h）。
3. 根因层 2：为什么快？配置 36 + warmup 越速 13。
4. 修法对应：B 改配置，C 改 warmup。

每一层根因对应一个修法。只修一层（只 B 或只 C）都不够，因为另一层的问题还在。这种”拆到每一层”的调试思路，是工程实战的核心能力。

参考

• 制动距离（Braking distance）
• PID 控制与反馈系统
• CARLA — Vehicle control

CI smoke + 文档同步：自动化兜底

四步端到端 smoke 流水线

Stream B 搭建了一条 43 秒 就能跑完的端到端 smoke 流水线，验证整条工程链没坏：

步骤	耗时	验证什么
① 单元测试	17 s	业务逻辑（如 proximity_yield 的 max/min、static_cross 速度上限）
② CARLA 启动	0 s	容器复用，不重新拉起
③ dummy 闭环	26 s	跑一个最简 tick 循环，验证管道连通
④ verify_batch L1 检查	0 s	L1 静态检查（配置完整性）
总计	43 s

任何人 push 代码前，一行命令就能跑完——这是把”测试自觉”变成”测试便宜”的工程。

为什么 CARLA 启动是 0 秒：容器复用

CARLA Server（UE 进程）冷启动要 30–60 秒（加载资产、初始化物理）。如果每次 smoke 都重启 CARLA，43 秒里一半是等启动。

解法是容器复用：

• CARLA 跑在一个常驻容器里，smoke 不重启它。
• smoke 只连接到已运行的 CARLA（localhost:2000）。
• 每次 smoke 跑完重置 world 状态，不杀进程。

代价是容器要长期占内存（CARLA idle 也要几 GB），但对开发体验的提升（43s vs 90s+）值得。

dummy 闭环：最小但完整

dummy 闭环不是真跑 SparseDriveV2（那要几十秒一帧），而是跑一个最简代理：

def dummy_agent(images):
    """最简代理：固定直行，验证管道连通。"""
    return carla.VehicleControl(throttle=0.3, steer=0.0)

它验证的是整条数据管道没断：

• world.tick() 能推进。
• 6 相机能采集。
• 队列能对齐。
• apply_control 能执行。
• 违规检测能跑。

如果 dummy 闭环挂了，说明是管道问题（不是模型问题）——这把”工程管道 bug”和”模型 bug”分离，让 smoke 能快速定位工程回归。

单元测试为什么占 17 秒（大头）

17 秒里跑的是业务逻辑测试，包括：

• proximity_yield 的边界值（max/min 语义）。
• static_cross 巡航速度上限。
• cut_in_left 不在 override 列表（B06）。
• static_cross 不在 YIELD_CASES（B10）。
• 各种参数的合理范围。

这些测试不需要 CARLA（纯 Python 逻辑），所以快。它们守护的是”那些反直觉决策”——每次代码改动后，这些测试确保历史教训不会被违反。

L1 / L2 检查的分层

verify_batch 的检查分两级：

• L1（静态检查）：不跑 CARLA，只看配置文件、日志格式、产物完整性。0 秒。
• L2（动态检查）：跑完整闭环，看 NPC 行为、违规记录。慢，不在 smoke 里跑。

smoke 只跑 L1——快速验证”工程管道没明显断裂”。L2 留给完整评测（一夜跑完 220 条）。这种分层让 smoke 能在 push 前跑，完整评测定期跑。

文档同步：和代码解耦

Stream B 还做文档同步，关键是和 Stream A（代码改动）完全解耦：

• README 状态行：更新 epic_v2 → epic_v3 的状态。
• plan 文档：加章节记录这次修复。
• report：追加 epic_v3 段。
• 基线归档、产物忽略（.gitignore）。

这些是纯文本改动，不依赖 CARLA，不和 Stream A 的代码改动冲突。两条流并发，互不阻塞。

易错点

• smoke 不能替代完整评测：dummy 闭环只验证管道，不验证模型行为。模型回归要靠 L2 完整评测发现。
• 容器复用有状态泄漏风险：上一次跑残留的 Actor 要清理干净，否则污染下一次。
• 单元测试要快：17 秒是上限，超过 30 秒开发者就会跳过不跑。

参考

• 持续集成 / Continuous Integration
• Smoke Testing（冒烟测试）
• Test Pyramid（测试金字塔）