又是一個讓程序員狂歡的研究！來自 OpenHands、耶魯、南加大和斯坦福的研究團隊剛剛發(fā)布了 LocAgent—— 一個專門用于代碼定位的圖索引 LLM Agent 框架，直接把代碼定位準確率拉到了 92.7% 的新高度。該研究已被 ACL 2025 錄用。

• 論文標題：LocAgent: Graph-Guided LLM Agents for Code Localization
• 論文鏈接：https://arxiv.org/abs/2503.09089
• 代碼鏈接：https://github.com/gersteinlab/LocAgent

一、痛點很真實：代碼定位到底有多難？

相信每個程序員都有過這樣的經(jīng)歷：看到一個 bug 報告，滿臉問號地想「這到底要改哪里？」。傳統(tǒng)方法要么靠關(guān)鍵詞匹配（太粗糙），要么直接把整個代碼庫丟給 LLMs（太低效），要么讓 Agent 盲目遍歷目錄（太笨拙）。

問題的核心在于：自然語言描述的問題和真正需要修復(fù)的代碼位置之間，往往隔著好幾層調(diào)用關(guān)系。比如用戶反饋「XSS 漏洞」，但實際需要修改的可能是某個深層的驗證工具函數(shù)。

換言之，代碼定位指的是在大型代碼庫中精確找到需要修改的代碼位置，在軟件開發(fā)與維護中，準確地定位代碼問題是提高開發(fā)效率的關(guān)鍵（圖 1 展示了四種常見的代碼修復(fù)場景）。

圖 1：給定一個代碼庫（左）和問題描述（中，包含四種場景的示例），代碼定位需要識別出需要修改的相關(guān)代碼位置（右），包括具體的文件、類和函數(shù)。LocAgent 旨在讓 LLM Agent 自動完成這一過程。

自然語言中的問題描述（如錯誤報告）往往與真正的故障根因存在顯著的語義差異與結(jié)構(gòu)距離（如圖 2 所示）。這不僅要求模型能夠深入理解自然語言編寫的錯誤報告，還需具備在龐大代碼庫中跨越層級結(jié)構(gòu)和復(fù)雜依賴關(guān)系進行推理和追蹤的能力。

圖 2: 圖中紅色節(jié)點表示問題描述中明確提及的函數(shù)，黃色節(jié)點表示實際需要修改（修補）的函數(shù)。任務(wù)難度定義為代碼圖中從提及函數(shù)到目標修補函數(shù)之間的最短路徑長度（最少跳數(shù)），圖示例中任務(wù)難度為 2 跳。

二、LocAgent：給 LLM 裝上「代碼地圖」

該研究團隊的解決方案相當(dāng)巧妙：首先他們把整個代碼庫解析成一張圖，包含文件、類、函數(shù)之間的包含、調(diào)用、繼承、導(dǎo)入關(guān)系。然后該團隊為 LLM Agent 提供簡潔統(tǒng)一的圖原語接口，以支持離效探索代碼庫。該方法通過將代碼庫解析為異構(gòu)圖表示，讓大語言模型能夠像使用地圖一樣高效地在代碼中「移動」，實現(xiàn)多跳推理，逐步接近目標代碼。

圖 3：LocAgent 框架概覽

如圖 3 所示，LocAgent 首先將代碼庫解析為一個異構(gòu)圖表示，圖中包含多種類型的代碼實體及其依賴關(guān)系。在此基礎(chǔ)上，系統(tǒng)構(gòu)建了分層稀疏索引，用于支持高效的內(nèi)容檢索與結(jié)構(gòu)化探索。借助這些索引，LocAgent 能夠結(jié)合圖結(jié)構(gòu)與工具接口，執(zhí)行由 Agent 驅(qū)動的逐步搜索過程，精準完成代碼定位任務(wù)。

2.1 代碼表示構(gòu)建過程

代碼圖表示構(gòu)建：為統(tǒng)一表示代碼庫中的結(jié)構(gòu)與語義信息，LocAgent 基于抽象語法樹（AST） 對代碼庫進行解析，構(gòu)建一個異構(gòu)有向圖 作為結(jié)構(gòu)化索引，詳細表示了代碼目錄、文件、類、函數(shù)之間的包含、調(diào)用、導(dǎo)入和繼承關(guān)系，使得隱式依賴顯性化，便于 LLM 高效推理。

