Serial-Studio Problem Center 实现拆解：从 19 项任务清单看诊断中心、1 Hz 采样与 API 暴露的完整落地（spec 0033）

Serial-Studio Problem Center 实现拆解：从 19 项任务清单看诊断中心、1 Hz 采样与 API 暴露的完整落地（spec 0033）

【免费下载链接】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 0033（Problem Center，项目 + 链路诊断）的第三阶段任务清单doc/claude/specs/0033-problem-center/tasks.md展开：逐项解读 19 个可独立验证的实现任务及其完成状态，结合当前仓库中的真实源码与测试文件，说明这套"检测器注册 + 1 Hz 轮询 + 全量切片替换"的诊断架构是如何从设计走到可验收代码的。读完后你能掌握：如何为大型 Qt/QML 应用设计一个"发现问题—聚合展示—一键跳转—API 暴露"的诊断子系统，以及该仓库如何用它自己的脚本化验证工具把每个任务的完成状态钉死。

一、tasks.md 在项目文档体系中的位置

Serial-Studio 采用四阶段规格驱动流程（spec → plan → tasks → implement），tasks.md是其中的Phase 3 of 4：把plan.md中"怎么做"的技术设计，拆分为小的、有序的、每一项都能独立验证的变更单元。同一目录下的三份文档构成完整脉络：

• spec.md：需求与验收标准（AC1–AC10）；
• plan.md：技术设计，含受影响文件清单与数据流图；
• tasks.md：19 项有序任务清单（T1–T19），执行者按序推进并保持状态勾选。

文档头部 frontmatter 标注status: approved（gate 已过，全部 19 项任务完成，updated: 2026-07-25）。值得注意的是：tasks.md 中各任务的文件路径写的是当时的app/src/...布局，而当前仓库已经过目录重组，C++ 源码主体位于core/下（如app/src/Misc/ProblemCenter.h现为 ProblemCenter.h）。本文引用路径以当前仓库实际位置为准，并在第五节给出对照表。

二、任务编写约定（Conventions）

tasks.md 在任务列表之前定义了五条约定，这些约定本身就是该仓库工程规范的一部分：

1. 一个任务 = 一个聚焦的、可独立评审的变更。若一个任务要动超过 3 个文件，或需要一整段话才能描述清楚，就拆分；
2. Verify 字段是该单元的确认方式——通常是python scripts/code-verify.py --check <files>，辅以测试或回读代码；
3. Deps 字段列出必须先落地的任务 ID，形成拓扑顺序；
4. 排列顺序保证树在概念上每一步之后都能编译；
5. Agent 不构建、不运行应用、不跑维护者专属步骤（T18 的--dump-api-schema、--benchmark-hotpath和 live-API pytest 文件由维护者执行）。

每条任务都带一个勾选框（[x] done）和完成后的补充说明，相当于把"实施结果"直接回写进了清单，使得这份文档同时是任务书和完工记录。

三、核心类型与模型：T1/T2 如何建立 ProblemCenter

T1 — ProblemCenter 核心类型 + 模型

T1 引入Misc::ProblemCenter（QAbstractListModel单例），它是整个特性的中枢。当前实现位于 ProblemCenter.h，与任务描述一一对应：

• Severity枚举（Info = 0, Warning = 1, Error = 2，与NotificationCenter::Level对齐）和Trigger位掩码（ProjectChanged = 1, LinkSample = 2, OnDemand = 4），见 ProblemCenter.h#L71-L83；
• Finding结构体：severity、entityUniqueId（无实体时为 -1）、code（稳定子 ID，如duplicate-frame-index）、title、explanation、remedy、checkerId、jump（""、"dataset"、"group"、"action"、"source"或"settings/<page>"），定义在 ProblemCenter.h#L101-L112；
• registerChecker(id, triggers, fn)注册检测器，Checker是std::function<void(QList<Finding>&)>；
• errorCount/warningCount/infoCount/totalCount四个 Q_PROPERTY加lastRunTime，全部以findingsChanged为 NOTIFY 信号，供 QML 面板与任务栏徽标直接绑定，见 ProblemCenter.h#L53-L67；
• runNow()、activate(row)：activate解析行对应的jump字段并发出jumpRequested(kind, uniqueId)信号（见 ProblemCenter.h#L116-L119）；
• 按检测器切片的全量替换 + 相等性比较：一次运行只重建某个 checker 的连续切片；拍平后的整体列表与上一轮逐字段比较，只有真正变化时才触发一次beginResetModel/endResetModel——这是为了避免 1 Hz 轮询在模型未变时每秒重绘面板。

