开源GrepAI通过本地嵌入与调用图分析在Claude Code比grep节省97%Token

Claude 在大代码仓库中因目录遍历与逐文件阅读造成 token 暴涨。通过本地语义搜索与调用图分析，搜索路径被一次命中，成本与时间同时塌缩。

在大型代码仓库中，真正吞噬 token、时间与耐心的环节，并非复杂逻辑推理，而是代码定位本身。Claude Code 默认依赖 grep、glob 等人类工具进行探索，这种方式在人脑中效率尚可，在语言模型环境中却会触发指数级 token 消耗。每一次“列目录—打开文件—判断相关性—继续查找”的循环，都会把上下文窗口当作一次性耗材使用，最终让智能体在还没真正开始干活之前，就已经气喘吁吁。

当代码规模来到十万行以上，这种模式会自动进入失控状态。目录越深，文件越多，Claude 为了确认“相关性”所付出的 token 成本就越高。这并非模型智力问题，而是工具路径与认知方式完全错位导致的结构性浪费。

传统 grep 流程在智能体世界里的真实运行方式

当 Claude Code 这类 AI 编程助手面对一个十几万行的大项目时，它就像一个刚入职的实习生，被扔进一间堆满图纸、零件和说明书的仓库里，老板只说了一句：“去把那个能处理用户登录的模块找出来。”结果呢？这个实习生只能挨个打开文件夹，一页页翻看内容，一边读一边猜：“这行代码是不是跟登录有关？”、“这个函数名听起来像认证，但实际干的是日志记录？”……更惨的是，每翻一页，都要把整页内容背下来汇报给大脑（也就是消耗大量 token），翻了几十页才发现方向错了，还得重来。

这种“列目录 → 读文件 → 判断相关性 → 再列目录”的循环，不仅慢，还贵得离谱——一次任务轻松吃掉五万多个 token，相当于让 AI 把整本《三体》从头到尾默写一遍。

在命令行世界里，grep 是精准、廉价、可靠的工具。但在 Claude Code 中，grep 的输出会被完整送入上下文窗口。每一行前缀都带着完整路径，每一个匹配结果都需要模型进行一次语义判断。

流程通常呈现为：

• 先列出几十个文件名
• 再逐个打开文件片段
• 再在片段中寻找是否存在真正相关逻辑
• 发现线索不完整后再次扩大搜索范围

这条路径并非低效，而是完全不适合语言模型的认知结构。模型并不擅长在大量“可能相关但尚未确认”的文本中做筛选，模型擅长的是在少量高相关信息中做推理。一旦输入侧冗余，模型的理解质量与判断稳定性都会同步下降。

GrepAI 的关键转向：让“意义”先行，而非“文件名”

GrepAI 的核心思路非常直接：让本地机器先完成“意义层面的粗筛”，再把结果交给 Claude。

在这一设计中，代码不再作为纯文本被逐行扫描，而是被转化为向量表示。每个文件、函数、调用关系都会被映射到“语义空间”中。搜索不再依赖关键词是否完全匹配，而是依赖概念是否相近、功能是否呼应、职责是否相同。

当询问“API 鉴权在哪里完成”时，系统并不寻找 authentication 这个字符串，而是寻找那些在语义空间中靠近“身份验证、请求校验、安全边界”的代码节点。这一变化直接绕开了 grep 所有最昂贵的失败路径。

GrepAI 的核心机制：实时索引 + 语义向量 + 调用图分析

GrepAI 的工作流程分两步走：先做一次全量扫描建立初始索引，然后开启后台守护进程（daemon）监听文件变化，实现增量更新。

初始化时，它会遍历整个项目目录，跳过 .gitignore 和配置文件中指定的忽略路径（比如 node_modules、dist、vendor 等），只处理支持的语言源码文件。目前支持 Go、JavaScript/TypeScript、Python、PHP、Rust、C/C++、Zig、Java、Ruby 等主流语言，未来可通过扩展支持更多。

每个被索引的文件会被切分成“块”（chunks），默认按 512 个 token 切分，前后有 50 个 token 的重叠，确保上下文连贯。这些块通过 Ollama 的嵌入模型转换成高维向量，存入本地数据库（默认用 gob 格式，也可接 PostgreSQL）。与此同时，GrepAI 还会解析代码的抽象语法树（AST），提取符号（symbols）——包括函数、方法、类、类型等，并记录它们之间的引用关系，构建出一张“调用图”。这张图后来会被 grepai trace 命令用来做跨文件的调用链分析。

一旦初始索引建好，GrepAI 就进入“守望模式”。它利用操作系统的文件监听机制（如 Linux 的 inotify、macOS 的 FSEvents），实时捕获文件的创建、修改、删除、重命名事件。为了避免频繁写入导致性能抖动，它采用“防抖”（debouncing）策略：如果 500 毫秒内有多次改动，就合并成一次批量处理。每次更新只重新索引变动的文件，不会全盘重来，保证高效。所有索引数据都会定期自动保存，关机时也会优雅退出并持久化状态。