這種圖結(jié)構(gòu)的優(yōu)勢在于：即使兩個代碼片段分處不同模塊，只要存在調(diào)用或繼承關(guān)系，在圖上它們就會變得「鄰近」。比如，以往基于目錄導(dǎo)航的方法會認為遠隔兩個子目錄的模塊毫不相干，但如果模塊 A 函數(shù)調(diào)用了模塊 B，在 LocAgent 的圖中 A 和 B 會通過調(diào)用邊直接連接，使它們在該圖結(jié)構(gòu)上靠近。對于代碼定位任務(wù)，這種「鄰近」至關(guān)重要，因為許多問題不是局限在單個文件夾內(nèi)部，而是通過調(diào)用鏈跨越多個模塊。

2.2 提供工具接口供 Agent 查詢

構(gòu)建好代碼圖后，LocAgent 提供了統(tǒng)一的工具接口，讓 LLM Agent 能夠方便地查詢圖結(jié)構(gòu)和代碼內(nèi)容。主要包括以下三個 API：

• SearchEntity：該工具基于層次化實體索引，使用關(guān)鍵詞搜索代碼庫中相關(guān)實體。當(dāng)在上層索引中未能找到匹配項時，系統(tǒng)會自動使用下一層索引進行搜索，從精確匹配到模糊搜索，以查找最接近的匹配項。對于檢索到的每個實體，SearchEntity 會返回該代碼片段的摘要（如圖 4，有折疊級別、預(yù)覽級別和完整代碼三級，可根據(jù)需要展開）。

圖 4: 為高效的 Agent 代碼交互而設(shè)計的不同輸出格式示例。

• RetrieveEntity：當(dāng) Agent 確定了某個代碼實體很可能就是目標時，可以用此工具提取該實體的完整信息。當(dāng)輸入實體 ID，RetrieveEntity 輸出該實體的文件路徑、起止行號、完整代碼內(nèi)容等詳細屬性。
• TraverseGraph：該工具在代碼圖上執(zhí)行類型感知的廣度優(yōu)先搜索。Agent 可以指定起始的實體 ID，以及希望遍歷的方向、步數(shù)（hops）、實體類型和關(guān)系類型等參數(shù)。工具會在圖中從起點出發(fā)按照要求走指定步數(shù)，返回遍歷到的子圖結(jié)構(gòu)。通過設(shè)置不同的類型過濾，Agent 可以靈活地探索比如「沿調(diào)用關(guān)系向下追蹤兩步」或「查看從某類出發(fā)的繼承層次」等等。值得一提的是，TraverseGraph 將返回的子圖格式化成一種樹狀結(jié)構(gòu)文本（見圖 5），以便 LLM 更容易理解關(guān)系拓撲。

圖 5：TraverseGraph 工具輸出示例。

2.3 Agent 驅(qū)動的推理階段

LocAgent 在提示設(shè)計上采用了「逐步思考」(Chain-of-Thought, CoT) 的策略，引導(dǎo) LLM Agent 將代碼定位任務(wù)分解為一系列步驟，模擬人類調(diào)試思路一步步逼近目標。整個問題求解過程可以概括為以下階段：

1. 問題理解與關(guān)鍵詞提取：Agent 首先對輸入的 issue 描述進行分析，劃分出不同方面的信息，然后提取出與問題相關(guān)的關(guān)鍵詞。這些關(guān)鍵詞相當(dāng)于為后續(xù)搜索指明了初步方向。
2. 鏈接關(guān)鍵詞到代碼實體：針對每個提取的關(guān)鍵詞，Agent 調(diào)用 SearchEntity 工具在代碼索引中查找匹配的代碼實體。
3. 多跳推理，生成故障鏈路：接下來，Agent 會嘗試串聯(lián)線索，從報錯表征推導(dǎo)故障原因。它先確定問題觸發(fā)的初始入口點（例如觸發(fā)錯誤的 API 或函數(shù)），然后以這些點為起點，在代碼圖上進行迭代探索：調(diào)用 TraverseGraph 沿調(diào)用關(guān)系或依賴關(guān)系向相關(guān)方向搜索；用 RetrieveEntity 查看某些關(guān)鍵節(jié)點的實現(xiàn)細節(jié)；必要時再次 SearchEntity 引入新的關(guān)鍵詞。通過多輪交替使用這些工具，Agent 逐步構(gòu)建起一條從問題癥狀到潛在根因的邏輯路徑。
4. 鎖定目標代碼：在形成對問題的全面理解后，Agent 根據(jù)「故障鏈路」中暴露的可疑環(huán)節(jié)，定位出所有可能需要修改的目標代碼實體（可能是若干個函數(shù)或類）。隨后，Agent 對這些候選實體按相關(guān)性進行排序輸出，并給出它們的文件路徑以及簡要的原因說明。

