CodeGraph使用指南-平芜编程栈

CodeGraph 使用指南

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

一、是什么

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

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

二、安装

Windows（PowerShell）

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

macOS / Linux

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

已有 Node.js 环境

npx @colbymchenry/codegraph# 零安装，直接使用npminstall-g@colbymchenry/codegraph# 全局安装

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

三、快速上手（3 步）

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

codegraphinstall--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=$(gitdiff--name-only HEAD|codegraph affected--stdin--quiet)if[-n"$AFFECTED"];thennpx vitest run$AFFECTEDfi

七、语言支持（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"]}}