GrepAI 故障排除指南 - 解决索引、搜索、连接等常见问题

grepai-troubleshooting by yoanbernabeu/grepai-skills

263 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/yoanbernabeu/grepai-skills --skill grepai-troubleshooting

AI/机器学习开发命令行工具

🇨🇳中文介绍

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

问题："模型未找到"

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"  # 非常宽泛的测试

问题：搜索结果不相关

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

查询过于模糊
未配置权重提升
索引了错误的内容

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

# 不佳
grepai search "auth"

# 良好
grepai search "user authentication middleware"

配置权重提升以惩罚测试文件：

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

检查索引了哪些内容：
```
grepai status
```

问题：索引已过时

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

监控守护进程未运行
防抖延迟
文件不在索引扩展名列表中

检查守护进程状态：
```
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。

问题：索引速度慢

症状： 初始索引耗时非常长。

大型代码库
嵌入提供程序速度慢
忽略模式不足

添加忽略模式：

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

使用更快的模型：

embedder:
  model: nomic-embed-text  # 更小、更快

使用 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
```

问题：追踪未找到符号

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

函数名拼写错误
语言未启用追踪
符号索引已过时

检查确切的函数名（区分大小写）

在配置中启用语言：

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

重新构建符号索引：
```
rm .grepai/symbols.gob
grepai watch
```

问题：MCP 不工作

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

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

手动测试 MCP 服务器：
```
grepai mcp-serve
```
检查 GrepAI 是否在 PATH 中：
```
which grepai
```

验证 MCP 配置：

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

# Cursor
cat .cursor/mcp.json

问题：内存不足

症状： GrepAI 崩溃或系统变慢。

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

使用更小的模型：

embedder:
  model: nomic-embed-text  # 更小

使用 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}  # 使用环境变量

#!/bin/bash
echo "=== GrepAI 诊断 ==="

echo -e "\n1. 版本："
grepai version

echo -e "\n2. 状态："
grepai status

echo -e "\n3. 配置："
cat .grepai/config.yaml 2>/dev/null || echo "未找到配置"

echo -e "\n4. 索引文件："
ls -la .grepai/ 2>/dev/null || echo "无 .grepai 目录"

echo -e "\n5. Ollama（如果使用）："
curl -s http://localhost:11434/api/tags | head -5 || echo "Ollama 无响应"

echo -e "\n6. 守护进程："
grepai watch --status 2>/dev/null || echo "守护进程未运行"

如果其他方法都失败，进行完全重置：

# 移除所有 GrepAI 数据
rm -rf .grepai

# 重新初始化
grepai init

# 启动新索引
grepai watch

如果问题仍然存在：

查看 GrepAI 文档：https://yoanbernabeu.github.io/grepai/
搜索问题：https://github.com/yoanbernabeu/grepai/issues
创建新问题时请提供：
- GrepAI 版本 (grepai version)
- 操作系统和架构
- 配置文件（移除密钥）
- 错误信息
- 重现步骤

🔍 GrepAI 诊断

版本：0.24.0
项目：/path/to/project

✅ 配置：已找到 (.grepai/config.yaml)
✅ 索引：245 个文件，1,234 个块
✅ 嵌入器：Ollama（已连接）
✅ 守护进程：运行中（PID 12345）
❌ 问题：[如有，描述问题]

推荐操作：
1. [操作项]
2. [操作项]

🇺🇸English

GrepAI Troubleshooting

This skill provides solutions for common GrepAI issues and diagnostic procedures.

When to Use This Skill

GrepAI not working as expected
Search returning poor results
Index not updating
Connection or configuration errors

Quick Diagnostics

Run these commands to understand your setup:

# 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

Common Issues

Issue: "Index not found"

Symptom:

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

Cause: No index has been created for this project.

Solution:

# Initialize if needed
grepai init

# Create the index
grepai watch

Issue: "Cannot connect to embedding provider"

Symptom:

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

Causes:

Ollama not running
Wrong endpoint configured
Firewall blocking connection

Solutions:

Start Ollama:

ollama serve

Check endpoint in config:

embedder:

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

3. Test connection:

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

Issue: "Model not found"

Symptom:

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

Cause: The embedding model hasn't been downloaded.

Solution:

# Download the model
ollama pull nomic-embed-text

# Verify
ollama list

Issue: Search returns no results

Symptom: Searches return empty or very few results.

Causes:

Index is empty
Files are being ignored
Query too specific

Solutions:

Check index status:

grepai status

# Should show files > 0 and chunks > 0

2. Verify files are being indexed:

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

3. Try broader query:

grepai search "function"  # Very broad test

Issue: Search returns irrelevant results

Symptom: Results don't match what you're looking for.

Causes:

Query too vague
Boosting not configured
Wrong content indexed

Solutions:

Improve query (see grepai-search-tips skill):

# Bad

