# 其他 AI Agent 集成指南

index1 支持任何 AI 工具接入，提供三种方式：MCP Server、CLI 命令行、Web UI。

## 前提条件

```bash
pipx install index1                    # 安装 index1
ollama pull nomic-embed-text           # 推荐，用于语义搜索
index1 index ./src ./docs              # 索引项目文件
```

## 方式一：MCP Server（推荐）

适用于支持 [MCP 协议](https://modelcontextprotocol.io/) 的 AI 工具。接入后，AI 工具可自动调用 index1 的 5 个搜索工具。

### 支持的工具

| 工具 | MCP 支持 | 说明 | 集成指南 |
|------|---------|------|---------|
| [OpenClaw](https://github.com/nicepkg/openclaw) | ✅ 原生 | 开源 Claude Code 替代品 | [详细指南](integration-openclaw.md) |
| [Cursor](https://cursor.com/) | ✅ 原生 | AI 代码编辑器 | [详细指南](integration-cursor.md) |
| [Windsurf](https://codeium.com/windsurf) | ✅ 原生 | AI 代码编辑器 | 见下方 |
| [Cline](https://github.com/cline/cline) | ✅ VS Code 扩展 | 自主编码 Agent | 见下方 |
| [Continue](https://continue.dev/) | ✅ VS Code/JetBrains | 开源 AI 编码助手 | 见下方 |

### Windsurf

编辑 `~/.codeium/windsurf/mcp_config.json`：

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

### Cline (VS Code)

打开 Cline 扩展 → MCP Servers → 添加配置：

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

### 其他 MCP 客户端

任何遵循 MCP 协议的工具，使用以下通用配置：

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

> 如果 `index1` 不在 PATH 中，使用完整路径：
> ```bash
> which index1          # macOS/Linux → 例如 /Users/you/.local/bin/index1
> where.exe index1      # Windows
> ```

### MCP 工具列表

接入后，以下 5 个工具可用：

| 工具 | 说明 | 用法 |
|------|------|------|
| `docs_search` | 混合搜索 | `docs_search(query="认证怎么实现")` |
| `docs_get` | 获取完整片段 | `docs_get(chunk_id=42)` |
| `docs_status` | 索引统计 | 查看文档数、片段数 |
| `docs_reindex` | 重建索引 | 代码更新后刷新 |
| `docs_config` | 查看配置 | 检查当前模型、路径 |

只需一个入口 `docs_search` 即可完成大多数搜索任务。工具自动处理 BM25 关键词匹配 + 向量语义搜索 + 结果融合排序。

## 方式二：CLI 命令行

适用于任何能运行 Shell 命令的 AI 工具，包括不支持 MCP 的工具。

### 基本用法

```bash
# 索引项目（首次，或代码更新后）
index1 index ./src ./docs

# 搜索
index1 search "认证怎么实现的"

# 获取某个片段的完整内容
index1 get <chunk_id>

# 查看索引状态
index1 status
```

CLI 输出纯文本，兼容任何能运行 Shell 命令的环境。

### 在 AI 工具中使用

大多数 AI 编码工具都有终端/Shell 功能。直接在终端中运行即可：

```bash
# 语义搜索（返回 top-k 结果，带相关度评分）
index1 search "数据库连接怎么管理的"

# 限定集合搜索
index1 search "认证" -c my_project

# 查看搜索结果的完整内容
index1 get 42
```

### 集成到脚本

```bash
#!/bin/bash
# 自动索引并搜索
index1 index ./src ./docs --quiet
result=$(index1 search "$1" 2>/dev/null)
echo "$result"
```

## 方式三：Web UI

适用于浏览器访问或需要可视化界面的场景。

```bash
index1 web    # 启动 Web UI，默认端口 6888
```

浏览器访问 `http://localhost:6888`，支持：

- 搜索框输入查询
- 查看搜索结果和相关度评分
- 浏览索引状态和配置

## 选择建议

| 场景 | 推荐方式 | 原因 |
|------|---------|------|
| AI 工具支持 MCP | MCP Server | 最佳体验，工具自动调用 |
| AI 工具不支持 MCP | CLI | 通用，无额外依赖 |
| 团队协作 / 演示 | Web UI | 可视化，易上手 |
| CI/CD 流水线 | CLI | 脚本友好，易集成 |

## 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| `command not found` | index1 不在 PATH | 使用完整路径，或 `pipx ensurepath` |
| 搜索无结果 | 未索引 | `index1 index ./src ./docs` |
| 中文搜索 0 结果 | 无 Ollama | `brew install ollama && ollama pull nomic-embed-text` |
| MCP 连接失败 | 配置路径错误 | 检查 `which index1` 的输出 |
| Web UI 打不开 | 端口占用 | `index1 web --port 6889` |
