Serial Studio 脚本解析器类型化单元格通道Spec 0086设计与实现解析【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio导读本文围绕 Serial Studio 仓库中 0086-script-parser-typed-results/plan.md 这一技术设计文档深入讲解其核心方案在脚本解析器Lua / JavaScript与帧构建器FrameBuilder之间引入一条类型化单元格通道cell lane让解析结果以数字 文本字节视图的单元格形式直达数据流水线从而消除每帧数字→文本→再解析回数字的往返开销并使数据集表格捕获table capture只在脚本真正引用表格 API 时才开启。读完本文你将理解 Serial Studio 热路径hotpath上的这一关键优化数据结构设计、两条引擎收集器、数字文本格式化规则、捕获作用域判定、表存储零分配写入以及对应的测试与验证体系。背景为什么需要一条新的解析通道Serial Studio 的脚本解析器允许用户用 Lua 或 JavaScript 编写解析脚本将一帧原始数据转换为多个数据集dataset值。在引入本方案之前解析结果通过QListQStringList传递脚本返回的数字先被格式化成字符串Lua 走luaValueToStringJS 走QJSValue::toString()随后帧构建器再对这些文本做数值探测numeric detection并解析回double。这条路径在功能上正确但在热路径上存在明显浪费数字被格式化→再解析每帧产生两次不必要的转换QListQStringList与逐字符串复制带来堆分配数据集表格捕获把 dataset 值写入DataTable供表格视图/API 读取在存在 Lua 解析引擎时无条件开启即使脚本根本没有引用表格 API也会为每帧付出写入代价表格存储使用 share-assign 写字符串既多一次分配又会让dataset.value的缓冲区被钉住pinning下一次原地写入被迫重新分配。Spec 0086 正是针对这些问题提出的四阶段计划中的第二阶段the HOW其完整需求与验收标准记录在同目录的 spec.md 中。总体架构span 车道、cell 车道与列表回退新方案在原有两条路径之间插入第三条解析通道FrameBuilder::parseProjectFrameFor的执行顺序变为parseProjectFrameFor trySpanLane ........... Native/PlainText保持不变 tryCellLane ........... PlainText 解码器 parser.parseCellsUtf8(bytes, sourceId, m_cellRows) for each row (rowStarts): captureLatestChannelSpans (views与 span 车道相同) [m_captureLatestFrame] applyDatasetValuesCells(frame, cells, count, info) m_stager.stage(sourceId, frame, ts step * row) list path ............. decodeProjectChannels → applyDatasetValues不变的回退对应源码中的实际实现位于 core/Pipeline/DataModel/FrameBuilder.cpptryCellLane约 L1799先检查播放器未打开、帧含分组且解码器为PlainText随后调用FrameParser::parseCellsUtf8约 L497。只有 PlainText 解码器进入 cell 车道Binary/Hex/Base64 脚本继续走列表路径作为后续明确跟进项对每一行按data-timestamp step * row打时间戳与列表路径完全一致依次做 latest-frame 捕获、applyDatasetValuesCells写数据集、m_stager.stage入队若引擎返回false混合形状、JS 非数组结果等则回退到原有的decodeProjectChannels → applyDatasetValues列表路径行为与旧版本一致。IScriptEngine接口core/Pipeline/DataModel/Scripting/IScriptEngine.h新增了两个虚方法// 类型化单元格通道spec 0086true 已填充 rowsfalse 列表结果留在 fallback 中 [[nodiscard]] virtual bool parseUtf8Cells(const QByteArray frame, ScriptCellRows rows, QListQStringList fallback) { Q_UNUSED(rows) fallback parseUtf8(frame); return false; } // 已加载脚本是否命名了表格 API 辅助函数spec 0086用于开启按数据集捕获 [[nodiscard]] virtual bool referencesTableApi() const noexcept { return false; }默认实现直接回退到列表路径因此不支持 cell 车道的引擎如 Native 解析器无需任何改动。值得注意的实现细节是parseUtf8Cells在失败时会把列表结果写回fallback这样引擎不会在拒绝后把脚本跑两遍。数据结构ScriptCell 与可复用的 ScriptCellRowscell 车道的数据结构定义在 core/Pipeline/DataModel/Scripting/ScriptCells.henum class CellKind : quint8 { Text, Number, }; struct ScriptCell { qsizetype offset; // 在 scratch 中的字节偏移 qsizetype length; // 字节长度 double number; // 数字单元格的数值 CellKind kind; // 类型 }; class ScriptCellRows { public: static constexpr qsizetype kMaxCellsPerResult 10000; static constexpr qsizetype kNumberTextCapacity 32; static constexpr qsizetype kBytesPerCellGuess 16; // ... void clear() noexcept; void reserve(qsizetype cells, qsizetype bytes); void beginRow(); void appendText(const char* bytes, qsizetype length); void appendUtf16(QStringView text); void appendNumber(double value, const char* text, qsizetype length); };几个关键设计点对应需求 R1 / R2单元格是偏移 长度而非视图指针ScriptCell保存offset/length指向所属ScriptCellRows的QByteArray m_scratch。这样即使某一帧更宽导致 scratch 重新分配旧单元格也不会失效引擎归属 跨帧复用ScriptCellRows由FrameBuilder持有一个 builder 一个成员m_cellRows引擎向其中写入clear()只resize(0)不释放缓冲区ScriptCells.cpp因此稳定的帧形状在稳态下零堆分配R2。初始容量为 64 个单元格 / 1024 字节首次见到更宽的帧时一次性扩容防钉住clear()在容量超过高水位线单元格 2^18、字节 16 MiB时释放回初始容量避免单个病态结果把内存钉住整个会话元素上限kMaxCellsPerResult 10000沿用既有元素上限不改变每帧/每结果的数量约束。引擎写入时的规则Lua 字符串只在 Lua 栈上存活到弹出为止因此必须复制进 scratchmemcpy到预留字节JS 文本则以 UTF-16 直接编码进 scratch 尾部appendUtf16用QStringEncoder预留最坏情况空间再裁剪避免临时QByteArray。两条引擎收集器LuaCellCollector 与 JsCellCollector计划文档将在引擎内部收集单元格定义为两处实现而实际落地见Implementation deviations一节改为两个与引擎状态无关的收集器类这样单元测试可以直接驱动一个裸lua_State/QJSEngine无需链接整个流水线core/Pipeline/DataModel/Scripting/LuaCellCollector.hLuaCellCollector::collect(lua_State*, ScriptCellRows, maxElements)。标量或扁平 table → 一行table 的 table二维表→ 每个内层 table 一行混合形状返回false走列表路径core/Pipeline/DataModel/Scripting/JsCellCollector.hJsCellCollector::collect(const QJSValue, ScriptCellRows, maxElements)。扁平数组 → 一行二维数组 → 每内层数组一行JS 中true/null等非数字非字符串值通过toString()作为文本单元格处理与今天true/null的字符串化结果保持一致非数组或混合结果返回false。两个收集器都只遍历结果一次首个元素决定扁平还是嵌套不匹配时在同一次遍历中直接拒绝避免二次扫描。Lua 引擎侧的接线在 core/Pipeline/DataModel/Scripting/LuaScriptEngine.cppparseUtf8Cells约 L821运行parseLuaText的 pcall 后调用收集器m_referencesTableApi在loadScript中通过ScriptApiCall::referencesTableApi(script)设置约 L595。数字文本格式化规则R5与旧路径逐字节一致计划中最重要的兼容性约束是 R5当一个数字单元格必须变成显示文本时仪表盘值、API 帧、导出文本必须与今天产生的完全一致。两种引擎各有一套规则见 plan 的 Formatting rules (R5) 一节均已在 ScriptCells.cpp 中实现为formatLuaNumber与formatJsNumberLua 规则formatLuaNumber整数值 →QString::number(lua_tointeger)即%lld其他 →QString::number(v, g, 15)即 C locale 下的%.15g非有限值沿用 Qt 拼写nan无符号、inf、-inf常规路径用std::to_chars(out, out capacity, value, std::chars_format::general, 15)复现%.15gApple 旧平台回退到snprintf_l。注意整数检测复用 LuaJIT 兼容层的lua_isintegershimLuaJIT 用 double 表示整数保证整数值不带小数部分输出。JavaScript 规则formatJsNumber目标是精确复现 ECMAScriptNumber::toString即QJSValue::toString()对数字的输出std::to_chars取**最短往返shortest round-trip**数字布局规则按 ECMA-262 6.1.6.1.201e-6 ≤ |x| 1e21用十进制形式0.000001而不是1e-06范围外用指数形式1e21、1e-7特殊值NaN、Infinity、-Infinity、-0 → 0。实现里对应常量kJsFixedUpperExponent 21、kJsFixedLowerExponent -6指数形式写作d[.ddd]e[-]N且无零填充。选择这套方案的原因记录在 plan 的 Tradeoffs 表中QJSValue::toString()本身就是被移除的分配点而 Qt 的FloatingPointShortest在指数边界如0.00001vs1e-05与 JS 不一致会破坏 R5。formatJsNumber还包含一个针对 Apple 13.3 之前平台的零分配回退实现snprintf_l精度搜索 strtod_l往返校验。格式化产生的文本写入 scratch因此数字单元格同时携带double值与显示文本单元格携带的文本与旧QStringList完全相同而帧构建器的 writer 直接从单元格取数字不再把文本解析回去。捕获作用域R6 / R7只在被引用时开启表格捕获这是本计划中用户可见规则变化最大的部分。表格捕获m_captureDatasetValues的输入从存在 Lua 解析引擎变为某个引擎的源码引用了表格 API 名称判定方式是在loadScript/ 变换编译时做编译期词扫描由头文件实现 core/Pipeline/DataModel/Scripting/TableApiScan.hstatic const QRegularExpression s_tableApiName( QStringLiteral(\\b(?:tableGet|tableSet|tableHandle|tableHandleMany|tableGetH|tableSetH| datasetGetRaw|datasetGetFinal|__ss)\\b)); return !source.isEmpty() s_tableApiName.match(source).hasMatch();对九个名称八个辅助函数 JS 桥接对象__ss做词边界匹配。它是刻意保守的注释或字符串字面量里的名称也会开启捕获每帧多付出几个百分点而备选的运行时首次触达标志会丢掉第一帧的值。各输入源的变化plan 的 Capture scoping 表输入之前之后解析引擎m_hasLuaEngine存在任何 Lua 解析器任何引擎源码引用表格 API 名称FrameParser::refreshEngineCachesepoch 照常递增变换引擎hasScriptEngines()任何变换或共享库源码引用表格 API 名称流变换注入即开启从不关闭被引用才开启worker 拆除时关闭外部用户粘性bool任何injectTableApi*设置项目加载时清除int计数控制脚本启停、API 服务器启停、表格视图开关、发送环境外部用户侧FrameBuilder用m_externalTableUsers计数core/Pipeline/DataModel/FrameBuilder.cpp配合armExternalTableUser()/disarmExternalTableUser()约 L2832 / L2888与TableApiUserLeaseRAII 封装。选择计数而非布尔的原因记录在 Tradeoffs 表R7 要求关闭一个用户后停止捕获布尔无法表达两个用户同时存在。实际落地的命名是injectTableApi*/releaseTableApiUser()--。新鲜度保证R7epoch 与计数都汇入既有的m_captureFlagsDirty → refreshDatasetCaptureFlag()重新推导路径在 builder 线程上执行遵守 spec-0051 的双线程刷新规则刷新槽是 pipeline-affine 的由 GUI 发射器排队因此捕获标志永远不会过期——脚本编辑使引用开始/停止后下一帧即生效。GUI 侧用户的 arm/disarm 通过injectTableApi*已使用的invokeOnBuilderThreadBlocking封送执行不引入任何新的跨线程信号/槽。表存储写入R8原地赋值与槽位缓存当捕获开启时把 dataset 值写入表格必须零分配R8。计划针对DataTable的两处改动setDatasetRawAt/setDatasetFinalAt用assign_string_in_place(rv.stringValue, str)替代 share-assign。这同时解决两个问题移除 profile 中可见的分配并且不再把dataset.value的缓冲区钉住——这正是 doc/claude/common-mistakes.md 中share-assign 重新链接缓冲区的反模式下一次原地写会先 detach 再重新分配。原地写之前仍保留等值检查因此依赖值未变则不写的 change-driven 变换跳过spec-0083 时代语义不变槽位缓存每 dataset 的槽位对缓存在FrameBuilder::m_datasetTableSlots按 dataset 序号索引initializeTableStore时重建替换每帧每 dataset 两次QHash::constFind。实际落地按 review 修正简化为每帧每 dataset 一次datasetSlots()查找。帧级 writer 的共享尾部是applyDatasetToken评审修正后不再是策略模板applyDatasetValueCell约 L2188与 span 车道的applyDatasetValueSpan共享从原始值复制、捕获、变换、表达式发布到最终捕获的全部后续逻辑。数值取用规则numericValue cell.kind Number ? cell.number : SerialStudio::toDouble(cell.text, isNumeric)数字单元格的isNumeric恒为true。热路径与线程影响计划明确标注了该改动触及热路径并列出必须遵守的规则一切在pipeline 线程执行引擎只在该线程使用ScriptCellRows是 builder 成员永不跨线程稳态下 cell 车道对纯数字结果Lua零分配JS 保留每单元格QJSValue临时值见下列表路径原样保留为回退dataset.value保持assign_utf8_in_place存储端字符串复制改为原地移除拖累 span 车道的 share-assign路由 lambda 内不允许出现lua_*或QJSValue调用扫描在loadScript于引擎自身线程执行单元格收集在既有 parse 调用内部执行structureGeneration戳记不变cell 车道与列表路径一样经由m_stager.stage入队时间戳归属不变行以data-timestamp step * row打戳。FrameParser侧新增parseCellsUtf8镜像parseMultiFrameUtf8的引擎 0 缓存路径且Native 引擎在不运行的情况下直接拒绝因此被拒的 Native 帧只需走一次列表路径而不是三次review 修正。基准计划--benchmark-hotpath前后对比Lua 数值、JS 数值、Lua 混合、JS 混合的 FPSspec-0084 的每帧分配列Lua 数值目标 0JS 记录其下限。权衡与替代方案Tradeoffs 摘要计划用一张决策表记录了每个关键取舍决策备选选择及理由结果表示(a) 字节视图单元格(b)QVariantList(c)std::vectorstd::variantdouble, QString(a)复用 span writer 及其原地 UTF-8 赋值稳态零分配文本单元格正是 Native 车道已消费的形式。(b)/(c) 每单元格或每字符串分配数字显示文本惰性按需 vs 急切写入 scratch急切保持 spec 0055 D6 契约不变使 R5 成为纯格式化等价性测试惰性属于未来的 display-text 规范JS 数字文本(a)QJSValue::toString()(b) QtFloatingPointShortest(c) ECMAScript 兼容格式化器(c)a 正是被移除的分配b 在指数边界与 JS 不一致0.00001vs1e-05破坏 R5JS 每单元格临时值(a) 接受并单独记录 JS 下限(b) 用 typed array 打包一次读回(a)QJSEngine无零拷贝 typed-array 读取b 仍要经过QJSValueR2 对 Lua 满足JS 的收益是移除格式化/解析往返表格 API 引用检测编译期词扫描 vs 运行时首触标志扫描保守、无首帧缺口且与发送环境区分ArmCapture/NamesOnly的方式一致外部用户粘性布尔现状vs 带 disarm 的计数计数R7 要求关闭用户即停止捕获布尔无法表达两个用户存储字符串写share-assign现状vsassign_string_in_place原地移除分配与缓冲区钉住等值 no-op 检查不变cell 车道解码器覆盖仅 PlainText vs 全部解码器PlainText 先行门控层级是 PlainTextBinary/Hex/Base64 脚本保持列表路径作为命名后续项风险与缓解格式化漂移Lua 与 JS 数字文本必须与现状逐字节一致否则导出与仪表盘会无声变化。对策是两套语料测试Lua同一测试内用QString::number对照JSNode 生成的 fixtureQJSValue::isNumber与旧toString的差异JS 的true/null今天会字符串化为true/nullcell 车道通过把非数字非字符串值按toString()处理保持相同行为扫描漏报通过local g tableGet别名访问仍含名称用_G字符串拼接构建的脚本检测不到已在 transform_lua.md / transform_js.md 中说明运行时桥接在首次调用时也会开启捕获作为安全网仅病态场景有一帧缺口漏掉 disarm 点后果只是捕获保持开启即现状行为绝不会在需要时关闭任务阶段逐一枚举每个injectTableApi*/noteGuiUser调用点配对共享的可静默破坏类别common-mistakes.md缓存标志输入缺刷新线路两个输入都已接线并由 AC5/AC6 测试、span 车道上的 share-assign正在移除而非新增、新模板产生的QListQStringListcell 车道即替代品列表路径仅作回退、JS 的guardedCall不变。评审阶段qt-cpp-review还修复了一批具体缺陷applyProjectSnapshot不再清零m_externalTableUsers租约应活得比一次库编辑更久阻塞式 arm 在 worker 循环被QThread::quit()展开时会被runOnObjectThread跳过导致后续 release 击穿零值触发 debug 断言——因此两个 arm 与 release 都改为排队投递splitScientific对指数用有界解析避免越界读ScriptCellRows::clear()释放高水位以上的容量~Output::Base仅在 surface 已准备m_sourceId 0时释放租约。测试与验证体系计划的验证分为四层测试文件均已落在仓库中单元测试ctestapp/tests/tst_script_cells.cpp 直接驱动裸lua_State/QJSEngine上的收集器链接集只含 LuaJIT 与QJSEngine不拉入整个流水线覆盖AC3Lua/JS 混合行{1, 2.5, x, 7}的每单元格kind、number、text与列表路径产物相等且与等价分隔文本喂给 Native span 车道的数值探测一致AC4二维结果的行数、顺序、值等于列表路径混合标量/向量结果回退parseUtf8Cells返回falseR2Lua 数值结果连续解析 1000 次用 TU 局部operator new计数器在首次解析后武装断言零分配分配探测还检查 scratch、单元格数组与存储注册缓冲区的地址稳定性因为 Qt 容器与 LuaJIT 在operator new之外分配R5formatJsNumber对照 tests/fixtures/js-number-format.json 语料Lua 格式化用例在同测试内对照QString::number。语料生成tests/scripts/gen_js_number_corpus.pyNode 的String(x)对边界值与随机 double 生成与 tests/scripts/test_js_number_corpus.pypytest 断言提交的 fixture 与生成器输出一致集成测试API 服务器运行中test_table_capture_scoping.py覆盖 AC5/AC6——仅解析器的项目在 10 秒内datatables写入时钟保持初值加入调用tableGet的控制脚本后首帧即开始推进变换中增删tableGet在一帧内反映/停止。实际可观察点是project.dataTable.getValue对__datasets__/raw:id的读取非武装读者而非不存在的写时钟 verb实现偏差一节静态与维护工具python scripts/code-verify.py --check覆盖所有改动文件热路径 TU 阻塞违规、qt-cpp-review审引擎与FrameBuilder.cpp/DataTable.cpp改动块、提交前sanitize-commit.py、文档编辑后claim-verify.py。AC1 由--benchmark-hotpath前后对比把关AC7 由导出保真与回放集成测试把关。结语Spec 0086 是 Serial Studio 脚本解析热路径的一次系统性优化类型化单元格R1、稳态零分配R2、文本等价R3/R5、多帧结果兼容R4、按引用开启的表格捕获R6/R7与零分配捕获写入R8八项需求通过一条位于 span 车道与列表回退之间的新通道落地。从设计文档到 ScriptCells.h、TableApiScan.h、FrameBuilder.cpp 等实现再到 tst_script_cells.cpp 与集成测试方案的每一处取舍都有源码级证据可循。对希望深入 Serial Studio 数据流水线或在其上扩展解析器的开发者而言这条 cell 车道是理解项目性能与正确性并重工程风格的最佳入口之一。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
