技能介绍

在 AI 编程助手里输入 /graphify，它会把整个项目（代码、文档、SQL Schema、配置、PDF、图片、视频）映射成一张知识图谱，让你用查询代替翻文件。

  • 代码建图免费、完全本地。 代码用 tree-sitter AST 解析：确定性、不用 LLM、数据不出你的机器。（文档、PDF、图片、视频使用你助手的模型，或配置的 API key，做一次语义抽取。）
  • 每条边都有解释。 每个连接都标注 EXTRACTED（源码中显式存在）或 INFERRED（由 graphify 解析推断），可以区分直接读到的与推断出来的。
  • 不是向量索引。 没有 embedding、没有向量库：是一张真正可遍历的图。提问、追溯两个事物之间的路径、或解释某个概念都可以。

官方 PyPI 包名是 graphifyy（双 y），CLI 命令仍是 graphify；官方源仓库为 https://github.com/Graphify-Labs/graphify 。一次安装适配 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 20+ 助手平台，覆盖 macOS、Linux、Windows。

适用场景

  • 不想 grep 或通读文件，想直接提问、追溯两个概念之间的连接路径、或解释某个概念。
  • 快速了解一个陌生代码库：GRAPH_REPORT.md 给出关键概念、意外连接与建议问题。
  • 团队把图谱提交共享，让所有人查询同一份上下文，并带图谱上下文做 PR 评审。
  • 把论文、PDF、视频等资料加进同一张图一并查询（/graphify add）。

核心能力

↔ 左右滑动查看完整表格
能力说明
枢纽节点（God nodes）连接最多的关键概念，看清所有东西流经哪里
社区（Communities）图谱拆分成子系统（Leiden 算法），生成不依赖 LLM 的标签
跨文件连接calls / imports / inherits / mixes_in，经 tree-sitter AST 跨约 40 种语言解析
查询 / 路径 / 解释提问、追溯两物之间的路径、解释单个概念，全部针对 graph.json
理由与文档引用# NOTE: / # WHY: 注释与 ADR/RFC 引用成为一等节点并与代码相连
超越代码文档、PDF、图片、音视频都映射进同一张图
本地优先代码本地解析（无 LLM、不出本机）；仅文档/媒体的语义抽取在配置后端后才调用

官方基准（所有系统同一测试框架、同一模型与预算，评分器经第二评分器盲验，一致率 90.6%）：LOCOMO（n=300）recall@10 0.497、LongMemEval-S（n=50）QA 准确率 76%（与稠密 RAG 持平）、建图 LLM 额度消耗 0。

效果预览

graphify 为 FastAPI 代码库生成的图谱：每个节点是一个概念，颜色是检测出的社区，整张图可在 graph.html 里点击交互。

图谱建好后直接查询而不是读文件。以下是在上面这个 FastAPI 代码库上运行 graphify 的真实输出：

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

每条边都带置信标记（EXTRACTED = 源码显式存在，INFERRED = 解析推断得出）。graphify query "" 针对一个自然语言问题返回限定范围的子图，graphify path A B 追溯任意两个事物如何相连。

工作方式

一次运行产出三个文件：

