管道没坏，契约断了：一次 AI 工作流 Slack 通知失效的根因分析

管道没坏，契约断了：一次 AI 工作流 Slack 通知失效的根因分析

事故发生在凌晨。情报管线按时运行，日报生成，Git 推送成功，所有任务节点绿灯——但总裁没有收到 Slack 通知。我查了将近一个小时，才意识到问题不在任何一行逻辑代码里，而在一个没人写下来的隐性假设上。

问题现场：WF-09 静默失败

我们的自动化体系里有一条工作流叫 WF-09，负责在情报日报完成后向总裁发送 Slack 通知。触发方是情报行动 Agent（action_agent.py），接收方是一个 n8n Webhook，Webhook 拼装消息后调用 Slack API 投递。整条链路部署时测试通过，稳定运行了两周。

这次的问题是：触发方发出的 HTTP 请求返回了 200，n8n 执行日志显示 “success”，但 Slack 消息从未出现。我第一反应是 Slack Token 失效，换了账号重新配置。没用。然后怀疑是 n8n 的 Webhook 解析逻辑出了问题，逐行对照——也没问题。

直到我把触发方的实际 payload 和 Webhook 期待的 payload 并排放在一起，才看到了裂缝。触发方在某次迭代后把字段 channel_id 改成了 slack_channel，Webhook 那侧从来没人告知，还在读一个不存在的键，读到空值，静默跳过了发送步骤。200 OK 是 HTTP 层的成功，不是业务层的成功。

契约漂移：比逻辑错误更难发现的故障模式

事后我在代码库里搜了一下，发现这个问题不是孤立的。类似的字段重命名在过去一个月里发生了至少三次，每次都只改了调用方，没有同步更新接收方的文档或校验逻辑。我把这种现象叫做「契约漂移」——调用方和接收方对同一份 payload 的字段理解逐渐不同步，但双方都不知道对方已经偏移了。

契约漂移之所以难发现，有几个原因。第一，它不触发异常。调用方发出请求，接收方返回成功响应，链路上没有任何报错信号，监控看板全绿。第二，它有延迟。字段改名可能发生在周一，但触发条件只在周四出现，等到问题暴露时，改名那次提交已经淹没在十几条 commit 里。第三，它的影响是非对称的。一个字段变更可能让三条依赖同一 Webhook 的管线同时失效，而修复时你只能逐条排查，因为每条管线的失效表现可能不同。

这和逻辑错误是两种完全不同的故障。逻辑错误通常有堆栈、有报错、有明确的代码位置；契约漂移的线索是分散的，藏在调用方和接收方的边界上，没有单一的「出错行」。在多 Agent 协作的 AI 工程体系里，管线数量越多，契约漂移的概率越高，因为每个 Agent 都有独立的迭代节奏，而接口文档往往是事后补写甚至根本没有。

我们是怎么修的，以及为什么之前没有防住

修复本身很简单：在 action_agent.py 里把字段名改回 channel_id，在 n8n Webhook 的输入校验里加了一个字段存在性检查——如果 channel_id 缺失就抛出显式错误而不是静默跳过。同时在 obs/04-content-pipeline/_inbox/ 里补了一份 payload 契约文档，记录每个字段的名称、类型、来源 Agent 和变更历史。

但我更在意的问题是：为什么之前没有防住？答案是我们对「接口稳定性」的假设太乐观了。在构建初期，为了快速迭代，我们对 Agent 间通信采用了松散的 JSON 结构，没有 schema 强校验，没有版本号，也没有变更通知机制。这在早期是合理的工程取舍，但随着管线数量增长，这个取舍的代价开始显现。

我们后来引入了一个轻量级的契约登记机制：每条 Webhook 对应一个 YAML 文件，声明期待的字段列表和类型；调用方在发送前先对照 schema 做本地校验；Webhook 收到请求后如果有未声明字段或缺失必填字段，返回 4xx 而不是 200。这个机制不完美，但它把「契约漂移」从一个隐性风险变成了一个显性错误。

可以带走的几条原则

一、把「契约」当作一等公民，和代码一起维护。 Agent 间传递的 payload 结构不是实现细节，是接口契约。字段改名、新增、删除都应该像改函数签名一样对待，写进 changelog，通知下游。

二、静默成功比显式失败更危险。 HTTP 200 只代表传输成功。业务层的失败如果没有显式信号，会在监控盲区里积累，直到某个依赖链路上的节点把问题放大。宁可让错误早点暴露，也不要让系统假装一切正常。

三、多管线系统里，单点变更的影响半径要主动评估。 在改一个字段名之前，搜一下这个字段被多少个调用方使用。这花不了五分钟，但能省掉一个凌晨的排查时间。

四、契约文档的价值在于「变更时有地方查」，不在于「写完就归档」。 文档如果不和代码一起更新，会比没有文档更有害，因为它会给人错误的安全感。

WF-09 这次故障最终修复只花了两小时，但它让我们重新审视了整个多 Agent 体系里所有 Webhook 的接口稳定性。排查下来发现有四个 Webhook 存在类似的潜在漂移风险。修复它们，比等下一次静默失败要划算得多。

如果你在构建 AI 工程团队，或者正在把多个 Agent 拼成一套协作管线，欢迎参考我们开源的 Synapse 框架。它是我们在实际生产中迭代出来的 AI 协作运营体系，包含了 Harness Engineering、Agent 间契约管理、执行链审计等实践。遇到的坑，我们大多已经踩过了。