Serial Studio 回放时间线重构实战磁带式 Scrubbing 与无损追赶Spec 0020【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio导读Serial Studio 是开源遥测数据面板支持 UART、BLE、MQTT、Modbus、CAN Bus 等多种数据源。当录制文件规模达到“现场项目级”字段项目 88 个分组、571 个数据集、每条 CAN 消息一行记录时旧版回放暴露出两个致命问题拖动时间轴会丢弃全部绘图数据并同步重建整个窗口单次拖动导致 UI 冻结数秒录制帧率超过回放处理能力时追赶循环永远落后回放变成永久慢放。本指南以doc/claude/specs/0020-replay-timeline/三份规格文档spec / plan / tasks为核心结合仓库源码与集成测试完整讲解 Serial Studio 2026 年回放时间线重构Spec 0020的动机、需求、架构设计与逐任务落地细节读者可据此理解磁带式 scrubbing与无损追赶在真实遥测面板中的实现方案。一、重构动机现场项目规模下的两大回放痛点Spec 0020 的出发点来自一次真实压测2026-07-18字段项目文件88 组、571 数据集、每条 CAN 消息一行记录从 CSV 或 MDF4 回放暴露出两类系统性问题Scrubbing 不可用早期版本允许用户拖动时间轴并观看曲线在光标下“播放”这是视觉定位事件、跳转到目标时刻的主要手段。但当时每次滑块移动都会丢弃全部绘图数据再通过通用解析管线同步重建整个绘图窗口——在字段项目规模上一个 tick 就要付出数百次完整管线帧注入的代价UI 冻结数秒实时 scrub 体验完全消失。回放无法跟上节奏当录制帧率超过回放管线处理能力时追赶catch-up循环以固定批量回放每一行中间数据且永远落后——录制永远以慢动作播放。Session 回放感觉稍好只是因为其帧计数折叠了同毫秒突发而非管线更快。维护者的定调2026-07-19scrubbing 必须像磁带一样——两个方向都快曲线始终反映光标位置向后 scrub 时点可见地回退追赶必须快到无损跳过录制数据不可接受。完整需求定义见 spec.md。二、需求矩阵R1–R6 与验收标准 AC1–AC5Spec 0020 将目标形式化为六条可验证需求编号需求核心语义R1位置精度磁带语义时间轴停在位置 P 时每个曲线精确显示以 P 结尾的尾随窗口内录制样本向后 scrub 无 P 之后残留样本窗口之前无空洞与到达 P 的方式无关R2实时 scrub 反馈字段项目规模下拖动时曲线每秒多次可见更新UI 绝不硬冻结仪表、条图、LED 等非曲线控件跟踪光标当前帧R3节拍化回放回放 N 秒墙钟时间后时间轴位置与 N 秒录制时间偏差在固定小容差内无无界漂移R4无损性完整回放过程中每条录制行恰好被处理并交付仪表盘一次——不跳过、不重复即使瞬时停滞触发追赶R5播放器对齐R1–R4 对 CSV、MDF4、Session 回放商业构建完全一致R6回放绝不重新录制scrubbing 与回放不得追加到任何导出汇CSV/MDF4/session/MQTT 发布——“倒带磁带不得制造新录音”对应五条验收标准AC1API 驱动回放 seek 后dashboard.tailFrames与全新打开直跳基准一致覆盖 CSVMDF4session 变体在商业构建上跑同一脚本AC2维护者现场观察双向拖动实时更新、无多秒冻结、可仅靠 scrub 定位事件AC3恒定速率宽 CSV 回放时间戳在容差内跟随墙钟 交付帧数等于录制行数即无损节奏联合断言AC4--benchmark-hotpath全部门控 tier 仍通过活动解析路径不得为回放让路而回退AC5CSV 导出开启时回放scrub导出文件不增长、不产生 session 行。约束与不变量还包括活动设备热路径保持其吞吐门256 kHz 参考、全部九个 benchmark tier录制值是最终值回放绝不重跑数据集变换CSV 回放保持 GPL、MDF4/session 回放保持商业门控单次拖动无 UI 停顿超过约 50 ms永久低配机器上回放拉伸时间无损而非跳行。全部细节见 spec.md。三、总体方案两条协作通道替换“一刀切注入”plan.md 给出的核心设计是两条协作通道回放注入快通道lane 1FrameBuilder新增回放入口直接接收播放器已切分好的通道行QStringList 录制时间戳消除“join 成字节 → 重新拆分”的往返发布到仪表盘与只读 API 观察者但绝不发布到录制汇CSV/MDF4/Sessions 导出、MQTT 发布从构造上满足 R6。节拍回放与追赶走此通道采用时间预算批量循环每次事件循环约 20 ms替代固定 100 行批量使重负载录制无损保持节奏且 GUI 保持响应。批量 seek 通道lane 2拖拽 scrub拖动滑块时合并到约 30 HzDashboard仅批量装载绘图环——直接从播放器现有内存存储中按需数值解析窗口行仅 plot-enabled 数据集字段项目规模下每 tick 约毫秒级另加一次快通道注入光标帧供标量控件使用随后一个防抖约 250 ms静止通道通过 lane 1 重放完整尾随窗口使 FFT/waterfall/GPS/3D 在静止位置精确对应 spec 的 Q3 决议。向后与向前 scrub 是同一操作重建以光标结尾的窗口因此磁带语义由构造保证。选择该方案的原因详见 plan.md 的 Tradeoffs 表放弃“仅预算化管线”字段项目规模下错过 50 ms 拖拽预算与“预计算数值矩阵”10M 行时内存达 GB 级违反内存约束回放发布目标选择“仪表盘 只读观察者、无录制器/MQTT”而非“全扇出 每汇门控”避免把门控摊到五个汇上引发静默重录回归。四、源码落地FrameBuilder 回放入口与发布目标策略设计落到 FrameBuilder.h 中的三个回放入口void replayChannels(int sourceId, const QStringList channels, const DataModel::TimestampedFrame::SteadyTimePoint timestamp); void replayChannelSpans(int sourceId, const QByteArrayView* cells, qsizetype count, const DataModel::TimestampedFrame::SteadyTimePoint timestamp); void replayChannelsTyped(int sourceId, const ReplayCell* cells, qsizetype count, const DataModel::TimestampedFrame::SteadyTimePoint timestamp);FrameBuilder.cpp 中replayChannels的实现体现了任务 T1 的全部不变量线程归属非 builder 线程调用时通过Qt::BlockingQueuedConnection派发回 builder 线程热路径断言SS_ASSERT_HOTPATH(m_playerOpen)断言播放器打开复用现有状态而非重新推导、m_operationMode SerialStudio::ProjectFile复用现有列映射通过applyDatasetValues(srcFrame, channels, info)应用已有的 replay 列映射变换保持门控关闭录制值是最终值发布走槽池publishReplayValues(sourceId, srcFrame, timestamp)复用acquireFrame的槽池机制structureGeneration与活动站点完全一致地盖章时间戳所有权录制时间戳由播放器在入口边界盖章Dashboard/观察者绝不重新盖章——这同时修复了旧版对回放帧的墙钟盖章问题无新信号跳变直接函数调用无新增信号无新增缓存标志输入。注释明确写道本入口发布到 “Dashboard and read-only API observers only; recording sinks never see replayed frames, so a replay can never re-record itself”即 R6 从构造上成立。replayChannelSpansUTF-8 视图单元直接来自 CSV 播放器的内存映射行零中间 QString 列表与replayChannelsTypedMDF4 播放器列式缓存的本地 double 借用文本指针是 spec 0022 的补充通道走同一槽池回放扇出。底层逐数据集发布由 ReplayIngest.cpp 完成columnsFor(sourceId)返回按源的 uid→列映射——plan.md 风险章节强调 uniqueIds 跨源并不唯一所有 uid→列映射必须保持按源m_replayColumnMap已然如此批量填充 provider 镜像之。五、CSV 播放器磁带式 scrub 的三段式实现CSV/Player.h 的setProgress/performSeekTick/performSeekSettle私有槽与 CSV/Player.cpp 的实现一起完整对应任务 T2 与 T6。setProgress记录目标非同步注入钳制进度到 [0,1]若正在播放先暂停计算newFramePos后更新帧位置与时间戳显示调用m_engine.armSeek()触发合并定时器。注释点明位置与时间戳立即更新合并定时器以约 30 Hz 实时填充曲线静止定时器在滑块停下后运行精确全窗口重建——setProgress 不再在每个滑块 tick 上做同步窗口注入T6 的 read-back 验证点。performSeekTick合并 tick批量填充 光标注入若m_seekColumnByKey为空则直接走 settle避免空序列映射的批量填充抹掉全部曲线导致整个拖拽期间空白这是 qt-cpp-review 修复项之一否则由seekWindowStartRow从光标向前回走确定尾随窗口起点覆盖 plot time range不少于points()行由引擎封顶以约束密集录制每 tick 成本buildSeekWindow从内存映射行直接填充每行一次 split、每单元 fast_float无 QString调用dashboard.bulkLoadPlotWindow(times, series)再anchorSteadyBase(target)injectRow(target)注入光标行供标量控件跟踪。performSeekSettle静止重建精确全窗口clearPlotData()后通过processFrameBatch(start, m_framePos)在快速通道重放完整尾随窗口使 FFT/waterfall/GPS/3D 等帧馈送控件精确backfillSparseSources()回填稀疏源随后若存在 seek 列映射再做一次全时间窗口批量填充让曲线保持完整磁带视图而非坍缩到管线批量。时间预算化追赶T2 的核心替换在 Player.cpp 的updateData中固定kMaxBatchSize 100被替换为约 20 ms 墙钟预算 单次最多 512 次注入的静态上限qt-cpp-review 修复项静态迭代上限与追赶时间预算并存constexpr qint64 kCatchUpBudgetMs 20; constexpr int kCatchUpMaxInjects 512; const QDeadlineTimer budget(kCatchUpBudgetMs); ... for (int processed 0; processed kCatchUpMaxInjects m_framePos targetRow !budget.hasExpired(); processed) { m_framePos qMin(targetRow, m_framePos stride); injectRow(m_framePos); }时间预算随项目宽度与机器速度自适应快机器一 pass 处理更多行慢机器“拉伸时间”天然发生spec Q2跳过仍被禁止事件循环通过现有单发定时器让出控制权GUI 保持响应。reanchorOnBackwardsRow处理录制时间戳回退毫秒回绕或两段日志拼接防止追赶把整个文件以 512 注入/20 ms 快进到 EOFbug B9。MDF4 播放器T3/T7与 Sessions 播放器T4/T8执行相同转换MDF4 直接由样本缓存构建通道列表同时移除自身多源 split-then-rejoinSessions 以窗口化范围查询读取readings表覆盖索引(session_id, unique_id, timestamp_ns)存在平局用reading_id打破绝不用DISTINCT timestamp_ns查询边界以窗口大小封顶且 seek 查询一次性 prepare check、失败时清除 NaN 序列qt-cpp-review 修复项。T9 按计划跳过250 ms 静止防抖每次移动重启足以可靠检测手势结束三个播放器对话框无需pressed绑定改动。六、Dashboard 批量窗口装载与时钟复位T5 将批量装载入口落在 Dashboard.h 的bulkLoadPlotWindow(timesSec, series)实现见 Dashboard.cppvoid UI::Dashboard::bulkLoadPlotWindow(const QVectordouble timesSec, const QHashqint64, QVectordouble series) { if (!m_layoutValid) [[unlikely]] return; if (!m_replaySeek.bulkLoadPlotWindow(timesSec, series)) return; m_plotControls.resetSweepStates(); resetPlotClocks(); m_updateRequired true; }设计约束与实现要点只写环批量装载重置并回填采样 y 环、每曲线TimeRing在已重置环上逐字复用appendDecimated按录制时间顺序喂给与注入路径完全相同的追加原语绝不手写 cell——绝对网格 TimeRing 语义得以保持、dataset-X 环、MultiPlot 曲线push 表与m_layoutValid不动任何布局变更仍走 reconfigureplan.md 风险章节的 push-table 陈旧性约束。seek 时钟复位m_plotClocks与m_plotDisplayTimeSec是同一状态只有resetPlotClocks()同时清除两者bulkLoadPlotWindow结尾复位使向后 scrub 后继续播放干净地从录制时间轴恢复避免 per-source 时钟永不回退导致压缩到单一 decimator cellplan.md 明确时钟回退必须显式复位AC1 的 scrub-then-play 断言覆盖之。槽池无分配批量装载运行在 UI 节奏的主线程成本以窗口 × plot-enabled 数据集为界不触碰 FrameReader、CircularBuffer、span 快通道或hotpathTxFrame的活动扇出活动热路径零新增工作/分配/锁。七、集成测试AC1 / AC3 / AC5 的自动化验证[T1–T10] 中 T10 新增 tests/integration/test_replay_timeline.py面向运行中的 Serial Studio本地 7777 API 服务需在设置中启用 API Server共四个用例test_backward_scrub_matches_direct_seekAC1打开 200 行 50 Hz 恒定速率录制 →csvPlayer.setProgress(0.8)→ 静止 → 再setProgress(0.4)→ 取dashboard.tailFrames的曲线 A 序列关闭后重新打开直接 seek 0.4 作为基线断言帧位置相等且 scrub 序列与直跳序列逐元素相等——这正是 R1 磁带语义“无论 P 如何到达曲线相同”的机器可验证形式。test_scrub_then_play_resumesAC1 补充向后 scrub 后取消暂停1 秒后帧位置前进——验证 seek 时钟复位使播放干净恢复。test_playback_pace_and_losslessnessAC3播放 2 秒后帧位置与2.0 * ROW_HZ偏差不超过ROW_HZ // 2节拍容差播完全部行后framePosition ROW_COUNT - 1且tailFrames的 y 序列与[0..199]精确匹配无损交付。test_replay_never_re_recordsAC5csvExport.setEnabled(true)后播放 scrub断言csvExport.getStatus()的isOpen为 False——回放与 scrub 从未打开导出文件R6。测试头注释明确记录了覆盖策略CSV 端到端覆盖共享通道AC1/AC3/AC5MDF4/session 文件因无测试写入辅助工具其变体依靠共享代码覆盖 AC2 维持T10 done 备注。八、Definition of Done 与质量门tasks.md 的完成清单全部勾选展示了该重构的质量纪律也是复现验证的检查表spec.md 中每条验收标准已满足并勾选——AC2/AC4 除外这两条由维护者在下一构建上执行应用内现场项目 scrub 手感观察 --benchmark-hotpath全部 tierpython scripts/code-verify.py --check对全部改动文件零错误零告警qt-cpp-review6-agent 评审2026-07-19确认的发现已修复编译保护安全的引擎拆除改经 playback-awarecompileTransforms追赶时间预算旁增设静态迭代上限QuickPlot scrub 回退到 settle 重建而非抹空环Sessions seek 查询一次性 prepare checked 失败清 NaN 序列CSV 日期/时间秒缓存Dashboard 填充辅助函数constFindbuildRowCells加[[nodiscard]] constreplaySeekSeries返回std::pairseek 槽加边界断言--benchmark-hotpath复跑为维护者 AC4 门span 通道不动QList 通道严格更轻pytest tests/integration/test_replay_timeline.py -v供维护者运行python scripts/sanitize-commit.py已跑树无 lint 债务每个改动文件都映射到 spec 0020、两个早期 bug 修复、mimalloc 升级或文档/测试同步——“diff 是所要求的且仅此而已”。九、验证路径速查验证项命令 / 操作依据静态检查python scripts/code-verify.py --check全部改动文件tasks.md T1–T8、DoD集成测试应用带 API Server 运行后pytest tests/integration/test_replay_timeline.py -vtest_replay_timeline.py热路径回归AC4--benchmark-hotpath全部九个门控 tierspec.md AC4提交清洁python scripts/sanitize-commit.pytasks.md DoD维护者观察AC2字段项目 真实捕获双向拖动、无多秒冻结、仅凭 scrub 定位事件spec.md AC2适用前提与限制MDF4/session 回放为商业构建门控CSV 回放保持 GPL所有时序结论基于 2026 年规格文档与当前源码实现字段项目参考规模为 88 组 / 571 数据集 / 10M 行录制上限。与本次重构配套的架构说明同步于 export.md 与 dataflow.mdT11回放入口、发布目标策略与 scrub 通道均已入档。若需本地复现可通过git clone获取仓库后按 README 构建并在应用中打开示例 CSV 录制文件体验双向磁带式 scrub。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Serial Studio 回放时间线重构实战：磁带式 Scrubbing 与无损追赶（Spec 0020）
Serial Studio 回放时间线重构实战磁带式 Scrubbing 与无损追赶Spec 0020【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio导读Serial Studio 是开源遥测数据面板支持 UART、BLE、MQTT、Modbus、CAN Bus 等多种数据源。当录制文件规模达到“现场项目级”字段项目 88 个分组、571 个数据集、每条 CAN 消息一行记录时旧版回放暴露出两个致命问题拖动时间轴会丢弃全部绘图数据并同步重建整个窗口单次拖动导致 UI 冻结数秒录制帧率超过回放处理能力时追赶循环永远落后回放变成永久慢放。本指南以doc/claude/specs/0020-replay-timeline/三份规格文档spec / plan / tasks为核心结合仓库源码与集成测试完整讲解 Serial Studio 2026 年回放时间线重构Spec 0020的动机、需求、架构设计与逐任务落地细节读者可据此理解磁带式 scrubbing与无损追赶在真实遥测面板中的实现方案。一、重构动机现场项目规模下的两大回放痛点Spec 0020 的出发点来自一次真实压测2026-07-18字段项目文件88 组、571 数据集、每条 CAN 消息一行记录从 CSV 或 MDF4 回放暴露出两类系统性问题Scrubbing 不可用早期版本允许用户拖动时间轴并观看曲线在光标下“播放”这是视觉定位事件、跳转到目标时刻的主要手段。但当时每次滑块移动都会丢弃全部绘图数据再通过通用解析管线同步重建整个绘图窗口——在字段项目规模上一个 tick 就要付出数百次完整管线帧注入的代价UI 冻结数秒实时 scrub 体验完全消失。回放无法跟上节奏当录制帧率超过回放管线处理能力时追赶catch-up循环以固定批量回放每一行中间数据且永远落后——录制永远以慢动作播放。Session 回放感觉稍好只是因为其帧计数折叠了同毫秒突发而非管线更快。维护者的定调2026-07-19scrubbing 必须像磁带一样——两个方向都快曲线始终反映光标位置向后 scrub 时点可见地回退追赶必须快到无损跳过录制数据不可接受。完整需求定义见 spec.md。二、需求矩阵R1–R6 与验收标准 AC1–AC5Spec 0020 将目标形式化为六条可验证需求编号需求核心语义R1位置精度磁带语义时间轴停在位置 P 时每个曲线精确显示以 P 结尾的尾随窗口内录制样本向后 scrub 无 P 之后残留样本窗口之前无空洞与到达 P 的方式无关R2实时 scrub 反馈字段项目规模下拖动时曲线每秒多次可见更新UI 绝不硬冻结仪表、条图、LED 等非曲线控件跟踪光标当前帧R3节拍化回放回放 N 秒墙钟时间后时间轴位置与 N 秒录制时间偏差在固定小容差内无无界漂移R4无损性完整回放过程中每条录制行恰好被处理并交付仪表盘一次——不跳过、不重复即使瞬时停滞触发追赶R5播放器对齐R1–R4 对 CSV、MDF4、Session 回放商业构建完全一致R6回放绝不重新录制scrubbing 与回放不得追加到任何导出汇CSV/MDF4/session/MQTT 发布——“倒带磁带不得制造新录音”对应五条验收标准AC1API 驱动回放 seek 后dashboard.tailFrames与全新打开直跳基准一致覆盖 CSVMDF4session 变体在商业构建上跑同一脚本AC2维护者现场观察双向拖动实时更新、无多秒冻结、可仅靠 scrub 定位事件AC3恒定速率宽 CSV 回放时间戳在容差内跟随墙钟 交付帧数等于录制行数即无损节奏联合断言AC4--benchmark-hotpath全部门控 tier 仍通过活动解析路径不得为回放让路而回退AC5CSV 导出开启时回放scrub导出文件不增长、不产生 session 行。约束与不变量还包括活动设备热路径保持其吞吐门256 kHz 参考、全部九个 benchmark tier录制值是最终值回放绝不重跑数据集变换CSV 回放保持 GPL、MDF4/session 回放保持商业门控单次拖动无 UI 停顿超过约 50 ms永久低配机器上回放拉伸时间无损而非跳行。全部细节见 spec.md。三、总体方案两条协作通道替换“一刀切注入”plan.md 给出的核心设计是两条协作通道回放注入快通道lane 1FrameBuilder新增回放入口直接接收播放器已切分好的通道行QStringList 录制时间戳消除“join 成字节 → 重新拆分”的往返发布到仪表盘与只读 API 观察者但绝不发布到录制汇CSV/MDF4/Sessions 导出、MQTT 发布从构造上满足 R6。节拍回放与追赶走此通道采用时间预算批量循环每次事件循环约 20 ms替代固定 100 行批量使重负载录制无损保持节奏且 GUI 保持响应。批量 seek 通道lane 2拖拽 scrub拖动滑块时合并到约 30 HzDashboard仅批量装载绘图环——直接从播放器现有内存存储中按需数值解析窗口行仅 plot-enabled 数据集字段项目规模下每 tick 约毫秒级另加一次快通道注入光标帧供标量控件使用随后一个防抖约 250 ms静止通道通过 lane 1 重放完整尾随窗口使 FFT/waterfall/GPS/3D 在静止位置精确对应 spec 的 Q3 决议。向后与向前 scrub 是同一操作重建以光标结尾的窗口因此磁带语义由构造保证。选择该方案的原因详见 plan.md 的 Tradeoffs 表放弃“仅预算化管线”字段项目规模下错过 50 ms 拖拽预算与“预计算数值矩阵”10M 行时内存达 GB 级违反内存约束回放发布目标选择“仪表盘 只读观察者、无录制器/MQTT”而非“全扇出 每汇门控”避免把门控摊到五个汇上引发静默重录回归。四、源码落地FrameBuilder 回放入口与发布目标策略设计落到 FrameBuilder.h 中的三个回放入口void replayChannels(int sourceId, const QStringList channels, const DataModel::TimestampedFrame::SteadyTimePoint timestamp); void replayChannelSpans(int sourceId, const QByteArrayView* cells, qsizetype count, const DataModel::TimestampedFrame::SteadyTimePoint timestamp); void replayChannelsTyped(int sourceId, const ReplayCell* cells, qsizetype count, const DataModel::TimestampedFrame::SteadyTimePoint timestamp);FrameBuilder.cpp 中replayChannels的实现体现了任务 T1 的全部不变量线程归属非 builder 线程调用时通过Qt::BlockingQueuedConnection派发回 builder 线程热路径断言SS_ASSERT_HOTPATH(m_playerOpen)断言播放器打开复用现有状态而非重新推导、m_operationMode SerialStudio::ProjectFile复用现有列映射通过applyDatasetValues(srcFrame, channels, info)应用已有的 replay 列映射变换保持门控关闭录制值是最终值发布走槽池publishReplayValues(sourceId, srcFrame, timestamp)复用acquireFrame的槽池机制structureGeneration与活动站点完全一致地盖章时间戳所有权录制时间戳由播放器在入口边界盖章Dashboard/观察者绝不重新盖章——这同时修复了旧版对回放帧的墙钟盖章问题无新信号跳变直接函数调用无新增信号无新增缓存标志输入。注释明确写道本入口发布到 “Dashboard and read-only API observers only; recording sinks never see replayed frames, so a replay can never re-record itself”即 R6 从构造上成立。replayChannelSpansUTF-8 视图单元直接来自 CSV 播放器的内存映射行零中间 QString 列表与replayChannelsTypedMDF4 播放器列式缓存的本地 double 借用文本指针是 spec 0022 的补充通道走同一槽池回放扇出。底层逐数据集发布由 ReplayIngest.cpp 完成columnsFor(sourceId)返回按源的 uid→列映射——plan.md 风险章节强调 uniqueIds 跨源并不唯一所有 uid→列映射必须保持按源m_replayColumnMap已然如此批量填充 provider 镜像之。五、CSV 播放器磁带式 scrub 的三段式实现CSV/Player.h 的setProgress/performSeekTick/performSeekSettle私有槽与 CSV/Player.cpp 的实现一起完整对应任务 T2 与 T6。setProgress记录目标非同步注入钳制进度到 [0,1]若正在播放先暂停计算newFramePos后更新帧位置与时间戳显示调用m_engine.armSeek()触发合并定时器。注释点明位置与时间戳立即更新合并定时器以约 30 Hz 实时填充曲线静止定时器在滑块停下后运行精确全窗口重建——setProgress 不再在每个滑块 tick 上做同步窗口注入T6 的 read-back 验证点。performSeekTick合并 tick批量填充 光标注入若m_seekColumnByKey为空则直接走 settle避免空序列映射的批量填充抹掉全部曲线导致整个拖拽期间空白这是 qt-cpp-review 修复项之一否则由seekWindowStartRow从光标向前回走确定尾随窗口起点覆盖 plot time range不少于points()行由引擎封顶以约束密集录制每 tick 成本buildSeekWindow从内存映射行直接填充每行一次 split、每单元 fast_float无 QString调用dashboard.bulkLoadPlotWindow(times, series)再anchorSteadyBase(target)injectRow(target)注入光标行供标量控件跟踪。performSeekSettle静止重建精确全窗口clearPlotData()后通过processFrameBatch(start, m_framePos)在快速通道重放完整尾随窗口使 FFT/waterfall/GPS/3D 等帧馈送控件精确backfillSparseSources()回填稀疏源随后若存在 seek 列映射再做一次全时间窗口批量填充让曲线保持完整磁带视图而非坍缩到管线批量。时间预算化追赶T2 的核心替换在 Player.cpp 的updateData中固定kMaxBatchSize 100被替换为约 20 ms 墙钟预算 单次最多 512 次注入的静态上限qt-cpp-review 修复项静态迭代上限与追赶时间预算并存constexpr qint64 kCatchUpBudgetMs 20; constexpr int kCatchUpMaxInjects 512; const QDeadlineTimer budget(kCatchUpBudgetMs); ... for (int processed 0; processed kCatchUpMaxInjects m_framePos targetRow !budget.hasExpired(); processed) { m_framePos qMin(targetRow, m_framePos stride); injectRow(m_framePos); }时间预算随项目宽度与机器速度自适应快机器一 pass 处理更多行慢机器“拉伸时间”天然发生spec Q2跳过仍被禁止事件循环通过现有单发定时器让出控制权GUI 保持响应。reanchorOnBackwardsRow处理录制时间戳回退毫秒回绕或两段日志拼接防止追赶把整个文件以 512 注入/20 ms 快进到 EOFbug B9。MDF4 播放器T3/T7与 Sessions 播放器T4/T8执行相同转换MDF4 直接由样本缓存构建通道列表同时移除自身多源 split-then-rejoinSessions 以窗口化范围查询读取readings表覆盖索引(session_id, unique_id, timestamp_ns)存在平局用reading_id打破绝不用DISTINCT timestamp_ns查询边界以窗口大小封顶且 seek 查询一次性 prepare check、失败时清除 NaN 序列qt-cpp-review 修复项。T9 按计划跳过250 ms 静止防抖每次移动重启足以可靠检测手势结束三个播放器对话框无需pressed绑定改动。六、Dashboard 批量窗口装载与时钟复位T5 将批量装载入口落在 Dashboard.h 的bulkLoadPlotWindow(timesSec, series)实现见 Dashboard.cppvoid UI::Dashboard::bulkLoadPlotWindow(const QVectordouble timesSec, const QHashqint64, QVectordouble series) { if (!m_layoutValid) [[unlikely]] return; if (!m_replaySeek.bulkLoadPlotWindow(timesSec, series)) return; m_plotControls.resetSweepStates(); resetPlotClocks(); m_updateRequired true; }设计约束与实现要点只写环批量装载重置并回填采样 y 环、每曲线TimeRing在已重置环上逐字复用appendDecimated按录制时间顺序喂给与注入路径完全相同的追加原语绝不手写 cell——绝对网格 TimeRing 语义得以保持、dataset-X 环、MultiPlot 曲线push 表与m_layoutValid不动任何布局变更仍走 reconfigureplan.md 风险章节的 push-table 陈旧性约束。seek 时钟复位m_plotClocks与m_plotDisplayTimeSec是同一状态只有resetPlotClocks()同时清除两者bulkLoadPlotWindow结尾复位使向后 scrub 后继续播放干净地从录制时间轴恢复避免 per-source 时钟永不回退导致压缩到单一 decimator cellplan.md 明确时钟回退必须显式复位AC1 的 scrub-then-play 断言覆盖之。槽池无分配批量装载运行在 UI 节奏的主线程成本以窗口 × plot-enabled 数据集为界不触碰 FrameReader、CircularBuffer、span 快通道或hotpathTxFrame的活动扇出活动热路径零新增工作/分配/锁。七、集成测试AC1 / AC3 / AC5 的自动化验证[T1–T10] 中 T10 新增 tests/integration/test_replay_timeline.py面向运行中的 Serial Studio本地 7777 API 服务需在设置中启用 API Server共四个用例test_backward_scrub_matches_direct_seekAC1打开 200 行 50 Hz 恒定速率录制 →csvPlayer.setProgress(0.8)→ 静止 → 再setProgress(0.4)→ 取dashboard.tailFrames的曲线 A 序列关闭后重新打开直接 seek 0.4 作为基线断言帧位置相等且 scrub 序列与直跳序列逐元素相等——这正是 R1 磁带语义“无论 P 如何到达曲线相同”的机器可验证形式。test_scrub_then_play_resumesAC1 补充向后 scrub 后取消暂停1 秒后帧位置前进——验证 seek 时钟复位使播放干净恢复。test_playback_pace_and_losslessnessAC3播放 2 秒后帧位置与2.0 * ROW_HZ偏差不超过ROW_HZ // 2节拍容差播完全部行后framePosition ROW_COUNT - 1且tailFrames的 y 序列与[0..199]精确匹配无损交付。test_replay_never_re_recordsAC5csvExport.setEnabled(true)后播放 scrub断言csvExport.getStatus()的isOpen为 False——回放与 scrub 从未打开导出文件R6。测试头注释明确记录了覆盖策略CSV 端到端覆盖共享通道AC1/AC3/AC5MDF4/session 文件因无测试写入辅助工具其变体依靠共享代码覆盖 AC2 维持T10 done 备注。八、Definition of Done 与质量门tasks.md 的完成清单全部勾选展示了该重构的质量纪律也是复现验证的检查表spec.md 中每条验收标准已满足并勾选——AC2/AC4 除外这两条由维护者在下一构建上执行应用内现场项目 scrub 手感观察 --benchmark-hotpath全部 tierpython scripts/code-verify.py --check对全部改动文件零错误零告警qt-cpp-review6-agent 评审2026-07-19确认的发现已修复编译保护安全的引擎拆除改经 playback-awarecompileTransforms追赶时间预算旁增设静态迭代上限QuickPlot scrub 回退到 settle 重建而非抹空环Sessions seek 查询一次性 prepare checked 失败清 NaN 序列CSV 日期/时间秒缓存Dashboard 填充辅助函数constFindbuildRowCells加[[nodiscard]] constreplaySeekSeries返回std::pairseek 槽加边界断言--benchmark-hotpath复跑为维护者 AC4 门span 通道不动QList 通道严格更轻pytest tests/integration/test_replay_timeline.py -v供维护者运行python scripts/sanitize-commit.py已跑树无 lint 债务每个改动文件都映射到 spec 0020、两个早期 bug 修复、mimalloc 升级或文档/测试同步——“diff 是所要求的且仅此而已”。九、验证路径速查验证项命令 / 操作依据静态检查python scripts/code-verify.py --check全部改动文件tasks.md T1–T8、DoD集成测试应用带 API Server 运行后pytest tests/integration/test_replay_timeline.py -vtest_replay_timeline.py热路径回归AC4--benchmark-hotpath全部九个门控 tierspec.md AC4提交清洁python scripts/sanitize-commit.pytasks.md DoD维护者观察AC2字段项目 真实捕获双向拖动、无多秒冻结、仅凭 scrub 定位事件spec.md AC2适用前提与限制MDF4/session 回放为商业构建门控CSV 回放保持 GPL所有时序结论基于 2026 年规格文档与当前源码实现字段项目参考规模为 88 组 / 571 数据集 / 10M 行录制上限。与本次重构配套的架构说明同步于 export.md 与 dataflow.mdT11回放入口、发布目标策略与 scrub 通道均已入档。若需本地复现可通过git clone获取仓库后按 README 构建并在应用中打开示例 CSV 录制文件体验双向磁带式 scrub。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
