又是一個讓程序員狂歡的研究！來自 OpenHands、耶魯、南加大和斯坦福的研究團隊剛剛發布了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

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

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

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

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

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

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

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

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

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

圖 3：LocAgent 框架概覽

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

2.1 代碼表示構建過程

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

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

2.2 提供工具接口供 Agent 查詢

構建好代碼圖后，LocAgent 提供了統一的工具接口，讓 LLM Agent 能夠方便地查詢圖結構和代碼內容。主要包括以下三個 API：

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

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

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

圖 5：TraverseGraph 工具輸出示例。

2.3 Agent 驅動的推理階段

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

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

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

三、實驗結果：真香警告

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

（1）代碼定位效果出色

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

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

（2）多任務場景下的泛化能力

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

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

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

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

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

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

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

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

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

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

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

（2）效果與成本比較

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

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

（3）應用效果：高質量定位顯著提升問題解決率

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

六、技術啟示：結構化索引 + 智能推理

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

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

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