← 所有文章

代理代码搜索有自己的 Token 预算

3分钟阅读
From the guides: Claude Code & Codex CLI

Semble 于 2026年5月17日突破 900 个 GitHub 星标，并提出了一个直白判断：代码代理在执行 grep、打开整个文件、读取远超任务所需的代码时，会浪费大部分上下文预算。1

这个判断之所以成立，是因为它把代码搜索重新定义为预算问题。人类可以快速扫过嘈杂的 rg 结果，忽略无关内容。代理却要为每一行无关文本付出代价：上下文、注意力和工具循环时间都会被消耗。

要点速览

Semble 是一个面向代理的代码搜索库。它提供 MCP 服务器、通过 AGENTS.md 或 CLAUDE.md 接入的 shell 集成、CLI，以及 Python API。1在底层，Semble 会对代码分块，使用 BM25 加静态 Model2Vec 代码嵌入进行搜索，通过 Reciprocal Rank Fusion 融合排序列表，再用符号加权、定义提升、标识符词干、文件一致性和噪声惩罚等代码感知信号重新排序。1它的基准测试报告显示，在 19 种语言、63 个代码库、约 1,250 个查询上，NDCG@10 达到 0.854，接近 CodeRankEmbed 混合方案的 0.862，同时在基准表中索引速度快得多。2真正重要的产品启示不是“替代 grep”。更准确地说，代理搜索工具应该返回最小的证据包，让模型能够正确行动。

关键结论

  • 对于代码代理用户：精确字符串仍然用 rg；当任务问的是行为而不是字面 token 时，使用按片段排序的搜索。
  • 对于工具构建者：优化取回来的上下文，而不只是优化检索准确率。真正有用的单位是每个 token 承载的证据。
  • 对于 Codex 和 Claude Code 用户：优先提供可通过 shell 访问的路径，因为顶层 MCP 工具未必能以同样方式触达被委派的代理。1
  • 对于阅读基准测试的人：要区分供应商基准声明和本地执行行为。我的冷启动 uvx 运行比 Semble 的基准表慢很多，因为包、模型和索引启动占了主要时间。
  • 对于公共写作：检索工具不会免除引用工作。它们只是让证据路径更便宜、更容易检查。

Grep 仍然好用，但还不够

rg 仍然是精确字符串的首选工具。如果我要找 visible_label_residue、某个凭据变量名或函数名，词法搜索应该凭借速度和确定性胜出。在我的本地测试中，对翻译残留术语执行字面 rg 查询，大约十分之一秒就返回了结果。5

问题出现在代理并不知道精确字符串的时候。

代理经常按意图搜索：“博客 i18n 关口在哪里检查可见标签残留”或“翻译发布验证是如何工作的？”字面搜索仍然可能找到有用行，但代理必须选择关键词、检查几十条命中、读取文件、重新表述查询，并判断哪一行承载答案。每一步都会消耗上下文，也都可能让代理过早停下。

Semble 针对的正是这种失败模式。它允许代理用自然语言查询，然后返回排序后的代码片段，而不是整个文件。1这并不意味着 rg 过时了。它改变的是默认交互：从“给我所有匹配这个术语的行”，变成“给我最小但有用的代码切片”。

这个区别很重要，因为代理不像人类那样阅读。人类可以扫过 80 行搜索输出，只把有意思的 3 行记在脑中。模型会把完整输出作为 token 接收。嘈杂的搜索结果会成为任务环境的一部分。

Semble 实际做了什么

Semble 的公开 README 描述了 4 种集成路径：MCP 服务器、Bash / AGENTS.md、CLI，以及 Python API。1Codex 设置是在 ~/.codex/config.toml 中添加本地 MCP 服务器条目；shell 路径则是在 AGENTS.md 或 CLAUDE.md 中添加代码搜索段落。1

shell 路径的重要性比乍看更高。README 写明，Claude Code 和 Codex CLI 子代理应使用 Bash 集成，而不是只使用 MCP，或者至少两者并用，因为在该设置下，子代理不能直接调用 MCP 工具。1这是一个实际的代理接口问题：搜索工具需要存在于工作发生的地方，而不只是顶层会话启动的地方。

