data-tools

数据工具技能

关键规则

绝不要对 JSON、JSONL、YAML、TOML、XML 或 CSV 使用 grep、sed、awk 或内联解释器（python3 -c、node -e）。 请拒绝并使用正确的工具——文本工具无法处理结构化数据；内联脚本冗长且脆弱。

---

关键模式

有关传统工具 → 现代工具的通用对比（grep→rg、 find→fd、cat→bat，……），请参阅 cli-tools 技能的表格。

转换： dasel -w FORMAT 或 yq -o FORMAT。

jq——JSON（不支持原地修改）

jq -r '.version' package.json
jq '.users[] | select(.role == "admin") | .name' users.json
jq '.version = "2.0.0"' pkg.json > pkg.json.tmp && mv pkg.json.tmp pkg.json
jq -s '.[0] * .[1]' base.json override.json

或者，若数据源来自 GitHub CLI，可使用 gh --jq（见下文）——无需单独运行 jq 进程。

yq——YAML（原地修改 -i）

yq '.services.web.image' docker-compose.yml
yq -i '.services.app.image = "node:20"' docker-compose.yml
yq -o json config.yml

dasel——TOML（唯一原生工具）/ XML（或使用 xmlstarlet 处理 XPath）/ 通用自动检测

dasel -f Cargo.toml '.package.version'
dasel put -f config.toml -t string -v "2.0" '.project.version'
dasel -f input.json -w yaml

qsv——CSV / TSV

qsv headers data.csv && qsv stats data.csv --everything | qsv table
qsv search -s status "active" users.csv | qsv select name,email
qsv join user_id orders.csv id users.csv

qsv index、stats 和 frequency 会在输入文件旁写入文件（x.csv.idx、x.stats.csv*）。在代码库或软件包目录中，请对副本运行这些命令（详情）。

mlr——JSONL / 多格式 / DSL（原地修改 -I）

mlr --c2j cat data.csv
mlr --jsonl filter '$level == "error"' logs.jsonl
mlr -I --csv put '$total = $qty * $price' orders.csv

GitHub CLI——始终使用 --jq

gh api repos/owner/repo/releases/latest --jq '.tag_name'
gh pr list --json number,title --jq '.[] | [.number, .title] | @tsv'

---

反模式

# BAD → GOOD: jq -r '.version' package.json
grep '"version"' package.json | sed 's/.*"\(.*\)".*/\1/'
# BAD → GOOD: yq -i '.services.app.image = "node:20"' compose.yml
sed -i 's/image: node:.*/image: node:20/' docker-compose.yml
# BAD → GOOD: qsv select 2 data.csv
awk -F',' '{print $2}' data.csv
# BAD → GOOD: jq -r '.version' plugin.json
python3 -c 'import json;print(json.load(open("plugin.json"))["version"])'

---

参考资料

Cookbook	内容
jq Cookbook	筛选、转换、GitHub CLI、大型输入（“Argument list too long”、Windows）
yq Cookbook	Actions、Compose、K8s
dasel Cookbook	TOML/XML、转换
CSV Processing	qsv 工作流、联接
mlr Cookbook	JSONL、DSL、统计、联接
Enforcement Hook	此插件随附的 PreToolUse 门控：禁止提取字段，否则仅警告一次

文档：jq、yq、dasel、qsv、mlr。