告别 " 黑箱调试 "！能精准定位 AI 代码 Agent 失败根源的可追溯框架来了。

随着 LLM 代码智能体的能力越来越强，但有一个关键问题始终没有被解决——当这些 Agent 失败时，我们往往不知道 " 它在哪一步出了错 "。

现有评测通常只关注最终的成功与失败，却对过程中每一步决策的对错一无所知。

于是来自南京大学 NJU-LINK 实验室刘佳恒老师课题组、快手科技等机构的研究者提出了 CodeTracer。

这是一个无需重新训练的轨迹追溯框架，可将 Agent 的运行状态转化为层级化状态树，自动定位任务失败的起始节点，并将生成的诊断信息反馈给 Agent ，从而实现错误恢复与执行恢复。

以下是更多详细内容。

为什么 AI 代码 Agent 的调试如此困难？

近年来，SWE-Agent、OpenHands 等代码 Agent 已可在真实软件仓库中自主完成漏洞修复、代码重构、终端交互等复杂任务。

但随着任务复杂度提升，Agent 的执行轨迹也愈发冗长：一次完整流程往往包含数百至上千个异构步骤：代码检索、文件读取、逻辑修改、项目构建、测试结果解析等。

当 Agent 完成 task 失败时，开发者面临的核心困境在于：整条执行链究竟从哪一步开始偏离正轨？

现有评测体系大多仅关注最终结果，只区分成功或失败，忽略了过程中决策的合理性，这导致了三大核心痛点：

1、错误链隐蔽：

Agent 早期的一次错误判断会逐级传导，引发后续连锁失败，最终导致整体任务失败。但缺乏步骤级的诊断能力，这条错误链几乎无法被追溯。

2、无效循环陷阱：

Agent 一旦陷入错误假设，往往会在无意义操作中反复循环，消耗大量 Token 与计算资源，却无法自主纠偏。

3、诊断难以规模化：

现有轨迹分析方法要么仅适用于简单交互场景，要么依赖人工逐行核查，无法应对真实工程中数千条轨迹的规模化分析需求。

其实问题根源在于，当前主流的四大 Agent 框架（SWE-Agent、MiniSWE-Agent、OpenHands、Terminus 2）在设计理念上差异明显，架构或轻量极简或重度编排，执行方式支持串行或并行，但无一具备失败后精准定位错误节点的能力。

而 CodeTracer 正是为解决这一共性难题而生。

CodeTracer 是如何工作的？

CodeTracer 的核心思路是：把 Agent 运行产生的杂乱日志，转化为结构化的执行状态历史，自动定位失败根因并将诊断信息反馈给 Agent，实现错误修正。

整个流程分为三个紧密协作的核心模块：

1、运行日志解析——进化式提取（Extraction Agent）

不同 Agent 框架的日志格式互不兼容，若为每个框架单独开发解析器，不仅维护成本高，还极易因框架升级、格式变更而失效。

为此，CodeTracer 设计了 " 探索 - 适配 - 复用 " 策略：首先自动扫描运行目录，识别日志结构；然后在解析器注册表中查找匹配的现有解析器；若无匹配项，则自动生成一个新解析器并注册入库，供后续同类格式复用。

随着适配场景不断丰富，系统兼容性持续增强。最终，将各类异构日志统一为标准化步骤记录，包含动作、观测结果、代码差异、验证结果等结构化信息。

2、构建执行视图——层级轨迹树（Structuring Agent）

解析完成后，系统将扁平的执行序列转化为层级轨迹状态树，其关键在于区分两类步骤的本质差异：

探索步骤：

只读取、搜索环境而不修改代码状态，说明 Agent 仍处于信息探查阶段；

状态变更步骤：

对代码库或执行环境产生实际修改，会触发状态跳转并生成新的子状态节点，标志着 Agent 完成了一次关键决策。

每个节点还附加意图与结果摘要，使整棵树成为一个压缩版的导航索引。诊断无需从头逐行阅读原始日志，即可快速定位从哪一次状态变更出现偏差。

3、精准定位与反思回放（Trace Agent + Reflective Replay）

Trace Agent 沿轨迹树进行遍历检索，输出三项诊断结果：失败责任阶段（Failure-Responsible Stage）、错误相关步骤集合（Error-Relevant Steps），以及支撑诊断结论的精简证据集（Evidence Set）。

在此基础上，这份诊断信号可作为前置提示注入原 Agent，驱动其在相同资源约束下重新执行任务，即 " 反思回放 " 机制。

值得注意的是，诊断过程中消耗的 Token 不计入回放预算，保证对比公平：回放的 Agent 与原始 Agent 拥有完全一致的迭代次数与 Token 配额 ，唯一的区别是提前获知上一轮的错误节点。

横向对比工业界框架和学术框架

另外，为了更直观地展示 CodeTracer 作用，研究团队还对常用 Agent 框架进行了量化分析。

学术 SOTA 框架对比

对于学术界与工业界广泛使用的四大 Agent 框架，从任务成功率与执行成本两个维度看：

数据背后的规律十分清晰：

