Graphify安装与结合claude code使用指南

不吃肥肉的傲寒2026-04-26 11:02

Graphify 安装与使用指南

把代码库编译成知识图谱，让 AI 真正"读过"你的代码。

基于实际项目 (pms-list, 1153 文件) 的安装经验整理。

一、Graphify 是什么

Graphify 是一个开源工具，把代码库一次性分析透，压缩成一张结构化的知识图谱。之后每次提问，AI 遍历图谱而不是重读文件。

核心价值：

  • 跨会话持久化 --- 图谱存储在 graphify-out/graph.json，下次开新会话直接查询，不用重新读代码
  • 带溯源的知识 --- 每条边标注 EXTRACTED(确定)/INFERRED(推断)/AMBIGUOUS(待审查)
  • 跨模块发现 --- 社区聚类自动发现你不会主动去查的隐性关联

二、环境要求

依赖 版本要求 检查命令
Python 3.10+ python --version
pip 最新版 pip --version
Claude Code 已安装 claude --version

三、安装步骤

3.1 安装 Python 包

bash 复制代码 
pip install graphifyy

注意 ：PyPI 包名是 graphifyy（双 y），不是 graphify 也不是 graphify-skill。
graphify 这个名字正在被回收，临时用双 y 代替。安装后 CLI 命令仍然是 graphify。

验证安装：

bash 复制代码 
python -c "import graphify; print('OK')"

3.2 安装 Claude Code 集成

bash 复制代码 
graphify install

这一步自动完成两件事：

  1. 在 ~/.claude/skills/graphify/SKILL.md 写入 Skill 定义
  2. 在 ~/.claude/CLAUDE.md 写入触发规则

安装后输出类似：

复制代码 
  skill installed  ->  C:\Users\<用户名>\.claude\skills\graphify\SKILL.md
  CLAUDE.md        ->  created at C:\Users\<用户名>\.claude\CLAUDE.md

3.3 验证集成

重启 Claude Code，检查 /graphify 是否可用：

  1. 打开任意项目目录
  2. 输入 /graphify .
  3. 如果 Graphify 开始检测文件，说明集成成功

四、项目配置

4.1 创建 .graphifyignore

在项目根目录创建 .graphifyignore，语法和 .gitignore 完全一样：

gitignore 复制代码 
# 构建输出
target/
build/
dist/

# IDE
.idea/
.vscode/
*.iml

# Maven
.mvn/

# Git
.git/

# 日志
logs/
*.log

# 临时文件
*.cache
*.tmp

# 系统文件
.DS_Store
Thumbs.db

# Gradle
.gradle/

# 生成代码
*.generated.java

为什么要配：不忽略这些目录，Graphify 会扫描大量无用文件，浪费时间和 token。

4.2 大项目建议

如果项目超过 200 个文件，建议按子模块分别建图：

bash 复制代码 
# Monorepo 按模块建图
/graphify ./auth
/graphify ./billing
/graphify ./infra

本次项目实测数据：

指标 数值
总文件数 1153
代码文件 1142 (.java)
文档 10 (.md)
图片 1 (.png)
AST 节点 7634
AST 边 42449
语义节点 1574
语义边 4155
最终图谱 8081 节点, 24242 边, 333 社区
全流程耗时 ~10 分钟

五、基本用法

5.1 建图（最常用）

复制代码 
/graphify .                        # 对当前目录建图
/graphify ./src                    # 只处理特定子目录
/graphify . --mode deep            # 深度模式，更多推断边
/graphify . --directed             # 有向图，保留边的方向

5.2 增量更新

复制代码 
/graphify . --update               # 只处理新增/修改的文件，合并到已有图谱

日常开发用 --update 即可，只有大规模重构后才需要完整重建。

5.3 查询图谱

建图完成后，直接用自然语言提问：

复制代码 
"支付重试逻辑在哪里？"
"auth 模块和 response 对象之间是什么关系？"
"这个代码库里最核心的节点是哪几个？"
"从 API 入口到数据库写入，完整的调用链是什么？"
"如果我修改 UserService，哪些模块会受影响？"

5.4 路径追踪

复制代码 
/graphify path "AuthModule" "Database"    # 两个概念之间的最短路径

5.5 概念解释

复制代码 
/graphify explain "ListHubOperateServiceImpl"    # 解释一个节点的所有连接

六、输出文件说明

