从零搭建自动驾驶中间件（四）：数据录制与回灌——算法调试的核心基础设施

这是系列第四篇。前三篇聊了通信和调度，这篇聊一个让算法工程师"离不开"的功能------数据录制与回灌。如果说通信是中间件的骨架，调度是心脏，那回灌就是灵魂。

1. 为什么回灌是"灵魂级"功能？

1.1 一个真实的场景

某个周五晚上 9 点，测试同学发来一段视频：自动驾驶车在 T 字路口左转时，突然向右偏了一下。

你打开日志，看到了这些：

[21:03:42.156] perception: detected 3 objects
[21:03:42.158] prediction: object[0] trajectory: straight
[21:03:42.161] planning: lateral offset = -0.3m   ← 异常！
[21:03:42.165] control: steering_angle = -2.1deg

lateral offset = -0.3m 是异常值，但为什么？是感知漏检了一个障碍物？是预测的轨迹有误？还是规划算法的边界条件没处理好？

没有当时的传感器原始数据，你永远无法定位根因。

1.2 数据回灌解决什么问题

场景	没有回灌	有回灌
复现 bug	只能靠日志猜，或等下一次出现	100% 精确复现当时的输入序列
算法调参	每次调参都要跑实车	离线反复回灌，几秒就能验证
回归测试	无法保证新版本不退化	同一批数据反复跑，自动对比输出
边界测试	难以遇到急刹、颠簸等场景	专门录制边界数据，反复测试
团队协作	算法工程师必须等实车数据	录制数据共享，人人可离线开发

一句话：没有回灌，算法调试只能靠"撞运气"；有了回灌，调试效率提升 10 倍。

---

2. 回灌的核心挑战

数据回灌听起来简单------把录制的数据重新写回系统不就行了？但工程实现中有三个核心挑战：

2.1 挑战一：时序控制

录制时，模块的执行顺序是这样的：

Step 1: Read(lidar, fid=1) → Process → Write(result, fid=1) → Notify
Step 2: Read(lidar, fid=2) → Process → Write(result, fid=2) → Notify
Step 3: Read(lidar, fid=3) → Process → Write(result, fid=3) → Notify

回灌时，我们必须按完全相同的时序回写数据：

回灌 Step 1: Write(lidar, fid=1) → Notify → 下游模块执行 Step 1
回灌 Step 2: Write(lidar, fid=2) → Notify → 下游模块执行 Step 2
回灌 Step 3: Write(lidar, fid=3) → Notify → 下游模块执行 Step 3

如果回灌顺序错了，下游模块可能读到错误帧的数据，导致算法输出与录制时不一致。

2.2 挑战二：时间源切换

算法模块经常使用时间戳：

void Step() override {
    auto now = GetTimestamp();  // 当前时间
    double dt = now - last_time_;
    last_time_ = now;
    // 用 dt 计算速度、积分等
}

回灌时，如果 GetTimestamp() 仍然返回当前实时时间，dt 会是回灌间隔（比如 100ms），而不是录制时的实际间隔（可能是 98ms 或 103ms）。这个微小差异可能导致算法输出与录制时不同，回灌就失去了"精确复现"的意义。

2.3 挑战三：对业务代码零侵入

最差的方案是让算法工程师在代码里写 if (fillback_mode) { ... } else { ... }。这会：

• 增加代码复杂度
• 容易引入 bug
• 让人不想用回灌功能

好的回灌机制应该对业务代码完全透明。

---

3. HyperFlow 的回灌架构

3.1 整体方案

HyperFlow 采用快照驱动回灌方案，核心思路是：

用录制好的 Snapshot 数据作为"节拍器"，按原始时序逐步回写数据并触发下游模块。

录制阶段                              回灌阶段
                                      
