技能介绍

要解决什么问题

在把 YAML 清单应用到集群之前，你往往只有一次机会确认变更是否安全。传统做法是跑一次 kubectl diff，或者把两份文件丢给 diff 命令。问题在于，原生行级 diff 只关心字节是否相同：字段被重新排序、apiVersion 写法变化、列表里元素整体平移，都会在输出里炸出大片无意义的红线。真正需要关注的语义变化——比如某个 replicas 从 3 变成 1、某个资源对象被整体删除——反而被淹没在噪音里。

当差异由自动化流水线或 agent 来审查时，这个问题更严重：行级 diff 无法被可靠地解析成「发生了什么」，脚本要么全量放行，要么把噪声当作风险拦截。

这个技能如何工作

核心思路是把比较从「字节层」抬到「结构层」。dyff 解析 YAML 文档，按对象路径组织差异，输出是一棵变化树而不是一段文本补丁：

按路径定位变化：每个差异节点都带完整的对象路径，例如 .spec.template.spec.containers[0].image，你能直接看到改的是哪个字段，而不用在上下文里人工搜索。
按语义忽略噪声：键的顺序变化、空白和注释差异不会触发输出，只有值或结构真正改变时才显示。
输出适合程序消费：支持 --omit-header、--set-exit-code 等选项，退出码可直接作为 CI 的门禁信号，agent 也能稳定地从结构化输出里提取变更条目。

典型工作流只有两步：先把 KUBECTL_EXTERNAL_DIFF 指向 dyff between --omit-header --set-exit-code，之后照常调用 kubectl diff。此后所有清单比较都会走 dyff 的语义路径，不需要改现有的部署习惯。

适用边界与注意点

依赖 dyff 本体：本技能不重新实现比较逻辑，行为完全取决于上游 dyff 的解析规则。YAML 解析歧义、多文档流中的边界情况都以 dyff 的处理为准。
环境要求：dyff 基于 Go 实现，需要 Go 1.23 及以上版本才能构建或安装，运行环境需满足这一前提。
聚焦清单场景：主要面向 Kubernetes 清单这类结构化 YAML。对于任意 YAML（配置模板、数据文件），dyff 同样可用，但语义层级的收益取决于文档是否具备清晰的对象结构。
这是预览手段：kubectl diff 反映的是客户端提交内容与集群当前状态之间的差异，不涉及服务端准入控制、默认值填充等真实生效环节，关键变更仍需在测试环境中验证。