建图完成后，graphify-out/ 目录结构：

复制代码 
graphify-out/
├── graph.html        # 交互式图谱（节点 > 5000 时需过滤后生成）
├── GRAPH_REPORT.md   # 审计报告：God 节点、惊喜连接、建议问题
├── graph.json        # 持久化图谱，跨会话查询用
├── cost.json         # 累计 token 消耗追踪
├── manifest.json     # 文件清单，用于增量更新比对
├── cache/            # SHA256 缓存，重跑只处理变更文件
├── converted/        # 非文本文件转换结果（如 Excel → Markdown）
└── obsidian/         # Obsidian vault（大图谱的可视化方案）
    ├── graph.canvas  # Obsidian 画布文件
    └── *.md          # 每个节点一个笔记

七、结合 Claude Code 的使用技巧

7.1 自动触发：CLAUDE.md 集成

graphify install 已在 ~/.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.

这意味着输入 /graphify 就会自动加载 Skill，无需手动配置。

7.2 让 Claude 先读图谱再回答

在项目的 CLAUDE.md 中加入以下指令：

markdown 复制代码 
## graphify

如果项目存在知识图谱 (graphify-out/graph.json)，在回答代码库相关问题时：
1. 先查询图谱获取结构和关系
2. 只在需要具体实现细节时才去读源文件
3. 这样可以大幅减少 token 消耗，回答也更准确

安装方式：

bash 复制代码 
graphify claude install     # 自动写入项目 CLAUDE.md

7.3 Git 钩子：每次提交自动更新

bash 复制代码 
graphify hook install       # 安装 post-commit 钩子
graphify hook status        # 检查状态
graphify hook uninstall     # 卸载

效果：每次 git commit 后自动重建图谱的代码部分（AST，无需 LLM）。

7.4 文件监听：开发时实时更新

复制代码 
/graphify . --watch         # 后台监听，代码保存即触发 AST 重建
  • 代码文件变更：即时重建（纯 AST，不消耗 token）
  • 文档/图片变更 ：提示你运行 --update 做 LLM 语义重提取

7.5 实用查询模式

场景 Claude Code 中输入
理解架构 /graphify query "这个项目的核心模块有哪些"
追踪调用链 /graphify path "ExternalSyncController" "ListSyncMapper"
修改影响分析 /graphify query "修改 ListHubHeadDO 会影响哪些模块"
理解设计意图 /graphify explain "ListBpmFactory"
添加外部资料 /graphify add https://arxiv.org/abs/1706.03762

7.6 大图谱可视化方案

当节点超过 5000 时，HTML 可视化会被跳过。两种替代方案：

方案 A：Obsidian Vault

复制代码 
/graphify . --obsidian

用 Obsidian 打开 graphify-out/obsidian/ 目录，可获得：

  • Graph View --- 节点按社区着色
  • graph.canvas --- 结构化社区布局
  • 每个节点一个笔记，含连接和来源

方案 B：过滤核心节点生成 HTML

Claude Code 中输入以下指令：

复制代码 
生成一个只包含度 >= 5 的核心节点的 graph.html

实测：8081 节点过滤后 → 2824 核心节点，可直接在浏览器中交互查看。

方案 C：SVG 导出

复制代码 
/graphify . --svg            # 生成 graph.svg，可嵌入 Notion / GitHub README

7.7 Neo4j 集成（高级）

复制代码 
/graphify . --neo4j                              # 生成 cypher.txt
/graphify . --neo4j-push bolt://localhost:7687    # 直接推送到 Neo4j

7.8 MCP Server 模式

复制代码 
/graphify . --mcp             # 启动 MCP stdio 服务器

暴露工具：query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path

可配置到 Claude Desktop 的 claude_desktop_config.json：

json 复制代码 
{
  "mcpServers": {
    "graphify": {
      "command": "python",
      "args": ["-m", "graphify.serve", "/absolute/path/to/graphify-out/graph.json"]
    }
  }
}

八、最佳实践

8.1 重建节奏

操作 何时使用
/graphify . 首次建图 / 大规模重构后
/graphify . --update 日常新增文件后
graphify hook install 每次提交自动更新（推荐）
/graphify . --watch 活跃开发期间实时同步

建议：活跃开发的项目，每 2-3 周做一次完整重建 (/graphify .)。

8.2 Token 节省

本次实测的 Token 压缩比：

