CodeGraph使用指南

作者：Keysqiu

创建时间：2026-05-25 16:46:26 最后一次修改时间：2026-05-25 16:46:26

Categories： Tags：

CodeGraph 使用指南

colbymchenry/codegraph — 为编程智能体预构建的代码知识图谱，更少 Token、更少工具调用，100% 本地运行。

一、是什么

CodeGraph 把你的代码库解析成一张语义知识图谱（节点 = 函数/类/方法，边 = 调用/导入/继承），存入本地 SQLite 数据库。AI 编程智能体（Claude Code、Cursor、Codex CLI 等）直接查询图谱，而不是反复用 grep/Read 扫描文件。

核心数据（7个真实代码库测试） ：平均 35% 成本降低 · 57% Token 减少 · 46% 更快的响应 · 71% 更少的工具调用。

二、安装

Windows（PowerShell）

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

macOS / Linux

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

已有 Node.js 环境

npx @colbymchenry/codegraph          # 零安装，直接使用

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

无需 Node.js，安装脚本自带运行时，无需编译。

三、快速上手（3 步）

第 1 步：安装并配置智能体

codegraph install --yes

交互式安装器会自动检测你已安装的编程智能体（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent），并自动配置 MCP 服务器连接和指令文件。

第 2 步：在项目目录中初始化

cd 你的项目目录
codegraph init -i

这会构建项目的知识图谱索引（.codegraph/codegraph.db）。索引自动遵循 .gitignore，node_modules 等不会进入图谱。

第 3 步：重启智能体

重启 Claude Code / Cursor / Codex CLI 等工具，MCP 服务器会自动加载。之后只要项目里有 .codegraph/ 目录，智能体就会自动使用 CodeGraph 工具。

四、核心命令速查

命令	作用
`codegraph install`	运行交互式安装器
`codegraph uninstall`	从所有智能体中移除 CodeGraph
`codegraph init [路径]`	在项目中初始化（`-i` 交互模式）
`codegraph uninit [路径]`	从项目中移除 CodeGraph
`codegraph index [路径]`	全量索引（`--force` 强制重建）
`codegraph sync [路径]`	增量更新索引
`codegraph status [路径]`	查看索引统计信息
`codegraph query <关键词>`	按名称搜索符号
`codegraph context <任务描述>`	为 AI 构建上下文
`codegraph callers <符号名>`	查找谁调用了某函数
`codegraph callees <符号名>`	查找某函数调用了谁
`codegraph impact <符号名>`	变更影响分析
`codegraph affected [文件...]`	查找受改动影响的测试文件
`codegraph serve --mcp`	启动 MCP 服务器

五、MCP 工具详解（智能体可用）

智能体在对话中可调用以下 10 个工具：

工具	用途	典型场景
`codegraph_context`	一次调用获取入口点、相关符号和代码片段	架构理解任务的首选
`codegraph_trace`	追踪两个符号之间的完整调用路径	“X 是如何调用到 Y 的？”
`codegraph_search`	按名称搜索符号	“找到 UserService”
`codegraph_callers`	找出谁调用了某个函数	了解调用方
`codegraph_callees`	找出函数调用了什么	了解依赖
`codegraph_impact`	分析修改某个符号的影响范围	改动前风险评估
`codegraph_explore`	批量获取多个相关符号的源码	批量查看相关代码
`codegraph_node`	获取单个符号详情	查看函数签名
`codegraph_files`	获取索引的文件结构	比文件系统扫描更快
`codegraph_status`	检查索引状态和统计	确认图谱是否最新

六、实际使用示例

场景 1：理解架构

对 Claude Code 说：

“How does the extension host communicate with the main process?”

智能体会先用 codegraph_context 定位相关区域，再用 codegraph_trace 追踪调用路径，一次对话即可获得完整答案，而不是启动多个 Explore 子代理去扫描文件。

场景 2：影响分析

先在终端用 CLI 分析：

codegraph impact handleRequest

输出该函数的所有调用方、被调用方及其依赖链，评估改动风险。

场景 3：CI 集成

#!/usr/bin/env bash
# 只运行受影响的测试
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

七、语言支持（19+）

TypeScript · JavaScript · Python · Go · Rust · Java · C# · PHP · Ruby · C · C++ · Swift · Kotlin · Scala · Dart · Svelte · Vue · Lua · Luau

八、工作原理

你的代码 → tree-sitter 解析 AST → 提取节点(函数/类)和边(调用/导入)
         → SQLite 存储 + FTS5 全文搜索
         → 引用解析(调用→定义)
         → 原生文件监视器自动同步(2秒防抖)
         → MCP 服务器暴露工具给智能体

九、手动配置（高级）

如需手动配置，在 ~/.claude.json 中添加：

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

~/.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"
    ]
  }
}

十、常见问题

Q：索引慢怎么办？
A：检查 node_modules 等大目录是否已在 .gitignore 中。使用 --quiet 减少输出开销。

Q：MCP 连接不上？
A：确保项目已 codegraph init，确认配置路径正确，手动运行 codegraph serve --mcp 测试。

Q：符号缺失？
A：MCP 服务器会自动同步（等待几秒）。手动运行 codegraph sync。确认文件语言是否在支持列表中。

Q：如何卸载？
A：codegraph uninstall 从智能体中移除配置，codegraph uninit 删除项目中的 .codegraph/ 目录。

GitHub 仓库：https://github.com/colbymchenry/codegraph
许可证：MIT
本周新增 Star：18,136 · 总 Star：23,249

Windows上用RTK给你的AI编程助手节省Token

GitHub 提交 Pull Request (PR)完整流程指南