docs/codegraph-guide.md

# CodeGraph 使用指南：从安装到实战

> 官方仓库：[colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)
>
> 作者：Colby McHenry
>
> 最新版本：v0.9.x（持续更新中）

---

## 一、项目背景：CodeGraph 是什么？

CodeGraph 是一个**本地优先的代码智能库 + CLI 工具 + MCP 服务器**。它用 tree-sitter 解析你的代码库，将符号（函数、类、变量等）、边（调用、继承、导入等）和文件结构存储到 SQLite（带 FTS5 全文搜索）中，然后通过 MCP 协议暴露给 AI 编程助手使用。

### 核心价值

传统 AI 编程助手（Claude Code、Cursor、Codex 等）在回答"X 函数被谁调用了？""如何从 A 走到 B？"这类代码结构问题时，需要反复 `grep`、`Read` 文件、甚至启动 Explore 子代理，这会消耗大量 token 和时间。

CodeGraph 的做法是：**提前建好代码知识图谱**，AI 只需调用几个 MCP 工具就能直接拿到答案 — 零文件读取、零 grep。

### 基准测试结果

官方在 7 个真实仓库上做了 A/B 测试（Opus 4.8，每组跑 4 次取中位数）：

| 指标 | 提升 |
|------|------|
| 费用 | **平均节省 25%** |
| Token 消耗 | **减少 57%** |
| 响应速度 | **快 23%** |
| 工具调用次数 | **减少 62%** |

### 支持的编程语言

TypeScript/JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Objective-C、Swift、Kotlin、Dart、Lua/Luau、Svelte、Vue、Liquid、Pascal/Delphi 等 **20+ 种语言**。

### 支持的框架路由识别

Django、Flask、FastAPI、Express、Rails、Spring、Gin、Axum、ASP.NET、React Router、SvelteKit、Vue/Nuxt 等 **14 种框架**。

### 关键特性

- **100% 本地运行** — 代码不离开你的机器，无需 API Key
- **零配置** — 无需配置文件，根据文件扩展名自动识别语言
- **确定性提取** — 基于 tree-sitter AST 结构提取，不依赖 LLM 总结
- **混合 iOS/React Native/Expo 桥接** — 支持 Swift↔ObjC、React Native Bridge、Expo Modules 等跨语言桥接

---

## 二、安装方式

### 方式一：自包含安装脚本（推荐，无需 Node.js）

#### Linux / macOS

```bash
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
```

这会：
- 下载自包含的 Node 运行时 + CodeGraph 二进制
- 安装到 `~/.codegraph/`
- 创建符号链接到 `~/.local/bin/codegraph`
- 自动检测系统（Darwin/Linux）和架构（arm64/x64）

环境变量控制：
- `CODEGRAPH_VERSION` — 指定安装版本
- `CODEGRAPH_INSTALL_DIR` — 自定义安装路径
- `CODEGRAPH_BIN_DIR` — 自定义二进制目录

**升级**：重新运行安装命令即可。
**卸载**：

```bash
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh -s -- --uninstall
```

#### Windows（PowerShell）

```powershell
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
```

安装到 `%LOCALAPPDATA%\codegraph\current\`，自动添加到用户 PATH。

同样支持 `CODEGRAPH_VERSION`、`CODEGRAPH_INSTALL_DIR` 环境变量。

### 方式二：通过 npm（需要 Node.js）

```bash
# 零安装（一次运行）
npx @colbymchenry/codegraph

