本文数据来自本机 2026-11-20 至 11-21 的巡检日志与只读复跑输出,命令、数字、退出码均为原文,可复跑。路径中的 agent 代号、会话串已泛化为
<agent-a>/<agent-b>/<session-id>,不含真实用户名、token、内网 IP 或公司信息。
一、先看结论
有一条只读巡检,每轮对账「声明过的产物」和「磁盘上真正的文件」。其中一段打印:
|
|
看板上写着 larger=6。第一反应是「有 6 个文件被写大了」。这个反应是错的,而且错得很安静——因为指标本身一个数都没算错。
三句话交代清楚:
larger=6数的不是 6 个文件,是 6 条声明行,它们只对应 5 个产物。同一个文件被两条声明行各记一次,就贡献两条 larger。- 这个数会随「今天写了几段日志、声明了几次」往上涨:03:22 是 6,04:22 是 7,05:22 是 10,06:22 是 11。文件没多,声明多了。
- 全程
shrink=0 / missing=0,说明数量维度上指标完全正确;错的是语义维度:指标名的单位(声明行)和读者脑中的单位(文件)不是同一个东西。
修法也因此很清楚:不要去改判定逻辑(它没坏),而是在报告里加一个按路径去重的读数,把两个数并排放出来。下面把这条链路完整走一遍。
二、这段巡检到底在比什么
先把口径钉死,否则后面所有讨论都会飘。
巡检里有一段叫 declared-vs-disk(本文简称 DVD)。逻辑不复杂:产物在写盘时,会在心跳日志或索引文件里留一条声明,形如「产物路径(字节)」。DVD 段把这些声明逐条读出来,对每条声明的路径调用一次 os.path.getsize,拿磁盘上的实际字节和声明里的字节比:
- 实际 == 声明 →
exact - 实际 > 声明 →
disk_larger(报告里简称 larger) - 实际 < 声明 →
shrink - 声明了但磁盘没有 →
missing
复跑的命令长这样(只读,不改任何文件):
|
|
判定代码的核心就一行意思:actual > declared 就算 larger。注意它遍历的单位是「声明行」——每一条形如 <path>(<bytes>) 的记录算一条。它从没说「一个文件算一条」。
这就是整件事的种子。脚本忠于自己的口径,报告忠实打印 larger=6,看板忠实展示 larger=6。每一环都没错,错在从数字到人心的那一跳。
三、六条声明行,其实只有五个文件
把 03:22 那个快照的六条 larger 逐条拆开,会看到一件有意思的事:
| # | 侧 | 声明来源 | 产物 | 说明 |
|---|---|---|---|---|
| 1 | agent-a | 心跳日志 | HB_INSTANCE_MUTEX_20261121.md |
交付后一次补记 |
| 2 | agent-a | 索引 | heartbeat/2026-11-21.md |
追加型日志 |
| 3 | agent-a | 索引 | HB_INSTANCE_MUTEX_20261121.md |
与 #1 同一个文件,双声明 |
| 4 | agent-b | 心跳日志 | <session-id>-20261121-0017.md |
兜底卡三段续写 |
| 5 | agent-b | 心跳日志 | SCORECARD_TODO_J1FAMILY.md |
判据台账追加 |
| 6 | agent-b | 心跳日志 | PENDING_DECISIONS.md |
裁决队列追加 |
六条里,#1 和 #3 指向同一个 HB_INSTANCE_MUTEX 文件——它在心跳日志里声明一次,又在索引里声明一次。两条声明记的字节数一样,磁盘实测也一样(都是 21,866 B),所以两条都判 larger。
于是:
- 按声明行数:6
- 按文件去重后:5
6 和 5 都是「对」的,只是单位不同。看板写的是前者,读者想的是后者。一个安静的计量单位错误,就这样产生了。
四、它会涨:6 → 7 → 10 → 11 的来历
如果 larger 是一个稳定的「异常文件数」,它应该基本不动。但它动了,而且动得很有规律。同一份日志逐轮读:
| 轮次 | entries | larger | 比例 | 新增来源 |
|---|---|---|---|---|
| 01:22 | 18 | 1 | 5.6% | 首轮,台账还没被多轮声明 |
| 02:22 | NA | NA | — | 日志被临时改名,整段 SKIP,不编数 |
| 03:22 | 28 | 6 | 21.4% | 快照点 |
| 04:22 | 29 | 7 | 24.1% | 心跳新增一段,对同一日志再声明一次 |
| 05:22 | 32 | 10 | 31.2% | 心跳两段 + 索引一条,仍是同一批文件 |
| 06:22 | 40 | 11 | 27.5% | 又一段心跳 + 一次索引补录 |
看清楚新增的那几条:没有一条是新文件,全部是新的声明行。比如 heartbeat/2026-11-21.md 这个文件,在 04:18、04:48、05:18、06:20 各被声明一次,每次声明记的是「当时写盘那一刻的字节数」,而这个文件每分钟都在被追加。于是同一文件贡献了四条 larger——不是它坏了四次,是它被声明了四次。
这就是「随声明次数涨」的直白证据:文件还是那几个文件,写的段落多了,声明行就多了,larger 跟着涨。
五、26%–28%:一个安静的结构性比例
单看今天的 27.5% 可能觉得偏高。把昨天的十二轮拉出来,规律立刻显形:
|
|
十二轮全部落在 26%–28% 的窄带里,今天这一轮 27.5% 稳稳在带内。而且 larger 随 entries 同步增长——entries 翻倍,larger 也大致翻倍,比例几乎不动。
这个形态是典型的「结构性比例」,不是「异常膨胀」。如果真有异常在累积,比例会失控上冲,或者伴随别的事故信号。两者都没有。它更像一个常数:每声明 4 条,大约有 1 条会因为「声明后又写了」而变成 larger。
换句话说,27.5% 不是坏消息,它是这套写盘方式的指纹。
六、shrink=0 / missing=0:为什么这不是事故
判断「文件被写坏」,真正要盯的是两个指标:
shrink:磁盘实际字节 < 声明字节。意思是文件被截断或覆盖了,这是数据事故的信号。missing:声明过但磁盘找不到。意思是幽灵文件或误删。
今天 01:22、03:22、04:22、05:22、06:22 五轮,加上 02:25 一次演练跑,六次读数全部是:
|
|
一次都没有例外。这五个文件只增不减、从没被覆盖、从没消失。larger 描述的是「声明值比实际值旧」——日志里记的是过去某一刻的快照,文件后来自然长大了——而不是「文件出了问题」。
所以定性是清楚的:数量维度上,指标百分之百正确;出错的是语义维度。larger 从来没打算报告「异常文件数」,但它的名字和它在看板上的位置,让每个读的人都默认成了那个意思。
七、错在三个东西没对齐
把这次误读拆开,是三个东西没对齐:
- 指标名。它叫
larger,中性词,读起来像「一类异常」。如果它叫larger_rows(偏大的声明行),第一眼就不会被当成文件数。 - 口径。脚本按声明行计数,这是对的——因为声明本来就可能重复。但报告里只打印总数,没说单位。
- 读者的心智模型。看到「产物对账」四个字,脑子自动切到「文件」这个单位。
三者单独看都合理,凑在一起就产生系统性误读。这类错误的可怕之处正在于:数据越准确,越容易骗人——因为它经得起逐条核对,你查半天会发现「每一条 larger 都对啊」,然后更加确信「有 6 个问题」。
八、修法:不判定,加一个并排读数
既然判定没错,就不要动判定。动判定有两个坏处:一是把一条正确规则改出风险,二是历史上所有基于 larger 的趋势数据都会断档。
正确做法是纯加法:保留原有的 larger(按声明行),另外算一个按路径去重后的读数,把两个数并排放在报告里。
设想新增一行:
|
|
这样看板上两个数各归其位:
larger=11:偏大的声明行数,用于和历史趋势对齐;distinct larger=5:偏大的文件数,用于回答「到底几个文件」。
去重的规则也简单:同一个路径取它最后一条声明来比对(因为最后一条最接近当前意图),同路径的多条声明算作一个文件。这一行不需要改 C2 契约、不需要改段数、不需要动 FAIL 阈值——就是多打印一行。
效果立竿见影:distinct larger 不随「今天写了几段心跳」漂移,它只随真正不同的文件变化。看板读者想看的那个数,终于有了一个诚实的位置。
九、三条更进一步的处置建议
多余的话不多说,三条提案,都涉及口径或跨 agent 台账形态,须裁决后才实施,本轮一律不动:
- 建议一(推荐):就是上节的 distinct 并排读数,纯加法,风险最低,直接消除单位歧义。
- 建议二:
PENDING_DECISIONS.md这类不按日滚动的长寿台账做月度归档。它约以 14 KB/日的速度增长,线性外推约 77 天到 1 MB。归档要先留备份,且下游三个消费者要同步改路径,所以要裁决。 - 建议三:报告类产物交付即冻结,后续补记另起文件。补记写进原文件会让「日志里的字节数」永久失真,持续产出 larger 行;但历史文件不必回改,改了反而破坏证据链。
十、怎么复现
想在自己机器上验证这条链路,三步:
|
|
三家 summary 的原会计数(现盘,06:25 时刻):
|
|
核对时不必对死数字(它会随追加漂移),对这三个不变量即可:
- 三家
shrink=0 missing=0 malformed=0; - 每条 larger 行的实际字节,等于该文件当前磁盘字节(声明值只是历史快照);
- 去重后产物数(现盘 7、快照点 5)与「11 条行 = 4 + 0 + 7」的构成关系对得上。
十一、边界与红线
这次分析全程只读:没有删除、改名、截断任何产物;没有改判定脚本、没有改任何判据数值;没有推送、没有联网取数、没有动看板状态。所有结论都能从上面几条命令复跑得到。
最后回到那句结论:指标本身没错,错在指标名和口径与读者以为的单位不一致。看到这类「安静的数字」,先问一句「它数的单位是什么」,常常比追问「数字为什么变大」更有用。前者能救命,后者只会让你在正确的数字里越挖越深。