graphify 自动化接入：Git 提交钩子自动重建知识图谱与 CLAUDE.md/AGENTS.md 原生指令集成

本篇文章面向在 Claude Code、Cursor、Codex、Gemini CLI 与 Factory Droid 等场景下使用 graphify 的开发者，系统讲解两条「免手工 /graphify」的常驻化路径：其一是通过 graphify hook install 安装 post-commit Git 钩子，让每次 git commit 后自动增量重建 graph.json 与 GRAPH_REPORT.md，无需后台常驻进程；其二是通过 graphify claude install 把 ## graphify 指令写入项目根目录的 CLAUDE.md（或 AGENTS.md），让 Agent 在会话中默认先查询图谱、改码后自动更新图谱。文章以该参考文档为核心，并结合仓库内 graphify/hooks.py、graphify/install.py 等实现源码，补充其底层运行机制、可调环境变量与故障排查要点，让读者既能照命令上手，也能理解钩子为何可靠、何时会静默跳过。

一、参考文档定位：一张「钩子 + 常驻指令」的速查卡

本主题的原始依据是 droid skill 下随取随载的参考文档 graphify/skills/droid/references/hooks.md。该文档声明了自己的触发条件（"Load this when the user asked to install the post-commit hook or wire graphify into a project's CLAUDE.md"），因此它是给 Agent 在用户提出「安装提交后钩子 / 把 graphify 接入项目记忆文件」这类请求时即时调用的一张最小操作卡。

它的正文只覆盖两个彼此正交的主题：

主题	解决的问题	核心命令
Git 提交钩子（post-commit hook）	每次 git commit 后自动增量重建知识图谱	graphify hook install / uninstall / status
原生 CLAUDE.md 集成	让 graphify 在后续会话中「常驻生效」，无需手动 /graphify	graphify claude install / uninstall

仓库内每个 skill 目录（agents、claude、codex、droid、kiro、opencode 等）都维护了一份几乎同构的 hooks.md，差异仅在「写入 CLAUDE.md 还是 AGENTS.md、对应命令是 claude 还是 agents/droid」。这一点在源码层面有明确佐证：graphify/main.py 的 help 文本分别说明 claude install 是 "write graphify section to CLAUDE.md + PreToolUse hook"，而 droid install（Factory Droid）等平台是 "write graphify section to AGENTS.md"；graphify/install.py 的注释也写明 "AGENTS.md covers: codex, aider, opencode, claw, droid, trae, trae-cn, hermes, copilot"。下文以参考文档原文为准，并在对应小节点出这一平台差异。

二、Git 提交钩子：提交即重建，无后台进程、适配任何编辑器

2.1 三条命令的安装 / 卸载 / 状态检查

参考文档给出的最小操作就是三个子命令，由 graphify/cli.py 的 hook 分支分发到 graphify/hooks.py 中的同名 install()、uninstall()、status()：

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

• install 会在最近的 Git 仓库（自当前目录向上查找 .git，见 hooks.py 的 _git_root）安装 post-commit 钩子；找不到仓库时直接抛错提示。
• status 是只读诊断，输出 post-commit、post-checkout 与 merge driver 三者的安装状态。
• 三者均尊重 core.hooksPath（例如 Husky），通过 git rev-parse --git-path hooks 解析真实钩子目录，避免手写 .git/config 解析在重复键/includeIf/linked worktree 等场景下出错（对应 hooks.py）。

2.2 触发后的实际行为：只重建变更文件

参考文档描述的核心语义是：每次 git commit 之后，钩子检测哪些代码文件发生了变化（经 git diff HEAD~1），只对这些文件重跑 AST 提取，然后重建 graph.json 与 GRAPH_REPORT.md；整个过程不需要任何后台进程，每次提交只触发一次，与编辑器无关。

源码印证了这一描述，并且揭示了更多细节：

