# index1 + Claude Code 使用指南

## 它们各自擅长什么

```
Claude Code 内置工具（Grep/Glob/Read）：
  ✅ 找具体代码        "class Database 在哪？"     → 4ms，精准
  ✅ 正则匹配          "所有 async def 函数"        → 4ms，无遗漏
  ❌ 理解性问题        "搜索怎么实现的？"           → 返回 881 行噪声
  ❌ 中文查英文代码     "向量搜索怎么做"             → 搜不到

index1（docs_search）：
  ✅ 理解性问题        "搜索怎么实现的？"           → 5 条精排结果
  ✅ 中文查英文        "向量搜索怎么做"             → 定位 embed.py, db.py
  ✅ 多概念查询        "怎么配置 watch 路径"        → 一次搜索搞定
  ❌ 精确标识符        "class Database 在哪？"      → Grep 更快更准
```

## 最佳配合方式

### 场景 1：探索性问题（最常见）

> "这个项目的搜索功能是怎么实现的？"

**推荐流程**：index1 定方向 → Grep 找代码 → Read 读细节

```
你: 搜索功能怎么实现的？

Claude Code 的做法:
  ① docs_search("搜索功能实现")           → search.py 是核心    ~460 tokens
  ② Grep "async def search" search.py    → 第 97 行            ~100 tokens
  ③ Read search.py:97-200                → 读完整函数           ~400 tokens
                                                         总计: ~960 tokens
如果不用 index1:
  ① Grep "search" 全项目                 → 881 行匹配        ~35,895 tokens
  ② 从 881 行里人工找入口                 → 还要再搜几次       +数千 tokens
                                                         总计: ~40,000 tokens
```

**节省：97% 的上下文窗口**

### 场景 2：已知标识符（直接 Grep）

> "_has_cjk 函数在哪？"

不需要 index1，直接 Grep：

```
你: _has_cjk 在哪？

Claude Code: Grep "_has_cjk" → search.py:52    ~100 tokens，4ms
```

### 场景 3：中文提问查英文代码（必须 index1）

> "向量搜索怎么做的？"

Grep 搜不到（中英文不匹配），只能用 index1：

```
你: 向量搜索怎么做的？

Claude Code:
  ① docs_search("向量搜索怎么做的")
     → embed.py（生成向量）
     → db.py:vector_search（余弦搜索）
     → search.py（RRF 融合）
  ② Read 相关文件
```

### 场景 4：常见关键词（优先 index1）

> "配置相关的代码在哪？"

"config" 在项目里到处都是，Grep 返回几百行：

```
用 Grep:    grep "config" → 300+ 行, ~8,000 tokens（噪声太多）
用 index1:  docs_search("配置相关代码") → 5 条, ~460 tokens（直接看到 config.py）
```

## 怎么让 Claude Code 自动遵循这个策略

在项目的 `.claude/CLAUDE.md` 里添加（已配好）：

```markdown
## 搜索策略

本项目配置了 index1 MCP Server。搜索代码时遵循：

1. 已知标识符（函数名/类名/文件名）→ 直接 Grep/Glob
2. 探索性问题（"XX 怎么实现的"）→ 先 docs_search，再 Grep 精确查找
3. 中文查英文代码 → 必须用 docs_search
4. 高频关键词（预期 > 50 行）→ 优先 docs_search
```

Claude Code 每次新对话都会读取这个文件，自动按策略执行。

## 不用 index1 时怎么省上下文

即使没有 index1，也有办法减少 Grep 的上下文消耗：

### 技巧 1：缩小搜索范围

```
❌ 搜全项目:  Grep "search" ./              → 881 行, ~35,895 tokens
✅ 限定目录:  Grep "search" ./src/          → 41 行, ~1,038 tokens
✅ 限定文件:  Grep "search" ./src/index1/search.py  → 4 行, ~200 tokens
```

### 技巧 2：用更精确的 pattern

```
❌ 宽泛:     Grep "search"                → 881 行
✅ 精确:     Grep "async def search"      → 1 行
✅ 正则:     Grep "def .*search.*query"   → 1 行
```

### 技巧 3：用 Glob 先找文件，再读

```
❌ 盲搜:     Grep "database" 全项目        → 数百行
✅ 先定位:   Glob "**/db.py"              → 1 个文件   ~20 tokens
            Read src/index1/db.py:1-50   → 类定义     ~200 tokens
```

### 技巧 4：用 files_with_matches 模式

```
❌ 返回内容:  Grep "embed" (content)       → 所有匹配行  ~6,000 tokens
✅ 只返回文件: Grep "embed" (files_with_matches) → 文件列表 ~200 tokens
```

先知道在哪些文件，再按需 Read。

### 技巧 5：用 head_limit 限制结果

```
❌ 全部返回:  Grep "TODO" → 可能几百行
✅ 只看前 10: Grep "TODO" head_limit=10  → 最多 10 行
```

## 上下文消耗速查表

| 操作 | 典型上下文消耗 | 适用场景 |
|------|-------------|---------|
| `docs_search`（top 5） | ~460 tokens | 语义/探索 |
| `Grep` 精确标识符 | ~100 tokens | 已知函数名 |
| `Grep` 常见词（全项目） | ~5,000–35,000 tokens | 避免！ |
| `Grep` 常见词（限定目录） | ~500–1,000 tokens | 可接受 |
| `Grep` files_with_matches | ~100–200 tokens | 先看文件列表 |
| `Glob` 找文件 | ~50–200 tokens | 定位文件 |
| `Read` 读文件 | ~200–2,000 tokens | 按需读取 |

## 一句话总结

```
会用 index1:    先问"在哪" → 再看代码    ~1,000 tokens/次查询
不会用 index1:  直接搜全项目            ~10,000 tokens/次查询
省 10 倍上下文 = 对话能多走 10 倍远
```
