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

本篇技术指南围绕 graphify 的 hooks 参考文档展开，讲解如何通过 graphify hook install 安装 post-commit 钩子，让知识图谱在每个 git commit 后自动增量重建，以及如何通过 graphify claude install 把 graphify 原生接入 Claude Code 的 CLAUDE.md，实现"会话内无需手动执行 /graphify"的常驻模式。读完你将掌握两条完整落地链路：git 提交即重建的自动化流程，以及 Claude Code 会话中按需检查、代码变更后自动重建的知识图谱工作流。

参考文档定位：Agent 技能引用与打包产物

该文档在仓库中承担"技能引用页"（reference）角色，供安装到各平台的 graphify skill 在遇到"安装 post-commit 钩子 / 把 graphify 接入项目 CLAUDE.md"这类请求时按需加载。仓库里存在两份完全一致的内容：

• 技能分发源：graphify/skills/droid/references/hooks.md；
• 打包校验基线：tools/skillgen/expected/graphify__skills__droid__references__hooks.md。

其中 droid 平台对应 .factory/skills/graphify/ 安装目标（见 graphify/install.py 中 _PLATFORM_CONFIG 的 droid 条目），tools/skillgen 则负责生成并校验各平台的 skill 与引用页不会发生漂移。文档开头的加载说明（"Load this when..."）体现了渐进式披露（progressive disclosure）的设计：技能主体保持精简，具体操作细节延迟到 references 中按需读取。

一、git post-commit 钩子：提交一次，图谱自动更新一次

文档给出的三条命令构成了钩子管理的完整闭环：

graphify hook install    # install
graphify hook uninstall  # remove
graphify hook status     # check

与"常驻后台进程 + 文件监听"的方案不同，post-commit 钩子每提交触发一次，不依赖后台守护进程，因此对任何编辑器、GUI 客户端与 CI 环境都生效——只要提交发生在 git 仓库内。CLI 分发逻辑位于 graphify/cli.py 的 hook 分支（install/uninstall/status 三个子命令），真正的实现则集中在 graphify/hooks.py。

提交后发生了什么

一次 git commit 之后，钩子会执行以下三步：

1. 识别变更文件：通过 git diff --name-only HEAD~1 HEAD（首次提交或空历史时回退到 git diff --name-only HEAD）得到本次提交改动的文件清单；
2. 增量提取：只对这些变更文件重新执行确定性 AST 提取，而非全量重建；
3. 重建产物：把变更合并进既有结果，重新生成 graph.json 与 GRAPH_REPORT.md。

重建核心复用 graphify/watch.py 的 _rebuild_code，钩子仅作为触发壳，确保逻辑与交互式 /graphify --update 完全同源。文档特别强调：文档与图片类变更会被钩子忽略——这类资源需要语义级理解，应手动执行 /graphify --update 触发完整管道处理。

增量重建的真实语义（源码级细节）

从 graphify/hooks.py 的钩子脚本体可以看到"增量"二字背后的工程细节，远不止"提交后跑一遍"：

• 变更列表通过环境变量传递：_HOOK_SCRIPT 把 CHANGED 导出为 GRAPHIFY_CHANGED，重建体按行解析为路径列表；若为空（如钩子被手动执行且无有效 diff）直接 exit 0；
• 产物目录自触发保护：当变更清单全部落在 graphify-out/ 下时直接退出，避免"图谱产物入库 → 提交产物 → 又触发重建"的死循环；
• rebase/merge/cherry-pick 期间自动跳过：检测到 rebase-merge、rebase-apply 目录或 MERGE_HEAD、CHERRY_PICK_HEAD 即退出，防止重建阻塞 --continue 并干扰尚未稳定的工作区状态；
• 支持非当前目录的仓库根：重建前读取 graphify-out/.graphify_root，若存在则以其中的记录为仓库根，钩子也能服务于根目录之外的子目录场景；
• 可随时一键关闭：GRAPHIFY_SKIP_HOOK=1 环境变量是全局开关，不希望某次提交触发重建时无需卸载钩子。

后台分离式重建：git 永不阻塞

全量重建可能耗时很久，钩子绝不能阻塞提交终端。实现上采用了跨平台的"分离式启动"（detached launch）方案：_detached_launch 生成一行 shell，调用 Python 的 subprocess.Popen 启动真正重建子进程并立刻返回。POSIX 下使用 start_new_session=True（等价 setsid），Windows 下使用 CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP 标志位组合——这一设计直接回应了历史问题：Git for Windows 的 MSYS shell 不带 nohup/setsid，旧的 nohup ... & 写法在 Windows 上会静默失效，导致图谱悄然过期。

