Appearance
Agent 可靠性：不重、不漏、不静默
第二部 · Agent 系统与平台 · 第6章
撰写日期：2026-08-31（合并多次长期在线与漏事件复盘）
结论
Agent 从演示变成长期系统后，主要故障通常不是模型答错，而是事件没进来、任务重复执行、状态没有落盘、失败被合理默认值掩盖。
可靠性可以收敛成三个用户承诺：同一动作不重复、该处理的事件不遗漏、系统坏了不会假装正常。
1. 不重：副作用必须幂等
- 每个事件保留稳定标识和已处理记录；
- 连接阶段失败可以重试，服务端可能已经处理的写操作不能无脑重放；
- 发送、扣费和创建资源前使用幂等键或先出队再执行；
- 同一自动化只有一个有效消费者，迁移时旧实例先退役。
2. 不漏：事件入口必须能对账
长连接、Webhook 和事件总线都可能出现“进程活着、事件没送达”。不要只监控连接状态，而要比较：
text
权威数据源中的应处理事件
− 本地已处理记录
= 待补偿缺口短周期回查只负责发现缺口，补偿事件仍进入原有处理流程。这样系统无需先解释连接为什么失效，也能恢复最终结果。
定时任务使用“上次成功游标 → 当前”的窗口；失败不推进游标。固定的“今天零点到现在”会在改时间或漏跑时留下永久空洞。
3. 不静默：失败不能伪装成业务值
采集失败返回 0、空数组或旧缓存，都会让故障看起来像“今天真的没数据”。系统应区分：
- 有效的零值；
- 数据暂未更新；
- 采集失败；
- 使用了旧数据。
队列中的异常默认留队、留痕并重试；只有到达明确截止时间，才进入经过设计的降级路径。
4. 三层兜底
| 层 | 机制 | 目标 |
|---|---|---|
| 自愈 | 有界重试、游标、恢复点 | 短故障不打扰人 |
| 告警 | 超过阈值只通知一次，附事实和入口 | 持续故障必须被看见 |
| 收尾 | 截止后执行预先批准的降级方案 | 任务不永久烂尾 |
成功通知和空通知通常应该静默。告警通道的稀缺性与可靠性本身同样重要。
5. 用合成事件验证整条链路
进程存活、端口正常、连接对象显示在线，都不能证明用户一定能收到结果。定期投递一条可识别的合成事件，验证接收、排队、模型处理、发送和状态记录整条路径，才是端到端健康检查。