Serial-Studio 帧注释层Spec 0059用一段 JS 解码器把裸字节流变成多行协议注释【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio本文基于 Serial-Studio 仓库中 spec 0059Frame annotation layer的任务清单 tasks.md 及其配套 spec.md、plan.md结合已合入的源码与测试完整讲解这一“帧注释层”的 T1–T9 任务是如何落地的AnnotationModel的有界存储与文本驻留interning、JS 解码器的看门狗与 carry-over 机制、Console::Handler的集成路径以及 track strip / 表格 / 载荷提取三类消费端的实现细节。读完后你可以理解该模块的数据模型设计、写出符合decode(bytes, offset, ctx)契约的解码器脚本并通过测试用例验证其行为边界。任务总览T1–T9 做了什么任务清单以九个任务全部完成勾勒出该特性从模型到文档的完整交付面任务内容对应仓库证据T1Console::AnnotationModelAnnotationFiltercore/Ui/Console/Annotations.h、Annotations.cppT2Console::AnnotationDecoderJS、看门狗、carry-over、失败锁存core/Ui/Console/Annotations.h#L254-L331T3Console::Handler所有权、数据喂入、QML 属性CMake 注册core/Ui/Console/Handler.h#L180-L188、core/Ui/CMakeLists.txt#L140T4ConsoleAnnotations.qmltrack / table CSV / payload / decoder与终端开关app/qml/Widgets/Dashboard/ConsoleAnnotations.qmlT5tst_console_annotations单测 CMake 注册app/tests/tst_console_annotations.cppT6文档dashboard 架构说明中的 tools 段落doc/claude/architecture/dashboard.md#L143T7Lua 解码器同一模型 API模型 API 与语言无关见下文说明T8Problem Center 解码器失败检查器见“错误处理”一节中的现状说明T9捆绑示例解码器分隔帧、长度前缀 CRC 等app/rcc/scripts/annotations/该特性的动机在 spec 中表述得很直接Serial-Studio 能看到设备发出的每一个字节但从不解释它们。终端Console显示原始字节解析器把分隔帧转成数据集而“哪些字节是头、哪些是 CRC、哪些是载荷、载荷含义是什么”这一中间层只存在于用户脑中。帧注释层要做的就是让一个用户编写的解码器复用既有 JS 或 Lua 引擎不引入新语言能对裸字节流的字节区间挂上注释形成逻辑分析仪式“位 - 字节 - 字段 - 包”的堆叠注释行。T1AnnotationModel —— 以绝对偏移为键的有界注释存储Annotations.h#L50-L58 定义了最核心的记录结构一条注释就是“一个字节区间 一个行号 一个类别 最多 3 级文本”struct Annotation { static constexpr int kTextLevels 3; qint64 start; // 绝对字节偏移含 qint64 end; // 绝对字节偏移含 qint32 row; // 解码器声明的行索引 qint32 cls; // 解码器声明的类别索引携带颜色 qint32 texts[kTextLevels]; // 驻留文本 id从最长到最短 };texts是一个“同一含义由长到短”的渲染序列例如[Sync byte 0xFE, SYNC, S]注释跨度在像素上很窄时界面可以自动退到更短的文本保证窄区间里仍能显示点东西。存储上限是硬编码常量Annotations.h#L124-L128这是 spec 里“有界内存”要求R4/R5 与 Constraints的直接体现常量值含义kMaxAnnotations65536注释条数上限超出时丢弃最旧记录kMaxTexts4096驻留文本表上限超出后新文本折叠到溢出占位 id 0...kMaxRetainedBytes1 MiB保留的原始字节副本上限用于载荷提取注释随窗口滚动而修剪kMaxRows/kMaxClasses16 / 64解码器可声明的行数与类别数文本驻留interning是该模型的关键设计解码器在一个会话里可能上百万次输出同样的字符串internText()Annotations.cpp#L696-L698保证相同字符串只存一份、注释里只存整数 id。构造函数会先驻留溢出占位符...使其 id 恒为 0Annotations.cpp#L48-L65。这与 spec 验收标准 AC2100 万条注释、8 种文本时驻留表只保持 8 条字符串一一对应。两阶段提交annotate()只是把记录暂存进m_pendingAnnotations.cpp#L583-L605commitPending()在 UI 节拍上一次性发布超容量时dropOldest()修剪最旧记录。注释如此写道“每秒输出数千条的解码器每个 UI tick 只产生一次模型事务”。存储用std::dequeAnnotation实现修剪代价只与丢弃的记录数成正比不复制存活部分。保留字节窗口ingestBytes()把原始流字节追加到有界窗口1 MiB并推进绝对偏移计数Annotations.cpp#L646-L661trimToRetainedBytes()丢弃end早于窗口起点的注释Annotations.cpp#L707。这实现了 spec R1终端丢弃旧字节时结束于保留窗口之前的注释随之丢弃。一个值得注意的实现细节trimToRetainedBytes()的前缀扫描仅在存储按 start 有序时提前终止commitPending()会为乱序输出的解码器清除该标志防止排在存活记录之后、却已越窗的注释永远无法修剪——这是对“解码器可能不按流序输出注释”的防御。AnnotationModel同时就是表格视图背后的QAbstractTableModel列为 Start / End / Length / Row / Class / TextAnnotations.cpp#L78-L81并为 QML 委托暴露了start、end、length、rowName、className、classColor、text、shortText等命名角色Annotations.cpp#L173-L188。declareLayout()采用解码器声明的行名与类别[{name, color}]或纯名字未指定颜色时按内置 8 色调色板循环取色并钳制到 16 行 / 64 类上限Annotations.cpp#L529-L575。T2AnnotationDecoder —— 带看门狗的 JS 解码器运行时解码器契约在 Annotations.h#L248-L253 的注释中定义一个全局decoder对象包含rows、classes和decode(bytes, offset, ctx)函数decode返回已消费的字节数其余字节作为有界的 carry-over 带入下一次调用。ctx就是AnnotationModel本身解码器通过它调用annotate(start, end, row, cls, texts)。运行时行为的关键参数Annotations.h#L285-L286kWatchdogMs 200每次decode()调用都在DataModel::JsWatchdog下运行Annotations.cpp#L1123-L1133死循环或超长解析会被看门狗打断不会阻塞 GUI 线程kMaxCarry 4096未消费字节上限。若解码器长期“吃不下去”数据carry 被截断防止无界增长失败锁存任何抛出、超时都会走fail()——m_failed true、m_enabled false、拆掉引擎、记录lastError并qWarningAnnotations.cpp#L1197-L1205。对应 spec R8“解码器失败禁用直到重新启用”也对应 AC5“每 chunk 抛错只产生一条错误而不是对话框风暴”。两个与性能/正确性相关的门控值得细看无视图则不跑active()为真当且仅当至少注册了一个注释视图Annotations.cpp#L904-L909。面板是存储的唯一消费端面板没开时控制台流“免费通行”——既没有保留窗口副本也没有每 chunk 的decode()调用。这落实了 spec R9 的“没有配置解码器时零开销”opt-in。暂停恢复丢弃 carrysetViewerActive()在恢复时清掉 carryAnnotations.cpp#L1004-L1009因为暂停期间的字节若拼接到恢复后的数据前面等于把一帧线上从未出现的帧喂给decode()。同理reset()先清空模型再重读偏移注释里明确记载了这个顺序反转曾经导致“注释落在窗口外、永远无法修剪”的真实缺陷Annotations.cpp#L1104-L1110。线程模型遵循 spec 的硬约束解码器在终端侧GUI 线程、chunk 节拍运行绝不在帧管线热路径上逐字节执行Console::Handler收到的原始字节流本来就是 GUI 线程上 chunk 级到达的因此管线线程零改动。T3Handler 集成 —— 所有权、数据路径与 QML 属性Console::Handler在构造函数中用普通new父对象为this不走单例创建并持有全部三个对象Handler.cpp#L119-L123, m_annotations(new AnnotationModel(this)) , m_annotationDecoder(new AnnotationDecoder(m_annotations, this)) , m_annotationFilter(new AnnotationFilter(this)) { m_annotationFilter-setSourceModel(m_annotations);对应 Handler.h#L394-L397 的成员声明“Frame annotation layer (spec 0059): owned here so the consoles raw feed is its input”。数据喂入路径有两条单设备路径hotpathRxData()中m_annotationDecoder-feed(data)Handler.cpp#L874-L879多设备路径hotpathRxDeviceData()只喂当前设备的数据Handler.cpp#L911-L916。三个对象分别以annotations、annotationDecoder、annotationFilter三个QObject*QML 属性暴露给界面Handler.h#L180-L188CMake 注册见 core/Ui/CMakeLists.txt#L140Console/Annotations.cpp与Console/Annotations.h均在构建列表中。架构文档 doc/claude/architecture/dashboard.md#L143-L147 中对这一层的描述与上述实现一致即 T6 的落点。T4三个消费端 —— track strip、过滤表格与载荷提取Spec 要求“一个模型服务三个消费端”实现上通过AnnotationModel的一组Q_INVOKABLE查询方法完成Annotations.h#L152-L1591. 注释轨道track strip终端渲染的是格式化文本而非字节单元格不存在“字节 - 单元格”的映射因此 plan 中明确放弃了在 VT100 网格上逐格叠加注释的方案改为“字节成比例的轨道条”每个声明行一条 lanespan 宽度与字节区间成正比文本取能放进像素宽度的最长一级。底层是collectRuns()Annotations.cpp#L336-L372它把某个行内、落在[from, to]窗口中的注释收集为“可分辨的运行”SpanRun——同一类别且当前缩放分不开的相邻注释会合并计数合并上限为一个像素簇保证宽窗口放大时仍能看到密度而非糊成一团。trackSpans()返回可读形式{start, end, cls, count, color, text, shortText}trackStrip()则返回打包好的像素几何{geometry, labels, shortLabels, count}供 Canvas 一次性绘制标签只在运行数不超过 256kLabelledSpanBudget时才附带避免海量标记时的字符串开销Annotations.cpp#L408-L442。查询效率上windowFirstIndex()利用“解码器通常按流序输出”这一不变量做lower_bound跳过历史乱序时退回全量扫描Annotations.cpp#L313-L328。2. 表格视图 CSV 导出AnnotationFilter是一个QSortFilterProxyModel按行 / 类别过滤-1 表示任意Annotations.h#L213-L246。CSV 导出由exportCsv()完成固定表头start,end,length,row,class,text对文本列做引号转义并在读取状态前强制flush()——注释解释了原因QTextStream有缓冲最后一段数据若落在析构阶段写入设备错误就永远不会被报告Annotations.cpp#L489-L519。这对应 spec R6 与 AC3导出 CSV 可用电子表格按“一行一条注释”打开。3. 载荷提取payload viewpayloadBytes(cls, maxBytes)按流顺序拼接某一类别所有保留注释的原始字节Annotations.cpp#L448-L471payloadHex()/payloadText()分别给出大写带空格的十六进制与 UTF-8 文本渲染。实现上只有当注释区间完全落在 1 MiB 保留字节窗口内才参与拼接越窗区间被跳过——这就是为什么要保留一份原始字节的有界副本。对应 spec R7 与 AC4对类别 payload 的载荷视图在已知抓取上逐字节复现拼接后的载荷字节。T5单元测试覆盖的行为边界tst_console_annotations.cpp 的八个测试方法文件头注释与私有槽声明恰好覆盖了 spec 的验收要点internsTextsAndBoundsThem相同文本只驻留一份超过kMaxTexts的新字符串折叠到 id 0对应 AC2 的驻留表有界性trimsToRetainedBytesAndCapacity注释随保留字节窗口滚动修剪且 65536 容量上限生效filterAndCsvAgree过滤代理与 CSV 导出看到的行一致payloadReproducesAnnotatedBytes载荷提取逐字节复现AC4decoderRunsWithCarryOverJS 解码器跨 chunk carry-over——测试用的newlineDecodertst_console_annotations.cpp#L62-L82标注换行分隔的“行”与 LF 字节未终止的尾巴返回已消费偏移带入下次调用decoderPausesWithoutViewer无视图注册时不执行解码decoderIsDisabledOnThrow抛出即禁用AC5 的单元侧对应decoderRejectsBadLayout非法rows/classes声明被拒绝。从测试结构看这组用例与 plan.md 中的测试计划“interning bound, retained-window trim, capacity trim, filter CSV, payload extraction, JS decoder with carry-over, throw disables, layout validation”逐项吻合。T9捆绑示例解码器首批解码器以资源形式捆绑在 app/rcc/scripts/annotations/由 templates.json 按清单顺序列出AnnotationDecoder::templates()/templateCode()从:/scripts/annotations/读取Annotations.cpp#L874-L901文件清单名称覆盖的帧结构line_framing.jsLine framing (LF)默认LF 分隔行nmea_0183.jsNMEA 0183 sentencesNMEA 句子slip.jsSLIP framing (RFC 1055)SLIP 帧cobs.jsCOBS packetsCOBS 编码包mavlink_v2.jsMAVLink v2 packetsMAVLink v2 包modbus_rtu.jsModbus RTU framesModbus RTU 帧fixed_records.jsFixed-size records定长记录以 modbus_rtu.js 为例它很好地展示了契约的用法与工程权衡RTU 在线路上靠空闲间隙分帧而字节流已经不携带间隙因此帧长从功能码推导读保持寄存器等COUNTED功能码的响应长度是3 数量字节 2异常响应恒为 5 字节一般请求恒为 8 字节声明了两行[frames, fields]和五个类别address / function / data / CRC / exception数据不足时return i把尾巴留给 carry-over注释文本用[addr b[i], String(b[i])]这样的长/短两级。注意其注释中明确说明“回退到扫描下一个合理地址字节”的兜底策略体现了解码器在无法确定边界时的保守消费方式。T7/T8Lua 支持与 Problem Center 的现状关于 T7Lua 解码器plan 阶段的决定是“本切片仅 JS模型/API 语言中立Lua 为后续跟进”plan.md 的 Decisions 表。从源码结构看当前AnnotationDecoder持有std::unique_ptrQJSEngine并直接调用QJSEngine::evaluateLua 若要接入需复用现有的 Lua Safe/Fast 模式与看门狗护栏spec Constraints 一节要求“不引入新引擎类型”就当前仓库而言Lua 解码器尚未在 Annotations.cpp 中见到对应实现属于计划中的后续项。关于 T8Problem Center 检查器spec R8 要求“解码器错误以每条不同消息一次的形式进入 Problem Center而不是每 chunk 弹窗”。当前实现中AnnotationDecoder::fail()的行为是禁用解码器 面板内显示消息 qWarningAnnotations.cpp#L1197-L1205plan 文档也把“Problem Center 检查器”列为该阶段有意推迟deferred的部分核心诉求“失败禁用 单条错误消息、无对话框风暴”已由失败锁存机制满足。设计决策回顾plan.md 记录了 spec 遗留问题的最终裁决这些决策直接塑造了实现形态问题决定宿主位置终端Console tool面板位于控制台下方ribbon 开关注释是否持久化到会话否回放时重跑解码器Console 数据流本身也回放Pro 门控无解码器分发通过widgetSettings(console)随项目捆绑解码器代码与启用状态在此持久化无需 schema 工作解码器语言本切片仅 JS模型 API 语言中立Lua 跟进VT100 网格上叠加弃用改为字节成比例轨道条终端渲染的是格式化文本无字节-单元格映射错误处理解码器禁用 面板消息 qWarningProblem Center 检查器推迟线程影响方面plan 明确“管线线程零开销”Console::Handler收到的原始字节本来就在 GUI 线程上以 chunk 节拍到达解码器在那里运行且受看门狗保护模型侧各集合注释、文本、字节、carry全部有界。小结Serial-Studio 的帧注释层用约 1300 行 CAnnotations.cpp 约 1216 行加一组 JS 模板兑现了 spec 0059 的核心承诺不引入新语言、不触碰帧热路径仅靠“有界模型 驻留文本 看门狗保护的脚本解码器”就让用户在终端下方看到逻辑分析仪式的多行协议注释并能按行/类别过滤导出、把某一类别的字节重新拼成独立数据流。对想编写自定义解码器的开发者约束可以浓缩为三条遵守decoder {rows, classes, decode(bytes, offset, ctx)}契约、返回真实消费字节数让未匹配尾巴走 carry-over、以及保证单次decode()在 200 ms 看门狗时限内返回——这三条在 tst_console_annotations.cpp 中都有对应的失败用例可以对照。【免费下载链接】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 帧注释层（Spec 0059）：用一段 JS 解码器把裸字节流变成多行协议注释
Serial-Studio 帧注释层Spec 0059用一段 JS 解码器把裸字节流变成多行协议注释【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio本文基于 Serial-Studio 仓库中 spec 0059Frame annotation layer的任务清单 tasks.md 及其配套 spec.md、plan.md结合已合入的源码与测试完整讲解这一“帧注释层”的 T1–T9 任务是如何落地的AnnotationModel的有界存储与文本驻留interning、JS 解码器的看门狗与 carry-over 机制、Console::Handler的集成路径以及 track strip / 表格 / 载荷提取三类消费端的实现细节。读完后你可以理解该模块的数据模型设计、写出符合decode(bytes, offset, ctx)契约的解码器脚本并通过测试用例验证其行为边界。任务总览T1–T9 做了什么任务清单以九个任务全部完成勾勒出该特性从模型到文档的完整交付面任务内容对应仓库证据T1Console::AnnotationModelAnnotationFiltercore/Ui/Console/Annotations.h、Annotations.cppT2Console::AnnotationDecoderJS、看门狗、carry-over、失败锁存core/Ui/Console/Annotations.h#L254-L331T3Console::Handler所有权、数据喂入、QML 属性CMake 注册core/Ui/Console/Handler.h#L180-L188、core/Ui/CMakeLists.txt#L140T4ConsoleAnnotations.qmltrack / table CSV / payload / decoder与终端开关app/qml/Widgets/Dashboard/ConsoleAnnotations.qmlT5tst_console_annotations单测 CMake 注册app/tests/tst_console_annotations.cppT6文档dashboard 架构说明中的 tools 段落doc/claude/architecture/dashboard.md#L143T7Lua 解码器同一模型 API模型 API 与语言无关见下文说明T8Problem Center 解码器失败检查器见“错误处理”一节中的现状说明T9捆绑示例解码器分隔帧、长度前缀 CRC 等app/rcc/scripts/annotations/该特性的动机在 spec 中表述得很直接Serial-Studio 能看到设备发出的每一个字节但从不解释它们。终端Console显示原始字节解析器把分隔帧转成数据集而“哪些字节是头、哪些是 CRC、哪些是载荷、载荷含义是什么”这一中间层只存在于用户脑中。帧注释层要做的就是让一个用户编写的解码器复用既有 JS 或 Lua 引擎不引入新语言能对裸字节流的字节区间挂上注释形成逻辑分析仪式“位 - 字节 - 字段 - 包”的堆叠注释行。T1AnnotationModel —— 以绝对偏移为键的有界注释存储Annotations.h#L50-L58 定义了最核心的记录结构一条注释就是“一个字节区间 一个行号 一个类别 最多 3 级文本”struct Annotation { static constexpr int kTextLevels 3; qint64 start; // 绝对字节偏移含 qint64 end; // 绝对字节偏移含 qint32 row; // 解码器声明的行索引 qint32 cls; // 解码器声明的类别索引携带颜色 qint32 texts[kTextLevels]; // 驻留文本 id从最长到最短 };texts是一个“同一含义由长到短”的渲染序列例如[Sync byte 0xFE, SYNC, S]注释跨度在像素上很窄时界面可以自动退到更短的文本保证窄区间里仍能显示点东西。存储上限是硬编码常量Annotations.h#L124-L128这是 spec 里“有界内存”要求R4/R5 与 Constraints的直接体现常量值含义kMaxAnnotations65536注释条数上限超出时丢弃最旧记录kMaxTexts4096驻留文本表上限超出后新文本折叠到溢出占位 id 0...kMaxRetainedBytes1 MiB保留的原始字节副本上限用于载荷提取注释随窗口滚动而修剪kMaxRows/kMaxClasses16 / 64解码器可声明的行数与类别数文本驻留interning是该模型的关键设计解码器在一个会话里可能上百万次输出同样的字符串internText()Annotations.cpp#L696-L698保证相同字符串只存一份、注释里只存整数 id。构造函数会先驻留溢出占位符...使其 id 恒为 0Annotations.cpp#L48-L65。这与 spec 验收标准 AC2100 万条注释、8 种文本时驻留表只保持 8 条字符串一一对应。两阶段提交annotate()只是把记录暂存进m_pendingAnnotations.cpp#L583-L605commitPending()在 UI 节拍上一次性发布超容量时dropOldest()修剪最旧记录。注释如此写道“每秒输出数千条的解码器每个 UI tick 只产生一次模型事务”。存储用std::dequeAnnotation实现修剪代价只与丢弃的记录数成正比不复制存活部分。保留字节窗口ingestBytes()把原始流字节追加到有界窗口1 MiB并推进绝对偏移计数Annotations.cpp#L646-L661trimToRetainedBytes()丢弃end早于窗口起点的注释Annotations.cpp#L707。这实现了 spec R1终端丢弃旧字节时结束于保留窗口之前的注释随之丢弃。一个值得注意的实现细节trimToRetainedBytes()的前缀扫描仅在存储按 start 有序时提前终止commitPending()会为乱序输出的解码器清除该标志防止排在存活记录之后、却已越窗的注释永远无法修剪——这是对“解码器可能不按流序输出注释”的防御。AnnotationModel同时就是表格视图背后的QAbstractTableModel列为 Start / End / Length / Row / Class / TextAnnotations.cpp#L78-L81并为 QML 委托暴露了start、end、length、rowName、className、classColor、text、shortText等命名角色Annotations.cpp#L173-L188。declareLayout()采用解码器声明的行名与类别[{name, color}]或纯名字未指定颜色时按内置 8 色调色板循环取色并钳制到 16 行 / 64 类上限Annotations.cpp#L529-L575。T2AnnotationDecoder —— 带看门狗的 JS 解码器运行时解码器契约在 Annotations.h#L248-L253 的注释中定义一个全局decoder对象包含rows、classes和decode(bytes, offset, ctx)函数decode返回已消费的字节数其余字节作为有界的 carry-over 带入下一次调用。ctx就是AnnotationModel本身解码器通过它调用annotate(start, end, row, cls, texts)。运行时行为的关键参数Annotations.h#L285-L286kWatchdogMs 200每次decode()调用都在DataModel::JsWatchdog下运行Annotations.cpp#L1123-L1133死循环或超长解析会被看门狗打断不会阻塞 GUI 线程kMaxCarry 4096未消费字节上限。若解码器长期“吃不下去”数据carry 被截断防止无界增长失败锁存任何抛出、超时都会走fail()——m_failed true、m_enabled false、拆掉引擎、记录lastError并qWarningAnnotations.cpp#L1197-L1205。对应 spec R8“解码器失败禁用直到重新启用”也对应 AC5“每 chunk 抛错只产生一条错误而不是对话框风暴”。两个与性能/正确性相关的门控值得细看无视图则不跑active()为真当且仅当至少注册了一个注释视图Annotations.cpp#L904-L909。面板是存储的唯一消费端面板没开时控制台流“免费通行”——既没有保留窗口副本也没有每 chunk 的decode()调用。这落实了 spec R9 的“没有配置解码器时零开销”opt-in。暂停恢复丢弃 carrysetViewerActive()在恢复时清掉 carryAnnotations.cpp#L1004-L1009因为暂停期间的字节若拼接到恢复后的数据前面等于把一帧线上从未出现的帧喂给decode()。同理reset()先清空模型再重读偏移注释里明确记载了这个顺序反转曾经导致“注释落在窗口外、永远无法修剪”的真实缺陷Annotations.cpp#L1104-L1110。线程模型遵循 spec 的硬约束解码器在终端侧GUI 线程、chunk 节拍运行绝不在帧管线热路径上逐字节执行Console::Handler收到的原始字节流本来就是 GUI 线程上 chunk 级到达的因此管线线程零改动。T3Handler 集成 —— 所有权、数据路径与 QML 属性Console::Handler在构造函数中用普通new父对象为this不走单例创建并持有全部三个对象Handler.cpp#L119-L123, m_annotations(new AnnotationModel(this)) , m_annotationDecoder(new AnnotationDecoder(m_annotations, this)) , m_annotationFilter(new AnnotationFilter(this)) { m_annotationFilter-setSourceModel(m_annotations);对应 Handler.h#L394-L397 的成员声明“Frame annotation layer (spec 0059): owned here so the consoles raw feed is its input”。数据喂入路径有两条单设备路径hotpathRxData()中m_annotationDecoder-feed(data)Handler.cpp#L874-L879多设备路径hotpathRxDeviceData()只喂当前设备的数据Handler.cpp#L911-L916。三个对象分别以annotations、annotationDecoder、annotationFilter三个QObject*QML 属性暴露给界面Handler.h#L180-L188CMake 注册见 core/Ui/CMakeLists.txt#L140Console/Annotations.cpp与Console/Annotations.h均在构建列表中。架构文档 doc/claude/architecture/dashboard.md#L143-L147 中对这一层的描述与上述实现一致即 T6 的落点。T4三个消费端 —— track strip、过滤表格与载荷提取Spec 要求“一个模型服务三个消费端”实现上通过AnnotationModel的一组Q_INVOKABLE查询方法完成Annotations.h#L152-L1591. 注释轨道track strip终端渲染的是格式化文本而非字节单元格不存在“字节 - 单元格”的映射因此 plan 中明确放弃了在 VT100 网格上逐格叠加注释的方案改为“字节成比例的轨道条”每个声明行一条 lanespan 宽度与字节区间成正比文本取能放进像素宽度的最长一级。底层是collectRuns()Annotations.cpp#L336-L372它把某个行内、落在[from, to]窗口中的注释收集为“可分辨的运行”SpanRun——同一类别且当前缩放分不开的相邻注释会合并计数合并上限为一个像素簇保证宽窗口放大时仍能看到密度而非糊成一团。trackSpans()返回可读形式{start, end, cls, count, color, text, shortText}trackStrip()则返回打包好的像素几何{geometry, labels, shortLabels, count}供 Canvas 一次性绘制标签只在运行数不超过 256kLabelledSpanBudget时才附带避免海量标记时的字符串开销Annotations.cpp#L408-L442。查询效率上windowFirstIndex()利用“解码器通常按流序输出”这一不变量做lower_bound跳过历史乱序时退回全量扫描Annotations.cpp#L313-L328。2. 表格视图 CSV 导出AnnotationFilter是一个QSortFilterProxyModel按行 / 类别过滤-1 表示任意Annotations.h#L213-L246。CSV 导出由exportCsv()完成固定表头start,end,length,row,class,text对文本列做引号转义并在读取状态前强制flush()——注释解释了原因QTextStream有缓冲最后一段数据若落在析构阶段写入设备错误就永远不会被报告Annotations.cpp#L489-L519。这对应 spec R6 与 AC3导出 CSV 可用电子表格按“一行一条注释”打开。3. 载荷提取payload viewpayloadBytes(cls, maxBytes)按流顺序拼接某一类别所有保留注释的原始字节Annotations.cpp#L448-L471payloadHex()/payloadText()分别给出大写带空格的十六进制与 UTF-8 文本渲染。实现上只有当注释区间完全落在 1 MiB 保留字节窗口内才参与拼接越窗区间被跳过——这就是为什么要保留一份原始字节的有界副本。对应 spec R7 与 AC4对类别 payload 的载荷视图在已知抓取上逐字节复现拼接后的载荷字节。T5单元测试覆盖的行为边界tst_console_annotations.cpp 的八个测试方法文件头注释与私有槽声明恰好覆盖了 spec 的验收要点internsTextsAndBoundsThem相同文本只驻留一份超过kMaxTexts的新字符串折叠到 id 0对应 AC2 的驻留表有界性trimsToRetainedBytesAndCapacity注释随保留字节窗口滚动修剪且 65536 容量上限生效filterAndCsvAgree过滤代理与 CSV 导出看到的行一致payloadReproducesAnnotatedBytes载荷提取逐字节复现AC4decoderRunsWithCarryOverJS 解码器跨 chunk carry-over——测试用的newlineDecodertst_console_annotations.cpp#L62-L82标注换行分隔的“行”与 LF 字节未终止的尾巴返回已消费偏移带入下次调用decoderPausesWithoutViewer无视图注册时不执行解码decoderIsDisabledOnThrow抛出即禁用AC5 的单元侧对应decoderRejectsBadLayout非法rows/classes声明被拒绝。从测试结构看这组用例与 plan.md 中的测试计划“interning bound, retained-window trim, capacity trim, filter CSV, payload extraction, JS decoder with carry-over, throw disables, layout validation”逐项吻合。T9捆绑示例解码器首批解码器以资源形式捆绑在 app/rcc/scripts/annotations/由 templates.json 按清单顺序列出AnnotationDecoder::templates()/templateCode()从:/scripts/annotations/读取Annotations.cpp#L874-L901文件清单名称覆盖的帧结构line_framing.jsLine framing (LF)默认LF 分隔行nmea_0183.jsNMEA 0183 sentencesNMEA 句子slip.jsSLIP framing (RFC 1055)SLIP 帧cobs.jsCOBS packetsCOBS 编码包mavlink_v2.jsMAVLink v2 packetsMAVLink v2 包modbus_rtu.jsModbus RTU framesModbus RTU 帧fixed_records.jsFixed-size records定长记录以 modbus_rtu.js 为例它很好地展示了契约的用法与工程权衡RTU 在线路上靠空闲间隙分帧而字节流已经不携带间隙因此帧长从功能码推导读保持寄存器等COUNTED功能码的响应长度是3 数量字节 2异常响应恒为 5 字节一般请求恒为 8 字节声明了两行[frames, fields]和五个类别address / function / data / CRC / exception数据不足时return i把尾巴留给 carry-over注释文本用[addr b[i], String(b[i])]这样的长/短两级。注意其注释中明确说明“回退到扫描下一个合理地址字节”的兜底策略体现了解码器在无法确定边界时的保守消费方式。T7/T8Lua 支持与 Problem Center 的现状关于 T7Lua 解码器plan 阶段的决定是“本切片仅 JS模型/API 语言中立Lua 为后续跟进”plan.md 的 Decisions 表。从源码结构看当前AnnotationDecoder持有std::unique_ptrQJSEngine并直接调用QJSEngine::evaluateLua 若要接入需复用现有的 Lua Safe/Fast 模式与看门狗护栏spec Constraints 一节要求“不引入新引擎类型”就当前仓库而言Lua 解码器尚未在 Annotations.cpp 中见到对应实现属于计划中的后续项。关于 T8Problem Center 检查器spec R8 要求“解码器错误以每条不同消息一次的形式进入 Problem Center而不是每 chunk 弹窗”。当前实现中AnnotationDecoder::fail()的行为是禁用解码器 面板内显示消息 qWarningAnnotations.cpp#L1197-L1205plan 文档也把“Problem Center 检查器”列为该阶段有意推迟deferred的部分核心诉求“失败禁用 单条错误消息、无对话框风暴”已由失败锁存机制满足。设计决策回顾plan.md 记录了 spec 遗留问题的最终裁决这些决策直接塑造了实现形态问题决定宿主位置终端Console tool面板位于控制台下方ribbon 开关注释是否持久化到会话否回放时重跑解码器Console 数据流本身也回放Pro 门控无解码器分发通过widgetSettings(console)随项目捆绑解码器代码与启用状态在此持久化无需 schema 工作解码器语言本切片仅 JS模型 API 语言中立Lua 跟进VT100 网格上叠加弃用改为字节成比例轨道条终端渲染的是格式化文本无字节-单元格映射错误处理解码器禁用 面板消息 qWarningProblem Center 检查器推迟线程影响方面plan 明确“管线线程零开销”Console::Handler收到的原始字节本来就在 GUI 线程上以 chunk 节拍到达解码器在那里运行且受看门狗保护模型侧各集合注释、文本、字节、carry全部有界。小结Serial-Studio 的帧注释层用约 1300 行 CAnnotations.cpp 约 1216 行加一组 JS 模板兑现了 spec 0059 的核心承诺不引入新语言、不触碰帧热路径仅靠“有界模型 驻留文本 看门狗保护的脚本解码器”就让用户在终端下方看到逻辑分析仪式的多行协议注释并能按行/类别过滤导出、把某一类别的字节重新拼成独立数据流。对想编写自定义解码器的开发者约束可以浓缩为三条遵守decoder {rows, classes, decode(bytes, offset, ctx)}契约、返回真实消费字节数让未匹配尾巴走 carry-over、以及保证单次decode()在 200 ms 看门狗时限内返回——这三条在 tst_console_annotations.cpp 中都有对应的失败用例可以对照。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考