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（源码中明确存在）vsINFERRED（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💡 个人启发
"图"比"向量"更可解释：大多数 RAG 工具用 embedding + 向量检索，graphify 选择了真实图结构，每条边都有标注（EXTRACTED/INFERRED），这种可解释性在大型代码库的 Debug 和架构梳理场景中非常有价值。
本地优先是工程实践的正确取向：代码解析完全离线（tree-sitter），只有文档/媒体的语义分析才可选地调用 API，这对企业级用户或涉密项目极为友好，也降低了使用门槛。
技能化而非独立工具：graphify 不做成独立 IDE，而是以"技能插件"形式嵌入 Claude Code、Cursor 等开发者已有的工具链，降低切换成本，这是一种值得借鉴的产品策略。
图查询 vs grep：
graphify path A B直接告诉你两个模块如何关联，这比反复 grep 文件、靠人脑串联上下文要高效得多，尤其适合接手陌生大型项目时快速定位。
🔭 延伸思考
知识图谱的"时效性"问题如何解决？
代码库持续演进，graph.json会快速过期。graphify 是否支持增量更新（只重新解析变更文件）？还是每次都需要全量重建？这直接影响其在 CI/CD 流水线中的实用性。INFERRED 边的准确性边界在哪里？
tree-sitter 解析的EXTRACTED边是确定性的，但INFERRED边依赖语义推断。在多态调用、动态语言（Python/JS）运行时绑定等场景下，误推断率有多高？是否会产生"幻觉连接"误导开发者？知识图谱能否成为 AI 编程助手的"长期记忆"基础设施？
当前 AI 助手的上下文窗口有限，graphify 的graph.json本质上是一种外部记忆。未来是否可以将图谱与 Agent 的规划模块深度结合，让 AI 在多步骤任务中自主遍历图谱、动态补充上下文，而非依赖人工/graphify触发？