南大快手推出可追溯框架精准定位Coding Agent失败根源无需重训即插即用

来自南京大学NJU-LINK实验室刘佳恒老师课题组与快手科技等机构的研究者，最近提出了一个名为CodeTracer的框架。这个框架的目标很明确：让AI代码智能体的失败变得可追溯、可诊断，从而告别“黑箱调试”的困境。

随着大语言模型驱动的代码智能体能力越来越强，它们能处理的任务也愈发复杂。然而，一个关键问题始终悬而未决：当这些智能体最终任务失败时，开发者往往很难 pinpoint 问题究竟出在哪一步。现有的评测体系通常只关注最终结果是成功还是失败，对于执行过程中每一步决策的对错，几乎一无所知。正是为了填补这一空白，CodeTracer应运而生。

这是一个无需重新训练的可追溯框架。它的核心思路是将智能体杂乱的运行日志，转化为结构化的层级状态树，自动定位任务失败的起始节点，并将诊断信息反馈给智能体，从而帮助其实现错误恢复与执行恢复。

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

近年来，像SWE-Agent、OpenHands这样的代码智能体已经能够在真实的软件仓库中自主完成漏洞修复、代码重构乃至终端交互等复杂任务。但任务越复杂，智能体的执行轨迹就越冗长。一次完整的流程可能包含数百甚至上千个步骤，涉及代码检索、文件读取、逻辑修改、项目构建、测试结果解析等多种异构操作。

当任务最终失败时，开发者面临的核心困境在于：这条长长的执行链，究竟是从哪一步开始偏离了正轨？现有评测体系“只问结果，不问过程”的做法，导致了几个突出的痛点：

首先，错误链极其隐蔽。智能体早期的一个错误判断，可能会像多米诺骨&牌一样引发后续一连串的失败，最终导致整体任务崩溃。但如果没有步骤级的诊断能力，这条错误链几乎无法被追溯。

其次，存在无效循环陷阱。智能体一旦陷入某个错误的假设，往往会在无意义的操作中反复打转，消耗大量计算资源（Token），却无法自主跳出这个循环。

最后，诊断难以规模化。现有的轨迹分析方法，要么只适用于简单的交互场景，要么严重依赖人工逐行检查，根本无法应对真实工程环境中动辄数千条的轨迹分析需求。

问题的根源在于，当前主流的几大Agent框架（如SWE-Agent、MiniSWE-Agent、OpenHands、Terminus 2）在设计理念和架构上差异显著，有的追求轻量极简，有的侧重重度编排，执行方式也分串行和并行。但遗憾的是，它们都缺乏在失败后精准定位错误节点的能力。而CodeTracer，正是为了解决这个共性难题而设计的。

CodeTracer是如何工作的？

简单来说，CodeTracer的工作流可以概括为三步：解析日志、构建视图、定位与回放。它将智能体运行产生的“天书”般的日志，转化为清晰的结构化历史，并自动找出失败的根因。

整个流程由三个核心模块紧密协作完成：

1. 运行日志解析——进化式提取
不同的Agent框架输出的日志格式千差万别。如果为每个框架都单独开发一个解析器，不仅维护成本高，而且一旦框架升级或日志格式变动，解析器很容易失效。CodeTracer采用了一种“探索-适配-复用”的智能策略：先自动扫描运行目录，识别日志结构；然后在内部的解析器注册表中查找是否有现成的匹配解析器；如果没有，就自动生成一个新的解析器并注册入库，供后续遇到同类格式时直接复用。这种设计让系统的兼容性能够随着使用场景的丰富而持续增强。最终，所有异构日志都被统一为标准化的步骤记录，包含动作、观测结果、代码差异等关键信息。

2. 构建执行视图——层级轨迹树
解析完成后，系统会将扁平的执行序列，转化成一棵层级分明的轨迹状态树。这里的关键在于区分两类步骤：探索步骤（只读取环境信息，不修改代码状态）和状态变更步骤（对代码或环境产生了实际修改）。后者会触发状态跳转，并生成新的子状态节点，标志着智能体完成了一次关键决策。

每个节点还附带了意图与结果的摘要。这样一来，整棵树就变成了一个高度压缩的导航索引。进行诊断时，无需再从头逐行阅读原始日志，就能快速定位到是哪一次状态变更出现了偏差。

3. 精准定位与反思回放
Trace Agent模块会沿着构建好的轨迹树进行遍历检索，最终输出三项诊断结果：失败责任阶段、错误相关步骤集合，以及支撑诊断结论的精简证据集。

