AI 智能体调试：你的仪表盘只知成本，不知根因

AI智能体调试始于可观测性仪表板终止之处。当AI编程智能体破坏了某些东西，而运行早已结束时，仪表板只能告诉你本次运行的成本（token、美元、延迟），却对你真正关心的唯一问题避而不答：智能体为什么改了那个文件？能回答这一问题的产物，是一段你可以打开、阅读并重放的录制轨迹，因为它把运行过程交还给你，而不是从外部进行描述。

从智能体开始真正干活的那一刻起，这就不再是稀罕事了。智能体会扫遍整个代码仓库，编辑好几个文件，运行检查，然后报告成功——这一切都发生在你相隔几分钟输入的两条提示之间。如果其中某次编辑出错了，你只能事后才发现：终端已经关闭，回滚缓冲区已经清空，那个本可以自我解释的进程已经退出。接下来会发生什么，完全取决于你保留了些什么。如果你保留的是一块成本仪表板，那你即将进行考古；如果你保留的是一段录制，那你即将进行阅读。

你无法复现的故障

事情大致是这样的：你回到代码仓库，发现一个你从未让任何人碰过的文件被重写、被删除，或被掏空——而那个其他一切都依赖的函数也不见了。你去问智能体发生了什么，可会话已经关闭；即便转录记录还在，智能体对自己这次运行的叙述也只是事后重构，而非实录。于是你顺理成章地重新跑了一遍，却得到另一次运行：不同的工具调用、不同的编辑，甚至可能根本没有失败，因为最初的轨迹取决于采样、取决于仓库的状态、取决于时序。而你需要检查的那次运行，已经不存在了。

这比不可重现更糟糕。它不可重现，却被标记为成功。当代理以 0 退出时，整个运行也以 0 退出，即使运行内部的某个检查以 1 退出：流水线可能显示绿色，而运行内的验证步骤实际已失败，而你自然会信任的退出码其实什么都没告诉你。

无论路由器为这次运行选择了哪个模型（GLM 5.3 Flash 还是其他模型）：一旦进程退出，推理过程也随之消失。证据只在运行期间存在：提示词、工具调用、输出、差异（diff）。如果没有任何记录，“它为什么改了那个文件”就没有答案。只剩推测。

这就是将AI 编程智能体与以往所有工具区分开来的失败模式：损害和解释发生在同一处，而该处随即关闭。

仪表盘衡量什么，又跳过了什么？

一次糟糕的运行之后，你的本能反应是打开可观测性仪表板，而仪表板确实很擅长它的本职工作。它的本职是流量：每天的 token 数、各模型的成本、延迟和错误率。对于容量规划和计费来说，这正是合适的工具；如果你在生产环境中运行 agent，就应该让它保持开启。

但你的问题并非聚合性的。它是具体的、因果性的：为什么这次运行改变了这个文件？聚合恰恰跳过了回答该问题所需的粒度。在多次运行中求平均时，你所关心的那次运行成了噪声；而在那次运行内部，你所关心的那次工具调用又成了噪声。

仪表盘是从外部描述一次运行：它发生过、它有多重、它花费多少。它无法将那次运行交到你手中，而“为什么”并非描述的一种属性。它是序列的一种属性。

• 这次运行的费用是多少？— 成本仪表盘可作答 vs 已记录的追踪可作答

• 为什么代理更改了该文件？ — 成本仪表板 无答案 vs 已记录的跟踪 编辑，按顺序，及其差异

• 绿色运行中哪一项检查失败？ — 成本仪表板：无答案 vs 记录的跟踪：该检查及其退出代码。

• 能否再次精确重现同一故障？ — 成本仪表板：否 vs 记录轨迹：可以，离线，且无需成本

解答这一问题的层面位于更底层：记录的请求日志，这些日志在运行发生时被捕获，包含了发送的每个提示、发出的每次工具调用、返回的每个响应，并按顺序排列。不是运行的摘要，而是运行本身。

将一次运行当作时间线来解读。

有了录制，调试就不再是考古，而成了阅读。没有录制时，你做的事就是考古：翻查 git reflog、stash 记录、shell 历史，还要凭记忆回想当天早些时候自己提过的需求。有了录制，你做的事就是阅读：打开时间线，向下滚动浏览。