MiniSWE ‑ Agent

作为极简轻量框架，工具与流程设计精简，以最少步骤和最低 Token 消耗完成任务，成功率 32.8%。

Terminus 2

在其基础上适度增加编排开销，Token 消耗小幅上升，成功率同步提升，成本与收益相对匹配。

SWE ‑ Agent

与OpenHands属于重量级框架，两者采用复杂多阶段流程与丰富工具集，Token 消耗接近 MiniSWE ‑ Agent 的两倍，但成功率仅分别提升至 37.5% 和 38.3%，相比轻量框架仅高出约 5 个百分点。

研究由此揭示一个关键结论：在通用终端编程任务中，框架复杂度与成功率并非线性相关。

过度复杂的编排设计，往往只带来更长执行链路与更高 Token 成本，却无法带来能力上的本质突破。

决定任务成功率上限的核心，是底层模型的推理能力，而非框架架构的复杂度。

这一发现对于工程实践具有明确的指导意义：在选择 Agent 框架时，盲目追求复杂架构并不明智。搭配合理模型的轻量框架，即可实现与重量级框架接近的效果，同时具备显著的成本优势。

Claude Code 对比分析

研究团队将 CodeTracer 进一步用于工业级 Agent Claude Code 的轨迹分析，并与学术框架对比，揭示出显著结构差异：

1、工具生态量级差异：

Claude Code 内置 40 余种专用工具，覆盖 8 大功能类别；而学术框架仅具备 5 – 10 种通用工具，复杂任务下的细粒度操作能力差距明显。

2、上下文管理的成熟度差异：

Claude Code 内置上下文压缩、Token 追踪、功能门控等机制，可支撑更长的有效轨迹；而学术框架普遍缺乏此类设计，导致在长轨迹任务中易出现上下文溢出或信息丢失。

3、探索 - 变更比例的结构差异：

Claude Code 的探索步骤占比显著更低，单次探索后能产生更多有效状态变更，这一指标与任务成功率高度相关，也印证了证据转化能力是区分高效 、与低效 Agent 的核心指标。

4、并行执行带来的新挑战：

工业 Agent 支持并行工具调用，执行效率更高，但也引入了执行顺序依赖、偶发错误难复现等问题，这是顺序执行的学术框架所不存在的新挑战，也是工业 Agent 诊断的一大难点。

5、工程和模型的拟合：

我们测试了多种模型，只有 claude 模型的表现较为优异（claude sonnet 4.5 52.1% 解决率）其他模型均和 claude code 框架并不适配，解决率并不理想，在泛化性方面和学术框架有较大差异，claude code 的工程设计对模型有做过专门的优化。

6、榜单标化分数的反思：

claude code 框架如此成熟的体系却在 terminal bench 上并没有取得预期非常高的分数，随着对错误样例的分析，terminal bench 一些 task 的设计和现实场景脱离，模型给出了实际解决问题的方案却无法迎合出题人的意图。

上述对比表明，CodeTracer 的设计可良好适配工业场景，其步骤级偏差标注还可作为密集训练信号用于工业 Agent 优化训练，但同时框架本身对 claude 模型的行为模式有着强依赖性，工程在模型行为上有着拟合。

深度解剖 Agent 行为：失败是怎么发生的？

除了框架层面的横向对比，研究团队还借助 CodeTraceBench 的步骤级标注，对 Agent 内部的行为模式进行了深度分析，解释了其失败背后的共性规律。

1、模型各有所长，但是失败模式高度趋同

在 340 类任务中，66 类常规任务可被全部五款模型解决，65 类高难度任务（如形式化验证、高级科学计算）则无一模型能完成。

各模型在专长上差异明显：GPT-5 擅长图论与化学任务，Claude-sonnet-4 擅长贝叶斯推断，Kimi-K2-Instruct 突出于图形渲染，DeepSeek-V3.2 则在数据管道与包管理更具优势。

但面对共同无法解决的难题时，所有模型的失败行为高度一致：普遍通过捏造证据、占位输出或提前终止来掩盖失败，而非坦诚报错。这种失败掩盖行为与模型能力强弱无关，值得高度警惕。

2、错误类型与执行阶段高度相关

通过对每条轨迹按执行阶段，即按环境验证、依赖安装、代码修改、验证等阶段拆解后发现：

早期阶段：

以环境配置、依赖安装为主，问题易被忽略并持续级联扩散；

中后期阶段：

以错误定位、错误假设与验证结果误读为主，Agent 常定位到可疑代码，但实际修改方向或结果解读错误。

与此形成对比，成功轨迹流程顺畅、阶段无反复振荡；而失败轨迹则在早期就过度消耗了 Token，陷入错误假设后的无效循环。

这一错误的可预测性为分阶段预警、提前阻断错误链提供了可行思路。

3、成功率在早中期快速饱和，盲目加迭代毫无意义

研究者对 max_iterations 从 5 到 300 进行了全面扫描，覆盖五款模型与三种 Agent。结果显示：

迭代至约 35 — 40% 最长长度时，成功率快速上升；

中后期曲线趋于饱和，额外迭代几乎不再提升效果。

