企业官网建设流程全解析

Graphify 实战：用 /graphify 把代码、文档与 PDF 变成可查询的知识图谱

【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify

graphify 是一个面向 AI 编程助手的 Skill：在 Claude Code、Codex、Cursor、Gemini CLI 等助手里输入/graphify，它读取你的文件夹（代码、Markdown、PDF、图片、音视频），在本地用确定性 AST 解析构建一个知识图谱，并输出可在浏览器里交互查看的graph.html、可持久查询的graph.json和高亮报告GRAPH_REPORT.md。读完本文，你将掌握 graphify 的安装与多平台接入方式、全部命令行参数、.graphifyignore配置、增量更新与 Git Hook 自动同步机制，以及从源码层面理解它的三段式构建管线、Leiden 社区聚类与 EXTRACTED/INFERRED/AMBIGUOUS 置信度标签的落地实现。

一、定位：不是向量索引，而是可遍历的图

graphify 的核心卖点可以归纳为三条（见 README.md）：

• 代码映射完全本地、免费。代码文件用 tree-sitter 做 AST 解析：确定性、不经过 LLM、内容不离开本机；
• 每条边都有解释。每条关系被标记为EXTRACTED（在源码中显式找到）或INFERRED（由解析推导得出），让你分清“直接读到的”和“推断出来的”；
• 不是向量检索。没有 embedding、没有向量库，而是一张真正可遍历的图——你可以提问、追溯两个概念之间的最短路径、或解释单个概念。

项目定位为“AI 编程助手 Skill”：它不替代助手，而是给助手提供一个结构化的记忆层。首次构建花费 token 提取并建图，之后每次查询都只读紧凑的图而非原始文件——这正是 token 节省随语料规模复利式增长的原因。

二、工作原理：三段式构建管线

2.1 三个 Pass 的分工

构建过程分三个 Pass（详见 docs/how-it-works.md）：

三个要点值得注意：

1. 纯代码语料不触发 Pass 3。代码文件在常规管线中不会送进 LLM 语义抽取器；如果一个语料只含代码文件，Pass 3 会被整体跳过；
2. Pass 3 前有可选转换器。Office 文件（.docx、.xlsx，需[office]extra）和 Google Workspace 快捷方式（.gdoc等，需--google-workspace或GRAPHIFY_GOOGLE_WORKSPACE=1，且需要已认证的gwsCLI）会先转成 Markdown sidecar 落到graphify-out/converted/；
3. 转写 prompt 的领域化。Pass 2 的 whisper prompt 会注入你代码图中连接度最高的概念，让转写聚焦你的领域。从源码看，这一逻辑在 graphify/transcribe.py 的build_whisper_prompt()中实现，transcribe_all()支持 URL 下载（yt-dlp）与本地文件批量转写。

2.2 AST 抽取的源码证据

Pass 1 的抽取入口是 graphify/extract.py 的extract()，关键设计包括：

• 按语言分发：主文件包含 Python、JS/TS、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Lua、Swift、Groovy、Vue/Svelte/Astro 等抽取器；Rust、Go、Elixir、Zig、Verilog、PowerShell、Fortran、Pascal、OCaml、Common Lisp 等语言放在 graphify/extractors/ 子包中按语言独立实现（每个语言一个模块，如 rust.py、go.py），SQL 有专门的确定性抽取（表、视图、外键、JOIN 关系，见 sql.py）；
• 并行抽取：_extract_parallel()用ProcessPoolExecutor绕过 GIL 做真正的多进程并行，_extract_sequential()作为回退。docs/how-it-works.md 给出的实测：84 个代码文件的语料，并行 AST 抽取比顺序执行快约 1.66 倍；
• 设计理由（rationale）抽取：_extract_python_rationale()、_extract_js_rationale()会把 Docstring 和# NOTE:/# WHY:/# HACK:/# IMPORTANT:这类注释变成rationale_for节点，这就是报告中“设计背后的为什么”的数据来源。

