CodeTracer：迈向可追踪的智能体状态

代码智能体调试框架，通过层次化轨迹追踪定位失败源头

前置知识

代码智能体（Code Agent）

代码智能体是由大语言模型驱动的自主系统，能够与软件仓库和开发环境交互，执行搜索代码、阅读文件、编辑实现、运行构建、解释测试反馈等异构操作序列，以解决仓库级Bug修复、系统配置等复杂工程任务。这些智能体通常通过框架编排并行工具调用和多阶段工作流，能够在长时间序列中自主决策。

本文的研究对象，理解代码智能体的执行机制和失败模式是读懂本文的基础

轨迹树（Trace Tree）

轨迹树是CODETRACER提出的层次化数据结构，用于压缩表示智能体的执行历史。树中每个节点代表一个状态，探索性步骤只观察当前环境而不修改代码库或执行状态，作为同一状态下的探索节点，而状态改变步骤修改代码库或执行环境，则作为触发状态转换的节点。每个节点进一步标注了意图和结果的摘要，使得后续操作是在未改变的上下文中还是干预后进行的变得显式。

CODETRACER的核心数据结构，理解它才能理解方法的创新点

失败起始定位（Failure Onset Localization）

失败起始定位是CODETRACER的核心诊断任务，给定一个标准化的轨迹被分割成有序阶段，预测一个失败负责阶段、该阶段内的一组错误相关步骤，以及支持诊断的紧凑证据集。监督信号标记了根据注释指南因果负责最终失败的阶段，评估使用步骤级别的Precision/Recall/F1与金标准不正确步骤集比较，以及在匹配预算下的token成本。

本文解决的核心问题，理解这个概念才能理解实验设计和结果

反射重放（Reflective Replay）

反射重放是一种将CODETRACER的诊断信号反馈给智能体的机制。在最初失败的运行上，相同的骨干网络在匹配预算下被重新调用，诊断作为前缀提示注入。这表明诊断帮助智能体修正早期错误承诺，而不是重复无生产力的探索。诊断过程本身平均消耗8.4k tokens（Claude-sonnet-4）、5.2k tokens（GPT-5）和7.1k tokens（DeepSeek-V3.2），这些token在重放预算外计算。

本文的重要应用方向，展示诊断如何转化为实际改进

研究动机

随着代码智能体能力提升，其执行变得越来越长且复杂，理解失败变得日益困难。当智能体运行失败时，往往不清楚轨迹在哪里首先出错，或者哪些中间决策导致了最终失败。当前评估实践仅提供有限的可见性：大多数基准使用端到端指标如通过率或补丁正确性来总结智能体性能，将整个轨迹折叠为单一成功或失败标签。现有的智能体轨迹分析要么依赖于粗粒度的结果级判断，要么依赖于少量运行的手动检查，难以扩展到具有长执行轨迹的现实软件工程工作负载。在复杂任务中，框架编排并行工具调用和多阶段工作流，使得智能体的状态转换和错误传播难以观察。早期错误可能将智能体困在无生产力的循环中，甚至级联成根本性错误，形成隐藏的错误链，使得难以判断智能体何时偏离轨道以及原因。

本文的目标是CODETRACER的具体目标是将异构的智能体运行目录转换为结构化的层次化轨迹，并自动识别轨迹中最早的失败关键阶段。系统还能产生可操作的调试信号，通过反射重放反馈到智能体中，实现从早期错误的有针对性的恢复。为支持系统评估，构建CODETRACEBENCH，一个包含步骤级注释的高质量代码智能体轨迹基准。该基准聚合了跨多种软件工程工作负载的多个广泛使用的智能体框架生成的轨迹，包括仓库级Bug修复和长视野终端交互任务，每个轨迹都标注了结构化的步骤元数据和失败关键标签，支持阶段级别定位和证据检索评估。

与已有工作不同的是，本文的独特切入角度是专注于过程级诊断而非仅关注端到端成功。现有研究主要强调端到端任务成功、补丁正确性和解决率，仅提供有限的长智能体轨迹首次变得失败关键的可见性。与之不同，CODETRACER将失败定位为时间性问题：轨迹在哪个阶段首次变得失败关键，而不是仅识别最终失败的哪个步骤负责。这种视角使得能够在错误级联之前进行阶段感知的护栏，而不是仅依赖事后诊断。此外，本文构建了包含步骤级注释的大规模基准，实现了过程级诊断的系统评估，这在现有工作中是缺失的。

