graphify 的 AGENTS.md 常驻指令块：让知识图谱成为 Agent 的第一查询路径

graphify 在生成代码知识图谱后，还需要回答一个工程问题：如何让 AI 编码助手"自动"优先用图谱而不是裸 grep 来回答代码库问题。本篇技术文章以 graphify 仓库中的常驻指令块模板 graphify/always_on/agents-md.md 为主体，逐条解析它的 5 条查询规则，并结合 tools/skillgen 生成器与 graphify/install.py 注入逻辑，说明这块 12 行 Markdown 如何被打包、写入 AGENTS.md、并通过字节级 roundtrip 守卫保持一致。读完后你将能理解 graphify 的"always-on"集成机制，并能在读取 AGENTS.md 的宿主（Trae、Amp、通用 Agent-Skills 目标）上正确地安装、验证和使用 graphify。

一、常驻指令块本体：完整的 12 行规则

graphify/always_on/agents-md.md 是面向读取 AGENTS.md 的 Agent 宿主的指令块。它的完整内容如下（逐字保留，未做删改）：

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.

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.
- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
- 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).

它的定位非常明确：不是给开发者看的文档，而是写给 Agent 的"常驻行为约束"——宿主每次加载 AGENTS.md 时都会读到这段规则，从而在没有人工提醒的情况下改变其信息获取顺序。下面逐条拆解。

1. 入口约定：/graphify 触发技能优先

指令块首先声明了图谱的存在："This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships"，即 graphify-out/ 目录下存放着含 god nodes（关键枢纽节点）、社区结构和跨文件关系边的图谱数据。随后规定：用户输入 /graphify 时，必须先使用已安装的 graphify skill 或指令再做任何其他事。这一约定把"斜杠命令"作为显式入口，避免 Agent 在图谱可用时仍然凭直觉直接浏览源码。

2. 查询优先级：query / path / explain 三命令

第一条规则是核心。当 graphify-out/graph.json 存在时，回答代码库问题要先运行：

命令	用途	返回形态
graphify query "<question>"	自然语言问题 → 子图	作用域受限的子图，通常远小于 GRAPH_REPORT.md 或裸 grep 的原始输出
graphify path "<A>" "<B>"	两个实体之间的关系路径	连接 A 与 B 的边链
graphify explain "<concept>"	聚焦解释单个概念	围绕该概念的子图与说明

规则中特意强调返回的是 "a scoped subgraph"，其设计意图是让 Agent 拿到"刚好够用"的上下文窗口内容，而不是动辄数万行的报告或全库 grep 命中集。这与 graphify 项目定位一致：本地确定性 AST 解析生成图谱，每一条边都有解释，不依赖向量库。

3. 脏文件容忍：dirty 不是跳过理由

第二条规则针对一个真实故障模式：hooks 触发或增量更新后，graphify-out/ 下的文件在版本控制中处于"脏"状态（modified/untracked），Agent 可能误判为"图谱不可信"而回退到裸源码浏览。规则明确：脏的图谱文件是预期现象，不是跳过 graphify 的理由；只有当任务本身就是排查图谱输出错误，或用户显式要求不用图谱时，才跳过。这保证了图谱在 CI 式高频变更场景中仍被优先使用。

4. 导航与报告的分级读取

规则把 graphify-out/ 内的产物按"读取时机"分了级：

• graphify-out/wiki/index.md 存在时：用它做广域导航，代替直接翻源码。wiki 是图谱的人类可读导览层，index 即目录入口；
• GRAPH_REPORT.md 只读于两种场景：做广域架构评审，或 query/path/explain 三者都无法给出足够上下文时。

这种"子图命令 → wiki 导航 → 全量报告"的三级递进，本质上是给 Agent 的上下文消耗设了预算：能查子图就不读全量，能看目录就不翻源码。

5. 写后刷新：graphify update .

最后一条规定：修改代码后运行 graphify update . 保持图谱最新，并括注了两个关键属性——AST-only（仅静态解析）且无 API 成本。这意味着刷新不触发 LLM 调用、不产生费用，适合作为"改完代码顺手执行"的低成本收尾步骤。

二、谁在使用这个块：AGENTS.md 宿主家族

graphify 的 always-on 机制按宿主读取的指令文件分为两个变体。从 tools/skillgen/platforms.toml 的平台清单可以看到划分逻辑：

• claude-md 变体（默认）：宿主读取 CLAUDE.md，通过 graphify claude install 接线，典型宿主是 Claude Code（含 Windows 变体），可配合 PreToolUse hook 做自动行为；
• agents-md 变体：宿主读取 AGENTS.md，通过 graphify <host> install 接线，且附带"无 PreToolUse hook"的注意事项。hooks_variant = "agents-md" 的宿主包括 trae / trae-cn、amp 和通用的 agents（跨框架 Agent-Skills 目标，落位 ~/.agents/skills 与 ./.agents/skills）。

platforms.toml 中的注释进一步说明了差异：Trae 读取 AGENTS.md 而非 CLAUDE.md，且没有 PreToolUse hook，因此 AGENTS.md 里的规则就是这些宿主的唯一"always-on"机制——没有工具调用时的自动图谱重建，需要手动运行更新。这也解释了为什么 agents-md 变体的注入块必须自带"After modifying code, run graphify update ."这一条：它替代了 hook 的职责。

各平台的渲染产物与引用目录在 graphify/ 下成体系存在，例如 agents 宿主的技能文件为 graphify/skill-agents.md，其 hooks 参考文档为 graphify/skills/agents/references/hooks.md，描述了针对 AGENTS.md 的安装/卸载流程。同目录下 claude/、trae/、amp/ 等子目录则是各宿主按需加载的参考分片（update、exports、extraction-spec 等）。

