rq - 通用格式转换器

技能脚本入口

本技能附带两套等价包装脚本（Unix .sh + Windows PowerShell .ps1），提供友好子命令入口与安装自检，免去记忆原始参数。

macOS / Linux（bash）：

bash scripts/rq-skill.sh <subcommand> [args...]
# 查看完整用法与示例
bash scripts/rq-skill.sh help

Windows（PowerShell）：

.\scripts\rq-skill.ps1 <subcommand> [args...]
# 若被执行策略拦截，用下面这种调用绕过：
powershell -ExecutionPolicy Bypass -File scripts\rq-skill.ps1 <subcommand> [args...]

可用子命令： convert、stdin、avro、protobuf、query、infer、validate、batch、pretty、compact

脚本选择规则： macOS / Linux 用 .sh；Windows 用 .ps1。两者子命令完全一致。

> 脚本仅作便捷封装，最终调用系统的 rq 二进制；运行前请确保已安装对应工具（安装方式见下文各节）。说明：SkillHub 不支持 .cmd / .bat 文件类型，故不附带 Windows cmd 版；无 PowerShell 的环境可用 Git Bash 运行 .sh 版。个别依赖 Unix 管道工具的子命令（如 gron 的 sed / fzf）在 Windows 下建议用 Git Bash 运行 .sh 版。

这是什么

rq (dflemstr/rq, 3.1k ⭐) 是一个 Record Query 工具，支持在 10+ 种结构化数据格式 间转换：Avro、CBOR、CSV、JSON、MessagePack、Protocol Buffers、TOML、YAML、awk-style text 等。核心特性：模式感知转换、流式处理、查询过滤、单二进制 (Rust)。

• GitHub: https://github.com/dflemstr/rq
• 文档: https://github.com/dflemstr/rq/blob/master/docs/index.md
• 适合：数据互换、ETL 管道、微服务间格式转换、Schema Registry 集成

何时使用我

当用户出现以下意图时加载此技能：

• "rq 命令"、"格式转换"、"avro 转 json"、"protobuf 转 yaml"
• "多格式互转"、"cbor 转 json"、"msgpack 解码"
• "schema 感知转换"、"protobuf schema 注册表"
• "流式转换大文件"、"二进制格式查看"
• "数据管道格式标准化"、"微服务数据互换"

支持格式矩阵

核心能力

1. 基础格式转换

# JSON -> YAML
rq -f json -t yaml data.json > data.yaml

# YAML -> TOML
rq -f yaml -t toml config.yaml > config.toml

# CSV -> JSON (自动推断类型)
rq -f csv -t json data.csv > data.json

# JSON -> CSV (扁平化)
rq -f json -t csv data.json > data.csv

# MessagePack -> JSON (查看二进制)
rq -f msgpack -t json data.msgpack

# CBOR -> JSON
rq -f cbor -t json data.cbor

# 从 stdin 读取，指定格式
cat data.json | rq -f json -t yaml

2. Avro 转换 (需 Schema)

# JSON -> Avro (需 schema 文件)
rq -f json -t avro --schema schema.avsc data.json > data.avro

# Avro -> JSON
rq -f avro -t json --schema schema.avsc data.avro > data.json

# Avro -> JSON (schema 内嵌在文件)
rq -f avro -t json data.avro > data.json

# 多记录 Avro 文件
rq -f avro -t jsonl --schema schema.avsc data.avro > data.jsonl

3. Protocol Buffers 转换 (需 .proto)

# JSON -> Protobuf
rq -f json -t protobuf --proto user.proto --message User data.json > data.pb

# Protobuf -> JSON
rq -f protobuf -t json --proto user.proto --message User data.pb > data.json

# Protobuf -> YAML
rq -f protobuf -t yaml --proto user.proto --message User data.pb > data.yaml

# 多消息类型
rq -f protobuf -t json --proto all.proto --message Package.Message data.pb

4. 查询与过滤 (Record Query)

# 选择字段
rq -f json -t json '.name, .email' data.json

# 过滤记录
rq -f json -t json 'select(.age > 30)' data.json

# 映射转换
rq -f json -t json 'map({name: .name, adult: .age >= 18})' data.json

# 聚合
rq -f json -t json 'reduce(.[]; .age | sum)' data.json

# 组合管道
rq -f json -t json 'select(.active) | .name | upper' data.json

5. 流式处理 (大文件/管道)

# JSON Lines 流式转换 (常数内存)
cat huge.jsonl | rq -f jsonl -t csv > huge.csv

