graphify 提交钩子与 CLAUDE.md 原生集成每次 git commit 自动重建知识图谱【免费下载链接】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 会在项目下生成可查询的知识图谱graphify-out/graph.json、GRAPH_REPORT.md但若每次代码变更都要手动触发一次全量重建图谱会迅速过期、失去价值。本文面向 graphify 的 Pi以及 Claude Code 等Agent 使用场景基于 hooks 参考文档 讲解两种自动化方案post-commit git 钩子每次 commit 自动增量重建图谱与原生 CLAUDE.md 集成让 Claude Code/Pi 会话天然感知图谱。读完本文你将掌握graphify hook install/uninstall/status与graphify claude install/uninstall的完整用法、底层触发机制以及全部可用环境变量与调优手段。一、核心背景把手动重建变成随提交自动发生graphify 的完整流水线详见 skill 主文档通常由用户显式触发产物落在graphify-out/graph.json结构化图谱、GRAPH_REPORT.md社区、枢纽节点、惊喜连接等人类可读报告、graph.html可视化。增量更新模式/graphify --update只对新增/变更文件重新抽取比全量重建便宜得多但依然需要一次人工调用。两个接线方案解决的问题正是这个最后一次调用git 提交钩子把增量重建挂到每次git commit之后触发一次、无需任何后台进程、与编辑器无关只要你还在用 git换任何编辑器都会触发。CLAUDE.md 原生集成把先查图谱、改完代码再更新图谱的规则写进项目本地的CLAUDE.md让 Agent 会话从第一天起就把图谱当作默认的代码库知识入口不再需要每次手动/graphify。注意钩子与 CLAUDE.md 集成只针对代码变更做 AST 增量重建确定性、无 LLM、零 API 成本。文档、图片等资源的变更不在钩子覆盖范围内需要手动执行graphify update .会话内等价于/graphify --update刷新。二、post-commit 钩子三个命令完成安装与生命周期管理参考文档给出的核心命令极简graphify hook install # 安装 graphify hook uninstall # 移除 graphify hook status # 检查安装后每次git commit钩子会自动通过git diff HEAD~1 HEAD找出本次提交变更的代码文件仅对这些变更文件重新执行 AST 抽取增量重建graphify-out/graph.json与graphify-out/GRAPH_REPORT.md。文档同时给出了两条重要的行为约定文档/图片类变更会被钩子忽略——这类资源需要手动跑/graphify --update若已存在其他 post-commit 钩子graphify 不会覆盖而是追加到现有钩子末尾。从源码看安装到底做了什么打开 hooks.py 可以看到install()hooks.py实际安装的是三类东西status也会分别报告每一类的状态安装产物用途标记marker.git/hooks/post-commitcommit 后增量重建# graphify-hook-start…# graphify-hook-end.git/hooks/post-checkout切换分支后全量重建# graphify-checkout-hook-start…# graphify-checkout-hook-endgit 合并驱动merge.graphifygraph.json的 union 合并.gitattributes中graphify-out/graph.json mergegraphify几个实现细节值得注意append 而非覆盖_install_hook()hooks.py在读入已有钩子后若内容中已存在 graphify 标记则原位更新这段内容幂等否则把 graphify 脚本追加到文件末尾全新文件则补写#!/bin/sh头并加可执行权限。对应测试见 tests/test_hooks.py。尊重core.hooksPath/ Huskyhooks 目录通过git rev-parse --git-path hooks解析hooks.py而不是手写解析.git/config因此能正确处理 Huskycore.hooksPath指向.husky/_、includeIf 与 linked worktree当目录以_结尾时还会自动回退到用户可编辑的父目录.husky/见_user_hooks_dir()hooks.py。安装位置install()会从当前目录向上查找最近的 git 仓库根.git目录找不到会抛出No git repository found。所以命令应在目标仓库根目录执行。增量重建的跳过逻辑与防抖设计生成的 post-commit 脚本在真正触发重建前会做一系列判断hooks.py理解它们有助于排查为什么提交后没重建rebase / merge / cherry-pick 期间跳过检测GIT_DIR/rebase-merge、rebase-apply、MERGE_HEAD、CHERRY_PICK_HEAD存在即退出避免阻塞--continue时的未暂存变更GRAPHIFY_SKIP_HOOK1可显式跳过post-checkout 同样遵守保证行为一致linked worktree 中跳过主 checkout 的graphify-out/才归属权威图谱从 worktree 重建会产生多余的增量图并与git clean竞争故比较git rev-parse --git-dir与--git-common-dir来识别并退出hooks.py仅 graphify-out/ 产物变化时跳过避免图谱输出被纳入版本控制时提交产物→触发重建→再提交产物的死循环无变更文件空 diff直接退出。此外脚本还会export PYTHONHASHSEED0保证 louvain 社区划分结果在多次运行间可复现并在 Windows/MSYS 环境默认把GRAPHIFY_MAX_WORKERS降为 1GUI git 客户端传入的管道句柄可能不稳定串行更安全。三、钩子重建是分离式后台进程提交绝不阻塞参考文档强调钩子不需要后台进程、每次 commit 只触发一次。实际上重建本身是在分离的子进程中执行的从而让git commit立即返回旧实现依赖nohup ... 而 Git for Windows 自带的 MSYS shell 没有nohup/setsid导致重建静默失败。现在由外层 Python 启动器负责分离POSIX 用start_new_sessionWindows 用CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP跨平台行为一致见_LAUNCHER_TEMPLATEhooks.py。子进程的输出写入日志~/.cache/graphify-rebuild.log可用GRAPHIFY_REBUILD_LOG覆盖。提交时终端只打印一行提示重建过程完全在后台完成。重建核心调用graphify.watch._rebuild_code(...)watch.py并把变更文件清单经GRAPHIFY_CHANGED环境变量传入post-commit走带changed_paths的增量路径post-checkout因分支切换可能牵动任意文件而走全量路径。重建前还会调用_apply_resource_limits()watch.py做 best-effort 的资源限制。若项目存在工作记忆graphify-out/memory/*.md重建后还会 best-effort 刷新反思笔记reflections/LESSONS.md失败不影响钩子退出码。找不到解释器怎么办四级探测链graphify 可能经 uv tool、pipx、venv 或系统安装钩子触发时尤其是 GUI git 客户端/CIPATH 往往很精简未必能找到解释器。为此安装时会固定安装时解释器的绝对路径运行时再按优先级探测hooks.py安装时钉住的sys.executable过滤掉含 shell 元字符的非法路径见_pinned_python()hooks.pygraphify-out/.graphify_python记录的解释器skill 与 CLI 都会写此文件内容同样经过字符白名单校验从 PATH 上的graphify启动器解析 shebang / 推断同目录python(.exe)扫描uv tool环境~/.local/share/uv/tools、$HOME/AppData/Roaming/uv/tools尊重UV_TOOL_DIR最后回退python3/python。探测使用importlib.util.find_spec而非真正导入 graphify避免每次提交前白白付出数秒的整包导入开销。若全部探测失败钩子打印提示并安全退出exit 0不会阻塞提交。四、钩子级可调参数与环境变量速查以下变量均可在源码注释与生成脚本中找到依据按需设置在 shell 环境或提交命令前环境变量默认值作用依据GRAPHIFY_SKIP_HOOK0设为1时跳过钩子触发的重建post-commit 与 post-checkout 均生效hooks.pyGRAPHIFY_REBUILD_TIMEOUT600重建超时秒超时后钩子进程以非零退出hooks.pyGRAPHIFY_FORCE空为1/true/yes时强制全量重建绕过增量hooks.pyGRAPHIFY_OUTgraphify-out输出目录名也可由.graphify_root侧车文件决定重建根目录hooks.pyGRAPHIFY_REBUILD_LOG~/.cache/graphify-rebuild.log后台重建进程的日志路径hooks.pyGRAPHIFY_MAX_WORKERS按平台Windows/MSYS 默认降为1可显式覆盖恢复并行hooks.pyGRAPHIFY_CHANGED—内部传递本次变更文件清单换行分隔hooks.pyPYTHONHASHSEED0钩子固定写入保证社区划分结果可复现hooks.py另一个项目级配置入口是仓库根目录的.graphifyrc文件keyvalue格式#开头为注释。目前支持viz_node_limit非负整数例如viz_node_limit0会在安装钩子时烘焙为export GRAPHIFY_VIZ_NODE_LIMIT${GRAPHIFY_VIZ_NODE_LIMIT:-值}见_load_graphifyrc()与install()hooks.py。注意烘焙时使用:-默认值形式因此单次运行的显式环境变量仍可覆盖项目默认值配置被修改后graphify hook status会提示钩子out of date需要重跑install同步。解析出错时status会打印 warning 而不崩溃。五、graph.json 的合并驱动多人协作不丢边代码仓库一般都会被多人提交、切分支、合并。如果graphify-out/graph.json被纳入版本控制常规的文本合并几乎必然冲突。因此graphify hook install会顺带注册一个git 合并驱动git 配置merge.graphify.drivergraphify merge-driver解释器同样以安装时钉住的方式传入确保合并时即使 PATH 无 graphify 也能运行.gitattributes写入graphify-out/graph.json mergegraphify默认输出目录被绝对路径覆盖时回退为字面graphify-out见_merge_attr_line()hooks.py。这样合并冲突时 git 调用graphify merge-driver %O %A %B对两份 graph.json 做 union 合并。graphify hook status会分别报告post-commit、post-checkout、merge driver三项状态含not registered、partially registered、installed/out of date等细分uninstall则把三者全部回滚。六、原生 CLAUDE.md 集成让 Agent 会话始终先查图谱git 钩子解决的是图谱如何保鲜CLAUDE.md 集成解决的是Agent 如何用起来。参考文档指出只需在项目里执行一次graphify claude install它会向项目本地的CLAUDE.md写入一个## graphify小节内容来自仓库打包的 claude-md.md该 always-on 块由 tools/skillgen 生成、skillgen --check防漂移安装器通过_replace_or_append_section()原样注入见 install.py。写入的规则本质上是回答代码库问题前先查图谱graphify query question存在graphify-out/graph.json时关系用graphify path A B概念聚焦用graphify explain concept——返回的是裁剪后的子图通常远小于全文 grep有 wiki 先用 wiki若graphify-out/wiki/index.md存在用它做大范围导航而不是直接翻源码GRAPH_REPORT.md仅作兜底只在 query/path/explain 信息不足或需要宏观架构审视时通读改完代码记得更新图谱graphify update .仅 AST、无 API 成本。这样后续会话无需再手动/graphifyAgent 在回答架构、文件关系类问题时会被强制先落入图谱这张地图。不止写文档还注册 PreToolUse 钩子graphify claude install的原生集成并不止于一段 markdown。它还会向.claude/settings.json写入PreToolUse 钩子install.py匹配Glob|Grep、Bash|Grep、Read|Glob等工具在 Agent 尝试搜索源码前注入提示搜索提示图谱存在时必须先graphify query question只有定位之后或需要修改/调试具体行时才允许 grep消息载荷见 cli.py读取提示读源码文件前应先 query/explain/path 定向该规则对子代理同样生效检测到文件在最近一次构建后发生过变更时还会提示图谱可能过期并建议graphify update见 cli.pystrict 模式可选地把首次原始文件读取直接 deny强制先跑一次graphify query可用GRAPHIFY_HOOK_STRICT0关闭。这些钩子的命令经_resolve_graphify_exe()解析为绝对路径项目级安装则使用裸graphify命令以便配置随仓库提交在 sh、cmd.exe、PowerShell 下均可解析。uninstall 会同时清理CLAUDE.md小节与.claude/settings.json/settings.local.json中的钩子install.pygraphify claude uninstall # 移除 graphify section 与 PreToolUse 钩子配套测试覆盖了 roundtrip、升级、字符串精确匹配等边界见 test_install_roundtrip.py 与 test_install.py。七、方案对比与适用建议关注点git 提交钩子CLAUDE.md 原生集成触发时机每次git commit 分支切换每次 Agent 会话开始前加载规则解决的问题图谱保鲜增量重建图谱被优先使用知识入口适用对象代码变更的持续追踪Claude Code / Pi 等以 CLAUDE.md 为上下文载体的 Agent文档/图片变更不覆盖需手动graphify update .规则文本本身不含此路径需要后台进程否提交触发、分离执行否推荐落地顺序先在仓库执行graphify claude install让 Agent 建立先查图谱的习惯再执行graphify hook install让图谱随提交自动保鲜两者互不冲突hook status与claude uninstall可随时用于诊断和回滚。若你使用 Codex、Cursor、Gemini 等其他宿主graphify 提供了对应的平台安装器agents/codex/gemini等见 skill 主文档 的分发结构各平台参考文件布局在 graphify/skills 下集成思路与本文一致一份 always-on 规则 一层工具级钩子。【免费下载链接】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），仅供参考