文章摘要Qdrant近期公开了一套Branch-Aware Semantic Code Search方案用于解决AI编程Agent在多Git分支环境中检索到错误版本代码的问题。普通向量索引往往只保存main分支或最后一次写入的Chunk当发布分支、功能分支和主干代码同时存在时Agent可能生成无法编译的调用方式。本文分析“错误版本问题”、代码Chunk身份、分支继承、增量索引和查询过滤的完整设计。一、语义代码搜索的新问题找对代码但版本错了传统grep在当前工作区执行因此天然对应当前分支。语义代码搜索通常会解析代码 → 按函数或类切分 → 生成Embedding → 写入向量数据库如果索引只基于main分支开发者在release分支中提问如何调用optimizer_thresholdsAgent可能检索到main中的新签名而当前release分支仍使用旧签名。结果是生成代码无法编译使用了尚未发布的API修改了错误版本文件发布分支被新功能污染Code Review难以理解来源。这就是Wrong-Version Problem。二、为什么不能给每个分支完整复制一份索引最直接方案main一份 release一份 feature-A一份 feature-B一份问题是代码高度重复。假设主干100万个Chunk 20个活跃分支 每个分支只修改1%完整复制会产生接近20倍存储而绝大多数内容相同。还会增加Embedding成本索引时间更新压力删除复杂度分支合并后的清理成本。更合理的方案是保存共享祖先版本 分支自己的差异三、代码Chunk必须有稳定身份普通文本RAG常用文档IDChunk序号代码搜索更适合按符号建立身份repository path language symbol_type qualified_name例如{repository:qdrant,path:src/config.rs,symbol_type:function,qualified_name:optimizer_thresholds}为什么不推荐滑动窗口第1—80行 第60—140行代码增加一行后后续窗口全部位移难以判断两个Chunk是否代表同一个函数。按函数、类、方法和声明切分身份更稳定。四、同一个符号可能存在多个版本例如mainoptimizer_thresholds(config, mode) release/v1.15optimizer_thresholds(config) feature-xoptimizer_thresholds(config, profile)向量数据库中不能简单使用path symbol作为唯一ID否则后写入的分支会覆盖其他版本。可以使用repository path symbol commit_hash或版本内容哈希importhashlibdefchunk_version_id(repository:str,path:str,symbol:str,content:str)-str:raw|.join([repository,path,symbol,content])returnhashlib.sha256(raw.encode(utf-8)).hexdigest()五、分支感知的核心可见性查询某个分支时需要返回该分支自己修改的版本 从祖先分支继承且未被覆盖的版本 已被删除的版本例如main ├── release/v1.15 └── feature-new-indexrelease分支能看到分支创建时从main继承的代码release后续自己的补丁看不到main后续新增且未合并的代码。因此简单过滤branch release/v1.15还不够因为继承的Chunk可能只标记在祖先提交上。六、两种常见实现方案一保存分支可见列表Payload{symbol:optimizer_thresholds,commit:abc123,visible_branches:[main,release/v1.15]}优点查询简单过滤快速。缺点分支创建、合并和删除时需要批量更新活跃分支很多时Payload膨胀。方案二保存提交和分支历史向量点保存created_commit deleted_commit symbol_identity查询时根据Git DAG判断该版本是否对目标分支可见。优点数据模型更接近Git不需要给每个点写所有分支。缺点查询逻辑复杂需要外部Git图服务或预计算。七、如何处理覆盖功能分支修改了父分支中的函数祖先版本A → 分支版本B在该功能分支查询时B可见 A不可见即使A的向量相似度更高也不能返回。需要记录symbol_identity version_order replaced_version查询先确定可见版本再做语义排序。八、如何处理删除代码删除不能只从索引中物理删除因为其他分支可能仍需要旧版本。应该记录墓碑{symbol:legacy_search,deleted_in_commit:d91f02,deleted_in_branch:main}main查询时排除旧release分支仍可见。只有确认所有活跃分支都不再引用该版本后才进行物理清理。九、增量索引链路Git Push → 获取变更文件 → AST解析 → 提取新增、修改、删除符号 → 计算内容哈希 → 只为新版本生成Embedding → 更新分支可见性 → 写入向量库不要每次Push重建整个仓库。伪代码defprocess_commit(commit):changesgit.diff(commit.parent,commit)forfile_changeinchanges:old_symbolsparse_symbols(file_change.old_content)new_symbolsparse_symbols(file_change.new_content)update_symbol_versions(branchcommit.branch,commit_hashcommit.hash,old_symbolsold_symbols,new_symbolsnew_symbols)十、查询接口应该携带什么{repository:enterprise-platform,branch:release/4.2,query:订单取消接口如何做幂等,language:java,top_k:10}过滤条件repository匹配 branch可见 language匹配 当前版本未删除 用户有仓库权限再执行向量排序和可选Reranker。十一、Chunk应该按什么粒度推荐优先级类 方法 函数 接口 类型定义 配置块同时附带文件路径类名方法签名DocstringImports父类调用关系分支Commit。过细会缺少上下文过大则检索不精确。可以采用方法Chunk负责召回 类级父Chunk负责补充上下文十二、与普通代码RAG的区别普通方案只关注语义相似度分支感知方案还必须关注版本正确性 分支可见性 符号身份 删除与覆盖 权限正确的旧版本代码比相似度更高的新版本代码更重要。十三、适合哪些场景多版本SDK长期维护release分支大型企业代码库AI Code Review代码问答自动修复迁移助手多仓库Agent。如果团队始终只在main开发、旧分支很快删除普通索引可能已经足够。十四、生产检查清单□ Chunk具有稳定符号身份 □ 同一符号支持多个版本 □ 查询明确携带branch □ 继承关系正确 □ 覆盖后旧版本不可见 □ 删除使用墓碑 □ 只对变更内容生成Embedding □ 分支合并后更新可见性 □ 用户权限进入过滤条件 □ Trace记录实际返回commit总结AI编程Agent不仅要找“语义最相似”的代码还要找当前仓库 当前分支 当前时间点 真正可用的代码版本分支感知语义搜索的关键不是增加一个branch字段而是把Git的继承、覆盖和删除语义带入向量检索。