# 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` 全局安装，请使用 [pipx](https://pipx.pypa.io/)：
> - macOS: `brew install pipx`
> - Linux: `pip install --user pipx && pipx ensurepath`
> - Windows: `scoop install pipx` 或 `pip install --user pipx`

## 快速开始

```bash
ollama pull nomic-embed-text      # 可选，用于语义搜索
index1 index ./docs ./src
index1 search "清算接口怎么用"
```

> Ollama 可选。没有它，index1 自动降级为 BM25 纯关键词搜索。

## AI 工具集成

### Claude Code

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

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

重启 Claude Code，五个 `docs_*` 工具即可使用（`docs_search`、`docs_get`、`docs_status`、`docs_reindex`、`docs_config`）。

> 完整指南：[Claude Code 集成](docs/integration-claude-code.md) — MCP 配置、搜索策略、CLAUDE.md 设置、省上下文技巧

### 其他 AI 工具（OpenClaw、Cursor、Windsurf、Cline...）

**支持 MCP 的工具**：将上面的配置添加到对应工具的 MCP 设置中即可。

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

```bash
index1 search "认证怎么实现的"
index1 get <chunk_id>
```

> 完整指南：[其他 AI Agent 集成](docs/integration-other-agents.md) — 各工具配置、CLI 用法、Web UI

### Ollama（推荐安装）

```bash
# macOS
brew install ollama && ollama pull nomic-embed-text

# Linux
curl -fsSL https://ollama.ai/install.sh | sh && ollama pull nomic-embed-text

# Windows — 从 https://ollama.ai/download 下载安装后：
ollama pull nomic-embed-text
```

> | 模型 | 维度 | 磁盘 | 内存 | 适用场景 |
> |------|------|------|------|---------|
> | `all-minilm` | 384 | ~45 MB | ~250 MB | 英文为主，低配设备 |
> | `nomic-embed-text`（默认） | 768 | ~270 MB | ~500 MB | 中英通用 |
> | `bge-m3` | 1024 | ~1.2 GB | ~1.2 GB | **中文最优**，100+ 语言 |
>
> 不安装 Ollama 时，index1 降级为 BM25 纯关键词搜索（无语义/跨语言支持）。

## CLI 命令

```bash
index1 index <paths...>          # 索引文件/目录
index1 search <query>            # 混合搜索
index1 status                    # 查看索引统计
index1 config [key] [value]      # 查看/修改配置
index1 serve                     # 启动 MCP Server（stdio）
index1 web                       # 启动 Web UI（端口 6888）
index1 watch <paths...>          # 监听文件变更，自动索引
```

## 支持的文件类型

`.md` `.markdown` `.py` `.rs` `.js` `.ts` `.jsx` `.tsx` `.txt`

每种类型使用结构感知分块：Markdown 按标题、Python 按 AST、Rust/JS/TS 按正则模式。

## 配置

配置文件：`~/.claude-index1/config.yaml`

```yaml
embedding_model: nomic-embed-text   # Ollama 模型
embedding_dim: 768
ollama_url: http://localhost:11434
top_k: 10                           # 每次查询返回结果数
collection: default                 # 命名空间隔离
```

项目级覆盖：在项目根目录放置 `.index1.yaml`。

## 架构

```
Claude Code ──► MCP Server (stdio)
                    │
CLI ────────────► 查询引擎 ──► SQLite
                    │           ├── FTS5 (BM25)
Web UI ─────────┘   │           └── sqlite-vec (向量)
                    │
              Ollama Embedding
```

- **存储**：单文件 SQLite（`~/.claude-index1/knowledge.db`）
- **搜索**：BM25 + 向量 + Reciprocal Rank Fusion（k=60）
- **分块**：按文件类型的结构感知切分

## 性能

| 模式 | 冷启动 | 热缓存 |
|------|--------|--------|
| Hybrid（BM25 + 向量） | 40–180 ms | < 1 ms |
| BM25-only（无 Ollama） | ~35 ms* | < 1 ms |
| Grep/Glob（原生工具） | 4 ms | 不适用 |

> \* 首次查询后。第一次冷查询无 Ollama 约 1 秒（连接超时），之后 60 秒内缓存失败状态。

