# Snow CLI 使用文档——代码库设置

欢迎使用 Snow CLI！在终端中进行 Agentic 编程。

## 代码库设置

Snow CLI 支持启用本地代码库功能。

_代码库是一个基于向量搜索的 Sqlite 数据库，用于存储代码库的源代码和注释。并通过向量化自然语言查询。_

## 配置存储

代码库配置分为两部分：

- **项目级配置** (`.snow/codebase.json`)：存储在项目根目录，控制当前项目的启停状态、索引参数、重排序配置等
- **全局配置** (`~/.snow/codebase.json`)：存储 Embedding 服务配置，跨项目共享

这样每个项目可以独立控制代码库功能的启停，而 Embedding 配置只需配置一次。

## 快速启停

使用 `/codebase` 命令可以快速控制当前项目的代码库功能：

- `/codebase` - 切换启停状态
- `/codebase on` - 启用代码库
- `/codebase off` - 禁用代码库
- `/codebase status` - 查看当前状态

首次启用时，需要先在 `/home` 中配置 Embedding 服务。

## 配置界面

在 `/home` → 代码库配置中，设置项按折叠分组排列，节约显示空间：

```
  启用代码库:              ← 总开关
  Agent 审查:              ← 搜索结果 AI 审查（与重排序互斥）
  结果重排序:              ← 搜索结果重排序（与 Agent 审查互斥）
  ▶ 嵌入模型配置           ← 按 Enter 展开/收起
  ▶ 重排序模型配置         ← 按 Enter 展开/收起
  ▶ 批处理设置             ← 按 Enter 展开/收起
```

使用 ↑↓ 导航，Enter 编辑/切换/展开，Ctrl+S 或 Esc 保存。

## 搜索结果优化

代码库搜索返回结果后，有两种优化方式可选（**二者互斥，不能同时开启**）：

### Agent 审查

使用 AI 模型（basicModel）对搜索结果进行语义审查，过滤不相关的结果，并可能建议更好的搜索关键词。适合需要深度理解代码语义的场景。

- 支持多轮重试和关键词建议
- 可识别高置信度文件进行深度探索
- 依赖已配置的 AI 模型（basicModel / advancedModel）

### 结果重排序（Reranking）

使用专用的 Rerank 模型对搜索结果按相关性重新排序，取 Top N 返回。相比 Agent 审查更轻量高效，适合追求速度的场景。

- 调用标准 Rerank API（兼容 Jina Reranker、Cohere Rerank 等）
- 内置 3 次失败重试（指数退避）
- 内置上下文长度防护：使用 tiktoken 精确计算 token，超长文档自动截断或丢弃，防止爆上下文
- 失败时自动降级为原始搜索结果

**互斥规则**：开启「结果重排序」会自动关闭「Agent 审查」，反之亦然。启用重排序前需要先配置重排序模型，否则无法切换。

## Embedding 服务配置

在「▶ 嵌入模型配置」中展开设置：

- 代码库支持三种请求方案：Jina（OpenAI 兼容）、Ollama（本地部署，支持 OpenAI 兼容 `/v1/embeddings` 与原生 `/api/embed`）和 Gemini。

- 代码库的 BaseURL（支持多种写法，程序会自动补全/规范化到最终端点）：

  - Jina（OpenAI 兼容）支持：`https://api.jina.ai`、`https://api.jina.ai/v1`、`https://api.jina.ai/v1/embeddings`（最终请求 `.../v1/embeddings`）。
  - Ollama 支持：`http://localhost:11434`、`http://localhost:11434/v1`、`http://localhost:11434/v1/embeddings`（OpenAI 兼容）；以及 `http://localhost:11434/api`、`http://localhost:11434/api/embed`（Ollama 原生）。

- 嵌入维度：填写嵌入模型支持的维度即可；部分服务可能忽略 `dimensions` 参数，若返回维度不一致会在日志中提示。

## 重排序模型配置

在「▶ 重排序模型配置」中展开设置：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| 模型名 | Rerank 模型名称，如 `jina-reranker-v2-base-multilingual` | — |
| Base URL | Rerank API 地址，如 `https://api.jina.ai`（自动补全为 `/v1/rerank`） | — |
| API 密钥 | API 认证密钥（可选，本地部署可留空） | — |
| 模型上下文长度 | 模型支持的最大上下文 token 数，用于防止请求超限 | 4096 |
| Top N | 重排序后返回前 N 个最相关的结果 | 5 |

**上下文长度防护机制**：发送请求前会使用 tiktoken 精确计算所有文档的 token 总量。单个文档超过上下文 30% 会被截断；累计超出上下文窗口的文档会被丢弃。确保请求不会超出模型限制。

## 索引参数配置

在「▶ 批处理设置」中展开设置：

- 分块配置：配置代码如何分割成块以进行索引。这些设置控制代码段的大小和重叠：
  - `maxLinesPerChunk`：每个分块的最大行数（默认：200）
  - `minLinesPerChunk`：每个分块的最小行数（默认：10）
  - `minCharsPerChunk`：每个分块的最小字符数（默认：20）
  - `overlapLines`：连续分块之间的重叠行数（默认：20）
    这些设置影响搜索准确性和索引性能。
- 批处理配置：控制文件如何分批处理以提高索引效率：
  - `maxLines`：每个批处理请求的最大行数（默认：10）
  - `concurrency`：并发批处理操作数（默认：3）
    这控制每次请求发送到嵌入 API 的 `input` 项数量。

**注意：批处理最大条数代表请求体中的 `input` 数，而非代码切片的行数**

## 相关功能

启用代码库索引后，以下功能会得到显著增强：

- [漏洞猎人模式](./11.漏洞猎人模式.md) - 代码库索引可以大幅提升安全分析的准确性和效率
- [指令面板说明](./09.0.指令面板说明.md) - 使用 `/reindex` 重建代码库索引，使用 `/codebase` 控制启停