25 篇博文 含有标签「debugging」

当你第一次尝试像调试服务那样调试 Agent 时，你会发现以往的肌肉记忆完全派不上用场。你设置了一个假设的断点——虽然 IDE 中没有面板可以放置它，但你在脑海中想象了一个——就在 planner 选错工具的那一步。你使用相同的输入重新运行。这一次，planner 选择了正确的工具。你再次运行。它又选了一个你从未见过的第三种工具。Bug 是真实存在的，你的同事今天早上复现了两次，而你用了十五年的调试器突然间变成了博物馆里的陈列品。

这里失效的心智模型并不是“使用调试器”，而是背后更深层的假设：即一个程序在给定相同输入的情况下，会产生相同的执行过程。现代调试器中的每一项功能——断点、单步跳过 (step-over)、观测表达式 (watch expressions)、条件断点、热重载——都是建立在这种确定性之上的。你暂停执行是因为暂停是有意义的。你向前单步执行是因为下一步是可预知的。你检查一个变量是因为它的值是一个事实，而不是从某种分布中随机抽取的结果。

当 AI 功能表现异常时，大多数工程师做的第一件事就是再次点击“运行（run）”。这种思路认为，模型是具有随机性的，所以这次运行可能只是运气不好。当第二次尝试产生看起来合理的结果时，工单就被关闭了。团队继续前进。而真正的 Bug——过期的工具响应、检索缺失、仅在包含特定 token 的输入时才触发的系统提示词冲突——仍然完好无损地留在生产环境中，等待下一个用户触发它。

这就是“重跑反模式（rerun antipattern）”，它是 AI 团队从聊天机器人时代继承下来的最昂贵的调试习惯。它看起来很严谨，因为模型确实是非确定性的。它看起来像是一种方差探测。但几乎没有人在重新运行之前写下假设，没有人预先决定多少次运行才算证据，也没有人考虑 token 的成本。正在发生的事情更接近于“老虎机式调试”：你不断拉动杠杆，直到红灯停止闪烁，然后你走开，并确信机器没问题。

质量在一夜之间下降了。值班工程师打开仪表盘，追踪了几个异常会话，并开始进行显而易见的二分定位：模型提供商在 UTC 时间 02:00 切换到了新的快照，于是将模型回退到固定的旧别名。评估套件仍然显示红色。回滚昨天的提示词更改。仍然是红色。将检索索引固定回上周的版本。仍然是红色。每个负责团队都在孤立地回滚自己的维度，并报告“不是我们的问题”。三个小时过去了，没有人负责诊断，因为没有人负责回归真正存在的交互面（interaction surface）——新模型以一种旧模型绝不会采取的方式，解释了新的工具描述。

这就是单轴工具无法解决的失败模式。git bisect 之所以有效，是因为搜索空间是一维的：提交记录的线性序列。而 Agent 没有单一的时间线。它有四到五个并行运行的时间线——模型快照、系统提示词、工具目录、检索索引、采样配置——每个都有自己的负责人、自己的部署节奏，以及自己的“回滚”按钮，只能将其自身的轴恢复到已知状态。你正在追踪的回归通常是一个双因素交互作用，沿着任何单一轴进行二分都会返回假阴性结果，因为该 bug 仅在“新模型遇上新工具描述”的交叉乘积单元格中触发。

一个回归错误流入了生产环境。团队选取了导致失败的输入，针对上周的提示词进行回放，却得到了不同的输出。现在他们必须查明原因——而答案埋藏在 3 MB 大小的文本差异、分歧的工具调用序列以及被打乱的检索块中，人类根本无法有效地进行比对（diff）。于是，他们将两份记录粘贴到左右分栏的查看器中，滚动查看了二十分钟，得出结论“模型今天感觉不太一样”，然后发布了一个并没有解决根本原因的热修复，因为他们从未找到真正的原因。

