关于本笔记

本笔记用于沉淀 CodeGraph 的使用方法与适用场景，目标是把它当作 AI 编程助手的“代码地图”，而不是只记一组命令。

主要参考：

• 网络资料：https://www.helpaio.com/guides/codegraph、https://juejin.cn/post/7641403640108007443#heading-4
• 官方仓库：https://github.com/colbymchenry/codegraph
• 官方文档：https://colbymchenry.github.io/codegraph/

目录

• 项目简介
• 工具特点
• 项目结构树
• 安装与初始化
• 配置文件说明（重点）
• MCP 工具与使用方式
• 推荐工作流
• 使用案例
• 刷新机制与维护
• 与其它工具的对比与选择
• 常见误区与修正
• 我的最小实践模板

项目简介

CodeGraph 是一个面向 AI 编程助手的本地代码知识图谱工具。

它会提前把项目解析成可查询的结构化图谱：函数、类、变量、接口、导入关系、调用关系、继承关系、文件结构与部分框架路由关系，然后通过 CLI 与 MCP Server 暴露给 Claude Code、Cursor、Codex CLI、opencode 等 AI 工具。

一句话：让 AI 先查图谱，再读文件。

传统 AI 理解代码库时，经常会反复执行：

1

glob -> grep -> read file -> 再 grep -> 再 read file

CodeGraph 的思路是把这件事前置：

1

源码 -> Tree-sitter 解析 -> 符号/关系图谱 -> SQLite 本地数据库 -> MCP 查询工具 -> AI 助手

适合解决的问题：

• “这个函数在哪里定义？”
• “谁调用了这个接口？”
• “改这个 service 会影响哪些测试？”
• “这个路由背后走到哪个 handler？”
• “我接手一个大项目，先看哪里？”

工具特点

CodeGraph 的核心特点可以概括为五点：

• 本地优先：图谱保存在项目本地的 .codegraph/ 目录中，默认不依赖云端服务
• 结构化理解：关注符号、调用链、导入、继承、文件结构，而不是单纯文本搜索
• MCP 接入：可以作为 MCP Server 被 Claude Code、Cursor、Codex CLI、opencode 等工具调用
• 增量同步：通过文件监听和 sync 机制让图谱跟随代码变化
• 查询成本低：让 AI 少做大范围文件扫描，减少工具调用和上下文浪费

它不是一个“替代 AI 的工具”，而是一个“给 AI 提供项目地图的工具”。

技术原理:

项目结构树

从公开资料与官方仓库信息看，CodeGraph 的能力可以理解为以下结构：

1
2
3
4
5
6
7
8
9
10
11
12
13

codegraph/
├── cli/                              # 命令行入口：install/init/index/sync/status/query
├── parser/                           # Tree-sitter 解析层
├── graph/                            # 符号、调用、导入、继承等图关系
├── db/                               # SQLite 数据库与 schema
├── search/                           # FTS5 全文符号搜索
├── sync/                             # 文件监听与增量同步
├── context/                          # 为 AI 任务构建上下文
├── mcp/                              # MCP Server，对外暴露查询工具
├── installer/                        # 自动检测并配置 AI Agent
└── .codegraph/
    ├── codegraph.db                  # 项目本地图谱数据库
    └── config.json                   # 项目级索引配置

注意：上面的结构树是理解模型，不是要求用户逐目录操作。日常只需要关心 CLI 命令、.codegraph/config.json 和 MCP 是否连通。

安装与初始化

方式一：一键安装脚本

macOS / Linux：

1

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

Windows PowerShell：

1

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

安装器会把 codegraph 放到 PATH 上。安装后如果当前终端识别不到命令，重新打开一个终端再试。

方式二：已有 Node 环境

1

npm i -g @colbymchenry/codegraph

也可以直接运行交互式安装器：

1

npx @colbymchenry/codegraph

配置 AI Agent

1

codegraph install

codegraph install 会自动检测并配置已安装的 AI 编程工具，例如 Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 等。

非交互模式适合脚本或 CI：

1
2
3
4

codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local
codegraph install --print-config codex

初始化项目

进入目标项目根目录：

1
2

cd your-project
codegraph init -i

init 会创建 .codegraph/ 目录；-i 或 --index 会在初始化后立即构建初始图谱。没有使用 -i 时，可以再执行：

1

codegraph index

验证安装

1
2
3

codegraph status
codegraph query UserService
codegraph files

如果 AI 工具里看不到 CodeGraph MCP 工具，优先检查：

1. codegraph 是否在 PATH 上
2. 当前项目是否执行过 codegraph init -i
3. AI 工具是否已重启
4. MCP 配置中的命令是否为 codegraph serve --mcp

配置文件说明（重点）

项目级配置通常位于：

1

.codegraph/config.json

一个典型配置可以这样理解：

1
2
3
4
5
6
7
8
9

{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js", ".git/**"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}

建议重点关注：

• languages：只索引项目真正使用的语言，减少噪音
• exclude：一定排除 node_modules/、dist/、build/、生成代码和压缩文件
• maxFileSize：避免超大文件拖慢索引
• extractDocstrings：需要文档注释上下文时开启
• trackCallSites：需要调用关系与影响分析时开启

MCP 工具与使用方式

CodeGraph 的价值主要通过 MCP 工具释放。常见工具可以按场景理解：

使用原则：先结构查询，再局部读文件。

不要把 CodeGraph 当成万能问答机。它擅长回答结构问题，不擅长直接判断复杂业务语义。

推荐提示词：

1
2

先使用 CodeGraph 查询项目结构、符号定义、调用关系和影响范围；
只有在需要确认实现细节时，再读取最相关的源文件。

推荐工作流

1. 新接手项目：codegraph init -i -> codegraph status -> 让 AI 用 codegraph_files 和 codegraph_explore 建立全局地图
2. 找功能入口：先 codegraph_search 找符号，再 codegraph_callers / codegraph_callees 看上下游
3. 改代码前：用 codegraph_impact 看影响半径，避免只改入口不看调用方
4. 改代码后：等待文件监听同步，或手动执行 codegraph sync
5. 提交前：结合 codegraph affected 推导可能受影响的测试范围

使用案例

案例 1：定位认证逻辑

问题：

1

这个项目的用户认证逻辑在哪里？

低效做法：让 AI 全项目 grep auth、login、token，再读大量文件。

推荐做法：

1
2
3

请先用 CodeGraph 搜索 auth/login/token/session 相关符号，
再用 callers/callees 找入口、调用方和下游依赖，
最后只读取最关键的 2-3 个文件确认实现细节。

这样可以把“找文件”变成“查图谱”。

案例 2：改函数前看影响面

问题：

1

我要修改 calculatePrice，会影响哪些模块和测试？

推荐做法：

1
2

请用 codegraph_impact 分析 calculatePrice 的调用方、下游依赖和测试覆盖，
按“直接调用者 / 间接影响 / 需要回归的测试”输出。

适合重构、改公共工具函数、改 service 层接口前使用。

案例 3：让 CI 只跑相关测试

1

git diff –name-only HEAD | codegraph affected --stdin | xargs <language-specific-test-runner>

这个思路不是替代完整 CI，而是在本地开发或大仓库中减少无意义的全量测试。

1. git diff –name-only HEAD

列出当前工作目录与最新提交(HEAD)之间有差异的文件名

–name-only：只显示文件路径，不显示差异内容

输出示例：

1
2
3

src/components/Button.tsx
src/utils/helpers.ts
tests/button.test.ts

2. codegraph affected –stdin

codegraph：代码依赖图分析工具（可能是内部工具或第三方库）

affected –stdin：从标准输入读取变更文件列表，分析受这些变更影响的文件（依赖传播分析）

输出受影响的文件（包括直接修改和间接依赖的文件）

3. xargs

xargs：将上一步输出的文件列表作为参数传递给后续命令

各语言的具体实现

各语言完整命令示例

Python (pytest)

1
2
3
4
5
6
7
8

# 基础版
git diff --name-only HEAD | codegraph affected --stdin | xargs pytest

# 推荐版：带空输入保护
changed=$(git diff --name-only HEAD)
if [ -n "$changed" ]; then
    echo "$changed" | codegraph affected --stdin | xargs -r pytest -v
fi

配套工具：pytest-git-selector 是专门为此设计的 pytest 插件，可直接用 pytest --git-diff-args main... 实现类似效果。

Java (Maven + JUnit)

1
2
3
4

# 需要转换文件路径 → 测试类名
git diff --name-only HEAD | codegraph affected --stdin | \
    sed 's/.*\/\(.*\)\.java/\1/' | \
    xargs -I {} mvn test -Dtest={}

Java (Gradle)

1
2
3

git diff --name-only HEAD | codegraph affected --stdin | \
    sed 's/.*\/\(.*\)\.java/\1/' | \
    xargs -I {} gradle test --tests *.{}

Go

1
2
3
4

# Go 的测试文件通常命名为 *_test.go
git diff --name-only HEAD | codegraph affected --stdin | \
    grep "_test\.go$" | \
    xargs go test

Rust

1
2
3
4

# 需要提取测试模块名
git diff --name-only HEAD | codegraph affected --stdin | \
    sed 's/.*\/\(.*\)\.rs/\1/' | \
    xargs -I {} cargo test --test {}

核心结论：只需替换 xargs 后面的测试命令，codegraph 的 affected 功能可以跨语言使用，因为它基于抽象语法树（tree-sitter）进行依赖分析，与最终运行测试的工具无关。

刷新机制与维护

CodeGraph 的图谱不是一次性产物，需要保持更新。

三层刷新机制

日常维护命令

1
2
3
4
5

codegraph status
codegraph sync
codegraph index --force
codegraph upgrade --check
codegraph upgrade

建议把 .codegraph/ 当作本地索引目录处理：

• 不提交数据库文件
• 不把它当作知识库源文件
• 不在不同机器之间强行同步
• 项目迁移后重新 codegraph init -i

与其它工具的对比与选择

CodeGraph vs grep / rg

选择建议：找“名字文本”用 rg，找“结构关系”用 CodeGraph。

CodeGraph vs ast-grep

选择建议：理解代码时先 CodeGraph，批量改代码时用 ast-grep。

CodeGraph vs Sourcegraph

CodeGraph vs repomix

选择建议：持续开发用 CodeGraph；需要把仓库快照发给模型或他人时用 repomix。

CodeGraph vs ctags / cscope

选择建议：传统编辑器导航继续用 ctags/cscope；AI 代理工作流优先 CodeGraph。

CodeGraph vs Cursor / Claude Code 自带索引

选择建议：如果你长期只用一个 IDE，内置索引可能够用；如果你在 Claude Code、Cursor、Codex CLI、opencode 之间切换，CodeGraph 更适合做统一底座。

常见误区与修正

误区 1：装了 CLI 就等于 AI 会自动使用。

修正：安装 CLI 只是第一步，还要 codegraph install 写入 MCP 配置，并重启 AI 工具。

误区 2：项目没初始化就开始问。

修正：每个项目都需要执行一次 codegraph init -i。

误区 3：把 .codegraph/ 当成需要提交的源码。

修正：它是本地索引目录，通常应加入 .gitignore。

误区 4：让 CodeGraph 回答所有业务语义问题。

修正：CodeGraph 负责结构定位；业务语义仍需要 AI 结合源代码、测试、文档判断。

误区 5：索引范围过大。

修正：排除 node_modules/、构建产物、生成代码、压缩文件和日志目录。

我的最小实践模板

可复制到每个准备使用 AI 深度开发的项目：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

CodeGraph 初始化清单：

1) 安装与接入
- [ ] 安装 `@colbymchenry/codegraph`
- [ ] 执行 `codegraph install`
- [ ] 重启 Claude Code / Cursor / Codex CLI / opencode

2) 项目索引
- [ ] 在项目根目录执行 `codegraph init -i`
- [ ] 执行 `codegraph status` 确认索引健康
- [ ] 检查 `.codegraph/config.json` 的 `exclude`

3) 日常使用
- [ ] 新任务先让 AI 用 `codegraph_search` / `codegraph_explore`
- [ ] 改公共函数前使用 `codegraph_impact`
- [ ] 索引疑似过期时执行 `codegraph sync`

4) 版本控制
- [ ] 确认 `.codegraph/` 不提交到仓库
- [ ] 团队统一 MCP 权限和工具使用规则