MinishLab/semble · 上手攻略

• 仓库：MinishLab/semble
• 链接：https://github.com/MinishLab/semble
• 分类：ai · code-search · developer-tools
• 作者：Jay
• 更新：2026-07-14

这是什么

Semble 是一个专为 AI Coding Agent 打造的代码搜索库，核心理念是：让 Agent 用自然语言提问，直接返回最相关的代码片段，全程不需要读取完整文件、不需要 grep，用比 grep+read 少约 98% 的 token 完成精准代码检索。

它本质上是一个本地代码语义索引工具：给 Semble 一个代码仓库，它会建立语义索引；Agent 问"How is authentication handled?"，Semble 返回相关代码片段，节省大量上下文窗口。索引速度比基于 Transformer 的专用代码搜索引擎快约 200 倍，查询速度约快 10 倍，且完全跑在 CPU 上，不需要 GPU、不需要 API Key、不需要外部服务。

解决什么问题

• Coding Agent 的上下文窗口浪费：传统让 Agent 用 grep 或直接读文件找代码，会消耗大量 token；Semble 只返回最相关的片段
• Agent 不熟悉大型代码库：Agent 可以用自然语言问任何问题，Semble 负责找到最相关的代码段
• 需要一个统一工具接口：不管用的是 Claude Code、Cursor、Codex 还是 OpenCode，Semble 都通过 MCP 协议统一接入

快速安装

环境要求

• Python 3.10+
• uv（必须，核心依赖管理工具）

安装 Semble CLI

uv tool install semble

交互式配置 Agent 集成

semble install

semble install 会自动检测你系统上安装了哪些 Coding Agent（Claude Code、Codex、Cursor、OpenCode 等），然后让你选择启用哪些集成：

• MCP server：将 Semble 作为 MCP 工具暴露给 Agent 直接调用
• Instructions：在 AGENTS.md / CLAUDE.md 里写入 Semble 使用说明
• Sub-agent：安装一个专用的 semble-search 子 Agent

非交互式（自动化 / CI 场景）

semble install --agent claude pi --type mcp subagent --yes

参数说明： - --agent：指定 agent id（支持 claude、codex、pi、opencode、cursor 等） - --type：集成方式 mcp / instructions / subagent / all - --yes：跳过确认提示

卸载

semble uninstall

核心用法

作为 CLI 使用

# 搜索本地仓库（首次自动建立索引）
semble search "authentication flow" ./my-project

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

# 限制返回结果数
semble search "API endpoints" ./my-project --top-k 10

# 搜索文档而非代码
semble search "deployment guide" ./my-project --content docs

# 搜索配置而非代码
semble search "CORS settings" ./my-project --content config

# 搜索全部内容
semble search "logging setup" ./my-project --content all

# 查找与某文件某行相关的代码
semble find-related src/auth.py 42 ./my-project

# 查看 token 节省统计
semble savings

--content 可选值：code（默认）、docs、config、all。

作为 Python 库使用

from semble import ContentType, SembleIndex

# 建立代码索引（默认只索引代码）
index = SembleIndex.from_path("./my-project")

# 同时索引文档（Markdown、RST 等）
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# 索引所有内容（代码 + 文档 + 配置）
index = SembleIndex.from_path(
    "./my-project",
    content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG]
)

# 从远程 Git 仓库建立索引
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# 自然语言搜索
results = index.search("save model to disk", top_k=3)

for r in results:
    print(r.chunk)        # 代码片段
    print(r.file_path)    # 文件路径
    print(r.score)        # 相关性分数

# 找相关代码
related = index.find_related("src/auth.py", 42)

MCP Server 使用（推荐给 Agent 用）

semble 会作为 MCP server 运行，Agent 可以直接调用 semble_search 和 semble_find_related 工具。Claude Code 示例：

# 自动配置方式
semble install --agent claude --type mcp --yes

Agent 调用时 Semble 会自动在后台： 1. 检测代码库是否有变更 2. 热更新索引（如有必要） 3. 返回相关代码片段

性能与基准

官方 benchmarks 数据：

Semble 在 99% 检索质量水平下，速度快 200 倍，token 节省 98%。

典型使用场景

场景 1：让 Claude Code / Cursor 更懂你的代码库

安装 Semble MCP 后，Agent 可以直接问"How does the payment flow work?"，无需你手动告诉它要读哪个文件。

semble install --agent claude --type mcp --yes
# 然后在 Claude Code 里直接问自然语言问题

场景 2：大型遗留代码库探索

面对没有文档的遗留代码库，让 Semble 帮你找到"哪段代码处理用户认证过期"：

semble search "session expiry handling" ./legacy-app

场景 3：跨仓库代码搜索

不问具体文件路径，直接搜索多个远程仓库：

semble search "rate limiting implementation" \
  https://github.com/your-org/api-gateway \
  --content all

场景 4：集成到 CI/CD 或脚本

在脚本中调用 Semble 做自动化代码分析：

from semble import SembleIndex

index = SembleIndex.from_path("./src")
results = index.search("security vulnerabilities")
if results:
    print("发现安全问题！")

坑与注意

⚠️ uv 是必装依赖

Semble 依赖 uv 作为包管理工具，没有 uv 无法安装。如果你的环境没有 uv，先装：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或用 pip
pip install uv

⚠️ MCP 模式下记得重启 MCP Client

安装 MCP server 后，需要重启你的 Agent 的 MCP 客户端才能加载 Semble 工具（Claude Code / Cursor 等需要刷新）。

⚠️ 索引首次建立需要时间

超大型仓库（>10万文件）首次建立索引可能需要数秒到数十秒，但后续查询极快（约1.5ms）。索引会自动缓存，文件变化后增量更新。

⚠️ .sembleignore 规则

Semble 读取 .gitignore 和 .sembleignore，但默认跳过常见非源码目录（node_modules、.venv、dist 等）。自定义排除规则需要编辑 .sembleignore（语法同 .gitignore）。

⚠️ Savings 统计仅限本地

semble savings 只统计本机使用量，不会云端同步。换了机器就重置。

⚠️ 不支持 Windows（直接安装）

semble 官方推荐 Linux/macOS，Windows 用户需要用 WSL2 或 WSL 环境运行。

⚠️ 某些 Agent 需额外配置

Pi（Replit Agent）需要先安装 Pi MCP extension：

pi install npm:pi-mcp-extension
semble install --agent pi --type mcp --yes

与同类对比

Semble 的核心差异化：精准检索 + 极致 token 效率 + 开箱即用的 MCP 集成，是专门为 AI Agent 设计的代码搜索工具，而非通用代码搜索引擎。

一句话推荐

如果你在用 Claude Code、Cursor 等 Coding Agent 写代码，装上 Semble 后 Agent 可以用自然语言精准找到需要的代码片段，节省约 98% 的上下文 token——这是一次性投入（semble install），长期高回报的操作。