semble-code-search

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

工作流

1. 先用 semble search 找到相关代码片段
2. 只有在返回的片段不够时，才用 Read 读完整文件
3. 用 semble find-related 探索相关实现
4. 只有需要精确字符串匹配或穷举时才用 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