Skip to content

Latest commit

 

History

History
253 lines (183 loc) · 6.64 KB

integration-claude-code.md

File metadata and controls

253 lines (183 loc) · 6.64 KB

Claude Code 集成指南

安装方式

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

index1 setup

自动完成：

  1. 注册 hooks（SessionStart、UserPromptSubmit、PostToolUse、SessionEnd）
  2. 注册 MCP Server（6 个工具）
  3. 检测并安装缺失的依赖

安装后重启 Claude Code 即可使用。

首次安装后，索引项目文件：

cd your-project
index1 index ./src ./docs

方式 B：手动配置 MCP Server

先安装 Python 包：

pipx install index1

然后配置 MCP（二选一）：

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

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

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

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

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

重启 Claude Code 后，6 个 MCP 工具即可使用：

工具 功能
recall 跨库统一搜索（代码 + 认知事实）
learn 记录 insight 或决策
read 读取文件内容 + 索引元数据
status 索引和认知统计
reindex 重建项目索引
config 查看/修改配置

安装后三步

⬛ 第 1 步：配置 MCP — 让 AI 能调用 index1

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

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

⚠️ 只做第 1 步 = 装了工具没教 AI 怎么用。第 2 步才是关键！

第 2 步：添加搜索规则

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

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

## 搜索策略

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

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

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

有规则 vs 没规则

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

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

上下文消耗速查表

操作 典型消耗 适用场景
recall（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：

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

执行以下步骤：

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

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

Skill 2：/isearch — 语义搜索

创建 .claude/skills/isearch.md：

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

使用 recall 搜索用户的问题。

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

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

Skill 3：/doctor — 诊断环境

创建 .claude/skills/doctor.md：

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

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

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

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

规则 vs Skill 怎么选

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

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

验证集成

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

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

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

故障排查

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

诊断命令

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/