Graphify：把代码库变成可查询的知识图谱

让编码助手改一个函数，它先去 grep，再一口气读十几个文件，跨文件的调用链还是可能漏掉。仓库越大，靠逐个读文件拼出来的上下文越不可靠，同一批文件被反复读进上下文也在持续消耗 token。

Graphify 是用 Python 写的本地知识图谱工具，把代码、文档、SQL schema、配置和 PDF 解析成一张可查询的图，供 Claude Code、Cursor、Codex 等编码助手检索。

它挂进助手的方式是 skill：在对话里敲 /graphify .，当前项目被解析成一张图，后面的问题不必再翻文件。代码走 tree-sitter 的确定性 AST 解析，不调用 LLM，解析过程不出本机；文档、PDF、图片和视频交给助手自带模型或你配置的 API key 做一次语义解析。

五分钟先跑通

先装 CLI。PyPI 上的包名是 graphifyy，比命令名多一个 y，名字写错会直接找不到包。

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # register the skill with your AI assistant

graphify install 负责把 skill 注册到你的编码助手。仓库列出的支持平台有 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot，以及另外 15 个以上；需要指定平台时用 graphify install --platform opencode 这种写法。

注册完成后，在助手里敲一条命令完成第一次建图：

/graphify .

仓库里没有写明最低 Python 版本要求。项目许可证是 Apache License 2.0，主要语言 Python，仓库地址是 https://github.com/Graphify-Labs/graphify ，当前 Star 122714、Fork 11824、开放 Issue 1518。

跑通之后你会得到什么

第一次跑完，当前目录下会多出一个 graphify-out/，里面是三个文件：

graphify-out/
├── graph.html       在浏览器里打开，点节点、过滤、搜索
├── GRAPH_REPORT.md  关键概念、意外连接、建议提的问题
└── graph.json       完整图数据，之后查询直接读它

graph.html 是可视化入口，节点代表概念，颜色区分检测出的社区，整张图可点可查。GRAPH_REPORT.md 是一份摘要，把连接最多的概念、看起来意外的关联和可以继续追问的问题列出来。graph.json 是底层数据，图建好之后，后续查询不再重新读你的源文件。

拿到图之后可以在终端里直接问：

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

这段输出是仓库 README 里在 FastAPI 代码库上的示例。每条边带置信标记：EXTRACTED 表示源文件里写明的，INFERRED 表示由解析过程推导出来的，两者能分开看。

主要功能

• 本地确定性 AST 解析：代码部分用 tree-sitter 解析成 AST，不调用 LLM，代码不出本机。文档、PDF、图片和视频另走一次语义解析，用助手自带模型或你配置的 API key。
• 每条边可追溯：连接标注 EXTRACTED 或 INFERRED，能区分直接读到的内容和推断出来的关系。
• 不用向量库：没有 embedding，也没有向量存储，检索动作是在图上遍历，不做相似度计算。
• 跨文件链接：calls、imports、inherits、mixes_in 这几类关系跨约 40 种语言解析。
• God nodes：把连接数最高的概念挑出来，看清整个项目围绕什么运转。
• 社区划分：用 Leiden 把图切成子系统，标签以非 LLM 方式生成。
• 三种查询入口：graphify query "<question>" 对自然语言问题返回范围内的子图，graphify path A B 追两点之间的路径，graphify explain X 解释单个概念。
• 增量监听：/graphify add ... --watch 在文件变动时更新图，适合边改边查的用法。

常用参数与配置

• graphify install：把 skill 注册给编码助手；加 --platform opencode 之类的参数指定平台。
• /graphify .：在助手里对当前目录建图，是主入口。
• graphify explain "<概念>"、graphify path A B、graphify query "<问题>"：三个查询命令，分别对应解释单点、追路径、按问题取子图。
• graphify.yaml：有用户在 Issue 里用它调本地 LLM（Ollama）和高核心数 CPU 的扩展行为。README 节选里没有给出这个文件的完整字段说明，具体字段以仓库文档为准。
• skill 自动刷新：v0.9.72 起，包升级后 graphify 会在任意非 install 的 CLI 命令执行时自动刷新已过期的 SKILL.md 及其引用文件并做本地备份，版本不匹配的告警不再需要手工跑一次 graphify install。

