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 仓库中的文档核对规范 ground-truth-factcheck.md 为核心完整讲解“代码是真相、文档是被告”the code is the truth; the doc is the suspect这一事实核查方法论哪些内容算可核查的声明claim、如何用Grep/Read定位地面真值、如何给出 VERIFIED / WRONG / NOT FOUND 三种裁定并附file:line证据以及如何产出标准化报告。读完本篇你能掌握一整套“文档事实声明 vs 源码实现”的审计流程并了解配套脚本 scripts/claim-verify.py 如何把其中机械可查的部分固化为可执行门禁。一、核心理念与适用边界该规范确立了一个基本立场发布或评审手册页面前每一条可核查的声明都必须对照仓库验证。它面向的是用户侧文档doc/help/**、README.md、examples/**/README.md的评审环节由 ss-docs 技能 在“更新工作流”和“评审工作流”中引用作为不变量第 1 条The code is the ground truth的具体程序每个默认值、取值范围、UI 标签、菜单路径、Pro 门槛和行为声明在写进文档之前都要用Grep/Read对照core//app/src/app/qml验证——绝不从另一篇文档或记忆中抄录。它的姊妹篇 ss-ai-audit 用同样的立场审计 AI 侧文档CLAUDE.md、doc/claude/**、.claude/skills/**。两者的共同点是“来源替换”博客类事实核查技能原本靠 WebFetch 抓取被引用的 URL 来对账而 Serial Studio 的手册来源不在网上于是对账动作替换为对core/、app/src、app/qml以及 doc/help/help.json 的Grep/Read。二、什么算一条“声明”claim规范给出了明确的判定标准凡是Grep/Read能够定案的都是声明。原文档的八类声明分类表完整继承如下并结合当前仓库源码补充了每一类“地面真值”的实际位置示例类型示例典型地面真值当前仓库中的对账位置示例默认值Default value波特率默认9600驱动构造函数初始化列表 / 成员初始化位于core/Devices/IO/Drivers/UART.cpp 中m_settings.value(IO_Serial_Baud_Rate, 9600)即默认值字面量取值范围 / 选项Range / options数据位5, 6, 7, 8喂给 UI 的枚举、combo-box 模型或校验器同一构造函数中dataBitsList()等列表函数见 UART.cppUI 标签 / 菜单路径Settings → Miscellaneous → Enable API Serverapp/qml/**中的字符串标签必须逐字匹配app/qml/下 QML 属性名与显示文本版本门槛Edition gating需要 Pro 授权守护该功能的SerialStudio::activated()/commercialCfg()调用点授权判定入口在 License.hCore::License::activated()声明与 License.cpp实现行为Behavior断开后自动重连实现该行为的槽函数 / 处理器UART.cpp 构造函数中m_autoReconnect(false)即“默认不自动重连”的地面真值文件 / 格式支持导出 MDF4 / 端口名示例导出器 / 驱动代码平台相关字面量core/Storage/MDF4/导出器源码CLI 参数--benchmark-hotpath在app/src/core/中精确检索该参数字符串CLI.cpp 中argvHasFlag(argc, argv, --benchmark-hotpath)以及 CLI.h 中的参数说明文案交叉引用[UART](https://link.gitcode.com/i/410f92df6c6a8f5e0b6937462010bb8a)目标文件存在且该条目已注册进help.jsonhelp.json 是id/title/section/file结构的 76 条目注册表如drivers-uart条目指向Drivers-UART.md规范同时划定了排除项观点、理论铺垫、协议背景知识不算声明——“审计事实而不是文体”audit facts, not prose。这避免了把核查范围膨胀成对整篇文档的改写任务。从源码结构看上表并非空对空波特率默认值、DTR 默认UartDriver/dtr缺省为 1即默认开启、奇偶校验/数据位/停止位/流控的缺省选择全部集中在 UART.cpp 构造函数里一次性恢复正好对应“Default value”与“Range / options”两类声明最常见的对账落点。三、四步核对程序Procedure原文档的程序共四步完整继承并逐步展开建立声明清单。针对本次范围内的页面逐条列出声明文本、类型kind、位置标题或行号。清单要编号后续报告按编号索引。逐条找地面真值。用Grep定位先搜精确的用户可见字符串再搜符号名然后Read命中处并带着上下文读。注意约束tests/可以佐证行为类声明但永远不能替代实现代码本身作为来源——测试断言的是“代码曾经这样”实现才是“代码现在这样”。给出裁定且禁止从别的 Markdown 文件推断裁定。这是本规范最锋利的规则之一文档之间会互相拷贝对方的错误一条错误声明正是靠“文档 A 抄文档 B”活过了评审。批量场景并行分发。当范围是整节手册时把任务扇出给多个只读子代理subagent每页一个每个子代理拿到一份显式编号的声明清单和下文规定的裁定格式结果再汇总。四、三种裁定Verdicts及其证据要求裁定体系完整继承如下表裁定含义必需证据VERIFIED代码与声明一致file:lineWRONG代码与声明矛盾file:line 正确事实NOT FOUND找不到地面真值列出尝试过的检索标记给维护者不许猜原文档还给了两条边界判例决定了裁定的严格程度改变含义的改写不是“接近”而是 WRONG。例如把 256 kHz 的门限写成“约 10 kHz”判 WRONG 而非近似成立。地面真值天然依赖运行时的声明OS 行为、硬件时序判 NOT FOUND 并附注说明而不是在文档里加一句含糊的“hedging”措辞——文档不应靠模糊措辞来掩盖无法静态对账的事实。五、标准报告格式核对结果必须按下述格式产出原文档模板原样继承其中行号为格式示意## Factcheck: page Claims: N — Verified: n | Wrong: n | Not found: n | # | Claim | Kind | Verdict | Evidence | |---|-------|------|---------|----------| | 1 | Baud default 9600 | default | VERIFIED | UART.cpp:88 | | 2 | DTR default Off | default | WRONG — default is On | UART.cpp:92 | | 3 | reconnect backoff 2 s | behavior | NOT FOUND | grepped reconnect, backoff |对照当前仓库看这个模板的威力第 1 条在今天的树里对 UART.cpp 依然成立VERIFIED而第 2 条恰好演示了 WRONG 的形态——构造函数里m_settings.value(UartDriver/dtr, 1)表明 DTR 默认是On若文档写 DTR default Off证据就是这一行。NOT FOUND 一列则展示了“尝试过什么”的证据要求不是空着手说找不到而是列出grepped reconnect, backoff这样的检索记录并把裁决权移交给维护者。六、三条铁律Rules原文档的 Rules 一节完整继承这三条划定了整个核对任务的权限边界Docs-only只动文档。如果核对中发现代码疑似错了某个默认值与 UI 文本矛盾、某个 Pro 功能漏了授权门只在对话里说出来——文档任务永远不改代码也绝不用“设计意图”替代“代码的实际行为”来写文档。文档记录现实维护者改变现实。每个 WRONG 修复必须在动手前附上file:line证据。无法举证“更正”就是一个新猜测与原文档的错误没有区别。修一处扫全部镜像。当一个修正改变了其他页面也在复述的事实要在doc/help/**和README.md全文检索那个错误字面量同一轮里修掉所有镜像——错误声明是群居的。七、可执行的一层claim-verify.py 如何机械化这套流程规范本身是给“人或 AI 评审者”看的程序而仓库另有一套脚本把其中机械可判的部分沉淀成了可执行门禁scripts/claim-verify.py。理解它能反过来加深对上述流程每一步的认知。7.1 扫描对象与豁免机制脚本默认扫描 AI 侧文档层CLAUDE.md、doc/claude、.claude/skills常量DOC_TARGETS刻意排除doc/claude/specs/**——规范是“带日期的决定记录”不是对代码树的现行声明。文档内可用!-- claim-verify off --/!-- claim-verify on --围栏豁免特定区域代码围栏fenced code block则整体跳过因为它们装的是示意性示例。7.2 七类检查声明类型表的脚本化对应脚本的七类发现finding正好覆盖规范“什么算声明”表的机械子集link-target-missing—— Markdown 链接指向的仓库路径不存在对应“交叉引用”类声明ss-ai-audit 步骤 2 中的“file path”。path-missing—— 反引号内的仓库路径app/...、core/...等前缀白名单在磁盘上不存在。line-out-of-range——file:line引文超出文件实际行数。这直接落实了报告的file:line证据纪律引文本身也要可验证。symbol-missing / symbol-moved—— 反引号中的Class::method末段标识符在app/src、app/qml、core的第一方代码里查无此名错误级或两段都存在但从不共现advisory疑似搬家。脚本用三路索引整文 blob、标识符集合、owners声明归属表区分“方法真的没了”和“文档只是没写限定名”。identifier-missing—— 裸 camelCase 名称不再存在advisory。anchor-drift—— scripts/doc-anchors.json 中钉住的常量漂移了代码侧正则不再匹配值变了或文档侧字面量消失了。这是“默认值”类声明的持续监控claim-verify.py 的check_anchors()同时绑定两侧任一半过时即报。7.3 基线与退出码把“发现漂移”变成 CI 门禁脚本支持--accept把当日错误冻结进 scripts/claim-baseline.json之后只有基线之外的新错误fresh findings才会让退出码为 1纯 advisory 不失败。退出码约定为 0 干净、1 发现错误、2 参数错误。它同时是 CI 和sanitize-commit.py预提交管线的一环见 ss-ai-audit 技能 步骤 0报告写入仓库根的.claim-report。这就形成了双层结构脚本抓“字符串层面还能对上”的漂移路径、符号、行号、钉住的常量而本篇规范的人工/Agent 流程负责脚本结构性查不了的部分——“这一段是否还在描述正确的机制”“这个步骤清单是否完整”“这条规则是否仍然有效”。两者合起来才是该仓库文档可信度的完整防线。八、在 ss-docs 工作流中的位置把规范放回它的调用上下文ss-docs/SKILL.md 的更新工作流第 2 步要求“提取你这次编辑触及的声明并逐条对代码验证——无法举证的声明不许进文档”评审工作流第 3 步则直接引用本规范执行“VERIFIED / WRONG附正确事实/ NOT FOUND file:line证据”的裁定输出且“WRONG 的事实性声明永远是 P0 级发现不许静默修复”。新条目清单第 3 步还要求“每个事实性声明都带着你本次会话里实际读过的地面真值证据”——禁止用缓存记忆顶替当场验证这正是第 3 步“禁止从别的 Markdown 推断裁定”在时间维度上的延伸。九、小结可复用的核对清单把本规范压缩成可迁移的操作清单适用于任何“文档 代码库”项目声明提取默认值、取值范围、UI 标签、授权门槛、行为、文件格式、CLI 参数、交叉引用——凡Grep/Read能定案的都入清单观点与理论背景排除在外检索顺序先精确用户可见字符串后符号名Read必须带上下文测试只作佐证、不作来源三值裁定VERIFIED 附file:lineWRONG 附file:line 正确事实NOT FOUND 附“尝试过什么”交给维护者禁止文档互抄式推断改变含义的改写判 WRONG运行时依赖的事实判 NOT FOUND 而非模糊措辞报告用统一表格格式本页声明数 / 各裁定计数 / 逐条证据权限纪律只改文档每个修复先给证据一个事实被多处复述时同轮修掉所有镜像能机械化的部分路径、链接、符号、行号引用、钉住常量交给类似 claim-verify.py 的脚本做基线化门禁人力聚焦机制层面的段落级核对。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考