SeaGOAT

SeaGOAT — 给代码装上「语义搜索引擎」，用自然语言在本地代码库里找答案

图1：SeaGOAT 项目标志

场景切入：为什么你需要 SeaGOAT？

想象一个常见的工作场景：你接手了一个陌生的代码库，代码库里有几万行代码，没有任何注释。你记得几个月前有人写过一个「处理税务计算」的函数，但你完全想不起函数名、文件名，甚至不确定用的是 Python 还是 JavaScript。

传统的 grep 只能搜关键词。grep tax_calc 找不到「deal with taxes」；grep calculate 会返回几百个无关结果。你只能一层层翻目录，或者问同事「那个税务的东西在哪」。

SeaGOAT 解决的就是这个问题：它让你用自然语言描述你想要的代码，然后返回一个真实的代码片段。它本质上是一个运行在本地的、基于向量嵌入（Vector Embeddings）的语义代码搜索引擎。

背景：代码搜索的进化史

代码搜索工具经历了三个阶段：

第一阶段：正则表达式搜索（grep、ripgrep） 按字符串匹配工作，输入「calc」就返回包含「calc」的行。优点是精确，缺点是需要你知道关键词。不认识代码、不理解语义。

第二阶段：结构化搜索（SourceGraph） 基于代码的 AST 结构进行搜索，能理解函数调用关系、类型信息。但需要服务器、数据库、云端部署，个人项目用起来成本较高。

第三阶段：语义向量搜索（SeaGOAT） 将代码片段转换为向量嵌入（embedding），在向量空间中找语义最接近的片段。「处理税务」和「calculate taxes」在向量空间中距离很近，因此能跨语言、跨命名风格匹配。

SeaGOAT 的作者 Daniel Kantor 从 2023 年 6 月开始开发这个项目，目标是为个人开发者和小团队提供一个无需云端、零依赖的本地语义搜索方案。2023 年该项目参加了 Hacktoberfest 开源活动，获得了大量社区贡献。

核心技术原理

SeaGOAT 的工作流程分为索引构建和语义查询两个阶段：

索引构建阶段

1. 文件解析：通过 seagoat/repository.py 遍历 Git 仓库的所有文件，使用 gitpython 库获取 Git 历史信息
2. 文件过滤：seagoat/utils/file_types.py 判断文件类型，过滤二进制文件和大文件（>200KB）
3. 分块（Chunking）：将代码文件按语义边界拆分成块（chunk），每块约 100 行代码
4. 向量嵌入：每个 chunk 通过 ChromaDB 的嵌入函数转换为向量，存储在本地 ChromaDB 实例中
5. 全文缓存：同时用 ripgrep 构建内存映射（mmap）缓存，支持正则表达式精确匹配

语义查询阶段

当用户输入自然语言查询（如「Where are the numbers rounded」）时：

1. Query 嵌入：将查询文本同样转换为向量
2. 向量检索：在 ChromaDB 中找向量距离最近的 chunks（距离阈值 < 1.5，见 sources/chroma.py）
3. 混合排序：结合 ripgrep 的正则匹配分数，对结果进行综合排序
4. 结果展示：调用 bat 工具高亮展示匹配行，支持上下文行显示

图2：SeaGOAT 自然语言搜索演示

技术栈解析

SeaGOAT 的技术选型非常务实，完全围绕「本地 + 高效 + 无外部依赖」展开：

组件	技术选型	作用
向量数据库	ChromaDB	本地嵌入式向量数据库，零配置，支持持久化
Git 操作	gitpython	Python 原生 Git 操作库
全文搜索	ripgrep (rg)	最快的正则搜索工具，通过 mmap 缓存加速
Web 服务	Flask + waitress	轻量级 HTTP API 服务，支持并发
嵌入模型	Ollama (本地 LLM)	默认使用 Ollama 本地模型生成向量
结果展示	bat / pygments	语法高亮，支持多种编程语言
CLI 框架	Click	Python 标准 CLI 框架
异步队列	自定义 TaskQueue	并行处理索引和查询任务
MCP 支持	FastMCP	支持 Model Context Protocol，可集成到 AI 编码助手

关键配置：嵌入函数在 .seagoat.yml 中定义，默认使用 Ollama 的 nomic-embed-text 模型。开发者也可以切换到 OpenAI、Azure 等云端嵌入服务。

上手体验：5 分钟跑起来

SeaGOAT 的安装和配置极为简单。

安装依赖