成功率上限主要由基本模型推理能力决定，与 Agent 框架设计关系差异并不大，比如 Claude-sonnet-4、GPT-5、DeepSeek-V3.2 均在各自步数达到上限后不再增长。

当 Agent 早期就形成了错误假设，额外的迭代多数只会空耗资源，并不能纠正底层认知偏差。

这也进一步印证了：在正确的时机提供正确的诊断信号远比给 Agent 更多次数的机会重试更有价值。

4、核心症结：探索与行动中的鸿沟

通过对每条轨迹步骤预算的拆解分析，研究发现了一个贯穿所有模型与框架的关键问题——证据 - 行动鸿沟（Evidence-to-Action Gap）：

失败轨迹中无效步骤占比约 40%，接近成功轨迹（22%）的两倍；

正确状态变更步骤从 30% 降至 21%，而探索信息获取能力下降并不明显。

这说明：Agent 失败并非找不到关键信息，而是无法将有效证据转化为正确决策。

这种鸿沟在 Qwen3-Coder-480B 与 Kimi-K2-Instruct 的身上体现得尤为突出，Claude-sonnet-4 和 GPT-5 则相对更小，说明更强的基本模型在证据转化上的优势。

这也正是 CodeTracer 反思回放机制的设计初衷：Agent 真正需要的不是更多重试机会，而是清晰的错误根因提示。

实验结果

最后研究团队在 CodeTraceBench 上，以精确率 P、召回率 R、F1 值及 Token 消耗为指标，对比了纯 LLM、Mini-CodeTracer 与完整 CodeTracer 三种定位方案：

在各类基本模型上，CodeTracer 均大幅优于直接 LLM 基线：F1 分数从 16% – 19% 提升至 46% – 48%，同时 Token 消耗明显下降。

核心原因在于其树形结构实现了证据聚焦检索，避免了对全量原始日志的低效遍历。

不同模型的诊断风格差异明显：

GPT-5 追求效率，精确率最高（45.0%）且 Token 开销最低（31.1k）；

Claude-sonnet-4 偏向全面检索，召回率最高（54.9%），适合高严谨度场景；

DeepSeek-V3.2 精度与召回均衡，整体表现最稳健。

研究者在 Mini-CodeTracer 基础上逐步叠加组件，验证各模块的独立贡献：

加入 " 进化式提取 " 后，F1 提升约 9 个百分点；

再加入 " 树形索引 " 后，F1 进一步提升约 18 个百分点，这证明了压缩式层级导航是实现精准错误定位的关键，而非辅助功能。

将 CodeTracer 的定位证据注入给原始失败的 Agent，在匹配的 Token 预算内重新执行，得到如下结果：

所有骨干模型的 Pass@1 均有显著提升，且诊断 pass 本身的额外 Token 消耗仅为 5k – 8k，性价比极高。

这说明 CodeTracer 的诊断信号能够有效帮助 Agent 修正早期的错误假设，避免无效重试，将计算资源集中在关键步骤。

总的来说，CodeTracer 是一个开源、无需训练的代码 Agent 轨迹追溯框架。

通过进化式日志提取、层级化状态树索引、失败起点自动定位三位一体的设计，系统性解决了长执行轨迹中 " 错在何处、为何失败 " 的核心诊断难题，并通过反思回放机制，将诊断信息转化为任务性能提升。

本研究的核心贡献可归纳为三点：

1、提出CodeTracer 框架，相比直接 LLM 提示基线，F1 分数提升近 30 个百分点，同时有效降低 Token 消耗；

2、构建CodeTraceBench 评测基准，作为首个步骤级代码轨迹评测集，覆盖 4 种主流框架、5 种骨干模型，包含数千条高质量标注轨迹；

3、形成一系列实证洞见，包括框架复杂度与成功率无显著线性关系、证据 - 行动鸿沟、错误分布与执行阶段强相关等关键规律。

但当前工作仍存在若干局限：轨迹标注仍涉及人工判断，对极复杂轨迹的分析存在一定主观性；评估基于离线轨迹，未能完全复现在线人机协作场景；反思回放验证了错误恢复的有效性，但尚未形成通用的训练信号生成范式。

展望未来，随着代码 Agent 能力与任务复杂度不断提升，让模型具备 " 自知失败原因 " 的能力，将成为推动 AI 软件工程走向可靠、可解释的关键。

对研究者而言，CodeTraceBench 提供了前所未有的细粒度评测视角；对工程实践者而言，CodeTracer 的诊断框架则是一个可以即插即用的调试工具。

二者共同为代码 Agent 从 " 可用 " 走向 " 可信 " 提供了重要的底层支撑。

代码链接：https://github.com/NJU-LINK/CodeTracer

论文链接：https://arxiv.org/abs/2604.11641

一键三连「点赞」「转发」「小心心」

欢迎在评论区留下你的想法！

—  完  —

我们正在招聘一名眼疾手快、关注 AI 的学术编辑实习生 

感兴趣的小伙伴欢迎关注  了解详情

点亮星标

科技前沿进展每日见