安装 Graphify，给仓库建出第一张代码图谱

本课目标

• 用 uv 装好 graphifyy，确认 graphify 和 graphify-mcp 两个命令可用
• 不调用任何模型，给一个真实仓库建出代码知识图谱
• 看懂 graphify-out 目录里每个文件的用途，知道哪些该提交、哪些该忽略

前置条件

• Linux 或 macOS 终端，Python 3.10 以上
• 已安装 uv（没有的话执行 curl -LsSf https://astral.sh/uv/install.sh | sh），或者用 pipx
• Git，用来克隆示例仓库

第 1 步：安装 graphifyy

官方推荐用 uv 装成独立的命令行工具：

uv tool install graphifyy

注意包名是 graphifyy，有两个 y。PyPI 上其他叫 graphify 的包与官方无关，装错了命令行为也会不同。没有 uv 时可以改用 pipx install graphifyy。

对照结果（只保留最后几行）：

 + tree-sitter-typescript==0.23.2
 + tree-sitter-verilog==1.0.3
 + tree-sitter-zig==1.1.2
Installed 2 executables: graphify, graphify-mcp

确认版本：

graphify --version

graphify 0.9.108

如果提示找不到 graphify，执行 uv tool update-shell 后重开终端。

第 2 步：准备示例仓库

本课用 Python 命令行库 click 做示例，它有 60 多个 Python 文件，结构清楚，几秒就能建完图。固定到 8.2.1 版，结果才能和下面的对照一致：

git clone --depth 1 --branch 8.2.1 https://github.com/pallets/click
cd click

你也可以直接换成自己的项目，后面的命令都一样。

第 3 步：只解析代码，建出图谱

graphify extract . --code-only

--code-only 只用 tree-sitter 在本机解析代码，跳过文档、PDF 和图片，所以不会调用任何模型，也不需要 API Key。

对照结果：

[graphify extract] scanning /path/to/click
[graphify extract] --code-only: skipping 43 non-code file(s) (37 docs, 0 papers, 6 images) — no LLM extraction
[graphify extract] found 81 code, 0 docs, 0 papers, 0 images
[graphify extract] AST extraction on 81 code files...
[graphify] Deduplicated 4 node(s) (4 exact).
[graphify extract] wrote /path/to/click/graphify-out/graph.json: 2080 nodes, 4312 edges, 117 communities
[graphify extract] next: run `graphify cluster-only /path/to/click` to generate GRAPH_REPORT.md and name communities

测试机上整个过程用了约 3.4 秒。81 个代码文件变成了 2080 个节点、4312 条边，并被聚成 117 个社区。还有 12 个文件（例如 docs/conf.py 和示例里的 pyproject.toml）没有解析出符号，输出里会给出一条 warning，属于正常情况。

第 4 步：生成报告和可视化页面

按上一步的提示执行：

graphify cluster-only . --no-label

Loading existing graph...
Graph: 2080 nodes, 4312 edges
Re-clustering...
Done - 117 communities. GRAPH_REPORT.md, graph.json and graph.html updated.

--no-label 表示社区先用「Community 0、Community 1」这样的编号命名。去掉它，Graphify 会调用你配置的模型给社区起名，需要 API Key。

第 5 步：认识 graphify-out 目录

ls -A1 graphify-out

.graphify_analysis.json
.graphify_build.json
.graphify_root
GRAPH_REPORT.md
cache
graph.html
graph.json
manifest.json

以点开头的几个是内部状态文件，不用管。之后跑过增量更新，这里还会多出几个类似的隐藏文件。

几个主要文件的用途：

打开报告的开头看一下：

head -14 graphify-out/GRAPH_REPORT.md

# Graph Report - click  (2026-11-15)

## Corpus Check
- cluster-only mode — file stats not available

## Summary
- 2080 nodes · 4312 edges · 117 communities (76 shown, 41 thin omitted)
- Extraction: 81% EXTRACTED · 19% INFERRED · 0% AMBIGUOUS · INFERRED: 805 edges (avg confidence: 0.88)
- Token cost: 0 input · 0 output

## Graph Freshness
- Built from commit: `fd183b2c`

重点看两行。Token cost: 0 input · 0 output 说明这次建图没有花任何模型费用。Extraction 一行是边的来源占比：EXTRACTED 是直接从源码读出来的关系，INFERRED 是解析器推断出来的关系，并带有置信度。

官方建议把 graph.json 和 GRAPH_REPORT.md 提交进仓库，让队友和 CI 用同一张图；cache/ 加进 .gitignore。

常见坑

• 装成了别的包：pip install graphify 装到的不是官方工具，一定要用 graphifyy
• 想建图却提示要 API Key：没加 --code-only 时，Graphify 会尝试对文档和图片做语义抽取，这一步需要模型。只想要代码图就加上它
• 在子目录里执行查询命令：后面的命令默认读当前目录下的 graphify-out/graph.json。换了目录就用 --graph 指定路径
• 大仓库打开 graph.html 很卡：节点上千时浏览器渲染会慢。CI 里可以给 cluster-only 加 --no-viz 跳过 HTML

小结

一条 graphify extract . --code-only 加一条 graphify cluster-only . --no-label，就在本机零成本建好了代码图谱。下一课开始真正用它回答问题。

参考来源

https://docs.graphify.com/open-source/installation

https://docs.graphify.com/open-source/cli-quickstart

https://github.com/Graphify-Labs/graphify

https://pypi.org/project/graphifyy/