graphify 提交钩子与 AGENTS.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/graphify本文聚焦 graphify 的两条“自动化”集成路径graphify hook install注册的git 提交钩子post-commit以及graphify amp install写入本地AGENTS.md的原生常驻规则。读完你就能把代码知识图谱接入日常 git 工作流——每次提交自动重建graphify-out/无需手工执行、无需常驻 watch 进程在 Amp 等 Agent 平台中让图谱在每次会话自动生效。对应的技能参考原文位于 graphify/skills/amp/references/hooks.md其 skillgen 生成快照为 tools/skillgen/expected/graphify__skills__amp__references__hooks.md。两条“常驻”路径的定位与适用场景graphify 本身把任意代码库连同文档、SQL schema、配置文件、PDF转化为可查询的知识图谱产物集中在graphify-out/下的graph.json与GRAPH_REPORT.md。图谱建好之后真正决定体验的是时效性代码改了图谱不更新查询就失去意义每次手敲命令又太繁琐。本篇对应的技能参考卡片明确其使用时机——当用户请求“安装 post-commit 钩子”或“把 graphify 接入项目的 AGENTS.md”时加载见源文档首行。它同时覆盖了两类互补场景git commit hook面向“人提交代码”的版本控制流用 git 机制触发无需后台进程、兼容任意编辑器native AGENTS.md integration面向“Agent 会话”的上下文注入让 Amp 在回答代码问题前先查图谱、改完代码后主动重建。值得先厘清的是graphify 源码中有两种名为 hook 的机制本文只讨论前者——机制触发点目的安装命令git commit 钩子post-commit / post-checkout每次git commit/ 切换分支自动增量重建图谱graphify hook installAgent PreToolUse 钩子守卫hook-guard/hook-checkAgent 调用 Read / 搜索工具前拦截“不看图谱就乱读源码”的访问graphify installClaude 等平台后者主要用于 Claude Code / Codex 等平台的会话前守卫与本文无关前者才是 git 工作流的自动化主体。一、graphify hook提交即重建的 git 钩子1.1 三个子命令技能参考文档给出的完整命令集如下graphify hook install # install graphify hook uninstall # remove graphify hook status # check在 CLI 层这三个子命令由 graphify/cli.py 分发直接调用 graphify/hooks.py 中导出的install()/uninstall()/status()对应源码graphify/hooks.py中的install、uninstall、status三个入口函数返回值会逐行打印到终端post-commit: installed at repo/.git/hooks/post-commit post-checkout: installed at repo/.git/hooks/post-checkout merge driver: registered (graphify-out/graph.json mergegraphify)也就是说graphify hook install实际一次性做三件事写入post-commit钩子、写入post-checkout钩子并在 git config 与.gitattributes中注册针对graph.json的 union merge driver用于分支合并时自动合并图谱文件。graphify hook status则以只读方式逐一报告post-commit、post-checkout、merge driver三者的安装状态见 graphify/hooks.py。1.2 每次 commit 发生什么参考文档描述的提交行为是每次git commit后钩子通过git diff HEAD~1找出本次变更的代码文件对这些文件重新执行 AST 抽取再重建graph.json与GRAPH_REPORT.md。对照 graphify/hooks.py 的post-commit钩子脚本完整链路如下定位变更文件git diff --name-only HEAD~1 HEAD脚本带有一个git diff --name-only HEAD的兜底分支兼容首次提交等无HEAD~1的情形。噪声过滤若变更全部落在graphify-out/内则直接退出——防止“图谱产物被纳入版本控制后反复触发重建循环”。变更注入把变更清单写入GRAPHIFY_CHANGED环境变量交给 Python 端的重建体处理。增量重建重建体调用 graphify/watch.py 中的_rebuild_code(root, changed_pathschanged, ...)只针对变更文件重跑确定性 AST 抽取不经过 LLM无 API 成本随后刷新graph.json与GRAPH_REPORT.md。重建体内部见 graphify/hooks.py还有两层自我保护超时熔断默认 600 秒由GRAPHIFY_REBUILD_TIMEOUT控制。POSIX 用SIGALRM非 POSIX 环境用守护线程os._exit(1)兜底超时不会无限挂起资源限制重建前先调用_apply_resource_limits()避免钩子重建抢占过多系统资源best-effort 附属动作若存在graphify-out/memory/工作记忆目录会顺带刷新reflections/LESSONS.md失败也绝不令钩子报错退出。1.3 “无后台进程”“兼容任何编辑器”背后的实现分离式启动参考文档强调“No background process needed - triggers once per commit, works with any editor”。拆开看有两层含义不需要常驻 watch 进程触发粒度是每次提交以及不阻塞 git 命令返回。源码里对应一个专门的跨平台“分离式启动”设计graphify/hooks.py。早期实现用nohup ... 后台化重建但 Git for Windows 自带的 MSYS shell 没有nohup/setsid导致“钩子静默失效、图谱悄悄过期”。现在的实现改为钩子先由外层小进程 spawn 一个完全脱离终端会话的 Python 子进程执行重建父进程随即返回。POSIX 侧使用start_new_sessionWindows 侧使用CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP并尽力附加CREATE_BREAKAWAY_FROM_JOB避免每次提交在 Windows Terminal 上弹出一个可见空窗口。重建日志统一追加到~/.cache/graphify-rebuild.log可用GRAPHIFY_REBUILD_LOG覆盖git 提交因此立即返回、不会卡住 shell。这一行为被测试锁定在 tests/test_hooks.py 中test_hooks_do_not_use_nohup断言生成脚本不再依赖nohuptest_hooks_use_cross_platform_detach断言使用了跨平台分离启动方案。1.4 追加而非覆盖与既有钩子和谐共存参考文档明确承诺“If a post-commit hook already exists, graphify appends to it rather than replacing it.”实现位于 graphify/hooks.py 的_install_hook新代码段以# graphify-hook-start/# graphify-hook-end标记包裹若文件里还没有这些标记则在原内容之后追加保留你或 Husky 等其他工具写的钩子逻辑若标记已存在则在原位置就地更新graphify 段而不产生重复。测试 tests/test_hooks.py 中test_install_appends_to_existing_hook与test_install_creates_hook分别验证了追加与新建两种路径。卸载则相反_uninstall_hook仅用正则剥离# graphify-hook-start到# graphify-hook-end之间的内容如果剥离后文件只剩#!/bin/sh之类的空壳才删除整个文件否则保留用户的其他钩子内容graphify/hooks.py。1.5 安全性与环境适配细节源码级为了让钩子在各类环境中“总是工作”钩子脚本还内置了多层防护理解它们有助于排查问题Python 解释器探测链钩子在安装时会钉住当时运行graphify hook install的解释器绝对路径_PINNED_PYTHON__随后依次探测graphify-out/.graphify_python文件、PATH 上的graphify启动器含解析 shebang、兼容 Windows.exe布局、uv tool 环境目录最后退回python3/python。探测使用importlib.util.find_spec而非整包 import避免冷启动拖慢每次提交。这样在 PATH 极简的 GUI git 客户端与 CI 里钩子也能工作rebase/merge/cherry-pick 期间自动跳过检测rebase-merge/、rebase-apply、MERGE_HEAD、CHERRY_PICK_HEAD后直接退出避免--continue被打断linked worktree 守卫git rev-parse --git-dir与--git-common-dir不一致说明处于git worktree中直接退出——避免在非主检出里写出“用户没要的孤儿图谱”也避免与git clean竞争删除graphify-out/确定性聚类脚本顶部export PYTHONHASHSEED0固定字符串键迭代顺序使 community 聚类结果可复现Windows 并行度收敛在WINDIR/MSYSTEM环境Git for Windows/MSYS默认GRAPHIFY_MAX_WORKERS1规避 GUI 客户端派生的脆弱管道句柄防止提交卡住显式设置仍以用户为准可跳过开关GRAPHIFY_SKIP_HOOK1可临时关闭两个钩子post-checkout也认这个开关见 graphify/hooks.py。1.6 顺带的分支切换重建与图谱合并虽然参考文档只提了 post-commitgraphify hook install同时会安装post-checkout钩子graphify/hooks.py。它只在真正的分支切换BRANCH_SWITCH 1且新旧 HEAD 不同、graphify-out/已存在时触发全量重建——因为切换分支可能改动任意文件此时不走增量路径。测试 tests/test_hooks.py 的test_install_creates_post_checkout_hook与test_uninstall_removes_post_checkout_hook覆盖了安装/卸载行为。此外安装时注册的graph.jsonmerge driver 让多人协作时图谱文件也能自动合并union 语义gitattributes 行形如graphify-out/graph.json mergegraphify。若仓库输出目录不是默认名则回退到默认名见 graphify/hooks.py。1.7 钩子只处理代码doc / image 变更需手动更新参考文档明确文档、图片等非代码文件的变更不会被钩子处理需要手动执行/graphify --update。原因从钩子脚本注释即可看出——“Auto-rebuilds the knowledge graph after each commit (code files only, no LLM needed)”。钩子的定位是廉价的确定性 AST 增量重建而 markdown 文档、图片、PDF 等语义文件抽取依赖 LLM 标注成本与机制都不同因此留给带--update增量模式的完整管线手动触发。对 Amp 平台而言对应的常驻规则在 AGENTS.md 中亦有体现见下节“改完代码运行graphify update .”。同理新增了非代码语料想进图谱、或希望做深度语义重建时也应手动跑更新而非依赖钩子。二、graphify amp install写入 AGENTS.md 的原生常驻规则2.1 安装与卸载参考文档给出在项目根目录执行一次即可让 graphify 在后续所有 Amp 会话中“常驻”graphify amp install # 写入 AGENTS.md 的 ## graphify 段 graphify amp uninstall # 移除该段CLI 分发见 graphify/install.py。非--project模式下_amp_install做两件事graphify/install.py把 Amp 技能文件复制到用户级技能目录~/.config/agents/skills/Amp 实际搜索的是.agents/skills与~/.config/agents/skills而不是旧版误写的~/.amp/skills安装时还会清理旧路径残留见_amp_legacy_cleanup调用_agents_install把一段以## graphify为标题的内容写入当前项目的AGENTS.md文件不存在则新建存在则用“替换或追加段落”的方式写入不会重复。若想连技能文件也放进项目随仓库提交、供 CI 或协作者复用加--project即可graphify amp install --project此时技能落在项目内.agents/skills/AGENTS.md 段落照常写入项目根graphify/install.py。卸载同理_agents_uninstall只按精确标题## graphify匹配段落并整段删除若 AGENTS.md 删空则删除该文件若还有其他内容则保留——匹配是整行精确匹配绝不会误删用户手写的### graphify之类子标题内容graphify/install.py。2.2 写入的段落到底“教”了 Agent 什么安装写入的段落来自仓库内的 always-on 模板 graphify/always_on/agents-md.md在 AMP 参考文档语境下即上述常驻机制的内容来源。其核心指令可归纳为四条规则先查图再回答遇到代码库问题时若graphify-out/graph.json存在先运行graphify query question获取 scoped 子图查关系用graphify path A B查聚焦概念用graphify explain concept——这些返回的子图通常远比整份GRAPH_REPORT.md或裸 grep 输出更小、更聚焦容忍“脏”产物钩子或增量更新后graphify-out/出现中间态文件是预期现象不得因此跳过 graphify只有任务本身关于“图谱过期/图谱输出错误”或用户明确说不用图时才允许跳过分层取用资料存在graphify-out/wiki/index.md时优先用它做宽泛导航GRAPH_REPORT.md仅在大局架构审视或 query/path/explain 提供的信息不足时才读改后自更新修改代码后运行graphify update .保持图谱最新仅 AST无 API 成本。于是参考文档所写的“instructs Amp to check the graph before answering codebase questions and rebuild it after code changes”便有了具体落点前两句对应“先查图”规则后一句对应“改后自更新”规则。安装完成后终端会提示对应平台“will now check the knowledge graph before answering codebase questions and rebuild it after code changes”并注明与 Claude Code 不同Amp 没有 PreToolUse 钩子等价物AGENTS.md 规则就是它的常驻机制见 graphify/install.py。三、两个机制配合使用的推荐工作流综合以上两点一份“提交即更新、会话即可用”的典型配置如下# 1. 在仓库内先构建一次完整图谱LLM 抽取 聚类 报告 graphify update . # 2. 安装 git 钩子此后每次 commit 自动增量重建AST-only、分离式后台运行 graphify hook install # 3. 接入 Amp 会话写入 AGENTS.md 的 ## graphify 常驻规则 graphify amp install # 之后日常开发 git commit -m ... # 提交自动触发增量重建git 立即返回 # 需要确认钩子状态时 graphify hook status # 检查 post-commit / post-checkout / merge driver graphify amp uninstall # 不再需要常驻规则时移除 AGENTS.md 段落关于时间线可以这样理解钩子保证图谱永远跟随 HEAD增量 AST毫秒到秒级开销、不阻塞提交AGENTS.md 保证 Agent任何会话都先想起图谱graphify query/path/explain工具前置。只有新增或改动 markdown/图片等语义语料时才需要手动跑一次完整更新——这是钩子刻意划出的边界也是保证钩子廉价可靠的前提。四、源码与测试导航若想继续深入验证以上机制可直接阅读仓库中对应实现与测试钩子实现全貌graphify/hooks.py解释器探测、分离式启动、rebase/worktree 守卫、安装/卸载/状态三入口、merge driver 注册均在文件内CLI 分发入口graphify/cli.pygraphify hook [install|uninstall|status]Amp / AGENTS.md 安装与卸载graphify/install.py_agents_install、_amp_install、_amp_uninstall及其平台分发 graphify/install.pyAGENTS.md 常驻段落模板graphify/always_on/agents-md.md钩子行为测试tests/test_hooks.py覆盖新建、追加、卸载、post-checkout、status、跨平台 detach、Windows 并行度限制等平台技能分发与安装入口graphify/main.pydispatch_install_cli的再导出与_PLATFORM_CONFIG中的amp定义。本技能参考的其余能力卡片query、update、transcribe、exports、add-watch 等位于 graphify/skills/amp/references其中 query 卡详细讲解graphify query的遍历语义update 卡讲解增量更新边界——与本文的“钩子只做代码增量、文档靠手动更新”互为印证。【免费下载链接】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），仅供参考