graphify 的工作原理¶

三遍处理¶

graphify 分三遍处理你的文件：

第 1 遍 — 代码结构（免费，无 API 调用） Tree-sitter 解析你的代码文件，提取类、函数、导入、调用图和行内注释。这一切在本地运行，不涉及 LLM。支持 25 种语言。SQL 文件会得到特殊处理：表、视图、外键和 JOIN 关系会被确定性地提取出来。

在常规流水线中，代码文件不会发送给 LLM 语义提取器。如果语料库只包含代码文件，则完全跳过第 3 遍；语义提取仅保留给文档、论文、图片和转录文本。

第 2 遍 — 视频和音频（本地，无 API 调用） 视频和音频文件使用 faster-whisper 转写。为了让转写内容聚焦于你的领域，转录 Prompt 会以你的顶级 god 节点（目前代码图中连接最密集的概念）作为种子。转写结果会被缓存——重新运行时跳过已处理的文件。

第 3 遍 — 文档、论文、图片（Claude 子代理，消耗 Token） Claude 并行处理 Markdown、PDF、图片和转录文本。每个子代理读取一批文件，并输出一个 JSON 片段：节点、边以及任何分组关系。这些片段会被合并成单个图。

在第 3 遍之前，可选的转换器会将受支持的指针/二进制格式转换为 graphify-out/converted/ 下的 Markdown sidecar 文件。Office 文件（.docx、.xlsx）使用 [office] 额外依赖。Google Workspace 快捷方式（.gdoc、.gsheet、.gslides）通过 --google-workspace 或 GRAPHIFY_GOOGLE_WORKSPACE=1 选择启用，并且需要已认证的 gws CLI。

社区检测的工作原理¶

社区通过 Leiden 算法 发现——这是一种按边密度对节点进行分组的图聚类方法。彼此之间连接很多的节点最终会落在同一个社区中。

无需 embedding。 Claude 提取的语义相似度边（semantically_similar_to）已经存在于图中，因此它们会直接影响社区形态。图结构本身就是相似性信号——不需要额外的 embedding 步骤，也不需要向量数据库。

置信度标记¶

每个关系都会被打上以下三种标签之一：

EXTRACTED 边的置信度始终为 1.0。INFERRED 边使用离散评分标准： - 0.95 — 几乎确定（明确的跨文件引用，且只有一个合理目标） - 0.85 — 强证据（命名和上下文对齐） - 0.75 — 合理（有上下文线索但不明确） - 0.65 — 较弱（仅命名相似） - 0.55 — 推测性

Token 基准测试¶

首次运行会提取并构建图——这会消耗 Token。之后的每次查询都会读取紧凑的图，而不是原始文件。节省就在这里不断累积。

在一个混合语料库（Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件）上：与直接读取原始文件相比，每次查询的 Token 消耗减少 71.5 倍。

Token 减少幅度随语料库规模扩大而增长。六个文件已经能放进上下文窗口——此时图的价值在于结构清晰，而不是压缩。到了 52 个文件时，节省效果会快速累积。

仓库中每个 worked/ 文件夹都包含原始输入文件和实际输出（GRAPH_REPORT.md、graph.json），你可以自行运行并验证。

并行提取¶

代码文件通过 ProcessPoolExecutor 并行提取——绕过 Python 的 GIL，实现真正的多进程处理。文档/论文/图片批次作为并行 Claude 子代理分发。在一个包含 84 个代码文件的语料库上，并行 AST 提取比串行快约 1.66 倍。

SHA256 缓存¶

每个被提取的文件都会通过内容哈希生成指纹。重新运行时，未变化的文件会被完全跳过——只有新增或修改过的文件才会再次执行提取。缓存位于 graphify-out/cache/。

图格式¶

输出的 graph.json 使用 NetworkX 的 node-link 格式。每个节点包含： - id — 稳定标识符 - label — 人类可读的名称 - file_type — code、document、paper、image、rationale - source_file — 来源文件

关于为 AI 导航添加紧凑可选摘要的两种提议方案，请参阅 RFC：文件级节点摘要。

每条边包含： - source、target — 节点 ID - relation — 动词短语（例如 calls、imports、implements、semantically_similar_to） - confidence — EXTRACTED、INFERRED 或 AMBIGUOUS - confidence_score — 浮点数（仅 INFERRED） - source_file — 发现该关系的文件

超边（连接 3 个以上节点的分组关系）位于 G.graph["hyperedges"] 中。