| 名称 | csv-编码修复医生 |
| 描述 | 诊断并修复 CSV/TSV/TXT 的编码与格式问题——GBK↔UTF-8 乱码、UTF-8 BOM 导致首列名带 \ufeff、CRLF/LF 混用、分号/逗号/TAB 分隔符不匹配、全角数字变文本、列数不齐、公式注入。纯 Python 标准库,无需 pandas。 when_to_use: 用户提到 CSV 乱码、Excel 打开中文乱码、编码转换、GBK 转 UTF-8、带 BOM、分隔符不对、所有列挤在一列、全角数字、列数对不上、导入系统报格式错误、pandas 读取报 UnicodeDecodeError |
| 版本 | 1.0.0 |
| 开源协议 | MIT |
CSV 编码体检与修复
这个技能解决什么
拿到一个 CSV,先回答三个问题,再动手改:
- 它到底是什么编码? 不能靠猜,也不能只靠
chardet的单一结论 —— 本技能给出候选编码 + 打分,把误判概率显式化。 - 它的换行和分隔符是什么? 中文环境下 80% 的“所有列挤在第一列”,是分隔符判定错了,不是数据坏了。
- 改完还是原来的数据吗? 必须有前后一致性校验,否则修完不敢用。
三步工作流
# 第 1 步:体检(不改文件)
python scripts/diag.py 台账.csv
python scripts/diag.py ./exports --json # 批量
# 第 2 步:修复(默认输出 台账.fixed.csv,不动原文件)
python scripts/fix.py 台账.csv \
--to-enc utf-8-sig --to-delim , --eol crlf \
--strip --halfwidth
# 第 3 步:校验(归一化比较,全角/空白差异不计)
python scripts/verify.py 台账.csv 台账.fixed.csv
# 用了 --drop-empty / --fix-formula 时,把这两项声明成有意改动,否则会被报成差异
python scripts/verify.py 台账.csv 台账.fixed.csv --ignore formula,empty
退出码是契约,可以直接接进流水线:
diag.py 0=干净 1=有问题 2=读不到;fix.py 0=成功 1=有字符装不下目标编码;verify.py 0=一致 1=有差异。
目标格式怎么定(按接收方选,不要按喜好选)
| 接收方 | 编码 | BOM | 换行 | 分隔符 |
|---|---|---|---|---|
| Excel 双击打开(中文 Windows) | utf-8-sig | 要 | CRLF | , |
| 老系统 / 政务 / 银行导入 | gbk 或 gb18030 | 不要 | CRLF | , 或 | |
| Python / pandas / 数据库 COPY | utf-8 | 不要 | LF | , |
| 大数据平台(Hive/Spark) | utf-8 | 不要 | LF | , 或 \t |
| 欧洲区域设置导出的 Excel | utf-8-sig | 要 | CRLF | ; |
判定口诀:带 BOM 为了 Excel 认中文,去 BOM 为了程序和数据库不把 \ufeff 当字段名。
参数速查
fix.py
| 参数 | 取值 | 说明 |
|---|---|---|
--from-enc |
auto(默认)/ gbk / utf-8 / utf-16 |
源编码,auto 走探测 |
--to-enc |
utf-8-sig(默认)/ utf-8 / gbk / gb18030 / utf-16 |
目标编码 |
--to-delim |
, ; tab pipe 或字面字符 |
目标分隔符 |
--eol |
keep(默认)/ lf / crlf |
目标换行 |
--quote |
minimal(默认)/ all |
all 给每个字段加引号,老系统更稳 |
--strip |
开关 | 去单元格首尾空白(含全角空格) |
--halfwidth |
开关 | 全角数字/字母/标点转半角 |
--drop-empty |
开关 | 删全空行 |
--fix-formula |
开关 | 公式开头的单元格加前导 ' |
--inplace |
开关 | 原地覆盖,自动生成 .bak(不覆盖已有备份) |
--dry-run |
开关 | 只报告,不写盘 |
症状 → 命令
| 症状 | 命令 |
|---|---|
| Excel 打开全是乱码 | fix.py 文件.csv --to-enc utf-8-sig |
首列表头变成 \ufeff姓名 |
fix.py 文件.csv --to-enc utf-8 |
| 所有内容挤在第一列 | 先 diag.py 看分隔符,再 fix.py --to-delim , |
| 数字列变成文本、无法求和 | fix.py 文件.csv --halfwidth |
| 导入报“列数不匹配” | diag.py --json 看 ragged_records,定位到具体第几条 |
| pandas 报 UnicodeDecodeError | diag.py 拿编码,读取时显式 encoding= |
| 转到 GBK 后出现问号 | fix.py 退出码 1 会报出装不下的字符,改投 --to-enc gb18030 |
实现要点(改代码前先读)
- 换行必须在解码后的文本上数。 UTF-16 的字节层是
b"\r\x00 \x00",字节级 count 全错。 - 引号内的换行不是记录分隔符。
csvkit.detect_newlines用状态机跳过引号区间,否则带备注换行的文件会被误判“混合换行”。 - 编码打分用中文高频字命中率。 Big5 被误当 GB18030 解出来的字全是生僻字,命中率趋近 0,这一条能把两种东亚编码分开;纯西文解出高位字节的一律压到 0.3 分以下。
- 写文件用
csv.writer+lineterminator,不要手动拼字符串。 否则单元格里的逗号、引号、换行全部炸掉。 --to-enc gbk可能装不下 emoji 和生僻字,此时脚本逐字探测,替换成?并返回退出码 1,绝不静默丢数据。
自检
python scripts/selftest.py
造 GBK+分号+全角+空白+单元格内换行的脏文件,跑完整链路,17 项断言。改动代码后先跑这个。
拿 examples 里的脏数据先跑一遍
python scripts/diag.py examples/sample_gbk.csv
python scripts/fix.py examples/sample_gbk.csv --to-enc utf-8-sig --to-delim , --eol crlf \
--strip --halfwidth --drop-empty --fix-formula
python scripts/verify.py examples/sample_gbk.csv examples/sample_gbk.fixed.csv --ignore formula,empty
预期:diag 报 4 条问题(空白 1 / 公式 2 / 空行 1 / 全角 17),fix 报 6 行→5 行,verify 差异 0 处,再对 .fixed.csv 跑 diag 结论为「干净」。
不适用
- 嵌套 JSON / XML 字段的 CSV(本技能不做字段内解析)
- 一个文件里混了两种编码(必须先用
split按字节边界分段,再分别处理) - XLSX(先另存为 CSV,或用 openpyxl 单独处理)
文件清单
SKILL.md
requirements.txt 说明零第三方依赖
scripts/csvkit.py 共用库:BOM/编码打分/换行状态机/分隔符判定/全角转半角
scripts/diag.py 体检:notes 与 issues 分开,支持 --json 与批量
scripts/fix.py 归一化:编码/分隔符/换行/空白/全角/公式/空行
scripts/verify.py 前后一致性校验(归一化比较)
scripts/selftest.py 端到端自检 17 项
examples/sample_gbk.csv 脏数据样例(GBK + 分号 + CRLF + 全角 + 空白 + 公式 + 空行 + 单元格内换行)
examples/sample_gbk.fixed.csv 上例跑完三件套的产物(UTF-8 BOM + 逗号 + 半角 + 公式已转义)
references/pitfalls.md 12 个真实踩坑与数值