Graphify 的核心价值在于结构化压缩：它将散乱的代码、论文、截图和笔记转化为一张互联的图谱，使 AI 在回答架构问题时，Token 消耗可降低高达 71.5 倍，并提供可解释的推理路径。
核心亮点
1. 混合多模态图谱构建
- 代码层（确定性）：使用
tree-sitter进行本地 AST 解析，提取类、函数、导入、调用图及注释中的设计动机（Rationale）。代码内容不上传云端，确保隐私。 - 语义层（AI 驱动）：并行调用 Claude Vision/Text 模型处理 PDF、Markdown、截图和白板照片，提取概念、关系和设计意图。
- 融合：将确定的代码结构与推断的语义关系合并，形成统一的 NetworkX 图。
2. 基于拓扑的社区发现
- 无 Embedding 依赖：不使用向量数据库，而是基于图的边密度，利用 Leiden 算法 进行社区聚类。
- 语义即结构：AI 提取的语义相似边（
semantically_similar_to）直接参与聚类，使得功能相关但物理隔离的代码模块能被正确归类。
3. 可解释性与置信度
每条关系都带有明确的来源标记：
- EXTRACTED：直接在源码或文档中找到（置信度 1.0）。
- INFERRED：模型合理推断（附带 0.0-1.0 置信度分数）。
- AMBIGUOUS：存在歧需人工复核。
- God Nodes：识别出度最高的核心概念节点。
- 意外连接：发现代码与论文、或不同模块间非显而易见的强关联。
4. 极致 Token 效率
- 压缩比：对于混合语料（如 Karpathy 的仓库 + 论文 + 图片），查询时的 Token 消耗比直接读取原始文件减少 71.5 倍。
- 增量更新：基于 SHA256 缓存，仅重新处理变更过的文件。
- 持久化：生成的
graph.json可跨会话保存，无需每次重新解析。
安装与配置
注意：PyPI 包名为
graphifyy（因graphify被占用），但 CLI 命令仍为graphify。
1. 安装 Skill
pip install graphifyy && graphify install
根据你使用的平台，选择对应的安装命令：
| 平台 | 安装命令 | 备注 |
|---|---|---|
| Claude Code | graphify install | 支持 PreToolUse Hook |
| Codex | graphify install --platform codex | 需在 config.tom8 开启 multi_agent = true |
| OpenCode | graphify install --platform opencode | - |
| OpenClaw | graphify install --platform claw | 目前为顺序提取 |
2. 启用常驻模式（推荐）
让 AI 助手在每次回答前自动参考图谱，而非盲目 grep。
# Claude Code: 写入 CLAUDE.md 并安装 Hook
graphify claude install
# Codex / OpenCode / OpenClaw: 写入 AGENTS.md
graphify codex install
graphify opencode install
graphify claw install
- 效果：当图谱存在时，AI 会先阅读
graphify-out/GRAPH_REPORT.md，了解 God Nodes 和社区结构，从而进行结构化导航。
使用指南
基础用法
# 对当前目录构建图谱
/graphify .
# 对指定目录构建
/graphify ./docs
# 深度模式：更激进地抽取推断关系
/graphify ./raw --mode deep
# 增量更新：只处理变更文件
/graphify ./raw --update
高级查询
一旦图谱构建完成，你可以使用以下命令进行精确导航：
# 自然语言查询
/graphify query "what connects attention to the optimizer?"
# 追踪具体路径 (DFS)
/graphify query "what connects attention to the optimizer?" --dfs
# 限制 Token 预算
/graphify query "..." --budget 1500
# 查找两个节点间的路径
/graphify path "DigestAuth" "Response"
# 解释特定概念
/graphify explain "SwinTransformer"
添加外部资源
Graphify 支持将外部链接纳入图谱：
# 添加 Arxiv 论文
/graphify add https://arxiv.org/abs/1706.03762
# 添加推文或网页
/graphify add https://x.com/karpathy/status/... --author "Andrej Karpathy"
自动化同步
- Watch 模式：
/graphify ./raw --watch后台监听文件变化，代码变动即时更新 AST，文档变动提示 LLM 更新。 - Git Hooks：
graphify hook install在post-commit和post-checkout时自动重建图谱。
输出产物
运行后会在 graphify-out/ 目录生成：
graph.html：可交互的可视化图谱，支持搜索、过滤和高亮。GRAPH_REPORT.md：人类可读审计报告，包含 God Nodes、意外连接和建议提问。graph.json：持久化的图谱数据，供 AI 后续查询。cache/：SHA256 缓存文件。- (可选)
wiki/：为每个社区生成的 Markdown 维基百科式文档。 - (可选)
graph.svg/graph.graphml：用于 Gephi 或 yEd 的标准格式。
隐私与安全
- 代码本地处理：所有代码文件的 AST 解析均在本地通过
tree-sitter完成，源代码不会发送给任何 API。 - 语义提取上云：仅文档、PDF 和图片的内容会被发送至你所配置的平台 API（如 Anthropic, OpenAI）进行语义提取。
- 无遥测：Graphify 本身不收集任何使用数据或遥测信息。
典型应用场景
- 遗留代码重构：快速识别核心模块（God Nodes）和隐藏的耦合关系。
- 新入职上手：通过图谱而非逐行阅读，快速建立对项目架构的心智模型。
- 学术研究辅助：将代码实现与相关论文、笔记关联，追溯算法的理论源头。
- AI 辅助开发：大幅降低 AI 理解大型项目的 Token 成本，提高回答的准确性和结构性。
