graphify 越南版 README 精读：从 /graphify 到可查询知识图谱的完整机制

本文以 graphify 仓库中的越南语 README（docs/translations/README.vi-VN.md）为主体，完整继承其「三遍处理（three passes）、置信度标签、安装与使用命令、输出产物、隐私边界」的核心脉络，并结合当前仓库源码（graphify/extract.py、graphify/cluster.py、graphify/cache.py、graphify/transcribe.py）与 docs/how-it-works.md 做源码级纵深扩充。读完你可以掌握：graphify 如何在不引入向量数据库的前提下，把代码、文档、PDF、视频统一变成一张可查询、可追溯路径的知识图谱。

一、它是什么：给 AI 编程助手的一个 /graphify 技能

越南版 README 的开篇定位是：「Kỹ năng dành cho trợ lý lập trình AI」（面向 AI 编程助手的技能）。在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Kiro 或 Google Antigravity 中输入 /graphify，它会读取你的文件、构建知识图谱，并返回你原本不知道存在的结构——让你更快理解 codebase，并挖出架构决策背后的「为什么」。

它的关键特征是完全多模态：代码、PDF、markdown、截图、架构图、白板照片、小语种图片，乃至视频和音频文件，graphify 都能从中抽取概念与关系，并连接进同一张图。其中视频在本地由 Whisper 转录，代码则通过 tree-sitter AST 解析——越南版 README 写作时的版本支持 25 种语言，当前仓库的 README.md 已扩展至 37 个 tree-sitter 语法（另有 Apex、Terraform、OCaml、Common Lisp 等独立解析器），这一点可以从 graphify/extract.py 的导入清单得到印证：apex、bash、blade、csharp、dart、go、rust、sql、terraform、verilog、zig 等解析器统一由 graphify/extractors/ 目录提供。

越南版 README 还引用了一个典型使用动机：Andrej Karpathy 习惯维护一个 /raw 目录，往里堆文章、推文、截图和笔记；graphify 针对的就是这种「文件越攒越多、上下文爆炸」的问题——每次查询比直接读原始文件少 71.5 倍 token，且在多次会话之间持续可用。

二、三遍处理机制：AST、Whisper 与并行子代理

「Cách hoạt động」（如何工作）一节是越南版 README 的核心骨架，原文描述了 graphify 的三次遍历，这一说法与 docs/how-it-works.md 完全一致，且都能在源码中找到落点。

Pass 1：AST 结构抽取（本地、零 LLM）

Tree-sitter 解析代码文件，抽取类、函数、导入、调用关系与行内注释，全程本地运行、不经过 LLM。graphify/extract.py 的模块 docstring 明确写着：「Deterministic structural extraction from source code using tree-sitter. Outputs nodes+edges dicts.」——确定性结构抽取，输出节点与边两个字典。

从源码结构看，抽取管线按语言注册了解析器（graphify/resolver_registry.py 中的 LanguageResolver 机制），并对跨语言/跨文件调用做了专门的消解：ruby_resolution.py、csharp_dispatch.py（C# 接口分派）、pascal_resolution.py（Pascal 继承调用）等模块都在 graphify/extract.py 顶部被显式接入。

一个值得注意的边界（docs/how-it-works.md 明确说明）：纯代码语料会完全跳过 Pass 3——代码文件不会被送入 LLM 语义抽取器，语义抽取只留给文档、论文、图片与转录文本。因此纯代码语料不需要任何 API key 即可离线运行。

Pass 2：视频/音频本地转录（faster-whisper）

graphify/transcribe.py 给出了具体实现：支持的媒体扩展名覆盖 .mp4 .mov .webm .mkv .avi .m4v .mp3 .wav .m4a .ogg，默认 Whisper 模型为 base（可通过 GRAPHIFY_WHISPER_MODEL 环境变量覆盖）；URL 下载走 yt-dlp，且在下发请求前先经 validate_url 阻断私网地址。转录结果写入 graphify-out/transcripts/ 并纳入缓存，重跑时跳过已处理文件。

docs/how-it-works.md 还补充了一个细节：转录的提示词会用当前代码图中度数最高的「god nodes」做播种（seeding），让转录聚焦于你的领域术语。

Pass 3：文档、论文、图片的并行语义抽取

