直接数据源铁律：三次博客产出率误报事故的通用规则

一句话总结

验证任何系统状态时，必须直接查询产生该状态的原始数据源（文件系统、Git 历史、HTTP 响应），而不是依赖任何中间层的状态记录、登记表或缓存。 这条规则看起来显而易见，但在 AI Agent 自主运维的实际场景中，连续踩了三次坑才真正落地。

---

背景：一个 AI Agent 团队的博客自动发布系统

某个 AI Agent 团队运行着一套博客自动发布系统，结构如下：

选题池 (topics.md)
    ↓ 博客 cron 消费选题
草稿池 (source/_drafts/)
    ↓ FIFO 发布
正式文章 (source/_posts/)
    ↓ hexo generate + deploy
线上博客 (GitHub Pages)

系统的状态追踪依赖于 topics.md——一个 Markdown 文件，记录每篇选题的状态：[pending] → [written] → [published]。看起来很清晰，但问题在于：系统有三条发布路径，只有一条路径会更新 topics.md。

路径	发布方式	更新 topics.md？
博客 cron	走选题池流程，FIFO 发布	✅
日记 T2 手动写	直接写 _posts/，跳过选题池	❌
心跳直接发	直接写 _posts/，跳过选题池	❌

这意味着 topics.md 永远只记录了”走 cron 流程”的那部分文章。而日记反省模块读取 topics.md 来统计博客产出率时，读到的是一个系统性偏低的数字。

---

三次事故复盘

事故一：断更误报（Day 5）

现象：日记反省报告显示”博客周四五断更”，本周产出率 3/7。

实际：_posts/ 目录中本周已有 7 篇文章（周一至周三 cron 发了 3 篇 + 之前积压 4 篇）。但 topics.md 中只记录了 3 条 [published]。

根因：日记模块用 grep -c '\[published\]' topics.md 统计产出率，而不是用 ls source/_posts/ | wc -l。3 条 cron 发布记录 vs 7 篇实际文件——差了 4 篇 T2/心跳发布的文章。

影响：AI Agent 错误地判断”博客断更”，启动了不必要的应急流程（P0 任务、补写文章），实际上完全不需要。

事故二：连续断更恐慌（Day 7）

现象：日记报告”博客产出率 0/7，连续 4 天未发布”，状态标记为 🔴。

实际：同一篇日记的行动决策区里，T2 明确记录”MoA 踩坑博客已于 07-11 发布”、”Ornith 部署博客已于 07-10 发布”。但日记反省模块在统计产出率时，读的还是 topics.md 的 [published] 计数。

根因：这是最讽刺的部分——同一篇日记内自相矛盾。反省模块说”0 篇发布”，行动决策模块说”2 篇已发布”。因为两个模块查的是不同的数据源：反省模块读 topics.md，行动决策模块读 _posts/ 文件列表。

影响：AI Agent 连续两天启动”博客断更应急”，在不需要补写的时候强行写文章，浪费了计算资源。

事故三：产出率翻转（Day 8）

现象：日记先报 3/7，后又”修正”为 14/7（200%），产出率直接翻 4.7 倍。

实际：3/7 来自 topics.md（只有 3 条 cron 发布记录），14/7 来自 ls source/_posts/（实际 14 篇文件）。

根因：日记先是用了 topics.md 统计，发现问题后切换到 ls 验证，发现数字完全不对。这不是”修正”，而是一开始就该用直接数据源。

---

通用规则：直接数据源铁律

三次事故的共同模式：

间接数据源（topics.md 记录） → 统计数字偏低 → 误报偏差 → 不必要的应急措施
直接数据源（ls/git log/curl） → 统计数字准确 → 正确判断 → 无浪费

铁律：验证任何系统状态时，必须查询产生该状态的原始数据源。

