graphify 技术解析：把任意代码库与文档变成可查询的知识图谱

graphify 是一个 AI 编码助手技能（Skill）：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro、Google Antigravity 等助手中输入 /graphify，它会读取你的文件、构建一张知识图谱，并把代码库中你自己都未必察觉的结构关系交还给你。本篇基于仓库中的 印地语版 README（与 英文 README 同源）展开，并结合 docs/how-it-works.md 与核心源码，讲清 graphify 的三阶段流水线、置信度标记体系、输出产物、安装与全部常用命令，读完即可在自己的仓库上完整落地并验证每一步行为。

为什么需要知识图谱而不是向量检索

graphify 的定位可以用三句话概括：

• 完全多模态。代码、PDF、Markdown、截图、图表、白板照片、其他语言中的图片，乃至音视频文件，graphify 都能从中抽取概念与关系，并统一接入同一张图。视频通过 faster-whisper 在本地转写。代码侧通过 tree-sitter AST 支持 25 种编程语言（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、SystemVerilog、Vue、Svelte、Dart）。
• 图拓扑驱动聚类，而非向量嵌入。Claude 抽取的语义相似边（semantically_similar_to）本来就在图里，因此社区发现算法（Leiden）直接被图结构影响，不需要单独的 embedding 步骤或向量数据库。
• 每条边都可解释。每个关系都带有 EXTRACTED、INFERRED 或 AMBIGUOUS 标签，你能始终分清"直接读到的"和"推断出来的"。

仓库中 worked/ 目录保留了真实语料的输入与完整输出（GRAPH_REPORT.md、graph.json、review.md），例如 worked/httpx/GRAPH_REPORT.md，可用于对照本文描述自行复现验证。

三阶段流水线：从文件到可查询图

graphify 按三个阶段处理文件，这与 docs/how-it-works.md 中的描述一一对应，也是 docs/translations/README.hi-IN.md 中"यह कैसे काम करता है"一节的主体：

Pass 1 — 代码结构（本地、确定性、不调用任何 LLM）。tree-sitter 解析代码文件，抽取类、函数、导入、调用图与行内注释，全程本地完成。纯代码语料会完全跳过 Pass 3，语义抽取只保留给文档、论文、图片与转写文本。这一阶段由 graphify/extractors/ 下的各语言抽取器实现（engine.py、go.py、rust.py、sql.py 等），SQL 文件还得到特殊处理：表、视图、外键与 JOIN 关系被确定性地抽取出来。

Pass 2 — 音视频（本地、不调用 API）。视频与音频由 faster-whisper 本地转写。转写提示词会用你代码图中度最高的"god nodes"做领域种子，使转写文本聚焦于你的项目语境；转写结果带缓存，重跑时跳过已处理文件。

Pass 3 — 文档、论文、图片（LLM 子代理并行、消耗 tokens）。Claude 子代理在 Markdown、PDF、图片与转写文本上并行运行，每个子代理读取一批文件并输出 JSON 片段（节点、边、组关系），片段被合并进一张 NetworkX 图。合并后执行 Leiden 社区发现做聚类，最终导出为交互式 HTML、可查询 JSON 与审计报告。

聚类这一步在 graphify/cluster.py 中实现：优先调用 graspologic 的 Leiden（其中 graphify/cluster.py 的 _native_leiden 还会绕过 graspologic 包导入，直连其 Rust 原生扩展以避免约 7–19 秒的一次性导入开销），未安装时回退到 networkx 内置的 Louvain；resolution > 1.0 得到更多更小的社区，< 1.0 则得到更少更大的社区——这正是 /graphify --cluster-only --resolution 1.5 这类命令的底层机制。

增量处理由 SHA256 内容哈希缓存支撑：每个被抽取的文件都按内容指纹记录，重跑时完全跳过未变更文件，只有新增或修改的文件重新走抽取。实现见 graphify/cache.py，缓存落在 graphify-out/cache/。从源码结构看，AST 缓存条目还会按包版本与缓存键 schema 做命名空间隔离（cache/ast/v{version}-s{schema}/），而语义缓存刻意不做版本化以避免每次发版重复计费——这是文档"SHA256 कैश"一节的源码级解释。

