检索工具解析

实际痛点

在使用 Claude Code、Codex、Windsurf 或类似 Agent 时，真正昂贵的往往不是“生成代码”，而是“熟悉项目”。如果 Agent 对仓库没有先验认知，它通常要通过 find / grep / glob / read 反复试探，才能逐步定位到关键文件、符号定义和调用链，这会显著增加工具调用次数、等待时间和 token 消耗

因此，所谓“上下文工程”的核心，不是简单把更多代码塞进 prompt，而是先建立一层检索基础设施：要么提前把代码结构化，要么训练一个更擅长搜索的模型，要么建立长期可复用的语义索引，要么在本地做更强的混合召回。

这里其实就是我们现在正在进行探索的四个方向，然后抽选出了代表性的四个工具解决办法

  1. codegraph：结构化检索关系的代表

核心机制是将代码转变为知识图谱的形式，类/函数等等作为实体，然后他们的关系做边。是我们通过index命令本地构建的索引，核心是sqllite的邻接表，通过这个来表现节点之间的关系

然后毕竟适合符号、调用关系和影响范围分析，因为核心是图，搜索速度快，但是自然语言检索效果不好

  1. fast-context：是windsurf的子代理，是训练模型检索的代表

主要是提供了专门针对检索场景的训练的模型SWE-grep和对应的mini版本，对grep/read/glob等命令更适配，然后检索的效率更高。是强化学习的代表。是语义检索最好的一位，速度也比较快。

  1. ACE：是Augment Context Engine 的上下文机制，

他的核心就是扫描全部工作区的文件，然后将其向量化，上传到云端，本地留有.ace-tool的缓存。

然后进行检索，核心机制是混合检索，语义搜索+不同类型的检索加权不同。第一次的时候速度较慢，因为需要建立索引，后续逐渐变快。

  1. Semble：是一个本地的检索机制

核心就是混合检索，向量+BM25关键词匹配，不同ACE的是，他是内存的索引，每次都要按需重建。然后进行RRF进行融合，然后再去对召回的进行处理，定义类/函数优先调用调用的，过滤调import这类的代码。

工具 核心范式 底层机制 优势 短板
CodeGraph 结构化图检索 tree-sitter 解析 AST，抽取符号与关系，落到本地 SQLite/FTS5，再按图关系查询。 符号级定位、调用链、影响范围分析很强，检索快且本地化。 对纯自然语言问题不如语义检索灵活。
Fast Context 检索专用子代理/专用模型 SWE-grep / SWE-grep-mini 经强化学习训练，专门做并行 grep/read/glob 检索。 语义意图理解强，速度快，适合“先问一句自然语言，再快速找代码”。 仍依赖工具探索，不像预建索引那样拥有稳定的全局结构图。
ACE 长期上下文引擎 全工作区扫描、语义索引、关系映射、持续维护“实时理解”，并按相关性压缩与排序。 适合跨仓库、跨服务、长期使用场景，冷启动后越用越顺。 首次建立和维护索引成本较高，且依赖平台侧基础设施。
Semble 本地混合检索 向量检索 + BM25 关键词匹配 + RRF 融合，再做代码感知后处理。 本地、轻量、兼顾精确关键词与语义召回，适合灵活接入。 索引生命周期较短，通常没有 ACE 那种持续演化的全局上下文记忆。

四个方向

CodeGraph

这里是代表将代码映射成图的方式，代表的工具是CodeGraph

CodeGraph 的底层思想是：不要等 Agent 进来之后再读文件，而是在本地先把仓库转换成“代码知识图谱”。它通常用 tree-sitter 把源码解析成 AST，再提取函数、类、方法、导入、继承、实现、调用等实体和关系，最后存入本地 SQLite 数据库，并结合 FTS5 做全文检索。

这意味着它不是按“文本块”理解代码，而是按“符号和边”理解代码。对于“这个函数被谁调用”“改这个接口会影响哪些实现”“某个 Controller 对应哪些路由和处理函数”这类问题，图结构天然优于普通向量检索，因为查询目标本身就是关系问题，而不是相似文本问题。

更深一层看，CodeGraph 的强项来自三步。第一步是 结构提取：AST 让系统知道什么是函数、什么是类，而不是把它们当普通字符串。 第二步是 引用解析：把“这里写了 foo()”进一步连到“foo 的定义在某处”，把 import 连到源文件，把继承连到父类。 第三步是 图遍历：从一个命中的节点出发，沿着调用边、继承边、实现边走几跳，就能快速圈出“真正相关”的局部子图。

它本质上是把“代码搜索问题”转化成“图查询问题”，因此对结构性问题极强，对模糊语义问题则往往需要额外的全文索引、别名词典，甚至和语义检索联用。

Fast-Context

Fast Context 代表的是另一条路线：不预建复杂图谱，而是专门训练一个“会搜索代码库”的小模型做子代理。

它的关键不在于“懂代码生成”，而在于“懂怎么搜”。这类模型被训练去高效使用有限工具集，例如 grep、read、glob，并尽量用并行搜索替代串行试探；文档提到它们可在最多 4 轮中执行最多 8 个并行工具调用，并通过强化学习优化速度和检索准确率。 这说明它的优化目标不是传统语言建模损失，而是更贴近真实检索任务的“找到正确上下文、少走弯路”。

从底层机制看，Fast Context 可以视为“agentic search policy 的蒸馏和强化学习化”。普通大模型也会 grep/read，但往往策略粗糙：先搜一个词，读一个文件，再临时改方向。SWE-grep 这类模型则更像被专门训练过的“检索调度器”，它知道如何拆搜索意图、并行尝试不同路径、控制上下文污染，并把最相关的片段交回主模型。

ACE

ACE 的路线更接近“长期在线的上下文引擎”。Augment 官方页面强调，它不是简单 grep，而是对代码做语义索引和关系映射，并维护对整个技术栈、提交历史、代码模式与依赖关系的“实时理解”；检索时不会把整个仓库塞进 prompt，而是只取相关部分、做压缩、排序和优先级控制。

ACE 的核心价值有三层。第一层是 全量预处理：扫描工作区乃至跨 repo 内容，形成长期可复用的索引。 第二层是 混合信号排序：不仅看语义相似度，还看依赖关系、活跃度、代码模式、历史变更等上下文特征。 第三层是 持续更新：随着 IDE 状态、仓库变更、commit 历史变化，索引不是一次性结果，而是活的上下文底座。

Semble

Semble 则更像本地可部署的实用主义方案：把向量检索和 BM25 关键词检索结合，再用 RRF 做融合。RRF 的典型公式是把每个候选文档在各排名列表中的贡献按累加，它的优点是不必强行对齐 BM25 和向量分数的量纲，只融合排序名次即可。

这类架构的好处非常适合代码库。向量检索擅长找“语义相关”，比如“支付请求日志”可能召回 billing.service.ts；BM25 则擅长找精确 token，如函数名、配置键、异常字符串、协议字段。 两者融合后，再通过代码感知后处理——例如优先保留类、函数、定义点、调用点，过滤掉纯 import 或噪声片段——就能比纯文本 RAG 更适合代码场景。

从底层原理看，这四类工具其实是在回答同一个问题：如何让模型在生成前，以更低成本拿到“最值得读的上下文”。 CodeGraph 靠结构先验，Fast Context 靠检索策略模型，ACE 靠长期语义与关系索引，Semble 靠本地混合召回与重排。 它们并不是互斥的，未来更强的系统很可能会把四者结合起来：用图谱保证结构精度，用专用检索模型提升搜索效率，用混合检索提升召回率，再用长期上下文引擎维护跨会话记忆与项目级理解。