首次在代码库中初始化 GrepAI…

在项目中首次设置 GrepAI 时，通过 grepai init 创建 .grepai/ 配置目录、了解默认设置并完成验证。

适用场景

解决思路

1. 进入项目根目录：cd /path/to/your/project，然后运行 grepai init。
2. 运行 grepai init 会创建 .grepai/ 目录，其中包含 config.yaml（配置文件）。
3. .grepai/index.gob 是向量索引，由后续运行 grepai watch 创建。
4. .grepai/symbols.gob 是用于 trace 的符号索引，由后续运行 grepai watch 创建。
5. 生成的 .grepai/config.yaml 默认版本为 version: 1。
6. 默认 embedder：provider: ollama，model: nomic-embed-text，endpoint: http://localhost:11434，用于本地生成嵌入。
7. 默认 store：backend: gob，使用本地文件存储。
8. 默认 chunking：size: 512，表示每个块 512 个 token；overlap: 50，表示上下文重叠。
9. 默认 watch：debounce_ms: 500，表示重新索引前等待 500 毫秒。
10. 默认 trace：mode: fast，并启用 .go、.js、.ts、.jsx、.tsx、.py、.php、.c、.h、.cpp、.hpp、.cc、.cxx、.rs、.zig、.cs、.pas、.dpr 等语言。
11. 默认 ignore 排除版本控制目录 .git、GrepAI 数据目录 .grepai、依赖目录 node_modules/vendor、构建输出 target/dist/build、缓存 __pycache__。
12. 初始化后编辑 .grepai/config.yaml 可自定义配置。
13. 更改嵌入提供方：在 .grepai/config.yaml 中设置 embedder.provider: openai、embedder.model: text-embedding-3-small、embedder.api_key: ${OPENAI_API_KEY}。
14. 更改存储后端：在 .grepai/config.yaml 中设置 store.backend: postgres，并配置 store.postgres.dsn: postgres://user:pass@localhost:5432/grepai。
15. 添加自定义忽略模式：在 .grepai/config.yaml 的 ignore 列表中加入如 `*.min.js`、`*.bundle.js`、coverage/、.nyc_output/ 等模式。
16. Monorepo 初始化方式一：进入 monorepo 根目录，运行 cd /path/to/monorepo && grepai init。
17. Monorepo 初始化方式二：使用 workspaces 建立独立索引，依次运行 grepai workspace create my-workspace、grepai workspace add my-workspace /path/to/project1、grepai workspace add my-workspace /path/to/project2。
18. 重置初始化：运行 rm -rf .grepai 删除现有配置，再运行 grepai init 重新初始化。
19. 重置警告：删除 .grepai 会删除索引，之后需要重新运行 grepai watch 建立索引。
20. 初始化后验证配置存在：运行 cat .grepai/config.yaml。
21. 初始化后检查状态：运行 grepai status，此时会显示尚无索引。
22. 若 .grepai 已存在，可删除后重新初始化：rm -rf .grepai && grepai init；或直接编辑现有配置。
23. 若配置已创建但 Ollama 未运行，在运行 grepai watch 前启动 Ollama：ollama serve。
24. 若在错误目录初始化，删除 .grepai，并在正确目录重新初始化。
25. 最佳实践：在项目根目录（主要代码所在处）初始化。
26. 最佳实践：将 .grepai/ 添加到 .gitignore，因为索引是机器特定的。
27. 最佳实践：自定义 ignore 模式，排除生成代码和第三方/vendor 代码。
28. 最佳实践：初始化后审阅 config.yaml，按项目技术栈调整设置。
29. 在 .gitignore 中添加：`# GrepAI` 和 `.grepai/`。
30. 成功初始化后输出会显示 Config: .grepai/config.yaml、默认 Embedder: Ollama (nomic-embed-text)、Storage: GOB (local file)、Chunking: 512 tokens, 50 overlap。
31. 成功初始化后的下一步：确保 Ollama 运行（ollama serve），然后运行 grepai watch 开始索引。

适用边界 · 注意事项

• 不适用于未安装或未使用 GrepAI 的项目。
• 不适用于无法运行 Ollama 且未在 .grepai/config.yaml 中改用其他嵌入提供方的场景（默认 embedder 依赖 Ollama）。
• 不要在未确认目录正确时运行 grepai init，否则会在错误位置创建 .grepai/；也不要随意删除已有 .grepai/，因为会丢失索引并需要重新运行 grepai watch。