graphify 入门指南

一句话理解

graphify 把你的代码、文档、论文、图片变成一张知识图谱，让 AI 助手”理解”你的项目，而不是每次都重新读文件。

核心价值：为什么需要它？

问题场景

当你问 AI 助手”这个项目的认证流程是怎样的？”：

  • 传统方式：AI 用 Grep 搜索关键词，读几十个文件，消耗大量 token
  • graphify 方式：AI 先读 GRAPH_REPORT.md（一页总结），按图谱导航，token 消耗降低 71.5 倍

适合谁？

你的情况 是否适合
项目文件超过 20 个 ✅ 非常适合
需要理解别人的代码库 ✅ 非常适合
有论文/文档需要和代码关联理解 ✅ 非常适合
只有 3-5 个小文件 ❌ 收益不大
只做简单单文件编辑 ❌ 用不上

快速开始（5 分钟）

第一步：安装

1
2
3
4
5
# 安装 Python 包（注意包名是 graphifyy，双 y）
pip install graphifyy

# 安装到你的 AI 助手（以 Claude Code 为例）
graphify install

第二步：构建图谱

在你的 AI 助手中输入：

1
/graphify .

第三步：查看结果

1
2
3
4
5
# 打开交互式图谱（可视化）
open graphify-out/graph.html

# 查看分析报告（文本总结）
cat graphify-out/GRAPH_REPORT.md

输出文件说明：

文件 用途
graph.html 可视化图谱，可点击节点、搜索、按社群过滤
GRAPH_REPORT.md 核心节点、意外连接、建议问题（AI 助手优先读这个）
graph.json 持久化图谱数据，支持精确查询
cache/ 缓存，增量更新时只处理变更文件

命令分类：哪些需要 AI 助手？

🔵 在 AI 助手中执行的命令（以 /graphify 开头）

这些命令会触发 AI 助手的技能系统：

命令 作用 何时使用
/graphify . 构建当前目录的图谱 首次分析项目
/graphify ./src 构建指定目录的图谱 只分析某个子目录
/graphify ./raw --update 增量更新图谱 文件有变更时
/graphify ./raw --mode deep 深度模式，更激进的推断 需要发现更多隐式关联
/graphify add <url> 添加论文/视频并更新图谱 扩充知识库

🟢 在终端直接执行的命令（以 graphify 开头）

这些命令不需要 AI 助手，直接在终端运行：

命令 作用 何时使用
graphify query "问题" 查询图谱 快速查找，不需要启动 AI
graphify path "A" "B" 查找两节点间最短路径 理解 A 如何连接到 B
graphify explain "节点名" 解释某个节点 快速了解某个概念
graphify hook install 安装 git hooks 自动化：提交后重建图谱
graphify claude install 让 Claude 始终使用图谱 一次设置，永久生效

🟡 可在两处执行的命令

命令 AI 助手中 终端中
查询图谱 /graphify query "..." graphify query "..."
解释节点 /graphify explain "..." graphify explain "..."
查找路径 /graphify path "A" "B" graphify path "A" "B"

建议：日常查询用终端更快；需要 AI 进一步分析时在 AI 助手中执行。

典型工作流

场景一：理解新项目

1
2
3
4
5
6
7
8
9
# 1. 构建图谱（在 AI 助手中）
/graphify .

# 2. 查看报告（终端）
cat graphify-out/GRAPH_REPORT.md

# 3. 查询具体问题（终端或 AI 助手）
graphify query "认证流程是怎样的？"
graphify path "LoginController" "UserRepository"

场景二：持续开发

1
2
3
4
5
6
7
8
9
10
# 1. 设置自动同步（终端，一次性）
graphify hook install        # 每次提交后自动重建图谱
graphify claude install      # 让 Claude 始终优先使用图谱

# 2. 日常开发
# 正常写代码，图谱会自动更新
# AI 助手会自动读取 GRAPH_REPORT.md

# 3. 需要时手动更新（AI 助手中）
/graphify . --update

场景三：代码 + 论文联合理解

1
2
3
4
5
6
7
8
# 1. 添加论文（AI 助手中）
/graphify add https://arxiv.org/abs/1706.03762

# 2. 构建联合图谱
/graphify .

# 3. 查询代码与论文的关联
graphify query "代码中的 attention 和论文里的 attention 有什么关系？"

安装后发生了什么？

graphify install 做了什么？

这个命令安装 技能文件，让 AI 助手能识别 /graphify 命令：

1
~/.claude/skills/graphify/SKILL.md    # 技能定义文件

