一、项目定位与核心理念
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 上同样适用。