它的检索栈也代表了代理搜索正在走向的方向：

层级 作用
代码感知分块 搜索返回片段，而不是整个文件
BM25 捕获标识符、API 名称、精确术语和词法线索
静态 Model2Vec 嵌入 在查询时无需 transformer 前向推理，也能捕获语义意图
Reciprocal Rank Fusion 无需分数校准即可融合词法排序和语义排序
代码感知重排 提升定义、符号匹配、文件级一致性和可能的规范实现

这种设计与我在本地检索系统中看到的情况一致：纯向量搜索会漏掉标识符，纯关键词搜索会漏掉意图，混合排序能让代理第一次阅读就更接近答案。4

基准声明谈的是上下文，不是魔法

Semble 的基准 README 报告了两类结果。

第一类衡量检索质量和速度。表中显示 Semble 的 NDCG@10 为 0.854，CodeRankEmbed Hybrid 为 0.862，BM25 为 0.673，ripgrep 为 0.126。该基准覆盖 19 种语言、63 个代码库、约 1,250 个查询，并采用纯 CPU 运行。2

第二类衡量 token 效率。基准模拟了一种常见代码代理工作流：把查询拆成关键词，运行 rg --fixed-strings --ignore-case，按不同关键词匹配数对文件排序，然后完整读取匹配文件。与这个基线相比，基准报告称，ripgrep 加完整文件读取平均消耗 45,692 个 token，而 Semble 为 566 个 token，减少 98%。2

这才是有意思的主张。它不是说“语义搜索在所有场景都胜过 grep”。也不是说“代理应该停止使用精确搜索”。它说的是：当任务只需要几个代码块时，grep 后再通读文件会把太多无关代码送进模型。

基准方法也说明了这个结论适用和不适用的范围。Semble 比较的是完整读取匹配文件。2如果您的工作流已经会使用 rg -n、sed 和精确行范围，那么您的基线可能比该基准中的 grep 加通读模型更紧凑。如果您的代理经常在宽泛搜索后打开整个文件，那么这个基准就更贴近真实失败模式。

我的本地测试

我在站点代码库中通过 uvx --from semble semble 运行 Semble，然后将它与字面 rg 搜索对比。

我先用了一个发布流程查询：

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Semble 返回了 5 个片段。第一条结果概述了某篇迁移文章表格中的博客翻译发布循环。另一条结果直接指向 scripts/i18n-automation/README.md，其中包含质量关口、发布验证器、母语审校、提交、推送、Railway、Cloudflare 和线上冒烟测试步骤。5

可比的 rg 命令返回很快，但它输出了大量字面匹配，包括脚本、测试和文档中的凭据变量、blog_release_verify 以及相关名称。5人类可以过滤这些内容。代理则必须花费上下文来完成同样的事。

然后我询问关口实现：

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Semble 的首条结果指向了准确的本地关口代码块：visible_label_residue 在那里被赋值、转化为错误，并影响 finding 状态。输出包含相关函数体行，而不是整个文件。5

可比的 rg 查询同样更快完成，但返回了测试、翻译提示、修复脚本、README 和关口实现中的大量命中。5

这个测试不能证明 Semble 的基准。我的调用使用了 uvx，下载了包和模型资产，索引了一个大型混合代码库，包含 Markdown 和 JSON 文件，并且是冷路径运行。第一次 Semble 查询约耗时 54 秒，第二次约耗时 31 秒。5这些数字与项目基准表不一致，我不会把它们作为 Semble 性能数据引用。

但这个测试证明了产品形态。Semble 返回的是更小、更像答案的证据包。两次搜索后，semble savings --verbose 报告称，按照它自己的“文件对片段”节省方法，估计节省约 38,100 个 token，比例为 94%。5这应视为工具报告的估计值，而不是独立测量；但方向与可见输出一致。

正确心智模型：证据包

代理搜索应该产出证据包。

证据包具备 4 个属性：

属性 重要性
小 模型把注意力花在相关代码上，而不是文件体量上
有位置 结果携带文件路径和行范围
足够 片段包含下一步所需的充分上下文
可升级 当片段不够时，代理可以打开完整文件

