Skip to content

chencore/graphify-knowledge-graph-docs

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
README.md
README.md
 
 

Repository files navigation

Graphify 知识图谱 - 安装与使用文档

将任何文件夹转化为可查询的知识图谱，支持 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid

📖 项目简介

Graphify 是一个 AI 编程助手技能（skill），它能够：

  • 读取代码、文档、PDF、图片等文件
  • 构建知识图谱，发现隐藏的结构和关系
  • 提供 71.5 倍的 token 节省（相比直接读取原始文件）
  • 支持跨会话持久化查询

核心特性：

  • ✅ 完全多模态：支持代码、PDF、Markdown、截图、图表、白板照片
  • ✅ 持久化图谱：跨会话可查询，无需重新读取文件
  • ✅ 智能聚类：基于 Leiden 社区发现算法
  • ✅ 置信度标注：每个关系都标记为 EXTRACTED（提取）、INFERRED（推断）或 AMBIGUOUS（模糊）
  • ✅ 缓存机制：SHA256 缓存，只处理变更的文件

🚀 快速开始

前置要求

安装步骤

# 1. 安装 graphify（PyPI 包名暂时为 graphifyy）
pip install graphifyy

# 2. 安装到你的 AI 编程助手
graphify install

平台特定安装

平台 安装命令
Claude Code (Linux/Mac) graphify install
Claude Code (Windows) graphify install --platform windows
Codex graphify install --platform codex
OpenCode graphify install --platform opencode
OpenClaw graphify install --platform claw
Factory Droid graphify install --platform droid

验证安装

# 检查安装
graphify --version

# 查看帮助
graphify --help

📚 使用指南

基本用法

在你的 AI 编程助手中输入：

/graphify .

这会在当前目录构建知识图谱。

指定目录

/graphify ./my-project

深度模式

/graphify ./raw --mode deep

更激进的推断边提取，发现更多隐藏关系。

增量更新

/graphify ./raw --update

只重新提取变更的文件，合并到现有图谱中。

只重新聚类

/graphify ./raw --cluster-only

在现有图谱上重新运行聚类，不重新提取。

📁 输出文件

Graphify 会在 graphify-out/ 目录生成以下文件：

graphify-out/
├── graph.html          # 交互式图谱（点击节点、搜索、按社区过滤）
├── GRAPH_REPORT.md     # 核心节点、意外连接、建议问题
├── graph.json          # 持久化图谱（数周后仍可查询）
└── cache/              # SHA256 缓存（只处理变更文件）

输出说明

graph.html - 交互式图谱可视化

  • 点击节点查看详情
  • 搜索特定节点
  • 按社区过滤

GRAPH_REPORT.md - 分析报告

  • 核心节点（God Nodes）：最高度的概念（所有内容都连接到的地方）
  • 意外连接：按复合分数排名，代码-论文边排名高于代码-代码
  • 建议问题：图谱特别适合回答的 4-5 个问题

graph.json - 持久化图谱

  • 跨会话查询
  • 无需重新读取原始文件

🔧 高级功能

1. 添加外部资源

# 添加 arXiv 论文
/graphify add https://arxiv.org/abs/1706.03762

# 添加推文
/graphify add https://x.com/karpathy/status/...

# 添加作者标签
/graphify add https://... --author "Name"
/graphify add https://... --contributor "Name"

2. 图谱查询

# 语义查询
/graphify query "what connects attention to the optimizer?"

# 深度优先搜索
/graphify query "what connects attention to the optimizer?" --dfs

# 限制 token 数量
/graphify query "what connects attention to the optimizer?" --budget 1500

3. 路径追踪

# 查找两个节点之间的路径
/graphify path "DigestAuth" "Response"

4. 节点解释

# 详细解释某个节点
/graphify explain "SwinTransformer"

5. 自动同步

# 监控文件变化，自动更新图谱
/graphify ./raw --watch

代码文件保存会立即触发重建（仅 AST，无 LLM）。文档/图片变化会通知你运行 --update。

6. Git 钩子

# 安装 git 钩子（提交和分支切换时自动重建）
graphify hook install

# 查看状态
graphify hook status

# 卸载
graphify hook uninstall

7. 导出格式

# 生成 Wiki
/graphify ./raw --wiki

# 导出 SVG
/graphify ./raw --svg

# 导出 GraphML（Gephi、yEd）
/graphify ./raw --graphml

# 导出 Neo4j Cypher
/graphify ./raw --neo4j

# 直接推送到 Neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687

# 启动 MCP stdio 服务器
/graphify ./raw --mcp

🤖 始终启用（Always-On）集成

Claude Code

# 安装始终启用集成
graphify claude install

# 这会：
# 1. 在 CLAUDE.md 中添加规则，让 Claude 在回答架构问题前读取 GRAPH_REPORT.md
# 2. 安装 PreToolUse 钩子，在每次 Glob/Grep 前提示存在知识图谱

# 卸载
graphify claude uninstall

其他平台

# Codex
graphify codex install

# OpenCode
graphify opencode install

# OpenClaw
graphify claw install

# Factory Droid
graphify droid install

这些平台会在项目根目录的 AGENTS.md 中写入相同的规则。

📊 支持的文件类型

类型 扩展名 提取方式
代码 .py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 AST（tree-sitter）+ 调用图 + 文档字符串/注释原理
文档 .md .txt .rst 通过 Claude 提取概念 + 关系 + 设计原理
Office .docx .xlsx 转换为 Markdown 后提取（需要 pip install graphifyy[office]）
论文 .pdf 引用挖掘 + 概念提取
图片 .png .jpg .webp .gif Claude 视觉 - 截图、图表、任何语言