整個 LocAgent 的使用對用戶來說非常簡潔：只需輸入自然語言的問題描述， LLM Agent 就會如上所述自主地完成一系列搜索、遍歷、讀取操作，最后給出代碼定位結(jié)果。

三、實驗結(jié)果：真香警告

LocAgent 在真實數(shù)據(jù)集上的表現(xiàn)和分析結(jié)果令人矚目。研究中使用了既有的基準數(shù)據(jù)集（SWE-Bench Lite）以及團隊新構(gòu)建的 Loc-Bench，對比了多種基線方法的代碼定位效果。

（1）代碼定位效果出色

SWE-Bench Lite 是從 GitHub issue 中構(gòu)建的倉庫級代碼修復(fù)數(shù)據(jù)集，也常用于代碼定位評估，包含 300 個問題及其對應(yīng)的修復(fù)代碼，其中大部分為 bug 報告。基于該基準，LocAgent 實現(xiàn)了目前最優(yōu)的代碼定位準確率，顯著優(yōu)于現(xiàn)有方法。

• 相比傳統(tǒng)的向量檢索方法有顯著提升：BM25 在文件級 Acc@5 上僅為 61.7%，而先進的代碼嵌入模型如 CodeRankEmbed 也僅達到 84.7%；而 LocAgent 準確率高達 92.7%，在函數(shù)級定位中也同樣顯著優(yōu)于這些方法。
• 多步推理的 Agent 類方法整體上勝過基于固定流程的方法。基于固定流程的方法（如 Agentless）往往只能依據(jù)字面匹配找到有限的候選，而引入了 Agent 逐步探索后，能夠考慮更廣的范圍，定位效果更好。
• 在文件、模塊、函數(shù)三個粒度上，LocAgent 全面超越了基于 GPT-4o 或 Claude-3.5 的現(xiàn)有 Agent 系統(tǒng)。使用 Claude-3.5 時，LocAgent 在 SWE-Bench Lite 文件級 Acc@5 達到 94%，在函數(shù)級定位上同樣優(yōu)于其他方法。
• LocAgent 搭配 Qwen2.5-32B (微調(diào)) 模型的性能幾乎與 Claude-3.5 持平：在 SWE-Bench Lite 文件級 Top-5 準確率上，前者為 92.7%，后者約 94.2%，差距很小。而如果使用 Qwen2.5-7B (微調(diào)) 小模型，雖然準確率略有下降（約 88.3%，但仍超過絕大多數(shù) baseline），其表現(xiàn)已能夠逼近 GPT-4o 的效果。

（2）多任務(wù)場景下的泛化能力

由于 SWE-Bench Lite 數(shù)據(jù)集過于偏重 Bug 類型，團隊打造了新的 Loc-Bench 基準，用于全面評估方法在多樣化軟件維護任務(wù)中的定位能力。Loc-Bench 共包含 560 個真實 GitHub issue，覆蓋 Bug 修復(fù)、功能新增、安全漏洞與性能優(yōu)化四大類，任務(wù)類型更加均衡，貼近實際工程場景。

四、開源福利：小模型也能打

這個研究最讓人興奮的地方在于：開源模型經(jīng)過微調(diào)后，也能達到商用大模型的效果。他們提供了兩個版本，1. Qwen2.5-7B 微調(diào)版：性能媲美 GPT-4o，單次處理成本僅 $0.05；2.Qwen2.5-32B 微調(diào)版：逼近 Claude-3.5 水平，成本節(jié)省 86%。這對于需要大規(guī)模部署的企業(yè)來說，這簡直是降本增效的神器。

具體而言，微調(diào)的 Qwen2.5-7B 模型，LocAgent 在 Loc-Bench 四類場景下的平均文件級 Acc@5 為 76.8%，函數(shù)級 Acc@15 為 46.9%，已接近 SWE-Agent 搭配 Claude-3.5 的表現(xiàn)（后者函數(shù)級約 45.4%）。進一步將 LocAgent 與 Claude-3.5 結(jié)合后，文件級平均準確率可提升至 81.1%，在四類任務(wù)中幾乎全面超越其他方法。

五、實際應(yīng)用：不僅是定位，還能助力解決問題

研究團隊驗證了一個關(guān)鍵點：更準確的代碼定位直接提升問題解決率。在 GitHub 問題自動修復(fù)任務(wù)中，使用 LocAgent 的 Pass@10 成功率比基線方法提升了 12%。這意味著這項技術(shù)不僅僅是個「定位工具」，而是能實實在在提升整個軟件維護流程效率的利器。

該團隊進一步從不同角度展開分析，探討其在復(fù)雜任務(wù)中的穩(wěn)定性、成本效率、關(guān)鍵組件作用以及對下游應(yīng)用的實際價值。

