CodeTracer团队 投稿量子位 | 公众号 QbitAI告别“黑箱调试”能精准定位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 ReplayTrace 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.1kClaude-sonnet-4偏向全面检索召回率最高54.9%适合高严谨度场景DeepSeek-V3.2精度与召回均衡整体表现最稳健。研究者在Mini-CodeTracer基础上逐步叠加组件验证各模块的独立贡献加入”进化式提取”后F1提升约9个百分点再加入”树形索引”后F1 进一步提升约18个百分点这证明了压缩式层级导航是实现精准错误定位的关键而非辅助功能。将CodeTracer的定位证据注入给原始失败的Agent在匹配的Token预算内重新执行得到如下结果所有骨干模型的Pass1均有显著提升且诊断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