1. 变更集探测：hooks.py 先执行 git diff --name-only HEAD~1 HEAD，在首个提交等无父提交的边界下回退到 git diff --name-only HEAD。
2. 避免自触发循环：若变更文件全部落在 graphify-out/ 内（即本次提交只改了图谱产物本身），钩子直接 exit 0，不会陷入「重建→提交→再重建」的死循环。
3. 把变更集交给重建器：钩子将变更清单导出为环境变量 GRAPHIFY_CHANGED，随后由 Python 重建体读取并传给 graphify.watch._rebuild_code(root, changed_paths=...) 做增量更新——只对变动的文件重跑 AST 提取，而非全量重扫。
4. 幂等安装、追加而非覆盖：这是参考文档明确强调的一点——若目标仓库已存在 post-commit 钩子，graphify 用 # graphify-hook-start / # graphify-hook-end 一对标记把自身脚本块追加到现有钩子末尾，绝不覆盖用户原有内容；重新安装同版本时原地替换并报告 "already installed"，保证幂等（见 hooks.py 的 _install_hook）。

2.3 文档 / 图片变更：钩子不处理，走手动更新

参考文档明确划定了边界：文档与图片文件的变更会被钩子忽略，这类内容需要手动执行 /graphify --update（会话内技能命令；等价 CLI 为 graphify update .）来刷新图谱。原因在代码中清晰可见：提交钩子的重建体仅对 git diff 出来的、被 changed_paths 携带的文件调用 _rebuild_code，而该增量路径面向的是代码 AST 提取；语义（文档/PDF/图片）抽取需要 LLM 或额外管线，不在「零 LLM 的代码钩子」职责内。因此推荐把钩子理解为代码图的自动保鲜器，把语义文档更新理解为有意识的、低频的手动动作。

2.4 源码级加固：为什么它足够可靠

参考文档虽未展开，但其设计的健壮性在源码中有大量注释与测试背书（相关断言集中在 tests/test_hooks.py）。以下是从 graphify/hooks.py 可直接核实的加固点：

• 不阻塞提交（detached launch）：旧实现曾用 nohup ... & 后台化重建，但 Git for Windows 的 MSYS shell 没有 nohup/setsid，导致重建静默失败；现在改为用 Python 自身做跨平台分离启动（POSIX 用 start_new_session，Windows 用 CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP），钩子进程在 spawn 出子进程后立即返回，git commit 不被拖慢。测试用例 test_hooks_do_not_use_nohup、test_hooks_use_cross_platform_detach、test_detached_launch_targets_graphify_python 直接锁定了这一契约。
• 解释器探测与固定（pinned interpreter）：uv tool / pipx 安装下，graphify 启动器位于隔离 venv，而 GUI Git 客户端与 CI 的 PATH 往往不含 ~/.local/bin。hook install 因此把当前 sys.executable 的绝对路径直接嵌入钩子脚本（README 亦在 README.md 提示：升级或重装 graphify 后需重跑 graphify hook install 刷新该内嵌路径）；运行时再以 find_spec 探测多级回退（固定路径 → graphify-out/.graphify_python → PATH 上的启动器 shebang → uv tool 目录 → python3/python），见 hooks.py。
• 确定性输出：钩子内 export PYTHONHASHSEED=0，避免 louvain 社区聚类因 PYTHONHASHSEED 随机化产生 run-to-run 抖动，使 graphify-out 产物可复现。
• rebase/merge/cherry-pick 期间自动跳过：rebase-merge/rebase-apply 目录存在或存在 MERGE_HEAD/CHERRY_PICK_HEAD 时直接退出，避免阻塞 --continue 流程。
• linked worktree 保护：当 git rev-parse --git-dir 与 --git-common-dir 解析后不一致（说明处于附加 worktree）时跳过重建，防止在非主检出目录写入「幽灵增量图」并干扰部署流水线的 git clean。
• 超时与资源控制：重建体通过 _apply_resource_limits() 施加资源限制，并以 GRAPHIFY_REBUILD_TIMEOUT（默认 600 秒）设置 SIGALRM / 看门狗计时；超时打印错误但不会挂死提交。运行日志默认追加到 ~/.cache/graphify-rebuild.log（可用 GRAPHIFY_REBUILD_LOG 覆盖）。
• 显式退出口：设 GRAPHIFY_SKIP_HOOK=1 可单次/永久跳过触发。

2.5 hook install 附带的额外能力：post-checkout 与 merge driver

graphify hook install 实际交付的内容比参考文档列举的三条命令更完整（卸载/状态输出会把它们一并列出）：

