代码代理需要多少静态结构？确定性锚定研究

通过轻量级静态分析注入结构化注释，使grep-first代码代理的导航更可预测、可复现

前置知识

grep-first代码代理

一种基于文本搜索的代码代理架构，给定自然语言bug描述后，代理迭代地发出关键词查询（grep/rg）、检查匹配片段、更新假设并重新搜索。商业助手如Copilot Workspace、Claude Code主要采用这种架构，因为其快速、语言无关、对不完整代码具有鲁棒性。现代LLM负责精度：过滤不相关匹配、推理代码语义、决定下一步导航位置。

本文研究的baseline就是这种架构，理解其工作原理是评估CodeAnchor改进效果的前提，也是理解为什么结构信息对导航有帮助的基础。

确定性锚定

通过离线静态分析提取的代码结构事实（如谁调用谁、继承关系、配置依赖），这些关系对给定代码快照是固定的，因此在不同运行间不应变化。CodeAnchor将这些事实作为纯文本注释注入到代码中，当代理检查实体时，周围的标签已经揭示了附近的结构链接（如调用者/被调用者、导入、配置使用），代理可以直接跟随这些链接，而不是通过额外搜索重新发现它们。

这是本文的核心创新概念，也是理解论文主要贡献的关键。确定性锚定减少了多跳搜索需求，约束了探索，使轨迹在随机LLM控制下更加一致。

检索短路

当代理检查一个实体时，周围的CodeAnchor标签已经揭示了附近的结构链接（调用者/被调用者、导入或配置使用），代理可以跟随这些链接直接导航到相关位置，而无需发出额外的搜索查询来重新发现这些链接。这减少了对迭代grep的依赖，使导航更加直接和高效。

这是确定性锚定如何工作的具体机制，也是解释为什么标签能够减少交互轮次和工具调用的关键概念。理解这一点有助于评估实验结果中trajectory缩短的原因。

研究动机

基于grep-first的代码代理面临基础表示不匹配问题。grep根据简单词汇标准返回行排名，不暴露组织真实软件的结构关系：谁调用谁、哪些类从哪个基类继承、配置值如何传播。一个位置是否与bug相关，不仅取决于它与查询的关键词重叠，还取决于它在程序结构拓扑中的位置。这种不匹配有两个关键后果：首先，代理必须通过临时多跳查询重新发现结构链接，导致碎片化的局部近视上下文；其次，LLM控制器本质上是随机的，早期搜索中的小扰动会级联成质量不同的导航路径。当与结构盲检索结合时，这产生脆弱的轨迹：同一任务上的两次运行可能访问不同的文件、采取不同数量的步骤并产生不同的补丁，即使最终结果相同。对于从业者来说，这种行为不可预测性是一个关键质量问题：从业者需要代理行为可检查和可复现，而不仅仅是在总体上正确。

本文的目标是本文的目标是理解在已经强大的grep-first代理基础上添加静态结构的边际价值。从一个已经比基于图的替代方案表现更好的baseline开始（在SWE-bench Lite上Func@5达到83.2%），研究轻量级结构注释提供的额外好处，并将轨迹质量和稳定性作为与定位准确性并列的一等公民结果。研究不仅关注是否让代码代理更聪明，更关注是否使其行为更加可预测、减少随机性，使开发者能够理解代理为何选择特定路径，而不仅仅是它是否成功。

与已有工作不同的是，本文的独特切入点不是放弃文本检索或构建新的图引导控制器，而是直接将稳定的程序结构注入到代理的文本视图中。与需要显式MCP工具（如LSP的"find references"）的替代方案不同，CodeAnchor采用"被动注入"立场：将结构上下文内联注入，就在代理打开的代码旁边，使跟随结构不需要显式工具使用决策。这种设计实现了检索短路：当代理检查实体时，周围的标签已经揭示了附近的结构链接，代理可以跟随这些链接而不是通过额外搜索重新发现它们。这与graph-guided agents不同：图引导代理将结构外化为代理通过自定义操作符查询的单独索引，而CodeAnchor将相同结构事实作为注释内联嵌入，让现有grep循环找到它们。两种设计在表达性和可访问性之间进行权衡：外部图可以编码更丰富的查询（传递闭包、类型化边、路径约束），而内联标签不需要新API并重用强grep-first代理已经调优的检索原语。

核心方法