（1）難度分級實驗與多跳魯棒性

為了深入了解 LocAgent 的能力，該團隊還按照任務(wù)的難度對性能進行了分析。該團隊將「難度」用代碼圖上函數(shù)距離（hop 數(shù)）來衡量：即 Issue 描述中提及的函數(shù)與實際需要修改的函數(shù)之間的最短路徑。直觀地說，hop=0 表示 Issue 直接提到了需要改的函數(shù)名；hop=1 表示目標函數(shù)是 Issue 中提到的函數(shù)之間有直接關(guān)系，hop 數(shù)越大則定位難度越高。

實驗發(fā)現(xiàn)：隨著 hop 數(shù)增加，所有方法的定位準確率都在下降。畢竟關(guān)聯(lián)越不直觀，模型需要推理的鏈路就越長。不過，不同方法的魯棒性差異明顯：Agent 類方法在高難度下的性能下降幅度明顯小于檢索類方法。特別是 LocAgent 借助圖結(jié)構(gòu)索引，在 hop 數(shù)增加時仍能保持相對較高的準確率，表現(xiàn)出較好的魯棒性。

相比之下，傳統(tǒng)檢索方法在需要兩跳以上時幾乎失效，在函數(shù)級定位上即使目標函數(shù)名字就出現(xiàn)在查詢里，有時都找不到（因為它們往往把查詢當(dāng)做整體，無法拆解處理細節(jié)）。

（2）效果與成本比較

借助結(jié)構(gòu)化圖索引與工具調(diào)用，LocAgent 僅需 6～9 輪交互即可完成一次代碼定位任務(wù)，推理過程高效。此外，該團隊利用開源模型取得了媲美商用大模型的結(jié)果，同時大幅降低推理成本，具備實際落地部署的可行性。

具體來看，使用 Claude-3.5 等商用 API 模型時，每個 Issue 的平均處理成本約為 $0.66；而使用本地部署的 Qwen2.5-32B 模型，成本降至約 $0.09，降低了 86%。若進一步采用 7B 的小模型，處理成本可低至 $0.05，仍能保持優(yōu)于大多數(shù)方法的性能。從函數(shù)級準確率與成本的比值來看，微調(diào)后的 Qwen-2.5-7B 是性價比最高的方案，其效率優(yōu)于所有商用模型；Qwen-2.5-32B 次之，也顯著優(yōu)于 Claude-3.5。這表明，結(jié)合 LocAgent 框架，開源模型不僅具備性能競爭力，更具部署經(jīng)濟性。

（3）應(yīng)用效果：高質(zhì)量定位顯著提升問題解決率

為評估代碼定位在實際軟件維護任務(wù)中的影響，該團隊進一步分析了 LocAgent 在自動解決 GitHub 問題中的效果。結(jié)果表明，隨著定位準確率的提升，問題解決成功率顯著提高，說明更精準的定位結(jié)果能夠顯著增強自動化代碼修改的質(zhì)量與穩(wěn)定性。該發(fā)現(xiàn)驗證了 LocAgent 不僅在定位本身表現(xiàn)優(yōu)秀，也能有效推動下游任務(wù)的整體性能，具備實際工程價值。

六、技術(shù)啟示：結(jié)構(gòu)化索引 + 智能推理

LocAgent 的成功揭示了一個重要趨勢：從「暴力計算」到「智能決策」的范式轉(zhuǎn)變。傳統(tǒng)方法要么把整個代碼庫直接丟給 LLM 進行暴力匹配，要么讓 Agent 按照預(yù)設(shè)規(guī)則盲目遍歷目錄，這些都屬于「計算密集型」的解決方案。而 LocAgent 通過圖索引等結(jié)構(gòu)化中間表示，將復(fù)雜問題進行結(jié)構(gòu)化分解，然后讓 LLM 承擔(dān)更高層次的推理和決策任務(wù)。

這種「agentic retrieval」范式的核心在于決策智能化。通過圖、樹等結(jié)構(gòu)化中間表示，信息變得更易于推理，Agent 能夠根據(jù)具體問題動態(tài)調(diào)整搜索策略，而非死板地遵循預(yù)設(shè)路徑。這代表了從「人工設(shè)計各種 RAG pipeline」向「讓 AI 自主決策如何檢索」的轉(zhuǎn)變。

這種結(jié)合結(jié)構(gòu)化索引與 LLM 智能體協(xié)同設(shè)計的范式，很可能成為未來 AI 工程應(yīng)用的標準模式。不再是讓 LLM 做更多計算，而是讓 LLM 做更智能的決策 - 程序員的 debugging 體驗又要迎來一次重大升級了！