Serial Studio 工作区设计实战指南从铺满仪表盘到精炼操作视图【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio导读Serial Studio 的仪表盘不是把每个数据组都铺成一块瓷砖而是一张经过编排的操作界面——它存在的唯一目的是让操作员在 1 秒内回答系统现在是否正常。本文以app/rcc/ai/skills/workspace_design.md这份 AI 技能文档为骨架结合仓库源码与dashboard_layoutAPI 细节讲解工作区的 Tab 组成、内容取舍优先级、瓷砖的空间摆放Peak-End 规则、按认知任务选组件、无障碍设计键盘/焦点/色彩、autoGenerate 后的精修流程、多角色 Profile 视图以及高频错误清单帮助你构建一个少而准的遥测仪表盘。先理解仪表盘的唯一 KPIworkspace_design技能文档开宗明义dashboard 的存在是为了快速回答一个问题——系统此刻是否正常运行其他一切都是次要的。这份技能文档覆盖的是你在调用addWidget之前的设计判断而调用层面的 API 细节slugs、枚举、min/max 配对、addWidget 预检由配套的 dashboard_layout 技能文档负责。两者分工明确dashboard_layout回答怎么把一个瓷砖放到工作区上API 层面workspace_design回答这个瓷砖到底该不该放、放在哪、用什么组件放设计层面。当用户说帮我整理仪表盘或建一个总览他们要的是一个经过策划的布局而不是把每个分组都丢一块瓷砖上去。这也是本文的核心立场策划curation先于生成generation。Tab 组成工作区 N 该放什么一个工作区在用户开始翻页找数据之前应该容纳5–9 块瓷砖。这来自米勒定律Millers Law人的短期记忆只能稳定保持 5±2 个条目超过这个数量操作员就会从阅读退化为扫视。因此瓷砖数量是预算budget不是目标target三块精挑细选的瓷砖胜过七块差强人意的瓷砖。多系统项目的默认工作区分层建议工作区用途瓷砖数Overview总览系统是否正常只放顶层 KPI 与告警4–6Subsystem子系统每个主要子系统一个Engine、Battery、Comms……5–8Diagnostics诊断原始标志位、调试信息、单个传感器、状态网格6–10Signal Analysis信号分析FFT / Waterfall / Plot3D一次只看一个信号2–4从源码结构看这个分层与 Serial Studio 的自动生成工作区 ID 约定相呼应1000是自动 Overview、1001是 All Data、1002gid是每个分组的自动 Tab、 5000是用户自建工作区见 dashboard_layout 的 Resetting / starting from scratch 一节。Overview 是使用频率最高、被编辑频率最低的工作区。把它当成报纸的头版每一块瓷砖都在争夺版面。这意味着Overview 上的每个组件都必须通过内容优先级四问的考验见下一节原始标志位和调试信息一律推到 Diagnostics宁可少放不可多放。内容优先级什么能上 Overview对每一个候选分组按顺序问四个问题它出错时操作员能否在 1 秒内察觉能就上 Overview电压越界、温度尖峰、通信故障。这个值是连续漂移还是离散跳变连续 → 时间序列组件Plot / Gauge / Meter / Bar离散 → 读数组件DataGrid / LED / 通知。脱离上下文这个值还有意义吗单独的 RPM 没有意义——必须配红线而荷电状态State-of-Charge单独就有意义。无上下文的数值需要配对参考画一条红线或者把widgetMin/widgetMax设为运行边界operating bounds而不是传感器量程sensor bounds。这是原始标志位还是派生状态二十个独立的刹车压力属于 Diagnostics派生的制动系统正常/故障LED 才属于 Overview。如果一个分组在问题 (1) 和 (4) 上不通过它就不属于 Overview——推到它的子系统工作区或 Diagnostics。要顶住用户全都展示出来的冲动布局一旦建成这句话就很难收回。这一条在源码层面同样有印证dashboard_layout的Building an executive / overview dashboard一节明确要求跳过原始标志位分组门开关、独立灯光、独立刹车压力它们属于专用诊断工作区。空间布局第一块和最后一块瓷砖最重要峰终定律Peak-End rule同样适用于仪表盘操作员对一次观察会话的记忆由最醒目的那块瓷砖和最后看到的那块瓷砖锚定。利用这一点左上角瓷砖LTR 语言环境下的第一扫描位置是最重要的阅读点。放主 KPI速度、总功率、活动告警数。不是装饰。右下角瓷砖是操作员离开前最后看到的东西。放一个系统状态摘要告警数、连接健康度、当前运行模式让它成为离别印象。中间瓷砖承载支撑性的时间序列。这些是被扫而不是被吸收的不需要像四角那样自解释。排序由relativeIndex控制。不关心顺序时可以省略它API 会自动分配但当四角位置至关重要时必须显式传入。关于relativeIndex需要特别澄清一个常见误解它是跨整个项目、按组件类型分桶的全局索引不是工作区内的局部计数器。从 WorkspacesHandler.cpp 的实现可以看到API 会按项目的分组顺序遍历根据groupId即Group.uniqueId和可选的datasetId自动计算出正确索引并在响应中返回relativeIndex与relativeIndexAutoAssigned: true。显式传入整数是脆弱的后续任何结构变更都会使旧值失效仅在从导出文件还原手工布局时才需要。因此日常操作一律省略relativeIndex。组件选择匹配认知任务而不是匹配数据类型用户不是在挑组件而是在决定操作员将如何读取这个值。把任务映射到瓷砖而不是数据集类型操作员任务最佳组件原因X 在范围内吗是/否LED、带色带的 Gauge在带内的位置感比数字更直观X 现在是多少精确值DataGrid、Gauge 数字页数字无歧义X 在上升还是下降Plot趋势就是全部意义频率成分是什么FFT、Waterfall时间序列会掩盖结构比较 X 与 Y、Z、WMultiPlot、Bar并排胜过四个单图X 在 3D 空间中的哪里Plot3D、GPS空间感胜过坐标三元组X 是否越过了阈值NotificationLog事件是事件不是样本两个典型反例用 Gauge 显示精确值是错误选择指针只能读到 ±5% 精度数字读数可以精确到最后一位。Bar / Gauge / Meter 在 Serial Studio 中渲染为双页滑动视图——第 0 页是模拟表盘第 1 页是等宽字体的大号数字读数用widgetMin/widgetMax稳定数值框尺寸用户滑动切换激活页按组件实例持久化Cpp_JSON_ProjectModel.saveWidgetSetting(widgetId, page, N)。所以Gauge 看趋势、DataGrid 看精确值才是正确分工。用 Plot 判断X 此刻是否在范围内是错误选择操作员必须扫一条线再和边界做心算比较。选组件时还要记住dashboard_layout的兼容性机制每个分组/数据集只兼容一部分组件类型compatibleWidgetTypes数组由分组自身的 widget shape与数据集逐项可视化选项两者并集动态计算而来是派生状态而非配置——你永远不能直接写它只能通过修改输入分组 widget 数据集选项后再读回来。无障碍键盘、焦点、色彩Serial Studio 运行在操作员工作站上那里的鼠标有时是被禁用的戴手套、面板安装、无障碍需求。因此工作区可从任务栏进行 Tab 导航组件焦点遵循 DOM 顺序这与relativeIndex顺序一致。按使用频率从左到右排列工作区第一个 Tab 是操作员最常碰的。不要把 Diagnostics 放第一位。按阅读顺序排列工作区内的组件Tab 键按relativeIndex顺序遍历它们不要把最重要的组件放在 Tab 循环的最后。色彩永远不能作为唯一信号一个只靠红/绿区分的 LED 告警瓷砖对约 8% 的男性操作员红绿色盲是不可见的。必须搭配文字ALARM 标签、形状实心 vs 描边或位置LED 从normal区移动到alarm区。theme.alarm适合用于强调不能作为唯一信号。不要剥离单位数据集的.units字段会渲染在使用它的每一块瓷砖上不要为了更干净的观感而用空字符串覆盖它。一个没有单位的数字让操作员只能靠猜。不要自动生成完就撒手project.workspace.autoGenerate{}生成的是一个合理起点布局每个分组一块瓷砖、每个数据集一个默认组件。它是一发式的起点不是终点。从源码看ProjectWorkspaces::autoGenerateWorkspaces() 会调用buildAutoWorkspaces()构造默认布局、重建工作区文件夹、强制打开定制模式并标记项目已修改同时它也保留了一个防御逻辑——如果定制模式已开启且工作区非空直接返回现有列表不会覆盖用户布局。所以先 autoGenerate、再手工精修是安全的工作流。autoGenerate 之后必须做的四步读project.workspace.list看看什么落在了哪里。用上面的优先级规则找出属于 Overview 的 4–6 块瓷砖移动它们或从零重建 Overview 工作区。把原始标志位和调试分组从 Overview 推到 Diagnostics。在推送之前把策划方案展示给用户列出工作区、每个工作区上的瓷砖以及理由Overview 放了您提到的四个 KPIDiagnostics 承载 18 个独立刹车传感器这样它们不会挤占头版。配套 API 的完整从零搭建总览仪表盘路径见 dashboard_layout 的 Building an executive / overview dashboard 一节先project.group.list读取每个分组的datasetSummary与compatibleWidgetTypes挑选 4–8 个真正与摘要相关的分组为每个挑选最易读的组件类型Gauge 配wgtMin/wgtMax、MultiPlot 配pltMin/pltMax、LED 用ledHigh阈值……绝不用widgetType0Terminal推送前在聊天里展示计划并附带每个数据集要设置的 min/max 范围最后setCustomizeMode{enabled: true}→workspace.add→ 逐项dataset.updateaddWidget再用project.dataset.getByPath回读验证。Profiles一个项目多种操作员视图当一个项目服务于多套设备或多类角色时不要 fork 项目。工作区 Profile规格见 WorkspaceProfile.h用名字记录某个视图要显示哪些工作区文件夹和游离工作区其余部分留在项目中、保持隐藏。关键 API 已在 WorkspaceProfileHandler.cpp 中注册project.workspace.profile.list读取所有 Profileproject.workspace.profile.add新建 Profileproject.workspace.profile.update{profileId, folderIds, workspaceIds}更新一个 Profile 引用的文件夹与工作区集合底层 ProjectWorkspaceProfiles.cpp 支持按 title 大小写不敏感解析以及逐个增删 folderId / workspaceIdproject.workspace.profile.remove移除 Profileproject.workspace.profile.select{title}按标题切换仪表盘视图。启动时还可以用命令行参数--profile title直接指定CLI 选项定义于 CLI.hOpens the project under the named workspace profile (see --project)在 CLI.cpp 中通过projectModel.setRequestedWorkspaceProfile(...)生效。瓷砖按分组和数据集身份存储因此隐藏文件夹永远不会改变可见瓷砖所展示的内容——Profile 切换只是换了一组可见的工作区集合不会破坏任何瓷砖绑定。这使一台测试台、三套操作角色成为可能一套 Operator 视图只看 KPI 与告警一套 Engineer 视图加挂全部诊断 Tab。常见错误清单workspace_design文档给出的高频错误每一项都能在实操中直接对号入座把所有东西都钉在 Overview 上——因为 autoGenerate 这么做了删掉显得不礼貌。要狠下心裁剪。一个嘈杂的 Overview 就是失败的 Overview。给每个数值数据集都选 Gauge——因为看起来像仪表盘。Gauge 只适合有界标量 位置感有意义的场景。带红线的 RPM是总里程表读数不是那该用 DataGrid。一个工作区放多个 FFT——FFT 很占横向空间而且操作员一次只能读一个频谱。把每个 FFT 放到独立的 Signal Analysis Tab或用 Waterfall 对时间维度做汇总。Gauge 和 Bar 不设 min/max——它们会渲染出来但显示空指针 / 平直填充。参见dashboard_layout的 min/max 章节wgtMin/wgtMax是必填的写入侧参数名。这里要特别强调dashboard_layout揭示的三对互相独立的 min/maxPlot 用pltMin/pltMaxY 轴、Gauge/Bar/Compass/Meter 用wgtMin/wgtMax表盘/填充刻度、FFT/Waterfall 用fftMin/fftMax期望的原始输入幅值范围用于在加窗变换前把时域信号归一化到 [-1, 1]dB Y 轴本身是写死的。它们不会级联——一个同时驱动 Plot 和 Gauge 的数据集必须两个配对都设否则其中一个渲染成 0..0。写入侧用缩写形式pltMin读回时用完整形式plotMin且必须setOptions之后、addWidget之前设置。跨工作区重复钉同一个 KPI——同时钉在 Overview 和子系统 Tab 上感觉很保险但会训练操作员无视 Overview我直接看子系统 Tab 就行了。每个读数只选一个家跨工作区用切换而不是复制。跳过策划方案直接推送——静默推送瓷砖、事后才问看起来还行吗等于强迫用户撤销你的工作来纠正方向。先展示方案。结语把展示一切翻译成回答一个问题工作区设计本质上是信息架构决策你为操作员回答系统现在是否正常编排了一条最短阅读路径。策划curation先于生成generation优先级过滤先于平铺认知任务先于组件外观键盘可达先于视觉装饰。配合 dashboard_layout 提供的 API 细节slug 优先于整数枚举、三对 min/max 配对、relativeIndex全局自动分配、setCustomizeMode前置、变更后回读验证你就能在 Serial Studio 中交付一个少而准的仪表盘——而不是一面铺满瓷砖的墙。如需把这份方法论落成可执行的端到端流程可继续阅读 dashboard_layoutAPI 与配方、api_semantics命令别名与语义以及本技能所在目录下的其他 AI 技能文档 skills。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