CodeAnchor框架有两个组件：离线静态分析管道和代理集成层。离线管道运行一次每个代码库快照（或在代码更改后增量运行），解析源文件、识别关键实体（函数、类、配置条目、文件），计算调用者、被调用者、继承、导入、包含、数据依赖和配置使用等关系，并将这些关系作为紧凑的机器可解析格式的合成注释附加到实体。在运行时，代理继续使用普通文本搜索（rg）在工作树上进行搜索。因为CodeAnchor标签直接插入到源文件中，搜索结果现在包括代码和附近的标签，代理在上下文窗口中将其作为普通文本读取。不需要新工具或API，检索保持相同的grep-first原语，只有代码库视图改变。代理发出关键词搜索（命中代码和标签）、打开文件并读取附近标签作为提示、跟随显式链接或发出新搜索，这实现了检索短路：标签提供确定性局部结构，减少搜索调用并约束合理的下一步。

核心创新点是"确定性锚定效应"：静态结构更少地通过让代理更聪明，更多地通过让其导航有纪律和可复现而提供帮助。这与现有方法的本质区别在于，CodeAnchor不是试图构建一个完整的图引导控制器或复杂的推理系统，而是通过轻量级静态分析提取结构事实，并将这些事实作为纯文本注释直接注入到代码中。标签充当"确定性锚点"：对于给定代码快照固定的仓库级关系（如谁调用谁、继承链接、配置使用），因此在运行间不应变化。当代理打开函数时，周围的标签已经揭示了其调用者、调用目标和上游配置，短路了原本需要的多跳搜索。这种设计保持了底层代理循环、工具和模型不变，专注于研究静态结构对从业者已部署架构的边际影响。与需要显式工具使用决策的图查询不同，标签提供被动结构提示：代理可以选择跟随或忽略，而不需要学习新API或改变其控制流。

方法步骤详情

CodeAnchor的工作流程分为离线标签生成和运行时代理集成两个阶段。离线阶段：（1）解析所有源文件为中间表示；（2）识别实体（函数、类、配置条目、文件）；（3）对每个实体，使用语言特定前端推断调用关系、数据流和域链接；（4）将关系规范化为稳定标识符（对函数使用文件路径加点名，如django/db/backends/base/schema.py:BaseDatabaseSchemaEditor._delete_composed_index）；（5）将标签渲染为语言特定注释；（6）将标签插入到定义位置附近。运行时阶段：代理继续发出普通文本搜索（rg），搜索结果现在包含原始代码和附近的标签。代理阅读代码和标签作为普通文本，当它检查一个实体时，周围的标签揭示了附近的结构链接（调用者/被调用者、导入、配置使用）。代理可以跟随这些链接直接导航到相关位置，而不是发出额外的搜索查询。在整个过程中，代理的外部控制循环、工具和模型保持不变，唯一变化的实验变量是标签是否存在于检索的代码上下文中。定位提示纯粹是任务导向的，不引用CodeAnchor标签或任何标签跟随策略，模型将它们视为普通注释。

技术新颖性

技术新颖性体现在三个方面：首先是"被动注入"设计，与需要显式MCP工具的图引导代理不同，CodeAnchor将结构上下文内联注入代码旁边，使跟随结构不需要显式工具使用决策。这解决了我们在20个SWE-bench任务上的试点中观察到的低工具使用率问题：代理通常依赖普通grep而不是可选的调用图工具。其次是"确定性锚定效应"的发现：静态结构通过使导航有纪律和可复现而提供帮助，而不仅仅是让代理更聪明。这通过三个观察支持：锚定有效（轻量级调用/继承拓扑提升函数级定位+2.2pp Func@5，缩短轨迹-1.6轮次）；锚定规模敏感（最优粒度和方向性依赖于仓库特性，密集语义显示收益递减，hub重的项目受益于仅反向链接）；锚定稳定（标签将链接跟随率从0.15-0.18提高到0.21-0.24，大约减半运行间方差，改善单次运行可靠性Pass@1 +3.4pp）。第三是对"结构迂回"的识别：有标签的代理可能首先访问通过结构注释暴露的hub或助手文件，然后在顶部几次打开内导航到ground-truth函数，用立即的"幸运"词汇命中交换基础的结构路径，这种权衡最终在函数识别中付出代价。

**Fig. 1**: The framework of CodeAnchor: Offline static analysis (PyCG call graphs + AST extractors) generates structured tags encoding call/inheritance/data-flow relationships, which are injected into source files as plain-text comments. At runtime, the grep-first agent retrieves code with embedded tags, enabling structure-guided navigation without changing the agent loop.

实验结果

