graphify always-on 指令机制解读：让 VS Code 里的 Copilot Chat"先查图、再翻源码"

本文基于 graphify 仓库中的 always-on VS Code 指令文档（graphify/always_on/vscode-instructions.md 及其由 skillgen 生成的同构产物 tools/skillgen/expected/graphify__always_on__vscode-instructions.md），解读这套"常驻指令"如何在 VS Code 的 Copilot Chat 中驱动 AI 助手优先使用知识图谱回答代码库问题。读完你会掌握：graphify query / graphify path / graphify explain 三个查询子命令的分工与使用时机、graphify-out/ 各产物的读取优先级，以及 graph-first 工作流背后的源码支撑与工程动机。

这套指令从哪来：skillgen 生成物与它的"母本"

先厘清一个容易混淆的点：本文所依据的关联文档位于 tools/skillgen/expected/graphify__always_on__vscode-instructions.md。这是一个由构建工具固化生成的期望产物（expected artifact），并非手工维护的原始文件。它的"母本"是仓库内同名的可编辑源文件 graphify/always_on/vscode-instructions.md，两者内容逐字一致。

从 skillgen 平台清单 可以还原它的生成语境：tools/skillgen/ 是一套面向多款 AI 宿主（Claude、Codex、Gemini、Copilot、Kiro、Trae 等）的 skill 装配器，以 [platform.<key>] 表声明每个宿主如何渲染 skill 产物。VS Code 对应的平台条目声明了：

• skill_dst = "graphify/skill-vscode.md"：渲染出的 skill 主体落到 graphify/skill-vscode.md；
• refs_dst = "graphify/skills/vscode/references"：配套的 references 侧车目录（如 query.md、exports.md、update.md），见 graphify/skills/vscode/references；
• extraction = "verbose"：VS Code 变体使用详细版抽取规范。

expected/ 目录存放的正是这些渲染结果的基准快照，注释表明在仓库根目录运行 python -m tools.skillgen 可重新生成，--check 检查漂移、--bless 刷新期望文件。而 graphify/always_on/vscode-instructions.md 则属于"常驻安装段"——它不与某个 skill 文件绑定，而是随安装过程写入编辑器配置的 instructions 文件，保证 AI 助手在任何会话的起点都能读到这套行为准则。同类文件还包括 agents-md.md、claude-md.md、gemini-md.md 等，分平台维护。

指令核心：graph-first 的查询三命令

指令正文最关键的规则只有一句话：只要 graphify-out/graph.json 存在，关于仓库架构、结构、组件、以及"如何增删改查某段代码"的任何问题，助手的第一动作都应该是 graphify query "<question>"。

指令把三类问题分别映射到三个子命令，构成一套"问题形态 → 查询原语"的分发表：

问题形态	首选命令	语义
一般性问题（"它是做什么的""怎么工作的"）	graphify query "<question>"	以 BFS 为主的知识图谱遍历，返回带上下文的子图
关系型问题（A 与 B 如何相关、谁依赖谁）	graphify path "<A>" "<B>"	两节点间最短路径查询
聚焦概念型问题（解释某个概念/节点）	graphify explain "<concept>"	单节点的邻接全景式解读

指令同时点明了选择这套命令的根本收益：它们返回的是"经过裁剪的作用域子图（scoped subgraph）"，通常远小于完整报告或原始 grep 输出。也就是说，graph-first 的本质是先用图结构把检索空间压缩到局部，再让助手基于局部子图作答，从而同时降低 token 消耗与噪声。

在触发条件上，文档给出的关键词清单非常直白——"how do I…""where is…""what does … do"、"add/modify a <component>"、"explain the architecture"，以及任何"依赖文件或类之间如何关联"的问题。这与 skill 前言的描述互相印证：指令把这类问句从"全文检索"语境中剥离出来，归入"图上查询"语境。

读取优先级设计：graph → wiki → report → 源码

指令中容易被忽略、但最能体现工程取舍的，是它对 graphify-out/ 各产物定义的一整套分层读取策略：

1. graphify-out/graph.json（存在时）→ 是 query/path/explain 的数据源，最高优先；
2. graphify-out/wiki/index.md（存在时）→ 用于"广度导航（broad navigation）"；
3. graphify-out/GRAPH_REPORT.md → 仅在需要"广度架构评审"，或 query/path/explain 没有提供足够上下文时才读取；
4. 源码文件 → 仅当满足以下任一条件才直接阅读：
   • (a) 正在修改或调试特定代码；
   • (b) 图中缺少所需细节；
   • (c) 图缺失或已过期。

这套优先级本质上是一条"成本与精度"的阶梯：图谱子查询是廉价的近似，报告是中价的概览，源码阅读是最贵但最精确的手段。指令刻意把"直接读源码"设为例外而非默认，从而防止 AI 助手在一问一答里就把整个代码库读进上下文。作为横向参照，agents-md.md（面向读取 AGENTS.md 的宿主）还补充了两条纪律：脏的 graphify-out/ 文件是 hook 或增量更新的正常产物，不应成为跳过图查询的理由；修改代码后应运行 graphify update . 让图保持最新。

/graphify：VS Code 里的构建入口

指令最后一行点明 VS Code 宿主上的操作入口：在 Copilot Chat 中输入 /graphify 即可构建或更新图谱。这条 slash 命令背后挂载的是 graphify/skill-vscode.md 描述的完整流水线——从 Step 1 的安装与解释器探测（检测 uv tool / pipx / python3，并把解释器路径写入 graphify-out/.graphify_python 供后续步骤复用），到 Step 2 的文件检测、Part A 的确定性 AST 抽取与 Part B 的语义抽取、Step 4 的建图与社区聚类、直至 Step 9 的清单（manifest）与成本追踪。对纯代码语料，AST 抽取无需 LLM、无需 API key，因此 "/graphify 之后直接开始提问"在 VS Code 场景下是零成本的常见路径。