同时在 ~/.claude/CLAUDE.md 中添加触发规则：

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

效果：当你在 Claude Code 中输入 /graphify .，Claude 会先加载技能文件，然后执行图谱构建。

graphify claude install 做了什么？

这个命令让 Claude 始终优先使用图谱，分为两步：

第一步：写入 CLAUDE.md 规则

在项目的 CLAUDE.md 中添加：

1
2
3
4
5
## graphify

Before answering architecture questions, read `graphify-out/GRAPH_REPORT.md` if it exists.
This gives you god nodes, community structure, and surprising connections.
Navigate via the graph instead of grepping through every file.

第二步：安装 PreToolUse Hook

在 ~/.claude/settings.json 中添加钩子：

1
2
3
4
5
6
7
8
9
10
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Glob|Grep",
        "command": "echo 'graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files.'"
      }
    ]
  }
}

触发时机：每次 Claude 准备执行 Glob 或 Grep 工具时。

效果：Claude 会看到提醒，先读图谱报告，而不是直接搜索文件。

常驻模式 vs 显式触发

方式 命令 作用 适用场景
常驻模式 graphify claude install AI 自动读取 GRAPH_REPORT.md 日常开发，自动获取结构概览
显式触发 /graphify query "问题" 精确查询 graph.json 需要具体路径、边详情时

类比：

  • 常驻模式 = 给 AI 一张地图概览
  • 显式触发 = 让 AI 在地图上精确导航

其他平台的安装效果

平台 安装效果
Cursor 写入 .cursor/rules/graphify.mdc，alwaysApply: true，每轮对话自动包含
Gemini CLI 写入 GEMINI.md + ~/.gemini/settings.json 的 BeforeTool hook
Codex 写入 AGENTS.md + .codex/hooks.json 的 PreToolUse hook
Aider / OpenClaw / Trae 只写入 AGENTS.md（这些平台不支持 hook）
Kiro 写入 .kiro/skills/ + .kiro/steering/graphify.md，inclusion: always
VS Code Copilot Chat 写入 .github/copilot-instructions.md，VS Code 自动读取

让 AI 助手”始终使用图谱”（推荐）

构建图谱后，运行一次以下命令，AI 助手就会在回答问题前自动读取图谱：

平台 命令
Claude Code graphify claude install
Codex graphify codex install
Cursor graphify cursor install
Gemini CLI graphify gemini install

卸载：graphify claude uninstall

graphify 如何工作？

三阶段处理流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌─────────────────────────────────────────────────────────────────┐
│  阶段一：AST 解析（代码文件）                                      │
│  ├─ tree-sitter 解析代码结构                                      │
│  ├─ 提取：类、函数、导入、调用图、docstring、注释                   │
│  └─ ❌ 不需要 LLM，完全本地处理                                    │
├─────────────────────────────────────────────────────────────────┤
│  阶段二：音视频转录（视频/音频文件）                                │
│  ├─ faster-whisper 本地转录                                      │
│  ├─ 使用语料库的 god nodes 生成领域感知提示词                       │
│  └─ ❌ 音频不离开你的机器，转录结果被缓存                           │
├─────────────────────────────────────────────────────────────────┤
│  阶段三：语义提取（文档、论文、图片、转录文本）                      │
│  ├─ Claude 子代理并行处理                                         │
│  ├─ 提取：概念、关系、设计动机                                     │
│  └─ ✅ 需要 LLM（发送到 AI 平台的模型 API）                        │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│  合并 → NetworkX 图 → Leiden 社群发现 → 输出文件                   │
└─────────────────────────────────────────────────────────────────┘

关键技术点

技术 作用 说明
tree-sitter 代码 AST 解析 支持 25 种语言，提取结构信息
faster-whisper 音视频转录 本地运行，音频不离开机器
Leiden 算法 社群发现 基于图拓扑聚类，不依赖 embeddings
NetworkX 图数据结构 存储节点、边、属性

聚类原理

不使用 embeddings，而是基于图拓扑：

  1. Leiden 算法按边密度发现社群
  2. Claude 提取的语义相似边（semantically_similar_to）已在图中
  3. 这些边直接影响社群划分
  4. 图结构本身就是相似性信号

输出目录详解：graphify-out/

运行 /graphify . 后生成：