# 核心依赖
pipx install seagoat
# 或 pip install seagoat

# 必需：ripgrep
# 必需：Python 3.10+
# 可选：bat（用于高亮显示，推荐安装）
# 可选：Ollama（用于本地嵌入模型）

启动服务端

seagoat-server start /path/to/your/repo

服务端启动后会在后台运行（通过 waitress 提供 HTTP API），监听默认端口 31134。

执行搜索

# 用 gt 或 seagoat 命令搜索
gt "Where are the numbers rounded"
gt "function calc_.* that deals with taxes"

支持正则表达式，可以将正则和语义搜索结合使用：

图3：SeaGOAT 正则表达式搜索

架构亮点

本地优先（Local-First）

SeaGOAT 最大的特色是完全本地化运行：

• ChromaDB 数据存在项目目录的 .seagoat/ 缓存目录
• 无需互联网连接，不向任何服务器发送代码
• 数据隔离在本地仓库内，换一台机器需要重新索引

这与 SourceGraph 的云端方案形成鲜明对比——SeaGOAT 适合隐私敏感场景和个人开发者，SourceGraph 适合大型团队的集中化管理。

双引擎混合架构

代码中 seagoat/sources/ 目录下维护了两个独立的数据源：

• chroma.py：向量语义搜索，处理自然语言查询
• ripgrep.py：正则表达式全文搜索，处理精确字符串匹配

两个引擎的结果在 engine.py 中合并打分，既能理解语义，又能精确定位。这是一种务实的工程折中——完全依赖向量搜索精度不够，完全依赖正则则失去了语义能力。

缓存层设计

项目使用了多级缓存策略：

• ChromaDB 持久化：索引构建后持久化到磁盘，重启后无需重建
• ripgrep mmap 缓存：将仓库内容预加载到内存映射文件，加速正则搜索
• Git 对象缓存（cache.py）：记录已分析的 commits 和 chunks，增量更新

MCP 集成：让 AI 编码助手更强

SeaGOAT 1.2.0 版本新增了 MCP（Model Context Protocol）服务器支持，通过 seagoat-mcp 命令启动后，可以被主流 AI 编码助手集成：

# MCP 工具定义（mcp_server.py）
@mcp.tool()
def search_code(query, limit, repo_path, context_above, context_below):
    # 调用本地 SeaGOAT 服务获取语义搜索结果
    ...

这意味着：当你用 Cursor、VS Code + Continue 等 AI 编码助手时，可以让 AI 直接调用 SeaGOAT 的搜索能力，在不离开 IDE 的情况下，用自然语言定位代码片段。相比 AI 自己扫描文件，这种方式更快、更准确。

局限与争议

1. 索引体积随代码库增长

ChromaDB 向量索引会随着仓库变大而增长。对于超大型单体仓库（数十万行代码），首次索引时间可能超过 10 分钟。不过增量索引（只分析新增的 commits）已经做了优化。

2. 嵌入质量依赖模型选择

默认使用 Ollama 本地模型（如 nomic-embed-text），嵌入质量不如 OpenAI 的 text-embedding-3-small。切换到云端模型需要额外配置 API Key，失去了本地化的隐私优势。

3. 不支持多仓库联合搜索

SeaGOAT 每次启动只针对一个 Git 仓库索引。如果需要在多个仓库间搜索，需要分别启动多个服务端实例，无法像 SourceGraph 那样建立跨仓库索引。

4. 没有 Web UI

目前只有 CLI 和 HTTP API，没有图形界面。对于非技术用户不够友好。

行业意义：向量搜索平民化

SeaGOAT 代表了一个重要趋势：将过去只有云端 AI 服务才有的向量搜索能力，下沉到本地工具链。

在此之前，语义代码搜索是 SourceGraph 的核心卖点，需要部署服务器、配置数据库。SeaGOAT 用 ChromaDB + Ollama 的组合，把这个能力压缩到了一个 pip 包里，零运维，零成本。

从数据看，项目从 2023 年 6 月起步，GitHub stars 增长到 1298（截至 2026 年 6 月），获得了 93 个 fork 和 44 个 open issues，社区活跃度良好。作者 Daniel Kantor 同时维护了另一个项目 zeitgrep，形成了搜索工具矩阵。

SeaGOAT 的定位不是替代 grep，而是扩展 grep 的能力边界——在正则表达式无法描述需求时，给开发者一个新的选择。

图4：SeaGOAT 完整使用流程演示