🎯 使用场景

1. 理解新代码库

/graphify .

快速理解陌生项目的架构和设计决策。

2. 研究论文集

/graphify ./papers --mode deep

构建论文之间的概念图谱，发现跨论文的连接。

3. 知识管理

/graphify ./notes --wiki

将笔记转化为可导航的知识库。

4. 代码审查

/graphify ./repo --update

增量更新图谱，追踪架构演变。

⚙️ 配置

.graphifyignore

创建 .graphifyignore 文件排除不需要的文件夹：

# .graphifyignore
vendor/
node_modules/
dist/
*.generated.py

语法与 .gitignore 相同。模式匹配相对于运行 graphify 的文件夹路径。

📈 性能基准

语料库 文件数 Token 节省
Karpathy repos + 5 papers + 4 images 52 71.5x
graphify source + Transformer paper 4 5.4x
httpx (synthetic Python library) 6 ~1x

Token 节省原理：

  • 首次运行：提取并构建图谱（消耗 token）
  • 后续查询：读取紧凑图谱而非原始文件（节省 token）
  • SHA256 缓存：只重新处理变更的文件

🔍 核心概念

God Nodes（核心节点）

最高度的概念 - 所有内容都连接到的地方。

Surprising Connections（意外连接）

按复合分数排名，代码-论文边排名高于代码-代码。每个结果包含通俗易懂的"为什么"。

The "Why"（原理）

文档字符串、内联注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）和文档中的设计原理被提取为 rationale_for 节点。

不仅是代码做了什么 - 还有为什么这样写。

Confidence Scores（置信度分数）

每个 INFERRED 边都有 confidence_score（0.0-1.0）。你不仅知道推测了什么，还知道模型有多自信。EXTRACTED 边总是 1.0。

Semantic Similarity Edges（语义相似边）

跨文件概念链接，无结构连接。两个函数解决同一问题但不互相调用，代码中的类和论文中描述同一算法的概念。

Hyperedges（超边）

连接 3+ 个节点的组关系，成对边无法表达。所有实现共享协议的类、认证流程中的所有函数、论文章节中形成一个想法的所有概念。

🛠️ 手动安装（curl）

如果不想使用 pip，可以手动安装：

# 创建目录
mkdir -p ~/.claude/skills/graphify

# 下载 SKILL.md
curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v3/graphify/skill.md \
  > ~/.claude/skills/graphify/SKILL.md

添加到 ~/.claude/CLAUDE.md：

- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"` before doing anything else.

❓ 常见问题

Q: 支持哪些 AI 编程助手？

A: Claude Code、Codex、OpenCode、OpenClaw、Factory Droid。

Q: 图谱会过期吗？

A: 不会。graph.json 是持久化的，数周后仍可查询。使用 --update 增量更新。

Q: 如何节省 token？

A: 首次构建图谱会消耗 token，但后续查询读取紧凑图谱，比读取原始文件节省 71.5 倍 token。

Q: 支持中文吗？

A: 支持。Claude 视觉可以处理任何语言的图片和文档。

Q: 可以排除某些文件夹吗？

A: 可以。创建 .graphifyignore 文件，语法与 .gitignore 相同。

Q: 如何与团队共享图谱？

A: 将 graphify-out/ 目录提交到 git 仓库，团队成员可以克隆后直接查询。

📝 完整命令参考

# 构建图谱
/graphify [path]                    # 在指定路径构建图谱
/graphify [path] --mode deep        # 深度模式
/graphify [path] --update           # 增量更新
/graphify [path] --cluster-only     # 只重新聚类
/graphify [path] --no-viz           # 跳过 HTML
/graphify [path] --obsidian         # 生成 Obsidian vault

# 添加资源
/graphify add <url>                 # 添加 URL
/graphify add <url> --author "Name" # 添加作者标签
/graphify add <url> --contributor "Name" # 添加贡献者标签

# 查询
/graphify query "question"          # 语义查询
/graphify query "question" --dfs    # 深度优先搜索
/graphify query "question" --budget N # 限制 token
/graphify path "NodeA" "NodeB"      # 路径追踪
/graphify explain "Node"            # 节点解释

# 监控
/graphify [path] --watch            # 自动同步

# 导出
/graphify [path] --wiki             # Wiki
/graphify [path] --svg              # SVG
/graphify [path] --graphml          # GraphML
/graphify [path] --neo4j            # Neo4j Cypher
/graphify [path] --neo4j-push URL   # 推送到 Neo4j
/graphify [path] --mcp              # MCP 服务器

# Git 钩子
graphify hook install               # 安装
graphify hook uninstall             # 卸载
graphify hook status                # 状态

# 始终启用集成
graphify claude install/uninstall   # Claude Code
graphify codex install/uninstall    # Codex
graphify opencode install/uninstall # OpenCode
graphify claw install/uninstall     # OpenClaw
graphify droid install/uninstall    # Factory Droid

📚 资源

📄 许可证

本项目基于原 graphify 项目的许可证。

🙏 致谢

感谢 safishamsi 开发了这个优秀的工具！

本文档基于 graphify v3 版本编写。

About

Graphify 知识图谱 - 完整中文安装与使用文档

Resources

Readme
Activity

Stars

7 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1