字段变更如何让读取统计悄悄失真

一个文件读取统计工具，最危险的错误可能是正常输出。作者原本想测量：把历史读取结果直接拿来重放，会有多少次读到错误内容？结果从旧表迁到新表后，过滤器悄悄漏掉了大量记录，算出的比例却仍然像一个可信答案。

修好过滤器，事情还没结束。文件被主动修改、两次读取覆盖不同的行，都被混进了「重放可能失效」的统计。这篇值得读的地方，是作者怎样连续推翻自己的数字，以及怎样让工具交代它到底看见了什么。

查询没报错，为什么结果仍然不可信

作者最初使用 version 1 表，找到 8 对可比较的读取，其中 3 对返回内容不同。随后想用 version 2 扩大样本，同一个数据库却查不到任何读取记录，相关指标变成了 None。

数据库没有丢数据。三个字段名和一种输出格式发生了变化，而这些变化碰巧都不会触发异常。

旧工具从 data.tool 取工具名，在 version 2 记录上得到 None，便把记录过滤掉；从 state.output 取输出，同样拿不到内容。后续检查文件标记时，自然什么都匹配不上。

路径字段更麻烦：input.path 和 input.filePath 仍然同时存在。当前表的 506 次读取中，285 次使用前者，221 次使用后者。只支持一个字段的工具照样能跑，还能拿到一批足够像样的数据。

作者给工具补上的第一项输出，是先展示读取记录的构成：

v2 reads found by name field   : 506
  of those, input.path         : 285
  of those, input.filePath     : 221
output shapes seen             : directory=16, file-v1=173, file-v2=214, image=103
a v1 filter on <type>file</type>: 173 of 506 reads (34%)

要看最后一行：旧过滤器依赖 <type>file</type>，只能识别 173 条，占全部读取的 34%。剩下 333 条对它不可见，其中包含 214 条新格式读取，它们并没有损坏。

这里也要分清：506 条里还包括目录和图片输出，不能把漏掉的 333 条全部认定为应该纳入文件比较的样本。但工具至少应该说明，这些记录为什么没进入计算。

计算过程正确，不代表参与计算的那批数据正确。

作者还提到，另一次查询曾返回 19,518 条完全正确、却已经过时两天的记录。那次错在时效，这次错在覆盖范围；两者都能躲过「查询成功」这层检查。

修好过滤器，为什么还得撤回 52.9%

修正筛选后，可比较读取对从 8 对增加到 34 对，内容不同的从 3 对增加到 18 对，比例达到 52.9%。

作者在 27 分钟前，已经把 8、3、27 这组数字发进了评论。因为读者正在据此和他讨论，他回到同一线程更正。但新的 52.9% 也不能直接用于回答原问题。

工具比较的是：同一个文件的两次读取，中间至少发生过另一次工具调用。如果中间调用恰好修改了文件，再次读取出现差异很正常。

34 对中，有 30 对在两次读取之间存在写入或编辑；18 对差异中，有 17 对属于这一组。对于会重放编辑步骤的缓存机制，这些差异不能直接证明缓存已经失效。

剩下没有记录到写入操作的只有 4 对，其中 1 对发生变化。作者最终愿意支持的表述是：全部 34 对中，有 1 对出现了没有已记录写入可解释的差异。

这里必须保留分母。1/34 表示这类差异在全部可比较读取对中的占比；如果只讨论「没有记录到写入」的子集，则是 1/4。两种口径回答不同问题，而后者样本尤其少。原文也没有说明那一次变化究竟来自哪里。

还有一批更容易误判的记录：部分读取。

读取文件第 40 到 80 行，输出会从 40: 开始。把它与全文读取直接比较，得到的差异可能只是读取范围不同。修正后的工具发现，这类读取对有 109 对，109 对全部不同。100% 看起来很醒目，却不能说明文件变化。

旧工具只排除了其中 27 对。修正后，筛选条件从「输出有没有文件标记」改成了「调用者是否请求读取整个文件」。

这也给重放系统提出了要求：记录一次观察时，除了时间，还要保存它覆盖的范围。只留下当时读到的一小段内容，后续就缺少核验依据。

工具应该先交代看了多少，再报告发现了什么

作者其实已经在另一项检查中做过覆盖率保护。他检查文章能否被索引时，会输出 posts_expected、posts_fetched、coverage_pct 和 verdict_trustworthy，覆盖率低于 80% 就以非零状态退出。

原因很直接：一篇都没抓到，与抓完后发现没有变化，可能输出相同结果。

但他没有把这套保护用在数据库测量上，因为他原先认为，访问外部系统可能失败，数据库查询则要么成功，要么抛异常。实际遗漏的是：字段的含义也会变化，查询成功只能证明语句执行了。

修正后的工具在报告结论前，先打印语料边界和会话覆盖情况：

corpora: v1 part closed at 1792081149400 | v2 session_message cutoff 1793439774214
  sessions: v1 50, v2 58, in both 50 -> merged 58 (v1-only 0, v2-only 8)

这里应关注 cutoff 和 merged 58：前者限定统计截点，后者交代合并后的会话规模。v1 有 50 个会话，v2 有 58 个，两边共有 50 个，新增的 8 个来自 v2。

作者还把支撑文章的数字固定在脚本里，执行 --check 时，只要数字变化就退出 1。这是让这一次结论可以复现的保护，不是要求持续增长的数据永远保持原值。

同一天，工具还犯过另一个错误：页面验证读取没有找到评论标记，就输出陌生人看不到评论。实际上评论一直公开可见，只是 dev.to 返回的缓存副本尚未包含它。

一次没读到，只能证明这次返回的内容里没有。

我的判断

我认同作者把覆盖范围放在统计结果旁边。对于处理 AI 工具调用日志的 Node 脚本，这比只补一个空数组判断更有用：空结果容易暴露，只漏一部分数据却很容易通过人工检查。

但原文不足以回答「文件读取重放到底有多可靠」。34 对可比较记录、其中仅 4 对没有已记录写入，支撑不了对一般项目的推断。是否漏记了外部修改，重放时如何核验文件，原文都没有说清。

80% 覆盖率阈值也来自作者另一项检查的经验，不能直接搬成所有统计任务的标准。没有阈值对照数据，就只能把它当作具体工具里的工程选择。

字段校验、格式归一化和覆盖率报告也各有作用。字段校验能暴露缺失，归一化能兼容多个版本；但如果入口已经过滤掉陌生记录，后两步仍可能看不到遗漏。原文最有价值的提醒，是让工具把未识别、未纳入的记录也报告出来。

能拿来做什么

• 维护 Node 日志分析脚本时，把候选记录数、成功解析数和排除原因一起输出，遇到新格式时留下可检查的计数。
• 评估 AI 编程工具的读取缓存时，分别统计有写入和无已记录写入的读取对，同时保存路径及读取范围，避免把编辑结果和窗口差异算成缓存问题。
• 给固定样本的测量脚本保存统计截点、会话数量和预期结果，用类似 --check 的检查暴露变化，并在更新样本后重新核对基线。
• 验证评论或其他公开内容时，把「当前响应未找到」与「内容不可见」分开报告；如果返回内容可能来自缓存，就先保留结论的不确定性。