編者按： AI 編程工具如何迅速檢索海量代碼庫，并精準定位到最相關的代碼片段？這個看似不可能完成的任務，卻是決定現代 AI 編程工具用戶體驗的關鍵技術挑戰。

我們今天為大家帶來的這篇文章，作者的觀點是：Cursor 通過巧妙運用默克爾樹數據結構，實現了對大型代碼庫的快速索引和高效增量更新，這正是其能夠提供精準 AI 輔助編程服務的技術基礎。

作者 | Engineer's Codex

編譯 | 岳揚

Cursor —— 這家最近宣布斬獲 3 億美元年營收的熱門 AI 開發工具 —— 正是利用默克爾樹（Merkle trees）實現對代碼的快速索引。本篇文章將為你詳細介紹其運作原理。

在深入了解 Cursor 的具體實現方法之前，我們先來了解一下默克爾樹的基本概念。

01 默克爾樹的簡單解釋

默克爾樹（Merkle tree）是一種樹狀數據結構，其每個“葉”節點都標注了對應數據塊的加密哈希值，而每個非葉節點則存儲其子節點哈希值組合后的新哈希值。這種層級結構通過比較哈希值，能有效地偵測任何層級的數據變動。

通俗理解，它就像是數據的指紋系統：

1）每份數據（例如文件）都擁有自己獨一無二的指紋（哈希值）

2）成對的指紋被組合在一起，生成一個新的指紋

3）此過程層層遞進，直至形成唯一的主指紋（根哈希）

根哈希（root hash）概括了所有底層數據塊的指紋信息，相當于對整個數據集做了一次加密公證。只要根哈希不變，就能證明原始數據分毫未改。此機制的精妙之處在于：任何一個數據塊發生變化，都將牽一發而動全身 —— 改變其上所有層級的指紋，最終徹底改變根哈希值。

02 Cursor 如何利用默克爾樹實現代碼庫索引功能

默克爾樹 (Merkle trees) 是 Cursor 代碼庫索引功能的核心組件。根據 Cursor 創始人發布的帖子[1]和 Cursor 的安全文檔[2]，其工作流程如下：

2.1 步驟 1：代碼分塊與預處理

Cursor 首先在本地對代碼庫文件進行分塊處理，將代碼分割成具有語義含義的片段。此步驟是后續操作的必要前提。

2.2 步驟 2：默克爾樹的構建與同步

啟用代碼庫索引功能后，Cursor 會掃描編輯器當前打開的文件夾，并為所有有效文件計算哈希值組成的默克爾樹。隨后，該默克爾樹會與 Cursor 的服務器同步，其安全文檔[2]詳細描述了此過程。

2.3 步驟 3：生成嵌入向量

將代碼分塊并發送至 Cursor 服務器后，將使用 OpenAI 的嵌入 API 或自研的嵌入模型（我未能驗證 Cursor 具體采用的是哪種方法）生成嵌入向量 (embeddings)。這些向量表征能夠捕捉代碼片段的語義信息。

2.4 步驟 4：存儲與索引

生成的嵌入向量，連同起始/結束行號及文件路徑等元數據，會被存儲在一個遠程向量數據庫（Turbopuffer）中。為兼顧路徑篩選功能與隱私保護，Cursor 會為每個向量附加經過混淆處理的相對文件路徑。Cursor 創始人曾明確表示[1]：“我們的數據庫中不會存儲任何代碼。請求處理完畢立即銷毀存儲的代碼數據?！?/p>

2.5 步驟 5：基于默克爾樹的定期更新

每隔 10 分鐘，Cursor 就會檢測哈希值的變化情況，利用默克爾樹精準定位哪些文件發生了變動。如 Cursor 的安全文檔[2]所述，只需上傳所定位到的發生變動的文件，從而大幅降低帶寬消耗。默克爾樹結構的最大價值正體現于此 —— 它能實現高效的增量更新。

03 代碼分塊策略

