AI超元域

AI超元域up主

3 minute read

Graphify 是一个面向 AI 编程助手的「技能插件」（Skill），其核心使命是：将任意文件夹中的代码、文档、论文、图片转化为一个可查询的知识图谱。它解决的核心痛点来自一个被 Andrej Karpathy 广泛传播的工作流问题——你有一个 /raw 文件夹，里面塞满了论文、推文截图、代码片段和笔记，但这些素材之间的关联全在你脑子里，任何 AI 助手想要理解它们就必须把所有文件全读一遍。Graphify 的答案是：一次性构建知识图谱，之后每次查询仅消耗原始 token 的 1/71.5。

该项目是 MIT 许可的开源项目，截至目前已有约 2.2k stars，支持 Claude Code、Codex、OpenCode 和 OpenClaw 四个 AI 编程平台。

🚀本篇笔记所对应的视频：

二、核心功能全景

1. 双通道提取引擎

Graphify 的提取分为两个独立的通道，可并行执行：

通道 A — AST 确定性提取：对代码文件使用 tree-sitter 进行抽象语法树分析，零 LLM 开销。支持 15 种编程语言（Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua）。提取内容包括类定义、函数签名、导入关系、调用图、文档字符串，以及带有 # WHY:、# HACK:、# NOTE: 等标记的设计决策注释。

通道 B — 语义提取：由 LLM 子代理对文档（.md/.txt/.rst）、论文（.pdf）和图片（.png/.jpg/.webp/.gif）进行概念抽取。图片使用视觉模型分析，PDF 进行引用挖掘和概念提取。这一通道会产生 token 消耗。

2. 三级置信度标签体系

每条关系边都被标记为三级之一：EXTRACTED（直接从源码找到的显式关系，置信度固定为 1.0）、INFERRED（合理推断的关系，附带 0.6-0.9 的置信度评分）、AMBIGUOUS（不确定的关系，标记留待人工审查）。这套体系是 graphify 的核心设计哲学——对自己「找到了什么」和「猜测了什么」保持诚实。

3. 图拓扑社区检测

使用 Leiden 算法（基于 graspologic 库）进行社区发现，完全基于图的边密度拓扑，不需要任何嵌入向量或向量数据库。LLM 提取出的语义相似性边（semantically_similar_to，标记为 INFERRED）直接参与社区检测的计算。

4. 丰富的输出格式

一次运行产出四类核心输出：graph.html（交互式可视化图，支持节点点击、搜索、按社区筛选）、GRAPH_REPORT.md（包含上帝节点、惊人连接、建议问题的审计报告）、graph.json（持久化图数据，可跨会话查询）、以及 cache/ 目录（SHA256 缓存，增量更新仅处理变更文件）。

可选输出还包括：Obsidian 知识库（--obsidian）、SVG 导出（--svg）、GraphML 格式（--graphml，供 Gephi/yEd 使用）、Neo4j Cypher 脚本（--neo4j）、直接推送 Neo4j（--neo4j-push）、MCP 服务器（--mcp）、Wiki 风格的 Markdown 知识库（--wiki）。

5. 高级图特性

超边（Hyperedges）：捕捉 3 个以上节点之间的群组关系，比如实现同一协议的所有类、认证流程中的所有函数。这是普通的成对边无法表达的关系。

语义相似性边：跨文件的概念链接，当两个函数解决同一问题但没有任何调用关系时自动建立连接。

设计决策节点（Rationale Nodes）：从文档和代码注释中提取的「为什么」信息，以 rationale_for 关系连接到对应的代码元素。

6. 运维自动化

Git Hooks（graphify hook install）：安装 post-commit 和 post-checkout 钩子，每次提交和分支切换后自动重建图谱（仅代码文件，无 LLM 开销）。如果重建失败，钩子会以非零退出码结束，Git 会显式地报告错误。

文件监听（--watch）：后台监控文件变更，代码变更即时触发 AST 重建，文档/图片变更则通知用户执行 --update。