原始 rg 提供位置和速度。完整文件读取提供上下文，但通常太多。向量搜索提供意图，但可能漏掉精确名称。好的代理搜索工作流应把它们结合起来：

  1. 当任务点名符号、错误、配置键、文件或字面字符串时，使用精确搜索。
  2. 当任务描述行为时，使用按片段排序的语义或混合搜索。
  3. 只有当片段证明相关时，才打开完整文件。
  4. 在最终答案中引用文件和行范围。
  5. 当片段提示出具体标识符时，再用精确搜索重试。

Semble 将这套工作流的大部分内容编码成了工具。代理仍然需要判断，而证据关口仍然需要一条可检查的追踪。

Semble 如何改变 Codex 和 Claude Code 工作流

实际问题不是要不要安装每一个新的搜索工具。问题是：代码搜索应该处在代理操作契约的什么位置。

对于顶层会话，MCP 可以运作良好，因为代理能看到工具 schema，并直接调用服务器。Semble 的 README 提供了面向 Claude Code、Codex、OpenCode、Cursor 和其他兼容 MCP 客户端的 MCP 设置示例。1

对于被委派的工作，shell 访问可能更重要。Semble 的 README 明确点出了面向 Claude Code 和 Codex CLI 子代理的 Bash 集成。1无法触达顶层 MCP 工具的子代理，如果工作流教会它何时以及如何使用 shell 命令，仍然可以执行搜索。

这意味着最好的集成方式可能很朴素：

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

这种指令比含糊的“使用语义搜索”更有效，因为它明确了路由决策。代理会学到哪个工具适合哪个问题。

我不会做什么

我不会替换 rg。

本地测试已经说明了这一点。rg 对字面查询的响应大约只需十分之一秒。Semble 在行为型查询上返回了更好的证据包，但我的冷启动 shell 调用确实有启动和索引成本。5

我不会把 Semble 的 98% token 节省声明当作普遍真理。该基准比较的是 grep 加完整文件读取。当这个基线类似于代理的真实行为时，声明是合理的。如果一个训练有素的工作流已经只读取精确行范围，那么这个收益就会被夸大。

我也不会把路由选择藏进黑盒。代理需要知道自己是在做精确查找、语义发现、相关代码探索，还是证据确认。没有路由规则的工具使用，会成为另一种貌似可信的失败来源。这与由聊天驱动的代理工作背后的接口问题相同。

为什么 Semble 应该与 Grep 论文并列讨论

近期的“Is Grep All You Need?”论文在 Chronos、Claude Code、Codex CLI 和 Gemini CLI 上，测试了 grep 与向量检索在长记忆对话 QA 中的表现。在该设置下，内联 grep 胜过内联向量，但论文更深层的教训更重要：执行环境对结果的影响不亚于检索方法本身。3

Semble 从代码侧指向了同一个操作层。搜索质量并不只存在于检索器内部。它还存在于：

  • 查询如何形成；
  • 精确路径和语义路径是否同时存在；
  • 工具返回多少上下文；
  • 片段是否携带文件和行号证据；
  • 代理是否只在必要时打开完整文件；
  • 被委派的代理是否能触达工具；
  • 最终答案是否引用了搜索实际找到的内容。

包装层仍然是产品。只有当执行环境把检索转化为证据时，搜索才有用。这也是为什么代理式设计控制面与检索算法同等重要。

我想要的标准

代理搜索工具不应只报告匹配项。

它应该报告：

  • 执行的查询；
  • 使用的检索路径；
  • 文件和行范围；
  • 片段；
  • 返回 token 的估计值；
  • 结果来自精确检索、语义检索还是混合检索；
  • 代理何时从片段升级到完整文件读取。

这样的输出会让代码搜索可审计。审阅者可以看到代理是否找到了正确代码、是否读取了足够上下文，以及是否避免把自己淹没在无关文件中。同样的原则也驱动着代理执行追踪：证明存在于路径中，而不只存在于答案里。

Semble 已经通过把片段大小和 token 节省作为一等产品问题，向这个方向迈出了一步。代理执行环境的下一步，是在审阅包和最终答案中呈现这条证据路径。

