检查Node.js环境

在终端中运行 `node --version` 和 `npm --version`，确保已安装Node.js（推荐v18+）和npm。如果未安装，请前往nodejs.org下载安装。

如果版本过低，建议使用nvm（Node Version Manager）来管理Node.js版本，方便切换。

全局安装CodeGraph

在终端中运行 `npm install -g @colbymchenry/codegraph`，将CodeGraph安装为全局命令。安装完成后，运行 `codegraph --version` 验证安装成功。

运行交互式安装器

在你想要使用CodeGraph的项目根目录中，运行 `npx codegraph init` 启动交互式安装器。安装器会： 1. 自动检测已安装的AI编程助手（Claude Code、Cursor、Codex CLI、opencode） 2. 询问是否将codegraph添加到PATH 3. 询问配置是应用于所有项目还是仅当前项目 4. 为每个选中的助手写入MCP服务器配置和指令文件 5. 初始化当前项目的索引

如果不想交互式操作，可以使用 `--target all --location global --yes` 等参数进行静默安装，适合脚本或CI环境。

重启AI编程助手

重启你的AI编程助手（Claude Code / Cursor / Codex CLI / opencode），让MCP服务器配置生效。

如果助手没有自动加载CodeGraph，可以检查配置文件中是否正确添加了MCP服务器配置。

尝试第一个查询

在AI助手中，针对你的项目提出一个架构或代码理解问题，例如：“这个项目中模块A是如何与模块B通信的？”观察AI助手的响应速度和工具调用次数。

CodeGraph提供了两个核心工具：`codegraphcontext`（获取上下文）和 `codegraphexplore`（探索相关源码）。AI助手会自动使用它们。

对比体验（可选）

如果你有对比兴趣，可以临时禁用CodeGraph，提出同样的问题，观察工具调用次数和响应时间的差异。

禁用方法：暂时移除AI助手的MCP配置中的CodeGraph条目，或使用 `--strict-mcp-config` 参数启动助手。

智能上下文构建

了解 `codegraphcontext` 工具：它一次调用就能返回入口点、相关符号和代码片段，无需AI助手启动昂贵的探索代理。在你的项目中尝试询问“这个函数的调用链是怎样的？”。

CodeGraph的指令文件会引导AI助手优先使用这些工具，而不是自己用grep/glob去扫描文件。

全文搜索

体验基于FTS5的全文搜索功能：在AI助手中询问“找到所有与‘用户认证’相关的代码”，观察它如何快速定位。

全文搜索基于预索引的SQLite数据库，速度极快，尤其适合大型代码库。

影响分析

尝试影响分析功能：询问“如果修改这个函数，会影响到哪些调用者？”。CodeGraph会追踪调用者和被调用者，给出完整的受影响范围。

影响分析对于重构和修改代码非常有用，可以避免遗漏依赖。

框架感知路由

如果你的项目使用了Django、Flask、Express、NestJS等13种框架之一，尝试询问“这个URL路径对应哪个处理器？”。CodeGraph会自动识别路由文件并链接到对应的处理函数。

CodeGraph支持多种主流框架的路由识别，包括Django的urls.py、Flask的装饰器、Express的app.get等。

理解索引机制

了解CodeGraph如何工作：它在后台使用树状解析器分析代码中的符号关系、调用图和结构，构建语义化的知识图谱，并存储在本地SQLite数据库中。

索引过程是100%本地的，不会将代码发送到任何外部服务，确保代码安全。

文件监视器

了解CodeGraph的文件监视器：它使用原生OS事件（FSEvents/inotify/ReadDirectoryChangesW）监听文件变化，并自动同步索引，无需手动重新索引。

这意味着你修改代码后，CodeGraph会自动更新知识图谱，AI助手始终能获取最新信息。

理解性能优势的来源

理解为什么CodeGraph能减少92%+的工具调用：有了预索引的知识图谱，AI助手可以直接回答，而不是启动子代理去grep/glob/Read文件。在大型代码库中，这种优势尤为明显。

README中的基准测试数据显示，在VS Code（~10k文件）上，工具调用从23次减少到7次，成本降低35%。