347 lines
15 KiB
Markdown
347 lines
15 KiB
Markdown
---
|
||
title: Graphify 知识图谱
|
||
date: 2026-05-28
|
||
tags:
|
||
- ai-agent
|
||
- knowledge-graph
|
||
- graphify
|
||
- gitnexus
|
||
- ue5
|
||
aliases:
|
||
- Graphify
|
||
- 知识图谱工具
|
||
---
|
||
# 前言
|
||
- https://github.com/safishamsi/graphify
|
||
- 安装: `pip install graphifyy`，然后 `graphify claude install`（注册到 Claude Code）
|
||
|
||
**一个面向 AI 编码助手的技能。** 在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 `/graphify`，它会读取你的文件、构建知识图谱，并把原本不明显的结构关系还给你。更快理解代码库，找到架构决策背后的"为什么"。
|
||
|
||
完全多模态。你可以直接丢进去代码、PDF、Markdown、截图、流程图、白板照片，甚至其他语言的图片 —— graphify 会用 Claude vision 从这些内容中提取概念和关系，并把它们连接到同一张图里。
|
||
|
||
> Andrej Karpathy 会维护一个 `/raw` 文件夹，把论文、推文、截图和笔记都丢进去。graphify 就是在解决这类问题 —— 相比直接读取原始文件，每次查询的 token 消耗可降低 **71.5 倍**，结果还能跨会话持久保存，并且会明确区分哪些内容是实际发现的，哪些只是合理推断。
|
||
|
||
# 安装
|
||
|
||
## 平台支持
|
||
|
||
安装 graphify Python 包：
|
||
|
||
```bash
|
||
pip install graphifyy
|
||
# 或
|
||
uv tool install graphifyy
|
||
```
|
||
|
||
然后使用对应平台命令将技能注册到 AI 助手：
|
||
|
||
| 平台 | 注册命令 |
|
||
|------|----------|
|
||
| Claude Code | `graphify claude install` |
|
||
| Codex | `graphify codex install` |
|
||
| OpenCode | `graphify opencode install` |
|
||
| OpenClaw | `graphify claw install` |
|
||
| Factory Droid | `graphify droid install` |
|
||
| Trae | `graphify trae install` |
|
||
| Trae CN | `graphify trae-cn install` |
|
||
|
||
> [!tip] 平台差异
|
||
> - **Codex** 用户需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，才能并行提取
|
||
> - **OpenClaw** 并行 agent 支持较早期，使用顺序提取
|
||
> - **Trae** 使用 Agent 工具进行并行子代理调度，==不支持== PreToolUse hook，AGENTS.md 是其常驻机制
|
||
|
||
然后打开 AI 编码助手，输入：
|
||
|
||
```
|
||
/graphify .
|
||
```
|
||
|
||
## 让助手始终优先使用图谱（推荐）
|
||
|
||
图构建完成后，在项目里运行对应平台的 install 命令（见上表）。
|
||
|
||
**Claude Code** 上会做两件事：
|
||
|
||
1. 在 `CLAUDE.md` 中写入规则，告诉 Claude 在回答架构问题前先读 `graphify-out/GRAPH_REPORT.md`
|
||
2. 安装 **PreToolUse hook**（写入 `settings.json`），在每次 `Glob` 和 `Grep` 前触发
|
||
|
||
> [!quote] Hook 提示效果
|
||
> *"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."*
|
||
>
|
||
> Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。
|
||
|
||
> [!info] 其他平台
|
||
> **Codex、OpenCode、OpenClaw、Factory Droid、Trae** 把同样规则写入 `AGENTS.md`。这些平台没有 PreToolUse hook，AGENTS.md 是其常驻机制。
|
||
|
||
卸载时使用对应平台的 uninstall 命令（如 `graphify claude uninstall`）。
|
||
|
||
## 常驻模式 vs 显式触发
|
||
|
||
> [!important] 常驻 hook
|
||
> 优先暴露 `GRAPH_REPORT.md` —— 一页式总结，包含 ==god nodes==、==社区结构== 和 ==意外连接==。助手在搜索文件前会先读它，按结构导航而非按关键字搜索。覆盖大部分日常问题。
|
||
|
||
`/graphify query`、`/graphify path` 和 `/graphify explain` 会更深入：逐跳遍历底层 `graph.json`，追踪节点间精确路径，展示边级别细节（关系类型、置信度、源位置）。适合精确回答特定问题。
|
||
|
||
> [!abstract] 一句话理解
|
||
> 常驻 hook ==先给助手一张地图==，`/graphify` 命令则 ==让助手沿着地图精确导航==。
|
||
|
||
<details>
|
||
<summary>手动安装（curl）</summary>
|
||
|
||
```bash
|
||
mkdir -p ~/.claude/skills/graphify
|
||
curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v3/graphify/skill.md \
|
||
> ~/.claude/skills/graphify/SKILL.md
|
||
```
|
||
|
||
把下面内容加到 `~/.claude/CLAUDE.md`：
|
||
|
||
```
|
||
- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
|
||
When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"` before doing anything else.
|
||
```
|
||
|
||
</details>
|
||
|
||
# 用法
|
||
推荐使用：`/graphify ./raw --directed --no-viz`
|
||
```
|
||
/graphify # 对当前目录运行
|
||
/graphify ./raw # 对指定目录运行
|
||
/graphify ./raw --mode deep # 更激进地抽取 INFERRED 边
|
||
/graphify ./raw --update # 只重新提取变更文件，并合并到已有图谱
|
||
/graphify ./raw --cluster-only # 只重新聚类已有图谱，不重新提取
|
||
/graphify ./raw --no-viz # 跳过 HTML，只生成 report + JSON
|
||
/graphify ./raw --obsidian # 额外生成 Obsidian vault（可选）
|
||
|
||
/graphify add https://arxiv.org/abs/1706.03762 # 拉取论文、保存并更新图谱
|
||
/graphify add https://x.com/karpathy/status/... # 拉取推文
|
||
/graphify add https://... --author "Name" # 标记原作者
|
||
/graphify add https://... --contributor "Name" # 标记是谁把它加入语料库的
|
||
|
||
/graphify query "what connects attention to the optimizer?"
|
||
/graphify query "what connects attention to the optimizer?" --dfs # 追踪一条具体路径
|
||
/graphify query "what connects attention to the optimizer?" --budget 1500 # 把预算限制在 N tokens
|
||
/graphify path "DigestAuth" "Response"
|
||
/graphify explain "SwinTransformer"
|
||
|
||
/graphify ./raw --watch # 文件变更时自动同步图谱（代码：立即更新；文档：提醒你）
|
||
/graphify ./raw --wiki # 构建可供 agent 抓取的 wiki（index.md + 每个 community 一篇文章）
|
||
/graphify ./raw --svg # 导出 graph.svg
|
||
/graphify ./raw --graphml # 导出 graph.graphml（Gephi、yEd）
|
||
/graphify ./raw --neo4j # 生成给 Neo4j 用的 cypher.txt
|
||
/graphify ./raw --neo4j-push bolt://localhost:7687 # 直接推送到运行中的 Neo4j
|
||
/graphify ./raw --mcp # 启动 MCP stdio server
|
||
|
||
# git hooks - 跨平台，在 commit 和切分支后重建图谱
|
||
graphify hook install
|
||
graphify hook uninstall
|
||
graphify hook status
|
||
|
||
# 常驻助手规则 - 按平台区分
|
||
graphify claude install # CLAUDE.md + PreToolUse hook（Claude Code）
|
||
graphify claude uninstall
|
||
graphify codex install # AGENTS.md（Codex）
|
||
graphify opencode install # AGENTS.md（OpenCode）
|
||
graphify claw install # AGENTS.md（OpenClaw）
|
||
graphify droid install # AGENTS.md（Factory Droid）
|
||
graphify trae install # AGENTS.md（Trae）
|
||
graphify trae uninstall
|
||
graphify trae-cn install # AGENTS.md（Trae CN）
|
||
graphify trae-cn uninstall
|
||
```
|
||
|
||
支持混合文件类型：
|
||
|
||
| 类型 | 扩展名 | 提取方式 |
|
||
|------|--------|----------|
|
||
| 代码 | `.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php` | tree-sitter AST + 调用图 + docstring / 注释中的 rationale |
|
||
| 文档 | `.md .txt .rst` | 通过 Claude 提取概念、关系和设计动机 |
|
||
| 论文 | `.pdf` | 引文挖掘 + 概念提取 |
|
||
| 图片 | `.png .jpg .webp .gif` | Claude vision —— 截图、图表、任意语言都可以 |
|
||
|
||
# 你会得到什么
|
||
- **God nodes** —— 度最高的概念节点（整个系统最容易汇聚到的地方）
|
||
- **意外连接** —— 按综合得分排序。代码-论文之间的边会比代码-代码边权重更高。每条结果都会附带一段人话解释。
|
||
- **建议提问** —— 图谱特别擅长回答的 4 到 5 个问题。
|
||
- **“为什么”** —— docstring、行内注释（`# NOTE:`、`# IMPORTANT:`、`# HACK:`、`# WHY:`）以及文档里的设计动机都会被抽取成 `rationale_for` 节点。不只是知道代码“做了什么”，还能知道“为什么要这么写”。
|
||
- **置信度分数** —— 每条 `INFERRED` 边都有 `confidence_score`（0.0-1.0）。你不只知道哪些是猜出来的，还知道模型对这个猜测有多有把握。`EXTRACTED` 边恒为 1.0。
|
||
- **语义相似边** —— 跨文件的概念连接，即使结构上没有直接依赖也能建立关联。比如两个函数做的是同一类问题但彼此没有调用，或者某个代码类和某篇论文里的算法概念本质相同。
|
||
- **超边（Hyperedges）** —— 用来表达 3 个以上节点的群组关系，这是普通两两边表达不出来的。比如：一组类共同实现一个协议、认证链路里的一组函数、同一篇论文某一节里的多个概念共同组成一个想法。
|
||
- **Token 基准** —— 每次运行后都会自动打印。对混合语料（Karpathy 的仓库 + 论文 + 图片），每次查询的 token 消耗可以比直接读原文件少 **71.5 倍**。第一次运行需要先提取并建图，这一步会花 token；后续查询直接读取压缩后的图谱，节省会越来越明显。SHA256 缓存保证重复运行时只重新处理变更文件。
|
||
- **自动同步**（`--watch`）—— 在后台终端里跑着，代码库一变化，图谱就会跟着更新。代码文件保存会立刻触发重建（只走 AST，不用 LLM）；文档/图片变更则会提醒你跑 `--update` 进行 LLM 再提取。
|
||
- **Git hooks**（`graphify hook install`）—— 安装 `post-commit` 和 `post-checkout` hook。每次 commit 后、每次切分支后都会自动重建图谱，不需要额外开一个后台进程。
|
||
- **Wiki**（`--wiki`）—— 为每个 community 和 god node 生成类似维基百科的 Markdown 文章，并提供 `index.md` 作为入口。任何 agent 只要读 `index.md`，就能通过普通文件导航整个知识库，而不必直接解析 JSON。
|
||
|
||
## Worked examples
|
||
|
||
| 语料 | 文件数 | 压缩比 | 输出 |
|
||
|------|--------|--------|------|
|
||
| Karpathy 的仓库 + 5 篇论文 + 4 张图片 | 52 | **71.5x** | [`worked/karpathy-repos/`](worked/karpathy-repos/) |
|
||
| graphify 源码 + Transformer 论文 | 4 | **5.4x** | [`worked/mixed-corpus/`](worked/mixed-corpus/) |
|
||
| httpx（合成 Python 库） | 6 | ~1x | [`worked/httpx/`](worked/httpx/) |
|
||
|
||
Token 压缩效果会随着语料规模增大而更明显。6 个文件本来就塞得进上下文窗口，所以 graphify 在这种场景里的价值更多是结构清晰度，而不是 token 压缩。到了 52 个文件（代码 + 论文 + 图片）这种规模，就能做到 71x+。每个 `worked/` 目录里都带了原始输入和真实输出（`GRAPH_REPORT.md`、`graph.json`），你可以自己跑一遍核对数字。
|
||
|
||
# 针对UE开发的使用方式
|
||
|
||
## 核心结论
|
||
|
||
> [!warning] Graphify ==不适合==索引 UE 引擎源码
|
||
> 引擎数百万行 C++ + 海量宏（`UCLASS()`、`GENERATED_BODY()`），LLM 语义提取成本极高且不精确。
|
||
>
|
||
> **引擎源码 → [[GitNexus 知识图谱|GitNexus]]**（Tree-sitter AST，无 LLM 成本）
|
||
|
||
**Graphify 的正确定位：项目业务层的宏观语义图谱。**
|
||
|
||
索引范围：
|
||
- 项目 C++ 业务代码（`Source/`）
|
||
- 设计文档和规范（`.trae/documents/`、`.trae/specs/`）
|
||
- 策划案和架构说明（Markdown）
|
||
- 排除所有编译产物、第三方插件、UE 配置/资产
|
||
|
||
## 实际配置（已验证 ✅）
|
||
|
||
### 1. 创建 `.graphifyignore`
|
||
|
||
> [!important] .graphifyignore 是唯一的排除机制
|
||
> 排除规则通过 `.graphifyignore` 控制（==gitignore 语法==）。**不存在** `--include`、`--ignore`、`--output`、`index` 等 CLI 参数 —— 这些都是虚构的。
|
||
|
||
```gitignore
|
||
# UE 编译产物
|
||
Binaries/
|
||
Intermediate/
|
||
Saved/
|
||
DerivedDataCache/
|
||
Build/
|
||
|
||
# UE 配置和资产（非代码）
|
||
Config/
|
||
Content/
|
||
|
||
# 第三方插件
|
||
Plugins/LogicDriver/
|
||
Plugins/UnrealImGui/
|
||
# ... 等
|
||
|
||
# AI 工具配置（非项目内容）
|
||
.kilocode/
|
||
.trae/skills/
|
||
.trae/plans/
|
||
.trae/.obsidian/
|
||
```
|
||
|
||
### 2. 构建图谱
|
||
|
||
```bash
|
||
/graphify . --directed --no-viz
|
||
```
|
||
|
||
- `--directed`：构建有向图（保留 source → target 方向）
|
||
- `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
|
||
- 输出固定到 `graphify-out/`，**不存在** `--output` 参数
|
||
|
||
### 3. 安装常驻规则
|
||
|
||
```bash
|
||
graphify claude install
|
||
```
|
||
|
||
在 `CLAUDE.md` 中写入规则 + 注册 PreToolUse hook，让 CC 优先用图谱导航而非盲搜 grep。
|
||
|
||
### 4. 增量更新
|
||
|
||
```bash
|
||
/graphify . --update # 只重新提取变更文件，合并到已有图谱
|
||
```
|
||
|
||
## 双图谱架构（Graphify + GitNexus）
|
||
|
||
| 工具 | 索引目标 | 技术 |
|
||
|------|----------|------|
|
||
| **Graphify** | 项目业务层：设计文档、模块架构、策划案 | LLM 语义 + AST |
|
||
| **GitNexus** | 项目 + 引擎符号层：C++ 类继承、函数调用链 | Tree-sitter AST |
|
||
|
||
### 引擎源码（一次性索引）
|
||
|
||
```bash
|
||
cd D:\UnrealEngine\UE_5.7\Engine\Source
|
||
npx gitnexus analyze --skip-agents-md --skip-skills
|
||
```
|
||
|
||
> [!note] 下载版引擎
|
||
> 下载版引擎无 `.git`，不需要 `--skip-git`；源码克隆版需要去掉此参数。
|
||
|
||
GitNexus MCP 单实例自动服务所有已索引仓库，通过 `repo` 参数区分目标。
|
||
|
||
### CLAUDE.md 路由优先级
|
||
```mermaid
|
||
graph TD
|
||
A[收到任务] --> B{需要什么信息?}
|
||
B -->|业务意图/模块关系| C[Graphify]
|
||
B -->|精确符号/调用链| D[GitNexus AIDM]
|
||
B -->|引擎底层 API| E[GitNexus UE Engine]
|
||
B -->|设计文档/规范| F[Graphify 社区]
|
||
```
|
||
|
||
> [!tip] 当前状态（2026-05-28）
|
||
> - Graphify AIDM：==4,168 nodes · 5,427 edges · 532 communities==
|
||
> - GitNexus AIDM：==59,371 symbols · 106,882 edges · 300 flows==
|
||
> - GitNexus UE Engine：索引中（`npx gitnexus analyze` 后台运行）
|
||
|
||
|
||
# 其他项目用命令行
|
||
|
||
## AssetMaker
|
||
### Graphify
|
||
#### 前置条件
|
||
1. 确保 `.graphifyignore` 已放在项目根目录（`D:\AI\Website\CharacterMaker\.graphifyignore`），内容：
|
||
```
|
||
frontend/public/
|
||
frontend/dist/
|
||
**/dist/
|
||
**/build/
|
||
**/node_modules/
|
||
**/*.min.js
|
||
**/*.min.css
|
||
**/*.map
|
||
**/*.lock
|
||
blender/
|
||
backend/server/uploads/
|
||
docs/graphify/
|
||
.claude/
|
||
.worktrees/
|
||
mongo-data/
|
||
redis-data/
|
||
graphify-out/
|
||
```
|
||
|
||
2. 安装 watchdog（watch 模式依赖）：
|
||
```powershell
|
||
pip install watchdog
|
||
```
|
||
|
||
#### 初始构建（首次或全量重建）
|
||
```bash
|
||
# 当前目录
|
||
/graphify . --directed --no-viz
|
||
# 指定目录
|
||
/graphify D:\AI\Website\CharacterMaker --directed --no-viz
|
||
```
|
||
- `--directed`：构建有向图（保留边方向）
|
||
- `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
|
||
|
||
> [!warning] 常见误区
|
||
> - `--output` ==不是有效 flag==，graphify 固定输出到项目根目录的 `graphify-out/`
|
||
> - `--ignore` ==不是有效 flag==，排除规则一律通过 `.graphifyignore` 文件控制
|
||
|
||
#### watch 模式（文件变更时自动更新图谱）
|
||
Claude Code 中运行（通过 skill 调度）：
|
||
```
|
||
/graphify D:\AI\Website\CharacterMaker --watch
|
||
```
|
||
|
||
或直接在终端运行（无需 Claude Code）：
|
||
```powershell
|
||
python -m graphify.watch D:\AI\Website\CharacterMaker --debounce 3
|
||
``` |