三、指令块如何被打包与注入

1. skillgen 生成：fragment 到发布产物

graphify/always_on/agents-md.md 不是手工维护的，而是构建时产物。tools/skillgen/gen.py 中的 ALWAYS_ON_BLOCKS 表声明了 6 个常驻块的映射关系：

ALWAYS_ON_BLOCKS = {
    "claude-md": "_CLAUDE_MD_SECTION",
    "agents-md": "_AGENTS_MD_SECTION",
    "gemini-md": "_GEMINI_MD_SECTION",
    "vscode-instructions": "_VSCODE_INSTRUCTIONS_SECTION",
    "antigravity-rules": "_ANTIGRAVITY_RULES",
    "kiro-steering": "_KIRO_STEERING",
}

render_always_on() 会读取同名的 fragment 源文件（agents-md 的源头是 tools/skillgen/fragments/always-on/agents-md.md）并渲染到 graphify/always_on/<basename>.md。由于这些块不随平台分化，它们在完整的 skillgen 运行中只渲染一次，不受 --platform 过滤影响。

2. 一致性守卫：字节级 roundtrip 与受控变更

gen.py 的注释交代了历史脉络：这 6 个常驻块曾经是 graphify/__main__.py 中的三引号字符串常量，后来被抽取为打包的 Markdown 文件。为保证抽取不引入漂移，--always-on-roundtrip 校验器会把每个 always_on/*.md 与 v8 基线 ref 中的旧常量做逐字节比对。

由此带来一个值得注意的工程约束：对常驻块的任何有意修改都必须登记到 ALWAYS_ON_SANCTIONED_EDITS（gen.py），以"旧文本 → 新文本"替换对的形式显式记录。其中唯一登记在 agents-md 块上的变更是 #1530：

"_AGENTS_MD_SECTION": (
    (
        "When the user types `/graphify`, invoke the `skill` tool with "
        '`skill: "graphify"` before doing anything else.',
        "When the user types `/graphify`, use the installed graphify skill or instructions "
        "before doing anything else.",
    ),
),

即把宿主专属的"调用 skill 工具、skill: "graphify""措辞改为宿主无关的"使用已安装的 graphify 技能或指令"——因为该块会被注入到多个异构宿主的 AGENTS.md，不能假设某个环境存在字面量的 skill 工具。未被登记的任何其他改动都会让 roundtrip 守卫失败，无法悄悄混入发布产物。

3. 运行时注入：install.py 的 marker 替换机制

安装侧由 graphify/install.py 完成。_always_on(basename) 加载器（install.py）通过 Path(__file__).parent / "always_on" 定位打包目录中的指令块——模块内的调用一律走该函数而非硬编码字符串，使导入方（包括安装字符串测试）拿到的内容与发布文件严格同源。agents-md 变体的安装逻辑位于 install.py：若宿主 AGENTS.md 中已存在 _AGENTS_MD_MARKER 标记的段落，则用最新的 _always_on("agents-md") 内容做替换；否则追加新段落。这一"marker 定位 + 幂等替换"模式同时支撑了 graphify <host> uninstall（移除标记段落）与升级场景下的原块更新。__main__.py 中同样通过 _always_on() 按 basename 分发（见 graphify/main.py 中对 agents-md 等六个别名的映射）。

四、实战使用：在 AGENTS.md 宿主上启用

基于上述机制，在读取 AGENTS.md 的宿主上使用 graphify 的完整路径如下（以 agents 通用目标为例，trae/amp 将命令中的宿主名换为 trae/amp 即可）：

1. 安装技能与常驻块：运行 graphify agents install，它会把技能文件写入 ~/.agents/skills（或项目内 ./.agents/skills），并向 AGENTS.md 注入带标记的 ## graphify 段落（即本文第一部分的全部内容）。重复执行会原地刷新段落而非重复追加；graphify agents uninstall 按标记移除该段。
2. 构建图谱：在目标仓库中执行 graphify 提取流程，产出 graphify-out/graph.json、GRAPH_REPORT.md 以及可选的 graphify-out/wiki/index.md。
3. 日常查询：此后 Agent 加载 AGENTS.md 即自动获得五条规则；代码库问题走 graphify query，实体关系走 graphify path，单概念走 graphify explain，广域导航看 wiki 索引，仅在架构评审级场景读全量报告。
4. 写后刷新：每次改完代码执行 graphify update .（仅 AST 解析、无 API 费用）；若宿主无 hook 支持（agents-md 家族即属此类），这一步必须由人显式执行，这正是常驻块把它写成硬性规则的原因。

需要注意的适用前提与限制：常驻块只在宿主实际读取 AGENTS.md 时才生效；graphify-out/graph.json 不存在时 query 规则自动退场（规则本身已带存在性前置）；图谱文件处于 dirty 状态属于 hooks/增量更新的正常副产品，不应触发"放弃图谱"的判断。

五、小结

graphify/always_on/agents-md.md 用 12 行完成了三件事：定义查询命令的优先级顺序（query/path/explain 子图 → wiki 导航 → GRAPH_REPORT 全量报告）、设定容错边界（脏文件不跳过、仅两种情况才跳过）、约束写后行为（graphify update . 低成本刷新）。仓库侧则用 skillgen 的 fragment 渲染、--always-on-roundtrip 字节级守卫、ALWAYS_ON_SANCTIONED_EDITS 受控变更登记，以及 install.py 的 marker 幂等注入，保证了这块指令在 6 个 always-on 变体、十余个宿主平台间的一致与可审计。对使用者而言，它是把"确定性 AST 知识图谱"接入 Agent 日常工作流的最小且完整的集成面；对维护者而言，它是理解 graphify 多宿主分发架构的最佳切入点。