Graphify：把任何文件夹变成可查询的知识图谱

如果你曾经面对一个装满研究论文、代码文件、截图和笔记的文件夹，心想"要是我能直接向它提问就好了"——graphify 可能正是你需要的工具。它目前拥有 37.6k GitHub 星标和 4.2k fork，是 2026 年增长最快的开发者工具之一。

Graphify 做了什么

Graphify 能把任何文件夹变成可查询的知识图谱。这个概念源自 Andrej Karpathy 的 /raw 文件夹工作流：把任何东西丢进一个目录——论文、推文、截图、代码、笔记——然后获得一个结构化的知识图谱，揭示你没想到的关联。

处理流水线清晰且确定性：

detect() → extract() → build_graph() → cluster() → analyze() → report() → export()

每个阶段都是独立模块中的单一函数，通过纯 Python 字典和 NetworkX 图通信——没有共享状态，没有输出目录之外的副作用。

Graphify 做了三件 LLM 单独做不到的事

持久化图谱——关系存储在 graph.json 中，跨会话存活。几周后仍可提问，无需重新阅读所有内容。
诚实的审计追踪——每条边都标注了 EXTRACTED（已提取）、INFERRED（推断）或 AMBIGUOUS（不确定）。你始终知道哪些是发现的，哪些是猜测的。
跨文档惊喜发现——社区发现（Leiden 算法）找到不同文件中概念之间的关联，这些关联你永远不会想到主动去问。

多模态输入支持

Graphify 是完全多模态的，它不止处理代码：

类型	扩展名	提取方法
代码	`.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .mm .jl .v`	tree-sitter AST + 调用图分析
文档	`.md .txt .rst .html .mdx`	LLM 概念+关系提取
论文	`.pdf`	引用挖掘 + 概念提取
图片	`.png .jpg .webp .gif`	LLM 视觉理解——截图、图表、任何语言
视频/音频	`.mp4 .mp3 .wav .mkv`	Whisper 转录 → 作为文档处理

tree-sitter 支持 23 种语言，这是一个显著优势：对于代码，AST 提取是确定性的、免费的（零 token 成本），且对于 import 和调用图等结构关系完全准确。

提取流水线详解

结构化提取（AST）

对于代码文件，graphify 使用 tree-sitter 解析 AST 并提取：

节点：函数、类、方法、模块
边：imports_from、calls、implements、uses

这个步骤是确定性的，零 token 成本。第二个调用图分析步骤会添加用于间接调用关系的 INFERRED 边。

语义提取（LLM）

对于文档、论文和图片，graphify 分派并行子代理来提取：

节点：命名概念、实体、引用
边：cites（引用）、conceptually_related_to（概念相关）、semantically_similar_to（语义相似）、rationale_for（设计理由）
超边：3+ 个节点参与的共享概念组

还有可选的 Kimi K2.6 后端（通过 MOONSHOT_API_KEY），相比 Claude 可提取 3-6 倍更丰富的关系，每 token 成本约低 3 倍。

置信度标注：诚实系统

这是 graphify 区别于朴素 RAG 系统的关键：

标签	含义
`EXTRACTED`	关系在源文件中明确陈述（import 语句、直接调用、引用）
`INFERRED`	合理推断（共享数据结构、隐含依赖、共现关系）
`AMBIGUOUS`	不确定——标记供人工审查

每条边还附带 0.1 到 1.0 之间的 confidence_score。报告中从不在符号后隐藏不确定性——始终显示原始数字。

输出产物

运行 graphify . 会生成：

graphify-out/
├── graph.html          交互式图谱——可点击节点、搜索、社区过滤
├── obsidian/           可作为 Obsidian 知识库打开（通过 --obsidian 启用）
├── wiki/               Wikipedia 风格的文章，供 Agent 导航（--wiki）
├── GRAPH_REPORT.md     核心节点、意外连接、建议问题
├── graph.json          持久化图谱——数周后仍然可以查询，无需重新阅读
└── cache/              SHA256 缓存——重新运行只处理变更文件

GRAPH_REPORT.md 尤其有用——它包含：

核心节点（God nodes）：度最高的概念（所有关系的枢纽）
意外连接（Surprising connections）：按综合得分排序，附通俗英文解释
建议问题（Suggested questions）：图谱独特视角能回答的 4-5 个问题

Token 压缩基准测试