# 全局安装
npm install -g @colbymchenry/codegraph
```

### 平台支持

| 平台 | 架构 |
|------|------|
| Windows | x64, arm64 |
| macOS | x64, arm64 (Apple Silicon) |
| Linux | x64, arm64 |

### 安装后的交互式配置

安装完成后，运行 `codegraph`（不带参数）或 `codegraph install` 会启动交互式安装向导：

1. **自动检测已安装的 AI 代理**（Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity、Kiro）
2. **选择要配置的代理**
3. **选择全局还是项目级配置**
4. **自动写入 MCP 服务器配置**到对应代理的配置文件
5. **为 Claude Code 设置 auto-allow 权限**
6. **初始化当前项目的 `.codegraph/` 索引**

非交互式标志：

```bash
codegraph install --yes                    # 全部默认
codegraph install --target=claude,cursor   # 指定代理
codegraph install --location=global        # 全局安装
codegraph install --no-permissions         # 跳过权限设置
```

---

## 三、基本使用

### 初始化项目

```bash
cd your-project

# 创建 .codegraph/ 并立即构建索引
codegraph init -i

# 只创建 .codegraph/（之后手动 codegraph index）
codegraph init

# 删除 .codegraph/
codegraph uninit
```

### CLI 命令一览

```bash
codegraph index [path]             # 完整索引（--force 强制重建）
codegraph sync [path]              # 增量更新
codegraph status [path]            # 查看索引统计
codegraph query <搜索词>           # 搜索符号（--kind, --limit, --json）
codegraph files [path]             # 查看文件结构（--format, --filter, --max-depth）
codegraph context <任务描述>       # 为 AI 构建代码上下文（--format, --max-nodes）
codegraph callers <符号>           # 查找谁调用了某个函数
codegraph callees <符号>           # 查找某个函数调用了谁
codegraph impact <符号>            # 影响范围分析
codegraph affected [文件...]       # 找到受变更影响的测试文件
codegraph serve --mcp              # 启动 MCP 服务器（stdio 传输）
```

### 10 个 MCP 工具（AI 代理可用）

| 工具 | 功能 |
|------|------|
| `codegraph_search` | 按名称搜索符号（FTS5 全文搜索） |
| `codegraph_context` | 为任务构建相关代码上下文 |
| `codegraph_trace` | 追溯两个符号之间的调用路径 |
| `codegraph_callers` | 找调用者 |
| `codegraph_callees` | 找被调用者 |
| `codegraph_impact` | 分析修改影响范围 |
| `codegraph_node` | 获取符号详情/源码 |
| `codegraph_explore` | 获取一组相关符号的源码 |
| `codegraph_files` | 索引化文件树（比文件系统扫描更快） |
| `codegraph_status` | 索引健康检查 |

### 默认排除规则

以下目录/文件默认不会被索引：

- `node_modules`、`vendor`、`dist`、`build`、`target`
- `.venv`、`Pods`、`.next`、`__pycache__`
- `.gitignore` 中列出的内容
- 大于 1MB 的文件

如果想将 `.gitignore` 中排除的目录重新纳入索引，可在 `.gitignore` 中使用 `!` 否定模式：

```gitignore
# .gitignore
vendor/

