BlueRoseNote/07-Other/AI/AI Agent/UnrealEngine/Graphify 知识图谱.md

title, date, tags, aliases

title	date	tags	aliases
Graphify 知识图谱	2026-05-28	ai-agent knowledge-graph graphify gitnexus ue5	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 包：

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 命令则 ==让助手沿着地图精确导航==。

手动安装（curl）

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.

用法

推荐使用：/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/
graphify 源码 + Transformer 论文	4	5.4x	worked/mixed-corpus/
httpx（合成 Python 库）	6	~1x	worked/httpx/

Token 压缩效果会随着语料规模增大而更明显。6 个文件本来就塞得进上下文窗口，所以 graphify 在这种场景里的价值更多是结构清晰度，而不是 token 压缩。到了 52 个文件（代码 + 论文 + 图片）这种规模，就能做到 71x+。每个 worked/ 目录里都带了原始输入和真实输出（GRAPH_REPORT.md、graph.json），你可以自己跑一遍核对数字。

针对UE开发的使用方式

核心结论

[!warning] Graphify ==不适合==索引 UE 引擎源码 引擎数百万行 C++ + 海量宏（UCLASS()、GENERATED_BODY()），LLM 语义提取成本极高且不精确。

引擎源码 → 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 参数 —— 这些都是虚构的。

# UE 编译产物
Binaries/
Intermediate/
Saved/
DerivedDataCache/
Build/

# UE 配置和资产（非代码）
Config/
Content/

# 第三方插件
Plugins/LogicDriver/
Plugins/UnrealImGui/
# ... 等

# AI 工具配置（非项目内容）
.kilocode/
.trae/skills/
.trae/plans/
.trae/.obsidian/

2. 构建图谱

/graphify . --directed --no-viz

• --directed：构建有向图（保留 source → target 方向）
• --no-viz：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
• 输出固定到 graphify-out/，不存在 --output 参数

3. 安装常驻规则

graphify claude install

在 CLAUDE.md 中写入规则 + 注册 PreToolUse hook，让 CC 优先用图谱导航而非盲搜 grep。

4. 增量更新

/graphify . --update    # 只重新提取变更文件，合并到已有图谱

双图谱架构（Graphify + GitNexus）

工具	索引目标	技术
Graphify	项目业务层：设计文档、模块架构、策划案	LLM 语义 + AST
GitNexus	项目 + 引擎符号层：C++ 类继承、函数调用链	Tree-sitter AST

引擎源码（一次性索引）

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 路由优先级

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 模式依赖）：

pip install watchdog

初始构建（首次或全量重建）

# 当前目录
/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）：

python -m graphify.watch D:\AI\Website\CharacterMaker --debounce 3