Graphify 深度解析：当 Karpathy 的／raw 文件夹有了大脑

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

 # Graphify 深度解析：当 Karpathy 的 /raw 文件夹有了大脑

开篇：那个让 Andrej Karpathy 头疼的问题

想象你是一位 AI 研究员。你的桌面上有一个文件夹，叫 /raw。

里面有什么？

昨天刚读的 Transformer 论文 PDF
上周截的某条推文讨论优化器
三个月前白板上的架构草图（拍的照）
随手记的 Markdown 笔记
某个实验的代码片段

这些素材之间的关联，全在你脑子里。

现在你想问 Claude Code："我之前看到那个关于注意力机制的优化技巧，跟我现在的代码有什么关系？"

Claude 会怎么做？

它会打开 /raw 文件夹，看到 200 个文件，然后——全部读一遍。52 个文件，200k Token，$2-3 的成本，就为了回答一个简单问题。

这就是 Andrej Karpathy 公开吐槽过的问题。他在 X 上分享自己的工作流时，那个 /raw 文件夹成了传奇。

Graphify 就是来解决这个问题的。

第一部分：71.5 倍的 Token 压缩率

一次构建，终身受益

Graphify 的核心洞察很简单：

> 不要把原始文件当知识库，把结构化的知识图谱当知识库。

它做了一件看似简单但极其巧妙的事——把你的文件堆变成一张图。

项目	原始方式	Graphify
Karpathy 素材包	52 文件 / 200k+ Token	图谱查询 / 2.8k Token
压缩率	1x	71.5x
持久化	每次重读	一次构建，跨会话复用
增量更新	重新全读	只处理变更文件

这 71.5 倍的差距是怎么来的？

原始方式：每问一个问题，Agent 都要重新读取所有文件，从非结构化的文本中重新提取关系。

Graphify 方式：一次性把文件解析成知识图谱（节点 + 边），之后的查询只是在图上遍历——2-3 跳邻居，几百个 Token 搞定。

第二部分：双通道提取引擎

通道 A：AST 确定性提取（零 LLM 开销）

对于代码文件，Graphify 不走 LLM——它用 tree-sitter 直接解析抽象语法树。

支持 15 种语言：

Python, TypeScript, JavaScript, Go, Rust, Java C, C++, Ruby, C#, Kotlin, Scala PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C

提取什么？

类定义、函数签名
Import/Export 关系
调用图（Call Graph）
文档字符串
特殊注释标记：# WHY:, # HACK:, # NOTE:, # IMPORTANT:

这些注释不是普通注释——它们是设计决策的显式记录。

def optimize_attention(q, k, v): # WHY: Flash Attention 在序列长度 > 2048 时内存效率更高 # HACK: 需要手动处理 causal mask 的边界情况 if seq_len > 2048: return flash_attention(q, k, v)

Graphify 会把这些注释提取为 rationale_for 边——不是代码做了什么，而是为什么这么做。

通道 B：语义提取（LLM 子代理）

对于非代码文件，Graphify 启动 Claude 子代理并行处理：

文件类型	处理方式
`.md/.txt/.rst`	概念提取 + 关系识别
`.pdf`	引用挖掘 + 核心概念
`.png/.jpg/.webp/.gif`	Claude Vision 图像理解

这意味着什么？

一张白板草图可以被解析为架构节点
一篇论文的"注意力机制"概念会自动链接到你代码中的 Attention 类
推文截图里的优化技巧会成为图中的独立节点

多模态知识图谱——这是传统代码分析工具做不到的。

第三部分：三级置信度——诚实的 AI

Graphify 最让我喜欢的设计，是它的诚实。

每条关系边都被标记为三级之一：

标签	含义	置信度
EXTRACTED	直接从源码找到的显式关系	1.0
INFERRED	合理推断的关系	0.6-0.9
AMBIGUOUS	不确定，标记待审查	人工审查

EXTRACTED 的例子：

from utils.auth import DigestAuth # 提取为：当前文件 --imports--> DigestAuth [EXTRACTED, 1.0]

INFERRED 的例子：

两个函数解决同一问题但没有调用关系 推断为：func_a --semantically_similar_to--> func_b [INFERRED, 0.82]

AMBIGUOUS 的例子：

一段注释提到"参考论文 X 的方法" 但无法确定具体是论文中的哪个概念 标记为：AMBIGUOUS（待人工确认）

这套体系的核心哲学：对自己"找到了什么"和"猜测了什么"保持诚实。

这比那些自信满满胡说八道的 AI 输出强太多了。

第四部分：图拓扑社区检测

不需要向量数据库的聚类