T1 有一条硬性设计约束：构造函数必须"惰性"（inert）——只做成员初始化，不调用instance()、不connect、不建定时器、不碰 QSettings，头注释里写清原因（对应 spec 0001 的 ctor-edge proof）。当前文件头部注释仍然保留这一说明（ProblemCenter.h#L44-L49："The constructor is deliberately inert... everything is wired in setupExternalConnections()"）。T1 的完成记录确认：零外发调用边的构造函数、仅在拍平列表变化时重置模型、每次运行对新增 finding 只发一次聚合通知。

T2 — 接入组合根

T2 把新模块焊进启动序列，改动 ModuleManager.cpp 与 CMake：

• 在instantiateCoreModules()中紧跟NotificationCenter之后加(void)Misc::ProblemCenter::instance();；
• 在setupCrossModuleConnections()中先于appState->restoreLastProject()调用ProblemCenter::instance().setupExternalConnections()（保证恢复项目时 ProjectModel 的变更信号已被订阅，不丢第一次触发）；
• 在registerCoreContextProperties()注册Cpp_Misc_ProblemCenter上下文属性——这正是 QML 里所有Cpp_Misc_ProblemCenter.xxx绑定的来源；
• setupExternalConnections()连接 ProjectModel 变更信号与Misc::TimerEvents::timeout1Hz，并把每次运行的摘要发给NotificationCenter。

任务完成记录特别强调顺序约束（注册必须先于restoreLastProject()）已回读确认，且 spec-0001 的 ctor-edge proof 对新节点重跑通过：零构造期外发边。

四、三类内置检测器：T3–T9

任务把"什么算问题"的知识全部收敛到三个 checker 文件中，ProblemCenter 本体对它们一无所知。当前源码位于 core/Ui/Misc/Problems/。

T3 — 项目 schema 检测器（spec R8）

ProjectCheckers.cpp 实现并注册了 spec R8 的完整检查集，覆盖五类 finding（完成记录中的命名）：

实现要点（全部回读确认过）：每个 finding 设置entityUniqueId与jump；所有索引/引用检查都以sourceId为作用域（跨源比较会产生假阳性）；没有项目文档（QuickPlot / 纯 Console 场景）时提前返回；每个切片封顶 50 条，超出追加一条 "and N more"。注册触发器为ProjectChanged | OnDemand。

T4/T5 — 让链路统计"可被拉取"

这是整套设计里最值得学的部分：热路径上不加信号、不加锁，只加四个无条件的整数自增。

• T4 在 FrameReader.h 中加入四个普通quint64计数器m_bytesIn、m_framesExtracted、m_checksumErrors、m_totalOverflowBytes，配[[nodiscard]]访问器（与既有的droppedFrameCount()并列）和一个组合 reset。自增点全部落在已存在的分支内：processData的 chunk 计字节、noteDroppedFrame旁的帧计数、ValidationStatus::ChecksumError分支、以及既有resetOverflowCount()调用之前的溢出累加（旧代码在那一行把数字销毁了）。顺带修复了一个既有缺陷：把未限流的逐次校验和qWarning限流到noteDroppedFrame已使用的 5 秒模式——这是整个特性唯一被允许"顺手改"的相邻修复，且必须在提交信息中点名说明。
• T5 解决可达性问题：DeviceManager的m_frameReader原本是私有的且无访问器，链路统计根本拿不到。于是给 DeviceManager.h 加[[nodiscard]] FrameReader* frameReader() const noexcept（reconfigure 到 open 之间返回空），给 ConnectionManager.h 加[[nodiscard]] LinkStats linkStats() const汇总所有设备（LinkStats是一个小型 POD：字节入、提取帧、丢弃、校验和错误、溢出字节）。只在 1 Hz 被调用——无缓存、无信号、帧路径上零调用点。

