## 项目概述

graphify 是一个 AI 编程助手技能（支持 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid、Trae 等），能够将任意文件夹中的代码、文档、论文或图片转化为可查询的知识图谱。它提取规范实体和类型化关系，在可配置本体下跨来源去重与调和，并提供查询界面供助手或终端用户推理。项目由 rhanka 维护，使用 TypeScript 编写，采用 MIT 许可证。

## 核心功能

- **知识图谱构建**：从代码、文档、论文、图片、音视频等语料中提取实体和关系，生成持久化的 `graph.json`。
- **本体配置**：支持自定义本体配置文件（`graphify.yaml`），定义节点类型、关系类型、视觉编码（形状和颜色）等。
- **实体调和**：将同一实体的不同提及（如别名、变体）合并为规范实体，支持候选生成、补丁生命周期（提议、验证、试运行、应用）和审计追踪。
- **查询与可视化**：提供 `graphify query`、`graphify path`、`graphify explain` 等命令，以及静态的 Ontology Studio 可视化界面。
- **多模态输入**：支持文档（Markdown、HTML 等）、Office 文件、PDF（含 OCR）、图片、音视频（本地转写）。
- **代码知识图谱**：通过 tree-sitter 进行无 LLM 的 AST 解析，支持约 20 种编程语言，提取类、函数、调用图等。
- **代理统计**：`graphify agent-stats` 索引代理 CLI 对话记录，基于证据归属分支、提交和工作包。
- **存储镜像**：可将图镜像到 Postgres 等数据库后端，加速分组计数。

## 适用与不适用场景

**适用场景：**
- 大型代码库理解：快速回答“什么调用了这个？”、“修改这个会破坏什么？”等问题。
- 跨文档知识整合：将多本书、手册、注册表中的实体和关系统一为知识图谱。
- 研究论文分析：提取概念、关系和设计原理。
- 多代理协作：跟踪不同 AI 代理在仓库中的工作归属。

**不适用场景：**
- 小型语料库：当语料很小且已能放入上下文时，token 节省不明显，价值主要在于结构清晰。
- 需要实时更新的场景：文档或图片变更后需要手动运行 `--update` 进行 LLM 重提取。
- 对隐私要求极高的场景：文档、论文、图片的内容会发送到模型 API 进行语义提取（代码文件除外）。

## 技术架构与依赖

- **语言**：TypeScript
- **核心依赖**：Graphology（图数据结构）、Louvain 社区检测（`graphology-communities-louvain`）、tree-sitter（AST 解析）、vis-network（旧版可视化，已移除）、unpdf（PDF 处理）、officeparser（Office 文件）、turndown（HTML 转 Markdown）、yt-dlp + ffmpeg + faster-whisper-ts（音视频转写）、Vercel AI SDK（可选直接后端）。
- **可选依赖**：tree-sitter 语法包（部分语言）、faster-whisper-ts（音视频）、@sentropic/design-system（设计系统令牌）。
- **架构**：确定性结构解析（无 LLM）+ 模型支持的语义解析，结果合并到 Graphology 图，使用 Louvain 聚类，导出多种格式。

## 安装与快速开始

**要求**：Node.js 20+ 和受支持的 AI 编程助手（Claude Code、Codex、Gemini CLI 等）。

```bash
npm install -g @sentropic/graphify
graphify install
```

在助手内构建第一个图：

```bash
/graphify .                        # Claude Code / Gemini CLI / Copilot / Aider / OpenCode 等
$graphify .                        # Codex
```

输出位于 `.graphify/` 目录，包含 `graph.json`、`GRAPH_REPORT.md`、`studio/`（静态可视化）、`wiki/`（可选）和 `cache/`。

## 典型使用方法

从终端查询图：

```bash
graphify query "what connects attention to the optimizer?" --graph .graphify/graph.json
graphify path "DigestAuth" "Response" --graph .graphify/graph.json
graphify explain "SwinTransformer" --graph .graphify/graph.json
graphify summary --graph .graphify/graph.json
```

构建选项：

```bash
/graphify ./raw --directed         # 保留方向
/graphify ./raw --mode deep        # 更激进的推断边提取
/graphify ./raw --update           # 仅重新提取变更文件
/graphify ./raw --cluster-only     # 仅重新聚类
/graphify ./raw --svg              # 导出 SVG
/graphify ./raw --graphml          # 导出 GraphML
/graphify ./raw --neo4j-push bolt://localhost:7687   # 推送到 Neo4j
```

本体调和工作流：

```bash
graphify ontology candidates --profile-state .graphify/profile/profile-state.json --out .graphify/ontology/candidates.json
graphify ontology patch validate --profile-state .graphify/profile/profile-state.json --patch patch.json
graphify ontology patch apply --profile-state .graphify/profile/profile-state.json --patch patch.json --dry-run
graphify ontology patch apply --profile-state .graphify/profile/profile-state.json --patch patch.json --write
```

## 配置与部署要点

- **本体配置**：在 `graphify.yaml` 中指定本体配置文件路径、输入语料、注册表等。
- **环境变量**：API 密钥仅从环境变量读取，如 `MISTRAL_API_KEY`、`ANTHROPIC_BASE_URL` 等。
- **PDF OCR**：通过 `GRAPHIFY_PDF_OCR` 控制，`auto` 模式本地预检，必要时调用 Mistral OCR。
- **音视频转写**：使用 faster-whisper-ts，可通过 `GRAPHIFY_WHISPER_MODEL` 等变量覆盖。
- **存储镜像**：配置 `GRAPHIFY_STORE=postgres` 和 `GRAPHIFY_POSTGRES_URL` 以使用 Postgres 后端。
- **安全**：代码文件本地处理，不上传；文档等发送到模型 API。无遥测。

## 限制、风险与许可证

- **限制**：语义提取依赖模型 API，可能产生幻觉；调和算法在大规模语料上可能不终止（已知问题）；token 指标为估计值，除非有真实模型调用。
- **风险**：存在已知 npm 安全公告（如 `ws`、`hono` 等），但多数不可达或为可选依赖；`ollama-ai-provider` 存在无修复的低危漏洞，需正式接受或移除。
- **许可证**：MIT。

## 官方链接

- GitHub 仓库：https://github.com/rhanka/graphify
- 在线演示（Ontology Studio）：https://mystery-saga.sent-tech.ca/studio/

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CHANGELOG、安全文档、研究文档。
- 分析时间：2026-07-31（基于仓库内容中的日期）。