Claude 子代理并行处理 markdown、PDF、图片与转录文本，每个子代理输出一段 JSON 片段（节点、边、组关系），最后合并为一张 NetworkX 图。文档链接（text 与 [[wikilinks]]）会生成文档之间的 references 边，对应实现见 graphify/extractors/markdown.py。

分社区：Leiden 聚类与降级路径

三遍结果合并后进入聚类。graphify/cluster.py 的模块注释概括了策略：「Uses Leiden (graspologic) if available, falls back to Louvain (networkx). Splits oversized communities. Returns cohesion scores.」即优先调用 Leiden 算法按边密度分组，不可用时降级到 NetworkX 的 Louvain；超大社区会被进一步拆分，并返回内聚度分数。源码中还可见一条性能优化路径：_native_leiden 直接调用 graspologic_native（Rust 扩展）而绕开 graspologic 完整包——注释里测量到绕过后省去了 7–19 秒的 umap/pynndescent 导入开销。

docs/how-it-works.md 特别强调：不需要嵌入（embeddings）。Claude 抽取出的语义相似边（semantically_similar_to）本身就在图里，直接参与社区形状的形成——图结构就是相似度信号，因此不存在独立的向量库。

每条边都有置信度标签

越南版 README 写道：「Mỗi mối quan hệ được gắn nhãn EXTRACTED, INFERRED（带置信度分数）或 AMBIGUOUS」。docs/how-it-works.md 给出了完整定义与评分细则：

标签	含义
EXTRACTED	直接从源码中找到（如一次函数调用、一条 import），置信度恒为 1.0
INFERRED	合理推断，带 0.0–1.0 的 confidence_score
AMBIGUOUS	不确定——在报告中被标记出来供人工复核

INFERRED 边采用离散评分量规：0.95（近乎确定：显式跨文件引用且目标唯一）、0.85（强证据：命名与上下文吻合）、0.75（合理：上下文相关但非显式）、0.65（弱：仅命名相似）、0.55（推测性）。测试 tests/test_confidence.py 与 tests/test_inferred_confidence_rubric.py 对该量规做了断言。

三、安装：一条命令注册技能

越南版 README 的安装一节给出了三条等价路径，前置要求是 Python 3.10+ 与任一 AI 编程助手：

uv tool install graphifyy && graphify install
# 或者用 pipx
pipx install graphifyy && graphify install
# 或者用 pip
pip install graphifyy && graphify install

原文特别强调：PyPI 上的官方包名是 graphifyy（双 y），其他 graphify* 包均非官方。当前仓库 README.md 进一步补充了排障要点：uvx 运行时必须写 uvx --from graphifyy graphify install，因为 uv tool run 把第一个词当包名解析；若装后提示 graphify: command not found，通常只需 uv tool update-shell 或 pipx ensurepath 后重开终端。

graphify install 的作用是把技能文件写入助手对应的用户级目录；若希望装进当前仓库而非用户主目录，当前版本支持 graphify install --project（例如写入 .claude/skills/graphify/SKILL.md）。仓库内 graphify/skills/ 目录下按平台（claude、codex、cursor、gemini、copilot、kiro 等）分列了技能与 references 文件，tools/skillgen/ 则用 platforms.toml 驱动这些平台文件的一致性生成。

四、使用：构建、增量更新与查询

越南版 README 的「Sử dụng」一节列出的核心命令，均可在 graphify/main.py 的帮助文本中找到对应实现：

/graphify .                          # 为当前目录构建图谱
/graphify ./raw --update             # 只重新抽取发生变化的文件
/graphify query "điều gì kết nối Attention với optimizer?"
/graphify path "DigestAuth" "Response"
graphify hook install                # 安装 git 钩子
graphify update ./src                # 增量更新指定目录

语义上：/graphify . 构建整图；--update 走 SHA256 缓存增量；query 对自然语言问题做 BFS 遍历并返回子图；path 追踪两个节点之间的最短路径；hook install 之后每次 git commit / 分支切换都会自动重建（纯 AST、零 API 成本）。当前仓库 README.md 还展示了真实查询输出形态：

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

每条边都带 EXTRACTED / INFERRED 标签，「读出来的」与「推断出来的」一目了然。

五、输出产物：四个文件构成的持续记忆

越南版 README 给出的输出目录结构：

