graphify 提交钩子与原生 CLAUDE.md 集成指南：让知识图谱随代码提交自动保鲜

本文基于仓库中 Windows 平台 Skill 参考文档 hooks.md 展开，系统讲解 graphify 两大“常驻式”集成方式：一键安装的 post-commit git 钩子（提交后自动增量重建知识图谱）与把 graphify 写进项目 CLAUDE.md 的原生绑定（让 Claude Code 会话内始终感知图谱）。读完本文，你将掌握 graphify hook install/status/uninstall 与 graphify claude install/uninstall 的完整用法、底层执行链路、可调环境变量，以及如何为协作仓库安全地启用这一机制。

为什么需要“自动保鲜”的知识图谱

graphify 会把整个代码库（连同文档、SQL Schema、配置与 PDF）转换成一个可查询的知识图谱，产出于 graphify-out/graph.json（GraphRAG 就绪的 JSON 图谱）与 graphify-out/GRAPH_REPORT.md（自然语言架构报告）。手工构建一次很容易，但代码每天都在变——如果图谱停留在“上次构建”的快照，Agent 基于它回答问题就会过时。

参考文档给出的答案是两种无需手动 /graphify 的常驻方案：

1. post-commit 钩子：每次 git commit 后自动重建图谱，无需任何后台守护进程，与编辑器无关；
2. 原生 CLAUDE.md 集成：一次性把 graphify 的使用规则写入项目 CLAUDE.md，此后 Claude Code 会话中图谱“始终在线”。

下文先围绕 hooks.md 的钩子部分展开，再结合 hooks.py 源码逐层剖析其真实行为。

git commit 钩子：一行命令接入

在项目根目录执行安装命令即可：

graphify hook install     # 安装
graphify hook uninstall   # 卸载
graphify hook status      # 检查状态

命令分发定义在 cli.py：hook 子命令直接调用 hooks.py 中的 install / uninstall / status 三个入口，作用于“当前目录向上最近的 git 仓库”。

安装后发生了什么

安装完成后，每次 git commit 提交成功后，钩子会自动执行以下流程（参考文档 + hooks.py 中注入的 post-commit 脚本）：

1. 定位变更文件：通过 git diff --name-only HEAD~1 HEAD 找出本次提交改动的代码文件（首次提交等无 HEAD~1 场景自动回退到 git diff --name-only HEAD）；
2. 增量 AST 提取：只对这些变更文件重新执行确定性 AST 提取，而不是全量重建；
3. 重建产物：重新生成 graph.json 与 GRAPH_REPORT.md，并附带刷新 graphify-out/reflections/LESSONS.md（当存在 memory/ 目录时，最佳努力执行，失败不会拖垮提交）；
4. 提交立刻返回：重建过程以“完全脱离终端”的后台子进程运行，git commit 不会阻塞等待。

整个设计“每次提交触发一次、无后台进程、兼容任意编辑器/任何 GUI 客户端”。文档/图片类改动被钩子忽略——这类非代码变更需要手动执行 /graphify --update（或 CLI 等价命令 graphify update .）来完成增量更新。

安全性与共存策略

参考文档特别强调：“如果已存在 post-commit 钩子，graphify 会追加而不是覆盖它。”源码级实现可进一步印证其边界设计（hooks.py）：

• 钩子内以 # graphify-hook-start / # graphify-hook-end 标记包裹自己的代码块；重复执行 install 时是“原地更新”而非二次追加；
• uninstall 用正则精确剥离标记区间，保留用户原有的其他钩子内容；仅当文件被清空或只剩 shebang 时才删除整个文件（hooks.py）；
• 新的钩子脚本会写入 #!/bin/sh 头并设置 0755 可执行权限；hooks 目录通过 git rev-parse --git-path hooks 解析，自动兼容 core.hooksPath（Husky 等工具）与 linked worktree 场景（hooks.py）。

仓库级自动跳过的安全网

从注入脚本可以看出，钩子内置了多层“该跳过时就跳过”的保护（hooks.py）：

• rebase / merge / cherry-pick 期间：检测到 rebase-merge、rebase-apply、MERGE_HEAD、CHERRY_PICK_HEAD 即退出，避免 --continue 被未暂存改动阻塞；
• 仅有图谱产物变动：若变更文件全部位于 graphify-out/（比如图谱产物被纳入了 git 跟踪），直接退出，防止“提交图谱→触发重建→再提交”的死循环；
• linked worktree：当 git-dir 与 common-dir 不一致（即 git worktree 场景）时跳过，避免在非主检出上写出多余的图谱并污染主检出（hooks.py）；
• 跨平台确定性：脚本导出 PYTHONHASHSEED=0，使 Louvain 社区聚类结果可复现；在 Windows/MSYS 环境下默认将 GRAPHIFY_MAX_WORKERS 收敛为 1，避免从 GUI 客户端继承到脆弱管道句柄。

