grepai-troubleshooting

GrepAI 故障排除

本技能提供常见 GrepAI 问题的解决方案和诊断流程。

何时使用此技能

• GrepAI 无法按预期工作
• 搜索结果不理想
• 索引未更新
• 连接或配置错误

快速诊断

运行以下命令以了解你的设置：

# Check GrepAI version
grepai version

# Check project status
grepai status

# Check Ollama (if using)
curl http://localhost:11434/api/tags

# Check config
cat .grepai/config.yaml

常见问题

---

问题：“Index not found”

症状：

Error: Index not found. Run 'grepai watch' first.

原因： 尚未为此项目创建索引。

解决方案：

# Initialize if needed
grepai init

# Create the index
grepai watch

---

问题：“Cannot connect to embedding provider”

症状：

Error: Cannot connect to Ollama at http://localhost:11434

原因：

1. Ollama 未运行
2. 配置的端点错误
3. 防火墙阻止了连接

解决方案：

1. 启动 Ollama：

ollama serve

2. 检查配置中的端点：

embedder:
  endpoint: http://localhost:11434  # Verify this

3. 测试连接：

curl http://localhost:11434/api/tags

---

问题：“Model not found”

症状：

Error: Model 'nomic-embed-text' not found

原因： 尚未下载嵌入模型。

解决方案：

# Download the model
ollama pull nomic-embed-text

# Verify
ollama list

---

问题：搜索无结果

症状： 搜索返回空结果或极少的结果。

原因：

1. 索引为空
2. 文件被忽略
3. 查询过于具体

解决方案：

1. 检查索引状态：

grepai status
# Should show files > 0 and chunks > 0

2. 确认文件已编入索引：

# Check ignore patterns in config
cat .grepai/config.yaml | grep -A 20 "ignore:"

3. 尝试更宽泛的查询：

grepai search "function"  # Very broad test

---

问题：搜索返回不相关结果

症状： 结果与要查找的内容不匹配。

原因：

1. 查询过于模糊
2. 未配置加权
3. 编入索引的内容不正确

解决方案：

1. 改进查询（参见 grepai-search-tips 技能）：

# Bad
grepai search "auth"

# Good
grepai search "user authentication middleware"

2. 配置加权以降低测试文件的权重：

search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5

3. 检查已编入索引的内容：

grepai status

---

问题：索引已过时

症状： 最近的文件更改未出现在搜索结果中。

原因：

1. 监视守护进程未运行
2. 防抖延迟
3. 文件扩展名不在已编入索引的范围内

解决方案：

1. 检查守护进程状态：

grepai watch --status

2. 重启守护进程：

grepai watch --stop
grepai watch --background

3. 强制重新建立索引：

rm .grepai/index.gob
grepai watch

---

问题：“Config not found”

症状：

Error: Config file not found at .grepai/config.yaml

原因： 尚未在此目录中初始化 GrepAI。

解决方案：

grepai init

---

问题：索引速度慢

症状： 初次建立索引耗时很长。

原因：

1. 代码库很大
2. 嵌入服务速度慢
3. 忽略规则不足

解决方案：

1. 添加忽略规则：

ignore:
  - node_modules
  - vendor
  - dist
  - build
  - "*.min.js"

2. 使用速度更快的模型：

embedder:
  model: nomic-embed-text  # Smaller, faster

3. 若隐私要求允许，可使用 OpenAI 提高速度：

embedder:
  provider: openai
  model: text-embedding-3-small
  parallelism: 8

---

问题：搜索速度慢

症状： 搜索查询需要数秒才能完成。

原因：

1. 索引非常大
2. 大型代码库使用 GOB 存储
3. 嵌入服务速度慢

解决方案：

1. 检查索引大小：

ls -lh .grepai/index.gob

2. 对于大型索引，请使用 Qdrant：

store:
  backend: qdrant

3. 限制结果数量：

grepai search "query" --limit 5

---

问题：Trace 找不到符号

症状： grepai trace callers 未返回结果。

原因：

1. 函数名称拼写错误
2. 未为 Trace 启用该语言
3. 符号索引已过时

解决方案：

1. 检查准确的函数名称（区分大小写）

2. 在配置中启用该语言：

trace:
  enabled_languages:
    - .go
    - .js
    - .ts

3. 重新构建符号索引：

rm .grepai/symbols.gob
grepai watch

---

问题：MCP 无法正常工作

症状： AI 助手无法使用 GrepAI 工具。

原因：

1. MCP 配置不正确
2. GrepAI 不在 PATH 中
3. 工作目录错误

解决方案：

1. 手动测试 MCP 服务：

grepai mcp-serve

2. 检查 GrepAI 是否在 PATH 中：

which grepai

3. 验证 MCP 配置：

# Claude Code
cat ~/.claude/mcp.json

# Cursor
cat .cursor/mcp.json

---

问题：内存不足

症状： GrepAI 崩溃或系统运行缓慢。

原因：

1. 嵌入模型过大
2. GOB 格式的索引非常大
3. 并行请求过多

解决方案：

1. 使用更小的模型：

embedder:
  model: nomic-embed-text  # Smaller

2. 使用 PostgreSQL 或 Qdrant 代替 GOB

3. 降低并行度：

embedder:
  parallelism: 2

---

问题：API 密钥错误（OpenAI）

症状：

Error: 401 Unauthorized - Invalid API key

解决方案：

1. 检查环境变量：

echo $OPENAI_API_KEY

2. 确保已导出变量：

export OPENAI_API_KEY="sk-..."

3. 检查配置中的密钥格式：

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"

重置所有内容

如果其他方法都无效，请执行完整重置：

# Remove all GrepAI data
rm -rf .grepai

# Re-initialize
grepai init

# Start fresh index
grepai watch

获取帮助

如果问题仍然存在：

1. 查看 GrepAI 文档：https://yoanbernabeu.github.io/grepai/
2. 搜索已有问题：https://github.com/yoanbernabeu/grepai/issues
3. 创建新问题，并提供：
   • 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]