重建日志统一写入 ~/.cache/graphify-rebuild.log（可用 GRAPHIFY_REBUILD_LOG 覆盖）。此外，钩子还做了确定性处理：脚本开头 export PYTHONHASHSEED=0，让 networkx louvain 等依赖字符串哈希序的聚类算法结果稳定可复现；在 Windows/MSYS 环境下默认把 GRAPHIFY_MAX_WORKERS 收敛为 1，规避 GUI 客户端继承的脆弱管道句柄。

与既有钩子共存：追加而非覆盖

文档强调的"若已存在 post-commit 钩子则追加"在源码中得到精确实现：_install_hook 先检查目标文件是否已含 # graphify-hook-start / # graphify-hook-end 标记——已有标记则就地原位更新（升级安装时自动替换旧版逻辑），无标记则在文件末尾追加，绝不破坏用户或其他工具（如 Husky）已有的钩子内容；卸载时 _uninstall_hook 只剥离两个标记之间的区段。需要说明的是，从 graphify/hooks.py 的 install() 返回值看，graphify hook install 实际会同时安装 post-commit 与 post-checkout 两个钩子并注册 merge driver，其中 post-checkout 只在分支切换（$3 == 1）且 graphify-out/ 已存在时触发全量重建，用于分支跳转后图谱与代码一致。

二、status 子命令：图谱自动化的体检工具

除安装与卸载外，graphify hook status 提供只读诊断，输出格式与安装/卸载保持对称的三行结构：

post-commit: installed
post-checkout: installed
merge driver: registered

从 graphify/hooks.py 的 status() 实现看，其检查维度包括：钩子文件是否存在、是否含 graphify 标记、.graphifyrc 中配置的 viz_node_limit 是否与钩子内烘焙值一致（不一致会提示 "out of date"），以及 merge driver 在 git config 与 .gitattributes 两侧是否都就位。这一命令在生产排障中非常实用——钩子"静默失效"常源于安装环境与触发环境不一致，状态行能快速定位问题层。

三、原生 CLAUDE.md 集成：让 graphify 在 Claude Code 中常驻

文档给出的第二条集成路径面向 Claude Code 会话：

graphify claude install

每个项目执行一次，即可让 graphify 在 Claude Code 会话中"always-on"。其效果是向项目根目录的本地 CLAUDE.md 写入一个 ## graphify 段落，指示 Claude 在回答代码库问题前先检查知识图谱、在代码变更后重建图谱。此后无需在新会话中手动调用 /graphify——这正是它与"斜杠命令手动触发"模式的关键差异。卸载同样简单：

graphify claude uninstall  # remove the section

## graphify 段落是如何写入的

命令入口是 graphify/install.py 的 claude_install()。其写入动作并非简单字符串拼接，而是调用 _replace_or_append_section()：

• 段落以精确等于 ## graphify 的行作为锚点（不允许作为子串出现，避免误伤用户手写内容里对 graphify 的普通提及），从该标题延续到下一个 H2（## ）或文件末尾；
• 若文件已存在同名段落则原地替换，保证升级安装后 CLAUDE.md 拿到最新版本的行为指引；
• 若不存在则追加到文件尾部，已有的手写内容（如项目自身的架构约定）全部保留；
• 当 CLAUDE.md 尚不存在时直接创建新文件。

被写入的段落正文来自打包资源 graphify/always_on/claude-md.md，由 tools/skillgen 从统一维护的片段生成。

常驻模式并不止于"一段文字"

从 graphify/install.py 的实现可以看到，graphify claude install 在写入 CLAUDE.md 之外还会同步完成三件配套工作：

1. 安装 Claude Code PreToolUse 钩子：向项目 .claude/settings.json 写入 Bash|Grep（搜索）与 Read|Glob（读取）两条 matcher 对应的 hook-guard 命令。这属于 graphify/main.py 中的 hook-guard 子命令，作用是当图谱新鲜就绪时，在 Claude 执行搜索/读取前通过 additionalContext 轻推其优先查询图谱（_run_hook_guard 以 JSON 负载而非退出码工作，始终返回 0，永不打断工具调用）；
2. 可选 --strict 严格模式：安装时传入 --strict，则首个原始文件读取会被拦截，直到会话内完成一次 graphify query，强制 AI 先看图再读码；运行时可用 GRAPHIFY_HOOK_STRICT 环境变量随时开启/关闭而无需重装；
3. 写入后提示：命令结束会明确告知"Claude Code will now check the knowledge graph before answering codebase questions and rebuild it after code changes"。

