Semble：为 Agent 优化的代码搜索（省 98% Token）

Semble：为 Agent 优化的代码搜索（省 98% Token） | 前端进阶之旅

Full translation

完整中文译文

用于 Agent 的快速准确的代码搜索使用的 Token 数量比 grep+read 少 98%

快速开始 • CLI • MCP Server • 安装 • 基准测试

Semble 是一个为 Agent 构建的代码搜索库。它能够即时返回 Agent 需要的精确代码片段，使用的 Token 数量比 grep+read 少约 98%。从端到端索引和搜索整个代码库只需不到一秒，索引速度快约 200 倍，查询速度快约 10 倍（相比代码专用 Transformer），检索质量达到 99%（见基准测试）。所有操作都在 CPU 上运行，无需 API 密钥、GPU 或外部服务。可作为 MCP server、通过 AGENTS.md 的 CLI 工具或专用子 Agent 使用，任何编码 Agent（Claude Code、Cursor、Codex、OpenCode 等）都能即时访问任何仓库。

你的 Agent 用自然语言查询 Semble（例如"身份验证是如何处理的？"），然后获得仅包含相关代码片段的结果，无需 grep 或读取完整文件。

快速开始

最快的入门方式是交互式安装程序。先安装 uv，然后运行：

uv tool install semble
semble install

semble install 会检测已安装的编码 Agent（如 Claude Code、Codex 和 OpenCode），然后让你选择启用哪些集成：

MCP server：让 Agent 能够直接将 Semble 作为工具调用。

Instructions：向 AGENTS.md / CLAUDE.md 添加 CLI 使用指南。

Sub-agent：安装专用的 semble-search 子 Agent。

要撤销设置，运行 semble uninstall。

有关手动设置说明（每个 Agent 的 MCP 配置、AGENTS.md 片段、子 Agent 文件），见安装文档。

uv tool upgrade semble   # 升级
uv cache clean semble    # MCP 用户适用（重启 MCP 客户端后）

对于沙箱或脚本环境，使用 --agent 和可选的 --type 跳过提示：

semble install --agent claude --type mcp subagent --yes

--agent 接受一个或多个 Agent ID（例如 claude、codex、pi）；--type 接受 mcp、instructions、subagent 或 all（默认：all）；--yes 跳过确认提示（完全非交互式运行需要 --agent）。

特性

快速：在约 250 ms 内索引平均仓库，在约 1.5 ms 内回答查询，全部在 CPU 上完成。

准确：基准测试上 NDCG@10 达到 0.854，与代码专用 Transformer 模型相当，但体积和成本仅为其中的一小部分。

Token 高效：仅返回相关块，使用的 Token 数量比 grep+read 少约 98%。

零配置：在 CPU 上运行，无需 API 密钥、GPU 或外部服务。

MCP server：兼容 Claude Code、Cursor、Codex、OpenCode、VS Code 和任何其他 MCP 兼容 Agent。

本地和远程：接受本地路径或 git URL。

CLI

Semble 也以独立 CLI 的形式提供。这在脚本中或任何你需要搜索结果但没有 MCP 会话的地方都很有用。索引在首次运行时构建和缓存，文件更改时自动失效。

# 搜索本地仓库（索引自动构建和缓存）
semble search "authentication flow" ./my-project

# 搜索远程仓库（按需克隆）
semble search "save model to disk" https://github.com/MinishLab/model2vec

# 限制结果
semble search "save model to disk" ./my-project --top-k 10

# 搜索文档/配置/所有内容而不仅仅是代码
semble search "deployment guide" ./my-project --content docs   # 或：config, all

# 查找与已知位置相似的代码
semble find-related src/auth.py 42 ./my-project

--content 接受 code（默认）、docs、config 或 all。省略时 path 默认为当前目录；接受 git URL。如果 semble 不在 $PATH 中，使用 uvx --from "semble[mcp]" semble 替代。

忽略文件

Semble 读取 .gitignore 和 .sembleignore 文件以确定要索引的文件。两个文件都使用标准 gitignore 语法，它们的模式会合并。.sembleignore 让你添加 Semble 特定的规则而无需修改 .gitignore。规则递归应用，因此子目录中的 .sembleignore 适用于该子树。

排除文件：以与 .gitignore 中相同的方式添加模式：

# .sembleignore
generated/     # 排除生成目录
*.pb.go.       # 排除 Go protobuf 文件

包含非默认扩展名：在扩展名模式前面加 ! 以强制包含 Semble 默认不会索引的文件：

# .sembleignore
!*.proto       # 包含 Protobuf 文件
!*.cob         # 包含 COBOL 文件

Semble 还总是跳过一组众所周知的非源代码目录，无论忽略文件如何（例如 node_modules/、.venv/、dist/、build/、pycache/ 和类似的）。

统计节省

semble savings 显示你所有搜索中 Semble 节省了多少 Token：

semble savings

  Semble Token Savings
  ════════════════════════════════════════════════════════════════════════

  Total saved:  ~714.2M tokens  (94%)
  Total calls:  14.3k
  Efficiency:  ███████████████████████░  94%

  By Period
  ────────────────────────────────────────────────────────────────────────
  Period             Calls           Saved  Ratio
  ────────────────────────────────────────────────────────────────────────
  Today                198    ~1.4M tokens  ███████████████████████░  95%
  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%

  By Call Type
  ────────────────────────────────────────────────────────────────────────
  #     Call type            Calls  Share
  ────────────────────────────────────────────────────────────────────────
  1.    search               14.1k  ████████████████    99%
  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
  ════════════════════════════════════════════════════════════════════════

