Serial Studio 的地面真值核对方法：如何把手册里的每一条事实声明逐条验证到源码

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能够定案的，都是声明。原文档的八类声明分类表完整继承如下，并结合当前仓库源码补充了每一类“地面真值”的实际位置示例：

规范同时划定了排除项：观点、理论铺垫、协议背景知识不算声明——“审计事实，而不是文体”（audit facts, not prose）。这避免了把核查范围膨胀成对整篇文档的改写任务。

从源码结构看，上表并非空对空：波特率默认值、DTR 默认（UartDriver/dtr缺省为 1，即默认开启）、奇偶校验/数据位/停止位/流控的缺省选择，全部集中在 UART.cpp 构造函数里一次性恢复，正好对应“Default value”与“Range / options”两类声明最常见的对账落点。

三、四步核对程序（Procedure）

原文档的程序共四步，完整继承并逐步展开：

1. 建立声明清单。针对本次范围内的页面，逐条列出：声明文本、类型（kind）、位置（标题或行号）。清单要编号，后续报告按编号索引。
2. 逐条找地面真值。用Grep定位（先搜精确的用户可见字符串，再搜符号名），然后Read命中处并带着上下文读。注意约束：tests/可以佐证行为类声明，但永远不能替代实现代码本身作为来源——测试断言的是“代码曾经这样”，实现才是“代码现在这样”。
3. 给出裁定，且禁止从别的 Markdown 文件推断裁定。这是本规范最锋利的规则之一：文档之间会互相拷贝对方的错误，一条错误声明正是靠“文档 A 抄文档 B”活过了评审。
4. 批量场景并行分发。当范围是整节手册时，把任务扇出给多个只读子代理（subagent），每页一个，每个子代理拿到一份显式编号的声明清单和下文规定的裁定格式，结果再汇总。

四、三种裁定（Verdicts）及其证据要求

裁定体系完整继承如下表：

原文档还给了两条边界判例，决定了裁定的严格程度：

• 改变含义的改写不是“接近”，而是 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 推断裁定”在时间维度上的延伸。

九、小结：可复用的核对清单

把本规范压缩成可迁移的操作清单，适用于任何“文档 + 代码库”项目：

1. 声明提取：默认值、取值范围、UI 标签、授权门槛、行为、文件格式、CLI 参数、交叉引用——凡Grep/Read能定案的都入清单，观点与理论背景排除在外；
2. 检索顺序：先精确用户可见字符串，后符号名；Read必须带上下文；测试只作佐证、不作来源；
3. 三值裁定：VERIFIED 附file:line；WRONG 附file:line+ 正确事实；NOT FOUND 附“尝试过什么”，交给维护者；
4. 禁止文档互抄式推断；改变含义的改写判 WRONG；运行时依赖的事实判 NOT FOUND 而非模糊措辞；
5. 报告用统一表格格式（本页声明数 / 各裁定计数 / 逐条证据）；
6. 权限纪律：只改文档；每个修复先给证据；一个事实被多处复述时同轮修掉所有镜像；
7. 能机械化的部分（路径、链接、符号、行号引用、钉住常量）交给类似 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