graphify 的 Kilo 专属技能规则：原生 Task 语义抽取 fan-out 与会话内增量更新

本指南剖析 graphify 为 Kilo Code 平台定制的技能片段 kilo-rules：它规定了语义抽取阶段如何用原生 Task 工具做扇出（fan-out）、为何所有分块任务必须在同一条响应内并行启动、抽取子代理必须使用什么类型，以及修改代码后如何用 graphify update . 让图谱与会话内的代码改动保持同步。读完本文，你将理解这条 4 行规则的来龙去脉——它源自哪里、如何被渲染进最终技能产物、每条规则的底层实现支撑，以及如何验证安装产物。

这段规则从哪来：skillgen 单源片段与渲染产物

kilo-rules 并不是独立散落的笔记，而是 graphify 技能生成管线（skillgen）中的**单源片段（single source of truth）**之一。仓库将"编辑者维护的内容"与"提交到仓库的技能产物"严格分离：

• 人编辑的源文件位于 tools/skillgen/fragments/，按 always-on / core / dispatch / extra / query-stub / references / shell 分目录组织；
• gen.py 在构建期把这些片段渲染成 graphify/skill*.md 以及 graphify/skills/<platform>/references/ 下的提交产物；
• expected/ 保存字节级快照，配合 --check 在 CI 与 pre-commit 中防漂移（drift guard）——任何人手工改动生成文件、或快照过期，都会被字节比对逮住。

kilo-rules 源片段位于 tools/skillgen/fragments/extra/kilo-rules.md，它属于"平台额外尾部"这一类片段。在 platforms.toml 的 Kilo 平台声明里可以清楚地看到它如何被装配：

[platform.kilo]
bucket = "split"
core = "core"
skill_dst = "graphify/skill-kilo.md"
refs_dst = "graphify/skills/kilo/references"
dispatch = "agent-tool-disk"
extraction = "verbose"
extra_sections = ["kilo-rules"]

也就是说：Kilo 走 split（共享精简核心 + 按需参考文档）路线，核心模板是 fragments/core/core.md，refs_dst 指向 graphify/skills/kilo/references/，并且在所有平台上只有 Kilo 通过 extra_sections 声明了 kilo-rules 这个额外尾部。在 gen.py 中，extra_sections 对应的片段会被依次读取、拼接进 @@EXTRA@@ 槽位，且按 platforms.toml 注释约定插在 Honesty Rules 之前。

这解释了为何你在全仓库搜索 Kilo-specific rules 只会命中少数几处：渲染后的产物 graphify/skill-kilo.md 恰好位于 ## Honesty Rules 之前。同时，gen.py 的覆盖率审计把 Kilo 旧版（v8）正文里的 ### Kilo-specific rules 显式登记进 _CONSOLIDATION_ALLOWLIST，说明该内容在拆分重构时被有意保留并提升为 ## 二级标题，而非被丢弃（参见 gen.py 对 kilo 的 allowlist 注释）。

语义抽取在 Kilo 上的原生 fan-out（规则 1–3 详解）

先回到技能主流程：Step 3 的抽取分为**结构化抽取（AST，确定性、免费、无需 LLM）和语义抽取（LLM，消耗 token）**两部分。纯代码语料直接走 Part A，无需 API Key；只有文档、论文、图片等非代码文件才会进入 Part B 语义抽取。Part B 的做法是把未命中缓存的非代码文件按 20–25 个一组切成 chunk（每张图片独占一个 chunk，图片需要独立的视觉上下文），每个 chunk 交给一个子代理，子代理要把结果 JSON 写回磁盘上的 graphify-out/.graphify_chunk_NN.json。

共享核心模板里，Part B2 面向的是 Claude 风格的 "Agent 工具 + subagent_type="general-purpose"" 措辞（见 fragments/dispatch/agent-tool-disk.md）。但 Kilo 平台的运行时并不相同，因此 kilo-rules 尾部用三条规则给出平台权威性覆盖，把通用措辞映射为 Kilo 原生语义：

• 使用原生 Task 工具做语义抽取 fan-out。 语义抽取必须一次性派出与 chunk 数量相等的多个子代理，逐个亲自读取文件是 5–10 倍慢的禁忌做法；子代理需要 Write 与 Bash 权限才能把 chunk 结果落盘。在 Kilo 上，这一并行任务机制对应的就是其原生 Task 工具。
• 所有 chunk 任务必须在同一条响应中启动。 这是"并行"的唯一实现方式：先发一个 Task、等待返回、再发下一个，就退化成了串行，fan-out 失去意义。渲染产物 graphify/skill-kilo.md 给了 3 个 chunk 的具体示例——3 个任务调用同属一条消息，而不是三条消息。
• 抽取 chunk 一律使用 subagent_type="general"。 这是 Kilo 上允许的类型；绝不能使用只读的 Explore 类型，因为它无法写盘，会导致 chunk 结果静默丢失。落盘检查是成功信号：Part B3 在收集阶段会逐个确认 graphify-out/.graphify_chunk_NN.json 是否存在，缺失即打印"chunk N missing from disk — subagent may have been read-only"的告警；若超过一半 chunk 失败或缺失，则应停下来让用户重新运行并确保使用 general 类型。