Module (enable_snapshot=true)         FillbackModule
  │                                     │
  ├── Step()                            ├── Step()
  │   ├── Read("sensor")                │   ├── 读取 Snapshot
  │   │   └─ 记录: INPUT, "sensor", fid=1   │   ├── 根据 INPUT 记录
  │   ├── 业务处理                       │   │   查找 fid=1 的数据
  │   └── Write("result")               │   ├── Write("sensor", data)
  │       └─ 记录: OUTPUT, "result", fid=1  │   ├── Write("sys.timesync", timestamp)
  │                                     │   └── NotifyAll()
  └── write_snapshot()                  │
      └── Write("sys.snapshot", data)   │
                                      Module (fillback=true)
RecordModule                            │
  └── Step()                            ├── Step()
      ├── Get("sensor") → MCAP          │   ├── Read("sensor") ← 回灌数据
      └── Get("sys.snapshot") → MCAP    │   ├── GetTimestamp() ← 录制时间
                                        │   └── 业务处理（代码不变！）

3.2 为什么选快照驱动而不是原始数据直接回灌？

方案	原理	问题
原始数据直接回灌	只录制传感器数据，回灌时按时间戳写入	不知道下游模块何时读取数据，无法保证执行节奏一致
快照驱动回灌	录制时同时记录模块的读写快照，回灌时按快照驱动	数据量略大，需要快照机制

打个比方：原始数据回灌就像给你一本乐谱（原始数据），让你自己决定演奏节奏；快照驱动回灌则像给你一份带节拍标记的乐谱，每个音符何时演奏都标注清楚了。

---

4. DataSnapshot：回灌的基础设施

4.1 快照数据结构

// 单次读写记录
struct RWSnapshotData {
    RwMode mode;           // INPUT / OUTPUT / INPUT_ERROR / OUTPUT_ERROR
    char name[35];         // 数据名称
    uint32_t frameid;      // 数据帧号 ← 关键！回灌时的匹配依据
};

// 模块级别的快照
struct ModuleSnapshotData {
    char module_name[32];  // 模块名
    uint64_t begin_time;   // Step 开始时间 (us)
    uint64_t end_time;     // Step 结束时间 (us)
    uint32_t step;         // Step 序号
    uint8_t num_snapshots; // 读写次数（最多 16 次）
    RWSnapshotData snapshots[16];
};

4.2 快照记录流程

快照记录对业务代码完全透明，框架在内部自动完成：

// ModuleImpl 内部
void run_step() {
    snapshot_.Begin(begin_timestamp, tick_count);  // 重置快照

    // 用户代码 ------ 完全不知道快照的存在
    module_->Step();

    snapshot_.End(end_timestamp);  // 记录结束时间
    write_snapshot();              // 写入 "sys.snapshot" 数据队列
}

// Write 操作被拦截
std::error_code Write(const std::string &name, const void *data, uint32_t size) {
    auto ec = data_queue->Write(data, size, frameid);
    if (enable_snapshot_) {
        snapshot_.AddSnapshot(name, frameid,
            ec ? RwMode::OUTPUT_ERROR : RwMode::OUTPUT);  // 记录输出
    }
    return ec;
}

// Read 操作被拦截
std::error_code Read(const std::string &name, ...) {
    auto ec = data_queue->Read(..., frameid);
    if (enable_snapshot_) {
        snapshot_.AddSnapshot(name, frameid,
            ec ? RwMode::INPUT_ERROR : RwMode::INPUT);   // 记录输入
    }
    return ec;
}

关键设计：

• 快照记录在 Write/Read 的内部拦截，用户代码无感知
• 只需配置 "enable_snapshot": true 即可开启
• frameid 是数据帧号，回灌时的精确匹配依据
• 最多记录 16 次操作（对绝大多数模块够用）

4.3 一个快照的实际内容

假设感知模块的一个 Step 执行了：

void Step() override {
    const PointCloud* cloud = nullptr;
    Get("lidar_points", cloud);       // Read → 快照: INPUT, "lidar_points", fid=42

    const CameraFrame* frame = nullptr;
    Get("camera_front", frame);       // Read → 快照: INPUT, "camera_front", fid=38

    DetectionResult result = Detect(cloud, frame);

    Write("detection_result", result);  // Write → 快照: OUTPUT, "detection_result", fid=1
    Notify("detection_ready");
}

