GrepAI 搜索/索引异常时的诊断与修复指南

当 GrepAI 出现索引、搜索、连接、配置、性能或 MCP 问题时，按步骤诊断并修复。

适用场景

解决思路

1. 运行 `grepai version` 查看 GrepAI 版本。
2. 运行 `grepai status` 查看项目状态。
3. 如果使用 Ollama，运行 `curl http://localhost:11434/api/tags` 检查 Ollama。
4. 运行 `cat .grepai/config.yaml` 查看配置。
5. 遇到 “Index not found” 时，先运行 `grepai init` 初始化（如需要）。
6. 遇到 “Index not found” 时，运行 `grepai watch` 创建索引。
7. 遇到 “Cannot connect to embedding provider” 时，运行 `ollama serve` 启动 Ollama。
8. 遇到 “Cannot connect to embedding provider” 时，检查配置中的 endpoint：`embedder: endpoint: http://localhost:11434`。
9. 遇到 “Cannot connect to embedding provider” 时，运行 `curl http://localhost:11434/api/tags` 测试连接。
10. 遇到 “Model not found” 时，运行 `ollama pull nomic-embed-text` 下载嵌入模型。
11. 遇到 “Model not found” 时，运行 `ollama list` 验证模型是否已安装。
12. 搜索无结果时，运行 `grepai status` 检查索引状态，确认 files > 0 且 chunks > 0。
13. 搜索无结果时，运行 `cat .grepai/config.yaml | grep -A 20 "ignore:"` 检查忽略规则，确认文件正在被索引。
14. 搜索无结果时，尝试更宽泛的查询：`grepai search "function"`。
15. 搜索返回无关结果时，改进查询，避免像 `grepai search "auth"` 这样过于宽泛，改用 `grepai search "user authentication middleware"` 这类更具体的查询。
16. 搜索返回无关结果时，配置 boosting 以惩罚测试文件：`search: boost: enabled: true penalties: - pattern: /tests/ factor: 0.5`。
17. 搜索返回无关结果时，运行 `grepai status` 检查实际索引内容。
18. 索引过期时，运行 `grepai watch --status` 检查 watch 守护进程状态。
19. 索引过期时，重启守护进程：`grepai watch --stop`，然后 `grepai watch --background`。
20. 索引过期时，强制重建索引：`rm .grepai/index.gob`，然后 `grepai watch`。
21. 遇到 “Config not found” 时，运行 `grepai init`。
22. 索引慢时，添加忽略模式：`ignore: - node_modules - vendor - dist - build - "*.min.js"`。
23. 索引慢时，使用更快的模型：`embedder: model: nomic-embed-text`。
24. 索引慢且隐私允许时，使用 OpenAI 提速：`embedder: provider: openai model: text-embedding-3-small parallelism: 8`。
25. 搜索慢时，运行 `ls -lh .grepai/index.gob` 检查索引大小。
26. 搜索慢且索引很大时，使用 Qdrant：`store: backend: qdrant`。
27. 搜索慢时，限制返回结果数量：`grepai search "query" --limit 5`。
28. `grepai trace callers` 找不到符号时，检查函数名拼写且区分大小写。
29. `grepai trace callers` 找不到符号时，在配置中启用语言：`trace: enabled_languages: - .go - .js - .ts`。
30. `grepai trace callers` 找不到符号时，重建符号索引：`rm .grepai/symbols.gob`，然后 `grepai watch`。
31. MCP 不工作时，手动测试 MCP 服务器：`grepai mcp-serve`。
32. MCP 不工作时，检查 GrepAI 是否在 PATH 中：`which grepai`。
33. MCP 不工作时，验证 MCP 配置：Claude Code 运行 `cat ~/.claude/mcp.json`，Cursor 运行 `cat .cursor/mcp.json`。
34. 内存不足时，使用更小的模型：`embedder: model: nomic-embed-text`。
35. 内存不足时，改用 PostgreSQL 或 Qdrant 代替 GOB。
36. 内存不足时，降低并行度：`embedder: parallelism: 2`。
37. OpenAI API key 报 401 时，运行 `echo $OPENAI_API_KEY` 检查环境变量。
38. OpenAI API key 报 401 时，确保已导出变量：`export OPENAI_API_KEY="sk-..."`。
39. OpenAI API key 报 401 时，检查配置中的 key 格式：`embedder: api_key: ${OPENAI_API_KEY}`。
40. 运行完整系统检查脚本： ```bash #!/bin/bash echo "=== GrepAI Diagnostics ===" echo -e "\n1. Version:" grepai version echo -e "\n2. Status:" grepai status echo -e "\n3. Config:" cat .grepai/config.yaml 2>/dev/null || echo "No config found" echo -e "\n4. Index files:" ls -la .grepai/ 2>/dev/null || echo "No .grepai directory" echo -e "\n5. Ollama (if using):" curl -s http://localhost:11434/api/tags | head -5 || echo "Ollama not responding" echo -e "\n6. Daemon:" grepai watch --status 2>/dev/null || echo "Daemon not running" ```
41. 若所有方法失败，移除所有 GrepAI 数据：`rm -rf .grepai`。
42. 重置后重新初始化：`grepai init`。
43. 重置后重新创建索引：`grepai watch`。
44. 问题持续时，查阅 GrepAI 文档：https://yoanbernabeu.github.io/grepai/。
45. 问题持续时，搜索 GitHub issues：https://github.com/yoanbernabeu/grepai/issues。
46. 创建新 issue 时，提供 GrepAI 版本（`grepai version`）。
47. 创建新 issue 时，提供操作系统和架构。
48. 创建新 issue 时，提供配置文件（移除 secrets）。
49. 创建新 issue 时，提供错误信息。
50. 创建新 issue 时，提供复现步骤。
51. 按诊断摘要模板输出： ``` 🔍 GrepAI Diagnostics Version: 0.24.0 Project: /path/to/project ✅ Config: Found (.grepai/config.yaml) ✅ Index: 245 files, 1,234 chunks ✅ Embedder: Ollama (connected) ✅ Daemon: Running (PID 12345) ❌ Issue: [Description if any] Recommended actions: 1. [Action item] 2. [Action item] ```

适用边界 · 注意事项

• 不适用于未使用 GrepAI 的项目，或排查其他搜索/索引工具的问题。
• 部分解决方案依赖 Ollama、OpenAI、Qdrant 或 PostgreSQL；未安装或不愿使用这些服务时，不应套用对应做法。
• `rm -rf .grepai`、`rm .grepai/index.gob`、`rm .grepai/symbols.gob` 是破坏性操作，只有在确认索引可重建且数据可丢弃时才使用。