反馈回路：每次 /graphify query 的问答结果自动保存到 graphify-out/memory/，下次 --update 时会被提取为图中的节点，让知识图谱越用越智能。

三、典型使用场景

场景 1：快速理解新代码库。你刚加入一个项目，面对数十个源文件。运行 /graphify . 后，GRAPH_REPORT 告诉你哪些是「上帝节点」（所有东西都连接到的核心概念），社区结构揭示了模块的真实边界，惊人连接可能揭示出某个看似无关的工具函数实际是性能瓶颈的根源。

场景 2：个人知识库管理。把论文、推文截图、白板照片、代码实验扔进一个文件夹，graphify 自动将它们连接起来。例如一篇 Transformer 论文中的「注意力机制」概念会与你代码中的 Attention 类自动建立跨模态关联。

场景 3：大型研究项目的文献管理。通过 /graphify add 从 arXiv 拉取论文、从 Twitter/X 抓取推文，自动融入现有图谱。引用图和概念图合二为一，让你发现论文之间的隐藏联系。

场景 4：团队协作中的架构文档自动化。通过 --wiki 生成 Wikipedia 风格的知识库，每个社区一篇文章，自动交叉引用。新成员阅读 index.md 即可导航整个代码库的知识结构。

四、管线架构

根据 ARCHITECTURE.md，整个管线是 detect() → extract() → build_graph() → cluster() → analyze() → report() → export()，每个阶段是一个独立模块中的单一函数，通过普通 Python 字典和 NetworkX 图进行通信，无共享状态，无副作用（所有输出仅写入 graphify-out/ 目录）。

核心模块包括：detect.py（文件收集与过滤）、extract.py（AST + 语义提取）、build.py（图构建与节点去重）、cluster.py（Leiden 社区检测）、analyze.py（上帝节点/惊人连接/建议问题分析）、report.py（报告生成）、export.py（多格式导出）、security.py（URL 验证、SSRF 防护、Cypher 注入防护等安全模块）。

五、Graphify 如何在 OpenClaw 中使用

这是你问题的核心部分。根据源码和文档的详细分析，在 OpenClaw 中使用 graphify 的完整流程如下：

第一步：安装

bash

`pip install graphifyy && graphify install –platform claw


这个命令做了一件事：将 `skill-claw.md` 文件复制到 `~/.claw/skills/graphify/SKILL.md`。这个路径是 OpenClaw 读取技能定义的标准位置。

### 第二步：使用 /graphify 命令构建图谱

在 OpenClaw 中打开你的项目，输入：

/graphify .`

OpenClaw 会读取 ~/.claw/skills/graphify/SKILL.md 中定义的完整管线指令，按步骤执行。

第三步：OpenClaw 的特殊行为

OpenClaw 与其他平台有一个关键区别——语义提取使用顺序模式而非并行模式。在 skill-claw.md 中明确写到：由于 OpenClaw 的多代理支持尚处于早期阶段，提取过程是逐文件顺序执行的。这意味着相比 Claude Code 的并行子代理提取，OpenClaw 上的首次构建会更慢，但结果完全一致。AST 提取（代码文件）不受此影响，仍然是瞬时完成的。

第四步：启用 Always-on 模式（推荐）

bash

graphify claw install

这个命令会在你的项目根目录写入一个 AGENTS.md 文件（而非 Claude Code 使用的 CLAUDE.md），其中包含一个 ## graphify 段落，指示 OpenClaw：在回答架构或代码库问题前，先读取 graphify-out/GRAPH_REPORT.md 了解上帝节点和社区结构；如果存在 graphify-out/wiki/index.md，优先导航 wiki 而非直接读源文件；修改代码后自动触发图谱重建。

需要注意的是，OpenClaw 不支持 Claude Code 的 PreToolUse hook 机制（该机制能在 Claude 每次执行 Glob/Grep 操作前自动提醒它先查看图谱）。AGENTS.md 是 OpenClaw 上唯一的 always-on 机制。

第五步：查询图谱

