Graphify：代码库知识图谱工具

1. 项目概述

Graphify 可将任何代码库——连同其文档、SQL 模式、配置文件和 PDF——转化为可查询的知识图谱，让开发者通过可解释的图谱遍历来理解大型、陌生的项目，而无需手动搜索文件或依赖不透明的语义搜索。

2. 背景与定位

理解大型代码库的传统方式要么是手动搜索文件，要么是依赖向量嵌入搜索，后者会返回“相似”结果，却无法解释为什么两段代码相关。Graphify 的诞生正是为了弥合这一差距：它使用确定性的 AST 工具（tree-sitter）在本地解析源代码，并构建一个包含实体和关系的真实图谱，该图谱可被遍历、查询和解释。

该项目的核心使命是透明性。它提取的每个关系都被标记为 EXTRACTED（源代码中显式存在，如导入或函数调用）或 INFERRED（由 graphify 自身的分析解析得出），因此开发者始终能知道某个连接是代码中的事实还是推导出的结论。

与典型的 RAG 式代码助手相比，graphify 明确将自己定位为非向量索引——构建核心图谱不涉及嵌入或向量存储。代码分析完全通过 tree-sitter 在本地机器上运行，构建源代码图谱无需任何 LLM 调用，也无需消耗任何 API 额度。可选的 AI 后端仅在从 PDF、图像和视频等非代码格式进行语义提取时才会被调用。

3. 功能分类

🕸️ 图谱构建 — 核心能力，从项目中构建知识图谱

上帝节点检测（识别代码库中连接最多的概念）
使用基于 Leiden 的聚类进行社区检测，以发现子系统
通过 tree-sitter 在约 40 种语言中解析跨文件链接
理由提取，将 # NOTE: 和 # WHY: 注释转化为一等图谱节点
增量更新，仅重新提取变更过的文件

🔍 查询与探索 — 用于在图谱构建后对其进行查询的命令

针对 graph.json 的自然语言查询
两个命名实体之间的最短路径查找
explain 命令，用于揭示某个实体为何重要以及哪些内容与其连接
AI 辅助的 PR 分类，按相关性对审查队列进行排序
架构图导出（例如调用流 HTML 可视化）

🌐 多格式摄取 — 将图谱扩展到源代码之外

覆盖 36 种 tree-sitter 语法（Python、TypeScript、Go、Rust、Java、C/C++、Ruby 等）的源代码
文档和 PDF
图像和视频/音频，通过 faster-whisper 进行本地转录
SQL 模式和基础设施即代码（Terraform）
针对 Salesforce Apex、Pascal/Delphi 及其他小众生态系统的可选扩展

🤖 AI 助手集成 — 将图谱引入现有开发者工作流

在 20 多个 AI 编程助手中原生支持 /graphify 技能/命令
平台特定的安装程序（钩子、指令文件或原生技能注册）
覆盖 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot CLI 等

4. 核心亮点

确定性、可解释的图谱 — 每条边都被标记为提取的事实或推导的结论，消除了基于嵌入的相似性搜索中常见的猜测。
完全本地化的代码分析 — 为源代码构建图谱无需任何 LLM 调用和 API 额度；代码本身不会离开机器。
广泛的语言覆盖 — 开箱即用支持 36 种 tree-sitter 语法，覆盖几乎所有主流语言，并通过可选扩展支持多种专业语言。
深度 AI 助手集成 — 作为 20 多种主流 AI 编程工具中的原生命令运行，无需单独的独立工作流。
理由即数据 — 设计决策注释（# NOTE:、# WHY:）被提升为可查询的图谱节点，保留了通常会丢失的设计意图。
强大的检索基准 — 在 LOCOMO 基准（n=300）上，graphify 报告 recall@10 为 0.497，明显领先于其基准中引用的同类记忆/检索工具。

5. 按角色划分的使用场景

普通开发者
在现有的 AI 编程助手中使用 /graphify .，即可在陌生的代码库上获得即时、可解释的上下文——无需手动搜索文件，即可追踪功能如何跨文件连接。

DevOps/SRE
利用 SQL 模式和 Terraform 摄取功能，将基础设施即代码关系与应用代码一起映射，并使用路径查询来追踪服务与其底层基础设施之间的依赖关系。

数据/研究科学家
将文档、PDF，甚至视频/音频材料摄取到与代码库相同的图谱中，从而能够将研究笔记和规范直接与实现连接起来进行查询。

