Files

BlueRose 25d42f8074 vault backup: 2026-04-15 11:56:39

2026-04-15 11:56:39 +08:00

17 KiB

Raw Blame History

前言

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 会做两件事：

在 CLAUDE.md 中写入一段规则，告诉 Claude 在回答架构问题前先读 graphify-out/GRAPH_REPORT.md
安装一个 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 这几个命令则是让它沿着地图精确导航。

手动安装（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                          # 对当前目录运行
/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开发的使用方式

具体的实施路线图

安装 Graphify 并配置 ClaudeCode 技能： 在你的项目根目录运行：

graphify install  # 自动向 CLAUDE.md 注入架构索引规则
/graphify .      # 生成初始代码图

编写 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).

开发 MCP 插件： 如果你有能力，实现一个简单的 MCP Server，能够通过命令行搜索 UE 的 Reflection Database。

总结建议

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

具体执行方案

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

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

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

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

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

# 进入引擎 Source 目录
cd /d D:/UnrealEngine/UE_5.7/Engine/Source

claude --dangerously-skip-permissions

# 执行 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/**"

提示： 这一步在 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\`.

C++ & Puerts代码图谱

# 同时指定项目路径和外部引擎路径
# TODO:添加Index Plugins
/graphify index ./Source ./TypeScript \
  --output ./Docs/Graphify/Project/Project.graph \
  --include "*.cpp,*.h,*.hpp,*.ts" \
  --ignore "**/Intermediate/**,**/ThirdParty/**"

增量更新模式（逻辑合并 - 推荐方案）

这是最符合工程实践的方法。先建立基础图谱，再将其他目录的内容“追随”进去。graphify 的 --update 标志会自动处理节点冲突并合并新的关系。

执行命令：

# 第一步：索引引擎（静态基础）
/graphify index /path/to/ue_engine/Source/Runtime \
  --output ./ue_workspace.graph \
  --include "**/Public/**/*.h"

# 第二步：将项目目录合并到同一个图谱中
/graphify index ./MyProject/Source \
  --output ./ue_workspace.graph \
  --update  # 关键参数：在现有图谱基础上合并

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

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

开发建议：

加载： 启动时同时 Load 两个 .graph 文件到内存。

查询逻辑：

async function searchClass(className) {
  // 1. 先查项目图谱
  let result = projectGraph.find(className);
  if (!result) {
    // 2. 如果没找到，且符合 UE 命名规范，查引擎图谱
    result = engineGraph.find(className);
  }
  return result;
}

总结执行清单：

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

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

17 KiB Raw Blame History Unescape Escape

前言

安装