2.9K Star！这个工具让 Agent 查代码快了 200 倍！节省 98% Token 消耗！

当下，Agent 正在越来越多地介入我们的代码工作流。

从代码补全到代码审查，从重构建议到自动生成测试，AI 已经成了很多开发者的得力助手。

但相信大家在深度使用时还是会有个问题！

那就是当 Agent 需要在一个大型代码库中找东西时，它要么瞎猜关键词，要么就得把整个项目内的文件都读一遍。

结果就是要么找不到，要么就是 Token 像流水一样哗哗地流。一个 100k Token 的上下文窗口，一大半都浪费在不相干的代码上，很心疼呀！

而且，光是等结果就够让人焦虑的了。用传统的代码搜索工具，索引一个仓库可能要几十秒，查一下可能要十几毫秒，对于 Agent 这种需要快速响应的场景来说，这根本就不够用。

直到我发现了 Semble，这个由 MinishLab 团队开发的面向 Agent 的代码搜索工具，简直就是为了解决这个问题而生的。

它让 Agent 用自然语言就能直接定位到最相关的几行代码，不用瞎猜关键词，不用读整个项目文件，而且速度快得离谱。

项目简介

Semble 是一个专为 Agent 打造的代码搜索库。

它的核心理念很简单：让 Agent 能快速、精准地找到它需要的代码片段，而不必浪费大量 Token 在不相干的内容上。

这个项目来自 MinishLab，也就是之前开发 Model2Vec 的那个团队。他们在快速检索领域已经有很深的积累，这次把同样的思路应用到了代码搜索上。

简单来说，Semble 解决了三大问题：

1. 1. 精准性问题：不用瞎猜关键词，用自然语言就能找到准确的代码
2. 2. Token 效率问题：只返回相关的代码块，节省 98% 的 Token
3. 3. 速度问题：索引快（~250ms）、查询快（~1.5ms），毫秒级响应

核心亮点

① 🚀 快到离谱的速度

Semble 的性能数据真是让人眼前一亮：

• • 索引一个普通仓库仅需约 250 毫秒
• • 回答查询仅需约 1.5 毫秒
• • NDCG@10 达到 0.854

Semble 达到了 CodeRankEmbed Hybrid 99% 的性能，但索引快了 218 倍，查询快了 11 倍！

而且这一切都是在 CPU 上运行的，不需要 GPU，不需要 API 密钥，也不需要外部服务。

② 💎 节省 98% Token 的魔法

在 Token 效率方面，Semble 的表现更是惊艳：

• • Semble 用 2k Token 就能达到 94% 的召回率
• • grep+read 需要塞满 100k Token 窗口才到 85%

传统的 grep+read 方式会把整文件都读进来，而 Semble 只返回真正相关的代码块。这对于 Agent 来说太重要了，毕竟 Token 就是钱，省下来的都是真金白银。

③ 🧠 智能分块，从不腰斩代码

Semble 的分块策略非常聪明，它不是按行数机械切割，而是用 Chonkie 按代码结构智能切分。

每个块都是有意义的代码单元——可能是一个函数、一个类、或者一个独立的逻辑块——绝对不会把一个函数拦腰斩断。

这样做的好处是，搜索返回的结果本身就是语义完整的，Agent 拿到就能用，不需要再去上下文中找缺失的部分。

④ 语义+词法，双路检索

Semble 用了两路检索系统：

• • 语义路：用 Model2Vec 和 potion-code-16M 模型生成静态嵌入，捕捉语义相似性
• • 词法路：用 BM25 做标识符和 API 名称的词法匹配

然后用 Reciprocal Rank Fusion (RRF) 把两路的结果融合在一起，取长补短。

⑤ 🎯 代码感知重排序，把最好的推到最前面

初步结果出来后，Semble 还会用一系列代码特有的信号来微调排名：

• • 自适应加权：符号类查询（如 Foo::bar、getUserById）会给词法匹配更多权重，自然语言查询则保持平衡
• • 定义优先：定义了查询符号的块（如 class、def）会排在仅引用它的块前面
• • 标识符词干匹配：查询词会被词干化，然后和代码块中的标识符词干匹配。比如查 parse config 会提升包含 parseConfig、ConfigParser、config_parser 的块
• • 文件连贯性：如果同一个文件有多个块匹配，整个文件会被提升，让最相关的文件排在前面
• • 噪声惩罚：测试文件、兼容层代码、示例代码、声明文件会被降权，让真正的实现代码浮上来

快速上手

安装非常简单，用 pip 或 uv 都可以：

pip install semble
# 或者
uv add semble

索引一个本地目录

from semble import SembleIndex

# 索引本地项目
index = SembleIndex.from_path("./my-project")

索引一个远程 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, ..."

CLI 使用

Semble 也提供了命令行接口，方便在脚本或终端中使用：

# 搜索本地仓库
semble search "authentication flow" ./my-project

# 搜索符号或标识符
semble search "save_pretrained" ./my-project

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

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

如果 semble 不在 PATH 中，可以用 uvx --from "semble[mcp]" semble 代替。

让你的 Agent 瞬间拥有代码搜索能力

Semble 最强大的地方之一是它可以作为 MCP 服务器运行。这样一来，任何支持 MCP 的 Agent（Claude Code、Cursor、Codex、OpenCode 等）都能直接用它搜索代码库，仓库会按需克隆和索引，索引会在会话期间缓存。

集成到 Claude Code

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

集成到 Codex

在 ~/.codex/config.toml 中添加：

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

集成到 OpenCode

在 ~/.opencode/config.json 中添加：

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

集成到 Cursor

在 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）中添加：

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

子 Agent 支持

Claude Code 和 Codex CLI 会懒加载 MCP 工具 schema，所以子 Agent 不能直接调用 mcp__semble__search。解决办法是通过 Bash 调用 Semble 的 CLI。

对于 Claude Code，在项目根目录运行一次：

semble init
# 或者，如果 semble 不在 PATH 中：
uvx --from "semble[mcp]" semble init

这会创建 .claude/agents/semble-search.md。

对于其他工具（Codex 等），把下面内容追加到你的 AGENTS.md：

## Code Search

用 `semble search` 来通过描述功能或命名符号/标识符来查找代码，而不是用 grep：

```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10

用 semble find-related 来发现与已知位置相似的代码（从之前的搜索结果传入 file_path 和 line）：

semble find-related src/auth.py 42 ./my-project

path 省略时默认为当前目录；也接受 git URL。

如果 semble 不在 $PATH 中，用 uvx --from "semble[mcp]" semble 代替。

写在最后

Semble 代表了 Agent 代码搜索的一个新方向。

它证明了我们不需要庞大的 transformer 模型也能获得高质量的代码搜索结果，而且速度更快、Token 效率更高、部署更简单。

对于任何想把 Agent 集成到代码工作流中的团队来说，Semble 都是一个值得关注的工具。它能让你的 Agent 更快、更准、更省 Token 地找到需要的代码。

GitHub：https://github.com/MinishLab/semble