graphify Kiro Steering 文件深度解析：让 Kiro 在每轮对话前优先查询知识图谱

本篇解析 graphify/always_on/kiro-steering.md 这一始终注入（always-on）的指令片段：它如何以 Kiro steering 文件的形式告诉 Kiro IDE/CLI“回答代码库、架构、依赖类问题前先查知识图谱”，以及它如何被 graphify/install.py 安装到项目内的 .kiro/steering/graphify.md 并参与 skillgen 生成链。读完你将掌握 steering 文件的格式约定、查询优先（query-first）决策规则的每一层含义，以及 graphify kiro install 的完整安装/卸载机制。

1. Steering 文件是什么：frontmatter 与 Kiro 的 always-on 约定

整个文件只有 5 行，结构如下（graphify/always_on/kiro-steering.md）：

---
inclusion: always
---

graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase,
architecture, or dependency questions, when `graphify-out/graph.json` exists, first
run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` /
`graphify explain "<concept>"`). These return a scoped subgraph, usually much
smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for
broad architecture review or when those commands do not surface enough context.

关键点有两个：

1. YAML frontmatter inclusion: always：这是 Kiro steering 文件的格式约定，声明该文件必须被包含进每次会话的上下文，而不是按需触发。安装后该文件落在项目的 .kiro/steering/graphify.md，因此 Kiro 在开启任何对话前都会读到这段指令——这也是 README.md 中“instruction-file platforms（指令文件平台）”一类做法的典型代表：与基于 hook 的平台不同，它不依赖工具调用拦截，而是靠持久化指令文件生效。
2. 正文是一个前缀为 graphify: 的单段行为规则：它定义了“什么条件下、以什么优先级、调用哪些命令、何时才回退到读报告”的四层决策策略（见第 3 节逐条拆解）。

这段文本不是手写的孤本。从源码结构看，graphify/install.py 中的 _always_on() 函数明确说明：六个 always-on 块（CLAUDE.md / AGENTS.md / GEMINI.md / VS Code Copilot instructions / Antigravity rules / Kiro steering）都以 markdown 形式提交在 graphify/always_on/ 目录下，由 tools/skillgen/gen.py 从单个人工编辑的 fragment 生成——Kiro 版对应的源片段是 tools/skillgen/fragments/always-on/kiro-steering.md，并在 tools/skillgen/platforms.toml 的 [platform.kiro] 配置段中声明其产物路径（skill_dst = "graphify/skill-kiro.md"、refs_dst = "graphify/skills/kiro/references"）。skillgen --check 负责防止生成物与 fragment 之间出现漂移，保证安装到各项目里的 steering 内容字节级一致。

2. 安装机制：从 fragment 到 .kiro/steering/graphify.md

对 Kiro 平台的安装入口是 _kiro_install()（graphify/install.py），由 CLI 子命令触发：

graphify kiro install        # 写 skill 到 .kiro/skills/graphify/ + steering 文件
graphify kiro uninstall      # 移除 skill + steering 文件

该分支在 graphify/main.py 中注册，帮助文案见同文件 第 700 行。_kiro_install() 做两件事：

第一步：写 skill 文件。 通过共享的 _copy_skill_file("kiro", project=True, ...) 把 graphify/skill-kiro.md 拷到 .kiro/skills/graphify/SKILL.md，并带上 references/ 侧车目录和 .graphify_version 版本戳。源码注释指出这是一次修复（issue #1142）：早期实现用裸 write_text 绕过了 _copy_skill_file，导致 kiro 虽然声明了 skill_refs: "kiro" 却从不落盘 references 目录。

第二步：写 steering 文件。 目标路径固定为 <项目根>/.kiro/steering/graphify.md，内容就是 _always_on("kiro-steering") 读出的这段指令，并带幂等/升级语义：

• 若目标文件已存在且内容与当前 always-on 块完全一致，打印 already configured (no change)，不做任何写入；
• 否则覆盖写入，并根据是否已存在打印 written 或 updated。注释特别说明：该文件完全由 graphify 所有（wholly graphify-owned），升级时必须覆盖，以免旧的“report-first”措辞悄悄残留（issue #580）。

安装完成的提示语也值得注意："Kiro will now read the knowledge graph before every conversation."——这句话正是 steering 机制的预期效果：知识图谱成为 Kiro 的默认第一信息源。

卸载则由 _kiro_uninstall()（graphify/install.py）执行：删除 .kiro/skills/graphify/SKILL.md、references 侧车与版本戳，再 unlink 掉 .kiro/steering/graphify.md，最后汇总打印 Removed: ...。

3. Steering 文本的决策规则逐条拆解

正文虽然只有一段，却是一条完整的“查询优先”决策链，共四层：

第一层——知识图谱的位置：A knowledge graph of this project lives in graphify-out/。这告诉 agent 产物目录是 graphify-out/（常量定义于 graphify/paths.py 的 GRAPHIFY_OUT，install.py 中即 from graphify.paths import GRAPHIFY_OUT），内含机器可读的 graph.json 与面向人类审阅的 GRAPH_REPORT.md。

第二层——触发条件：when graphify-out/graph.json exists。指令明确以“图谱文件实际存在”为前提，避免 agent 在尚未构建图谱的项目上徒劳调用命令。这也是 README.md 描述的安装行为：安装脚本“写一个小配置文件，告诉助手在回答代码库问题时先查知识图谱，并优先使用 graphify query "<question>" 这类范围化查询，而不是通读报告或 grep 原始文件”。

第三层——优先命令及其返回物：按问题类型给出三条路径——

命令	适用问题	返回
graphify query "<question>"	自然语言的代码库/架构/依赖提问	范围化子图（scoped subgraph）
graphify path "<A>" "<B>"	“A 和 B 之间如何连通”	两点间的路径
graphify explain "<concept>"	单个概念/符号（类、模块、函数）	该概念的邻域解释

文中强调这些命令“返回一个范围化子图，通常远小于 GRAPH_REPORT.md 或原始 grep 输出”。这正是该设计对 LLM 的价值：token 消耗可控、答案可追溯。补充一点背景——README.md 说明图谱中每条边都带置信度标签（EXTRACTED = 源码中显式存在，INFERRED = 由符号解析推导得出），因此 query 返回的子图不仅更小，还自带“哪些是读出来的、哪些是推出来的”证据区分。

第四层——回退策略：Read GRAPH_REPORT.md only for broad architecture review or when those commands do not surface enough context。即 GRAPH_REPORT.md 不是被禁用，而是降级为兜底：仅用于宽范围的架构综述，或前三条命令都拿不到足够上下文时。这保证了 agent 不会把全量报告塞进每次对话，同时保留了完整审阅能力。

可以推断，这条决策链与仓库中其他 always-on 块（如 claude-md.md、agents-md.md）遵循同一套语义——它们都由同一 fragment 家族生成、面向不同宿主；Kiro 版只是其中适配 steering 文件格式的一支。对 Claude Code 等 hook 平台，graphify 还提供 --strict 模式真正拦截首次原始文件读取；而 Kiro 这类 instruction-file 平台靠的就是这段始终在场的话来“引导”（nudge）助手走图谱路径。

4. 实操核对清单

在任意目标项目中验证本机制是否生效（只涉及查看与运行，不修改本仓库）：

# 1. 安装到 Kiro（项目作用域）
graphify kiro install
# 预期输出含：.kiro/steering/graphify.md  ->  always-on steering written

# 2. 检查 steering 文件
cat .kiro/steering/graphify.md   # 应与 graphify/always_on/kiro-steering.md 内容一致
cat .kiro/skills/graphify/SKILL.md

# 3. 构建/更新图谱（生成 graphify-out/graph.json 后 steering 规则才开始生效）
graphify /graphify 或按 SKILL.md 指引构建

# 4. 验证 steering 指向的三条命令
graphify query "what connects auth to the database?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

# 5. 升级后重跑 install：内容一致则提示 already configured，不一致则 updated
# 6. 卸载
graphify kiro uninstall

注意适用前提：steering 规则本身是无条件生效的（inclusion: always），但其核心指令受 graphify-out/graph.json 存在这一条件约束；若项目尚未运行过 graphify 构建，agent 读到的是规则本身而非图谱数据。

5. 小结

graphify/always_on/kiro-steering.md 虽然只有 5 行，却是 graphify 在 Kiro 平台上“查询优先”策略的全部载体：inclusion: always 让它进入每轮对话，正文则规定了“图谱存在 → 先 query/path/explain 拿范围化子图 → 才回退读 GRAPH_REPORT.md”的完整决策链。它的工程闭环同样清晰：fragment 由 tools/skillgen/ 生成与漂移守护，安装由 graphify/install.py 以幂等且可覆盖升级的方式落盘，卸载对称清理——这正是 graphify 让“本地确定性 AST 解析出的知识图谱”真正被 AI 助手日常消费的关键一环。