1. post-checkout 钩子：切换分支时若 graphify-out/ 已存在则触发一次全量代码重建（分支切换可能改动任意文件，不宜走增量），且仅在真正的分支切换（$3 == 1）且 HEAD 确有变化时执行。
2. graph.json 的 union merge driver：为多人协作注册 merge.graphify 驱动，并在 .gitattributes 写入 <out>/graph.json merge=graphify 行，使 graph.json 合并冲突时自动做并集合并、永不出现冲突标记。README 在 README.md 对此有说明，实现见 hooks.py 的 _register_merge_driver。

2.6 关联的 CLI 子命令与可调参数速查

钩子最终驱动的是 graphify update <path>（增量更新，AST-only、无需 API key；另有 --force 覆盖更少节点场景、--no-cluster 跳过聚类）与 graphify watch <path>。参考文档中的 graphify hook 系列命令含义如下：

环境变量 / 配置	默认值	作用
GRAPHIFY_OUT	graphify-out	图谱输出目录（支持相对/绝对，也可在 .graphify_root 中记录实际根）
GRAPHIFY_REBUILD_TIMEOUT	600（秒）	重建超时；设为 0 表示不限制
GRAPHIFY_FORCE	空	1/true/yes 时强制覆盖写入（即使节点数变少）
GRAPHIFY_SKIP_HOOK	0	设为 1 跳过钩子触发
GRAPHIFY_REBUILD_LOG	~/.cache/graphify-rebuild.log	重建日志路径（钩子不阻塞，排查靠它）
GRAPHIFY_MAX_WORKERS	CPU 数	并行度；Windows/MSYS 环境默认强制为 1
.graphifyrc 的 viz_node_limit	未设置	以 GRAPHIFY_VIZ_NODE_LIMIT 烘焙进钩子的可视化节点上限默认值

三、原生 CLAUDE.md / AGENTS.md 集成：让 graphify 每次会话「常驻」

3.1 claude install：一次性写入，永久生效

参考文档给出第二条路径：对每个项目执行一次

graphify claude install

即可让 graphify 在 Claude Code 会话中常驻开启。其含义是：向项目根目录的 CLAUDE.md 写入一个 ## graphify 区块，区块指示 Claude「在回答代码库问题前先查图谱、在代码变更后重建图谱」；此后新会话不再需要手动敲 /graphify。对应的卸载命令为：

graphify claude uninstall  # remove the section

实现位于 graphify/install.py 的 claude_install()：目标文件存在时用 _replace_or_append_section 按标记做幂等替换/追加（已有旧版区块则原位更新），不存在则直接写入；内容取自打包好的 ## graphify 区块。随后 claude_install 还会无条件重装 Claude Code 的 PreToolUse 钩子（写入 .claude/settings.json，见 install.py），保证升级后旧版钩子载荷被替换。卸载时 claude_uninstall 移除 CLAUDE.md 区块，并同时清理 .claude/settings.json 与 settings.local.json 里的 graphify 钩子。

3.2 区块里究竟写了什么

## graphify 区块的内容是打包的 Markdown 片段，存放于 graphify/always_on/claude-md.md（CLAUDE.md 用）与 graphify/always_on/agents-md.md（AGENTS.md 用）。以 agents-md.md 为例，其核心指令可归纳为三条：

1. 先查询，再 grep：回答代码问题前，若 graphify-out/graph.json 存在，先运行 graphify query "<question>"；关系用 graphify path "<A>" "<B>"，聚焦概念用 graphify explain "<concept>"。这些返回的是范围化子图，通常远小于 GRAPH_REPORT.md 或原始 grep 输出。
2. 脏图不是跳过理由：钩子或增量更新后 graphify-out/ 出现未整理产物是预期现象；除非任务本身涉及「图谱过期/错误」或用户明确要求，否则不应跳过 graphify。
3. 改码必更新：修改代码后运行 graphify update . 保持图谱最新（AST-only，零 API 成本）。

（注：具体措辞以对应 always_on 文件为准，不同平台安装的区块文本会引用本平台习惯的 Agent 名。）

3.3 平台变体：Claude Code 之外的 AGENTS.md 阵营

参考文档隶属于 droid skill，正文以 claude install + CLAUDE.md 为例；但同一份操作卡在其他 skill 下对应不同平台命令，机制完全一致：

• Claude Code → graphify claude install，写 CLAUDE.md；
• Factory Droid（droid）、Codex、Aider、OpenCode、Claw、Trae 等 → graphify droid install（及各自命令），写根目录 AGENTS.md。

