夜雨聆风代码知识图谱 · MCP 服务器 · 语义索引 · 减少 Token 消耗 · 本地运行 —— CodeGraph 为 Claude Code、Cursor、Codex CLI 和 opencode 等 AI 编码助手提供预构建的本地代码知识图谱，让 agent 在几秒内理解整个项目结构， 实测平均节省 35% 成本、59% Token、70% 工具调用。
AI 读代码的隐形成本
用过 Claude Code 或 Cursor 的开发者都知道：当你在一个中型以上的仓库中问
"这个功能是怎么实现的"时，agent 并不会直接答——它会先启动一个 Explore
子 agent，后者开始逐级调用 find、grep、cat、Read 等工具扫描文件。
一次架构探索少则几十次、多则上百次工具调用，每一次都意味着 token 消耗。
作者用 7 个真实开源项目（VS Code、Django、Tokio、OkHttp、Excalidraw 等）做了对照测试：同样一个问题，不装 CodeGraph 时 Claude Code 要消耗 39 万到 340 万 token 来探索并回答；装上之后降到 35 万到 110 万 token。在 Excalidraw（约 600 个文件）上，工具调用次数从 83 次降到了 12 次。这组数据点出了核心矛盾——AI 编码助手擅长写代码，但读代码的效率 恰恰是它的短板。
CodeGraph 的目标用户很明确：日常使用 AI 编码助手、仓库有一定规模 （数百文件以上）、关心 API 调用成本的开发者。如果你只在几十个文件的 小项目里用 agent，grep 本身已经够快；但一旦项目上千文件，agent 的每轮 文件扫描都会变成真金白银的 token 开销——这正是 CodeGraph 要解决的问题。
三分钟上手，六条命令覆盖日常
安装 CodeGraph 不需要注册账号、不需要配 API Key，一条命令搞定：
npx @colbymchenry/codegraph
交互式安装程序会自动检测你机器上装了哪些 agent（Claude Code、Cursor、
Codex CLI、opencode），并为每个 agent 写入对应的 MCP 配置文件和指令文件
（如 ~/.claude.json、.cursor/rules/codegraph.mdc）。重启 agent 后，
它就能用上 CodeGraph 的能力了。
入门三步走：
npx @colbymchenry/codegraph
# 2. 在目标项目中建索引
cd your-project
codegraph init -i
# 3. 开始用——agent 会自动调用 MCP 工具
"解释一下用户认证模块的架构"
三个最实用的日常场景：
场景 1：搜索符号定义。你想改 UserService 这个类，用
codegraph_search 可以一秒定位它在哪、有哪些属性和方法，不需要自己
猜路径。
场景 2：追踪调用链。想知道某个函数被哪些地方调用了？codegraph_callers
直接返回所有 caller 的完整信息，比 grep 递归扫整个项目快了一个数量级。
统计显示仅这一项就能让 agent 少做 60–80% 的 grep/Read 调用。
场景 3：变更影响分析。改一个公共工具函数之前，codegraph_impact
会列出一张完整的"受影响文件清单"。结合 codegraph affected 子命令，
还能自动查出哪些测试文件需要重新运行：
git diff --name-only | codegraph affected --quiet
这个输出可以直接 pipe 给测试运行器，实现精准回归测试。
一个小细节：CodeGraph 在 IDE 中也不会掉链子。它使用 OS 原生文件 事件（macOS 上的 FSEvents、Linux 上的 inotify、Windows 上的 RDCW）监听 文件变更，2 秒静默期后自动增量同步——写代码、保存、agent 再问，索引 已经是最新的。
从 AST 到可查询的知识图谱
CodeGraph 的核心架构是一条清晰的数据流水线：
源码 -> tree-sitter 解析（AST）-> 提取节点与边 -> 引用解析 -> SQLite 存储 -> MCP 工具
第一步：tree-sitter 解析。每个源文件经过 tree-sitter 解析器被转为 抽象语法树。团队为 19 种语言（TypeScript、Python、Go、Rust、Java、 C#、PHP、Ruby、C/C++、Swift、Kotlin、Dart、Svelte、Vue、Liquid 等） 编写了针对性的查询规则，从 AST 中提取函数、类、接口、成员等实体（Node） 以及调用、继承、导入等关系（Edge）。
第二步：引用解析。这是区分"符号倒排"和"知识图谱"的关键一步。解析器
会跨文件追踪 import 语句、resolve 别名（tsconfig paths、Cargo workspace
member globs），把 import { foo } from '@/utils/bar' 中的 foo 匹配
到它的实际定义位置。对于框架级路由，CodeGraph 还内置了 13 个 Web 框架
的路由解析器（Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、
Spring、Gin、Axum、ASP.NET、Vapor、React Router），能直接建立
"URL -> handler 函数"的映射关系。
第三步：SQLite 存储。所有节点（约 NODE_KINDS = 22 种类型）和边
（EdgeKind = 12 种关系）存入本地 SQLite 数据库，附 FTS5 全文搜索索引。
数据库优先使用 better-sqlite3 原生模块（C++ 绑定，性能比 WASM 快
5–10 倍），不可用时自动回退到 WASM SQLite 兜底。
与常规方案的本质区别：
| 维度 | 常规 agent 探索 | CodeGraph |
|---|---|---|
| 时机 | 运行时实时扫描 | 预先索引，查询即响应 |
| 数据 | plain text，需 grep 逐行匹配 | 结构化图：符号 + 关系 + 引用 |
| 增量 | 每次重新扫 | 文件事件监听 + 增量同步 |
| 成本 | 每个工具调用按 token 计费 | 本地 SQLite 查询，零 Token 消耗 |
创新性不体现在某个颠覆性的算法上——它在于把"计算"从运行时前移到索引
时。Claude Code 本身是一个通用 agent，它不具备对特定项目的代码结构
"记忆"。CodeGraph 补上了这个缺口：每次 codegraph_context 调用返回的
已经是按相关性排序、去重、附源码片段的上下文，agent 不用再自己 grep
和拼接。
立刻能用上的场景与扩展空间
马上可落地的场景：
• CI 精准测试：配合 git hooks，codegraph affected 可在每个 PR 中
只运行受变更影响的测试文件，取代全量测试——对于大仓库，单次 CI 节省
数分钟到数十分钟。
• 团队 Onboarding：新成员接手一个不熟悉的老项目，直接在 Cursor 中 问 "这个项目的模块划分和核心数据流是什么？"，agent 靠 CodeGraph 的 预索引几秒内给出完整的架构概览。
• 代码审查辅助：review 时选中一个函数提问"有哪些 caller？"、 "这个 change 会影响哪些模块"，agent 直接回答，不用 reviewer 自己 顺着 import 链逐级翻查。
更广阔的想象空间：
CodeGraph 的 MCP 集成架构意味着它不绑定具体 agent——任何支持 MCP
协议的客户端（未来的 Windsurf、Zed、Continue 等）都能接入。目前
installer/targets/ 目录只有 4 个 agent target，但架构设计为每加一个
agent 只需加一个文件 + 一行注册，扩展成本极低。如果社区接管了更多
IDE 的 MCP 协议集成，CodeGraph 可能成为跨 IDE 的代码理解基础设施
层——不再需要每个 agent 各自反复扫描同一份代码。
此外，项目当前的弱点是仅针对已索引的静态结构。如果未来能结合 运行时的 profile 数据（如调用频次、热路径），从"代码怎么连的"走向 "代码怎么跑的"，它的价值会再上一个台阶。
