# 代码搜索

index1 的核心功能：从项目代码中快速找到最相关的内容。

## 搜索原理

index1 使用 **BM25 + 向量混合搜索**，通过 RRF（Reciprocal Rank Fusion）融合两种结果：

```
用户查询
   ├── BM25 全文搜索（关键词匹配，精确快速）
   ├── 向量搜索（语义相似度，理解意图）
   └── RRF 融合（k=60）→ 排序后返回 top-k
```

- **BM25**：精确匹配关键词，对函数名、变量名等标识符搜索效果最好
- **向量搜索**：理解查询语义，支持跨语言搜索（中文查询 → 英文代码）
- **RRF 融合**：综合两种结果，避免单一方法的盲区

## 代码图增强

index1 使用 tree-sitter 提取代码符号（函数、类、方法），构建项目代码图：

- **符号提取**：支持 30 种编程语言的函数/类/方法识别
- **引用解析**：追踪跨文件调用关系
- **PageRank 排序**：被引用越多的符号，搜索权重越高
- **图增强重排**：搜索结果中，包含重要符号的代码片段排名更高

搜索权重（可配置）：

| 权重项 | 默认值 | 说明 |
|--------|--------|------|
| `graph_weight_semantic` | 0.6 | 语义相关度 |
| `graph_weight_pagerank` | 0.2 | 符号重要性 |
| `graph_weight_structural` | 0.2 | 结构关联度 |

查看项目符号和代码图：

```bash
index1 symbols src/main.py     # 查看文件符号列表
index1 symbols --rank           # 按 PageRank 排序 top 20
index1 repo-map                 # 生成项目结构地图
```

> 代码图为可选功能，需安装 `pip install index1[codegraph]`（tree-sitter 依赖）。未安装时自动降级为 Pygments 符号提取，或跳过符号分析。

## 支持的文件类型

| 类型 | 扩展名 | 分块策略 |
|------|--------|----------|
| Markdown | `.md` `.markdown` | 按标题层级分块 |
| Python | `.py` | AST 级别（函数/类边界） |
| Rust | `.rs` | 正则模式（fn/struct/impl） |
| JavaScript | `.js` `.jsx` | 正则模式（function/class） |
| TypeScript | `.ts` `.tsx` | 正则模式（function/class/interface） |
| 纯文本 | `.txt` | 按段落/固定行数 |

每种文件类型使用**结构感知分块**，确保代码片段语义完整。

## 搜索模式

index1 根据 embedding 后端可用性自动选择搜索模式：

| 模式 | 条件 | 能力 |
|------|------|------|
| **hybrid** | Embedding 可用 | BM25 + 向量 + RRF 融合，最佳效果 |
| **bm25_only** | Embedding 不可用 | 纯关键词搜索，不支持语义/跨语言 |

CJK（中日韩）查询会自动调整权重：BM25=0.2, Vector=0.8，因为向量搜索对 CJK 文本效果更好。

## 搜索性能

| 模式 | 冷启动 | 缓存命中 |
|------|--------|----------|
| Hybrid (BM25 + Vector) | 40–180 ms | < 1 ms |
| BM25-only | ~35 ms | < 1 ms |

index1 内置两级缓存：
- **L1 缓存**：完整搜索响应，相同查询直接返回
- **L2 缓存**：embedding 向量，避免重复计算

## 命名空间隔离

使用 `--collection` 隔离不同项目的索引：

```bash
index1 index ./project-a -c proj_a
index1 index ./project-b -c proj_b
index1 search "认证" -c proj_a    # 只搜索 project-a
```

## 搜索策略建议

| 场景 | 推荐方式 | 说明 |
|------|----------|------|
| 已知函数名/类名 | Grep/Glob | 精确匹配更快（~4ms） |
| 探索性问题 | index1 search | 语义搜索找到方向 |
| 中文查英文代码 | index1 search | Grep 不支持跨语言 |
| 高频关键词（>50 结果） | index1 search | 节省 90%+ 上下文 token |
