当下，Agent 正在越来越多地介入代码工作流。从代码补全到代码审查，从重构建议到自动生成测试，AI 已经成了很多开发者的得力助手。

但深度使用时会遇到一个问题：当 Agent 需要在一个大型代码库中找东西时，它要么瞎猜关键词，要么就得把整个项目内的文件都读一遍。结果就是要么找不到，要么 Token 像流水一样哗哗地流。一个 100k Token 的上下文窗口，一大半都浪费在不相干的代码上。

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

直到 Semble——这个由 MinishLab 团队开发的面向 Agent 的代码搜索工具，2.9K Star，让 Agent 用自然语言就能直接定位到最相关的几行代码，不用瞎猜关键词，不用读整个项目文件，速度快得离谱。

项目简介

Semble 是一个专为 Agent 打造的代码搜索库，来自 MinishLab（开发 Model2Vec 的团队）。核心理念很简单：让 Agent 能快速、精准地找到它需要的代码片段，而不必浪费大量 Token 在不相干的内容上。

Semble 解决了三大问题：

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

核心亮点

1. 快到离谱的速度

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

Semble 达到了 CodeRankEmbed Hybrid 99% 的性能，但索引快了 218 倍，查询快了 11 倍。而且这一切都是在 CPU 上运行的，不需要 GPU、API 密钥或外部服务。

2. 节省 98% Token

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

传统 grep+read 方式会把整文件都读进来，Semble 只返回真正相关的代码块。省下来的 Token 都是真金白银。

3. 智能分块，从不腰斩代码

Semble 用 Chonkie 按代码结构智能切分，每个块都是有意义的代码单元——一个函数、一个类、或者一个独立的逻辑块，绝对不会把一个函数拦腰斩断。搜索返回的结果本身就是语义完整的，Agent 拿到就能用。

4. 语义+词法，双路检索

• 语义路：用 Model2Vec 和 potion-code-16M 模型生成静态嵌入，捕捉语义相似性
• 词法路：用 BM25 做标识符和 API 名称的词法匹配
• 用 Reciprocal Rank Fusion (RRF) 把两路结果融合，取长补短

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

• 自适应加权：符号类查询给词法匹配更多权重，自然语言查询保持平衡
• 定义优先：定义了查询符号的块排在仅引用它的块前面
• 标识符词干匹配：查 parse config 会提升包含 parseConfig、ConfigParser 的块
• 文件连贯性：同一文件多个块匹配时，整个文件被提升
• 噪声惩罚：测试文件、兼容层代码、声明文件被降权

快速上手

安装：

pip install semble
# 或
uv add semble

索引本地项目：

from semble import SembleIndex

index = SembleIndex.from_path("./my-project")

索引远程仓库：

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 search "authentication flow" ./my-project

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

# 搜索远程仓库
semble search "save model to disk" https://github.com/MinishLab/model2vec

MCP 集成

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"]

Cursor（~/.cursor/mcp.json）：

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

写在最后

Semble 代表了 Agent 代码搜索的一个新方向。它证明了我们不需要庞大的 transformer 模型也能获得高质量的代码搜索结果——速度更快、Token 效率更高、部署更简单。对于任何想把 Agent 集成到代码工作流中的团队来说，Semble 都是一个值得关注的工具。

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