系列第四篇。前三篇讲了 Action、执行、对话本篇进入 Agent 的记忆系统——代码库索引。Warp 用 Merkle Tree 实现了 O(changes) 的增量索引比全量扫描快一个数量级。一、问题Agent 理解代码库的代价AI Agent 要理解代码库需要先建索引方案 A: 每次查询全量扫描 → 2 万个文件 × 每个文件 embedding → 慢、贵 方案 B: 全量建一次索引之后不管 → 代码改了索引就过期了 方案 C: 增量索引 — 只重建变化的部分 ← Warp 的选择增量索引的核心问题怎么知道哪些文件变了轮询所有文件的 mtime→ O(n)跟全量扫描差不多监听文件变更事件→ 不可靠会丢事件Merkle Tree→ O(changes)只检查 hash 不同的子树二、Merkle Tree 在代码索引中的角色2.1 树结构/src (Hash: H_src hash(H_foo, H_bar, H_bazz)) ├── /src/foo.rs (Hash: H_foo hash(Fragment1, Fragment2)) │ ├── Fragment1 (lines 1-50, Hash: C1) │ └── Fragment2 (lines 51-120, Hash: C2) ├── /src/bar.rs (Hash: H_bar hash(Fragment3)) │ └── Fragment3 (lines 1-80, Hash: C3) └── /src/bazz (Hash: H_bazz hash(H_buzz)) └── /src/bazz/buzz.rs (Hash: H_buzz hash(Fragment4)) └── Fragment4 (lines 1-60, Hash: C4)规则叶子节点 代码片段Fragmenthash SHA-256(内容)文件节点 该文件所有 Fragment 的父节点hash SHA-256(子节点 hash 列表)目录节点 该目录所有子节点的父节点hash SHA-256(子节点 hash 列表)2.2 增量检测修改前: H_src hash(H_foo, H_bar, H_bazz) 修改 bar.rs 的第 30 行: → Fragment3 变了 → C3 → H_bar → H_src 检测变化: H_src ! H_src → 根节点变了 H_foo H_foo → foo.rs 没变跳过整棵子树 H_bar ! H_bar → bar.rs 变了需要重建 H_bazz H_bazz → bazz/ 没变跳过复杂度O(changes)而不是 O(n)。1 万个文件中改了 3 个只需要重建 3 个文件对应的子树。三、源码结构crates/ai/src/index/full_source_code_embedding/ ├── mod.rs # 入口 EmbeddingConfig Fragment 定义 ├── codebase_index.rs # 主索引逻辑 (2427行) ├── chunker.rs # 代码分片器 ├── fragment_metadata.rs # Fragment 元数据 ├── manager.rs # 索引管理器 ├── sync_client.rs # 服务端同步 ├── store_client.rs # 存储客户端抽象 ├── merkle_tree/ # Merkle Tree 实现 │ ├── tree.rs # MerkleTree 结构 │ ├── node.rs # MerkleNode (27KB) │ ├── hash.rs # ContentHash NodeHash │ ├── serialized_tree.rs # 序列化 │ └── ... └── ...四、EmbeddingConfig4 种嵌入模型pubenumEmbeddingConfig{OpenAiTextSmall3_256,VoyageCode3_512,Voyage3_5_Lite_512,#[default]Voyage3_5_512,}默认使用Voyage 3.5512 维这是一个专门为代码优化过的嵌入模型。支持运行时切换——如果用户没有 Voyage 的 API key可以降级到 OpenAI。4.1 Fragment索引的最小单元// chunker.rspubstructFragmenta{pubcontent:astr,pubstart_line:usize,pubend_line:usize,pubstart_byte_index:ByteOffset,pubend_byte_index:ByteOffset,pubfile_path:aPath,}// mod.rspubstructFragment{content:String,content_hash:ContentHash,// SHA-256 内容哈希location:FragmentLocation,// 文件位置 字节范围}Fragment 不是文件级别而是代码片段级别。一个大文件会被切分成多个 Fragment每个独立计算 hash 和 embedding。这样做的好处修改文件末尾不影响开头的索引搜索时可以精确到函数/类级别embedding 更精准不会把整个 2000 行文件的语义压缩成一个向量五、增量更新流程5.1 核心常量/// 定期重建索引的间隔 (20 分钟)constREINDEX_INTERVAL:DurationDuration::from_secs(20*60);5.2 增量更新核心// codebase_index.rsasyncfnincremental_update_internal_operation(muttree:MerkleTree,// 当前的 Merkle Treechanged_files:ChangedFiles,// 变更的文件列表store_client:ArcdynStoreClient,embedding_config:EmbeddingConfig,...)-IncrementalUpdateResult{letmutfragment_metadata_updatesLeafToFragmentMetadataUpdates::empty();// 1. 处理删除if!changed_files.deletions().is_empty(){let(deleted_nodes,deletion_fragment_metadata_updates)tree.remove_files(changed_files.deletions())?;fragment_metadata_updates.merge(deletion_fragment_metadata_updates);}// 2. 处理修改和新增forfileinchanged_files.updates_and_additions(){let(node_lens,leaf_to_fragment_meta_updates)tree.update_file(file)?;// 只更新变化的子树fragment_metadata_updates.merge(leaf_to_fragment_meta_updates);}// 3. 生成新的 embedding// 4. 同步到服务端// 5. 返回更新结果}5.3 同步队列// sync_client.rspubenumSyncTask{GenerateEmbeddings(GenerateEmbeddingsTask),// 生成 embeddingUpdateIntermediateNodes(UpdateIntermediateNodesTask),// 更新中间节点SyncMerkleTree(SyncMerkleTreeTask),// 同步 Merkle Tree}三种同步任务按优先级执行GenerateEmbeddings— 为新增/变化的 Fragment 生成向量UpdateIntermediateNodes— 更新 Merkle Tree 中间节点的 hashSyncMerkleTree— 把完整的 Merkle Tree 同步到服务端5.4 服务端架构客户端 (Warp App) │ ├─ Merkle Tree (本地) ├─ Fragment 元数据 (本地) │ ├─ SyncTask 队列 │ ├─ GenerateEmbeddings → 服务端生成 │ ├─ UpdateIntermediateNodes → 服务端更新 │ └─ SyncMerkleTree → 服务端同步 │ └─ StoreClient (抽象接口) └─ 远程服务端 (Warp Cloud) ├─ 向量数据库 ├─ Merkle Tree 存储 └─ 语义搜索 API注意Embedding 生成在服务端完成因为需要调用 Voyage/OpenAI APIMerkle Tree 的比较在客户端完成因为需要访问本地文件。六、线程池设计constMAX_PARALLEL_THREADS:usize2;fncreate_thread_pool()-Optionrayon::ThreadPool{letnum_threadsavailable_parallelism().map(|p|(p.get()/2).clamp(1,MAX_PARALLEL_THREADS)).unwrap_or(MAX_PARALLEL_THREADS);rayon::ThreadPoolBuilder::new().thread_name(|i|format!(warp-code-indexing-{i})).num_threads(num_threads).build().ok()}设计约束最多 2 个线程 — 索引不能抢占 UI 线程用 CPU 核数的一半 — 给主线程留足余量rayon 线程池 — 数据并行适合文件扫描七、与业界方案对比维度WarpClaude CodeCursorGitHub Copilot索引方式Merkle Tree 增量全量 缓存全量 缓存服务端索引变更检测O(changes)O(n) 轮询文件监听Git push 触发索引粒度Fragment (代码片段)文件文件仓库嵌入模型Voyage 3.5 / OpenAI自研自研自研增量间隔20 分钟实时(轮询)实时(监听)按需线程限制2 线程无限制无限制N/A服务端同步Merkle Tree diff无无全量推送Warp 的核心优势Merkle Tree 让增量检测从 O(n) 降到了 O(changes)。1 万个文件的仓库改了 5 个文件只需要重建 5 个文件的索引。八、与 Hermes Agent 的 ContextEngine 对比维度Warp Merkle IndexHermes ContextEngine增量策略Merkle Tree hash 比较迭代摘要压缩检索方式向量相似度搜索摘要 关键词路由Token 预算Fragment 大小控制尾部保护裁剪存储位置客户端 云端混合纯客户端重索引频率20 分钟按需互补关系Warp 的 Merkle Index 解决的是代码搜索问题找哪段代码相关Hermes 的 ContextEngine 解决的是上下文压缩问题把找到的代码塞进有限的 Token 窗口。两者可以组合使用。九、可复用模式Merkle Tree Incremental Index┌─────────────────────────────────────────┐ │ Merkle Tree Incremental Index │ ├─────────────────────────────────────────┤ │ 1. Fragment 级索引粒度 │ │ - 文件 → Fragment 切分 │ │ - 每个 Fragment 独立 hash embed │ │ - 修改局部不影响全局 │ │ │ │ 2. Merkle Tree 增量检测 │ │ - 叶子: ContentHash(SHA-256) │ │ - 中间: NodeHash hash(children) │ │ - 比较: O(changes)跳过未变子树 │ │ │ │ 3. 分层同步 │ │ - 本地: Merkle Tree Fragment 元数据 │ │ - 云端: Embedding 生成 向量搜索 │ │ - 客户端比较 → 云端生成 → 双向同步 │ │ │ │ 4. 资源限制 │ │ - 线程池: max 2 线程 │ │ - 重建间隔: 20 分钟 │ │ - 批量限制: 4MB / batch │ └─────────────────────────────────────────┘十、总结Warp 的代码库索引系统用 Merkle Tree 实现了高效的增量索引Fragment 级粒度— 不是文件级而是代码片段级搜索更精准Merkle Tree 增量检测— O(changes) 而非 O(n)改 5 个文件只重建 5 个客户端-云端混合— 本地比较 Merkle Tree云端生成 Embedding严格资源限制— 2 线程 20 分钟间隔 4MB 批量限制一句话总结Merkle Tree 让代码索引从全量扫描变成了只扫变化的——这是让 Agent 理解大型代码库的关键基础设施。系列导航一类型即协议二风险分级执行三对话状态机四Merkle Tree 增量索引 ← 你在这里五跨生态联邦