Semble 实战指南：用语义代码搜索让 AI 编程 Agent 节省 98% Token

在 AI 辅助编码的日常中，一个常见的痛点是：Agent 为了理解代码库，会反复用 grep 搜索 + 逐个阅读完整文件，消耗大量 Token 和上下文窗口。Semble 的出现解决了这个问题——它是一个专为 AI Agent 设计的代码搜索库，返回精确的代码片段而非整文件，比 grep+read 节省约 98% 的 Token。

这篇文章将带你完成从安装到深度集成的完整流程，包括 MCP Server、AGENTS.md 配置、子 Agent 独立搜索，以及 CLI 脚本集成。

安装

Semble 基于纯 CPU 运行，无需 GPU 或 API Key。推荐用 uv 安装：

uv tool install semble

或者用 pip：

pip install semble

如果你要用 MCP Server 模式，安装时带上 MCP 依赖：

uv tool install "semble[mcp]"

安装后验证：

semble search "hello world" .

如果输出正常，说明安装成功。

方式一：MCP Server（推荐）

MCP（Model Context Protocol）是目前 AI Agent 集成工具的标准方式。Semble 以 MCP Server 形式暴露两个工具：

• search：自然语言或代码查询源码
• find_related：根据文件路径和行号查找相似代码

在 Claude Code 中集成

一条命令搞定：

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

想同时搜索文档和配置文件？追加 --content all：

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

在 Cursor 中集成

编辑 ~/.cursor/mcp.json，添加：

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

在 Codex / OpenCode 中集成

Codex：编辑 ~/.codex/config.toml：

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

OpenCode：编辑 ~/.opencode/config.json：

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

在 Zed 中集成

编辑 ~/.config/zed/settings.json：

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

方式二：AGENTS.md / CLAUDE.md 集成

如果不使用 MCP，也可以通过 AGENTS.md 让 Agent 调用 Semble CLI。将以下内容加入项目根目录的 AGENTS.md 或 CLAUDE.md：

## Code Search

Use `semble search` to find code by describing what it does:

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

For repeated searches, pre-index the repo：

semble index ./my-project -o my_index
semble search "authentication" --index my_index

Search docs or config separately：

semble search "deployment guide" ./my-project --content docs
semble search "database host port" ./my-project --content config

Use semble find-related to discover code similar to a known location：

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

Workflow：

1. Index the repo with semble index -o cached_index
2. Search with semble search to find relevant chunks
3. Use --content docs/config/all to broaden search scope
4. Use semble find-related to discover related implementations
5. 只用 grep 做精确文字匹配

## 方式三：子 Agent 独立搜索

对于支持子 Agent 的工具，Semble 提供了独立搜索进程的能力。在项目根目录运行：

```bash
# Claude Code
semble init

# Gemini CLI
semble init --agent gemini

# Cursor
semble init --agent cursor

# OpenCode
semble init --agent opencode

# GitHub Copilot CLI
semble init --agent copilot

这会生成一个专用的 semble-search 子 Agent，搜索任务在独立上下文中执行，不占用主 Agent 的 Token 窗口。

CLI 实用技巧

几个日常高频用法：

# 搜索本地仓库
semble search "error handling pattern" .

# 搜索远程仓库（自动克隆+索引）
semble search "database connection" https://github.com/user/repo

# 先索引再搜索（多次查询时更快）
semble index . -o .semble-index
semble search "user login" --index .semble-index

# 查看 Token 节省统计
semble savings

# 查看详细统计
semble savings --verbose

--savings 功能特别实用，它会统计每次搜索节省的字符数，换算成 Token 并展示按天/周/全部的汇总。统计存于 ~/.semble/savings.jsonl。

Token 节省效果到底多明显？

根据官方基准测试，Semble 在 63 个仓库、19 种编程语言的约 1250 条查询上做了评测：

• 仅用 2k Token 就达到 94% 召回率
• 而 grep+read 需要 100k Token 才能达到 85% 召回率
• 平均节省 98% Token

在质量方面，Semble 的 NDCG@10 为 0.854，达到专用代码嵌入模型（CodeRankEmbed Hybrid）的 99%，但索引速度 快 218 倍，检索速度 快 10 倍。

工作原理简述

Semble 的搜索流程分为三步：

1. 代码感知分块：用 tree-sitter 解析代码的 AST（抽象语法树），按函数、类等逻辑单元切分，而非按行数硬切
2. 双通道检索：语义通道使用轻量级模型 potion-code-16M 生成嵌入向量，配合 BM25 做标识符匹配，然后用 Reciprocal Rank Fusion 融合两个排序
3. 代码感知重排：根据是否包含定义、标识符词干匹配、文件内聚性、测试文件降权等信号做二次排序

整个过程在 CPU 上只需 几毫秒，无需 GPU 或外部 API。

最佳实践

1. 先索引，后搜索：如果同一次会话中需要多次搜索，先用 semble index 创建索引文件，后续搜索直接传入 --index，速度更快。

2. 按内容类型搜索：不要只搜代码，用 --content docs 搜文档， --content config 搜配置， --content all 搜索所有内容。匹配度更高。

3. 把 Semble 放在主 Agent 外：优先使用子 Agent 模式（semble init）或 MCP Server，把搜索任务隔离到独立上下文，不占用 Agent 的主体 Token 窗口。

4. 结合 grep 使用：Semble 擅长语义搜索，但精确字符串匹配还是 grep 的长处。把它们组合使用——Semble 找概念相关代码，grep 做精确引用定位。

5. 定期更新：代码库变化后记得重新索引。Semble 在 MCP 模式下会自动监听本地文件变化，但 CLI 索引需要手动更新：

semble index . -o .semble-index  # 更新索引

总结

Semble 解决了一个非常具体却高频的问题：AI Agent 搜索代码时的 Token 浪费。它的安装和集成流程简洁直观，支持 MCP、AGENTS.md、子 Agent 三种集成方式，覆盖 Claude Code、Cursor、Codex、OpenCode 等主流工具。无论你是个人开发者还是团队协作，将 Semble 配入 AI 编码工作流，都能获得立竿见影的 Token 节省效果。