2.3 SHA256 缓存与增量

每个被抽取的文件都按内容哈希（SHA256）打指纹，重跑时未变更的文件整体跳过，只有新增或修改的文件重新走抽取流程，缓存位于graphify-out/cache/。从源码看，缓存读写与命中判定实现在 graphify/cache.py（file_hash()、load_cached()、save_cached()、check_semantic_cache()），语义缓存还带 prompt 指纹与 partial 标记处理；graphify update命令复用这套机制只重抽代码文件（不需要 LLM）。

三、聚类与置信度：图结构本身就是相似性信号

3.1 Leiden 社区检测，无 Embedding

社区发现使用 Leiden 算法——一种按边密度把节点分组的图聚类方法：节点之间连接越多，越会被划进同一社区。关键设计是不需要 embedding：Pass 3 中 Claude 抽取的语义相似边（semantically_similar_to，标记为 INFERRED）本来就在图里，因此它们直接参与社区形状的计算，省去了独立的 embedding 步骤和向量数据库。

实现位于 graphify/cluster.py：cluster()调用_native_leiden()（graspologic，仅 Python < 3.13 可用，见 pyproject.toml 中leidenextra 的python_version < '3.13'约束），并提供_partition()回退；cohesion_score()/score_all()计算每个社区的凝聚度，label_communities_by_hub()在无 LLM 时也能给出社区标签。--cluster-only参数允许在已有图上单独重跑聚类。

3.2 三级置信度标签

每条关系都带一个标签：

INFERRED 边采用离散评分标准（见 docs/how-it-works.md）：

• 0.95— 近乎确定（显式跨文件引用、唯一合理解）
• 0.85— 强证据（命名与上下文一致）
• 0.75— 合理（有上下文但不显式）
• 0.65— 弱（仅命名相似）
• 0.55— 推测性

AST 抽取器产出的边默认confidence="EXTRACTED"（可对照 graphify/extractors/engine.py 中add_edge()的默认参数），而语义抽取结果则经过 graphify/semantic_cleanup.py 的validate_semantic_fragment()/sanitize_semantic_fragment()做结构与 ID 校验后才入图。

3.3 graph.json 的图格式

输出graph.json采用 NetworkX 的 node-link 格式。每个节点含：id（稳定标识）、label（可读名）、file_type（code/document/paper/image/rationale）、source_file（来源）。每条边含：source、target（节点 ID）、relation（动词短语，如calls、imports、implements、semantically_similar_to）、confidence（EXTRACTED/INFERRED/AMBIGUOUS）、confidence_score（仅 INFERRED 有）、source_file。连接 3 个及以上节点的超边（group 关系）存放在G.graph["hyperedges"]中。节点/边的去重与合并逻辑在 graphify/build.py（dedupe_nodes()、dedupe_edges()、build_merge()），实体级去重见 graphify/dedup.py。

四、安装：官方包名是 graphifyy（双 y）

前提：Python 3.10+（pyproject.toml 声明requires-python = ">=3.10"），以及至少一个受支持的 AI 编程助手（Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro、Google Antigravity 等 20+ 平台）。

重要提醒：PyPI 官方包名是graphifyy（双 y），PyPI 上其他graphify*包均与本项目无关；CLI 命令和 Skill 命令仍叫graphify。这与 pyproject.toml 的name = "graphifyy"一致（当前仓库版本 0.9.52）：

# 推荐 —— 在 Mac 和 Linux 上无需额外 PATH 配置 uv tool install graphifyy && graphify install # 或用 pipx pipx install graphifyy && graphify install # 或直接用 pip pip install graphifyy && graphify install

遇到graphify: command not found？优先使用uv tool install（推荐）或pipx install——两者都会把 CLI 放到自动进入 PATH 的受管目录。用uv tool install/pipx install后若仍找不到命令，运行uv tool update-shell（或pipx ensurepath）再开新终端；用裸pip安装时可能要把~/.local/bin（Linux）或~/Library/Python/3.x/bin（Mac）加入 PATH，或者改用python -m graphify。

