Semble 中文教程：给编码 Agent 加本地语义搜索
Semble 用静态嵌入在本机索引代码，让 Agent 用“认证流程在哪里”这类自然语言找到相关片段。它可以作为 CLI 使用，也能给支持 MCP 的编码 Agent 安装工具、指令或专用搜索子代理。
uv tool install semble，旧版 uvx --from "semble[mcp]" 不再是首选入门流程。1. 安装并让 Semble 识别 Agent
uv tool install semble semble install
交互式安装器会检测 Claude Code、Codex、OpenCode 等环境，并让你选择 MCP、instructions 或 subagent。团队环境不要直接写全局配置；先检查安装器准备修改哪些文件。脚本化安装可显式指定目标：
semble install --agent codex --type mcp instructions --yes
2. 先从熟悉的仓库试搜
semble search "authentication flow" ./my-project semble search "where is cache invalidated" ./my-project semble search "shared protocol" ./api ./worker
第一次查询会建立索引，此后文件变化会使缓存失效。0.6.0 支持一次搜索多个仓库，适合前后端或协议仓库分开的项目。传入 Git URL 时会按需克隆，私有仓库的凭据和落盘目录要按团队规范管理。
3. 看懂官方 benchmark 的边界
README 报告平均仓库约 500 ms 建索引、约 1 ms 查询、NDCG@10 为 0.854，并称比 grep+read 少约 99% token。这些是项目 benchmark 的结果，不等于你的仓库会复现。语言、生成代码、超大文件和查询写法都会影响召回；上线前应准备一组已知答案的真实问题复测。
与 ripgrep 对比
ripgrep 按正则逐行递归搜索，并默认遵守 gitignore，适合已知符号、错误码或固定文本的精确匹配。Semble 根据自然语言返回排序后的相关片段，适合不知道函数名时探索。实际工作中可以先用 Semble 找方向，再用 ripgrep 穷举并确认影响范围。
4. 更新和撤销
uv tool upgrade semble uv cache clean semble semble uninstall
MCP 客户端可能缓存旧进程，升级和清理缓存后需要重启客户端。semble uninstall 用于撤销安装器加入的集成；手工改过的 Agent 配置仍要自行检查。
pyproject.toml 和 v0.6.0 Release；没有安装 uv 或 Semble、下载模型、索引仓库或运行 benchmark。本文不复述旧稿的性能结论为实测结果。这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
采用建议
Semble 适合给编码 Agent 增加轻量的本地语义检索。先在一个熟悉的仓库比较召回结果与耗时，再决定是否写入全局 Agent 配置；需要精确穷举时保留 ripgrep。
原教程未展开的系统信息
核心功能
自然语言代码检索
首次查询时建立本地索引，返回带文件位置的相关片段，并在文件变化后使缓存失效。
本地与多仓库搜索
查询可指向本地路径或 Git URL；0.6.0 新增一次搜索多个仓库的支持。
架构与数据流
Python 包把代码切片后交给 model2vec 静态嵌入，在本机 CPU 上建立和查询索引；CLI 负责 search/install/uninstall 等入口，MCP 适配层把检索暴露给支持该协议的 Agent。无需远程向量数据库或 API key。
技术栈和运行条件
语言
Python 3.10+
框架
CLI + MCP server
关键依赖
- model2vec >=0.4,<0.10
- numpy
- watchfiles
- GitPython
运行环境
uv；本机 CPU；无需 GPU、API key 或外部检索服务
常见问题
Semble 0.6.0 需要什么 Python 版本？
官方 pyproject.toml 要求 Python 3.10 或更高版本，当前 README 推荐通过 uv 安装。
Semble 会把代码发送到外部服务吗？
官方说明索引和检索在本机 CPU 上完成，不需要 API key、GPU 或外部服务；远程 Git URL 仍会按需克隆仓库。
Semble 能完全替代 ripgrep 吗？
不能。Semble 适合按语义找相关片段；需要完整枚举精确字符串或正则命中时，ripgrep 更合适。
更新 Semble 后为什么 MCP 还在用旧版本？
官方更新说明建议执行 uv tool upgrade semble，清理 semble 的 uv 缓存，然后重启 MCP 客户端。