# Claude Code 集成指南

## 安装方式

### 方式 A：Marketplace 一键安装（推荐）

在 Claude Code 中执行：

```
/plugin marketplace add gladego/index1-plugins
/plugin install index1
```

或者用交互式界面：输入 `/plugin` 打开插件管理器，在 Discover 标签页找到 index1 安装。

安装后重启 Claude Code。插件会自动：
1. 检测本机是否有 `index1` 命令
2. 没有则自动通过 pipx/pip 安装 Python 包
3. 启动 MCP Server，注入 5 个搜索工具

> 首次安装后，还需要选择 embedding 后端并索引项目：
> ```bash
> index1 init                        # 选择 embedding 后端（默认 Ollama）
> cd your-project
> index1 index ./src ./docs          # 索引项目文件
> ```

### 方式 B：手动配置 MCP Server

如果你更喜欢手动配置，先安装 Python 包：

```bash
pipx install index1
index1 init                            # 选择 embedding 后端
```

然后配置 MCP（二选一）：

**项目级（推荐）** — 在项目根目录创建 `.mcp.json`：

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

**全局** — 添加到 `~/.claude/settings.json`：

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

> 如果 `index1` 不在 PATH 中：`which index1`（macOS/Linux）或 `where.exe index1`（Windows）获取完整路径。

重启 Claude Code 后，5 个 `docs_*` 工具即可使用。

## 安装后三步

<h3>⬛ 第 1 步：配置 MCP — 让 AI 能调用 index1</h3>

<h3>⬛ 第 2 步：添加搜索规则 — 让 AI 知道何时该调用</h3>

<h3>⬜ 第 3 步（可选）：创建 Skill — 常用操作一键触发</h3>

<h2 style="color:red">⚠️ 只做第 1 步 = 装了工具没教 AI 怎么用。第 2 步才是关键！</h2>

---

## 第 2 步：添加搜索规则

> **这是最关键的一步。** 没有规则，AI 有了工具但不知道什么时候该用，经常白白 Grep 几万 tokens。

在项目的 **`.claude/CLAUDE.md`** 中添加以下内容：

```markdown
## 搜索策略

本项目已配置 index1 MCP Server（docs_search 等 5 个工具）。搜索代码时遵循：

1. 已知标识符（函数名/类名/文件名）→ 直接 Grep/Glob（4ms）
2. 探索性问题（"XX 怎么实现的"）→ 先 docs_search 定位方向，再 Grep 精确查找
3. 中文查英文代码 → 必须用 docs_search（Grep 不支持跨语言）
4. 高频关键词（预期匹配 > 50 行）→ 优先 docs_search（节省 90%+ 上下文）
```

Claude Code 每次新对话都会读取 `CLAUDE.md`，自动按策略执行。

### 有规则 vs 没规则

```
❌ 没有规则（只做了第 1 步）：
   你: "搜索功能怎么实现的？"
   AI: Grep "search" 全项目 → 881 行 → 35,895 tokens 💥
   结果: 上下文爆炸，对话很快触顶

✅ 有规则（做了第 2 步）：
   你: "搜索功能怎么实现的？"
   AI: docs_search("搜索功能") → 5 条 → 460 tokens ✓
       Grep "async def search" search.py → 1 行 → 100 tokens ✓
       Read search.py:97-200 → 400 tokens ✓
   结果: 总共 960 tokens，节省 97%
```

### 上下文消耗速查表

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

---

## 第 3 步（可选）：创建 Skill

Skill 是 Claude Code 的快捷命令（`/命令名`），适合把常用操作封装成一键触发。

### Skill 1：`/reindex` — 重建索引

创建 `.claude/skills/reindex.md`：

```markdown
---
name: reindex
description: 重建 index1 项目索引
---

执行以下步骤：

1. 运行 `index1 index ./src ./docs --force`
2. 运行 `index1 status` 查看结果
3. 报告索引的文档数和片段数
```

使用：在对话中输入 `/reindex`，AI 自动执行索引重建。

### Skill 2：`/isearch` — 语义搜索

创建 `.claude/skills/isearch.md`：

```markdown
---
name: isearch
description: 用 index1 语义搜索项目代码
---

使用 docs_search 搜索用户的问题。

搜索后：
1. 列出 top-5 结果的文件名和摘要
2. 如果用户需要详细代码，用 Grep 在对应文件中精确查找
3. 用 Read 读取相关代码段
```

使用：`/isearch 认证怎么实现的`

### Skill 3：`/doctor` — 诊断环境

创建 `.claude/skills/doctor.md`：

```markdown
---
name: doctor
description: 诊断 index1 环境状态
---

依次运行以下命令并报告结果：

1. `index1 doctor` — 环境诊断
2. `index1 status` — 索引状态
3. `ollama list` — 已安装模型

如果发现问题，给出修复建议。
```

### 规则 vs Skill 怎么选

| | 规则（CLAUDE.md） | Skill（/命令） |
|---|---|---|
| 触发方式 | **自动**，每次对话都生效 | 手动，需要输入 `/命令` |
| 适合场景 | 搜索策略、行为指引 | 具体操作、一键执行 |
| 优先级 | **必做** | 可选，锦上添花 |

**结论：规则是基础（必须有），Skill 是快捷方式（可选）。**

---

## 验证集成

```
你: 用 docs_status 看一下索引状态
→ 应返回文档数和片段数

你: 搜索功能怎么实现的？
→ AI 应先调用 docs_search，而不是 Grep 全项目
```

如果 AI 直接 Grep 全项目而不用 docs_search，说明第 2 步的规则没生效——检查 `.claude/CLAUDE.md` 是否存在且内容正确。

## 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| 工具没出现 | MCP 配置错误 | 检查 `.mcp.json` 格式和 index1 路径 |
| AI 不用 docs_search | 没加搜索规则 | **做第 2 步**，添加 CLAUDE.md |
| 搜索无结果 | 未索引 | `index1 index ./src ./docs` |
| 中文搜索 0 结果 | 无 Ollama 或模型不支持 | `ollama pull bge-m3`，重建索引 |
| 搜索很慢（>1s） | 首次冷启动 | 正常，后续 < 200ms |
| 工具报错 | index1 版本旧 | `pipx upgrade index1` |

## 诊断命令

```bash
index1 doctor              # 一键诊断环境问题
index1 status              # 查看索引状态
ollama list                # 检查模型是否已拉取
curl http://localhost:11434   # 检查 Ollama 是否运行
```

## 完整项目结构

```
项目根目录/
├── .mcp.json                    ← 第 1 步：MCP 配置
├── .claude/
│   ├── CLAUDE.md                ← 第 2 步：搜索规则（关键！）
│   └── skills/                  ← 第 3 步：快捷 Skill（可选）
│       ├── reindex.md
│       ├── isearch.md
│       └── doctor.md
├── src/
└── docs/
```