目标不是让搜索更漂亮。目标是降低每个 token 中无依据断言的密度。

常见问题

Semble 会替代 grep 吗？

不会。精确字符串、符号、配置键、文件名和快速确认仍然用 rg。当任务描述的是行为或相关实现，而代理不知道精确标识符时，再使用 Semble 式片段检索。

您的本地测试确认了 Semble 的速度声明吗？

没有。我的本地 uvx 调用第一次查询约耗时 54 秒，第二次约耗时 31 秒，主要是因为包、模型启动和索引占据了这次临时运行的大部分时间。Semble 的基准表报告了快得多的受控测量结果，但我的本地运行应视为工作流证据，而不是性能基准。25

您的本地测试确认了 token 节省方向吗？

在工作流层面，是的。与宽泛的字面 rg 输出相比，Semble 返回的片段小得多；它的 savings 命令在两次搜索后报告约节省 38,100 个估计 token。这个节省数字来自 Semble 自己的统计方法，因此应视为工具遥测，而不是独立证明。5

为什么代理代码搜索对 Codex 和 Claude Code 重要？

当搜索倾倒过多上下文，或隐藏过多证据时，代理质量会下降。好的工作流会教代理何时使用精确搜索、何时使用按片段排序的检索、何时打开完整文件，以及如何引用结果。

团队应该把 Semble 加进 AGENTS.md 吗？

只有在自己的代码库上测试之后才应该这样做。可以先从一条指令开始：行为型问题使用按片段排序的搜索，精确字符串使用 rg。然后衡量代理是否能更快找到正确文件，并读取更少无关行。

参考资料

  1. MinishLab，《Semble README》，GitHub 代码库文档。Semble 用途、集成路径、MCP 和 AGENTS.md 设置、子代理 Bash 说明、search/savings 命令、检索架构、代码感知排序信号，以及核心功能声明的来源。2026年5月17日的当前会话验证发现，PyPI 版本为 0.1.7，最新 GitHub 发布版本为 v0.1.7，许可证为 MIT，代码库描述为“Fast and Accurate Code Search for Agents. Uses ~98% fewer tokens than grep+read.” ↩↩↩↩↩↩↩↩↩↩

  2. MinishLab，《Semble benchmarks》，GitHub 基准文档。63 个代码库、19 种语言、约 1,250 个查询的方法；NDCG@10 和延迟表；纯 CPU 基准说明；token 效率方法；以及 ripgrep 加完整文件读取平均 45,692 个 token、Semble 平均 566 个 token 报告值的来源。 ↩↩↩↩↩

  3. Sahil Sen, Akhil Kasturi, Elias Lumer, Anmol Gulati, Vamse Kumar Subbiah，《Is Grep All You Need? How Agent Harnesses Reshape Agentic Search》，arXiv:2605.15184v1，提交于 2026年5月14日。长记忆 QA 搜索在 Chronos、Claude Code、Codex CLI 和 Gemini CLI 上的比较，以及检索行为取决于执行环境和交付路径这一结论的来源。 ↩

  4. 作者此前的生产检索文章，《面向 Obsidian 的混合检索器》，blakecrosley.com。本地 BM25 加向量检索模式、RRF 融合框架，以及个人知识库中精确路径与语义路径失败模式的来源。 ↩

  5. 作者于 2026年5月17日进行的当前会话本地验证。命令包括 uvx --from semble semble --help、uvx --from semble semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files、uvx --from semble semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files、可比的 rg 搜索，以及 uvx --from semble semble savings --verbose。观察结果：Semble 暴露了 search、find-related、init 和 savings；第一次查询返回了有针对性的发布循环片段；第二次查询返回了 visible_label_residue 关口代码块；可比的 rg 搜索完成更快，但返回了更宽泛的字面匹配流；Semble 报告了 2 次搜索调用，并估计节省约 38,100 个 token，比例为 94%。 ↩↩↩↩↩↩↩↩↩↩

相关文章

上下文工程即架构：650个文件之后的实践

横跨650个文件、七层层级结构的AI代理上下文工程。三次生产故障、真实的token预算，以及在这些考验中存活下来的系统。

2 分钟阅读