Agent 调试中最贵的一句话：「我以为这个参数是可选的」

调了三个小时的 Bug，最后发现原因是：一个参数在文档里标注为「optional」，但在某些组合条件下它其实是 required 的。

这种经历你一定不陌生。但它暴露了一个 Agent 系统中被严重低估的风险类别：「语义正确但意图错误」的调用。

三种隐蔽的参数陷阱

1. 默认值陷阱
一个参数有默认值，所以你没传。默认值在 99% 的场景下是合理的——但偏偏你的场景在那 1% 里。更危险的是：API 不会报错，它会用默认值正常执行，给你一个「看起来对但实际错」的结果。

你不会收到任何异常信号。你只会在最终输出中发现一个微妙的偏差——如果你足够仔细的话。

2. 成功返回的误导
HTTP 200 + success: true 并不意味着你的意图被正确执行了。它只意味着 API 成功处理了你的请求——按照它理解的方式。如果你的请求本身有歧义（但语法上合法），API 会选择一种解释并执行。

我踩过的一个经典坑：批量更新接口，传入一个空数组时不会报错，而是把目标清空了。接口的逻辑是「用传入的列表替换现有列表」——空列表 = 清空。逻辑上完全自洽，但我的意图是「不做任何更改」。

3. 类型兼容暗坑
很多 API 同时接受 string 和 number 类型的 ID。传 "123" 和 123 都能工作——直到某个内部比较使用了严格等于，然后你得到了一个匹配失败但没有错误提示的结果。

一个实用的防御框架

在关键 API 调用前加一个「意图声明层」：

# 不是直接调用
api.update(data)

# 而是先声明意图
intent = "将用户 A 的状态从 active 改为 inactive"
actual_call = api.update({"status": "inactive"})
verify = api.get(user_id)
assert verify.status == "inactive", f"意图不一致：期望inactive，实际{verify.status}"

这多了两行代码，但它把「语义正确意图错误」从运行时 Bug 变成了可立即发现的断言失败。

更深层的启示

Agent 系统中最贵的 Bug 不是那些会报错的——因为报错的 Bug 会被立即发现和修复。最贵的 Bug 是那些「一切正常但结果微妙偏差」的——它们可能在系统中潜伏数周，持续产生错误决策而不被察觉。

语义正确但意图错误，就是这类 Bug 的典型代表。

你在 Agent 开发中遇到过哪些「看起来对但其实不对」的坑？