核心方法

CODETRACER的整体思路是解决代码智能体调试中的可观测性挑战。直觉上，当智能体执行失败时，我们需要回溯执行历史来找到第一个错误决策。然而，运行目录是异构的且其文件布局依赖于智能体框架，硬编码的解析器很脆弱。因此，CODETRACER将追踪分解为三个阶段：演进式提取、树索引和诊断，同时积累可重用的解析器，使得对新格式的支持随时间改进。演进式提取扫描运行目录，产生描述哪些工件记录执行步骤的紧凑布局规范，并相应地调整解析器。树索引将扁平的标准化步骤序列转换为层次结构的轨迹树。诊断遍历树，发出结构化证据查询，并输出失败负责阶段、错误相关步骤和紧凑证据集。这种分离使得对不断发展的智能体框架的适应性成为可能。

CODETRACER的核心创新点是层次化轨迹树结构和失败起始定位框架。与现有分析要么关注简单交互要么依赖小规模手动检查不同，CODETRACER通过演进式提取器解析异构运行工件，重建完整的具有持久内存的层次化轨迹树作为状态转换历史，并执行失败起始定位以精确定位失败源头及其下游链。关键的技术创新在于：首先，将步骤分为探索性和状态改变两类，构建层次化树结构而非扁平序列；其次，提出阶段级失败定位而非仅步骤级；最后，产生可重放的诊断信号而非仅描述性分析。这种结构使得能够压缩长轨迹的导航，并在错误级联前进行有针对性的干预。

方法步骤详情

CODETRACER的方法分为三个主要步骤，每个步骤有明确的输入输出和具体操作。第一步是演进式提取：输入是原始运行目录包含日志文件等异构工件，系统首先扫描目录产生紧凑的布局规范描述哪些工件记录执行步骤；然后检查现有解析器注册表；如果未找到匹配，则合成并注册新解析器；接着实例化格式特定的诊断提示与固定查询模式。该阶段输出标准化步骤记录，包含类型化字段如动作、观察、差异、验证结果，同时防止跨运行的格式漂移。第二步是树索引：输入是扁平的标准化步骤序列，系统将只检查当前环境而不修改代码库或执行状态的步骤表示为同一状态下的探索节点，而修改代码库或执行环境的步骤表示为触发状态转换的状态改变节点。每个节点进一步标注意图和结果的摘要。该步骤输出层次化轨迹树，提供了压缩的导航索引。第三步是诊断：输入是轨迹树，系统遍历树，发出结构化证据查询，并输出失败负责阶段、该阶段内的一组错误相关步骤，以及支持诊断的紧凑证据集。

技术新颖性

CODETRACER的技术新颖性体现在多个方面。首先，层次化轨迹树结构是新颖的：现有工作通常将轨迹视为扁平序列，而CODETRACER明确区分探索性和状态改变步骤，构建压缩的层次化表示，使得能够快速导航长轨迹并理解操作的上下文依赖。其次，演进式提取器具有适应性：不同于硬编码解析器，CODETRACER通过布局发现和解析器适应来支持不断发展的智能体框架，积累可重用解析器使得对新格式的支持改进。第三，阶段级失败定位是新的时间视角：将失败定位为轨迹首次变得失败关键的阶段，而非仅识别最终失败的哪个步骤，使得能够在错误级联前进行阶段感知的护栏。最后，可重放的诊断输出：产生结构化的、可注入的调试信号而非仅描述性分析，使得诊断能够转化为实际的性能改进。

**Figure 1**: Overview of the CODETRACER pipeline. Raw trajectories are standardized into hierarchical traces, curated into CODETRACEBENCH with step-level supervision, and diagnosed via failure onset localization with optional reflective replay.

**Figure 4**: Hierarchical trace tree. Exploration steps remain under the current state node, whereas state-changing steps induce transitions to child states. CODETRACER builds this structure during tree indexing to provide compressed navigation of execution traces.

实验结果