值得注意的细节是：chunk 的 JSON schema、节点 ID 规则、置信度评分（EXTRACTED/INFERRED/AMBIGUOUS）、hyperedges 与视觉规则，都在抽取规范参考文档中定义。Kilo 平台配置了 extraction = "verbose"，因此渲染时选用的是完整版规范（verbose 变体，源文件见 fragments/references/shared/extraction-spec.md），对应产物为 graphify/skills/kilo/references/extraction-spec.md——Step B2 加载它并把完整提示词原文交给每个子代理。

规则四：会话内改完代码就跑 graphify update .

第四条规则解决的是图谱与当前会话状态漂移的问题：当 Agent 在一次会话中修改、新增或删除了代码文件后，磁盘上的 graphify-out/graph.json 是基于旧代码构建的，若立即用自然语言提问，图谱会给出过期答案。此时无需重跑完整的 Step 1–9，只需：

graphify update .

这条 CLI 路径的底层实现位于 cli.py 的 cmd == "update" 分支。值得展开的机制点包括：

• 无 LLM 的代码增量重建。 该命令读取可选的路径参数（默认是 .），随后调用 graphify.watch._rebuild_code(...) 只对代码文件做增量 AST 重抽取——因为 AST 是确定性解析，不需要任何模型调用，成本极低。运行成功后会打印 Code graph updated.，并提示"文档/论文/图片类的改动请在你的 AI 助手中运行 /graphify --update"——也就是说语义侧（Part B）仍要走缓存增量流程，代码侧则走这条轻量快速通道。
• 扫描根目录的自恢复。 若省略路径参数，CLI 会尝试读取上次完整构建写入的 graphify-out/.graphify_root 来恢复扫描根；不存在时才回退到 .。这与主技能 Step 1 中把扫描根保存到 .graphify_root 的逻辑呼应（参见 graphify/skill-kilo.md），保证 graphify update . 与你之前构建的语料位置一致。
• 可选参数。 支持 --force（穿透 graph.json 的 shrink 保护强制重建）与 --no-cluster（跳过昂贵的社区聚类步骤）；同时读取 GRAPHIFY_FORCE 环境变量。若想深入了解增量更新背后的"只重抽取变更文件 + manifest 差异"机制，可阅读 fragments/references/shared/update.md，它对应渲染产物 graphify/skills/kilo/references/update.md。

规则在 Kilo 安装产物中的体现

这些规则最终装进 Kilo Code 的是渲染后的完整技能包。从 install.py 可以看到 Kilo 平台的目标位置：

• 技能文件渲染为 skill-kilo.md，安装到 ~/.config/kilo/skills/graphify/SKILL.md；
• 参考文档目录 graphify/skills/kilo/references/ 随技能一起部署；
• 由于 "Kilo Code 也支持原生的 /graphify 命令文件"（install.py），安装器还会把包内的 command-kilo.md 复制为 ~/.config/kilo/command/graphify.md，让用户可以直接用原生 /graphify 触发。

同时 _kilo_install 会先调用 install(platform="kilo") 再调用 _agents_install(...)（install.py），即把 always-on 项目接线写入 AGENTS.md 一类的共享规则文件；命令行入口为 graphify kilo install / graphify kilo uninstall（cli.py）。也就是说：语义抽取的并行纪律写在 SKILL.md 正文（kilo-rules 尾部），而"什么时候自动重建、装在哪里"则由安装器与 AGENTS.md 接线决定。

维护与校验视角：这条片段如何被保护

由于 kilo-rules 是片段（fragment），对它唯一的正确修改位置就是源片段本身，而不是渲染产物。skillgen 提供了对应的构建与防漂移命令（构建期工具，不随 wheel 分发，见 gen.py）：

python -m tools.skillgen                    # 全量重新渲染所有平台的产物
python -m tools.skillgen --platform kilo    # 只渲染 Kilo
python -m tools.skillgen --check            # 字节比对渲染结果 vs 提交产物 + expected/，有漂移则退出码 1
python -m tools.skillgen --bless            # 用当前渲染刷新 expected/ 快照

渲染被刻意设计为幂等：平台槽位按固定顺序填充、参考索引按名称排序、统一 LF 换行、绝不写入时间戳或版本号。Kilo 的渲染快照保存在 tools/skillgen/expected/graphify__skill-kilo.md，任何不经片段的直接改动都会被 --check 拦截。想验证你本机 Kilo 技能文件里确实含有这四条规则，直接查看安装路径下的 SKILL.md 中 ## Kilo-specific rules 一节即可——它与本仓库源片段逐字节一致。

小结

kilo-rules 用四条精简规则锁定了 graphify 在 Kilo Code 平台上的关键行为契约：语义抽取必须通过原生 Task 工具做真正的并行扇出、一律使用 general 子代理类型，并在会话内改动代码后用 graphify update . 保持图谱新鲜。理解这条片段的完整链路——从 源片段、经 platforms.toml 的装配与 gen.py 的渲染、到 skill-kilo.md 的最终产物与 install.py 的部署——能帮助你在实际使用中判断：哪些工作适合交给无 LLM 的代码增量通道，哪些文件变更需要走语义抽取的并行 fan-out，以及当图谱与代码不一致时应从哪一层排查。