grepai search "auth"

# Good
grepai search "user authentication middleware"

2. Configure boosting to penalize tests:

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

3. Check what's indexed:

grepai status

Issue: Index is outdated

Symptom: Recent file changes aren't appearing in search results.

Causes:

Watch daemon not running
Debounce delay
File not in indexed extensions

Solutions:

Check daemon status:

grepai watch --status

Restart daemon:

grepai watch --stop

grepai watch --background

3. Force re-index:

rm .grepai/index.gob
grepai watch

Issue: "Config not found"

Symptom:

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

Cause: GrepAI not initialized in this directory.

Solution:

grepai init

Issue: Slow indexing

Symptom: Initial indexing takes very long.

Causes:

Large codebase
Slow embedding provider
Not enough ignore patterns

Solutions:

Add ignore patterns:

ignore:

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

2. Use faster model:

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

3. Use OpenAI for speed (if privacy allows):

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

Issue: Slow searches

Symptom: Search queries take several seconds.

Causes:

Very large index
GOB storage on large codebase
Embedding provider slow

Solutions:

Check index size:

ls -lh .grepai/index.gob

For large indices, use Qdrant:

store:

  backend: qdrant

3. Limit results:

grepai search "query" --limit 5

Issue: Trace not finding symbols

Symptom: grepai trace callers returns no results.

Causes:

Function name spelled wrong
Language not enabled for trace
Symbols index out of date

Solutions:

Check exact function name (case-sensitive)
Enable language in config:

trace:

  enabled_languages:
    - .go
    - .js
    - .ts

3. Re-build symbol index:

rm .grepai/symbols.gob
grepai watch

Issue: MCP not working

Symptom: AI assistant can't use GrepAI tools.

Causes:

MCP config incorrect
GrepAI not in PATH
Working directory wrong

Solutions:

Test MCP server manually:

grepai mcp-serve

Check GrepAI is in PATH:

which grepai

Verify MCP config:

# Claude Code

cat ~/.claude/mcp.json

# Cursor
cat .cursor/mcp.json

Issue: Out of memory

Symptom: GrepAI crashes or system becomes slow.

Causes:

Large embedding model
Very large index in GOB format
Too many parallel requests

Solutions:

Use smaller model:

embedder:

  model: nomic-embed-text  # Smaller

2. Use PostgreSQL or Qdrant instead of GOB

Reduce parallelism:

embedder:

  parallelism: 2

Issue: API key errors (OpenAI)

Symptom:

Error: 401 Unauthorized - Invalid API key

Solutions:

Check environment variable:

echo $OPENAI_API_KEY

Ensure variable is exported:

export OPENAI_API_KEY="sk-..."

Check key format in config:

embedder:

  api_key: ${OPENAI_API_KEY}  # Uses env var

Diagnostic Commands

Full System Check

#!/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"

Reset Everything

If all else fails, complete reset:

# Remove all GrepAI data
rm -rf .grepai

# Re-initialize
grepai init

# Start fresh index
grepai watch

Getting Help

If issues persist:

Check GrepAI documentation: https://yoanbernabeu.github.io/grepai/
Search issues: https://github.com/yoanbernabeu/grepai/issues
Create new issue with:
- GrepAI version (grepai version)
- OS and architecture
- Config file (remove secrets)
- Error message
- Steps to reproduce

Output Format

Diagnostic summary:

🔍 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]

Weekly Installs

263

Repository

yoanbernabeu/gr…i-skills

GitHub Stars

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode210

codex203

gemini-cli185

github-copilot184

kimi-cli171

amp170

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

GrepAI 故障排除指南 - 解决索引、搜索、连接等常见问题

🇨🇳中文介绍

GrepAI 故障排除

何时使用本技能

快速诊断

常见问题

问题："索引未找到"

问题："无法连接到嵌入提供程序"

相关 Skills

问题："模型未找到"

问题：搜索无结果

问题：搜索结果不相关

问题：索引已过时

问题："配置未找到"

问题：索引速度慢

问题：搜索速度慢

问题：追踪未找到符号

问题：MCP 不工作

问题：内存不足

问题：API 密钥错误（OpenAI）

诊断命令

完整系统检查

重置所有内容

获取帮助

输出格式

🇺🇸English

GrepAI Troubleshooting

When to Use This Skill

Quick Diagnostics

Common Issues

Issue: "Index not found"

Issue: "Cannot connect to embedding provider"

Issue: "Model not found"

Issue: Search returns no results

Issue: Search returns irrelevant results

Issue: Index is outdated

Issue: "Config not found"

Issue: Slow indexing

Issue: Slow searches

Issue: Trace not finding symbols

Issue: MCP not working

Issue: Out of memory

Issue: API key errors (OpenAI)

Diagnostic Commands

Full System Check

Reset Everything

Getting Help

Output Format

最新 Skills