节省计算如下：对于每次调用，Semble 记录包含返回块的唯一文件的总字符数和返回片段的字符数。估计的节省 Token 数是 (file chars − snippet chars) / 4（4 个字符 = 1 Token）。这是保守的估计：基线是读取匹配的完整文件，这是编码 Agent 在探索陌生代码时的常见做法。

默认情况下，你的 Semble 节省统计和任何保存的索引存储在操作系统缓存文件夹（macOS 上的 ~/Library/Caches/semble/、Linux 上的 ~/.cache/semble/、Windows 上的 %LOCALAPPDATA%\semble\Cache\）。要覆盖此位置，可以提供环境变量 SEMBLE_CACHE_LOCATION，其值应为目标缓存位置的完整路径，例如 ~/my-folder/my-caches/semble。

首次使用时，Semble 还会从 Hugging Face 下载嵌入模型并缓存在标准 Hugging Face 缓存中（默认为 ~/.cache/huggingface/，或 $HF_HOME 如果设置）；这仅发生一次并需要网络访问。

Python 库

Semble 也可作为 Python 库供程序化访问，对于构建自定义工具或将搜索直接集成到你自己的代码中很有用。

from semble import ContentType, SembleIndex

# 索引本地目录（仅代码，默认）
index = SembleIndex.from_path("./my-project")

# 索引文档和散文（markdown、rst 等）
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# 索引所有内容（代码、文档和配置）
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG])

# 一起索引代码和文档
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# 索引远程 git 仓库
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# 用自然语言或代码查询搜索索引
results = index.search("save model to disk", top_k=3)

# 查找与特定结果相似的代码
related = index.find_related(results[0], top_k=3)

# 每个结果都暴露匹配的块
result = results[0]
result.chunk.file_path   # "model2vec/model.py"
result.chunk.start_line  # 127
result.chunk.end_line    # 150
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

MCP Server

Semble 作为 MCP server 运行，所以 Agent 可以直接将任何代码库的搜索作为原生工具调用。仓库按需索引并缓存；本地路径在文件更改时自动重新索引。

有关每个 Agent 的设置说明，见安装文档。

基准测试

我们在 19 种语言的 63 个仓库上的约 1,250 个查询中进行了质量和速度基准测试（左图），以及与 grep+read 在等价召回率下的 Token 效率基准测试（右图）。

质量基准测试（左图）根据总延迟对检索质量（NDCG@10）进行评分；Semble 实现了 137M 参数的 CodeRankEmbed Hybrid 99% 的质量，同时索引速度快 218 倍。Token 效率基准测试（右图）测量每种方法需要多少 Token 才能达到给定的召回率；Semble 平均使用 98% 更少的 Token，并在仅 2k Token 时达到 94% 的召回率，而 grep+read 需要完整的 100k 上下文窗口才能达到 85%。见基准测试了解每种语言的结果、消融和完整方法论。

工作原理

Semble 使用 tree-sitter 将每个文件分割成代码感知的块，然后用两个互补的检索器对每个查询与块进行评分：使用代码专用的 potion-code-16M-v2 模型的静态 Model2Vec 嵌入用于语义相似性，以及 BM25 用于标识符和 API 名称的词汇匹配。这两个评分列表用倒数排名融合（RRF）进行融合。

融合后，结果用一组代码感知的信号重新排名：

自适应加权。类似符号的查询（Foo::bar、_private、getUserById）获得更多词汇权重，而自然语言查询在语义和词汇检索器之间保持平衡。

定义提升。定义所查询符号（类、def、func 等）的块被排在仅仅引用它的块之上。

标识符词干。查询标记被进行词干处理，并与块中的标识符词干匹配，为包含它们的块提供额外的权重。例如，查询 parse config 会提升包含 parseConfig、ConfigParser 或 config_parser 的块。

文件连贯性。当同一文件中的多个块与查询匹配时，该文件被提升，以便顶部结果反映广泛的文件级相关性，而不是单个上下文外的块。

噪声罚分。测试文件、compat/legacy/ shim、示例代码和 .d.ts 声明存根被降低排名，以便规范实现浮出水面。

由于嵌入模型是静态的，在查询时没有 Transformer 前向传递，所有这些都在毫秒内在 CPU 上运行。

缓存和增量索引

索引在首次搜索时自动缓存到磁盘。在后续运行中，Semble 遍历文件树并比较修改时间；添加、移除或更改的文件会增量重新索引，而无需重建其余索引。只有在索引设置更改时才会发生完整重建（例如在 semble 升级后改变了模型、分块或缓存格式）。在 MCP 模式下，索引会在文件更改时自动检查和刷新，因此结果在整个会话中保持最新。

致谢

感谢 Greptile 为其 AI 代码评审平台提供免费访问权限。

引用

如果你在研究中使用 Semble，请按如下方式引用：

@software{minishlab2026semble,
  author       = {{van Dongen}, Thomas and Stephan Tulkens},
  title        = {Semble: Fast and Accurate Code Search for Agents},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19785932},
  url          = {https://github.com/MinishLab/semble},
  license      = {MIT}
}