Semble 上手：给 Coding Agent 一套省 token 的代码搜索层

Coding Agent 最浪费 token 的地方，往往是“找代码”

一个 Agent 改代码，最先做的通常不是写，而是找：登录逻辑在哪、配置怎么读、某个函数谁调用、测试入口是哪一个。很多工具默认做法是 grep、read、再 grep、再 read。仓库小还行，仓库一大，token 就开始哗哗流。

Semble 的切口很清楚：给 Agent 一套专门的代码搜索层，让它先拿到相关代码片段，而不是把大量文件读进上下文里硬筛。

它不是 IDE 搜索的替代品，也不是给人用的花哨搜索框。它是给 Agent 用的：返回短、准、带文件路径和行号的 chunk，让下一步读文件和修改更省。

先用 Python API 跑一遍

安装很轻：

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
result.chunk.start_line
result.chunk.end_line
result.chunk.content

这套接口适合你在自己的工具里嵌入 Semble。比如内部 Agent 平台、代码审查机器人、文档生成器，都可以先用 Semble 定位候选代码，再决定是否读取完整文件。

更适合 Agent 的接法：MCP Server

Semble 可以作为 MCP server 接进 Claude Code、Codex、OpenCode、Cursor。这样 Agent 不需要你写中间层，直接调用 search 和 find_related。

Claude Code：

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

Codex：

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

OpenCode：

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

Cursor：

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

这类工具最大的好处，是把“查代码”变成 Agent 可重复调用的能力，而不是每次都靠模型临场选择 grep 参数。

子 Agent 场景里，CLI 反而更稳

README 里有个很实际的提醒：Claude Code 和 Codex CLI 会 lazy-load MCP tool schema，某些 sub-agent 可能不能直接调用 mcp__semble__search。这时更稳的办法，是让子 Agent 通过 CLI 调用 Semble。

Claude Code 可以先初始化：

semble init
# 或者
uvx --from "semble[mcp]" semble init

其他工具可以把下面这段写进 AGENTS.md：

## Code Search

Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep.

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

Use `semble find-related` to discover code similar to a known location:
semble find-related src/auth.py 42 ./my-project

注意这段里有个关键约束：用 Semble 开局，只有当返回 chunk 不够时再读完整文件。 这才是省 token 的核心，而不是装个工具就自动省。

CLI 用法：本地和远程仓库都能搜

单独跑也很方便：

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

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

# 搜远程仓库，按需 clone 和索引
semble search "save model to disk" https://github.com/MinishLab/model2vec

# 从已知位置找类似代码
semble find-related src/auth.py 42 ./my-project

建议把它当成 Agent 的第一步，而不是最后补救。任务开始时先搜一轮，读最相关的 2 到 3 段代码，能少掉很多盲读文件。

它为什么能快

Semble 不是简单 keyword search。它会先把文件切成 code-aware chunks，然后用两类检索器一起打分：

静态 Model2Vec embedding，偏语义相似；
BM25，偏 identifier、API 名、精确词匹配。

两路结果用 Reciprocal Rank Fusion 合并，再叠加一些代码感知信号：

symbol-like query 提高 lexical 权重；
定义位置比引用位置更靠前；
identifier stem 能匹配 parseConfig、config_parser 这类变体；
同一文件多个 chunk 命中时，提升文件级相关性；
test、legacy、compat、example、.d.ts 等噪声会降权。

关键是它用的是静态 embedding，没有 transformer query-time forward pass，所以可以在 CPU 上毫秒级跑。项目给出的 benchmark 里，Semble 在 63 个仓库、19 种语言、约 1250 个 query 上，冷启动 index + query 的速度很猛，质量接近更重的 code-specialized transformer。

用的时候别完全替代 grep

Semble 很适合“我想找做某件事的代码”。但 grep 仍然有位置：

找精确字符串：grep / ripgrep
找某类实现：semble search
找相似实现：semble find-related
确认全量替换风险：grep / ripgrep
让 Agent 少读上下文：Semble 开局

不要把所有搜索都变成语义搜索。精确匹配、全局替换、许可证文本、错误码、配置键，传统 grep 依然更稳。

最适合的工作流

给 Coding Agent 加 Semble 后，推荐这样写项目规矩：

1. 新任务先用 semble search 找候选文件
2. 只读取 top 结果相关文件
3. 需要扩散时再用 find-related
4. 只有确认 exact string 时才用 grep
5. 修改前输出 file_path/start_line/end_line 作为证据

这套流程能把 Agent 从“全仓库乱翻”拉回到“先定位、再读取、再修改”。对大仓库尤其明显。

最后看法

Semble 这类工具会越来越重要。模型上下文再大，也不应该把大仓库当垃圾桶往里倒。真正靠谱的 Coding Agent，需要一套能省 token、低延迟、可解释的代码定位层。

它不替你写代码，但能让 Agent 少看废话。很多时候，少看废话就是少犯错。