T6 — 链路检测器：差值语义与抑制

LinkCheckers.cpp 实现 spec R9，且必须对上一拍快照求差值而不是绝对总量，因为重连会重建FrameReader并清零计数器——从源码结构看，任何计数器"减少"都意味着 reader 被重建，此时应当重新定基（rebase）而不是算出负速率。完成的link.statistics检测器包含这些行为：

• 检查项：持续窗口内收到字节但提不出帧；提出帧但解析数为零；校验和失败率超阈值；帧队列丢弃；环形缓冲溢出；
• 播放器抑制：回放（replay）绕过FrameReader，检测到任一 player 打开（SerialStudio::isAnyPlayerOpen()）或链路关闭时自我抑制；
• 采样节流：采样器最多每 500 ms 推进一次，防止problems.run的按需重跑把"持续窗口"折叠掉；
• 文本稳定性：所有计数按数量级分桶（decade bucket）、校验和率用粗粒度区间报告——条件不变时 finding 文案不变，模型才不会反复重置。

触发器为LinkSample | OnDemand。

T7/T8/T9 — 脚本错误检测

• T7 给 IScriptEngine.h 接口加errorCount()、lastError()、consecutiveTimeouts()、disabled()、resetErrorStats()。关键约束：接口保持非 QObject（纯虚函数），JS 与 Lua 引擎在已经拼接错误消息串的既有分支里记录m_errorCount/m_lastError（成功路径零分配）；Native/CFrameParser继承默认的零/空实现（完成记录提到CFrameParser::lastError()因此补了override）。
• T8 在 FrameBuilder.h 加m_transformErrors、m_lastTransformError、m_lastTransformDatasetUniqueId，计数器在既有 transform 错误分支自增；消息串只在失败的数据集与上次记录的不同时才捕获——一个每帧都抛错的 dataset 只分配一次，而不是每帧一次。FrameParser::scriptStats()则遍历各 source 的引擎输出QList<ScriptStat>。
• T9 的 ScriptCheckers.cpp 注册script.parser（按 source：被 watchdog 禁用的引擎报 Error，反复失败报 Warning）与script.transform（逐数据集失败，可跳转到该数据集），同为LinkSample | OnDemand，计数分桶、保留原始错误文本。

五、暴露面：API、Assistant、命令面板与 UI（T10–T17）

T10/T11 — 只读 Problems API handler

ProblemsHandler.h 是一个无状态、静态注册的 handler（双许可 SPDX，GPL 侧可用），提供三个命令，schema 用API/SchemaBuilder.h构建，形状对齐ScriptsHandler，所有结果带尾部hint字符串约定：

T11 在 CommandHandler.cpp 的initializeHandlers()GPL 块中加#include与Handlers::ProblemsHandler::registerCommands();（回读确认位于#ifdef BUILD_COMMERCIAL之前），并明确不把任何名字加入destructiveCommandSet()——纯读命令不应被破坏性保护机制标记。

T12 — Assistant 安全分层

command_safety.json 要求每个已注册命令恰好落在一个安全层级；未标注的名字会解析成Confirm，导致只读调用也弹确认。因此三个命令名按字母序加入"safe"数组（当前文件 L92-L94 可见三者都在 safe 层），并在 ToolDispatcher.cpp 的scopeDescriptions()加problems顶层 scope 描述，否则meta.listCategories会给它一个空 blurb。

T13/T15 — 静态测试与命令清单绑定