代碼庫索引的有效性很大程度上取決于代碼的分塊方式。盡管我先前的說明未深入探討代碼分塊方法，但這篇關于構建類 Cursor 代碼庫功能的博客[3]揭示了一些技術細節：

簡單的分塊方式（按字符/按單詞/按行）往往會遺漏語義邊界 —— 導致嵌入向量質量下降。

• 盡管可根據固定的 token 數分割代碼，但這種方式可能導致函數或類等代碼塊被強制截斷。
• 更有效的方案是使用能夠理解代碼結構的智能分割器，例如遞歸文本分割器（recursive text splitters），它使用高級分隔符（如類定義和函數聲明）在恰當的語義邊界處進行精準切分。
• 一個更優雅的解決方案是根據代碼的抽象語法樹（AST）結構來分割代碼。通過深度優先遍歷 AST，將代碼分割成符合 token 數量限制的子樹結構。為避免產生過多的碎片化分塊，系統會在滿足 token 限制的前提下，將同級語法節點合并為更大的代碼塊。此類 AST 解析工作可借助 tree-sitter[4] 等工具實現，其支持絕大多數主流編程語言。

04 嵌入向量在推理階段的應用

在了解 Cursor 如何創建和存儲代碼嵌入向量后，一個自然而然的問題就出現了：這些嵌入向量在生成之后究竟是如何使用的？

4.1 語義搜索（Semantic Search）與上下文檢索（Context Retrieval）

當你使用 Cursor 的 AI 功能（例如通過 @Codebase 或 ? Enter 詢問代碼庫相關問題時），將觸發以下流程：

1）將查詢轉換為向量：Cursor 會為您的提問或當前代碼上下文生成對應的嵌入向量。

2）向量相似性搜索：該查詢向量被發送至 Turbopuffer（Cursor 的向量數據庫），通過最近鄰搜索找出與查詢語義相似的代碼塊。

3）訪問本地文件：Cursor 客戶端接收到的檢索結果包含經過混淆處理的文件路徑和最相關代碼塊的行號范圍。實際代碼內容始終保留在用戶本地設備，僅在需要時從本地讀取。

4）上下文整合：客戶端從用戶本地文件讀取這些相關代碼塊，并將其作為上下文與您的問題一并發送至服務器供大語言模型處理。

5）生成響應：此時大語言模型已獲取代碼庫中的相關上下文，可據此提供精準回答或生成符合場景的代碼補全。

這種由嵌入向量驅動的檢索機制支持以下功能：

1）根據上下文生成代碼：在編寫新代碼時，Cursor 可參考現有代碼庫中的相似實現，保持代碼模式與代碼風格的一致性。

2）代碼庫智能問答：可以獲取基于代碼庫中實際代碼的精準解答，而非通用回復。

3）智能代碼補全：代碼補全建議會融合項目的特定約定與特定模式。

4）智能重構輔助：重構代碼時，系統可自動識別代碼庫中所有需要同步修改的關聯代碼段。

05 Cursor 為何選擇默克爾樹

這些設計細節多與安全有關，具體可參閱 Cursor 的安全文檔[2]。

5.1 高效的增量更新

默克爾樹使 Cursor 能精準定位自上次同步后變更的文件。因此，無需重新上傳整個代碼庫，僅需上傳修改過的特定文件。對于大型代碼庫來說這一點非常重要 —— 重新索引所有文件會消耗過多的帶寬和處理時間。

5.2 數據完整性驗證

默克爾樹結構讓 Cursor 能高效驗證所索引的文件與服務器上存儲的文件是否一致。分層的哈希結構可輕松檢測傳輸過程中的數據異?；驍祿p壞。

5.3 緩存優化

Cursor 將嵌入向量（embeddings）存儲在以代碼塊（chunk）哈希值為索引的緩存中，使得重復索引相同代碼庫時速度大幅提升。這對多人協作開發同一代碼庫的團隊尤為有利。

5.4 隱私保護型索引