1
2
3
4
5
6
7
8
9
10
11
graphify-out/
├── graph.html        # 交互式可视化图谱
├── GRAPH_REPORT.md   # 人类可读的分析报告
├── graph.json        # 持久化图谱数据（JSON 格式）
├── graph.svg         # SVG 导出（可选）
├── graph.graphml     # GraphML 导出（可选，用于 Gephi/yEd）
├── cypher.txt        # Neo4j Cypher 脚本（可选）
├── cache/            # SHA256 缓存目录
│   └── *.json        # 每个文件的提取结果缓存
└── transcripts/      # 音视频转录缓存（如有）
    └── *.txt         # Whisper 转录结果

各文件详解

文件 格式 用途 谁使用
graph.html HTML 可视化图谱，可点击节点、搜索、按社群过滤 人类查看
GRAPH_REPORT.md Markdown 核心节点、意外连接、建议问题（一页总结） AI 助手优先读这个
graph.json JSON 完整图谱数据，支持精确查询 graphify query 命令
cache/ JSON 每个文件的 SHA256 缓存 增量更新时判断是否需要重新处理

graph.json 结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "nodes": [
    {
      "id": "UserService",
      "type": "class",
      "file": "src/services/user.py",
      "docstring": "用户服务类...",
      "community": 1
    }
  ],
  "edges": [
    {
      "source": "UserService",
      "target": "UserRepository",
      "relation": "calls",
      "type": "EXTRACTED",
      "confidence": 1.0,
      "file": "src/services/user.py",
      "line": 42
    }
  ]
}

缓存机制

  • SHA256 哈希：每个文件内容计算哈希值
  • 增量更新：只处理哈希值变化的文件
  • 跨会话持久化：graph.json 保存后，数周后仍可查询

.graphifyignore 配置文件

作用

排除不需要分析的目录或文件，语法与 .gitignore 完全相同。

创建方式

在项目根目录创建 .graphifyignore：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# .graphifyignore

# 依赖目录
node_modules/
vendor/
venv/
.venv/

# 构建产物
dist/
build/
*.min.js
*.generated.py

# 缓存和临时文件
.cache/
*.tmp
*.log

# 测试覆盖率报告
coverage/
.nyc_output/

# 大型二进制文件
*.exe
*.dll
*.so
*.dylib

工作原理

  • 放在项目根目录即可
  • 对子目录运行 /graphify ./src 时，规则仍然生效
  • 支持所有 .gitignore 语法：*、**、! 取反等

团队协作

设计理念

graphify-out/ 设计为提交到 git，让团队成员共享知识图谱。

推荐的 .gitignore 配置

1
2
3
# 提交图谱输出，忽略提取缓存
graphify-out/cache/
graphify-out/transcripts/

为什么忽略缓存？

  • cache/ 是每个文件的提取结果缓存（SHA256 哈希）
  • transcripts/ 是音视频转录缓存
  • 这些是本地优化，不需要共享
  • graph.json 和 GRAPH_REPORT.md 才是团队共享的核心

团队工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌─────────────────────────────────────────────────────────────────┐
│  开发者 A（首次构建）                                             │
│  ├─ 1. 运行 /graphify . 构建图谱                                  │
│  ├─ 2. git add graphify-out/                                     │
│  └─ 3. git commit -m "添加知识图谱"                               │
├─────────────────────────────────────────────────────────────────┤
│  开发者 B（拉取使用）                                             │
│  ├─ 1. git pull                                                  │
│  ├─ 2. AI 助手立即可读取 GRAPH_REPORT.md                          │
│  └─ 3. 无需重新构建，直接查询图谱                                  │
├─────────────────────────────────────────────────────────────────┤
│  代码变更后                                                       │
│  ├─ 方式一：手动更新 /graphify . --update                         │
│  ├─ 方式二：git hooks 自动重建                                    │
│  └─ 提交更新后的图谱                                              │
└─────────────────────────────────────────────────────────────────┘

Git Hooks 自动化

安装 git hooks，让图谱在代码变更后自动重建：

1
2
3
4
5
6
7
8
# 安装 hooks（项目根目录执行一次）
graphify hook install

# 查看状态
graphify hook status

# 卸载
graphify hook uninstall

安装后效果：

Hook 触发时机 作用
post-commit 每次 git commit 后 自动重建图谱
post-checkout 每次切换分支后 自动重建图谱

工作原理：

  • hooks 调用 graphify update 命令
  • 只处理变更文件（利用缓存）
  • 如果重建失败，hook 返回非零退出码，git 会显示错误

团队最佳实践

1. 谁负责维护图谱？

场景 建议
小团队（2-3人） 每人本地运行，按需提交
中型团队 指定一人负责，或用 CI 自动更新
大型团队 CI/CD 流水线中集成，定期重建

2. CI/CD 集成示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# .github/workflows/graphify.yml
name: Update Knowledge Graph

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