这就是 Agent 状态差异问题，也是通用工程工具在处理 Agent 系统时失效的首要环节。传统的回归二分查找（bisect）针对的是确定性代码：相同的输入产生相同的输出，git bisect 遍历历史记录，直到你找到破坏代码的提交。但 Agent 的运行不是确定性的，输入也不仅仅是一个字符串，其“历史”是一个多轴的包（envelope）——模型快照、采样配置、检索到的上下文、工具目录、框架标志——其中任何一个变量都可以独立地改变行为。

用户报告 Agent 给出了错误答案。你打开 Trace。模型的推理过程看起来没问题。工具调用全部返回 200 OK。Harness 日志显示没有重试、没有截断、没有异常。然而，答案就是错的。于是你花了接下来的两个小时，将三个具有不同格式、不同时钟的独立日志流缝合在一起，最终发现某个工具针对特定的查询形状静默返回了 {"result": null}，模型将这个 null 合理化为一个听起来合乎逻辑的事实，而 Harness 则愉快地将这个幻觉转发给了用户。这三个层级中的任何一个都没有单独记录任何警报。故障发生在连接处。

这是生产级 Agent 系统中最主要的故障模式，而大多数团队都在使用单层工具进行调试。模型团队归咎于工具。工具团队归咎于模型。平台团队归咎于 Harness。每个人都部分正确，因为 Agent 故障几乎从来不是单一组件的 Bug —— 它是三个组件之间的失配，而每个组件都在不同的“步骤”心理模型上运行。在你的 Trace 基础设施反映这一现实之前，你将不断为披着不同外衣的同类事故买单。

当你的 LLM 智能体失败时，最诱人的事情莫过于问它为什么。它会给出流畅、具体、看似充满自我意识的回答。它可能会说："我误解了用户的意图，检索了关于 X 的文档，而实际上应该定向到 Y。"听起来就像是根本原因。你把它记下来，打开提示编辑器，然后花四十分钟追查一个错误的问题。

这就是 LLM 自我调试的核心陷阱。模型的解释和模型实际的失败机制是两回事。有时两者重叠，但经常并不重合。在采取行动之前判断自己处于哪种情况，是区分快速调试和昂贵弯路的关键所在。

一个客服 Agent 在 12% 的工单中生成了幻觉式的故障排查步骤。HTTP 日志全部显示 200 OK。延迟正常。错误率平稳。从每一项传统指标来看，系统都是健康的——但它却在大规模地悄悄捏造答案。

当工程师最终对决策层进行插桩后，根本原因在几分钟内便浮出水面：检索到的文档块相似度得分全部低于 0.4，对上下文的置信度为 0.28，而模型输出的置信度却显示为 0.91。这是一个巨大的不匹配——在传统日志中完全不可见，但在捕获了决策状态的追踪中一目了然。

这就是将传统日志应用于 LLM 系统时的根本问题。I/O 日志告诉你系统运行了。AI 原生日志告诉你它是否推理正确。

一位我上季度合作过的 Staff Engineer 发现了一个在过去六周内已经被“修复”过三次的 bug。由三位不同的工程师处理，涉及三个不同的文件。三次 CI 运行都顺利通过。三次都采用了由 Agent 生成并被接受的补丁。每一个补丁都让失败的测试通过了，也让用户报告的错误消失了。但每一个补丁都只是把 bug 转移到了别处，潜伏在那里，直到被另一个表现面再次触发。当它第四次出现时，它导致的数据损坏已经静默累积了 40 天。

这个 bug 只是分页游标中一个简单的“差一错误”（off-by-one）。Agent 对于“症状会消失”的判断是正确的，但它对“原因”的判断是错误的。而那些优秀的、资深的、动机良好的工程师们，在理解失败机制之前，就各自接受了一个通过测试的补丁。

这就是“智能代理调试陷阱”（agentic debugger's trap）：你的 Agent 生成修复方案的速度，超过了你构建评估该方案正确性所需的心智模型（mental model）的速度。补丁速度超过了诊断速度。Bug 数量下降了，CI 面板变绿了，而你交付的代码库，其失败模式你却不再理解。

