# 前言
- https://github.com/safishamsi/graphify
- 安装:pip install graphifyy && graphify install

**一个面向 AI 编码助手的技能。** 在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 `/graphify`，它会读取你的文件、构建知识图谱，并把原本不明显的结构关系还给你。更快理解代码库，找到架构决策背后的"为什么"。

完全多模态。你可以直接丢进去代码、PDF、Markdown、截图、流程图、白板照片，甚至其他语言的图片 —— graphify 会用 Claude vision 从这些内容中提取概念和关系，并把它们连接到同一张图里。

> Andrej Karpathy 会维护一个 `/raw` 文件夹，把论文、推文、截图和笔记都丢进去。graphify 就是在解决这类问题 —— 相比直接读取原始文件，每次查询的 token 消耗可降低 **71.5 倍**，结果还能跨会话持久保存，并且会明确区分哪些内容是实际发现的，哪些只是合理推断。

# 安装
## 平台支持

| 平台            | 安装命令                                   |
| ------------- | -------------------------------------- |
| Claude Code   | `graphify install`                     |
| Codex         | `graphify install --platform codex`    |
| OpenCode      | `graphify install --platform opencode` |
| OpenClaw      | `graphify install --platform claw`     |
| Factory Droid | `graphify install --platform droid`    |
| Trae          | `graphify install --platform trae`     |
| Trae CN       | `graphify install --platform trae-cn`  |

Codex 用户还需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，这样才能并行提取。OpenClaw 目前的并行 agent 支持还比较早期，所以使用顺序提取。Trae 使用 Agent 工具进行并行子代理调度，**不支持** PreToolUse hook，因此 AGENTS.md 是其常驻机制。

然后打开你的 AI 编码助手，输入：

```
/graphify .
```

## 让助手始终优先使用图谱（推荐）

图构建完成后，在项目里运行一次：

| 平台 | 命令 |
|------|------|
| 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` |

**Claude Code** 会做两件事：
1. 在 `CLAUDE.md` 中写入一段规则，告诉 Claude 在回答架构问题前先读 `graphify-out/GRAPH_REPORT.md`
2. 安装一个 **PreToolUse hook**（写入 `settings.json`），在每次 `Glob` 和 `Grep` 前触发

如果知识图谱存在，Claude 会先看到：_"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."_ —— 这样 Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。

**Codex、OpenCode、OpenClaw、Factory Droid、Trae** 会把同样的规则写进项目根目录的 `AGENTS.md`。这些平台没有 PreToolUse hook，所以 `AGENTS.md` 是它们的常驻机制。

卸载时使用对应平台的 uninstall 命令即可（例如 `graphify claude uninstall`）。

**常驻模式和显式触发有什么区别？**

常驻 hook 会优先暴露 `GRAPH_REPORT.md` —— 这是一页式总结，包含 god nodes、社区结构和意外连接。你的助手在搜索文件前会先读它，因此会按结构导航，而不是按关键字乱搜。这已经能覆盖大部分日常问题。

`/graphify query`、`/graphify path` 和 `/graphify explain` 会更深入：它们会逐跳遍历底层 `graph.json`，追踪节点之间的精确路径，并展示边级别细节（关系类型、置信度、源位置）。当你想从图谱里精确回答某个问题，而不仅仅是获得整体感知时，就该用这些命令。

可以这样理解：常驻 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                          # 对当前目录运行
/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开发的使用方式
### 具体的实施路线图
1. **安装 Graphify 并配置 ClaudeCode 技能：** 在你的项目根目录运行：
```
graphify install  # 自动向 CLAUDE.md 注入架构索引规则
/graphify .      # 生成初始代码图
```
2. **编写 `CLAUDE.md` 引导：** 在项目根目录创建或修改 `CLAUDE.md`：
> **Architecture Context:** Always read `graphify-out/GRAPH_REPORT.md` before answering architecture questions. **UE Standards:** Follow Unreal Engine 5.x coding standards (PascalCase, U-Prefixes).
3. **开发 MCP 插件：** 如果你有能力，实现一个简单的 MCP Server，能够通过命令行搜索 UE 的 `Reflection Database`。

### 总结建议
- **如果你追求立即理解代码逻辑：** 优先配置 **Graphify**。它能让 Claude 从“逐行看代码”进化到“看地图写代码”。
- **如果你在进行长期复杂的特性开发：** 引入 **Graphiti** 作为 Claude 的“开发日志”，防止它忘记你之前的架构决策。

---

# 具体执行方案
---

**Gemini**

实现这一方案的关键在于将 `graphify` 从一个“傻瓜式扫描器”转变为一个“受控的提取引擎”。针对 Unreal Engine 的庞大规模，我们需要通过精确的路径控制和排除规则来实施。

以下是具体的执行方法与命令：

### 1\. 离线构建 Engine 基础图谱 (The Static Atlas)

由于引擎源码几乎不变量，我们只需构建一次。

**执行策略：** 只索引 `Public` 接口，忽略所有实现（`.cpp` ）和私有目录。

**具体命令：**

```
# 进入引擎 Source 目录
cd /Users/Shared/Epic\ Games/UE_5.4/Engine/Source