在混合语料库（Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件）上：查询时 token 使用量减少 71.5 倍，相比直接阅读原始文件。token 压缩比随语料库规模增长——6 个文件时图谱价值在于结构清晰度而非压缩。

安装和使用

pip install graphifyy && graphify install

PyPI 包名暂时为 graphifyy（双 y），因为 graphify 正在回收中。CLI 和技能命令仍然是 graphify。

基本用法：

/graphify .                        # 对当前目录运行完整流程
/graphify ./raw                    # 对指定文件夹运行
/graphify ./raw --mode deep        # 更激进的推断边提取
/graphify ./raw --update           # 增量更新——只重新提取变更文件
/graphify add https://arxiv.org/abs/1706.03762   # 抓取论文，更新图谱
/graphify query "attention 和 optimizer 之间有什么联系？"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

能否接入你的工作流？

简短回答：可以，而且它已经为此设计。

对 Claude Code / Codex / OpenCode / Cursor / Gemini CLI / Hermes

Graphify v5 在其 pyproject.toml 描述中明确列出了 Hermes 作为支持平台。graphify install 命令为你的 Agent 平台设置技能。技能文件是一个 61K 字符的详细编排文档，逐步指导 Agent 完成整个流程。

MCP 服务器集成

通过 --mcp 参数，graphify 启动一个 stdio MCP 服务器，暴露工具：query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path。这意味着任何兼容 MCP 的 Agent 都可以实时查询图谱：

python3 -m graphify.serve graphify-out/graph.json

Git Hook 自动重建

graphify hook install    # 安装 post-commit 钩子

每次 git commit 后，钩子检测变更的代码文件，重新运行 AST 提取，重建图谱。不需要后台进程。

Watch 模式用于 Agent 工作流

graphify . --watch       # 文件变化时自动同步图谱

代码文件保存触发即时重建（仅 AST，无需 LLM）。文档/图片变化会通知你运行 --update 进行 LLM 重新提取。适合多个 Agent 并行写代码的场景。

安全模型

Graphify 是一个本地开发工具，没有服务器组件（除非你显式启动 MCP 服务器）。所有外部输入通过 security.py 验证：

URL 验证仅允许 http/https，阻止私有 IP 和云元数据端点
下载大小上限 50 MB，文本 10 MB
路径遍历防护——图谱路径必须解析在 graphify-out/ 内
XSS 防护——所有节点标签在可视化前进行 HTML 转义
提示注入防护——标签在 MCP 文本输出中被清除

项目采用 MIT 许可，活跃维护中（214 次 commit，70 个 tag，当前版本 v5 分支上的 0.5.5）。

实际接入路径

对于已经在使用 AI 编程助手的开发者，以下是具体的接入路径：

作为技能——通过 graphify install 安装，然后在你的 Agent 中输入 /graphify . 构建项目图谱。Agent 理解图谱并可以回答关于代码库的结构性问题。
作为 MCP 服务器——将 MCP 服务器添加到 Agent 配置中，实现实时图谱查询。其他 Agent 可以发现关系而无需阅读每个文件。
作为库——import graphify 提供编程访问 extract()、build_from_json()、cluster()、god_nodes() 等函数。构建自定义流程。
作为 CI/CD 步骤——git hook 或 watch 模式自动保持图谱最新。将文档生成器或入职工具指向 GRAPH_REPORT.md。

局限性和注意事项

需要 Python 3.10–3.13——tree-sitter 绑定尚不支持 3.14
语义提取消耗 token——AST 步骤免费，但文档/论文/图片提取使用 LLM 调用，需预算规划
大图谱（>5000 节点）——HTML 可视化切换到聚合社区视图，完整节点详情通过 Obsidian 知识库导出
语料库大小警告——超过 200 个文件或 200 万字时，graphify 会请求你先选择子目录
PyPI 包名是 graphifyy（双 y）——临时措施，正在回收原始名称

结论

Graphify 解决了一个真实且日益增长的问题：随着我们的个人和专业知识库增长到涵盖代码、论文、笔记、截图和文档，我们需要一种方式来导航它们之间的连接——而不仅仅是搜索每个文件内部的文字。确定性 AST 提取、诚实置信度标注、社区发现和持久化图谱存储的结合，使它成为一个真正有用的工具，而不仅仅是演示。

71 倍的 token 压缩基准令人信服，但真正的价值是结构性的：你发现那些你不知道存在的联系。这比任何压缩比都更有价值。

来源：