技能介绍

要解决的问题

在项目里，配置和数据往往分散在 YAML、JSON、XML、CSV、TOML 与 properties 文件中。人工查看、筛选、批量修改或做格式转换时，容易写出依赖行匹配的 grep、sed、脚本；这类方式在字段嵌套、数组、类型变化面前很脆弱，也会让 CI 和本地环境之间的数据处理结果不一致。

技能如何工作

该技能围绕命令行工具 yq 组织结构化数据处理流程：先用 jq 风格的表达式定位目标字段，例如 .a.b[0].c，再决定是读取、更新还是转换为其他格式。它覆盖 YAML、JSON、XML、CSV、TOML 和 properties 等常见结构化文本，适合在脚本、流水线和本地排障中把数据当作有结构的文档来处理，而不是当作一堆需要正则拼接的行。

关键步骤大致是：确认输入格式与期望输出；用路径表达式缩小到需要处理的节点；对结果做必要更新或转换；在写回前检查类型、数组边界、空值和文档分隔符，避免把局部字段误改成整份配置。

适用边界与注意点

yq 的能力来自上游工具，因此表达式语法、默认行为和转换结果会受版本与安装路径影响；接入脚本前应先在目标环境验证。对于多文档、嵌套数组、混合类型或编码异常的输入，需要先明确数据模型，再确认路径表达式与输出格式是否保持了原有语义。转换不等于无损迁移：字段顺序、注释、默认值和宿主工具的特殊解析规则可能无法完全保留，关键数据应在变更后做结构化校验和 diff 检查。