Graphify —— 将代码与文档转化为可查询知识图谱的 AI 编程助手

这是什么

Graphify 是一个开源知识图谱映射工具（主语言 Python，GitHub ★83865），核心能力是把整个项目的源代码、文档、PDF、图片和视频等静态文件自动转化为一个可交互的、可查询的知识图谱。用户无需再手动 grep 文件或逐行阅读代码，只需在 AI 编码助手中输入 /graphify .，即可生成三个输出文件：

• graph.html — 可在浏览器中打开的交互式图谱，支持点击节点、筛选和搜索；
• GRAPH_REPORT.md — 关键概念、意外连接和建议查询问题的摘要；
• graph.json — 完整的图结构数据，可供后续查询，无需反复读取原始文件。

Graphify 覆盖 20 多种 AI 助手平台，包括 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等。安装后，在助手内直接调用即可。

解决的问题

大型代码库或文档库中，开发者经常面临以下痛点：

• 信息碎片化：需要跨多个文件 grep 关键字、阅读大量无关代码才能理解一个概念的全貌；
• 上下文关联缺失：代码中的函数、类、导入关系、文档引用等依赖关系分散在数百个文件中，人工追踪耗时且容易遗漏；
• 多模态文件割裂：代码、设计文档、PDF 手册、截图、视频等实体之间缺乏结构化关联，无法统一查询；
• LLM 助手的上下文窗口瓶颈：传统方法把整个代码库塞进提示词不现实，向量检索又会丢失精确的引用关系。

Graphify 通过构建一个有向标注图（节点 = 概念，边 = 关系），将所有这些元数据整合为一张可遍历的结构化网络，让开发者能像问数据库一样问“APIRouter 是什么？”、“FastAPI 与 ModelField 如何连接？”，而非反复查看原始文件。

核心功能

1. 全本地代码映射
   代码分析使用 tree-sitter 解析 AST，完全确定性，不依赖任何 LLM，数据绝不出机器。文档、PDF、图片、视频则使用助手自带的模型或用户配置的 API key 做语义补充。

2. 可解释的边标注
   每条连接都被标记为 EXTRACTED（源文件中显式存在）或 INFERRED（由 Graphify 解析推导），用户能清楚区分哪些是直接从源码读取的，哪些是推理得到的。

3. 非向量索引的真实图结构
   不依赖 embedding、不用向量数据库，真正的有向图。支持三种查询模式：

   • graphify explain <概念> — 返回该节点的定义、所在文件和连接列表；
   • graphify path A B — 找出两个概念之间的最短路径（例如 FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField）；
   • graphify query "<问题>" — 用自然语言问题返回相关的子图。

4. 平台无关的安装与集成
   通过 uv tool install graphifyy 或 pipx install graphifyy 安装 CLI，再用 graphify install 注册技能到当前 AI 助手。支持项目级安装（写入 .claude/skills/ 等目录）和全局安装。

5. 可选的后台建议模式
   运行 graphify recommend 后，助手在查询代码时会自动优先调用 graphify query 而不是直接 grep 文件，进一步减少手动阅读。

亮点 / 与同类相比

| 维度 | Graphify | 传统 grep / 搜索 | 向量索引方案 | |------|----------|------------------|--------------| | 精度 | 确定性 AST 解析，边可追溯 | 全文匹配，无关系理解 | 语义相似度，可能丢失精确关系 | | 可解释性 | 每条边标注 EXTRACTED/INFERRED | 无 | 无 | | 多模态支持 | 代码 + 文档 + PDF + 图片 + 视频 | 仅文本 | 需要分别处理 | | 数据隐私 | 代码部分完全本地，无数据离开 | 本地 | 通常依赖云端 API | | 集成成本 | 20+ 平台，30 秒安装 | 内置，但功能单一 | 需嵌入 SDK | | 查询灵活性 | 路径解释、子图查询、自然语言 | 关键字搜索 | 语义搜索，但无结构 |

• 对比 Codebase RAG 工具：Graphify 不依赖向量嵌入，而是保留源代码中的精确引用关系（如导入、调用、类继承），因此当需要回答“这个函数在哪里被调用？”或“这两段代码有什么直接联系？”时，结果完全可验证。
• 对比 AST 浏览器：Graphify 不仅展示静态 AST，还整合了文档、图片等非代码实体的语义连接，并且通过 AI 助手提供交互式查询。

适合谁用 / 上手

适合人群：

• 维护大型单体项目或微服务代码库的后端开发者；
• 需要快速理解陌生代码库（如接手遗留系统、参与开源项目）的技术人员；
• 在 AI 编码助手中工作，希望减少手动文件浏览的前沿开发者；
• 需要将多份文档、设计图与代码结构统一关联的架构师或技术写作人员。

上手步骤（30 秒内完成）：

1. 安装 CLI

   • macOS: brew install [email protected] uv
   • Windows: winget install astral-sh.uv
   • Ubuntu/Debian: curl -LsSf https://astral.sh/uv/install.sh | sh
     然后执行 uv tool install graphifyy（或 pipx install graphifyy）。

2. 注册助手技能
   graphify install（若需项目级安装加上 --project）。

3. 在 AI 助手内运行
   打开助手，输入 /graphify .。等待几秒后，项目根目录出现 graphify-out/ 文件夹，里面就是图谱文件。

4. 开始查询

   • graphify explain "APIRouter" → 查看节点详情
   • graphify path "FastAPI" "ModelField" → 追踪连接路径
   • graphify query "这个项目的认证流程是怎样的？" → 自然语言子图查询

注意：官方 PyPI 包名为 graphifyy（双 y），CLI 命令仍是 graphify。不要安装其他名称的包。确保 ~/.local/bin 在 PATH 中，或使用 uv tool run --from graphifyy graphify ... 运行。