Graphify：将代码库变成可查询知识图谱的 AI 编程助手技能

---

🧠 核心观点

Graphify 是一个可集成到 AI 编程助手（如 Claude Code、Cursor、Codex、Gemini CLI 等）中的技能插件，核心思路是：将代码库（乃至文档、PDF、图片、视频）解析为知识图谱，用"图查询"替代"文件搜索"，从而让 AI 助手能真正"理解"整个项目的结构与关联。

一句话总结：/graphify . → 你的项目变成一张可点击、可查询、可追踪的知识图谱。

---

📌 关键信息

1. 是什么？

特性	说明
类型	AI 编程助手技能（Skill/Plugin）
核心技术	tree-sitter AST 解析 + 图结构（非向量索引）
支持平台	Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 20+ 工具
支持内容	代码、SQL Schema、R 脚本、Shell 脚本、文档、PDF、图片、视频
隐私保障	代码解析完全本地（tree-sitter），不调用 LLM，不上传数据

---

2. 核心能力一览

能力	说明
God Nodes（核心节点）	找出连接最多的概念，看清整个项目的"枢纽"
社区划分（Communities）	用 Leiden 算法自动划分子系统，无需 LLM
跨文件链接	解析 calls / imports / inherits / mixes_in，支持约 40 种语言
查询 / 路径 / 解释	自然语言提问、追踪两个概念之间的路径、解释某个节点
注释与设计文档节点化	# NOTE: / # WHY: 注释以及 ADR/RFC 引用成为图中的一等节点
边的置信标签	EXTRACTED（源码中明确存在）vs INFERRED（graphify 推断得出）
本地优先	代码解析零 LLM 调用；文档/媒体的语义处理才调用后端（可选配置）

---

3. 输出产物（三个文件）

graphify-out/
├── graph.html        # 浏览器可打开，支持点击节点、过滤、搜索
├── GRAPH_REPORT.md   # 关键概念、异常连接、建议提问列表
└── graph.json        # 完整图数据，随时可查询，无需重新解析

---

4. 性能基准（Benchmarks）

测试集	指标	graphify	对比系统
LOCOMO (n=300)	recall@10	0.497	mem0: 0.048，supermemory: 0.149
LOCOMO (n=300)	QA 准确率	45.3%	supermemory: 49.7%，mem0: 27.3%
LongMemEval-S (n=50)	QA 准确率	76%	与密集 RAG 持平
图构建	LLM 调用费用	0	大多数系统按 token 收费

评测采用盲验证，两位评审一致性 90.6%，Cohen's kappa = 0.81，可信度较高。

---

💻 代码 / 示例

快速上手（30 秒）

# 1. 安装 CLI（注意 PyPI 包名是 graphifyy，双 y）
uv tool install graphifyy
# 或：pipx install graphifyy

# 2. 注册到 AI 助手
graphify install

# 3. 在 AI 助手中运行（PowerShell 用 graphify . 不要加斜杠）
/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]
#   DefaultPlaceholder
#   ModelField ...

# 自然语言查询（返回子图）
graphify query "如何处理请求验证错误？"

# 追踪两个概念之间的路径
graphify path APIRouter ModelField

平台指定安装

# 安装到当前项目（而非用户全局）
graphify install --project

# 指定特定平台
graphify install --platform cursor
graphify install --platform gemini
graphify install --platform codex

# 项目级 + 平台指定
graphify claude install --project
graphify codex install --project

系统要求

# macOS (Homebrew)
brew install python@3.12 uv

# Windows
winget install astral-sh.uv

# Ubuntu/Debian
sudo apt install python3.12 python3-pip pipx
# 或安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

---

💡 个人启发

1. "图"比"向量"更可解释：大多数 RAG 工具用 embedding + 向量检索，graphify 选择了真实图结构，每条边都有标注（EXTRACTED/INFERRED），这种可解释性在大型代码库的 Debug 和架构梳理场景中非常有价值。

2. 本地优先是工程实践的正确取向：代码解析完全离线（tree-sitter），只有文档/媒体的语义分析才可选地调用 API，这对企业级用户或涉密项目极为友好，也降低了使用门槛。

3. 技能化而非独立工具：graphify 不做成独立 IDE，而是以"技能插件"形式嵌入 Claude Code、Cursor 等开发者已有的工具链，降低切换成本，这是一种值得借鉴的产品策略。

4. 图查询 vs grep：graphify path A B 直接告诉你两个模块如何关联，这比反复 grep 文件、靠人脑串联上下文要高效得多，尤其适合接手陌生大型项目时快速定位。

---

🔭 延伸思考

1. 知识图谱的"时效性"问题如何解决？
   代码库持续演进，graph.json 会快速过期。graphify 是否支持增量更新（只重新解析变更文件）？还是每次都需要全量重建？这直接影响其在 CI/CD 流水线中的实用性。

2. INFERRED 边的准确性边界在哪里？
   tree-sitter 解析的 EXTRACTED 边是确定性的，但 INFERRED 边依赖语义推断。在多态调用、动态语言（Python/JS）运行时绑定等场景下，误推断率有多高？是否会产生"幻觉连接"误导开发者？

3. 知识图谱能否成为 AI 编程助手的"长期记忆"基础设施？
   当前 AI 助手的上下文窗口有限，graphify 的 graph.json 本质上是一种外部记忆。未来是否可以将图谱与 Agent 的规划模块深度结合，让 AI 在多步骤任务中自主遍历图谱、动态补充上下文，而非依赖人工 /graphify 触发？