# graphify-knowledge-graph-docs **Repository Path**: xyb-luwei/graphify-knowledge-graph-docs ## Basic Information - **Project Name**: graphify-knowledge-graph-docs - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-21 - **Last Updated**: 2026-04-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Graphify 知识图谱 - 安装与使用文档 > 将任何文件夹转化为可查询的知识图谱，支持 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid ## 📖 项目简介 Graphify 是一个 AI 编程助手技能（skill），它能够： - 读取代码、文档、PDF、图片等文件 - 构建知识图谱，发现隐藏的结构和关系 - 提供 71.5 倍的 token 节省（相比直接读取原始文件） - 支持跨会话持久化查询 **核心特性：** - ✅ 完全多模态：支持代码、PDF、Markdown、截图、图表、白板照片 - ✅ 持久化图谱：跨会话可查询，无需重新读取文件 - ✅ 智能聚类：基于 Leiden 社区发现算法 - ✅ 置信度标注：每个关系都标记为 EXTRACTED（提取）、INFERRED（推断）或 AMBIGUOUS（模糊） - ✅ 缓存机制：SHA256 缓存，只处理变更的文件 --- ## 🚀 快速开始 ### 前置要求 - Python 3.10+ - 任一 AI 编程助手： - [Claude Code](https://claude.ai/code) - [Codex](https://openai.com/codex) - [OpenCode](https://opencode.ai) - [OpenClaw](https://openclaw.ai) - [Factory Droid](https://factory.ai) ### 安装步骤 ```bash # 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` | ### 验证安装 ```bash # 检查安装 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. 添加外部资源 ```bash # 添加 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. 图谱查询 ```bash # 语义查询 /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. 路径追踪 ```bash # 查找两个节点之间的路径 /graphify path "DigestAuth" "Response" ``` ### 4. 节点解释 ```bash # 详细解释某个节点 /graphify explain "SwinTransformer" ``` ### 5. 自动同步 ```bash # 监控文件变化，自动更新图谱 /graphify ./raw --watch ``` 代码文件保存会立即触发重建（仅 AST，无 LLM）。文档/图片变化会通知你运行 `--update`。 ### 6. Git 钩子 ```bash # 安装 git 钩子（提交和分支切换时自动重建） graphify hook install # 查看状态 graphify hook status # 卸载 graphify hook uninstall ``` ### 7. 导出格式 ```bash # 生成 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 ```bash # 安装始终启用集成 graphify claude install # 这会： # 1. 在 CLAUDE.md 中添加规则，让 Claude 在回答架构问题前读取 GRAPH_REPORT.md # 2. 安装 PreToolUse 钩子，在每次 Glob/Grep 前提示存在知识图谱 # 卸载 graphify claude uninstall ``` ### 其他平台 ```bash # 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，可以手动安装： ```bash # 创建目录 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`： ```markdown - **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 仓库，团队成员可以克隆后直接查询。 --- ## 📝 完整命令参考 ```bash # 构建图谱 /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 /graphify add --author "Name" # 添加作者标签 /graphify add --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 ``` --- ## 📚 资源 - **GitHub 仓库**: https://github.com/safishamsi/graphify - **PyPI 包**: https://pypi.org/project/graphifyy/ - **问题反馈**: https://github.com/safishamsi/graphify/issues --- ## 📄 许可证 本项目基于原 graphify 项目的许可证。 --- ## 🙏 致谢 感谢 [safishamsi](https://github.com/safishamsi) 开发了这个优秀的工具！ 本文档基于 graphify v3 版本编写。