夜雨聆风CodeGraph：AI 编程助手的语义代码智能引擎，成本直降 35%
核心要点：CodeGraph 是一个 100% 本地运行的 MCP 服务器，为 Claude Code、Cursor 等 AI 编程助手提供预索引的知识图谱——符号关系、调用图和代码结构。查询结果即时返回，无需逐文件扫描，平均降低 35% 成本、减少 70% 工具调用
一句话介绍
CodeGraph 为 AI 编程助手建立代码知识图谱，让探索代码从"扫描文件"变为"查询索引"，大幅提升效率。
性能数据
在 7 个开源项目上的基准测试结果（中位数）：
代码库越大，收益越显著。大型仓库中，CodeGraph 的代理仅需少量调用即可从索引获取答案，零文件读取。
技术特点：收益规模与代码库大小正相关。大型仓库中，有 CodeGraph 的代理只需几次调用即可从索引获取答案，而无需通过 grep/find/Read 展开搜索
快速开始
1. 安装
无需 Node.js，一条命令即可：
# macOS / Linuxcurl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh# Windows (PowerShell)irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
已有 Node.js？使用 npm：
npx @colbymchenry/codegraph # 零安装，或npm i -g @colbymchenry/codegraph
CodeGraph 自带运行时，无需编译、无需原生构建，跨平台一致运行。交互式安装程序会自动配置你的代理——Claude Code、Cursor、Codex CLI、opencode、Hermes Agent。
2. 初始化项目
cd your-projectcodegraph init -i
构建项目的知识图谱索引。同时配置项目级本地代理配置。
3. 重启你的 AI 编程助手
重启你的代理（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent），让 MCP 服务器加载生效。
完成——当 .codegraph/ 目录存在时，你的代理将自动使用 CodeGraph 工具。
卸载
一条命令从所有已配置的代理中移除 CodeGraph：
codegraph uninstall逆向安装过程——从每个配置的代理中剥离 CodeGraph 的 MCP 服务器配置、指令和权限。项目索引（.codegraph/）不受影响，可使用 codegraph uninit 逐个移除。
使用 --target 指定目标代理，--yes 非交互式运行。
核心功能
框架感知路由
CodeGraph 检测 Web 框架的路由文件，生成通过引用边连接到处理函数或类的路由节点。查询视图/控制器的调用者时，现在能同时看到绑定它的 URL 模式。
path()re_path()、url()、include() | |
@app.route('/path') | |
@app.get()@router.post() 等 | |
app.get()router.post() 及中间件链 | |
@Controller@Get/@Post、GraphQL @Resolver、@MessagePattern | |
Route::get()Route::resource() | |
@GetMapping@PostMapping、@RequestMapping | |
r.GET()router.HandleFunc() | |
.route("/x", get(handler)) | |
[HttpGet("/x")] | |
get '/x', to: 'users#index' | |
CLI 命令参考
codegraph # 运行交互式安装程序codegraph install # 显式运行安装程序codegraph uninstall # 从代理中移除 CodeGraphcodegraph init [path] # 在项目中初始化（--index 同时索引）codegraph uninit [path] # 从项目中移除（--force 跳过确认）codegraph index [path] # 完整索引（--force 重新索引）codegraph sync [path] # 增量更新codegraph status [path] # 显示统计信息codegraph query <search> # 搜索符号（--kind、--limit、--json）codegraph files [path] # 展示文件结构codegraph context <task> # 为 AI 构建上下文codegraph callers <symbol> # 查找函数的调用者codegraph callees <symbol> # 查找函数调用的内容codegraph impact <symbol> # 分析变更影响范围codegraph affected [files...] # 查找受影响的测试文件codegraph serve --mcp # 启动 MCP 服务器
codegraph affected 命令
传递依赖追踪，查找受源文件变更影响的测试文件。
codegraph affected src/utils.ts src/api.ts # 直接传参git diff --name-only | codegraph affected --stdin # 从 git diff 管道输入codegraph affected src/auth.ts --filter "e2e/*" # 自定义测试文件匹配
CI 钩子示例：
#!/usr/bin/env bashAFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)if [ -n "$AFFECTED" ]; thennpx vitest run $AFFECTEDfi
MCP 工具
作为 MCP 服务器运行时，CodeGraph 向 Claude Code 暴露以下工具：
codegraph_search | |
codegraph_context | |
codegraph_callers | |
codegraph_callees | |
codegraph_impact | |
codegraph_node | |
codegraph_explore | |
codegraph_files | |
codegraph_status |
原理架构
┌─────────────────────────────────────────────────────────────────┐│ Claude Code ││ ││ "实现用户认证功能" ││ │ ││ ▼ ││ ┌─────────────────┐ ┌─────────────────┐ ││ │ Explore Agent │ ──── │ Explore Agent │ ││ └────────┬────────┘ └────────┬────────┘ ││ │ │ │└───────────┼────────────────────────┼─────────────────────────────┘│ │▼ ▼┌───────────────────────────────────────────────────────────────────┐│ CodeGraph MCP Server ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ 搜索 │ │ 调用者 │ │ 上下文 │ ││ │ "auth" │ │ "login()" │ │ 构建 │ ││ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ ││ │ │ │ ││ └────────────────┼────────────────┘ ││ ▼ ││ ┌───────────────────────┐ ││ │ SQLite 图谱数据库 │ ││ │ • 387 个符号 │ ││ │ • 1,204 条边 │ ││ │ • 即时查询 │ ││ └───────────────────────┘ │└───────────────────────────────────────────────────────────────────┘
工作流程：
提取 — tree-sitter 将源码解析为 AST。语言特定的查询提取节点（函数、类、方法）和边（调用、导入、继承、实现） 存储 — 所有数据存入本地 SQLite 数据库（ .codegraph/codegraph.db），支持 FTS5 全文搜索解析 — 提取完成后解析引用关系：函数调用 → 定义、导入 → 源文件、类继承和框架特定模式 自动同步 — MCP 服务器使用原生 OS 文件事件监控项目。变更经去抖（2 秒静默窗口）后增量同步。图谱随编码实时更新，零配置
作为库使用
import CodeGraph from '@colbymchenry/codegraph';const cg = await CodeGraph.init('/path/to/project');// 或：const cg = await CodeGraph.open('/path/to/project');await cg.indexAll({onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)});const results = cg.searchNodes('UserService');const callers = cg.getCallers(results[0].node.id);const context = await cg.buildContext('fix login bug', {maxNodes: 20, includeCode: true, format: 'markdown'});const impact = cg.getImpactRadius(results[0].node.id, 2);cg.watch(); // 文件变更自动同步cg.unwatch(); // 停止监控cg.close();
配置说明
CodeGraph 是零配置工具。它会索引所有扩展名对应支持语言的文件，并遵循 .gitignore 规则：
git 忽略的内容—— node_modules、构建输出、.env中的密钥——永远不会被索引没有需要编写或同步的配置文件，无需按语言设置 超过 1 MB 的文件将被跳过（生成包、压缩 JS、第三方大文件） 若提交了不被 gitignore 的文件（如 vendor/或dist/），仍会被索引
常见问题排查
codegraph init | |
node_modules 等大型目录是否被排除 | |
/mnt 上，将项目移至本地磁盘 | |
codegraph serve --mcp 是否正常工作 | |
codegraph sync。检查文件语言是否被支持 |
平台与代理支持
支持平台：
支持代理：
Claude Code、Cursor、Codex CLI、opencode、Hermes Agent
支持语言（共 19+）：
TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Lua、Luau
安装选项参考
codegraph install --yes # 自动检测代理，全局安装codegraph install --target=cursor,claude --yes # 指定目标代理codegraph install --target=auto --location=local # 检测到的代理，项目级安装codegraph install --print-config codex # 仅打印配置片段，不写文件
--target | ||
--location | ||
--yes | ||
--no-permissions | ||
--print-config <id> |
注意事项：CodeGraph 的收益规模与代码库大小正相关。在小型仓库（如 ~150 文件的 Gin）上，原生搜索成本已足够低，优势相对较小。对于中大型项目，效果尤为显著
文档来源：CodeGraph
原始作者：Colby McHenry
本文由 AI 助手整理优化，欢迎关注、分享转载，请注明出处
