用途
GrepAI Troubleshooting 是一个面向 GrepAI 的故障排查技能，用于诊断和修复 GrepAI 使用过程中的常见问题。当 GrepAI 未按预期工作、搜索结果质量差、索引不更新，或出现连接与配置错误时，可使用本技能。
快速诊断
可先运行以下命令了解当前环境：
# 检查 GrepAI 版本
grepai version
# 检查项目状态
grepai status
# 检查 Ollama（如果使用）
curl http://localhost:11434/api/tags
# 检查配置
cat .grepai/config.yaml
常见问题与解决
索引未找到
症状：Error: Index not found. Run 'grepai watch' first.
原因：该项目尚未创建索引。
解决：
# 如需要先初始化
grepai init
# 创建索引
grepai watch
无法连接嵌入提供方
症状：Error: Cannot connect to Ollama at http://localhost:11434
原因：Ollama 未运行、端点配置错误、防火墙阻止连接。
解决：启动 Ollama（ollama serve）；在配置中检查端点：
embedder:
endpoint: http://localhost:11434 # Verify this
测试连接：curl http://localhost:11434/api/tags
模型未找到
症状：Error: Model 'nomic-embed-text' not found
原因：嵌入模型尚未下载。
解决：
# 下载模型
ollama pull nomic-embed-text
# 验证
ollama list
搜索无结果
症状：搜索返回空或结果极少。
原因：索引为空、文件被忽略、查询过于具体。
解决：检查索引状态（grepai status，应显示 files > 0 且 chunks > 0）；检查配置中的忽略模式（cat .grepai/config.yaml | grep -A 20 "ignore:"）；尝试更宽泛的查询（grepai search "function"）。
搜索结果不相关
症状：结果与目标不匹配。
原因：查询过于模糊、未配置 boosting、索引了错误内容。
解决：改进查询，例如将 grepai search "auth" 改为 grepai search "user authentication middleware"；配置 boosting 以惩罚测试文件：
search:
boost:
enabled: true
penalties:
- pattern: /tests/
factor: 0.5
并检查已索引内容（grepai status）。
索引过期
症状：最近的文件变更未出现在搜索结果中。
原因：watch 守护进程未运行、防抖延迟、文件不在已索引扩展名中。
解决：检查守护进程状态（grepai watch --status）；重启守护进程：
grepai watch --stop
grepai watch --background
强制重建索引：
rm .grepai/index.gob
grepai watch
配置未找到
症状：Error: Config file not found at .grepai/config.yaml
原因：该目录未初始化 GrepAI。
解决：grepai init
索引缓慢
症状：初始索引耗时很长。
原因：代码库庞大、嵌入提供方慢、忽略模式不足。
解决：添加忽略模式：
ignore:
- node_modules
- vendor
- dist
- build
- "*.min.js"
使用更快的模型：
embedder:
model: nomic-embed-text # Smaller, faster
如隐私允许，可使用 OpenAI 提速：
embedder:
provider: openai
model: text-embedding-3-small
parallelism: 8
搜索缓慢
症状：搜索查询耗时数秒。
原因：索引非常大、大型代码库上使用 GOB 存储、嵌入提供方慢。
解决：检查索引大小（ls -lh .grepai/index.gob）；大型索引改用 Qdrant：
store:
backend: qdrant
限制结果数量：grepai search "query" --limit 5
trace 找不到符号
症状：grepai trace callers 无结果。
原因：函数名拼写错误、语言未启用 trace、符号索引过期。
解决：检查准确的函数名（区分大小写）；在配置中启用语言：
trace:
enabled_languages:
- .go
- .js
- .ts
重建符号索引：
rm .grepai/symbols.gob
grepai watch
MCP 无法使用
症状：AI 助手无法使用 GrepAI 工具。
原因：MCP 配置不正确、GrepAI 不在 PATH 中、工作目录错误。
解决：手动测试 MCP 服务器（grepai mcp-serve）；检查 PATH（which grepai）；验证 MCP 配置：
# Claude Code
cat ~/.claude/mcp.json
# Cursor
cat .cursor/mcp.json
内存不足
症状：GrepAI 崩溃或系统变慢。
原因：嵌入模型过大、GOB 格式索引非常大、并行请求过多。
解决：使用更小的模型：
embedder:
model: nomic-embed-text # Smaller
改用 PostgreSQL 或 Qdrant 替代 GOB；降低并行度：
embedder:
parallelism: 2
API 密钥错误（OpenAI）
症状：Error: 401 Unauthorized - Invalid API key
解决：检查环境变量（echo $OPENAI_API_KEY）；确保变量已导出（export OPENAI_API_KEY="sk-..."）；检查配置中的密钥格式：
embedder:
api_key: ${OPENAI_API_KEY} # Uses env var
诊断命令
完整系统检查脚本：
#!/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"
完全重置（如果其他方法都失败）：
# 删除所有 GrepAI 数据
rm -rf .grepai
# 重新初始化
grepai init
# 重新建立索引
grepai watch
获取帮助
如果问题仍然存在：查阅 GrepAI 文档 https://yoanbernabeu.github.io/grepai/ ；搜索 issues https://github.com/yoanbernabeu/grepai/issues ；创建新 issue 时附上：GrepAI 版本（grepai version）、操作系统与架构、配置文件（移除密钥）、错误信息、复现步骤。
输出格式
诊断摘要示例：
🔍 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 进行代码检索、索引与符号追踪时遇到故障的排查场景，尤其适合需要快速定位配置、连接、索引与性能问题的开发者。限制方面，资料未提供 GrepAI 的收费、价格、平台支持范围及具体效果保证等信息，相关内容暂未提供。