docs: add CodeGraph comprehensive guide (安装/使用/文件监听/Claude Code Hooks)

2026-06-01 09:24:40 +08:00
commit 57f1b67cdc
1 changed files with 472 additions and 0 deletions
@@ -0,0 +1,472 @@
+# 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