对应的 ModuleSnapshotData：

module_name: "perception"
begin_time:  1700000000123456 (us)
end_time:    1700000000156789 (us)
step:        42
num_snapshots: 3

snapshots[0]: INPUT,    "lidar_points",     fid=42
snapshots[1]: INPUT,    "camera_front",     fid=38
snapshots[2]: OUTPUT,   "detection_result", fid=1

---

5. RecordModule：数据录制

5.1 MCAP 文件格式

HyperFlow 选择 MCAP 作为录制格式。MCAP 是一种高效的容器格式，源自 ROS2 生态：

• 支持 LZ4 压缩
• Channel 机制天然对应 DataQueue
• 消息序列号天然对应 frameid
• 支持索引，可按时间范围读取

5.2 录制实现

RecordModule::Step() {
    // 文件轮转
    if (writer_->file_size() >= file_roll_size_bytes_) {
        rotate_file();
    }

    // 逐个读取 input 数据并写入 MCAP
    for (auto& input : inputs_) {
        for (size_t i = 0; i < kMaxFrameCount; i++) {
            void *data = nullptr;
            uint32_t size;
            auto ec = Get(input, &data, size, ReadMode::READ_NEXT);
            if (ec) break;

            mcap::Message msg;
            msg.channelId = get_channel_id(input);
            msg.data = data;
            msg.dataSize = size;
            msg.logTime = utils::GetTimestampUs();
            msg.sequence = GetLastFrameId();  // frameid → sequence
            writer_->write(msg);
        }
    }
}

5.3 文件轮转策略

record.mcap          ← 当前写入文件
record.1.mcap        ← 上一轮
record.2.mcap        ← 更早
...
record.{N}.mcap      ← 最早（超过 max_file_count 则删除）

• file_roll_size：单文件大小上限（默认 10MB）
• max_file_count：最大文件数（默认 8）

5.4 配置示例

{
    "name": "recorder",
    "type": "sys.RecordModule",
    "interval": 20,
    "input": [
        "lidar_points",
        "camera_front",
        "sys.snapshot",
        "sys.diag"
    ],
    "file_path": "./data/record.mcap",
    "file_roll_size": 10,
    "max_file_count": 8
}

---

6. FillbackModule：离线回灌

6.1 核心回灌流程

FillbackModule::Step() {
    // 1. 按时间顺序遍历 MCAP 消息
    while (iterator != messages.end()) {
        auto& message = *iterator++;

        if (channel->topic == "sys.snapshot") {
            // 2. Snapshot → "节拍器"
            auto snapshot = (ModuleSnapshotData*)message.data;
            if (module_name_ != snapshot->module_name) continue;

            // 3. 根据 Snapshot 中的 INPUT 记录回写数据
            write_data(*snapshot);

            // 4. 通知所有 Trigger，唤醒下游模块
            NotifyAll();

            break;  // 每个 Step 只处理一条 Snapshot
        } else {
            // 5. 非 Snapshot 消息 → 缓存到帧队列
            FillbackFrame frame;
            frame.frameid = message.sequence;
            frame.data = Slice(message.data, message.dataSize);
            frame_queue_map_[channel->topic]->push_back(frame);
        }
    }
}

6.2 数据回写逻辑

FillbackModule::write_data(const ModuleSnapshotData &snapshot) {
    // 1. 写入时间同步数据
    TimesyncData timesync;
    timesync.timestamp = snapshot.begin_time;  // 录制时的时间戳
    Write("sys.timesync", timesync);

    // 2. 遍历 Snapshot 中的 INPUT 记录
    for (int i = 0; i < snapshot.num_snapshots; ++i) {
        if (snapshot.snapshots[i].mode != RwMode::INPUT) continue;

        string name = snapshot.snapshots[i].name;
        uint32_t frameid = snapshot.snapshots[i].frameid;

        // 3. 在帧队列中查找匹配的数据
        auto queue = get_frame_queue(name);
        for (auto& frame : *queue) {
            if (frame.frameid == frameid) {
                Write(name, frame.data.GetData(), frame.data.GetLength());
                break;
            }
        }
    }
}

