2 篇博文 含有标签「api-contracts」

在事故复盘报告中，最昂贵的代码行反而是没人写出的那一行：一个字段缺失的 200 OK。原本应该将难题上报（Escalate）给更强模型的路由，在整整六周的时间里上报的流量为零。成本看板在欢庆，质量看板却在下滑——但仅限于那组被现有评估集低估的难题切片。直到客户投诉系统以前能正确处理的特定问题时，一切看起来都还像是场胜利。

起因是协议栈上层的一个响应结构变化。供应商的中级方案取消了逐 Token 的 logprobs，这在发行说明中被称作“特定层级的特性对等调整”。客户端收到的仍是有效的 JSON，HTTP 状态码依然是 200，响应中的模型标识符与请求中的模型标识符也完全匹配。唯一的变化是，路由用来做上报决策的字段消失了，而一年前在一次事故中添加的防御性默认设置，悄然变成了每个请求的生产环境默认行为。

一个下游搜索服务在周二下午发布了 v2.3.2 版本。发布说明提到重命名了一个状态字段，新增了一个可为空的 confidence 值，并重新排列了结果包中的数组。CHANGELOG 中没有任何内容被标记为破坏性变更。提供商自家的客户端库通过一个小版本更新消化了这些变化。你团队的 HTTP 集成通常会在一小时内记录下反序列化错误。但你的智能体——那个通过该搜索工具路由客户问题的智能体——并没有报错。它继续回答。问题依然得到解决。仪表盘依然是一片绿色。

六周后，有人注意到“缺货”回复在查询中的比例从 2% 攀升到了 11%。根本原因是 v2.3.2 的升级。重命名后的状态字符串从 in_stock 变为 available，而智能体——作为一个对文本进行灵活推理而非严格遵守模式（schema）的客户端——将旧令牌（token）的缺失解读为“无货”，然后将这一发现组织成乐于助人、语气自信但内容错误的客户消息。契约回归在消费者端被吸收了，而那里没有任何测试套件在监控。

这是传统的 API 规范（hygiene）从未被设计用来捕捉的故障模式。严格的客户端会大声报错。智能体则静默失效。你越是将智能体当作普通的 HTTP 消费者对待，这类 Bug 隐藏在看似正常的指标中的时间就越长。