xsv/qsv - 极速 CSV 分析工具箱

技能脚本入口

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

macOS / Linux（bash）：

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

Windows（PowerShell）：

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

可用子命令： index、count、headers、stats、frequency、sample、slice、select、search、join、partition、split、cat、table、fmt、fixlengths、reverse、flatten、pivot、dedup、cast、replace、sql

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

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

这是什么

xsv (BurntSushi/xsv, 10.8k ⭐) 和其维护版 qsv (dathere/qsv, 5.2k ⭐) 是用 Rust 编写的高性能 CSV/TSV 处理工具箱。核心特性：索引加速、流式处理、常数时间随机访问、并行计算。适合 GB 级大文件。

• xsv GitHub: https://github.com/BurntSushi/xsv (已归档，推荐用 qsv)
• qsv GitHub: https://github.com/dathere/qsv (活跃维护，功能更多)
• 文档: https://github.com/dathere/qsv/blob/master/docs/index.md
• 单二进制，零依赖，极快

何时使用我

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

• "xsv/qsv 命令"、"处理大 CSV 文件"
• "CSV 统计/摘要/频率分析"
• "CSV 切片/采样/分割/合并"
• "CSV 连接/关联" (join 多个 CSV)
• "CSV 格式化/对齐输出" (table 美化)
• "CSV 搜索/过滤/正则匹配"
• "CSV 列选择/重排/重命名"
• "大文件随机访问/快速切片"
• "数据清洗/类型推断/异常检测"

核心能力

1. 索引加速 (核心特性)

# 创建索引 (一次性，极快)
xsv index data.csv
# 或 qsv index data.csv

# 索引后所有操作常数时间：
xsv count data.csv        # 瞬间返回行数
xsv slice -s 1000000 data.csv  # 直接跳到第 100 万行
xsv stats data.csv        # 并行统计，秒级完成

2. 数据概览与统计

# 显示表头
xsv headers data.csv

# 统计行数 (有索引瞬间完成)
xsv count data.csv

# 完整统计：类型、范围、均值、标准差、中位数、众数、基数
xsv stats data.csv
xsv stats --everything data.csv | xsv table  # 美化输出

# 频率分析 (Top N)
xsv frequency data.csv
xsv frequency --limit 10 data.csv

# 采样预览 (水库抽样，内存恒定)
xsv sample 10 data.csv | xsv table

3. 切片与采样

# 切片：行范围 (有索引极快)
xsv slice -s 100 -e 200 data.csv        # 第 100-200 行
xsv slice -s 100 data.csv               # 第 100 行到末尾
xsv slice -l 50 data.csv                # 最后 50 行

# 随机采样 (水库抽样，大文件也快)
xsv sample 100 data.csv | xsv table

# 逆序
xsv reverse data.csv | head -20

4. 列操作

# 选择/重排列
xsv select col1,col3,col2 data.csv

# 排除列
xsv select '!col2,col4' data.csv

# 重命名列
xsv select 'old_name:new_name,other_col' data.csv

# 扁平化查看单行 (调试用)
xsv slice -i 5 data.csv | xsv flatten

5. 搜索与过滤

# 正则搜索 (逐字段匹配)
xsv search 'pattern' data.csv
xsv search -s 'col_name' 'pattern' data.csv  # 指定列

# 选择满足条件的行 (需配合其他工具)
xsv search 'active' data.csv | xsv select id,name,status

6. 连接 (Join) - 强大功能

# 内连接 (默认)
xsv join --left id users.csv id orders.csv

# 左/右/全外连接
xsv join --left id users.csv id orders.csv
xsv join --right id users.csv id orders.csv
xsv join --outer id users.csv id orders.csv

# 多键连接
xsv join --left 'id,date' users.csv 'id,date' orders.csv

# 无索引也可工作，有索引极快

7. 数据重塑

# 分割：按列值分文件
xsv partition -s category data.csv

# 分割：按行数分块
xsv split 10000 data.csv  # 每 1 万行一个文件

# 合并：按行拼接
xsv cat file1.csv file2.csv > combined.csv

# 合并：按列拼接 (同行数)
xsv cat --columns file1.csv file2.csv > combined.csv

