graphify × Gemini CLI:让 AI 助手优先查询代码知识图谱的 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/graphifygraphify 会把任意代码库连同其文档、SQL schema、配置文件一起解析为本地确定性 AST 知识图谱。本文以 gemini-md.md 这个 Gemini CLI 专用常驻指令块为主体,逐条拆解它写入项目GEMINI.md的四条图谱优先工作规则,并结合 install.py 的安装器源码与 test_gemini_hook.py 的测试,说明这套指令如何通过graphify install --platform gemini落地、又被 BeforeTool hook 如何实时提醒AI 走图谱路径,读完后你可以完整复现 Gemini CLI graphify 的接入与日常使用闭环。一、它是什么:写在 GEMINI.md 里的常驻规则块gemini-md.md 只有短短十行,但它是 graphify 为 Gemini CLI 定制的always-on指令块——一段会在每次会话中被 Gemini CLI 读取、并长期生效的行为约束。原文完整内容如下:## graphify This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: - For codebase questions, first run graphify query question when graphify-out/graph.json exists. Use graphify path A B for relationships and graphify explain concept for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).它的定位非常清晰:声明事实 四条规则。开头一句向 AI 声明本项目在graphify-out/目录下已有一份包含 god nodes(枢纽节点)、community structure(社区结构)与跨文件关系的知识图谱;随后四条规则规定了 AI 回答代码库问题时的信息检索次序——先查图谱、再查 wiki 导航、最后才读完整报告,改完代码还要刷新图谱。这四条规则构成了整篇文章的展开主线。二、四条规则逐条解读规则 1:代码问题先查图谱——query / path / explain 三级查询这是四条规则中信息量最大的一条,它给了 Gemini 三个分层工具:命令用途CLI 完整用法(摘自 cli.py 的 Usage 提示)graphify query question面向自然语言问题的范围化子图检索graphify query question [--dfs] [--context C] [--budget N] [--graph path]graphify path A B查询两个节点之间的关系路径graphify path source target [--graph path]graphify explain node聚焦解释某个概念/节点graphify explain node [--graph path]规则原文强调的前提是graphify-out/graph.json exists——即只有当图谱确实构建过,才走查询路径,避免空图查询。三条命令返回的都是scoped subgraph(范围化子图),指令块明确指出其体积通常远小于 GRAPH_REPORT.md 或裸 grep 的输出。这正是 graphify 的核心卖点:用一份小得多的上下文回答代码库问题,而不是让模型去读整个报告或大海捞针式地 grep。从源码结构看,query在 cli.py 中被实现为基于graphify.serve._query_graph_text的图上检索,并保持图无向以支持 BFS/DFS 探索;path与explain则强制使用有向视图。三种查询执行后都会调用querylog.log_query记录查询日志,并写入查询时间戳,为 hook 的近期是否查过图判断提供依据。规则 2:用 wiki 做宽泛导航第二条规则要求:如果graphify-out/wiki/index.md存在,就用它做宽泛导航,而不是直接翻原始源码。graphify 构建图谱时会同步产出一个 markdown 形式的 wiki 索引(见 wiki.py),相当于给整个代码库生成了一份目录页。这条规则的意义在于把浏览这一动作从逐文件打开,升级为沿 wiki 层级跳转,既省上下文窗口,也避免模型在目录树里迷路。规则 3:GRAPH_REPORT.md 只作最后兜底第三条规则刻意降权了graphify-out/GRAPH_REPORT.md:它只应在两种场景被读取——做全局架构评审时,或者query/path/explain三者都没有给出足够上下文时。仓库内 worked/httpx/GRAPH_REPORT.md 这类报告可以看到其形态:整库级的社区划分与枢纽节点综述,信息密度高但体积大,适合作为地图总览而非问题答案。指令块把阅读次序硬编码为:子图查询 → wiki 导航 → 完整报告,本质是一份针对 AI 的渐进式信息披露(progressive disclosure)策略。规则 4:改完代码必须graphify update .最后一条规则规定了图谱保鲜义务:修改代码之后运行graphify update .。括号里的 (AST-only, no API cost) 点明了它的成本模型——增量更新只走本地确定性 AST 解析,不产生任何 LLM API 费用。这与 graphify本地解析、每条边可解释、不依赖向量库的整体设计一致:图谱可以低成本地随代码演进,而不需要重新花钱全量重建。三、指令块如何进入 GEMINI.md:installer 源码级走读gemini-md.md 只是包内的源文件,真正把它变成项目规则的是 install.py 中的gemini_install(第 707 行起)。执行graphify install --platform gemini时会发生三件事:拷贝技能文件:_copy_skill_file(gemini, ...)把包内skill.md原样拷入~/.gemini/skills/graphify/SKILL.md(项目级安装则是.gemini/skills/graphify/SKILL.md),并附带references/渐进式文档与.graphify_version版本戳;写入 GEMINI.md 规则段:以## graphify作为 section 标记,通过_replace_or_append_section将 gemini-md.md 的内容幂等地写入或替换到项目根目录的GEMINI.md(见 install.py)。替换是关键:旧版本安装留下的过时措辞会在升级时被整段覆盖,用户无需卸载重装;注册 BeforeTool hook:向.gemini/settings.json的hooks.BeforeTool数组追加一条钩子(见 install.py)。其中 section 替换函数_replace_or_append_section有一个值得注意的健壮性设计:它只在某一行精确等于## graphify(去除首尾空白后)时才算命中,绝不做子串匹配;section 范围延伸到下一个 H2 标题之前。注释里说明这是为了避免历史上子串误匹配删掉用户手写内容的缺陷——对用户自维护的GEMINI.md来说,精确边界是安全底线。卸载时gemini_uninstall用同样精确匹配的_remove_marker_section反向清理,若清完后文件为空则直接删除GEMINI.md。四、BeforeTool hook:规则 1 的运行时第二保险GEMINI.md里的规则是软约束(依赖模型自觉遵守),graphify 还配了一条硬提醒。_gemini_hook(install.py)生成的钩子形如:{ matcher: read_file|list_directory, hooks: [{ type: command, command: graphify 可执行路径 hook-guard gemini }] }即:每当 Gemini CLI 调用read_file或list_directory工具前,都会先执行graphify hook-guard gemini。它的行为由 tests/test_gemini_hook.py 完整固化:永不拦截:无论图谱是否存在,返回的 JSON 恒为{decision: allow},工具调用不会被 hook 阻断;有图谱就提醒:当前目录存在graphify-out/graph.json时,在additionalContext中追加先用graphify query的引导文本(测试test_allows_and_nudges_with_graph断言该文本包含graphify query);无图谱则静默:没有图谱时不附加任何上下文,避免噪音;尊重输出目录覆盖:GRAPHIFY_OUT环境变量生效(测试test_honors_graphify_out_override)。这个设计与 paths.py 相呼应:输出目录名默认是graphify-out,但可通过GRAPHIFY_OUT环境变量改为任意相对名或绝对路径(适用于 worktree 或共享输出场景),hook 与 CLI 读取的是同一个单一事实来源。项目级安装时,由于.gemini/settings.json会被提交进版本库,钩子命令刻意使用裸graphify命令而非某台机器的绝对路径,保证换机器后依然可用。五、这个文件从何而来:skillgen 单一事实源与防漂移gemini-md.md 并不是手写的散落副本,而是由 tools/skillgen 从人类维护的单一 fragment tools/skillgen/fragments/always-on/gemini-md.md 生成的六个 always-on 块之一(同族还有claude-md、agents-md、antigravity-rules、kiro-steering、vscode-instructions)。install.py 的_always_on函数文档字符串写得很直白:安装包内的六个块必须与 fragment 逐字节一致,由skillgen --check的 roundtrip 校验守护漂移。这也解释了为什么graphify install能幂等升级——只要 fragment 更新,一次重新安装即可让所有项目的GEMINI.md段同步到最新措辞。六、落地清单与自定义在任意项目根目录,完整接入流程为:安装 Gemini 平台技能(用户级,技能落在~/.gemini/skills/graphify/):graphify install --platform gemini;使用项目级安装(规则、.gemini/settings.json钩子与.gemini/skills/graphify/SKILL.md全部落在项目内并可提交版本库):graphify install --project --platform gemini,安装器会自动提示git add对应路径;首次构建图谱后,项目内即出现graphify-out/graph.json、GRAPH_REPORT.md与wiki/索引,此后 Gemini CLI 按本文规则 1–3 的次序检索;每次改动代码后运行graphify update .增量刷新;需要换输出目录时,在进程启动前设置GRAPHIFY_OUT环境变量(例如 worktree 隔离或团队共享输出)。若需调整规则措辞,正确做法是修改 tools/skillgen/fragments/always-on/gemini-md.md 后由 skillgen 重新生成,而不是手改各项目里的GEMINI.md段落——否则下次graphify install的精确 section 替换会用包内版本覆盖你的手工修改。小结gemini-md.md 用十行文字把图谱优先的检索次序钉死在 Gemini CLI 的会话规则里:query/path/explain三级子图查询是默认入口,wiki 索引承担宽泛导航,GRAPH_REPORT.md退居全局评审兜底,graphify update .保证图谱零 API 成本地保鲜。配合 install.py 的幂等 section 注入与hook-guard gemini的每次读取前提醒,这套机制让 AI 助手在回答代码库问题时,先看到的永远是小得多、且每条边都有解释的范围化子图,而不是整个报告或 grep 的洪流。【免费下载链接】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），仅供参考
graphify × Gemini CLI:让 AI 助手优先查询代码知识图谱的 always-on 指令层设计与实践
graphify × Gemini CLI:让 AI 助手优先查询代码知识图谱的 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/graphifygraphify 会把任意代码库连同其文档、SQL schema、配置文件一起解析为本地确定性 AST 知识图谱。本文以 gemini-md.md 这个 Gemini CLI 专用常驻指令块为主体,逐条拆解它写入项目GEMINI.md的四条图谱优先工作规则,并结合 install.py 的安装器源码与 test_gemini_hook.py 的测试,说明这套指令如何通过graphify install --platform gemini落地、又被 BeforeTool hook 如何实时提醒AI 走图谱路径,读完后你可以完整复现 Gemini CLI graphify 的接入与日常使用闭环。一、它是什么:写在 GEMINI.md 里的常驻规则块gemini-md.md 只有短短十行,但它是 graphify 为 Gemini CLI 定制的always-on指令块——一段会在每次会话中被 Gemini CLI 读取、并长期生效的行为约束。原文完整内容如下:## graphify This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. Rules: - For codebase questions, first run graphify query question when graphify-out/graph.json exists. Use graphify path A B for relationships and graphify explain concept for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. - After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).它的定位非常清晰:声明事实 四条规则。开头一句向 AI 声明本项目在graphify-out/目录下已有一份包含 god nodes(枢纽节点)、community structure(社区结构)与跨文件关系的知识图谱;随后四条规则规定了 AI 回答代码库问题时的信息检索次序——先查图谱、再查 wiki 导航、最后才读完整报告,改完代码还要刷新图谱。这四条规则构成了整篇文章的展开主线。二、四条规则逐条解读规则 1:代码问题先查图谱——query / path / explain 三级查询这是四条规则中信息量最大的一条,它给了 Gemini 三个分层工具:命令用途CLI 完整用法(摘自 cli.py 的 Usage 提示)graphify query question面向自然语言问题的范围化子图检索graphify query question [--dfs] [--context C] [--budget N] [--graph path]graphify path A B查询两个节点之间的关系路径graphify path source target [--graph path]graphify explain node聚焦解释某个概念/节点graphify explain node [--graph path]规则原文强调的前提是graphify-out/graph.json exists——即只有当图谱确实构建过,才走查询路径,避免空图查询。三条命令返回的都是scoped subgraph(范围化子图),指令块明确指出其体积通常远小于 GRAPH_REPORT.md 或裸 grep 的输出。这正是 graphify 的核心卖点:用一份小得多的上下文回答代码库问题,而不是让模型去读整个报告或大海捞针式地 grep。从源码结构看,query在 cli.py 中被实现为基于graphify.serve._query_graph_text的图上检索,并保持图无向以支持 BFS/DFS 探索;path与explain则强制使用有向视图。三种查询执行后都会调用querylog.log_query记录查询日志,并写入查询时间戳,为 hook 的近期是否查过图判断提供依据。规则 2:用 wiki 做宽泛导航第二条规则要求:如果graphify-out/wiki/index.md存在,就用它做宽泛导航,而不是直接翻原始源码。graphify 构建图谱时会同步产出一个 markdown 形式的 wiki 索引(见 wiki.py),相当于给整个代码库生成了一份目录页。这条规则的意义在于把浏览这一动作从逐文件打开,升级为沿 wiki 层级跳转,既省上下文窗口,也避免模型在目录树里迷路。规则 3:GRAPH_REPORT.md 只作最后兜底第三条规则刻意降权了graphify-out/GRAPH_REPORT.md:它只应在两种场景被读取——做全局架构评审时,或者query/path/explain三者都没有给出足够上下文时。仓库内 worked/httpx/GRAPH_REPORT.md 这类报告可以看到其形态:整库级的社区划分与枢纽节点综述,信息密度高但体积大,适合作为地图总览而非问题答案。指令块把阅读次序硬编码为:子图查询 → wiki 导航 → 完整报告,本质是一份针对 AI 的渐进式信息披露(progressive disclosure)策略。规则 4:改完代码必须graphify update .最后一条规则规定了图谱保鲜义务:修改代码之后运行graphify update .。括号里的 (AST-only, no API cost) 点明了它的成本模型——增量更新只走本地确定性 AST 解析,不产生任何 LLM API 费用。这与 graphify本地解析、每条边可解释、不依赖向量库的整体设计一致:图谱可以低成本地随代码演进,而不需要重新花钱全量重建。三、指令块如何进入 GEMINI.md:installer 源码级走读gemini-md.md 只是包内的源文件,真正把它变成项目规则的是 install.py 中的gemini_install(第 707 行起)。执行graphify install --platform gemini时会发生三件事:拷贝技能文件:_copy_skill_file(gemini, ...)把包内skill.md原样拷入~/.gemini/skills/graphify/SKILL.md(项目级安装则是.gemini/skills/graphify/SKILL.md),并附带references/渐进式文档与.graphify_version版本戳;写入 GEMINI.md 规则段:以## graphify作为 section 标记,通过_replace_or_append_section将 gemini-md.md 的内容幂等地写入或替换到项目根目录的GEMINI.md(见 install.py)。替换是关键:旧版本安装留下的过时措辞会在升级时被整段覆盖,用户无需卸载重装;注册 BeforeTool hook:向.gemini/settings.json的hooks.BeforeTool数组追加一条钩子(见 install.py)。其中 section 替换函数_replace_or_append_section有一个值得注意的健壮性设计:它只在某一行精确等于## graphify(去除首尾空白后)时才算命中,绝不做子串匹配;section 范围延伸到下一个 H2 标题之前。注释里说明这是为了避免历史上子串误匹配删掉用户手写内容的缺陷——对用户自维护的GEMINI.md来说,精确边界是安全底线。卸载时gemini_uninstall用同样精确匹配的_remove_marker_section反向清理,若清完后文件为空则直接删除GEMINI.md。四、BeforeTool hook:规则 1 的运行时第二保险GEMINI.md里的规则是软约束(依赖模型自觉遵守),graphify 还配了一条硬提醒。_gemini_hook(install.py)生成的钩子形如:{ matcher: read_file|list_directory, hooks: [{ type: command, command: graphify 可执行路径 hook-guard gemini }] }即:每当 Gemini CLI 调用read_file或list_directory工具前,都会先执行graphify hook-guard gemini。它的行为由 tests/test_gemini_hook.py 完整固化:永不拦截:无论图谱是否存在,返回的 JSON 恒为{decision: allow},工具调用不会被 hook 阻断;有图谱就提醒:当前目录存在graphify-out/graph.json时,在additionalContext中追加先用graphify query的引导文本(测试test_allows_and_nudges_with_graph断言该文本包含graphify query);无图谱则静默:没有图谱时不附加任何上下文,避免噪音;尊重输出目录覆盖:GRAPHIFY_OUT环境变量生效(测试test_honors_graphify_out_override)。这个设计与 paths.py 相呼应:输出目录名默认是graphify-out,但可通过GRAPHIFY_OUT环境变量改为任意相对名或绝对路径(适用于 worktree 或共享输出场景),hook 与 CLI 读取的是同一个单一事实来源。项目级安装时,由于.gemini/settings.json会被提交进版本库,钩子命令刻意使用裸graphify命令而非某台机器的绝对路径,保证换机器后依然可用。五、这个文件从何而来:skillgen 单一事实源与防漂移gemini-md.md 并不是手写的散落副本,而是由 tools/skillgen 从人类维护的单一 fragment tools/skillgen/fragments/always-on/gemini-md.md 生成的六个 always-on 块之一(同族还有claude-md、agents-md、antigravity-rules、kiro-steering、vscode-instructions)。install.py 的_always_on函数文档字符串写得很直白:安装包内的六个块必须与 fragment 逐字节一致,由skillgen --check的 roundtrip 校验守护漂移。这也解释了为什么graphify install能幂等升级——只要 fragment 更新,一次重新安装即可让所有项目的GEMINI.md段同步到最新措辞。六、落地清单与自定义在任意项目根目录,完整接入流程为:安装 Gemini 平台技能(用户级,技能落在~/.gemini/skills/graphify/):graphify install --platform gemini;使用项目级安装(规则、.gemini/settings.json钩子与.gemini/skills/graphify/SKILL.md全部落在项目内并可提交版本库):graphify install --project --platform gemini,安装器会自动提示git add对应路径;首次构建图谱后,项目内即出现graphify-out/graph.json、GRAPH_REPORT.md与wiki/索引,此后 Gemini CLI 按本文规则 1–3 的次序检索;每次改动代码后运行graphify update .增量刷新;需要换输出目录时,在进程启动前设置GRAPHIFY_OUT环境变量(例如 worktree 隔离或团队共享输出)。若需调整规则措辞,正确做法是修改 tools/skillgen/fragments/always-on/gemini-md.md 后由 skillgen 重新生成,而不是手改各项目里的GEMINI.md段落——否则下次graphify install的精确 section 替换会用包内版本覆盖你的手工修改。小结gemini-md.md 用十行文字把图谱优先的检索次序钉死在 Gemini CLI 的会话规则里:query/path/explain三级子图查询是默认入口,wiki 索引承担宽泛导航,GRAPH_REPORT.md退居全局评审兜底,graphify update .保证图谱零 API 成本地保鲜。配合 install.py 的幂等 section 注入与hook-guard gemini的每次读取前提醒,这套机制让 AI 助手在回答代码库问题时,先看到的永远是小得多、且每条边都有解释的范围化子图,而不是整个报告或 grep 的洪流。【免费下载链接】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），仅供参考