sxebu/docs

Fork 0

Files

T

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

2026-06-01 09:24:40 +08:00

15 KiB

Raw Permalink Blame History

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

官方仓库：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

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 — 自定义二进制目录

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

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

Windows（PowerShell）

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

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

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

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

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

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

平台支持

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

安装后的交互式配置

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

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

非交互式标志：

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

三、基本使用

初始化项目

cd your-project

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

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

# 删除 .codegraph/
codegraph uninit

CLI 命令一览

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
vendor/

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

四、文件监听机制详解

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

监听原理

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

macOS：FSEvents
Linux：inotify
Windows：ReadDirectoryChangesW

三层同步机制

文件监听 + 防抖自动同步 — 捕获每个源文件的创建/修改/删除事件。在防抖窗口（默认 2000ms，可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 调整，范围 [100ms, 60s]）结束后触发增量索引。连续的编辑会被合并为一次同步。
文件级过期提示 — 在防抖窗口期间，MCP 工具响应中如果引用了尚未同步的文件，会添加 ⚠️ 横幅提示 AI 代理直接读取该文件。
连接时追补 — 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` 标志（推荐）

codegraph serve --mcp --no-watch

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

方式二：环境变量

CODEGRAPH_NO_WATCH=1 codegraph serve --mcp

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

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

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

如果想强制启用：

CODEGRAPH_FORCE_WATCH=1 codegraph serve --mcp

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

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

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

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

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

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

手动同步：codegraph sync
Git Hook 回退：CodeGraph 安装向导提供了 Git Hook 方案（post-commit、post-merge、post-checkout），在 git 操作后自动运行 codegraph sync
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：

{
  "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 每次完成响应后统一同步一次（而不是每次编辑都同步）：

{
  "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 本身是增量操作，重复执行成本很低：

{
  "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 是否生效

确保项目中已有 .codegraph/ 目录（运行 codegraph init -i）
运行 codegraph status 查看当前索引状态
让 Claude Code 修改项目中的某个文件
修改完成后，运行 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 中添加：

{
  "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
官方文档：codegraph.dev
npm：@colbymchenry/codegraph
环境变量参考：codegraph serve --help

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

15 KiB Raw Permalink Blame History Unescape Escape