这些平台的安装/卸载统一经 graphify/install.py 注释所言的 AGENTS.md 阵营分发到 _agents_install/_agents_uninstall，并在 graphify/main.py 的 help 中逐个列出。因此若你用的是 Factory Droid 而非 Claude Code，把参考文档命令中的 claude 换成 droid、目标文件换成 AGENTS.md 即为等价操作。graphify uninstall 也会一次性清理所有已检测平台的区块与钩子（install.py）。

四、端到端推荐工作流

综合参考文档与 README 中「Recommended workflow」的指引（README.md、README.md），一个团队仓库的推荐接入流程如下：

1. 克隆仓库后执行一次 graphify hook install——它会一次性装好 post-commit、post-checkout 钩子，并注册 graph.json 的 union merge driver（避免团队冲突时出现冲突标记）。
2. 按你的 Agent 平台执行一次常驻集成：Claude Code 用 graphify claude install；Droid/Codex 等读 AGENTS.md 的平台用 graphify droid install（或对应平台命令）。
3. 日常提交即自动增量重建代码图；git pull 拉取他人改动后建议手动跑一次 graphify update . 补齐（README 把这一步列为与钩子配合的显式动作）。
4. 用 graphify hook status 确认钩子状态；若曾升级/重装 graphify（解释器路径变化、钩子载荷过期），重跑 graphify hook install 刷新内嵌解释器路径与载荷。

五、验证方式与故障排查

5.1 自动化测试佐证

graphify/hooks.py 的行为由 tests/test_hooks.py 系统锁定，可作为行为契约阅读：

• 幂等与追加语义：test_install_idempotent、test_install_appends_to_existing_hook；
• 可执行位与路径解析：test_install_is_executable、test_hooks_dir_accepts_absolute_git_hooks_path、test_posix_custom_hookspath_still_works、test_windows_hookspath_rejected_no_junk_dir_on_posix（POSIX/WSL 下误传 Windows 风格 hooks 路径会大声报错而非创建垃圾目录）；
• 卸载与状态：test_uninstall_removes_hook、test_status_shows_both_hooks、test_uninstall_removes_post_checkout_hook；
• 跨平台启动细节：test_hooks_do_not_use_nohup、test_hooks_use_cross_platform_detach、test_hooks_limit_windows_workers_by_default、test_probes_use_find_spec_not_full_import（探测用 find_spec 而非整体 import，避免每次提交前冷启动 10s+ 的包导入）；
• 内嵌载荷安全性：test_launcher_payload_is_shell_quote_safe、test_installed_hooks_contain_no_nohup。

5.2 常见问题定位思路

• 提交后图谱没有更新：先查重建日志（默认 ~/.cache/graphify-rebuild.log，或 GRAPHIFY_REBUILD_LOG 指定路径）；若日志提示定位不到 Python，说明钩子内嵌的解释器路径已失效——用安装 graphify 的同一环境重跑 graphify hook install。
• 钩子被跳过而非报错：钩子对 rebase/merge/cherry-pick、linked worktree、graphify-out/ 专属提交、GRAPHIFY_SKIP_HOOK=1 都设计为静默 exit 0，这是刻意的 fail-soft 行为，不是故障。
• 只想临时不触发：GRAPHIFY_SKIP_HOOK=1 git commit ... 即可，无需卸载。
• 文档/图片改了图没动：符合设计——语义类变更请手动 /graphify --update 或 graphify update .。
• 确认安装状态：graphify hook status 会分项报告 post-commit、post-checkout 与 merge driver 的状态，还会提示钩子与 .graphifyrc 中 viz_node_limit 不一致等「已安装但过期」的情形。

结语

把「提交后自动增量重建」与「Agent 会话常驻指令」两者叠加，graphify 就获得了近似 watch 服务的保鲜能力，却不需要任何后台守护进程：代码变更由 Git 事件自然驱动（每次提交至多触发一次、与编辑器无关），语义文档变更保留为显式的手动动作，而对 Agent 而言，图谱的存在与用法通过 CLAUDE.md/AGENTS.md 区块在每次会话开始时即可见、可执行。若需深入底层，可继续阅读 graphify/hooks.py（钩子模板与解释器探测）、graphify/watch.py（_rebuild_code 增量重建入口）与 tests/test_hooks.py（行为契约）。