Graphify - 代码库转知识图谱的 AI 编程助手技能

解决什么

传统代码阅读依赖 grep、全局搜索或 IDE 跳转,面对大型项目时难以把握全局架构和隐式依赖关系。Graphify 将整个代码库(包括 SQL 模式、R 脚本、Shell 脚本、文档、图片、视频)转化为可查询的知识图谱,开发者可以直接提问"FastAPI 和 ModelField 如何连接"或"解释 APIRouter 的作用",系统返回带路径的结构化答案,而非文件列表。每条边标注 EXTRACTED(源码显式)或 INFERRED(工具推导),确保溯源透明。

为何火

8.6 万 stars 的热度源于三个差异化设计:1) 完全本地化的代码解析,基于 tree-sitter AST 而非 LLM,无需上传代码即可生成确定性图谱;2) 真实图结构而非向量索引,支持路径查询、社区检测等图算法,可回答"两个模块间的最短依赖链"这类传统 RAG 无法处理的问题;3) 零配置集成 AI 助手,通过 /graphify 命令直接在 Claude Code、Cursor 等 15+ 平台使用,30 秒内生成交互式 HTML 可视化图谱。项目由 Y Combinator S26 孵化,技术栈覆盖 40+ 编程语言。

核心功能

• 多语言 AST 解析:通过 tree-sitter 支持 Python、JavaScript、Go、Rust、Java、C/C++、Ruby、Kotlin、Scala、PHP、Swift 等 40+ 语言,提取函数调用、类继承、模块导入等显式关系
• 图谱查询三件套:graphify query "<问题>" 返回相关子图,graphify path A B 追踪两节点间最短路径,graphify explain "概念" 展示节点的所有连接及置信度
• 社区检测:基于 Leiden 算法自动识别代码库的子系统划分,无需 LLM 即可生成模块标签
• 交互式可视化:生成 graph.html 力导向图,支持节点点击、社区筛选、全文搜索,浏览器直接打开
• 增量更新:已生成的 graph.json 可重复查询,无需重新扫描文件;支持 Docker 容器化部署为 HTTP MCP 服务

安装

推荐使用 uv 或 pipx 安装(避免污染全局 Python 环境):

# 方式一:uv(推荐)
uv tool install graphifyy

# 方式二:pipx
pipx install graphifyy

# 注册到 AI 助手
graphify install

在 AI 助手中运行:

/graphify .

输出三个文件:

• graph.html:浏览器可视化
• GRAPH_REPORT.md:关键概念摘要
• graph.json:完整图谱数据

Docker 部署(适合团队共享):

docker build -t graphify .
docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
    /data/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"

适合谁

• 接手遗留系统的工程师:快速理解陌生代码库的架构脉络,识别核心模块和边缘依赖
• 技术 Leader:通过"上帝节点"(最高连接度节点)定位架构瓶颈,评估重构风险
• 开源贡献者:在大型项目中追踪某个 API 的调用链,找到需要修改的所有位置
• AI 编程助手重度用户:已在使用 Claude Code、Cursor 等工具,希望增强上下文理解能力

中文用户注意:代码解析完全离线,但处理 PDF、图片、视频时会调用 AI 助手的模型(如 Claude API),需确保网络可达或自行配置 API Key。

社区评价

暂无足量社区公开讨论,以下为基于项目本身的中立评估:

项目在 GitHub 获得 8.6 万 stars 和 155 位贡献者,显示出较高的开发者关注度。504 个 open issues 表明功能迭代快速但可能存在稳定性待优化。技术选型上,使用 tree-sitter 而非 LLM 进行代码解析是务实的工程决策,避免了 token 成本和隐私风险,但对自然语言文档的理解仍依赖外部模型。Leiden 社区检测算法在学术界已验证有效,应用于代码模块划分具有理论支撑。项目由 Y Combinator 孵化,商业化路径可能影响未来开源策略。

选型对比

vs 传统代码搜索(grep/ripgrep)

• Graphify:结构化关系查询,可回答"A 如何影响 B";传统搜索:文本匹配,需人工串联上下文
• Graphify:社区检测自动分组;传统搜索:依赖目录结构或人工经验

vs 向量数据库 RAG(如 Copilot 的 embedding 检索)

• Graphify:图遍历保证路径完整性,边有明确语义(调用/继承);RAG:相似度匹配可能遗漏中间节点
• Graphify:代码解析无需 LLM,成本更低;RAG:所有内容需 embedding,token 消耗大

vs IDE 的调用层次视图(如 IntelliJ 的 Call Hierarchy)

• Graphify:跨文件全局视图,支持自然语言查询;IDE:单文件或单符号视角,需手动展开
• Graphify:导出静态图谱可分享;IDE:实时但不可持久化

取舍:Graphify 适合"理解架构"场景,IDE 更适合"精确跳转"场景;若需处理非代码资产(文档/视频),Graphify 是唯一选择。

已知坑

1. 504 个 open issues:功能迭代快但 bug 修复可能滞后,生产环境使用需评估风险
2. 文档处理需外部 API:虽然代码解析本地化,但 PDF/图片/视频仍需调用 AI 模型,中国大陆用户可能需配置代理或使用国内模型 API
3. 图谱规模限制:超大型项目(如 Linux 内核)生成的图谱可能包含数万节点,浏览器渲染 graph.html 时可能卡顿,建议用 graphify query 提取子图
4. tree-sitter 版本锁定:依赖特定版本范围(如 tree-sitter-python>=0.23,<0.26),升级 Python 解析器可能导致兼容性问题
5. 无内置权限控制:Docker 部署的 HTTP 服务需自行配置 --api-key,否则图谱数据暴露在公网
6. 社区标签质量:Leiden 算法生成的模块标签是基于图结构而非语义,可能出现"utils 和 core 被分到同一社区"的反直觉结果