实验结果表明CODETRACER在步骤级失败定位方面显著优于直接提示和轻量级基线。在CodeTraceBench上，三个前沿骨干网络（Claude-sonnet-4、GPT-5、DeepSeek-V3.2）使用CODETRACER达到相似的宏F1分数（46-48%），但表现出不同的搜索深度策略：GPT-5更早终止搜索，以更高的精度达到最佳精度45.0%整体和49.9%简单，以及最低token成本31.1k整体和20.6k简单，但遗漏了一些错误贡献步骤；Claude-sonnet-4在结论前继续深入扫描轨迹，浮现更多失败相关证据并在所有分割中达到最高召回率54.9%整体和59.1%简单，但以更高的token消耗56.8k和更低精度40.5%为代价；DeepSeek-V3.2介于两者之间，平衡覆盖和简洁性，在难度水平之间具有最均匀的精度和召回率差距。更难的任务与更长轨迹和成比例更高的token预算相关，简单到困难的token比例对于每个骨干网络大约加倍，确认定位难度随轨迹复杂性缩放。树索引通过提供压缩的层次化导航驱动最大的单一增益18.3个百分点F1，而演进式提取通过解析器重用的格式标准化进一步贡献9.4点提升。反射重放显示，在最初失败的运行上注入CODETRACER的诊断信号在匹配预算下一致地恢复原始失败的运行，提高所有骨干网络的Pass@1：Claude从21.3%提升到26.9%，GPT-5从23.9%提升到29.3%，DeepSeek从26.9%提升到32.6%，Qwen从20.2%提升到32.6%，Kimi-2.5从38.2%提升到48.3%。工业智能体分析揭示Claude Code使用更丰富的工具基础设施（40+跨8个类别的专业工具）和复杂的上下文管理，产生与更高轨迹效率相关的更低探索改变比，但并行工具执行引入顺序敏感性问题，这在顺序学术框架中不存在。

**Table 1**: End-to-end success versus process cost on the no intersection setting. Tok.(k) is the average token consumption per task in thousands. SWE-Agent and OpenHands consume 2× the tokens of MiniSWE-Agent for only modest success gains.

**Table 2**: Resolved rate (%) and token consumption (in thousands) across iteration budgets and backbones. Tok.(k) reports average token usage within the first max_iter rounds over all valid samples with extractable prefix token traces. Token coverage by model and budget is reported separately for auditability.

**Table 3**: Main localization results on CodeTraceBench (macro, step level) stratified by difficulty. P/R/F1 are reported as percentages (%). Tok denotes total LLM tokens (in thousands). Overall uses the full evaluation set; Easy/Medium/Hard split by trajectory difficulty.

**Table 4**: Component ablation. Each row incrementally adds one component on top of MINI-CODETRACER (diagnosis loop). Evolving extraction adds layout discovery and parser adaptation with accumulating reuse; tree indexing builds a hierarchical trace tree for compressed navigation. P/R/F1 are step level macro metrics (%); Tok is average tokens per instance (k).

**Figure 2**: Task categories solved per backbone. The central 66 categories are solved by all five models; 65 categories remain unsolved by any model.

**Figure 3**: Distribution of error critical steps across stages, contrasting solved and unsolved runs.

**Figure 5**: Step budget decomposition per backbone (solved vs. unsolved) on the intersection subset. Each bar shows the fraction of total steps that are correct state changes, useful exploration, or ineffective. Hatched bars denote unsolved trajectories.

**Figure 6**: Reflective replay. Pass@1 on originally failed runs before and after injecting CODETRACER's diagnostic signals under matched budgets.

**Figure 7**: Effective action ratio. (a)–(e) per model histograms; (f) cross model violin and box summary.

查看结构化数据

任务	指标	本文	基线	提升
失败起始定位（步骤级宏平均）	Precision / Recall / F1 (%)	CODETRACER: Claude-sonnet-4 (40.47/54.87/46.57), GPT-5 (45.02/51.46/48.02), DeepSeek-V3.2 (43.17/49.58/46.14)	Bare LLM: Claude-sonnet-4 (16.64/15.82/16.22), GPT-5 (16.69/21.46/18.78), DeepSeek-V3.2 (13.11/21.66/16.33)	CODETRACER相对Bare LLM的F1提升：Claude-sonnet-4 +30.35pp, GPT-5 +29.24pp, DeepSeek-V3.2 +29.81pp
反射重放恢复率（Pass@1提升）	Pass@1 (%)	Claude Code: 26.9→32.6 (+5.7pp), GPT-5: 23.9→29.3 (+5.4pp), DeepSeek: 26.9→32.6 (+5.7pp), Qwen: 20.2→32.6 (+12.4pp), Kimi-2.5: 38.2→48.3 (+10.1pp)	原始失败的运行（无诊断注入）	平均提升约7.3个百分点，Qwen和Kimi-2.5显示最大收益（+12.4pp和+10.1pp）
Token效率（整体数据集）	平均tokens每实例（千）	CODETRACER: Claude-sonnet-4 (56.8), GPT-5 (31.1), DeepSeek-V3.2 (44.6)	Bare LLM: Claude-sonnet-4 (105.1), GPT-5 (58.5), DeepSeek-V3.2 (83.4)	CODETRACER相对Bare LLM的token节省：Claude-sonnet-4 -46.0%, GPT-5 -46.8%, DeepSeek-V3.2 -46.5%

