CodeGraph 简介与使用手册
一、它是什么
CodeGraph 是一个开源的本地代码知识图谱工具（GitHub: colbymchenry/codegraph，MIT 协议，TypeScript 编写）。它把代码库预先解析成一张"代码地图"——每个符号（函数/类/方法）、每条调用关系、每个依赖都存进本地 SQLite——然后通过 MCP 协议或命令行供 AI 编程助手查询。
一句话定位：让 AI 写代码前的"翻代码"环节，从几十次 grep/Read 往返变成一两次查询。
二、工作原理
执行 codegraph init 后：
- Tree-sitter 解析所有源文件 → AST（抽象语法树）
- 提取符号：函数、类、方法、路由、组件
- 提取关系：调用、导入、继承、动态跳转
- 存入项目目录 .codegraph/ 下的 SQLite
之后文件监听自动增量同步（约 1 秒延迟），查询亚毫秒级返回。
- 100% 本地运行，代码不出机器，无需任何云服务账号
- 支持 30+ 语言：TypeScript/JavaScript、Python、Go、Rust、C#、Java、C/C++、PHP、Ruby、Vue、Svelte 等
- 支持接入 Claude Code、Cursor、Codex CLI、Gemini CLI、Copilot、Kimi Code 等
三、传统方式 vs CodeGraph
| 场景 | 传统方式 | CodeGraph |
|---|---|---|
| 理解一个功能 | grep 找 → Read 读 → 发现引用 → 再 grep…… | explore 一次返回相关源码+调用路径 |
| 改代码前评估风险 | 手动找所有调用方，容易漏 | impact 一键出影响面 |
| 动态调用（Vue 事件、回调） | grep 根本追不到 | 图谱能还原动态跳转 |
| token 消耗 | 随仓库规模线性增长 | 一次查询固定开销 |
官方实测（VS Code 仓库，4000+ 文件）：回答"扩展主机如何与主进程通信"，有 CodeGraph 3 次调用 17 秒，无 CodeGraph 52 次调用 1 分 37 秒。
四、安装（一次性）
npm install -g @colbymchenry/codegraph
五、使用方法
第 1 步：在项目里建索引（每个项目一次）
codegraph init
输出示例：Indexed 240 files ● 7,550 nodes, 17,241 edges in 2.6s
第 2 步：使用——三种方式
方式 A：命令行直接查
- codegraph explore 名称：一次拿全相关源码+调用路径+影响面（最常用）
- codegraph query 关键词：全库搜索符号
- codegraph callers 符号：谁调用了它
- codegraph callees 符号：它调用了谁
- codegraph impact 符号：改它的影响面
- codegraph files：项目结构总览
- codegraph status：索引状态统计
- codegraph sync：手动增量同步（平时自动）
- codegraph uninit：删除该项目的索引
方式 B：AI 助手自动调用（推荐日常用法）
已接入 Kimi Code（配置在 ~/.kimi-code/mcp.json，新开会话生效）。之后正常给 AI 派活即可，它会自动调用 codegraph_explore：
- "看一下成绩分析怎么实现的" → AI 先查图谱再回答
- "给门户通知加置顶功能" → AI 先摸清 Notices 相关代码和影响面再动手
方式 C：接入其他 AI 工具
codegraph install -t cursor # Cursor
codegraph install -t claude # Claude Code
查询技巧（重要）：
- 语义匹配的是符号名，不是自然语言：查 ExamAnalysis、StudentsController 可以；查"学生列表的数据库访问层"查不到
- 一次可以传多个名称：codegraph explore ExamAnalysisView ExamAnalysisController
- 空结果时它会提示哪些词没有匹配、建议换成什么名字
六、典型工作流（以"给考试列表加学期筛选"为例）
- codegraph explore ExamsController ExamMgmt → 摸清考试管理的控制器、前端页面、学期数据来源
- codegraph impact ExamsView → 确认改动波及面
- 动手改代码
- codegraph explore 复查改后的符号源码
七、边界与注意事项
| 能做 | 不能做 |
|---|---|
| 静态结构分析（符号、调用、依赖） | 编译/类型检查/跑测试（仍靠 dotnet build、npm run build） |
| 动态跳转尽力还原（Vue 事件、回调） | 反射、运行时 DI 等无法静态确定的行为 |
| 快速定位与影响分析 | 语义理解——它是词法匹配，不是"懂"代码 |
| 省 token、省往返 | 小项目收益不明显（省 token 效果随仓库变大而提升） |
其他注意：
- .codegraph/ 不要提交 git，加进 .gitignore
- 响应里出现 "changed since last index sync" 提示的文件，改用 Read 直接看
- 无源码的项目（如纯二进制）建不了有效索引
- 官方默认收集匿名使用统计，可 codegraph telemetry off 关闭