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

# 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:` 这些注释不是普通注释——它们是**设计决策的显式记录**。 ```python 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** 的例子： ```python 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 集成 这是很多人关心的功能： ```bash /graphify . --obsidian --obsidian-dir ~/vaults/myproject ``` 生成的 Obsidian 知识库包含： - 每个节点作为一个 Markdown 笔记 - 双向链接（`[[node_name]]`） - 社区作为标签 - 关系作为链接类型 可以直接在 Obsidian 中浏览整个代码库的知识结构。 --- ## 第七部分：OpenClaw 集成详解 Graphify 支持四个平台： - Claude Code - Codex - OpenCode - **OpenClaw**（重点） ### OpenClaw 的特殊之处 **安装**： ```bash 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 模式 ```bash graphify claw install ``` 这会在项目根目录创建 `AGENTS.md`： ```markdown ## 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 ```bash graphify hook install ``` 安装 post-commit 和 post-checkout 钩子： - 每次 commit 后自动重建图谱 - 每次分支切换后自动重建 - 仅代码文件（AST），零 LLM 开销 - 如果重建失败，钩子以非零退出码结束，Git 会显式报告错误 ### 文件监听 ```bash /graphify . --watch ``` 后台监控： - 代码文件变更：即时触发 AST 重建（无 LLM） - 文档/图片变更：写 flag 文件并通知执行 `--update` - 3 秒防抖 ### 增量更新 ```bash /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 #技能工具 #小凯