# 但这一部分需要索引
!vendor/my-internal-lib/
```

---

## 四、文件监听机制详解

> **这是之前重点讨论过的问题，务必理解。**

### 监听原理

CodeGraph 使用 **chokidar**（操作系统原生文件 API 的薄封装）来监听文件变更：

- **macOS**：FSEvents
- **Linux**：inotify
- **Windows**：ReadDirectoryChangesW

### 三层同步机制

1. **文件监听 + 防抖自动同步** — 捕获每个源文件的创建/修改/删除事件。在防抖窗口（默认 **2000ms**，可通过 `CODEGRAPH_WATCH_DEBOUNCE_MS` 调整，范围 [100ms, 60s]）结束后触发增量索引。连续的编辑会被合并为一次同步。

2. **文件级过期提示** — 在防抖窗口期间，MCP 工具响应中如果引用了尚未同步的文件，会添加 ⚠️ 横幅提示 AI 代理直接读取该文件。

3. **连接时追补** — MCP 服务器（重新）连接时，在回答第一个查询前先做一次快速的 `(size, mtime)` + 内容哈希对比，吸收离线下产生的编辑。

### 守护进程模式（v0.9.5+）

同一项目中的多个 AI 代理共享**一个**后台守护进程，它持有单一的文件监听器、SQLite 连接和 tree-sitter 预热 — 避免 N 个独立副本同时运行。守护进程脱离会话运行，空闲超时（默认 5 分钟，可通过 `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` 调整）后自动退出。

环境变量：
- `CODEGRAPH_NO_DAEMON=1` — 退出守护进程共享模式

---

## 五、文件监听的问题与解决方案

### 问题 1：Linux inotify 耗尽（Issue #276）

**症状**：在大型仓库中，`codegraph` 消耗大量 inotify watches，导致系统无法为其他应用监听文件。

**根因**：早期版本对项目中所有目录（包括 `node_modules/`、`dist/` 等）都注册了 inotify 监听，导致超出内核的每用户 inotify watch 上限。

**修复（v0.9.5+）**：
- 使用 chokidar 的 `ignored` 回调，在注册 inotify watch **之前**就过滤掉排除目录
- 排除集合使用索引器的 `buildDefaultIgnore`（内置默认值 + 项目 `.gitignore`）
- `node_modules/`、`dist/`、`.git/`、`build/`、`target/`、`.venv/`、`Pods/`、`__pycache__/`、`.next/` 等绝不会被注册 inotify watch

### 问题 2：WSL2 `/mnt/` 驱动器性能问题（Issue #199）

**症状**：在 WSL2 的 `/mnt/c`、`/mnt/d/` 等 Windows 挂载驱动器上，递归 `fs.watch` 速度极慢（NTFS 通过 9p/drvfs 桥接），可能卡住事件循环，超过 MCP 握手超时（OpenCode 的 30 秒限制）。

**自动处理**：
- 自动检测 WSL2 + `/mnt/` 挂载
- **自动禁用文件监听**
- 提供 git-hook 回退方案

### 问题 3：无 `.gitignore` 的项目（Issue #407）

**症状**：没有 `.gitignore` 的项目，其 `node_modules/`、`build/`、`cache/` 等目录会被监听和索引。

**修复**：添加了内置默认排除项，即使没有 `.gitignore` 也生效。

---

## 六、如何关闭文件监听

有四种方式：

### 方式一：`--no-watch` 标志（推荐）

```bash
codegraph serve --mcp --no-watch
```

这会设置 `CODEGRAPH_NO_WATCH=1`，被监听器和 MCP 服务器共同遵循。

### 方式二：环境变量

```bash
CODEGRAPH_NO_WATCH=1 codegraph serve --mcp
```

显式退出 — 总是覆盖自动检测。

### 方式三：WSL2 自动禁用（仅 WSL2）

在 WSL2 的 `/mnt/*` 挂载驱动器上，文件监听**自动禁用**，无需手动操作。

如果想强制启用：

```bash
CODEGRAPH_FORCE_WATCH=1 codegraph serve --mcp
```

### 方式四：修改代理的 MCP 配置

如果通过安装向导配置了代理，可以在代理的 MCP 配置中给 `codegraph serve --mcp` 命令加上 `--no-watch` 参数：

**Claude Code**（`.mcp.json` 或 `~/.claude.json`）：

```json
{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp", "--no-watch"]
    }
  }
}
```

### 关闭监听后如何保持索引更新？

监听关闭后，CodeGraph 不会自动同步代码变更。需要手动或通过其他方式触发同步：

1. **手动同步**：`codegraph sync`
2. **Git Hook 回退**：CodeGraph 安装向导提供了 Git Hook 方案（post-commit、post-merge、post-checkout），在 git 操作后自动运行 `codegraph sync`
3. **Claude Code Hooks**：见下一节

---

## 七、Claude Code 集成：添加 Hooks 实现自动同步

> 注意：旧版 CodeGraph（v0.8 之前）使用 `PostToolUse`/`Stop` hooks（`mark-dirty` + `sync-if-dirty` 子命令），这些已在 v0.8+ 中**移除**（因为这些 CLI 子命令已不存在，会导致每次交互都报错）。新版由文件监听器驱动同步。下面的 Hooks 方案是**独立的**自动化方案，适用于关闭了文件监听的场景。

### Claude Code Hooks 配置位置

- **全局**（对所有项目生效）：`~/.claude/settings.json`
- **项目级**（仅当前项目）：`.claude/settings.json`

### 方案 A：每次文件编辑后同步（轻量）

在 Claude Code 的 `settings.json` 中添加 `PostToolUse` Hook，匹配 Edit/Write 工具，检查 `.codegraph` 目录是否存在，存在则运行 `codegraph sync`：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'test -d .codegraph && codegraph sync --quiet || true'"
          }
        ]
      }
    ]
  }
}
```

- `matcher: "Edit|Write"` — 匹配 Claude 的 Edit 和 Write 工具
- `test -d .codegraph && codegraph sync --quiet` — 先检查 `.codegraph` 是否存在，存在才执行同步
- `--quiet` 参数减少输出噪音
- `|| true` 确保即使同步失败也不会阻断 Claude 的响应流

### 方案 B：每轮对话结束后同步（更高效，推荐）

使用 `Stop` Hook，在 Claude 每次完成响应后统一同步一次（而不是每次编辑都同步）：

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'test -d .codegraph && codegraph sync --quiet || true'"
          }
        ]
      }
    ]
  }
}
```

这个方案更推荐，因为：
- 一轮对话中可能有多次 Edit/Write，`Stop` Hook 将多次变更合并为一次同步
- 不会增加 Claude 响应中的等待时间（Hook 在 Claude 输出完成后运行）
- 与文件监听器的防抖策略思路一致

### 方案 C：两者结合（最稳妥）

同时使用 `PostToolUse`（捕获每次编辑）和 `Stop`（确保最终一致），`codegraph sync` 本身是增量操作，重复执行成本很低：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'test -d .codegraph && codegraph sync --quiet || true'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'test -d .codegraph && codegraph sync --quiet || true'"
          }
        ]
      }
    ]
  }
}
```

### 验证 Hooks 是否生效

1. 确保项目中已有 `.codegraph/` 目录（运行 `codegraph init -i`）
2. 运行 `codegraph status` 查看当前索引状态
3. 让 Claude Code 修改项目中的某个文件
4. 修改完成后，运行 `codegraph status` 再次检查，应该能看到节点数/边数的变化

---

## 八、最佳实践

### 1. 大型 Java 项目的额外排除

CodeGraph 默认不排除 `lib/` 和 `out/` 目录（这些在 Java 项目中可能存在数万个 class 文件）。建议在项目根目录创建 `.codegraphignore`：

```
lib/
out/
.gradle/
```

### 2. 合理使用监听策略

| 场景 | 推荐方案 |
|------|----------|
| Linux/macOS 本地开发 | 默认启用文件监听（自动防抖） |
| WSL2 `/mnt/*` 挂载 | 自动禁用监听 + Git Hook 回退 |
| 大型单体仓库（10 万+ 文件） | `--no-watch` + Claude Code Hooks |
| 服务器/CI 环境 | `--no-watch` + `codegraph sync` |

### 3. MCP 权限配置

为了更好的体验，建议在 Claude Code 中开启 CodeGraph 所有工具的 auto-allow 权限。CodeGraph 的安装向导默认会帮你做这件事。手动配置方式：

在 `~/.claude/settings.json` 或 `.claude/settings.json` 中添加：

```json
{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_context",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}
```

---

## 九、相关资源

- 官方仓库：[github.com/colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)
- 官方文档：[codegraph.dev](https://codegraph.dev)
- npm：[@colbymchenry/codegraph](https://www.npmjs.com/package/@colbymchenry/codegraph)
- 环境变量参考：`codegraph serve --help`

---

> 最后更新：2026-06-01
> 基于 CodeGraph v0.9.x