• T13 的 test_problem_center_static.py 是agent 可运行的静态测试：断言三个命令在 safe 层且不在其他层、C++ 注册位于 GPL 块、无BUILD_COMMERCIAL守卫、存在 scope 描述、未进入destructiveCommandSet()。完成记录：7 项全绿（后由 T15 扩到 10 项）。
• T15 在 app.json 加app.problems清单条目（kind: "action"、contexts: ["app","dashboard","editor"]、category: "tools"、icon: "notifications/warning"——该图标已带全四个层级，无需新 SVG、无需改 rcc.qrc），当前条目位于 app.json#L174；对应的map行与QtObject写入 AppCommandBindings.qml（"app.problems" 绑定见 L57）与ProjectEditorCommandBindings.qml，镜像app.helpCenter的写法；并重跑generate-command-strings.py同步字符串（顺带收编了 spec-0031 的 Undo/Redo 待处理字符串、清掉一条陈旧 "Recover" 条目）。

T14/T16/T17 — 窗口、任务栏指示器与跳转导航

• T14 的 ProblemCenter.qml 是Widgets.SmartWindow { category: "ProblemCenter" }面板：ListView直接绑定Cpp_Misc_ProblemCenter，展示严重度图标、标题、解释、修复建议，jump !== ""时出现 "Go To"，另有严重度过滤器、刷新按钮（runNow()）、清空按钮与空状态；main.qml提供DialogLoader与app.showProblemCenter()。图标请求遵循 16 px 槽位用 16 px、空状态 48 px 槽位用 48 px 的渲染尺寸 lint。
• T16 在 Taskbar.qml 的 MQTT 指示器旁加严重度指示器：图标跟随最高存在的严重度、圆角Label徽标显示 error 数量、visible: Cpp_Misc_ProblemCenter.totalCount > 0，向上Popup展示三个计数加 "Open Problem Center" 按钮。该任务完成记录里有一个细节：因为没有商业守卫（功能本身 GPL），不需要Loader包装。
• T17 实现jumpRequested(kind, uniqueId)的 QML 侧路由：settings/<page>打开对应偏好页，否则app.showProjectEditor()后按 uniqueId 选中实体。任务中固化了检测器契约：entityUniqueId对jump == "source"是sourceId、"action"是actionId、"group"是位置索引groupId、"dataset"是数据集uniqueId（QML 侧selectDatasetByUniqueId()把它映射为selectDataset()需要的(groupId, datasetId)对）。硬约束：C++ 侧绝不反向调用编辑器——回读确认没有 C++ 文件因此新增编辑器依赖。

六、验收与完成定义：T18 与 Definition of Done

T18 — 集成测试（维护者运行）

test_problem_center.py 按plan.md命名写出 AC2–AC7 共 8 项验收测试，使用api_client/device_simulator/clean_statefixtures 与tests/README.md的延迟表；链路测试在断言前至少等两个 1 Hz tick，实际做法是以约 1 秒为轮次流数据、轮次之间调用problems.run代替盲睡，使三个持续样本在单测 30 秒超时内累计完成。标记策略：四项项目/API 测试带project，三项链路/脚本测试带network+slow。完成记录还诚实标注了两处对 spec 的偏差（均遵循 plan）：duplicate-frame-index按Warning断言；checksum finding 通过重开链路清除而不是靠稀释比率——因为检测器累计的是 reader 存活期的总量。

Definition of Done（整特性闸门）

tasks.md 末尾的 DoD 是整个特性的验收清单，全部勾选，且多数条目带完成证据：

• spec.md全部验收标准满足（AC1、AC10 已核；AC2–AC7 代码完成，等维护者跑集成文件）；
• python scripts/code-verify.py --check对所有变更文件干净（0 错误，仅arch-singleton-instance预警，且该预警在 plan 的风险列表中已预判）；
• scripts/registry-verify.py干净（清单 schema、id、图标解析、快捷键唯一性、商业守卫扫描、QML 图标渲染尺寸 lint）；
• python scripts/generate-command-strings.py --check干净（无清单/字符串漂移）；
• pytest tests/scripts/test_problem_center_static.py绿色（10 passed，agent 执行）；
• C++ diff 跑过qt-cpp-review；
• T4/T8 之前重读ss-hotpath；--benchmark-hotpath由维护者执行，九个门禁层级零回归；
• spec-0001 的 ctor-edge proof 重跑并记录：Misc::ProblemCenter构造期零外发边；
• 集成测试文件连同运行说明（应用启动、API server 开在 7777 端口）移交给维护者；
• python scripts/sanitize-commit.py已跑，工作树无 lint 债务；
• 维护者专属后续在 handoff 中标明：SerialStudio --dump-api-schema app/rcc/api/api-schema.json后重跑sanitize-commit.py，让 JS/Lua SDK 拾取三个新命令；
• diff 就是所要求的、且仅此而已——唯一刻意的相邻修复（校验和qWarning限流）在提交信息中点名并给出理由。