更重要的是，这份诊断信号可以作为“前置提示”注入给原来的智能体，驱动它在相同的资源约束（相同的迭代次数和Token预算）下重新执行任务，这就是“反思回放”机制。值得注意的是，诊断过程本身消耗的Token不计入回放预算，确保了对比的公平性——回放的智能体与原始智能体唯一的区别，就是提前知道了上一轮错误发生在哪里。

横向对比：工业界框架与学术框架的差异

为了更直观地展示CodeTracer的价值，研究团队对常用的Agent框架进行了一次量化分析，揭示了学术界SOTA框架与工业级框架之间的显著差异。

首先看学术界广泛使用的四大框架（MiniSWE-Agent, Terminus 2, SWE-Agent, OpenHands），从任务成功率和执行成本两个维度来看：

数据背后规律清晰：MiniSWE-Agent作为极简轻量框架，以最少的步骤和最低的Token消耗完成了任务，成功率为32.8%。Terminus 2在其基础上适度增加了编排，Token消耗小幅上升，成功率也同步提升，成本与收益相对匹配。而SWE-Agent和OpenHands属于重量级框架，采用了复杂得多阶段流程和丰富的工具集，其Token消耗接近MiniSWE-Agent的两倍，但成功率仅分别提升至37.5%和38.3%，相比轻量框架只高出约5个百分点。

这揭示了一个关键结论：在通用终端编程任务中，框架的复杂度与成功率并非线性正相关。过度复杂的编排设计，往往只带来更长的执行链路和更高的计算成本，却无法带来能力上的本质突破。决定任务成功率上限的核心，仍然是底层大语言模型的推理能力，而非框架架构本身的复杂度。这对工程实践具有明确的指导意义：盲目追求复杂架构可能并不明智，搭配合理模型的轻量框架，往往能以更低的成本实现接近的效果。

研究团队进一步将CodeTracer用于分析工业级Agent Claude Code，并与学术框架对比，发现了更深刻的结构性差异：

1. 工具生态的量级差异：Claude Code内置了40多种专用工具，覆盖8大功能类别；而学术框架通常只有5-10种通用工具，在复杂任务下的细粒度操作能力差距明显。
2. 上下文管理的成熟度差异：Claude Code内置了上下文压缩、Token追踪、功能门控等机制，能支撑更长的有效轨迹；学术框架普遍缺乏此类设计，长轨迹任务中容易发生上下文溢出或信息丢失。
3. 探索与变更的比例差异：Claude Code的探索步骤占比显著更低，单次探索后能产生更多有效的状态变更。这一指标与任务成功率高度相关，印证了“将证据转化为有效行动”的能力是区分高效与低效智能体的核心。
4. 并行执行带来的新挑战：工业级Agent支持并行工具调用，效率更高，但也引入了执行顺序依赖、偶发错误难复现等新问题，这是顺序执行的学术框架所不存在的诊断难点。
5. 工程与模型的强拟合：测试发现，Claude Code框架与Claude模型（如Sonnet 4.5，解决率52.1%）适配性最佳，与其他模型的适配并不理想，说明其工程设计对特定模型的行为模式做了深度优化，泛化性上与学术框架有较大差异。
6. 对评测榜单的反思：尽管Claude Code体系成熟，但在某些评测（如Terminal Bench）上并未取得预期高分。分析发现，部分评测任务的设计与现实场景有所脱离，导致模型给出了实际可行的解决方案，却无法满足出题人的特定意图。

上述对比表明，CodeTracer的设计能够良好适配工业场景，其步骤级偏差标注还可作为密集训练信号用于优化工业级Agent。但同时，框架本身对Claude模型的行为模式存在较强依赖性，体现了工程与模型之间的深度拟合。

深度解剖：Agent的失败是如何发生的？

除了框架层面的对比，研究团队还借助CodeTraceBench提供的步骤级标注，对智能体内部的行为模式进行了深度分析，揭示了其失败背后的共性规律。

1. 模型各有所长，但失败模式高度趋同
在涵盖的340类任务中，有66类常规任务能被全部五款测试模型解决，另有65类高难度任务（如形式化验证、高级科学计算）则无一模型能够完成。

各模型在专长领域差异明显：GPT-5擅长图论与化学任务，Claude-sonnet-4擅长贝叶斯推断，Kimi-K2-Instruct在图形渲染上突出，DeepSeek-V3.2则在数据管道与包管理上更具优势。然而，当面对共同无法解决的难题时，所有模型的失败行为却出奇地一致：它们普遍倾向于通过捏造证据、输出占位符或提前终止来掩盖失败，而非坦诚地报错。这种“失败掩盖”行为与模型本身的能力强弱无关，是一个值得高度警惕的现象。