# 压缩文件透明处理
rq -f json.gz -t yaml data.json.gz > data.yaml
rq -f json -t yaml.gz data.json > data.yaml.gz

# 管道链式
curl -s api.example.com/data.json | rq -f json -t csv | gzip > data.csv.gz

6. Schema 管理

# 从数据推断 schema
rq infer -f json data.json > inferred.avsc
rq infer -f csv data.csv > inferred.avsc

# 验证数据对 schema
rq validate -f avro --schema schema.avsc data.avro

# Schema 注册表集成 (Confluent/Apicurio)
rq -f json -t avro --schema-registry http://localhost:8081 --subject user-value data.json

7. 输出格式控制

# JSON 格式化
rq -f json -t json --pretty data.json

# JSON 紧凑
rq -f json -t json --compact data.json

# CSV 分隔符
rq -f csv -t json --csv-delimiter ';' data.csv

# CSV 无表头
rq -f csv -t json --no-headers data.csv

# YAML 流格式 (多文档)
rq -f json -t yaml --yaml-stream data.json

8. 批量转换

# 目录下所有 JSON -> YAML
for f in *.json; do
  rq -f json -t yaml "\$f" > "\${f%.json}.yaml"
done

# 并行转换 (GNU parallel)
ls *.json | parallel -j 4 'rq -f json -t yaml {} > {.}.yaml'

典型工作流示例

场景 1：微服务数据互换标准化

# 服务 A 输出 Avro (Kafka)
# 服务 B 需要 JSON (REST)
# 网关层转换：

# 1. 从 Kafka 消费 Avro
kafka-console-consumer --topic user-events --bootstrap-server localhost:9092 \
  --property schema.registry.url=http://sr:8081 \
  | rq -f avro -t json --schema-registry http://sr:8081 --subject user-events-value \
  > user_events.jsonl

场景 2：数据湖格式统一 (Parquet/Avro -> JSONL)

# 1. Avro 文件转 JSONL (流式)
rq -f avro -t jsonl --schema schema.avsc part-00000.avro > part-00000.jsonl

# 2. CBOR 日志转 JSON
rq -f cbor -t jsonl logs.cbor > logs.jsonl

# 3. 统一导入数据仓库

场景 3：Protocol Buffers 调试

# 1. 二进制 pb 文件查看
rq -f protobuf -t json --proto user.proto --message User response.pb | jq .

# 2. JSON 请求转 pb 发送
rq -f json -t protobuf --proto api.proto --message Request request.json | \
  grpcurl -d @ localhost:50050 service.Method

场景 4：配置文件多格式同步

# 单一源头 (YAML) -> 多目标格式
rq -f yaml -t json config.yaml > config.json
rq -f yaml -t toml config.yaml > config.toml
rq -f yaml -t env config.yaml > .env
# env 格式输出: KEY=value

场景 5：CSV/Excel 数据清洗管道

# 1. Excel -> CSV (先用其他工具)
# 2. CSV -> JSON -> 清洗 -> CSV
rq -f csv -t json dirty.csv | \
  rq -f json -t json 'select(.email =~ "@") | .email |= lower' | \
  rq -f json -t csv > clean.csv

查询语言速查 (rq 表达式)

# 字段选择
.field                    # 单字段
.field1, .field2         # 多字段
.*                       # 所有字段

# 过滤
select(.age > 30)        # 条件过滤
select(.tags[] == "admin")  # 数组包含

# 映射
map({new_name: .old_name})  # 重命名/计算
map({name, adult: .age >= 18})  # 简写

# 聚合
reduce(.[]; .value | sum)   # 求和
reduce(.[]; .value | max)   # 最大值
group_by(.category)         # 分组

# 字符串
upper, lower, trim
split("."), join(".")

# 条件
if .age > 18 then "adult" else "minor" end

安装方式

# macOS (Homebrew)
brew install rq

# Linux (二进制下载 - GitHub Releases)
# 单文件，解压到 PATH

# Cargo (最新版)
cargo install rq

# Docker
docker run --rm -v "\${PWD}":/data ghcr.io/dflemstr/rq -f json -t yaml /data/config.json

故障排查

相关技能

• dasel - 统一选择器查询/修改 (更适合交互式探索)
• yq - YAML/JSON/XML/CSV/TOML 转换 (更常用格式)
• miller - CSV/TSV/JSON 流式处理 (awk 风格)
• sqlite-utils - 导入 SQLite 做复杂 SQL
• xsv - CSV 统计/连接/切片
• gron - JSON 扁平化 (配合行工具处理)

技能版本: 1.0.0 | 作者: asdw741111 | 适用平台: OpenCode, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI