# 快速开始

index1 是 AI 的项目知识库。BM25 + 向量混合搜索，< 200ms 响应。

## 安装

**一键安装（推荐）**：

```bash
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/gladego/index1/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/gladego/index1/main/scripts/install.ps1 | iex
```

脚本会自动检测 Python、通过 pipx 安装、配置 Ollama、创建默认配置。

**手动安装**：

```bash
pipx install index1    # 推荐
# 或: pip install index1
```

> macOS 默认禁止全局 `pip install`，请用 [pipx](https://pipx.pypa.io/)：
> - macOS: `brew install pipx`
> - Linux: `pip install --user pipx && pipx ensurepath`
> - Windows: `scoop install pipx` 或 `pip install --user pipx`

## 第一次使用

### 1. 索引项目

```bash
index1 index ./src ./docs
```

index1 会扫描所有支持的文件类型，自动分块、提取符号、生成向量。

### 2. 搜索

```bash
index1 search "如何使用认证 API"
```

返回按相关度排序的 top-k 结果，包含文件路径、所属章节、内容摘要。

### 3. 查看状态

```bash
index1 status
```

显示索引统计：文档数、片段数、集合列表、最近索引记录。

## 接入 Claude Code

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "index1": {
      "type": "stdio",
      "command": "index1",
      "args": ["serve"]
    }
  }
}
```

重启 Claude Code，6 个 MCP 工具立即可用：`recall`（搜索）、`learn`（记录）、`read`（读取）、`status`（状态）、`reindex`（重建）、`config`（配置）。

> 详见 [MCP 工具参考](mcp-tools.md)

## 接入其他 AI 工具

**支持 MCP 的工具**（Cursor、Windsurf、Cline 等）：使用上面相同的 MCP 配置。

**CLI 模式**（任何工具可用）：

```bash
index1 search "认证流程"
index1 web    # 启动 Web UI (http://localhost:6888)
```

## Embedding 后端

index1 默认使用 **ONNX 后端**（bge-small-en-v1.5, 384 维），无需安装任何外部服务即可向量搜索。

如需更好的中文和多语言支持，推荐安装 Ollama：

```bash
brew install ollama           # macOS
ollama pull nomic-embed-text  # 下载默认模型
```

| 后端 | 优点 | 缺点 |
|------|------|------|
| ONNX（默认） | 零配置，开箱即用 | 英文模型，中文支持有限 |
| Ollama | 中文优秀，模型可选 | 需要额外安装，占用 ~500MB 内存 |
| 纯 BM25 | 零依赖 | 无语义搜索，不支持跨语言 |

切换后端：

```bash
index1 init              # 交互式选择
index1 init --backend ollama  # 直接切换
```

> 详见 [配置参考](configuration.md)

## 下一步

- [代码搜索](features/code-search.md) — 搜索策略、代码图、文件类型
- [AI 记忆](features/ai-memory.md) — 认知事实、自动学习、跨会话持久化
- [CLI 命令参考](cli-reference.md) — 所有命令和选项
- [MCP 工具参考](mcp-tools.md) — 6 个 MCP 工具详解
- [配置参考](configuration.md) — 配置项、模型选择、性能调优
