graphify VS Code 常驻指令：让 Copilot Chat 优先走知识图谱 query/path/explain 的接线指南

本文以 vscode-instructions.md 这份"常驻指令"（always-on instructions）文档为主体，完整解读 graphify 为 VS Code Copilot Chat 编写的行为契约：AI 助手在回答架构、结构、组件归属类问题时，应如何以 graphify query / path / explain 三个子命令为第一动作，按什么优先级读取 graphify-out/ 下的图产物，以及什么条件下才允许回退到直接读源码。读完后你能理解这套指令如何被 graphify vscode install 写入 .github/copilot-instructions.md、各产物的角色边界，以及如何为团队仓库正确接线与拆除。

1. 文档定位：这是一份写给 AI 的"第一动作"契约

vscode-instructions.md 是 graphify 打包在 graphify/always_on/ 目录下的一组平台常驻指令之一，专门面向 VS Code Copilot Chat 场景。它的核心主张只有一句话，即文档开头的规则：

对于任何关于本仓库架构、结构、组件，或"如何新增/修改/查找代码"的问题，只要 graphify-out/graph.json 存在，你的第一个动作就应该是 graphify query "<question>"。

这份文件不是给人阅读的操作手册，而是会原样注入 Copilot 上下文的规则文本——它的写作特点是全部使用祈使句和明确的条件分支（when … exists），便于 LLM 直接执行。同目录下的 claude-md.md、agents-md.md 等文件是同一规则体系针对不同平台的变体：Claude Code 版本额外附带"改完代码后运行 graphify update . 保持图谱最新"的维护规则，而 VS Code 版本则聚焦于"提问路径"本身。

指令中定义的触发场景（Triggers）覆盖了开发者向 AI 提问的典型形态：

• "how do I…"（怎么做……）
• "where is…"（……在哪里）
• "what does … do"（……是干什么的）
• "add/modify a <component>"（新增/修改某个组件）
• "explain the architecture"（解释架构）
• 以及一切"依赖于文件或类之间如何关联"的问题

判断逻辑很直接：只要问题涉及文件、类之间的关联关系，就属于图谱问题，而不是 grep 问题。

2. 三条查询命令的分工：query、path、explain

文档将三种子命令按问题类型做了明确分工：

命令	适用问题	形式
graphify query "<question>"	任意架构/结构/组件问题（默认第一动作）	自然语言问题
graphify path "<A>" "<B>"	两个实体之间的关系问题（"A 和 B 怎么关联"）	两个节点名
graphify explain "<concept>"	聚焦于单个概念的解释	单个概念名

文档强调这三条命令的共同优势：返回的是"作用域受限的子图"（scoped subgraph），通常比完整报告或原始 grep 输出小得多。这一点是整份指令的收益来源——把 AI 需要消化上下文的篇幅从"全仓库搜索结果"压缩到"恰好覆盖该问题的一小片图"。

结合 CLI 帮助文本（main.py 中 graphify --help 的输出）可以补充这些命令的实际参数与默认值：

graphify query "<question>"
#   --dfs                   改用深度优先而非广度优先遍历
#   --context C             显式边上下文过滤（可重复）
#   --budget N              输出 token 上限（默认 2000）
#   --graph <path>          指定 graph.json 路径（默认 graphify-out/graph.json）

graphify path "<A>" "<B>"      # 图中两节点间的最短路径
graphify explain "<X>"         # 某节点及其邻居的白话解释
# 后两者同样支持 --graph <path>

从源码结构看，query 被描述为对 graph.json 的 BFS 遍历（帮助文本："BFS traversal of graph.json for a question"），path 求两节点最短路径，explain 展开"节点及其邻居"。也就是说，三条命令读的是同一份图数据，只是遍历策略不同：query 按问题广度展开、path 沿最短链路走、explain 只做单点邻域展开。这解释了文档中"focused-concept questions 用 explain"的分工——概念类问题只需要一跳邻域，不必让 BFS 铺开。

3. 读取优先级：从 wiki 到 GRAPH_REPORT 再到源码的四级降级

文档的后半段规定了信息源的选择顺序，这是一条严格的降级链：

1. graphify-out/wiki/index.md（如存在）：用于宽泛导航（broad navigation）。即当问题是"这个项目大致有哪些部分"这类无明确目标的浏览型请求时，先翻 wiki 索引而不是逐目录扫源码。
2. graphify-out/GRAPH_REPORT.md：仅在两种情况下读取——做宽泛的架构评审，或者 query/path/explain 都没有给出足够上下文时。
3. 直接读源文件：只有三个条件之一成立时才允许——
   • (a) 正在修改/调试具体代码（必须看到真实代码）；
   • (b) 图谱缺少所需的细节；
   • (c) 图谱缺失或已过期（stale）。

这条链路的工程含义是：AI 的每一步"扩大搜索面"都必须付出明确的理由成本。GRAPH_REPORT.md 是全量架构报告，token 开销大，所以被压到第三级；源码是全量真相，但无差别读源码正是图谱工具要消灭的低效模式，所以被压到最后且附带三个准入条件。对团队的实际价值在于：AI 的回答过程从"grep + 随机翻文件"变成"查图 → 看邻域 → 定点验证"，上下文更省、引用更可追溯（每条边都有来源）。

