企业官网建设流程全解析

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 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