此外，graphify hook install 还会顺带注册 post-checkout 钩子与 graph.json 的 union merge driver（hooks.py）：切换分支且 graphify-out/ 已存在时后台全量重建；merge driver 则通过 git config + .gitattributes 写入 merge=graphify，让团队多人并行提交 graph.json 时能安全合并。

深入钩子的运行时：环境变量控制面

重建真正发生在一个“脱离 shell、由 Python 自我守护”的子进程里（替代了过去依赖 nohup 的做法，后者在 Git for Windows 自带 shell 中不可用）。对使用者而言，最有价值的是一组可用环境变量控制面，全部可在 hooks.py 重建体中找到对应读取点：

环境变量	默认值	作用
GRAPHIFY_SKIP_HOOK	0	设为 1 可临时禁用钩子（对 post-commit 与 post-checkout 同时生效），用于“本次提交跳过重建”
GRAPHIFY_REBUILD_TIMEOUT	600（秒）	重建超时上限；设为 0 关闭超时
GRAPHIFY_FORCE	关	设为 1 / true / yes 时强制全量重建（而非只处理变更文件）
GRAPHIFY_OUT	graphify-out	输出目录覆盖（与 .graphifyrc/graphify 配置一致）
GRAPHIFY_MAX_WORKERS	Windows/MSYS 下为 1	重建并发度，显式设置优先
GRAPHIFY_VIZ_NODE_LIMIT	由 .graphifyrc 烘焙	可视化节点上限；命令行显式值优先于项目持久化默认

其中 viz_node_limit 来自项目根目录 .graphifyrc 文件的 key=value 行（例如 viz_node_limit=0），install 时被烘焙进钩子脚本作为默认值，使“每次提交的持久化配置”与“某一次的临时覆盖”互不干扰（hooks.py）。重建日志默认落在 ~/.cache/graphify-rebuild.log，便于排查“提交成功但图谱没更新”的问题。

graphify hook status 是只读诊断命令，会逐项报告 post-commit、post-checkout、merge driver 三个组件的安装状态，并能在钩子里烘焙的 viz_node_limit 与 .graphifyrc 不一致时给出“out of date”提示（hooks.py）；仓库测试覆盖了安装、追加、卸载、.graphifyrc 解析与超时注入等路径（见 test_hooks.py）。

原生 CLAUDE.md 集成：让 Claude Code 会话始终“带着图谱”

参考文档的第二半部分解决另一个问题：即便图谱新鲜，Agent 也得知道去用它。在 Windows 平台上（以及绝大多数平台默认），graphify 将这一绑定落到项目的 CLAUDE.md：

graphify claude install     # 写入 ## graphify 段落到本地 CLAUDE.md
graphify claude uninstall   # 移除该段落

install 的实现位于 install.py：它定位到 (项目目录)/CLAUDE.md，用 ## graphify 标记把打包好的“常驻指令块”追加或替换进文档。该指令块本体是 claude-md.md，内容是若干条极简规则：

• 回答代码库问题前，先跑 graphify query "<question>"（存在 graphify-out/graph.json 时），关系用 graphify path "<A>" "<B>"，概念解释用 graphify explain "<concept>"，返回的都是比 GRAPH_REPORT.md 或原始 grep 小得多的局部子图；
• 若 graphify-out/wiki/index.md 存在，优先用于大范围导航；
• GRAPH_REPORT.md 仅在需要通盘架构审视、而上述命令又给不出足够上下文时才通读；
• 改完代码后运行 graphify update . 保持图谱新鲜（纯 AST 增量、无 API 开销）。

uninstall 则只剥离 ## graphify 段落，不动 CLAUDE.md 中其他内容（install.py）。由于 claude_md 是 Windows 等平台在 install.py 平台表中开启的开关，配合“Windows 默认平台即 windows”的 CLI 默认逻辑（install.py），Windows 用户执行一次安装即可获得“图谱常驻”。对使用 AGENTS.md 规范的其他平台，等价命令是 graphify agents install（参见 agents 平台参考）。

使用建议与注意事项

综合参考文档与实现，实际落地时有几点值得注意：

1. 适合对“图谱产出”进行 git 跟踪的团队：钩子与 merge driver 相辅相成——多成员提交各自的增量图谱后，graph.json 由 git 自定义 merge driver 做 union 合并，避免冲突反复出现；
2. 文档/图片变更不会触发钩子：编辑 README、架构图、视频转写等后，需手动 graphify update .（或 skill 中的 /graphify --update），钩子只对代码文件负责；
3. 大规模仓库的提交体验：重建在脱离终端、后台进程中执行，提交本身即时返回；超时、跳过开关等控制面都通过环境变量暴露，适合接入 CI 或交给 Agent 按需调用；
4. 卸载干净利落：hook uninstall + claude uninstall 会移除钩子代码块、还原已有钩子内容，并剥离 CLAUDE.md 中的 ## graphify 段落，可放心随时回退。

对想在 Windows 上把 graphify 真正“融进日常开发流”的用户，这组集成把“图谱新鲜度”从手动纪律变成了 git 自身的职责：提交即重建，会话即感知——图谱不再是一次性产物，而是与代码同步演进的活基础设施。