CodeGraph 中文教程：把代码库变成语义图和 MCP 工具
CodeGraph 的核心不是“再做一个代码聊天框”，而是把代码库解析成函数、类、导入、调用链和依赖关系，再通过查询工具交给 Agent。面对跨文件改动、陌生仓库和调用链追踪，这比反复翻目录更有帮助。
1. 先做一个可复核的测试
选一个能运行测试的仓库，记下提交号、语言、文件数和一次普通搜索结果。这样索引后才知道 CodeGraph 是节省了定位时间，还是只是换了一种展示方式。
2. 安装、索引、检查
git clone https://github.com/codegraph-ai/CodeGraph.git && cd CodeGraph && 按官方 README 安装依赖并建立目标仓库索引
官方命令会随版本变化，安装前先看 README 的当前路径。索引完成后，抽查一个已知函数的定义、调用方、导入链和测试文件；发现缺失时记录语言、生成代码和宏等因素。
3. 接入 VS Code 或 MCP
VS Code 扩展适合人在编辑器里导航；MCP 适合让 Agent 查询“谁调用了这个函数”“这个配置影响哪些模块”等关系。给 Agent 的规则要写清楚：图用于定位，最终改动必须回到文件、测试和构建结果确认。
4. 什么时候值得用
大型多语言仓库、重构和故障排查更适合语义图；小项目、一次性字符串替换和日志检索，grep、IDE 搜索或语言服务器可能更快。索引本身也有成本，要把索引时间和图数据库占用纳入评估。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
原教程未展开的系统信息
核心功能
语义代码图
官方 README 说明图中包含函数、类、导入和调用链。
多语言和 VS Code
README 列出 38 种语言和 VS Code extension，具体解析效果需在目标仓库复核。
核验与使用边界
优势与限制
优势
- 跨文件关系比纯文本搜索更直观
- 可通过 MCP 供 Agent 查询
- 持久化图适合重复导航
限制
- 动态调用、生成代码和宏可能导致漏边
- 索引耗时和存储有成本
- 本轮未安装或给真实仓库建图
排错时先核对版本、运行环境和未覆盖范围。这里没有执行过的步骤不会写成实测结论。
版本与同类选择
同类项目怎么选
相比 grep，CodeGraph 能回答跨文件关系问题；相比语言服务器，它更强调持久化图和 Agent 查询。两者并非互斥，关键结论仍要用源码、测试和构建确认。
官方与对比资料
以下链接用于核对版本、安装方式、功能边界和同类差异。
常见问题
CodeGraph 会替代语言服务器吗？
不应这样理解。语言服务器负责编辑器实时语义能力，CodeGraph 更强调持久化跨文件图和 Agent 查询，两者可以互补。
图能发现所有调用关系吗？
不能保证。动态调用、生成代码、宏和不完整依赖都可能影响解析，关键结论要回到源码和测试。
为什么要记录提交号？
代码图和源码必须对应同一版本，否则 Agent 可能基于旧索引给出错误建议。
如何判断它真的有用？
用同一批定位任务比较“普通搜索”和“图查询”的完成时间、漏查数和最终测试结果，而不是只看图的视觉效果。