局限与改进

本文的研究有几个局限性。首先，虽然CodeTraceBench是从跨越多个智能体框架、骨干网络和工作负载的执行轨迹构建的，但它不覆盖软件工程智能体的完整设计空间或真实世界仓库；关于失败模式和重放收益的结论可能不会统一转移到其他框架、领域或部署设置。其次，监督依赖于失败关键行为的阶段和步骤级注释。虽然注释指南旨在使这些判断一致，但诸如不正确、无用和错误关键等标签仍然涉及注释器解释，特别是对于具有交织探索和状态改变的长轨迹。第三，追踪和重放结果在匹配的离线预算下对先前收集的运行进行评估。该设置隔离了诊断质量，但不能完全捕获智能体如何适应交互式人类监督、变化环境或重复在线干预。最后，反射重放实验测试了本地化证据是否可以帮助恢复失败的运行，但它们本身不建立一般的训练信号或保证跨所有任务类别和模型系列的稳健改进。

独立分析的弱点

CODETRACER的独立分析弱点包括：首先，对复杂并行工作流的支持有限。工业智能体使用并行工具执行，引入顺序敏感性问题，而CODETRACER当前侧重于顺序学术框架。改进方向是扩展轨迹树以表示并行执行和同步点。其次，注释器主观性可能影响标签质量，特别是对于具有交织探索和状态改变的长轨迹。改进方向是发展自动化或半自动化的注释工具，并提供更细粒度的注释指南。第三，仅在离线设置中评估，不能捕获智能体如何适应交互式人类监督或变化环境。改进方向是开发在线诊断和干预机制，支持实时调试和自适应恢复。第四，基线比较相对有限，主要与直接提示和轻量级基线比较。改进方向包括与更多先进的轨迹分析方法和调试工具比较。最后，错误类型覆盖可能不完整，当前覆盖环境设置问题、依赖解决失败、错误定位编辑、不正确假设、验证误解和无生产循环等6类，但可能遗漏其他重要错误模式。

未来方向

未来研究方向包括：作者提出的发展过程感知轨迹分析在软件工程智能体中的更广泛需求，这可以扩展到其他领域如文档生成、测试生成和代码审查。基于成果的可延伸方向包括：首先，开发更强大的并行工作流追踪，支持工业智能体中常见的复杂工具编排。其次，将CODETRACER集成到智能体训练中，使用失败定位作为监督信号来训练更鲁棒的智能体。第三，扩展错误类型覆盖和诊断粒度，例如区分假设错误、执行错误和环境错误。第四，开发在线诊断和实时干预机制，支持在执行过程中检测和纠正错误，而非仅事后分析。第五，探索跨轨迹学习，识别跨越多个任务和框架的通用失败模式，开发预训练的诊断模型。第六，开发自动化或半自动化的注释工具，减少人工注释成本并提高一致性。最后，将CODETRACER应用到其他类型的智能体，如文档处理智能体、数据分析智能体等。

复现评估

代码和数据在GitHub公开可用（https://github.com/NJU-LINK/CodeTracer），包括CODETRACER框架、CODETRACEBENCH基准、注释指南和提示。数据集包含4,354个标准化和步骤级注释的轨迹，覆盖5个基准、5个骨干网络和4个框架。轨迹从原始的7,936个运行经过四重过滤（超时、截断、环境配置、短轨迹）后保留3,326个轨迹。实验使用Claude-sonnet-4、GPT-5和DeepSeek-V3.2进行，覆盖交子集评估。轨迹分析需要大量计算资源，特别是对于长轨迹的诊断。复现难度中等：代码开源、数据公开，但需要访问多个模型API和设置环境以运行轨迹。注释由作者完成，对15%子集进行双重注释，达到Cohen的Kappa系数0.73的注释间一致性。

CodeTracer：迈向可追踪的智能体状态 CodeTracer: Towards Traceable Agent States