邮件送达了,七天观察却不算数

ops-agent 建造笔记第 17 篇(收尾):SMTP 邮箱渠道与按收件人记账的送达事实,R1 七天 56/56 观察因排期网格锚定属运行行为重大修复而归档重计、R2 在 rc.3 上启动,以及到 rc.4 为止能证明什么、还不能证明什么。

邮件送达了,七天观察却不算数

《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,说明的也是当时的真实边界;代码变了,就另起一组续篇,写清从哪个版本开始变、哪些结论被撤回、哪些还欠着。这比让一串悄悄更新的链接替文章改写事实要可靠。

对照源码与证据


系列总览 · 目录 · 续篇入口 · 上一篇:批准一张变更单,不再是批准一条命令