一句话理解：CodeGraph 不是另一个“会写代码的模型”，而是给 Claude Code、Codex、Cursor 等 agent 准备的本地代码知识图谱。它提前把仓库解析成符号、调用关系、文件结构和框架路由，让 agent 少 grep、少 Read、少走弯路。
CodeGraph 是一个“本地优先”的代码智能索引器：把仓库提前解析成可查询的代码知识图谱，再通过 MCP 暴露给 AI coding agent。
没有 CodeGraph 时，agent 像第一次进陌生城市：先问路、翻地图、走错巷子、再回头。CodeGraph 像提前给它装了一张带路网、建筑、门牌和通行关系的本地地图。agent 不必每次用 grep 和 Read 重新探索。
它用 tree-sitter 解析源文件，抽取 nodes/edges/files，存入本地 SQLite + FTS5；再做 import、call、inheritance、framework route 等 resolution；最后通过 CLI 和 MCP server 提供 search、explore、callers、callees、impact 等查询。
大仓库里，一个“这个模块怎么工作”的问题，agent 常常要跑多轮 find/grep/Read。每一轮都是 token、时间和上下文污染。
把更多文件塞进上下文并不等于理解。没有结构化关系时，模型只能在一堆片段中猜调用链和依赖边界。
很多团队不能把完整代码上传外部服务。CodeGraph 的卖点是本地 SQLite、本地 MCP、无 API key。
| 方案 | 核心做法 | 优势 | 短板 |
|---|---|---|---|
| 纯 grep / Read | agent 实时扫文件 | 无需预处理，结果一定来自当前文件 | 慢、费 token、容易漏跨文件关系 |
| RAG / embedding | 按语义检索代码块 | 能找相似语义 | 不一定懂调用、继承、路由等结构关系 |
| IDE/LSP | 语言服务提供符号能力 | 单语言体验成熟 | 跨语言、跨框架、agent MCP 统一查询不一定顺滑 |
| CodeGraph | 静态解析 + 图关系 + MCP 工具 | 结构化、跨 agent、本地、适合架构问答和影响分析 | 静态分析天然有动态边界，索引质量决定答案质量 |
官方文档把流程拆成四段：Extraction、Storage、Resolution、Auto-sync。我把它翻译成更接近工程落地的版本。
官方列出的节点类型包括 file、module、class、struct、interface、trait、protocol、function、method、property、variable、constant、enum、route、component 等。
边类型包括 contains、calls、imports、exports、extends、implements、references、type_of、returns、instantiates、overrides、decorates 等。
静态分析最怕 callback、observer、EventEmitter、React re-render、JSX child、Django ORM descriptor 这类“名字不直接写死”的路径。CodeGraph 的做法不是假装 100% 精确，而是通过 synthesizer 补一些启发式边，并标记 provenance 为 heuristic，把这些边的来源显示给 agent。
官方文档强调三层机制：MCP server 启动时用系统文件事件监听项目，默认 2000ms debounce 后增量 sync；如果查询结果引用了刚修改但还没同步的文件，会加 staleness banner 提醒 agent 直接 Read；MCP 连接时还会做一次 size/mtime + hash 的 catch-up。
codegraph init -i # 创建 .codegraph 并建立初始索引
codegraph index # 全量索引
codegraph sync # 增量更新
codegraph status # 查看节点、边、文件数和索引健康度
codegraph serve --mcp # 启动 MCP serverCodeGraph 的正确使用方式不是让 agent “先想再 grep”，而是让 agent 第一时间问图。官方 v0.9.9 也把 codegraph_explore 提升为主工具。
| 工具 | 适合问题 | 我的理解 |
|---|---|---|
codegraph_explore | “这个功能怎么实现？”“这条链路在哪？” | 一次返回相关符号源码、按文件分组、带关系图。v0.9.9 后官方主推。 |
codegraph_search | “UserService 在哪？” | 符号级搜索，不是全文乱搜。 |
codegraph_callers / callees | “谁调用它？”“它调用谁？” | 做一跳调用关系检查，适合改代码前摸边界。 |
codegraph_impact | “改这个会影响哪里？” | 做 blast radius，配合测试选择很有用。 |
codegraph_node | “给我这个符号的定义和源码” | 查精确节点，名字重载时新版会返回多个定义。 |
codegraph_files | “仓库结构是什么？” | 比 agent 自己扫文件树更省。 |
codegraph_status | “索引是不是新鲜？” | 检查健康度和 pending sync。 |
README 给出的 benchmark 平均结果是：16% cheaper、47% fewer tokens、22% faster、58% fewer tool calls。测试覆盖 7 个真实开源仓库，使用 Claude Code headless、Opus 4.8、每组 4 次取中位数。
| 仓库 | 语言 | 成本 | Tokens | 时间 | 工具调用 |
|---|---|---|---|---|---|
| VS Code | TypeScript | 18% cheaper | 64% fewer | 11% faster | 81% fewer |
| Django | Python | 8% cheaper | 60% fewer | 13% faster | 77% fewer |
| OkHttp | Java | 25% cheaper | 54% fewer | 31% faster | 50% fewer |
| Alamofire | Swift | 40% cheaper | 64% fewer | 33% faster | 58% fewer |
动态语言、反射、依赖注入、运行时注册、配置驱动路由、monkey patch 都可能让图不完整。启发式边能补一部分，但不该当作形式化证明。
watcher、debounce、connect-time catch-up 设计不错，但在沙箱、CI、远程文件系统、大量生成文件场景下，要用 codegraph status 和 sync 做兜底。
官方列出很多 Full support，但每门语言的“符号抽取”与“框架语义”深度不可能完全一致。真正落地前要拿自己的主仓库做试跑。
收益依赖 agent 是否优先调用 CodeGraph。如果团队 prompt、权限、MCP 配置、自动 allow 没处理好，工具可能装了但很少用。
codegraph init -i，再看 codegraph status 的节点、边、文件数。codegraph install 或手动把 codegraph serve --mcp 配到你的 agent。# macOS / Linux 安装
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 或 npm
npm i -g @colbymchenry/codegraph
# 配 agent
codegraph install
# 在项目中初始化并索引
cd your-project
codegraph init -iCodeGraph 的价值不在“它能替代模型理解代码”，而在“它把代码库探索这件事从随机游走变成结构化查询”。这类工具会越来越重要，因为 AI coding agent 的瓶颈正在从“能不能生成代码”转向“能不能稳定理解大仓库、少打扰、少浪费、少误判”。
如果说 2024-2025 年大家在给模型堆上下文，那么 CodeGraph 代表的是更务实的一条路：把上下文前面加一层本地、结构化、可查询的代码地图。它不会消灭 Read/grep/LSP，也不会解决所有动态语言问题，但它很可能成为成熟 agent 工作流里的基础组件。