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

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/graphifygraphify 是一个面向 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.mdPass输入处理方式是否消耗 LLMPass 1代码文件tree-sitter 本地 AST 解析类、函数、导入、调用图、内联注释否Pass 2视频/音频本地 faster-whisper 转写转写 prompt 用你语料中的“神节点”god nodes做领域化引导结果缓存否Pass 3Markdown、PDF、图片、转写稿并行子代理subagents抽取概念、关系与设计理由输出 JSON 片段后合并是三个要点值得注意纯代码语料不触发 Pass 3。代码文件在常规管线中不会送进 LLM 语义抽取器如果一个语料只含代码文件Pass 3 会被整体跳过Pass 3 前有可选转换器。Office 文件.docx、.xlsx需[office]extra和 Google Workspace 快捷方式.gdoc等需--google-workspace或GRAPHIFY_GOOGLE_WORKSPACE1且需要已认证的gwsCLI会先转成 Markdown sidecar 落到graphify-out/converted/转写 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.pySQL 有专门的确定性抽取表、视图、外键、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.pyfile_hash()、load_cached()、save_cached()、check_semantic_cache()语义缓存还带 prompt 指纹与 partial 标记处理graphify update命令复用这套机制只重抽代码文件不需要 LLM。三、聚类与置信度图结构本身就是相似性信号3.1 Leiden 社区检测无 Embedding社区发现使用 Leiden 算法——一种按边密度把节点分组的图聚类方法节点之间连接越多越会被划进同一社区。关键设计是不需要 embeddingPass 3 中 Claude 抽取的语义相似边semantically_similar_to标记为 INFERRED本来就在图里因此它们直接参与社区形状的计算省去了独立的 embedding 步骤和向量数据库。实现位于 graphify/cluster.pycluster()调用_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 三级置信度标签每条关系都带一个标签标签含义EXTRACTED在源码中直接找到如函数调用、import置信度恒为 1.0INFERRED合理的推断附confidence_score0.0–1.0AMBIGUOUS不确定在报告中标记待人工复核INFERRED 边采用离散评分标准见 docs/how-it-works.md0.95— 近乎确定显式跨文件引用、唯一合理解0.85— 强证据命名与上下文一致0.75— 合理有上下文但不显式0.65— 弱仅命名相似0.55— 推测性AST 抽取器产出的边默认confidenceEXTRACTED可对照 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_typecode/document/paper/image/rationale、source_file来源。每条边含source、target节点 ID、relation动词短语如calls、imports、implements、semantically_similar_to、confidenceEXTRACTED/INFERRED/AMBIGUOUS、confidence_score仅 INFERRED 有、source_file。连接 3 个及以上节点的超边group 关系存放在G.graph[hyperedges]中。节点/边的去重与合并逻辑在 graphify/build.pydedupe_nodes()、dedupe_edges()、build_merge()实体级去重见 graphify/dedup.py。四、安装官方包名是 graphifyy双 y前提Python 3.10pyproject.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双 yPyPI 上其他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/binLinux或~/Library/Python/3.x/binMac加入 PATH或者改用python -m graphify。可选 extras按需安装完整清单见 pyproject.toml常用几类Extra作用安装video音视频转写faster-whisper yt-dlp需 Python 3.11uv tool install graphifyy[video]pdfPDF 抽取uv tool install graphifyy[pdf]office.docx/.xlsxuv tool install graphifyy[office]leidenLeiden 社区检测仅 Python 3.13uv tool install graphifyy[leiden]sqlSQL schema 抽取tree-sitter-sqluv tool install graphifyy[sql]mcpMCP stdio 服务uv tool install graphifyy[mcp]all以上全部uv tool install graphifyy[all]4.1 各平台安装命令平台安装命令Claude CodeLinux/Macgraphify installClaude CodeWindowsgraphify install自动检测或graphify install --platform windowsCodexgraphify install --platform codexOpenCodegraphify install --platform opencodeGitHub Copilot CLIgraphify install --platform copilotVS Code Copilot Chatgraphify vscode installAidergraphify install --platform aiderOpenClawgraphify install --platform clawFactory Droidgraphify install --platform droidTraegraphify install --platform traeTrae CNgraphify install --platform trae-cnGemini CLIgraphify install --platform geminiHermesgraphify install --platform hermesKiro IDE/CLIgraphify kiro installCursorgraphify cursor installGoogle Antigravitygraphify antigravity install安装逻辑在 graphify/install.pyinstall()把对应平台的 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 让助手始终优先用图推荐建完图后在项目里再执行一次对应平台的注册命令平台命令Claude Codegraphify claude installCodexgraphify codex installOpenCodegraphify opencode installGitHub Copilot CLIgraphify copilot installVS Code Copilot Chatgraphify vscode installAidergraphify aider installOpenClawgraphify claw installFactory Droidgraphify droid installTraegraphify trae installTrae CNgraphify trae-cn installCursorgraphify cursor installGemini CLIgraphify gemini installHermesgraphify hermes installKirographify kiro installGoogle Antigravitygraphify antigravity install这些命令会写入 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_MODEtrue /graphify ./raw --update # 只重新抽取有变化的文件 /graphify ./raw --directed # 构建有向图 /graphify ./raw --cluster-only # 在已有图上重跑聚类 /graphify ./raw --no-viz # 不生成 HTML只出 Report JSON /graphify ./raw --obsidian # 生成 Obsidian Vaultopt-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.pyingest()支持 arXiv、网页、推文与普通 URL统一转成 Markdown 存入目标目录watch的长驻监听在 graphify/watch.pywatch()带 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-mcpgraphify/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_score0.0–1.0Token 基准——每次运行后自动打印。在混合语料Karpathy 仓库 5 篇论文 4 张图片52 个文件上每次查询比直接读原始文件少约71.5 倍token语料越小节省越有限6 个文件时约 1 倍节省幅度随语料规模复利增长数据与复现口径见 docs/how-it-works.md 和 BENCHMARKS.md自动同步--watch——后台运行代码变化时自动更新图graphify/watch.pyGit Hooksgraphify hook install——安装 Post-Commit 与 Post-Checkout Hookgraphify/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 直接读出networkx3.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 Leidengraspologic 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考