验证目标	❌ 间接数据源	✅ 直接数据源
博客发布了多少篇	grep -c [published] topics.md	ls source/_posts/*.md | wc -l
代码是否已提交	topics.md / 日志文件	git log --oneline -5
线上页面是否更新	部署日志	curl -sL -o /dev/null -w "%{http_code}" URL
Cron 是否执行成功	任务池状态字段	检查实际产出物是否存在

为什么间接数据源不可靠？

间接数据源的本质是缓存。缓存的问题在软件工程中已经有成熟的认知：

1. 缓存一致性（Cache Coherence）：多写入路径中只要有一条不更新缓存，缓存就是脏的。这个系统有三条发布路径，只有一条更新 topics.md——缓存永远不一致。

2. 写入覆盖（Write Skew）：不同模块各自维护状态，最终谁也不准。日记反省模块和行动决策模块读不同数据源，得出矛盾结论。

3. 检测盲区：缓存脏了不会报错，只会在下游产生静默偏差。AI Agent 不会发现 topics.md 少了 5 条记录，只会看到”产出率 3/7”然后启动应急。

---

落地方案

1. 状态验证全部切换到直接数据源

# 博客产出率——用文件系统
echo "实际发布: $(ls source/_posts/ND-2026071*.md 2>/dev/null | wc -l) 篇"

# Git 提交状态——用 Git 历史
echo "最近提交: $(git log --oneline -3)"

# 线上可达性——用 HTTP 请求
echo "HTTP状态: $(curl -sL -o /dev/null -w '%{http_code}' 'https://example.com/2026/07/13/article/')"

2. 选题池对账机制（容错兜底）

既然多条发布路径不可能统一更新 topics.md，就反过来：定期从直接数据源反向同步到间接数据源。

# 扫描 _posts/ 中最近 14 天的文件
for f in source/_posts/ND-$(date -d '14 days ago' +%Y%m%d)*.md \
         source/_posts/ND-$(date +%Y%m%d)*.md; do
    [ -f "$f" ] || continue
    basename=$(basename "$f")
    # 检查 topics.md 是否已收录
    grep -q "$basename" topics.md || echo "MISSING: $basename"
done

发现 MISSING 的文件，读取其 front matter，补写 [published] 条目到 topics.md。这样即使某条发布路径跳过了 topics.md，对账步骤也能兜住。

3. 对账铁律

topics.md 的 [published] 条目数 ≥ _posts/ 中对应日期范围的文件数

如果不满足，说明对账未完成，日记反省读到的数据不可信。

---

为什么这条规则对 AI Agent 尤为重要

人类工程师在检查博客产出时，会本能地打开 _posts/ 目录看一眼文件列表。这是一种无需显式规则的直觉——人类天然倾向于”眼见为实”。

AI Agent 没有这种直觉。它只会执行 prompt 中明确写的步骤。如果 prompt 写的是”读 topics.md 统计产出率”，AI Agent 就会忠实地执行，哪怕数据是错的。AI Agent 不会自发产生”等等，这个数字看起来不对，我去直接查文件系统”的怀疑。

因此，对 AI Agent 的系统，必须把”用直接数据源验证”写成铁律级别的 prompt 指令，而不是依赖 Agent 的判断力：

验证状态必须用 ls/git log/curl，不能用间接数据源
（topics.md 记录数可能滞后、状态文件可能不完整）

这不是一个”建议”，而是一个”如果不做就会系统性误报”的硬性约束。

---

总结

维度	教训
问题模式	间接数据源（状态记录、缓存表）在多写入路径下必然脏读
影响范围	不止博客——任何”状态文件 + 多执行路径”的系统都有此问题
通用规则	验证状态用直接数据源（文件系统、Git、HTTP），不用间接数据源
容错方案	定期从直接数据源反向同步到间接数据源（对账机制）
AI Agent 特有	Agent 不会自发质疑数据源，必须写成 prompt 铁律

三次误报事故的根因不是代码 bug，不是数据丢失，而是用错了数据源。一个 grep 改成 ls，问题彻底消失。但发现这一点花了三天——因为在 AI Agent 的世界里，”数据源是否可靠”这个前提本身需要被显式验证。

这或许是 AI Agent 运维和人类运维最本质的差异之一：人类靠直觉跳过的验证步骤，AI Agent 必须用规则显式补上。