之所以把 CLAUDE.md 段落与 settings 钩子合在一起做，是因为二者互补：CLAUDE.md 提供"常驻行为指令"，settings 钩子提供"工具调用时刻的即时引导"，共同实现文档所述的"检查-再回答、变更-即重建"。

卸载的对称性与范围控制

graphify claude uninstall 会做全量反向清理（见 claude_uninstall()）：删除技能树（SKILL.md + references/）、从 CLAUDE.md、CLAUDE.local.md、.claude/CLAUDE.local.md 中剥离 ## graphify 段落（标题同样要求精确匹配，杜绝误删用户手写的 ### graphify），并从 .claude/settings.json 与 .claude/settings.local.json 中移除 PreToolUse 钩子。项目级 --project 安装产生的本地文件与用户级全局技能互不干扰，卸载作用域清晰可预期。

四、两个集成点的协同工作流

把两条路径串联起来，就构成了一套无需任何后台进程的完整自动化闭环：

日常开发
  ├─ 写代码 → git commit
  │    └─ post-commit 钩子：增量 AST 提取 → 重建 graph.json / GRAPH_REPORT.md
  ├─ 切换分支
  │    └─ post-checkout 钩子：全量重建图谱（若 graphify-out/ 已存在）
  └─ Claude Code 会话
       ├─ CLAUDE.md ## graphify 段落：常驻指令（先查图谱再回答）
       ├─ PreToolUse 钩子：搜索/读取前 nudge 优先走 graphify query
       └─ 代码变更后：自动触发重建，图谱保持新鲜

文档中"doc/image changes are ignored by the hook - run /graphify --update manually"的边界说明在这里尤为关键：提交钩子只负责代码的确定性增量，而 Markdown、图片、PDF 等非代码资源需要在 Claude 会话中通过 /graphify --update 触发完整的语义提取管道，二者分工明确。

五、自动化相关的环境变量与配置速查

综合钩子脚本与安装实现，以下变量/配置直接影响钩子行为（均可在 graphify/hooks.py 源码中印证）：

名称	默认值	作用
GRAPHIFY_SKIP_HOOK	未设置	设为 1 时临时跳过本次提交触发的重建
GRAPHIFY_REBUILD_TIMEOUT	600（秒）	重建超时上限，超时记录到日志并退出（不阻塞 commit）
GRAPHIFY_FORCE	关闭	置为 1/true/yes 时强制全量重建而非增量
GRAPHIFY_OUT	graphify-out	图谱产物输出目录
GRAPHIFY_REBUILD_LOG	~/.cache/graphify-rebuild.log	分离式重建的后台日志路径
GRAPHIFY_MAX_WORKERS	未设置	并发提取上限；Windows/MSYS 环境默认降为 1
GRAPHIFY_VIZ_NODE_LIMIT	.graphifyrc 可选配置	可视化节点数上限，经 .graphifyrc 的 viz_node_limit 烘焙进钩子，运行期仍可用环境变量覆盖

.graphifyrc 支持 key=value 格式的 viz_node_limit=整数 配置（要求非负整数），解析与校验逻辑在 _load_graphifyrc() 中；status 会同时校验钩子内烘焙值与当前配置文件是否一致。

六、集成后的验证路径

安装完成后建议依次验证：

1. graphify hook status 确认 post-commit / post-checkout / merge driver 三行均为就绪状态；
2. 提交一次纯代码改动，观察终端出现 [graphify hook] launching background rebuild，随后在 ~/.cache/graphify-rebuild.log 查看重建结果；
3. 在 Claude Code 新会话中直接提问代码库问题，观察是否无需手动 /graphify 即可命中图谱数据（说明 CLAUDE.md 段落已生效）；
4. 查看 tests/test_hooks.py 与 tests/test_hook_guard.py 等测试，理解仓库对钩子追加、标记剥离、严格模式与各类边界条件的回归保障。

无论是单人维护还是团队协作，这套"提交即重建 + CLAUDE.md 常驻 + 工具钩子引导"的组合都能让代码知识图谱始终与仓库真实状态对齐——图谱不再是需要刻意维护的额外资产，而是融入日常 git 工作流的自然产出。