项目经理
使用 graphify prs --triage 获取 AI 排序的拉取请求审查队列，并使用图谱导出（例如调用流图）向利益相关者传达架构，而无需手动绘制图表。

6. 快速上手

查找所需内容 — 浏览仓库 docs/ 目录中的文档、架构指南和翻译版 README（14 种语言），或阅读 ARCHITECTURE.md 了解模块级分解。

安装/集成

uv tool install graphifyy
graphify install

然后在受支持的 AI 编程助手中调用 /graphify . 为当前项目构建图谱。其他安装方式：

pipx install graphifyy
# 或
pip install graphifyy

贡献

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify && git checkout v8
uv sync --all-extras
uv run pytest tests/ -q

活跃开发在 v8 分支上进行；提交遵循 fix: / feat: / docs: 前缀，新的语言支持应在 tests/fixtures/ 下包含测试夹具，并在 test_languages.py 中添加测试用例。

7. 项目结构

graphify/
├── .github/              # GitHub 工作流（CI、发布）
├── docs/                 # 文档，包括 14 种语言的翻译
├── graphify/             # 主包源代码
├── scripts/              # 实用脚本
├── tests/                # 测试套件，包括语言夹具
├── tools/                # 辅助工具
├── worked/                # 带审查注释的示例提取
├── ARCHITECTURE.md       # 模块职责和语言集成指南
├── BENCHMARKS.md         # 性能和准确性指标
└── AGENTS.md             # 代理框架文档

graphify/ 包含核心提取和查询引擎；ARCHITECTURE.md 是贡献者了解模块如何组合或添加新语言支持的推荐起点。

8. 相关生态

依赖/构建于：

tree-sitter — 提供驱动本地代码分析的确定性 AST 解析
faster-whisper — 用于视频/音频输入的本地转录
可选的图和数据库后端：Neo4j、FalkorDB、PostgreSQL/SQL

互补工具：

与 AI 编程助手（Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot CLI 等）协同工作，而非替代它们——它提供这些工具消费的结构化上下文
可选的 AI 后端（包括通过 Ollama 提供的本地选项），用于从文档、图像和视频中进行语义提取

9. 许可证

Graphify 采用双重许可，用户可以选择最适合其使用场景的许可证。

✅ 在 Apache License 2.0 或 MIT License 下使用、修改和分发代码，任选其一
✅ 在任一许可证条款下用于商业和专有项目
❌ 任一许可证均不提供担保——软件按“原样”提供
ℹ️ Apache-2.0 和 MIT 的署名和许可证声明要求略有不同——在重新分发前请审查所选许可证的具体条款

10. 常见问题

问：graphify 会将我的代码发送到外部服务器或 LLM 吗？
答：不会。源代码通过 tree-sitter 在本地解析，为代码构建图谱无需任何 LLM 调用。只有对 PDF、图像和视频的可选处理会使用配置的 AI 后端，而且即使如此，也可以通过 Ollama 完全在本地运行。

问：graphify 支持哪些 AI 编程助手？
答：超过 20 个，包括 Claude Code、Cursor、Codex、Gemini CLI 和 GitHub Copilot CLI。运行 graphify install 即可设置平台特定的集成。

问：这与使用向量嵌入的 RAG 工具有何不同？
答：Graphify 构建的是实际可遍历的图谱，而非向量索引。关系被明确标记为 EXTRACTED 或 INFERRED，因此结果是可解释的，而非相似性分数。

问：支持多少种编程语言？
答：默认包含 36 种 tree-sitter 语法，覆盖大多数主流语言，并为 Salesforce Apex 和 Pascal/Delphi 等语言提供额外的可选扩展。

问：如何查询现有图谱？
答：针对生成的 graph.json 使用 graphify query "什么连接了 auth 和 database？"、graphify path "ServiceA" "ServiceB" 或 graphify explain "ComponentName" 等命令。

11. 快速链接

仓库：https://github.com/Graphify-Labs/graphify
架构指南：仓库根目录下的 ARCHITECTURE.md
贡献：仓库 README 中的开发设置和指南
基准：仓库根目录下的 BENCHMARKS.md

12. 总结

Graphify 为开发者提供了一张可解释、本地计算的图谱，展示代码库——及其周边文档、模式和其他工件——如何真正组合在一起，用可遍历、可查询的图谱取代了手动文件搜索和不透明的相似性搜索。它对于刚接触大型或陌生代码库的开发者，以及希望 AI 编程助手基于可验证、有来源的上下文而非猜测来推理架构的团队尤其有价值。