6.3 frameid 匹配机制

这是回灌精确性的关键。

录制时：
  Module Read("lidar_points") → frameid=42 → Snapshot: INPUT, "lidar_points", fid=42
  MCAP: lidar_points message, sequence=42

回灌时：
  MCAP 消息到达：lidar_points (seq=42) → 缓存到 frame_queue["lidar_points"]
  MCAP 消息到达：Snapshot (INPUT, "lidar_points", fid=42)
  → 在 frame_queue 中查找 fid=42 → 找到！→ Write 回共享内存

为什么不用时间戳匹配？

时间戳可能有微秒级误差，且同一时间戳可能有多条数据。frameid 是 DataQueue 单调递增的序号，精确且唯一。

6.4 帧队列缓存

MCAP 中的消息按时间交错到达，需要先缓存原始数据，等 Snapshot 到达后再按 frameid 匹配回写：

MCAP 消息流（按时间交错）：
  lidar_points (fid=1)     → 缓存
  camera_front (fid=1)     → 缓存
  sys.snapshot (step=1)    → 触发回写: lidar fid=1 + camera fid=1
  lidar_points (fid=2)     → 缓存
  sys.snapshot (step=2)    → 触发回写: lidar fid=2
  ...

struct FillbackFrame {
    uint32_t frameid;
    Slice data;
};

// 每个数据名对应一个帧队列
unordered_map<string, shared_ptr<deque<FillbackFrame>>> frame_queue_map_;

// 队列最大长度 32，超出时丢弃最早的帧

---

7. 时间源透明切换

7.1 问题

算法模块中经常使用时间戳：

void Step() override {
    auto now = GetTimestamp();
    double dt = (now - last_time_) / 1e6;
    last_time_ = now;

    // 用 dt 做积分、计算速度等
    velocity_ = (current_pos_ - last_pos_) / dt;
}

如果回灌时 GetTimestamp() 返回实时时钟，dt 就是回灌间隔而不是录制时的实际间隔。

7.2 解法

Module::GetTimestamp() {
    if (impl_->GetFillback()) {
        // 回灌模式：从共享内存读取录制时间
        TimesyncData timesync;
        Read<TimesyncData>("sys.timesync", timesync, READ_LATEST);
        return timesync.timestamp;
    } else {
        // 正常模式：系统实时时钟
        return utils::GetTimestampUs();
    }
}

业务代码完全不变 ，GetTimestamp() 在回灌模式下自动返回录制时间。

7.3 时间切换的完整流程

录制时：
  Module Step → begin_time = 1700000000123456 (us)
              → end_time   = 1700000000156789 (us)
  Snapshot 写入 MCAP

回灌时：
  FillbackModule → Write("sys.timesync", { timestamp: 1700000000123456 })
  Module Step → GetTimestamp()
              → Read("sys.timesync") → 1700000000123456   ← 录制时间！
              → dt = (1700000000123456 - last_time_) / 1e6
              → 与录制时完全一致

---

8. 被回灌模块的配置

只需在原模块配置中添加两个字段：

{
    "name": "perception",
    "type": "PerceptionModule",
    "fillback": true,                    // ← 启用回灌模式
    "listen": "fillback.data_ready",     // ← 由 FillbackModule 触发
    "input": ["lidar_points", "camera_front"]
}

fillback: true 的效果：

1. GetTimestamp() 返回录制时间而非实时时钟
2. 运行时可通过 Terminal 查看回灌状态

---

9. 在线回灌：XTestingModule

除了离线 MCAP 回灌，HyperFlow 还支持通过 XTesting 可视化平台在线回灌。

9.1 两种回灌方式对比

