一、项目概述

CodeGraph 由 colbymchenry 开源，GitHub 地址为 github.com/colbymchenry/codegraph。项目核心理念**：让 AI Agent 在编码前先”理解”代码库的结构与依赖关系**，而非每次都从零开始全文检索（grep 仍是不可替代的广度兜底，详见第二章后的对比）。

属性	说明
技术栈	tree-sitter（AST 解析）+ SQLite FTS5（全文搜索）+ MCP Server
许可证	MIT
主要语言	TypeScript / JavaScript
支持平台	macOS / Linux / Windows（Node.js 环境）
适配 Agent	Claude Code、Cursor、Windsurf、Cline 等支持 MCP 的客户端

---

二、解决的核心问题

CodeGraph 的解决思路：

1. 预索引：在 Agent 工作前，先用 tree-sitter 解析整个代码库，提取函数、类、方法、模块的定义与引用关系
2. 构建知识图谱：将解析结果存入 SQLite 数据库，建立符号间的调用/依赖/继承关系图
3. MCP 暴露：通过 MCP Server 将知识图谱的查询能力暴露给 AI Agent，Agent 可精准定位而非盲搜

---

二· CodeGraph 与 grep：不是替代，是分层协作

检索栈的分层结构

成熟的 Agent 代码检索不是二选一，而是一个”广度入口 → 深度跳转 → 精读”的漏斗：

flowchart TB
    Q[Agent 要改 / 理解一段代码] --> G["① grep / ripgrep 广度入口
任意关键词 · 字符串 · 正则
零索引 · 实时 · 什么都能搜"]
    G --> C["② CodeGraph 深度跳转
谁调用了它 · 找实现 · 算影响面
基于 AST 的语义关系推理"]
    C --> R["③ read 精读
只把命中的少数文件读进上下文"]
    R --> A[理解 + 修改]
    G -. 找注释/配置/错误码/魔法字符串 .-> R

举个真实流程：Agent 要改 parseConfig —— 先 grep 找到它定义在哪（顺带搜到配置文件里相关字段名），再用 CodeGraph 查”谁调了它、改了会炸哪些测试”，最后 read 精读那几个文件。grep 管”在哪”，CodeGraph 管”关系”，各司其职。

能力边界对比

场景	CodeGraph	grep
精确符号的调用关系（谁调了谁）	✅ 强项	❌ 分不清重名
类的子类 / 接口实现	✅ 强项	❌
改动影响面分析	✅ 强项	❌
注释 / TODO / 字符串字面量	❌ 通常不入图	✅ 直接命中
配置 / YAML / SQL / 日志 / 错误码	❌ 无解析器就无图	✅ 全文都能搜
语法报错 / 半成品代码（调试时）	❌ 解析失败建不出图	✅ 照搜不误
刚改完、索引未更新的最新代码	⚠️ 可能过期	✅ 实时

---

三、性能基准测试

官方在 SWE-bench Verified 子集上的测试结果（对比无 CodeGraph 的 baseline）：

指标	提升幅度	说明
成本节省	~35% ↓	API 调用费用降低
Token 消耗	~59% ↓	输入+输出 token 总量
响应速度	~49% ↑	任务完成时间缩短
工具调用次数	~70% ↓	Agent 探索步骤减少

---

四、支持的语言

完整支持（有专用 tree-sitter grammar）：

• Swift
• TypeScript / JavaScript
• Python
• Rust
• Go
• Java / Kotlin
• C / C++
• Ruby
• PHP

社区贡献 / 实验性：

• C#
• Dart
• Elixir
• Scala
• Zig
• Lua
• Haskell

---

五、快速开始

5.1 安装

npm install -g @anthropic/codegraph

5.2 索引代码库

# 进入项目根目录
cd ~/Projects/MyiOSApp

# 运行索引（生成 .codegraph/ 目录）
codegraph index .

5.3 配置 MCP Server

在 Claude Code 的 MCP 配置文件中添加：

{
  "codegraph": {
    "command": "codegraph",
    "args": ["serve", "--project", "/path/to/your/project"]
  }
}

5.4 验证

codegraph status
# 输出：Indexed 1,234 files, 5,678 symbols, 12,345 references

---

六、核心功能与 MCP 工具

CodeGraph MCP Server 暴露以下工具供 AI Agent 调用：

MCP 工具	功能
search_symbol	按名称模糊搜索函数/类/方法定义
find_references	查找某个符号的所有引用位置
get_definition	获取符号的完整定义代码
get_dependencies	获取符号的上下游依赖关系
get_file_symbols	列出某文件中的所有符号
get_call_graph	获取函数调用图（谁调用了谁）

---

七、高阶玩法

7.1 codegraph affected — CI 智能测试

CodeGraph 提供 affected 命令，基于依赖图分析代码变更的影响范围，只运行受影响的测试：

# 分析 git diff，找出受影响的测试文件
codegraph affected --since HEAD~1

# 集成到 CI pipeline
codegraph affected --since $CI_MERGE_REQUEST_DIFF_BASE_SHA | xargs xcodebuild test -only-testing

7.2 自定义索引规则

{
  "include": ["**/*.swift", "**/*.m", "**/*.h"],
  "exclude": ["Pods/**", "Carthage/**", "DerivedData/**"],
  "maxFileSize": "1MB",
  "symbolTypes": ["function", "class", "protocol", "struct", "enum"]
}

7.3 多项目联合索引

对于模块化 iOS 架构（主 App + 多个 Framework），可以联合索引：

codegraph index . --include-deps ./Modules/NetworkKit ./Modules/UIComponents

7.4 与 CLAUDE.md 协同

在项目根目录的 CLAUDE.md 中引导 Agent 优先使用 CodeGraph：

# Code Navigation
- Always use codegraph tools (search_symbol, find_references) before grep/find
- Use get_call_graph to understand function relationships before refactoring
- Use get_dependencies to check impact before modifying shared code

7.5 增量索引与 Git Hooks

#!/bin/sh
# .git/hooks/post-commit
codegraph index . --incremental

---

八、适用场景与工具链集成

最佳适用场景：

• 大型代码库（> 500 文件）
• 复杂依赖关系的模块化架构
• 频繁重构需要影响分析
• CI/CD 测试优化
• 多人协作的团队项目

支持的 AI 客户端：

• Claude Code（官方推荐）
• Cursor（通过 MCP）
• Windsurf（通过 MCP）
• Cline / Roo Code
• 任何支持 MCP 协议的客户端

---

九、注意事项与局限

---

十、总结与建议

维度	评价
实用性	高 ↑ — 直接降低 AI 编码成本和时间
iOS 适配	好 ↑ — Swift 完整支持，Alamofire 实测优秀
学习成本	低 ↓ — npm install + codegraph index 即可
成熟度	中等 — 活跃开发中，功能快速迭代
社区活跃	高 ↑ — GitHub 星标快速增长，贡献者活跃