一天一个开源项目

开源项目第182期：Graphify — 把整个代码库变成可查询知识图谱，让 AI 编程助手真正「懂」你的项目

YC 支持的开源工具，用 tree-sitter AST 解析代码、LLM 处理文档，把代码库、文档、PDF、图片、视频全部构建成一张知识图谱。AI 助手通过图遍历而不是 grep 来理解代码，每条边标注 EXTRACTED/INFERRED/AMBIGUOUS 来源。增量更新只 patch 变更文件（0.8 秒），不像 RAG 需要重新嵌入整个索引。支持 Claude Code、Cursor、Codex 等 15+ 个 AI 工具，MCP 协议接入，Neo4j/FalkorDB 可选后端。101k Stars，Apache-2.0 + MIT。

·约 10 分钟阅读·AI Tools
open-sourceknowledge-graphAI-agentcode-intelligencetree-sitterMCPcontext-engineeringClaude-CodeRAG-alternativePythonYC

引言

"AI 编程助手为什么老是理解不了你的代码库？因为它每次都在 grep，而不是真正理解项目结构。"

这是「每日一个开源项目」系列的第 182 篇。今天的项目是 Graphify —— Y Combinator 支持的开源工具，把整个项目（代码、文档、PDF、图片、视频）构建成一张可查询的知识图谱，作为 AI 编程助手的上下文层。

在 Claude Code 或 Cursor 里让 AI 解释某段代码的依赖关系，它可能准确，也可能从几十个文件里随机挑一些，漏掉关键的跨文件联系。根本原因是 AI 助手靠文件 grep 和向量相似度来"理解"代码库，这两种方式都没有真正捕捉代码的结构关系。Graphify 用知识图谱替代这两种方式：每个函数、类、文档节点都有明确的关系边，AI 沿着图的路径遍历，而不是猜。

2.5 个月就积累了 73,000 Stars，2.2M 次下载，101k Stars。Apache-2.0 + MIT。

你会学到什么

  • Graphify 和 RAG 的本质差异：图遍历 vs 向量相似度搜索
  • tree-sitter AST 本地解析：代码分析零 API 调用，不离开本机
  • 边来源标注（Edge Provenance）：EXTRACTED / INFERRED / AMBIGUOUS
  • God Nodes：自动识别高影响节点，可视化变更的爆炸半径
  • 增量更新：3 个文件变更只需 0.8 秒，不重建整张图
  • 在 Claude Code 里的一键安装和使用方式

前提知识

  • 使用过 Claude Code、Cursor 或类似 AI 编程工具
  • 了解知识图谱的基本概念（节点、边、关系）会有帮助
  • 熟悉 Python 环境操作

问题背景：AI 助手的"项目盲视"

一个有 500 个文件的代码库，你问 Claude Code："auth 模块是怎么连接到数据库的？"

它的处理流程大概是：

  1. 在上下文里搜索"auth"相关的文件
  2. 把搜到的几个文件内容加进上下文
  3. 基于这些片段生成回答

问题在于步骤 1：搜索是基于关键词或向量相似度，不是基于代码的实际结构关系。它可能：

  • 找到三个都包含"auth"字符串的文件，但遗漏了真正关键的中间层
  • 发现 auth.py 和 db.py，但看不出两者之间经过了哪几层调用
  • 下次问同一个问题，结果可能不一样

这不是模型能力的问题，是上下文构建方式的问题。

Graphify 的解法：在你问问题之前，先把整个代码库解析成一张图，每个函数、类、模块、文档都是节点，调用关系、引用关系、继承关系都是有方向的边。AI 助手查询这张图来构建上下文，而不是 grep。

核心架构：本地 AST + 可选 LLM

Graphify 把项目分为两类内容，用不同方式处理：

代码文件
    → tree-sitter AST 本地解析
    → 零 API 调用，不离开本机
    → 提取函数/类/模块节点 + calls/imports/inherits 关系边
    
文档 / PDF / 图片 / 视频
    → 配置的 LLM 后端处理（Anthropic/OpenAI/Gemini/Ollama 等）
    → 提取语义节点和关系
    
                ↓
        统一的知识图谱
        
输出文件：
├── graph.html       ← 浏览器可视化
├── GRAPH_REPORT.md  ← 人类可读的报告和建议问题
└── graph.json       ← 完整可查询的图数据

tree-sitter：确定性代码解析

tree-sitter 是业界标准的增量 AST 解析库，被 Neovim、GitHub 等工具广泛使用。Graphify 用它解析代码，而不是让 LLM 来"理解"代码结构。

好处：

  • 确定性：同样的代码每次解析结果相同
  • 零 API 成本：代码解析完全本地，不调用任何 LLM
  • 速度：AST 解析比 LLM 推理快几个数量级
  • 隐私：代码不离开本机

支持 36+ 种编程语言：Python、TypeScript/JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Swift、Scala、PHP、Lua、Zig、SQL 等。

边来源标注（Edge Provenance）

这是 Graphify 区别于其他知识图谱工具的核心设计之一。

图里的每一条边都带有来源标签：

标签含义
EXTRACTED从代码结构直接提取，确定性的
INFERRED从 LLM 推理得出，有一定不确定性
AMBIGUOUS来源不确定，需要人工验证

为什么重要：当 AI 助手沿着图路径回答问题时，它知道哪些关系是"代码里写死的事实"，哪些是"模型推断的"。这直接影响回答的可信度判断。

用户问："login 函数如何触发数据库写入？"
 
AI 沿图遍历找到路径：
login() --[EXTRACTED: calls]--> validate_user()
validate_user() --[EXTRACTED: calls]--> db.query()
db.query() --[INFERRED: writes_to]--> users_table
 