结果在哪里看

看整体结构和可视化，打开浏览器里的 graphify-out/graph.html。想快速知道这个项目有什么看点，读 graphify-out/GRAPH_REPORT.md。要给别的工具用或写脚本，读 graphify-out/graph.json，它是完整的图数据。

命令行这一侧的输出直接打在终端。以 explain 为例，它会给出节点所在文件与行号（示例里是 routing.py L2210）、所属社区编号和度数值，再把该节点的连接逐条列出来。

仓库 README 还提到 graphify 可以通过 MCP 被其他工具调用，但节选部分没有给出这条路径的完整说明。Issue 里有用户尝试过 python3 -m graphify.serve graphify-out/graph.json，遇到报错后该条已标记解决。

实际使用中的坑

• Codex 上的 hook 兼容性：codex not support additionalContext on PreToolUse 这条仍待解决，报错为「PreToolUse hook returned unsupported additionalContext」。更早一条「Codex: PreToolUse failed」已经解决。
• 社区划分不可复现：Non-deterministic community assignments across identical-corpus runs (0.9.6) 待解决，同一份语料跑两次，节点的社区归属可能不同。如果你要把社区编号写进文档或 CI 断言，先绕开这一点。
• 新平台的适配在追问中：Is pi or omp supported? 待解决，用户在问 pi 与 oh-my-pi 这类助手能否直接使用。仓库支持列表之外的平台，需要自己先验证。
• 提取器覆盖仍在补：PHP 闭包在任何位置都产生不了节点、ObjC 提取器曾丢掉约 60% 的关系，两条目前都已解决，说明各语言提取器的深度是逐步补齐的。
• 两处历史安全问题已修：v0.9.68 修掉 --watch 的路径参数被未加引号拼进 shell 命令的问题，v0.9.70 修掉 Fortran cpp 预处理步骤可被不受信任的 .F/.F90 文件读取宿主机任意文件的问题。跑旧版本的建议升级。

选型参考

需要一次性把仓库读进上下文、之后不做关系追问，Repomix 那种压成单文件的路径步骤更少，Graphify 要先建图再查。语料以笔记、邮件这类自然语言文本为主时，LEANN 的本地索引更贴合相似度检索，Graphify 的长处在代码里的调用与引用关系。它不如对比项的地方在前置成本：图没建好之前什么都查不到，大仓库第一次解析要等。

合规红线

Graphify 会遍历你指定的目录，读取其中的代码、配置、SQL schema、PDF 和图片。执行范围限制在你拥有或已获授权的仓库与文档上；把客户代码、第三方仓库或含个人信息的 PDF 指给它之前，先确认你有权处理这些内容。

代码解析在本机完成，文档、PDF、图片和视频的语义解析则会把内容交给你的编码助手模型，或交给你配置的 API key 背后的服务方。这一步等价于把材料发送给模型服务提供方，涉及客户数据或受监管数据时，需要按你所在环境的数据出境与保密要求判断。

什么情况下别用它

你只想要一次性的代码通读，读完就丢，Graphify 的建图步骤比打包成单文件的方案多，过程中还多出一份需要维护的图数据。

你的日常工作里没有 Claude Code、Cursor、Codex、Gemini CLI 这类支持 skill 的编码助手，这套工具的入口设计围绕 /graphify 展开，用起来会缺掉主路径。

你的语料是个人笔记、聊天记录、邮件这类自然语言文本，问题形态是找相似内容，本地向量索引类工具更直接；Graphify 要先把这些内容过一遍语义解析，再当成图里的节点处理。

你需要社区划分结果可复现，或者要把社区编号写进自动化断言，当前这个不稳定问题还没有标记为已解决，等它修完再用。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。