晨会上出现了一个回归问题：支持代理昨晚回答错了三个客户问题。有人说：“我们试试在这个路径上用 Opus，看看能不能解决。”四十分钟后，评估通过率回升了，团队关闭了工单，而该路径上的推理账单悄然翻了三倍。六周后，同样形式的回归出现在另一个路径上，并采用了同样的修复方法。你的团队刚刚训练出了一种巴甫洛夫反射：质量回归 → 增加算力。更大的模型是你的技术栈中最昂贵的调试工具，而你现在却首先想到它。

问题不在于更大的模型没有帮助。它们确实有——有时甚至很大。问题在于，更大的模型是一种绝对占优的“掩盖”策略。当提示词指令冲突、检索返回了过时的块、工具描述被误读，或者评估集没有覆盖失效的分布时，更强大的模型会绕过这些故障而不修复其中的任何一个。下一次回归仍具有相同的根本原因，账单已经复加，而底层系统变得更加脆弱，而非更加稳健，因为升级带来的缓冲空间让所有人都不再去探究底层逻辑。

智能体用 400 毫秒回答了一个简单的问题，然后因递归限制错误（recursion-limit error）崩溃。Trace 显示了 25 次工具调用。从上到下阅读 Trace，工程师会得出结论：智能体糊涂了 —— 以略有不同的顺序反复调用那几个工具，始终无法收敛。这个结论是错误的。智能体并没有糊涂。它陷入了一个死循环：工具 A 调用了模型，模型选择了工具 B，工具 B 的实现再次调用模型来格式化其输出，而格式化程序又选择了工具 A。Trace UI 将四个嵌套调用渲染为扁平列表中的四个兄弟调用，导致唯一能发现问题的开发者也无法察觉这个循环。

这就是工具重入（tool reentrancy），这是一种你的函数调用层几乎肯定没有建模的 Bug 类别。并发安全的代码对此已有数十年的原语支持：记录同一线程嵌套获取次数的重入互斥锁（reentrant mutexes）、语言层面的递归限制、堆栈检查 API，以及一种文化共识：任何回调运行时的函数都需要一个明确的契约，规定允许何种重入。工具调用层默认采用“发后即忘”（fire-and-forget）模式。运行时没有可供检查的调用栈，调度前没有循环检测器，工具定义上没有重入属性，Trace UI 的形式像日志而非图。结果就是，任何超过十几个条目的工具目录都会悄悄变成框架无法察觉的递归。

用户将一份冗长且复杂的错误报告粘贴到你的 AI 助手。它看起来像是一个经典的空指针问题，其措辞和代码布局与数以千计的 Stack Overflow 帖子如出一辙。模型自信地做出了响应，引用了常用的修复方案，听起来非常权威。用户向它表示感谢。然而，错误依然存在。这份报告实际上关于的是竞态条件 (race condition)；空指针的表述只是用户描述症状时的偶然方式。

这是在生产环境 LLM 系统中捕捉难度最高的一类 Bug。模型没有拒绝回答，没有推诿。它没有幻觉出一个虚假的 API。它只是极其流畅地解决了错误的问题，而下游的所有环节——包括用户、你的评估流水线、你的护栏 (guardrails)——都看到了一个看似合理且切中要害的回答，然后继续下一步。我将此称为模式匹配失败 (pattern-matching failures)：模型锁定了查询的表面特征，并针对与实际提出的问题相邻的问题给出了一个自信的答案。

某用户提交了一个支持工单："你们的 AI 助手告诉我合同续签截止日期是 3 月 15 日，实际上是 2 月 28 日，我们因此错过了截止日期。"你调出日志，响应已生成，模型没有报错，所有指标都是绿色。但你根本不知道它检索了哪份文档、模型读取了什么内容，也不知道那个日期究竟来自上下文还是完全被幻觉出来的。

这就是数据血缘的缺失。这不是监控问题，而是从一开始就埋下的架构问题。