# 高级搜索模式

本文档提供 Code Search MCP 的高级搜索模式和技巧。

## 搜索模式概览

| 模式 | 工具 | 适用场景 |
|------|------|----------|
| 文件名搜索 | find_files | 快速定位文件 |
| 符号搜索 | find_symbols | 查找函数/类定义 |
| 内容搜索 | find_content | 代码内搜索 |
| 结构分析 | get_structure | 理解文件组成 |

---

## find_files 高级模式

### 模式 1: 按扩展名过滤

```python
# 搜索特定类型的配置文件
find_files: {
    "query": "config",
    "extensions": [".json", ".yaml", ".yml", ".toml", ".ini"]
}

# 搜索测试文件
find_files: {
    "query": "test",
    "extensions": [".test.js", ".test.ts", "_test.py", ".spec.js"]
}

# 搜索所有 TypeScript 文件
find_files: {
    "query": "",
    "extensions": [".ts", ".tsx"]
}
```

### 模式 2: 目录路径搜索

```python
# 搜索 src 目录下的文件
find_files: {
    "query": "component",
    "limit": 30
}
# 配合路径过滤

# 搜索组件目录
find_files: {
    "query": "Button",
    "limit": 20
}
# 结果自然包含组件路径
```

### 模式 3: 多关键词组合

```python
# 搜索复杂命名
find_files: {
    "query": "user_auth_handler",
    "limit": 20
}

# 搜索缩写
find_files: {
    "query": "utm",  # 可能匹配 utm_tracker, utm_utils
    "limit": 20
}
```

---

## find_symbols 高级模式

### 模式 1: 按类型过滤

```python
# 仅搜索函数
find_symbols: {
    "query": "get",
    "kind": "function",
    "limit": 30
}

# 仅搜索类
find_symbols: {
    "query": "Handler",
    "kind": "class",
    "limit": 20
}

# 仅搜索方法
find_symbols: {
    "query": "onClick",
    "kind": "method",
    "limit": 20
}
```

### 模式 2: 文件范围限定

```python
# 搜索特定文件的符号
find_symbols: {
    "query": "",
    "kind": "all",
    "file": "**/utils/*.js",
    "limit": 50
}

# 搜索组件目录
find_symbols: {
    "query": "",
    "kind": "class",
    "file": "**/components/*.tsx",
    "limit": 50
}
```

### 模式 3: 模糊匹配

```python
# 搜索以某前缀开头的符号
find_symbols: {
    "query": "handle",
    "limit": 30
}
# 匹配: handleClick, handleSubmit, handleInput...

# 搜索包含某词的符号
find_symbols: {
    "query": "data",
    "limit": 30
}
# 匹配: fetchData, getData, processData...
```

### 模式 4: 导出符号分析

```python
# 搜索所有导出的函数（通常是大写开头或特定命名）
find_symbols: {
    "query": "",
    "kind": "function",
    "limit": 100
}
# 筛选导出函数
```

---

## find_content 高级模式

### 模式 1: 正则表达式搜索

```python
# 搜索函数定义
find_content: {
    "query": "^\\s*def\\s+\\w+\\s*\\(",
    "regex": True,
    "limit": 50
}

# 搜索类定义
find_content: {
    "query": "^\\s*class\\s+\\w+",
    "regex": True,
    "limit": 30
}

# 搜索 import 语句
find_content: {
    "query": "^\\s*import\\s+",
    "regex": True,
    "limit": 50
}

# 搜索 async 函数
find_content: {
    "query": "async\\s+(function|def|const)",
    "regex": True,
    "limit": 30
}
```

### 模式 2: TODO/FIXME 搜索

```python
# 搜索所有 TODO
find_content: {
    "query": "TODO",
    "limit": 100
}

# 搜索所有 FIXME 和 TODO
find_content: {
    "query": "TODO|FIXME|XXX|HACK",
    "regex": True,
    "limit": 100
}

# 搜索特定人员的 TODO
find_content: {
    "query": "TODO.*zeng",
    "regex": True,
    "limit": 50
}
```