用户只需在项目根目录运行两条命令：

grepai init
grepai watch

前者生成配置文件 .grepai/config.yaml，后者启动守护进程。
也可以加 --background 参数让它在后台运行，用 --status 查状态，--stop 安全关闭。日志会按操作系统规范存放在 ~/Library/Logs/grepai（macOS）、~/.local/state/grepai/logs（Linux）等位置，方便排查问题。

调用图分析让搜索具备结构感

单纯的语义相似度在代码世界中仍然存在歧义。GrepAI 引入调用图分析，用来补足“结构维度”。

函数调用关系天然携带着程序的真实运行路径。通过调用图，系统可以区分“定义层逻辑”与“执行层逻辑”，区分“工具函数”与“核心流程函数”。

语义相似度负责告诉系统“这段代码像是在干什么”，调用图负责告诉系统“这段代码在什么时候被用到”。两者叠加后，搜索结果会自然向真正的关键路径收敛，而不是停留在表面描述相似的辅助代码上。

为什么语义搜索比手动维护 Markdown 索引更靠谱？

社区中常见的解决方式，是维护一个或多个 MD 文件，记录脚本路径、模块职责、设计背景。这种方式在中小项目中确实有效，也极具工程美感。
有人提议：不如让 AI 自己写个 scriptReferences.md 文件，列出所有脚本的名称、功能和路径，以后直接查这个不就行了？
听起来很美，但实际用起来问题一大堆。

问题出现在规模与变化速度上：
每一次代码修改，都要求文档同步更新。
每一次结构调整，都要求重新组织索引。
一旦文档与真实代码产生时间差，模型反而会被错误引导。

首先，这个文档必须时刻与代码同步——今天新增一个 authMiddleware.ts，明天删掉一个 legacyUtils.js，如果不及时更新索引，AI 就会基于过期信息做决策，轻则浪费时间，重则引入 bug。

其次，在大型项目中，函数和模块成千上万，靠人工或半自动方式维护一份“准确+简洁+有用”的摘要，几乎是不可能的任务。

AI 自己写？那它又得先读一遍所有文件，token 开销一点没省。

而 GrepAI 的优势在于全自动、零维护。代码一改，索引自动更新；代码一删，条目立刻移除。它不依赖任何外部描述，直接从源码中提取结构化信息，永远反映最新状态。更重要的是，它支持“模糊语义查询”——比如问“哪里处理 API 认证？”，即使代码里没有“API”或“认证”这两个词，只要逻辑匹配（比如检查 Authorization header、调用 JWT 验证），就能被召回。而静态 Markdown 只能做精确匹配，无法理解“认证”和“鉴权”、“登录”、“身份验证”其实是同一件事。

当然，GrepAI 也允许用户自定义忽略规则和权重调整。比如可以给 test/ 目录下的文件打低分，避免测试代码干扰主逻辑检索；或者完全屏蔽 *.min.js 这类压缩文件。这种灵活性让它既能适应通用场景，也能针对特定项目微调。

在大型仓库中，这种“人工知识库”很快会从助力变成负担。GrepAI 选择彻底跳过人工维护这一层，让索引始终与代码本体保持一致。

关于性能与理解深度的争议

部分质疑集中在一个点：当 Claude 只看到“精选片段”，是否会因为信息不足而做出错误决策。

这个担忧本身非常合理，但真实情况恰恰相反。
当模型面对整文件甚至整目录时，注意力会被大量无关上下文稀释。
当模型面对高度相关的少量证据时，推理路径反而更加稳定。

GrepAI 的目标从来不是“替模型理解代码”，而是“让模型更快抵达值得理解的地方”。

语义搜索与 grep 并非对立关系

在实践中，最有效的方式并非单选。
精确符号定位、重构替换、查找特定调用点，grep 依然具备无可替代的优势。
跨模块职责定位、功能入口查找、设计意图反推，语义搜索明显更适合。

GrepAI 的出现，本质上是把“意义级探索”从 Claude 的上下文窗口中挪到了本地机器完成。

更深一层的启示：问题并不在模型

一个被反复忽略的事实：
当前智能体系统的最大浪费，并非来自模型能力，而是来自工具输出形式与模型认知方式的不匹配。

为人类设计的工具输出，往往冗长、重复、路径导向明显。
为模型设计的工具输出，应当短、密、结构清晰、直接服务于决策。

GrepAI 并非终局形态，而是一个方向性信号：
代码搜索开始从“文本匹配问题”升级为“认知接口问题”。

性能对比：
https://yoanbernabeu.github.io/grepai/blog/benchmark-grepai-vs-grep-claude-code/