vault backup: 2026-05-28 18:41:41
This commit is contained in:
@@ -1,6 +1,19 @@
|
||||
---
|
||||
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 install
|
||||
- 安装: `pip install graphifyy`，然后 `graphify claude install`（注册到 Claude Code）
|
||||
|
||||
**一个面向 AI 编码助手的技能。** 在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 `/graphify`，它会读取你的文件、构建知识图谱，并把原本不明显的结构关系还给你。更快理解代码库，找到架构决策背后的"为什么"。
|
||||
|
||||
@@ -9,32 +22,21 @@
|
||||
> 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` |
|
||||
安装 graphify Python 包：
|
||||
|
||||
Codex 用户还需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，这样才能并行提取。OpenClaw 目前的并行 agent 支持还比较早期，所以使用顺序提取。Trae 使用 Agent 工具进行并行子代理调度，**不支持** PreToolUse hook，因此 AGENTS.md 是其常驻机制。
|
||||
|
||||
然后打开你的 AI 编码助手，输入：
|
||||
|
||||
```
|
||||
/graphify .
|
||||
```bash
|
||||
pip install graphifyy
|
||||
# 或
|
||||
uv tool install graphifyy
|
||||
```
|
||||
|
||||
## 让助手始终优先使用图谱（推荐）
|
||||
然后使用对应平台命令将技能注册到 AI 助手：
|
||||
|
||||
图构建完成后，在项目里运行一次：
|
||||
|
||||
| 平台 | 命令 |
|
||||
|------|------|
|
||||
| 平台 | 注册命令 |
|
||||
|------|----------|
|
||||
| Claude Code | `graphify claude install` |
|
||||
| Codex | `graphify codex install` |
|
||||
| OpenCode | `graphify opencode install` |
|
||||
@@ -43,23 +45,45 @@ Codex 用户还需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `mult
|
||||
| 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` 前触发
|
||||
> [!tip] 平台差异
|
||||
> - **Codex** 用户需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，才能并行提取
|
||||
> - **OpenClaw** 并行 agent 支持较早期，使用顺序提取
|
||||
> - **Trae** 使用 Agent 工具进行并行子代理调度，==不支持== PreToolUse hook，AGENTS.md 是其常驻机制
|
||||
|
||||
如果知识图谱存在，Claude 会先看到：_"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."_ —— 这样 Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。
|
||||
然后打开 AI 编码助手，输入：
|
||||
|
||||
**Codex、OpenCode、OpenClaw、Factory Droid、Trae** 会把同样的规则写进项目根目录的 `AGENTS.md`。这些平台没有 PreToolUse hook，所以 `AGENTS.md` 是它们的常驻机制。
|
||||
```
|
||||
/graphify .
|
||||
```
|
||||
|
||||
卸载时使用对应平台的 uninstall 命令即可（例如 `graphify claude uninstall`）。
|
||||
## 让助手始终优先使用图谱（推荐）
|
||||
|
||||
**常驻模式和显式触发有什么区别？**
|
||||
图构建完成后，在项目里运行对应平台的 install 命令（见上表）。
|
||||
|
||||
常驻 hook 会优先暴露 `GRAPH_REPORT.md` —— 这是一页式总结，包含 god nodes、社区结构和意外连接。你的助手在搜索文件前会先读它，因此会按结构导航，而不是按关键字乱搜。这已经能覆盖大部分日常问题。
|
||||
**Claude Code** 上会做两件事：
|
||||
|
||||
`/graphify query`、`/graphify path` 和 `/graphify explain` 会更深入：它们会逐跳遍历底层 `graph.json`，追踪节点之间的精确路径，并展示边级别细节（关系类型、置信度、源位置）。当你想从图谱里精确回答某个问题，而不仅仅是获得整体感知时，就该用这些命令。
|
||||
1. 在 `CLAUDE.md` 中写入规则，告诉 Claude 在回答架构问题前先读 `graphify-out/GRAPH_REPORT.md`
|
||||
2. 安装 **PreToolUse hook**（写入 `settings.json`），在每次 `Glob` 和 `Grep` 前触发
|
||||
|
||||
可以这样理解：常驻 hook 是先给助手一张地图，`/graphify` 这几个命令则是让它沿着地图精确导航。
|
||||
> [!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>
|
||||
@@ -160,166 +184,114 @@ graphify trae-cn uninstall
|
||||
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 的“开发日志”，防止它忘记你之前的架构决策。
|
||||
## 核心结论
|
||||
|
||||
---
|
||||
> [!warning] Graphify ==不适合==索引 UE 引擎源码
|
||||
> 引擎数百万行 C++ + 海量宏（`UCLASS()`、`GENERATED_BODY()`），LLM 语义提取成本极高且不精确。
|
||||
>
|
||||
> **引擎源码 → [[GitNexus 知识图谱|GitNexus]]**（Tree-sitter AST，无 LLM 成本）
|
||||
|
||||
# 具体执行方案
|
||||
---
|
||||
**Graphify 的正确定位：项目业务层的宏观语义图谱。**
|
||||
|
||||
实现这一方案的关键在于将 `graphify` 从一个“傻瓜式扫描器”转变为一个“受控的提取引擎”。针对 Unreal Engine 的庞大规模，我们需要通过精确的路径控制和排除规则来实施。
|
||||
索引范围：
|
||||
- 项目 C++ 业务代码（`Source/`）
|
||||
- 设计文档和规范（`.trae/documents/`、`.trae/specs/`）
|
||||
- 策划案和架构说明（Markdown）
|
||||
- 排除所有编译产物、第三方插件、UE 配置/资产
|
||||
|
||||
以下是具体的执行方法与命令：
|
||||
### 1\. 离线构建 Engine 基础图谱 (The Static Atlas)
|
||||
## 实际配置（已验证 ✅）
|
||||
|
||||
由于引擎源码几乎不变量，我们只需构建一次。
|
||||
### 1. 创建 `.graphifyignore`
|
||||
|
||||
**执行策略：** 只索引 `Public` 接口，忽略所有实现（`.cpp` ）和私有目录。
|
||||
**具体命令：**
|
||||
```
|
||||
# 进入引擎 Source 目录
|
||||
cd /d D:/UnrealEngine/UE_5.7/Engine/Source
|
||||
> [!important] .graphifyignore 是唯一的排除机制
|
||||
> 排除规则通过 `.graphifyignore` 控制（==gitignore 语法==）。**不存在** `--include`、`--ignore`、`--output`、`index` 等 CLI 参数 —— 这些都是虚构的。
|
||||
|
||||
claude --dangerously-skip-permissions
|
||||
```gitignore
|
||||
# UE 编译产物
|
||||
Binaries/
|
||||
Intermediate/
|
||||
Saved/
|
||||
DerivedDataCache/
|
||||
Build/
|
||||
|
||||
# 执行 graphify 扫描
|
||||
# --include: 仅包含 Public 文件夹下的头文件，这是剪枝的核心
|
||||
# --ignore: 排除掉极其庞大的第三方库和中间件
|
||||
/graphify index . \
|
||||
--output D:/MatrixTA/AIGameDev/AIDM0/Docs/Graphify/UE5.7_Header.graph \
|
||||
--include "**/Public/**/*.h" \
|
||||
--ignore "ThirdParty/**,Developer/**,Programs/**,Intermediate/**,**/Private/**"
|
||||
# UE 配置和资产（非代码）
|
||||
Config/
|
||||
Content/
|
||||
|
||||
# 第三方插件
|
||||
Plugins/LogicDriver/
|
||||
Plugins/UnrealImGui/
|
||||
# ... 等
|
||||
|
||||
# AI 工具配置（非项目内容）
|
||||
.kilocode/
|
||||
.trae/skills/
|
||||
.trae/plans/
|
||||
.trae/.obsidian/
|
||||
```
|
||||
|
||||
**提示：** 这一步在 M1 Ultra 上可能仍需数十分钟。建议通过 `--max-depth` 限制继承链的抓取深度，通常设置为 5 已经能覆盖 90% 的关键基类（如 `UObject` -> `AActor` -> `APawn` -> `ACharacter` ）。
|
||||
### 2. 构建图谱
|
||||
|
||||
---
|
||||
|
||||
### 2\. ~~针对 UE 的“剪枝”策略配置文件~~
|
||||
|
||||
为了避免长命令，建议在项目根目录创建一个 `.graphifyconfig` (或工具支持的配置文件)。
|
||||
|
||||
**精细化剪枝逻辑：**
|
||||
|
||||
- **反射优先：** 重点提取带有 `GENERATED_BODY()` 的类。
|
||||
- **模块白名单：** 如果你主要做游戏逻辑，只包含以下核心模块：
|
||||
- `Runtime/Engine`
|
||||
- `Runtime/Core`
|
||||
- `Runtime/CoreUObject`
|
||||
- `Runtime/InputCore`
|
||||
|
||||
**自动化剪枝脚本示例 (Python)：** 如果你发现 `graphify` 无法过滤细碎路径，可以用这个脚本生成一个“干净”的临时符号链接目录供其索引：
|
||||
```python
|
||||
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\`.
|
||||
```
|
||||
|
||||
#### C++ & Puerts代码图谱
|
||||
```bash
|
||||
# 同时指定项目路径和外部引擎路径
|
||||
# TODO:添加Index Plugins
|
||||
/graphify index ./Source ./TypeScript \
|
||||
--output ./Docs/Graphify/Project/Project.graph \
|
||||
--include "*.cpp,*.h,*.hpp,*.ts" \
|
||||
--ignore "**/Intermediate/**,**/ThirdParty/**"
|
||||
/graphify . --directed --no-viz
|
||||
```
|
||||
|
||||
#### 增量更新模式（逻辑合并 - 推荐方案）
|
||||
这是最符合工程实践的方法。先建立基础图谱，再将其他目录的内容“追随”进去。`graphify` 的 `--update` 标志会自动处理节点冲突并合并新的关系。
|
||||
- `--directed`：构建有向图（保留 source → target 方向）
|
||||
- `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
|
||||
- 输出固定到 `graphify-out/`，**不存在** `--output` 参数
|
||||
|
||||
### 3. 安装常驻规则
|
||||
|
||||
**执行命令：**
|
||||
```bash
|
||||
# 第一步：索引引擎（静态基础）
|
||||
/graphify index /path/to/ue_engine/Source/Runtime \
|
||||
--output ./ue_workspace.graph \
|
||||
--include "**/Public/**/*.h"
|
||||
|
||||
# 第二步：将项目目录合并到同一个图谱中
|
||||
/graphify index ./MyProject/Source \
|
||||
--output ./ue_workspace.graph \
|
||||
--update # 关键参数：在现有图谱基础上合并
|
||||
graphify claude install
|
||||
```
|
||||
|
||||
在 `CLAUDE.md` 中写入规则 + 注册 PreToolUse hook，让 CC 优先用图谱导航而非盲搜 grep。
|
||||
|
||||
### 4. 增量更新
|
||||
|
||||
```bash
|
||||
/graphify . --update # 只重新提取变更文件，合并到已有图谱
|
||||
```
|
||||
|
||||
---
|
||||
## 双图谱架构（Graphify + GitNexus）
|
||||
|
||||
### 4\. 实施 Multi-Graph 挂载的 MCP 方案
|
||||
要让 ClaudeCode 真正理解这两个图谱，你需要一个简单的 MCP Server 来做中转。
|
||||
| 工具 | 索引目标 | 技术 |
|
||||
|------|----------|------|
|
||||
| **Graphify** | 项目业务层：设计文档、模块架构、策划案 | LLM 语义 + AST |
|
||||
| **GitNexus** | 项目 + 引擎符号层：C++ 类继承、函数调用链 | Tree-sitter AST |
|
||||
|
||||
**开发建议：**
|
||||
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。
|
||||
```bash
|
||||
cd D:\UnrealEngine\UE_5.7\Engine\Source
|
||||
npx gitnexus analyze --skip-agents-md --skip-skills
|
||||
```
|
||||
|
||||
这种“重引擎索引 + 轻业务监控”的模式，能保证在 64GB 内存的本地环境下，ClaudeCode 既能秒回 API 调用问题，又能深刻理解你的业务代码耦合。你想尝试编写这个 MCP 路由器的代码吗？
|
||||
> [!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
|
||||
#### 前置条件
|
||||
@@ -354,14 +326,14 @@ pip install watchdog
|
||||
# 当前目录
|
||||
/graphify . --directed --no-viz
|
||||
# 指定目录
|
||||
/graphify D:\AI\Website\CharacterMaker --directed --no-viz
|
||||
/graphify D:\AI\Website\CharacterMaker --directed --no-viz
|
||||
```
|
||||
|
||||
- `--directed`：构建有向图（保留边方向）
|
||||
- `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
|
||||
- 输出位置：`D:\AI\Website\CharacterMaker\graphify-out\`
|
||||
- **注意**：`--output` 不是有效 flag，graphify 固定输出到项目根目录的 `graphify-out/`
|
||||
- **注意**：`--ignore` 不是有效 flag，排除规则一律通过 `.graphifyignore` 文件控制
|
||||
|
||||
> [!warning] 常见误区
|
||||
> - `--output` ==不是有效 flag==，graphify 固定输出到项目根目录的 `graphify-out/`
|
||||
> - `--ignore` ==不是有效 flag==，排除规则一律通过 `.graphifyignore` 文件控制
|
||||
|
||||
#### watch 模式（文件变更时自动更新图谱）
|
||||
Claude Code 中运行（通过 skill 调度）：
|
||||
@@ -372,6 +344,4 @@ Claude Code 中运行（通过 skill 调度）：
|
||||
或直接在终端运行（无需 Claude Code）：
|
||||
```powershell
|
||||
python -m graphify.watch D:\AI\Website\CharacterMaker --debounce 3
|
||||
```
|
||||
|
||||
## GitNexus
|
||||
```
|
||||
Reference in New Issue
Block a user