### 模式 3: 错误处理模式

```python
# 搜索 try-catch 块
find_content: {
    "query": "try\\s*\\{",
    "regex": True,
    "limit": 30
}

# 搜索 throw 语句
find_content: {
    "query": "throw\\s+new\\s+Error",
    "regex": True,
    "limit": 30
}

# 搜索 console.error
find_content: {
    "query": "console\\.(error|warn)",
    "regex": True,
    "limit": 50
}
```

### 模式 4: API 相关搜索

```python
# 搜索 fetch/axios 调用
find_content: {
    "query": "(fetch|axios)\\(",
    "regex": True,
    "limit": 30
}

# 搜索 API 路由定义
find_content: {
    "query": "(get|post|put|delete|patch)\\s*\\(",
    "regex": True,
    "limit": 30
}

# 搜索事件监听
find_content: {
    "query": "addEventListener\\(",
    "limit": 30
}
```

### 模式 5: 代码注释搜索

```python
# 搜索 JSDoc 注释
find_content: {
    "query": "/\\*\\*",
    "regex": True,
    "limit": 30
}

# 搜索行内注释
find_content: {
    "query": "//\\s*@",
    "regex": True,
    "limit": 50
}

# 搜索文档注释
find_content: {
    "query": "\"\"\".*\"\"\"",
    "regex": True,
    "limit": 30
}
```

---

## get_structure 高级模式

### 模式 1: 快速文件概览

```python
# 获取文件结构
get_structure: {
    "file_path": "/path/to/file.py"
}

# 返回:
{
    "path": "/path/to/file.py",
    "language": "python",
    "symbols": [
        {"name": "MyClass", "kind": "class", "line": 10},
        {"name": "method1", "kind": "method", "line": 15},
        {"name": "method2", "kind": "method", "line": 25},
        {"name": "helper", "kind": "function", "line": 40}
    ]
}
```

### 模式 2: 结合符号搜索

```python
# 1. 先搜索符号
find_symbols: {
    "query": "UserService",
    "kind": "class"
}

# 2. 获取该文件结构
get_structure: {
    "file_path": "/path/to/UserService.ts"
}

# 3. 导航到具体方法
```

---

## 组合搜索工作流

### 工作流 1: 理解新代码库

```python
# Step 1: 获取整体统计
get_stats: {}

# Step 2: 搜索核心模块
find_files: {
    "query": "index",
    "extensions": [".ts", ".js"]
}

# Step 3: 分析入口文件
get_structure: {
    "file_path": "src/index.ts"
}

# Step 4: 搜索关键类
find_symbols: {
    "query": "",
    "kind": "class"
}
```

### 工作流 2: 定位 Bug

```python
# Step 1: 搜索错误相关代码
find_content: {
    "query": "error|Error|exception",
    "limit": 50
}

# Step 2: 找到相关文件
# → 获取文件结构
get_structure: {
    "file_path": "..."
}

# Step 3: 分析错误处理
find_content: {
    "query": "throw|catch",
    "file_pattern": "*.ts"
}
```

### 工作流 3: 重构准备

```python
# Step 1: 找到目标类/函数
find_symbols: {
    "query": "OldAPI",
    "kind": "class"
}

# Step 2: 找到所有调用
find_content: {
    "query": "OldAPI",
    "limit": 100
}

# Step 3: 分析依赖
find_symbols: {
    "query": "",
    "file": "**/old*.py"
}
```

---

## 性能优化技巧

### 1. 合理使用 limit

```python
# 不需要太多结果时
find_files: {"query": "test", "limit": 10}  # 足够定位

# 需要全面搜索时
find_content: {"query": "TODO", "limit": 100}
```

### 2. 组合过滤

```python
# 先缩小范围，再精确搜索
find_files: {"query": "api", "extensions": [".ts"]}
find_content: {"query": "fetch", "file_pattern": "**/api/**"}
```

### 3. 使用增量索引

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