Graphify：AI 编程助手技能，将代码库转化为可查询的知识图谱

这是什么

graphify 是一个基于 Python 的开源 AI 编程助手技能（Skill）和命令行工具，由 safishamsi 维护。它能够将整个代码库（包括代码、文档、PDF、图片、视频等）映射为一个可查询的知识图谱（Knowledge Graph）。

该项目并非传统的代码搜索工具，而是通过构建节点和边，将非结构化或半结构化的项目数据转化为结构化的关系网络。用户只需在支持的 AI 编码助手（如 Claude Code、Cursor、GitHub Copilot 等）中输入 /graphify，即可触发对项目的全面理解与查询，替代低效的文件遍历（grep）方式。

解决的问题

现代大型软件项目通常面临以下痛点，graphify 旨在解决这些问题：

1. 上下文碎片化：代码逻辑分散在多个文件、模块甚至不同格式（Markdown、PDF）中，AI 助手难以一次性获取全局视图。
2. 搜索效率低下：传统的 grep 或全文搜索只能匹配关键词，无法理解代码间的依赖关系、调用流程或设计意图。
3. AI 助手“幻觉”与局限：通用 AI 模型缺乏对特定私有代码库的深层结构理解，容易给出基于通用知识的错误建议，而非基于项目实际架构的回答。
4. 架构理解成本高：新加入项目的开发者需要花费大量时间阅读文档和代码才能理清模块间的复杂联系。

核心功能

1. 多模态知识图谱构建

graphify 支持提取多种类型的数据源：

• 代码：通过 tree-sitter 在本地解析 AST（抽象语法树），无需调用外部 API，确保代码隐私。
• 文档与媒体：支持 PDF、Markdown、图片、视频等。
• Google Workspace：通过 gws CLI 集成，支持将 Google Docs、Sheets 和 Slides 转换为 Markdown 侧边文件进行提取。

2. 智能输出与可视化

执行 /graphify . 后，生成三个核心文件：

• graph.html：交互式可视化界面，支持节点点击、过滤和搜索，直观展示项目结构。
• GRAPH_REPORT.md：提炼关键概念、意外连接（Surprising Connections）及建议问题，适合快速架构审查。
• graph.json：完整的图谱数据，供后续查询或二次开发使用。

3. 深度语义分析

• God Nodes（核心节点）：识别项目中连接度最高的概念，所有逻辑往往围绕这些节点展开。
• 意外连接：发现跨文件或跨模块的潜在联系，并按“意外程度”排序。
• 设计意图提取：从注释（# NOTE:, # WHY:）、Docstrings 和文档中提取设计理由，将其作为独立节点链接到对应代码。
• 置信度标签：每个推断的关系都标记为 EXTRACTED（提取）、INFERRED（推断）或 AMBIGUOUS（模糊），明确区分事实与推测。

4. 广泛的 AI 助手集成

支持在多种 AI 编码助手中注册为“Skill”，包括：

• Claude Code, Codex, OpenCode, Kilo Code, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, Amp, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, Devin CLI, Google Antigravity。
• 提供项目级（Project-scoped）安装，将配置写入 .claude/skills/ 或 .agents/skills/ 等目录，便于版本控制。

5. 架构可视化与查询

• 调用流图：通过 graphify export callflow-html 生成基于 Mermaid 的架构/调用流 HTML 图。
• 自然语言查询：支持 /graphify query "what connects auth to the database?" 等自然语言提问，直接基于图谱回答。

亮点 / 与同类相比

• 本地优先的代码解析：代码提取完全在本地通过 tree-sitter 完成，不依赖外部 API，保障了代码安全性，同时避免了网络延迟。其他非结构化数据则通过用户配置的 AI 模型 API 处理。
• 主动式引导机制：不同于被动等待用户提问，graphify 可通过安装 Hook（如 PreToolUse）或写入 AGENTS.md 等配置文件，在 AI 助手执行搜索或读取文件前，主动提示其优先查询知识图谱。这显著提升了回答的准确性。
• 细粒度的控制选项：支持 --cluster-only（仅重新聚类）、--resolution（调整社区发现的粒度）、--exclude-hubs（排除超级枢纽节点）等参数，允许开发者精细调整图谱构建过程。
• 多平台适配策略：针对不同 AI 助手（如 Claude Code 的 Hook 机制、Cursor 的 .mdc 规则、Codex 的 AGENTS.md）提供了特定的安装和配置指南，确保最佳兼容性。
• 置信度透明化：明确标注关系的来源（提取 vs 推断），帮助用户判断 AI 回答的可信度，这是许多其他代码分析工具所缺乏的。

适合谁用 / 上手

适合人群

• 大型项目维护者：需要快速理解复杂代码库架构、依赖关系和设计意图的开发者。
• AI 编码助手重度用户：希望提升 Claude Code、Cursor、Copilot 等工具对私有项目理解深度的工程师。
• 技术文档与知识管理：需要将代码、文档和多媒体资料整合为可查询知识图谱的团队。
• 新入职开发者：希望通过交互式图谱快速上手新项目，减少阅读代码的时间。

上手指南

1. 安装环境：

   • macOS: brew install [email protected] uv
   • Windows: winget install astral-sh.uv
   • Ubuntu/Debian: sudo apt install python3.12 python3-pip pipx 或安装 uv。
   • 注意：推荐使用 uv 或 pipx 安装，以避免路径和环境冲突问题。

2. 安装软件包：

   # 推荐方式
   uv tool install graphifyy
   # 或
   pipx install graphifyy
   

   注意：PyPI 上的包名为 graphifyy（双 y），其他 graphify* 包非官方。

3. 注册 AI 助手技能：

   graphify install
   

   若需仅在当前项目生效，可添加 --project 标志：

   graphify install --project
   

4. 使用： 打开支持的 AI 编码助手，输入 /graphify . 开始构建当前目录的知识图谱。构建完成后，可在浏览器中打开 graphify-out/graph.html 进行交互探索，或在 AI 助手中使用 /graphify query 进行提问。

5. 高级配置：

   • 安装 Git Hook 以在每次提交后自动更新调用流图：graphify hook install。
   • 配置 Google Workspace 支持需额外安装 graphifyy[google] 并认证 gws CLI。