用途
GrepAI Configuration Reference（grepai-config-reference）是一个技能，提供 GrepAI 在 .grepai/config.yaml 中所有配置选项的完整参考。当需要理解全部可用配置项、针对特定用例优化 GrepAI、排查配置问题或搭建高级配置时，可使用该技能。
配置文件位置
/your/project/.grepai/config.yaml
完整配置结构
配置文件以 version: 1 开头，包含以下主要配置块。
嵌入器配置（embedder）
将代码文本转换为向量嵌入。
provider：提供方，可选ollama、openai、lmstudio。model：模型名称（取决于提供方）。- Ollama：
nomic-embed-text、bge-m3、mxbai-embed-large - OpenAI：
text-embedding-3-small、text-embedding-3-large - LM Studio：
nomic-embed-text-v1.5、bge-small-en-v1.5
- Ollama：
endpoint：API 端点 URL。Ollama 默认http://localhost:11434，LM Studio 默认http://localhost:1234，OpenAI 使用官方 API。dimensions：向量维度（省略时自动检测）。nomic-embed-text为 768，text-embedding-3-small为 1536，text-embedding-3-large为 3072。api_key：API 密钥（用于 OpenAI，支持环境变量）。parallelism：并行请求数（仅 OpenAI，用于提速）。
存储配置（store）
存储向量嵌入的位置。
backend：后端，可选gob、postgres、qdrant。postgres：当 backend 为 postgres 时使用，配置dsn。qdrant：当 backend 为 qdrant 时使用，配置endpoint、port、use_tls，以及可选的api_key。
分块配置（chunking）
如何将代码文件切分以便嵌入。
size：每个分块的 token 数（越小越精确，越大上下文越多），推荐 256–1024。overlap：分块之间的重叠量（保留边界上下文），推荐为 size 的 10%–20%。
监听配置（watch）
文件监听守护进程设置。
debounce_ms：防抖延迟（毫秒），把快速的多次文件变更合并处理。
追踪配置（trace）
调用图分析设置。
mode：提取模式，可选fast（使用正则，无依赖，更快）或precise（使用 tree-sitter AST 解析，更准确）。enabled_languages：要分析调用图的语言，示例包括 .go、.js、.ts、.jsx、.tsx、.py、.php、.c、.h、.cpp、.hpp、.cc、.cxx、.rs、.zig、.cs、.pas、.dpr。exclude_patterns：从追踪分析中排除的模式，示例有*_test.go、*.spec.ts、*.test.js。
搜索配置（search）
搜索结果评分与排序。
boost.enabled：是否启用评分提升。boost.penalties：降低某些路径的分数，示例：/tests/因子 0.5，_test.因子 0.5，.spec.因子 0.5，/docs/因子 0.6，/vendor/因子 0.3，/node_modules/因子 0.3。boost.bonuses：提高某些路径的分数，示例：/src/因子 1.1，/lib/因子 1.1，/core/因子 1.2，/app/因子 1.1。hybrid.enabled：是否启用混合搜索（向量 + 关键词）。hybrid.k：BM25 参数。
忽略配置（ignore）
从索引中排除的文件和目录。
- 目录示例：
.git、.grepai、.svn、.hg、node_modules、vendor、target、__pycache__、.pytest_cache、dist、build、out、.next、.nuxt。 - 文件示例：
*.min.js、*.min.css、*.bundle.js、*.map、*.lock、package-lock.json、yarn.lock、pnpm-lock.yaml、go.sum。 - 生成文件示例：
*.generated.*、*.pb.go、*.d.ts。
按用例配置
- 小型个人项目：embedder 用 ollama/nomic-embed-text，store 用 gob，chunking size 512、overlap 50。
- 大型代码库：embedder 用 ollama/bge-m3，parallelism 4，store 用 postgres 并配置 dsn，chunking size 768、overlap 100。
- 团队环境：embedder 用 openai/text-embedding-3-small，api_key 用环境变量，parallelism 8，store 用 qdrant 并配置 endpoint、port、use_tls。
- 最大隐私：embedder 用 ollama/nomic-embed-text，endpoint 为 http://localhost:11434，store 用 gob（仅本地文件）。
环境变量
GrepAI 支持环境变量替换，例如在配置中写 api_key: ${OPENAI_API_KEY}、dsn: ${DATABASE_URL}，然后在 shell 中设置：
export OPENAI_API_KEY="sk-..."
export DATABASE_URL="postgres://..."
验证配置
检查配置是否有效：
grepai status
若有配置错误，会显示出来。
配置优先级
- 当前目录下的
.grepai/config.yaml - 工作区配置（如使用工作区）
- 默认值
最佳实践
- 从简单开始：先用默认值，之后再优化。
- 让分块匹配代码风格：冗长代码用更大的分块。
- 使用评分提升：惩罚 test/vendor，提升 src/lib。
- 保护 API 密钥：使用环境变量，切勿提交到仓库。
- 排除噪声：忽略生成文件和依赖。
输出格式
配置有效时输出示例（含嵌入器、存储、分块、追踪模式、语言数量、忽略模式数量、评分提升状态等信息）。