构建完成后，可使用以下命令在 OpenClaw 中交互式探索：

  • /graphify query "什么连接了认证模块和数据库？" — BFS 广度遍历
  • /graphify query "..." --dfs — DFS 深度追踪特定路径
  • /graphify path "AuthModule" "Database" — 两个概念间的最短路径
  • /graphify explain "SwinTransformer" — 某个节点的完整解释

第六步：卸载

bash

graphify claw uninstall

这会从 AGENTS.md 中移除 graphify 段落。如果移除后文件为空，会直接删除该文件。

OpenClaw 集成的技术细节总结

从源码 __main__.py 可以看到，OpenClaw 的平台配置为：技能文件使用 skill-claw.md，安装目标路径为 ~/.claw/skills/graphify/SKILL.md，不使用 CLAUDE.md（claude_md: False）。always-on 集成通过写入项目根目录的 AGENTS.md 实现。Git hooks（graphify hook install）是跨平台的，在 OpenClaw 上同样适用。

用例一：接手一个陌生项目，5 分钟建立全局认知

你刚加入团队，面前是一个几十个文件的 Python 项目，完全不知道从哪里看起。

/graphify .

graphify 扫描整个目录，代码文件走 tree-sitter AST 提取，文档走语义提取，几分钟后直接在聊天里输出三段关键信息：上帝节点（所有东西都连接到的核心概念，比如某个 BaseHandler 类被 15 个模块依赖）、惊人连接（你绝对想不到的跨模块关联，比如日志模块和认证模块共享同一个配置解析器）、建议问题（图谱最擅长回答的 4-5 个架构问题）。同时生成 graphify-out/graph.html，浏览器打开就是一张可交互的节点图，按社区着色，点击任意节点查看它的所有连接。

你不需要读一行代码就已经知道了这个项目的骨架。

用例二：追踪两个概念之间的依赖链路

你在 code review 时发现改了 DigestAuth 模块后 Response 模块的测试挂了，但你不理解它们之间有什么关系。

/graphify path "DigestAuth" "Response"

graphify 在已有的知识图谱上跑最短路径算法，返回类似这样的结果：

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

每一跳都标注了关系类型、置信度和源码位置。你立刻知道中间经过了 AuthFlow 和 RequestBuilder，而且 AuthFlow 到 RequestBuilder 之间的关系是推断出来的（不是显式调用，而是共享数据结构），置信度 0.82。这比自己在代码里追调用链快得多。

用例三：深度理解某个核心模块

你想搞清楚项目里最关键的 Gateway 模块到底做了什么、和谁有关系。

/graphify explain "Gateway"

返回该节点的完整连接画像：度数（多少个其他节点连接到它）、所有邻居节点及其关系类型、源码文件位置。然后 Claude 用这些图数据写一段 3-5 句话的结构化解释，每个论断都引用了 source_location。

用例四：带着具体问题查询图谱

你想知道项目里的错误处理和日志记录之间是怎么协作的。

/graphify query "错误处理和日志记录之间有什么关系？"

graphify 用 BFS 从匹配的节点出发，向外探索 3 层邻居，返回相关的子图。Claude 基于子图中的节点、边和置信度标签来回答你的问题，而且只使用图谱中实际存在的信息——如果图谱里没有足够的数据，它会明确告诉你而不是编造。

如果你想追踪一条具体的依赖链而不是看广泛的上下文：

/graphify query "错误处理和日志记录之间有什么关系？" --dfs

DFS 模式会沿着一条路径深入追踪到 6 层，适合回答”A 怎么最终影响到 B”这类链式问题。

用例五：往知识库里添加外部资料

你读到一篇和项目相关的论文，想把它纳入图谱。

/graphify add <https://arxiv.org/abs/1706.03762>

graphify 自动抓取论文的摘要和元数据，保存为 Markdown 文件到 ./raw 目录，然后自动触发 --update 管线，只提取这一个新文件并合入现有图谱。论文中的概念会和代码中的已有节点自动建立跨模态关联。

同样支持推文：