值得强调的是 always-on 指令与 skill 的分工：always-on 段负责"会话中任何时刻都记得先查图"，skill 负责"真正执行建图与查图时的分步动作"。二者叠加，才构成 VS Code 中完整的 graphify 体验。

源码侧印证：query 子命令在 CLI 中的真实实现

"先查图"指令不是一句口号——它在 CLI 层有具体的命令分发实现。在 graphify/cli.py 中可以看到 query 子命令的入口逻辑：

• 参数少于 3 个（即缺少 question 参数）时，打印用法 graphify query "<question>" [--dfs] [--context C] [--budget N] [--graph path] 并退出；
• 通过 --dfs 切换遍历模式；
• --budget 默认值为 2000，用于限制回答规模，且同时支持 --budget N 与 --budget=N 两种写法；
• 运行时从 graphify.serve 引入 _query_graph_text 作为查询执行体。

从这里可以看出三个与 always-on 指令呼应的设计点：

1. --budget 2000 默认值与"scoped subgraph"理念一致——查询本身就被设计为带 token 上限的轻量操作；
2. --dfs 是 BFS 之外的显式选择，对应 references/query.md 里那张模式对照表：BFS（默认）适合"What is X connected to"式的广谱上下文，DFS 适合"How does X reach Y"式的链路追踪；
3. 图路径可覆盖（--graph path），允许对非默认位置的图发起查询，这与 always-on 指令中"当 graphify-out/graph.json 存在时"的前提形成灵活互补。

更进一步，references/query.md 揭示了 CLI 之外的第二套执行路径：当 graphify query 命令不可用时，助手可以退化为内联 NetworkX 遍历——直接读取 graphify-out/graph.json，用 json_graph.node_link_graph 还原图，按节点标签与查询词的重叠打分选取 1～3 个起点，BFS 层数限制为 3、DFS 深度限制为 6，最终按 --budget 折算的字符预算截断输出。这套"CLI 优先、NetworkX 兜底"的双轨机制保证了 always-on 指令在任何环境下都具备可执行性。

防幻觉的三道闸门

指令要求助手严格依据图上证据作答，源码与 reference 把它落实为三层约束：

• 受约束的查询扩展：references/query.md 要求遍历前先从 graph.json 节点标签中抽取词表，只允许从图内真实存在的 token 中挑选最多 12 个做查询扩展，明令禁止"从训练记忆里找近义词"——当用户用词与图词汇不一致（如跨语言、简称）时，先扩展再遍历，避免字面匹配返回零结果；
• 引用留痕：答案必须只依据图输出内容，引用具体事实时注明 source_location；
• 诚实法则：图信息不足时明说，绝不编造边。skill 底部的 Honesty Rules（"Never invent an edge. If unsure, use AMBIGUOUS"）与图节点的 confidence 标签（EXTRACTED / INFERRED / AMBIGUOUS）共同构成信任边界。

结果回流：让每次问答改进下一张图

值得在文章末尾补上的一个进阶细节是 save-result 闭环：reference 建议每次作答后调用

python -m graphify save-result --question "<原始问题>" --answer "<回答>" --type query --nodes <引用的节点标签>

把问答写回图，使下一次 --update 能把该 Q&A 作为图节点抽取出来；再配合 --outcome useful|dead_end|corrected 标记经验（有效来源/死胡同/纠错）与 graphify reflect --if-stale 刷新 graphify-out/reflections/LESSONS.md，图就不仅是静态索引，而会随每次问答"自我改进"。这也是 always-on 指令鼓励"图在就先用图"的深层原因——用得越多，图越准。

可验证性：来自测试与示例产物的佐证

上述机制并非孤立文档，仓库提供了多层可验证依据：

• 行为契约层：tools/skillgen/expected/ 中固化了一批宿主 instruction 的快照（如 graphify__always_on__agents-md.md、graphify__always_on__claude-md.md），说明 always-on 段是跨宿主标准化产物，VS Code 版本并非特例；
• 可执行契约层：仓库真实运行后生成的 graphify/skills/vscode/references/query.md 与 CLI 解析代码 graphify/cli.py 给出了命令的准确用法与默认值；
• 端到端样例层：worked/ 目录下保留了多个真实语料跑出的图产物（例如 worked/httpx/graph.json、worked/karpathy-repos/graph.json），可供对照理解 graph.json 的结构形态；
• 测试验证层：仓库测试目录存在 test_query_cli.py、test_explain_cli.py、test_path_cli.py 等文件（见 tests/），覆盖查询命令的 CLI 行为，是"图查询可用性"最直接的回归保障。

小结

graphify/always_on/vscode-instructions.md（及其 skillgen 期望产物 tools/skillgen/expected/graphify__always_on__vscode-instructions.md）浓缩了 graphify 在 VS Code / Copilot Chat 场景下的全部会话纪律：图在则先查图（query/path/explain），再借 wiki 导航，后以报告兜底，最后才读源码；建图与更新则交给 /graphify slash 命令。这套指令的工程内核——作用域子图压缩检索空间、词表受限扩展防止幻觉、save-result 回流让图自我进化——在 graphify/cli.py、references/query.md 与 graphify/skill-vscode.md 中都有迹可循。理解这套"指令—技能—实现"三层结构，你也就掌握了在 VS Code 中把任何代码库当作一张可查询知识图谱来使用的完整方法。