特性	FillbackModule	XTestingModule
数据来源	本地 MCAP 文件	XTesting 平台（WebSocket）
回灌触发	定时 Step 主动读取	回调被动接收
可视化	无	数据可视化 + 实时调参
适用场景	离线批量回归测试	在线调试、可视化分析

9.2 什么时候用哪种？

• 算法调试：XTestingModule（可视化、可交互）
• 回归测试：FillbackModule（自动化、可批量）
• 性能分析：FillbackModule（稳定、可重复）

---

10. 完整工作流示例

10.1 录制

// 配置：开启快照 + 添加录制模块
{
    "modules": [
        {
            "name": "perception",
            "type": "PerceptionModule",
            "enable_snapshot": true,    // ← 开启快照
            "interval": 100,
            "input": ["lidar_points"],
            "output": ["detection_result"],
            "notify": ["detection_ready"]
        },
        {
            "name": "recorder",
            "type": "sys.RecordModule",
            "interval": 20,
            "input": ["lidar_points", "sys.snapshot"],
            "file_path": "./data/record.mcap"
        }
    ]
}

运行进程，录制数据自动写入 record.mcap。

10.2 离线回灌

{
    "modules": [
        {
            "name": "perception",
            "type": "PerceptionModule",
            "fillback": true,           // ← 回灌模式
            "listen": "fillback.ready",
            "input": ["lidar_points"],
            "output": ["detection_result"]
        },
        {
            "name": "fillback",
            "type": "sys.FillbackModule",
            "interval": 100,
            "file_path": "./data/record.mcap",
            "module_name": "perception",
            "notify": ["fillback.ready"],
            "output": ["lidar_points", "sys.timesync"]
        }
    ]
}

运行回灌进程，感知模块将按录制时的输入序列重新执行。

---

11. 踩坑总结

1. 快照最多 16 条 ：单次 Step 超过 16 次 Read/Write 会溢出，需要调大 kMaxSnapshots
2. frameid 必须一致 ：MCAP 的 sequence 必须用写入时的 frameid，否则回灌匹配失败
3. 子状态机与回灌：回灌只还原数据输入，不还原状态机状态------状态机需要独立处理初始状态
4. 共享内存大小 ：回灌配置的 data_size 和 data_count 必须与录制时一致
5. 帧队列溢出：如果 MCAP 中某条数据连续很多帧才被 Snapshot 引用，帧队列可能溢出（默认 32 帧）
6. 时间同步精度 ：TimesyncData 的时间戳精度为微秒，对于毫秒级算法足够，但对于需要纳秒精度的控制算法可能不够

---

12. 与 CyberRT / ROS2 录制回灌的对比

维度	HyperFlow	CyberRT	ROS2
录制格式	MCAP	cyber_recorder 自有格式	rosbag2 (MCAP/SQLite)
回灌机制	Snapshot 驱动	原始数据回灌	原始数据回灌
时序保证	Snapshot 节拍器 + frameid 匹配	按时间戳回写	按时间戳回写
时间源切换	自动（fillback: true）	手动	手动
零侵入	是	部分需要修改代码	部分需要修改代码
在线回灌	XTestingModule	cyber_visualizer	rviz2 playback
可视化平台	XTesting	cyber_visualizer	rviz2

HyperFlow 的核心差异：Snapshot 驱动 + 时间源透明切换，实现了真正的"零侵入"回灌。

---

13. 小结

数据录制与回灌是自动驾驶算法调试的核心基础设施。HyperFlow 的设计通过三个关键机制解决了回灌的三大挑战：

1. Snapshot 节拍器 → 解决时序控制
2. frameid 精确匹配 → 解决数据一致性
3. fillback 时间源切换 → 解决时间源问题，对业务代码零侵入

这套机制让算法工程师可以"像看电影一样回放"自动驾驶系统的运行过程，极大提升了调试效率。

下一篇，我们将聊状态机、诊断与运维------让自动驾驶系统"可观测、可控制"。

---

下期预告：《从零搭建自动驾驶中间件（五）：状态机、诊断与运维------让系统可观测可控制》