TreeSearch 代码库与文档树检索

先说清楚它解决的问题

当代码库或文档集长到几十个仓库、几千个文件时，常见的检索方案基本是两条路：要么上向量检索，要么继续用 grep。向量方案要先接嵌入模型、准备向量库，还要把文档切成 chunk，切得不好检索结果会飘到别的章节；grep 虽然简单，但它对文档结构完全没有感知，匹配到一行就返回一行，你很难从结果里看出来这一行属于哪个目录、哪个文件、哪个标题层级。

TreeSearch 针对的就是这个中间地带：文档本身是有结构的——目录、文件、Markdown 的标题层级、代码文件的组织方式都是现成的信息，却很少有检索工具真正利用它们。

它是怎么工作的

TreeSearch 是一个结构感知的文档检索库，核心机制可以概括为三点：

• 不生成嵌入向量。没有 embedding 模型，也就没有向量库的存储和检索开销，也没有 chunk 切分带来的上下文割裂。
• 基于 SQLite FTS5 的关键词匹配。索引落到本地 SQLite，查询时用全文检索能力做匹配，结果可解释、可回溯。
• 保留文档树结构。检索命中之后，结果会带上它在文档树中的位置信息，你能知道命中内容属于哪棵树、哪个分支，而不是一堆扁平的文本片段。

它支持 Markdown、纯文本和代码文件的索引。在 Python 里拿到结果的方式也很直接：from treesearch import TreeSearch，把文档树交给它，剩下的索引和查询都由库来处理。

适用边界

需要注意几点：

• 适合明确的关键词查询。你知道要找的函数名、类名、标题词或配置项，这种查询它响应很快，也足够准。
• 不适合语义泛化。查询“怎么处理错误”这类意图型问题，关键词匹配的召回就比较有限，这种场景仍然需要嵌入模型。
• 不做代码语义分析。它是文本检索工具，不理解调用关系、类型推断或跨文件的重构意图。
• 首次索引有成本。语料规模很大时，建索引本身需要时间，之后才能享受本地 SQLite 的查询速度。