data-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data Tools Skill

结构化数据处理工具技能指南

Critical Rule

核心规则

NEVER use
grep
,
sed
, or
awk
on JSON, YAML, TOML, XML, or CSV data.

These text-processing tools treat structured data as flat text. They break on multi-line values, nested structures, quoted strings containing delimiters, and field reordering. Use the right tool for the format.

绝对不要在JSON、YAML、TOML、XML或CSV数据上使用
grep
、
sed
或
awk
。

这些文本处理工具会将结构化数据视为纯文本处理。它们会在多行值、嵌套结构、包含分隔符的带引号字符串以及字段重排序场景下失效。请针对对应格式使用正确的工具。

Tool Selection Guide

工具选择指南

Format	Tool	Notes
JSON	jq	Or `gh --jq` for GitHub CLI output
YAML	yq	Same jq-like syntax, in-place editing
TOML	dasel	Native TOML support
XML	dasel	Or `xmlstarlet` for XPath
CSV / TSV	qsv	Fast, memory-efficient, purpose-built
Mixed / multiple	dasel	Universal selector, auto-detects format

Quick decision:

One format, one file? Use the format-specific tool (jq/yq/qsv).
Multiple formats or TOML/XML? Use dasel.
GitHub CLI output? Use
```
gh --jq
```
flag directly (never pipe to jq).

格式	工具	备注
JSON	jq	处理GitHub CLI输出时可使用 `gh --jq`
YAML	yq	与jq类似的语法，支持原地编辑
TOML	dasel	原生支持TOML格式
XML	dasel	或使用 `xmlstarlet` 处理XPath表达式
CSV / TSV	qsv	快速、内存高效、专为表格数据打造
混合/多种格式	dasel	通用选择器，可自动检测格式

快速决策建议：

单一格式、单一文件？使用对应格式的专用工具（jq/yq/qsv）。
多种格式或处理TOML/XML？使用dasel。
GitHub CLI输出？直接使用
```
gh --jq
```
参数（绝对不要通过管道传递给jq）。

Quick Examples

快速示例

jq -- JSON

jq -- JSON处理

bash

jq -r '.version' package.json
jq '.users[] | select(.role == "admin")' users.json
jq '.version = "2.0.0"' pkg.json > pkg.json.tmp && mv pkg.json.tmp pkg.json

bash

jq -r '.version' package.json
jq '.users[] | select(.role == "admin")' users.json
jq '.version = "2.0.0"' pkg.json > pkg.json.tmp && mv pkg.json.tmp pkg.json

yq -- YAML

yq -- YAML处理

bash

yq '.services.web.image' docker-compose.yml
yq -i '.jobs.test.strategy.matrix.php-version = ["8.2", "8.3", "8.4"]' .github/workflows/ci.yml

bash

yq '.services.web.image' docker-compose.yml
yq -i '.jobs.test.strategy.matrix.php-version = ["8.2", "8.3", "8.4"]' .github/workflows/ci.yml

dasel -- TOML / XML / Universal

dasel -- TOML / XML / 通用处理

bash

dasel -f Cargo.toml '.package.version'
dasel put -f config.json -t string -v "localhost" '.database.host'
dasel -f input.json -w yaml

bash

dasel -f Cargo.toml '.package.version'
dasel put -f config.json -t string -v "localhost" '.database.host'
dasel -f input.json -w yaml

qsv -- CSV / TSV

qsv -- CSV / TSV处理

bash

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

bash

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

GitHub CLI -- always use --jq

GitHub CLI -- 始终使用--jq参数

bash

gh api repos/owner/repo/releases --jq '.[0].tag_name'
gh pr list --json number,title --jq '.[] | "\(.number)\t\(.title)"'

bash

gh api repos/owner/repo/releases --jq '.[0].tag_name'
gh pr list --json number,title --jq '.[] | "\(.number)\t\(.title)"'

Anti-Patterns

反模式示例

bash

undefined

bash

undefined

BAD: grep/sed on JSON (breaks on formatting, nesting, escapes)

错误：在JSON上使用grep/sed（会在格式、嵌套、转义场景下失效）

grep '"version"' package.json | sed 's/.: "(.)".*/\1/'

GOOD:

正确：

jq -r '.version' package.json


```bash

jq -r '.version' package.json


```bash

BAD: sed on YAML (ignores indentation, multi-line values)

错误：在YAML上使用sed（忽略缩进、多行值）

sed -i 's/image: node:.*/image: node:20/' docker-compose.yml

GOOD:

正确：

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


```bash

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


```bash

BAD: awk on CSV (breaks on quoted fields containing commas)

错误：在CSV上使用awk（会在包含逗号的带引号字段场景下失效）

awk -F',' '{print $2}' data.csv

GOOD:

正确：

qsv select 2 data.csv

---

qsv select 2 data.csv

---

References

参考资料

Cookbook	Content
jq Cookbook	Extraction, filtering, transformation, GitHub CLI patterns
yq Cookbook	YAML editing, GitHub Actions, Docker-Compose, Kubernetes
dasel Cookbook	TOML/XML editing, format conversion, universal selector
CSV Processing	qsv workflows, joins, stats, large file handling

External docs: jq manual | yq docs | dasel docs | qsv docs

手册	内容
jq 手册	提取、过滤、转换、GitHub CLI使用模式
yq 手册	YAML编辑、GitHub Actions、Docker-Compose、Kubernetes配置
dasel 手册	TOML/XML编辑、格式转换、通用选择器
CSV 处理指南	qsv工作流、连接、统计、大文件处理

外部文档：jq 官方手册 | yq 官方文档 | dasel 官方文档 | qsv 官方文档