Snow CLI 代码库功能设置指南:向量检索+SQLite索引,让AI真正读懂你的项目
Snow CLI 代码库功能设置指南:向量检索+SQLite索引,让AI真正读懂你的项目
Snow CLI 是一款运行在终端的 AI 编程智能体,同时兼容 Claude、OpenAI、Gemini 等主流大模型。它的代码库功能通过向量检索 + SQLite 本地索引,把你的项目源码转换成可自然语言查询的语义索引,让 AI 不再"盲人摸象"。本文带你快速完成 Snow CLI 代码库设置,三步即可让 AI 读懂整个项目 🚀
为什么需要 Snow CLI 代码库功能?
大模型对话时上下文有限,如果让它逐个文件"翻"你的项目,既慢又容易遗漏。Snow CLI 的代码库功能解决了这个问题:
- 索引本地化:源码分块后生成嵌入向量(Embedding),存入项目内的 SQLite 数据库,全程不依赖云端存储
- 自然语言查询:用"用户登录鉴权在哪里实现"这样的问法,直接检索出相关代码片段
- 语义级匹配:基于余弦相似度计算,找的是"意思相近"的代码,而不是死板的关键词
实现核心位于 codebaseSearch.ts,检索服务会先校验索引可用性,再执行带重试逻辑的语义搜索。
核心原理:SQLite 存储 + 向量相似度检索
代码库本质上是一个基于向量搜索的 SQLite 数据库,用于存储代码库的源代码和注释,并支持向量化自然语言查询。
关键数据存放在项目根目录的 .snow/codebase/embeddings.db 中。在 codebaseDatabase.ts 中可以看到核心表结构:
CREATE TABLE IF NOT EXISTS code_chunks (
...
embedding BLOB NOT NULL,
...
)
- 源码按分块(chunk)切分后,每块生成一个 Float32 向量,以 BLOB 形式存入
code_chunks表 - 查询时,先把你的自然语言问题转成向量,再遍历计算余弦相似度,取得分最高的 Top N 片段返回(见 codebaseSearch.ts 中的
cosineSimilarity实现)
Embedding 服务本身由 embedding.ts 统一封装,支持 Jina、Ollama(本地部署)、Gemini 三种接入方案——用 Ollama 的话,整个索引链路可以完全离线运行。
一键启用:/codebase 命令快速开关
进入 Snow CLI 后,用 /codebase 命令即可控制当前项目的代码库功能:
| 命令 | 作用 |
|---|---|
/codebase |
切换启停状态 |
/codebase on |
启用代码库 |
/codebase off |
禁用代码库 |
/codebase status |
查看当前状态 |
/reindex |
重建代码库索引 |
⚠️ 首次启用前,需要先进入 /home 菜单,选择「代码库设置」完成 Embedding 服务配置,否则索引无从建立。
配置界面详解:两级配置,一次配置长期生效
配置分为两层,职责清晰:
| 层级 | 文件 | 内容 |
|---|---|---|
| 项目级 | .snow/codebase.json |
启停状态、索引参数、重排序配置 |
| 全局级 | ~/.snow/codebase.json |
Embedding 服务配置,跨项目共享 |
也就是说:Embedding 只需配置一次,每个项目可以独立决定开不开代码库功能。
在 /home → 代码库配置中(界面实现见 CodeBaseConfigScreen.tsx),设置项按折叠分组排列:
启用代码库: ← 总开关
Agent 审查: ← 搜索结果 AI 审查(与重排序互斥)
结果重排序: ← 搜索结果重排序(与 Agent 审查互斥)
▶ 嵌入模型配置 ← 按 Enter 展开/收起
▶ 重排序模型配置 ← 按 Enter 展开/收起
▶ 批处理设置 ← 按 Enter 展开/收起
使用 ↑↓ 导航、Enter 编辑或展开、Ctrl+S 或 Esc 保存。
最快配置方法:Embedding 服务怎么填?
展开「▶ 嵌入模型配置」,只需三个关键字段:
- 请求方案:Jina(OpenAI 兼容)/ Ollama(本地部署)/ Gemini
- Base URL:支持多种写法,程序会自动补全规范化,例如 Ollama 本地可填
http://localhost:11434 - 嵌入维度:填写模型支持的向量维度即可;若返回维度不一致,日志会给出提示
搜索结果优化:Agent 审查 vs 结果重排序
索引建好后,检索结果还可以再精修。两种优化方式互斥,只能二选一:
| 维度 | Agent 审查 | 结果重排序(Reranking) |
|---|---|---|
| 原理 | 用 AI 模型语义审查结果,过滤噪声、建议更优关键词 | 用专用 Rerank 模型按相关性重新排序,取 Top N |
| 适合场景 | 需要深度理解代码语义 | 追求速度与轻量 |
| 特点 | 支持多轮重试、可深度探索高置信度文件 | 内置 3 次指数退避重试;用 tiktoken 精确计算 token 防止爆上下文;失败自动降级 |
重排序模型支持 Jina Reranker、Cohere Rerank 等标准 Rerank API,默认返回 Top 5 条结果。相关实现见 rerank.ts。
注意:开启其中一个会自动关闭另一个;启用重排序前需先配置好重排序模型。
进阶调优:分块与批处理参数
在「▶ 批处理设置」中可以微调索引质量与性能,直接影响搜索准确性:
| 参数 | 说明 | 默认值 |
|---|---|---|
maxLinesPerChunk |
每个分块最大行数 | 200 |
minLinesPerChunk |
每个分块最小行数 | 10 |
minCharsPerChunk |
每个分块最小字符数 | 20 |
overlapLines |
相邻分块重叠行数 | 20 |
maxLines |
每次 Embedding 请求的输入条数 | 10 |
concurrency |
并发批处理数 | 3 |
💡 调参建议:项目结构复杂时适当调大 overlapLines,可减少跨块语义被截断;索引大项目时调高 concurrency 能显著提速。完整的重建流程由 reindexCodebase.ts 负责,配合 .gitignore 规则(gitignoreValidator.ts)自动跳过不该索引的文件。
常见问题
Q:为什么 AI 搜索代码库没结果?
先确认 .snow/codebase/embeddings.db 是否存在且非空。若刚克隆新项目,请执行 /reindex 重建索引。
Q:Ollama 本地方案可以完全离线吗?
可以。Embedding 用 Ollama 的 /v1/embeddings 或原生 /api/embed 端点,整个向量检索链路均在本地 SQLite 中完成。
Q:代码库功能会消耗多少 API 额度? 仅索引阶段调用 Embedding API;查询阶段若未开启重排序/Agent 审查,则只走本地向量计算,几乎零开销。
小结:三步让 AI 读懂你的项目
/home→ 代码库设置 → 配置 Embedding 服务并启用/reindex建立向量索引- 按需开启重排序或 Agent 审查,用自然语言提问开始检索
官方详细文档见 04.代码库设置.md,更多指令用法可参考 09.0.指令面板说明.md。开启代码库索引后,Snow CLI 的漏洞猎人模式等功能的分析与安全审查能力也会同步增强——这一次,AI 是真的"读懂"了你的代码库 📖



