Cursor 是一款广受欢迎的 AI 驱动集成开发环境（IDE），近期宣布其年经常性收入（ARR）已达到 3 亿美元。这款工具在代码索引方面的卓越表现，主要得益于采用了 Merkle 树 这一高效的数据结构。本文将深入剖析 Cursor 如何利用 Merkle 树实现代码库的快速索引，带你了解这一技术在实际应用中的价值。
在探讨 Cursor 的具体实现之前，我们先简要了解一下 Merkle 树的基本概念。
什么是 Merkle 树？
Merkle 树是一种广泛应用于数据完整性验证和高效更新的树形数据结构。每个“叶子”节点存储数据块的加密哈希值，而非叶子节点则存储其子节点哈希值的组合哈希。这种层级结构使得数据变化能在任何层级通过比较哈希值被高效检测到。
你可以将 Merkle 树想象成一种数据的“指纹”系统：
- 每一块数据（如一个文件）都会生成一个独特的“指纹”（即哈希值）。
- 成对的指纹会被合并，生成一个新的指纹。
- 这个过程不断重复，直到最终生成一个总指纹（即根哈希）。
根哈希代表了整个数据集的加密摘要，概括了所有单个数据块的内容。因此，Merkle 树不仅能有效表示数据，还能迅速检测数据变化。其巧妙之处在于，只要任何一块数据发生改变，其上层的所有指纹都会随之更新，最终导致根哈希的变化。这使得 Merkle 树非常适合用于数据完整性检测和高效增量更新。
Merkle 树示意图
Cursor 如何利用 Merkle 树进行代码库索引
Cursor 将 Merkle 树作为代码库索引功能的核心组件。根据 Cursor 创始人论坛帖子 和 官方安全文档 的信息，其工作流程如下：
第一步：代码分块与本地处理
Cursor 首先在本地将代码库文件分块，拆分成有意义的代码片段。这一步在数据上传或处理之前完成，确保代码结构得以保留。
第二步：构建 Merkle 树并同步
启用代码库索引功能后，Cursor 会扫描编辑器中打开的文件夹，计算所有有效文件的哈希值，并构建一个 Merkle 树。随后，这个 Merkle 树会被同步到 Cursor 的服务器，具体细节可参考 官方安全文档。
第三步：生成嵌入向量
代码片段上传至服务器后，Cursor 会使用 OpenAI 的嵌入 API 或定制的嵌入模型为这些片段生成嵌入向量（具体模型未获证实，无法确认使用哪种模型）。这些向量捕捉了代码片段的语义信息。
第四步：存储与索引
生成的嵌入向量被存储在远程向量数据库（Turbopuffer）中。同时，元数据（如起始/结束行号和文件路径）也会一并存储。为了在保护隐私的同时支持基于路径的过滤，Cursor 会对每个向量的相对文件路径进行模糊化处理。值得注意的是，根据 Cursor 创始人 的说法：“我们不会在数据库中存储任何代码内容，代码在请求处理完成后即被删除。”
第五步：利用 Merkle 树定期更新
Cursor 每隔 10 分钟检查哈希值是否不匹配，利用 Merkle 树快速识别发生变化的文件。只需要上传变更的文件即可完成更新，这大大减少了带宽消耗。Merkle 树在这一步展现了高效增量更新的巨大价值，详见 官方安全文档。
代码分块策略
代码库索引的效果很大程度上取决于代码分块的方式。虽然简单的分块方法可以按字符、单词或行数分割代码，但这些方法往往忽略语义边界，导致嵌入质量下降。以下是一些常见策略，部分内容参考自 相关博客文章：
- 按固定令牌数分割：按固定的令牌（token）数量分割代码，但可能会在函数或类定义中间切断，导致语义不完整。
- 智能分割器：使用理解代码结构的分块工具，例如递归文本分割器，利用高级分隔符（如类或函数定义）在合适的语义边界处分割代码。
- 基于抽象语法树（AST）分割：更优雅的方法是基于代码的抽象语法树（一种表示代码结构的树形模型）进行分割。通过深度优先遍历 AST，将代码分割成符合令牌限制的子树，同时通过合并兄弟节点避免生成过多小片段。工具如 tree-sitter 可用于 AST 解析，支持多种编程语言。
Cursor 采用了基于抽象语法树（AST）的分块策略，以确保代码分块的语义完整性。
嵌入向量的具体应用流程
在了解了 Cursor 如何创建和存储代码嵌入向量之后，一个自然的问题是：这些嵌入向量在实际使用中是如何发挥作用的？ 以下是它们在日常使用中的具体应用流程。
语义搜索与上下文检索
当你使用 Cursor 的 AI 功能（例如通过 @Codebase 或 ⌘ Enter 询问代码库相关问题）时，会启动以下流程：
- 查询嵌入：Cursor 为你的问题或当前代码上下文计算一个嵌入向量。
- 向量相似性搜索：该查询嵌入被发送到 Turbopuffer（Cursor 的向量数据库），数据库会执行最近邻搜索，找出与查询语义最相似的代码片段。
- 本地文件访问：Cursor 客户端接收搜索结果，包括模糊化处理的文件路径和相关代码片段的行范围。重要的是，实际代码内容始终保留在本地设备上，并从本地文件读取。
- 上下文组装：客户端从本地文件读取相关代码片段，并将其作为上下文与你的问题一起发送到服务器，供大语言模型（LLM）处理。
- 精准回复：有了代码库的上下文，LLM 能够提供更具针对性和相关性的回答，或生成更合适的代码补全建议。
这种基于嵌入的检索机制带来了以下优势：
- 上下文相关的代码生成：在编写新代码时，Cursor 可以参考代码库中现有的类似实现，保持代码风格和模式的一致性。
- 代码库问答：你可以直接询问关于代码库的问题，并获得基于实际代码的精准回答，而非泛泛而谈的回复。
- 智能代码补全：代码补全功能能够根据项目特定的规范和模式提供更智能的建议。
- 高效代码重构：在重构代码时，系统可以识别代码库中所有可能需要类似修改的相关部分。
Cursor 选择 Merkle 树的原因
Merkle 树在 Cursor 的设计中扮演了关键角色，以下是其主要优势，部分内容参考自 Cursor 安全文档：
1. 高效的增量更新
通过 Merkle 树，Cursor 能快速识别自上次同步以来发生变化的文件，无需重新上传整个代码库。这一特性显著减少了大型代码库的同步时间和带宽消耗，对大型项目尤为重要。
2. 数据完整性验证
Merkle 树的层级哈希结构使 Cursor 能高效验证索引文件与服务器存储内容的一致性，轻松检测传输过程中的数据不一致或损坏，确保代码库索引的可靠性。
3. 优化缓存机制
Cursor 将嵌入向量存储在以代码片段哈希作为索引的缓存中，确保对同一代码库的重复索引速度更快。这对于多人协作的团队尤为有益，提升了团队效率。
4. 保护隐私的索引方式
为了保护文件路径中的敏感信息，Cursor 通过将路径按 '/' 和 '.' 分割并对每个部分进行加密，实现路径模糊化。虽然这仍会暴露部分目录层级信息，但大部分敏感细节得以隐藏，保障了用户隐私。
5. Git 历史集成
在启用代码库索引的 Git 仓库中，Cursor 还会索引 Git 历史，存储提交 SHA、父提交信息及模糊化后的文件名。为了便于同一 Git 仓库和团队的用户共享数据结构，文件名模糊化所用的密钥基于近期提交内容的哈希生成。这一机制在支持团队协作的同时保护了数据安全。
嵌入模型的选择与挑战
选择嵌入模型对代码搜索和理解的质量有很大影响。虽然一些系统使用开源模型如 all-MiniLM-L6-v2，但 Cursor 可能采用了 OpenAI 的嵌入模型或专门为代码定制的模型。针对代码语义理解，微软的 unixcoder-base 或 Voyage AI 的 voyage-code-2 都是不错的选择。
嵌入模型的令牌限制也带来了挑战。例如，OpenAI 的 text-embedding-3-small 模型令牌上限为 8192。有效的分块策略需要在保持语义完整性的同时遵守令牌限制。
握手过程：Merkle 树同步的关键
Cursor 的 Merkle 树实现中一个重要环节是同步过程中的“握手”机制。根据 Cursor 应用的日志显示，在初始化代码库索引时，Cursor 会创建一个“merkle 客户端”，并与服务器进行“启动握手”。这一过程涉及将本地计算的 Merkle 树根哈希发送到服务器，相关细节可见 GitHub 问题 #2209 和 GitHub 问题 #981。
握手过程使服务器能够判断代码库的哪些部分需要同步。通过握手日志可以看出，Cursor 会计算代码库的初始哈希并发送到服务器进行验证。
技术实现的挑战
尽管 Merkle 树带来了诸多优势，但其实现并非没有挑战。Cursor 的索引功能经常面临高负载，导致许多请求失败，文件可能需要多次上传才能完成索引。用户可能会注意到与 'repo42.cursor.sh' 之间的网络流量高于预期，这是重试机制导致的，详见 Cursor 安全文档。
另一个挑战涉及嵌入安全。学术研究表明，在某些情况下嵌入向量可能被逆向还原。这种逆向还原可能导致敏感代码信息泄露，构成潜在的安全威胁。虽然当前攻击通常需要访问嵌入模型并针对短字符串，但如果攻击者获得 Cursor 向量数据库的访问权限，可能存在从存储的嵌入中提取代码库信息的风险。
结语
Cursor 利用 Merkle 树实现了高效、安全的代码库索引功能，从增量更新到数据完整性验证，再到隐私保护，Merkle 树在其中发挥了不可替代的作用。通过这一设计，Cursor 不仅提升了开发者的工作效率，还确保了代码库的安全性和隐私保护，让开发者能够更加专注于创新与开发。尽管技术实现中仍存在一些挑战，但这一工具无疑为开发者提供了强大支持，帮助他们更高效地管理和理解复杂代码库。如果你想体验 Cursor 带来的高效代码管理和安全性，不妨访问 Cursor 官方网站，了解更多信息并开始试用。