# 格式化：对齐输出 (弹性制表符)
xsv table data.csv

# 重新格式化：分隔符、引用规则
xsv fmt -t '|' -q always data.csv  # 管道分隔、强制引用

8. 数据清洗

# 修复不等长记录 (填充/截断)
xsv fixlengths data.csv

# 类型推断与统计
xsv stats --everything data.csv | xsv table

# 搜索异常值
xsv search -s 'age' '^[^0-9]' data.csv  # 非数字年龄

9. qsv 独有高级功能

# 数据透视表
qsv pivot -r region -c product -v sales data.csv

# 数据去重
qsv dedup data.csv

# 类型转换
qsv cast -t 'col1:int,col2:float,col3:date' data.csv

# 正则替换
qsv replace -p 'col' -r 'old' -R 'new' data.csv

# SQL 查询 (实验性)
qsv sql "SELECT * FROM data WHERE age > 30" data.csv

# JSON Lines 输入/输出
qsv input jsonl data.jsonl | qsv stats

典型工作流示例

场景 1：GB 级日志/交易数据快速探索

# 1. 建立索引 (一次性，几秒)
xsv index huge_transactions.csv

# 2. 瞬间知道规模
xsv count huge_transactions.csv
# 127,453,291 rows

# 3. 秒级统计概览
xsv stats huge_transactions.csv | xsv table

# 4. 抽样看数据分布
xsv sample 20 huge_transactions.csv | xsv table

# 5. 切片看特定时间段 (配合日期排序)
xsv slice -s 1000000 -l 100 huge_transactions.csv | xsv table

场景 2：多表关联分析 (订单 + 用户 + 商品)

# 1. 为各表建索引
xsv index users.csv
xsv index orders.csv
xsv index products.csv

# 2. 连接查询：用户 + 订单
xsv join --left user_id users.csv user_id orders.csv > user_orders.csv

# 3. 再连接商品
xsv join --left product_id user_orders.csv product_id products.csv > full_data.csv

# 4. 统计分析
xsv stats full_data.csv | xsv table
xsv frequency full_data.csv --limit 20

场景 3：数据清洗管道

# 1. 检查结构
xsv headers dirty.csv
xsv stats dirty.csv | xsv table

# 2. 修复长度不一致
xsv fixlengths dirty.csv > clean1.csv

# 3. 统一格式
xsv fmt -t ',' -q minimal clean1.csv > clean2.csv

# 4. 采样验证
xsv sample 50 clean2.csv | xsv table

场景 4：报表生成与导出

# 1. 选择需要的列
xsv select date,customer,product,amount,region sales.csv > report_base.csv

# 2. 格式化为美观表格
xsv table report_base.csv > report.txt

# 3. 或转为 JSON 供前端用
xsv select date,customer,product,amount,region sales.csv | \
  xsv fmt -t ',' | \
  python -c "import sys,csv,json; print(json.dumps(list(csv.DictReader(sys.stdin))))" > report.json

场景 5：大文件分片并行处理

# 1. 分割成 10 万行 chunks
xsv split 100000 huge.csv

# 2. 并行处理每个 chunk (GNU parallel)
ls huge.*.csv | parallel -j 8 'xsv stats {} | xsv table > {.}.stats.txt'

# 3. 合并统计结果
cat huge.*.stats.txt | xsv table > combined_stats.txt

命令速查表

qsv 独有命令 (推荐迁移)

安装方式

# xsv (原版，已归档)
# macOS
brew install xsv

# Linux (二进制)
cargo install xsv

# qsv (推荐，活跃维护)
# macOS
brew install qsv

# Linux
cargo install qsv

# 或下载预编译二进制 (GitHub Releases)

性能对比参考

故障排查

相关技能

• visidata - 交互式终端电子表格 (可视化探索、透视图)
• miller - 命名索引数据处理 (awk 风格，更适合流式转换)
• dasel - 统一选择器跨格式查询
• yq - YAML/JSON/XML/CSV 互转
• sqlite-utils - CSV 导入 SQLite 做复杂 SQL 查询
• gron - JSON 扁平化 (CSV 转 JSON 后可用)

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