clean-csv-toolkit v0.1.0
这是一个小型、诚实的工具包，用于处理工作代理经常要做的任务：读取某人发送给您的 CSV 文件，弄清楚它的内容，清理它，并仅将安全的行转发到下游。它仅使用 Python 3 标准库构建，不需要 pandas、numpy、pip 安装或远程调用。
此技能的功能
scripts/inspect.py — 分析 .csv / .tsv / .jsonl 文件：行数、自动检测的列类型（int、float、bool、date、datetime、string、empty）、每列空值计数、每列唯一值计数（上限）、每列三个样本值、文件大小和检测到的编码。
scripts/validate.py — 验证文件是否符合小型 JSON 模式（必需列、每列类型、最小/最大值、枚举、正则表达式、唯一性）。退出代码为 0/1，因此可以集成到 CI 中。
scripts/dedupe.py — 删除重复行，方法是全行匹配或按键列匹配。可选参数 --keep first|last、--case-insensitive、--trim 和 JSONL 报告每个删除的行。
scripts/diff.py — 比较两个文件，按键列比较，并将每行分类为添加、删除、更改或未更改，并提供更改行的每列差异。
scripts/convert.py — 在 CSV、TSV、JSON Lines、JSON 数组和 GitHub 风格的 Markdown 表格之间转换。
scripts/check_deps.sh — 验证 python3 是否可用。
此技能不做什么
它不调用任何 LLM、Web 服务或远程 API。
它不将整个数据框加载到内存中，只是为了进行简单的结构工作；辅助函数在可能的情况下会流式传输行。
它不在调用者提供的输入/输出路径之外写入任何内容。
它不进行统计分析（均值、百分位、相关性）。对于这些操作，请使用数据框库。
它不解析 Excel 文件（.xls / .xlsx）。请先导出为 CSV。
所需依赖
bash scripts/check_deps.sh
仅需要 python3。该技能使用 csv、json、re、pathlib、argparse、datetime、collections —— 所有这些都是标准库的一部分。
工作流程
python3 scripts/inspect.py customers.csv
输出：文件：/path/customers.csv
大小：284 B（284 字节）
编码：utf-8
种类：csv
行数：5
列数：6
# 名称 类型 空值 空值% 唯一值 样本
----------------------------------------------------------------------------------------------------
1 id int 0 0.00 5 '1'、'2'、'3'
2 email string 0 0.00 5 'alice@example.com'、...
3 name string 0 0.00 5 'Alice'、'Bob'、'Carol'
4 amount float 1 20.00 4 '42.50'、'100.00'、'7.25'
5 status string 0 0.00 3 'approved'、'pending'、...
6 signup_date date 0 0.00 5 '2025-01-15'、...
传递 --json 以获得机器可读的输出，该输出可以传递到其他工具中。脚本自动检测方言（CSV 与 TSV 与 JSON Lines）和合理的编码（utf-8、utf-8-sig、cp1252、latin-1）。类型推断最多取每列 1000 个非空值，并选择最具体的类型以适应所有这些值。
编写 schema.json：
{
"required_columns": ["id", "email", "amount", "status"],
"columns": {
"id": {"type": "int", "required": true, "unique": true, "min": 1},
"email": {"type": "string", "required": true, "regex": ".+@.+\\..+"},
"amount": {"type": "float", "min": 0, "max": 100000},
"status": {"type": "string", "enum": ["pending", "approved", "rejected"]},
"signup_date": {"type": "date"}
}
}
然后：
python3 scripts/validate.py customers.csv --schema schema.json
干净的文件退出代码为 0，结果为：通过。
坏文件退出代码为 1，带有详细的错误表：
行 列 名称 类型 详细信息
----------------------------------------------------------------------------------------------------
2 email regex_mismatch 值不匹配正则表达式 | 值='not-an-email'
2 amount bad_type 值不匹配类型 'float' | 值='abc'
3 amount below_min 值 -50.0 < 最小值 0 | 值='-50.00'
3 status not_in_enum 值不在允许的集合中 | 值='unknown_status'
4 id duplicate_unique 值已经在此列中看到 | 值='1'
传递 --json 以获得结构化报告，并传递 --max-errors N 以在大文件上限制收集。
按全行匹配（任意两行在每列中都相同）：
python3 scripts/dedupe.py messy.csv clean.csv
按键列（每个 id 只有一行规范行）：
python3 scripts/dedupe.py messy.csv clean.csv --key id \
--removed-report removed.jsonl --keep first
（默认）保留较早出现的行；--keep last 保留较晚出现的行 —— 当较晚的行是更正时很有用。--case-insensitive 和 --trim 正则化...
by