补充一个运维细节：文档中写的 graphify-out/ 是默认输出目录名。从 paths.py 可以看到，目录名可通过环境变量 GRAPHIFY_OUT 覆盖（接受相对名或绝对路径，用于 worktree 或共享输出场景，且该值在进程启动时读取一次）。如果项目做了此配置，指令文本中出现的 graphify-out/graph.json 等路径需按实际输出目录理解——这是文档未展开、但由源码确认的前提。

4. 指令如何进入 VS Code：graphify vscode install 的完整链路

文档最后一行写着 "Type /graphify in Copilot Chat to build or update the graph"，这句话的前提是安装步骤已完成。实现入口在 install.py 的 vscode_install()，流程如下：

1. 安装 Skill：把 graphify/skill-vscode.md（缺失时回退到 skill-copilot.md）复制到 ~/.copilot/skills/graphify/SKILL.md，采用"临时文件 + os.replace"的原子写方式；若存在打包的 references/ 侧车目录，一并安装，并在 skill 目录写 .graphify_version 版本戳（用于后续版本漂移告警，见 main.py 的 _check_skill_version）。
2. 写入常驻指令：向项目内 .github/copilot-instructions.md 写入本文件（vscode-instructions.md）的内容。关键逻辑在 install.py：

instructions = (project_dir or Path(".")) / ".github" / "copilot-instructions.md"
instructions.parent.mkdir(parents=True, exist_ok=True)
if instructions.exists():
    new_content = _replace_or_append_section(
        content, _VSCODE_INSTRUCTIONS_MARKER, _always_on("vscode-instructions")
    )
    ...
else:
    instructions.write_text(_always_on("vscode-instructions"), encoding="utf-8")

其中标记常量 _VSCODE_INSTRUCTIONS_MARKER = "## graphify"（install.py）。_replace_or_append_section 的行为是幂等的：文件里已有 ## graphify 章节就整体替换该章节，没有就追加，并打印 already configured (no change) / updated / created 三种状态之一。这意味着团队成员重复执行安装不会产生重复段落。

命令行形态（来自 main.py 帮助文本）：

graphify vscode install      # 配置 VS Code Copilot Chat（skill + .github/copilot-instructions.md）
graphify vscode uninstall    # 移除 VS Code Copilot Chat 配置

对应地，vscode_uninstall()（install.py）会删除用户级 skill 文件、版本戳与 references/ 目录，并仅移除 .github/copilot-instructions.md 中 ## graphify 标记覆盖的章节——章节之外用户自有的指令内容会被保留，章节移除后文件若为空才整体删除。

一个容易混淆的点在 main.py 的帮助文本中已经区分开：vscode install 面向 VS Code 内的 Copilot Chat（写项目内 .github/copilot-instructions.md），而 copilot install 面向 GitHub Copilot CLI（终端）（把 skill 复制到 ~/.copilot/skills）。两者共享同一份 skill 内容源，但配置落点不同。

5. 片段来源与一致性保证

这份指令文本并不是手写在 install 逻辑里的字符串字面量。main.py 的注释说明了机制：

"always-on 指令块是打包在 graphify/always_on/ 下的 markdown，由 tools/skillgen 生成，并由 skillgen --check 守护。"

即 graphify/always_on/vscode-instructions.md 与生成工具 tools/skillgen 及其期望输出 tools/skillgen/expected/graphify__always_on__vscode-instructions.md 之间受测试守护（见 tests/test_skillgen.py、tests/test_install_strings.py）：任何一处改动都需要同步另一处，否则校验失败。运行时则通过 _always_on("vscode-instructions") 按名读取片段，别名映射见 main.py 的 _ALWAYS_ON_ALIASES（"_VSCODE_INSTRUCTIONS_SECTION": "vscode-instructions"）。对使用者的意义是：.github/copilot-instructions.md 里的这段文字应与仓库中 graphify/always_on/vscode-instructions.md 逐字节一致，排查"为什么 AI 没有遵守规则"时可以直接对照这两处。

6. 实操清单：为 VS Code 项目接线 graphify 的最小步骤

1. 安装 CLI 后，在项目根目录执行 graphify vscode install：生成 ~/.copilot/skills/graphify/SKILL.md 与 .github/copilot-instructions.md 中的 ## graphify 章节（即本文主体文档内容）。
2. 在 VS Code 的 Copilot Chat 面板输入 /graphify，构建 graphify-out/graph.json、graphify-out/wiki/ 与 graphify-out/GRAPH_REPORT.md（对应文档第 4 与 12 行引用的三个产物）。
3. 之后的架构类提问按文档规则自动走 query/path/explain；宽泛浏览走 graphify-out/wiki/index.md；只有改代码或图谱缺细节时才落到源文件。
4. 若使用 GRAPHIFY_OUT 自定义了输出目录，需确保 AI 侧理解的产物路径与实际一致。
5. 拆除时执行 graphify vscode uninstall，skill 与指令章节会按上文第 4 节描述的幂等逻辑被干净移除。

7. 小结

vscode-instructions.md 虽然只有十余行，但定义了 graphify 在 VS Code 场景下的完整提问协议："存在 graph.json → 先查图；关系问题用 path；概念问题用 explain；导航走 wiki；报告最后读；源码只在三个明确条件下读"。配合 graphify vscode install 的幂等写入与 skillgen 的字节级一致性守护，这套契约可以随仓库分发、可重复安装、可干净卸载，使团队里任何一位开发者的 Copilot Chat 都以相同的方式利用同一份知识图谱。