用 AI 编码助手最烦的一种情况，是它明明很会写代码，却总在项目上下文里迷路。
你问它“认证链路最后是在哪里写数据库的”，它开始读十几个文件；你问它“这个函数影响哪些模块”，它又去 grep 一轮。上下文塞满了，答案还不一定准。
今天小金看到一个挺适合接到编码助手里的开源项目，叫 Graphify。
它做的事情很简单：把一个目录里的代码、文档、SQL schema、脚本、图片、视频这些材料，抽成一张可以查询的知识图谱，再尽量让 Claude Code、Codex、Cursor、Gemini CLI 这类助手别一上来就 grep 仓库，而是先从已有图谱里找线索。
项目地址是：github.com/safishamsi/…
截至小金查看时，这个仓库已有 约 6.2 万 Star、6.4k Fork。
先说怎么用。
官方包名有点容易踩坑，PyPI 上叫 graphifyy，两个 y，但命令仍然叫 graphify。
uv tool install graphifyy
graphify install
装完之后，在支持的 AI 编码助手里跑：
/graphify .
如果是在 Codex 的 assistant 命令里，README 特别提醒要用 $graphify，不是 /graphify。Windows PowerShell 也别写 /graphify .，直接用 graphify .，因为开头的斜杠会被 PowerShell 当成路径。
跑完之后，项目里会多一个 graphify-out/目录，里面主要有 3 个东西：
- •
graph.html：浏览器里看的交互式图。 - •
GRAPH_REPORT.md：项目的关键概念、意外关联、推荐问题。 - •
graph.json：完整图谱，后面查询、MCP、团队共享都靠它。
这个产物思路挺直接。以前 AI 助手回答项目问题，经常是临时读文件、临时总结、临时猜关系。Graphify 先把项目里的实体和关系沉淀下来，后面再问问题时，不需要每次从零翻仓库。
举个更具体的例子。
你可以问：
graphify query "what connects auth to the database?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"
这几条命令分别对应查关联、找路径、解释节点。它还有 MCP server，可以用 stdio 方式给本机助手调用，也可以用 HTTP 方式在团队里共享，默认 HTTP 端口是 8080，公开到局域网时可以加 --api-key。
这比单纯生成一份架构说明更实用。
架构说明适合人读，但 AI 助手真正需要的是可反复检索的结构化上下文。Graphify 暴露的 MCP 工具包括 query_graph、get_node、get_neighbors、shortest_path这些，刚好是 Agent 做代码理解时经常需要的动作。
接下来要说它覆盖的范围。
基本主流的 AI IDE 和 CLI 都支持，包括 Claude Code、CodeBuddy、Codex、OpenCode、Kilo Code、Cursor、Gemini CLI、GitHub Copilot CLI等。
不同宿主的接入方式不完全一样。Claude Code、CodeBuddy、Codex、Gemini CLI 这些会写入对应的 skill、规则文件或 hook；Cursor 走 .cursor/rules/graphify.mdc；有些工具目前更偏顺序执行，不能完全拿到并行 Agent 的收益。
所以别把它理解成“所有助手体验完全一致”。
它更像是一层项目记忆适配器。能接得深的工具，体验会更自动；接得浅的工具，至少也能通过 graphify query把图谱查起来。
文件覆盖范围也比较宽。
代码侧主要靠 tree-sitter 做 AST 抽取，常见语言基本都覆盖了，比如 Python、JavaScript/TypeScript、Java、Go、Rust、C/C++、C#、Kotlin、Swift、PHP、Ruby、Shell 等。除此之外，它还扩展到了 SQL schema、Terraform/HCL、MCP 配置、Markdown、HTML、YAML、PDF、Office、图片、音视频、YouTube 或普通 URL 这类材料。
不过这里有个前提。
代码类材料可以本地解析，纯代码仓库不需要 API key；文档、PDF、图片这类语义抽取会走你配置的模型或 IDE 会话。 如果你的仓库里有敏感需求文档、内部截图、合同 PDF，不能只看到“本地知识图谱”几个字就默认全程离线。
代码文件通过 tree-sitter 本地处理；视频、音频用 faster-whisper 本地转录；文档、PDF、图片会发给 AI 助手或你指定的后端做语义抽取。可用后端包括 Gemini、Kimi、Claude、OpenAI、DeepSeek、Azure OpenAI、AWS Bedrock、Ollama 和 Claude CLI。
如果你想尽量本地化，可以选 Ollama：
graphify extract ./docs --backend ollama
如果是云端模型，就按后端设置对应环境变量，比如 OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、DEEPSEEK_API_KEY、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT等。
技术栈也比较简单。主语言是 Python，要求 Python 3.10+，核心依赖里能看到 networkx、datasketch、rapidfuzz和一大串 tree-sitter grammar。可选依赖按 mcp、neo4j、pdf、office、video、postgres、terraform、ollama等功能拆开，默认安装不至于太重。
Graphify 还有一些很偏工程现场的小功能。
比如 graphify hook install可以装 git hook，提交后自动重建代码图谱。团队协作时，官方建议把 graphify-out/也提交到仓库里，这样其他人拉下来后，助手马上就能读已有图谱，不用每个人先跑一遍完整抽取。
不过这一步别无脑做。graphify-out/graph.json里会包含项目实体、路径、关系和部分语义信息，私有仓库问题不大；开源仓库，或者包含敏感业务命名、接口名、SQL schema 的仓库，提交前最好先看一眼产物内容。
再比如 graphify export callflow-html可以导出可读的调用流 HTML；graphify merge-graphs可以合并多张图；graphify prs会看 PR、CI、review 状态和图谱影响范围。里面的 graphify prs --triage属于 AI 排序能力，会用到你配置的模型后端，别把它理解成纯本地静态分析。
但也要说边界。
Graphify 不是装完就一定能让 Agent 变聪明。它更像一层可查询的项目记忆，图谱质量取决于抽取质量，也取决于仓库本身的结构。代码里的 AST 关系相对可靠，文档、PDF、图片这类语义关系更依赖模型抽取，可能漏、可能错，也可能把两个只是名字相近的概念连在一起。
图谱里的边还有置信度标签，分成 EXTRACTED、INFERRED、AMBIGUOUS。这说明作者自己也承认，有些关系是明确抽出来的，有些只是推断，有些需要人看。
还有一点别忽略：它现在迭代非常快，issue 也不少。小金复查时，GitHub 页面已经能看到约 120 多个 open issue。最近有人反馈过 OpenAI backend 参数兼容、AST 跨文件继承漏抽、多仓库集成这类问题或需求。这类工具接了很多宿主和文件类型，稳定性很难一下子拉满。我的建议是先在个人项目或非核心仓库里试，不要一上来就塞进团队主流程。
另外，README 里提到 graphify query、graphify path、graphify explain和 MCP 的 query_graph调用会默认写入 ~/.cache/graphify-queries.log，记录时间、问题、语料路径、返回节点数、耗时这些信息。它默认不存完整子图响应，但如果你特别在意本机痕迹，可以设置：
GRAPHIFY_QUERY_LOG_DISABLE=1
还有一个现实问题，大仓库图谱太大时，graph.html未必适合浏览器打开。官方给的处理方式是超过 5000 个节点时可以跳过 HTML，直接查 JSON：
graphify cluster-only ./my-project --no-viz
graphify query "..."
所以它适合的是“把项目上下文变成助手可查的记忆层”，不是把所有信息都塞进一张炫酷大图里看。
如果你已经在用 Claude Code、Codex、Cursor、Gemini CLI 这类工具写代码，而且经常让它们回答跨文件、跨模块、跨文档的问题，Graphify 值得试，但别急着把它当成生产级代码理解中枢。
更稳的用法是：先在一个中等规模项目里跑一遍，问几个你自己知道答案的问题，比如认证入口、数据库访问链路、核心服务调用关系、某个接口影响范围。如果这些问题命中率不错，再接到日常工作流里。
纯代码仓库可以先本地跑一遍，成本不高；如果涉及 PDF、图片、内部文档，就要先看清楚模型后端、数据流向和查询日志。不要只看 graph.html好不好看，重点看它能不能稳定回答你关心的那几个工程问题。
