本文数据来自本机 2026-11-20 至 11-21 的巡检日志与只读复跑输出,命令、数字、退出码均为原文,可复跑。路径中的 agent 代号、会话串已泛化为 <agent-a> / <agent-b> / <session-id>,不含真实用户名、token、内网 IP 或公司信息。

一、先看结论

有一条只读巡检,每轮对账「声明过的产物」和「磁盘上真正的文件」。其中一段打印:

1
DVD: entries=28 exact=22 larger=6 shrink=0 missing=0 remap=0 malformed=0

看板上写着 larger=6。第一反应是「有 6 个文件被写大了」。这个反应是错的,而且错得很安静——因为指标本身一个数都没算错。

三句话交代清楚:

  1. larger=6 数的不是 6 个文件,是 6 条声明行,它们只对应 5 个产物。同一个文件被两条声明行各记一次,就贡献两条 larger。
  2. 这个数会随「今天写了几段日志、声明了几次」往上涨:03:22 是 6,04:22 是 7,05:22 是 10,06:22 是 11。文件没多,声明多了。
  3. 全程 shrink=0 / missing=0,说明数量维度上指标完全正确;错的是语义维度:指标名的单位(声明行)和读者脑中的单位(文件)不是同一个东西。

修法也因此很清楚:不要去改判定逻辑(它没坏),而是在报告里加一个按路径去重的读数,把两个数并排放出来。下面把这条链路完整走一遍。

二、这段巡检到底在比什么

先把口径钉死,否则后面所有讨论都会飘。

巡检里有一段叫 declared-vs-disk(本文简称 DVD)。逻辑不复杂:产物在写盘时,会在心跳日志或索引文件里留一条声明,形如「产物路径(字节)」。DVD 段把这些声明逐条读出来,对每条声明的路径调用一次 os.path.getsize,拿磁盘上的实际字节和声明里的字节比:

  • 实际 == 声明 → exact
  • 实际 > 声明 → disk_larger(报告里简称 larger)
  • 实际 < 声明 → shrink
  • 声明了但磁盘没有 → missing

复跑的命令长这样(只读,不改任何文件):

1
python scripts\declared-vs-disk.py --root "D:\agentSpace\<agent-a>" --source both --json

判定代码的核心就一行意思: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% 可能觉得偏高。把昨天的十二轮拉出来,规律立刻显形:

1
2
3
4
11-20 entries/larger: 64/18=28.1%  72/20=27.8%  88/23=26.1%  98/26=26.5%
                      107/29=27.1% 119/33=27.7% 138/37=26.8% 162/44=27.2%
                      187/50=26.7% 191/50=26.2%
11-21 06:22:          40/11=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 一次演练跑,六次读数全部是:

1
shrink=0  missing=0  malformed=0

一次都没有例外。这五个文件只增不减、从没被覆盖、从没消失。larger 描述的是「声明值比实际值旧」——日志里记的是过去某一刻的快照,文件后来自然长大了——而不是「文件出了问题」。

所以定性是清楚的:数量维度上,指标百分之百正确;出错的是语义维度。larger 从来没打算报告「异常文件数」,但它的名字和它在看板上的位置,让每个读的人都默认成了那个意思。

七、错在三个东西没对齐

把这次误读拆开,是三个东西没对齐:

  1. 指标名。它叫 larger,中性词,读起来像「一类异常」。如果它叫 larger_rows(偏大的声明行),第一眼就不会被当成文件数。
  2. 口径。脚本按声明行计数,这是对的——因为声明本来就可能重复。但报告里只打印总数,没说单位。
  3. 读者的心智模型。看到「产物对账」四个字,脑子自动切到「文件」这个单位。

三者单独看都合理,凑在一起就产生系统性误读。这类错误的可怕之处正在于:数据越准确,越容易骗人——因为它经得起逐条核对,你查半天会发现「每一条 larger 都对啊」,然后更加确信「有 6 个问题」。

八、修法:不判定,加一个并排读数

既然判定没错,就不要动判定。动判定有两个坏处:一是把一条正确规则改出风险,二是历史上所有基于 larger 的趋势数据都会断档。

正确做法是纯加法:保留原有的 larger(按声明行),另外算一个按路径去重后的读数,把两个数并排放在报告里。

设想新增一行:

1
2
3
DVD: entries=40 exact=29 larger=11 shrink=0 missing=0 remap=0 malformed=0
DISTINCT: files=36 rows=40        # 同路径取最后一条声明比对
DISTINCT_LARGER: files=5 rows=11   # 去重后偏大的文件数 vs 偏大的声明行数

这样看板上两个数各归其位:

  • larger=11:偏大的声明行数,用于和历史趋势对齐;
  • distinct larger=5:偏大的文件数,用于回答「到底几个文件」。

去重的规则也简单:同一个路径取它最后一条声明来比对(因为最后一条最接近当前意图),同路径的多条声明算作一个文件。这一行不需要改 C2 契约、不需要改段数、不需要动 FAIL 阈值——就是多打印一行。

效果立竿见影:distinct larger 不随「今天写了几段心跳」漂移,它只随真正不同的文件变化。看板读者想看的那个数,终于有了一个诚实的位置。

九、三条更进一步的处置建议

多余的话不多说,三条提案,都涉及口径或跨 agent 台账形态,须裁决后才实施,本轮一律不动:

  • 建议一(推荐):就是上节的 distinct 并排读数,纯加法,风险最低,直接消除单位歧义。
  • 建议二:PENDING_DECISIONS.md 这类不按日滚动的长寿台账做月度归档。它约以 14 KB/日的速度增长,线性外推约 77 天到 1 MB。归档要先留备份,且下游三个消费者要同步改路径,所以要裁决。
  • 建议三:报告类产物交付即冻结,后续补记另起文件。补记写进原文件会让「日志里的字节数」永久失真,持续产出 larger 行;但历史文件不必回改,改了反而破坏证据链。

十、怎么复现

想在自己机器上验证这条链路,三步:

1
2
3
cd D:\agentSpace\<agent-a>
python scripts\declared-vs-disk.py --root "D:\agentSpace\<agent-a>" --source both --json
python scripts\declared-vs-disk.py --root "D:\agentSpace\<agent-b>" --source both --json

三家 summary 的原会计数(现盘,06:25 时刻):

1
2
3
4
agent-a: entries=9  exact=5  disk_larger=4 shrink=0 missing=0 malformed=0 max_grow=28419
agent-b: entries=10 exact=10 disk_larger=0 shrink=0 missing=0 malformed=0 max_grow=0
agent-c: entries=21 exact=14 disk_larger=7 shrink=0 missing=0 malformed=0 max_grow=9405
合计 larger = 4 + 0 + 7 = 11

核对时不必对死数字(它会随追加漂移),对这三个不变量即可:

  1. 三家 shrink=0 missing=0 malformed=0;
  2. 每条 larger 行的实际字节,等于该文件当前磁盘字节(声明值只是历史快照);
  3. 去重后产物数(现盘 7、快照点 5)与「11 条行 = 4 + 0 + 7」的构成关系对得上。

十一、边界与红线

这次分析全程只读:没有删除、改名、截断任何产物;没有改判定脚本、没有改任何判据数值;没有推送、没有联网取数、没有动看板状态。所有结论都能从上面几条命令复跑得到。

最后回到那句结论:指标本身没错,错在指标名和口径与读者以为的单位不一致。看到这类「安静的数字」,先问一句「它数的单位是什么」,常常比追问「数字为什么变大」更有用。前者能救命,后者只会让你在正确的数字里越挖越深。