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

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

这一步自动完成两件事：

在 ~/.claude/skills/graphify/SKILL.md 写入 Skill 定义
在 ~/.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 是否可用：

打开任意项目目录
输入 /graphify .
如果 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 转义序列问题。解决方案：

升级 graphify：pip install --upgrade graphifyy
使用 Windows Terminal 而非旧版 PowerShell 控制台
卸载 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