graphify-out/
├── graph.html       交互式图谱——在任意浏览器打开
├── GRAPH_REPORT.md  神节点、意外连接、建议提问
├── graph.json       持续图谱——数周之后仍可查询
└── cache/           SHA256 缓存——重跑只处理已变更的文件

这四个产物在仓库中都有实证：graph.json 采用 NetworkX 的 node-link 格式（节点含 id、label、file_type、source_file；边含 source、target、relation、confidence、confidence_score、source_file）；仓库自带了真实运行样例，如 worked/httpx/ 与 worked/mixed-corpus/ 下完整的 graph.json + GRAPH_REPORT.md + review.md，可直接打开验证。

关于 cache/ 的实现，graphify/cache.py 的 save_cached 按「文件内容的 SHA256」作为键存储 nodes/edges 结果，load_cached 在哈希匹配时直接回放缓存。源码注释还揭示了一个细节设计：AST 缓存按包版本 + 缓存 schema 命名空间隔离（cache/ast/v{version}-s{schema}/），因为 AST 结果是 graphify 自身抽取器代码的产物，新版本修复了抽取 bug 时旧缓存不应继续生效；而语义缓存刻意不做版本隔离，只以抽取提示词的指纹作为失效条件，避免每次发版就对未变更文件重新计费。

六、你能得到什么：神节点、意外连接与 71.5x token 基准

越南版 README 的「Những gì bạn nhận được」一节列出了报告的五类内容，均对应 docs/how-it-works.md 与仓库样例：

• 神节点（God nodes）——度数最高的概念，一切流量都经过它们；
• 意外连接（Surprising connections）——跨文件/跨模块的关联，按「意外程度」排序；
• 建议提问（Suggested questions）——这张图恰好有资格回答的 4–5 个问题；
• 「为什么」（Rationale）——# NOTE: / # WHY: 行内注释、docstring 与设计理由被抽成独立节点，链接到它所解释的代码；
• Token 基准——混合语料上比直接读原始文件节省 71.5 倍 token。

这个 71.5x 数字不是孤证：docs/how-it-works.md 给出了完整基准表——「Karpathy 仓库 + 5 篇论文 + 4 张图片、52 个文件」的混合语料上节省 71.5 倍；4 个文件的语料节省 5.4 倍；6 个文件的 httpx 约为 1 倍。原文同时诚实地说明：token 节省随语料规模增长，小语料的价值在于结构清晰度而非压缩。仓库内的 worked/ 目录每个样例都保留了原始输入与真实输出，可复现验证；CLI 侧也有 graphify benchmark 子命令直接度量相对朴素全语料方案的 token 缩减。

七、隐私边界：什么留在本地，什么经过模型

越南版 README 的「Quyền riêng tư」一节只有三句话，但每条都有源码支撑：

1. 代码文件经 tree-sitter 本地处理——graphify/extract.py 是纯本地确定性管线，纯代码语料零 API 调用；
2. 视频本地转录——graphify/transcribe.py 使用 faster-whisper 本地推理，音频不出机器；
3. 无遥测（no telemetry）——不采集用量、不做分析。

需要注意的边界是：文档、PDF、图片的语义抽取会经过 AI 助手（在 IDE 内走当前会话的模型；无头 graphify extract 则需要配置 GEMINI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY 等后端密钥之一）。当前仓库 README.md 的隐私一节补充了数据驻留选项：对有驻留要求的代码可用 --backend ollama 全本地推理，或用 --backend 显式指定后端；查询日志（graphify query/path/explain 的本地 JSON Lines 记录）默认关闭，可用 GRAPHIFY_QUERY_LOG_ENABLE=1 显式开启、GRAPHIFY_QUERY_LOG_DISABLE=1 强制关闭。

八、小结：从「grep 文件」到「查询图」

回到越南版 README 的核心命题：/graphify . 一行命令之后，你得到的不是又一个索引，而是一张每条边都能解释来源与置信度的真实图——AST 确定性抽取保证代码结构零幻觉，faster-whisper 保证媒体内容本地化，Leiden 聚类让子系统浮出水面，SHA256 缓存让「持续图谱」在数周尺度上保持廉价。想进一步验证，建议直接打开 worked/httpx/graph.json 与 worked/httpx/GRAPH_REPORT.md 对照本文第三节、第五节的内容，或在自己的项目里跑一遍 uv tool install graphifyy && graphify install，再输入 /graphify .。