jobs:
  update-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install graphify
        run: pip install graphifyy

      - name: Update graph
        run: graphify . --update

      - name: Commit changes
        run: |
          git config user.name "CI"
          git config user.email "ci@example.com"
          git add graphify-out/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update knowledge graph"
          git push

3. 冲突处理

graph.json 是 JSON 文件，可能产生合并冲突：

1
2
3
4
5
6
7
# 方式一：解决冲突后重建
git merge feature-branch
# 解决冲突...
graphify . --update

# 方式二：直接重建覆盖
graphify . --no-viz  # 跳过 HTML，更快

4. 大型仓库策略

对于大型仓库，考虑：

1
2
3
4
5
6
# 只分析核心目录
/graphify ./src/core

# 使用 .graphifyignore 排除
echo "legacy/" >> .graphifyignore
echo "experiments/" >> .graphifyignore

团队协作检查清单

  • graphify-out/ 已添加到 git（除 cache/ 和 transcripts/）
  • .graphifyignore 已配置，排除不需要分析的目录
  • 团队成员都知道如何查询图谱：graphify query "问题"
  • 可选：git hooks 或 CI 自动更新图谱

输出解读

GRAPH_REPORT.md 包含什么？

  1. God Nodes（核心节点）：度数最高的概念，所有内容都通过它们连接
  2. Surprising Connections（意外连接）：图谱发现的非显而易见的关联
  3. Suggested Questions（建议问题）：图谱特别擅长回答的问题

关系标签含义

标签 含义 置信度
EXTRACTED 直接从源码/文档中发现 1.0
INFERRED 合理推断 0.0-1.0（有分数）
AMBIGUOUS 有歧义，需要人工复核 -

支持的文件类型

类型 扩展名 处理方式 需要 LLM？
代码 .py .ts .js .go .rs .java .c .cpp .rb .cs .kt .php .swift ... tree-sitter AST ❌ 本地处理
文档 .md .txt .rst Claude 提取概念 ✅
论文 .pdf 引文挖掘 + 概念提取 ✅
图片 .png .jpg .webp .gif Claude vision ✅
视频/音频 .mp4 .mp3 .wav ... Whisper 本地转录 ❌ 本地转录，转录结果需 LLM 提取

隐私说明：

  • 代码文件：tree-sitter AST 本地处理，不离开你的机器
  • 视频/音频：faster-whisper 本地转录，音频不离开你的机器
  • 文档/论文/图片：发送到 AI 平台的模型 API 进行语义提取

常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# === 构建与更新 ===
/graphify .                          # 构建当前目录图谱
/graphify ./src --update             # 增量更新
/graphify . --mode deep              # 深度模式
/graphify . --watch                  # 监听模式，自动同步

# === 查询 ===
graphify query "认证流程"             # 查询图谱
graphify path "A" "B"                # 最短路径
graphify explain "SwinTransformer"   # 解释节点

# === 添加内容 ===
/graphify add https://arxiv.org/abs/xxx  # 添加论文
/graphify add <video-url>                # 添加视频

# === 自动化 ===
graphify hook install                # git hooks（提交后自动重建）
graphify claude install              # Claude 始终使用图谱

# === 导出 ===
/graphify . --svg                    # 导出 SVG
/graphify . --graphml                # 导出 GraphML（Gephi）
/graphify . --wiki                   # 生成 Wiki

常见问题

Q: Windows 上 graphify: command not found

1
2
3
# 方法一：添加 pip 脚本目录到 PATH
# 方法二：使用 python -m 调用
python -m graphify query "问题"

Q: 图谱太大，查询慢怎么办？

1
2
3
4
5
# 限制查询预算
graphify query "问题" --budget 500

# 使用深度优先搜索追踪特定路径
graphify query "问题" --dfs

Q: 如何排除某些目录？

在项目根目录创建 .graphifyignore：

1
2
3
4
vendor/
node_modules/
dist/
*.generated.py

Q: 团队如何共享图谱？

graphify-out/ 设计为提交到 git。推荐的 .gitignore：

1
graphify-out/cache/   # 忽略缓存，提交图谱

相关链接

总结

步骤 命令 说明
1. 安装 pip install graphifyy && graphify install 一次性设置
2. 构建 /graphify . 在 AI 助手中执行
3. 查询 graphify query "问题" 终端或 AI 助手
4. 自动化 graphify hook install && graphify claude install 一次设置，永久生效

核心理念：先构建图谱，后续查询效率提升 71.5 倍，且跨会话持久化。