CodeGraph v0.8.0：给 AI 编程 Agent 装一个本地知识图谱，省 35% 费用
安装即用，Claude Code / Cursor 直接提速 49%，大项目 tool calls 骤降 86%
【一句话摘要】
让 Claude Code 告别文件扫描，直接从本地 SQLite 知识图谱查代码结构 — 大项目省 35% token 费用、少 70% 工具调用。
【实战价值】
– 省费用：Uber 用 Claude Code 4 个月烧完全年 AI 预算（Forbes 三天前报道）。CodeGraph 在大项目（VS Code 级别）可省 35% 费用
– 提速度：大项目问答延迟从分钟级降到秒级 — 7 个开源项目实测中位数快 49%
– 减少 context 污染：原来 Agent 要 spawn 子 Agent 扫描文件，现在一次工具调用查完入口点、调用链、相关符号
– 站长友好：19+ 语言 + 13 种框架路由识别。PHP/Laravel、Python/Django、JS/Express 站长直接受益
| 项目 | 语言 | 费用节省 | Token 节省 | 速度提升 | Tool calls 减少 |
|---|---|---|---|---|---|
| VS Code（~10k 文件） | TypeScript | 35% | 73% | 41% | 72% |
| Excalidraw（~600 文件） | TypeScript | 47% | 73% | 60% | 86% |
| Django（~2.7k 文件） | Python | 34% | 64% | 59% | 81% |
| Tokio（~700 文件） | Rust | 52% | 81% | 63% | 89% |
| OkHttp（~640 文件） | Java | 17% | 41% | 36% | 64% |
| Gin（~150 文件） | Go | 22% | 23% | 34% | 19% |
| Alamofire（~100 文件） | Swift | 38% | 59% | 51% | 77% |
【核心指令】
“`bash
# 一键安装（交互式，自动检测已安装的 Agent）
npx @colbymchenry/codegraph
# 项目初始化
cd your-project
codegraph init -i
“`
安装器会问三个问题：配哪个 Agent（自动检测）、装全局还是项目级、是否自动配置 MCP。回答完重开终端 / 重启 Agent 即可使用。
“`bash
# 非交互式安装（适合 CI/脚本）
codegraph install –yes
codegraph install –target=cursor,claude –yes
codegraph install –print-config codex # 只输出配置片段，不写文件
“`
【SOP：3 分钟配置全流程】
1. 全局安装
“`bash
npx @colbymchenry/codegraph
“`
一路选择默认选项（auto-detect agents + global install）。
2. 初始化项目
“`bash
cd your-project
codegraph init -i
“`
这一步建索引。秒级完成 — 小项目（~100 文件）< 1s，大项目（VS Code 级）约 5-10s。
3. 重启 Agent 后直接使用
重开 Claude Code / Cursor，执行架构问答或代码修改任务时，Agent 自动通过 MCP 调用 8 个 CodeGraph 工具：
```bash
# 查询符号
codegraph query "UserService" --limit 10 --json
# 查调用者
codegraph callers "login()"
# 查影响范围（改某个符号前必看）
codegraph impact "UserService.getUser" --depth 2
# 获取构建代码上下文
codegraph context "fix login auth bug" --format markdown --max-nodes 20
# 检查索引状态
codegraph status
```
4. 配合 git hooks 检测影响测试
```bash
# 输出被修改文件影响的测试
git diff --name-only HEAD | codegraph affected --stdin
# 在 CI 中只跑受影响测试
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi
```
【核心参数配置表】
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| languages | array | []（自动检测） | 指定索引语言，留空自动识别 |
| exclude | array | node_modules/**, dist/** | 忽略模式，排除大目录避免慢索引 |
| maxFileSize | number | 1048576（1MB） | 超过此大小的文件跳过索引 |
| extractDocstrings | boolean | true | 提取文档字符串/注释 |
| trackCallSites | boolean | true | 追踪调用位置 |
【支持的框架路由一览】
| 语言/生态 | 框架 | 识别模式 |
|---|---|---|
| Python | ||
| Django | path(), re_path(), url(), include() | |
| Flask | @app.route() + blueprint | |
| FastAPI | @app.get(), @router.post() | |
| JavaScript/TypeScript | ||
| Express | app.get(), router.post() + middleware chain | |
| NestJS | @Controller + @Get/@Post + GraphQL @Resolver | |
| React Router | Route component nodes | |
| SvelteKit | Route component nodes | |
| PHP | ||
| Laravel | Route::get(), Route::resource() | |
| Java/Kotlin | ||
| Spring | @GetMapping, @PostMapping, @RequestMapping | |
| Go | ||
| Gin / chi / gorilla / mux | r.GET(), router.HandleFunc() | |
| Rust | ||
| Axum / Actix / Rocket | .route(“/x”, get(handler)) | |
【深入理解架构】
CodeGraph 的工作分四层：
1. 解析层 — tree-sitter 把你的代码解析为 AST，提取函数、类、方法作为节点，调用、继承、实现作为边
2. 存储层 — 全部存入项目本地 .codegraph/codegraph.db（SQLite + FTS5 全文搜索），100% 本地，不联网
3. 解析层 — 跨文件引用消歧：函数调用 → 定义定位、import → 源文件、类继承链、框架路由模式匹配
4. 同步层 — 用原生 OS 文件事件监听（macOS: FSEvents / Linux: inotify / Windows: ReadDirectoryChangesW），2 秒防抖自动增量同步
项目越大增益越明显：VS Code 级大项目 Agent 直接从索引回答，零文件扫描；小项目（Gin ~150 文件）原生搜索已够快，增益收窄但仍有 22% 费用节省。
【避坑指南】
– 索引慢先查 node_modules：默认排除，但如果自定义了 exclude 配置漏掉 build 目录，几万个文件会拖垮索引速度。用 `codegraph status` 查看 Backend 行 — native 才是快路径
– Backend: wasm 说明跑在慢路径：better-sqlite3 原生模块没装成功。`npm rebuild better-sqlite3` 修复，Windows 下装 Visual Studio Build Tools，macOS 下装 Xcode CLI tools
– 框架路由识别需要运行目录下有对应框架文件：比如 Django 项目必须有 urls.py，Flask 项目有 @app.route 装饰器文件，CodeGraph 才会建立 URL→Handler 节点关联
– 小项目收益不高：如果你的项目 < 100 文件，费用节省可能只有 15-20%，value prop 主要在 "更快" 而不是 "省钱"
- 首次索引后需要等 2 秒同步：修改文件后 MCP 服务器用 2 秒防抖窗口确认文件不再变化后再触发增量索引，不是 bug 是设计
【视觉展示】
[配图由 Architect 补充]
来源：GitHub colbymchenry/codegraph；360 视界整理编译