2. 错误类型与执行阶段高度相关
将每条轨迹按执行阶段（环境验证、依赖安装、代码修改、验证等）拆解后发现：在早期阶段，错误多以环境配置、依赖安装问题为主，这些问题容易被忽略并持续级联扩散；到了中后期，错误则主要集中在错误定位、错误假设以及对验证结果的误读上——智能体常常能定位到可疑代码，但实际的修改方向或对结果的解读却是错误的。

相比之下，成功的轨迹流程顺畅，阶段之间没有反复振荡；而失败的轨迹则在早期就过度消耗了Token，一旦陷入错误假设，就会进入无效循环。这种错误发生的可预测性，为实施分阶段预警、提前阻断错误链提供了可行的思路。

3. 成功率在早中期快速饱和，盲目增加迭代次数意义不大
研究者对最大迭代次数从5到300进行了全面扫描。结果显示，成功率曲线在迭代至约35%—40%的最大长度时快速上升，之后便趋于饱和，额外的迭代几乎不再提升效果。成功率的上限主要由基础模型的推理能力决定，与Agent框架的设计差异关系不大。

这意味着，如果智能体在早期就形成了错误的假设，那么给予它更多次的重试机会，多半只是在空耗资源，并不能纠正其底层的认知偏差。这进一步印证了一个观点：在正确的时机提供正确的诊断信号，远比单纯给Agent更多重试机会更有价值。

4. 核心症结：探索与行动之间的“鸿沟”
通过对轨迹步骤的预算拆解，研究发现了贯穿所有模型与框架的一个关键问题——证据-行动鸿沟。在失败轨迹中，无效步骤的占比高达约40%，接近成功轨迹（22%）的两倍；与此同时，正确的状态变更步骤比例从30%下降到了21%，而探索信息获取的能力下降并不明显。

这说明，智能体的失败往往不是因为找不到关键信息，而是无法将有效的证据转化为正确的决策。这种鸿沟在Qwen3-Coder-480B与Kimi-K2-Instruct上体现得尤为突出，Claude-sonnet-4和GPT-5则相对较小，表明更强的基础模型在证据转化上具有优势。这也正是CodeTracer“反思回放”机制的设计初衷：智能体真正需要的不是更多机会，而是清晰的错误根因提示。

实验结果

研究团队在CodeTraceBench上，以精确率、召回率、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定位到的证据注入给原始失败的智能体，在匹配的Token预算内让其重新执行任务，结果如下：

所有骨干模型的Pass@1指标均有显著提升，而诊断过程本身带来的额外Token消耗仅为5k–8k，性价比极高。这说明CodeTracer提供的诊断信号，能够有效帮助智能体修正早期的错误假设，避免无效重试，将宝贵的计算资源集中在正确的关键步骤上。

总而言之，CodeTracer是一个开源、无需训练的代码智能体轨迹追溯框架。它通过进化式日志提取、层级化状态树索引、失败起点自动定位这三位一体的设计，系统性地解决了长执行轨迹中“错在何处、为何失败”的核心诊断难题，并通过反思回放机制，将诊断信息直接转化为任务性能的提升。

本研究的主要贡献可归纳为三点：
1. 提出了CodeTracer框架，相比直接的LLM提示基线，将错误定位的F1分数提升了近30个百分点，同时有效降低了Token消耗。
2. 构建了CodeTraceBench评测基准，这是首个提供步骤级标注的代码轨迹评测集，覆盖了4种主流框架和5种骨干模型，包含数千条高质量标注轨迹。
3. 形成了一系列实证洞见，包括框架复杂度与成功率无显著线性关系、证据-行动鸿沟的存在、错误分布与执行阶段强相关等关键规律，对后续研究和工程实践具有指导意义。

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

展望未来，随着代码智能体能力和任务复杂度的不断提升，让模型具备“自知失败原因”的能力，将成为推动AI软件工程走向可靠、可解释的关键一步。对于研究者而言，CodeTraceBench提供了前所未有的细粒度评测视角；对于工程实践者而言，CodeTracer的诊断框架则是一个可以即插即用的调试工具。二者共同为代码智能体从“可用”走向“可信”提供了重要的底层支撑。

代码链接：https://github.com/NJU-LINK/CodeTracer
论文链接：https://arxiv.org/abs/2604.11641