输出产物 graphify-out/

执行 /graphify . 后得到如下目录（与原文档一致）：

graphify-out/
├── graph.html       # 交互式图谱 —— 在任意浏览器打开，点击节点、搜索
├── GRAPH_REPORT.md  # god nodes、意外连接、建议问题
├── graph.json       # 持久化图谱 —— 数周后仍可直接查询
└── cache/           # SHA256 缓存 —— 重跑时只处理变更过的文件

• graph.html 可在任意浏览器中打开，支持点击节点、过滤与搜索；
• GRAPH_REPORT.md 是"高亮点"报告（见下文"报告里有什么"）；
• graph.json 采用 NetworkX node-link 格式，每个节点含 id、label、file_type（code/document/paper/image/rationale）、source_file；每条边含 source、target、relation（calls、imports、implements、semantically_similar_to 等动词短语）、confidence 标签与 confidence_score（仅 INFERRED 边）；
• 3 个及以上节点的组关系（超边）存放在 G.graph["hyperedges"] 中。

报告生成逻辑可见 graphify/report.py，god nodes 即按边数（degree）排序输出。

忽略规则：.graphifyignore

用 .graphifyignore 文件排除不需要的目录，语法与 .gitignore 相同（含 ! 取反）：

# .graphifyignore
vendor/
node_modules/
dist/
*.generated.py

从源码结构看，该文件的匹配逻辑分布在 graphify/detect.py 与 graphify/extract.py 中；英文 README 进一步说明 .gitignore 会被自动读取，两者同时存在时合并生效且 .graphifyignore 后评估（冲突时胜出），子目录作用域与 git 一致。

安装

前提：Python 3.10+（见 pyproject.toml 中 requires-python = ">=3.10"），以及上述任意一个 AI 编码助手。

# 推荐 —— Mac 与 Linux 上无需配置 PATH 即可工作
uv tool install graphifyy && graphify install
# 或用 pipx
pipx install graphifyy && graphify install
# 或用普通 pip
pip install graphifyy && graphify install

官方包名提示：PyPI 包名是 graphifyy（双写 y，与 pyproject.toml 中 name = "graphifyy" 一致），PyPI 上其他 graphify* 命名的包与本项目无关。CLI 命令始终叫 graphify（入口定义见 pyproject.toml 的 [project.scripts]：graphify = "graphify.__main__:main"，另有一个 graphify-mcp 入口指向 graphify/serve.py）。

平台支持

原文档给出完整的平台安装命令表，完整继承如下：

平台	安装命令
Claude Code (Linux/Mac)	graphify install
Claude Code (Windows)	graphify install（自动识别）或 graphify install --platform windows
Codex	graphify install --platform codex
OpenCode	graphify install --platform opencode
GitHub Copilot CLI	graphify install --platform copilot
VS Code Copilot Chat	graphify vscode install
Aider	graphify install --platform aider
OpenClaw	graphify install --platform claw
Factory Droid	graphify install --platform droid
Trae	graphify install --platform trae
Gemini CLI	graphify install --platform gemini
Hermes	graphify install --platform hermes
Kiro IDE/CLI	graphify kiro install
Cursor	graphify cursor install
Google Antigravity	graphify antigravity install

安装完成后，打开你的 AI 编码助手并输入：

/graphify .

各平台安装行为的差异（写哪些指令文件、装哪些 hook）在 graphify/install.py 与各 skill-*.md 文件（如 graphify/skill.md）中定义，安装逻辑可用 tests/test_install.py 与 tests/test_install_roundtrip.py 对照验证。

使用：构建、查询与维护

原文档的完整命令清单（直接可用）：

/graphify                          # 当前目录
/graphify ./raw                    # 指定文件夹
/graphify ./raw --update           # 只重新抽取变更过的文件
/graphify ./raw --directed          # 有向图
/graphify ./raw --no-viz           # 仅报告 + JSON
/graphify ./raw --obsidian          # 生成 Obsidian vault