七、从源码结构看：这套设计的三条不变量

通读 tasks.md 与其在当前仓库的落地实现，可以归纳出三条贯穿所有 19 个任务的不变量：

1. 热路径只许加整数自增，不许加信号/锁/分配。T4 的 Verify 要求"回读确认没有新增 atomic、mutex、signal 或 allocation"，T8 的"首失败每数据集才捕获字符串"同理；dataflow.md 的 "Diagnostic Counters — Pulled at 1 Hz (spec 0033)" 一节把这条规则写进了架构文档，CLAUDE.md热路径块也新增了对应一行。
2. 一切诊断都是"拉"而不是"推"。检测器只读计数器和项目文档，ProblemCenter 在 1 Hz tick / 项目变更 / 按需三个时机调用它们；LinkStats、scriptStats()均为纯读取。重连导致的计数器归零通过"减少即重置"的差值语义消化，而不是负速率告警。
3. 变更必须自灭。每个 checker 的 findings 切片每轮整体替换，条件修复后 finding 自动消失；模型只在拍平列表真正变化时 reset，保证 1 Hz 轮询不引起 UI 空转。

配套的文档侧改动（T19）也值得注意：API-Reference.md 按既有的逐命令格式新增### Problems Commands (3)一节（含 finding 字段表，当前位于 L4226 起）；用户侧帮助文档见 Problem-Center.md。

八、任务与当前仓库文件对照表

tasks.md 写作时的app/src/...路径在当前仓库重组后大多迁至core/，阅读源码时按下表对照：

从源码结构看，core/Ui/Misc/Problems/下还存在一个 tasks.md 未列出的ExtensionCheckers.{h,cpp}，推测为后续 spec 在同一检测器框架上追加的扩展类检查——这恰好印证了该框架"中心只认 checker，不认问题领域"的可扩展设计。

九、复现验证的实用命令

在只读地浏览本仓库之外，若在自己的构建环境中复现该特性的验证链（前提：已装好 Qt 构建依赖与 Python 环境，且仓库完整），tasks.md 给出了一组可直接照抄的检查命令：

# 1. 静态代码检查（C++/QML 变更文件） python scripts/code-verify.py --check core/Ui/Misc/ProblemCenter.h core/Ui/Misc/ProblemCenter.cpp # 2. 清单/图标/快捷键/图标渲染尺寸 lint python scripts/registry-verify.py # 3. 命令字符串与清单同步检查 python scripts/generate-command-strings.py --check # 4. agent 可运行的静态测试 pytest tests/scripts/test_problem_center_static.py -v # 5. 文档锚点校验 python scripts/documentation-verify.py # 6. 集成验收（维护者侧，需应用已启动且 API server 监听 7777） pytest tests/integration/test_problem_center.py

需要强调的适用前提：第 6 项是 tasks.md 明确划给维护者的步骤（agent 不运行 live-API 测试）；--benchmark-hotpath与SerialStudio --dump-api-schema app/rcc/api/api-schema.json同属维护者专属后续，用于九层级热路径门禁与 SDK schema 同步。

总结来说，tasks.md 的价值不在于它列了 19 个任务，而在于它把"一个诊断子系统应该怎么实现、怎么验证、谁来验收"压缩成了可勾选、可重放、可审计的文本：每个任务有明确的文件边界、回读式验证方式和依赖顺序，完成记录直接回写状态，DoD 把整特性闸门与单个任务的闸门区分开。对想在大型 Qt/QML 应用中落地类似"问题中心"的读者，这份文档与它对应的 ProblemCenter.h、Problems 检测器目录、静态测试 构成了一条从任务书到可运行证据的完整链路，值得作为规格驱动开发的参考样本研读。

【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio