让 Agent 少读代码：本地索引实战

截至 2026 年 10 月，AI Agent 在代码仓库里的最大浪费，往往不是模型推理，而是“找代码”这一步：先 grep，再打开一批文件，接着沿着调用关系继续读取，最后把大量并不相关的文本带进上下文。Local Indexing，也就是本地索引，是解决这个问题的一条相当务实的路线。

**本地索引是指先在开发者设备上为代码、符号、依赖关系和文档建立可查询索引，再让 AI Agent 查询索引结果，而不是每次从文件系统重新扫描项目。**它不改变模型本身，却改变了 Agent 获取上下文的方式：从“把文件搬给模型看”，变成“先定位，再只取模型需要的片段”。

这类优化最近重新受到关注，原因很现实：代码 Agent 的上下文窗口越来越大，但大型仓库的无效读取也在同步膨胀。一个 10,000 个文件的 TypeScript 单体仓库，模型真正需要的可能只有 3 个函数和一条调用链，传统工具却可能让它读几十个文件。

98% 的 Token 节省，究竟省在哪里

“Token 消耗减少 98%”这个数字容易被误解。它通常不是说 grep 命令本身节省了 98%，因为 grep 是本地执行的，根本不消耗模型 Token；真正被压缩的是 grep 之后返回给模型的内容，以及由此引发的后续工具调用。

Agent 搜代码的主要成本，是工具返回结果进入上下文后的重复阅读，而不是本地搜索动作本身。

一个典型的低效流程是：

1. 搜索 AuthService，得到 20 个文件；
2. Agent 逐个读取文件，确认哪些定义了登录校验；
3. 继续搜索 validateToken、refreshSession 等相关符号；
4. 再读取调用方、配置文件和测试文件；
5. 在下一轮修改或调试时重复上述过程。

假设每个文件平均 500 行，单个文件约 4,000 Token，Agent 读取 10 个文件就可能将 40,000 Token 放入上下文。真正相关的代码也许只有 200 行，约 1,600 Token。此时，问题不是模型不会理解，而是它被迫先处理 25 倍于有效信息量的文本。

本地索引的目标，就是把这个比例扳回来。索引层可以先返回：

• 符号名称和类型，例如类、函数、接口、常量；
• 文件路径和行号；
• 函数签名与简短摘要；
• 调用者和被调用者；
• 模块依赖关系；
• 与查询最相近的代码片段；
• 测试文件、配置文件和实现文件之间的关联。

Agent 先用这些低成本元数据做判断，只有在确定相关之后，才读取完整实现。也就是说，索引不是把代码“压缩成向量”这么简单，而是把代码仓库变成一个可以分层查询的知识结构。

Local Indexing 和普通 RAG 不是一回事

**代码本地索引是面向软件结构的检索系统，而普通 RAG 通常是面向文本相似度的文档检索系统。**两者都能减少上下文，但解决的问题不同。

传统 RAG 往往把 Markdown、PDF 或代码按固定长度切块，再用向量相似度检索。这个方案适合知识库，却不一定适合代码。代码的关键关系通常不是“这两段文本语义相似”，而是“这个函数调用了另一个模块里的函数”“这个接口由三个类实现”“这个变量来自某个配置注入”。

因此，适合代码 Agent 的本地索引通常是混合检索：

| 检索方式 | 擅长解决的问题 | 局限 | 适合返回的内容 | |---|---|---|---| | 文件名与关键词检索 | 快速找出显式命名、错误信息和配置项 | 不理解代码结构，噪声较多 | 文件路径、匹配行 | | AST 符号索引 | 定位函数、类、接口和参数 | 对动态语言和宏代码支持依赖解析器 | 符号定义、签名、行号 | | 调用图索引 | 查找调用者、被调用者和依赖链 | 构建和维护成本更高 | 调用路径、模块关系 | | 向量语义检索 | 查找描述不同但含义相近的代码 | 可能忽略精确符号关系 | 相关代码片段 | | 关键词与语义混合检索 | 同时处理精确名称和自然语言需求 | 需要排序与去重策略 | 排序后的候选片段 |

如果用户问“谁调用了 refreshSession”，AST 和调用图比向量搜索可靠；如果用户问“找出处理登录失败重试的逻辑”，语义检索更有帮助。真正有效的系统，往往会把这些结果合并，再进行二次排序。

Semble 的思路：先检索，再重排，最后按需读取

近期被开发者讨论较多的 Semble，核心定位很明确：让 Agent 搜索代码时少读文件、少走几轮工具调用。它支持作为 MCP Server 接入 Claude Code、Cursor、Codex 等开发工具，也可以作为本地命令行工具使用。

Semble 是一个面向代码 Agent 的本地混合检索工具，重点不是生成代码，而是用代码级索引返回更小、更相关的上下文。

它的工作方式可以概括为四层：

1. 本地解析：扫描项目，识别函数、类、接口、导入关系和文件结构；
2. 候选召回：同时使用关键词、符号匹配和语义相关性找到候选结果；
3. 多层重排序：根据命名匹配、路径、代码结构和查询语义重新排序；
4. 分级输出：优先返回摘要、签名和位置，需要时再读取实现代码。

其中最有价值的不是“搜索更快”，而是它允许 Agent 先使用 outline，也就是代码轮廓模式。轮廓模式只返回函数签名、类名、接口定义和文件位置，不直接返回函数体。

假设一个 500 行的服务文件包含 20 个函数，完整读取可能需要几千 Token；如果只返回这些函数的名称、参数和返回值，内容可能压缩到原来的 2% 到 10%。Agent 先通过轮廓确认目标，再读取其中一两个函数，通常比一上来打开整份文件更稳定。

可以用下面的方式安装和接入本地工具，具体参数应以项目当前版本文档为准：

# Python 版本，作为本地 MCP 服务运行
pip install semble

# Rust 版本
cargo install semble_rs

这种工具的优势也很直接：不需要 GPU，不依赖云端索引服务，索引和代码都留在本机，适合包含私有业务代码的仓库。代价是首次建立索引需要时间，而且不同语言的解析质量并不完全一致。

实战：给一个大型仓库建立分层索引

本地索引落地的关键，不是安装一个搜索工具，而是把 Agent 的读取顺序改成“索引优先、文件兜底”。

下面以一个包含前端、后端和基础设施目录的仓库为例。

第一步：先划分索引边界

不要默认扫描整个磁盘，也不要把 node_modules、构建产物、缓存和二进制目录纳入索引。一个合理的初始范围通常包括：

• src/、app/、packages/ 等源码目录；
• tests/、__tests__/ 等测试目录；
• README、架构文档和模块说明；
• 类型定义、路由、配置和数据库迁移文件。

应排除：

• node_modules/、vendor/、dist/、build/；
• 大型日志、快照和生成文件；
• 包含密钥、令牌或个人信息的本地配置；
• 与当前任务无关的历史归档目录。

索引范围越干净，召回结果越稳定。把所有内容都索引进去，不等于 Agent 会更聪明，很多时候只会增加候选噪声。

第二步：建立符号和依赖索引

代码索引至少应记录以下字段：

symbol: AuthService.validateToken
kind: method
file: packages/auth/src/auth-service.ts
line: 84-137
signature: validateToken(token: string): Promise<User>
callers: LoginController.login, SessionMiddleware.handle
callees: JwtProvider.verify, UserRepository.findById
module: packages/auth

这类结构化记录比直接存储完整文件更适合 Agent。对于“梳理登录校验调用链”这样的任务，模型首先需要的是入口、出口和中间依赖，不是整个仓库的原始文本。

索引更新也不必每次全量执行。文件保存后，只重新解析发生变化的文件，并更新受影响的符号关系即可。对于大型仓库，增量索引比每次从头扫描更重要；否则索引本身就可能成为开发流程中的等待点。

第三步：设置三档读取策略

建议把返回内容分成三档，而不是让所有查询都直接返回完整代码。

**第一档是 outline。**只返回路径、符号、签名和行号，适合定位入口、确认命名和快速了解项目结构。

**第二档是 snippet。**返回目标函数及其前后少量上下文，适合判断业务逻辑、异常处理和参数流转。

**第三档是 full read。**读取完整文件或较大的代码区间，只在需要理解复杂状态机、继承关系或跨函数副作用时使用。

一个经验规则是：先用 outline 找候选，最多挑选 3 到 5 个相关符号，再读取 snippet；只有当 snippet 不能解释问题时，才扩大范围。这个过程像调试器里的逐层展开，而不是把整个调用栈一次性打印出来。

第四步：为 Agent 规定工具优先级

如果 Agent 同时能使用 list_dir、grep、read_file 和代码索引工具，它未必会自动选择最省 Token 的路径。项目级规则文件应明确告诉它：

• 查询代码结构时优先使用索引；
• 先查询符号和调用关系，再读取文件；
• 不要为了确认一个函数而读取整个目录；
• 发现索引结果过旧时，只刷新相关文件；
• 对生成文件、依赖目录和日志目录默认跳过；
• 只有索引无法解析的格式，才使用通用文本搜索兜底。

这类规则的价值在于减少无效探索。它不是给模型增加更多背景知识，而是限制模型不要采用昂贵且低信息密度的动作。

Token 节省应该怎样测

评估本地索引是否有效，不能只看单次搜索耗时，应该同时统计工具调用次数、输入 Token、返回 Token 和任务完成轮次。

建议建立一组固定任务，例如：

1. 找出某个 API 路由的完整调用链；
2. 修复一个跨模块的类型错误；
3. 为已有服务补充单元测试；
4. 解释某个状态字段从写入到读取的路径；
5. 修改一个功能并同步更新相关测试。

然后分别测试“传统 grep + read_file”和“本地索引优先”两种方案。可以使用下面的指标表：

| 指标 | 传统文件检索 | 本地索引优先 | 关注点 | |---|---:|---:|---| | 工具调用次数 | 例如 20 次 | 例如 6 次 | 是否减少探索轮次 | | 返回上下文 Token | 例如 40,000 | 例如 4,000 | 是否减少无关文本 | | 首次定位耗时 | 例如 2.5 秒 | 例如 0.3 秒 | 索引查询是否足够快 | | 完成任务总轮次 | 例如 12 轮 | 例如 7 轮 | 是否减少反复确认 | | 任务准确率 | 以测试结果为准 | 以测试结果为准 | 是否因过度压缩而漏信息 |

在最佳场景下，outline 加精准片段确实可能把上下文压缩到原来的 2% 到 10%，也就是减少 90% 至 98% 的代码读取 Token。但这个数字不应被当作普遍承诺：小项目、一次性任务或本来就只需读取一个文件的任务，收益会很有限。

更值得关注的是调用轮次。假设每轮工具调用都会让 Agent 重新携带部分历史上下文，那么从 12 轮降到 7 轮，节省的不只是 5 次工具返回结果，还包括后续每一轮都要重复计入的对话上下文。修复循环越长，本地索引的累计收益越明显。

它和代码图谱、工具预过滤是什么关系

本地索引并不是唯一的 Agent 降本手段，而是更大优化体系中的“代码检索层”。

代码图谱关注项目中的结构关系，例如模块依赖、调用者和被调用者；本地索引关注如何快速取出这些关系以及相关文本；工具预过滤则解决另一个问题：不要让 Agent 在每一轮都看到几十个无关工具的完整描述。

有研究和生产实践显示，工具语义预过滤可以把每次查询携带的工具描述从 1,557 Token 降至 275 Token，减少约 89%；在某些测试中，准确率还从 75.8% 提升到 82.3%。这说明“给模型更多工具”并不等于更强，工具太多反而会增加选择负担。

因此，一个更完整的 Agent 上下文优化链路可以是：

1. 用项目规则限制不必要的探索；
2. 用工具预过滤减少无关工具 Schema；
3. 用本地索引定位符号、文件和调用链；
4. 用代码图谱补充结构关系；
5. 用 outline 和 snippet 控制返回粒度；
6. 对重复查询做缓存和去重；
7. 最后才把必要的完整代码交给模型。

这比单独追求“更大的上下文窗口”更划算。上下文窗口解决的是“能不能装下”，本地索引解决的是“有没有必要装进去”。

局限：不是所有代码都能被索引理解

本地索引并非万能。静态分析对强类型语言、明确的模块系统和标准项目结构通常更有效；对于大量使用反射、运行时拼接、动态注册、宏、代码生成或字符串路由的项目，调用图可能不完整。

动态语言中的别名导入、依赖注入和框架约定，也可能让索引误判。此时必须保留 grep 和直接读取文件作为兜底，否则 Agent 可能因为索引“看起来很确定”而漏掉真正的实现。

索引过期也是常见问题。开发者修改文件后，如果索引没有及时增量更新，Agent 得到的行号、签名甚至调用关系都可能已经失效。实战中应该展示索引时间戳，并在检测到文件变更时自动刷新，而不是静默使用旧结果。

另一个问题是安全。虽然索引在本地运行，但索引数据库本身可能包含文件路径、符号名和代码片段。它同样需要纳入项目的访问控制、备份策略和敏感信息排除规则。对包含凭证、个人数据或客户代码的目录，默认不建立索引通常更稳妥。

结论：Agent 的下一步不是“读更多”，而是“先知道该读什么”

本地索引的价值不在于把某个搜索命令包装成更复杂的工具，而在于改变 Agent 的工作范式：从全目录扫描、整文件读取和多轮试错，转向符号定位、关系查询和按需展开。

如果你的项目只有几百个文件，直接使用编辑器搜索可能已经足够；但当仓库达到数千甚至上万个文件，或者 Agent 经常需要跨模块追踪调用链时，本地索引会从“锦上添花”变成基础设施。尤其是每天运行多个代码 Agent、频繁进行修复循环的团队，减少一次上下文读取，往往比单纯更换模型更容易立刻看到成本和延迟收益。

我的判断是：**98% 不是所有任务都能复现的统一指标，但“索引优先、文本兜底”确实是代码 Agent 走向稳定生产化的正确方向。**它最重要的成果不是让模型拥有更多代码，而是让模型少看无关代码、少调用工具、少在错误路径上浪费上下文。

对开发者来说，最值得今天就做的改动只有三件事：为仓库建立增量索引，为 Agent 默认开启 outline 查询，并记录每项任务的工具调用次数和上下文 Token。先把浪费测出来，再决定是否需要更复杂的代码图谱和语义重排。

参考来源

• Semble 项目检索结果（GitHub）：用于了解 Semble 相关开源项目及其代码 Agent 检索方向。
• Token 降本：Harness 工作流的成本优化实践（知乎）：讨论代码图谱、子 Agent、上下文缓存和工具调用优化。
• N+1 查询问题已经感染了你的 AI Agent（天帆，知乎相关转载）：本文用于参考 Agent 工具调用批处理、去重和并行执行等优化思路；该链接为原文地址，便于读者进一步核对。