时间线按实际发生顺序展开整个运行过程：启动它的提示词、每一次工具调用、每一次带 diff 的文件编辑、每一次检查、每一个退出码。文件系统快照按轮拍摄，而不是按工具调用拍摄——这足以让你在对话的每一步都能看到仓库的状态，又不会被单次调用的噪声淹没。让它成为调试而非浏览的，是相邻性：那次编辑和发现问题的检查按顺序紧挨在一起，中间没有任何需要猜测的东西。“为什么”在很大程度上是相邻性的一种属性。

一个具体的例子，直接从录下的修复记录中读出：14 个事件，包括打印为 +1 -3 的文件改动，以及一次以退出码 1 失败的检查。那次编辑，以及随后因它而失败的检查，在记录中相邻。这就是从零散片段重建一次运行与直接读取一次运行之间的全部区别。这一点对终端编码智能体最为重要，其工作空间是一个任务一结束就会关闭的终端：时间线就是留存下来的回滚缓冲。

记录还是推断：追踪所知道的，对比它推导出的

时间线告诉你按顺序发生了什么。因果图告诉你什么导致了什么，而这两者之间的差距，正是信任必须赢得的地方。

该图将事件连接起来：先是这次编辑，然后是这次失败的检查。其中一些边是记录下来的事实——产生 diff 的那次工具调用就明明白白地留在追踪记录里。另一些边则是推断出来的，例如图得出“检查失败是由那个 diff 导致的”这一结论。orca graph 会为每条边标注 recorded（已记录）或 inferred（推断），并且无论哪种情况都会指明其所依据的规则，因此你永远都能分清自己看到的究竟是这次运行实际做过的事，还是工具对这次运行分析得出的认识。

这种区分是强制执行的，而不是一句口号：推断出的边永远不会被写回追踪记录。追踪记录仍然是对所发生事件的忠实记录；推断只是叠加其上的一种视图，你可以检查、质疑，甚至不认同它。当涉及多个智能体时，这一点最为关键。当重构智能体和编写测试的智能体修改同一批文件时，“这次改动是哪个智能体造成的”正是多智能体归因所要回答的问题。一条边若悄悄把自己从推断升格为事实，到头来你调试的就会是一个故事，而不是一次运行。

可随意免费复制，想复制多少次就复制多少次，分文不取。

阅读能解释，回放能证明。一旦你有了一个假设（检查失败是因为编辑删除了重置调用），你就会想再次运行它，亲眼看着它发生。重新运行实时智能体会让你获得一条新的轨迹和一张新的账单。

重放这段录制能让你获得完全相同的运行：重放时网络被阻断，因此不消耗 token，也没有任何随机性。每次都是同样的事件，在离线状态下发生。正是这个特性，让智能体调试从“赌博”变成了“工程”：失败变得确定，而确定的失败终会被修复。

这套工具同样并非黑箱。OrcaReplay以 Apache-2.0 协议开源，其跟踪格式采用 CC BY 4.0，因此任何人都可以重新实现它：你的录制内容不会被专有格式绑架，我们自己的也不例外。而且它是经过实际运行检验的，而不只是演示——在 Node 20 和 Node 22 上共有 1393 个测试。在把团队的运行记录托付给它之前，你可以亲自阅读源代码、检查格式，并运行整套测试。

要点

仪表盘是一张账单。被记录的轨迹才是运行本身。如果你调试AI智能体的方案止步于成本仪表盘，那你并没有调试方案：你只有一套计费系统。仪表盘永远能告诉你一次运行花费了多少，却永远无法告诉你智能体为什么删除了你的文件，因为“为什么”存在于序列之中，而序列只有在你保留它时才会存在。

整个方法分为四个步骤：

• 记录运行。

• 阅读时间线。

• 检查图的边。

• 免费重播那些让你害怕的内容，次数不限。

来源说明：本文中的每个数字均为厂商报告，来自我们自己的产品和 OrcaReplay 仓库及其文档：某次运行的退出码行为、带有 +1 -3 差异和 exit-1 检查的 14 事件记录修复、orca graph 中的边标注、每回合一次的快照节奏、阻断网络时的离线重放，以及 Node 20 和 Node 22 上的 1393 项测试套件。本文未引用任何第三方测量结果。1393 项测试套件是唯一您可以自行验证的说法——克隆仓库并运行即可。所有条目最后核验时间为 2026-09-04。