改一行重试代码，AI为何总漏掉依赖？

找代码不难，难的是找到"对的那段代码"，更难的是判断一次改动会牵动什么。设想让一个AI编码代理去修改支付重试策略：它找到了负责重试的函数，改完，报告成功。但另一个模块在调用这个函数，一份配置控制着它的行为，现有测试还依赖它当前的约定。

问题未必出在代理不会写代码，而在于它检索到的上下文不足以理解这次改动。语义代码智能（semantic code intelligence）正是为此而生：它是一组技术手段，帮开发者和AI代理借助代码的结构、符号、关系，有时还有语义相似度，来在代码库中穿行。它是一个宽泛的行业术语，而非某项单一标准技术，不同实现提供的能力各不相同。

文本搜索与代码智能，区别在哪

假设你想找到 getUser 定义在哪里。执行 grep -rn "getUser" src/，返回的是文本匹配，可能混着定义、调用、注释和测试。语言感知的工具则能解析符号、定位定义——前提是语言服务器支持该操作，且项目信息足够充分。

区别很简单：文本搜索找的是匹配的文本；符号感知导航能识别代码实体及其关系。两者都有用，难点在于为问题选对方法。

几块主要拼图

• 语法解析：Tree-sitter 把源码解析成语法树，识别函数、类、表达式等结构，适合结构化查询和符号感知的代码切块。但解析本身并不能解析所有符号，也无法确立程序的完整含义。
• 符号导航与索引：语言服务器协议（LSP）定义开发工具与语言服务器之间的通信，视实现不同，支持跳转定义、查找引用、重命名；SCIP 则是与语言无关的源码索引协议，用于支撑代码导航。前者是通信协议，后者是索引格式，两者都不保证覆盖所有语言特性或仓库——准确性取决于语言支持、索引覆盖、项目配置和新鲜度。
• 嵌入与向量搜索：有时你知道要找的行为，却不知道哪个函数实现了它，比如"我们在哪里重试失败的支付"。基于嵌入的检索把代码片段和查询表示为向量，再按相似度取候选。当查询与源码用词不同时，这能帮你发现实现，但相似不等于功能等价。用它来发现候选，别用它保证引用完整或证明行为。
• 代码图：表示函数调用、导入、依赖、继承等关系，能回答"哪些函数调用了这个方法""哪些模块依赖这个接口""改动这个组件可能影响什么"。静态图可能漏掉动态派发、反射、生成代码或运行时配置相关的关系；依赖信息也不保证改动就是安全的。
• 混合检索：把词法搜索、语义相似度和结构信息组合进一条检索流水线。典型流程是：按符号切块、用 BM25 等方法建索引、生成嵌入做语义检索、合并并重排候选、再用符号与依赖信息精修结果。混合检索不会自动更准，效果取决于索引、切块、排序和底层数据质量。

一个具体例子：改支付重试策略

代理接到任务：提高支付重试的最大次数。文本搜索可能找到多处 retry，但相关行为可能分散在服务、配置文件和测试套件里。搜索 retry 可能暴露 retry_payment()、max_attempts、recover_transaction()；符号解析能区分 retry_payment() 的定义与调用方，依赖分析则帮助追踪这个函数如何被使用。

关键在于每一步回答的是不同问题：语义检索帮你发现候选，符号索引帮你建立代码关系，测试提供行为证据。单独任何一步，都不能证明所有相关组件都已找到，也不能证明改动正确。

为什么这对AI编码代理重要

AI代理在改动代码库之前需要相关上下文。检索不力，它可能反复搜文件、读无关段落、手工重建依赖，代价是多余的 token 消耗、漏掉的依赖、不完整的改动和重复的探索。持久化索引能让符号与关系信息跨任务复用，减少重复探索，其价值取决于仓库、语言支持、索引开销和代码变更频率。

更好的检索能改善代理可用的上下文，但不保证推理正确或改动安全。代理仍须检查源码、验证假设、测试改动。这些能力可以通过 API、工具或 MCP（模型上下文协议）这类集成暴露给代理，代理只应使用集成实际支持的能力。

引入前要算的账

• 索引新鲜度：过期索引会给出误导结果，增量更新或重建索引是必需的。
• 语言支持：不同语言和框架的索引能力与精度不一。
• 基础设施成本：持久索引需要存储、算力和维护。
• 检索质量：嵌入和重排器需要评估，相似度分数本身不证明正确。
• 分析局限：静态分析可能捕捉不到全部运行时行为。
• 安全：代码索引和嵌入存储可能包含专有源码信息，需要相应的访问控制。

小仓库里，普通搜索加上现有语言服务器功能可能就够了。大型单体仓库，或涉及频繁跨文件改动的代理工作流，额外的索引与依赖分析才值得这份复杂度。做法是：从现有搜索起步，需要时加符号感知导航，当具体问题足以证明必要时再引入语义检索或图分析，并用代表性任务、检索精确率与召回率、索引新鲜度、延迟、token 消耗和端到端任务成功率来评估结果。

语义代码智能不是文本搜索的替代品，它组合互补技术，以不同层次的结构与语义信息检索代码。精确匹配用词法搜索，定义与引用用符号索引，按意图发现实现用嵌入，探索依赖与潜在影响用代码图。对AI编码代理来说，目标不是不加区分地多捞代码，而是捞到相关证据、理解其局限、并验证改动。目标不是让每次搜索都变语义，而是为所问的问题取到对的证据。