graphify-out/
├── graph.html       open in any browser: click nodes, filter, search
├── GRAPH_REPORT.md  the highlights: key concepts, surprising connections, suggested questions
└── graph.json       the full graph: query it anytime without re-reading your files
  • 持久化的图包含 graph.schema_version（供集成方检测不兼容的格式变更）与 graph.graphify_version（产出该图的 Graphify 版本）。
  • 代码经 tree-sitter AST 本地确定性抽取，社区划分用 Leiden 算法，每条边带 EXTRACTED/INFERRED 置信标记。
  • 隐私：代码文件全部本地处理，不出机器；纯代码语料无需 API key，graphify extract 完全离线；混合仓库可加 --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片。音视频用 faster-whisper 本地转写。无遥测、无使用追踪、无统计分析。
  • 忽略规则遵循 .gitignore，并支持 --exclude 与项目级 .graphifyignore；项目配置写 .graphifyrc（一行一个 key=value，# 开头是注释，可声明 .inc/.h/.m 等模糊扩展名对应的语言）。
  • 常驻使用：在项目里运行一次 graphify install（如 graphify claude install），写入小配置让助手回答代码库问题时优先查图。Hook 平台（Claude Code、Gemini CLI）会在搜索类工具调用前自动引导查图；指令文件平台（Codex、OpenCode、Cursor 等）通过 AGENTS.md、.cursor/rules/ 等持久指令实现同样的「先查图」策略。卸载用 graphify uninstall（加 --purge 连 graphify-out/ 一起删）。
  • 查询日志：每次 graphify query / path / explain 与 MCP query_graph 调用会以 JSON Lines 记到 ~/.cache/graphify-queries.log（时间戳、问题、语料、返回节点数、耗时），默认不存完整子图；设 GRAPHIFY_QUERY_LOG_DISABLE=1 可关闭。

你需要提供

  • Python 3.10+，以及 uv（推荐）或 pipx。
  • 一个要建图的项目目录。
  • 只建代码图不需要任何 API key；若要对文档、PDF、图片做语义抽取，无头运行 graphify extract 需要任一后端：GEMINI_API_KEY / MOONSHOT_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY、Ollama（OLLAMA_BASE_URL）、AWS Bedrock（走 IAM，无需 key）或 claude CLI；也可以直接用 /graphify 技能走 IDE 会话里的助手模型。按设置的 key 自动选后端（优先级 Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama），并打印选中后端所依据的环境变量。

你会获得

  • 三个文件：graph.html（浏览器交互图谱：点击节点、过滤、搜索）、GRAPH_REPORT.md（重点摘要：关键概念、意外连接、建议问题）、graph.json（完整图谱，之后随时查询、不必重读文件）。
  • 三个查询命令：graphify query ""（自然语言问限定子图）、graphify path A B（追溯路径）、graphify explain （解释单个概念）。名称匹配到多个节点时列出候选而不是乱猜；退出码 0 有答案、3 名称歧义、4 无匹配节点。
  • 额外产出：graphify export callflow-html（Mermaid 架构/调用流 HTML，装了 hook 会在每次 git commit 后自动重新生成）、/graphify . --wiki（从图谱生成 Markdown wiki）、graphify merge-graphs a.json b.json（合并多张图）、graphify prs（PR 仪表盘：CI 状态、评审状态、worktree 映射）。

使用示例

安装（30 秒开始，需要 Python 3.10+ 与 uv 或 pipx）：

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # detects your assistant and registers the skill

然后在 AI 助手里：

/graphify .

常用命令（Codex 用户用 $graphify 代替 /graphify）：

/graphify .                        # build graph for current folder
/graphify ./docs --update          # re-extract only changed files
/graphify . --cluster-only         # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5      # more granular communities
/graphify . --cluster-only --exclude-hubs 99     # suppress utility super-hubs from god-node rankings
/graphify . --no-viz               # skip the HTML, just the report + JSON
/graphify . --wiki                 # build a markdown wiki from the graph
graphify export callflow-html      # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)

/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # fetch a paper and add it
/graphify add <youtube-url>                       # transcribe and add a video

graphify hook install              # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below)
graphify merge-graphs a.json b.json              # combine two graphs

graphify prs                       # PR dashboard: CI state, review status, worktree mapping
graphify prs 42                    # deep dive on PR #42 with graph impact
graphify prs --triage              # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts           # PRs sharing graph communities: merge-order risk

可选扩展按需安装（如 uv tool install "graphifyy[pdf]"）：pdf（PDF 抽取）、office（.docx/.xlsx）、video（音视频转写）、mcp（MCP stdio server）、sql（SQL schema 抽取）、neo4j/falkordb（图数据库推送）、ollama/openai/anthropic 等（LLM 后端）、chinese（中文查询分词），全部装 graphifyy[all]。