实验在SWE-bench Lite（274个任务，平均35k LOC）和SWE-bench Verified（500个任务，平均120k LOC）上评估CodeAnchor。RQ1表明轻量级拓扑提供可靠益处：在Lite上，Anchor-Topo提升函数级召回+2.2pp（Func@5: 0.8540 vs 0.8321，McNemar p=0.041），缩短轨迹-1.6轮次（33.7 vs 35.3）；在Verified上提升+1.2pp Func@5（0.6308 vs 0.6187，McNemar p=0.023）。定位增益传播到修复：在80个Baseline和Anchor-Topo在top-5函数集上不一致的Verified实例上，Anchor-Topo解决48/80 vs Baseline的38/80（60.0% vs 47.5%，+12.5pp），具有严格超集属性。RQ2发现粒度饱和：从Anchor-Topo到Anchor-Dense，Lite上函数精度保持不变（Func@5/10都为0.8540）而轮次增加+4.9，输入token使用增长+18.8%（530k vs 446k）；Verified上Dense仅挽救15/500隐式依赖任务且略微降低Func@5（0.6288 vs 0.6308）。方向性效应规模依赖：在Lite（中规模仓库）上，移除前向边（Anchor-Inv）降低性能：Func@5降至0.8242（-3pp vs Anchor-Topo），轮次膨胀至55.0（+21.3）；在Verified（大型仓库，23% hub节点）上，Anchor-Inv匹配或超过其他变体的函数指标（Func@5: 0.6329）且输入token占用与Anchor-Topo相当（620k vs 618k）。RQ3表明标签将代理从纯关键词跳跃转向结构跟随行走，LFR从0.15-0.18提高到0.21-0.24。在Lite上，标签提升函数准确性+3.6pp Func@10且大约减半方差（std 0.0223 vs 0.0429）；在Verified上，标签改善函数指标+4.6pp Func@10且标准差更小。有效标签率：在所有跟随标签的跳跃中，落在ground-truth实体上的分数在Lite上为27.1%，Verified上为26.6%；在实例级别，55.2%（Lite）和58.7%（Verified）的任务包含至少一次这样的跳跃。成本方面，Anchor-Topo在Lite上平均增加∼9.9%输入token，案例研究显示27%的实例在CodeAnchor下花费更少输入token。

**Table 1**: Preliminary SWE-bench Lite head-to-head (matched model/limits, N=274).

**Table 2**: RQ1: Baseline vs. Anchor-Topo on SWE-bench Lite and Verified.

**Table 3**: RQ2: Effect of granularity and directionality on localization and efficiency. Tokens are mean per-instance input tokens; Baseline shown for reference.

**Table 4**: Trajectory guidance metrics (RQ3). Hops = total navigation transitions across all tasks. Struct/Lex are structural-/lexical-link following rates; LFR is overall link-following rate.

**Table 5**: Stability over k=10 runs (mean ± std). Right block: single-run Pass@k on Func@5 across 50 Lite tasks.

**Fig. 3**: Target-file hit probability over steps (RQ3). CodeAnchor tags sustain higher early hit rates on both datasets.

查看结构化数据

任务	指标	本文	基线	提升
SWE-bench Lite函数定位	Func@5	0.8540 (Anchor-Topo)	0.8321 (Baseline)	+2.2pp, McNemar p=0.041
SWE-bench Lite交互效率	平均轮次	33.7 (Anchor-Topo)	35.3 (Baseline)	-1.6轮次
SWE-bench Verified函数定位	Func@5	0.6308 (Anchor-Topo)	0.6187 (Baseline)	+1.2pp, McNemar p=0.023 for Func@10
链接跟随率 (Lite)	LFR	0.236 (Anchor-Topo)	0.178 (Baseline)	+0.058
运行稳定性 (Lite Func@10)	标准差	0.025 (Anchor-Topo)	0.043 (Baseline)	减半方差
单次运行可靠性	Pass@1	0.776 (CodeAnchor)	0.742 (Baseline)	+3.4pp

局限与改进

作者承认的局限性包括：实现使用特定的代理循环和静态分析管道，虽然在配置间固定代理、提示、模型和工具仅变化标签存在性来减轻偏差，但标签生成管道是任务无关的且不使用任何ground-truth信息；外部有效性仅在SWE-bench Lite和Verified上使用单个Codex风格代理评估，这些基准强调跨文件推理但不覆盖所有项目类型，结果反映主导的grep-first检索而非普遍保证；静态分析不完善，CodeAnchor依赖保守静态分析（PyCG + AST提取器）实现快速CI友好生成，优先考虑精度而非召回，因此注入的结构是不完善的：它捕获验证的关系但错过动态特征（getattr、反射、monkey patching）；评估范围仅定位而非端到端修复以隔离表示效应；稳定性分析使用50任务子集和k=10次运行。本文自身的观察包括：确定性锚定在大型hub重项目上的稳定性益处减弱；静态分析不完善但代理具有韧性，LLM似乎将标签用作软提示而非严格约束；标签仅在已有强baseline（>80%召回）时最有价值，对弱baseline（<60%召回）或单文件关键词密集bug问题价值有限；成本方面Anchor-Topo平均增加∼10%输入token，虽然通过减半运行间方差可以减少"best-of-N"采样的需求，潜在降低实现可靠结果的总成本。