Graphify 使用 Leiden 算法（来自 graspologic 库）进行社区发现。

关键点：完全基于图的边密度拓扑，不需要任何嵌入向量或向量数据库。

这意味着什么？

没有 embedding 开销
没有向量数据库部署
聚类结果反映真实的代码结构关系，而非表面的语义相似

社区发现的结果：

每个节点被标记为属于哪个社区
社区代表一个主题领域（如"认证流程"、"数据层"、"前端组件"）
可视化时按社区着色，一眼看出架构边界

上帝节点与惊人连接

社区检测后，Graphify 会输出三类关键信息：

上帝节点（God Nodes）：

度数最高的节点
所有东西都连接到的核心概念
例如：被 15 个模块依赖的 BaseHandler 类

惊人连接（Surprising Connections）：

跨社区、跨文件类型的意外关联
按综合评分排序
Code-Paper 边（代码-论文关联）比 Code-Code 边权重更高
附带 plain-English 解释：为什么这两个东西有关联

建议问题（Suggested Questions）：

4-5 个图谱最擅长回答的问题
例如："为什么日志模块和认证模块共享同一个配置解析器？"

第五部分：管线架构——Unix 哲学的胜利

Graphify 的架构清晰得让人舒服：

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

每个阶段是一个独立模块中的单一函数：

模块	职责	输入 → 输出
`detect.py`	文件收集与过滤	directory → `[Path]`
`extract.py`	AST + 语义提取	file path → `{nodes, edges}`
`build.py`	图构建与节点去重	extractions → `nx.Graph`
`cluster.py`	Leiden 社区检测	graph → graph (带 community 属性)
`analyze.py`	核心分析	graph → analysis dict
`report.py`	报告生成	graph + analysis → GRAPH_REPORT.md
`export.py`	多格式导出	graph → HTML/JSON/Obsidian/…

设计原则：

无共享状态
无副作用（所有输出仅写入 graphify-out/）
通过普通 Python 字典和 NetworkX 图通信

第六部分：丰富的输出格式

一次运行，产出四类核心输出：

graphify-out/
├── graph.html          # 交互式可视化图（vis.js）
├── GRAPH_REPORT.md     # 审计报告：上帝节点、惊人连接、建议问题
├── graph.json          # 持久化图数据（可跨会话查询）
└── cache/              # SHA256 缓存（增量更新）

可选输出

参数	输出	用途
`--obsidian`	`obsidian/`	Obsidian 知识库
`--wiki`	`wiki/`	Wikipedia 风格文章
`--svg`	`graph.svg`	矢量图
`--graphml`	`graph.graphml`	Gephi / yEd
`--neo4j`	`cypher.txt`	Neo4j 导入脚本
`--neo4j-push`	直接推送	推送到运行中的 Neo4j
`--mcp`	MCP 服务器	其他 Agent 实时查询

Obsidian 集成

这是很多人关心的功能：

/graphify . --obsidian --obsidian-dir ~/vaults/myproject

生成的 Obsidian 知识库包含：

每个节点作为一个 Markdown 笔记
双向链接（[[node_name]]）
社区作为标签
关系作为链接类型

可以直接在 Obsidian 中浏览整个代码库的知识结构。

第七部分：OpenClaw 集成详解

Graphify 支持四个平台：

Claude Code
Codex
OpenCode
OpenClaw（重点）

OpenClaw 的特殊之处

安装：

pip install graphifyy && graphify install --platform claw

这会将 skill-claw.md 复制到 ~/.claw/skills/graphify/SKILL.md。

关键差异：

特性	Claude Code	OpenClaw
语义提取	并行子代理	顺序执行
Always-on	CLAUDE.md + PreToolUse hook	AGENTS.md only
首次构建速度	快	较慢（但结果一致）

为什么顺序执行？

skill-claw.md 中明确说明：由于 OpenClaw 的多代理支持尚处于早期阶段，提取过程是逐文件顺序执行的。

这意味着：

AST 提取不受影响（仍然是瞬时完成）
语义提取（文档/图片）会变慢
但最终图谱质量完全一致

Always-on 模式

graphify claw install

这会在项目根目录创建 AGENTS.md：

 graphify 在回答架构或代码库问题前： 1. 读取 `graphify-out/GRAPH_REPORT.md` 了解上帝节点和社区结构 2. 如果存在 `graphify-out/wiki/index.md`，优先导航 wiki 而非直接读源文件 3. 修改代码后自动触发图谱重建

注意：OpenClaw 不支持 Claude Code 的 PreToolUse hook（在每次 Glob/Grep 前自动提醒）。AGENTS.md 是 OpenClaw 上唯一的 always-on 机制。

