做电商数据分析，最烦的事情不是算法有多复杂，是数据进不了分析环节——CSV文件打不开，打开了是乱码，不乱码的金额字段带符号，长数字被Excel转成了科学计数法。
每个问题单拎出来都不难：编码不对就转码，脏字符就strip掉，长数字保护成文本。但每次拿到一个新文件，这四个步骤重来一遍，同一个问题处理二十次之后就会想，能不能一次性解决，之后给什么文件都不再操心编码和脏数据的事。
qinshihuang-csv 就是从这件事开始的。
编码检测是经典问题，经典到有很多现成库。但实际用下来，电商平台的CSV文件有个常见的毛病——文件里有坏字节，可能某个位置的一个byte损坏了。chardet遇到这种情况，对中文的置信度直接掉到0.2以下，跳过去选一个"什么东西都能解码"的编码（比如cp1252），输出就是一串乱码。
备选方案是四层兜底：BOM检测 → charset-normalizer → chardet → 广度回退。前三层解决95%，最后一层是防线的防线——对CJK编码用errors='replace'，解码后数汉字数量，少于5个就算匹配失败，继续试下一个。这个思路是从数据库的字符集容错策略抄来的：别因为几个坏字节就放弃整个文件。
BOM不是可选项。中文Windows版Excel打开不带BOM的UTF-8 CSV，会按系统区域编码（GBK）解析，全部变乱码。所以只要用户指定UTF-8，输出文件自动升级为UTF-8-SIG。这是Excel的bug，不是用户的问题，必须替用户兜住。
编码统一之后，数据本身还有问题。
脏数据经常是复合的： ,,￥123456789012345,,￥， ，一次strip清不干净——清掉首尾空格暴露出逗号，清掉逗号暴露出币种符号。得用while循环，直到字符串不再变化为止。看起来笨，但电商CSV里这种嵌套格式确实常见。
金额列里出现纯短横 - 或者 –，不是数据缺失，是"此订单无退/无佣金"，值等于0。需要在数值上下文中识别并替换为0。
一行数据可能有多个特征：19位订单号既是"纯数字"又可能被识别为"数值"。设互斥优先级——文本格式 > 日期格式 > 数值格式。标记为文本的列排除出其他格式的候选集。
Excel只能精确表示15位有效数字，但实测12位的商品ID在Excel里已经可能触发科学计数法。阈值定在12位，覆盖商品ID、订单号、流水号等常见场景。
这个项目最后分了三个交付层次：Hermes Agent Skill 给习惯AI工作流的人、prompt引导给有兴趣但不熟环境的人、GUI源码加exe给即开即用的人。不是一开始就想好的，是做到一半发现不同人的门槛不一样，做不到一个版本覆盖所有人。
GitHub 地址：https://github.com/benyichan/qinshihuang-csv 有对应中英文 README 和完整文档。
⭐ 如果它帮你省了一次抓狂的时间，点个星。