為保護文件路徑中的敏感信息，Cursor 采用路徑混淆技術：通過用 “/” 和 “.” 為分隔符切割路徑，并用存儲在客戶端的密鑰加密每一段。雖然這樣做會暴露部分目錄結構，但能隱藏絕大多數敏感細節。

5.5 集成 Git 版本歷史

在 Git 倉庫中啟用代碼庫索引時，Cursor 還會索引 Git 的版本歷史記錄。它會存儲 commit 的 SHA 值、父提交信息（parent information）及混淆后的文件名。為實現同 Git 倉庫且同團隊用戶間的數據結構共享，用于混淆文件名的秘鑰來自最近 commit 內容的哈希值。

06 嵌入模型的選擇與技術考量

嵌入模型的選擇直接影響代碼搜索與理解的質量。 部分系統采用開源模型（如all-MiniLM-L6-v2[5]），而 Cursor 可能使用 OpenAI 的嵌入模型或針對代碼場景進行優化的定制模型。對于專用的代碼嵌入模型，微軟的 unixcoder-base[6] 或 Voyage AI 的 voyage-code-2[7] 等模型對代碼的語義理解效果顯著。

由于嵌入模型存在 token 容量限制，使得該技術的實現難度大幅增加。以 OpenAI 的 text-embedding-3-small[8] 為例，其 token 上限為 8192。有效的分塊策略能在保留語義的前提下不超出該限制。

07 握手同步流程

Cursor 默克爾樹實現的核心在于同步時的握手機制。根據應用日志顯示：在初始化代碼庫索引時，Cursor 會創建一個“merkle client”并與服務器進行“初始化握手流程”（詳見 GitHub Issue #2209[9] 與 Issue #981[10]），該握手流程涉及向服務器發送本地計算的默克爾樹的根哈希值。

握手流程使服務器能精準判定需同步的代碼范圍。 如握手日志所示（參照 GitHub Issue #2209[11]），Cursor 會計算代碼庫的初始哈希值，并將其發送至服務器進行驗證。

08 技術實現挑戰

雖然默克爾樹方案有許多優勢，但其實現過程仍存在一些技術難點。 Cursor 的索引服務常因瞬時流量過載，導致大量請求失敗。如安全文檔所述[2]，用戶可能觀察到向 ??repo42.cursor.sh?? 發送的網絡流量比預期要高 —— 這正是由于文件需多次重傳才能被完全索引。

另一項挑戰與嵌入向量的安全性有關。學術研究表明，特定條件下存在逆向解析嵌入向量的可能性。雖然當前的攻擊手段通常需同時滿足：1) 擁有嵌入模型的訪問權限 2) 僅對短文本有效。但若攻擊者獲取 Cursor 向量數據庫的訪問權限，仍存在從存儲的嵌入向量中提取代碼庫信息的風險。

END

本期互動內容 ??

?Cursor 通過路徑混淆和本地哈希計算保護隱私，但同步時仍需上傳部分數據。在團隊協作場景下，你更傾向于完全本地化的方案，還是接受有限數據上傳以換取更強的 AI 輔助？為什么？

文中鏈接

[1]??https://forum.cursor.com/t/codebase-indexing/36??

[2]??https://www.cursor.com/en/security??

[3]??https://blog.lancedb.com/rag-codebase-1/??

[4]??https://tree-sitter.github.io/tree-sitter/??

[5]??https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2??

[6]??https://huggingface.co/microsoft/unixcoder-base??

[7]??https://docs.voyageai.com/embeddings/models/??

[8]??https://platform.openai.com/docs/guides/embeddings??

[9]??https://github.com/getcursor/cursor/issues/2209??

[10]??https://github.com/getcursor/cursor/issues/981??

[11]??https://github.com/getcursor/cursor/issues/2209??

本文經原作者授權，由 Baihai IDP 編譯。如需轉載譯文，請聯系獲取授權。

原文鏈接：

??https://read.engineerscodex.com/p/how-cursor-indexes-codebases-fast??