# 执行 graphify 扫描
# --include: 仅包含 Public 文件夹下的头文件，这是剪枝的核心
# --ignore: 排除掉极其庞大的第三方库和中间件
graphify index . \
  --output ~/ue_engine_full.graph \
  --include "**/Public/**/*.h" \
  --ignore "ThirdParty/**,Developer/**,Programs/**,Intermediate/**,**/Private/**" \
  --max-depth 5
```

**提示：** 这一步在 M1 Ultra 上可能仍需数十分钟。建议通过 `--max-depth` 限制继承链的抓取深度，通常设置为 5 已经能覆盖 90% 的关键基类（如 `UObject` -> `AActor` -> `APawn` -> `ACharacter` ）。

---

### 2\. 针对 UE 的“剪枝”策略配置文件

为了避免长命令，建议在项目根目录创建一个 `.graphifyconfig` (或工具支持的配置文件)。

**精细化剪枝逻辑：**

- **反射优先：** 重点提取带有 `GENERATED_BODY()` 的类。
- **模块白名单：** 如果你主要做游戏逻辑，只包含以下核心模块：
	- `Runtime/Engine`
		- `Runtime/Core`
		- `Runtime/CoreUObject`
		- `Runtime/InputCore`

**自动化剪枝脚本示例 (Python)：** 如果你发现 `graphify` 无法过滤细碎路径，可以用这个脚本生成一个“干净”的临时符号链接目录供其索引：

```
import os
from pathlib import Path

source_dir = Path("/Users/Shared/Epic Games/UE_5.4/Engine/Source/Runtime")
target_dir = Path("./UE_Thin_Source")

# 仅挑选核心模块的 Public 目录建立软链接
core_modules = ['Engine', 'Core', 'CoreUObject', 'RenderCore']

for module in core_modules:
    pub_path = source_dir / module / "Public"
    if pub_path.exists():
        os.makedirs(target_dir / module, exist_ok=True)
        os.symlink(pub_path, target_dir / module / "Public")
```

然后对 `UE_Thin_Source` 运行 `/graphify` 。

---

### 3\. 实时构建 Project 业务图谱 (The Dynamic Layer)

业务代码变动频繁，需要更轻量、更高频的更新。

**执行命令：**

```
# 在你的项目根目录执行，排除插件和中间文件
graphify index ./Source \
  --output ./project_current.graph \
  --ignore "**/Intermediate/**,**/Binaries/**" \
  --watch
```

**进阶：结合 ClaudeCode 的 `CLAUDE.md`** 在项目根目录的 `CLAUDE.md` 中添加指令，让 Claude 意识到有两个图谱存在：

```
### Knowledge Graph Context
- **Static Engine Graph:** \`~/ue_engine_full.graph\` (Read-only, contains UE5 API)
- **Project Graph:** \`./project_current.graph\` (Updated on save, contains business logic)
- **Rule:** When a class is prefixed with 'U' or 'A' and not in Project Graph, query Engine Graph via \`mcp-graph-tool\`.
```

---

### 4\. 实施 Multi-Graph 挂载的 MCP 方案

要让 ClaudeCode 真正理解这两个图谱，你需要一个简单的 MCP Server 来做中转。

**开发建议：**

1. **加载：** 启动时同时 Load 两个 `.graph` 文件到内存。
2. **查询逻辑：**
	```
	async function searchClass(className) {
	  // 1. 先查项目图谱
	  let result = projectGraph.find(className);
	  if (!result) {
	    // 2. 如果没找到，且符合 UE 命名规范，查引擎图谱
	    result = engineGraph.find(className);
	  }
	  return result;
	}
	```

### 总结执行清单：

1. **环境准备：** 确定 UE 引擎路径。
2. **首次索引：** 使用上述“剪枝命令”生成 `ue_engine_full.graph` ，存放在家目录作为持久缓存。
3. **项目配置：** 在项目内运行带有 `--watch` 的 `graphify` 。
4. **注入 Claude：** 编写 MCP Server 将两个图谱的查询接口暴露给 ClaudeCode。

这种“重引擎索引 + 轻业务监控”的模式，能保证在 64GB 内存的本地环境下，ClaudeCode 既能秒回 API 调用问题，又能深刻理解你的业务代码耦合。你想尝试编写这个 MCP 路由器的代码吗？