可选 extras（按需安装）：完整清单见 pyproject.toml，常用几类：

4.1 各平台安装命令

安装逻辑在 graphify/install.py：install()把对应平台的 skill 文件复制到用户或项目目录（--project装进当前仓库，例如.claude/skills/graphify/SKILL.md，并打印git add提示），同时为支持 PreToolUse hook 的平台注册钩子（_claude_pretooluse_hooks()、_gemini_hook()等）。Codex 用户还需在~/.codex/config.toml的[features]下开启multi_agent = true以启用并行抽取。

4.2 让助手始终优先用图（推荐）

建完图后，在项目里再执行一次对应平台的注册命令：

这些命令会写入 always-on 提示（如 AGENTS.md / CLAUDE.md 中的段落），引导助手在读文件前先查图。

五、使用：命令与参数全解

打开 AI 助手后输入：

/graphify .

Codex 使用$而不是/，输入$graphify .。PowerShell 中注意用graphify .而非/graphify .（前导斜杠在 PowerShell 里是路径分隔符）。

完整的调用形式（Skill 文档见 graphify/skill.md，参数解析见 graphify/cli.py）：

/graphify # 处理当前目录 /graphify ./raw # 处理指定文件夹 /graphify ./raw --mode deep # 更激进的 INFERRED 边抽取（子代理带 DEEP_MODE=true） /graphify ./raw --update # 只重新抽取有变化的文件 /graphify ./raw --directed # 构建有向图 /graphify ./raw --cluster-only # 在已有图上重跑聚类 /graphify ./raw --no-viz # 不生成 HTML，只出 Report + JSON /graphify ./raw --obsidian # 生成 Obsidian Vault（opt-in） /graphify add https://arxiv.org/abs/1706.03762 # 抓取论文、保存并更新图 /graphify add <video-url> # 下载音频、转写并加入 /graphify query "what connects Attention to the optimizer?" /graphify path "DigestAuth" "Response" /graphify explain "SwinTransformer" graphify hook install # 安装 Git Hooks graphify update ./src # 重新抽取代码文件，不需要 LLM graphify watch ./src # 文件变化时自动更新图

参数行为在源码中可逐一对应：--directed透传给 graphify/build.py 的build(directed=...)；--no-viz在 graphify/cli.py 中解析后跳过 HTML 导出；--update走detect_incremental()（graphify/detect.py）按清单差异只处理变化文件；add <url>的抓取逻辑在 graphify/ingest.py（ingest()支持 arXiv、网页、推文与普通 URL，统一转成 Markdown 存入目标目录）；watch的长驻监听在 graphify/watch.py（watch()带 debounce 与重建锁，代码变更触发check_update()轻量重抽，非代码变更才触发 LLM 路径）。

查询侧命令同样在 CLI 提供：graphify query、graphify path、graphify explain都直接对graph.json做确定性图操作（BFS/DFS 子图展开与最短路径，见 graphify/serve.py 的_query_graph_text()/_shortest_path_text()），不依赖 LLM。如果安装了[mcp]extra，还能通过graphify-mcp（graphify/serve.py 的_main()）把图作为 MCP 工具暴露给外部 Agent。

5.1 用 .graphifyignore 排除目录

在仓库根目录放一个.graphifyignore文件即可排除目录或文件：

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

语法与.gitignore相同。可以把唯一的.graphifyignore放在仓库根目录——即使 graphify 在子目录上运行，模式也能正确生效。从源码看，忽略规则解析实现在 graphify/detect.py（_load_graphifyignore()、_parse_ignore_pattern()、_match_anchored_ignore_pattern()），同时支持目录级忽略、globstar 匹配，并与.gitignore语义协同。

六、你会得到什么

运行/graphify .后，输出目录结构为：

