Graphify 知识图谱自动增量重建Git post-commit 钩子与 CLAUDE.md 原生集成实战【免费下载链接】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 把代码库连同文档、SQL schema、配置、PDF解析成位于graphify-out/下的可查询知识图谱graph.json、GRAPH_REPORT.md但要让它始终反映最新的代码就必须在代码变更后重新构建图谱。本指南讲解 graphify 提供的两条自动维护路径Git post-commit 钩子每次git commit后自动增量重建无需常驻后台进程、与任何编辑器/IDE 解耦与CLAUDE.md 原生集成把 graphify 的规则写入项目CLAUDE.md让 Claude Code 会话中图谱常开。读完你就能在自己的仓库上安装、检查、卸载这两种集成并理解它们在 graphify/hooks.py、graphify/install.py、graphify/watch.py 中的底层实现。本文面向的内容是仓库中随 skill 分发的钩子与集成参考文档 graphify/skills/opencode/references/hooks.md同名文档也存在于tools/skillgen/expected/下的生成产物中二者内容一致。一、两种常开集成适用场景与分工默认的/graphify path构建是一次性全量管道见 graphify/skill-opencode.md生成的图谱不会自己跟上代码演化。于是 graphify 提供了两种互补的自动更新手段集成方式触发机制谁来执行典型场景graphify hook installgit 层post-commit每个 commit 触发一次机器上的 git任何编辑器/CLI/CI 环境只要走git commit就能自动重建graphify claude installAgent 会话内的CLAUDE.md规则Claude Code 会话让 Agent 在回答代码问题时先查图谱、改完代码后重建图谱前者解决物理层的同步每次提交后代码变了图谱跟着变后者解决会话层的同步让 Agent 的每次问答都建立在最新图谱上不再需要人工敲/graphify。两者可以同时启用职责不冲突。注意本文引用的是随 opencode skill 分发的 hooks 参考文档其中的命令graphify hook …、graphify claude …是 graphify CLI 的全局子命令不依赖特定 Agent 平台。二、Git post-commit 钩子安装、卸载与状态检查安装钩子只需在目标 git 仓库根目录下执行三条命令原文命令完整继承graphify hook install # install graphify hook uninstall # remove graphify hook status # checkinstall在最近的 git 仓库中安装 post-commit 与 post-checkout 两个钩子并注册 graph.json 的 union merge driveruninstall只移除 graphify 写入的部分保留钩子文件里其他人/工具已有的内容status只读诊断报告 post-commit、post-checkout、merge driver 三项的安装状态若钩子内容与当前配置已不一致还会提示 out of date。graphify hook status典型输出形如post-commit: installed post-checkout: installed merge driver: registered viz node limit: 0 # 仅当 .graphifyrc 配置了该选项时显示CLI 侧的命令分发位于 graphify/cli.py三个子命令分别映射到 graphify/hooks.py 中的install()/uninstall()/status()三个函数。2.1 触发时机与工作方式安装成功后每次git commit都会触发一次 post-commit 钩子完整链路为钩子先用git diff --name-only HEAD~1 HEAD找出本次提交改动的文件首个提交等没有 HEAD~1 时回退为git diff HEAD见 graphify/hooks.py过滤掉仅graphify-out/产物自身的变化避免图谱输出被 git 跟踪 → 钩子又触发重建的死循环见 graphify/hooks.py把待处理文件列表通过环境变量交给一个分离的后台 Python 进程该进程调用 graphify/watch.py 的_rebuild_code(root, changed_pathschanged)只对改动的代码文件重新执行 AST 提取未变化的文件节点从既有graph.json中保留删除的文件则从保留集中剔除重建产物graph.json与GRAPH_REPORT.md见 graphify/watch.py。不需要任何常驻后台进程或 watcher 守护——每次 commit 触发一次恢复期间零开销因为是纯 git 层的post-commit机制所以与编辑器无关VS Code、JetBrains、Vim、命令行都适用也不需要 agent 会话在线。代码重建全程为确定性 AST 解析不依赖 LLM、不消耗 API token这从源码注释 Auto-rebuilds the knowledge graph after each commit (code files only, no LLM needed) 可以直接印证graphify/hooks.py。2.2 文档与图片变化会被忽略钩子只负责代码的 AST 增量重建文档.md 等与图片的改动会被钩子忽略——因为语义抽取需要 LLM/视觉模型而钩子刻意不进入 LLM 流程。遇到这类变更原文文档给出的做法是手动执行/graphify --update # 在 Agent 会话中 # 或等价的 CLI 形式 graphify update .这里值得注意graphify/install.py 的 always-on 集成块见 graphify/always_on/claude-md.md同样要求 Agent After modifying code, rungraphify update .与钩子的代码只归 git 管、文档/图片手动更新策略完全自洽。2.3 与既有钩子共存追加而非覆盖如果仓库里已经存在其他工具如 lint 检查、提交信息规范、CI 通知写入的 post-commit 钩子graphify不会清空或覆盖它而是把自己的代码块追加到文件末尾卸载时也只删除由 marker 包裹的 graphify 段落保留其余内容。实现上每个钩子文件用成对的 marker 界定归属post-commit# graphify-hook-start…# graphify-hook-endpost-checkout# graphify-checkout-hook-start…# graphify-checkout-hook-end对应常量与追加/就地更新逻辑见 graphify/hooks.py 与_install_hook()/_uninstall_hook()graphify/hooks.py。_install_hook是幂等的若 marker 已存在且内容一致返回 already installed不会重复追加若内容过期则就地替换graphify 段落这对升级后钩子脚本更新很有用。2.4 install 还顺带做了什么graphify hook install不止装 post-commit。从 graphify/hooks.py 可以看到它一次完成三件事post-commit 钩子每次提交后增量重建post-checkout 钩子每次git checkout切换分支时做一次全量代码重建分支切换可能改动任意文件所以不走增量、以完整重建路径处理见 graphify/hooks.py注册 graph.json 的 union merge driver向 git config 写入merge.graphify.driver并在.gitattributes增加一行graphify-out/graph.json mergegraphifygraphify/hooks.py多人协作合并且图谱输出被 git 跟踪时用 graphify 自身的合并驱动避免冲突。另外安装器会**把安装时运行的 Python 解释器绝对路径钉死**进钩子脚本__PINNED_PYTHON__占位符见 graphify/hooks.py。这样即使用 GUI 客户端或 CI 等 PATH 极简的环境触发钩子也能找到正确的解释器而不会因~/.local/bin不在 PATH 上而静默失败。钩子目录的解析尊重core.hooksPath例如 Husky 场景通过git rev-parse --git-path hooks交给 git 自己解析而不是手写解析.git/config——相关兼容处理与注释见 graphify/hooks.py。三、重建细节深挖跳过高开销步骤的工程化设计参考文档对钩子只给了一句话级描述但 graphify/hooks.py 的生成脚本里隐藏了大量工程细节值得展开说明。3.1 重建是分离进程执行的commit 不被阻塞钩子触发后git commit立即返回重建在一个完全分离的后台进程里进行。这点非常关键全仓库重建可能耗时很长若同步跑在 post-commit 里会阻塞 shell。跨平台分离的实现值得一提它没有用传统的nohup … Git for Windows 自带的 MSYS shell 没有nohup/setsid会导致重建静默从未运行而是让 Python 自己做 detach——外层小进程 spawn 真正的重建进程后立即返回POSIX 用start_new_session等价 setsidWindows 用CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP并尽可能CREATE_BREAKAWAY_FROM_JOB避免每次 commit 弹出一个空白的控制台窗口。相关设计讨论完整记录在 graphify/hooks.py。后台进程的输出统一写入~/.cache/graphify-rebuild.log可用环境变量GRAPHIFY_REBUILD_LOG覆盖钩子返回前会打印一行提示例如[graphify hook] launching background rebuild (log: /home/you/.cache/graphify-rebuild.log)重建若超时或失败会以非零状态退出并在日志中留下[graphify hook] Rebuild failed: …之类的明确信息graphify/hooks.py——即使后台失败也不会把失败传染给已成功的git commit本身。3.2 并发保护与排队多人/多工具频繁提交时多个 post-commit 可能几乎同时触发。_rebuild_code用每仓库一把非阻塞flock防止重建堆积graphify/watch.py增量重建带changed_paths抢锁失败时会把本次改动写入待处理队列由正在持锁的重建完成后统一 drain、合并成一次重建避免改动集丢失全量重建无changed_paths直接吞并队列——它本就覆盖所有文件提交/切分支连环触发时锁保证不会互相踩踏。3.3 钩子的自动跳过场景为了不干扰用户工作流钩子内置了多道退出闸门全部满足时才会真正启动重建处于rebase / merge / cherry-pick中间状态存在rebase-merge、rebase-apply、MERGE_HEAD、CHERRY_PICK_HEAD时跳过避免阻塞--continue设置了GRAPHIFY_SKIP_HOOK1显式退出开关post-commit 与 post-checkout 都认在linked worktree中提交git worktree add场景下主 checkout 才拥有规范产物从 worktree 重建会写出无人需要的增量图还会与 CI 的git clean竞态改动只涉及graphify-out/产物本身post-checkout 额外要求必须是分支切换第三个参数为 1、新旧 HEAD 不同、且graphify-out/已存在图从未建过则不建。对应逻辑可见 graphify/hooks.py。从源码结构还可推断重建进程内设置了PYTHONHASHSEED0固定 Python 字符串哈希随机化——因为 louvain 社区检测会遍历字符串 key 的集合哈希种子不定会让社区划分在每次运行时抖动钉死后graphify-out的产出才是可复现的graphify/hooks.py。3.4 可调环境变量与.graphifyrc钩子生成的脚本预留了若干可用环境变量均在 graphify/hooks.py 中可见整理如下环境变量默认值作用GRAPHIFY_SKIP_HOOK未设置设为1时本次跳过重建两个钩子都生效GRAPHIFY_REBUILD_TIMEOUT600重建超时上限秒设为0表示不限时。POSIX 用SIGALRMWindows 用 watchdog 线程兜底GRAPHIFY_REBUILD_LOG~/.cache/graphify-rebuild.log后台重建输出日志路径GRAPHIFY_FORCE未设置1/true/yes时绕过to_json的节点数收缩保护允许重建后图谱节点变少重构删代码时用GRAPHIFY_OUTgraphify-out输出目录名钩子也会读取其中的.graphify_root以定位真正的仓库根GRAPHIFY_MAX_WORKERS自动Git for Windows/MSYS 环境默认限为1串行避免继承 GUI 客户端脆弱的管道句柄GRAPHIFY_VIZ_NODE_LIMIT来自.graphifyrc可视化节点上限可单次覆盖仓库默认其中GRAPHIFY_VIZ_NODE_LIMIT的项目级默认值来自仓库根目录的.graphifyrc文件keyvalue格式支持#注释目前唯一支持的键是viz_node_limit如# graphify-out 可视化上限 viz_node_limit0install时会把它烘焙进钩子脚本形式为${GRAPHIFY_VIZ_NODE_LIMIT:-n}保证一次性的命令行覆盖仍然生效status校验钩子里的值与.graphifyrc是否一致。配置解析器见 graphify/hooks.py。四、CLAUDE.md 原生集成让图谱在 Claude Code 会话中常开第二部分是每项目运行一次的 Agent 集成。在项目根目录执行graphify claude install这会做两件事实现见 graphify/install.py向项目根目录的CLAUDE.md写入一个## graphify小节若文件不存在则新建若已存在同名节则更新向.claude/settings.json注册 graphify 的 PreToolUse 钩子让 Claude Code 在调用搜索/读取类工具前先考虑走图谱查询。此后不再需要手动/graphify——新会话加载CLAUDE.md时就会看到这些规则自动遵守。集成块内容由仓库内的 always-on 模板 graphify/always_on/claude-md.md 注入由 graphify/install.py 读取、_replace_or_append_section落盘。写入的## graphify小节核心规则如下模板原文先查图谱涉及代码库的问题若graphify-out/graph.json存在先运行graphify query question查询关系用graphify path A B聚焦概念用graphify explain concept。这三者返回的是作用域子图通常远小于整份报告或原始 grep 输出优先 wiki 导航若graphify-out/wiki/index.md存在用它做广度导航而非直接翻源码大报告最后兜底graphify-out/GRAPH_REPORT.md只用于整体架构审阅或在 query/path/explain 信息不足时再读改码即更新修改代码后运行graphify update .让图谱跟上仅 AST、无 API 成本。配套的 CLI 子命令graphify claude install # 写入 ## graphify 小节并注册 PreToolUse 钩子 graphify claude uninstall # 移除该小节及相关钩子卸载是双向清理graphify/install.py除了项目根CLAUDE.md还会检查CLAUDE.local.md、.claude/CLAUDE.local.md用户可能把规则挪到这些本地文件以避免入库以及.claude/settings.json/.claude/settings.local.json中的 graphify PreToolUse 钩子若某文件因移除小节而变空则直接删除该文件。安装与卸载均保持幂等重复执行 already configured / no change。关于 strict 模式claude_install支持可选 strict 参数开启后会话中第一次裸文件读取会被拦截直到先跑过一次graphify query详见 graphify/install.py适合希望强制图谱优先的团队属于参考文档之外的进阶选项。五、何时需要手动 update即便装好了钩子与 CLAUDE.md 集成以下场景仍应手动执行graphify updateAgent 会话内对应/graphify --update新增/改动了文档、图片、PDF——钩子只处理代码的 AST 重建语义抽取类内容必须手动跑增量管道需要立即在本次会话内让图谱反映刚写的代码等不及下一个 commit 触发在非 git 目录、或未安装钩子的机器上工作希望强制执行一次全量一致性检查graphify update . --force类选项可绕过收缩保护。graphify update走的是与钩子完全相同的_rebuild_code路径只是阻塞等待锁所以产物与提交触发的重建保持一致。六、相关源码与测试参考想深入验证本文所述行为可从仓库内以下路径继续跟进钩子脚本生成、安装/卸载/状态、解释器探测、merge driver graphify/hooks.py增量重建核心_rebuild_code与并发锁 graphify/watch.pyCLI 子命令分发hook、claude、install等 graphify/cli.py各平台集成安装/卸载器claude_install/claude_uninstall等 graphify/install.pyCLAUDE.md 注入模板## graphify小节原文 graphify/always_on/claude-md.mdskill 主文件中指向本文参考文档的入口 graphify/skill-opencode.md参考文档的本体 graphify/skills/opencode/references/hooks.md仓库的测试目录tests/为这些机制提供了回归覆盖例如钩子逻辑相关测试 tests/test_hooks.py、安装/卸载相关 tests/test_install.py、tests/test_install_roundtrip.py、tests/test_install_references.py以及 CLAUDE.md 集成相关 tests/test_claude_md.py 等。结语一条原则贯穿全文钩子管代码Agent 规则管会话LLM 工作留给手动 update。graphify hook install用一次安装换来每次提交自动增量重建、不阻塞、不依赖编辑器、不消耗 API的图维护机制graphify claude install则把先查图谱、改后重建固化进每个 Claude Code 会话。两条路径配合 graphify/hooks.py 中沉淀的工程细节分离进程、解释器钉死、并发排队、rebase/worktree 跳过、merge driver让知识图谱在真实的多人协作节奏中始终保持新鲜。【免费下载链接】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），仅供参考 Graphify 知识图谱自动增量重建：Git post-commit 钩子与 CLAUDE.md 原生集成实战
Graphify 知识图谱自动增量重建Git post-commit 钩子与 CLAUDE.md 原生集成实战【免费下载链接】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 把代码库连同文档、SQL schema、配置、PDF解析成位于graphify-out/下的可查询知识图谱graph.json、GRAPH_REPORT.md但要让它始终反映最新的代码就必须在代码变更后重新构建图谱。本指南讲解 graphify 提供的两条自动维护路径Git post-commit 钩子每次git commit后自动增量重建无需常驻后台进程、与任何编辑器/IDE 解耦与CLAUDE.md 原生集成把 graphify 的规则写入项目CLAUDE.md让 Claude Code 会话中图谱常开。读完你就能在自己的仓库上安装、检查、卸载这两种集成并理解它们在 graphify/hooks.py、graphify/install.py、graphify/watch.py 中的底层实现。本文面向的内容是仓库中随 skill 分发的钩子与集成参考文档 graphify/skills/opencode/references/hooks.md同名文档也存在于tools/skillgen/expected/下的生成产物中二者内容一致。一、两种常开集成适用场景与分工默认的/graphify path构建是一次性全量管道见 graphify/skill-opencode.md生成的图谱不会自己跟上代码演化。于是 graphify 提供了两种互补的自动更新手段集成方式触发机制谁来执行典型场景graphify hook installgit 层post-commit每个 commit 触发一次机器上的 git任何编辑器/CLI/CI 环境只要走git commit就能自动重建graphify claude installAgent 会话内的CLAUDE.md规则Claude Code 会话让 Agent 在回答代码问题时先查图谱、改完代码后重建图谱前者解决物理层的同步每次提交后代码变了图谱跟着变后者解决会话层的同步让 Agent 的每次问答都建立在最新图谱上不再需要人工敲/graphify。两者可以同时启用职责不冲突。注意本文引用的是随 opencode skill 分发的 hooks 参考文档其中的命令graphify hook …、graphify claude …是 graphify CLI 的全局子命令不依赖特定 Agent 平台。二、Git post-commit 钩子安装、卸载与状态检查安装钩子只需在目标 git 仓库根目录下执行三条命令原文命令完整继承graphify hook install # install graphify hook uninstall # remove graphify hook status # checkinstall在最近的 git 仓库中安装 post-commit 与 post-checkout 两个钩子并注册 graph.json 的 union merge driveruninstall只移除 graphify 写入的部分保留钩子文件里其他人/工具已有的内容status只读诊断报告 post-commit、post-checkout、merge driver 三项的安装状态若钩子内容与当前配置已不一致还会提示 out of date。graphify hook status典型输出形如post-commit: installed post-checkout: installed merge driver: registered viz node limit: 0 # 仅当 .graphifyrc 配置了该选项时显示CLI 侧的命令分发位于 graphify/cli.py三个子命令分别映射到 graphify/hooks.py 中的install()/uninstall()/status()三个函数。2.1 触发时机与工作方式安装成功后每次git commit都会触发一次 post-commit 钩子完整链路为钩子先用git diff --name-only HEAD~1 HEAD找出本次提交改动的文件首个提交等没有 HEAD~1 时回退为git diff HEAD见 graphify/hooks.py过滤掉仅graphify-out/产物自身的变化避免图谱输出被 git 跟踪 → 钩子又触发重建的死循环见 graphify/hooks.py把待处理文件列表通过环境变量交给一个分离的后台 Python 进程该进程调用 graphify/watch.py 的_rebuild_code(root, changed_pathschanged)只对改动的代码文件重新执行 AST 提取未变化的文件节点从既有graph.json中保留删除的文件则从保留集中剔除重建产物graph.json与GRAPH_REPORT.md见 graphify/watch.py。不需要任何常驻后台进程或 watcher 守护——每次 commit 触发一次恢复期间零开销因为是纯 git 层的post-commit机制所以与编辑器无关VS Code、JetBrains、Vim、命令行都适用也不需要 agent 会话在线。代码重建全程为确定性 AST 解析不依赖 LLM、不消耗 API token这从源码注释 Auto-rebuilds the knowledge graph after each commit (code files only, no LLM needed) 可以直接印证graphify/hooks.py。2.2 文档与图片变化会被忽略钩子只负责代码的 AST 增量重建文档.md 等与图片的改动会被钩子忽略——因为语义抽取需要 LLM/视觉模型而钩子刻意不进入 LLM 流程。遇到这类变更原文文档给出的做法是手动执行/graphify --update # 在 Agent 会话中 # 或等价的 CLI 形式 graphify update .这里值得注意graphify/install.py 的 always-on 集成块见 graphify/always_on/claude-md.md同样要求 Agent After modifying code, rungraphify update .与钩子的代码只归 git 管、文档/图片手动更新策略完全自洽。2.3 与既有钩子共存追加而非覆盖如果仓库里已经存在其他工具如 lint 检查、提交信息规范、CI 通知写入的 post-commit 钩子graphify不会清空或覆盖它而是把自己的代码块追加到文件末尾卸载时也只删除由 marker 包裹的 graphify 段落保留其余内容。实现上每个钩子文件用成对的 marker 界定归属post-commit# graphify-hook-start…# graphify-hook-endpost-checkout# graphify-checkout-hook-start…# graphify-checkout-hook-end对应常量与追加/就地更新逻辑见 graphify/hooks.py 与_install_hook()/_uninstall_hook()graphify/hooks.py。_install_hook是幂等的若 marker 已存在且内容一致返回 already installed不会重复追加若内容过期则就地替换graphify 段落这对升级后钩子脚本更新很有用。2.4 install 还顺带做了什么graphify hook install不止装 post-commit。从 graphify/hooks.py 可以看到它一次完成三件事post-commit 钩子每次提交后增量重建post-checkout 钩子每次git checkout切换分支时做一次全量代码重建分支切换可能改动任意文件所以不走增量、以完整重建路径处理见 graphify/hooks.py注册 graph.json 的 union merge driver向 git config 写入merge.graphify.driver并在.gitattributes增加一行graphify-out/graph.json mergegraphifygraphify/hooks.py多人协作合并且图谱输出被 git 跟踪时用 graphify 自身的合并驱动避免冲突。另外安装器会**把安装时运行的 Python 解释器绝对路径钉死**进钩子脚本__PINNED_PYTHON__占位符见 graphify/hooks.py。这样即使用 GUI 客户端或 CI 等 PATH 极简的环境触发钩子也能找到正确的解释器而不会因~/.local/bin不在 PATH 上而静默失败。钩子目录的解析尊重core.hooksPath例如 Husky 场景通过git rev-parse --git-path hooks交给 git 自己解析而不是手写解析.git/config——相关兼容处理与注释见 graphify/hooks.py。三、重建细节深挖跳过高开销步骤的工程化设计参考文档对钩子只给了一句话级描述但 graphify/hooks.py 的生成脚本里隐藏了大量工程细节值得展开说明。3.1 重建是分离进程执行的commit 不被阻塞钩子触发后git commit立即返回重建在一个完全分离的后台进程里进行。这点非常关键全仓库重建可能耗时很长若同步跑在 post-commit 里会阻塞 shell。跨平台分离的实现值得一提它没有用传统的nohup … Git for Windows 自带的 MSYS shell 没有nohup/setsid会导致重建静默从未运行而是让 Python 自己做 detach——外层小进程 spawn 真正的重建进程后立即返回POSIX 用start_new_session等价 setsidWindows 用CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP并尽可能CREATE_BREAKAWAY_FROM_JOB避免每次 commit 弹出一个空白的控制台窗口。相关设计讨论完整记录在 graphify/hooks.py。后台进程的输出统一写入~/.cache/graphify-rebuild.log可用环境变量GRAPHIFY_REBUILD_LOG覆盖钩子返回前会打印一行提示例如[graphify hook] launching background rebuild (log: /home/you/.cache/graphify-rebuild.log)重建若超时或失败会以非零状态退出并在日志中留下[graphify hook] Rebuild failed: …之类的明确信息graphify/hooks.py——即使后台失败也不会把失败传染给已成功的git commit本身。3.2 并发保护与排队多人/多工具频繁提交时多个 post-commit 可能几乎同时触发。_rebuild_code用每仓库一把非阻塞flock防止重建堆积graphify/watch.py增量重建带changed_paths抢锁失败时会把本次改动写入待处理队列由正在持锁的重建完成后统一 drain、合并成一次重建避免改动集丢失全量重建无changed_paths直接吞并队列——它本就覆盖所有文件提交/切分支连环触发时锁保证不会互相踩踏。3.3 钩子的自动跳过场景为了不干扰用户工作流钩子内置了多道退出闸门全部满足时才会真正启动重建处于rebase / merge / cherry-pick中间状态存在rebase-merge、rebase-apply、MERGE_HEAD、CHERRY_PICK_HEAD时跳过避免阻塞--continue设置了GRAPHIFY_SKIP_HOOK1显式退出开关post-commit 与 post-checkout 都认在linked worktree中提交git worktree add场景下主 checkout 才拥有规范产物从 worktree 重建会写出无人需要的增量图还会与 CI 的git clean竞态改动只涉及graphify-out/产物本身post-checkout 额外要求必须是分支切换第三个参数为 1、新旧 HEAD 不同、且graphify-out/已存在图从未建过则不建。对应逻辑可见 graphify/hooks.py。从源码结构还可推断重建进程内设置了PYTHONHASHSEED0固定 Python 字符串哈希随机化——因为 louvain 社区检测会遍历字符串 key 的集合哈希种子不定会让社区划分在每次运行时抖动钉死后graphify-out的产出才是可复现的graphify/hooks.py。3.4 可调环境变量与.graphifyrc钩子生成的脚本预留了若干可用环境变量均在 graphify/hooks.py 中可见整理如下环境变量默认值作用GRAPHIFY_SKIP_HOOK未设置设为1时本次跳过重建两个钩子都生效GRAPHIFY_REBUILD_TIMEOUT600重建超时上限秒设为0表示不限时。POSIX 用SIGALRMWindows 用 watchdog 线程兜底GRAPHIFY_REBUILD_LOG~/.cache/graphify-rebuild.log后台重建输出日志路径GRAPHIFY_FORCE未设置1/true/yes时绕过to_json的节点数收缩保护允许重建后图谱节点变少重构删代码时用GRAPHIFY_OUTgraphify-out输出目录名钩子也会读取其中的.graphify_root以定位真正的仓库根GRAPHIFY_MAX_WORKERS自动Git for Windows/MSYS 环境默认限为1串行避免继承 GUI 客户端脆弱的管道句柄GRAPHIFY_VIZ_NODE_LIMIT来自.graphifyrc可视化节点上限可单次覆盖仓库默认其中GRAPHIFY_VIZ_NODE_LIMIT的项目级默认值来自仓库根目录的.graphifyrc文件keyvalue格式支持#注释目前唯一支持的键是viz_node_limit如# graphify-out 可视化上限 viz_node_limit0install时会把它烘焙进钩子脚本形式为${GRAPHIFY_VIZ_NODE_LIMIT:-n}保证一次性的命令行覆盖仍然生效status校验钩子里的值与.graphifyrc是否一致。配置解析器见 graphify/hooks.py。四、CLAUDE.md 原生集成让图谱在 Claude Code 会话中常开第二部分是每项目运行一次的 Agent 集成。在项目根目录执行graphify claude install这会做两件事实现见 graphify/install.py向项目根目录的CLAUDE.md写入一个## graphify小节若文件不存在则新建若已存在同名节则更新向.claude/settings.json注册 graphify 的 PreToolUse 钩子让 Claude Code 在调用搜索/读取类工具前先考虑走图谱查询。此后不再需要手动/graphify——新会话加载CLAUDE.md时就会看到这些规则自动遵守。集成块内容由仓库内的 always-on 模板 graphify/always_on/claude-md.md 注入由 graphify/install.py 读取、_replace_or_append_section落盘。写入的## graphify小节核心规则如下模板原文先查图谱涉及代码库的问题若graphify-out/graph.json存在先运行graphify query question查询关系用graphify path A B聚焦概念用graphify explain concept。这三者返回的是作用域子图通常远小于整份报告或原始 grep 输出优先 wiki 导航若graphify-out/wiki/index.md存在用它做广度导航而非直接翻源码大报告最后兜底graphify-out/GRAPH_REPORT.md只用于整体架构审阅或在 query/path/explain 信息不足时再读改码即更新修改代码后运行graphify update .让图谱跟上仅 AST、无 API 成本。配套的 CLI 子命令graphify claude install # 写入 ## graphify 小节并注册 PreToolUse 钩子 graphify claude uninstall # 移除该小节及相关钩子卸载是双向清理graphify/install.py除了项目根CLAUDE.md还会检查CLAUDE.local.md、.claude/CLAUDE.local.md用户可能把规则挪到这些本地文件以避免入库以及.claude/settings.json/.claude/settings.local.json中的 graphify PreToolUse 钩子若某文件因移除小节而变空则直接删除该文件。安装与卸载均保持幂等重复执行 already configured / no change。关于 strict 模式claude_install支持可选 strict 参数开启后会话中第一次裸文件读取会被拦截直到先跑过一次graphify query详见 graphify/install.py适合希望强制图谱优先的团队属于参考文档之外的进阶选项。五、何时需要手动 update即便装好了钩子与 CLAUDE.md 集成以下场景仍应手动执行graphify updateAgent 会话内对应/graphify --update新增/改动了文档、图片、PDF——钩子只处理代码的 AST 重建语义抽取类内容必须手动跑增量管道需要立即在本次会话内让图谱反映刚写的代码等不及下一个 commit 触发在非 git 目录、或未安装钩子的机器上工作希望强制执行一次全量一致性检查graphify update . --force类选项可绕过收缩保护。graphify update走的是与钩子完全相同的_rebuild_code路径只是阻塞等待锁所以产物与提交触发的重建保持一致。六、相关源码与测试参考想深入验证本文所述行为可从仓库内以下路径继续跟进钩子脚本生成、安装/卸载/状态、解释器探测、merge driver graphify/hooks.py增量重建核心_rebuild_code与并发锁 graphify/watch.pyCLI 子命令分发hook、claude、install等 graphify/cli.py各平台集成安装/卸载器claude_install/claude_uninstall等 graphify/install.pyCLAUDE.md 注入模板## graphify小节原文 graphify/always_on/claude-md.mdskill 主文件中指向本文参考文档的入口 graphify/skill-opencode.md参考文档的本体 graphify/skills/opencode/references/hooks.md仓库的测试目录tests/为这些机制提供了回归覆盖例如钩子逻辑相关测试 tests/test_hooks.py、安装/卸载相关 tests/test_install.py、tests/test_install_roundtrip.py、tests/test_install_references.py以及 CLAUDE.md 集成相关 tests/test_claude_md.py 等。结语一条原则贯穿全文钩子管代码Agent 规则管会话LLM 工作留给手动 update。graphify hook install用一次安装换来每次提交自动增量重建、不阻塞、不依赖编辑器、不消耗 API的图维护机制graphify claude install则把先查图谱、改后重建固化进每个 Claude Code 会话。两条路径配合 graphify/hooks.py 中沉淀的工程细节分离进程、解释器钉死、并发排队、rebase/worktree 跳过、merge driver让知识图谱在真实的多人协作节奏中始终保持新鲜。【免费下载链接】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），仅供参考