| name | semble-code-search |
| description | 本地语义代码搜索。当需要按意图定位代码、查找实现、理解代码结构时使用，优先于 grep/read 用于探索性搜索。触发词："搜代码"、"code search"、"find implementation"、"理解代码实现"、"semble"、"语义搜索"、"search code"。 |
Semble Code Search
本地语义代码搜索引擎，纯 CPU 运行，零外部依赖。首次索引约 100-250ms（小仓库），查询约 1-2ms。比 grep+read 节省约 98% token。
搜索
用自然语言或标识符搜索代码：
semble search "authentication flow" ./project-path
semble search "save_pretrained" ./project-path
semble search "how does error handling work" ./project-path --top-k 10
查找相关代码
基于已知位置查找语义相关的代码（file_path 和 line 来自搜索结果）：
semble find-related src/auth.py 42 ./project-path
工作流
- 先用
semble search 找到相关代码片段
- 只有在返回的片段不够时，才用 Read 读完整文件
- 用
semble find-related 探索相关实现
- 只有需要精确字符串匹配或穷举时才用 grep
参数
path：本地目录路径或 git URL，默认当前目录--top-k / -k：返回结果数量，默认 5--include-text-files：同时索引 .md/.yaml/.json 等文本文件（注意：对含大 JSON 的仓库会导致索引时间暴增到十几秒，慎用）
性能特征
- 默认只索引代码文件（约 280 种扩展名），跳过 >1MB 的文件
- 自动尊重 .gitignore 和 .sembleignore
- 自动跳过 .git/、node_modules/、pycache/、dist/、build/ 等目录
- 对大仓库（上千文件），索引约 2-10 秒；可搜索子目录替代根目录加速
- 如果 semble 不在 PATH，用
uvx --from "semble[mcp]" semble 替代
适用场景
- 理解不熟悉的代码库结构
- 按意图定位实现（"哪里处理了用户认证"）
- 查找某个概念的多个实现位置
- 探索相关代码的调用关系
不适用场景
- 需要精确字符串匹配 → 用 grep
- 需要穷举所有匹配 → 用 grep
- 只需看一两个已知文件 → 用 Read
