Graphify 技能

Graphify 将包含代码、文档、图片和视频的文件夹转化为一个可查询的知识图谱。执行 graphify . 后，生成的 GRAPH_REPORT.md 文件会在你要求助手探索代码库时被自动引用。利用它，你可以快速导航陌生的代码库、追溯架构设计意图，并高效共享上下文信息。

凭证说明：语义提取（文档、PDF、图片）需调用外部 LLM，使用你自己的 API 密钥（ANTHROPIC_API_KEY 或 OPENAI_API_KEY）。AST 代码解析与 Whisper 音视频转录则完全在本地运行，无需任何 API 密钥。

Token 效率：读取 GRAPH_REPORT.md 的开销约为读取原始源文件的 1/71.5。请务必优先查阅该报告。

安装

最小化安装

pip install graphify

推荐安装（含全部扩展功能）

pip install "graphify[pdf,video,watch,svg]"

注册至 OpenClaw

graphify claw install

该命令将技能复制到 OpenClaw 的全局技能目录，并在项目根目录下生成 AGENTS.md 文件，确保每次工具调用时均会参考该知识图谱。

注册至其他平台

graphify claude install     # Claude Code（生成 CLAUDE.md + PreToolUse 钩子）
graphify cursor install     # Cursor（生成 .cursorrules）
graphify codex install      # Codex（生成 AGENTS.md）
graphify copilot install    # GitHub Copilot CLI
graphify gemini install     # Gemini CLI
graphify aider install      # Aider

Git post-commit 钩子（可选，仅限当前项目）

在当前项目的 .git/hooks/ 目录中安装钩子 —— 不影响全局配置。

graphify hook install

构建知识图谱

首次运行

graphify .

Graphify 执行一个三阶段流水线：

1. AST 提取 — 使用 tree-sitter 对所有代码文件进行确定性语法树解析（不调用 LLM）
2. 转录 — 在本地运行 Whisper 处理音视频文件
3. 语义提取 — 并行调用 LLM（使用你配置的 API 密钥），分析文档、论文与图片

增量更新（仅处理变更文件）

graphify . --update

使用位于 graphify-out/cache/ 中的 SHA-256 缓存 —— 可安全地在每次保存后运行。

监听模式（文件变更时自动同步）

graphify . --watch

深度模式（激进的推断边提取）

graphify . --mode deep

添加带置信度评分（0.0–1.0）的 INFERRED 边，以及标记为待人工审查的 AMBIGUOUS 边。

保留边的方向性

graphify . --directed

仅重新聚类（跳过内容重提取）

graphify . --cluster-only

跳过 HTML 可视化（加速 CI 构建）

graphify . --no-viz

输出产物

所有产物均存放于 graphify-out/ 目录中：

其他导出格式

graphify . --svg        # SVG 可视化
graphify . --graphml    # 兼容 Gephi / yEd 的导出格式
graphify . --wiki       # 每个节点生成维基风格文章

查询图谱

# 自然语言语义搜索
graphify query "认证逻辑实现在何处？"

# 追踪特定路径（DFS 遍历）
graphify query "请求如何到达数据库？" --dfs

# 两节点间最短路径
graphify path "AuthMiddleware" "PostgresAdapter"

# 以自然语言解释某节点
graphify explain "UserSessionManager"

添加外部内容

graphify add      # 获取并索引一篇研究论文
graphify add      # 获取并索引一条推文
graphify add      # 下载并转录音视频

添加完成后，运行 graphify . --update 将新节点整合进图谱。

忽略文件

在项目根目录创建 .graphifyignore 文件（语法同 .gitignore）：

node_modules/
dist/
build/
.next/
vendor/
*.generated.*
*.min.js
*.lock
graphify-out/cache/

完整示例可参见本技能中的 templates/graphifyignore.txt。

关系类型

使用 --mode deep 可最大化 INFERRED 关系覆盖率；当精度至关重要时，请过滤掉 AMBIGUOUS 关系。

OpenClaw / Claude Code 最佳实践

1. 探索前务必先阅读报告

Read graphify-out/GRAPH_REPORT.md

该报告识别出“上帝节点”（度数最高的概念）、社区聚类及建议的切入点问题。请据此聚焦后续搜索范围。

2. 将社区映射至功能模块

报告中每个社区对应代码库的一个功能区域。修复缺陷或新增功能时，请先识别相关社区，再将文件读取范围限定于该聚类内。

3. 查询前优先使用 graphify query 而非 grep

对于开放式问题（如“X 功能实现在何处？”），应优先使用 graphify query —— 它在语义图谱中搜索，返回的是排序后的节点路径，而非原始文本匹配结果。

4. 使用 graphify path 进行影响分析

编辑某个节点前，运行 graphify path "NodeA" "NodeB" 查找耦合链路，评估变更影响范围（blast radius）。

5. 积极使用 --update

每次重要修改后，均应运行 graphify . --update 以保持图谱时效性。得益于缓存机制，该操作开销极低。

6. 团队协作流程

• 提交 graphify-out/ 目录（排除 graphify-out/cache/），使团队成员检出代码后即可立即获得图谱上下文。
• 由一名成员构建初始图谱；其余成员均可零成本复用。
• 安装 graphify hook install 实现每次提交后自动重建图谱。

7. 多模态上下文

在运行 graphify . 前，将架构图、白板照片或设计原型图放入项目目录中。Claude Vision 将自动建立视觉概念与代码节点之间的关联。

支持的语言

Python、JavaScript、TypeScript、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、SystemVerilog、Vue、Svelte、Dart

此外还支持：Markdown、MDX、HTML、纯文本、RST、PDF、PNG/JPG/WebP/GIF 图片、MP4/MOV/MKV/WebM/MP3/WAV/M4A/OGG 媒体文件。

故障排查