复制代码 
语料总量:    307,282 词 ≈ 409,709 tokens（直接读文件）
图谱查询:    平均 ~169,769 tokens/次
压缩比:      2.4x

项目越大，压缩比越高。官方数据：52 文件混合语料 → 71.5x 压缩。

8.3 隐私注意

文件类型 处理方式 隐私风险
代码文件 AST 提取结构化符号，不发送原始代码 低
文档/PDF 发送给 LLM 做语义提取 高
图片 发送给 LLM 做视觉理解 高
视频/音频 本地 Whisper 转录，不上传 低

敏感文档请加入 .graphifyignore。

8.4 何时不用 Graphify

  • 项目主要是散文式文档（没有复杂调用关系的纯文本）
  • 项目只有几个文件（直接读就行，图谱价值在结构清晰度而非压缩）
  • 项目频繁大规模重构（图谱漂移问题严重，需要频繁重建）

九、常见问题

Q: pip install graphify-skill 报错找不到包？

包名是 graphifyy（双 y），不是 graphify-skill。

bash 复制代码 
pip install graphifyy    # 正确

Q: PowerShell 滚动卡住？

这是 graspologic 库的 ANSI 转义序列问题。解决方案：

  1. 升级 graphify：pip install --upgrade graphifyy
  2. 使用 Windows Terminal 而非旧版 PowerShell 控制台
  3. 卸载 graspologic：pip uninstall graspologic，会回退到 NetworkX 的 Louvain 算法

Q: 图谱太大，HTML 无法生成？

节点 > 5000 时 HTML 可视化被禁用。替代方案：

  • --obsidian 生成 Obsidian vault
  • 让 Claude 过滤核心节点后生成 HTML
  • --svg 导出静态 SVG
  • --graphml 用 Gephi/yEd 打开

Q: 图谱描述的是旧结构？

大规模重构后未及时重建图谱。判断方法：对一个你刚重构过的模块做路径查询，如果描述的还是旧关系，说明该重建了。

Q: Windows 上路径问题？

Graphify 在 Windows 上完全支持。如遇到路径问题，确保：

  • Python 3.10+
  • 使用完整绝对路径
  • .graphifyignore 使用正斜杠 /

十、快速开始清单

bash 复制代码 
# 1. 安装
pip install graphifyy

# 2. 配置 Claude Code 集成
graphify install

# 3. 进入项目目录
cd /your/project

# 4. 创建忽略文件（可选但推荐）
# 参考 4.1 节的 .graphifyignore 模板

# 5. 首次建图
# 在 Claude Code 中输入：
/graphify .

# 6. 安装 git 钩子（可选）
graphify hook install

# 7. 开始查询
# 在 Claude Code 中用自然语言提问即可

基于 Graphify v0.5.0 整理，项目仓库：https://github.com/safishamsi/graphify

相关推荐
seven97_top1 小时前
Tomcat的架构设计和启动过程详解
java·tomcat
djjdjdjdjjdj2 小时前
golang如何编写SSL证书到期检测工具_golang SSL证书到期检测工具编写总结
jvm·数据库·python
axinawang2 小时前
第2课： 与世界打招呼（输出）
python
2301_813599552 小时前
HTML5中Canvas局部刷新区域重绘的算法优化
jvm·数据库·python
m0_602857762 小时前
mysql如何防止用户通过子查询窃取权限_MySQL安全参数设置
jvm·数据库·python
我是无敌小恐龙2 小时前
Java SE 零基础入门 Day05 类与对象核心详解（封装+构造方法+内存+变量）
java·开发语言·人工智能·python·机器学习·计算机视觉·数据挖掘
qq_189807032 小时前
Less如何处理CSS长文本换行_封装Mixin解决不同场景需求
jvm·数据库·python
小灰灰搞电子2 小时前
Python self关键字详解及其应用
开发语言·python
HHHHH1010HHHHH2 小时前
CSS如何处理带有状态切换的折叠菜单_利用BEM修饰符管理状态
jvm·数据库·python
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月032026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元042026年4月AI大事件深度解读：大模型竞争进入“深水区“052026年AI前瞻：量子AI、具身智能与科学发现的新纪元06codex app每次打开重连5次Reconnecting问题解决07AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析082026 年 AI 辅助编程工具全景对比：Copilot、Cursor、Claude Code 与 Codex 深度解析09CC-Switch & Claude 基于 Linux 服务器安装使用指南102026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free