# 故障排查指南

本文档帮助解决 Code Search MCP 常见问题。

---

## 索引问题

### 问题：索引失败

**症状**: `index_repository` 返回 `success: false`

**排查步骤**:

```python
# 1. 检查日志
get_logs: {"success": False, "limit": 10}

# 2. 常见原因
```

#### 原因 1: 路径不存在

```python
# 错误
index_repository: {"repo_path": "/nonexistent/path"}

# 解决
# 确认路径存在
import os
os.path.isdir("/your/actual/path")  # True
```

#### 原因 2: 权限不足

```python
# 错误
# Permission denied

# 解决
# 检查文件权限
ls -la /path/to/repo

# 或使用有权限的路径
```

#### 原因 3: 编码问题

```python
# 症状
# UnicodeDecodeError

# 解决
# Code Search 会自动跳过编码问题文件
# 检查日志获取详细信息
```

---

### 问题：索引不完整

**症状**: 文件数量少于预期

**排查**:

```python
# 1. 检查统计
get_stats: {}

# 2. 检查文件过滤
# 默认忽略以下目录:
# node_modules, .git, __pycache__, .venv, dist, build
```

**可能原因**:

| 原因 | 解决 |
|------|------|
| 文件在忽略目录 | 移动文件或修改代码 |
| 扩展名不支持 | 确认文件类型 |
| 文件为空 | 跳过空文件 |

---

### 问题：增量索引不工作

**症状**: 每次都重新索引所有文件

**排查**:

```python
# 检查是否使用 force_rebuild
index_repository: {"repo_path": path, "force_rebuild": False}

# 检查文件修改时间
# Code Search 基于 modified_time 判断
```

---

## 搜索问题

### 问题：搜索无结果

**症状**: 返回空数组

**排查步骤**:

```python
# 1. 确认已索引
get_stats: {}
# 确保 files > 0

# 2. 检查查询
find_files: {"query": "test"}

# 3. 尝试不同搜索
```

#### 原因 1: 未索引

```python
# 解决：先索引
index_repository: {"repo_path": "/path/to/repo"}
```

#### 原因 2: 查询不匹配

```python
# 问题：文件名不包含 query
find_files: {"query": "不存在的内容"}

# 解决：使用更通用的词
find_files: {"query": ""}  # 返回所有文件
```

#### 原因 3: 扩展名过滤

```python
# 问题：限定了不存在的扩展名
find_files: {"query": "x", "extensions": [".nonexistent"]}

# 解决：不限定或使用正确扩展名
find_files: {"query": "x"}
```

---

### 问题：搜索结果少

**症状**: 应该返回更多结果

**排查**:

```python
# 1. 增加 limit
find_files: {"query": "x", "limit": 100}

# 2. 检查扩展名过滤
find_files: {"query": "x", "extensions": [".py"]}

# 3. 尝试内容搜索
find_content: {"query": "keyword"}
```

---

### 问题：正则搜索失败

**症状**: 正则搜索报错或无结果

**排查**:

```python
# 1. 检查正则语法
find_content: {"query": "invalid(regex", "regex": True}

# 2. 简化正则
find_content: {"query": "function\\s+\\w+", "regex": True}
# 改为
find_content: {"query": "function "}
```

---

## 性能问题

### 问题：索引变慢

**症状**: 索引时间变长

**排查**:

```python
# 1. 检查文件数量
get_stats: {}

# 2. 检查日志
get_logs: {"success": False}

# 3. 原因分析
# - 网络存储（慢）
# - 大量小文件
# - 编码问题文件
```

**解决**:

```python
# 使用增量索引
index_repository: {"repo_path": path, "force_rebuild": False}
```

---

### 问题：搜索变慢

**症状**: 搜索延迟 > 100ms

**排查**:

```python
# 1. 检查数据量
get_stats: {}

# 2. 添加过滤
find_content: {"query": "x", "file_pattern": "**/src/**"}

# 3. 减少 limit
find_files: {"query": "x", "limit": 20}
```

---

### 问题：内存占用高

**症状**: 内存使用持续增长

**排查**:

```python
# 1. 检查日志缓冲
# 默认缓冲 1000 条

# 2. 清理旧日志
# 清理 0 天前的所有日志
logger.clear_old_logs(days=0)
```

---

## MCP 客户端问题

### 问题：无法连接

**症状**: MCP 客户端连接失败

**排查**:

```python
# 1. 确认安装
pip list | grep code-search

# 2. 测试运行
python -m code_search_mcp

# 3. 检查配置
# Claude Code 配置正确
{
  "mcpServers": {
    "code-search": {
      "command": "python",
      "args": ["-m", "code_search_mcp"]
    }
  }
}
```

---

### 问题：工具调用超时

**症状**: 调用超时

**排查**:

```python
# 1. 检查索引状态
get_stats: {}

# 2. 使用增量索引
index_repository: {"repo_path": path, "force_rebuild": False}

# 3. 限制返回数量
find_files: {"query": "x", "limit": 20}
```

---

## 日志问题

### 问题：日志过多

**解决**:

```python
# 清理旧日志
logger.clear_old_logs(days=7)  # 保留7天

# 或清理所有
logger.clear_old_logs(days=0)
```

---

### 问题：无法查看日志

**排查**:

```python
# 1. 确认日志存在
get_stats: {}

# 2. 使用正确参数
get_logs: {"limit": 10}

# 3. 检查权限
```

---

## 错误代码

### 错误：`Unknown tool`

**原因**: 工具名拼写错误

**解决**:
```
正确工具名:
- index_repository
- find_files
- find_symbols
- find_content
- get_structure
- get_stats
- get_logs
- get_call_stats
```

---

### 错误：`Missing required parameter`

**原因**: 缺少必填参数

**解决**:
```python
# 必填参数:
# - index_repository: repo_path
# - find_files: query
# - find_symbols: query
# - find_content: query
# - get_structure: file_path
```

---

### 错误：`Invalid parameter type`

**原因**: 参数类型错误

**解决**:
```python
# 确保类型正确
find_files: {"query": "test", "limit": 20}  # limit 是数字
find_content: {"regex": True}  # regex 是布尔
```

---

## 诊断命令

### 完整诊断

```python
# 1. 索引状态
get_stats: {}

# 2. 调用统计
get_call_stats: {}

# 3. 最近日志
get_logs: {"limit": 20}

# 4. 错误日志
get_logs: {"success": False, "limit": 10}
```

---

## 获取帮助

如果以上方法无法解决问题：

1. 查看完整日志
```python
get_logs: {"limit": 100}
```

2. 检查 GitHub Issues

3. 提供以下信息：
   - 错误信息
   - 复现步骤
   - 环境信息