/graphify add <https://x.com/karpathy/status/>... --author "Karpathy"

也支持任意网页、PDF 链接和图片 URL。

用例六：代码改了之后增量更新图谱

你做了一轮重构，改了几个核心文件。

/graphify . --update

graphify 比较 SHA256 缓存，只对变更的文件重新提取。如果只改了代码文件，它会自动跳过语义提取（零 LLM 开销，只跑 AST）。更新完成后还会展示图谱 diff——新增了哪些节点、新增了多少条边。

用例七：让图谱完全自动维护，不需要手动操作

你希望图谱永远和代码保持同步，不想记任何命令。

# 在终端执行一次
graphify claude install
graphify hook install

第一条命令做两件事：在项目的 CLAUDE.md 里写入指令让 Claude 每次回答架构问题前自动查图谱，并在 .claude/settings.json 里注册 PreToolUse hook 在每次 Glob/Grep 前自动提醒。第二条命令安装 git post-commit 和 post-checkout 钩子，每次提交和切换分支都自动重建。

装完之后你就可以忘掉 graphify 的存在了。你正常提问，Claude 自动走图谱路径；你正常 commit，图谱自动更新。

用例八：用 –mode deep 做更激进的关系发现

你觉得默认提取太保守，想发现更多潜在的关联。

/graphify . --mode deep

deep 模式让语义提取的子代理更激进地推断 INFERRED 边——间接依赖、共享假设、潜在耦合都会被标注出来。不确定的用 AMBIGUOUS 标记而不是省略。适合做架构审计或准备重构前的全面摸底。

用例九：生成可供团队浏览的 Wiki 知识库

你想让团队其他成员也能浏览项目的知识结构，但他们不用 Claude Code。

/graphify . --wiki

生成 graphify-out/wiki/ 目录，包含 index.md 入口页和每个社区、每个上帝节点的独立文章，带有交叉链接、内聚度评分和审计追踪。任何人用 Markdown 阅读器就能导航整个知识库。

用例十：导出到外部工具做更深入的分析

你想用专业的图分析工具进一步探索。

/graphify . --graphml    # 导出给 Gephi 或 yEd
/graphify . --neo4j      # 生成 Cypher 导入脚本
/graphify . --neo4j-push bolt://localhost:7687  # 直接推到 Neo4j
/graphify . --mcp        # 启动 MCP 服务器，其他 AI agent 可以实时查询

MCP 服务器模式特别值得注意——它暴露了 query_graph、get_node、get_neighbors、shortest_path 等工具接口，可以加入 Claude Desktop 的 MCP 配置，让其他 agent 也能查询这张图谱。

用例十一：实时监听文件变更自动同步

你在一个长时间的开发会话中，希望图谱实时跟上你的改动。

/graphify . --watch

在后台终端运行。代码文件变更立即触发 AST 重建（无 LLM 开销）；文档或图片变更会写一个 flag 文件并通知你执行 --update。设有 3 秒防抖，不会因为快速连续保存触发多次重建。

用例十二：只调整社区划分，不重新提取

你觉得社区划分不够理想，想用已有的图数据重新跑一次聚类。

/graphify . --cluster-only

跳过所有提取步骤，直接加载 graph.json，重新运行 Leiden 社区检测，重新生成报告和可视化。零 token 开销，几秒完成。

Comments

You May Also Enjoy

🦞OpenClaw第二大脑：lossless-claw-enhanced让小龙虾具备精准记忆能力越用越聪明！超长对话也不会忘记早期对话细节！实测召回率直接冲到100%！保姆级教程中文增强版插件实测演示

2 minute read

如果你平时主要用 OpenClaw 跑中文任务，或者经常混合处理中英日内容，那你大概率会遇到一个很现实的问题： 上下文看起来还没满，结果实际已经快炸了。 这背后的一个关键原因，是很多上下文压缩方案在 token 估算时，默认更偏向英文文本，而对中文、日文、韩文这类 CJK 文本估算偏低。lossless-claw...