473 lines
15 KiB
Markdown
473 lines
15 KiB
Markdown
# 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
|