回答里可以明确说：前两跳是代码确认的，最后一跳是推断的。

God Nodes：识别高风险节点

Graphify 用图论里的**介数中心性（betweenness centrality）**计算自动识别"God Nodes"——那些连接最多社区、被最多路径经过的节点。

在一个真实代码库里，God Node 通常是：

  • 被 20 个模块都 import 的工具函数
  • 连接前端和后端的 API 层文件
  • 包含所有数据库连接逻辑的单一 service 类

这些节点有个特点：一旦出现 bug，影响范围最大。Graphify 的可视化里，God Node 以醒目的方式标出，让你在做重构或者看 AI 生成的代码改动时，立刻知道这个改动的"爆炸半径"有多大。

社区检测：发现隐藏的子系统边界

Graphify 用 Leiden 算法对图做社区检测，自动把代码库拆分成功能性的子系统，不依赖文件夹结构。

实际意义：

  • 代码库可能有一个 utils/ 文件夹，但里面混了属于不同子系统的代码
  • Leiden 算法从实际的调用关系和引用关系出发，识别出哪些文件真正是"一起工作"的
  • 结果展示在 graph.html 里，用颜色区分不同社区

这在大型代码库的架构理解和重构规划里特别有价值。

增量更新：不重建整张图

传统 RAG 的痛点之一：代码变了就要重新嵌入整个索引，几百个文件的项目可能要等几分钟甚至更长。

Graphify 的增量更新：只 patch 实际变更的文件，其余节点完全不动。

官方数据：50 万节点的图，3 个文件变更，patch 耗时 0.8 秒。

查询接口：用自然语言遍历图

# 自然语言查询
graphify query "login form 是怎么连接到 users 表的？"
# → 返回从 UI 经过 API 层到数据库的完整路径，每条边带来源标签
 
# 两个节点之间的最短路径
graphify path auth.login db.users
 
# 让 AI 基于图解释一个函数
graphify explain src/auth/handler.py:validate_token

支持的数据源

Graphify 不只是代码图，整个项目的所有文档和媒体文件都可以纳入：

代码（本地 AST，零 LLM）

  • 36+ 语言：Python、TS/JS、Go、Rust、Java、C/C++、Ruby、Kotlin、Swift 等

文档

  • Markdown、HTML、RST、YAML、TXT
  • .docx、.xlsx（可选扩展）
  • PDF（可选扩展）

媒体

  • 图片：PNG、JPG、WebP、GIF（视觉提取）
  • 视频/音频：MP4、MOV、MP3、WAV（本地 faster-whisper 转录）

特殊格式

  • MCP 配置文件
  • 包清单文件：pyproject.toml、go.mod、pom.xml
  • Google Workspace：Docs、Sheets、Slides（通过 gws CLI）
  • YouTube URL

安装和快速上手

安装

# 安装 CLI（推荐 uv）
uv tool install graphifyy   # 注意：PyPI 包名是 graphifyy（双 y）
 
# 注册到 AI 助手
graphify install

在 Claude Code 里使用

# 安装完成后，在 Claude Code 里：
/graphify .              # 构建当前目录的图
 
# 之后可以直接用自然语言问项目相关问题
# AI 会基于图路径而不是 grep 来回答

输出文件

graphify-out/
├── graph.html       ← 浏览器打开，交互式可视化
├── GRAPH_REPORT.md  ← 图的亮点、意外连接、建议问题
└── graph.json       ← 完整图数据，可供程序查询

MCP Server 模式

# 作为 MCP server 启动
graphify mcp --transport stdio   # 标准输入输出
graphify mcp --transport http    # HTTP 模式

配置好后，任何支持 MCP 的 AI 工具都能通过工具调用直接遍历你的代码图。

可选后端

# 推送到 Neo4j（企业级图数据库）
graphify push --backend neo4j --uri bolt://localhost:7687
 
# FalkorDB
graphify push --backend falkordb

Benchmark 数据

官方 BENCHMARKS.md 里有与主流 memory/RAG 系统的对比：

基准指标Graphifymem0supermemory
LOCOMO (n=300)recall@100.4970.0480.149
LOCOMO (n=300)QA 准确率45.3%27.3%49.7%
LongMemEval-S (n=50)QA 准确率76%——
图构建LLM 消耗0（代码部分）按 token 计费按 token 计费

注：LongMemEval-S 上 Graphify 与 dense RAG 持平（76%），但代码部分的图构建完全免费（本地 AST 解析）。

支持的 AI 助手

安装后一个命令注册，支持：

Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot、Aider、Kilo Code、OpenCode、Factory Droid、Trae、Amp、Kiro、Devin CLI，以及其他任何支持 Skills 的工具。

项目地址与资源

总结

Graphify 的核心洞察：AI 编程助手的上下文质量，比模型能力更能决定回答质量。

同一个 Claude Sonnet，给它一堆通过 grep 找到的文件片段，和给它一条沿着真实代码关系遍历的图路径，回答的深度和准确性差异显著。Graphify 做的是后者：用 tree-sitter 精确提取代码结构，用 Leiden 算法识别子系统，用介数中心性找出风险节点，把这一切构建成一张可查、可追溯、带来源标注的知识图谱。

边来源标注（EXTRACTED vs INFERRED）这个设计细节值得记住。在一个大型代码库里，你需要知道"这条关系是代码里写死的还是 AI 猜的"，这直接影响你对答案的信任程度和后续的决策。

2.5 个月 73,000 Stars，说明这个痛点是真实的。

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。

← 返回博客列表