**无 Ollama 时**：冷启动慢 6–8 倍，中文语义搜索**返回 0 条结果**，不支持跨语言查询。

**上下文节省**：index1 返回 top-k 排序结果（~400–500 tokens），而 Grep 返回所有匹配行（常见关键词 ~5,000–35,000 tokens）。宽泛查询下节省 **90–99% 的 LLM 上下文窗口**。

完整测试报告和集成指南：
- [性能基准测试](docs/benchmark-vs-native-tools.zh-CN.md)（[English](docs/benchmark-vs-native-tools.md)）
- [Claude Code 集成指南](docs/integration-claude-code.md) — MCP 配置、搜索策略、CLAUDE.md 设置、省上下文技巧
- [其他 AI Agent 集成指南](docs/integration-other-agents.md) — Windsurf、Cline、CLI、Web UI
- [OpenClaw 集成指南](docs/integration-openclaw.md) | [Cursor 集成指南](docs/integration-cursor.md)

## 常见问题

**Ollama 没运行 / 没安装？**
index1 自动降级为 BM25 纯关键词搜索，但代价很大：
- **冷查询慢 6–8 倍**（连接超时开销）
- 中日韩语义查询**直接返回 0 结果**
- 无法跨语言搜索（中文查英文代码）

强烈建议安装 Ollama：

```bash
# macOS
brew install ollama
ollama pull nomic-embed-text

# Linux
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull nomic-embed-text

# Windows — 从 https://ollama.ai/download 下载安装后：
ollama pull nomic-embed-text
```

Ollama 在本地 11434 端口运行（可配置）。所有数据留在本机，不上传到任何外部服务器。

**安装 vs 不安装 Ollama 的资源对比：**

| | 不安装 Ollama | 安装 Ollama（`nomic-embed-text`） |
|---|---|---|
| **磁盘** | 0 | ~270 MB（模型文件） |
| **内存** | 0 | ~500 MB（运行时） |
| **冷查询** | ~1s（超时）→ ~35ms（缓存后） | 40–180 ms |
| **中日韩搜索** | 返回 0 结果 | 完整语义搜索 |
| **跨语言查询** | 不支持 | 支持（中文查英文代码） |
| **搜索模式** | BM25 纯关键词 | BM25 + 向量混合 |

> Ollama 只在运行时占内存，停止 `ollama serve` 后内存完全释放。磁盘占用取决于模型——存储空间有限的机器可选 `all-minilm`（仅 ~45 MB）。

**如何切换 embedding 模型？**

```bash
index1 config embedding_model <model-name>
index1 index --force ./docs ./src   # 用新模型重建索引
```

**能管理多个项目吗？**
可以，用 `--collection` 隔离命名空间：

```bash
index1 index ./project-a -c proj_a
index1 index ./project-b -c proj_b
index1 search "query" -c proj_a
```

**数据库存在哪里？**
默认：`~/.claude-index1/knowledge.db`。可通过 `index1 config db_path /自定义/路径.db` 或设置 `INDEX1_HOME` 环境变量覆盖。

**从旧版本迁移？**
```bash
mv ~/.index1 ~/.claude-index1
```

**如何重建索引？**

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

**如何监听文件变更？**

```bash
index1 watch ./docs ./src
```

## 贡献

```bash
git clone https://github.com/gladego/index1.git
cd index1
pip install -e ".[dev]"
pytest
```

欢迎 PR。提交前请确保 `pytest` 全部通过。

## 更新日志

### v0.1.0

- BM25 + 向量混合搜索，RRF 融合排序
- 结构感知分块（Markdown、Python、Rust、JS/TS）
- MCP Server 提供 5 个工具，集成 Claude Code
- Web UI 带 Atom Core 动画 Logo
- L1/L2 查询缓存（10 分钟 TTL）
- 文件监听器，自动重索引
- 可选 Rerank（余弦相似度）
- 一键安装脚本

## 系统要求

- Python >= 3.10
- macOS / Linux / Windows
- [Ollama](https://ollama.ai)（可选，用于语义搜索）

## 许可证

[Apache 2.0](LICENSE)