/graphify add https://arxiv.org/abs/1706.03762   # 抓取论文
/graphify add <video-url>                       # 转写视频
/graphify query "attention 和 optimizer 之间有什么联系?"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

graphify hook install              # 安装 Git hooks
graphify update ./src              # 重新抽取代码文件，无需 LLM
graphify watch ./src              # 自动同步图谱更新

这些命令背后分别对应 CLI 子命令实现（graphify/cli.py、graphify/main.py）：

• query 对 graph.json 做一次范围化子图检索，适合"X 和 Y 之间如何连接"这类问题；
• path 计算两节点间最短路径，逐步列出每一跳；
• explain 输出节点的来源位置、所属社区、度数与完整连接列表；
• hook install 注册 post-commit / post-checkout hooks，使提交与切分支时自动重建图谱（纯 AST，无 API 成本）；
• update 只走确定性 AST 路径，不调用 LLM；
• watch 基于文件变更监听自动同步。

query/path/explain 的行为分别由 tests/test_query_cli.py、tests/test_path_cli.py、tests/test_explain_cli.py 覆盖，可作为行为契约参考。

报告里有什么

原文档"आपको क्या मिलता है"一节列出的六项能力，逐条对应源码可查证：

• God nodes（枢纽节点）——连接度最高的概念，一切数据都流经它们。
• 意外连接（surprising connections）——按组合评分排序，代码-论文边会获得更高排名。
• 建议问题（suggested questions）——4–5 个该图特别擅长回答的问题。
• "为什么"（rationale）——docstring、行内注释与设计动机被抽取为 rationale_for 节点，链接到所解释的代码。
• 置信度分数——每条 INFERRED 边都带 confidence_score（0.0–1.0）。按 docs/how-it-works.md 的离散标准：EXTRACTED 边恒为 1.0；INFERRED 边取 0.95（几乎确定：显式跨文件引用且只有一个合理目标）、0.85（强证据：命名与上下文吻合）、0.75（合理：上下文相关但不显式）、0.65（弱：仅命名相似）、0.55（推测）；AMBIGUOUS 边则被标记供人工复核。
• Token 基准——每次运行后自动打印。混合语料上：相比直接读原始文件，每次查询减少 71.5 倍 tokens。该数据在 docs/how-it-works.md 中有完整基准表（52 文件混合语料 71.5x、4 文件 5.4x、6 文件约 1x），并说明 token 节省随语料规模增长——小语料已在上下文窗口内时，图的价值在于结构清晰度而非压缩。

隐私与数据边界

原文档的隐私一节给出了明确的数据流边界，这也是 graphify 的架构设计原则：

• 代码文件：通过 tree-sitter 在本地处理，不出机器；纯代码语料可完全离线运行；
• 音视频文件：通过 faster-whisper 在本地转写，不出机器；
• 文档、论文、图片：其内容会发往你 AI 助手的模型 API 做语义抽取（经由 /graphify 技能，使用你 IDE 会话中的模型）；
• 无遥测、无跟踪、无分析统计。

小结

graphify 的核心工程取舍在 docs/translations/README.hi-IN.md 中已经说得很清楚：代码侧走确定性 AST 抽取（零成本、可复现、可增量），语义侧才动用 LLM，而聚类完全由图拓扑驱动、不引入向量库。结合 graphify/cluster.py、graphify/cache.py 与 docs/how-it-works.md 可以看到：Leiden/Louvain 回退链、SHA256 内容缓存与 EXTRACTED/INFERRED/AMBIGUOUS 三级置信度标签，是这套"可查询、可审计、可增量"图谱的三个支柱。安装 graphifyy 包、graphify install 注册技能后，对任意文件夹执行 /graphify . 即可得到 graph.html、GRAPH_REPORT.md 与 graph.json 三个产物，并在此之上用 query、path、explain 持续查询。