🔍 Semble：2.3k Stars 的 Agent 代码检索引擎，比 grep+read 省 98% 的 Token
项目地址：https://github.com/MinishLab/semble | ⭐ 2,273 | 🛠 Python | MinishLab
老实说，让 AI Agent 在大型代码库里找东西是个老大难。grep 只能搜字符串，根本理解不了"authentication flow"这种自然语言查询。让 Agent 把整个文件读一遍？一个 500 行的 Python 文件就烧掉几千 token，项目一大了钱包受不了。
Semble 就是冲着这个问题来的。它是个专为 AI Agent 设计的代码搜索引擎——用自然语言描述你想要的功能，它直接给你返回相关的代码片段，不走弯路。比 grep+read 省 98% 的 token，索引一个仓库平均 250ms，查询 1.5ms，全部在 CPU 上跑。
最骚的操作是：它不需要 GPU、不需要 API key、不需要装任何外部服务。一个 pip install 就完事。
一、MCP 集成：一行命令让你的 Agent 装上代码搜索超能力
Semble 提供 MCP Server，直接对接 Claude Code、Codex、Cursor、OpenCode 等主流编码 Agent。
# 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"]
装完之后，Agent 就能直接用自然语言搜你的代码库了。你可以直接问"帮我找到认证相关的代码"，它就会返回精确的代码片段，不用自己手动 grep。
二、CLI 命令：不用 MCP 一样好用
不想配 MCP？直接用命令行也一样爽：
pip install 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 savings 命令可以查看替你省了多少 token：
semble savings --verbose
输出长这样：
Semble Token Savings
════════════════════
Period Calls Savings
Today 42 58.4k tokens (95%)
All time 1.4k 1.2M tokens (89%)
看了这个数字你就知道这玩意儿到底省了多少。
三、AGENTS.md 集成：子 Agent 也能用
Claude Code 的子 Agent 不能直接调 MCP，但可以通过 AGENTS.md 搞。在项目的 AGENTS.md 或 CLAUDE.md 里加上这段：
## Code Search
Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
Use semble find-related to discover code similar to a known location:
semble find-related src/auth.py 42 ./my-project
```
然后在项目根目录跑一次 semble init，子 Agent 就也能搜代码了。
四、原理浅析：为什么这么快？
Semble 用 tree-sitter 把代码拆成语义块，然后用两个互补的检索引擎打分：一个是用模型专门搞语义匹配（potion-code-16M 嵌入模型），一个是 BM25 搞标识符/API 名的精确匹配。两个分数用 RRF 融合后，再加一堆代码特有的排位信号：
- 自适应加权：符号查询（
Foo::bar）加重词法权重，自然语言查询保持均衡 - 定义提升：定义某个符号的代码块排在使用/引用的前面
- 文件连贯性：同一个文件的多个匹配块整体提升
- 噪声惩罚：测试文件、compat/legacy 目录、示例代码自动降权
所有操作在 CPU 上毫秒级完成，不需要跑 GPU 推理。论质量，NDCG@10 达到 0.854，接近 137M 参数的 CodeRankEmbed 模型，但索引速度快了 218 倍。
五、踩坑记录
搭 MCP 的时候有个坑：如果你用 uv tool install semble 之后装 MCP server，需要 uv cache clean semble 再重启 MCP client，不然可能版本对不上。别问我怎么知道的。
另外 semble search 支持 git URL 直接搜远程仓库，它会自动 clone 然后索引。但首次 clone 大项目会慢一些，好在索引是一次性的，之后从缓存走。
要点总结：
- Semble 是专为 AI Agent 设计的代码搜索引擎，自然语言查询直接返回相关代码片段
- 比 grep+read 省 98% token，索引 250ms，查询 1.5ms，全 CPU 运行
- MCP Server 一行命令接入 Claude Code / Codex / Cursor，AGENTS.md 让子 Agent 也能用
- 底层用 tree-sitter + Model2Vec + BM25 双引擎 + 代码语义排位信号
- pip install semble 就完事，不需要 GPU、API key 或外部服务
标签：#CodeSearch #MCP #AI #Agent #DeveloperTools