在 OpenClaw 中使用

构建：

/graphify .

查询：

/graphify query "什么连接了认证模块和数据库？" /pathify query "..." --dfs # 深度追踪特定路径 /graphify path "AuthModule" "Database" # 最短路径 /graphify explain "Gateway" # 节点完整解释

第八部分：运维自动化

Git Hooks

graphify hook install

安装 post-commit 和 post-checkout 钩子：

每次 commit 后自动重建图谱
每次分支切换后自动重建
仅代码文件（AST），零 LLM 开销
如果重建失败，钩子以非零退出码结束，Git 会显式报告错误

文件监听

/graphify . --watch

后台监控：

代码文件变更：即时触发 AST 重建（无 LLM）
文档/图片变更：写 flag 文件并通知执行 --update
3 秒防抖

增量更新

/graphify . --update

比较 SHA256 缓存
只处理变更文件
合并到现有图谱

如果只改了代码文件，自动跳过语义提取（零 LLM 开销）。

反馈回路

每次 /graphify query 的问答结果自动保存到 graphify-out/memory/。

下次 --update 时，这些结果会被提取为图中的新节点。

知识图谱越用越智能。

第九部分：典型使用场景

场景 1：接手陌生项目

你刚加入团队，面对几十个源文件。

/graphify .

5 分钟后，你知道了：

上帝节点：BaseHandler 被 15 个模块依赖
社区结构：3 个主要模块边界
惊人连接：日志模块和认证模块共享配置解析器
建议问题："为什么错误处理在数据层而非 API 层？"

不需要读一行代码，你已经知道骨架。

场景 2：个人知识库

mkdir ~/knowledge/raw cd ~/knowledge/raw # 扔进去各种素材 # - 论文 PDF # - 推文截图 # - 白板照片 # - 代码片段 # - Markdown 笔记 /graphify . --obsidian

打开 Obsidian，一个跨模态的知识图谱等着你：

Transformer 论文的"注意力机制"链接到代码中的 Attention 类
推文里的优化技巧成为独立节点
白板草图被解析为架构节点

场景 3：追踪依赖链路

Code Review 时发现改了 DigestAuth 后 Response 模块测试挂了。

/graphify path "DigestAuth" "Response"

输出：

Shortest path (3 hops): DigestAuth --calls--> [EXTRACTED] AuthFlow --shares_data_with--> [INFERRED, 0.82] RequestBuilder --implements--> [EXTRACTED] Response

原来经过 AuthFlow 和 RequestBuilder，而且中间那段是推断关系（共享数据结构）。

场景 4：添加外部资料

读到一篇相关论文：

/graphify add https://arxiv.org/abs/1706.03762 --author "Vaswani"

自动抓取、保存、触发 --update，只提取新文件。

论文中的概念会和代码中的已有节点自动建立跨模态关联。

第十部分：技术栈与隐私

技术栈

组件	用途
NetworkX	图数据结构
Leiden (graspologic)	社区检测
tree-sitter	AST 解析
Claude API	语义提取
vis.js	可视化

无需 Neo4j，无需服务器，完全本地运行。

隐私

代码文件：tree-sitter 本地处理，无文件内容离开你的机器
文档/图片：发送到 Anthropic API 进行语义提取
无遥测、无使用追踪、无分析
唯一的网络调用是 Anthropic API（使用你自己的 API Key）

结语：从文件堆到知识图谱

Graphify 的价值可以用一句话概括：

> 把非结构化的文件堆，变成结构化的知识图谱。

它不是第一个做代码分析的，但它是第一个真正为AI 编程助手设计的知识库工具：

71.5x Token 压缩：让大规模代码库查询变得经济可行
多模态：代码、文档、论文、图片统一图谱
诚实：三级置信度让你知道什么是找到，什么是猜测
持久化：一次构建，跨会话复用
增量更新：只处理变更，零重复开销
丰富导出：HTML、Obsidian、Neo4j、MCP，随你用

对于 Karpathy 那个 /raw 文件夹的问题，Graphify 给出了优雅的答案：

不是让 AI 每次都重新读一遍，而是帮 AI 把文件预先消化成知识。

未来的 AI 编程工作流，一定是先构建知识图谱，再基于图谱进行推理。

Graphify 让这种未来，现在就能用。

参考信息

GitHub: https://github.com/safishamsi/graphify
安装: pip install graphifyy && graphify install
教程: https://www.aivi.fyi/llms/graphify
License: MIT
Stars: ~2.2k

#知识图谱 #Karpathy #AI编程 #OpenClaw #技能工具 #小凯

Graphify 深度解析：当 Karpathy 的 ／raw 文件夹有了大脑