## 项目概述

Graphify 是一个开源工具，旨在将任何代码库（包括文档、SQL 模式、配置文件和 PDF）转换为可查询的知识图谱。它作为 AI 编程助手（如 Claude Code、Cursor、Codex 和 Gemini CLI）的技能（skill）运行，通过本地确定性的 AST 解析（使用 tree-sitter）构建图谱，无需向量存储。每个边都有明确的解释（EXTRACTED 或 INFERRED），帮助开发者理解代码结构、发现隐藏关系，并以自然语言查询代码库。项目由 Graphify-Labs 维护，采用 Apache-2.0 许可证，主要使用 Python 编写。

## 核心功能

- **代码图谱构建**：使用 tree-sitter AST 解析代码，提取类、函数、导入、调用关系等，完全本地化，无需 LLM 调用。
- **多模态支持**：支持文档（Markdown、PDF、图片、视频/音频）的语义提取，通过 AI 助手模型或配置的 API 密钥进行。
- **图谱查询**：提供 `query`、`path`、`explain` 命令，可对图谱进行自然语言查询、路径追踪和概念解释。
- **社区检测**：使用 Leiden 算法将图谱划分为社区，并自动生成标签。
- **可视化**：生成交互式 HTML 图谱（graph.html），支持点击、过滤和搜索。
- **报告生成**：生成 GRAPH_REPORT.md，包含关键概念、意外连接和建议问题。
- **增量更新**：支持增量提取，仅处理变更文件，节省时间和 API 成本。
- **实体去重**：通过 MinHash/LSH 和 Jaro-Winkler 算法合并近似重复的实体。
- **多平台集成**：支持 20+ 种 AI 编程助手平台，包括 Claude Code、Cursor、Codex、Gemini CLI 等。
- **MCP 服务器**：可将图谱作为 MCP 服务器暴露，支持 stdio 和 HTTP 传输。

## 适用与不适用场景

**适用场景：**
- 大型代码库的快速理解和导航。
- 跨文件、跨模块的依赖关系分析。
- 文档、论文、图片等多模态资料的整合查询。
- 团队协作时共享代码知识图谱。
- 需要本地优先、隐私敏感的开发环境。

**不适用场景：**
- 需要实时、动态更新的场景（图谱构建需要时间）。
- 对图谱准确性要求极高，无法容忍推断错误的场景。
- 仅处理少量文件（如少于 6 个文件）时，图谱优势不明显。
- 需要向量相似度搜索的场景（Graphify 不使用向量存储）。

## 技术架构与依赖

- **核心语言**：Python 3.10+。
- **主要依赖**：tree-sitter（AST 解析）、NetworkX（图数据结构）、Leiden 算法（社区检测）、datasketch（MinHash/LSH）、rapidfuzz（Jaro-Winkler）。
- **可选依赖**：faster-whisper（视频/音频转录）、yt-dlp（视频下载）、Ollama（本地推理）、OpenAI/Gemini/Anthropic API 等。
- **架构**：三阶段处理——AST 提取（本地）、视频/音频转录（本地）、语义提取（LLM，可选）。
- **输出格式**：graph.json（NetworkX node-link 格式）、graph.html（可视化）、GRAPH_REPORT.md（报告）。

## 安装与快速开始

**安装：**
```bash
# 推荐使用 uv
uv tool install graphifyy
# 或 pipx
pipx install graphifyy
# 或 pip
pip install graphifyy
```

**注册技能：**
```bash
graphify install
```

**快速开始：**
在 AI 编程助手中输入 `/graphify .`，即可为当前目录构建知识图谱。输出文件位于 `graphify-out/` 目录。

## 典型使用方法

```bash
# 构建图谱
/graphify .

# 查询图谱
graphify query "what connects auth to the database?"

# 路径追踪
graphify path "UserService" "DatabasePool"

# 解释概念
graphify explain "RateLimiter"

# 增量更新
graphify extract ./docs --update

# 导出为 Mermaid 架构图
graphify export callflow-html

# 启动 MCP 服务器
graphify serve graphify-out/graph.json
```

## 配置与部署要点

- **环境变量**：根据后端选择设置 API 密钥，如 `ANTHROPIC_API_KEY`、`GEMINI_API_KEY`、`OPENAI_API_KEY` 等。
- **忽略文件**：使用 `.graphifyignore` 文件排除不需要索引的目录，语法与 `.gitignore` 相同。
- **团队协作**：将 `graphify-out/` 提交到 Git，团队成员共享图谱。
- **Git Hooks**：使用 `graphify hook install` 在每次提交后自动重建图谱。
- **部署**：可通过 Docker 部署 MCP HTTP 服务器，供团队共享。

## 限制、风险与许可证

- **限制**：代码解析仅支持 tree-sitter 覆盖的语言；语义提取需要 LLM API 调用，可能产生费用；图谱构建时间随文件数量增加。
- **风险**：推断的边可能不准确；文档、PDF 等内容的语义提取依赖外部 API，存在数据隐私风险（但代码和视频/音频处理是本地化的）。
- **许可证**：Apache-2.0。

## 官方链接

- GitHub 仓库：https://github.com/Graphify-Labs/graphify
- PyPI 包：https://pypi.org/project/graphifyy/
- 官方网站：https://graphify.com
- 文档：仓库内 docs/ 目录

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、docs/ 目录下的文档（how-it-works.md、docker-mcp-sqlite.md 等）、最新发布信息（v0.9.39）。
- 分析时间：2026-08-10（基于最新发布版本日期）。