独立分析的弱点

独立分析的弱点包括：首先，对hub重仓库的"结构干扰"问题。当高度助手函数积累密集前向链接注释时（例如"CALLS: foo.py:bar, baz.py:qux, ...[20 more]"），标签文本主导词汇匹配并将结构中央hub推到搜索结果顶部。代理跟随这些突出链接并花费多轮次在实用模块和重新导出中，可能永远不会返回bug站点。虽然Anchor-Inv通过暴露"谁依赖我"而不放大出站噪声来解决这个问题，但这是一种权衡：更弱的前向信号换取更锐利的检索。改进方向可以实现更智能的hub检测和过滤策略：计算平均调用出度和hub百分比（度>10的节点），如果平均出度<5使用Anchor-Topo；如果>8使用Anchor-Inv；否则使用带度数上限的Anchor-Topo。其次，标签仅在已有强baseline（>80%召回）时提供价值。对于弱baseline（<60%召回）代理，结构注释可能不足以补偿基础推理能力的不足。改进方向可以结合其他增强技术如更好的提示工程、多步骤推理或领域知识注入。第三，标签主要对跨文件依赖或继承层次的任务有价值，对单文件关键词密集bug问题价值有限。改进方向可以发展任务感知的标签策略：仅在检测到跨文件模式时激活结构注释。第四，静态分析不完善错过动态特征。改进方向可以开发更精确的动态分析管道或结合静态和动态分析。

未来方向

作者提出的未来工作方向包括：首先，验证在不同代理架构上的泛化性。标签是纯带内文本，预期效应会固定到SOTA代理如Claude Code、Cursor等，但尚未测试。其次，多语言验证。标签模式和代理集成是语言无关的，Java、C++、JavaScript和Go存在成熟的静态分析工具可以填充相同标签字段，但效应大小可能在不同语言间仍然不同。第三，更深层故障的验证。SWE-bench Lite和Verified主要包含1-2跳故障，怀疑更深故障（多模块重构、深度继承解析）会从标签中受益更多，因为标签为代理提供多跳路径的指导，而词汇搜索必须一次跳跃重建它们，但确认这需要一个按结构深度排序任务的基准。基于本文成果可延伸的未来工作包括：首先，结合CodeAnchor与图引导检索。CodeAnchor和graph-guided agents处于不同点：图引导代理外化结构为单独索引，CodeAnchor嵌入相同结构事实为注释。两种设计权衡表达力和可访问性。自然扩展是将两者结合：标签作为快路径，图查询作为后备。其次，自适应标签策略。根据仓库特性（LOC、hub密度、平均出度）动态选择标签配置：对小型中规模仓库使用轻量级拓扑，对大型hub重仓库使用仅反向链接，对隐式依赖情况使用密集标签。第三，端到端修复评估。本文仅评估定位以隔离表示效应，未来工作应研究定位增益如何传播到端到端修复成功率。第四，更细粒度的标签内容。当前标签主要包含结构关系，未来可以添加语义摘要、文档片段或使用示例等 richer content 以进一步增强代理理解。

复现评估

复现评估：代码和结果已在GitHub开源（https://github.com/mathieu0905/Code-Anchor），包括实现、标记管道和评估轨迹。静态图构建（AST遍历加调用/继承/导入提取）在四个Python仓库上耗时：pytest-7432（73k LOC）6.8秒，sklearn-15512（247k）21.1秒，astropy-12907（341k）58.4秒，django-13658（367k LOC）133.4秒；成本与LOC和图大小近线性缩放。代码更改后的增量再生仅影响受影响文件。标签生成是每个代码库快照的一次性成本并在所有查询间重用。评估使用SWE-bench Lite（274个实例）和Verified（500个实例）基准，对于稳定性分析在RQ3中构建每数据集50实例子集并重复k=10次，优先选择Baseline和Anchor-Topo不一致的边界情况然后用均匀随机样本填充。功率分析确认在α=0.05下对中等效应大小d≥0.4有80%功效。代理使用OpenAI的GPT-5.1-codex模型（思考努力设置为高）。复现难度中等：需要访问GPT-5.1-codex API、SWE-bench数据集和Python静态分析工具（PyCG）。实验主要限制是使用单个Codex风格代理和Python仓库，多语言泛化仍有待验证。

代码代理需要多少静态结构？确定性锚定研究 How Much Static Structure Do Code Agents Need? A Study of Deterministic Anchoring