graphify-out/ ├── graph.html # 交互式图谱 —— 浏览器打开，点击节点、搜索、筛选 ├── GRAPH_REPORT.md # 高亮报告：神节点、意外连接、建议问题 ├── graph.json # 持久化图谱 —— 几周后无需重读文件即可查询 └── cache/ # SHA256 缓存 —— 重跑只处理改过的文件

报告与导出的具体内容：

• 神节点（God Nodes）——连接度最高的概念，即“一切流经”的地方。实现见 graphify/analyze.py 的god_nodes()（默认取 top 10）；
• 意外连接（Surprising Connections）——按综合得分排序，代码—论文跨类型边权重更高，每个结果都附一句“为什么”（surprising_connections()/_surprise_score()）；
• 建议问题——图谱最能回答的 4–5 个问题（suggest_questions()）；
• 设计理由（The “Why”）——Docstring、内联注释（# NOTE:/# IMPORTANT:/# HACK:/# WHY:）与文档中的设计理由被抽成rationale_for节点并与代码关联；
• 置信度——每条 INFERRED 边带confidence_score（0.0–1.0）；
• Token 基准——每次运行后自动打印。在混合语料（Karpathy 仓库 + 5 篇论文 + 4 张图片，52 个文件）上，每次查询比直接读原始文件少约71.5 倍token；语料越小节省越有限（6 个文件时约 1 倍），节省幅度随语料规模复利增长，数据与复现口径见 docs/how-it-works.md 和 BENCHMARKS.md；
• 自动同步（--watch）——后台运行，代码变化时自动更新图（graphify/watch.py）；
• Git Hooks（graphify hook install）——安装 Post-Commit 与 Post-Checkout Hook（graphify/hooks.py 的install()/uninstall()/status()），并在安装时把当前解释器路径直接嵌入 hook 脚本，保证 GUI git 客户端和 CI runner 中也能触发；升级 graphify 后建议重跑一次以刷新嵌入路径。

仓库的 worked/ 目录保留了真实运行的输入与输出（如 worked/httpx/graph.json、worked/httpx/GRAPH_REPORT.md），你可以自行重跑并核对。

七、隐私与数据边界

graphify 对数据流向的划分是明确的：

• 文档、论文、图片：文件内容会发送到你 AI 助手所连接模型 API 用于语义抽取（这是 Pass 3 的必然成本）；
• 代码文件：完全本地，经 tree-sitter AST 处理——代码内容不离开你的设备；
• 视频/音频：本地 faster-whisper 转写，不出网；
• 无遥测、无使用追踪（仓库亦提供 SECURITY.md 说明安全边界）。

八、技术栈

核心依赖可从 pyproject.toml 直接读出：networkx（>=3.4）、numpy、rapidfuzz，以及一整套tree-sitter语言语法（Python、JS、TS、Go、Rust、Java、Groovy、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、Fortran、Bash、JSON 等）。组合起来即官方描述：NetworkX + Leiden（graspologic）+ tree-sitter + vis.js；语义抽取使用你平台所用的模型（Claude、GPT-4 等），音视频转写用 faster-whisper + yt-dlp（可选）。

九、如何验证与深入阅读

• 三段管线、置信度标准、Token 基准的原始说明：docs/how-it-works.md；
• 语言检测、.graphifyignore与增量清单：graphify/detect.py；
• 构建、去重与增量合并：graphify/build.py、graphify/dedup.py、graphify/cache.py；
• 报告生成与社区导出：graphify/report.py、graphify/export.py、graphify/exporters/html.py；
• 回归测试覆盖抽取、置信度、聚类与缓存等核心行为，例如 tests/test_extract.py、tests/test_inferred_confidence_rubric.py、tests/test_cluster.py、tests/test_cache.py、tests/test_watch.py。

一句话总结：graphify 用“本地确定性 AST + 每条边可解释 + 图拓扑即相似性”三件套，把散落在代码、文档和多媒体里的知识固化成一份可持续查询的图——首跑付一次 token，之后所有问题都问图而不是问文件。

【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify