邮件送达了,七天观察却不算数
《ops-agent 建造笔记》第 17 篇(续篇分篇 · 收尾) 代码基线:v0.1.0-rc.4,提交
8dfa085(2026-11-09 候选版);前 13 篇仍固定 v0.1.0-rc.1 对照实现:agent/notify.py、agent/schedule.py与docs/validation/下的验收记录 续篇入口:文章锁在 rc.1,代码已经走到 rc.4
0. 告警多了第二个出口
第 3 篇拆开通知状态时,只有 webhook 一条渠道。v0.1.0-rc.3 加了 channel: email(SMTP),让没接 Slack / 飞书 / 钉钉的人也能收到告警。它仍是「只启用一个渠道」的设计——换渠道改配置即可,没有做多渠道路由;去重、恢复、静默、失败重试语义完全一致,第 3 篇拆开的那几份状态还是那几份。
配置入口把凭据 handling 收得比较紧:
./opsagent notify setup --channel email --smtp-host smtp.example.com --smtp-port 465 \
--from ops@example.com --to oncall@example.com,you@example.com \
--smtp-user ops@example.com
# 密码也可用 OPSAGENT_SMTP_PASSWORD 提供,不进 shell 历史
- 465 走隐式 TLS,其它端口要求 STARTTLS(本机回环中继除外,便于本地验证);SMTP 认证可选,纯标准库,无新增依赖。
- 收件人上限 20;地址、主机、端口在配置入口校验,拒绝空白、控制字符、CR/LF(防邮件头注入)、多
@、host 里塞端口。 - 密码只存 0600 的
notify.json;事件与发件箱只记smtp://host:port → N 个收件人,SMTP 错误回显里的账号密码同样脱敏。 notify test / status / list / retry / mute与doctor一并对齐邮箱渠道;既有 webhook 配置零改动,缺channel字段一律按 webhook 处理。
真实渠道这一项终于不再是本地桩:2026-11-06 用 QQ 邮箱 SMTP(587 / STARTTLS)完成投递验收(notify test 返回 SMTP 250,收件人实收),随后在部署本版的主机上跑通 W8 通知全链路——首次异常、持续去重、级别升级、恢复、投递失败退避、自动补发、superseded 跳过、复发重新告警,邮件实收。第 12 篇里「实际通知渠道」那笔欠账,到这里可以划掉。
1. rc.4 补的是「送达」这一层事实
渠道通了,不等于每条消息都送到了每个人。SMTP 部分收件人拒收不一定抛异常,原实现可能把整条记成成功,于是已送达的人会在补发时收到重复打扰,漏收的人却再也收不到。
rc.4 的 R07 / F04 / V01 把状态改成按收件人记账:
- 记录保存已接受收件人的散列标识(不存明文地址);部分失败仍记
failed,retry_pending只补发未成功者。 - 状态项记下
delivered_recipient_ids,纯恢复消息按这个集合定向投递——只发给确实收到过原异常的人;恢复后旧异常标superseded,不再补发,也不产生无来源的恢复消息。 - 部分重试新增的受众也同步进状态机;只有全部投递完成才清恢复态、记完成事件。
- 纯恢复消息的部分失败不并入该集合,避免把原异常受众反向缩小。
这里保留了一个明确的取舍:同轮既有新异常又有恢复的 mixed 消息仍聚合成一条发给全部收件人,恢复行也随之可见。优先保证新异常送达,不为定向恢复拆消息刷屏。
常驻调度的心跳恢复也一并修了:移除「已告警」旗标,每次成功扫描后交给通知状态机判重,首次心跳写盘失败时下一轮仍能补发恢复通知。代价是每轮多一次同量级的状态读写,换的是「恢复」这句话不会因为一次写盘失败永久丢失。
2. 一次跑满的七天观察,被我自己作废
这段不是加功能,是把一条已经成立的结论撤回,也是本组续篇里最该记住的一段。
R1 从 2026-10-28 16:57 跑到 11-04 17:37,实际 168h40m:56 个排期槽位全部命中、56/56 succeeded、0 漏跑、守护进程 0 重启,每轮 24 项规则检查全 ok,56 次真实模型调用,run / report / session / signal 证据齐全。11-05 的验收记录当时判「7 天连续运行门禁通过」。
但逐日表里有个数字一直在涨:最大漂移 +4.3min → +40.1min。根因是 every 任务取 next_run = now + interval,加上取任务与完成时双重锚定,每周期漂移 = 认领延迟 + 整段执行时长,无上界累积。3 小时周期内没造成漏跑,可名义时刻表在持续偏移。rc.2 改成按槽位网格锚定(anchor + k*every),finish 不再重锚 every(daily 保留 DST 重锚),漂移降为常数 ≤60s;daemon 对账容忍 OSError,睡眠下限从 30s 降到 1s。
问题在于:这属于「影响运行行为的重大修复」。下一阶段规划里早写了一条规则——探针、通知状态机、调度推进或执行记录重大修复后,须在真实环境启动修复版本重新计满 7 天。于是 11-07 由维护者裁决:R1 结论归档为历史轮次,不作当前门禁证据;原始逐日数据与证据原样保留、不改写、不删除;R2 于 2026-11-07 09:38 在 v0.1.0-rc.3 上重启(sch-35e3e0,3h / 56 槽位,预期 11-14 09:38 满 168h),并用独立状态目录,以免报告轮转把首日证据冲掉。
还有一层容易漏:rc.4 改了通知状态机和调度恢复行为,同样属于运行行为重大修复。当前 R2 跑的是 rc.3,rc.4 没有部署到观察环境,R2 的证据不能证明 rc.4 已通过;实际部署 rc.4 后还要按同一规则再计满七天。11-09 那次邮箱全链路演练(隔离目录、7 个场景、5 封实收)验证的是通知状态机,记录里明确写了「不构成 R2 观察期内的送达证据」,不改门禁判定。
第 11 篇讲证据怎样组织,第 12 篇讲「不能把候选版发布冒充连续七天验收」。这一段是那两句话真正被执行的样子:跑满了也不算数,因为跑的版本已经不是要发的版本。
3. 到 rc.4 为止,能证明什么
我继续把「通过」分开写,不把它们加成一个大数字。
| 证据 | 结果 | 覆盖范围 |
|---|---|---|
./opsx selftest |
322/322 通过,退出 0 | rc.4 本机,macOS / Python 3.9.6 |
unittest discover |
364 项结束:350 通过、14 跳过 | 跳过项涉及本机未安装的可选 A2A 依赖,由 CI 独立 job 用真 SDK 覆盖 |
| 审查反例 | 首轮 9/9、复审 5/5、边界 2/2;本机与远程日志定向回归 5/5 | R01–R09、F01–F05、V01 等已复现问题 |
| A2A | 单测 + e2e(真实 uvicorn 服务端、官方客户端、桩 LLM) | 能力发现、无 token 401、只读直通、写操作中断与拒绝、批准后审计 |
| 真实模型调用 | R1 期间 56 次,调用/时间/退出码/用量可查 | 属 R1 归档证据,不作当前门禁 |
| 真实通知渠道 | 11-06 QQ 邮箱 SMTP 投递与 W8 渠道全链路验收通过 | 在 rc.3 上完成;异常/去重/升级/恢复/失败补发/复发 |
| 隔离通知演练 | 11-09 7 场景、5 封实收 | rc.3 隔离状态目录;明确不算 R2 观察期送达证据 |
| 连续 7 天观察 | R1 56/56 已归档;R2 进行中(预期 11-14 满 168h) | R2 跑 rc.3;rc.4 部署后须重计 |
| W8 整体 | 未通过 | 真实 SSH 恢复、断线 unknown 防重放、服务后验三项始终缺实机证据 |
数字从 309/223 涨到 322/364,说明的是回归面变大,不是生产结论变强。全量单测里那 14 个跳过项也不能省:它们涉及本机未装的可选 A2A 依赖,得靠 CI 独立 job 真装 SDK 之后才把 e2e 跑起来。
前 13 篇反复写「真实 SSH、真实模型、真实通知渠道验收与连续 7 天观察未完成」,那是 rc.1 当时的状态。到 rc.4,真实模型调用和真实邮箱渠道已经验收通过,R1 七天观察跑满后被归档;仍未完成的是真实 SSH 恢复、断线 unknown 防重放、服务后验,以及修复版本上的连续七天观察。旧句不能整句沿用,也不能反过来写成「已验收、稳定运行」。三个候选版都没有提前转正式版:VERSION 仍是 0.1.0-rc.4,S4 正式发布门禁未完成,W8 整体未通过,也不替代 latest。
4. 补进欠账簿的几笔
第 12 篇列了没开的门和没底的取舍,旧的基本还在:静态阈值、PID 复用、手动离线备份、没有完整 shell AST、没有通用 DAG、没有向量记忆、没有 Web/双向 IM、没有无审批自动自愈。多渠道路由仍然没有——邮箱是「二选一」的第二个出口,不是并行投递。
新增的几笔主要来自前四篇:任务状态在内存,长期挂起的确认流程要接持久化 task store;A2A 没声明流式、取消不保证停、单一信任域、1.0 与 0.3 不兼容;logscan 的规则外语义异常仍需人工复核;通知记录没有收件人粒度事实的旧数据,不能反推当时每位收件人是否实收。还有最实际的一笔:R2 观察没跑完,rc.4 一旦部署还要重计。
写这五篇时我特意没有回头改前 13 篇。它们锁在 rc.1,说明的也是当时的真实边界;代码变了,就另起一组续篇,写清从哪个版本开始变、哪些结论被撤回、哪些还欠着。这比让一串悄悄更新的链接替文章改写事实要可靠。
对照源码与证据
- 通知渠道与送达状态机 · 常驻调度与心跳恢复
- rc.3 发布说明(SMTP 渠道) · rc.4 发布说明(R07/R08/F04/F05/V01)
- R1 七天验收记录(已归档) · R2 重启记录
- 11-06 渠道验收 · 11-09 通知演练
- 下一阶段规划(重计规则) · 完整变更日志
系列总览 · 目录 · 续篇入口 · 上一篇:批准一张变更单,不再是批准一条命令